kankaku-claude 1.3.0 → 1.4.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": "1.3.0",
+  "version": "1.4.0",
   "author": {
     "name": "soyunninja"
   },

package/CHANGELOG.md

@@ -4,6 +4,26 @@ 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/).
 
+## 1.4.0 — 2026-09-30
+
+### Added
+
+- **`/kankaku:target`.** Chooses the client and project a Claude Code session
+  works for, from inside the session: with no argument it prints the current
+  target and its source and the active clients numbered; `<number | code |
+  text>` picks a client and lists its projects, a following pick sets the
+  project, `<client> <project>` sets both, and `clear` returns to the
+  automatic resolution. The pick is session-only (stored next to the task
+  link, never in `config.json`) and wins over the project config and
+  `repo_paths` when records are written; `/kankaku:status` and
+  `/kankaku:doctor` show `source: session`. Changing the project drops the
+  task link unless the linked task belongs to the new project.
+
+## 1.3.1 — 2026-09-30
+
+No changes in this package; released in lockstep with kankaku-pi and
+kankaku 1.3.1.
+
 ## 1.3.0 — 2026-09-29
 
 ### Added

package/README.md

@@ -153,6 +153,9 @@ anything behind in whatever project happens to be open.
   session upgraded mid-way, or resumed without its state) — no later
   prompt carries that part.
   The resolved work target comes first (wraps `node dist/cli.js status`).
