kankaku 0.6.0 → 0.6.5

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
@@ -686,7 +688,11 @@ 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
+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:
@@ -719,6 +725,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 +834,33 @@ 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.
 
+### 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>`.
+
 ### Caching and offline behaviour
 
 The catalog (clients/projects) is cached machine-wide at
@@ -905,10 +941,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 +1291,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;

package/dist/domain/work-target.js

@@ -26,7 +26,18 @@ function findUsableProject(projects, projectId, clientId) {
         return undefined;
     return project;
 }
-function buildTarget(client, project) {
+/**
+ * A hub task usable as a link target: exists and belongs to `projectId`.
+ * Any {@link HubTask.status} is accepted — a task marked `done` mid-session
+ * keeps linking — only the project match matters here.
+ */
+function findUsableTask(tasks, taskId, projectId) {
+    const task = tasks.find((candidate) => candidate.id === taskId);
+    if (!task || task.projectId !== projectId)
+        return undefined;
+    return task;
+}
+function buildTarget(client, project, task) {
     return {
         clientId: client.id,
         clientCode: client.code,
@@ -38,6 +49,7 @@ function buildTarget(client, project) {
                 projectName: project.name,
             }
             : {}),
+        ...(task !== undefined ? { hubTaskId: task.id, hubTaskTitle: task.title } : {}),
     };
 }
 /**
@@ -45,14 +57,17 @@ function buildTarget(client, project) {
  * file) into a target, or `undefined` when the client id does not resolve
  * to a usable client. A projectId that does not resolve to a usable
  * project of that client is dropped — the client-only target is still
- * returned — rather than failing the whole candidate.
+ * returned — rather than failing the whole candidate. A `hubTaskId` is
+ * kept only when it resolves to a task of the resolved project; a target
+ * with no project never carries one.
  */
-function resolveCandidate(candidate, clients, projects) {
+function resolveCandidate(candidate, clients, projects, tasks) {
     const client = findUsableClient(clients, candidate.clientId);
     if (!client)
         return undefined;
     const project = candidate.projectId !== undefined ? findUsableProject(projects, candidate.projectId, client.id) : undefined;
-    return buildTarget(client, project);
+    const task = project !== undefined && candidate.hubTaskId !== undefined ? findUsableTask(tasks, candidate.hubTaskId, project.id) : undefined;
+    return buildTarget(client, project, task);
 }
 /** The longest-matching active project whose `repoPaths` contains `cwd`, exactly or as an ancestor directory. */
 function matchByRepoPath(cwd, projects) {
@@ -82,11 +97,12 @@ function isCwdWithin(cwd, repoPath) {
 /** Which source (if any) {@link resolveWorkTarget} would use, computed independently so callers can display it. */
 export function resolveWorkTargetSource(input) {
     const { session } = input;
+    const tasks = input.tasks ?? [];
     if (session === "skipped")
         return undefined;
-    if (session !== undefined && resolveCandidate(session, input.clients, input.projects) !== undefined)
+    if (session !== undefined && resolveCandidate(session, input.clients, input.projects, tasks) !== undefined)
         return "session";
-    if (input.project !== undefined && resolveCandidate(input.project, input.clients, input.projects) !== undefined)
+    if (input.project !== undefined && resolveCandidate(input.project, input.clients, input.projects, tasks) !== undefined)
         return "project";
     const matched = matchByRepoPath(input.cwd, input.projects);
     if (matched && findUsableClient(input.clients, matched.clientId))
@@ -101,15 +117,16 @@ export function resolveWorkTargetSource(input) {
  */
 export function resolveWorkTarget(input) {
     const { session } = input;
+    const tasks = input.tasks ?? [];
     if (session === "skipped")
         return undefined;
     if (session !== undefined) {
-        const resolved = resolveCandidate(session, input.clients, input.projects);
+        const resolved = resolveCandidate(session, input.clients, input.projects, tasks);
         if (resolved)
             return resolved;
     }
     if (input.project !== undefined) {
-        const resolved = resolveCandidate(input.project, input.clients, input.projects);
+        const resolved = resolveCandidate(input.project, input.clients, input.projects, tasks);
         if (resolved)
             return resolved;
     }
@@ -117,11 +134,16 @@ export function resolveWorkTarget(input) {
     if (matched) {
         const client = findUsableClient(input.clients, matched.clientId);
         if (client)
-            return buildTarget(client, matched);
+            return buildTarget(client, matched, undefined);
     }
     return 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 function formatWorkTargetLabel(target) {
-    return target.projectName ? `${target.clientName} · ${target.projectName}` : target.clientName;
+    const base = target.projectName ? `${target.clientName} · ${target.projectName}` : target.clientName;
+    return target.hubTaskTitle ? `${base} › ${target.hubTaskTitle}` : base;
 }

package/dist/ports/catalog.d.ts

@@ -1,10 +1,12 @@
-import type { Client, Project } from "../domain/work-target.ts";
-/** A cached read of the hub's clients/projects, plus when and against which hub URL it was fetched. */
+import type { Client, HubTask, Project } from "../domain/work-target.ts";
+/** A cached read of the hub's clients/projects/tasks, plus when and against which hub URL it was fetched. */
 export interface CatalogSnapshot {
     fetchedAt: number;
     url: string;
     clients: Client[];
     projects: Project[];
+    /** Optional because a cache written by an older build (before hub task linking) never had this field; a missing value reads as "no tasks known yet." */
+    tasks?: HubTask[];
 }
 /**
  * Read-only access to the hub catalog (clients/projects). `read()` is a

package/package.json

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