kankaku 0.7.1 → 0.8.2

package/dist/adapters/report.d.ts

@@ -0,0 +1,112 @@
+import type { SessionView, TaskView } from "../domain/task-view.ts";
+import type { WorkRecord, WorkRole } from "../domain/work-record.ts";
+export { localDay } from "../domain/day.ts";
+export interface RoleTotals {
+    workMs: number;
+    waitingMs: number;
+    wallMs: number;
+    count: number;
+    /** Estimated cost in USD, as priced by pi's model table. */
+    cost: number;
+    /** Prompt input tokens, summed across every record of this role. */
+    input: number;
+    /** Prompt-cache read tokens, summed across every record of this role. */
+    cacheRead: number;
+    /** Prompt-cache write tokens, summed across every record of this role. */
+    cacheWrite: number;
+    /** Per-tag total milliseconds summed across every record of this role. */
+    segments: Record<string, number>;
+}
+export interface TaskTotals {
+    count: number;
+    wallMs: number;
+    workMs: number;
+    /** Estimated cost in USD, orchestrator and subagents combined. */
+    cost: number;
+    /** Prompt input tokens, orchestrator and subagents combined. */
+    input: number;
+    /** Prompt-cache read tokens, orchestrator and subagents combined. */
+    cacheRead: number;
+    /** Prompt-cache write tokens, orchestrator and subagents combined. */
+    cacheWrite: number;
+    /** Per-tag total milliseconds summed across every task (orchestrator and subagents). */
+    segments: Record<string, number>;
+}
+export type Summary = Record<WorkRole, RoleTotals> & {
+    tasks: TaskTotals;
+};
+export interface SummarizeOptions {
+    /** Local day in `YYYY-MM-DD` format. Defaults to today when `all` is not set. */
+    day?: string;
+    /** Include every record regardless of day. */
+    all?: boolean;
+}
+/**
+ * Aggregate work records by role, restricted to one local day unless `all`
+ * is set. Also computes a `tasks` segment (union-based `wallMs`/`workMs`
+ * over one orchestrator run and its subagents) for tasks whose `startedAt`
+ * falls on the same day.
+ */
+export declare function summarize(records: WorkRecord[], options: SummarizeOptions): Summary;
+/**
+ * Count of `uncertain` records (ADR 0022) within the same day scope
+ * `summarize` uses, so the `/kankaku` report can surface a one-line hint
+ * when some records are silently excluded from the task count
+ * (SUBAGENT-REQ-017): an undercount must never be silent.
+ */
+export declare function countUncertain(records: WorkRecord[], options: SummarizeOptions): number;
+/** Render a short, human-readable summary for the `/kankaku` command. */
+export declare function formatReport(summary: Summary): string;
+/** Render one line per task: time, client (when present), union-based wall/work, cost, non-zero segment tags, subagent count, and a truncated prompt (`…` marks a cut). */
+export declare function formatTasks(tasks: TaskView[]): string;
+export interface ClientTotals {
+    wallMs: number;
+    waitingMs: number;
+    workMs: number;
+    /** Estimated cost in USD, summed across this client's tasks. */
+    cost: number;
+    /** Prompt input tokens, summed across this client's tasks. */
+    input: number;
+    /** Prompt-cache read tokens, summed across this client's tasks. */
+    cacheRead: number;
+    /** Prompt-cache write tokens, summed across this client's tasks. */
+    cacheWrite: number;
+    count: number;
+}
+/**
+ * Aggregate tasks by billing client (see `domain/client-label.ts`), summing
+ * work/waiting/wall time, cost, and task count. Tasks without a `client`
+ * are grouped under `"(none)"`. Returned as a `Map` rather than a plain
+ * object so an attacker-controlled client name can never repoint a
+ * prototype property.
+ */
+export declare function summarizeByClient(tasks: TaskView[]): Map<string, ClientTotals>;
+export interface ProjectTotals {
+    /** Display name: the project's `projectName`, or `"(no project)"` for the ungrouped bucket. */
+    name: string;
+    wallMs: number;
+    waitingMs: number;
+    workMs: number;
+    /** Estimated cost in USD, summed across this project's tasks. */
+    cost: number;
+    /** Prompt input tokens, summed across this project's tasks. */
+    input: number;
+    /** Prompt-cache read tokens, summed across this project's tasks. */
+    cacheRead: number;
+    /** Prompt-cache write tokens, summed across this project's tasks. */
+    cacheWrite: number;
+    count: number;
+}
+/**
+ * Aggregate tasks by hub project (see `domain/work-target.ts`), keyed by
+ * `projectId` (so two projects that happen to share a display name are
+ * never merged) with the name denormalised alongside for display. Tasks
+ * without a `projectId` are grouped under `"(no project)"`.
+ */
+export declare function summarizeByProject(tasks: TaskView[]): Map<string, ProjectTotals>;
+/** Render one line per project, sorted alphabetically by display name, with work/waiting/wall time, cost, and task count. */
+export declare function formatProjects(totals: Map<string, ProjectTotals>): string;
+/** Render one line per client, sorted alphabetically, with work/waiting/wall time, cost, and task count. */
+export declare function formatClients(totals: Map<string, ClientTotals>): string;
+/** Render one line per session: truncated id, time range, union-based wall/work, cost, non-zero segment tags, and task count. */
+export declare function formatSessions(sessions: SessionView[]): string;

