kankaku-pi 1.0.0

package/src/domain/ancestry-match.ts

@@ -0,0 +1,84 @@
+import type { RegistryEntry } from "../ports/process-registry.ts";
+import type { OrchestratorRef } from "./work-record.ts";
+
+/**
+ * Max allowed drift (ms) between a live process's freshly re-derived start
+ * identity and the one recorded in its registry entry. Absorbs
+ * second-granularity rounding/reading noise from the underlying OS
+ * start-time source (`adapters/ancestry.ts`) — not a measure of real clock
+ * error, since both readings of the *same* process instance stay tightly
+ * consistent regardless of that source's own precision (see that module's
+ * docs). A genuine pid-reuse produces a gap far larger than this.
+ */
+export const START_ID_TOLERANCE_MS = 2000;
+
+/** Whether two start identities are close enough to be the same process instance. `undefined` on either side is always "no", never a coincidental match. */
+function sameProcessInstance(recorded: number | undefined, live: number | undefined): boolean {
+  if (recorded === undefined || live === undefined) return false;
+  return Math.abs(recorded - live) <= START_ID_TOLERANCE_MS;
+}
+
+/**
+ * The nearest tracked ancestor whose identity can actually be *proven*: the
+ * first `ancestryPids` entry (ordered nearest-parent first, see
+ * `adapters/ancestry.ts#walkAncestry`) that has a matching
+ * {@link RegistryEntry} AND whose registry-recorded `processStartId`
+ * agrees, within {@link START_ID_TOLERANCE_MS}, with `liveStartId(pid)` —
+ * a fresh re-derivation of that same pid's actual OS start time, taken
+ * from the same ancestry snapshot the caller already has. Matching by pid
+ * number alone is not safe: the OS reuses pids, so a stale entry left
+ * behind by a dead, never-cleaned-up process can otherwise be
+ * misattributed to whatever unrelated live process the kernel later hands
+ * that same pid to (a genuine top-level session silently misclassified as
+ * someone's subagent forever). A candidate whose identity cannot be
+ * verified — no `processStartId` on the entry (legacy/malformed), or no
+ * live start id available for that pid (platform without ancestor-chain
+ * support, or a snapshot gap) — is never matched; the walk continues past
+ * it exactly like an untracked hop, so a further genuine ancestor can still
+ * be found. Returns `undefined` when no ancestor pid is trackable at all —
+ * callers must treat that exactly like "no registry available" (safe
+ * fallback to the pre-registry behaviour), never invent a match.
+ */
+export function findAncestorEntry(ancestryPids: number[], entries: RegistryEntry[], liveStartId: (pid: number) => number | undefined): RegistryEntry | undefined {
+  if (ancestryPids.length === 0 || entries.length === 0) return undefined;
+
+  const byPid = new Map<number, RegistryEntry>();
+  for (const entry of entries) {
+    // First entry for a given pid wins; a pid should only ever have one
+    // live registry file, but a torn write racing a sweep could in theory
+    // leave two candidates behind — deterministic tie-break, not correctness-critical.
+    if (!byPid.has(entry.pid)) byPid.set(entry.pid, entry);
+  }
+
+  for (const pid of ancestryPids) {
+    const entry = byPid.get(pid);
+    if (!entry) continue;
+    if (sameProcessInstance(entry.processStartId, liveStartId(pid))) return entry;
+    // Either unprovable, or this pid has genuinely been reused by a
+    // different process instance since the entry was written: not our
+    // ancestor. Keep walking — a further, verifiable ancestor may still exist.
+  }
+  return undefined;
+}
+
+/**
+ * Resolve the ultimate, top-level {@link OrchestratorRef} for `ancestorEntry`
+ * (the nearest verified ancestor {@link findAncestorEntry} returned) — F4's
+ * nested-subagent fix. When that ancestor is itself a `subagent`-role entry
+ * that already resolved its own verified `orchestratorRef` (a
+ * subagent-of-subagent chain: this process's parent is itself someone's
+ * child), that inherited ref is returned instead of one built from the
+ * ancestor's own identity — so a grandchild's `orchestratorRef` (and, via
+ * its `dir`, `extension.ts`'s F1 write-routing target) always points at
+ * the real top-level orchestrator, never a middle hop. Falls back to an
+ * ancestor's own identity when it is an orchestrator, or a subagent that
+ * never resolved a ref of its own (e.g. it discovered no tracked ancestor
+ * at its own startup) — never invents one. `undefined` in, `undefined` out.
+ */
+export function resolveOrchestratorRef(ancestorEntry: RegistryEntry | undefined): OrchestratorRef | undefined {
+  if (ancestorEntry === undefined) return undefined;
+  if (ancestorEntry.role === "subagent" && ancestorEntry.orchestratorRef !== undefined) {
+    return ancestorEntry.orchestratorRef;
+  }
+  return { pid: ancestorEntry.pid, project: ancestorEntry.project, startedAt: ancestorEntry.startedAt, dir: ancestorEntry.dir };
+}

