kankaku 0.6.0 → 0.7.0

package/src/adapters/kankaku-command.ts

@@ -2,8 +2,7 @@ import type { AutocompleteItem } from "@earendil-works/pi-tui";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Box, Text } from "@earendil-works/pi-tui";
 import { isValidClient } from "../domain/client-label.ts";
-import { exportRows, toCsv, toJson } from "../domain/export.ts";
-import { buildSessions, buildTasks, detectSameProcessOverlaps, orphanSubagents, uncertainRecords } from "../domain/task-view.ts";
+import { detectSameProcessOverlaps, orphanSubagents, uncertainRecords } from "../domain/task-view.ts";
 import { formatWorkTargetLabel } from "../domain/work-target.ts";
 import { findAmbiguousToolNames } from "../domain/subagent-profile.ts";
 import type { SubagentProfile } from "../domain/subagent-profile.ts";
@@ -12,19 +11,9 @@ import type { SyncState } from "../domain/sync-plan.ts";
 import type { RegistryClassification } from "../domain/registry-health.ts";
 import type { Catalog } from "../ports/catalog.ts";
 import type { WorkLog } from "../ports/work-log.ts";
+import { buildSyncStatusLines, formatBackfillLines, formatCatalogRefreshLines, formatSyncSummaryLines } from "./hub-actions.ts";
+import { buildClientsView, buildExportContent, buildProjectsView, buildSessionsView, buildSummaryView, buildTasksView } from "./report-views.ts";
 import type { SyncSummary, SyncTrigger } from "./sync-runner.ts";
-import {
-  countUncertain,
-  formatClients,
-  formatProjects,
-  formatReport,
-  formatSessions,
-  formatTasks,
-  localDay,
-  summarize,
-  summarizeByClient,
-  summarizeByProject,
-} from "./report.ts";
 import type { SessionClient } from "./session-client.ts";
 import { readNonDefaultSessionDir } from "./session-dir.ts";
 import type { SessionTarget } from "./session-target.ts";
@@ -44,10 +33,172 @@ export function notifyError(ctx: ExtensionContext, error: unknown): void {
   ctx.ui.notify(`kankaku: ${message}`, "error");
 }
 
