kankaku-claude 0.11.0 → 0.12.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "kankaku",
   "description": "Records how long Claude Code works on each of your prompts: wall time, waiting time, work time and cost, per prompt, in kankaku's worklog format.",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "author": {
     "name": "soyunninja"
   },

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to this project are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## 0.12.0 — 2026-09-29
+
+### Added
+
+- **`/kankaku:task` links the session to a hub task.** It lists the open
+  tasks of the project resolved for the folder, and picks one by number, hub
+  id or title text (`clear` removes the link). The link is session-only, kept
+  in `<KANKAKU_DIR>/claude/<session>.target.json`, and the records written at
+  Stop, SessionEnd and crash recovery carry `hubTaskId` and `hubTaskTitle`
+  while the task still belongs to the resolved project. `/kankaku:status` and
+  `/kankaku:doctor` print the `task:` line. The CLI finds its session from its
+  own process; `KANKAKU_CLAUDE_SESSION` names it explicitly.
+
 ## 0.11.0 — 2026-09-29
 
 ### Added

package/README.md

@@ -142,6 +142,8 @@ anything behind in whatever project happens to be open.
   session id, whether its process is still alive, whether a prompt is open,
   and the last cost the statusline reported, preceded by the resolved work
   target (wraps `node dist/cli.js status`).
+- `/kankaku:task` — links this session to a hub task (wraps
+  `node dist/cli.js task`); see "Linking a task" below.
 - `/kankaku:setup` — prints the `statusLine` snippet described above (wraps
   `node dist/cli.js setup`).
 - `/kankaku:sync` — manually syncs recent local work records to the hub
@@ -222,7 +224,36 @@ crash recovery), never on the per-tool-call hooks. `/kankaku:status` and
 `/kankaku:doctor` print `target: <client> · <project> (source: ...)`, or
 `target: none (<reason>)`.
 
-There is nothing to pick inside Claude Code yet. Assignment is create-only
+### Linking a task
+
+`/kankaku:task` links the session to one hub task of the project resolved
+for the folder, so the records written from then on carry that task:
+
+- `/kankaku:task` lists the project's open tasks (status `open` or `doing`),
+  numbered, and marks the linked one; Claude then asks which one you want.
+- `/kankaku:task <number>` picks from the last list shown in this session,
+  `/kankaku:task <id>` by hub id, and `/kankaku:task <text>` by a unique
+  case-insensitive part of the title (several matches are listed and nothing
+  changes). A purely numeric argument is always a list number.
+- `/kankaku:task clear` removes the link.
+
+The link is session-only, like `/kankaku task pick` in pi: it is stored in
+`<KANKAKU_DIR>/claude/<session>.target.json`, never in `config.json`, and is
+removed when the session ends. The list refreshes the catalog first (bounded
+to 3 seconds) and falls back to the cache, saying how old it is; the hooks
+still only read the cache. A record keeps the link only while the task still
+belongs to the resolved project in the catalog; otherwise it is dropped and
+`/kankaku:status` and `/kankaku:doctor` print
+`task: none (linked task "<title>" is not in project <name>)`. Both print
+`task: <title>` or `task: none` otherwise.
+
+The CLI finds its session from its own process: it walks up to the Claude
+Code process and takes the session state of this project whose `pid` matches
+(most recent activity first). Without a session it prints
+`no active Claude Code session found for this folder`. Set
+`KANKAKU_CLAUDE_SESSION=<session id>` to name the session explicitly (tests,
+scripting); it wins over the process lookup. Overriding the client or project
+from Claude Code is not supported yet. Assignment is create-only
 on the hub: a row already uploaded as unassigned stays that way until it is
 reassigned in the web app; a later sync does not move it.
 

package/commands/task.md

@@ -0,0 +1,14 @@
+---
+description: Link this session to a hub task (list open tasks, pick one, or clear the link)
+argument-hint: [number | id | text | clear]
+allowed-tools: Bash(node:*)
+---
+
+Run the kankaku CLI task command and show its output to the user verbatim,
+inside a code block, with no summarizing or reformatting:
+
+!node "${CLAUDE_PLUGIN_ROOT}/dist/cli.js" task $ARGUMENTS
+
+If no argument was given and the output lists tasks, ask the user which one
+they want (by number), then run the same CLI command with that number and show
+its output verbatim in a code block. Never pick a task on the user's behalf.

