kankaku 0.5.0 → 0.5.1

package/README.md

@@ -804,7 +804,9 @@ On `session_start`, for the orchestrator role with a UI available:
    sorted by name, plus "— skip —"), then for the project (active projects
    of that client, plus "(no project)" and "— skip —"). Declining at either
    step — "— skip —" or dismissing the dialog — cancels the whole pick and
-   is remembered for the session.
+   is remembered for the session. The picker shows the freshly refreshed
+   catalog when the hub answered within the deadline described in "Caching
+   and offline behaviour" below; otherwise it falls back to the cache.
 
 After a pick, kankaku asks whether to remember it for this repository; a
 "yes" merges `clientId`/`projectId` into `<KANKAKU_DIR>/config.json`.
@@ -826,19 +828,36 @@ a project) in place of the legacy client label, both idle and during a run.
 ### Caching and offline behaviour
 
 The catalog (clients/projects) is cached machine-wide at
-`~/.kankaku/catalog.json` with a 6-hour TTL. On startup: a fresh cache is
-used as-is; a stale cache is used immediately while a refresh happens in
-the background; when there is no cache at all, one refresh is awaited
-(bounded by the hub client's own request timeout, 3s by default) before
-falling back. If the hub is unreachable and there is no cache, kankaku
-notifies once (`kankaku: hub unreachable, using local labels`) and
-continues exactly as it would without a hub configured. `/kankaku catalog
-refresh` forces a refresh on demand. The cache file is always written
-owner-only (`0600`); if kankaku is the first thing to ever create
-`~/.kankaku` itself (no project has put its own `.kankaku` there), the
-directory is created owner-only (`0700`) too — but an already-existing
-`~/.kankaku` is never chmod'd, since it may be a project's own kankaku
-directory (see "The registry" below for the same rule applied to `run/`).
+`~/.kankaku/catalog.json`. On `session_start`, for the orchestrator role
+with a UI available, kankaku always starts a background refresh when a
+cache already exists — regardless of the cache's age — so a client or
+project created in the hub minutes ago shows up without waiting for a TTL
+to expire (the 6-hour TTL and `isStale()` still exist and still gate other
+callers, but session start no longer depends on them). If the target
+resolves silently from the project config file or `repo_paths` against
+the cached snapshot, `ensurePicked` returns immediately without waiting
+for that refresh at all; it keeps running in the background and
+`catalog.read()` reflects it once it lands, exactly as before. Only when
+the picker is actually about to be shown does kankaku wait for the
+in-flight refresh, bounded by a short deadline (1.5s by default,
+`pickerRefreshDeadlineMs`): if the hub answers in time, the picker offers
+the fresh clients/projects; otherwise (or if the refresh fails) it falls
+back to the cached snapshot silently, and the refresh keeps running
+in the background rather than being aborted. `/kankaku target pick` (the
+explicit re-pick command) follows the same wait-then-fall-back rule. When
+there is no cache at all, one refresh is still awaited (bounded by the hub
+client's own request timeout, 3s by default) before falling back — this
+path is unchanged. If the hub is unreachable and there is no cache,
+kankaku notifies once (`kankaku: hub unreachable, using local labels`) and
+continues exactly as it would without a hub configured; a background
+refresh that merely fails once a cache already exists is silent, with no
+notification. `/kankaku catalog refresh` still forces a refresh on demand
+independently of any of this. The cache file is always written owner-only
+(`0600`); if kankaku is the first thing to ever create `~/.kankaku` itself
+(no project has put its own `.kankaku` there), the directory is created
+owner-only (`0700`) too — but an already-existing `~/.kankaku` is never
+chmod'd, since it may be a project's own kankaku directory (see "The
+registry" below for the same rule applied to `run/`).
 
 ### Privacy (catalog)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kankaku",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "pi extension that records agent work time per prompt, excluding waits for the user, with subagent linkage and task/session views",
   "license": "MIT",
   "author": "soyunninja",

package/src/adapters/session-target.ts

@@ -32,12 +32,21 @@ export interface SessionTargetDeps {
    * per-request. Defaults to 5000.
    */
   firstFetchDeadlineMs?: number;
+  /**
+   * Deadline, in ms, for awaiting an already-in-flight background refresh
+   * before showing the picker with the cached snapshot instead — see
+   * {@link getSnapshotForPicker}. The refresh itself is never aborted at
+   * this deadline; it keeps running, and a later `catalog.read()` call
+   * (e.g. the next run) sees its result once it lands. Defaults to 1500.
+   */
+  pickerRefreshDeadlineMs?: 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;
+const DEFAULT_PICKER_REFRESH_DEADLINE_MS = 1500;
 
 export interface SessionTarget {
   /** Restore the session-level target (or its remembered "skipped" state) from the last `kankaku-target` entry. */
@@ -86,6 +95,7 @@ export function createSessionTarget(deps: SessionTargetDeps): SessionTarget {
   const scheduleTimeout = deps.setTimeout ?? setTimeout;
   const cancelTimeout = deps.clearTimeout ?? clearTimeout;
   const firstFetchDeadlineMs = deps.firstFetchDeadlineMs ?? DEFAULT_FIRST_FETCH_DEADLINE_MS;
+  const pickerRefreshDeadlineMs = deps.pickerRefreshDeadlineMs ?? DEFAULT_PICKER_REFRESH_DEADLINE_MS;
 
   /** Session-level override, restored on `session_start` or set by an explicit pick/skip/legacy command. */
   let sessionOverride: WorkTargetSessionOverride;
@@ -166,30 +176,18 @@ export function createSessionTarget(deps: SessionTargetDeps): SessionTarget {
   }
 
   /**
-   * 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
+   * The no-cache-at-all path: 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;
-    }
-
+  async function awaitFirstFetch(ctx: ExtensionContext): Promise<CatalogSnapshot | undefined> {
     const controller = new AbortController();
     const timer = scheduleTimeout(() => controller.abort(), firstFetchDeadlineMs);
     let fresh: CatalogSnapshot | undefined;
@@ -204,6 +202,50 @@ export function createSessionTarget(deps: SessionTargetDeps): SessionTarget {
     return fresh;
   }
 
+  /**
+   * Races an already-started background refresh against
+   * {@link SessionTargetDeps.pickerRefreshDeadlineMs} (default 1500ms): if
+   * the refresh lands in time (and did not fail — `refresh()` resolving
+   * `undefined` falls back exactly like a deadline miss, with no
+   * notification), the picker shows the fresh snapshot; otherwise it
+   * shows `cached`. The refresh is never aborted here — it keeps running
+   * in the background, and `catalog.read()` reflects it once it resolves,
+   * exactly as it would without a picker in the way.
+   */
+  function awaitPickerRefresh(
+    refreshPromise: Promise<CatalogSnapshot | undefined>,
+    cached: CatalogSnapshot,
+  ): Promise<CatalogSnapshot> {
+    return new Promise((resolve) => {
+      let settled = false;
+      const timer = scheduleTimeout(() => {
+        if (settled) return;
+        settled = true;
+        resolve(cached);
+      }, pickerRefreshDeadlineMs);
+      void refreshPromise.then((fresh) => {
+        if (settled) return;
+        settled = true;
+        cancelTimeout(timer);
+        resolve(fresh ?? cached);
+      });
+    });
+  }
+
+  /** Resolves silently (project config / `repoPaths`) against `snapshot`, or shows the picker with it. */
+  async function resolveOrShowPicker(pi: ExtensionAPI, ctx: ExtensionContext, snapshot: CatalogSnapshot): Promise<void> {
+    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 runPicker(pi: ExtensionAPI, ctx: ExtensionContext, snapshot: CatalogSnapshot): Promise<void> {
     const result = await pickTarget(ctx, snapshot);
 
@@ -227,24 +269,44 @@ export function createSessionTarget(deps: SessionTargetDeps): SessionTarget {
     if (deps.role !== "orchestrator" || !ctx.hasUI) return;
     if (sessionOverride !== undefined) return;
 
-    const snapshot = await getSnapshot(ctx);
-    if (!snapshot) return;
+    const cached = deps.catalog.read();
+    if (!cached) {
+      const fresh = await awaitFirstFetch(ctx);
+      if (!fresh) return;
+      await resolveOrShowPicker(pi, ctx, fresh);
+      return;
+    }
+
+    // Always start a refresh, regardless of staleness (the owner hit a
+    // clients/projects change that a merely-stale-TTL check missed). Silent
+    // resolution below returns without ever awaiting it; the refresh keeps
+    // running and `catalog.read()` reflects it once it lands.
+    const refreshPromise = deps.catalog.refresh();
 
     const projectIds = deps.resolveProjectConfigIds();
     const resolved = resolveWorkTarget({
       project: projectIds,
       cwd: cwd(),
-      clients: snapshot.clients,
-      projects: snapshot.projects,
+      clients: cached.clients,
+      projects: cached.projects,
     });
     if (resolved) return;
 
+    const snapshot = await awaitPickerRefresh(refreshPromise, cached);
     await runPicker(pi, ctx, snapshot);
   }
 
   async function pick(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
-    const snapshot = await getSnapshot(ctx);
-    if (!snapshot) return;
+    const cached = deps.catalog.read();
+    if (!cached) {
+      const fresh = await awaitFirstFetch(ctx);
+      if (!fresh) return;
+      await runPicker(pi, ctx, fresh);
+      return;
+    }
+
+    const refreshPromise = deps.catalog.refresh();
+    const snapshot = await awaitPickerRefresh(refreshPromise, cached);
     await runPicker(pi, ctx, snapshot);
   }