+/**
+ * Append a {@link KankakuReportData} as a durable entry in the chat
+ * transcript when a UI is attached, or fall back to a one-shot notify
+ * otherwise. Exact body of `/kankaku`'s own `showReport` (which now
+ * delegates here), so the panel's "pin to chat" action
+ * (`screens/report.ts`, `screens/doctor.ts`) renders identically to every
+ * existing subcommand's report.
+ */
+export function appendReportEntry(pi: ExtensionAPI, ctx: ExtensionContext, report: KankakuReportData): void {
+  if (ctx.hasUI) {
+    pi.appendEntry<KankakuReportData>(REPORT_ENTRY_TYPE, report);
+    return;
+  }
+  ctx.ui.notify(`${report.title}\n${report.lines.join("\n")}`);
+}
+
+/**
+ * Handle `/kankaku doctor`'s line-building: a no-network diagnostic
+ * (SUBAGENT-REQ-017) reporting orphan/uncertain record counts (ADR 0022)
+ * with why, and whether ancestor-chain detection is available on this
+ * platform, so silent undercount stays visible (see README "Subagents").
+ * Extracted from `handleDoctorCommand` so the panel's doctor screen
+ * (`screens/doctor.ts`) can never drift from `/kankaku doctor`'s own output.
+ */
+export function buildDoctorLines(deps: KankakuCommandDeps, ctx: ExtensionContext): string[] {
+  const records = deps.log.readAll();
+  const orphans = orphanSubagents(records);
+  const uncertain = uncertainRecords(records);
+  const ancestorDetectionAvailable = deps.ancestorDetectionAvailable ? deps.ancestorDetectionAvailable() : process.platform !== "win32";
+
+  const lines = [
+    `ancestor-chain detection: ${ancestorDetectionAvailable ? "available" : "unavailable"}`,
+    `orphan subagent record(s): ${orphans.length}` +
+      (orphans.length > 0 ? " — recognised as someone's child (an env marker matched), but no orchestrator could be matched" : ""),
+    `uncertain record(s): ${uncertain.length}` +
+      (uncertain.length > 0
+        ? " — no recognised child-env-marker, but a live tracked ancestor process was found; not counted as a new task, not synced"
+        : ""),
+  ];
+
+  if (!ancestorDetectionAvailable) {
+    lines.push(
+      "on this platform/environment, ancestor-chain detection could not run (Windows, or a failed/unavailable ps/proc read): " +
+        "an unmarked subagent system may be counted twice (a genuine child with no recognised marker looks like a fresh top-level " +
+        "session). Mark it explicitly with KANKAKU_ROLE=subagent in the child's environment (or KANKAKU_ROLE=orchestrator to force " +
+        "the other way).",
+    );
+  }
+
+  if (deps.roleOverride) {
+    if (deps.childMarkerPresent) {
+      // R1: both signals present — the confirmed child marker always
+      // wins (config.ts#detectRole), so the override did not decide
+      // anything, whatever it said.
+      lines.push(
+        `role override: KANKAKU_ROLE=${deps.roleOverride} was present, but the confirmed child marker (GENTLE_PI_AGENTS_CHILD=1) takes precedence — resolved role: subagent`,
+      );
+    } else if (deps.overrideIgnoredInteractive) {
+      lines.push(
+        "role override: KANKAKU_ROLE=subagent was ignored for this interactive session (likely a leaked shell export) — resolved role: orchestrator",
+      );
+    } else {
+      lines.push(`role override: KANKAKU_ROLE=${deps.roleOverride} (deciding signal for this process's role)`);
+    }
+  }
+
+  // C2 item 2/3: a configured child-env marker matched but was ignored
+  // for this process's role because it looked interactive — a
+  // configured marker, unlike a built-in one, never demotes an
+  // interactive session. Escalated when this process also has no
+  // tracked ancestor at all (C2 item 3's self-check: the strongest
+  // signal the marker is genuinely ambient, not a real subagent
+  // mechanism).
+  if (deps.configuredMarkerIgnoredInteractive) {
+    lines.push(
+      deps.hasTrackedAncestor
+        ? "configured marker: a KANKAKU_SUBAGENT_CHILD_ENV marker was present but ignored for this interactive session — resolved role: orchestrator"
+        : "configured marker: a KANKAKU_SUBAGENT_CHILD_ENV marker was present on this interactive, TOP-LEVEL session (no tracked ancestor) — the marker is likely ambient (set on every process of its kind, not just a subagent's child), not a real subagent mechanism; resolved role: orchestrator",
+    );
+  }
+
+  // C2 item 1: markers rejected at config load time as looking
+  // pi/shell/OS/npm-owned rather than genuinely child-only.
+  if (deps.rejectedSubagentChildEnvMarkers && deps.rejectedSubagentChildEnvMarkers.length > 0) {
+    for (const rejected of deps.rejectedSubagentChildEnvMarkers) {
+      lines.push(`rejected KANKAKU_SUBAGENT_CHILD_ENV marker "${rejected.name}": ${rejected.reason}`);
+    }
+  }
+
+  // SUBAGENT-REQ-001/002/003/005/017 (6b): active profiles, any configured
+  // tool names/markers, which profile matched each subagent record, and
+  // any tool-name ambiguity among the active set. Omitted entirely when
+  // deps.subagentProfiles was not wired (back-compat).
+  if (deps.subagentProfiles) {
+    const profiles = deps.subagentProfiles;
+    lines.push(`subagent profiles active: ${profiles.map((p) => p.id).join(", ")}`);
+
+    const configured = profiles.find((p) => p.id === "configured");
+    if (configured) {
+      if (configured.toolNames.length > 0) lines.push(`configured subagent tools: ${configured.toolNames.join(", ")}`);
+      if (configured.childEnvMarkers.length > 0) {
+        lines.push(`configured child-env markers: ${configured.childEnvMarkers.map((m) => (m.value !== undefined ? `${m.name}=${m.value}` : m.name)).join(", ")}`);
+      }
+    }
+
+    const subagentRecords = records.filter((record) => record.role === "subagent");
+    if (subagentRecords.length > 0) {
+      const counts = new Map<string, number>();
+      let unmatched = 0;
+      for (const record of subagentRecords) {
+        if (record.profile) {
+          counts.set(record.profile, (counts.get(record.profile) ?? 0) + 1);
+        } else {
+          unmatched++;
+        }
+      }
+      const parts = profiles.filter((p) => counts.has(p.id)).map((p) => `${p.id}: ${counts.get(p.id)}`);
+      if (unmatched > 0) parts.push(`unmatched: ${unmatched}`);
+      lines.push(`profile matches: ${parts.join(", ")}`);
+    }
+
+    for (const { toolName, profileIds } of findAmbiguousToolNames(profiles)) {
+      lines.push(`ambiguous tool name "${toolName}": registered by ${profileIds.join(", ")} — never guessed, resolved by child-env marker or left uncertain`);
+    }
+  }
+
+  // SUBAGENT-REQ-015 (6c): same-pid overlapping orchestrator records —
+  // never observed from any real subagent mechanism today, but flagged
+  // here (informational only, never changing buildTasks' own numbers) as
+  // the observable signature an in-process nested session would leave.
+  for (const overlap of detectSameProcessOverlaps(records)) {
+    lines.push(
+      `likely in-process nesting: pid ${overlap.pid} has ${overlap.recordIds.length} overlapping orchestrator records (${overlap.recordIds.join(", ")}) — union of their wall time is ${overlap.unionedWallMs}ms`,
+    );
+  }
+
+  if (deps.workLogRouting?.usedFallback) {
+    lines.push(
+      `kankaku: this subagent could not write to its orchestrator's directory (${deps.workLogRouting.parentDir}); ` +
+        "fell back to its own local worklog — this record may show as an orphan until reunited manually",
+    );
+  }
+
+  if (deps.registryHealth) {
+    const { keep, discard } = deps.registryHealth();
+    const counts = new Map<string, number>();
+    for (const { reason } of discard) counts.set(reason, (counts.get(reason) ?? 0) + 1);
+    const byReason = Array.from(counts.entries())
+      .map(([reason, count]) => `${reason}: ${count}`)
+      .join(", ");
+    lines.push(`registry (~/.kankaku/run): ${keep.length} entrie(s) trusted${discard.length > 0 ? `, ${discard.length} discarded (${byReason})` : ""}`);
+  }
+
+  const sessionDir = readNonDefaultSessionDir(ctx.sessionManager);
+  if (sessionDir !== undefined) {
+    lines.push(`session dir (non-default): ${sessionDir}`);
+  }
+
+  return lines;
+}
+
 const COMMAND_TOKENS = ["all", "tasks", "sessions", "client", "clients", "export", "doctor"];
 /** Only offered when the hub is configured, so completions are unchanged for users without one. */