package/dist/cli-core.js

@@ -1,4 +1,3 @@
-import { homedir } from "node:os";
 import { basename, join } from "node:path";
 import { JsonlWorkLog } from "kankaku/hub";
 import { listStateFiles, resolveKankakuDir } from "./paths.js";
@@ -7,8 +6,9 @@ import { readCost } from "./cost-store.js";
 import { formatReport } from "./report.js";
 import { runSyncCli } from "./sync-cli.js";
 import { runDoctor } from "./doctor.js";
-import { formatTargetLine, resolveClaudeWorkTarget } from "./work-target.js";
-const USAGE = "usage: node dist/cli.js <report|status|setup|sync|doctor> [--days N]\n";
+import { runTaskCli } from "./task-cli.js";
+import { formatTargetLine, formatTaskLine, resolveSessionWorkTarget } from "./work-target.js";
+const USAGE = "usage: node dist/cli.js <report|status|setup|sync|doctor|task> [--days N]\n";
 /** CLI commands, resolved from `deps.cwd`. */
 export async function runCli(argv, deps) {
     const [command, ...rest] = argv;
@@ -21,6 +21,8 @@ export async function runCli(argv, deps) {
             return runSetup(deps);
         case "sync":
             return runSyncCli(rest, deps);
+        case "task":
+            return runTaskCli(rest, deps);
         case "doctor":
             return { stdout: runDoctor(deps), exitCode: 0 };
         default:
@@ -45,7 +47,8 @@ function runStatus(deps) {
     const kankakuDir = resolveKankakuDir(deps.env.KANKAKU_DIR ?? ".kankaku", deps.cwd);
     const claudeDir = join(kankakuDir, "claude");
     const files = listStateFiles(claudeDir);
-    const targetLine = formatTargetLine(resolveClaudeWorkTarget({ cwd: deps.cwd, kankakuDir, homeDir: deps.env.HOME || homedir(), env: deps.env }));
+    const resolved = resolveSessionWorkTarget(deps);
+    const targetLine = `${formatTargetLine(resolved)}\n${formatTaskLine(resolved)}`;
     if (files.length === 0) {
         return { stdout: `${targetLine}\nNo active sessions.\n`, exitCode: 0 };
     }

package/dist/cli.js

@@ -1,7 +1,7 @@
 import { fileURLToPath } from "node:url";
 import { dirname } from "node:path";
 import { runCli } from "./cli-core.js";
-import { isAlive } from "./claude-pid.js";
+import { isAlive, runPsProcess } from "./claude-pid.js";
 // src/cli.ts -> src -> repo root (the directory that contains .claude-plugin/).
 const pluginRoot = dirname(dirname(fileURLToPath(import.meta.url)));
 const result = await runCli(process.argv.slice(2), {
@@ -10,6 +10,8 @@ const result = await runCli(process.argv.slice(2), {
     now: () => Date.now(),
     isAlive,
     pluginRoot,
+    pid: process.pid,
+    runPs: runPsProcess,
 });
 if (result.stdout)
     process.stdout.write(result.stdout);

package/dist/doctor.js

@@ -5,7 +5,7 @@ import { JsonlWorkLog, SyncStateStore, computeSyncStatus, resolveHubCredentials
 import { costDir } from "./cost-store.js";
 import { listStateFiles, resolveKankakuDir } from "./paths.js";
 import { readState } from "./session-state.js";
-import { formatTargetLine, resolveClaudeWorkTarget } from "./work-target.js";
+import { formatTargetLine, formatTaskLine, resolveSessionWorkTarget } from "./work-target.js";
 function metadata(file) {
     try {
         const value = JSON.parse(readFileSync(file, "utf8"));
@@ -23,6 +23,10 @@ function syncWindowHours(env) {
     const hours = Number(env.KANKAKU_SYNC_WINDOW_HOURS);
     return env.KANKAKU_SYNC_WINDOW_HOURS && Number.isFinite(hours) && hours > 0 ? hours : 24;
 }
+function workTargetLines(deps) {
+    const resolved = resolveSessionWorkTarget(deps);
+    return [formatTargetLine(resolved), formatTaskLine(resolved)];
+}
 /** Read-only, local diagnostic. No sync runner or network client is reachable from this path. */
 export function runDoctor(deps) {
     const dir = resolveKankakuDir(deps.env.KANKAKU_DIR ?? ".kankaku", deps.cwd);
@@ -65,7 +69,7 @@ export function runDoctor(deps) {
     const target = hub.credentials?.url ?? store.read()?.target ?? "";
     const { state, pending, staleOutsideWindow } = computeSyncStatus(log, store, target, syncWindowHours(deps.env));
     const hubState = hub.invalidReason ? "invalid URL" : hub.credentials ? "configured" : "unconfigured";
-    const commands = ["report", "status", "setup", "sync", "sync-status", "sync-all", "doctor"];
+    const commands = ["report", "status", "setup", "sync", "sync-status", "sync-all", "doctor", "task"];
     const present = commands.filter((name) => existsSync(join(deps.pluginRoot, "commands", `${name}.md`))).length;
     const actions = ["/kankaku:status", "/kankaku:sync-status"];
     if (!costsVisible)
@@ -90,7 +94,7 @@ export function runDoctor(deps) {
         `alive: ${alive}; dead: ${dead}; open prompts: ${open}; unreadable: ${unreadable}`,
         `cost files visible: ${costsVisible ? "yes" : "no"} (current HOME)`,
         "", "## Work target",
-        formatTargetLine(resolveClaudeWorkTarget({ cwd: deps.cwd, kankakuDir: dir, homeDir: deps.env.HOME || homedir(), env: deps.env })),
+        ...workTargetLines(deps),
         "", "## Hub / sync",
         `hub: ${hubState}`,
         `pending: ${pending}`,

package/dist/find-session.js

@@ -0,0 +1,43 @@
+import { statSync } from "node:fs";
+import { basename } from "node:path";
+import { resolveClaudePid } from "./claude-pid.js";
+import { readEventLog } from "./event-log.js";
+import { listStateFiles } from "./paths.js";
+import { readState } from "./session-state.js";
+const SESSION_ID = /^[\w.-]+$/;
+function activity(stateFile) {
+    let latest = 0;
+    try {
+        latest = statSync(stateFile).mtimeMs;
+    }
+    catch { /* unreadable: oldest */ }
+    const events = readEventLog(stateFile.replace(/\.state\.json$/, ".events.jsonl"));
+    const last = events[events.length - 1]?.ts;
+    return typeof last === "number" && last > latest ? last : latest;
+}
+/**
+ * The Claude Code session this CLI process runs under: `KANKAKU_CLAUDE_SESSION`
+ * (a plain session id) wins; otherwise the CLI's pid is walked up to the
+ * Claude process and matched against the project's session state files
+ * (`pid`), most recent activity first. `undefined` when nothing matches.
+ */
+export function findSession(input) {
+    const override = input.env.KANKAKU_CLAUDE_SESSION?.trim();
+    if (override && SESSION_ID.test(override))
+        return override;
+    if (input.pid === undefined || input.runPs === undefined)
+        return undefined;
+    const claudePid = resolveClaudePid({ startPid: input.pid, runPs: input.runPs });
+    if (!Number.isSafeInteger(claudePid) || claudePid <= 0)
+        return undefined;
+    const list = input.listStateFiles ?? listStateFiles;
+    let best;
+    for (const file of list(input.claudeDir)) {
+        if (readState(file)?.pid !== claudePid)
+            continue;
+        const at = activity(file);
+        if (!best || at > best.at)
+            best = { id: basename(file).replace(/\.state\.json$/, ""), at };
+    }
+    return best?.id;
+}

package/dist/handle-hook.js

@@ -136,7 +136,7 @@ async function handleStop(paths, sessionId, deps) {
     const core = replayPrompt(last, { cost: costDelta });
     if (core) {
         const assignment = await assignmentResolver(paths, deps);
-        const record = buildClaudeRecord(core, state, sessionId, cost?.model, assignment(state.cwd));
+        const record = buildClaudeRecord(core, state, sessionId, cost?.model, assignment(state.cwd, sessionId));
         const log = deps.log ?? new JsonlWorkLog(paths.kankakuDir);
         log.append(record);
     }
@@ -198,7 +198,7 @@ async function handleSessionEnd(paths, sessionId, cwd, ts, deps) {
             if (core) {
                 const model = readCost(deps.env, sessionId)?.model;
                 const assignment = await assignmentResolver(paths, deps);
-                const record = buildClaudeRecord(core, state, sessionId, model, assignment(state.cwd));
+                const record = buildClaudeRecord(core, state, sessionId, model, assignment(state.cwd, sessionId));
                 const log = deps.log ?? new JsonlWorkLog(paths.kankakuDir);
                 log.append(record);
             }
@@ -221,14 +221,21 @@ async function assignmentResolver(paths, deps) {
     try {
         const { resolveClaudeWorkTarget } = await import("./work-target.js");
         const { homedir } = await import("node:os");
+        const { readSessionTarget } = await import("./session-target-store.js");
+        const { resolveTargetFile } = await import("./paths.js");
         const resolve = deps.resolveTarget ?? resolveClaudeWorkTarget;
-        return (cwd) => {
+        return (cwd, sessionId) => {
             try {
+                // The session-only task link (`/kankaku:task`); heavy hooks only.
+                const stored = readSessionTarget(resolveTargetFile(paths.claudeDir, sessionId));
                 const { target, legacyClient } = resolve({
                     cwd,
                     kankakuDir: paths.kankakuDir,
                     homeDir: deps.env.HOME || homedir(),
                     env: deps.env,
+                    ...(stored?.hubTaskId !== undefined
+                        ? { taskLink: { hubTaskId: stored.hubTaskId, ...(stored.hubTaskTitle !== undefined ? { hubTaskTitle: stored.hubTaskTitle } : {}) } }
+                        : {}),
                 });
                 return {
                     ...(target !== undefined ? { target } : {}),
@@ -259,7 +266,7 @@ async function syncHeavy(trigger, cwd, deps) {
     }
 }
 function deleteSessionFiles(paths) {
-    for (const file of [paths.stateFile, paths.eventsFile]) {
+    for (const file of [paths.stateFile, paths.eventsFile, paths.targetFile]) {
         try {
             unlinkSync(file);
         }

package/dist/inflight-recovery.js

@@ -1,6 +1,6 @@
 import { unlinkSync } from "node:fs";
 import { basename } from "node:path";
-import { listStateFiles } from "./paths.js";
+import { listStateFiles, resolveTargetFile } from "./paths.js";
 import { readState } from "./session-state.js";
 import { readEventLog } from "./event-log.js";
 import { splitPrompts, replayPrompt } from "./replay.js";
@@ -26,9 +26,11 @@ export function recoverStaleSessions(input) {
             continue;
         const state = readState(stateFile);
         const eventsFile = stateFile.replace(/\.state\.json$/, ".events.jsonl");
+        const targetFile = resolveTargetFile(input.claudeDir, sessionId);
         if (!state) {
             safeUnlink(stateFile);
             safeUnlink(eventsFile);
+            safeUnlink(targetFile);
             continue;
         }
         const dead = state.pid <= 0 || !input.isAlive(state.pid);
@@ -47,12 +49,13 @@ export function recoverStaleSessions(input) {
                 const core = replayPrompt(last, { settledAt });
                 if (core) {
                     const model = readCost(input.env, sessionId)?.model;
-                    records.push(buildClaudeRecord(core, state, sessionId, model, input.resolveAssignment?.(state.cwd)));
+                    records.push(buildClaudeRecord(core, state, sessionId, model, input.resolveAssignment?.(state.cwd, sessionId)));
                 }
             }
         }
         safeUnlink(stateFile);
         safeUnlink(eventsFile);
+        safeUnlink(targetFile);
         deleteCost(input.env, sessionId);
     }
     return records;

package/dist/paths.js

@@ -18,6 +18,7 @@ export function resolvePaths(input) {
         claudeDir,
         eventsFile: join(claudeDir, `${input.sessionId}.events.jsonl`),
         stateFile: join(claudeDir, `${input.sessionId}.state.json`),
+        targetFile: resolveTargetFile(claudeDir, input.sessionId),
     };
 }
 /** Every `*.state.json` path in `claudeDir`, absolute. Empty array when the directory does not exist. */
@@ -33,3 +34,7 @@ export function listStateFiles(claudeDir) {
         .filter((name) => name.endsWith(".state.json"))
         .map((name) => join(claudeDir, name));
 }
+/** `<claudeDir>/<sessionId>.target.json`: the session-only task link (see `session-target-store.ts`). */
+export function resolveTargetFile(claudeDir, sessionId) {
+    return join(claudeDir, `${sessionId}.target.json`);
+}

package/dist/record.js

@@ -50,6 +50,8 @@ export function buildClaudeRecord(core, state, sessionId, model, assignment = {}
                 clientName: target.clientName,
                 ...(target.projectId !== undefined ? { projectId: target.projectId } : {}),
                 ...(target.projectName !== undefined ? { projectName: target.projectName } : {}),
+                ...(target.hubTaskId !== undefined ? { hubTaskId: target.hubTaskId } : {}),
+                ...(target.hubTaskId !== undefined && target.hubTaskTitle !== undefined ? { hubTaskTitle: target.hubTaskTitle } : {}),
             }
             : {}),
     };

package/dist/session-target-store.js

@@ -0,0 +1,39 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+function str(value) {
+    return typeof value === "string" && value !== "" ? value : undefined;
+}
+/** `undefined` when the file is absent or malformed. Extra or invalid fields are dropped. */
+export function readSessionTarget(file) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        return undefined;
+    const o = parsed;
+    if (o.hubTaskId !== undefined && typeof o.hubTaskId !== "string")
+        return undefined;
+    if (o.lastList !== undefined && !Array.isArray(o.lastList))
+        return undefined;
+    const hubTaskId = str(o.hubTaskId);
+    const hubTaskTitle = str(o.hubTaskTitle);
+    const projectId = str(o.projectId);
+    return {
+        ...(hubTaskId !== undefined ? { hubTaskId } : {}),
+        ...(hubTaskId !== undefined && hubTaskTitle !== undefined ? { hubTaskTitle } : {}),
+        ...(hubTaskId !== undefined && projectId !== undefined ? { projectId } : {}),
+        ...(hubTaskId !== undefined && typeof o.pickedAt === "number" ? { pickedAt: o.pickedAt } : {}),
+        lastList: (Array.isArray(o.lastList) ? o.lastList : []).filter((id) => typeof id === "string"),
+    };
+}
+/** Atomic tmp+rename write, creating parent directories as needed. */
+export function writeSessionTarget(file, link) {
+    mkdirSync(dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, JSON.stringify(link));
+    renameSync(tmp, file);
+}

package/dist/task-cli.js

@@ -0,0 +1,114 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { CachedCatalog, PocketBaseClient, createPocketBaseCatalogFetcher, resolveHubCredentials } from "kankaku/hub";
+import { findSession } from "./find-session.js";
+import { resolveKankakuDir, resolveTargetFile } from "./paths.js";
+import { readSessionTarget, writeSessionTarget } from "./session-target-store.js";
+import { listOpenTasks, selectTask } from "./task-select.js";
+import { resolveClaudeWorkTarget } from "./work-target.js";
+const DEFAULT_REFRESH_MS = 3000;
+const NO_SESSION = "no active Claude Code session found for this folder\n";
+const HINT = "pick one with: /kankaku:task <number>";
+const say = (lines, exitCode) => ({ stdout: lines.join("\n") + "\n", exitCode });
+/**
+ * `task [list | clear | <number> | <hub id> | <text>]`: links the hub task
+ * this Claude Code session is working on, session-only (see
+ * `session-target-store.ts`). Not a hook: it may use the network, bounded.
+ */
+export async function runTaskCli(args, deps) {
+    const kankakuDir = resolveKankakuDir(deps.env.KANKAKU_DIR ?? ".kankaku", deps.cwd);
+    const claudeDir = join(kankakuDir, "claude");
+    const session = findSession({
+        claudeDir,
+        env: deps.env,
+        ...(deps.pid !== undefined ? { pid: deps.pid } : {}),
+        ...(deps.runPs !== undefined ? { runPs: deps.runPs } : {}),
+    });
+    if (!session)
+        return { stdout: NO_SESSION, exitCode: 1 };
+    const file = resolveTargetFile(claudeDir, session);
+    const stored = readSessionTarget(file) ?? { lastList: [] };
+    const arg = args.join(" ").trim();
+    if (arg === "clear") {
+        if (stored.hubTaskId === undefined)
+            return say(["no task linked"], 0);
+        writeSessionTarget(file, { lastList: stored.lastList });
+        return say(["task link cleared"], 0);
+    }
+    const homeDir = deps.env.HOME || homedir();
+    const note = await refreshCatalog(deps, homeDir);
+    const prefix = note?.text ? [note.text] : [];
+    const resolved = resolveClaudeWorkTarget({ cwd: deps.cwd, kankakuDir, homeDir, env: deps.env });
+    const projectId = resolved.target?.projectId;
+    if (!resolved.target || projectId === undefined) {
+        const reason = resolved.reason ?? "the resolved client has no project";
+        return say([...prefix, `no project resolved for this folder (${reason}); a task belongs to a project`], 1);
+    }
+    const projectName = resolved.target.projectName ?? projectId;
+    const open = listOpenTasks(note?.tasks ?? [], projectId);
+    if (arg === "" || arg === "list") {
+        if (open.length === 0)
+            return say([...prefix, `no open tasks in project ${projectName}`], 0);
+        writeSessionTarget(file, { ...stored, lastList: open.map((task) => task.id) });
+        return say([...prefix, `open tasks in project ${projectName}:`, ...numbered(open, stored.hubTaskId), HINT], 0);
+    }
+    const selection = selectTask(arg, { open, lastList: stored.lastList });
+    if (selection.kind === "unknown")
+        return say([...prefix, selection.message], 1);
+    if (selection.kind === "ambiguous") {
+        writeSessionTarget(file, { ...stored, lastList: selection.candidates.map((task) => task.id) });
+        return say([...prefix, `several open tasks match "${arg}":`, ...numbered(selection.candidates, stored.hubTaskId), HINT], 1);
+    }
+    const task = selection.task;
+    writeSessionTarget(file, {
+        hubTaskId: task.id, hubTaskTitle: task.title, projectId, pickedAt: deps.now(), lastList: stored.lastList,
+    });
+    return say([...prefix, `linked: ${task.title}`], 0);
+}
+function numbered(tasks, linkedId) {
+    return tasks.map((task, index) => {
+        const ref = task.externalRef ? ` (${task.externalRef})` : "";
+        const linked = task.id === linkedId;
+        return `${linked ? "*" : " "} ${index + 1}. ${task.title}${ref}${linked ? " [linked]" : ""}`;
+    });
+}
+/**
+ * Best-effort refresh bounded by `catalogTimeoutMs`; on failure the cached
+ * snapshot is used and its age reported. `undefined` when there is neither
+ * credentials nor a cache (the project lookup then reports why).
+ */
+async function refreshCatalog(deps, homeDir) {
+    const hub = resolveHubCredentials({ env: deps.env, homeDir: () => homeDir });
+    if (!hub.credentials)
+        return undefined;
+    const client = new PocketBaseClient({ ...hub.credentials, ...(deps.fetch ? { fetch: deps.fetch } : {}) });
+    const catalog = new CachedCatalog({
+        filePath: join(homeDir, ".kankaku", "catalog.json"),
+        url: hub.credentials.url,
+        clock: { now: deps.now },
+        fetchCatalog: createPocketBaseCatalogFetcher(client),
+    });
+    const controller = new AbortController();
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => { controller.abort(); resolve(undefined); }, deps.catalogTimeoutMs ?? DEFAULT_REFRESH_MS);
+    });
+    const fresh = await Promise.race([catalog.refresh(controller.signal), timeout]);
+    clearTimeout(timer);
+    if (fresh)
+        return { tasks: fresh.tasks ?? [] };
+    const cached = catalog.read();
+    if (!cached)
+        return undefined;
+    return { tasks: cached.tasks ?? [], text: `catalog from cache, ${formatAge(deps.now() - cached.fetchedAt)} old` };
+}
+function formatAge(ms) {
+    const seconds = Math.max(0, Math.round(ms / 1000));
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m`;
+    const hours = Math.floor(minutes / 60);
+    return hours < 24 ? `${hours}h` : `${Math.floor(hours / 24)}d`;
+}

package/dist/task-select.js

@@ -0,0 +1,50 @@
+/**
+ * Pure task selection for `/kankaku:task`. Mirrors pi's picker
+ * (`adapters/target-picker.ts#pickHubTask`): a task is pickable when its
+ * status is not `done` (the hub's statuses are `open | doing | done`, see
+ * `HubTask` in `kankaku/domain`) and it belongs to the resolved project.
+ */
+export function isOpenTask(task) {
+    return task.status !== "done";
+}
+/** The project's open tasks, sorted by title (the order the list is numbered in). */
+export function listOpenTasks(tasks, projectId) {
+    return tasks
+        .filter((task) => task.projectId === projectId && isOpenTask(task))
+        .sort((a, b) => a.title.localeCompare(b.title));
+}
+/**
+ * `arg` is one of: a list number (a purely numeric argument is ALWAYS a
+ * number, never an id), a hub id, or a case-insensitive title substring
+ * that must match exactly one open task.
+ */
+export function selectTask(arg, ctx) {
+    const text = arg.trim();
+    if (text === "")
+        return { kind: "unknown", message: "no task given" };
+    if (/^-?\d+$/.test(text))
+        return selectByNumber(Number(text), ctx);
+    const byId = ctx.open.find((task) => task.id === text);
+    if (byId)
+        return { kind: "picked", task: byId };
+    const needle = text.toLowerCase();
+    const matches = ctx.open.filter((task) => task.title.toLowerCase().includes(needle));
+    if (matches.length === 1)
+        return { kind: "picked", task: matches[0] };
+    if (matches.length > 1)
+        return { kind: "ambiguous", candidates: matches };
+    return { kind: "unknown", message: `no open task matches "${text}"` };
+}
+function selectByNumber(n, ctx) {
+    if (ctx.lastList.length === 0) {
+        return { kind: "unknown", message: "no task list shown yet in this session; list the tasks first" };
+    }
+    if (!Number.isSafeInteger(n) || n < 1 || n > ctx.lastList.length) {
+        return { kind: "unknown", message: `${n} is not on the list (1-${ctx.lastList.length})` };
+    }
+    const id = ctx.lastList[n - 1];
+    const task = ctx.open.find((candidate) => candidate.id === id);
+    if (!task)
+        return { kind: "unknown", message: `task ${n} is no longer open; list the tasks again` };
+    return { kind: "picked", task };
+}

package/dist/work-target.js

@@ -1,6 +1,10 @@
+import { homedir } from "node:os";
 import { join } from "node:path";
 import { CachedCatalog, readProjectClient, readProjectTargetIds, resolveHubCredentials, } from "kankaku/hub";
 import { formatWorkTargetLabel, isValidClient, resolveClient, resolveWorkTarget, resolveWorkTargetSource, } from "kankaku/domain";
+import { findSession } from "./find-session.js";
+import { resolveKankakuDir, resolveTargetFile } from "./paths.js";
+import { readSessionTarget } from "./session-target-store.js";
 /**
  * Resolves the work target for a session, for record stamping and display.
  *
@@ -26,7 +30,12 @@ export function resolveClaudeWorkTarget(input) {
 function resolveUnsafe(input) {
     const projectClient = readProjectClient(input.kankakuDir);
     const legacyFallback = resolveClient({ env: input.env.KANKAKU_CLIENT, project: projectClient });
-    const withLegacy = (result) => legacyFallback !== undefined ? { ...result, legacyClient: legacyFallback } : result;
+    const link = input.taskLink;
+    const dropped = link !== undefined ? { droppedTask: { title: link.hubTaskTitle ?? link.hubTaskId } } : {};
+    const withLegacy = (result) => {
+        const base = result.target === undefined ? { ...result, ...dropped } : result;
+        return legacyFallback !== undefined ? { ...base, legacyClient: legacyFallback } : base;
+    };
     const snapshot = readCatalogCache(input);
     if (!snapshot)
         return withLegacy({ reason: "no catalog cache" });
@@ -43,9 +52,21 @@ function resolveUnsafe(input) {
     }
     // Mirrors the pi extension: with a hub target the legacy label is the
     // client's code, omitted when it is not a valid label.
+    // A linked task is validated by the library as the session source's task:
+    // same client and project as resolved above, so it can only ever add the
+    // task (kept when it belongs to that project and is still in the catalog).
+    const withTask = link !== undefined && target.projectId !== undefined
+        ? resolveWorkTarget({
+            ...resolveInput,
+            session: { clientId: target.clientId, projectId: target.projectId, hubTaskId: link.hubTaskId },
+            tasks: snapshot.tasks ?? [],
+        })
+        : undefined;
+    const finalTarget = withTask?.hubTaskId !== undefined ? withTask : target;
     return {
-        target,
+        target: finalTarget,
         source,
+        ...(link !== undefined && finalTarget.hubTaskId === undefined ? dropped : {}),
         ...(isValidClient(target.clientCode) ? { legacyClient: target.clientCode } : {}),
     };
 }
@@ -67,5 +88,36 @@ export function formatTargetLine(result) {
     if (!result.target)
         return `target: none (${result.reason ?? "unresolved"})`;
     const source = result.source === "project" ? "project config" : "repo_paths";
-    return `target: ${formatWorkTargetLabel(result.target)} (source: ${source})`;
+    // The task has its own line (see formatTaskLine); keep this one to client and project.
+    const { hubTaskId: _id, hubTaskTitle: _title, ...bare } = result.target;
+    return `target: ${formatWorkTargetLabel(bare)} (source: ${source})`;
+}
+/** The `task:` line printed by `/kankaku:status` and `/kankaku:doctor`. */
+export function formatTaskLine(result) {
+    if (result.target?.hubTaskTitle !== undefined)
+        return `task: ${result.target.hubTaskTitle}`;
+    if (result.droppedTask === undefined)
+        return "task: none";
+    const where = result.target?.projectName !== undefined ? `is not in project ${result.target.projectName}` : "needs a project";
+    return `task: none (linked task "${result.droppedTask.title}" ${where})`;
+}
+/**
+ * The work target for display (`status`, `doctor`): the folder's target plus
+ * the task linked by the session this process runs under, when one is found.
+ */
+export function resolveSessionWorkTarget(deps) {
+    const kankakuDir = resolveKankakuDir(deps.env.KANKAKU_DIR ?? ".kankaku", deps.cwd);
+    const claudeDir = join(kankakuDir, "claude");
+    const session = findSession({
+        claudeDir, env: deps.env,
+        ...(deps.pid !== undefined ? { pid: deps.pid } : {}),
+        ...(deps.runPs !== undefined ? { runPs: deps.runPs } : {}),
+    });
+    const stored = session !== undefined ? readSessionTarget(resolveTargetFile(claudeDir, session)) : undefined;
+    return resolveClaudeWorkTarget({
+        cwd: deps.cwd, kankakuDir, homeDir: deps.env.HOME || homedir(), env: deps.env,
+        ...(stored?.hubTaskId !== undefined
+            ? { taskLink: { hubTaskId: stored.hubTaskId, ...(stored.hubTaskTitle !== undefined ? { hubTaskTitle: stored.hubTaskTitle } : {}) } }
+            : {}),
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kankaku-claude",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Claude Code plugin that records how long the agent works on each user prompt, in kankaku's worklog format.",
   "type": "module",
   "files": [
@@ -27,7 +27,7 @@
     "prepublishOnly": "npm run check"
   },
   "dependencies": {
-    "kankaku": "^0.11.0"
+    "kankaku": "^0.12.0"
   },
   "devDependencies": {
     "@types/node": "^24.13.4",