kankaku 0.4.6 → 0.5.0

package/src/adapters/process-identity.ts

@@ -0,0 +1,162 @@
+import { detectRole, readRoleOverride, stripRoleOverride } from "../config.ts";
+import type { RoleOverride } from "../config.ts";
+import { resolveOrchestratorRef } from "../domain/ancestry-match.ts";
+import type { OrchestratorRef } from "../domain/work-record.ts";
+import { GENTLE_PI_PROFILE, builtinChildMarkers, configuredChildMarkers, matchesAnyMarker, resolveChildProfile } from "../domain/subagent-profile.ts";
+import type { SubagentProfile } from "../domain/subagent-profile.ts";
+import type { ProcessRegistry, RegistryEntry } from "../ports/process-registry.ts";
+import { resolveSubagentStartup } from "./subagent-startup.ts";
+import type { AncestrySnapshot } from "./ancestry.ts";
+
+/** `resolveProcessIdentity`'s default `subagentProfiles` when a caller does not pass its own active profile set: exactly gentle-pi's own marker, matching this module's behaviour before SUBAGENT-REQ-001/002/003 existed — so a caller that has not opted into the wider profile set (e.g. an existing test) keeps behaving byte-for-byte the same. */
+const DEFAULT_SUBAGENT_PROFILES: readonly SubagentProfile[] = [GENTLE_PI_PROFILE];
+
+/**
+ * Everything about THIS OS process's identity that `role` (and everything
+ * derived from it — `orchestratorRef`, F1's write-routing target) depends
+ * on. Computed once by {@link resolveProcessIdentity}; see
+ * `process-identity-memo.ts` for why a caller must never simply call this
+ * again on a same-process factory re-invocation (G1).
+ */
+export interface ProcessIdentity {
+  role: "orchestrator" | "subagent";
+  /** `KANKAKU_ROLE`, as read BEFORE this call strips it from `deps.env` — never re-derivable afterwards. */
+  roleOverride: RoleOverride | undefined;
+  /** Whether `GENTLE_PI_AGENTS_CHILD=1` was present (never stripped, so re-reading `env` later would still agree — kept here anyway so every process-level fact lives in one place). */
+  childMarkerPresent: boolean;
+  /** See `config.ts#RoleDetection.overrideIgnoredInteractive`. */
+  overrideIgnoredInteractive: true | undefined;
+  /** C2: see `config.ts#RoleDetection.configuredMarkerIgnoredInteractive`. */
+  configuredMarkerIgnoredInteractive: true | undefined;
+  /** Whether a live, identity-verified tracked ancestor was found via the machine-wide registry (F2/F3's `hasTrackedAncestor`). */
+  hasTrackedAncestor: boolean;
+  /** The nearest verified tracked ancestor's own registry entry, if any. */
+  ancestorEntry: RegistryEntry | undefined;
+  /** F4: the real top-level orchestrator's ref, resolved through a possible subagent-of-subagent chain. `undefined` for an `orchestrator`-role process. */
+  orchestratorRef: OrchestratorRef | undefined;
+  /** F5: this process's own OS start-time identity, derived without a subprocess spawn. */
+  ownProcessStartId: number;
+  /** Live start-identity lookup from the same ancestry snapshot `resolveSubagentStartup` took (or a fail-safe always-unknown function when it never took one — F5). */
+  liveStartId: (pid: number) => number | undefined;
+  /**
+   * SUBAGENT-REQ-005/017: the {@link SubagentProfile} `id` whose child-env
+   * marker(s) confirmed this process's `role: "subagent"` classification,
+   * when exactly one profile's marker matched. `undefined` when no known
+   * marker matched (role, if `subagent`, then came from ancestry alone) or
+   * when 2+ matched at once (never guessed). Always `undefined` for an
+   * `orchestrator`-role process.
+   */
+  profile: string | undefined;
+}
+
+export interface ResolveProcessIdentityDeps {
+  /** This process's own env. Mutated in place: the override is stripped after being read (R1, layer 2). */
+  env: NodeJS.ProcessEnv;
+  registry: ProcessRegistry;
+  /** This process's own OS parent pid (`process.ppid`). */
+  ppid: number;
+  /** `Date.now`, injected. */
+  now: () => number;
+  /** `process.uptime`, injected. */
+  uptimeSeconds: () => number;
+  /** A cheap, synchronous interactivity proxy (`process.stdout.isTTY`) — see `config.ts#detectRole`'s doc comment. */
+  isInteractiveGuess: boolean;
+  /** Injectable for tests; forwarded to `resolveSubagentStartup`. */
+  snapshotAncestry?: () => AncestrySnapshot;
+  /**
+   * SUBAGENT-REQ-001/002/003/005: the full active {@link SubagentProfile}
+   * set (`config.ts#loadConfig`'s `subagentProfiles`) whose child-env
+   * markers confirm a subagent, generalised beyond gentle-pi's own. Defaults
+   * to gentle-pi alone — this module's exact pre-6b behaviour — so a caller
+   * that has not opted into the wider set (an existing test, or any
+   * embedder that has not been updated) sees no change at all.
+   */
+  subagentProfiles?: readonly SubagentProfile[];
+}
+
+/**
+ * Compute this OS process's role/ancestry identity exactly once: reads
+ * `KANKAKU_ROLE` and the confirmed-child marker, walks the machine-wide
+ * registry/ancestor chain only when it could find something (F5), decides
+ * `role` (R1's precedence), strips the override from `deps.env` so no
+ * child this process spawns ever inherits it (R1, layer 2), and resolves
+ * the verified `orchestratorRef` (F4) a subagent routes its writes to
+ * (F1's write-routing target, alongside this process's own resolved dir —
+ * see `extension.ts`).
+ *
+ * Mirrors what used to be inlined directly in `extension.ts` (and still is,
+ * independently, in `scripts/e2e-cross-worktree-real-processes.ts`'s
+ * `runStartup`, which exercises this exact sequence against real OS
+ * processes) — pulled out into its own function so
+ * `process-identity-memo.ts` (G1) can freeze its result across a
+ * same-process factory re-invocation (`/new`/`/resume`/`/fork`/`/reload`)
+ * without `extension.ts` duplicating this sequence, and so this exact
+ * sequence has one place to be tested directly.
+ */
+export function resolveProcessIdentity(deps: ResolveProcessIdentityDeps): ProcessIdentity {
+  const startup = resolveSubagentStartup({
+    registry: deps.registry,
+    ppid: deps.ppid,
+    now: deps.now,
+    uptimeSeconds: deps.uptimeSeconds,
+    ...(deps.snapshotAncestry !== undefined ? { snapshotAncestry: deps.snapshotAncestry } : {}),
+  });
+  const hasTrackedAncestor = startup.ancestorEntry !== undefined;
+
+  // SUBAGENT-REQ-001/002/003/005: the full active profile set's markers,
+  // generalising the single hardcoded GENTLE_PI_AGENTS_CHILD check this
+  // module used before — see DEFAULT_SUBAGENT_PROFILES for why an omitted
+  // `deps.subagentProfiles` is a complete no-op. C2: split into two tiers —
+  // built-in markers always win; the user-configured one never demotes an
+  // interactive session (see `config.ts#detectRole`'s doc comment).
+  const profiles = deps.subagentProfiles ?? DEFAULT_SUBAGENT_PROFILES;
+  const builtinMarkers = builtinChildMarkers(profiles);
+  const userConfiguredMarkers = configuredChildMarkers(profiles);
+
+  // R1 (BLOCKER): read KANKAKU_ROLE, and whether A confirmed BUILT-IN child
+  // marker (from any recognised profile) is present, exactly once here —
+  // then strip the override from this process's own env so a child this
+  // process spawns never inherits it. `childMarkerPresent` deliberately
+  // reflects the built-in tier only — it backs the doctor's "the confirmed
+  // child marker takes precedence" message (`kankaku-command.ts`), which is
+  // only true for this tier (C2).
+  const childMarkerPresent = matchesAnyMarker(deps.env, builtinMarkers);
+  const roleOverride = readRoleOverride(deps.env);
+  // `hasTrackedAncestor` is irrelevant to `role` itself (only to the
+  // separately-deferred `roleConfidence`, resolved later by the caller),
+  // so `false` is passed here purely to obtain `role`/`overrideIgnoredInteractive` cheaply.
+  const detection = detectRole(deps.env, false, deps.isInteractiveGuess, builtinMarkers, userConfiguredMarkers);
+  const { role } = detection;
+  const overrideIgnoredInteractive = detection.overrideIgnoredInteractive === true ? true : undefined;
+  const configuredMarkerIgnoredInteractive = detection.configuredMarkerIgnoredInteractive === true ? true : undefined;
+  stripRoleOverride(deps.env);
+
+  // SUBAGENT-REQ-005/017 + C2 item 3: WHICH profile's marker confirmed this
+  // process, if exactly one did (never guessed — see resolveChildProfile) —
+  // but only ever attributed when this process actually ended up
+  // classified `subagent`. A configured marker present but ignored for
+  // interactivity (role stays `orchestrator`) must never carry a
+  // `profile`: an orchestrator record with `profile: "configured"` would
+  // be a self-contradictory pair no doctor/report reader could make sense
+  // of.
+  const profile = role === "subagent" ? resolveChildProfile(profiles, deps.env).profile?.id : undefined;
+
+  // F4: resolves through a subagent-of-subagent chain to the real top-level
+  // orchestrator (never a middle hop), carrying that orchestrator's `dir`
+  // for F1's write routing.
+  const orchestratorRef = role === "subagent" ? resolveOrchestratorRef(startup.ancestorEntry) : undefined;
+
+  return {
+    role,
+    roleOverride,
+    childMarkerPresent,
+    overrideIgnoredInteractive,
+    configuredMarkerIgnoredInteractive,
+    hasTrackedAncestor,
+    ancestorEntry: startup.ancestorEntry,
+    orchestratorRef,
+    ownProcessStartId: startup.ownProcessStartId,
+    liveStartId: startup.liveStartId,
+    profile,
+  };
+}

