@gitkraken/core-gitlens 0.3.0 → 0.3.1

package/dist/plus/agents/providers/claudeCodeProvider.js

@@ -15,12 +15,12 @@ import { prepareStoredPrompt } from '../sanitizePrompt.js';
 import { classifyPermissionKind, deriveStatusFromEvent, describeToolInput, extractPlanSummary, extractQuestionDetails, getToolFilePath, getToolReadPath, isProcessAlive, rehydrateSubagents, } from '../stateMachine.js';
 import { getPhaseForStatus } from '../types.js';
 import { ClaudeCodeTranscriptReader } from './claudeCodeTranscript.js';
-const staleCheckIntervalMs = 60 * 1000; // 1 minute
-/** Cooldown between PostToolUse and dropping the file from `currentFiles`. Held long enough that
- *  surfaces consuming the list (WIP file decoration, treemap activity overlay) keep showing a file
- *  the agent just touched well past the moment the tool call completed — a single edit reads as a
- *  sustained presence rather than a flash. */
-const postToolUseClearDelayMs = 120000;
+const staleCheckIntervalMs = 15 * 60 * 1000; // 15 minutes
+/** Default cooldown between PostToolUse and dropping the file from `fileActivity`. Held long
+ *  enough that the treemap activity overlay can render a decay tail well past the moment the tool
+ *  call completed. The host may override per-call via `AgentProviderCallbacks.getActivityDecayMs`
+ *  (driven by the user's `gitlens.graph.experimental.visualizations.activityDecay` setting). */
+const defaultActivityDecayMs = 5 * 60 * 1000; // 5 minutes
 /** Grace period before `Stop` commits to `idle`. Long enough to absorb a same-turn continuation
  *  (hook-driven re-prompt, IPC event reordering, auto-resume); short enough that legitimate idle
  *  is visible promptly. */
@@ -38,21 +38,33 @@ const phaseSinceRestoreWindowMs = 2000;
 function normalizeWorkspacePath(value) {
     return value ? normalizePath(value) : undefined;
 }
