kankaku 0.7.0 → 0.8.0

package/src/adapters/hub-actions.ts

@@ -6,15 +6,14 @@
  * see odd/tasks/kankaku-panel.md P4.
  */
 import type { CatalogSnapshot } from "../ports/catalog.ts";
-import type { SyncCommandDeps } from "./kankaku-command.ts";
-import type { SyncSummary } from "./sync-runner.ts";
+import type { SyncStatusSnapshot, SyncSummary } from "./sync-runner.ts";
 
 /**
  * `/kankaku sync status`'s report lines: the watermark, the pending count,
  * how many tasks fell outside this run's revisit window (R3), and the last
  * error, when any. Exact body of `handleSyncCommand`'s `status` branch.
  */
-export function buildSyncStatusLines(status: ReturnType<SyncCommandDeps["status"]>): string[] {
+export function buildSyncStatusLines(status: SyncStatusSnapshot): string[] {
   const { state, pending, staleOutsideWindow } = status;
   const lines = [state?.syncedThrough ? `synced through ${state.syncedThrough}` : "never synced", `pending: ${pending}`];
   if (staleOutsideWindow > 0) {

package/src/adapters/kankaku-command.ts

@@ -7,24 +7,20 @@ import { formatWorkTargetLabel } from "../domain/work-target.ts";
 import { findAmbiguousToolNames } from "../domain/subagent-profile.ts";
 import type { SubagentProfile } from "../domain/subagent-profile.ts";
 import type { RejectedChildEnvMarker } from "../config.ts";
-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 type { SyncStatusSnapshot, SyncSummary, SyncTrigger } from "./sync-runner.ts";
 import type { SessionClient } from "./session-client.ts";
 import { readNonDefaultSessionDir } from "./session-dir.ts";
 import type { SessionTarget } from "./session-target.ts";
+import type { KankakuReportData } from "./report-data.ts";
 
-const REPORT_ENTRY_TYPE = "kankaku-report";
+export type { KankakuReportData } from "./report-data.ts";
 
-/** Durable report rendered inside the chat transcript; never sent to the LLM. */
-export interface KankakuReportData {
-  title: string;
-  lines: string[];
-}
+const REPORT_ENTRY_TYPE = "kankaku-report";
 
 /** Notify the user of an error through the UI, when one is available. */
 export function notifyError(ctx: ExtensionContext, error: unknown): void {
@@ -217,7 +213,7 @@ export interface SyncCommandDeps {
    * count, and (R3) how many tasks changed since their last sync but fall
    * outside this run's revisit window — needs `sync all`. No network.
    */
-  status: () => { state: SyncState | undefined; pending: number; staleOutsideWindow: number };
+  status: () => SyncStatusSnapshot;
 }
 
 export interface KankakuCommandDeps {

package/src/adapters/panel/kankaku-panel.ts

@@ -12,7 +12,7 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import type { Component, TUI, TuiMouseEvent, TuiMouseEventResult } from "@earendil-works/pi-tui";
-import { Key, matchesKey, SelectList, Text, visibleWidth } from "@earendil-works/pi-tui";
+import { Key, matchesKey, SelectList, Text, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import type { SelectItem } from "@earendil-works/pi-tui";
 import { footerHints, navBack, navCurrent, navPush, navRoot, panelTitle, rootMenu } from "../../domain/panel-model.ts";
 import type { PanelHint, PanelNav, PanelScreenId } from "../../domain/panel-model.ts";
@@ -38,6 +38,19 @@ export interface PanelHost {
    * `screens/target.ts`'s legacy-label submenu).
    */
   setBodyWantsText(flag: boolean): void;
+  /**
+   * Set (or clear) whether the current body owns Escape (a submenu or text
+   * field is open and must see it before the shell does — e.g. the target
+   * screen's client/project/task submenus, its legacy-label `Input`, or an
+   * `actionItem`'s result view). The shell owns Escape (and left arrow) by
+   * default and pops the current screen itself: it never relies on
+   * pi-tui's `SettingsList`/`SelectList` `onCancel` firing on its own,
+   * since that path does not reliably fire in the real TUI (see
+   * `KankakuPanelComponent#handleInput`). A screen must reset this to
+   * `false` when the thing that captured Escape closes (see
+   * `screens/target.ts` and every `actionItem` call site).
+   */
+  setBodyCapturesEscape(flag: boolean): void;
 }
 
 export interface KankakuPanelDeps {
@@ -54,6 +67,47 @@ interface HintSpan {
 
 const HINT_SEPARATOR = " · ";
 
+/**
+ * Below this width the frame (border + one column of inner padding) no
+ * longer leaves room for any content, so `render` falls back to the
+ * unframed layout instead of throwing (see `KankakuPanelComponent#render`).
+ */
+const MIN_FRAME_WIDTH = 8;
+
+/** Columns the frame's left border ("│") and its one column of padding occupy, left of every inner/body row. */
+const FRAME_LEFT_PADDING = 2;
+
+/**
+ * Wraps `content` between the frame's left/right border (`│ ... │`),
+ * padding/truncating it to `innerWidth` first — ANSI-safe, via pi-tui's
+ * `truncateToWidth` (never raw string length; see the module doc).
+ */
+function frameLine(theme: Theme, content: string, innerWidth: number): string {
+  const left = theme.fg("border", "│ ");
+  const right = theme.fg("border", " │");
+  const padded = truncateToWidth(content, innerWidth, "…", true);
+  return `${left}${padded}${right}`;
+}
+
+/**
+ * The framed top border: `╭─ <title> ` then a `─` fill, then `╮`, sized to
+ * `width`. `titleStyled` keeps its own styling (bold/accent, applied by the
+ * caller); it is itself truncated (ANSI-aware) if the title cannot fit.
+ */
+function frameTop(theme: Theme, titleStyled: string, width: number): string {
+  const available = Math.max(0, width - 5); // "╭─ " + " " + "╮"
+  const title = truncateToWidth(titleStyled, available, "…", false);
+  const fillLen = Math.max(0, available - visibleWidth(title));
+  const left = theme.fg("border", "╭─ ");
+  const fill = theme.fg("border", `${"─".repeat(fillLen)}╮`);
+  return `${left}${title} ${fill}`;
+}
+
+/** The framed bottom border: `╰` + a `─` fill + `╯`, sized to `width`. */
+function frameBottom(theme: Theme, width: number): string {
+  return theme.fg("border", `╰${"─".repeat(Math.max(0, width - 2))}╯`);
+}
+
 /** Placeholder body for a screen id with no registered factory yet (P2–P4 fill these in). */
 function comingSoonBody(theme: Theme): PanelBody {
   return new Text(theme.fg("muted", "coming soon"));
@@ -105,11 +159,20 @@ class KankakuPanelComponent implements Component {
   private body: PanelBody;
   /** Set via `PanelHost.setBodyWantsText` by a screen that owns a text field (e.g. the target screen's legacy-label `Input`), so `q` types instead of closing. */
   private bodyWantsText = false;
+  /** Set via `PanelHost.setBodyCapturesEscape` by a screen whose body must see Escape/← itself (an open submenu or text field) before the shell pops the screen. */
+  private bodyCapturesEscape = false;
   private hints: PanelHint[] = [];
   private hintSpans: HintSpan[] = [];
   /** -1 until the first `render()`, so a mouse event that arrives before any render never mismatches row 0 for the footer. */
   private footerRowIndex = -1;
   private hoveredHintIndex: number | undefined;
+  /** Whether the last `render()` drew the frame (`width >= MIN_FRAME_WIDTH`) or fell back to the unframed layout. */
+  private framed = false;
+  /** -1 until the first `render()` draws the frame; the absolute row index of the body's first rendered line. */
+  private bodyRowStart = -1;
+  private bodyRowCount = 0;
+  /** The width last passed to `this.body.render(...)` (`width` unframed, `width - 4` framed), for shifted mouse events. */
+  private bodyWidth = 0;
 
   constructor(tui: TUI, theme: Theme, deps: KankakuPanelDeps, done: (result: void) => void) {
     this.tui = tui;
@@ -126,6 +189,9 @@ class KankakuPanelComponent implements Component {
       setBodyWantsText: (flag) => {
         this.bodyWantsText = flag;
       },
+      setBodyCapturesEscape: (flag) => {
+        this.bodyCapturesEscape = flag;
+      },
     };
     this.nav = navRoot();
     this.body = this.createBody("root");
@@ -148,6 +214,7 @@ class KankakuPanelComponent implements Component {
     this.nav = navPush(this.nav, id);
     this.body = this.createBody(id);
     this.bodyWantsText = false;
+    this.bodyCapturesEscape = false;
     this.hoveredHintIndex = undefined;
     this.tui.requestRender();
   }
@@ -162,6 +229,7 @@ class KankakuPanelComponent implements Component {
     this.nav = nav;
     this.body = this.createBody(navCurrent(nav));
     this.bodyWantsText = false;
+    this.bodyCapturesEscape = false;
     this.hoveredHintIndex = undefined;
     this.tui.requestRender();
   }
@@ -181,13 +249,27 @@ class KankakuPanelComponent implements Component {
 
   render(width: number): string[] {
     const screen = navCurrent(this.nav);
-    const lines: string[] = [];
-    lines.push(this.theme.bold(this.theme.fg("accent", panelTitle(screen))));
-    lines.push("");
-    lines.push(...this.body.render(width));
+    const titleStyled = this.theme.bold(this.theme.fg("accent", panelTitle(screen)));
+    this.hints = footerHints(screen, { searchable: this.body.searchable ?? false });
+
+    if (width < MIN_FRAME_WIDTH) {
+      return this.renderUnframed(width, titleStyled);
+    }
+    return this.renderFramed(width, titleStyled, screen);
+  }
+
+  /** Legacy, unframed layout: title, body at `width`, footer — used when `width` is too narrow to fit a frame (see `MIN_FRAME_WIDTH`). */
+  private renderUnframed(width: number, titleStyled: string): string[] {
+    this.framed = false;
+    const lines: string[] = [titleStyled, ""];
+
+    const bodyLines = this.body.render(width);
+    this.bodyRowStart = lines.length;
+    this.bodyRowCount = bodyLines.length;
+    this.bodyWidth = width;
+    lines.push(...bodyLines);
     lines.push("");
 
-    this.hints = footerHints(screen, { searchable: this.body.searchable ?? false });
     const { line, spans } = renderFooter(this.hints, this.theme, this.hoveredHintIndex);
     this.hintSpans = spans;
     this.footerRowIndex = lines.length;
@@ -196,19 +278,66 @@ class KankakuPanelComponent implements Component {
     return lines;
   }
 
+  /**
+   * Rounded frame around the panel (see the module's "no padding/border"
+   * feature doc, `odd/tasks/kankaku-panel.md`): a `╭─ <title> ─…─╮` top
+   * border, one blank inner line, the body rendered at `innerWidth`
+   * (`width - 4`), a blank inner line, the footer hints, and a `╰─…─╯`
+   * bottom border. Every inner line is `│ <content> │`.
+   */
+  private renderFramed(width: number, titleStyled: string, screen: PanelScreenId): string[] {
+    this.framed = true;
+    const innerWidth = width - 4;
+    const lines: string[] = [];
+
+    lines.push(frameTop(this.theme, titleStyled, width));
+    lines.push(frameLine(this.theme, "", innerWidth));
+
+    const bodyLines = this.body.render(innerWidth);
+    this.bodyRowStart = lines.length;
+    this.bodyRowCount = bodyLines.length;
+    this.bodyWidth = innerWidth;
+    for (const bodyLine of bodyLines) lines.push(frameLine(this.theme, bodyLine, innerWidth));
+
+    lines.push(frameLine(this.theme, "", innerWidth));
+
+    const { line, spans } = renderFooter(this.hints, this.theme, this.hoveredHintIndex);
+    // The footer's own hit-test spans are local to its (unframed) content;
+    // shift them by the left border + padding so they match the actual
+    // rendered column once wrapped in `frameLine`.
+    this.hintSpans = spans.map((span) => ({ start: span.start + FRAME_LEFT_PADDING, end: span.end + FRAME_LEFT_PADDING }));
+    this.footerRowIndex = lines.length;
+    lines.push(frameLine(this.theme, line, innerWidth));
+
+    lines.push(frameBottom(this.theme, width));
+
+    return lines;
+  }
+
   handleInput(data: string): void {
+    // The shell owns Escape and left arrow itself; it never relies on
+    // pi-tui's `SettingsList`/`SelectList` calling `onCancel` on its own
+    // (via `getKeybindings().matches(data, "tui.select.cancel")`) — that
+    // path does not reliably fire in the real TUI, which is the bug this
+    // guards against. Only when the current body has explicitly captured
+    // Escape (`PanelHost.setBodyCapturesEscape(true)` — an open submenu or
+    // text field that must see the key itself, e.g. the target screen's
+    // client/project/task submenus or its legacy-label `Input`) is the key
+    // forwarded; otherwise the shell pops the current screen directly.
     if (matchesKey(data, Key.escape)) {
-      // Forward escape to the body when it can handle input itself (a real
-      // `SettingsList`/`SelectList`-backed screen): pi-tui's own
-      // `SettingsList.handleInput`/`SelectList.handleInput` already close an
-      // open submenu on escape and fall through to the body's own
-      // `onCancel` only once no submenu remains — wired to `host.back()` by
-      // every real screen (the root `SelectList`, the target screen). Only
-      // a body with no `handleInput` at all (the placeholder "coming soon"
-      // `Text`, or a read-only note like the subagent target screen) has no
-      // way to react, so the shell pops the stack itself in that case.
-      if (this.body.handleInput) {
-        this.body.handleInput(data);
+      if (this.bodyCapturesEscape) {
+        this.body.handleInput?.(data);
+      } else {
+        this.goBack();
+      }
+      return;
+    }
+    if (matchesKey(data, Key.left)) {
+      if (this.bodyCapturesEscape) {
+        // Translate to the escape sequence so a captured body (which only
+        // ever wires up Escape, not left arrow) closes exactly as it would
+        // on Escape.
+        this.body.handleInput?.("\x1b");
       } else {
         this.goBack();
       }
@@ -225,7 +354,21 @@ class KankakuPanelComponent implements Component {
     if (event.y === this.footerRowIndex) {
       return this.handleFooterMouse(event);
     }
-    return this.body.handleMouse?.(event);
+    if (!this.framed) {
+      // Legacy, unframed layout: any non-footer row delegates as-is.
+      return this.body.handleMouse?.(event);
+    }
+    const bodyRowEnd = this.bodyRowStart + this.bodyRowCount;
+    if (event.y < this.bodyRowStart || event.y >= bodyRowEnd) {
+      // Frame border or blank padding row: nothing to delegate to.
+      return undefined;
+    }
+    return this.body.handleMouse?.({
+      ...event,
+      x: event.x - FRAME_LEFT_PADDING,
+      y: event.y - this.bodyRowStart,
+      width: this.bodyWidth,
+    });
   }
 
   private handleFooterMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined {
@@ -241,7 +384,9 @@ class KankakuPanelComponent implements Component {
 
     if (event.type === "click" && event.button === "left" && hitIndex !== -1) {
       const hint = this.hints[hitIndex]!;
-      if (hint.key === "esc") {
+      // "esc" at root, "esc/←" on every other screen (see `footerHints`) —
+      // `goBack()` already closes the panel outright when at root.
+      if (hint.key.startsWith("esc")) {
         this.goBack();
         return { handled: true };
       }

package/src/adapters/panel/panel-items.ts

@@ -18,6 +18,10 @@ export interface ActionItemOptions {
   run: () => string[] | Promise<string[]>;
   /** Called once `run()` settles (success or error), so the caller can re-render — this component has no `host` reference of its own. */
   onDone?: () => void;
+  /** Called synchronously when the submenu component is created (the action starts running). */
+  onOpen?: () => void;
+  /** Called right before `done(...)` is invoked on close (Enter or Escape), so the caller can, e.g., clear `PanelHost.setBodyCapturesEscape`. */
+  onClose?: () => void;
 }
 
 class ActionItemComponent implements Component {
@@ -35,6 +39,7 @@ class ActionItemComponent implements Component {
     this.theme = theme;
     this.options = options;
     this.done = done;
+    this.options.onOpen?.();
     void this.start();
   }
 
@@ -58,9 +63,14 @@ class ActionItemComponent implements Component {
 
   handleInput(data: string): void {
     if (matchesKey(data, Key.enter) || matchesKey(data, Key.escape)) {
-      // Keep the cursor on the row that opened this action — the caller
-      // (the enclosing SettingsList) restores selection to it by id.
-      this.done(undefined, { navigateTo: this.options.id });
+      this.options.onClose?.();
+      // Close with NO `navigateTo`: pi-tui's `SettingsList.closeSubmenu`
+      // treats `navigateTo` as "select that row and activate it", and
+      // activating this row opens its submenu again — the result would
+      // reopen and the action re-run on every Enter/Escape, leaving the
+      // user stuck until `q`. Without it the list restores the cursor to
+      // the row that opened the submenu on its own (`submenuItemIndex`).
+      this.done();
     }
   }
 }

package/src/adapters/panel/screens/doctor.ts

@@ -47,6 +47,8 @@ class DoctorScreenComponent implements Component {
           this.deps.pinReport({ title: "doctor", lines: this.lines });
           return ["pinned to the chat transcript"];
         },
+        onOpen: () => this.host.setBodyCapturesEscape(true),
+        onClose: () => this.host.setBodyCapturesEscape(false),
         onDone: () => this.host.requestRender(),
       }),
       actionItem(this.settingsTheme, {
@@ -56,6 +58,8 @@ class DoctorScreenComponent implements Component {
           this.lines = buildDoctorLines(this.deps.commandDeps, this.deps.ctx);
           return ["refreshed"];
         },
+        onOpen: () => this.host.setBodyCapturesEscape(true),
+        onClose: () => this.host.setBodyCapturesEscape(false),
         onDone: () => this.host.requestRender(),
       }),
     ];

package/src/adapters/panel/screens/export.ts

@@ -70,6 +70,8 @@ class ExportScreenComponent implements Component {
           this.lastNote = `wrote ${path}`;
           return [this.lastNote];
         },
+        onOpen: () => this.host.setBodyCapturesEscape(true),
+        onClose: () => this.host.setBodyCapturesEscape(false),
         onDone: () => this.host.requestRender(),
       }),
       actionItem(this.settingsTheme, {
@@ -79,6 +81,8 @@ class ExportScreenComponent implements Component {
           this.deps.pinReport({ title: "export", lines: [this.lastNote] });
           return ["pinned to the chat transcript"];
         },
+        onOpen: () => this.host.setBodyCapturesEscape(true),
+        onClose: () => this.host.setBodyCapturesEscape(false),
         onDone: () => this.host.requestRender(),
       }),
     ];

package/src/adapters/panel/screens/report.ts

@@ -99,6 +99,8 @@ class ReportScreenComponent implements Component {
           this.deps.pinReport(this.report);
           return ["pinned to the chat transcript"];
         },
+        onOpen: () => this.host.setBodyCapturesEscape(true),
+        onClose: () => this.host.setBodyCapturesEscape(false),
         onDone: () => this.host.requestRender(),
       }),
     ];

package/src/adapters/panel/screens/sync.ts

@@ -60,18 +60,24 @@ class SyncScreenComponent implements Component {
         id: "sync-now",
         label: "Sync now",
         run: async () => formatSyncSummaryLines(await this.deps.sync.run({})),
+        onOpen: () => this.host.setBodyCapturesEscape(true),
+        onClose: () => this.host.setBodyCapturesEscape(false),
         onDone: () => this.refreshStatus(),
       }),
       actionItem(this.settingsTheme, {
         id: "sync-all",
         label: "Sync all",
         run: async () => formatSyncSummaryLines(await this.deps.sync.run({ full: true })),
+        onOpen: () => this.host.setBodyCapturesEscape(true),
+        onClose: () => this.host.setBodyCapturesEscape(false),
         onDone: () => this.refreshStatus(),
       }),
       actionItem(this.settingsTheme, {
         id: "backfill",
         label: "Backfill",
         run: async () => formatBackfillLines(await this.deps.sync.run({ full: true })),
+        onOpen: () => this.host.setBodyCapturesEscape(true),
+        onClose: () => this.host.setBodyCapturesEscape(false),
         onDone: () => this.refreshStatus(),
       }),
     ];
@@ -83,6 +89,8 @@ class SyncScreenComponent implements Component {
           id: "catalog-refresh",
           label: "Refresh catalog",
           run: async () => formatCatalogRefreshLines(await catalog.refresh()),
+          onOpen: () => this.host.setBodyCapturesEscape(true),
+          onClose: () => this.host.setBodyCapturesEscape(false),
           onDone: () => this.refreshStatus(),
         }),
       );
@@ -96,6 +104,8 @@ class SyncScreenComponent implements Component {
           this.deps.pinReport({ title: STATUS_TITLE, lines: this.statusLines });
           return ["pinned to the chat transcript"];
         },
+        onOpen: () => this.host.setBodyCapturesEscape(true),
+        onClose: () => this.host.setBodyCapturesEscape(false),
         onDone: () => this.host.requestRender(),
       }),
     );

package/src/adapters/panel/screens/target.ts

@@ -235,10 +235,25 @@ class TargetScreenComponent implements Component {
     return { id: row.id, label: row.label, currentValue: row.value, ...(row.description !== undefined ? { description: row.description } : {}) };
   }
 
+  /**
+   * Wraps a row's submenu factory so opening it sets
+   * `PanelHost.setBodyCapturesEscape(true)` (the shell forwards Escape/←
+   * to this screen instead of popping it while the submenu — or the
+   * legacy-label `Input`, which also uses this via `buildLegacySubmenu` —
+   * is open) and clears it again right before the submenu's own `done` is
+   * invoked, on every close path (a pick, "— use defaults —"/"— none —",
+   * cancel, or a disabled note closing on any key).
+   */
   private rowItem(row: PanelRow, submenu: (done: (selectedValue?: string, options?: { navigateTo?: string }) => void) => Component): SettingItem {
     return {
       ...this.plainItem(row),
-      submenu: (_currentValue, done) => submenu(done),
+      submenu: (_currentValue, done) => {
+        this.host.setBodyCapturesEscape(true);
+        return submenu((selectedValue, options) => {
+          this.host.setBodyCapturesEscape(false);
+          done(selectedValue, options);
+        });
+      },
     };
   }
 
@@ -320,6 +335,8 @@ class TargetScreenComponent implements Component {
         const saved = this.deps.sessionTarget?.rememberTarget() ?? false;
         return [saved ? "saved clientId/projectId to config.json" : "nothing to save"];
       },
+      onOpen: () => this.host.setBodyCapturesEscape(true),
+      onClose: () => this.host.setBodyCapturesEscape(false),
       onDone: () => this.host.requestRender(),
     });
     return { ...item, currentValue: row.value };

package/src/adapters/pi-tracker.ts

@@ -496,6 +496,14 @@ export function createPiTracker(pi: ExtensionAPI, deps: PiTrackerDeps): void {
       ...(roleConfidence !== undefined ? { roleConfidence } : {}),
       ...(deps.orchestratorRef !== undefined ? { orchestratorRef: deps.orchestratorRef } : {}),
       ...(deps.profile !== undefined ? { profile: deps.profile } : {}),
+      // Who measured this record, not who later syncs it — see
+      // `domain/work-record.ts#WorkRecordMetadata.agent`. Always stamped for
+      // every record this process appends; the versions are the same ones
+      // `extension.ts` already resolves for the `about` screen.
+      agent: "pi",
+      ...(deps.agentVersion !== undefined ? { agentVersion: deps.agentVersion } : {}),
+      plugin: "kankaku",
+      ...(deps.pluginVersion !== undefined ? { pluginVersion: deps.pluginVersion } : {}),
     };
   }
 

package/src/adapters/report-data.ts

@@ -0,0 +1,13 @@
+/**
+ * Pi-free home for {@link KankakuReportData}, the shape every `/kankaku`
+ * report view and the panel's report screen produce. Extracted out of
+ * `kankaku-command.ts` (which still re-exports it) so `report-views.ts` can
+ * be published through `kankaku/hub` without pulling in anything that
+ * touches `@earendil-works/*` — see AGENTS.md "Code conventions".
+ */
+
+/** Durable report rendered inside the chat transcript; never sent to the LLM. */
+export interface KankakuReportData {
+  title: string;
+  lines: string[];
+}

package/src/adapters/report-views.ts

@@ -9,7 +9,7 @@
 import { buildSessions, buildTasks } from "../domain/task-view.ts";
 import { exportRows, toCsv, toJson } from "../domain/export.ts";
 import type { WorkRecord } from "../domain/work-record.ts";
-import type { KankakuReportData } from "./kankaku-command.ts";
+import type { KankakuReportData } from "./report-data.ts";
 import { countUncertain, formatClients, formatProjects, formatReport, formatSessions, formatTasks, localDay, summarize, summarizeByClient, summarizeByProject } from "./report.ts";
 
 /** Shared by every view except `buildTasksView`: `all` includes every day, otherwise only today's local day. */

package/src/adapters/sync-runner.ts

@@ -250,12 +250,31 @@ function persistError(deps: SyncRunnerDeps, state: ReturnType<SyncStateStore["re
   });
 }
 
-/** Number of tasks pending a sync right now, for `/kankaku sync status` — computed locally, no network. */
+/**
+ * Number of tasks pending a sync right now — computed locally, no network.
+ *
+ * @deprecated Superseded by {@link computeSyncStatus}, which returns the same
+ * `pending` count together with `state` and `staleOutsideWindow`. Nothing in
+ * kankaku calls this any more; it stays only because it is part of the
+ * published `kankaku/hub` surface. It will be removed in the next minor.
+ */
 export function pendingCount(tasks: TaskView[], state: ReturnType<SyncStateStore["read"]>, target: string, windowHours?: number): number {
   const plan = planSync(tasks, state, { target, ...(windowHours !== undefined ? { windowHours } : {}) });
   return plan.toSync.length + plan.correctionsDeferred;
 }
 
+/**
+ * {@link computeSyncStatus}'s return shape, exported so a caller (e.g.
+ * `hub-actions.ts#buildSyncStatusLines`, or a future standalone TUI reusing
+ * `kankaku/hub`) can depend on this type without importing anything that
+ * touches `@earendil-works/*` — see AGENTS.md "Code conventions".
+ */
+export interface SyncStatusSnapshot {
+  state: SyncState | undefined;
+  pending: number;
+  staleOutsideWindow: number;
+}
+
 /**
  * `/kankaku sync status`: the persisted state, a locally-computed pending
  * count, and (R3) how many tasks changed since their last sync but fall
@@ -263,12 +282,7 @@ export function pendingCount(tasks: TaskView[], state: ReturnType<SyncStateStore
  * (see `domain/sync-plan.ts#SyncPlan.staleOutsideWindow`, and README "Hub
  * (PocketBase)" > "Sync" > "Limitations"). No network.
  */
-export function computeSyncStatus(
-  log: WorkLog,
-  stateStore: SyncStateStore,
-  target: string,
-  windowHours?: number,
-): { state: ReturnType<SyncStateStore["read"]>; pending: number; staleOutsideWindow: number } {
+export function computeSyncStatus(log: WorkLog, stateStore: SyncStateStore, target: string, windowHours?: number): SyncStatusSnapshot {
   const state = stateStore.read();
   const tasks = buildTasks(log.readAll());
   const plan = planSync(tasks, state, { target, ...(windowHours !== undefined ? { windowHours } : {}) });