kankaku 0.6.0 → 0.7.0

package/README.md

@@ -114,7 +114,9 @@ remains valid.
 `clientId`, `clientName`, `projectId`, `projectName` and `machine` are only
 present once a hub is configured (see "Hub (PocketBase)"); every report and
 export written before this feature, or by a user without a hub, is
-unaffected.
+unaffected. `hubTaskId`/`hubTaskTitle` are set alongside them only when a
+hub task is linked to the session (`/kankaku task pick`) — see "Linking to
+a hub task" below.
 
 `sessionDir` is present only when pi's session manager reports a
 *non-default* session directory (`--session-dir`, or a resumed session
@@ -685,13 +687,53 @@ the future, this is the signal that would surface it.
 
 ## The `/kankaku` command
 
-Run `/kankaku` inside pi to see today's totals (work, waiting, record count)
-per role, plus a union-based tasks segment. In the interactive TUI the report
-is appended to the chat transcript as a durable card that is never sent to
-the LLM; without a UI (print or RPC mode) it falls back to a notification.
-Arguments are whitespace-separated and order-insensitive:
-
-- `/kankaku` — today's role totals and tasks segment, each with its estimated cost.
+`/kankaku` with no arguments, run inside pi's TUI, opens an overlay panel
+modelled on pi's own `/settings` (the same pi-tui `SettingsList`/
+`SelectList` widgets, the same keys) from which every kankaku view and
+action is reachable:
+
+- **Target** — billing client, project, hub task, and the legacy label
+  (see "Billing labels" and "Hub (PocketBase)" below). The Task row lists
+  the open/doing hub tasks of the current project; picking one links the
+  session, exactly like `/kankaku task pick` below — **session-only**,
+  never persisted (see "Linking to a hub task").
+- **Report** — today/all totals, tasks, sessions, clients, and projects:
+  the same five views `/kankaku`'s subcommands produce.
+- **Sync** (hub only) — status, sync now, sync all, backfill, and a
+  catalog refresh.
+- **Export** — write today's or every task as csv/json.
+- **Doctor** — orphan/uncertain subagent counts and ancestor-detection
+  availability.
+- **About** — versions, the resolved `KANKAKU_DIR`, the hub URL, and every
+  env-only setting, read-only.
+
+Keys: `↑↓` move, `Enter` open a section or select a value, `Esc` go back
+(or close the panel at the root), `q` close from anywhere. Mouse: the
+footer hints and list rows are clickable, but only in pi's fullscreen
+mode — pi does not dispatch mouse events in its regular (non-fullscreen)
+mode, so there the panel is keyboard-only.
+
+Every subcommand below is unchanged, and is exactly what headless (print
+or RPC) mode still uses — `/kankaku` there keeps showing today's totals
+directly, never the panel, since there is no UI to open one in. Run
+`/kankaku <subcommand>` (with arguments) in the TUI to skip the panel and
+go straight to that subcommand's output, exactly as before the panel
+existed.
+
+Plain `/kankaku` (headless, or any subcommand below) shows today's totals
+(work, waiting, record count) per role, plus a union-based tasks segment.
+Each totals line also shows `cache hit NN%` when tokens were recorded: the
+share of prompt input tokens served from the provider's prompt cache, cache
+reads over input plus cache reads plus cache writes; the segment is
+omitted, not shown as `0%`, when no tokens were recorded. In the
+interactive TUI the report is appended to the chat transcript as a durable
+card that is never sent to the LLM; without a UI (print or RPC mode) it
+falls back to a notification. Arguments are whitespace-separated and
+order-insensitive:
+
+- `/kankaku` (headless only — the TUI opens the panel instead, whose
+  Report screen defaults to the same view) — today's role totals and
+  tasks segment, each with its estimated cost.
 - `/kankaku all` — same, but across every record.
 - `/kankaku tasks` — one line per task (time, union wall/work, cost,
   subagent count, truncated prompt) for the **current pi session**. Add `all` for