-/** Order-insensitive comparison — entries come from a `Map.values()` iterator, but tracked
- *  tool-use ids are uncorrelated with file order, so two snapshots with the same files in a
- *  different order shouldn't fire a no-op change event. Treats `undefined` and `[]` as equal. */
-function currentFilesEqual(a, b) {
+/** Structural comparison of two `fileActivity` arrays — same set of paths, same kinds present,
+ *  same `reading`/`editing` flags. Ignores numeric timestamp values because those drift between
+ *  every call (Date.now() advances) even when nothing has actually changed. Used to gate event
+ *  firing: timestamps still get refreshed via the `_sessions[]` write, but a fire only happens
+ *  when the structural shape changed. Treats `undefined` and `[]` as equal. */
+function fileActivityStructurallyEqual(a, b) {
     const aLen = a?.length ?? 0;
     const bLen = b?.length ?? 0;
     if (aLen !== bLen)
         return false;
     if (aLen === 0)
         return true;
-    if (aLen === 1)
-        return a[0] === b[0];
-    const set = new Set(a);
-    for (const v of b) {
-        if (!set.has(v))
+    const byPath = new Map();
+    for (const entry of a) {
+        byPath.set(entry.path, entry);
+    }
+    for (const entry of b) {
+        const other = byPath.get(entry.path);
+        if (other == null)
+            return false;
+        if ((entry.readAt != null) !== (other.readAt != null))
+            return false;
+        if ((entry.editedAt != null) !== (other.editedAt != null))
+            return false;
+        if ((entry.reading ?? false) !== (other.reading ?? false))
+            return false;
+        if ((entry.editing ?? false) !== (other.editing ?? false))
             return false;
     }
     return true;
@@ -76,6 +88,10 @@ export class ClaudeCodeProvider {
     _pendingIdleTimers = new Map();
     _workspacePaths = [];
     _staleCheckTimer;
+    /** Whether Claude hooks are installed, pushed by the host via {@link setClaudeHooksInstalled}.
+     *  Fail-open (`true`) until the first push lands so a fresh window with real hooks isn't
+     *  suppressed on its first ticks. Gates the reconciliation poll in {@link syncSessions}. */
+    _claudeHooksInstalled = true;
     _transcriptReader = new ClaudeCodeTranscriptReader();
     constructor(callbacks) {
         this.callbacks = callbacks;
@@ -132,6 +148,19 @@ export class ClaudeCodeProvider {
                 .catch((ex) => Logger.error(ex, 'ClaudeCodeProvider.updateWorkspacePaths: publishAgents failed'));
         }
     }
+    setClaudeHooksInstalled(installed) {
+        const wasOff = !this._claudeHooksInstalled;
+        this._claudeHooksInstalled = installed;
+        // On a fresh off→on transition, reconcile immediately rather than waiting up to a full
+        // interval — picks up any session that was already running before hooks were installed.
+        // This is a deliberate discovery pass (like the cold-start bootstrap), not a routine tick:
+        // hooks were just off, so the live path couldn't have seen these sessions and anything we
+        // find here is expected, not drift. Run it ungated so it neither skips nor reports drift
+        // telemetry (an ungated `syncSessions()` always polls and never emits `onSyncDiscrepancy`).
+        if (installed && wasOff) {
+            void this.syncSessions();
+        }
+    }
     dispose() {
         this._disposed = true;
         this.stop();
@@ -233,7 +262,7 @@ export class ClaudeCodeProvider {
                 return;
             void this.querySiblingWindowSessions();
             this._staleCheckTimer?.dispose();
-            this._staleCheckTimer = disposableInterval(() => void this.syncSessions(), staleCheckIntervalMs);
+            this._staleCheckTimer = disposableInterval(() => void this.syncSessions({ gate: true }), staleCheckIntervalMs);
         }
         catch (ex) {
             Logger.error(ex, 'ClaudeCodeProvider.ensureIpcServer');
@@ -246,6 +275,7 @@ export class ClaudeCodeProvider {
             workspacePath: workspacePath,
             isInWorkspace: workspacePath != null,
             cwd: event.cwd,
+            initialCwd: event.initialCwd,
             planFile: event.planFile,
             sessionName: event.sessionName,
         };
@@ -340,7 +370,7 @@ export class ClaudeCodeProvider {
                 const toolName = hookInput?.tool_name ?? event.toolName ?? '';
                 const statusDetail = toolInput != null && toolName ? describeToolInput(toolName, toolInput) : toolName || undefined;
                 // Capture pre-update status so we can tell whether the upcoming updateSessionStatus
-                // will fire on its own — needed to avoid dropping currentFiles changes when the
+                // will fire on its own — needed to avoid dropping fileActivity changes when the
                 // session is already in tool_use (back-to-back tool calls).
                 const sessionIndex = this._sessions.findIndex(s => s.id === event.sessionId);
                 const prevStatus = sessionIndex >= 0 ? this._sessions[sessionIndex].status : undefined;
@@ -362,11 +392,28 @@ export class ClaudeCodeProvider {
                 bk.activeToolCount = Math.max(0, bk.activeToolCount - 1);
                 // Cooldown the file-edit decoration instead of dropping it immediately, so a quick
                 // follow-up Edit/Write to the same path doesn't blink. The deferred clear fires its
-                // own change event when it expires.
-                this.scheduleClearToolUseFile(event.sessionId, event);
-                this.scheduleClearToolUseRead(event.sessionId, event);
+                // own change event when it expires. The immediate re-sync inside each flips
+                // `editing`/`reading` off the moment refcount hits zero, though — capture whether that
+                // changed the published list so we fire it ourselves when the status update below short-
+                // circuits (a parallel tool is still in flight, so activeToolCount stays > 0).
+                const filesChanged = this.scheduleClearToolUseFile(event.sessionId, event);
+                const readsChanged = this.scheduleClearToolUseRead(event.sessionId, event);
                 if (bk.activeToolCount === 0) {
+                    // updateSessionStatus short-circuits without firing when status+detail are unchanged
+                    // (already 'thinking' with no detail) — which would drop the editing/reading flag-flip
+                    // above and leave a stale live pulse. Capture whether it will fire on its own and, if
+                    // not, fire explicitly — mirrors the PreToolUse / PermissionDenied guards.
+                    const idx = this._sessions.findIndex(s => s.id === event.sessionId);
+                    const statusWillFire = idx < 0 ||
+                        this._sessions[idx].status !== 'thinking' ||
+                        this._sessions[idx].statusDetail != null;
                     this.updateSessionStatus(event.sessionId, 'thinking', eventContext);
+                    if ((filesChanged || readsChanged) && !statusWillFire) {
+                        this._onDidChangeSessions.fire();
+                    }
+                }
+                else if (filesChanged || readsChanged) {
+                    this._onDidChangeSessions.fire();
                 }
                 break;
             }
@@ -377,7 +424,10 @@ export class ClaudeCodeProvider {
                     pending.reject(new Error('Session stopped'));
                     this._pendingPermissions.delete(event.sessionId);
                 }
-                this.resetBookkeeping(event.sessionId);
+                // Turn ended: stop the "live" pulse but keep the per-operation decay tail fading over
+                // the configured window (anchored at each tool's completion, not at the turn end). A full
+                // reset here would wipe the tail the instant the agent finishes a response.
+                this.settleBookkeeping(event.sessionId);
                 // Apply Stop's metadata synchronously so we don't carry stale context through the
                 // debounce window — any in-window mutations (e.g. CwdChanged) survive when the
                 // timer fires. ensureSession doesn't fire on metadata-only updates of existing
@@ -586,12 +636,39 @@ export class ClaudeCodeProvider {
                 pendingFileClears: new Map(),
                 currentReadCounts: new Map(),
                 pendingReadClears: new Map(),
+                lastTouchedAt: new Map(),
                 gitInfoUnresolvable: false,
             };
             this._sessionBookkeeping.set(sessionId, bk);
         }
         return bk;
     }
+    /** Returns the active decay window in milliseconds — the cooldown between PostToolUse and
+     *  dropping the path from the bookkeeping. Reads through the host callback every time so a
+     *  setting change takes effect on the next Pre/Post pair without re-wiring (existing timers
+     *  keep their original timeout — acceptable since they're short-lived relative to the setting). */
+    get activityDecayMs() {
+        return this.callbacks.getActivityDecayMs?.() ?? defaultActivityDecayMs;
+    }
+    /** Locates the *parent* session id that owns the given session id — returns the id itself when
+     *  it matches a top-level session, otherwise the `id` of the parent that holds it under
+     *  `subagents[]`. Returns `undefined` when neither match (session no longer exists). Used to
+     *  route per-session bookkeeping changes to the right top-level `syncSessionFileActivity` call.
+     *  Tool events are parent-keyed (the CLI sends a sub-agent's tool events under the parent id),
+     *  so the `subagents[]` branch is a defensive fallback for any other-keyed caller. */
+    findOwningParentId(sessionId) {
+        for (const s of this._sessions) {
+            if (s.id === sessionId)
+                return s.id;
+            if (s.subagents != null) {
+                for (const sub of s.subagents) {
+                    if (sub.id === sessionId)
+                        return s.id;
+                }
+            }
+        }
+        return undefined;
+    }
     resetBookkeeping(sessionId) {
         const bk = this.getBookkeeping(sessionId);
         bk.activeToolCount = 0;
@@ -600,9 +677,43 @@ export class ClaudeCodeProvider {
         bk.currentFileCounts.clear();
         this.cancelPendingReadClears(bk);
         bk.currentReadCounts.clear();
+        bk.lastTouchedAt.clear();
         bk.gitInfoUnresolvable = false;
-        this.syncSessionCurrentFiles(sessionId, bk);
-        this.syncSessionCurrentReads(sessionId, bk);
+        const parentId = this.findOwningParentId(sessionId);
+        if (parentId != null) {
+            this.syncSessionFileActivity(parentId);
+        }
+    }
+    /** Turn-end settle (Stop): the agent finished its turn, so nothing is "live" anymore — but
+     *  the per-operation decay tail must survive. Heat fades over {@link activityDecayMs} measured
+     *  from when each *tool* finished (the PostToolUse cooldown), NOT from when the turn ends, so a
+     *  Stop must not cancel those cooldowns or clear `lastTouchedAt`. We only reset turn-scoped
+     *  state and force-finish any path whose PostToolUse never arrived before Stop: drop its
+     *  refcount to 0 (flipping `editing`/`reading` off so the pulse stops) and schedule the same
+     *  decay eviction a normal completion would. Contrast {@link resetBookkeeping}, which hard-
+     *  wipes everything for SessionStart/SessionEnd (the agent is gone, not merely between turns). */
+    settleBookkeeping(sessionId) {
+        const bk = this.getBookkeeping(sessionId);
+        bk.activeToolCount = 0;
+        bk.pendingPermission = undefined;
+        // Allow git re-resolution next turn (matches the prior reset-on-Stop intent).
+        bk.gitInfoUnresolvable = false;
+        for (const [path, count] of bk.currentFileCounts) {
+            if (count > 0) {
+                bk.currentFileCounts.set(path, 0);
+                this.scheduleFileDecayEviction(bk, sessionId, path);
+            }
+        }
+        for (const [path, count] of bk.currentReadCounts) {
+            if (count > 0) {
+                bk.currentReadCounts.set(path, 0);
+                this.scheduleReadDecayEviction(bk, sessionId, path);
+            }
+        }
+        const parentId = this.findOwningParentId(sessionId);
+        if (parentId != null && this.syncSessionFileActivity(parentId)) {
+            this._onDidChangeSessions.fire();
+        }
     }
     cancelPendingFileClears(bk) {
         for (const timer of bk.pendingFileClears.values()) {
@@ -630,11 +741,37 @@ export class ClaudeCodeProvider {
         const toolInput = hookInputPopulated ? rawHookInput : event.toolInput;
         return getToolFilePath(toolName, toolInput);
     }
-    /** Records that a file-mutating tool call is in flight against `filePath` so the WIP details
-     *  panel can decorate the row. Refcounts per path — keyed by path (not `tool_use_id`, which
-     *  the GK CLI doesn't reliably surface) so parallel calls bump the count and Post/Pre order
-     *  doesn't matter. Returns whether the session's published list actually changed so callers
-     *  can fire when the surrounding {@link updateSessionStatus} short-circuits. */
+    /** Stamps the per-path/per-kind `lastTouchedAt[kind]` to the current epoch ms. Stamped on every
+     *  PreToolUse for the matching kind so `serializeFileActivity` can emit `readAt`/`editedAt` as
+     *  a relative `now - timestamp` delta. */
+    stampLastTouched(bk, filePath, kind) {
+        const existing = bk.lastTouchedAt.get(filePath);
+        const next = existing != null ? { ...existing } : {};
+        next[kind] = Date.now();
+        bk.lastTouchedAt.set(filePath, next);
+    }
+    /** Drops the `lastTouchedAt[kind]` slot for `filePath`, and the whole entry when neither kind
+     *  remains. Mirrors the cooldown-timer eviction in `scheduleClear*` — once the path is gone
+     *  from the count map for that kind, its timestamp is no longer load-bearing. */
+    clearLastTouched(bk, filePath, kind) {
+        const existing = bk.lastTouchedAt.get(filePath);
+        if (existing == null)
+            return;
+        if (existing[kind] == null)
+            return;
+        const next = { ...existing, [kind]: undefined };
+        if (next.edit == null && next.read == null) {
+            bk.lastTouchedAt.delete(filePath);
+        }
+        else {
+            bk.lastTouchedAt.set(filePath, next);
+        }
+    }
+    /** Records that a file-mutating tool call is in flight against `filePath` so consumers can
+     *  highlight the path. Refcounts per path — keyed by path (not `tool_use_id`, which the GK CLI
+     *  doesn't reliably surface) so parallel calls bump the count and Post/Pre order doesn't matter.
+     *  Returns whether the parent's published `fileActivity` actually changed so callers can fire
+     *  when the surrounding {@link updateSessionStatus} short-circuits. */
     trackToolUseFile(sessionId, event) {
         const filePath = this.getEventFilePath(event);
         if (filePath == null)
@@ -648,31 +785,46 @@ export class ClaudeCodeProvider {
             bk.pendingFileClears.delete(filePath);
         }
         bk.currentFileCounts.set(filePath, (bk.currentFileCounts.get(filePath) ?? 0) + 1);
-        return this.syncSessionCurrentFiles(sessionId, bk);
+        this.stampLastTouched(bk, filePath, 'edit');
+        return this.syncSessionFileActivityForChild(sessionId);
     }
     /** Decrements the in-flight refcount for a finished tool call's file. While the count stays
-     *  above zero (overlapping parallel calls) the path remains decorated. When the count drops
-     *  to zero, leaves the entry in place at count `0` and schedules a {@link postToolUseClearDelayMs}
-     *  cooldown before actually dropping it — so back-to-back Edit/Write to the same file doesn't
-     *  flicker the decoration. A Pre arriving during cooldown cancels the timer and bumps the
-     *  count back above zero. */
+     *  above zero (overlapping parallel calls) the path remains marked. When the count drops to
+     *  zero, leaves the entry in place at count `0` and schedules a {@link activityDecayMs}
+     *  cooldown before actually dropping it — so a recently-edited file lingers as a decay tail
+     *  on the treemap. A Pre arriving during cooldown cancels the timer and bumps the count back
+     *  above zero. Returns whether the parent's published `fileActivity` changed (i.e. `editing`
+     *  flipped off) so the PostToolUse caller can fire when its `updateSessionStatus` short-
+     *  circuits (a parallel tool still in flight keeps activeToolCount > 0). */
     scheduleClearToolUseFile(sessionId, event) {
         const filePath = this.getEventFilePath(event);
         if (filePath == null)
-            return;
+            return false;
         const bk = this.getBookkeeping(sessionId);
         const count = bk.currentFileCounts.get(filePath);
         // A duplicate / out-of-order Post during cooldown (count is already 0) would drive the
         // refcount negative and schedule a second timer — ignore those so the cooldown stays
         // authoritative until either its timer fires or a fresh Pre bumps the count back up.
         if (count == null || count <= 0)
-            return;
+            return false;
         const next = count - 1;
         bk.currentFileCounts.set(filePath, next);
+        // Re-sync so `editing` drops from `true` to `undefined` the moment refcount hits zero —
+        // the cooldown only governs when the path itself leaves the snapshot, not when the
+        // "live" boolean flips off.
+        const changed = this.syncSessionFileActivityForChild(sessionId);
         if (next > 0)
-            return;
-        // Refcount just hit zero — keep the path in `currentFileCounts` (still decorated) for the
-        // cooldown window, then drop it.
+            return changed;
+        // Refcount just hit zero — keep the path in `currentFileCounts` for the cooldown window,
+        // then drop it.
+        this.scheduleFileDecayEviction(bk, sessionId, filePath);
+        return changed;
+    }
+    /** Schedules (replacing any prior timer) the {@link activityDecayMs} cooldown that finally
+     *  drops `filePath` from the edit bookkeeping once it has fully decayed. Shared by the
+     *  PostToolUse cooldown path and the Stop settle ({@link settleBookkeeping}); the path stays
+     *  in `currentFileCounts` at count 0 meanwhile so its `editedAt` keeps aging on the client. */
+    scheduleFileDecayEviction(bk, sessionId, filePath) {
         const existing = bk.pendingFileClears.get(filePath);
         if (existing != null) {
             clearTimeout(existing);
@@ -689,14 +841,15 @@ export class ClaudeCodeProvider {
             if ((cur.currentFileCounts.get(filePath) ?? 0) > 0)
                 return;
             cur.currentFileCounts.delete(filePath);
-            if (this.syncSessionCurrentFiles(sessionId, cur)) {
+            this.clearLastTouched(cur, filePath, 'edit');
+            if (this.syncSessionFileActivityForChild(sessionId)) {
                 this._onDidChangeSessions.fire();
             }
-        }, postToolUseClearDelayMs);
+        }, this.activityDecayMs);
         bk.pendingFileClears.set(filePath, timer);
     }
     /** Drops a tracked tool call's file immediately (no cooldown). Used for PermissionDenied,
-     *  where the tool never ran — keeping a "currently editing" badge would be misleading.
+     *  where the tool never ran — keeping the "live" badge would be misleading.
      *  Returns whether the published list changed. */
     untrackToolUseFile(sessionId, event) {
         const filePath = this.getEventFilePath(event);
@@ -708,7 +861,7 @@ export class ClaudeCodeProvider {
             return false;
         if (count > 1) {
             bk.currentFileCounts.set(filePath, count - 1);
-            return false;
+            return this.syncSessionFileActivityForChild(sessionId);
         }
         const pending = bk.pendingFileClears.get(filePath);
         if (pending != null) {
@@ -716,21 +869,8 @@ export class ClaudeCodeProvider {
             bk.pendingFileClears.delete(filePath);
         }
         bk.currentFileCounts.delete(filePath);
-        return this.syncSessionCurrentFiles(sessionId, bk);
-    }
-    /** Writes the bookkeeping's tracked file paths onto the session in place. Returns whether the
-     *  session's `currentFiles` actually changed. Keys (not values) — entries with count `0` are
-     *  cooldown-residents, still part of the published list. */
-    syncSessionCurrentFiles(sessionId, bk) {
-        const index = this._sessions.findIndex(s => s.id === sessionId);
-        if (index < 0)
-            return false;
-        const prev = this._sessions[index];
-        const next = bk.currentFileCounts.size > 0 ? [...bk.currentFileCounts.keys()] : undefined;
-        if (currentFilesEqual(prev.currentFiles, next))
-            return false;
-        this._sessions[index] = { ...prev, currentFiles: next };
-        return true;
+        this.clearLastTouched(bk, filePath, 'edit');
+        return this.syncSessionFileActivityForChild(sessionId);
     }
     /** Mirror of {@link getEventFilePath} for read-only file tools. */
     getEventReadPath(event) {
@@ -754,23 +894,32 @@ export class ClaudeCodeProvider {
             bk.pendingReadClears.delete(filePath);
         }
         bk.currentReadCounts.set(filePath, (bk.currentReadCounts.get(filePath) ?? 0) + 1);
-        return this.syncSessionCurrentReads(sessionId, bk);
+        this.stampLastTouched(bk, filePath, 'read');
+        return this.syncSessionFileActivityForChild(sessionId);
     }
-    /** Cooldown mirror of {@link scheduleClearToolUseFile} for read-only file tools. */
+    /** Cooldown mirror of {@link scheduleClearToolUseFile} for read-only file tools. Returns
+     *  whether the parent's published `fileActivity` changed (i.e. `reading` flipped off). */
     scheduleClearToolUseRead(sessionId, event) {
         const filePath = this.getEventReadPath(event);
         if (filePath == null)
-            return;
+            return false;
         const bk = this.getBookkeeping(sessionId);
         const count = bk.currentReadCounts.get(filePath);
         // Same guard as scheduleClearToolUseFile — duplicate / out-of-order Posts during cooldown
         // would otherwise drive the refcount negative and stack up redundant clear timers.
         if (count == null || count <= 0)
-            return;
+            return false;
         const next = count - 1;
         bk.currentReadCounts.set(filePath, next);
+        // Re-sync so `reading` drops to `undefined` the moment refcount hits zero.
+        const changed = this.syncSessionFileActivityForChild(sessionId);
         if (next > 0)
-            return;
+            return changed;
+        this.scheduleReadDecayEviction(bk, sessionId, filePath);
+        return changed;
+    }
+    /** Read-class mirror of {@link scheduleFileDecayEviction}. */
+    scheduleReadDecayEviction(bk, sessionId, filePath) {
         const existing = bk.pendingReadClears.get(filePath);
         if (existing != null) {
             clearTimeout(existing);
@@ -785,10 +934,11 @@ export class ClaudeCodeProvider {
             if ((cur.currentReadCounts.get(filePath) ?? 0) > 0)
                 return;
             cur.currentReadCounts.delete(filePath);
-            if (this.syncSessionCurrentReads(sessionId, cur)) {
+            this.clearLastTouched(cur, filePath, 'read');
+            if (this.syncSessionFileActivityForChild(sessionId)) {
                 this._onDidChangeSessions.fire();
             }
-        }, postToolUseClearDelayMs);
+        }, this.activityDecayMs);
         bk.pendingReadClears.set(filePath, timer);
     }
     /** Immediate-drop mirror of {@link untrackToolUseFile} for read-only file tools. */
@@ -802,7 +952,7 @@ export class ClaudeCodeProvider {
             return false;
         if (count > 1) {
             bk.currentReadCounts.set(filePath, count - 1);
-            return false;
+            return this.syncSessionFileActivityForChild(sessionId);
         }
         const pending = bk.pendingReadClears.get(filePath);
         if (pending != null) {
@@ -810,20 +960,89 @@ export class ClaudeCodeProvider {
             bk.pendingReadClears.delete(filePath);
         }
         bk.currentReadCounts.delete(filePath);
-        return this.syncSessionCurrentReads(sessionId, bk);
+        this.clearLastTouched(bk, filePath, 'read');
+        return this.syncSessionFileActivityForChild(sessionId);
     }
-    /** Sync mirror of {@link syncSessionCurrentFiles} for read paths. Uses {@link currentFilesEqual}
-     *  (which is just a generic order-insensitive `string[] | undefined` comparator). */
-    syncSessionCurrentReads(sessionId, bk) {
-        const index = this._sessions.findIndex(s => s.id === sessionId);
-        if (index < 0)
+    /** Convenience wrapper that resolves the parent for a possibly-sub-agent session id, then calls
+     *  {@link syncSessionFileActivity}. Tool-call handlers call this without knowing whether the
+     *  session is a top-level or sub-agent session. Returns `false` when the session isn't found
+     *  (already pruned / unknown peer id). */
+    syncSessionFileActivityForChild(sessionId) {
+        const parentId = this.findOwningParentId(sessionId);
+        if (parentId == null)
             return false;
-        const prev = this._sessions[index];
-        const next = bk.currentReadCounts.size > 0 ? [...bk.currentReadCounts.keys()] : undefined;
-        if (currentFilesEqual(prev.currentReads, next))
+        return this.syncSessionFileActivity(parentId);
+    }
+    /** Rebuilds the parent session's `fileActivity` array from its bookkeeping and writes it onto
+     *  the session in place. Returns whether the *structural* shape changed (paths/kinds/flags) —
+     *  timestamps are always refreshed regardless, but a fire is gated on structural change so
+     *  non-meaningful drift doesn't churn the wire.
+     *
+     *  No separate sub-agent rollup is needed: the GK CLI keys a sub-agent's tool events under its
+     *  PARENT session id (with `agentId` set), so they accumulate in the parent's own bookkeeping
+     *  directly and are already reflected here. Sub-agent serialized objects carry no `fileActivity`. */
+    syncSessionFileActivity(parentSessionId) {
+        const index = this._sessions.findIndex(s => s.id === parentSessionId);
+        if (index < 0)
             return false;
-        this._sessions[index] = { ...prev, currentReads: next };
-        return true;
+        const parent = this._sessions[index];
+        const parentBk = this._sessionBookkeeping.get(parentSessionId);
+        const merged = new Map();
+        const contributeFrom = (bk) => {
+            if (bk == null)
+                return;
+            for (const [path, count] of bk.currentFileCounts) {
+                let entry = merged.get(path);
+                if (entry == null) {
+                    entry = { editCount: 0, readCount: 0 };
+                    merged.set(path, entry);
+                }
+                entry.editCount += count;
+                const ts = bk.lastTouchedAt.get(path)?.edit;
+                if (ts != null && (entry.editAt == null || ts > entry.editAt)) {
+                    entry.editAt = ts;
+                }
+            }
+            for (const [path, count] of bk.currentReadCounts) {
+                let entry = merged.get(path);
+                if (entry == null) {
+                    entry = { editCount: 0, readCount: 0 };
+                    merged.set(path, entry);
+                }
+                entry.readCount += count;
+                const ts = bk.lastTouchedAt.get(path)?.read;
+                if (ts != null && (entry.readAt == null || ts > entry.readAt)) {
+                    entry.readAt = ts;
+                }
+            }
+        };
+        contributeFrom(parentBk);
+        const now = Date.now();
+        let next;
+        if (merged.size > 0) {
+            next = [];
+            for (const [path, contrib] of merged) {
+                const entry = { path: path };
+                if (contrib.editAt != null) {
+                    entry.editedAt = Math.max(0, now - contrib.editAt);
+                }
+                if (contrib.readAt != null) {
+                    entry.readAt = Math.max(0, now - contrib.readAt);
+                }
+                if (contrib.editCount > 0) {
+                    entry.editing = true;
+                }
+                if (contrib.readCount > 0) {
+                    entry.reading = true;
+                }
+                next.push(entry);
+            }
+        }
+        const changed = !fileActivityStructurallyEqual(parent.fileActivity, next);
+        // Always replace so timestamps reflect the latest serialization, even when the structural
+        // shape is unchanged (so a downstream fire from anywhere else carries fresh `sinceMs`).
+        this._sessions[index] = { ...parent, fileActivity: next };
+        return changed;
     }
     /** Defer the `Stop → idle` commit. If the agent produces a non-idle event within
      *  `stopToIdleDebounceMs`, `cancelPendingIdleTransition` (called from `updateSessionStatus`)
@@ -993,7 +1212,7 @@ export class ClaudeCodeProvider {
         }
     }
     ensureSession(sessionId, context) {
-        const { pid, workspacePath, isInWorkspace, cwd, planFile, sessionName } = context ?? {};
+        const { pid, workspacePath, isInWorkspace, cwd, initialCwd, planFile, sessionName } = context ?? {};
         let index = this._sessions.findIndex(s => s.id === sessionId);
         if (index < 0) {
             const now = new Date();
@@ -1011,6 +1230,7 @@ export class ClaudeCodeProvider {
                 isSubagent: false,
                 workspacePath: workspacePath,
                 cwd: cwd,
+                initialCwd: initialCwd ?? cwd,
                 planFile: planFile,
                 isInWorkspace: isInWorkspace ?? false,
             });
@@ -1029,19 +1249,27 @@ export class ClaudeCodeProvider {
         const updatedPlanFile = planFile ?? existing.planFile;
         const updatedName = sessionName || existing.name;
         const updatedCwd = cwd ?? existing.cwd;
+        // Prefer the CLI's authoritative `initialCwd` (the true launch dir it captured first-hand,
+        // even for sessions that started before this window opened); otherwise keep whatever we
+        // already captured, and only as a last resort backfill from the current cwd (older CLIs that
+        // don't send `initialCwd`, or a cold-create before any cwd was known). Comparing live `cwd`
+        // against `initialCwd` is how consumers detect launch-vs-current drift, so it stays stable.
+        const updatedInitialCwd = initialCwd ?? existing.initialCwd ?? cwd;
         let changed = false;
         if (updatedPid !== existing.pid ||
             updatedWorkspacePath !== existing.workspacePath ||
             updatedIsInWorkspace !== existing.isInWorkspace ||
             updatedPlanFile !== existing.planFile ||
             updatedName !== existing.name ||
-            updatedCwd !== existing.cwd) {
+            updatedCwd !== existing.cwd ||
+            updatedInitialCwd !== existing.initialCwd) {
             this._sessions[index] = {
                 ...existing,
                 name: updatedName,
                 pid: updatedPid,
                 workspacePath: updatedWorkspacePath,
                 cwd: updatedCwd,
+                initialCwd: updatedInitialCwd,
                 planFile: updatedPlanFile,
                 isInWorkspace: updatedIsInWorkspace,
             };
@@ -1110,14 +1338,26 @@ export class ClaudeCodeProvider {
                 }
                 return;
             }
+            // Capture the worktree/commonPath at the first successful resolve so consumers can
+            // detect drift (e.g. an agent that `cd`'d into a sibling worktree after launch). Gated
+            // on `initialCommonPath` — captured together with `initialWorktreePath` so a first
+            // resolve where `info.worktreePath` happens to be undefined doesn't leave the latter
+            // open to a later overwrite. Once set, never overwritten.
+            const firstResolve = session.initialCommonPath == null;
+            const updatedInitialWorktreePath = firstResolve ? info.worktreePath : session.initialWorktreePath;
+            const updatedInitialCommonPath = firstResolve ? info.repoRoot : session.initialCommonPath;
             if (cwd !== session.cwd ||
                 info.worktreePath !== session.worktreePath ||
-                info.repoRoot !== session.commonPath) {
+                info.repoRoot !== session.commonPath ||
+                updatedInitialWorktreePath !== session.initialWorktreePath ||
+                updatedInitialCommonPath !== session.initialCommonPath) {
                 this._sessions[index] = {
                     ...session,
                     cwd: cwd,
                     worktreePath: info.worktreePath,
                     commonPath: info.repoRoot,
+                    initialWorktreePath: updatedInitialWorktreePath,
+                    initialCommonPath: updatedInitialCommonPath,
                 };
                 this._onDidChangeSessions.fire();
             }
@@ -1174,13 +1414,29 @@ export class ClaudeCodeProvider {
                 this._pendingPermissions.delete(id);
             }
             this.cancelPendingIdleTransition(id);
+            // Cancel any in-flight decay-eviction timers before dropping the bookkeeping (mirrors
+            // SessionEnd). A Stopped-then-killed session reaches here with armed cooldown timers
+            // (settleBookkeeping leaves them running), so without this they'd leak until they fire.
+            const bk = this._sessionBookkeeping.get(id);
+            if (bk != null) {
+                this.cancelPendingFileClears(bk);
+                this.cancelPendingReadClears(bk);
+            }
             this._sessionBookkeeping.delete(id);
             this._transcriptReader.forget(id);
         }
         Logger.debug(`ClaudeCodeProvider.syncSessions: removed ${removedIds.length} stale session(s): ${removedIds.map(id => id.substring(0, 8)).join(', ')}`);
         return true;
     }
-    async syncSessions() {
+    async syncSessions(options) {
+        // Recurring (gated) calls skip the CLI spawn when there's nothing to reconcile: no tracked
+        // sessions AND no installed hooks. Sessions only ever appear via the IPC push path or a peer,
+        // so an empty list with hooks off means no agents are reachable here. We still poll whenever
+        // sessions exist — that's the only local backstop for pruning agents that die without firing
+        // `SessionEnd`, and it keeps us correct even if hook detection is stale/wrong. The bootstrap
+        // call in `ensureIpcServer` passes no options, so cold-start discovery always runs.
+        if (options?.gate && this._sessions.length === 0 && !this._claudeHooksInstalled)
+            return;
         let sessions;
         try {
             const output = await this.callbacks.runCLICommand(['ai', 'hook', 'list-sessions', '--json']);
@@ -1192,13 +1448,25 @@ export class ClaudeCodeProvider {
             }
             return;
         }
+        // Snapshot what the live IPC path had already tracked, so we can detect drift between it and
+        // what the poll returns. Ideally they match exactly — any difference means the live push path
+        // missed an add (poll discovers it) or a teardown (poll no longer reports a session we track).
+        const trackedBefore = new Set(this._sessions.map(s => s.id));
+        const polledAlive = new Set();
+        // Mutable copy of `trackedBefore` that also accumulates ids added during this poll, so the
+        // membership check below is O(1) and duplicate ids within a single poll response are only
+        // added once. `trackedBefore` itself stays the pre-poll snapshot used by the `missing` calc.
+        const known = new Set(trackedBefore);
         let changed = false;
+        let discovered = 0;
         for (const data of sessions) {
             if (!data.sessionId || !data.pid || !isProcessAlive(data.pid)) {
                 continue;
             }
-            if (this._sessions.some(s => s.id === data.sessionId))
+            polledAlive.add(data.sessionId);
+            if (known.has(data.sessionId))
                 continue;
+            known.add(data.sessionId);
             const workspacePath = this.resolveWorkspacePath(data.cwd);
             const isInWorkspace = workspacePath != null;
             const status = deriveStatusFromEvent(data.event);
@@ -1230,6 +1498,10 @@ export class ClaudeCodeProvider {
                 isSubagent: false,
                 workspacePath: workspacePath,
                 cwd: data.cwd,
+                // Prefer the CLI's launch dir; fall back to the snapshot's (possibly drifted) cwd on
+                // older CLIs that don't record it. Without this, a window that cold-starts after the
+                // agent drifted would stamp the drifted cwd as the launch dir.
+                initialCwd: data.initialCwd ?? data.cwd,
                 planFile: data.planFile ?? undefined,
                 isInWorkspace: isInWorkspace,
                 lastPrompt: prepareStoredPrompt(data.prompt ?? undefined),
@@ -1237,6 +1509,7 @@ export class ClaudeCodeProvider {
                 subagents: subagents,
             });
             changed = true;
+            discovered++;
             if (data.cwd) {
                 void this.resolveGitInfo(data.sessionId, data.cwd);
             }
@@ -1248,6 +1521,28 @@ export class ClaudeCodeProvider {
         if (changed) {
             this._onDidChangeSessions.fire();
         }
+        // Report any drift between the live-synced set and the poll. Only on the recurring (gated)
+        // poll — the ungated bootstrap call runs before the live path has had a chance to receive
+        // any events, so its discoveries are expected cold-start state, not drift. `missing` counts
+        // sessions we still track that the poll no longer reports alive (a teardown the live path
+        // missed, e.g. an agent killed without firing `SessionEnd`).
+        if (options?.gate) {
+            let missing = 0;
+            for (const id of trackedBefore) {
+                if (!polledAlive.has(id)) {
+                    missing++;
+                }
+            }
+            if (discovered > 0 || missing > 0) {
+                this.callbacks.onSyncDiscrepancy?.({
+                    provider: this.id,
+                    discovered: discovered,
+                    missing: missing,
+                    polled: polledAlive.size,
+                    tracked: trackedBefore.size,
+                });
+            }
+        }
     }
     async querySiblingWindowSessions() {
         const discoveryDir = this.callbacks.ipc.agentDiscoveryDir;
@@ -1300,6 +1595,7 @@ export class ClaudeCodeProvider {
                             this.cancelPendingReadClears(bk);
                             bk.currentFileCounts.clear();
                             bk.currentReadCounts.clear();
+                            bk.lastTouchedAt.clear();
                         }
                         this._sessions[idx] = {
                             ...existing,
@@ -1309,17 +1605,27 @@ export class ClaudeCodeProvider {
                             statusDetail: peerSession.statusDetail,
                             lastActivity: peerActivity,
                             subagents: rehydrateSubagents(peerSession.subagents),
-                            // Carry the peer's in-flight file-edit set + repo identity across so
-                            // peer-window WIP decorations + sameFamily anchoring follow the agent.
-                            // Owned by the peer (it's the hook recipient); we never originate these
-                            // fields for a remote session.
-                            currentFiles: peerSession.currentFiles,
-                            currentReads: peerSession.currentReads,
+                            // Carry the peer's published fileActivity across so peer-window WIP
+                            // decorations + treemap heatmap follow the agent. Owned by the peer (it's
+                            // the hook recipient); we never originate this field for a remote session.
+                            fileActivity: peerSession.fileActivity,
+                            // Track the peer's resolved repo identity. The peer owns the hook flow and
+                            // re-resolves both on `CwdChanged`, so a worktree move (e.g. the agent
+                            // `cd`'d into a sibling worktree of the same repo — `commonPath` unchanged
+                            // but `worktreePath` changed) only reaches us if we carry BOTH. Carrying
+                            // `commonPath` alone froze the displayed worktree at first-discovery.
+                            worktreePath: peerSession.worktreePath ?? existing.worktreePath,
                             commonPath: peerSession.commonPath ?? existing.commonPath,
                             // Pick up the peer's latest cwd so our backfill probe (queued below)
                             // targets the right path. Stale-cwd locally would just re-probe the
                             // non-repo dir and hit the gitInfoUnresolvable retry guard again.
                             cwd: cwdChanged ? peerSession.cwd : existing.cwd,
+                            // Launch-state fields are immutable per session: prefer whichever side
+                            // already set them (peer that owns the hook flow typically sets first),
+                            // and never overwrite a populated local value with the peer's.
+                            initialCwd: existing.initialCwd ?? peerSession.initialCwd,
+                            initialWorktreePath: existing.initialWorktreePath ?? peerSession.initialWorktreePath,
+                            initialCommonPath: existing.initialCommonPath ?? peerSession.initialCommonPath,
                             // Forward peer-discovered transcript titles. Both windows can resolve them
                             // independently against the same on-disk transcript, but only the peer's
                             // hook flow drives its updates — without this, we'd freeze the snapshot