-const HUB_COMMAND_TOKENS = ["target", "projects", "catalog", "sync", "backfill"];
+const HUB_COMMAND_TOKENS = ["target", "task", "projects", "catalog", "sync", "backfill"];
 const TARGET_TOKENS = ["pick", "clear"];
+const TASK_TOKENS = ["pick", "clear"];
 const CATALOG_TOKENS = ["refresh"];
 const SYNC_TOKENS = ["all", "status"];
 
@@ -174,6 +325,14 @@ export interface KankakuCommandDeps {
    * a caller has not wired this — back-compat with an older embedder.
    */
   subagentProfiles?: SubagentProfile[];
+  /**
+   * Opens the `/kankaku` overlay panel (`adapters/panel/kankaku-panel.ts`)
+   * when present. `/kankaku` with no arguments prefers this over the plain
+   * summary report whenever a UI is attached; absent (or without a UI),
+   * behaviour is unchanged — the summary report, exactly as before this
+   * panel existed.
+   */
+  openPanel?: (ctx: ExtensionContext) => Promise<void>;
 }
 
 export interface KankakuCommand {
@@ -232,11 +391,7 @@ export function registerKankakuCommand(pi: ExtensionAPI, deps: KankakuCommandDep
   });
 
   function showReport(ctx: ExtensionContext, report: KankakuReportData): void {
-    if (ctx.hasUI) {
-      pi.appendEntry<KankakuReportData>(REPORT_ENTRY_TYPE, report);
-      return;
-    }
-    ctx.ui.notify(`${report.title}\n${report.lines.join("\n")}`);
+    appendReportEntry(pi, ctx, report);
   }
 
   /**
@@ -328,6 +483,35 @@ export function registerKankakuCommand(pi: ExtensionAPI, deps: KankakuCommandDep
     notifyError(ctx, new Error(`unknown target subcommand: ${rest.join(" ")}`));
   }
 
+  /**
+   * Handle `/kankaku task [pick|clear]`; `rest` excludes the leading `task`
+   * token. Default (no args) is `pick`. `pickTask`/`clearTask`
+   * (`session-target.ts`) notify their own outcome directly, so this only
+   * dispatches and refreshes the idle status line.
+   */
+  async function handleTaskCommand(rest: string[], ctx: ExtensionContext): Promise<void> {
+    const sessionTarget = deps.sessionTarget;
+    if (!sessionTarget) {
+      notifyError(ctx, new Error("hub is not configured"));
+      return;
+    }
+
+    if (rest.length === 1 && rest[0] === "clear") {
+      sessionTarget.clearTask(pi);
+      deps.refreshIdleStatus(ctx);
+      showReport(ctx, { title: "task", lines: ["task link cleared for this session"] });
+      return;
+    }
+
+    if (rest.length === 0 || (rest.length === 1 && rest[0] === "pick")) {
+      await sessionTarget.pickTask(pi, ctx);
+      deps.refreshIdleStatus(ctx);
+      return;
+    }
+
+    notifyError(ctx, new Error(`unknown task subcommand: ${rest.join(" ")}`));
+  }
+
   /** Handle `/kankaku catalog refresh`; `rest` excludes the leading `catalog` token. */
   async function handleCatalogCommand(rest: string[], ctx: ExtensionContext): Promise<void> {
     const catalog = deps.catalog;
@@ -342,38 +526,13 @@ export function registerKankakuCommand(pi: ExtensionAPI, deps: KankakuCommandDep
         notifyError(ctx, new Error("hub unreachable; catalog not refreshed"));
         return;
       }
-      showReport(ctx, {
-        title: "catalog",
-        lines: [`refreshed: ${snapshot.clients.length} client(s), ${snapshot.projects.length} project(s)`],
-      });
+      showReport(ctx, { title: "catalog", lines: formatCatalogRefreshLines(snapshot) });
       return;
     }
 
     notifyError(ctx, new Error(`unknown catalog subcommand: ${rest.join(" ")}`));
   }
 