+- `/kankaku:target` — chooses the client and project this session works
+  for (wraps `node dist/cli.js target`); see "Choosing the client and
+  project for a session" below.
 - `/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
@@ -215,9 +218,10 @@ Each record is stamped with a hub client and project when one resolves, so
 the hub files the task under the right client instead of "Sin determinar".
 Sources, in order:
 
-1. the project's `<KANKAKU_DIR>/config.json` ids (`clientId`, optional
+1. the session's own pick, made with `/kankaku:target` (see below);
+2. the project's `<KANKAKU_DIR>/config.json` ids (`clientId`, optional
    `projectId`);
-2. the cached catalog's `repo_paths`: the active project whose path equals
+3. the cached catalog's `repo_paths`: the active project whose path equals
    the session's working directory, or contains it.
 
 Inactive clients and projects, and the "unassigned" client, are never used.
@@ -235,6 +239,53 @@ crash recovery), never on the per-tool-call hooks. `/kankaku:status` and
 `/kankaku:doctor` print `target: <client> · <project> (source: ...)`, or
 `target: none (<reason>)`.
 
+### Choosing the client and project for a session
+
+`/kankaku:target` picks the client and project the records of this session
+are filed under, for the cases where the folder does not say (or says the
+wrong thing):
+
+- `/kankaku:target` prints the current target and its source (`session`,
+  `project config` or `repo_paths`), then the active clients numbered;
+  Claude then asks which one you want. The unassigned client is never
+  listed.
+- `/kankaku:target <number | code | text>` picks a client: from the last
+  list shown in this session (a purely numeric argument is always a list
+  number), by client code (exact, case-insensitive), or by a unique
+  case-insensitive part of its name. It prints `client set to <Client>` and
+  that client's active projects numbered. A following
+  `/kankaku:target <number | code | text>` that matches one of those
+  projects sets the project (`target set to <Client> · <Project>`).
+- `/kankaku:target <client> <project>` sets both at once; the project must
+  belong to the client, otherwise nothing changes.
+- `/kankaku:target clear` removes the pick and prints what the automatic
+  resolution gives now.
+
+Text that matches nothing, or several entries, changes nothing (several are
+listed so one can be picked by number). Inactive entries are never
+selectable.
+
+The pick is session-only, like `/kankaku target pick|clear` in pi: it is
+stored in `<KANKAKU_DIR>/claude/<session>.target.json` next to the task
+link, removed when the session ends, and **`config.json` is never written**.
+For a permanent choice use `kankaku setup` or the project's `config.json`.
+Precedence at record time is the library's: session pick, then `config.json`,
+then `repo_paths`; a picked client or project that is no longer active in
+the catalog falls through to the next source. Records carry the picked
+client and project (`clientId`, `clientName`, `projectId`, `projectName`,
+and the legacy `client` label = the client code when it is a valid label),
+and `/kankaku:status` and `/kankaku:doctor` print `(source: session)`.
+
+Changing or clearing the client or project also decides the task link: it is
+kept only when the linked task belongs to the resulting project, and the
+command says which happened (`task link kept`, or `task link dropped
+(<title> is not in <Project>)`). Picking only a client always drops it,
+since no project is chosen yet. `/kankaku:task` lists the tasks of the
+resulting project. Listing and picking refresh the catalog first (bounded to
+3 seconds) and fall back to the cache (`catalog from cache, <age> old`);
+without a cache and without a hub the command says `no catalog` and exits
+with 1.
+
 ### Linking a task
 
 `/kankaku:task` links the session to one hub task of the project resolved

package/commands/target.md

@@ -0,0 +1,19 @@
+---
+description: Choose the client and project this session works for (list clients, pick one, or clear)
+argument-hint: [number | code | text] [project] | clear
+allowed-tools: Bash(node:*)
+---
+
+Run the kankaku CLI target 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" target $ARGUMENTS
+
+If the output lists clients or projects, 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 client or a project on the user's behalf.
+
+The choice lasts for this session only: it does not change the project's
+`config.json`.

package/dist/catalog-refresh.js

@@ -0,0 +1,44 @@
+import { join } from "node:path";
+import { CachedCatalog, PocketBaseClient, createPocketBaseCatalogFetcher, resolveHubCredentials } from "kankaku-pi/hub";
+const DEFAULT_REFRESH_MS = 3000;
+/**
+ * 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 caller then reports why). CLI commands only:
+ * the hooks never call this.
+ */
+export 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 { snapshot: fresh };
+    const cached = catalog.read();
+    if (!cached)
+        return undefined;
+    return { snapshot: cached, 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/cli-core.js

@@ -7,8 +7,9 @@ import { formatReport } from "./report.js";
 import { runSyncCli } from "./sync-cli.js";
 import { runDoctor } from "./doctor.js";
 import { runTaskCli } from "./task-cli.js";
+import { runTargetCli } from "./target-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";
+const USAGE = "usage: node dist/cli.js <report|status|setup|sync|doctor|task|target> [--days N]\n";
 /** CLI commands, resolved from `deps.cwd`. */
 export async function runCli(argv, deps) {
     const [command, ...rest] = argv;
@@ -23,6 +24,8 @@ export async function runCli(argv, deps) {
             return runSyncCli(rest, deps);
         case "task":
             return runTaskCli(rest, deps);
+        case "target":
+            return runTargetCli(rest, deps);
         case "doctor":
             return { stdout: runDoctor(deps), exitCode: 0 };
         default:

package/dist/doctor.js

@@ -69,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", "task"];
+    const commands = ["report", "status", "setup", "sync", "sync-status", "sync-all", "doctor", "task", "target"];
     const present = commands.filter((name) => existsSync(join(deps.pluginRoot, "commands", `${name}.md`))).length;
     const actions = ["/kankaku:status", "/kankaku:sync-status"];
     if (!costsVisible)

package/dist/handle-hook.js

@@ -301,21 +301,19 @@ 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 { readSessionTarget, sessionInputs } = await import("./session-target-store.js");
         const { resolveTargetFile } = await import("./paths.js");
         const resolve = deps.resolveTarget ?? resolveClaudeWorkTarget;
         return (cwd, sessionId) => {
             try {
-                // The session-only task link (`/kankaku:task`); heavy hooks only.
+                // The session-only target and task link (`/kankaku:target`, `/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 } : {}) } }
-                        : {}),
+                    ...(stored !== undefined ? sessionInputs(stored) : {}),
                 });
                 return {
                     ...(target !== undefined ? { target } : {}),

package/dist/session-target-store.js

@@ -1,8 +1,25 @@
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
+const LIST_KINDS = ["clients", "projects", "tasks"];
 function str(value) {
     return typeof value === "string" && value !== "" ? value : undefined;
 }
+function strings(value) {
+    return value.filter((id) => typeof id === "string");
+}
+/** A plain array is the pre-`target` format: the ids of a task list. `undefined` when malformed. */
+function readList(value) {
+    if (value === undefined)
+        return { kind: "tasks", ids: [] };
+    if (Array.isArray(value))
+        return { kind: "tasks", ids: strings(value) };
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const { kind, ids } = value;
+    if (typeof kind !== "string" || !LIST_KINDS.includes(kind) || !Array.isArray(ids))
+        return undefined;
+    return { kind: kind, ids: strings(ids) };
+}
 /** `undefined` when the file is absent or malformed. Extra or invalid fields are dropped. */
 export function readSessionTarget(file) {
     let parsed;
@@ -15,21 +32,43 @@ export function readSessionTarget(file) {
     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))
+    for (const key of ["hubTaskId", "clientId", "projectId"]) {
+        if (o[key] !== undefined && typeof o[key] !== "string")
+            return undefined;
+    }
+    const lastList = readList(o.lastList);
+    if (lastList === undefined)
         return undefined;
     const hubTaskId = str(o.hubTaskId);
     const hubTaskTitle = str(o.hubTaskTitle);
-    const projectId = str(o.projectId);
+    const clientId = str(o.clientId);
+    const projectId = hubTaskId !== undefined || clientId !== undefined ? str(o.projectId) : undefined;
     return {
+        ...(clientId !== undefined ? { clientId } : {}),
+        ...(clientId !== undefined && typeof o.pickedTargetAt === "number" ? { pickedTargetAt: o.pickedTargetAt } : {}),
         ...(hubTaskId !== undefined ? { hubTaskId } : {}),
         ...(hubTaskId !== undefined && hubTaskTitle !== undefined ? { hubTaskTitle } : {}),
-        ...(hubTaskId !== undefined && projectId !== undefined ? { projectId } : {}),
+        ...(projectId !== undefined ? { projectId } : {}),
         ...(hubTaskId !== undefined && typeof o.pickedAt === "number" ? { pickedAt: o.pickedAt } : {}),
-        lastList: (Array.isArray(o.lastList) ? o.lastList : []).filter((id) => typeof id === "string"),
+        lastList,
     };
 }
