kankaku 0.4.6 → 0.5.0

package/src/adapters/pi-tracker.ts

@@ -1,11 +1,21 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { WorkRecord, WorkRecordCore, WorkRole } from "../domain/work-record.ts";
+import { isValidClient } from "../domain/client-label.ts";
+import { formatWorkTargetLabel } from "../domain/work-target.ts";
+import type { RegistryClassification } from "../domain/registry-health.ts";
+import type { SubagentProfile } from "../domain/subagent-profile.ts";
+import type { RejectedChildEnvMarker } from "../config.ts";
+import type { OrchestratorRef, WorkRecord, WorkRecordCore, WorkRole } from "../domain/work-record.ts";
 import type { WorkTracker } from "../domain/work-tracker.ts";
+import type { Catalog } from "../ports/catalog.ts";
 import type { InflightStore } from "../ports/inflight-store.ts";
 import type { WorkLog } from "../ports/work-log.ts";
 import { createSessionClient } from "./session-client.ts";
+import { readNonDefaultSessionDir } from "./session-dir.ts";
+import type { SessionTarget } from "./session-target.ts";
 import { createStatusBar } from "./status-bar.ts";
 import { notifyError, registerKankakuCommand } from "./kankaku-command.ts";
+import type { SyncCommandDeps } from "./kankaku-command.ts";
+import type { SyncTrigger } from "./sync-runner.ts";
 
 export type { KankakuReportData } from "./kankaku-command.ts";
 