-  /** Render a {@link SyncSummary} as report lines: counts, any stop reason, the new watermark, and the unassigned breakdown. */
-  function formatSyncSummary(summary: SyncSummary): string[] {
-    const lines = [`uploaded ${summary.uploaded}, updated ${summary.updated}, skipped ${summary.skipped}, failed ${summary.failed.length}`];
-
-    if (summary.locked) lines.push("another sync is already in progress; nothing was attempted");
-    if (summary.error) lines.push(`stopped early: ${summary.error}`);
-    if (summary.syncedThrough) lines.push(`synced through ${summary.syncedThrough}`);
-
-    const unassignedEntries = Object.entries(summary.unassigned).sort(([a], [b]) => a.localeCompare(b));
-    if (unassignedEntries.length > 0) {
-      lines.push("unassigned (Sin determinar):");
-      for (const [label, count] of unassignedEntries) lines.push(`  ${label}: ${count}`);
-    }
-
-    if (summary.failed.length > 0) {
-      lines.push("failed:");
-      for (const entry of summary.failed) lines.push(`  ${entry.id}: ${entry.reason}`);
-    }
-
-    return lines;
-  }
-
   /** Handle `/kankaku sync [all|status]`; `rest` excludes the leading `sync` token. */
   async function handleSyncCommand(rest: string[], ctx: ExtensionContext): Promise<void> {
     const sync = deps.sync;
@@ -383,13 +542,7 @@ export function registerKankakuCommand(pi: ExtensionAPI, deps: KankakuCommandDep
     }
 
     if (rest.length === 1 && rest[0] === "status") {
-      const { state, pending, staleOutsideWindow } = sync.status();
-      const lines = [state?.syncedThrough ? `synced through ${state.syncedThrough}` : "never synced", `pending: ${pending}`];
-      if (staleOutsideWindow > 0) {
-        lines.push(`${staleOutsideWindow} task(s) never synced fall outside the sync window — run '/kankaku sync all' to upload them`);
-      }
-      if (state?.lastError) lines.push(`last error: ${state.lastError.message} (at ${state.lastError.at})`);
-      showReport(ctx, { title: "sync status", lines });
+      showReport(ctx, { title: "sync status", lines: buildSyncStatusLines(sync.status()) });
       return;
     }
 
@@ -400,7 +553,7 @@ export function registerKankakuCommand(pi: ExtensionAPI, deps: KankakuCommandDep
 
     const full = rest[0] === "all";
     const summary = await sync.run({ full });
-    showReport(ctx, { title: full ? "sync (all)" : "sync", lines: formatSyncSummary(summary) });
+    showReport(ctx, { title: full ? "sync (all)" : "sync", lines: formatSyncSummaryLines(summary) });
   }
 
   /** Handle `/kankaku backfill`: a full sync, reported as the "Sin determinar" breakdown that needs reassigning in the web. */
@@ -412,161 +565,16 @@ export function registerKankakuCommand(pi: ExtensionAPI, deps: KankakuCommandDep
     }
 
     const summary = await sync.run({ full: true });
-    const unassignedEntries = Object.entries(summary.unassigned).sort(([a], [b]) => a.localeCompare(b));
-
-    const lines =
-      unassignedEntries.length > 0
-        ? [
-            ...unassignedEntries.map(([label, count]) => `${label}: ${count} task(s) -> Sin determinar`),
-            "reassign these in the hub web app's unassigned queue",
-          ]
-        : ["no unassigned tasks"];
-
-    if (summary.error) lines.push(`stopped early: ${summary.error}`);
-    showReport(ctx, { title: "backfill", lines });
+    showReport(ctx, { title: "backfill", lines: formatBackfillLines(summary) });
   }
 
   /**
-   * Handle `/kankaku doctor`: a no-network diagnostic (SUBAGENT-REQ-017)
-   * reporting orphan/uncertain record counts (ADR 0022) with why, and
-   * whether ancestor-chain detection is available on this platform, so
-   * silent undercount stays visible (see README "Subagents").
+   * Handle `/kankaku doctor`: builds the lines (shared with the panel's
+   * doctor screen — see {@link buildDoctorLines}) and shows them as the
+   * durable report.
    */
   function handleDoctorCommand(ctx: ExtensionContext): void {
-    const records = log.readAll();
-    const orphans = orphanSubagents(records);
-    const uncertain = uncertainRecords(records);
-    const ancestorDetectionAvailable = deps.ancestorDetectionAvailable ? deps.ancestorDetectionAvailable() : process.platform !== "win32";
-
-    const lines = [
-      `ancestor-chain detection: ${ancestorDetectionAvailable ? "available" : "unavailable"}`,
-      `orphan subagent record(s): ${orphans.length}` +
-        (orphans.length > 0 ? " — recognised as someone's child (an env marker matched), but no orchestrator could be matched" : ""),
-      `uncertain record(s): ${uncertain.length}` +
-        (uncertain.length > 0
-          ? " — no recognised child-env-marker, but a live tracked ancestor process was found; not counted as a new task, not synced"
-          : ""),
-    ];
-
-    if (!ancestorDetectionAvailable) {
-      lines.push(
-        "on this platform/environment, ancestor-chain detection could not run (Windows, or a failed/unavailable ps/proc read): " +
-          "an unmarked subagent system may be counted twice (a genuine child with no recognised marker looks like a fresh top-level " +
-          "session). Mark it explicitly with KANKAKU_ROLE=subagent in the child's environment (or KANKAKU_ROLE=orchestrator to force " +
-          "the other way).",
-      );
-    }
-
-    if (deps.roleOverride) {
-      if (deps.childMarkerPresent) {
-        // R1: both signals present — the confirmed child marker always
-        // wins (config.ts#detectRole), so the override did not decide
-        // anything, whatever it said.
-        lines.push(
-          `role override: KANKAKU_ROLE=${deps.roleOverride} was present, but the confirmed child marker (GENTLE_PI_AGENTS_CHILD=1) takes precedence — resolved role: subagent`,
-        );
-      } else if (deps.overrideIgnoredInteractive) {
-        lines.push(
-          "role override: KANKAKU_ROLE=subagent was ignored for this interactive session (likely a leaked shell export) — resolved role: orchestrator",
-        );
-      } else {
-        lines.push(`role override: KANKAKU_ROLE=${deps.roleOverride} (deciding signal for this process's role)`);
-      }
-    }
-
-    // C2 item 2/3: a configured child-env marker matched but was ignored
-    // for this process's role because it looked interactive — a
-    // configured marker, unlike a built-in one, never demotes an
-    // interactive session. Escalated when this process also has no
-    // tracked ancestor at all (C2 item 3's self-check: the strongest
-    // signal the marker is genuinely ambient, not a real subagent
-    // mechanism).
-    if (deps.configuredMarkerIgnoredInteractive) {
-      lines.push(
-        deps.hasTrackedAncestor
-          ? "configured marker: a KANKAKU_SUBAGENT_CHILD_ENV marker was present but ignored for this interactive session — resolved role: orchestrator"
-          : "configured marker: a KANKAKU_SUBAGENT_CHILD_ENV marker was present on this interactive, TOP-LEVEL session (no tracked ancestor) — the marker is likely ambient (set on every process of its kind, not just a subagent's child), not a real subagent mechanism; resolved role: orchestrator",
-      );
-    }
-
-    // C2 item 1: markers rejected at config load time as looking
-    // pi/shell/OS/npm-owned rather than genuinely child-only.
-    if (deps.rejectedSubagentChildEnvMarkers && deps.rejectedSubagentChildEnvMarkers.length > 0) {
-      for (const rejected of deps.rejectedSubagentChildEnvMarkers) {
-        lines.push(`rejected KANKAKU_SUBAGENT_CHILD_ENV marker "${rejected.name}": ${rejected.reason}`);
-      }
-    }
-
-    // SUBAGENT-REQ-001/002/003/005/017 (6b): active profiles, any configured
-    // tool names/markers, which profile matched each subagent record, and
-    // any tool-name ambiguity among the active set. Omitted entirely when
-    // deps.subagentProfiles was not wired (back-compat).
-    if (deps.subagentProfiles) {
-      const profiles = deps.subagentProfiles;
-      lines.push(`subagent profiles active: ${profiles.map((p) => p.id).join(", ")}`);
-
-      const configured = profiles.find((p) => p.id === "configured");
-      if (configured) {
-        if (configured.toolNames.length > 0) lines.push(`configured subagent tools: ${configured.toolNames.join(", ")}`);
-        if (configured.childEnvMarkers.length > 0) {
-          lines.push(`configured child-env markers: ${configured.childEnvMarkers.map((m) => (m.value !== undefined ? `${m.name}=${m.value}` : m.name)).join(", ")}`);
-        }
-      }
-
-      const subagentRecords = records.filter((record) => record.role === "subagent");
-      if (subagentRecords.length > 0) {
-        const counts = new Map<string, number>();
-        let unmatched = 0;
-        for (const record of subagentRecords) {
-          if (record.profile) {
-            counts.set(record.profile, (counts.get(record.profile) ?? 0) + 1);
-          } else {
-            unmatched++;
-          }
-        }
-        const parts = profiles.filter((p) => counts.has(p.id)).map((p) => `${p.id}: ${counts.get(p.id)}`);
-        if (unmatched > 0) parts.push(`unmatched: ${unmatched}`);
-        lines.push(`profile matches: ${parts.join(", ")}`);
-      }
-
-      for (const { toolName, profileIds } of findAmbiguousToolNames(profiles)) {
-        lines.push(`ambiguous tool name "${toolName}": registered by ${profileIds.join(", ")} — never guessed, resolved by child-env marker or left uncertain`);
-      }
-    }
-
-    // SUBAGENT-REQ-015 (6c): same-pid overlapping orchestrator records —
-    // never observed from any real subagent mechanism today, but flagged
-    // here (informational only, never changing buildTasks' own numbers) as
-    // the observable signature an in-process nested session would leave.
-    for (const overlap of detectSameProcessOverlaps(records)) {
-      lines.push(
-        `likely in-process nesting: pid ${overlap.pid} has ${overlap.recordIds.length} overlapping orchestrator records (${overlap.recordIds.join(", ")}) — union of their wall time is ${overlap.unionedWallMs}ms`,
-      );
-    }
-
-    if (deps.workLogRouting?.usedFallback) {
-      lines.push(
-        `kankaku: this subagent could not write to its orchestrator's directory (${deps.workLogRouting.parentDir}); ` +
-          "fell back to its own local worklog — this record may show as an orphan until reunited manually",
-      );
-    }
-
-    if (deps.registryHealth) {
-      const { keep, discard } = deps.registryHealth();
-      const counts = new Map<string, number>();
-      for (const { reason } of discard) counts.set(reason, (counts.get(reason) ?? 0) + 1);
-      const byReason = Array.from(counts.entries())
-        .map(([reason, count]) => `${reason}: ${count}`)
-        .join(", ");
-      lines.push(`registry (~/.kankaku/run): ${keep.length} entrie(s) trusted${discard.length > 0 ? `, ${discard.length} discarded (${byReason})` : ""}`);
-    }
-
-    const sessionDir = readNonDefaultSessionDir(ctx.sessionManager);
-    if (sessionDir !== undefined) {
-      lines.push(`session dir (non-default): ${sessionDir}`);
-    }
-
-    showReport(ctx, { title: "doctor", lines });
+    showReport(ctx, { title: "doctor", lines: buildDoctorLines(deps, ctx) });
   }
 
   /** Handle `/kankaku export [csv|json] [all]`; `rest` excludes the leading `export` token. Default format is csv. */