+/** What the work-target resolution takes from a session's file: the `/kankaku:target` pick and the task link. */
+export function sessionInputs(link) {
+    return {
+        ...(link.clientId !== undefined
+            ? { sessionTarget: { clientId: link.clientId, ...(link.projectId !== undefined ? { projectId: link.projectId } : {}) } }
+            : {}),
+        ...(link.hubTaskId !== undefined
+            ? { taskLink: { hubTaskId: link.hubTaskId, ...(link.hubTaskTitle !== undefined ? { hubTaskTitle: link.hubTaskTitle } : {}) } }
+            : {}),
+    };
+}
+/** The same file content without the task link (the target and the list are kept). */
+export function withoutTaskLink(link) {
+    const { hubTaskId: _id, hubTaskTitle: _title, pickedAt: _at, projectId, ...rest } = link;
+    return { ...rest, ...(link.clientId !== undefined && projectId !== undefined ? { projectId } : {}) };
+}
 /** Atomic tmp+rename write, creating parent directories as needed. */
 export function writeSessionTarget(file, link) {
     mkdirSync(dirname(file), { recursive: true });

package/dist/target-cli.js

@@ -0,0 +1,119 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { refreshCatalog } from "./catalog-refresh.js";
+import { findSession } from "./find-session.js";
+import { resolveKankakuDir, resolveTargetFile } from "./paths.js";
+import { readSessionTarget, sessionInputs, withoutTaskLink, writeSessionTarget } from "./session-target-store.js";
+import { activeClients, activeProjects, pickBoth, pickTarget, taskLinkOutcome } from "./target-select.js";
+import { formatTargetLine, resolveClaudeWorkTarget } from "./work-target.js";
+const NO_SESSION = "no active Claude Code session found for this folder\n";
+const NO_CATALOG = "no catalog: configure the hub or run kankaku catalog refresh";
+const HINT = "pick one with: /kankaku:target <number>";
+const EMPTY_LIST = { kind: "tasks", ids: [] };
+const say = (lines, exitCode) => ({ stdout: lines.join("\n") + "\n", exitCode });
+/**
+ * `target [<number | code | text> [<project>] | clear]`: picks the client
+ * and project this Claude Code session works for, session-only (see
+ * `session-target-store.ts`); it never touches the project's `config.json`.
+ * Not a hook: it may use the network, bounded, like `task`.
+ */
+export async function runTargetCli(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: EMPTY_LIST };
+    const words = args.map((word) => word.trim()).filter((word) => word !== "");
+    const homeDir = deps.env.HOME || homedir();
+    const catalog = await refreshCatalog(deps, homeDir);
+    const prefix = catalog?.text ? [catalog.text] : [];
+    const resolve = (sessionTarget) => resolveClaudeWorkTarget({ cwd: deps.cwd, kankakuDir, homeDir, env: deps.env, ...(sessionTarget ? { sessionTarget } : {}) });
+    if (words.length === 1 && words[0].toLowerCase() === "clear") {
+        return clear({ file, stored, prefix, tasks: catalog?.snapshot.tasks ?? [], automatic: resolve() });
+    }
+    if (!catalog)
+        return say([NO_CATALOG], 1);
+    const { clients, projects, tasks = [] } = catalog.snapshot;
+    const link = sessionInputs(stored).taskLink;
+    const ctx = {
+        clients, projects, lastList: stored.lastList, ...(stored.clientId !== undefined ? { clientId: stored.clientId } : {}),
+    };
+    if (words.length === 0) {
+        const shown = activeClients(clients);
+        writeSessionTarget(file, { ...stored, lastList: { kind: "clients", ids: shown.map((client) => client.id) } });
+        const current = formatTargetLine(resolve(sessionInputs(stored).sessionTarget));
+        return say([...prefix, current, ...(shown.length > 0 ? [...clientLines(shown), HINT] : ["no active clients"])], 0);
+    }
+    const pick = choose(words, ctx);
+    if (pick.kind === "unknown")
+        return say([...prefix, pick.message], 1);
+    if (pick.kind === "ambiguous") {
+        const isClients = pick.of === "clients";
+        writeSessionTarget(file, { ...stored, lastList: { kind: pick.of, ids: pick.candidates.map((entry) => entry.id) } });
+        const shown = isClients ? clientLines(pick.candidates) : projectLines(pick.candidates);
+        const owner = clients.find((client) => client.id === stored.clientId);
+        const what = isClients || owner === undefined ? pick.of : `${pick.of} of ${owner.name}`;
+        return say([...prefix, `several ${what} match "${words.join(" ")}":`, ...shown, HINT], 1);
+    }
+    const now = deps.now();
+    if (pick.kind === "client") {
+        const outcome = taskLinkOutcome(link, tasks, undefined);
+        const shown = activeProjects(projects, pick.client.id);
+        const { projectId: _project, ...rest } = stored.hubTaskId !== undefined ? withoutTaskLink(stored) : stored;
+        writeSessionTarget(file, {
+            ...rest, clientId: pick.client.id, pickedTargetAt: now, lastList: { kind: "projects", ids: shown.map((project) => project.id) },
+        });
+        return say([
+            ...prefix, `client set to ${pick.client.name}`, ...(outcome ? [outcome.message] : []),
+            ...(shown.length > 0 ? [...projectLines(shown), HINT] : ["no active projects"]),
+        ], 0);
+    }
+    const client = pick.kind === "both" ? pick.client : clients.find((entry) => entry.id === stored.clientId);
+    const outcome = taskLinkOutcome(link, tasks, pick.project);
+    const base = outcome?.keep === false ? withoutTaskLink(stored) : stored;
+    writeSessionTarget(file, {
+        ...base, clientId: client.id, projectId: pick.project.id, pickedTargetAt: now,
+        lastList: pick.kind === "both" ? EMPTY_LIST : stored.lastList,
+    });
+    return say([...prefix, `target set to ${client.name} · ${pick.project.name}`, ...(outcome ? [outcome.message] : [])], 0);
+}
+/**
+ * One word is `pickTarget`'s. Several words are `<client> <project>` (see
+ * `pickBoth`); when that finds nothing they may still be one multi-word name
+ * ("Acme Corp"), which is then tried as a whole.
+ */
+function choose(words, ctx) {
+    if (words.length === 1)
+        return pickTarget(words[0], ctx);
+    const both = pickBoth(words, ctx);
+    if (both.kind !== "unknown")
+        return both;
+    const whole = pickTarget(words.join(" "), ctx);
+    return whole.kind === "client" || whole.kind === "project" ? whole : both;
+}
+function clear({ file, stored, prefix, tasks, automatic }) {
+    if (stored.clientId === undefined)
+        return say([...prefix, "no session target to clear"], 0);
+    const project = automatic.target?.projectId !== undefined
+        ? { id: automatic.target.projectId, name: automatic.target.projectName ?? automatic.target.projectId }
+        : undefined;
+    const outcome = taskLinkOutcome(sessionInputs(stored).taskLink, tasks, project);
+    const { clientId: _client, pickedTargetAt: _at, projectId: _project, ...rest } = stored;
+    const kept = outcome?.keep === true && project !== undefined ? { ...rest, projectId: project.id } : withoutTaskLink(rest);
+    writeSessionTarget(file, { ...kept, lastList: EMPTY_LIST });
+    const back = automatic.target !== undefined ? formatTargetLine(automatic).replace(/^target: /, "") : `none (${automatic.reason ?? "unresolved"})`;
+    return say([...prefix, `target cleared for this session; back to ${back}`, ...(outcome ? [outcome.message] : [])], 0);
+}
+function clientLines(clients) {
+    return clients.map((client, index) => `  ${index + 1}. ${client.name} (${client.code})`);
+}
+function projectLines(projects) {
+    return projects.map((project, index) => `  ${index + 1}. ${project.name}${project.code ? ` (${project.code})` : ""}`);
+}

