kankaku-pi 1.0.0

package/dist/domain/task-view.js

@@ -0,0 +1,428 @@
+import { unionMs } from "./intervals.js";
+import { emptyUsage, finiteOrZero } from "./work-record.js";
+function toMs(iso) {
+    return Date.parse(iso);
+}
+/**
+ * Sum per-tag milliseconds across several segment maps (older records
+ * without one count as `{}`). Accumulated in a `Map`, then emitted via
+ * `Object.fromEntries` (never `result[tag] = ...` on a plain object) so a
+ * tag from a hand-edited worklog line named `__proto__` or `constructor`
+ * becomes an own data property with the right total instead of silently
+ * reading (and arithmetically corrupting) an inherited `Object.prototype`
+ * value. Mirrors `work-tracker.ts`'s own segment-building convention.
+ */
+function sumSegments(segmentMaps) {
+    const totals = new Map();
+    for (const segments of segmentMaps) {
+        for (const [tag, ms] of Object.entries(segments ?? {})) {
+            totals.set(tag, (totals.get(tag) ?? 0) + ms);
+        }
+    }
+    return Object.fromEntries(totals);
+}
+/**
+ * Sum several {@link UsageTotals}, tolerating a missing entry (a record
+ * without a `usage` field) and missing or non-finite numeric fields on an
+ * entry — both treated as zero rather than corrupting the sum with
+ * `undefined`/`NaN`.
+ */
+export function sumUsage(totals) {
+    const usage = emptyUsage();
+    for (const total of totals) {
+        usage.input += finiteOrZero(total?.input);
+        usage.output += finiteOrZero(total?.output);
+        usage.cacheRead += finiteOrZero(total?.cacheRead);
+        usage.cacheWrite += finiteOrZero(total?.cacheWrite);
+        usage.cost += finiteOrZero(total?.cost);
+    }
+    return usage;
+}
+/**
+ * A record is only eligible to anchor a new task when it is a *confirmed*
+ * orchestrator: `role === "orchestrator"` and not flagged `uncertain`
+ * (ADR 0022). An uncertain record is never dropped — see
+ * {@link uncertainRecords} — but it never anchors a task locally and is
+ * therefore never synced as one either (SUBAGENT-REQ-014), since sync
+ * (`adapters/sync-runner.ts`) uploads exactly what {@link buildTasks}
+ * produces.
+ */
+function isConfirmedOrchestrator(record) {
+    return record.role === "orchestrator" && record.roleConfidence !== "uncertain";
+}
+/** How long after a record settled a child it launched may still start and be joined to it by span evidence (see {@link matchChildren}). */
+const LATE_CHILD_GRACE_MS = 5000;
+/** `true` when `orchestrator` opened more subagent spans of `child`'s profile than it has been given children for. A missing profile on either side matches any. */
+function hasUnclaimedSpan(orchestrator, child, alreadyAssigned) {
+    const sameKind = (profile) => child.profile === undefined || profile === undefined || profile === child.profile;
+    const spans = orchestrator.subagents.filter((span) => sameKind(span.profile)).length;
+    const claimed = alreadyAssigned.filter((other) => sameKind(other.profile)).length;
+    return spans > claimed;
+}
+/** A pid means nothing across machines. Only decidable when both records name theirs (`machine` is written when a hub is configured). */
+function differentMachines(a, b) {
+    return a.machine !== undefined && b.machine !== undefined && a.machine !== b.machine;
+}
+/**
+ * The same record can be in the log twice under one id: written at settle,
+ * then written again by crash recovery because the process died before its
+ * checkpoint was cleared. Count it once, keeping the most complete copy —
+ * the later `settledAt` (a checkpoint taken while a newer run was folded in
+ * is later AND larger than the settled copy; a stale one is earlier).
+ */
+/** Later `settledAt` wins; on a tie the copy carrying more cost, then more wall time — never insertion order. */
+function moreComplete(candidate, seen) {
+    const byEnd = toMs(candidate.settledAt) - toMs(seen.settledAt);
+    if (byEnd !== 0)
+        return byEnd > 0;
+    const byCost = finiteOrZero(candidate.usage?.cost) - finiteOrZero(seen.usage?.cost);
+    if (byCost !== 0)
+        return byCost > 0;
+    return candidate.wallMs > seen.wallMs;
+}
+export function dedupeById(records) {
+    const byId = new Map();
+    for (const record of records) {
+        const seen = byId.get(record.id);
+        if (!seen || moreComplete(record, seen))
+            byId.set(record.id, record);
+    }
+    if (byId.size === records.length)
+        return records;
+    const kept = new Set(byId.values());
+    return records.filter((record) => kept.delete(record));
+}
+/**
+ * Second pass, only for a child no orchestrator window contains: join it to
+ * the most recent record of the very process that launched it, as PROVEN by
+ * its `orchestratorRef` (written at child start from a live registry entry
+ * whose OS start time was checked — never inferred here). `ref.startedAt`
+ * is when that process last REGISTERED, which `/new`, `/resume`, `/fork` and
+ * `/reload` re-stamp: a parent record older than the last re-registration is
+ * therefore not eligible. That only ever misses a rescue (the child stays an
+ * orphan, as before); it can never produce a wrong join.
+ *
+ * Why a child can start outside every window: its parent's run was never
+ * recorded (a run an extension started, before `WorkTracker.onAgentStart`
+ * existed), or the parent crashed before settling. Without this pass that
+ * child's time and cost stay in the log forever and never reach a task.
+ *
+ * Why this is an identity join and not the time-only join SUBAGENT-REQ-007
+ * forbids: a candidate must carry the referenced pid AND have started inside
+ * `[ref.startedAt, child.startedAt]`. The referenced process was alive at
+ * both ends of that interval, and the OS cannot hand a live process's pid to
+ * another one, so any record with that pid in that interval was written by
+ * that exact process. A record older than `ref.startedAt` (a previous owner
+ * of a reused pid) or newer than the child is never eligible; a child with
+ * no `orchestratorRef` is never rescued at all.
+ */
+function rescueByParentIdentity(child, orchestrators, assigned) {
+    const ref = child.orchestratorRef;
+    if (!ref)
+        return undefined;
+    const processStart = toMs(ref.startedAt);
+    const childStart = toMs(child.startedAt);
+    if (!Number.isFinite(processStart) || !Number.isFinite(childStart))
+        return undefined;
+    let best;
+    let bestStart = Number.NEGATIVE_INFINITY;
+    let bestLaunched = false;
+    for (const orchestrator of orchestrators) {
+        if (orchestrator.pid !== ref.pid)
+            continue;
+        // A pid is only unique on ONE machine: a worklog shared between two
+        // (a synced KANKAKU_DIR) must never join across them.
+        if (differentMachines(orchestrator, child))
+            continue;
+        const start = toMs(orchestrator.startedAt);
+        if (!(start >= processStart && start <= childStart))
+            continue;
+        // Among the proven process's records, one that actually launched a
+        // subagent of this kind beats a newer one that launched nothing.
+        const launched = hasUnclaimedSpan(orchestrator, child, assigned.get(orchestrator.id) ?? []);
+        if (best === undefined || (launched && !bestLaunched) || (launched === bestLaunched && start > bestStart)) {
+            best = orchestrator;
+            bestStart = start;
+            bestLaunched = launched;
+        }
+    }
+    return best;
+}
+/**
+ * Match every subagent record to the orchestrator record it belongs to:
+ * `parentPid === orchestrator.pid` and the child's `startedAt` falls inside
+ * the orchestrator's `[startedAt, settledAt]` window. `project` is a
+ * *hint*, never a hard filter (ADR 0021, SUBAGENT-REQ-008): among several
+ * candidates matching on pid/time (a reused pid, or a genuine cross-project
+ * match), a same-project one is always preferred; a cross-project candidate
+ * is only ever eligible here because its record already lives in the same
+ * `worklog.jsonl` this array was read from — F1's write-side routing
+ * (`extension.ts`, `domain/ancestry-match.ts#resolveOrchestratorRef`)
+ * reunites a verified cross-worktree child with its orchestrator by writing
+ * straight into the orchestrator's own directory, so no later registry
+ * lookup is ever needed here — this function itself does no registry
+ * lookups and stays pure. Each child is assigned at most once; unmatched
+ * children are orphans.
+ */
+function matchChildren(allRecords) {
+    const records = dedupeById(allRecords);
+    const orchestrators = records.filter(isConfirmedOrchestrator);
+    const subagents = records.filter((record) => record.role === "subagent").sort((a, b) => toMs(a.startedAt) - toMs(b.startedAt));
+    const childrenByOrchestratorId = new Map();
+    for (const orchestrator of orchestrators) {
+        childrenByOrchestratorId.set(orchestrator.id, []);
+    }
+    const orphans = [];
+    for (const child of subagents) {
+        const childStart = toMs(child.startedAt);
+        let best;
+        let bestStart = Number.NEGATIVE_INFINITY;
+        let bestSameProject = false;
+        let bestLaunched = false;
+        for (const orchestrator of orchestrators) {
+            if (orchestrator.pid !== child.parentPid)
+                continue;
+            if (differentMachines(orchestrator, child))
+                continue;
+            const parentStart = toMs(orchestrator.startedAt);
+            const parentEnd = toMs(orchestrator.settledAt);
+            if (childStart < parentStart)
+                continue;
+            // Evidence that THIS record launched a subagent of the child's kind
+            // and has not been given a child for every such span yet.
+            const launched = hasUnclaimedSpan(orchestrator, child, childrenByOrchestratorId.get(orchestrator.id));
+            // A record can be closed the instant the next run begins (see
+            // WorkTracker.settleAll): its background child then appears a moment
+            // AFTER it settled, inside the next record's window. Only a record with
+            // span evidence gets this short grace — never time alone.
+            const inWindow = childStart <= parentEnd;
+            if (!inWindow && !(launched && childStart - parentEnd <= LATE_CHILD_GRACE_MS))
+                continue;
+            const sameProject = orchestrator.project === child.project;
+            const better = best === undefined ||
+                (launched && !bestLaunched) ||
+                (launched === bestLaunched && sameProject && !bestSameProject) ||
+                (launched === bestLaunched && sameProject === bestSameProject && parentStart > bestStart);
+            if (better) {
+                best = orchestrator;
+                bestStart = parentStart;
+                bestSameProject = sameProject;
+                bestLaunched = launched;
+            }
+        }
+        best ??= rescueByParentIdentity(child, orchestrators, childrenByOrchestratorId);
+        if (best) {
+            childrenByOrchestratorId.get(best.id).push(child);
+        }
+        else {
+            orphans.push(child);
+        }
+    }
+    return { childrenByOrchestratorId, orphans };
+}
+/**
+ * C1 (CRITICAL fix): the reconciliation ADR 0006 keeps in exactly this one
+ * place — the only spot that decides whether a subagent span's
+ * `forwardedUsage` (`domain/work-tracker.ts#onToolEnd`, SUBAGENT-REQ-006
+ * revised) actually gets added to this task's total, or is assumed already
+ * covered by a joined child record's own `usage`.
+ *
+ * There is no explicit per-span correlation id today (same limitation
+ * `computeSubagentLinkage` in `domain/hub-entry.ts` already documents), so
+ * this reconciles at PROFILE granularity, not per span: a span's forwarded
+ * usage is excluded only when this task also has at least one joined child
+ * record confirmed by the SAME profile (`WorkRecord.profile`) — i.e. a
+ * profile that can BOTH forward usage AND be ancestry-joined for the same
+ * kind of call (today, only a user-configured profile that declares both a
+ * child-env marker and usage forwarding — see `buildConfiguredProfile`'s
+ * doc comment; none of the built-ins can be both at once, so their spans'
+ * forwarded usage is never excluded here). A span whose profile is
+ * `undefined` (an ambiguous match — see `safeAmbiguousResultInfo`) never
+ * carries `forwardedUsage` in the first place, so it never reaches this
+ * function at all.
+ */
+function unjoinedForwardedUsage(orchestrator, subagents) {
+    // Only a DIRECT child can be the process behind one of this record's
+    // spans; a grandchild joined by {@link rescueByParentIdentity} never is.
+    // Deliberately NOT narrowed to children that started inside the window:
+    // gentle-pi's child process starts ~90 ms after `subagent_run` returns,
+    // often after this record settled, and it IS that span's child — narrowing
+    // billed it twice. The other error (a later, unrelated launch of the same
+    // profile cancelling this span's forwarded usage) under-bills instead,
+    // which is the safer side to be wrong on.
+    const launchedHere = subagents.filter((child) => child.parentPid === orchestrator.pid);
+    // One joined child accounts for ONE span of its profile, not for all of
+    // them: three spans and one child record means two children never wrote a
+    // record, and their forwarded usage is the only trace of their cost.
+    const remaining = new Map();
+    for (const child of launchedHere) {
+        if (child.profile !== undefined)
+            remaining.set(child.profile, (remaining.get(child.profile) ?? 0) + 1);
+    }
+    const kept = [];
+    for (const span of orchestrator.subagents) {
+        if (span.forwardedUsage === undefined)
+            continue;
+        const left = span.profile !== undefined ? (remaining.get(span.profile) ?? 0) : 0;
+        if (left > 0) {
+            remaining.set(span.profile, left - 1);
+            continue;
+        }
+        kept.push(span.forwardedUsage);
+    }
+    return kept;
+}
+function buildTaskView(orchestrator, subagents) {
+    const parentStart = toMs(orchestrator.startedAt);
+    const parentEnd = toMs(orchestrator.settledAt);
+    const intervals = [
+        { start: parentStart, end: parentEnd },
+        ...subagents.map((child) => ({ start: toMs(child.startedAt), end: toMs(child.settledAt) })),
+    ];
+    const wallMs = unionMs(intervals);
+    const endedAtMs = Math.max(parentEnd, ...subagents.map((child) => toMs(child.settledAt)));
+    const waitingMs = orchestrator.waitingMs;
+    const workMs = wallMs - waitingMs;
+    const usage = sumUsage([orchestrator.usage, ...subagents.map((child) => child.usage), ...unjoinedForwardedUsage(orchestrator, subagents)]);
+    const segments = sumSegments([orchestrator.segments, ...subagents.map((child) => child.segments)]);
+    return {
+        id: orchestrator.id,
+        ...(orchestrator.sessionId !== undefined ? { sessionId: orchestrator.sessionId } : {}),
+        ...(orchestrator.client !== undefined ? { client: orchestrator.client } : {}),
+        ...(orchestrator.sessionName !== undefined ? { sessionName: orchestrator.sessionName } : {}),
+        ...(orchestrator.sessionDir !== undefined ? { sessionDir: orchestrator.sessionDir } : {}),
+        ...(orchestrator.clientId !== undefined ? { clientId: orchestrator.clientId } : {}),
+        ...(orchestrator.clientName !== undefined ? { clientName: orchestrator.clientName } : {}),
+        ...(orchestrator.projectId !== undefined ? { projectId: orchestrator.projectId } : {}),
+        ...(orchestrator.projectName !== undefined ? { projectName: orchestrator.projectName } : {}),
+        ...(orchestrator.hubTaskId !== undefined ? { hubTaskId: orchestrator.hubTaskId } : {}),
+        ...(orchestrator.hubTaskTitle !== undefined ? { hubTaskTitle: orchestrator.hubTaskTitle } : {}),
+        project: orchestrator.project,
+        prompt: orchestrator.prompt,
+        startedAt: orchestrator.startedAt,
+        endedAt: new Date(endedAtMs).toISOString(),
+        wallMs,
+        waitingMs,
+        workMs,
+        status: orchestrator.status,
+        orchestrator,
+        subagents,
+        usage,
+        segments,
+    };
+}
+/**
+ * Build one {@link TaskView} per *confirmed* orchestrator record, sorted by
+ * `startedAt`. An orchestrator-role record flagged `roleConfidence:
+ * "uncertain"` (ADR 0022) never anchors a task here — see
+ * {@link isConfirmedOrchestrator} and {@link uncertainRecords}.
+ */
+export function buildTasks(allRecords) {
+    const records = dedupeById(allRecords);
+    const orchestrators = records.filter(isConfirmedOrchestrator).sort((a, b) => toMs(a.startedAt) - toMs(b.startedAt));
+    const { childrenByOrchestratorId } = matchChildren(records);
+    return orchestrators.map((orchestrator) => buildTaskView(orchestrator, childrenByOrchestratorId.get(orchestrator.id) ?? []));
+}
+/** Subagent records that could not be matched to any orchestrator record. */
+export function orphanSubagents(records) {
+    return matchChildren(records).orphans;
+}
+/**
+ * Orchestrator-role records that could not be positively proven top-level
+ * (ADR 0022's "uncertain" state): no recognised child-env-marker matched,
+ * but a live tracked ancestor process was found. Never counted as a new
+ * task ({@link buildTasks} excludes them) and never synced as one, but
+ * never dropped either — surfaced here so `/kankaku doctor` and the report
+ * hint (SUBAGENT-REQ-017) can make the gap visible instead of silent.
+ */
+export function uncertainRecords(records) {
+    return records.filter((record) => record.role === "orchestrator" && record.roleConfidence === "uncertain");
+}
+/**
+ * SUBAGENT-REQ-015: flag confirmed-orchestrator records that share an OS
+ * pid AND overlap in time — a pattern that should never occur if pi only
+ * ever runs one session per process at a time, but is the observable
+ * signature an in-process nested session mechanism (if one existed) would
+ * leave behind: two independent `WorkTracker` records, same pid, running
+ * concurrently. Purely informational (`/kankaku doctor` reads this, see
+ * `adapters/kankaku-command.ts`) — it never changes {@link buildTasks}'
+ * own per-task `wallMs`, so a plain pi run or today's gentle-pi setup is
+ * completely unaffected; each flagged record still anchors its own
+ * `TaskView` exactly as before. `unionedWallMs` is provided (via the
+ * existing `unionMs` primitive, ADR 0006 — the interval-union rule stays
+ * in exactly this one place) so a human reading the doctor report can see
+ * what the corrected total would be, without kankaku silently changing any
+ * number on its own.
+ */
+export function detectSameProcessOverlaps(records) {
+    const orchestratorsByPid = new Map();
+    for (const record of records.filter(isConfirmedOrchestrator)) {
+        const group = orchestratorsByPid.get(record.pid);
+        if (group) {
+            group.push(record);
+        }
+        else {
+            orchestratorsByPid.set(record.pid, [record]);
+        }
+    }
+    const overlaps = [];
+    for (const [pid, group] of orchestratorsByPid) {
+        if (group.length < 2)
+            continue;
+        const intervals = group.map((record) => ({ start: toMs(record.startedAt), end: toMs(record.settledAt) }));
+        const anyOverlap = intervals.some((a, i) => intervals.some((b, j) => i !== j && a.start < b.end && b.start < a.end));
+        if (!anyOverlap)
+            continue;
+        overlaps.push({
+            pid,
+            recordIds: group.map((record) => record.id),
+            unionedWallMs: unionMs(intervals),
+        });
+    }
+    return overlaps;
+}
+/**
+ * Group tasks by `sessionId` (tasks without one fall under `"unknown"`).
+ * `wallMs` is the union of every interval — orchestrator and subagent alike
+ * — across all of the session's tasks, not a sum of per-task `wallMs`.
+ */
+export function buildSessions(tasks) {
+    const groups = new Map();
+    for (const task of tasks) {
+        const key = task.sessionId ?? "unknown";
+        const list = groups.get(key);
+        if (list) {
+            list.push(task);
+        }
+        else {
+            groups.set(key, [task]);
+        }
+    }
+    const sessions = [];
+    for (const [sessionId, sessionTasks] of groups) {
+        const intervals = sessionTasks.flatMap((task) => [
+            { start: toMs(task.orchestrator.startedAt), end: toMs(task.orchestrator.settledAt) },
+            ...task.subagents.map((child) => ({ start: toMs(child.startedAt), end: toMs(child.settledAt) })),
+        ]);
+        const wallMs = unionMs(intervals);
+        const waitingMs = sessionTasks.reduce((sum, task) => sum + task.waitingMs, 0);
+        const workMs = wallMs - waitingMs;
+        const startedAtMs = Math.min(...sessionTasks.map((task) => toMs(task.startedAt)));
+        const endedAtMs = Math.max(...sessionTasks.map((task) => toMs(task.endedAt)));
+        const usage = sumUsage(sessionTasks.map((task) => task.usage));
+        const segments = sumSegments(sessionTasks.map((task) => task.segments));
+        sessions.push({
+            sessionId,
+            project: sessionTasks[0].project,
+            startedAt: new Date(startedAtMs).toISOString(),
+            endedAt: new Date(endedAtMs).toISOString(),
+            wallMs,
+            waitingMs,
+            workMs,
+            tasks: sessionTasks,
+            usage,
+            segments,
+        });
+    }
+    return sessions.sort((a, b) => toMs(a.startedAt) - toMs(b.startedAt));
+}