package/src/adapters/project-config.ts

@@ -1,5 +1,6 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import type { WorkTargetCandidate } from "../domain/work-target.ts";
 import { resolveKankakuDir } from "./kankaku-dir.ts";
 
 const CONFIG_FILE_NAME = "config.json";
@@ -42,3 +43,74 @@ export class LazyProjectClientSource {
     return readProjectClient(resolveKankakuDir(this.dirOrRelative, this.fallbackCwd()));
   }
 }
+
+/**
+ * Read `clientId`/`projectId` from `<dir>/config.json`, the lowest-precedence
+ * source in `domain/work-target.ts#resolveWorkTarget`. Tolerates the same
+ * failure modes as {@link readProjectClient}. `undefined` when `clientId`
+ * is absent or not a string (a `projectId` without a `clientId` is not a
+ * valid candidate); a non-string `projectId` is dropped, keeping `clientId`.
+ */
+export function readProjectTargetIds(dir: string): WorkTargetCandidate | undefined {
+  const filePath = join(dir, CONFIG_FILE_NAME);
+  if (!existsSync(filePath)) return undefined;
+
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(filePath, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
+    const record = parsed as Record<string, unknown>;
+    const clientId = record["clientId"];
+    if (typeof clientId !== "string") return undefined;
+    const projectId = record["projectId"];
+    return typeof projectId === "string" ? { clientId, projectId } : { clientId };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Merge `clientId`/`projectId` into `<dir>/config.json`, preserving every
+ * other existing key (including the legacy `client` label). Writes
+ * atomically (tmp + rename), mirroring `file-inflight-store.ts`. A missing
+ * or malformed existing file is treated as `{}` rather than failing.
+ */
+export function writeProjectTargetIds(dir: string, ids: WorkTargetCandidate): void {
+  const filePath = join(dir, CONFIG_FILE_NAME);
+  let existing: Record<string, unknown> = {};
+  if (existsSync(filePath)) {
+    try {
+      const parsed: unknown = JSON.parse(readFileSync(filePath, "utf8"));
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        existing = parsed as Record<string, unknown>;
+      }
+    } catch {
+      existing = {};
+    }
+  }
+
+  const merged = { ...existing, clientId: ids.clientId, ...(ids.projectId !== undefined ? { projectId: ids.projectId } : {}) };
+
+  mkdirSync(dir, { recursive: true });
+  const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, JSON.stringify(merged, null, 2));
+  renameSync(tmp, filePath);
+}
+
+/** Reads target ids from a kankaku dir resolved lazily against `fallbackCwd()` at call time. */
+export class LazyProjectTargetSource {
+  private readonly dirOrRelative: string;
+  private readonly fallbackCwd: () => string;
+
+  constructor(dirOrRelative: string, fallbackCwd: () => string = () => process.cwd()) {
+    this.dirOrRelative = dirOrRelative;
+    this.fallbackCwd = fallbackCwd;
+  }
+
+  read(): WorkTargetCandidate | undefined {
+    return readProjectTargetIds(resolveKankakuDir(this.dirOrRelative, this.fallbackCwd()));
+  }
+
+  write(ids: WorkTargetCandidate): void {
+    writeProjectTargetIds(resolveKankakuDir(this.dirOrRelative, this.fallbackCwd()), ids);
+  }
+}