package/dist/adapters/report.js

@@ -0,0 +1,236 @@
+import { buildTasks, uncertainRecords } from "../domain/task-view.js";
+import { localDay } from "../domain/day.js";
+import { cacheHitRatio, finiteOrZero } from "../domain/work-record.js";
+export { localDay } from "../domain/day.js";
+const ROLES = ["orchestrator", "subagent"];
+function emptyTotals() {
+    return { workMs: 0, waitingMs: 0, wallMs: 0, count: 0, cost: 0, input: 0, cacheRead: 0, cacheWrite: 0, segments: {} };
+}
+/**
+ * Add per-tag milliseconds from `segments` (missing on older records) into
+ * `into`, a `Map` rather than a plain object so a tag from a hand-edited
+ * worklog line named `__proto__` or `constructor` accumulates as a normal
+ * entry instead of silently reading (and arithmetically corrupting) an
+ * inherited `Object.prototype` value.
+ */
+function addSegments(into, segments) {
+    for (const [tag, ms] of Object.entries(segments ?? {})) {
+        into.set(tag, (into.get(tag) ?? 0) + ms);
+    }
+}
+/**
+ * Aggregate work records by role, restricted to one local day unless `all`
+ * is set. Also computes a `tasks` segment (union-based `wallMs`/`workMs`
+ * over one orchestrator run and its subagents) for tasks whose `startedAt`
+ * falls on the same day.
+ */
+export function summarize(records, options) {
+    const targetDay = options.all ? undefined : (options.day ?? localDay(new Date().toISOString()));
+    const summary = {
+        orchestrator: emptyTotals(),
+        subagent: emptyTotals(),
+        tasks: { count: 0, wallMs: 0, workMs: 0, cost: 0, input: 0, cacheRead: 0, cacheWrite: 0, segments: {} },
+    };
+    // Accumulated in Maps (see `addSegments`) and only converted to the
+    // returned plain objects at the very end, via `Object.fromEntries`.
+    const segmentsByRole = { orchestrator: new Map(), subagent: new Map() };
+    const taskSegments = new Map();
+    for (const record of records) {
+        if (targetDay !== undefined && localDay(record.startedAt) !== targetDay)
+            continue;
+        const totals = summary[record.role];
+        totals.workMs += record.workMs;
+        totals.waitingMs += record.waitingMs;
+        totals.wallMs += record.wallMs;
+        totals.count += 1;
+        totals.cost += finiteOrZero(record.usage.cost);
+        totals.input += finiteOrZero(record.usage.input);
+        totals.cacheRead += finiteOrZero(record.usage.cacheRead);
+        totals.cacheWrite += finiteOrZero(record.usage.cacheWrite);
+        addSegments(segmentsByRole[record.role], record.segments);
+    }
+    const tasks = buildTasks(records).filter((task) => targetDay === undefined || localDay(task.startedAt) === targetDay);
+    for (const task of tasks) {
+        summary.tasks.count += 1;
+        summary.tasks.wallMs += task.wallMs;
+        summary.tasks.workMs += task.workMs;
+        summary.tasks.cost += task.usage.cost;
+        summary.tasks.input += finiteOrZero(task.usage.input);
+        summary.tasks.cacheRead += finiteOrZero(task.usage.cacheRead);
+        summary.tasks.cacheWrite += finiteOrZero(task.usage.cacheWrite);
+        addSegments(taskSegments, task.segments);
+    }
+    summary.orchestrator.segments = Object.fromEntries(segmentsByRole.orchestrator);
+    summary.subagent.segments = Object.fromEntries(segmentsByRole.subagent);
+    summary.tasks.segments = Object.fromEntries(taskSegments);
+    return summary;
+}
+/**
+ * Count of `uncertain` records (ADR 0022) within the same day scope
+ * `summarize` uses, so the `/kankaku` report can surface a one-line hint
+ * when some records are silently excluded from the task count
+ * (SUBAGENT-REQ-017): an undercount must never be silent.
+ */
+export function countUncertain(records, options) {
+    const targetDay = options.all ? undefined : (options.day ?? localDay(new Date().toISOString()));
+    return uncertainRecords(records).filter((record) => targetDay === undefined || localDay(record.startedAt) === targetDay).length;
+}
+function formatMinutes(ms) {
+    const totalSeconds = Math.round(ms / 1000);
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = totalSeconds % 60;
+    return `${minutes}m${String(seconds).padStart(2, "0")}s`;
+}
+/** Estimated USD cost with two decimals, e.g. `$1.23`. */
+function formatCost(cost) {
+    return `$${cost.toFixed(2)}`;
+}
+function formatTime(iso) {
+    const date = new Date(iso);
+    const hours = String(date.getHours()).padStart(2, "0");
+    const minutes = String(date.getMinutes()).padStart(2, "0");
+    return `${hours}:${minutes}`;
+}
+/** Render `cache hit NN%` (integer percent) for a usage totals triple, or `undefined` when the ratio is undefined (nothing recorded). */
+function formatCacheHit(usage) {
+    const ratio = cacheHitRatio(usage);
+    return ratio === undefined ? undefined : `cache hit ${Math.round(ratio * 100)}%`;
+}
+/** Render non-zero segment tags as `tag Xm00s` pairs, sorted alphabetically, joined by `, `. Undefined when none are non-zero. */
+function formatSegmentTags(segments) {
+    const tags = Object.keys(segments)
+        .filter((tag) => segments[tag] > 0)
+        .sort();
+    if (tags.length === 0)
+        return undefined;
+    return tags.map((tag) => `${tag} ${formatMinutes(segments[tag])}`).join(", ");
+}
+/** Render a short, human-readable summary for the `/kankaku` command. */
+export function formatReport(summary) {
+    const lines = ROLES.map((role) => {
+        const totals = summary[role];
+        const cacheHit = formatCacheHit(totals);
+        const cacheHitPart = cacheHit !== undefined ? `, ${cacheHit}` : "";
+        return `${role}: work ${formatMinutes(totals.workMs)}, waiting ${formatMinutes(totals.waitingMs)}, ${totals.count} record(s), ${formatCost(totals.cost)}${cacheHitPart}`;
+    });
+    const tasksCacheHit = formatCacheHit(summary.tasks);
+    const tasksCacheHitPart = tasksCacheHit !== undefined ? `, ${tasksCacheHit}` : "";
+    lines.push(`tasks: ${summary.tasks.count}, wall ${formatMinutes(summary.tasks.wallMs)}, work ${formatMinutes(summary.tasks.workMs)}, ${formatCost(summary.tasks.cost)}${tasksCacheHitPart}`);
+    const segmentTags = formatSegmentTags(summary.tasks.segments);
+    if (segmentTags !== undefined) {
+        lines.push(`segments: ${segmentTags}`);
+    }
+    return lines.join(" | ");
+}
+/** Maximum visible width of a task prompt before it is truncated with an ellipsis marker. */
+const PROMPT_DISPLAY_LIMIT = 60;
+/** Truncate `text` to `limit` visible characters, appending `…` (counted within the limit) when it was cut. */
+function truncateWithEllipsis(text, limit) {
+    return text.length > limit ? `${text.slice(0, limit - 1)}…` : text;
+}
+/** Render one line per task: time, client (when present), union-based wall/work, cost, non-zero segment tags, subagent count, and a truncated prompt (`…` marks a cut). */
+export function formatTasks(tasks) {
+    if (tasks.length === 0)
+        return "no tasks";
+    return tasks
+        .map((task) => {
+        const prompt = truncateWithEllipsis(task.prompt, PROMPT_DISPLAY_LIMIT);
+        const segmentTags = formatSegmentTags(task.segments);
+        const segmentPart = segmentTags !== undefined ? `  ${segmentTags}` : "";
+        const clientPart = task.client !== undefined ? `  client:${task.client}` : "";
+        const cacheHit = formatCacheHit(task.usage);
+        const cacheHitPart = cacheHit !== undefined ? `  ${cacheHit}` : "";
+        return `${formatTime(task.startedAt)}${clientPart}  wall ${formatMinutes(task.wallMs)}  work ${formatMinutes(task.workMs)}  ${formatCost(task.usage.cost)}${cacheHitPart}${segmentPart}  subagents ${task.subagents.length}  ${prompt}`;
+    })
+        .join("\n");
+}
+/** Client name under which tasks without a resolved client are grouped. */
+const NO_CLIENT = "(none)";
+/**
+ * Aggregate tasks by billing client (see `domain/client-label.ts`), summing
+ * work/waiting/wall time, cost, and task count. Tasks without a `client`
+ * are grouped under `"(none)"`. Returned as a `Map` rather than a plain
+ * object so an attacker-controlled client name can never repoint a
+ * prototype property.
+ */
+export function summarizeByClient(tasks) {
+    const totals = new Map();
+    for (const task of tasks) {
+        const key = task.client ?? NO_CLIENT;
+        const entry = totals.get(key) ?? { wallMs: 0, waitingMs: 0, workMs: 0, cost: 0, input: 0, cacheRead: 0, cacheWrite: 0, count: 0 };
+        entry.wallMs += task.wallMs;
+        entry.waitingMs += task.waitingMs;
+        entry.workMs += task.workMs;
+        entry.cost += finiteOrZero(task.usage.cost);
+        entry.input += finiteOrZero(task.usage.input);
+        entry.cacheRead += finiteOrZero(task.usage.cacheRead);
+        entry.cacheWrite += finiteOrZero(task.usage.cacheWrite);
+        entry.count += 1;
+        totals.set(key, entry);
+    }
+    return totals;
+}
+/** Key (and display name) under which tasks without a resolved project are grouped. */
+const NO_PROJECT = "(no project)";
+/**
+ * Aggregate tasks by hub project (see `domain/work-target.ts`), keyed by
+ * `projectId` (so two projects that happen to share a display name are
+ * never merged) with the name denormalised alongside for display. Tasks
+ * without a `projectId` are grouped under `"(no project)"`.
+ */
+export function summarizeByProject(tasks) {
+    const totals = new Map();
+    for (const task of tasks) {
+        const key = task.projectId ?? NO_PROJECT;
+        const name = task.projectId !== undefined ? (task.projectName ?? task.projectId) : NO_PROJECT;
+        const entry = totals.get(key) ?? { name, wallMs: 0, waitingMs: 0, workMs: 0, cost: 0, input: 0, cacheRead: 0, cacheWrite: 0, count: 0 };
+        entry.wallMs += task.wallMs;
+        entry.waitingMs += task.waitingMs;
+        entry.workMs += task.workMs;
+        entry.cost += finiteOrZero(task.usage.cost);
+        entry.input += finiteOrZero(task.usage.input);
+        entry.cacheRead += finiteOrZero(task.usage.cacheRead);
+        entry.cacheWrite += finiteOrZero(task.usage.cacheWrite);
+        entry.count += 1;
+        totals.set(key, entry);
+    }
+    return totals;
+}
+/** Render one line per project, sorted alphabetically by display name, with work/waiting/wall time, cost, and task count. */
+export function formatProjects(totals) {
+    if (totals.size === 0)
+        return "no projects";
+    return Array.from(totals.values())
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((t) => {
+        const cacheHit = formatCacheHit(t);
+        const cacheHitPart = cacheHit !== undefined ? `  ${cacheHit}` : "";
+        return `${t.name}  work ${formatMinutes(t.workMs)}  waiting ${formatMinutes(t.waitingMs)}  wall ${formatMinutes(t.wallMs)}  ${formatCost(t.cost)}${cacheHitPart}  tasks ${t.count}`;
+    })
+        .join("\n");
+}
+/** Render one line per client, sorted alphabetically, with work/waiting/wall time, cost, and task count. */
+export function formatClients(totals) {
+    if (totals.size === 0)
+        return "no clients";
+    return Array.from(totals.entries())
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([client, t]) => {
+        const cacheHit = formatCacheHit(t);
+        const cacheHitPart = cacheHit !== undefined ? `  ${cacheHit}` : "";
+        return `${client}  work ${formatMinutes(t.workMs)}  waiting ${formatMinutes(t.waitingMs)}  wall ${formatMinutes(t.wallMs)}  ${formatCost(t.cost)}${cacheHitPart}  tasks ${t.count}`;
+    })
+        .join("\n");
+}
+/** Render one line per session: truncated id, time range, union-based wall/work, cost, non-zero segment tags, and task count. */
+export function formatSessions(sessions) {
+    if (sessions.length === 0)
+        return "no sessions";
+    return sessions
+        .map((session) => {
+        const segmentTags = formatSegmentTags(session.segments);
+        const segmentPart = segmentTags !== undefined ? `  ${segmentTags}` : "";
+        return `${session.sessionId.slice(0, 8)}  ${formatTime(session.startedAt)}–${formatTime(session.endedAt)}  wall ${formatMinutes(session.wallMs)}  work ${formatMinutes(session.workMs)}  ${formatCost(session.usage.cost)}${segmentPart}  tasks ${session.tasks.length}`;
+    })
+        .join("\n");
+}