@@ -578,14 +586,9 @@ export function registerKankakuCommand(pi: ExtensionAPI, deps: KankakuCommandDep
 
     const all = rest.includes("all");
     const format: "csv" | "json" = rest.includes("json") ? "json" : "csv";
-    const records = log.readAll();
-    const today = localDay(new Date().toISOString());
-    const tasks = buildTasks(records).filter((task) => all || localDay(task.startedAt) === today);
-    const rows = exportRows(tasks);
-    const content = format === "json" ? toJson(rows) : toCsv(rows);
-    const name = `tasks-${all ? "all" : today}.${format}`;
+    const { name, content, rowCount } = buildExportContent(log.readAll(), { format, all });
     const path = deps.writeExportFile(name, content);
-    showReport(ctx, { title: "export", lines: [`wrote ${rows.length} row(s) to ${path}`] });
+    showReport(ctx, { title: "export", lines: [`wrote ${rowCount} row(s) to ${path}`] });
   }
 
   pi.registerCommand("kankaku", {
@@ -598,6 +601,8 @@ export function registerKankakuCommand(pi: ExtensionAPI, deps: KankakuCommandDep
       "'doctor' to report orphan/uncertain subagent counts and ancestor-detection availability (no network). " +
       "When a hub (PocketBase) is configured: 'target' to show the effective client/project and its source, " +
       "'target pick' to run the picker again, 'target clear' to clear the session target, " +
+      "'task' (or 'task pick') to link this session to an open/doing hub task of the effective project, " +
+      "'task clear' to drop the link, " +
       "'catalog refresh' to force a catalog refresh, 'projects' for per-project totals today ('projects all' for every day), " +
       "'sync' to push pending tasks to the hub ('sync all' for a full re-evaluation, 'sync status' for the watermark/pending count/last error), " +
       "'backfill' to run a full sync and report how many tasks went to Sin determinar, grouped by their old label. " +
@@ -615,6 +620,11 @@ export function registerKankakuCommand(pi: ExtensionAPI, deps: KankakuCommandDep
         const prefix = targetMatch[1] ?? "";
         return TARGET_TOKENS.filter((value) => value.startsWith(prefix)).map((value) => ({ value, label: value }));
       }
+      const taskMatch = /^task\s+(\S*)$/.exec(argumentPrefix);
+      if (taskMatch) {
+        const prefix = taskMatch[1] ?? "";
+        return TASK_TOKENS.filter((value) => value.startsWith(prefix)).map((value) => ({ value, label: value }));
+      }
       const catalogMatch = /^catalog\s+(\S*)$/.exec(argumentPrefix);
       if (catalogMatch) {
         const prefix = catalogMatch[1] ?? "";
@@ -647,6 +657,11 @@ export function registerKankakuCommand(pi: ExtensionAPI, deps: KankakuCommandDep
           return;
         }
 
+        if (tokens[0] === "task") {
+          await handleTaskCommand(tokens.slice(1), ctx);
+          return;
+        }
+
         if (tokens[0] === "catalog") {
           await handleCatalogCommand(tokens.slice(1), ctx);
           return;
@@ -667,58 +682,35 @@ export function registerKankakuCommand(pi: ExtensionAPI, deps: KankakuCommandDep
           return;
         }
 
+        if (tokens.length === 0 && ctx.hasUI && deps.openPanel) {
+          await deps.openPanel(ctx);
+          return;
+        }
+
         const all = tokens.includes("all");
         const records = log.readAll();
-        const today = localDay(new Date().toISOString());
 
         if (tokens.includes("clients")) {
-          const tasks = buildTasks(records).filter((task) => all || localDay(task.startedAt) === today);
-          showReport(ctx, {
-            title: all ? "clients (all days)" : "clients (today)",
-            lines: formatClients(summarizeByClient(tasks)).split("\n"),
-          });
+          showReport(ctx, buildClientsView(records, { all }));
           return;
         }
 
         if (tokens.includes("projects")) {
-          const tasks = buildTasks(records).filter((task) => all || localDay(task.startedAt) === today);
-          showReport(ctx, {
-            title: all ? "projects (all days)" : "projects (today)",
-            lines: formatProjects(summarizeByProject(tasks)).split("\n"),
-          });
+          showReport(ctx, buildProjectsView(records, { all }));
           return;
         }
 
         if (tokens.includes("tasks")) {
-          const sessionId = ctx.sessionManager.getSessionId();
-          const scoped = all || !sessionId;
-          const tasks = buildTasks(records).filter((task) => scoped || task.sessionId === sessionId);
-          showReport(ctx, {
-            title: scoped ? "tasks (every session)" : "tasks (this session)",
-            lines: formatTasks(tasks).split("\n"),
-          });
+          showReport(ctx, buildTasksView(records, { all, sessionId: ctx.sessionManager.getSessionId() }));
           return;
         }
 
         if (tokens.includes("sessions")) {
-          const tasks = buildTasks(records).filter((task) => all || localDay(task.startedAt) === today);
-          showReport(ctx, {
-            title: all ? "sessions (all days)" : "sessions (today)",
-            lines: formatSessions(buildSessions(tasks)).split("\n"),
-          });
+          showReport(ctx, buildSessionsView(records, { all }));
           return;
         }
 
-        const summary = summarize(records, { all });
-        const lines = formatReport(summary).split(" | ");
-        const uncertainCount = countUncertain(records, { all });
-        if (uncertainCount > 0) {
-          lines.push(`kankaku: ${uncertainCount} uncertain record(s) excluded from tasks — run /kankaku doctor`);
-        }
-        showReport(ctx, {
-          title: all ? "summary (all days)" : "summary (today)",
-          lines,
-        });
+        showReport(ctx, buildSummaryView(records, { all }));
       } catch (error) {
         notifyError(ctx, error);
       }