package/src/adapters/report.ts

@@ -1,4 +1,4 @@
-import { buildTasks } from "../domain/task-view.ts";
+import { buildTasks, uncertainRecords } from "../domain/task-view.ts";
 import type { SessionView, TaskView } from "../domain/task-view.ts";
 import { localDay } from "../domain/day.ts";
 import { finiteOrZero } from "../domain/work-record.ts";
@@ -42,10 +42,16 @@ function emptyTotals(): RoleTotals {
   return { workMs: 0, waitingMs: 0, wallMs: 0, count: 0, cost: 0, segments: {} };
 }
 
-/** Add per-tag milliseconds from `segments` (missing on older records) into `into`. */
-function addSegments(into: Record<string, number>, segments: Record<string, number> | undefined): void {
+/**
+ * Add per-tag milliseconds from `segments` (missing on older records) into
+ * `into`, a `Map` rather than a plain object so a tag from a hand-edited
+ * worklog line named `__proto__` or `constructor` accumulates as a normal
+ * entry instead of silently reading (and arithmetically corrupting) an
+ * inherited `Object.prototype` value.
+ */
+function addSegments(into: Map<string, number>, segments: Record<string, number> | undefined): void {
   for (const [tag, ms] of Object.entries(segments ?? {})) {
-    into[tag] = (into[tag] ?? 0) + ms;
+    into.set(tag, (into.get(tag) ?? 0) + ms);
   }
 }
 
@@ -63,6 +69,10 @@ export function summarize(records: WorkRecord[], options: SummarizeOptions): Sum
     subagent: emptyTotals(),
     tasks: { count: 0, wallMs: 0, workMs: 0, cost: 0, segments: {} },
   };
