kankaku 0.6.0 → 0.7.0

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,34 @@ 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;
+  /**
+   * Set the linked hub task directly, bypassing the picker — the panel's
+   * target screen (`adapters/panel/screens/target.ts`) uses this once the
+   * user has already chosen a task from its own `SelectList`. Builds the
+   * session override from the current {@link effectiveTarget}'s candidate
+   * plus `hubTaskId` and appends the session entry, exactly like
+   * {@link pickTask}'s own persistence step. A no-op when there is no
+   * effective target with a project.
+   */
+  setTask(pi: ExtensionAPI, hubTaskId: string): void;
+  /**
+   * `/kankaku target remember` / the panel's "Remember" row: persists the
+   * current {@link effectiveTarget}'s `clientId`/`projectId` (never
+   * `hubTaskId` — task linking stays session-only) to the project's
+   * `.kankaku/config.json`. Returns `false`, without persisting anything,
+   * when there is no effective target.
+   */
+  rememberTarget(): boolean;
   /** Current effective target (session > project config > repoPaths), regardless of role. */
   effectiveTarget(): WorkTarget | undefined;
   /** Which source produced {@link effectiveTarget}. */
@@ -81,7 +116,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 +152,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 +174,7 @@ export function createSessionTarget(deps: SessionTargetDeps): SessionTarget {
       cwd: cwd(),
       clients: snapshot?.clients ?? [],
       projects: snapshot?.projects ?? [],
+      tasks: snapshot?.tasks ?? [],
     });
   }
 
@@ -320,5 +364,68 @@ export function createSessionTarget(deps: SessionTargetDeps): SessionTarget {
     pi.appendEntry<KankakuTargetEntryData>(TARGET_ENTRY_TYPE, {});
   }
 
-  return { restore, ensurePicked, pick, setExplicit, clear, effectiveTarget, effectiveSource, runTarget, idleTarget, endRun };
+  function setTask(pi: ExtensionAPI, hubTaskId: string): void {
+    const target = effectiveTarget();
+    if (!target || target.projectId === undefined) return;
+
+    const ids: WorkTargetCandidate = { ...candidateFrom(target), hubTaskId };
+    sessionOverride = ids;
+    pi.appendEntry<KankakuTargetEntryData>(TARGET_ENTRY_TYPE, entryDataFrom(ids));
+  }
+
+  function rememberTarget(): boolean {
+    const target = effectiveTarget();
+    if (!target) return false;
+    deps.persistProjectConfig(candidateFrom(target));
+    return true;
+  }
+
+  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;
+
+    setTask(pi, result.task.id);
+
+    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,
+    setTask,
+    rememberTarget,
+    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 };
+}

package/src/domain/hub-entry.ts

@@ -13,13 +13,15 @@
 import type { TaskView } from "./task-view.ts";
 import type { WorkRecord, WorkRole, WorkStatus } from "./work-record.ts";
 import { finiteOrZero } from "./work-record.ts";