@@ -15,6 +25,54 @@ export interface PiTrackerDeps {
   /** Crash-recovery checkpoint store; see the "Crash recovery" README section. */
   inflight: InflightStore;
   role: WorkRole;
+  /**
+   * Static `roleConfidence`, applied from the very first record this
+   * process builds. Back-compat / direct-injection path: prefer
+   * {@link resolveRoleConfidence} for real wiring (`extension.ts`), since
+   * interactivity (F3) is normally only knowable once pi's own
+   * `ExtensionContext` is available at `session_start`, later than this
+   * object is constructed. When both are set, `resolveRoleConfidence`
+   * (once it has run, at `session_start`) wins. Never counted as a new task
+   * locally or synced to the hub when `"uncertain"` — see
+   * `domain/task-view.ts#buildTasks`/`uncertainRecords` and
+   * `triggerAutoSync` below.
+   */
+  roleConfidence?: "uncertain";
+  /**
+   * Deferred `roleConfidence` resolution (F3, ADR 0022 refined): called
+   * once, at `session_start`, with whether this is an interactive TUI
+   * session (`ctx.mode === "tui"`) — the signal a verified tracked ancestor
+   * alone cannot supply, since every subagent mechanism kankaku recognises
+   * launches its child non-interactively. `role` itself never depends on
+   * this (only `GENTLE_PI_AGENTS_CHILD`/`KANKAKU_ROLE` decide it, both
+   * already final at factory time); only whether an `"orchestrator"` record
+   * is further flagged `uncertain`. Once set here, stays stable for the
+   * rest of this process's life (every `session_start` after the first
+   * simply recomputes the same answer, since interactivity cannot change
+   * mid-process).
+   */
+  resolveRoleConfidence?: (isInteractive: boolean) => "uncertain" | undefined;
+  /**
+   * Set only when `role` is `"subagent"` and this process discovered a
+   * tracked ancestor via the machine-wide process registry (ADR 0023,
+   * F1/F4's rewrite). Attached to every record this process appends so
+   * `matchChildren` can reunite it with its orchestrator even across a
+   * different project/`KANKAKU_DIR` — its `dir` field is also what
+   * `extension.ts` uses to route this process's own work log/inflight
+   * checkpoints straight into the real orchestrator's directory, so the
+   * two records end up in the same `worklog.jsonl` to begin with.
+   */
+  orchestratorRef?: OrchestratorRef;
+  /**
+   * SUBAGENT-REQ-005/017: the {@link SubagentProfile} `id` whose child-env
+   * marker(s) confirmed this process's `role: "subagent"` (see
+   * `adapters/process-identity.ts#ProcessIdentity.profile`). Attached to
+   * every record this process appends so `/kankaku doctor` can report which
+   * profile matched each record. Never set for an `orchestrator` record.
+   */
+  profile?: string;
+  /** The full active subagent-profile set, forwarded to `/kankaku doctor` — see `kankaku-command.ts#KankakuCommandDeps.subagentProfiles`. */
+  subagentProfiles?: SubagentProfile[];
   pid: number;
   parentPid: number;
   /** Status line refresh interval in ms. Defaults to 1000. */
@@ -36,8 +94,91 @@ export interface PiTrackerDeps {
    * is not configured.
    */
   writeExportFile?: (name: string, content: string) => string;
+  /**
+   * Present only when the hub (PocketBase) is configured; see README "Hub
+   * (PocketBase)". Drives the session-start picker and the `/kankaku
+   * target`/`catalog` commands. Absent entirely when the hub is not
+   * configured, so behaviour and record shape are unchanged for users
+   * without one.
+   */
+  sessionTarget?: SessionTarget;
+  /** This machine's hostname or `KANKAKU_MACHINE`; only attached to records when `sessionTarget` is present. */
+  machine?: string;
+  /** Present only when the hub is configured; forwarded to `/kankaku catalog refresh` and the hub-aware `/kankaku client`. */
+  catalog?: Catalog;
+  /** A configured-but-rejected hub URL (see `adapters/hub-credentials.ts`); surfaced once via `ctx.ui.notify` on the first `session_start`. */
+  hubConfigError?: string;
+  /** Present only when the hub is configured; forwarded to `/kankaku sync [all|status]` and `/kankaku backfill`. */
+  sync?: SyncCommandDeps;
+  /** Forwarded to `/kankaku doctor`; see `kankaku-command.ts#KankakuCommandDeps.registryHealth`. */
+  registryHealth?: () => RegistryClassification;
+  /** Forwarded to `/kankaku doctor` (F2); see `kankaku-command.ts#KankakuCommandDeps.ancestorDetectionAvailable`. */
+  ancestorDetectionAvailable?: () => boolean;
+  /** Forwarded to `/kankaku doctor` (F3); see `kankaku-command.ts#KankakuCommandDeps.roleOverride`. */
+  roleOverride?: "orchestrator" | "subagent";
+  /**
+   * Whether `GENTLE_PI_AGENTS_CHILD=1` (the confirmed child marker) was
+   * also present on this process (R1); forwarded to `/kankaku doctor` so it
+   * can flag "override present AND child marker present" with the resolved
+   * outcome — see `kankaku-command.ts#KankakuCommandDeps.childMarkerPresent`.
+   */
+  childMarkerPresent?: boolean;
+  /**
+   * Set when `KANKAKU_ROLE=subagent` was present, with no confirmed child
+   * marker, but was ignored because this process looked interactive (R1 —
+   * see `config.ts#detectRole`'s precedence doc). Surfaced once via
+   * `ctx.ui.notify` at `session_start` and forwarded to `/kankaku doctor`.
+   */
+  overrideIgnoredInteractive?: boolean;
+  /**
+   * C2 (CRITICAL fix): set when a USER-CONFIGURED child-env marker
+   * (`KANKAKU_SUBAGENT_CHILD_ENV`) was present, but was ignored because
+   * this process looked interactive — a configured marker never demotes an
+   * interactive session (see `config.ts#detectRole`'s precedence doc).
+   * Surfaced once via `ctx.ui.notify` at `session_start` and forwarded to
+   * `/kankaku doctor`; escalated there (C2 item 3's self-check) when this
+   * process also has no tracked ancestor at all — the strongest signal the
+   * marker is genuinely ambient.
+   */
+  configuredMarkerIgnoredInteractive?: boolean;
+  /** C2 item 3: whether a live tracked ancestor was found for this process (`adapters/process-identity.ts#ProcessIdentity.hasTrackedAncestor`) — combined with `configuredMarkerIgnoredInteractive` above to decide the doctor self-check's wording. */
+  hasTrackedAncestor?: boolean;
+  /**
+   * C2 (CRITICAL fix, item 1): every `KANKAKU_SUBAGENT_CHILD_ENV` marker
+   * `config.ts#validateSubagentChildEnvMarkers` rejected as looking
+   * pi/shell/OS/npm-owned rather than genuinely child-only. Surfaced once
+   * via `ctx.ui.notify` at `session_start` and forwarded to `/kankaku
+   * doctor`. Absent (never an empty array) when nothing was rejected.
+   */
+  rejectedSubagentChildEnvMarkers?: RejectedChildEnvMarker[];
+  /** Forwarded to `/kankaku doctor` (F1); see `kankaku-command.ts#KankakuCommandDeps.workLogRouting`. */
+  workLogRouting?: { usedFallback: boolean; parentDir: string };
+  /**
+   * `KANKAKU_SYNC_AUTO` (default enabled): when `true` and `sync` is
+   * present, fire-and-forget a sync on `session_start` (orchestrator role
+   * only, after crash recovery) and again after `agent_settled`. Both go
+   * through `sync.run`, which callers are expected to wrap with a
+   * single-flight guard (see `adapters/sync-runner.ts#singleFlight`) so
+   * these two triggers never race. Never awaited; errors are swallowed
+   * (`sync.run` never throws) and surfaced at most once per session via a
+   * quiet notification, never on success.
+   */
+  autoSyncEnabled?: boolean;
+  /**
+   * Upper bound (ms) on how long the `session_shutdown` handler awaits
+   * `sync.run({ trigger: "session_shutdown" })` before giving up and
+   * letting cleanup proceed regardless. pi awaits `session_shutdown`
+   * handlers with no timeout of its own (verified in pi's dist), so this
+   * is the only thing bounding how long quitting can take when the hub is
+   * unreachable. Defaults to 3000; injectable so tests never wait on a
+   * real timer.
+   */
+  shutdownSyncTimeoutMs?: number;
 }
 
+/** Default for {@link PiTrackerDeps.shutdownSyncTimeoutMs}. */
+const DEFAULT_SHUTDOWN_SYNC_TIMEOUT_MS = 3000;
+
 /** Default `isAlive`: probe with signal 0 — no signal is sent, only existence/permission is checked. */
 function defaultIsAlive(pid: number): boolean {
   try {
@@ -60,6 +201,17 @@ function guarded<E>(fn: (event: E, ctx: ExtensionContext) => void): (event: E, c
   };
 }
 
+/** Async counterpart of {@link guarded}: also catches a rejected promise, e.g. from the target picker's `ctx.ui.select`. */
+function guardedAsync<E>(fn: (event: E, ctx: ExtensionContext) => Promise<void>): (event: E, ctx: ExtensionContext) => Promise<void> {
+  return async (event, ctx) => {
+    try {
+      await fn(event, ctx);
+    } catch (error) {
+      notifyError(ctx, error);
+    }
+  };
+}
+
 /**
  * Wires pi lifecycle events to a {@link WorkTracker}, persisting finished
  * records to a {@link WorkLog} and exposing the `/kankaku` report command.
@@ -68,16 +220,36 @@ export function createPiTracker(pi: ExtensionAPI, deps: PiTrackerDeps): void {
   const { tracker, log, inflight, role, pid, parentPid } = deps;
   const isAlive = deps.isAlive ?? defaultIsAlive;
 
+  /**
+   * F3: mutable so `session_start` can finalise it once `ctx.mode` (and
+   * therefore interactivity) is known — see `resolveRoleConfidence` above.
+   * Starts from the static `roleConfidence`, if any, so a caller that never
+   * fires `session_start` at all (e.g. most existing tests) still behaves
+   * exactly as before this change.
+   */
+  let roleConfidence: "uncertain" | undefined = deps.roleConfidence;
+
   const sessionClient = createSessionClient({
     role,
     envClient: deps.envClient,
     resolveProjectClient: deps.resolveProjectClient,
   });
 
+  /** Prefer the hub target's display label over the legacy client label, when one is active. */
+  function runDisplayLabel(): string | undefined {
+    const target = deps.sessionTarget?.runTarget();
+    return target ? formatWorkTargetLabel(target) : sessionClient.runClient();
+  }
+
+  function idleDisplayLabel(): string | undefined {
+    const target = deps.sessionTarget?.idleTarget();
+    return target ? formatWorkTargetLabel(target) : sessionClient.idleClient();
+  }
+
   const statusBar = createStatusBar({
     intervalMs: deps.statusIntervalMs,
-    resolveRunClient: () => sessionClient.runClient(),
-    resolveIdleClient: () => sessionClient.idleClient(),
+    resolveRunClient: runDisplayLabel,
+    resolveIdleClient: idleDisplayLabel,
   });
 
   const kankakuCommand = registerKankakuCommand(pi, {
@@ -85,8 +257,96 @@ export function createPiTracker(pi: ExtensionAPI, deps: PiTrackerDeps): void {
     sessionClient,
     refreshIdleStatus: (ctx) => statusBar.showIdle(ctx),
     writeExportFile: deps.writeExportFile,
+    sessionTarget: deps.sessionTarget,
+    catalog: deps.catalog,
+    sync: deps.sync,
+    registryHealth: deps.registryHealth,
+    ancestorDetectionAvailable: deps.ancestorDetectionAvailable,
+    roleOverride: deps.roleOverride,
+    childMarkerPresent: deps.childMarkerPresent,
+    overrideIgnoredInteractive: deps.overrideIgnoredInteractive,
+    configuredMarkerIgnoredInteractive: deps.configuredMarkerIgnoredInteractive,
+    hasTrackedAncestor: deps.hasTrackedAncestor,
+    rejectedSubagentChildEnvMarkers: deps.rejectedSubagentChildEnvMarkers,
+    workLogRouting: deps.workLogRouting,
+    subagentProfiles: deps.subagentProfiles,
   });
 
+  /** At most one quiet auto-sync failure notification per session; never notified on success. Shared by the fire-and-forget `triggerAutoSync` and the awaited shutdown sync below. */
+  let autoSyncErrorNotified = false;
+
+  function notifyAutoSyncFailureOnce(ctx: ExtensionContext, message: string): void {
+    if (autoSyncErrorNotified) return;
+    autoSyncErrorNotified = true;
+    if (ctx.hasUI) ctx.ui.notify(message, "warning");
+  }
+
+  // An uncertain-role process (ADR 0022) never anchors a task (see
+  // `domain/task-view.ts#buildTasks`), so a sync attempt from it would
+  // only ever find nothing new to push — skip it outright, exactly like a
+  // subagent, rather than pay for a pointless run. Shared by every
+  // automatic trigger, fire-and-forget or awaited.
+  function autoSyncEligible(): boolean {
+    return Boolean(deps.sync) && role === "orchestrator" && roleConfidence !== "uncertain" && deps.autoSyncEnabled !== false;
+  }
+
+  /** Fire-and-forget a sync (orchestrator role, `sync` configured, auto-sync enabled). Never awaited, never throws. `trigger` lets the automatic path's version short-circuit and throttle (see `adapters/sync-runner.ts#runSync`) tell apart `session_start` from `agent_settled`. */
+  function triggerAutoSync(ctx: ExtensionContext, trigger: SyncTrigger): void {
+    if (!deps.sync || !autoSyncEligible()) return;
+    void deps.sync
+      .run({ trigger })
+      .then((summary) => {
+        if (summary.error) notifyAutoSyncFailureOnce(ctx, `kankaku: sync failed: ${summary.error}`);
+      })
+      .catch(() => {
+        // sync.run is expected to never throw (see adapters/sync-runner.ts);
+        // this catch only guards against a misbehaving implementation.
+      });
+  }
+
+  /**
+   * Awaited counterpart of {@link triggerAutoSync}, for `session_shutdown`
+   * only: called after every settled record for this shutdown has already
+   * been appended (see the handler below), so the sync it runs includes
+   * them. Races `sync.run({ trigger: "session_shutdown" })` against
+   * `shutdownSyncTimeoutMs` (default {@link DEFAULT_SHUTDOWN_SYNC_TIMEOUT_MS})
+   * so an unreachable hub costs at most that timeout, never longer, and pi
+   * awaits this handler with no timeout of its own. Never throws: a
+   * rejection from `sync.run` (never expected — see
+   * `adapters/sync-runner.ts`) is caught exactly like `triggerAutoSync`'s
+   * own `.catch`, and is never left as an unhandled rejection even when the
+   * timeout branch of the race wins first. Notifies at most once per
+   * session, sharing {@link notifyAutoSyncFailureOnce}'s guard.
+   */
+  async function runShutdownSync(ctx: ExtensionContext): Promise<void> {
+    if (!deps.sync || !autoSyncEligible()) return;
+    const sync = deps.sync;
+
+    const timeoutMs = deps.shutdownSyncTimeoutMs ?? DEFAULT_SHUTDOWN_SYNC_TIMEOUT_MS;
+    let timer: NodeJS.Timeout | undefined;
+    // Caught right here, unconditionally, so this promise never becomes an
+    // unhandled rejection regardless of which side of the race below wins.
+    const settled = sync
+      .run({ trigger: "session_shutdown" })
+      .then((summary) => ({ kind: "summary", summary }) as const)
+      .catch((error: unknown) => ({ kind: "rejected", error }) as const);
+    const timedOut = new Promise<{ kind: "timeout" }>((resolve) => {
+      timer = setTimeout(() => resolve({ kind: "timeout" }), timeoutMs);
+    });
+
+    const outcome = await Promise.race([settled, timedOut]);
+    if (timer !== undefined) clearTimeout(timer);
+
+    if (outcome.kind === "timeout") {
+      notifyAutoSyncFailureOnce(ctx, "kankaku: shutdown sync timed out");
+    } else if (outcome.kind === "rejected") {
+      const message = outcome.error instanceof Error ? outcome.error.message : String(outcome.error);
+      notifyAutoSyncFailureOnce(ctx, `kankaku: sync failed: ${message}`);
+    } else if (outcome.summary.error) {
+      notifyAutoSyncFailureOnce(ctx, `kankaku: sync failed: ${outcome.summary.error}`);
+    }
+  }
+
   /** `log.append` plus cache invalidation, so every append this process makes keeps the completion cache correct. */
   function appendRecord(record: WorkRecord): void {
     log.append(record);
@@ -95,10 +355,17 @@ export function createPiTracker(pi: ExtensionAPI, deps: PiTrackerDeps): void {
 
   function buildRecord(core: WorkRecordCore, ctx: ExtensionContext): WorkRecord {
     const model = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
-    // Subagent children never carry their own client: they inherit the
-    // orchestrator's label at task level (see task-view.ts).
-    const client = sessionClient.runClient();
+    const thinkingLevel = readThinkingLevel(pi);
+    // Subagent children never carry their own client/target: they inherit
+    // the orchestrator's at task level (see task-view.ts).
+    const target = deps.sessionTarget?.runTarget();
+    // When a hub target is active, the legacy `client` label is the
+    // client's code (kept valid against CLIENT_PATTERN so every existing
+    // report/export keeps working); an invalid code is omitted rather than
+    // breaking the record. Without a hub target, behaviour is unchanged.
+    const client = target ? (isValidClient(target.clientCode) ? target.clientCode : undefined) : sessionClient.runClient();
     const sessionName = pi.getSessionName();
+    const sessionDir = readNonDefaultSessionDir(ctx.sessionManager);
     return {
       ...core,
       role,
@@ -109,8 +376,22 @@ export function createPiTracker(pi: ExtensionAPI, deps: PiTrackerDeps): void {
       sessionFile: ctx.sessionManager.getSessionFile(),
       mode: ctx.mode,
       ...(model !== undefined ? { model } : {}),
+      ...(thinkingLevel !== undefined ? { thinkingLevel } : {}),
       ...(client !== undefined ? { client } : {}),
       ...(sessionName !== undefined ? { sessionName } : {}),
+      ...(sessionDir !== undefined ? { sessionDir } : {}),
+      ...(target !== undefined
+        ? {
+            clientId: target.clientId,
+            clientName: target.clientName,
+            ...(target.projectId !== undefined ? { projectId: target.projectId } : {}),
+            ...(target.projectName !== undefined ? { projectName: target.projectName } : {}),
+          }
+        : {}),
+      ...(deps.machine !== undefined ? { machine: deps.machine } : {}),
+      ...(roleConfidence !== undefined ? { roleConfidence } : {}),
+      ...(deps.orchestratorRef !== undefined ? { orchestratorRef: deps.orchestratorRef } : {}),
+      ...(deps.profile !== undefined ? { profile: deps.profile } : {}),
     };
   }
 
@@ -138,6 +419,21 @@ export function createPiTracker(pi: ExtensionAPI, deps: PiTrackerDeps): void {
     }),
   );
 
+  pi.on(
+    "agent_start",
+    guarded((_event, ctx) => {
+      // A run an extension started itself never fires before_agent_start
+      // (see WorkTracker.onAgentStart): open the record, the status clock and
+      // the crash-recovery checkpoint here instead. A no-op for a user prompt.
+      const wasIdle = tracker.peek("interrupted") === undefined;
+      tracker.onAgentStart();
+      if (wasIdle) statusBar.start(ctx);
+      // Always: when this start set a record aside, the checkpoint on disk
+      // must become the merged snapshot now, not at the next turn_end.
+      checkpoint(ctx);
+    }),
+  );
+
   pi.on(
     "agent_end",
     guarded((event) => {
@@ -198,41 +494,116 @@ export function createPiTracker(pi: ExtensionAPI, deps: PiTrackerDeps): void {
   pi.on(
     "agent_settled",
     guarded((_event, ctx) => {
-      const core = tracker.onSettled();
+      const cores = tracker.settleAll();
       try {
-        if (core) {
+        for (const core of cores) {
           appendRecord(buildRecord(core, ctx));
         }
       } finally {
         // Always clean up, even when appendRecord above threw: an unpersisted
         // checkpoint must not linger, and the status timer must not leak.
         inflight.clear();
-        statusBar.stop(ctx);
-        sessionClient.endRun();
+        if (tracker.peek("interrupted") !== undefined) {
+          // A new run overtook this settle (see WorkTracker.settleAll): it is
+          // still open, so its clock keeps running and it gets its own
+          // checkpoint back — the clear above only dropped the old record's.
+          checkpoint(ctx);
+        } else {
+          statusBar.stop(ctx);
+          sessionClient.endRun();
+          deps.sessionTarget?.endRun();
+        }
+        triggerAutoSync(ctx, "agent_settled");
       }
     }),
   );
 
   pi.on(
     "session_shutdown",
-    guarded((_event, ctx) => {
-      const core = tracker.onShutdown();
+    guardedAsync(async (_event, ctx) => {
+      const cores = tracker.shutdownAll();
       try {
-        if (core) {
+        for (const core of cores) {
           appendRecord(buildRecord(core, ctx));
         }
+        // Only reached once every record above was appended: the shutdown
+        // sync (bounded by runShutdownSync's own timeout, see above) must
+        // include them. If appendRecord threw, this is skipped and the
+        // finally below still runs cleanup — never left half-done.
+        await runShutdownSync(ctx);
       } finally {
         inflight.clear();
         statusBar.stop(ctx);
         sessionClient.endRun();
+        deps.sessionTarget?.endRun();
       }
     }),
   );
 
+  let hubConfigErrorNotified = false;
+  let overrideIgnoredInteractiveNotified = false;
+  let configuredMarkerIgnoredInteractiveNotified = false;
+  let rejectedSubagentChildEnvMarkersNotified = false;
+
   pi.on(
     "session_start",
-    guarded((_event, ctx) => {
+    guardedAsync(async (_event, ctx) => {
+      // F3: finalise roleConfidence now that ctx.mode (and therefore
+      // interactivity) is known — see resolveRoleConfidence's doc comment.
+      // A no-op when extension.ts did not wire it (deps.roleConfidence, if
+      // any, is left exactly as constructed).
+      if (deps.resolveRoleConfidence) {
+        roleConfidence = deps.resolveRoleConfidence(ctx.mode === "tui");
+      }
+
+      if (deps.hubConfigError && !hubConfigErrorNotified) {
+        hubConfigErrorNotified = true;
+        if (ctx.hasUI) ctx.ui.notify(deps.hubConfigError, "error");
+      }
+
+      // R1: KANKAKU_ROLE=subagent was ignored at factory time (no confirmed
+      // child marker, and this process looked interactive) — this is
+      // almost always a leaked shell export, and honouring it would have
+      // silently dropped this session's own work. Never silent: warn once.
+      if (deps.overrideIgnoredInteractive && !overrideIgnoredInteractiveNotified) {
+        overrideIgnoredInteractiveNotified = true;
+        if (ctx.hasUI) {
+          ctx.ui.notify(
+            "kankaku: ignoring KANKAKU_ROLE=subagent for this interactive session (likely a leaked shell export) — treating it as orchestrator; see /kankaku doctor",
+            "warning",
+          );
+        }
+      }
+
+      // C2 item 2/3: a KANKAKU_SUBAGENT_CHILD_ENV marker matched, but was
+      // ignored because this process looked interactive — a configured
+      // marker never demotes an interactive session. Escalate the wording
+      // when this process ALSO has no tracked ancestor at all (the
+      // strongest signal the marker is genuinely ambient, not a real
+      // subagent mechanism — C2 item 3's self-check).
+      if (deps.configuredMarkerIgnoredInteractive && !configuredMarkerIgnoredInteractiveNotified) {
+        configuredMarkerIgnoredInteractiveNotified = true;
+        if (ctx.hasUI) {
+          const message = deps.hasTrackedAncestor
+            ? "kankaku: ignoring a KANKAKU_SUBAGENT_CHILD_ENV marker for this interactive session — treating it as orchestrator; see /kankaku doctor"
+            : "kankaku: a KANKAKU_SUBAGENT_CHILD_ENV marker matched this interactive, top-level session (no tracked ancestor) — the marker is likely ambient, not a real subagent mechanism; treating it as orchestrator; see /kankaku doctor";
+          ctx.ui.notify(message, "warning");
+        }
+      }
+
+      // C2 item 1: one or more KANKAKU_SUBAGENT_CHILD_ENV entries were
+      // rejected at config load time (looked pi/shell/OS/npm-owned, not
+      // genuinely child-only) — never silent.
+      if (deps.rejectedSubagentChildEnvMarkers?.length && !rejectedSubagentChildEnvMarkersNotified) {
+        rejectedSubagentChildEnvMarkersNotified = true;
+        if (ctx.hasUI) {
+          const names = deps.rejectedSubagentChildEnvMarkers.map((rejected) => rejected.name).join(", ");
+          ctx.ui.notify(`kankaku: ignoring KANKAKU_SUBAGENT_CHILD_ENV marker(s) that look ambient, not child-only: ${names}; see /kankaku doctor`, "warning");
+        }
+      }
+
       sessionClient.restore(ctx);
+      deps.sessionTarget?.restore(ctx);
       statusBar.showIdle(ctx);
 
       const recovered = inflight.recoverStale(isAlive);
@@ -242,6 +613,29 @@ export function createPiTracker(pi: ExtensionAPI, deps: PiTrackerDeps): void {
       if (recovered.length > 0 && ctx.hasUI) {
         ctx.ui.notify(`kankaku: recovered ${recovered.length} interrupted record(s)`, "warning");
       }
+
+      // Runs after recovery so a freshly picked target does not affect
+      // records recovered from before this session started. See README
+      // "Hub (PocketBase)": a no-op unless orchestrator + hasUI + configured.
+      if (deps.sessionTarget) {
+        await deps.sessionTarget.ensurePicked(pi, ctx);
+        statusBar.showIdle(ctx);
+      }
+
+      // Fire-and-forget, after recovery so a just-recovered interrupted
+      // record is included. See README "Hub (PocketBase)" sync section.
+      triggerAutoSync(ctx, "session_start");
     }),
   );
 }
+
+/** pi's current reasoning effort, or `undefined` on a pi that predates `getThinkingLevel` or has no session to ask yet. Never throws. */
+function readThinkingLevel(pi: ExtensionAPI): string | undefined {
+  try {
+    const read = (pi as { getThinkingLevel?: () => unknown }).getThinkingLevel;
+    const level = typeof read === "function" ? read.call(pi) : undefined;
+    return typeof level === "string" && level.length > 0 ? level : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/src/adapters/pocketbase-catalog.ts

@@ -0,0 +1,60 @@
+import type { Client, Project } from "../domain/work-target.ts";
+import type { PocketBaseClient, PocketBaseRecord } from "./pocketbase-client.ts";
+
+interface ClientRecord extends PocketBaseRecord {
+  name: string;
+  code: string;
+  active?: boolean;
+  unassigned?: boolean;
+}
+
+interface ProjectRecord extends PocketBaseRecord {
+  name: string;
+  code?: string;
+  client: string;
+  repo_paths?: unknown;
+  active?: boolean;
+}
+
+function mapClient(record: ClientRecord): Client {
+  return {
+    id: record.id,
+    name: record.name,
+    code: record.code,
+    active: record.active === true,
+    ...(record.unassigned === true ? { unassigned: true } : {}),
+  };
+}
+
+function mapProject(record: ProjectRecord): Project {
+  return {
+    id: record.id,
+    name: record.name,
+    ...(record.code !== undefined ? { code: record.code } : {}),
+    clientId: record.client,
+    repoPaths: Array.isArray(record.repo_paths) ? record.repo_paths.filter((path): path is string => typeof path === "string") : [],
+    active: record.active === true,
+  };
+}
+
+/**
+ * Build the `fetchCatalog` function {@link CachedCatalog} (`cached-catalog.ts`)
+ * needs, backed by a {@link PocketBaseClient}. Fetches every `clients` and
+ * `projects` record (no `active` filter, so the domain resolver can tell
+ * "deleted" from "inactive"; see `domain/work-target.ts`), sorted by name.
+ * `signal`, when given, bounds both fetches (see
+ * `pocketbase-client.ts#request`).
+ */
+export function createPocketBaseCatalogFetcher(client: PocketBaseClient): (signal?: AbortSignal) => Promise<{ clients: Client[]; projects: Project[] }> {
+  return async (signal?: AbortSignal) => {
+    const [clientRecords, projectRecords] = await Promise.all([
+      client.list<ClientRecord>("clients", { sort: "name" }, signal),
+      client.list<ProjectRecord>("projects", { sort: "name" }, signal),
+    ]);
+
+    return {
+      clients: clientRecords.map(mapClient),
+      projects: projectRecords.map(mapProject),
+    };
+  };
+}