+  // Accumulated in Maps (see `addSegments`) and only converted to the
+  // returned plain objects at the very end, via `Object.fromEntries`.
+  const segmentsByRole: Record<WorkRole, Map<string, number>> = { orchestrator: new Map(), subagent: new Map() };
+  const taskSegments = new Map<string, number>();
 
   for (const record of records) {
     if (targetDay !== undefined && localDay(record.startedAt) !== targetDay) continue;
@@ -72,7 +82,7 @@ export function summarize(records: WorkRecord[], options: SummarizeOptions): Sum
     totals.wallMs += record.wallMs;
     totals.count += 1;
     totals.cost += finiteOrZero(record.usage.cost);
-    addSegments(totals.segments, record.segments);
+    addSegments(segmentsByRole[record.role], record.segments);
   }
 
   const tasks = buildTasks(records).filter((task) => targetDay === undefined || localDay(task.startedAt) === targetDay);
@@ -81,12 +91,27 @@ export function summarize(records: WorkRecord[], options: SummarizeOptions): Sum
     summary.tasks.wallMs += task.wallMs;
     summary.tasks.workMs += task.workMs;
     summary.tasks.cost += task.usage.cost;
-    addSegments(summary.tasks.segments, task.segments);
+    addSegments(taskSegments, task.segments);
   }
 
+  summary.orchestrator.segments = Object.fromEntries(segmentsByRole.orchestrator);
+  summary.subagent.segments = Object.fromEntries(segmentsByRole.subagent);
+  summary.tasks.segments = Object.fromEntries(taskSegments);
+
   return summary;
 }
 