package/dist/domain/work-record.d.ts

@@ -0,0 +1,236 @@
+/** Current schema version for {@link WorkRecord}. */
+export declare const WORK_RECORD_SCHEMA = 1;
+export type WorkRole = "orchestrator" | "subagent";
+export type WorkStatus = "completed" | "aborted" | "interrupted";
+export interface UsageTotals {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cost: number;
+}
+export interface SubagentSpan {
+    toolCallId: string;
+    agent: string;
+    mode: string;
+    taskId?: string;
+    ms: number;
+    /**
+     * The {@link SubagentProfile}'s `id` that matched this tool call
+     * (`domain/subagent-profile.ts`, ADR 0020), when unambiguous. Omitted
+     * when no profile's tool name matched at all, or when 2+ profiles
+     * registered the same tool name and could not be told apart
+     * (SUBAGENT-REQ-005) — `/kankaku doctor` surfaces both cases. Optional so
+     * an older-format span (written before profiles existed) still validates.
+     */
+    profile?: string;
+    /**
+     * C1 (CRITICAL fix, SUBAGENT-REQ-006 revised): nested LLM usage the
+     * matched profile's `readResult` forwarded from this span's tool result,
+     * kept SEPARATE from the orchestrator's own `WorkRecordCore.usage` —
+     * never folded in at write time (`domain/work-tracker.ts#onToolEnd`).
+     * `domain/task-view.ts#buildTasks` (ADR 0006: aggregation across
+     * spans/children stays in exactly this one place) is the only place that
+     * decides whether to add it to a task's total, based on whether a joined
+     * child record with the SAME `profile` already carries this same cost
+     * through its own confirmed-marker ancestry join — see
+     * `task-view.ts#unjoinedForwardedUsage`. Never set for an ambiguous
+     * tool-name match (nothing money-affecting is ever taken from one — see
+     * `domain/subagent-profile.ts#safeAmbiguousResultInfo`) or when the
+     * matched profile's `readResult` reported no usage at all. Optional so an
+     * older-format span (written before this field existed) still validates.
+     */
+    forwardedUsage?: Partial<UsageTotals>;
+}
+/**
+ * Identity of the tracked ancestor process a `subagent` record discovered
+ * via the machine-wide process registry (`~/.kankaku/run/<pid>.json`, see
+ * `ports/process-registry.ts`). Used to reunite a cross-worktree child with
+ * its orchestrator locally, before `buildTasks` runs (ADR 0023) — never
+ * set on an `orchestrator` record.
+ */
+export interface OrchestratorRef {
+    pid: number;
+    project: string;
+    startedAt: string;
+    /**
+     * The real orchestrator's resolved, absolute kankaku directory (its
+     * `RegistryEntry.dir`), when known — carried through a nested
+     * subagent-of-subagent chain via `domain/ancestry-match.ts#resolveOrchestratorRef`
+     * so a grandchild can route its writes (F1) straight to the true root's
+     * directory without a fresh registry lookup for an ancestor that may no
+     * longer even be alive. Optional so an older-format entry/record (written
+     * before this field existed) still validates and — when absent — the
+     * reader simply falls back to its own local directory rather than
+     * routing anywhere (see `adapters/extension.ts`'s write-routing).
+     */
+    dir?: string;
+}
+/**
+ * Fields the pure {@link WorkTracker} state machine can compute on its own,
+ * with no knowledge of the pi process or session it runs in.
+ */
+/** What started a record: absent = a user prompt (every record before this field existed). */
+export type RunTrigger = "extension";
+/** The `prompt` of a record no user prompt started — see {@link RunTrigger}. */
+export declare const EXTENSION_RUN_PROMPT = "(no user prompt \u2014 run started by an extension)";
+export interface WorkRecordCore {
+    schema: number;
+    id: string;
+    prompt: string;
+    /**
+     * `"extension"` when an extension, not the user, started this record's
+     * first run (e.g. gentle-pi waking the orchestrator because a background
+     * subagent finished). Optional and additive: `WORK_RECORD_SCHEMA` is
+     * unchanged and an older record without it still validates.
+     */
+    trigger?: RunTrigger;
+    startedAt: string;
+    settledAt: string;
+    wallMs: number;
+    waitingMs: number;
+    workMs: number;
+    /**
+     * Agent loops inside this record: the first one plus every
+     * `agent.continue()` pi ran before settling it (auto-retry after a provider
+     * error, overflow recovery, a queued steer/follow-up). Informational only —
+     * never used for time or cost.
+     */
+    runs: number;
+    turns: number;
+    tools: Record<string, number>;
+    subagents: SubagentSpan[];
+    /**
+     * Union milliseconds per tag spent in tool calls matched by a
+     * {@link SegmentRule} (e.g. `review`). Optional so older persisted
+     * records without this field still satisfy the type; callers reading
+     * from disk should treat a missing value as `{}`.
+     */
+    segments?: Record<string, number>;
+    usage: UsageTotals;
+    status: WorkStatus;
+    /**
+     * `true` when at least one turn of this run reported a real (finite)
+     * provider `cost` figure — as opposed to every turn's cost being
+     * absent/non-finite (a subscription/OAuth provider that reports token
+     * usage but no cost). Omitted (never `false`) when no turn ever observed
+     * one, so an old persisted record without this field reads exactly the
+     * same as a run that genuinely never saw a cost figure — both correctly
+     * map to `cost_quality: "unknown"` in `domain/hub-entry.ts`. Optional:
+     * adding it did not bump `WORK_RECORD_SCHEMA`.
+     */
+    costObserved?: true;
+}
+/** Process/session metadata the adapter layer attaches before persisting a record. */
+export interface WorkRecordMetadata {
+    role: WorkRole;
+    pid: number;
+    parentPid: number;
+    project: string;
+    sessionId?: string;
+    sessionFile?: string;
+    mode?: string;
+    model?: string;
+    /**
+     * The model's reasoning effort when the record settled, as pi names it
+     * (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`). Optional and
+     * additive; absent on older records and on a pi too old to report it.
+     */
+    thinkingLevel?: string;
+    /** Who this work is billed to. See {@link resolveClient} in `client-label.ts`. */
+    client?: string;
+    /** pi's session display name at the time this record settled. */
+    sessionName?: string;
+    /**
+     * Absolute session directory, set only when pi's session manager reports
+     * it as *non-default* (`SessionManager#usesDefaultSessionDir()` false) —
+     * exactly the condition under which pi's own `formatResumeCommand` adds
+     * `--session-dir` to the printed resume command. Omitted for an ordinary
+     * default-location session, so most records never carry this at all.
+     * Local-only today: the hub has no field for it yet (see README
+     * "Subagents" / AGENTS.md for the recommended `session_dir` migration).
+     */
+    sessionDir?: string;
+    /** Hub (PocketBase) client record id, when a hub target is active for this run. See `domain/work-target.ts`. */
+    clientId?: string;
+    /** Hub client display name, denormalised alongside `clientId` for readability. */
+    clientName?: string;
+    /** Hub (PocketBase) project record id, when the active hub target has a project. */
+    projectId?: string;
+    /** Hub project display name, denormalised alongside `projectId`. */
+    projectName?: string;
+    /** Hub `tasks` record id linked for this session (`/kankaku task pick`), when one is active. See `domain/work-target.ts#HubTask`. */
+    hubTaskId?: string;
+    /** Hub task title, denormalised alongside `hubTaskId`. */
+    hubTaskTitle?: string;
+    /** This machine's hostname, or `KANKAKU_MACHINE`, set only when the hub is configured. */
+    machine?: string;
+    /**
+     * Set only on an `orchestrator` record that could not be positively
+     * proven top-level (ADR 0022's four-state classification, applied on top
+     * of this still-binary `role`): no recognised child-env-marker matched,
+     * but a live tracked ancestor process was found in the machine-wide
+     * registry. Never counted as a new task locally or synced to the hub
+     * until the ambiguity is resolved (see README "Subagents"). Omitted
+     * entirely for a confirmed orchestrator, so a record from a build
+     * predating this field is indistinguishable from a confirmed one.
+     */
+    roleConfidence?: "uncertain";
+    /**
+     * The tracked ancestor a `subagent` record discovered via the
+     * machine-wide process registry. See {@link OrchestratorRef}.
+     */
+    orchestratorRef?: OrchestratorRef;
+    /**
+     * The {@link SubagentProfile} `id` (ADR 0020) whose child-env marker(s)
+     * confirmed THIS process's `role: "subagent"` classification — e.g.
+     * `"gentle-pi"` or `"pi-subagents"`. Set only when exactly one profile's
+     * marker matched (SUBAGENT-REQ-005 never guesses); omitted when this
+     * process's role came from ancestry alone (no known marker present, e.g.
+     * pi's bundled reference example) or from 2+ markers matching at once.
+     * `/kankaku doctor` reports which profile matched each record
+     * (SUBAGENT-REQ-017). Never set on an `orchestrator` record.
+     */
+    profile?: string;
+    /**
+     * Coding agent that MEASURED this record, lowercase slug (e.g. `"pi"`).
+     * Who measured, not who syncs — a different process (a standalone
+     * `kankaku` TUI, or a session for a different agent sharing the same
+     * `worklog.jsonl`) may later push this record to the hub, and must never
+     * overwrite this identity with its own. See kankaku-hub `docs/contract.md`
+     * "Agent and measurement quality" and `domain/hub-entry.ts`. Optional and
+     * additive: `WORK_RECORD_SCHEMA` is unchanged and an older record without
+     * it still validates.
+     */
+    agent?: string;
+    /** The measuring agent'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 record, lowercase slug (e.g. `"kankaku"`). Same who-measured-not-who-syncs rule as {@link agent}. */
+    plugin?: string;
+    /** This integration's own version, from its `package.json`, read once. */
+    pluginVersion?: string;
+}
+export type WorkRecord = WorkRecordCore & WorkRecordMetadata;
+export declare function emptyUsage(): UsageTotals;
+/** A finite number, or `0` for `undefined`/`NaN`/`Infinity`/non-numbers. */
+export declare function finiteOrZero(value: unknown): number;
+/**
+ * Share of prompt input tokens served from the provider's prompt cache:
+ * `cacheRead / (input + cacheRead + cacheWrite)`. pi's `usage.input` maps to
+ * the provider's `input_tokens`, which already excludes cached tokens, so
+ * the three fields are disjoint and this sum is the true denominator.
+ * Returns `undefined` when the denominator is `0` (nothing to compute a
+ * ratio from) rather than `0`, so callers never render a misleading `0%`.
+ * Non-finite fields count as `0`, mirroring {@link finiteOrZero}.
+ */
+export declare function cacheHitRatio(usage: {
+    input: number;
+    cacheRead: number;
+    cacheWrite: number;
+}): number | undefined;
+/**
+ * Runtime guard for a {@link WorkRecord} read back from disk. `readAll`
+ * skips lines that parse as JSON but fail this check, so a torn write or a
+ * record from an incompatible schema does not crash task/session views.
+ */
+export declare function isWorkRecord(value: unknown): value is WorkRecord;