package/dist/target-select.js

@@ -0,0 +1,150 @@
+/**
+ * Pure selection logic for `/kankaku:target`. Only active entries are ever
+ * selectable, and a client flagged `unassigned` never is. A numeric argument
+ * is ALWAYS a number on the last list printed for the session (the same rule
+ * as `task-select.ts`), never a code or a name.
+ */
+export function activeClients(clients) {
+    return clients.filter((client) => client.active && client.unassigned !== true).sort(byName);
+}
+/** The client's active projects, by name (the order the list is numbered in). */
+export function activeProjects(projects, clientId) {
+    return projects.filter((project) => project.active && project.clientId === clientId).sort(byName);
+}
+function byName(a, b) {
+    return a.name.localeCompare(b.name);
+}
+const NUMBER = /^-?\d+$/;
+/** Exact code, else exact name, else a unique case-insensitive name substring; all case-insensitive. */
+function match(text, entries) {
+    const needle = text.toLowerCase();
+    const stages = [
+        entries.filter((entry) => entry.code?.toLowerCase() === needle),
+        entries.filter((entry) => entry.name.toLowerCase() === needle),
+        entries.filter((entry) => entry.name.toLowerCase().includes(needle)),
+    ];
+    for (const found of stages) {
+        if (found.length === 1)
+            return { kind: "picked", item: found[0] };
+        if (found.length > 1)
+            return { kind: "ambiguous", candidates: found };
+    }
+    return { kind: "none" };
+}
+function usableClient(clients, id) {
+    return activeClients(clients).find((client) => client.id === id);
+}
+function unknown(message) {
+    return { kind: "unknown", message };
+}
+/** A number on the last list, checked against the kind wanted and against the entries still eligible. */
+function byNumber(n, wanted, list, eligible) {
+    if (list.ids.length === 0)
+        return { message: `no ${wanted.slice(0, -1)} list shown yet in this session; list the ${wanted} first` };
+    if (list.kind !== wanted) {
+        return { message: `the last list shown was ${list.kind}, not ${wanted}; list the ${wanted} first` };
+    }
+    if (!Number.isSafeInteger(n) || n < 1 || n > list.ids.length)
+        return { message: `${n} is not on the list (1-${list.ids.length})` };
+    const item = eligible.find((entry) => entry.id === list.ids[n - 1]);
+    return item ? { item } : { message: `${wanted.slice(0, -1)} ${n} is no longer available; list the ${wanted} again` };
+}
+function pickClient(text, ctx) {
+    const clients = activeClients(ctx.clients);
+    if (NUMBER.test(text)) {
+        const r = byNumber(Number(text), "clients", ctx.lastList, clients);
+        return "item" in r ? { kind: "client", client: r.item } : unknown(r.message);
+    }
+    const m = match(text, clients);
+    if (m.kind === "picked")
+        return { kind: "client", client: m.item };
+    if (m.kind === "ambiguous")
+        return { kind: "ambiguous", of: "clients", candidates: m.candidates };
+    return unknown(`no client matches "${text}"`);
+}
+/**
+ * One argument of `target <arg>`. With a projects list on screen (and the
+ * session client still eligible) a number can only mean one of THOSE
+ * projects, and text is tried against them first, then against the clients.
+ */
+export function pickTarget(arg, ctx) {
+    const text = arg.trim();
+    if (text === "")
+        return unknown("no client given");
+    const sessionClient = ctx.clientId !== undefined ? usableClient(ctx.clients, ctx.clientId) : undefined;
+    if (ctx.lastList.kind !== "projects" || sessionClient === undefined)
+        return pickClient(text, ctx);
+    const projects = activeProjects(ctx.projects, sessionClient.id);
+    if (NUMBER.test(text)) {
+        const r = byNumber(Number(text), "projects", ctx.lastList, projects);
+        return "item" in r ? { kind: "project", project: r.item } : unknown(r.message);
+    }
+    const m = match(text, projects);
+    if (m.kind === "picked")
+        return { kind: "project", project: m.item };
+    if (m.kind === "ambiguous")
+        return { kind: "ambiguous", of: "projects", candidates: m.candidates };
+    const client = pickClient(text, ctx);
+    return client.kind === "unknown" ? unknown(`no project of ${sessionClient.name} or client matches "${text}"`) : client;
+}
+function pickProjectOf(client, text, ctx) {
+    if (NUMBER.test(text))
+        return unknown(`a project is given by code or name here, not by number: "${text}"`);
+    const m = match(text, activeProjects(ctx.projects, client.id));
+    if (m.kind === "picked")
+        return { kind: "project", project: m.item };
+    if (m.kind === "ambiguous")
+        return { kind: "ambiguous", of: "projects", candidates: m.candidates };
+    const others = ctx.projects.filter((project) => project.clientId !== client.id && usableClient(ctx.clients, project.clientId));
+    const other = match(text, others);
+    const owner = other.kind === "picked" ? usableClient(ctx.clients, other.item.clientId) : undefined;
+    if (other.kind === "picked" && owner)
+        return unknown(`${other.item.name} belongs to ${owner.name}, not ${client.name}`);
+    return unknown(`no project of ${client.name} matches "${text}"`);
+}
+/**
+ * `target <client> <project>`: the arguments are split at every position
+ * (a name can hold spaces); exactly one split must yield a client and one
+ * of ITS projects. A number can name the client (from the clients list) but
+ * never the project.
+ */
+export function pickBoth(args, ctx) {
+    if (args.length < 2)
+        return unknown("give a client and a project");
+    const successes = [];
+    let failure;
+    let clientFailure;
+    for (let i = 1; i < args.length; i++) {
+        const client = pickClient(args.slice(0, i).join(" "), ctx);
+        if (client.kind !== "client") {
+            clientFailure ??= client;
+            continue;
+        }
+        const project = pickProjectOf(client.client, args.slice(i).join(" "), ctx);
+        if (project.kind === "project")
+            successes.push({ client: client.client, project: project.project });
+        else
+            failure ??= project;
+    }
+    if (successes.length === 1)
+        return { kind: "both", ...successes[0] };
+    if (successes.length > 1)
+        return unknown(`"${args.join(" ")}" can be split into a client and a project in more than one way; use the client code`);
+    return failure ?? clientFailure ?? unknown("give a client and a project");
+}
+/**
+ * The task-link rule for any change of the session target: the link
+ * survives only when the linked task belongs to the resulting project.
+ * `undefined` when there is no link to decide about.
+ */
+export function taskLinkOutcome(link, tasks, project) {
+    if (link === undefined)
+        return undefined;
+    const title = link.hubTaskTitle ?? link.hubTaskId;
+    if (project === undefined)
+        return { keep: false, message: `task link dropped (${title} needs a project)` };
+    const task = tasks.find((candidate) => candidate.id === link.hubTaskId);
+    if (task?.projectId === project.id)
+        return { keep: true, message: "task link kept" };
+    return { keep: false, message: `task link dropped (${title} is not in ${project.name})` };
+}

