kankaku 0.7.0 → 0.8.0

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

@@ -198,7 +198,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}

package/dist/domain/sync-plan.js

@@ -71,6 +71,16 @@ export function computeTaskContentHash(task) {
         // `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,
+        // A task gaining a who-measured identity
+        // (domain/hub-entry.ts#resolveTaskIdentity) must resync, since it
+        // changes which agent/plugin the row is attributed to; the version
+        // fields are left out on purpose so a version-only bump alone does not
+        // force a resync. The keys are added CONDITIONALLY: `stableStringify`
+        // renders an `undefined` value as `"agent":undefined`, so an
+        // unconditional key would change every legacy task's hash and force a
+        // full resync right after upgrading (see the golden-hash test).
+        ...(task.orchestrator.agent !== undefined ? { agent: task.orchestrator.agent } : {}),
+        ...(task.orchestrator.plugin !== undefined ? { plugin: task.orchestrator.plugin } : {}),
     }));
 }
 /**

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

@@ -192,6 +192,23 @@ export interface WorkRecordMetadata {
      * (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;

package/dist/domain/work-record.js

@@ -83,5 +83,9 @@ export function isWorkRecord(value) {
         (record["roleConfidence"] === undefined || record["roleConfidence"] === "uncertain") &&
         (record["orchestratorRef"] === undefined || isOrchestratorRef(record["orchestratorRef"])) &&
         (record["costObserved"] === undefined || record["costObserved"] === true) &&
-        (record["profile"] === undefined || typeof record["profile"] === "string"));
+        (record["profile"] === undefined || typeof record["profile"] === "string") &&
+        (record["agent"] === undefined || typeof record["agent"] === "string") &&
+        (record["agentVersion"] === undefined || typeof record["agentVersion"] === "string") &&
+        (record["plugin"] === undefined || typeof record["plugin"] === "string") &&
+        (record["pluginVersion"] === undefined || typeof record["pluginVersion"] === "string"));
 }

package/dist/hub/index.d.ts

@@ -7,7 +7,9 @@
  * for which ones and why.
  */
 export * from "../adapters/cached-catalog.ts";
+export * from "../adapters/export-writer.ts";
 export * from "../adapters/file-modes.ts";
+export * from "../adapters/hub-actions.ts";
 export * from "../adapters/hub-credentials.ts";
 export * from "../adapters/jsonl-work-log.ts";
 export * from "../adapters/kankaku-dir.ts";
@@ -15,5 +17,9 @@ export * from "../adapters/lazy-jsonl-work-log.ts";
 export * from "../adapters/pocketbase-catalog.ts";
 export * from "../adapters/pocketbase-client.ts";
 export * from "../adapters/pocketbase-sink.ts";
+export * from "../adapters/project-config.ts";
+export * from "../adapters/report-data.ts";
+export * from "../adapters/report.ts";
+export * from "../adapters/report-views.ts";
 export * from "../adapters/sync-runner.ts";
 export * from "../adapters/sync-state-store.ts";

package/dist/hub/index.js

@@ -7,7 +7,9 @@
  * for which ones and why.
  */
 export * from "../adapters/cached-catalog.js";
+export * from "../adapters/export-writer.js";
 export * from "../adapters/file-modes.js";
+export * from "../adapters/hub-actions.js";
 export * from "../adapters/hub-credentials.js";
 export * from "../adapters/jsonl-work-log.js";
 export * from "../adapters/kankaku-dir.js";
@@ -15,5 +17,9 @@ export * from "../adapters/lazy-jsonl-work-log.js";
 export * from "../adapters/pocketbase-catalog.js";
 export * from "../adapters/pocketbase-client.js";
 export * from "../adapters/pocketbase-sink.js";
+export * from "../adapters/project-config.js";
+export * from "../adapters/report-data.js";
+export * from "../adapters/report.js";
+export * from "../adapters/report-views.js";
 export * from "../adapters/sync-runner.js";
 export * from "../adapters/sync-state-store.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kankaku",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "pi extension that records agent work time per prompt, excluding waits for the user, with subagent linkage and task/session views",
   "license": "MIT",
   "author": "soyunninja",