package/dist/adapters/sync-runner.d.ts

@@ -5,6 +5,7 @@
  * Never throws to its caller: every failure mode is folded into the
  * returned {@link SyncSummary}.
  */
+import type { SyncState } from "../domain/sync-plan.ts";
 import type { TaskView } from "../domain/task-view.ts";
 import type { Clock } from "../ports/clock.ts";
 import type { WorkLog } from "../ports/work-log.ts";
@@ -70,8 +71,26 @@ export declare function runSync(deps: SyncRunnerDeps, options?: {
     full?: boolean;
     trigger?: SyncTrigger;
 }): Promise<SyncSummary>;
-/** Number of tasks pending a sync right now, for `/kankaku sync status` — computed locally, no network. */
+/**
+ * Number of tasks pending a sync right now — computed locally, no network.
+ *
+ * @deprecated Superseded by {@link computeSyncStatus}, which returns the same
+ * `pending` count together with `state` and `staleOutsideWindow`. Nothing in
+ * kankaku calls this any more; it stays only because it is part of the
+ * published `kankaku/hub` surface. It will be removed in the next minor.
+ */
 export declare function pendingCount(tasks: TaskView[], state: ReturnType<SyncStateStore["read"]>, target: string, windowHours?: number): number;
+/**
+ * {@link computeSyncStatus}'s return shape, exported so a caller (e.g.
+ * `hub-actions.ts#buildSyncStatusLines`, or a future standalone TUI reusing
+ * `kankaku/hub`) can depend on this type without importing anything that
+ * touches `@earendil-works/*` — see AGENTS.md "Code conventions".
+ */
+export interface SyncStatusSnapshot {
+    state: SyncState | undefined;
+    pending: number;
+    staleOutsideWindow: number;
+}
 /**
  * `/kankaku sync status`: the persisted state, a locally-computed pending
  * count, and (R3) how many tasks changed since their last sync but fall
@@ -79,11 +98,7 @@ export declare function pendingCount(tasks: TaskView[], state: ReturnType<SyncSt
  * (see `domain/sync-plan.ts#SyncPlan.staleOutsideWindow`, and README "Hub
  * (PocketBase)" > "Sync" > "Limitations"). No network.
  */