package/dist/task-cli.js

@@ -1,12 +1,11 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { CachedCatalog, PocketBaseClient, createPocketBaseCatalogFetcher, resolveHubCredentials } from "kankaku-pi/hub";
+import { refreshCatalog } from "./catalog-refresh.js";
 import { findSession } from "./find-session.js";
 import { resolveKankakuDir, resolveTargetFile } from "./paths.js";
-import { readSessionTarget, writeSessionTarget } from "./session-target-store.js";
+import { readSessionTarget, sessionInputs, withoutTaskLink, 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 });
@@ -27,41 +26,46 @@ export async function runTaskCli(args, deps) {
     if (!session)
         return { stdout: NO_SESSION, exitCode: 1 };
     const file = resolveTargetFile(claudeDir, session);
-    const stored = readSessionTarget(file) ?? { lastList: [] };
+    const stored = readSessionTarget(file) ?? { lastList: { kind: "tasks", ids: [] } };
     const arg = args.join(" ").trim();
     if (arg === "clear") {
         if (stored.hubTaskId === undefined)
             return say(["no task linked"], 0);
-        writeSessionTarget(file, { lastList: stored.lastList });
+        writeSessionTarget(file, withoutTaskLink(stored));
         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 tasks = note?.snapshot.tasks ?? [];
+    const shownIds = stored.lastList.kind === "tasks" ? stored.lastList.ids : [];
+    const { sessionTarget } = sessionInputs(stored);
+    const resolved = resolveClaudeWorkTarget({
+        cwd: deps.cwd, kankakuDir, homeDir, env: deps.env, ...(sessionTarget !== undefined ? { sessionTarget } : {}),
+    });
     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);
+    const open = listOpenTasks(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) });
+        writeSessionTarget(file, { ...stored, lastList: { kind: "tasks", ids: 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 });
+    const selection = selectTask(arg, { open, lastList: shownIds });
     if (selection.kind === "unknown")
         return say([...prefix, selection.message], 1);
     if (selection.kind === "ambiguous") {
-        writeSessionTarget(file, { ...stored, lastList: selection.candidates.map((task) => task.id) });
+        writeSessionTarget(file, { ...stored, lastList: { kind: "tasks", ids: 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,
+        ...stored, hubTaskId: task.id, hubTaskTitle: task.title, projectId, pickedAt: deps.now(),
     });
     return say([...prefix, `linked: ${task.title}`], 0);
 }
@@ -72,43 +76,3 @@ function numbered(tasks, 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/work-target.js

@@ -4,11 +4,12 @@ import { CachedCatalog, readProjectClient, readProjectTargetIds, resolveHubCrede
 import { formatWorkTargetLabel, isValidClient, resolveClient, resolveWorkTarget, resolveWorkTargetSource, } from "kankaku-pi/domain";
 import { findSession } from "./find-session.js";
 import { resolveKankakuDir, resolveTargetFile } from "./paths.js";
-import { readSessionTarget } from "./session-target-store.js";
+import { readSessionTarget, sessionInputs } from "./session-target-store.js";
 /**
  * Resolves the work target for a session, for record stamping and display.
  *
- * Sources, in order: the project's `config.json` ids, then the cached
+ * Sources, in order: the session's `/kankaku:target` pick, the project's
+ * `config.json` ids, then the cached
  * catalog's `repo_paths` match for `cwd`. The catalog comes only from the
  * cache file that every real sync refreshes — there is no fetch, no refresh
  * and no network here, and nothing throws: an unusable cache means "no
@@ -40,6 +41,7 @@ function resolveUnsafe(input) {
     if (!snapshot)
         return withLegacy({ reason: "no catalog cache" });
     const resolveInput = {
+        ...(input.sessionTarget !== undefined ? { session: input.sessionTarget } : {}),
         project: readProjectTargetIds(input.kankakuDir),
         cwd: input.cwd,
         clients: snapshot.clients,
@@ -47,7 +49,7 @@ function resolveUnsafe(input) {
     };
     const target = resolveWorkTarget(resolveInput);
     const source = resolveWorkTargetSource(resolveInput);
-    if (!target || (source !== "project" && source !== "repoPaths")) {
+    if (!target || source === undefined) {
         return withLegacy({ reason: `no match for ${input.cwd}` });
     }
     // Mirrors the pi extension: with a hub target the legacy label is the
@@ -87,7 +89,7 @@ function readCatalogCache(input) {
 export function formatTargetLine(result) {
     if (!result.target)
         return `target: none (${result.reason ?? "unresolved"})`;
-    const source = result.source === "project" ? "project config" : "repo_paths";
+    const source = result.source === "session" ? "session" : result.source === "project" ? "project config" : "repo_paths";
     // 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})`;
@@ -116,8 +118,6 @@ export function resolveSessionWorkTarget(deps) {
     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 } : {}) } }
-            : {}),
+        ...(stored !== undefined ? sessionInputs(stored) : {}),
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kankaku-claude",
-  "version": "1.3.0",
+  "version": "1.4.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-pi": "^1.3.0"
+    "kankaku-pi": "^1.4.0"
   },
   "devDependencies": {
     "@types/node": "^24.13.4",