kankaku 0.6.0 → 0.6.5

package/src/adapters/cached-catalog.ts

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
-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";
 import { OWNER_DIR_MODE, OWNER_FILE_MODE } from "./file-modes.ts";
@@ -16,6 +16,10 @@ function isProjectArray(value: unknown): value is Project[] {
   return Array.isArray(value) && value.every((item) => item && typeof item === "object" && typeof (item as Project).id === "string");
 }
 
+function isHubTaskArray(value: unknown): value is HubTask[] {
+  return Array.isArray(value) && value.every((item) => item && typeof item === "object" && typeof (item as HubTask).id === "string");
+}
+
 function isCatalogSnapshot(value: unknown): value is CatalogSnapshot {
   if (!value || typeof value !== "object") return false;
   const record = value as Record<string, unknown>;
@@ -23,7 +27,8 @@ function isCatalogSnapshot(value: unknown): value is CatalogSnapshot {
     typeof record["fetchedAt"] === "number" &&
     typeof record["url"] === "string" &&
     isClientArray(record["clients"]) &&
-    isProjectArray(record["projects"])
+    isProjectArray(record["projects"]) &&
+    (record["tasks"] === undefined || isHubTaskArray(record["tasks"]))
   );
 }
 
@@ -35,8 +40,13 @@ export interface CachedCatalogDeps {
   clock: Clock;
   /** Cache TTL in ms. Defaults to 6 hours. */
   ttlMs?: number;
-  /** Fetch a fresh `{ clients, projects }` pair, e.g. `createPocketBaseCatalogFetcher(...)`. */
-  fetchCatalog: (signal?: AbortSignal) => Promise<{ clients: Client[]; projects: Project[] }>;
+  /**
+   * 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[] }>;
 }
 
 /**
@@ -73,8 +83,14 @@ export class CachedCatalog implements Catalog {
 
   async refresh(signal?: AbortSignal): Promise<CatalogSnapshot | undefined> {
     try {
-      const { clients, projects } = await this.deps.fetchCatalog(signal);
-      const snapshot: CatalogSnapshot = { fetchedAt: this.deps.clock.now(), url: this.deps.url, clients, projects };
+      const { clients, projects, tasks } = await this.deps.fetchCatalog(signal);
+      const snapshot: CatalogSnapshot = {
+        fetchedAt: this.deps.clock.now(),
+        url: this.deps.url,
+        clients,
+        projects,
+        ...(tasks !== undefined ? { tasks } : {}),
+      };
       this.writeDisk(snapshot);
       this.memo = snapshot;
       this.memoized = true;

package/src/adapters/kankaku-command.ts

@@ -46,8 +46,9 @@ export function notifyError(ctx: ExtensionContext, error: unknown): void {
 
 const COMMAND_TOKENS = ["all", "tasks", "sessions", "client", "clients", "export", "doctor"];
 /** Only offered when the hub is configured, so completions are unchanged for users without one. */
-const HUB_COMMAND_TOKENS = ["target", "projects", "catalog", "sync", "backfill"];
+const HUB_COMMAND_TOKENS = ["target", "task", "projects", "catalog", "sync", "backfill"];
 const TARGET_TOKENS = ["pick", "clear"];
+const TASK_TOKENS = ["pick", "clear"];
 const CATALOG_TOKENS = ["refresh"];
 const SYNC_TOKENS = ["all", "status"];
 
@@ -328,6 +329,35 @@ export function registerKankakuCommand(pi: ExtensionAPI, deps: KankakuCommandDep
     notifyError(ctx, new Error(`unknown target subcommand: ${rest.join(" ")}`));
   }
 
+  /**
+   * Handle `/kankaku task [pick|clear]`; `rest` excludes the leading `task`
+   * token. Default (no args) is `pick`. `pickTask`/`clearTask`
+   * (`session-target.ts`) notify their own outcome directly, so this only
+   * dispatches and refreshes the idle status line.
+   */
+  async function handleTaskCommand(rest: string[], ctx: ExtensionContext): Promise<void> {
+    const sessionTarget = deps.sessionTarget;
+    if (!sessionTarget) {
+      notifyError(ctx, new Error("hub is not configured"));
+      return;
+    }
+
+    if (rest.length === 1 && rest[0] === "clear") {
+      sessionTarget.clearTask(pi);
+      deps.refreshIdleStatus(ctx);
+      showReport(ctx, { title: "task", lines: ["task link cleared for this session"] });
+      return;
+    }
+
+    if (rest.length === 0 || (rest.length === 1 && rest[0] === "pick")) {
+      await sessionTarget.pickTask(pi, ctx);
+      deps.refreshIdleStatus(ctx);
+      return;
+    }
+
+    notifyError(ctx, new Error(`unknown task subcommand: ${rest.join(" ")}`));
+  }
+
   /** Handle `/kankaku catalog refresh`; `rest` excludes the leading `catalog` token. */
   async function handleCatalogCommand(rest: string[], ctx: ExtensionContext): Promise<void> {
     const catalog = deps.catalog;
@@ -598,6 +628,8 @@ export function registerKankakuCommand(pi: ExtensionAPI, deps: KankakuCommandDep
       "'doctor' to report orphan/uncertain subagent counts and ancestor-detection availability (no network). " +
       "When a hub (PocketBase) is configured: 'target' to show the effective client/project and its source, " +
       "'target pick' to run the picker again, 'target clear' to clear the session target, " +
+      "'task' (or 'task pick') to link this session to an open/doing hub task of the effective project, " +
+      "'task clear' to drop the link, " +
       "'catalog refresh' to force a catalog refresh, 'projects' for per-project totals today ('projects all' for every day), " +
       "'sync' to push pending tasks to the hub ('sync all' for a full re-evaluation, 'sync status' for the watermark/pending count/last error), " +
       "'backfill' to run a full sync and report how many tasks went to Sin determinar, grouped by their old label. " +
@@ -615,6 +647,11 @@ export function registerKankakuCommand(pi: ExtensionAPI, deps: KankakuCommandDep
         const prefix = targetMatch[1] ?? "";
         return TARGET_TOKENS.filter((value) => value.startsWith(prefix)).map((value) => ({ value, label: value }));
       }
+      const taskMatch = /^task\s+(\S*)$/.exec(argumentPrefix);
+      if (taskMatch) {
+        const prefix = taskMatch[1] ?? "";
+        return TASK_TOKENS.filter((value) => value.startsWith(prefix)).map((value) => ({ value, label: value }));
+      }
       const catalogMatch = /^catalog\s+(\S*)$/.exec(argumentPrefix);
       if (catalogMatch) {
         const prefix = catalogMatch[1] ?? "";
@@ -647,6 +684,11 @@ export function registerKankakuCommand(pi: ExtensionAPI, deps: KankakuCommandDep
           return;
         }
 
+        if (tokens[0] === "task") {
+          await handleTaskCommand(tokens.slice(1), ctx);
+          return;
+        }
+
         if (tokens[0] === "catalog") {
           await handleCatalogCommand(tokens.slice(1), ctx);
           return;

package/src/adapters/pi-tracker.ts

@@ -386,6 +386,8 @@ export function createPiTracker(pi: ExtensionAPI, deps: PiTrackerDeps): void {
             clientName: target.clientName,
             ...(target.projectId !== undefined ? { projectId: target.projectId } : {}),
             ...(target.projectName !== undefined ? { projectName: target.projectName } : {}),
+            ...(target.hubTaskId !== undefined ? { hubTaskId: target.hubTaskId } : {}),
+            ...(target.hubTaskTitle !== undefined ? { hubTaskTitle: target.hubTaskTitle } : {}),
           }
         : {}),
       ...(deps.machine !== undefined ? { machine: deps.machine } : {}),

package/src/adapters/pocketbase-catalog.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 { PocketBaseClient, PocketBaseRecord } from "./pocketbase-client.ts";
 
 interface ClientRecord extends PocketBaseRecord {
@@ -16,6 +16,15 @@ interface ProjectRecord extends PocketBaseRecord {
   active?: boolean;
 }
 
+interface TaskRecord extends PocketBaseRecord {
+  title?: string;
+  project: string;
+  status?: string;
+  external_ref?: string;
+}
+
+const TASK_STATUSES = new Set(["open", "doing", "done"]);
+
 function mapClient(record: ClientRecord): Client {
   return {
     id: record.id,
@@ -37,24 +46,44 @@ function mapProject(record: ProjectRecord): Project {
   };
 }
 
+/** `open` on any unrecognised or missing status, rather than dropping the task. */
+function mapTaskStatus(status: string | undefined): HubTask["status"] {
+  return status !== undefined && TASK_STATUSES.has(status) ? (status as HubTask["status"]) : "open";
+}
+
+function mapTask(record: TaskRecord): HubTask {
+  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: PocketBaseClient): (signal?: AbortSignal) => Promise<{ clients: Client[]; projects: Project[] }> {
+export function createPocketBaseCatalogFetcher(
+  client: PocketBaseClient,
+): (signal?: AbortSignal) => Promise<{ clients: Client[]; projects: Project[]; tasks: HubTask[] }> {
   return async (signal?: AbortSignal) => {
-    const [clientRecords, projectRecords] = await Promise.all([
+    const [clientRecords, projectRecords, taskRecords] = await Promise.all([
       client.list<ClientRecord>("clients", { sort: "name" }, signal),
       client.list<ProjectRecord>("projects", { sort: "name" }, signal),
+      client.list<TaskRecord>("tasks", { sort: "title" }, signal),
     ]);
 
     return {
       clients: clientRecords.map(mapClient),
       projects: projectRecords.map(mapProject),
+      tasks: taskRecords.map(mapTask),
     };
   };
 }

package/src/adapters/pocketbase-sink.ts

@@ -14,7 +14,7 @@
 import { buildTaskEntryCreatePayload, buildTaskEntryUpdatePayload, buildWorkRecordPayload, resolveTaskAssignment, taskWorkRecords } from "../domain/hub-entry.ts";
 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 { PushOutcome, PushTaskResult, WorkSink } from "../ports/work-sink.ts";
 import type { PocketBaseClient, PocketBaseRecord } from "./pocketbase-client.ts";
 import { PocketBaseError } from "./pocketbase-client.ts";
@@ -24,6 +24,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"`. */
@@ -105,10 +106,21 @@ export class PocketBaseSink implements WorkSink {
     return found.get(value);
   }
 
-  private get entryContext(): { clients: Client[]; projects: Project[]; machine: string; promptMode: PromptPrivacyMode; agent: string; agentVersion?: string; plugin: string; pluginVersion?: string } {
+  private get entryContext(): {
+    clients: Client[];
+    projects: Project[];
+    tasks: HubTask[];
+    machine: string;
+    promptMode: PromptPrivacyMode;
+    agent: string;
+    agentVersion?: string;
+    plugin: string;
+    pluginVersion?: string;
+  } {
     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",
@@ -177,7 +189,7 @@ export class PocketBaseSink implements WorkSink {
   }
 
   private async pushOne(task: TaskView, existingId: string | undefined): Promise<PushOutcome> {
-    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 {

package/src/adapters/report.ts

@@ -1,7 +1,7 @@
 import { buildTasks, uncertainRecords } from "../domain/task-view.ts";
 import type { SessionView, TaskView } from "../domain/task-view.ts";
 import { localDay } from "../domain/day.ts";
-import { finiteOrZero } from "../domain/work-record.ts";
+import { cacheHitRatio, finiteOrZero } from "../domain/work-record.ts";
 import type { WorkRecord, WorkRole } from "../domain/work-record.ts";
 
 export { localDay } from "../domain/day.ts";
@@ -13,6 +13,12 @@ export interface RoleTotals {
   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>;
 }
@@ -23,6 +29,12 @@ export interface TaskTotals {
   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>;
 }
@@ -39,7 +51,7 @@ export interface SummarizeOptions {
 const ROLES: WorkRole[] = ["orchestrator", "subagent"];
 
 function emptyTotals(): RoleTotals {
-  return { workMs: 0, waitingMs: 0, wallMs: 0, count: 0, cost: 0, segments: {} };
+  return { workMs: 0, waitingMs: 0, wallMs: 0, count: 0, cost: 0, input: 0, cacheRead: 0, cacheWrite: 0, segments: {} };
 }
 
 /**
@@ -67,7 +79,7 @@ export function summarize(records: WorkRecord[], options: SummarizeOptions): Sum
   const summary: Summary = {
     orchestrator: emptyTotals(),
     subagent: emptyTotals(),
-    tasks: { count: 0, wallMs: 0, workMs: 0, cost: 0, segments: {} },
+    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`.
@@ -82,6 +94,9 @@ export function summarize(records: WorkRecord[], options: SummarizeOptions): Sum
     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);
   }
 
@@ -91,6 +106,9 @@ export function summarize(records: WorkRecord[], options: SummarizeOptions): Sum
     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);
   }
 
@@ -131,6 +149,12 @@ function formatTime(iso: string): string {
   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: { input: number; cacheRead: number; cacheWrite: number }): string | undefined {
+  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: Record<string, number>): string | undefined {
   const tags = Object.keys(segments)
@@ -144,10 +168,14 @@ function formatSegmentTags(segments: Record<string, number>): string | undefined
 export function formatReport(summary: Summary): string {
   const lines = ROLES.map((role) => {
     const totals = summary[role];
-    return `${role}: work ${formatMinutes(totals.workMs)}, waiting ${formatMinutes(totals.waitingMs)}, ${totals.count} record(s), ${formatCost(totals.cost)}`;
+    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)}`,
+    `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) {
@@ -173,7 +201,9 @@ export function formatTasks(tasks: TaskView[]): string {
       const segmentTags = formatSegmentTags(task.segments);
       const segmentPart = segmentTags !== undefined ? `  ${segmentTags}` : "";
       const clientPart = task.client !== undefined ? `  client:${task.client}` : "";
-      return `${formatTime(task.startedAt)}${clientPart}  wall ${formatMinutes(task.wallMs)}  work ${formatMinutes(task.workMs)}  ${formatCost(task.usage.cost)}${segmentPart}  subagents ${task.subagents.length}  ${prompt}`;
+      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");
 }
@@ -184,6 +214,12 @@ export interface ClientTotals {
   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;
 }
 
@@ -201,11 +237,14 @@ export function summarizeByClient(tasks: TaskView[]): Map<string, ClientTotals>
   const totals = new Map<string, ClientTotals>();
   for (const task of tasks) {
     const key = task.client ?? NO_CLIENT;
-    const entry = totals.get(key) ?? { wallMs: 0, waitingMs: 0, workMs: 0, cost: 0, count: 0 };
+    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);
   }
@@ -220,6 +259,12 @@ export interface ProjectTotals {
   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;
 }
 
@@ -237,11 +282,14 @@ export function summarizeByProject(tasks: TaskView[]): Map<string, ProjectTotals
   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, count: 0 };
+    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);
   }
@@ -253,10 +301,11 @@ export function formatProjects(totals: Map<string, ProjectTotals>): string {
   if (totals.size === 0) return "no projects";
   return Array.from(totals.values())
     .sort((a, b) => a.name.localeCompare(b.name))
-    .map(
-      (t) =>
-        `${t.name}  work ${formatMinutes(t.workMs)}  waiting ${formatMinutes(t.waitingMs)}  wall ${formatMinutes(t.wallMs)}  ${formatCost(t.cost)}  tasks ${t.count}`,
-    )
+    .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");
 }
 
@@ -265,10 +314,11 @@ export function formatClients(totals: Map<string, ClientTotals>): string {
   if (totals.size === 0) return "no clients";
   return Array.from(totals.entries())
     .sort(([a], [b]) => a.localeCompare(b))
-    .map(
-      ([client, t]) =>
-        `${client}  work ${formatMinutes(t.workMs)}  waiting ${formatMinutes(t.waitingMs)}  wall ${formatMinutes(t.wallMs)}  ${formatCost(t.cost)}  tasks ${t.count}`,
-    )
+    .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");
 }
 

package/src/adapters/session-target.ts

@@ -3,7 +3,7 @@ import { formatWorkTargetLabel, resolveWorkTarget, resolveWorkTargetSource } fro
 import type { WorkTarget, WorkTargetCandidate, WorkTargetSessionOverride, WorkTargetSourceName } from "../domain/work-target.ts";
 import type { WorkRole } from "../domain/work-record.ts";
 import type { Catalog, CatalogSnapshot } from "../ports/catalog.ts";
-import { pickTarget } from "./target-picker.ts";
+import { pickHubTask, pickTarget } from "./target-picker.ts";
 
 /** Persisted as a `kankaku-target` custom session entry so the session-level target survives a reload. */
 export interface KankakuTargetEntryData {
@@ -11,6 +11,13 @@ export interface KankakuTargetEntryData {
   projectId?: string;
   /** `true` when the user explicitly declined the picker; distinct from "no entry yet". */
   skipped?: boolean;
+  /**
+   * A hub task picked for this session (`/kankaku task pick`). Session-only:
+   * never written to the project's `.kankaku/config.json`, and dropped by
+   * any target change (`pick`/`setExplicit`/`clear`/`ensurePicked`'s
+   * silent resolution) since those all build a fresh candidate without it.
+   */
+  hubTaskId?: string;
 }
 
 export const TARGET_ENTRY_TYPE = "kankaku-target";
@@ -64,6 +71,16 @@ export interface SessionTarget {
   setExplicit(pi: ExtensionAPI, ids: WorkTargetCandidate): void;
   /** Clear the session-level override; resolution falls back to the project config file / `repo_paths`. */
   clear(pi: ExtensionAPI): void;
+  /**
+   * `/kankaku task pick`: shows the hub-task picker for the effective
+   * project's open/doing tasks and links the pick to the session (never
+   * persisted to the project config file). Notifies when there is no
+   * effective client/project yet, or the project has no open/doing task.
+   * A no-op unless `role === "orchestrator"` and `ctx.hasUI`.
+   */
+  pickTask(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void>;
+  /** `/kankaku task clear`: drops the linked hub task, keeping the rest of the session target. A no-op when none is linked. */
+  clearTask(pi: ExtensionAPI): void;
   /** Current effective target (session > project config > repoPaths), regardless of role. */
   effectiveTarget(): WorkTarget | undefined;
   /** Which source produced {@link effectiveTarget}. */
@@ -81,7 +98,11 @@ function candidateFrom(target: WorkTarget): WorkTargetCandidate {
 }
 
 function entryDataFrom(ids: WorkTargetCandidate): KankakuTargetEntryData {
-  return { clientId: ids.clientId, ...(ids.projectId !== undefined ? { projectId: ids.projectId } : {}) };
+  return {
+    clientId: ids.clientId,
+    ...(ids.projectId !== undefined ? { projectId: ids.projectId } : {}),
+    ...(ids.hubTaskId !== undefined ? { hubTaskId: ids.hubTaskId } : {}),
+  };
 }
 
 /**
@@ -113,7 +134,11 @@ export function createSessionTarget(deps: SessionTargetDeps): SessionTarget {
         if (data?.skipped === true) {
           sessionOverride = "skipped";
         } else if (typeof data?.clientId === "string") {
-          sessionOverride = { clientId: data.clientId, ...(typeof data.projectId === "string" ? { projectId: data.projectId } : {}) };
+          sessionOverride = {
+            clientId: data.clientId,
+            ...(typeof data.projectId === "string" ? { projectId: data.projectId } : {}),
+            ...(typeof data.hubTaskId === "string" ? { hubTaskId: data.hubTaskId } : {}),
+          };
         } else {
           sessionOverride = undefined;
         }
@@ -131,6 +156,7 @@ export function createSessionTarget(deps: SessionTargetDeps): SessionTarget {
       cwd: cwd(),
       clients: snapshot?.clients ?? [],
       projects: snapshot?.projects ?? [],
+      tasks: snapshot?.tasks ?? [],
     });
   }
 
@@ -320,5 +346,39 @@ export function createSessionTarget(deps: SessionTargetDeps): SessionTarget {
     pi.appendEntry<KankakuTargetEntryData>(TARGET_ENTRY_TYPE, {});
   }
 
-  return { restore, ensurePicked, pick, setExplicit, clear, effectiveTarget, effectiveSource, runTarget, idleTarget, endRun };
+  async function pickTask(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
+    if (deps.role !== "orchestrator" || !ctx.hasUI) return;
+
+    const target = effectiveTarget();
+    if (!target || target.projectId === undefined) {
+      ctx.ui.notify("kankaku: Pick a client and project first (/kankaku target pick)", "warning");
+      return;
+    }
+
+    const tasks = deps.catalog.read()?.tasks ?? [];
+    const result = await pickHubTask(ctx, tasks, target.projectId);
+
+    if (result.kind === "empty") {
+      ctx.ui.notify(`kankaku: No open tasks for ${target.projectName ?? target.projectId} in the hub`, "warning");
+      return;
+    }
+    if (result.kind === "skipped") return;
+
+    const ids: WorkTargetCandidate = { ...candidateFrom(target), hubTaskId: result.task.id };
+    sessionOverride = ids;
+    pi.appendEntry<KankakuTargetEntryData>(TARGET_ENTRY_TYPE, entryDataFrom(ids));
+
+    const updated = effectiveTarget();
+    if (updated) ctx.ui.notify(`kankaku: task set to ${formatWorkTargetLabel(updated)}`);
+  }
+
+  function clearTask(pi: ExtensionAPI): void {
+    if (sessionOverride === undefined || sessionOverride === "skipped") return;
+    if (sessionOverride.hubTaskId === undefined) return;
+    const { hubTaskId: _hubTaskId, ...rest } = sessionOverride;
+    sessionOverride = rest;
+    pi.appendEntry<KankakuTargetEntryData>(TARGET_ENTRY_TYPE, entryDataFrom(rest));
+  }
+
+  return { restore, ensurePicked, pick, setExplicit, clear, pickTask, clearTask, effectiveTarget, effectiveSource, runTarget, idleTarget, endRun };
 }

package/src/adapters/target-picker.ts

@@ -1,5 +1,5 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { Client, Project, WorkTarget } from "../domain/work-target.ts";
+import type { Client, HubTask, Project, WorkTarget } from "../domain/work-target.ts";
 
 const SKIP_OPTION = "— skip —";
 const NO_PROJECT_OPTION = "(no project)";
@@ -80,3 +80,48 @@ export async function pickTarget(ctx: ExtensionContext, catalog: PickerCatalog):
 
   return { kind: "picked", target };
 }
+
+export type PickHubTaskResult = { kind: "picked"; task: HubTask } | { kind: "skipped" } | { kind: "empty" };
+
+/**
+ * Build `label -> task` options for {@link pickHubTask}, sorted by title.
+ * When two tasks share the same title, disambiguate every colliding label
+ * with the task's `externalRef` when it has one, or its bare id otherwise —
+ * unlike {@link labelOptions}, a hub task has no `code`, and every task
+ * needs a disambiguator, not just the ones lucky enough to have one.
+ */
+function labelTaskOptions(tasks: HubTask[]): LabeledOption<HubTask>[] {
+  const sorted = [...tasks].sort((a, b) => a.title.localeCompare(b.title));
+  const titleCounts = new Map<string, number>();
+  for (const task of sorted) {
+    titleCounts.set(task.title, (titleCounts.get(task.title) ?? 0) + 1);
+  }
+
+  return sorted.map((task) => {
+    const collides = (titleCounts.get(task.title) ?? 0) > 1;
+    const label = collides ? `${task.title} (${task.externalRef ?? task.id})` : task.title;
+    return { label, item: task };
+  });
+}
+
+/**
+ * Run the hub-task picker (`ctx.ui.select`) for `projectId`'s open/doing
+ * tasks. Pure UI interaction: no network, no persistence — the caller
+ * (`session-target.ts#pickTask`) decides what to do with the result.
+ * `{ kind: "empty" }` is returned without ever prompting when the project
+ * has no open/doing task, so the caller can tell "nothing to pick from"
+ * apart from "the user skipped".
+ */
+export async function pickHubTask(ctx: ExtensionContext, tasks: HubTask[], projectId: string): Promise<PickHubTaskResult> {
+  const pickable = tasks.filter((task) => task.status !== "done" && task.projectId === projectId);
+  if (pickable.length === 0) return { kind: "empty" };
+
+  const taskOptions = labelTaskOptions(pickable);
+  const choice = await ctx.ui.select("kankaku — task", [...taskOptions.map((option) => option.label), SKIP_OPTION]);
+  if (choice === undefined || choice === SKIP_OPTION) return { kind: "skipped" };
+
+  const task = taskOptions.find((option) => option.label === choice)?.item;
+  if (!task) return { kind: "skipped" };
+
+  return { kind: "picked", task };
+}