package/src/domain/client-label.ts

@@ -0,0 +1,56 @@
+/**
+ * Client (billing target) label resolution: pure, no I/O.
+ *
+ * A client name identifies who a piece of work is billed to. It can come
+ * from three sources, in decreasing precedence: the pi session (set with
+ * `/kankaku client <name>`), the `KANKAKU_CLIENT` environment variable, or
+ * the project's `.kankaku/config.json`.
+ */
+
+/** Safe client name: letters, digits, `.`, `_`, `-`, 1-64 chars. */
+const CLIENT_PATTERN = /^[A-Za-z0-9._-]{1,64}$/;
+
+/** Property names that behave specially on a plain object; never usable as a client name. */
+const RESERVED_NAMES = new Set(["__proto__", "constructor", "prototype"]);
+
+export interface ClientSources {
+  /** Set for the current pi session via `/kankaku client <name>`. Highest precedence. */
+  session?: string;
+  /** From the `KANKAKU_CLIENT` environment variable. */
+  env?: string;
+  /** From the project's `.kankaku/config.json`. Lowest precedence. */
+  project?: string;
+}
+
+export type ClientSourceName = "session" | "env" | "project";
+
+/** `true` when `value` is a non-empty, safe client name. */
+export function isValidClient(value: string): boolean {
+  return CLIENT_PATTERN.test(value) && !RESERVED_NAMES.has(value);
+}
+
+/** Trim and validate a candidate client name; `undefined` when absent or invalid. */
+function normalize(value: string | undefined): string | undefined {
+  if (value === undefined) return undefined;
+  const trimmed = value.trim();
+  if (trimmed.length === 0) return undefined;
+  return isValidClient(trimmed) ? trimmed : undefined;
+}
+
+/**
+ * Resolve the effective client name from `session`, `env` and `project`
+ * sources, in that precedence order. Each candidate is trimmed; an empty
+ * string or a value that does not match the safe client-name pattern is
+ * treated as absent and resolution falls through to the next source.
+ */
+export function resolveClient(sources: ClientSources): string | undefined {
+  return normalize(sources.session) ?? normalize(sources.env) ?? normalize(sources.project);
+}
+
+/** Which source produced {@link resolveClient}'s result, or `undefined` when none applies. */
+export function resolveClientSource(sources: ClientSources): ClientSourceName | undefined {
+  if (normalize(sources.session) !== undefined) return "session";
+  if (normalize(sources.env) !== undefined) return "env";
+  if (normalize(sources.project) !== undefined) return "project";
+  return undefined;
+}

package/src/domain/day.ts

@@ -0,0 +1,8 @@
+/** Local (not UTC) calendar day of an ISO timestamp, as `YYYY-MM-DD`. */
+export function localDay(iso: string): string {
+  const date = new Date(iso);
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}

package/src/domain/export.ts

