kankaku 0.5.0 → 0.6.0

package/dist/domain/export.js

@@ -0,0 +1,68 @@
+import { localDay } from "./day.js";
+import { finiteOrZero } from "./work-record.js";
+/** First 200 chars of `prompt`, with `\n`/`\r` collapsed to a single space. */
+function truncatePrompt(prompt) {
+    return prompt.slice(0, 200).replace(/\r\n|\r|\n/g, " ");
+}
+/** Build one flat {@link ExportRow} per task, in the same order as `tasks`. */
+export function exportRows(tasks) {
+    return tasks.map((task) => ({
+        id: task.id,
+        day: localDay(task.startedAt),
+        startedAt: task.startedAt,
+        endedAt: task.endedAt,
+        client: task.client ?? "",
+        sessionName: task.sessionName ?? "",
+        sessionId: task.sessionId ?? "",
+        project: task.project,
+        status: task.status,
+        prompt: truncatePrompt(task.prompt),
+        wallMs: task.wallMs,
+        waitingMs: task.waitingMs,
+        workMs: task.workMs,
+        cost: finiteOrZero(task.usage.cost),
+        tokensIn: finiteOrZero(task.usage.input),
+        tokensOut: finiteOrZero(task.usage.output),
+        cacheRead: finiteOrZero(task.usage.cacheRead),
+        subagentCount: task.subagents.length,
+        segments: JSON.stringify(task.segments),
+        model: task.orchestrator.model ?? "",
+    }));
+}
+/** Column order for {@link toCsv}'s header row, matching {@link ExportRow}'s field order. */
+const COLUMNS = [
+    "id",
+    "day",
+    "startedAt",
+    "endedAt",
+    "client",
+    "sessionName",
+    "sessionId",
+    "project",
+    "status",
+    "prompt",
+    "wallMs",
+    "waitingMs",
+    "workMs",
+    "cost",
+    "tokensIn",
+    "tokensOut",
+    "cacheRead",
+    "subagentCount",
+    "segments",
+    "model",
+];
+/** RFC 4180 field quoting: quote a field containing `,`, `"`, or a newline; double any embedded quote. */
+function csvField(value) {
+    const text = String(value);
+    return /[",\r\n]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text;
+}
+/** Render `rows` as RFC 4180 CSV: a header row, one row per record, `\n` line endings. */
+export function toCsv(rows) {
+    const lines = [COLUMNS.join(","), ...rows.map((row) => COLUMNS.map((column) => csvField(row[column])).join(","))];
+    return lines.join("\n");
+}
+/** Render `rows` as pretty-printed (2-space indent) JSON. */
+export function toJson(rows) {
+    return JSON.stringify(rows, null, 2);
+}

package/dist/domain/hub-entry.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Map a {@link TaskView} (and its `WorkRecord`s) to the hub's `task_entries`
+ * / `work_records` payload shapes. Pure, no I/O — see `contract.md` in
+ * kankaku-hub for the exact field names/types this mirrors.
+ *
+ * The CRITICAL rule this file encodes: assignment (`client`/`project`/
+ * `task`/`legacy_client_label`) is create-only. The owner reassigns rows in
+ * the web; a later re-sync of the same task must never undo that, so
+ * `buildTaskEntryUpdatePayload` never includes those fields. See
+ * `buildTaskEntryCreatePayload` vs `buildTaskEntryUpdatePayload`.
+ */
+import type { TaskView } from "./task-view.ts";
+import type { WorkRecord, WorkRole, WorkStatus } from "./work-record.ts";
+import type { Client, Project } from "./work-target.ts";
+export type PromptPrivacyMode = "none" | "truncated" | "full";
+export interface HubEntryContext {
+    clients: Client[];
+    projects: Project[];
+    /** This machine's hostname or `KANKAKU_MACHINE`. */
+    machine: string;
+    /** `KANKAKU_SYNC_PROMPT`; see {@link applyPromptPrivacy}. */
+    promptMode: PromptPrivacyMode;
+    /** Coding agent that produced this row, lowercase slug. Always `"pi"` for this package. See kankaku-hub `docs/contract.md` "Agent and measurement quality". */
+    agent: string;
+    /** The `pi` package's own version, when it could be determined without a hot-path cost. Never guessed — omitted rather than sent wrong. */
+    agentVersion?: string;
+    /** The integration that wrote this row, lowercase slug. Always `"kankaku"` for this package. */
+    plugin: string;
+    /** This kankaku package's own version, from its `package.json`, read once. */
+    pluginVersion?: string;
+}
+export interface TaskAssignment {
+    /** `clients` relation id, or `""` when no usable client could be resolved. */
+    clientId: string;
+    /** `projects` relation id, or `""`. */
+    projectId: string;
+    /** Only set (non-empty) for a task routed to the unassigned client. */
+    legacyClientLabel: string;
+    /** `true` when this task was routed to the catalog's unassigned ("Sin determinar") client. */
+    routedToUnassigned: boolean;
+}
+/**
+ * Resolve which client/project a task's `task_entries` row should link to.
+ *
+ * - A task whose `clientId` still exists in `clients` links to that client
+ *   (regardless of its `active` flag — this is a historical fact, not a
+ *   future selection), and to `projectId` too when it still exists and
+ *   belongs to that client; otherwise the project relation is empty.
+ * - A task with no `clientId`, or whose `clientId` no longer resolves,
+ *   routes to the catalog's unassigned client (the row with
+ *   `unassigned: true`), carrying forward the record's free-text `client`
+ *   label (or its `clientName` when the label itself is absent) as
+ *   `legacyClientLabel` — the historical backfill rule (proposal §5.3).
+ */
+export declare function resolveTaskAssignment(task: TaskView, clients: Client[], projects: Project[]): TaskAssignment;
+/**
+ * Privacy transform for a prompt about to leave the machine
+ * (`KANKAKU_SYNC_PROMPT`, default `none`): `none` omits it entirely,
+ * `truncated` keeps the first 120 chars plus an ellipsis marker when
+ * anything was cut, `full` sends it verbatim.
+ */
+export declare function applyPromptPrivacy(prompt: string, mode: PromptPrivacyMode): string;
+export type WaitingQuality = "measured" | "unavailable";
+export type CostQuality = "measured" | "estimated" | "unknown";
+export type SubagentLinkage = "linked" | "unlinked" | "not_applicable";
+/**
+ * Whether waiting time (time blocked on the human) was actually observed
+ * for this task, as opposed to `work_ms` being an unmeasured upper bound
+ * equal to `wall_ms`. pi always instruments `ui_prompt_start`/`_end` and
+ * interactive-tool spans (`domain/work-tracker.ts`), so this is always
+ * `"measured"` for kankaku/pi — a constant here, not computed from a
+ * record, kept as its own function (rather than a literal in the payload)
+ * so the reasoning has one documented home.
+ */
+export declare function computeWaitingQuality(): WaitingQuality;
+/**
+ * Whether this task's cost figure came from a real provider-reported cost
+ * (`"measured"`) or not (`"unknown"`) — never `"estimated"`: kankaku has no
+ * token-based price-table estimator today, only a real provider figure or
+ * nothing. A task counts as measured when its own orchestrator record OR
+ * any of its joined subagent records observed one (see
+ * `WorkRecord.costObserved`, set by `domain/work-tracker.ts`).
+ */
+export declare function computeCostQuality(task: TaskView): CostQuality;
+/**
+ * Whether this task's subagent tool spans (`orchestrator.subagents`,
+ * `SubagentSpan[]` — the orchestrator's own tool-call bookkeeping) are
+ * accounted for by joined child `WorkRecord`s (`task.subagents`, from
+ * `domain/task-view.ts#matchChildren`). There is no explicit per-span
+ * correlation id today (README "Subagents" > "Limitations": upstream
+ * gentle-pi does not hand a child its own task id), so this is a
+ * task-level approximation, not a per-span one:
+ *
+ * - `not_applicable`: the orchestrator opened no subagent spans at all.
+ * - `linked`: at least as many child records were joined as spans were
+ *   opened — plausibly every span is accounted for (a gentle-pi subagent
+ *   spawns exactly one child process per span, so counts normally match
+ *   1:1).
+ * - `unlinked`: fewer joined children than spans (including zero) — at
+ *   least one span's time is only visible inside the orchestrator's own
+ *   tool-call span, with no corroborating child record. This also covers
+ *   a fully in-process subagent mechanism (no separate OS process at all,
+ *   invisible to the registry/ancestry machinery) and a genuine join miss
+ *   alike — kankaku cannot tell those apart from here, so it reports the
+ *   conservative, visible-gap answer rather than guessing "linked".
+ */
+export declare function computeSubagentLinkage(task: TaskView): SubagentLinkage;
+/** The `task_entries` fields present on every write. */
+export interface TaskEntryPayload {
+    task_id: string;
+    client: string;
+    project: string;
+    task: string;
+    started_at: string;
+    ended_at: string;
+    wall_ms: number;
+    waiting_ms: number;
+    work_ms: number;
+    input: number;
+    output: number;
+    cache_read: number;
+    cache_write: number;
+    cost: number;
+    segments: Record<string, number>;
+    subagent_count: number;
+    runs: number;
+    turns: number;
+    status: WorkStatus;
+    session_id: string;
+    session_name: string;
+    machine: string;
+    model: string;
+    /** The model's reasoning effort; omitted when the record does not know it. */
+    thinking_level?: string;
+    prompt: string;
+    legacy_client_label: string;
+    repo_project: string;
+    schema: number;
+    agent: string;
+    agent_version?: string;
+    /** Non-default session directory, see `TaskView.sessionDir`. A measurement field, not assignment: sent on both create and update. */
+    session_dir?: string;
+    plugin: string;
+    plugin_version?: string;
+    waiting_quality: WaitingQuality;
+    cost_quality: CostQuality;
+    subagent_linkage: SubagentLinkage;
+}
+/** `TaskEntryPayload` minus the assignment fields — what an update sends. See the module docs' CRITICAL rule. */
+export type TaskEntryUpdatePayload = Omit<TaskEntryPayload, "client" | "project" | "task" | "legacy_client_label">;
+/** Build the full `task_entries` payload for a **create** request — every field, including assignment. */
+export declare function buildTaskEntryCreatePayload(task: TaskView, ctx: HubEntryContext): TaskEntryPayload;
+/**
+ * Build the `task_entries` payload for an **update** request: measurement
+ * fields only — never `client`, `project`, `task` or `legacy_client_label`,
+ * so a re-sync can never undo a reassignment made in the web. See the
+ * module docs' CRITICAL rule.
+ */
+export declare function buildTaskEntryUpdatePayload(task: TaskView, ctx: HubEntryContext): TaskEntryUpdatePayload;
+/** One `work_records` row — raw per-`WorkRecord` detail, always `rollup: false`. */
+export interface WorkRecordPayload {
+    kankaku_id: string;
+    task_entry: string;
+    rollup: false;
+    role: WorkRole;
+    pid: number;
+    parent_pid: number;
+    started_at: string;
+    settled_at: string;
+    wall_ms: number;
+    waiting_ms: number;
+    work_ms: number;
+    runs: number;
+    turns: number;
+    status: WorkStatus;
+    model: string;
+    thinking_level?: string;
+    input: number;
+    output: number;
+    cache_read: number;
+    cache_write: number;
+    cost: number;
+    segments: Record<string, number>;
+    tools: Record<string, number>;
+    session_id: string;
+    prompt: string;
+    machine: string;
+    schema: number;
+}
+/**
+ * Build one `work_records` payload from a raw {@link WorkRecord}
+ * (orchestrator or subagent), linked to its parent `task_entries` row by
+ * PocketBase id. `work_records` carries no assignment fields, so there is
+ * no create/update distinction here — this payload is sent as-is either way.
+ */
+export declare function buildWorkRecordPayload(record: WorkRecord, taskEntryRecordId: string, ctx: {
+    machine: string;
+    promptMode: PromptPrivacyMode;
+}): WorkRecordPayload;
+/** Every `WorkRecord` folded into a task: the orchestrator plus its subagents, in that order. */
+export declare function taskWorkRecords(task: TaskView): WorkRecord[];

package/dist/domain/hub-entry.js

@@ -0,0 +1,211 @@
+/**
+ * Map a {@link TaskView} (and its `WorkRecord`s) to the hub's `task_entries`
+ * / `work_records` payload shapes. Pure, no I/O — see `contract.md` in
+ * kankaku-hub for the exact field names/types this mirrors.
+ *
+ * The CRITICAL rule this file encodes: assignment (`client`/`project`/
+ * `task`/`legacy_client_label`) is create-only. The owner reassigns rows in
+ * the web; a later re-sync of the same task must never undo that, so
+ * `buildTaskEntryUpdatePayload` never includes those fields. See
+ * `buildTaskEntryCreatePayload` vs `buildTaskEntryUpdatePayload`.
+ */
+import { finiteOrZero } from "./work-record.js";
+/**
+ * Resolve which client/project a task's `task_entries` row should link to.
+ *
+ * - A task whose `clientId` still exists in `clients` links to that client
+ *   (regardless of its `active` flag — this is a historical fact, not a
+ *   future selection), and to `projectId` too when it still exists and
+ *   belongs to that client; otherwise the project relation is empty.
+ * - A task with no `clientId`, or whose `clientId` no longer resolves,
+ *   routes to the catalog's unassigned client (the row with
+ *   `unassigned: true`), carrying forward the record's free-text `client`
+ *   label (or its `clientName` when the label itself is absent) as
+ *   `legacyClientLabel` — the historical backfill rule (proposal §5.3).
+ */
+export function resolveTaskAssignment(task, clients, projects) {
+    const client = task.clientId !== undefined ? clients.find((candidate) => candidate.id === task.clientId) : undefined;
+    if (client) {
+        const project = task.projectId !== undefined ? projects.find((candidate) => candidate.id === task.projectId && candidate.clientId === client.id) : undefined;
+        return {
+            clientId: client.id,
+            projectId: project ? project.id : "",
+            legacyClientLabel: "",
+            routedToUnassigned: false,
+        };
+    }
+    const unassigned = clients.find((candidate) => candidate.unassigned === true);
+    return {
+        clientId: unassigned ? unassigned.id : "",
+        projectId: "",
+        legacyClientLabel: task.client ?? task.clientName ?? "",
+        routedToUnassigned: true,
+    };
+}
+/**
+ * Privacy transform for a prompt about to leave the machine
+ * (`KANKAKU_SYNC_PROMPT`, default `none`): `none` omits it entirely,
+ * `truncated` keeps the first 120 chars plus an ellipsis marker when
+ * anything was cut, `full` sends it verbatim.
+ */
+export function applyPromptPrivacy(prompt, mode) {
+    if (mode === "full")
+        return prompt;
+    if (mode === "truncated")
+        return prompt.length > 120 ? `${prompt.slice(0, 120)}…` : prompt;
+    return "";
+}
+/**
+ * PocketBase `date` fields read back as `"YYYY-MM-DD HH:MM:SS.mmmZ"` (space,
+ * not `T`) though both forms are accepted on write; kankaku always sends
+ * the space form so a round trip through the contract's documented shape
+ * never depends on PocketBase's own normalization.
+ */
+function toPbDate(iso) {
+    return iso.replace("T", " ");
+}
+/**
+ * Whether waiting time (time blocked on the human) was actually observed
+ * for this task, as opposed to `work_ms` being an unmeasured upper bound
+ * equal to `wall_ms`. pi always instruments `ui_prompt_start`/`_end` and
+ * interactive-tool spans (`domain/work-tracker.ts`), so this is always
+ * `"measured"` for kankaku/pi — a constant here, not computed from a
+ * record, kept as its own function (rather than a literal in the payload)
+ * so the reasoning has one documented home.
+ */
+export function computeWaitingQuality() {
+    return "measured";
+}
+/**
+ * Whether this task's cost figure came from a real provider-reported cost
+ * (`"measured"`) or not (`"unknown"`) — never `"estimated"`: kankaku has no
+ * token-based price-table estimator today, only a real provider figure or
+ * nothing. A task counts as measured when its own orchestrator record OR
+ * any of its joined subagent records observed one (see
+ * `WorkRecord.costObserved`, set by `domain/work-tracker.ts`).
+ */
+export function computeCostQuality(task) {
+    const observed = task.orchestrator.costObserved === true || task.subagents.some((child) => child.costObserved === true);
+    return observed ? "measured" : "unknown";
+}
+/**
+ * Whether this task's subagent tool spans (`orchestrator.subagents`,
+ * `SubagentSpan[]` — the orchestrator's own tool-call bookkeeping) are
+ * accounted for by joined child `WorkRecord`s (`task.subagents`, from
+ * `domain/task-view.ts#matchChildren`). There is no explicit per-span
+ * correlation id today (README "Subagents" > "Limitations": upstream
+ * gentle-pi does not hand a child its own task id), so this is a
+ * task-level approximation, not a per-span one:
+ *
+ * - `not_applicable`: the orchestrator opened no subagent spans at all.
+ * - `linked`: at least as many child records were joined as spans were
+ *   opened — plausibly every span is accounted for (a gentle-pi subagent
+ *   spawns exactly one child process per span, so counts normally match
+ *   1:1).
+ * - `unlinked`: fewer joined children than spans (including zero) — at
+ *   least one span's time is only visible inside the orchestrator's own
+ *   tool-call span, with no corroborating child record. This also covers
+ *   a fully in-process subagent mechanism (no separate OS process at all,
+ *   invisible to the registry/ancestry machinery) and a genuine join miss
+ *   alike — kankaku cannot tell those apart from here, so it reports the
+ *   conservative, visible-gap answer rather than guessing "linked".
+ */
+export function computeSubagentLinkage(task) {
+    const spanCount = task.orchestrator.subagents.length;
+    if (spanCount === 0)
+        return "not_applicable";
+    return task.subagents.length >= spanCount ? "linked" : "unlinked";
+}
+/** Build the full `task_entries` payload for a **create** request — every field, including assignment. */
+export function buildTaskEntryCreatePayload(task, ctx) {
+    const assignment = resolveTaskAssignment(task, ctx.clients, ctx.projects);
+    return {
+        task_id: task.id,
+        client: assignment.clientId,
+        project: assignment.projectId,
+        task: "",
+        started_at: toPbDate(task.startedAt),
+        ended_at: toPbDate(task.endedAt),
+        wall_ms: task.wallMs,
+        waiting_ms: task.waitingMs,
+        work_ms: task.workMs,
+        input: finiteOrZero(task.usage.input),
+        output: finiteOrZero(task.usage.output),
+        cache_read: finiteOrZero(task.usage.cacheRead),
+        cache_write: finiteOrZero(task.usage.cacheWrite),
+        cost: finiteOrZero(task.usage.cost),
+        segments: task.segments,
+        subagent_count: task.subagents.length,
+        runs: task.orchestrator.runs,
+        turns: task.orchestrator.turns,
+        status: task.status,
+        session_id: task.sessionId ?? "",
+        session_name: task.sessionName ?? "",
+        machine: ctx.machine,
+        model: task.orchestrator.model ?? "",
+        ...(task.orchestrator.thinkingLevel !== undefined ? { thinking_level: task.orchestrator.thinkingLevel } : {}),
+        prompt: applyPromptPrivacy(task.prompt, ctx.promptMode),
+        legacy_client_label: assignment.legacyClientLabel,
+        repo_project: task.project,
+        schema: task.orchestrator.schema,
+        agent: ctx.agent,
+        ...(ctx.agentVersion !== undefined ? { agent_version: ctx.agentVersion } : {}),
+        ...(task.sessionDir !== undefined ? { session_dir: task.sessionDir } : {}),
+        plugin: ctx.plugin,
+        ...(ctx.pluginVersion !== undefined ? { plugin_version: ctx.pluginVersion } : {}),
+        waiting_quality: computeWaitingQuality(),
+        cost_quality: computeCostQuality(task),
+        subagent_linkage: computeSubagentLinkage(task),
+    };
+}
+/**
+ * Build the `task_entries` payload for an **update** request: measurement
+ * fields only — never `client`, `project`, `task` or `legacy_client_label`,
+ * so a re-sync can never undo a reassignment made in the web. See the
+ * module docs' CRITICAL rule.
+ */
+export function buildTaskEntryUpdatePayload(task, ctx) {
+    const { client: _client, project: _project, task: _task, legacy_client_label: _legacy, ...rest } = buildTaskEntryCreatePayload(task, ctx);
+    return rest;
+}
+/**
+ * Build one `work_records` payload from a raw {@link WorkRecord}
+ * (orchestrator or subagent), linked to its parent `task_entries` row by
+ * PocketBase id. `work_records` carries no assignment fields, so there is
+ * no create/update distinction here — this payload is sent as-is either way.
+ */
+export function buildWorkRecordPayload(record, taskEntryRecordId, ctx) {
+    return {
+        kankaku_id: record.id,
+        task_entry: taskEntryRecordId,
+        rollup: false,
+        role: record.role,
+        pid: record.pid,
+        parent_pid: record.parentPid,
+        started_at: toPbDate(record.startedAt),
+        settled_at: toPbDate(record.settledAt),
+        wall_ms: record.wallMs,
+        waiting_ms: record.waitingMs,
+        work_ms: record.workMs,
+        runs: record.runs,
+        turns: record.turns,
+        status: record.status,
+        model: record.model ?? "",
+        ...(record.thinkingLevel !== undefined ? { thinking_level: record.thinkingLevel } : {}),
+        input: finiteOrZero(record.usage.input),
+        output: finiteOrZero(record.usage.output),
+        cache_read: finiteOrZero(record.usage.cacheRead),
+        cache_write: finiteOrZero(record.usage.cacheWrite),
+        cost: finiteOrZero(record.usage.cost),
+        segments: record.segments ?? {},
+        tools: record.tools,
+        session_id: record.sessionId ?? "",
+        prompt: applyPromptPrivacy(record.prompt, ctx.promptMode),
+        machine: ctx.machine,
+        schema: record.schema,
+    };
+}
+/** Every `WorkRecord` folded into a task: the orchestrator plus its subagents, in that order. */
+export function taskWorkRecords(task) {
+    return [task.orchestrator, ...task.subagents];
+}

package/dist/domain/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Public library entrypoint (`kankaku/domain`): the pure domain layer, with
+ * no I/O and no pi imports. See AGENTS.md "Architecture (hexagonal)" and
+ * odd/tasks/library-exports.md.
+ */
+export * from "./ancestry-match.ts";
+export * from "./client-label.ts";
+export * from "./day.ts";
+export * from "./export.ts";
+export * from "./hub-entry.ts";
+export * from "./intervals.ts";
+export * from "./registry-health.ts";
+export * from "./segment-rule.ts";
+export * from "./subagent-profile.ts";
+export * from "./sync-plan.ts";
+export * from "./task-view.ts";
+export * from "./work-record.ts";
+export * from "./work-target.ts";
+export * from "./work-tracker.ts";

package/dist/domain/index.js

@@ -0,0 +1,19 @@
+/**
+ * Public library entrypoint (`kankaku/domain`): the pure domain layer, with
+ * no I/O and no pi imports. See AGENTS.md "Architecture (hexagonal)" and
+ * odd/tasks/library-exports.md.
+ */
+export * from "./ancestry-match.js";
+export * from "./client-label.js";
+export * from "./day.js";
+export * from "./export.js";
+export * from "./hub-entry.js";
+export * from "./intervals.js";
+export * from "./registry-health.js";
+export * from "./segment-rule.js";
+export * from "./subagent-profile.js";
+export * from "./sync-plan.js";
+export * from "./task-view.js";
+export * from "./work-record.js";
+export * from "./work-target.js";
+export * from "./work-tracker.js";

package/dist/domain/intervals.d.ts

@@ -0,0 +1,17 @@
+export interface Interval {
+    start: number;
+    end: number;
+}
+/**
+ * Restrict every interval to `[windowStart, windowEnd]` and drop any that
+ * become empty (or invalid) after clamping.
+ */
+export declare function clampIntervals(intervals: Interval[], windowStart: number, windowEnd: number): Interval[];
+/**
+ * Total duration covered by the union of the given intervals — never the
+ * sum, so overlapping (e.g. parallel subagent) spans are not double-counted.
+ */
+export declare function unionMs(intervals: Array<{
+    start: number;
+    end: number;
+}>): number;

package/dist/domain/intervals.js

@@ -0,0 +1,43 @@
+/**
+ * Restrict every interval to `[windowStart, windowEnd]` and drop any that
+ * become empty (or invalid) after clamping.
+ */
+export function clampIntervals(intervals, windowStart, windowEnd) {
+    return intervals
+        .map((interval) => ({
+        start: Math.max(interval.start, windowStart),
+        end: Math.min(interval.end, windowEnd),
+    }))
+        .filter((interval) => interval.end > interval.start);
+}
+/**
+ * Total duration covered by the union of the given intervals — never the
+ * sum, so overlapping (e.g. parallel subagent) spans are not double-counted.
+ */
+export function unionMs(intervals) {
+    const sorted = [...intervals].sort((a, b) => a.start - b.start);
+    let total = 0;
+    let currentStart;
+    let currentEnd;
+    for (const interval of sorted) {
+        if (interval.end <= interval.start)
+            continue;
+        if (currentStart === undefined || currentEnd === undefined) {
+            currentStart = interval.start;
+            currentEnd = interval.end;
+            continue;
+        }
+        if (interval.start <= currentEnd) {
+            currentEnd = Math.max(currentEnd, interval.end);
+        }
+        else {
+            total += currentEnd - currentStart;
+            currentStart = interval.start;
+            currentEnd = interval.end;
+        }
+    }
+    if (currentStart !== undefined && currentEnd !== undefined) {
+        total += currentEnd - currentStart;
+    }
+    return total;
+}

package/dist/domain/registry-health.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Decide which machine-wide {@link RegistryEntry} rows a sweep should keep
+ * vs discard, and why. Pure, no I/O — `adapters/machine-process-registry.ts`
+ * drives this with real `isAlive`/`liveStartId`/`now`, and
+ * `adapters/kankaku-command.ts`'s `/kankaku doctor` reuses it (cheap mode,
+ * no fresh identity re-verification) to report registry health.
+ */
+import type { RegistryEntry } from "../ports/process-registry.ts";
+/** Sane last-resort ceiling on an entry's age, regardless of aliveness/identity: 7 days. */
+export declare const DEFAULT_MAX_ENTRY_AGE_MS: number;
+export type DiscardReason = "dead"
+/** The pid is alive, but its live start identity no longer matches what this entry recorded: the OS has reused this pid for a different process instance. */
+ | "stale-reuse" | "over-age";
+export interface RegistryClassifyDeps {
+    isAlive: (pid: number) => boolean;
+    /** Live start identity for a pid, from the same ancestry snapshot the caller already took. `undefined` means "unknown" — never treated as evidence of reuse. */
+    liveStartId: (pid: number) => number | undefined;
+    now: number;
+    maxAgeMs: number;
+}
+export interface RegistryClassification {
+    keep: RegistryEntry[];
+    discard: Array<{
+        entry: RegistryEntry;
+        reason: DiscardReason;
+    }>;
+}
+/**
+ * Classify every entry except `ownPid`'s (the caller's own, just-written
+ * entry — always kept, never re-evaluated against its own freshly-recorded
+ * data). An entry is discarded the first reason that applies, in this
+ * order: dead pid; alive but identity mismatched beyond
+ * {@link START_ID_TOLERANCE_MS} (pid reuse) — only ever checked when the
+ * entry actually carries a `processStartId`; older than `maxAgeMs`.
+ * Anything else is kept.
+ *
+ * An entry with no verifiable `processStartId` at all (written by a build
+ * predating this field, or a torn/partial write) is **never used for
+ * identity matching** (`domain/ancestry-match.ts#findAncestorEntry` already
+ * requires both sides to carry a start id) — but that alone is no longer
+ * grounds for deletion here (F4): a live, in-age entry that merely cannot be
+ * verified is kept, exactly like a verified one, so a sweep run by an
+ * unrelated sibling process can never un-register a genuinely live
+ * orchestrator whose own start-time read happened to fail. It still gets
+ * cleaned up the ordinary way once its pid dies or it ages out — dead and
+ * over-age entries are discarded regardless of whether they carry a
+ * `processStartId`.
+ */
+export declare function classifyRegistryEntries(entries: RegistryEntry[], ownPid: number, deps: RegistryClassifyDeps): RegistryClassification;