@@ -719,6 +761,9 @@ The following are available only when a hub is configured (see "Hub
   produced it. `/kankaku target pick` runs the picker again (works
   mid-session; the new target applies to records settled afterwards).
   `/kankaku target clear` clears the session-level target.
+- `/kankaku task` (or `/kankaku task pick`) — link this session to an
+  open/doing hub task of the effective project. `/kankaku task clear`
+  drops the link. See "Linking to a hub task" below.
 - `/kankaku catalog refresh` — force a catalog refresh and report the
   client/project counts.
 - `/kankaku projects` — one line per project (work/waiting/wall time, cost,
@@ -825,6 +870,45 @@ task view exposes it from the orchestrator record only.
 The status bar shows `💼 <client> · <project>` (or just `💼 <client>` without
 a project) in place of the legacy client label, both idle and during a run.
 
+Mid-session, the `/kankaku` panel's Target screen (see "The `/kankaku`
+command" above) is the interactive way to change the client or project
+without going through `/kankaku target pick`'s picker dialog — it edits the
+same session-level target, applies through the same `SessionTarget`, and
+has its own "Remember" row for `<KANKAKU_DIR>/config.json`.
+
+### Linking to a hub task
+
+`/kankaku task` (or `/kankaku task pick`) links the current session to one
+of the effective project's existing hub `tasks` rows: a `ctx.ui.select`
+picker lists the project's `open`/`doing` tasks, sorted by title (colliding
+titles are disambiguated with the task's external reference, or its id).
+`/kankaku task clear` drops the link, keeping the rest of the session
+target. kankaku never creates a task from pi — this only links to one
+that already exists in the hub.
+
+The link is **session-only**: unlike `clientId`/`projectId`, it is never
+persisted to `<KANKAKU_DIR>/config.json`, and it is never asked for at
+`session_start` — you always link a task explicitly, with `/kankaku task`.
+Any target change (`/kankaku target pick`, `/kankaku target clear`, or the
+legacy `/kankaku client <name>`) drops the linked task, since a new client
+or project makes the old task's link meaningless. A task whose project no
+longer matches the effective project (e.g. after a target change or a
+reassignment in the hub) is also dropped by the domain resolver, never
+silently linked across projects. A task already marked `done` when linked
+keeps linking for the rest of the session — only the picker itself hides
+`done` tasks, so you cannot accidentally pick a closed one, but finishing
+the picked task in the hub mid-session does not break the link. Subagent
+records never carry a linked task, exactly like `clientId`/`projectId` —
+the task view exposes it from the orchestrator record only, and
+`formatWorkTargetLabel` appends it to the status-bar/report label as
+`<client> · <project> › <task title>`.
+
+The `/kankaku` panel's Target screen's Task row is the interactive
+equivalent of `/kankaku task pick`/`clear`: it lists the same open/doing
+tasks, applies the link through the same `SessionTarget.setTask`, and
+stays just as session-only — picking a task there is never persisted to
+`config.json` either.
+
 ### Caching and offline behaviour
 
 The catalog (clients/projects) is cached machine-wide at
@@ -905,10 +989,13 @@ web app) can move a task from one client/project to another directly in
 PocketBase — for example, moving a "Sin determinar" row to its real
 client once you have identified it. A later re-sync of that same task
 **must never undo that**: on create kankaku sends the full row, including
-`client`/`project`/`legacy_client_label`; on every subsequent update it
-sends measurement fields only (`wall_ms`, `cost`, `status`, ...) and never
-touches assignment fields again. If you need kankaku itself to change a
-task's assignment, do it in the web app, not by re-syncing.
+`client`/`project`/`task`/`legacy_client_label`; on every subsequent update
+it sends measurement fields only (`wall_ms`, `cost`, `status`, ...) and
+never touches assignment fields again. `task` (the linked `tasks` relation)
+is create-only for the exact same reason: reassigning which task a row
+belongs to in the web app is never undone by a later sync. If you need
+kankaku itself to change a task's assignment, do it in the web app, not by
+re-syncing.
 
 **Historical ("Sin determinar") records.** A record with no `clientId`, or
 whose `clientId` no longer resolves in the catalog, is routed to the hub's
@@ -1252,8 +1339,10 @@ notice; import only `kankaku/domain`, `kankaku/ports`, or `kankaku/hub`.
   is not; the compiled entry points are today consumed as a library, not a
   binary.
 - Linking a `task_entries` row to an existing `tasks` record (phase 3 in the
-  hub's own data model) — kankaku never invents tasks; it would only ever
-  link to one created in the manager.
+  hub's own data model) has shipped: `/kankaku task pick`/`clear` (see
+  "Linking to a hub task" above). Creating a task from pi
+  (`/kankaku task new`) is deliberately not included — kankaku never
+  invents tasks; it only ever links to one already created in the manager.
 - Generic subagent detection (phase 6): 6a fixed the two correctness bugs
   described in "Subagents" above (a phantom-orchestrator double count; a
   gentle-pi cross-worktree child's work going missing). 6b added the

package/dist/adapters/cached-catalog.d.ts

@@ -1,4 +1,4 @@
-import type { Client, Project } from "../domain/work-target.ts";
+import type { Client, HubTask, Project } from "../domain/work-target.ts";
 import type { Clock } from "../ports/clock.ts";
 import type { Catalog, CatalogSnapshot } from "../ports/catalog.ts";
 export interface CachedCatalogDeps {
@@ -9,10 +9,16 @@ export interface CachedCatalogDeps {
     clock: Clock;
     /** Cache TTL in ms. Defaults to 6 hours. */
     ttlMs?: number;
-    /** Fetch a fresh `{ clients, projects }` pair, e.g. `createPocketBaseCatalogFetcher(...)`. */
+    /**
+     * Fetch a fresh `{ clients, projects, tasks }` triple, e.g.
+     * `createPocketBaseCatalogFetcher(...)`. `tasks` is optional here (unlike
+     * on the real PocketBase fetcher) so a test double that only cares about
+     * clients/projects keeps compiling unchanged.
+     */
     fetchCatalog: (signal?: AbortSignal) => Promise<{
         clients: Client[];
         projects: Project[];
+        tasks?: HubTask[];
     }>;
 }
 /**

package/dist/adapters/cached-catalog.js

@@ -9,6 +9,9 @@ function isClientArray(value) {
 function isProjectArray(value) {
     return Array.isArray(value) && value.every((item) => item && typeof item === "object" && typeof item.id === "string");
 }
+function isHubTaskArray(value) {
+    return Array.isArray(value) && value.every((item) => item && typeof item === "object" && typeof item.id === "string");
+}
 function isCatalogSnapshot(value) {
     if (!value || typeof value !== "object")
         return false;
@@ -16,7 +19,8 @@ function isCatalogSnapshot(value) {
     return (typeof record["fetchedAt"] === "number" &&
         typeof record["url"] === "string" &&
         isClientArray(record["clients"]) &&
-        isProjectArray(record["projects"]));
+        isProjectArray(record["projects"]) &&
+        (record["tasks"] === undefined || isHubTaskArray(record["tasks"])));
 }
 /**
  * Disk-backed {@link Catalog}: `read()` is a synchronous, cheap read of the
@@ -49,8 +53,14 @@ export class CachedCatalog {
     }
     async refresh(signal) {
         try {
-            const { clients, projects } = await this.deps.fetchCatalog(signal);
-            const snapshot = { fetchedAt: this.deps.clock.now(), url: this.deps.url, clients, projects };
+            const { clients, projects, tasks } = await this.deps.fetchCatalog(signal);
+            const snapshot = {
+                fetchedAt: this.deps.clock.now(),
+                url: this.deps.url,
+                clients,
+                projects,
+                ...(tasks !== undefined ? { tasks } : {}),
+            };
             this.writeDisk(snapshot);
             this.memo = snapshot;
             this.memoized = true;

package/dist/adapters/pocketbase-catalog.d.ts

@@ -1,14 +1,16 @@
-import type { Client, Project } from "../domain/work-target.ts";
+import type { Client, HubTask, Project } from "../domain/work-target.ts";
 import type { PocketBaseClient } from "./pocketbase-client.ts";
 /**
  * Build the `fetchCatalog` function {@link CachedCatalog} (`cached-catalog.ts`)
- * needs, backed by a {@link PocketBaseClient}. Fetches every `clients` and
- * `projects` record (no `active` filter, so the domain resolver can tell
- * "deleted" from "inactive"; see `domain/work-target.ts`), sorted by name.
- * `signal`, when given, bounds both fetches (see
+ * needs, backed by a {@link PocketBaseClient}. Fetches every `clients`,
+ * `projects` and `tasks` record in parallel (no `active`/`status` filter,
+ * so the domain resolver can tell "deleted" from "inactive"/"done"; see
+ * `domain/work-target.ts`), clients/projects sorted by name and tasks by
+ * title. `signal`, when given, bounds every fetch (see
  * `pocketbase-client.ts#request`).
  */
 export declare function createPocketBaseCatalogFetcher(client: PocketBaseClient): (signal?: AbortSignal) => Promise<{
     clients: Client[];
     projects: Project[];
+    tasks: HubTask[];
 }>;

package/dist/adapters/pocketbase-catalog.js

@@ -1,3 +1,4 @@
+const TASK_STATUSES = new Set(["open", "doing", "done"]);
 function mapClient(record) {
     return {
         id: record.id,
@@ -17,23 +18,39 @@ function mapProject(record) {
         active: record.active === true,
     };
 }
+/** `open` on any unrecognised or missing status, rather than dropping the task. */
+function mapTaskStatus(status) {
+    return status !== undefined && TASK_STATUSES.has(status) ? status : "open";
+}
+function mapTask(record) {
+    return {
+        id: record.id,
+        title: record.title ?? "",
+        projectId: record.project,
+        status: mapTaskStatus(record.status),
+        ...(typeof record.external_ref === "string" && record.external_ref !== "" ? { externalRef: record.external_ref } : {}),
+    };
+}
 /**
  * Build the `fetchCatalog` function {@link CachedCatalog} (`cached-catalog.ts`)
- * needs, backed by a {@link PocketBaseClient}. Fetches every `clients` and
- * `projects` record (no `active` filter, so the domain resolver can tell
- * "deleted" from "inactive"; see `domain/work-target.ts`), sorted by name.
- * `signal`, when given, bounds both fetches (see
+ * needs, backed by a {@link PocketBaseClient}. Fetches every `clients`,
+ * `projects` and `tasks` record in parallel (no `active`/`status` filter,
+ * so the domain resolver can tell "deleted" from "inactive"/"done"; see
+ * `domain/work-target.ts`), clients/projects sorted by name and tasks by
+ * title. `signal`, when given, bounds every fetch (see
  * `pocketbase-client.ts#request`).
  */
 export function createPocketBaseCatalogFetcher(client) {
     return async (signal) => {
-        const [clientRecords, projectRecords] = await Promise.all([
+        const [clientRecords, projectRecords, taskRecords] = await Promise.all([
             client.list("clients", { sort: "name" }, signal),
             client.list("projects", { sort: "name" }, signal),
+            client.list("tasks", { sort: "title" }, signal),
         ]);
         return {
             clients: clientRecords.map(mapClient),
             projects: projectRecords.map(mapProject),
+            tasks: taskRecords.map(mapTask),
         };
     };
 }

package/dist/adapters/pocketbase-sink.d.ts

@@ -12,7 +12,7 @@
  */
 import type { PromptPrivacyMode } from "../domain/hub-entry.ts";
 import type { TaskView } from "../domain/task-view.ts";
-import type { Client, Project } from "../domain/work-target.ts";
+import type { Client, HubTask, Project } from "../domain/work-target.ts";
 import type { PushTaskResult, WorkSink } from "../ports/work-sink.ts";
 import type { PocketBaseClient } from "./pocketbase-client.ts";
 export interface PocketBaseSinkDeps {
@@ -20,6 +20,7 @@ export interface PocketBaseSinkDeps {
     /** Catalog snapshot to resolve assignment against; see `domain/hub-entry.ts#resolveTaskAssignment`. */
     clients: Client[];
     projects: Project[];
+    tasks: HubTask[];
     machine: string;
     promptMode: PromptPrivacyMode;
     /** Coding agent that produced these rows; see `domain/hub-entry.ts#HubEntryContext.agent`. Defaults to `"pi"`. */

package/dist/adapters/pocketbase-sink.js

@@ -76,6 +76,7 @@ export class PocketBaseSink {
         return {
             clients: this.deps.clients,
             projects: this.deps.projects,
+            tasks: this.deps.tasks,
             machine: this.deps.machine,
             promptMode: this.deps.promptMode,
             agent: this.deps.agent ?? "pi",
@@ -139,7 +140,7 @@ export class PocketBaseSink {
         }
     }
     async pushOne(task, existingId) {
-        const assignment = resolveTaskAssignment(task, this.deps.clients, this.deps.projects);
+        const assignment = resolveTaskAssignment(task, this.deps.clients, this.deps.projects, this.deps.tasks);
         const pushAssignment = { unassigned: assignment.routedToUnassigned, ...(assignment.legacyClientLabel ? { legacyLabel: assignment.legacyClientLabel } : {}) };
         try {
             const { id, created } = await this.upsertTaskEntry(task, existingId);

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

@@ -11,11 +11,13 @@
  */
 import type { TaskView } from "./task-view.ts";
 import type { WorkRecord, WorkRole, WorkStatus } from "./work-record.ts";
-import type { Client, Project } from "./work-target.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}. */
@@ -34,13 +36,16 @@ export interface TaskAssignment {
     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 a task's `task_entries` row should link to.
+ * 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
@@ -51,8 +56,12 @@ export interface TaskAssignment {
  *   `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 declare function resolveTaskAssignment(task: TaskView, clients: Client[], projects: Project[]): TaskAssignment;
+export declare function resolveTaskAssignment(task: TaskView, clients: Client[], projects: Project[], tasks: HubTask[]): TaskAssignment;
 /**
  * Privacy transform for a prompt about to leave the machine
  * (`KANKAKU_SYNC_PROMPT`, default `none`): `none` omits it entirely,

package/dist/domain/hub-entry.js

@@ -11,7 +11,8 @@
  */
 import { finiteOrZero } from "./work-record.js";
 /**
- * Resolve which client/project a task's `task_entries` row should link to.
+ * 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
@@ -22,14 +23,22 @@ import { finiteOrZero } from "./work-record.js";
  *   `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, clients, projects) {
+export function resolveTaskAssignment(task, clients, projects, tasks) {
     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,
         };
@@ -38,6 +47,7 @@ export function resolveTaskAssignment(task, clients, projects) {
     return {
         clientId: unassigned ? unassigned.id : "",
         projectId: "",
+        hubTaskId: "",
         legacyClientLabel: task.client ?? task.clientName ?? "",
         routedToUnassigned: true,
     };
@@ -118,12 +128,12 @@ export function computeSubagentLinkage(task) {
 }
 /** 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);
+    const assignment = resolveTaskAssignment(task, ctx.clients, ctx.projects, ctx.tasks);
     return {
         task_id: task.id,
         client: assignment.clientId,
         project: assignment.projectId,
-        task: "",
+        task: assignment.hubTaskId,
         started_at: toPbDate(task.startedAt),
         ended_at: toPbDate(task.endedAt),
         wall_ms: task.wallMs,

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

@@ -33,6 +33,10 @@ export interface TaskView {
     projectId?: string;
     /** Hub project display name, from the orchestrator record only. */
     projectName?: string;
+    /** Hub task record id, from the orchestrator record only. See `domain/work-target.ts#HubTask`. */
+    hubTaskId?: string;
+    /** Hub task title, from the orchestrator record only. */
+    hubTaskTitle?: string;
     /**
      * Per-tag total milliseconds across the orchestrator and every subagent,
      * summed rather than unioned: unlike `wallMs`, segment intervals are not

package/dist/domain/task-view.js

@@ -295,6 +295,8 @@ function buildTaskView(orchestrator, subagents) {
         ...(orchestrator.clientName !== undefined ? { clientName: orchestrator.clientName } : {}),
         ...(orchestrator.projectId !== undefined ? { projectId: orchestrator.projectId } : {}),
         ...(orchestrator.projectName !== undefined ? { projectName: orchestrator.projectName } : {}),
+        ...(orchestrator.hubTaskId !== undefined ? { hubTaskId: orchestrator.hubTaskId } : {}),
+        ...(orchestrator.hubTaskTitle !== undefined ? { hubTaskTitle: orchestrator.hubTaskTitle } : {}),
         project: orchestrator.project,
         prompt: orchestrator.prompt,
         startedAt: orchestrator.startedAt,

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

@@ -159,6 +159,10 @@ export interface WorkRecordMetadata {
     projectId?: string;
     /** Hub project display name, denormalised alongside `projectId`. */
     projectName?: string;
+    /** Hub `tasks` record id linked for this session (`/kankaku task pick`), when one is active. See `domain/work-target.ts#HubTask`. */
+    hubTaskId?: string;
+    /** Hub task title, denormalised alongside `hubTaskId`. */
+    hubTaskTitle?: string;
     /** This machine's hostname, or `KANKAKU_MACHINE`, set only when the hub is configured. */
     machine?: string;
     /**
@@ -193,6 +197,20 @@ export type WorkRecord = WorkRecordCore & WorkRecordMetadata;
 export declare function emptyUsage(): UsageTotals;
 /** A finite number, or `0` for `undefined`/`NaN`/`Infinity`/non-numbers. */
 export declare function finiteOrZero(value: unknown): number;
+/**
+ * Share of prompt input tokens served from the provider's prompt cache:
+ * `cacheRead / (input + cacheRead + cacheWrite)`. pi's `usage.input` maps to
+ * the provider's `input_tokens`, which already excludes cached tokens, so
+ * the three fields are disjoint and this sum is the true denominator.
+ * Returns `undefined` when the denominator is `0` (nothing to compute a
+ * ratio from) rather than `0`, so callers never render a misleading `0%`.
+ * Non-finite fields count as `0`, mirroring {@link finiteOrZero}.
+ */
+export declare function cacheHitRatio(usage: {
+    input: number;
+    cacheRead: number;
+    cacheWrite: number;
+}): number | undefined;
 /**
  * Runtime guard for a {@link WorkRecord} read back from disk. `readAll`
  * skips lines that parse as JSON but fail this check, so a torn write or a

package/dist/domain/work-record.js

@@ -9,6 +9,22 @@ export function emptyUsage() {
 export function finiteOrZero(value) {
     return typeof value === "number" && Number.isFinite(value) ? value : 0;
 }
+/**
+ * Share of prompt input tokens served from the provider's prompt cache:
+ * `cacheRead / (input + cacheRead + cacheWrite)`. pi's `usage.input` maps to
+ * the provider's `input_tokens`, which already excludes cached tokens, so
+ * the three fields are disjoint and this sum is the true denominator.
+ * Returns `undefined` when the denominator is `0` (nothing to compute a
+ * ratio from) rather than `0`, so callers never render a misleading `0%`.
+ * Non-finite fields count as `0`, mirroring {@link finiteOrZero}.
+ */
+export function cacheHitRatio(usage) {
+    const input = finiteOrZero(usage.input);
+    const cacheRead = finiteOrZero(usage.cacheRead);
+    const cacheWrite = finiteOrZero(usage.cacheWrite);
+    const denominator = input + cacheRead + cacheWrite;
+    return denominator === 0 ? undefined : cacheRead / denominator;
+}
 const ROLES = new Set(["orchestrator", "subagent"]);
 const STATUSES = new Set(["completed", "aborted", "interrupted"]);
 /** A finite, non-negative number: durations such as `wallMs` can never be negative. */
@@ -61,6 +77,8 @@ export function isWorkRecord(value) {
         (record["clientName"] === undefined || typeof record["clientName"] === "string") &&
         (record["projectId"] === undefined || typeof record["projectId"] === "string") &&
         (record["projectName"] === undefined || typeof record["projectName"] === "string") &&
+        (record["hubTaskId"] === undefined || typeof record["hubTaskId"] === "string") &&
+        (record["hubTaskTitle"] === undefined || typeof record["hubTaskTitle"] === "string") &&
         (record["machine"] === undefined || typeof record["machine"] === "string") &&
         (record["roleConfidence"] === undefined || record["roleConfidence"] === "uncertain") &&
         (record["orchestratorRef"] === undefined || isOrchestratorRef(record["orchestratorRef"])) &&

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

@@ -29,6 +29,18 @@ export interface Project {
     repoPaths: string[];
     active: boolean;
 }
+/**
+ * A hub `tasks` row: something kankaku can link a session's `task_entries`
+ * row to (`task_entries.task`), never create. See `domain/hub-entry.ts` for
+ * the create-only assignment rule this feeds.
+ */
+export interface HubTask {
+    id: string;
+    title: string;
+    projectId: string;
+    status: "open" | "doing" | "done";
+    externalRef?: string;
+}
 export interface WorkTarget {
     clientId: string;
     clientCode: string;
@@ -36,11 +48,22 @@ export interface WorkTarget {
     projectId?: string;
     projectCode?: string;
     projectName?: string;
+    /** Hub `tasks` record id, kept only when it belongs to `projectId`. See {@link resolveWorkTarget}. */
+    hubTaskId?: string;
+    /** Denormalised alongside `hubTaskId` for display. */
+    hubTaskTitle?: string;
 }
 /** ids picked from the session, or from the project's `.kankaku/config.json`. */
 export interface WorkTargetCandidate {
     clientId: string;
     projectId?: string;
+    /**
+     * A hub task the user picked for this session (`/kankaku task pick`).
+     * Only ever set on the session-level candidate — the project config file
+     * and `repoPaths` matching never carry one (task linking is session-only,
+     * see AGENTS.md).
+     */
+    hubTaskId?: string;
 }
 /**
  * The session-level override: `undefined` when no session entry exists yet
@@ -57,6 +80,8 @@ export interface ResolveWorkTargetInput {
     cwd: string;
     clients: Client[];
     projects: Project[];
+    /** The hub's known tasks, to validate a candidate's `hubTaskId` against. Defaults to `[]` so existing callers compile unchanged. */
+    tasks?: HubTask[];
 }
 export type WorkTargetSourceName = "session" | "project" | "repoPaths";
 /** Which source (if any) {@link resolveWorkTarget} would use, computed independently so callers can display it. */
@@ -68,5 +93,9 @@ export declare function resolveWorkTargetSource(input: ResolveWorkTargetInput):
  * declined), returning `undefined` rather than falling through.
  */
 export declare function resolveWorkTarget(input: ResolveWorkTargetInput): WorkTarget | undefined;
-/** `<clientName>` or `<clientName> · <projectName>` — the display label used by the status bar and the "remember" prompt. */
+/**
+ * `<clientName>`, `<clientName> · <projectName>`, or with a linked hub task
+ * appended as `... › <hubTaskTitle>` — the display label used by the
+ * status bar and the "remember" prompt.
+ */
 export declare function formatWorkTargetLabel(target: WorkTarget): string;