@@ -0,0 +1,107 @@
+import { localDay } from "./day.ts";
+import { finiteOrZero } from "./work-record.ts";
+import type { WorkStatus } from "./work-record.ts";
+import type { TaskView } from "./task-view.ts";
+
+/** One flat, spreadsheet-friendly row per {@link TaskView}. */
+export interface ExportRow {
+  id: string;
+  /** Local calendar day (`YYYY-MM-DD`) the task started on. */
+  day: string;
+  startedAt: string;
+  endedAt: string;
+  /** Empty string when the task has no resolved client. */
+  client: string;
+  /** Empty string when the orchestrator record has no session name. */
+  sessionName: string;
+  /** Empty string when the orchestrator record has no session id. */
+  sessionId: string;
+  project: string;
+  status: WorkStatus;
+  /** First 200 chars of the task's prompt, with newlines collapsed to spaces. */
+  prompt: string;
+  wallMs: number;
+  waitingMs: number;
+  workMs: number;
+  cost: number;
+  tokensIn: number;
+  tokensOut: number;
+  cacheRead: number;
+  subagentCount: number;
+  /** JSON-encoded `TaskView.segments` map. */
+  segments: string;
+  /** Empty string when the orchestrator record has no model. */
+  model: string;
+}
+
+/** First 200 chars of `prompt`, with `\n`/`\r` collapsed to a single space. */
+function truncatePrompt(prompt: string): string {
+  return prompt.slice(0, 200).replace(/\r\n|\r|\n/g, " ");
+}
+
+/** Build one flat {@link ExportRow} per task, in the same order as `tasks`. */
+export function exportRows(tasks: TaskView[]): ExportRow[] {
+  return tasks.map((task) => ({
+    id: task.id,
+    day: localDay(task.startedAt),
+    startedAt: task.startedAt,
+    endedAt: task.endedAt,
+    client: task.client ?? "",
+    sessionName: task.sessionName ?? "",
+    sessionId: task.sessionId ?? "",
+    project: task.project,
+    status: task.status,
+    prompt: truncatePrompt(task.prompt),
+    wallMs: task.wallMs,
+    waitingMs: task.waitingMs,
+    workMs: task.workMs,
+    cost: finiteOrZero(task.usage.cost),
+    tokensIn: finiteOrZero(task.usage.input),
+    tokensOut: finiteOrZero(task.usage.output),
+    cacheRead: finiteOrZero(task.usage.cacheRead),
+    subagentCount: task.subagents.length,
+    segments: JSON.stringify(task.segments),
+    model: task.orchestrator.model ?? "",
+  }));
+}
+
+/** Column order for {@link toCsv}'s header row, matching {@link ExportRow}'s field order. */
+const COLUMNS: Array<keyof ExportRow> = [
+  "id",
+  "day",
+  "startedAt",
+  "endedAt",
+  "client",
+  "sessionName",
+  "sessionId",
+  "project",
+  "status",
+  "prompt",
+  "wallMs",
+  "waitingMs",
+  "workMs",
+  "cost",
+  "tokensIn",
+  "tokensOut",
+  "cacheRead",
+  "subagentCount",
+  "segments",
+  "model",
+];
+
+/** RFC 4180 field quoting: quote a field containing `,`, `"`, or a newline; double any embedded quote. */
+function csvField(value: string | number): string {
+  const text = String(value);
+  return /[",\r\n]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text;
+}
+
+/** Render `rows` as RFC 4180 CSV: a header row, one row per record, `\n` line endings. */
+export function toCsv(rows: ExportRow[]): string {
+  const lines = [COLUMNS.join(","), ...rows.map((row) => COLUMNS.map((column) => csvField(row[column])).join(","))];
+  return lines.join("\n");
+}
+
+/** Render `rows` as pretty-printed (2-space indent) JSON. */
+export function toJson(rows: ExportRow[]): string {
+  return JSON.stringify(rows, null, 2);
+}

package/src/domain/hub-entry.ts

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