+/**
+ * Count of `uncertain` records (ADR 0022) within the same day scope
+ * `summarize` uses, so the `/kankaku` report can surface a one-line hint
+ * when some records are silently excluded from the task count
+ * (SUBAGENT-REQ-017): an undercount must never be silent.
+ */
+export function countUncertain(records: WorkRecord[], options: SummarizeOptions): number {
+  const targetDay = options.all ? undefined : (options.day ?? localDay(new Date().toISOString()));
+  return uncertainRecords(records).filter((record) => targetDay === undefined || localDay(record.startedAt) === targetDay).length;
+}
+
 function formatMinutes(ms: number): string {
   const totalSeconds = Math.round(ms / 1000);
   const minutes = Math.floor(totalSeconds / 60);
@@ -187,6 +212,54 @@ export function summarizeByClient(tasks: TaskView[]): Map<string, ClientTotals>
   return totals;
 }
 
+export interface ProjectTotals {
+  /** Display name: the project's `projectName`, or `"(no project)"` for the ungrouped bucket. */
+  name: string;
+  wallMs: number;
+  waitingMs: number;
+  workMs: number;
+  /** Estimated cost in USD, summed across this project's tasks. */
+  cost: number;
+  count: number;
+}
+
+/** Key (and display name) under which tasks without a resolved project are grouped. */
+const NO_PROJECT = "(no project)";
+
+/**
+ * Aggregate tasks by hub project (see `domain/work-target.ts`), keyed by
+ * `projectId` (so two projects that happen to share a display name are
+ * never merged) with the name denormalised alongside for display. Tasks
+ * without a `projectId` are grouped under `"(no project)"`.
+ */
+export function summarizeByProject(tasks: TaskView[]): Map<string, ProjectTotals> {
+  const totals = new Map<string, ProjectTotals>();
+  for (const task of tasks) {
+    const key = task.projectId ?? NO_PROJECT;
+    const name = task.projectId !== undefined ? (task.projectName ?? task.projectId) : NO_PROJECT;
+    const entry = totals.get(key) ?? { name, wallMs: 0, waitingMs: 0, workMs: 0, cost: 0, count: 0 };
+    entry.wallMs += task.wallMs;
+    entry.waitingMs += task.waitingMs;
+    entry.workMs += task.workMs;
+    entry.cost += finiteOrZero(task.usage.cost);
+    entry.count += 1;
+    totals.set(key, entry);
+  }
+  return totals;
+}
+
+/** Render one line per project, sorted alphabetically by display name, with work/waiting/wall time, cost, and task count. */
+export function formatProjects(totals: Map<string, ProjectTotals>): string {
+  if (totals.size === 0) return "no projects";
+  return Array.from(totals.values())
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map(
+      (t) =>
+        `${t.name}  work ${formatMinutes(t.workMs)}  waiting ${formatMinutes(t.waitingMs)}  wall ${formatMinutes(t.wallMs)}  ${formatCost(t.cost)}  tasks ${t.count}`,
+    )
+    .join("\n");
+}
+
 /** Render one line per client, sorted alphabetically, with work/waiting/wall time, cost, and task count. */
 export function formatClients(totals: Map<string, ClientTotals>): string {
   if (totals.size === 0) return "no clients";

package/src/adapters/session-dir.ts

@@ -0,0 +1,28 @@
+/**
+ * `SessionManager#usesDefaultSessionDir()`/`#getSessionDir()` are real
+ * methods on pi's session manager (mirrors what pi's own
+ * `formatResumeCommand` does to decide whether to print `--session-dir`),
+ * but `usesDefaultSessionDir` is not part of the `ReadonlySessionManager`
+ * type `ctx.sessionManager` is typed as — so this is a guarded duck-typed
+ * call, not a typed one: an older pi version (or any future shape change)
+ * that lacks the method degrades to "no sessionDir," never a crash.
+ * Returns the session dir only when it is genuinely non-default, exactly
+ * the condition under which pi itself would print `--session-dir`. Shared
+ * by `pi-tracker.ts` (record metadata) and `kankaku-command.ts` (the
+ * `/kankaku doctor` display) — kept as its own module so neither adapter
+ * has to import the other.
+ */
+export function readNonDefaultSessionDir(sessionManager: unknown): string | undefined {
+  const candidate = sessionManager as { usesDefaultSessionDir?: () => boolean; getSessionDir?: () => string };
+  if (typeof candidate.usesDefaultSessionDir !== "function" || typeof candidate.getSessionDir !== "function") return undefined;
+  try {
+    if (candidate.usesDefaultSessionDir()) return undefined;
+    const dir = candidate.getSessionDir();
+    // An unpersisted session (e.g. `--no-session`) can report
+    // usesDefaultSessionDir() === false with an empty getSessionDir() — not
+    // a real custom directory, so there is nothing meaningful to carry.
+    return dir ? dir : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/src/adapters/session-target.ts

@@ -0,0 +1,262 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { formatWorkTargetLabel, resolveWorkTarget, resolveWorkTargetSource } from "../domain/work-target.ts";
+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";
+
+/** Persisted as a `kankaku-target` custom session entry so the session-level target survives a reload. */
+export interface KankakuTargetEntryData {
+  clientId?: string;
+  projectId?: string;
+  /** `true` when the user explicitly declined the picker; distinct from "no entry yet". */
+  skipped?: boolean;
+}
+
+export const TARGET_ENTRY_TYPE = "kankaku-target";
+
+export interface SessionTargetDeps {
+  role: WorkRole;
+  catalog: Catalog;
+  /** Lazily reads `clientId`/`projectId` from `<kankaku dir>/config.json`. */
+  resolveProjectConfigIds: () => WorkTargetCandidate | undefined;
+  /** Persist `clientId`/`projectId` into `<kankaku dir>/config.json`, merging existing keys. */
+  persistProjectConfig: (ids: WorkTargetCandidate) => void;
+  /** Current working directory, matched against catalog `repo_paths`. Defaults to `process.cwd()`. */
+  cwd?: () => string;
+  /**
+   * Overall deadline, in ms, for the very first (no-cache) catalog fetch —
+   * see {@link getSnapshot}. Bounds auth, pagination and the 401 retry
+   * together via an `AbortSignal` composed with each request's own
+   * per-request timeout, instead of leaving that awaited path bounded only
+   * per-request. Defaults to 5000.
+   */
+  firstFetchDeadlineMs?: number;
+  /** Injectable for tests; defaults to the global timer functions. */
+  setTimeout?: (handler: () => void, ms: number) => NodeJS.Timeout;
+  clearTimeout?: (timer: NodeJS.Timeout) => void;
+}
+
+const DEFAULT_FIRST_FETCH_DEADLINE_MS = 5000;
+
+export interface SessionTarget {
+  /** Restore the session-level target (or its remembered "skipped" state) from the last `kankaku-target` entry. */
+  restore(ctx: ExtensionContext): void;
+  /**
+   * The `session_start` flow: resolves silently from the project config
+   * file or catalog `repo_paths`, or — only when nothing resolves and no
+   * session entry (pick or skip) already exists — shows the picker. A
+   * no-op unless `role === "orchestrator"` and `ctx.hasUI`.
+   */
+  ensurePicked(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void>;
+  /** Force the picker again, e.g. `/kankaku target pick`. Ignores any existing session override. */
+  pick(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void>;
+  /** Set the session target directly, bypassing the picker (the legacy `/kankaku client <name>` compatibility path). */
+  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;
+  /** Current effective target (session > project config > repoPaths), regardless of role. */
+  effectiveTarget(): WorkTarget | undefined;
+  /** Which source produced {@link effectiveTarget}. */
+  effectiveSource(): WorkTargetSourceName | undefined;
+  /** Role-gated target for the in-progress run (`undefined` for a subagent); caches the project config read for the run. */
+  runTarget(): WorkTarget | undefined;
+  /** Role-gated target to show while idle, reusing the run's cached project config read when still held. */
+  idleTarget(): WorkTarget | undefined;
+  /** Drop the per-run cached project config read; call when a run settles or the session shuts down. */
+  endRun(): void;
+}
+
+function candidateFrom(target: WorkTarget): WorkTargetCandidate {
+  return { clientId: target.clientId, ...(target.projectId !== undefined ? { projectId: target.projectId } : {}) };
+}
+
+function entryDataFrom(ids: WorkTargetCandidate): KankakuTargetEntryData {
+  return { clientId: ids.clientId, ...(ids.projectId !== undefined ? { projectId: ids.projectId } : {}) };
+}
+
+/**
+ * Owns the session-level hub target override (`/kankaku target pick`), its
+ * restore/persist round-trip through session entries, and target
+ * resolution for both the in-progress run and the idle status line. See
+ * README "Hub (PocketBase)" and `domain/work-target.ts#resolveWorkTarget`.
+ */
+export function createSessionTarget(deps: SessionTargetDeps): SessionTarget {
+  const cwd = deps.cwd ?? (() => process.cwd());
+  const scheduleTimeout = deps.setTimeout ?? setTimeout;
+  const cancelTimeout = deps.clearTimeout ?? clearTimeout;
+  const firstFetchDeadlineMs = deps.firstFetchDeadlineMs ?? DEFAULT_FIRST_FETCH_DEADLINE_MS;
+
+  /** Session-level override, restored on `session_start` or set by an explicit pick/skip/legacy command. */
+  let sessionOverride: WorkTargetSessionOverride;
+  /** Project config ids read once per run (first record build) so checkpoints do not hit the filesystem repeatedly. */
+  let runProjectIds: { value: WorkTargetCandidate | undefined } | undefined;
+  /** Only notify "hub unreachable" once per process for the silent `ensurePicked`/`pick` path. */
+  let notifiedUnreachable = false;
+
+  function restore(ctx: ExtensionContext): void {
+    const entries = ctx.sessionManager.getEntries();
+    for (let i = entries.length - 1; i >= 0; i--) {
+      const entry = entries[i] as { type: string; customType?: string; data?: unknown };
+      if (entry.type === "custom" && entry.customType === TARGET_ENTRY_TYPE) {
+        const data = entry.data as KankakuTargetEntryData | undefined;
+        if (data?.skipped === true) {
+          sessionOverride = "skipped";
+        } else if (typeof data?.clientId === "string") {
+          sessionOverride = { clientId: data.clientId, ...(typeof data.projectId === "string" ? { projectId: data.projectId } : {}) };
+        } else {
+          sessionOverride = undefined;
+        }
+        return;
+      }
+    }
+    sessionOverride = undefined;
+  }
+
+  function computeTarget(projectIds: WorkTargetCandidate | undefined): WorkTarget | undefined {
+    const snapshot = deps.catalog.read();
+    return resolveWorkTarget({
+      session: sessionOverride,
+      project: projectIds,
+      cwd: cwd(),
+      clients: snapshot?.clients ?? [],
+      projects: snapshot?.projects ?? [],
+    });
+  }
+
+  function effectiveTarget(): WorkTarget | undefined {
+    return computeTarget(deps.resolveProjectConfigIds());
+  }
+
+  function effectiveSource(): WorkTargetSourceName | undefined {
+    const snapshot = deps.catalog.read();
+    return resolveWorkTargetSource({
+      session: sessionOverride,
+      project: deps.resolveProjectConfigIds(),
+      cwd: cwd(),
+      clients: snapshot?.clients ?? [],
+      projects: snapshot?.projects ?? [],
+    });
+  }
+
+  function runIds(): WorkTargetCandidate | undefined {
+    if (!runProjectIds) {
+      runProjectIds = { value: deps.resolveProjectConfigIds() };
+    }
+    return runProjectIds.value;
+  }
+
+  function runTarget(): WorkTarget | undefined {
+    return deps.role === "orchestrator" ? computeTarget(runIds()) : undefined;
+  }
+
+  function idleTarget(): WorkTarget | undefined {
+    const ids = runProjectIds ? runProjectIds.value : deps.resolveProjectConfigIds();
+    return deps.role === "orchestrator" ? computeTarget(ids) : undefined;
+  }
+
+  function endRun(): void {
+    runProjectIds = undefined;
+  }
+
+  function notifyUnreachableOnce(ctx: ExtensionContext): void {
+    if (notifiedUnreachable) return;
+    notifiedUnreachable = true;
+    if (ctx.hasUI) ctx.ui.notify("kankaku: hub unreachable, using local labels", "warning");
+  }
+
+  /**
+   * Resolve a catalog snapshot to show the picker with: the cached
+   * snapshot immediately when fresh; the cached snapshot immediately with
+   * a fire-and-forget refresh when stale (not deadline-bound: it is never
+   * awaited, so a slow or hung refresh here cannot block anything); or,
+   * when there is no cache at all, one awaited refresh bounded by an
+   * *overall* deadline ({@link SessionTargetDeps.firstFetchDeadlineMs},
+   * default 5000ms) — not merely the hub client's own per-request timeout,
+   * which alone does not bound the whole sequence of a lazy auth,
+   * pagination, and a possible 401 retry. The deadline is enforced with an
+   * `AbortSignal` composed, per request, with that request's own
+   * per-request timeout (see `pocketbase-client.ts#rawFetch`). Notifies
+   * "hub unreachable" at most once when no snapshot is available at all,
+   * whether because the hub failed outright or because the deadline fired
+   * first — both are treated identically.
+   */
+  async function getSnapshot(ctx: ExtensionContext): Promise<CatalogSnapshot | undefined> {
+    const cached = deps.catalog.read();
+    if (cached) {
+      if (deps.catalog.isStale()) {
+        void deps.catalog.refresh();
+      }
+      return cached;
+    }
+
+    const controller = new AbortController();
+    const timer = scheduleTimeout(() => controller.abort(), firstFetchDeadlineMs);
+    let fresh: CatalogSnapshot | undefined;
+    try {
+      fresh = await deps.catalog.refresh(controller.signal);
+    } finally {
+      cancelTimeout(timer);
+    }
+    if (!fresh) {
+      notifyUnreachableOnce(ctx);
+    }
+    return fresh;
+  }
+
+  async function runPicker(pi: ExtensionAPI, ctx: ExtensionContext, snapshot: CatalogSnapshot): Promise<void> {
+    const result = await pickTarget(ctx, snapshot);
+
+    if (result.kind === "skipped") {
+      sessionOverride = "skipped";
+      pi.appendEntry<KankakuTargetEntryData>(TARGET_ENTRY_TYPE, { skipped: true });
+      return;
+    }
+
+    const ids = candidateFrom(result.target);
+    sessionOverride = ids;
+    pi.appendEntry<KankakuTargetEntryData>(TARGET_ENTRY_TYPE, entryDataFrom(ids));
+
+    const remember = await ctx.ui.confirm("kankaku", `Remember ${formatWorkTargetLabel(result.target)} for this repository?`);
+    if (remember) {
+      deps.persistProjectConfig(ids);
+    }
+  }
+
+  async function ensurePicked(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
+    if (deps.role !== "orchestrator" || !ctx.hasUI) return;
+    if (sessionOverride !== undefined) return;
+
+    const snapshot = await getSnapshot(ctx);
+    if (!snapshot) return;
+
+    const projectIds = deps.resolveProjectConfigIds();
+    const resolved = resolveWorkTarget({
+      project: projectIds,
+      cwd: cwd(),
+      clients: snapshot.clients,
+      projects: snapshot.projects,
+    });
+    if (resolved) return;
+
+    await runPicker(pi, ctx, snapshot);
+  }
+
+  async function pick(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
+    const snapshot = await getSnapshot(ctx);
+    if (!snapshot) return;
+    await runPicker(pi, ctx, snapshot);
+  }
+
+  function setExplicit(pi: ExtensionAPI, ids: WorkTargetCandidate): void {
+    sessionOverride = ids;
+    pi.appendEntry<KankakuTargetEntryData>(TARGET_ENTRY_TYPE, entryDataFrom(ids));
+  }
+
+  function clear(pi: ExtensionAPI): void {
+    sessionOverride = undefined;
+    pi.appendEntry<KankakuTargetEntryData>(TARGET_ENTRY_TYPE, {});
+  }
+
+  return { restore, ensurePicked, pick, setExplicit, clear, effectiveTarget, effectiveSource, runTarget, idleTarget, endRun };
+}