-export declare function computeSyncStatus(log: WorkLog, stateStore: SyncStateStore, target: string, windowHours?: number): {
-    state: ReturnType<SyncStateStore["read"]>;
-    pending: number;
-    staleOutsideWindow: number;
-};
+export declare function computeSyncStatus(log: WorkLog, stateStore: SyncStateStore, target: string, windowHours?: number): SyncStatusSnapshot;
 /**
  * Wrap an async function so concurrent callers share one in-flight call
  * instead of starting a new one each — kankaku's single-flight guard for

package/dist/adapters/sync-runner.js

@@ -60,7 +60,11 @@ function isThrottled(state, trigger, now, minIntervalMs) {
 export async function runSync(deps, options = {}) {
     const startedAt = deps.clock.now();
     if (options.trigger !== undefined) {
-        const peek = deps.stateStore.read();
+        // Gated like every other read below: a state written for another hub
+        // says nothing about THIS hub, so neither its `logVersion` (which
+        // would otherwise skip the new hub's very first run until the next
+        // record is appended) nor its `lastRunAt` throttle may apply.
+        const peek = stateForTarget(deps, deps.stateStore.read());
         const currentVersion = deps.log.version?.();
         const versionUnchanged = currentVersion !== undefined && peek?.logVersion === currentVersion;
         if (versionUnchanged && peek?.lastError === undefined) {
@@ -75,10 +79,17 @@ export async function runSync(deps, options = {}) {
     try {
         lockAcquired = deps.stateStore.tryLock();
         if (!lockAcquired) {
-            const state = deps.stateStore.read();
+            const state = stateForTarget(deps, deps.stateStore.read());
             return { ...emptySummary(deps.clock.now() - startedAt, state?.syncedThrough), locked: true };
         }
         const state = deps.stateStore.read();
+        // A state from another hub is ignored wholesale, on EVERY path below
+        // (the summary, the error path, and the successful merge): its
+        // watermark and its hashes describe rows the configured hub does not
+        // have (mirrors `domain/sync-plan.ts#planSync`'s gate). `planSync`
+        // still receives the raw `state`, since it applies that same gate
+        // itself and its `target` comparison is what makes the run a full one.
+        const priorState = stateForTarget(deps, state);
         // Captured once, here, and persisted as-is below: this is the version
         // the tasks below were actually built from, not whatever the log might
         // become by the time an awaited push finishes.
@@ -93,10 +104,15 @@ export async function runSync(deps, options = {}) {
             // WorkSink implementations are expected never to throw, but this
             // runner must hold that guarantee even if one does.
             const message = error instanceof Error ? error.message : String(error);
-            const summary = emptySummary(deps.clock.now() - startedAt, state?.syncedThrough);
+            const summary = emptySummary(deps.clock.now() - startedAt, priorState?.syncedThrough);
             summary.skipped = plan.unchangedCount;
             summary.error = message;
-            persistError(deps, state, message, logVersionAtRead);
+            // `priorState`, never `state`: a throwing sink on the first run
+            // against a NEW hub must not carry the old hub's hashes and
+            // watermark over under the new target, or the next run would
+            // skip every task as "unchanged" (the exact bug 0.8.1 fixed on the
+            // successful path).
+            persistError(deps, priorState, message, logVersionAtRead);
             return summary;
         }
         const byId = new Map(plan.toSync.map((task) => [task.id, task]));
@@ -111,7 +127,7 @@ export async function runSync(deps, options = {}) {
         const unassigned = new Map();
         let uploaded = 0;
         let updated = 0;
-        let syncedThrough = state?.syncedThrough;
+        let syncedThrough = priorState?.syncedThrough;
         let stopError;
         // Whether at least one task was actually resolved (pushed or recorded
         // as failed) this run — as opposed to the run stopping on its very
@@ -147,13 +163,16 @@ export async function runSync(deps, options = {}) {
             }
             else {
                 // "error": a network/timeout/5xx/auth failure. Stop here — nothing
-                // after this point in the (chronologically sorted) results is
-                // considered resolved, so syncedThrough does not advance past it.
+                // after this point in the results is considered resolved. The
+                // results follow `plan.toSync`'s order (new work oldest-first,
+                // then corrections newest-first), and `syncedThrough` is a max
+                // over what WAS resolved, so stopping early can only leave it
+                // lower, never advance it past an unresolved task.
                 stopError = result.outcome.reason;
                 break;
             }
         }
-        const mergedHashes = { ...(state?.hashes ?? {}), ...Object.fromEntries(newHashes) };
+        const mergedHashes = { ...(priorState?.hashes ?? {}), ...Object.fromEntries(newHashes) };
         // G2: no longer window-bound — see `domain/sync-plan.ts#pruneHashes`'s
         // doc comment. `tasks` here is every task `buildTasks` currently knows
         // about (the full `readAll()`, not just this run's eligible/window
@@ -188,6 +207,11 @@ export async function runSync(deps, options = {}) {
             deps.stateStore.unlock();
     }
 }
+/** `state` when it was written against `deps.target`; `undefined` (as if there were no state at all) when it belongs to another hub. */
+function stateForTarget(deps, state) {
+    return state !== undefined && state.target === deps.target ? state : undefined;
+}
+/** Persist a failed run. `state` must already be gated by {@link stateForTarget}: what it carries is re-written under `deps.target`. */
 function persistError(deps, state, message, logVersionAtRead) {
     deps.stateStore.write({
         target: deps.target,
@@ -198,7 +222,14 @@ function persistError(deps, state, message, logVersionAtRead) {
         lastRunAt: deps.clock.now(),
     });
 }
-/** Number of tasks pending a sync right now, for `/kankaku sync status` — computed locally, no network. */
+/**
+ * Number of tasks pending a sync right now — computed locally, no network.
+ *
+ * @deprecated Superseded by {@link computeSyncStatus}, which returns the same
+ * `pending` count together with `state` and `staleOutsideWindow`. Nothing in
+ * kankaku calls this any more; it stays only because it is part of the
+ * published `kankaku/hub` surface. It will be removed in the next minor.
+ */
 export function pendingCount(tasks, state, target, windowHours) {
     const plan = planSync(tasks, state, { target, ...(windowHours !== undefined ? { windowHours } : {}) });
     return plan.toSync.length + plan.correctionsDeferred;

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

@@ -145,18 +145,35 @@ export interface TaskEntryPayload {
     legacy_client_label: string;
     repo_project: string;
     schema: number;
+    /** Coding agent that MEASURED this task, lowercase slug — the orchestrator record's own {@link WorkRecordMetadata.agent} when it carries one (who measured, not who syncs), else `ctx.agent` (the syncing process's own identity) as a legacy fallback. See {@link WorkRecordMetadata.agent}. */
     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;
+    /** The integration that wrote this task's records, lowercase slug — same record-wins-over-ctx rule as {@link agent}. */
     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">;
+/**
+ * `TaskEntryPayload` minus the assignment fields — what an update sends. See
+ * the module docs' CRITICAL rule.
+ *
+ * `agent`/`agent_version`/`plugin`/`plugin_version` are optional here (unlike
+ * on `TaskEntryPayload`, where they are always sent on create): an update for
+ * a task whose orchestrator record carries no who-measured identity (a
+ * legacy record, written before this feature existed) omits them entirely,
+ * so a re-sync by a DIFFERENT process never overwrites a row's original
+ * identity with its own. See {@link buildTaskEntryUpdatePayload}.
+ */
+export type TaskEntryUpdatePayload = Omit<TaskEntryPayload, "client" | "project" | "task" | "legacy_client_label" | "agent" | "agent_version" | "plugin" | "plugin_version"> & {
+    agent?: string;
+    agent_version?: string;
+    plugin?: string;
+    plugin_version?: string;
+};
 /** Build the full `task_entries` payload for a **create** request — every field, including assignment. */
 export declare function buildTaskEntryCreatePayload(task: TaskView, ctx: HubEntryContext): TaskEntryPayload;
 /**
@@ -164,6 +181,13 @@ export declare function buildTaskEntryCreatePayload(task: TaskView, ctx: HubEntr
  * 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.
+ *
+ * `agent`/`agent_version`/`plugin`/`plugin_version` are included ONLY when
+ * the orchestrator record itself carries a who-measured `agent` — otherwise
+ * they are OMITTED entirely (never sent as `ctx`'s own identity), so a
+ * re-sync of a legacy record by a different process never overwrites the
+ * row's original identity in the hub. See `domain/work-record.ts`'s
+ * "Measurement rules" and {@link resolveTaskIdentity}.
  */
 export declare function buildTaskEntryUpdatePayload(task: TaskView, ctx: HubEntryContext): TaskEntryUpdatePayload;
 /** One `work_records` row — raw per-`WorkRecord` detail, always `rollup: false`. */

package/dist/domain/hub-entry.js

@@ -126,9 +126,34 @@ export function computeSubagentLinkage(task) {
         return "not_applicable";
     return task.subagents.length >= spanCount ? "linked" : "unlinked";
 }
+/**
+ * The who-measured identity (`agent`/`agentVersion`/`plugin`/`pluginVersion`)
+ * for a task's payload: the orchestrator record's own fields, taken as a
+ * unit, when it carries an `agent` — a missing version on the record is
+ * omitted, never backfilled from `ctx` — otherwise `ctx`'s identity (the
+ * syncing process's own), exactly as before this feature existed. See
+ * `domain/work-record.ts#WorkRecordMetadata.agent`'s doc comment.
+ */
+function resolveTaskIdentity(task, ctx) {
+    const orchestrator = task.orchestrator;
+    if (orchestrator.agent !== undefined) {
+        // The record's four fields are taken as a unit. A record written by an
+        // integration that stamped `agent` but not `plugin` gets the syncing
+        // context's `plugin` ONLY on create, so the row is never blank; the
+        // update payload below never resends a plugin the record does not own.
+        return {
+            agent: orchestrator.agent,
+            agentVersion: orchestrator.agentVersion,
+            plugin: orchestrator.plugin ?? ctx.plugin,
+            pluginVersion: orchestrator.plugin !== undefined ? orchestrator.pluginVersion : undefined,
+        };
+    }
+    return { agent: ctx.agent, agentVersion: ctx.agentVersion, plugin: ctx.plugin, pluginVersion: ctx.pluginVersion };
+}
 /** 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, ctx.tasks);
+    const identity = resolveTaskIdentity(task, ctx);
     return {
         task_id: task.id,
         client: assignment.clientId,
@@ -158,11 +183,11 @@ export function buildTaskEntryCreatePayload(task, ctx) {
         legacy_client_label: assignment.legacyClientLabel,
         repo_project: task.project,
         schema: task.orchestrator.schema,
-        agent: ctx.agent,
-        ...(ctx.agentVersion !== undefined ? { agent_version: ctx.agentVersion } : {}),
+        agent: identity.agent,
+        ...(identity.agentVersion !== undefined ? { agent_version: identity.agentVersion } : {}),
         ...(task.sessionDir !== undefined ? { session_dir: task.sessionDir } : {}),
-        plugin: ctx.plugin,
-        ...(ctx.pluginVersion !== undefined ? { plugin_version: ctx.pluginVersion } : {}),
+        plugin: identity.plugin,
+        ...(identity.pluginVersion !== undefined ? { plugin_version: identity.pluginVersion } : {}),
         waiting_quality: computeWaitingQuality(),
         cost_quality: computeCostQuality(task),
         subagent_linkage: computeSubagentLinkage(task),
@@ -173,10 +198,29 @@ export function buildTaskEntryCreatePayload(task, ctx) {
  * 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.
+ *
+ * `agent`/`agent_version`/`plugin`/`plugin_version` are included ONLY when
+ * the orchestrator record itself carries a who-measured `agent` — otherwise
+ * they are OMITTED entirely (never sent as `ctx`'s own identity), so a
+ * re-sync of a legacy record by a different process never overwrites the
+ * row's original identity in the hub. See `domain/work-record.ts`'s
+ * "Measurement rules" and {@link resolveTaskIdentity}.
  */
 export function buildTaskEntryUpdatePayload(task, ctx) {
-    const { client: _client, project: _project, task: _task, legacy_client_label: _legacy, ...rest } = buildTaskEntryCreatePayload(task, ctx);
-    return rest;
+    const { client: _client, project: _project, task: _task, legacy_client_label: _legacy, agent, agent_version, plugin, plugin_version, ...rest } = buildTaskEntryCreatePayload(task, ctx);
+    if (task.orchestrator.agent === undefined)
+        return rest;
+    // `plugin`/`plugin_version` are resent only when the record itself carries
+    // them; a record with `agent` but no `plugin` must never have the syncing
+    // process's plugin written over the row's original one.
+    const recordHasPlugin = task.orchestrator.plugin !== undefined;
+    return {
+        ...rest,
+        agent,
+        ...(agent_version !== undefined ? { agent_version } : {}),
+        ...(recordHasPlugin ? { plugin } : {}),
+        ...(recordHasPlugin && plugin_version !== undefined ? { plugin_version } : {}),
+    };
 }
 /**
  * Build one `work_records` payload from a raw {@link WorkRecord}