-import type { Client, 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}. */
@@ -39,6 +41,8 @@ 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. */
@@ -46,7 +50,8 @@ export interface TaskAssignment {
 }
 
 /**
- * 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
@@ -57,16 +62,25 @@ 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 function resolveTaskAssignment(task: TaskView, clients: Client[], projects: Project[]): TaskAssignment {
+export function resolveTaskAssignment(task: TaskView, clients: Client[], projects: Project[], tasks: HubTask[]): TaskAssignment {
   const client = task.clientId !== undefined ? clients.find((candidate) => candidate.id === task.clientId) : undefined;
 
   if (client) {
     const project =
       task.projectId !== undefined ? projects.find((candidate) => candidate.id === task.projectId && candidate.clientId === client.id) : undefined;
+    const hubTask =
+      project !== undefined && task.hubTaskId !== undefined
+        ? tasks.find((candidate) => candidate.id === task.hubTaskId && candidate.projectId === project.id)
+        : undefined;
     return {
       clientId: client.id,
       projectId: project ? project.id : "",
+      hubTaskId: hubTask ? hubTask.id : "",
       legacyClientLabel: "",
       routedToUnassigned: false,
     };
@@ -76,6 +90,7 @@ export function resolveTaskAssignment(task: TaskView, clients: Client[], project
   return {
     clientId: unassigned ? unassigned.id : "",
     projectId: "",
+    hubTaskId: "",
     legacyClientLabel: task.client ?? task.clientName ?? "",
     routedToUnassigned: true,
   };
@@ -208,12 +223,12 @@ export type TaskEntryUpdatePayload = Omit<TaskEntryPayload, "client" | "project"
 
 /** Build the full `task_entries` payload for a **create** request — every field, including assignment. */
 export function buildTaskEntryCreatePayload(task: TaskView, ctx: HubEntryContext): TaskEntryPayload {
-  const assignment = resolveTaskAssignment(task, ctx.clients, ctx.projects);
+  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/src/domain/panel-model.ts

@@ -0,0 +1,267 @@
+/**
+ * Pure model for the `/kankaku` panel (see odd/tasks/kankaku-panel.md): the
+ * set of screens, the root menu, an immutable navigation stack, the
+ * title/footer-hint text every adapter screen renders from, and pure row
+ * builders (e.g. {@link buildTargetRows}) that turn kankaku state into row
+ * models for a screen's `SettingsList`. No I/O, no pi imports — see
+ * AGENTS.md "Architecture (hexagonal)".
+ */
+
+import type { WorkTarget } from "./work-target.ts";
+
+export type PanelScreenId = "root" | "target" | "report" | "sync" | "export" | "doctor" | "about";
+
+/** One row of the root menu (`rootMenu`): a section the panel can navigate to. */
+export interface PanelMenuItem {
+  id: PanelScreenId;
+  label: string;
+  description: string;
+  /** Offered only when the hub (PocketBase) is configured; see {@link rootMenu}. */
+  hubOnly: boolean;
+}
+
+const ROOT_MENU_ITEMS: PanelMenuItem[] = [
+  // Not hub-only: the legacy billing label (`/kankaku client <name>`) is
+  // set from this same screen and works with no hub configured at all.
+  { id: "target", label: "Target", description: "Billing client, project, hub task, legacy label", hubOnly: false },
+  { id: "report", label: "Report", description: "Today/all totals, tasks, sessions, clients, projects", hubOnly: false },
+  { id: "sync", label: "Sync", description: "Status, sync now, sync all, backfill, catalog refresh", hubOnly: true },
+  { id: "export", label: "Export", description: "Write today's or every task as csv/json", hubOnly: false },
+  { id: "doctor", label: "Doctor", description: "Orphan/uncertain subagent counts, ancestor detection", hubOnly: false },
+  { id: "about", label: "About", description: "Versions, KANKAKU_DIR, env-only config", hubOnly: false },
+];
+
+/**
+ * The root menu's rows, in a fixed order. `hubOnly` rows (only `sync`;
+ * `target` is not hub-only — see `ROOT_MENU_ITEMS`'s comment) are omitted
+ * entirely when the hub is not configured, so the panel offers exactly what
+ * `/kankaku` itself would today.
+ */
+export function rootMenu(options: { hubConfigured: boolean }): PanelMenuItem[] {
+  return ROOT_MENU_ITEMS.filter((item) => options.hubConfigured || !item.hubOnly);
+}
+
+/** Immutable navigation stack: `stack[0]` is always `"root"`. */
+export interface PanelNav {
+  stack: PanelScreenId[];
+}
+
+/** A fresh navigation stack, positioned at the root screen. */
+export function navRoot(): PanelNav {
+  return { stack: ["root"] };
+}
+
+/** Push a screen onto the stack, returning a new {@link PanelNav}; the input is never mutated. */
+export function navPush(nav: PanelNav, id: PanelScreenId): PanelNav {
+  return { stack: [...nav.stack, id] };
+}
+
+/**
+ * Pop the current screen, returning a new {@link PanelNav} and whether the
+ * panel should close. At the root, there is nothing left to pop: the stack
+ * is returned unchanged and `closed` is `true` — the caller closes the
+ * overlay instead of navigating.
+ */
+export function navBack(nav: PanelNav): { nav: PanelNav; closed: boolean } {
+  if (nav.stack.length <= 1) {
+    return { nav, closed: true };
+  }
+  return { nav: { stack: nav.stack.slice(0, -1) }, closed: false };
+}
+
+/** The screen currently on top of the stack. */
+export function navCurrent(nav: PanelNav): PanelScreenId {
+  return nav.stack[nav.stack.length - 1] ?? "root";
+}
+
+const SCREEN_TITLES: Record<Exclude<PanelScreenId, "root">, string> = {
+  target: "Target",
+  report: "Report",
+  sync: "Sync",
+  export: "Export",
+  doctor: "Doctor",
+  about: "About",
+};
+
+/** `kankaku` at root, `kankaku · <Screen>` on every other screen. */
+export function panelTitle(screen: PanelScreenId): string {
+  if (screen === "root") return "kankaku";
+  return `kankaku · ${SCREEN_TITLES[screen]}`;
+}
+
+/** One clickable/keyboard hint shown in the panel's footer. */
+export interface PanelHint {
+  key: string;
+  label: string;
+}
+
+/**
+ * The footer hint row for a screen: navigation hints, an optional search
+ * hint when the current body supports it, and how Escape/`q` behave — back
+ * at root closes the panel outright, so root shows only `esc close`; every
+ * other screen shows both `esc back` and `q close`.
+ */
+export function footerHints(screen: PanelScreenId, options: { searchable: boolean }): PanelHint[] {
+  const hints: PanelHint[] = [{ key: "↑↓", label: "move" }];
+
+  if (screen === "root") {
+    hints.push({ key: "enter", label: "open" });
+    if (options.searchable) hints.push({ key: "/", label: "search" });
+    hints.push({ key: "esc", label: "close" });
+    return hints;
+  }
+
+  hints.push({ key: "enter", label: "select" });
+  if (options.searchable) hints.push({ key: "/", label: "search" });
+  hints.push({ key: "esc", label: "back" }, { key: "q", label: "close" });
+  return hints;
+}
+
+/** One row of a `SettingsList`-backed screen (e.g. {@link buildTargetRows}'s output). */
+export interface PanelRow {
+  id: string;
+  label: string;
+  value: string;
+  description?: string;
+}
+
+const NONE_VALUE = "— none —";
+
+/** Pure input for {@link buildTargetRows}. */
+export interface TargetRowsInput {
+  /** Whether the hub (PocketBase) is configured; see `rootMenu`'s `target` row, which is offered either way. */
+  hubConfigured: boolean;
+  /** The current effective hub target, if any (`SessionTarget#effectiveTarget()`). */
+  target?: WorkTarget;
+  /** Which source produced {@link target} (already formatted by the caller as `"session" | "config" | "repoPaths"`), or `undefined` for none. */
+  source?: string;
+  /** The current effective legacy billing label (`SessionClient#effectiveClient()`), if any. */
+  legacyLabel?: string;
+  /** Which source produced {@link legacyLabel} (already formatted by the caller), or `undefined` for none. */
+  legacySource?: string;
+}
+
+/**
+ * Build the target screen's rows from kankaku's current billing-target
+ * state. Pure: the caller (`adapters/panel/screens/target.ts`) resolves
+ * `target`/`source`/`legacyLabel`/`legacySource` from `SessionTarget`/
+ * `SessionClient` and formats each source name as a plain string, so this
+ * function never depends on their concrete types.
+ *
+ * `client`/`project`/`task`/`source`/`remember` are included only when
+ * {@link TargetRowsInput.hubConfigured} is `true` — the panel's `target`
+ * screen is offered either way (see `rootMenu`), but those rows only make
+ * sense once a hub exists to resolve them against. `legacy` is always
+ * included: the legacy billing label works with no hub at all.
+ */
+export function buildTargetRows(input: TargetRowsInput): PanelRow[] {
+  const rows: PanelRow[] = [];
+  const target = input.target;
+  const hasClient = target !== undefined;
+  const hasProject = target !== undefined && target.projectId !== undefined;
+
+  if (input.hubConfigured) {
+    rows.push({
+      id: "client",
+      label: "Client",
+      value: hasClient ? `${target.clientName} (${target.clientCode})` : NONE_VALUE,
+    });
+
+    rows.push({
+      id: "project",
+      label: "Project",
+      value: hasProject ? (target.projectName ?? NONE_VALUE) : NONE_VALUE,
+      ...(hasClient ? {} : { description: "pick a client first" }),
+    });
+
+    rows.push({
+      id: "task",
+      label: "Task",
+      value: hasProject && target.hubTaskTitle !== undefined ? target.hubTaskTitle : NONE_VALUE,
+      ...(hasProject ? {} : { description: "pick a project first" }),
+    });
+
+    rows.push({
+      id: "source",
+      label: "Source",
+      value: input.source ?? "none",
+    });
+
+    rows.push({
+      id: "remember",
+      label: "Remember",
+      value: "save to config.json",
+      description: "Saves the client and project (never the linked task) to this repository's .kankaku/config.json.",
+    });
+  }
+
+  rows.push({
+    id: "legacy",
+    label: "Legacy label",
+    value: input.legacyLabel ?? NONE_VALUE,
+    description: `Source: ${input.legacySource ?? "none"}`,
+  });
+
+  return rows;
+}
+
+/**
+ * Pure input for {@link buildAboutRows}. Every env-only value is passed in
+ * already extracted from `KankakuConfig` (see `config.ts`) rather than the
+ * config object itself: `KankakuConfig` lives outside `src/domain/`, and
+ * this module must import nothing but `src/domain/`/`src/ports/` (see
+ * AGENTS.md "Architecture (hexagonal)").
+ */
+export interface AboutRowsInput {
+  /** kankaku's own version (`adapters/agent-info.ts#resolvePluginVersion`). */
+  pluginVersion?: string;
+  /** pi's version (`adapters/agent-info.ts#resolveAgentVersion`). */
+  agentVersion?: string;
+  /** This session's resolved kankaku directory (`adapters/kankaku-dir.ts#resolveKankakuDir`). */
+  kankakuDir: string;
+  /** The hub (PocketBase) URL, when configured. */
+  hubUrl?: string;
+  /** `KankakuConfig.interactiveTools`. */
+  interactiveTools: string[];
+  /** `KankakuConfig.segmentRules.length`. */
+  segmentRuleCount: number;
+  /** `KankakuConfig.subagentProfiles`' ids. */
+  subagentProfileNames: string[];
+  /** `KankakuConfig.client`. */
+  client?: string;
+}
+
+/**
+ * Build the panel's `about` screen rows: versions, the resolved directory,
+ * the hub URL, and every env-only setting (`KANKAKU_INTERACTIVE_TOOLS`,
+ * `KANKAKU_SEGMENTS`, `KANKAKU_SUBAGENT_TOOLS`/`KANKAKU_SUBAGENT_CHILD_ENV`,
+ * `KANKAKU_CLIENT`) with its env var name as the row's description — every
+ * row is read-only (see `screens/about.ts`).
+ */
+export function buildAboutRows(input: AboutRowsInput): PanelRow[] {
+  return [
+    { id: "kankaku", label: "kankaku", value: input.pluginVersion ?? "unknown" },
+    { id: "pi", label: "pi", value: input.agentVersion ?? "unknown" },
+    { id: "directory", label: "Directory", value: input.kankakuDir },
+    { id: "hub", label: "Hub", value: input.hubUrl ?? "not configured" },
+    {
+      id: "interactive-tools",
+      label: "Interactive tools",
+      value: input.interactiveTools.length > 0 ? input.interactiveTools.join(", ") : NONE_VALUE,
+      description: "KANKAKU_INTERACTIVE_TOOLS",
+    },
+    {
+      id: "segments",
+      label: "Segments",
+      value: `${input.segmentRuleCount} rule(s)`,
+      description: "KANKAKU_SEGMENTS",
+    },
+    {
+      id: "subagent-profiles",
+      label: "Subagent profiles",
+      value: input.subagentProfileNames.length > 0 ? input.subagentProfileNames.join(", ") : NONE_VALUE,
+      description: "KANKAKU_SUBAGENT_TOOLS / KANKAKU_SUBAGENT_CHILD_ENV",
+    },
+    { id: "client", label: "Client", value: input.client ?? NONE_VALUE, description: "KANKAKU_CLIENT" },
+  ];
+}

package/src/domain/task-view.ts

@@ -36,6 +36,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
@@ -368,6 +372,8 @@ function buildTaskView(orchestrator: WorkRecord, subagents: WorkRecord[]): TaskV
     ...(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/src/domain/work-record.ts

@@ -168,6 +168,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;
   /**
@@ -210,6 +214,23 @@ export function finiteOrZero(value: unknown): number {
   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: { input: number; cacheRead: number; cacheWrite: number }): number | undefined {
+  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<WorkRole>(["orchestrator", "subagent"]);
 const STATUSES = new Set<WorkStatus>(["completed", "aborted", "interrupted"]);
 
@@ -267,6 +288,8 @@ export function isWorkRecord(value: unknown): value is WorkRecord {
     (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"])) &&