kankaku 0.5.0 → 0.6.0

package/dist/domain/sync-plan.js

@@ -0,0 +1,182 @@
+/**
+ * Decide which tasks a sync run should push, without touching the network
+ * or the filesystem. Pure, no I/O — see `sync-runner.ts` for the adapter
+ * that drives this with a real clock, `WorkLog` and `WorkSink`.
+ *
+ * A task is not final the moment it is first written: a background
+ * subagent can settle after its orchestrator and extend the task's union
+ * (see `task-view.ts`), which is exactly why every sync also revisits a
+ * trailing window behind the watermark instead of only pushing brand-new
+ * tasks (proposal §6.0).
+ */
+import { computeCostQuality, computeSubagentLinkage } from "./hub-entry.js";
+const DEFAULT_WINDOW_HOURS = 24;
+/** How many already-synced, out-of-window rows one incremental run corrects at most; the rest wait for the next run (or `sync all`). */
+export const MAX_CORRECTIONS_PER_RUN = 50;
+function windowMs(hours) {
+    return hours * 60 * 60 * 1000;
+}
+/** Stable (key-sorted) JSON serialization so field order never changes a hash. */
+function stableStringify(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+    const record = value;
+    const keys = Object.keys(record).sort();
+    return `{${keys.map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`).join(",")}}`;
+}
+/** FNV-1a 32-bit over a UTF-16 code-unit stream — not a security hash, just a cheap deterministic change fingerprint. */
+function fingerprint(input) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < input.length; i++) {
+        hash ^= input.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16).padStart(8, "0");
+}
+/**
+ * Content hash of everything a re-sync could change: the measurement
+ * fields (never the assignment — a reassignment made in the web is never
+ * visible locally, and must never trigger a resync on its own). A task
+ * whose hash matches the last stored one is unchanged and can be skipped
+ * without a request. Includes the derived measurement-quality fields
+ * (`domain/hub-entry.ts`) too, not just the raw numbers they are computed
+ * from: a background subagent that joins *after* this task was first
+ * synced can turn `cost_quality`/`subagent_linkage` from `"unknown"`/
+ * `"unlinked"` into a better answer without any of the other numeric
+ * fields necessarily changing (e.g. a joined child with no cost of its own
+ * still flips `subagent_linkage`) — that must still trigger a resync.
+ * `waiting_quality` is a true constant (`domain/hub-entry.ts`'s
+ * `computeWaitingQuality`) and is deliberately left out: it can never
+ * change between two evaluations of the same task. `sessionDir` is also a
+ * measurement-style field (`domain/hub-entry.ts`'s `session_dir`, sent on
+ * both create and update) — its own change, e.g. a resume that switches to
+ * a non-default session directory, must trigger a resync on its own even
+ * when nothing else changed.
+ */
+export function computeTaskContentHash(task) {
+    return fingerprint(stableStringify({
+        endedAt: task.endedAt,
+        status: task.status,
+        wallMs: task.wallMs,
+        waitingMs: task.waitingMs,
+        workMs: task.workMs,
+        subagentCount: task.subagents.length,
+        usage: task.usage,
+        segments: task.segments,
+        costQuality: computeCostQuality(task),
+        subagentLinkage: computeSubagentLinkage(task),
+        sessionDir: task.sessionDir,
+        // `undefined` is dropped by the serialiser, so a task that never knew
+        // its reasoning effort keeps the hash it had before this field existed.
+        thinkingLevel: task.orchestrator.thinkingLevel,
+    }));
+}
+/**
+ * Decide which tasks need a request this run.
+ *
+ * Eligibility: every task, when there is no state yet, the state's
+ * `target` differs from the configured hub URL, or `options.full` is set
+ * (a full sync); otherwise only tasks with `endedAt` after
+ * `syncedThrough - window`. Within the eligible set, a task is only
+ * included in `toSync` when its current content hash differs from the one
+ * stored in `state.hashes` (absent, i.e. never synced, always counts as
+ * different).
+ */
+export function planSync(tasks, state, options) {
+    const windowHours = options.windowHours ?? DEFAULT_WINDOW_HOURS;
+    const isFullSync = options.full === true || state === undefined || state.target !== options.target;
+    const sorted = [...tasks].sort((a, b) => Date.parse(a.endedAt) - Date.parse(b.endedAt));
+    let eligible;
+    let outsideWindow;
+    if (isFullSync) {
+        eligible = sorted;
+        outsideWindow = [];
+    }
+    else {
+        const syncedThroughMs = state.syncedThrough ? Date.parse(state.syncedThrough) : Number.NEGATIVE_INFINITY;
+        const cutoff = syncedThroughMs - windowMs(windowHours);
+        eligible = sorted.filter((task) => Date.parse(task.endedAt) > cutoff);
+        outsideWindow = sorted.filter((task) => Date.parse(task.endedAt) <= cutoff);
+    }
+    const hashes = state?.hashes ?? {};
+    const changed = (task) => hashes[task.id] !== computeTaskContentHash(task);
+    // A row the hub ALREADY holds is corrected wherever it sits: the window
+    // bounds how far back NEW work is looked for, never whether a known row
+    // may go stale. A child can move between tasks (task-view.ts's rescue
+    // join, or a crash-recovered parent appearing later), so a task can
+    // SHRINK — skipping it would leave its old, larger cost on the hub next
+    // to the row the money moved to.
+    // Newest first and capped: anything that invalidates many stored hashes at
+    // once (a new field in the content hash, a damaged state file) must drain
+    // over several runs, never as one burst from an automatic sync. New work
+    // goes FIRST and corrections last, so a correction the hub keeps failing
+    // (the runner stops at the first transport error) can never hold newer
+    // rows back; the runner's watermark is a max, so the order is safe for it.
+    const allCorrections = outsideWindow.filter((task) => hashes[task.id] !== undefined && changed(task)).reverse();
+    const knownAndChanged = isFullSync ? allCorrections : allCorrections.slice(0, MAX_CORRECTIONS_PER_RUN);
+    const correctionsDeferred = allCorrections.length - knownAndChanged.length;
+    const toSync = [...eligible.filter(changed), ...knownAndChanged];
+    // R3: cheap, pure visibility into a task that changed but that this
+    // incremental run's window will not re-evaluate — see SyncPlan's doc
+    // comment. No extra work: `outsideWindow` is already computed above,
+    // this just re-applies the same hash-mismatch check to it.
+    const staleOutsideWindow = outsideWindow.filter((task) => hashes[task.id] === undefined);
+    return { toSync, unchangedCount: eligible.length - eligible.filter(changed).length, isFullSync, staleOutsideWindow, correctionsDeferred };
+}
+/**
+ * Drop hash entries for task ids that no longer exist in `tasks` (which
+ * should not normally happen since `worklog.jsonl` is append-only — this
+ * is a defensive backstop, not the normal path). `sync-state.json`'s
+ * `hashes` are otherwise kept **forever** for every task this process
+ * still knows about, regardless of how far outside the revisit window its
+ * `endedAt` has fallen (G2 fix).
+ *
+ * This used to also drop a hash once its task's `endedAt` fell behind
+ * `syncedThrough - window` — but `planSync`'s `staleOutsideWindow` treats a
+ * *missing* hash exactly like "content changed" (there is no third state
+ * for "unchanged but I forgot"), so that window-based pruning made every
+ * task older than the window look permanently changed, forever, the moment
+ * its hash was first pruned: `/kankaku sync status` would report a
+ * never-shrinking "changed outside the window" count that training taught
+ * users to ignore (the bug this rewrite fixes).
+ *
+ * Never pruning by window instead means `hashes` grows with the total
+ * number of distinct tasks a directory has ever synced, not with time — an
+ * FNV-1a hash is 8 hex chars and a task id (a `crypto.randomUUID()`) is 36,
+ * so each retained entry costs roughly 50 bytes of JSON. Measured: 10,000
+ * entries serialize to well under 1MB (see `tests/sync-plan.test.ts`'s
+ * state-size-bound test) — even a directory with a decade of daily,
+ * multi-task-per-day history stays a small, instantly-parseable file. A
+ * coarser design (e.g. one rolling digest per closed day) would bound the
+ * file even tighter, but cannot answer "which specific task changed" —
+ * `staleOutsideWindow` needs exactly that, per-task precision, to stay
+ * useful — so it was rejected in favour of this simpler, still-cheap
+ * per-task scheme.
+ *
+ * No migration is needed for an existing `sync-state.json`: it already has
+ * exactly this shape (`Record<taskId, hash>`), just with some outside-
+ * window entries already missing from a build that pruned them. The first
+ * sync after upgrading treats each of those exactly like "never synced" —
+ * a real fact this process cannot know is false, since the old hash is
+ * genuinely gone — and reports it once via `staleOutsideWindow`; once that
+ * task's hash is recorded again (an ordinary `sync all`, or simply being
+ * observed unchanged), this function never drops it again. See
+ * `tests/sync-plan.test.ts`'s "first sync after upgrading" test.
+ *
+ * Accumulated in a `Map` and emitted via `Object.fromEntries` (never
+ * `pruned[id] = ...` on a plain object), since a task id ultimately traces
+ * back to free-text worklog content: a value like `__proto__` written to a
+ * plain object would silently no-op (the inherited accessor ignores a
+ * non-object assignment) instead of being kept as an own property.
+ */
+export function pruneHashes(hashes, tasks) {
+    const knownIds = new Set(tasks.map((task) => task.id));
+    const pruned = new Map();
+    for (const [id, hash] of Object.entries(hashes)) {
+        if (knownIds.has(id))
+            pruned.set(id, hash);
+    }
+    return Object.fromEntries(pruned);
+}

package/dist/domain/task-view.d.ts

@@ -0,0 +1,113 @@
+import type { UsageTotals, WorkRecord, WorkStatus } from "./work-record.ts";
+/**
+ * One orchestrator run plus every subagent it spawned, with `wallMs`
+ * recomputed as the union of the orchestrator's span and each child's span
+ * — never their sum — because background children keep running in parallel
+ * after the orchestrator settles.
+ */
+export interface TaskView {
+    id: string;
+    sessionId?: string;
+    project: string;
+    prompt: string;
+    startedAt: string;
+    endedAt: string;
+    wallMs: number;
+    waitingMs: number;
+    workMs: number;
+    status: WorkStatus;
+    orchestrator: WorkRecord;
+    subagents: WorkRecord[];
+    usage: UsageTotals;
+    /** Who this task is billed to, from the orchestrator record only — subagent children do not carry their own. */
+    client?: string;
+    /** pi's session display name, from the orchestrator record. */
+    sessionName?: string;
+    /** Non-default session directory, from the orchestrator record. See `WorkRecordMetadata.sessionDir`. Local-only today — no hub field yet. */
+    sessionDir?: string;
+    /** Hub client record id, from the orchestrator record only. See `domain/work-target.ts`. */
+    clientId?: string;
+    /** Hub client display name, from the orchestrator record only. */
+    clientName?: string;
+    /** Hub project record id, from the orchestrator record only. */
+    projectId?: string;
+    /** Hub project display name, from the orchestrator record only. */
+    projectName?: string;
+    /**
+     * Per-tag total milliseconds across the orchestrator and every subagent,
+     * summed rather than unioned: unlike `wallMs`, segment intervals are not
+     * persisted on disk, so once a record settles its per-tag total is all
+     * that remains, and there is nothing left to union across records.
+     */
+    segments: Record<string, number>;
+}
+/** One or more tasks grouped by their pi session, with the same union rule. */
+export interface SessionView {
+    sessionId: string;
+    project: string;
+    startedAt: string;
+    endedAt: string;
+    wallMs: number;
+    waitingMs: number;
+    workMs: number;
+    tasks: TaskView[];
+    usage: UsageTotals;
+    /** Per-tag total milliseconds summed across the session's tasks. See {@link TaskView.segments}. */
+    segments: Record<string, number>;
+}
+/**
+ * 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 declare function sumUsage(totals: Array<Partial<UsageTotals> | undefined>): UsageTotals;
+export declare function dedupeById(records: WorkRecord[]): WorkRecord[];
+/**
+ * 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 declare function buildTasks(allRecords: WorkRecord[]): TaskView[];
+/** Subagent records that could not be matched to any orchestrator record. */
+export declare function orphanSubagents(records: WorkRecord[]): WorkRecord[];
+/**
+ * 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 declare function uncertainRecords(records: WorkRecord[]): WorkRecord[];
+/** One cluster of confirmed-orchestrator records sharing a pid with overlapping `[startedAt, settledAt]` windows — see {@link detectSameProcessOverlaps}. */
+export interface SameProcessOverlap {
+    pid: number;
+    recordIds: string[];
+    /** The union (never the sum) of every clustered record's own wall-time window, via `unionMs`. */
+    unionedWallMs: number;
+}
+/**
+ * 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 declare function detectSameProcessOverlaps(records: WorkRecord[]): SameProcessOverlap[];
+/**
+ * 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 declare function buildSessions(tasks: TaskView[]): SessionView[];