From 49eec0334abfe3736316e915f753b1ae7f2d1eda Mon Sep 17 00:00:00 2001
From: Jean-Baptiste <jean-baptiste@konvex-it.fr>
Date: Sun, 13 Sep 2026 13:04:30 +0200
Subject: [PATCH 1/3] (session-state): subagent activity feeds the same running
 set and the same rung for every source

A remote or local-transcript subagent event now threads its agentId into
activeSubagentsByParent through one write path, so the child row gets the
same running dot, slot and TTL as a local PTY subagent. Closes #285.

On a remote parent, a busy touch that coincides with a fresh subagent spawn
(3 s window, either order) no longer outranks agentsBusy for the 20 s decay:
the Task-tool invocation writes the parent's own transcript too, which put
the remote row on the animated busy rung while the local row sat on the
static agents-busy rung. A busy touch outside the window still wins.
Closes #284.
---
 .ai/contexts/session-state.md                 |  26 +++
 .ai/contexts/subagent-observability.md        |  36 ++++
 eslint.config.js                              |   2 +
 public/local-transcript-adapter.js            |   5 +
 public/remote-activity-ui.js                  |  33 +++-
 public/sidebar.js                             |  30 +--
 ...om-sidebar-subagent-running-parity.test.js | 180 ++++++++++++++++++
 test/remote-session-adapter.test.js           |  52 +++++
 8 files changed, 352 insertions(+), 12 deletions(-)
 create mode 100644 test/dom-sidebar-subagent-running-parity.test.js

diff --git a/.ai/contexts/session-state.md b/.ai/contexts/session-state.md
index 0b2628ae..876c0900 100644
--- a/.ai/contexts/session-state.md
+++ b/.ai/contexts/session-state.md
@@ -189,6 +189,32 @@ per remote session id in `remoteSessionStates` (a `Map`, pruned in
 `projectLocalPtyState`, see "The local-pty adapter" below), just fed from the
 remote-ssh adapter's own snapshot instead.
 
+### A coincident parent-file touch must not outrank a fresh subagent spawn (issue #284)
+
+A Task-tool invocation typically appends to the parent's own top-level
+transcript (recording the tool_use/tool_result around the spawn) at almost
+the same moment it appends to the subagent's own file. On the remote-ssh
+adapter this used to mean a plain `busy` edge could win the icon rung over
+`agentsBusy` for its full 20s decay, even though the top-level agent was
+really just idle waiting on the subagent — visibly different from a local-pty
+row, which reflects the OSC-driven busy edge instantly and clears it just as
+fast. Fixed with a **3s coincidence window** (`SUBAGENT_BUSY_COINCIDENCE_MS`,
+`public/remote-activity-ui.js`) keyed off the moment `agentsBusy` transitions
+false→true (`remoteSubagentSpawnAt`), not every subsequent subagent touch: a
+plain busy touch inside that window of a fresh spawn is recorded
+(`transcriptTouched`) but not applied as `busy`, and a spawn arriving shortly
+after an already-live busy touch retroactively demotes it (cancels its decay
+timer, applies `busy:false`). A busy touch outside the window — the top-level
+agent genuinely still producing output — is unaffected and wins the rung
+normally, tinted violet by the existing `.has-busy-agents .session-icon--busy::before`
+rule. The window is deliberately keyed off the *spawn edge*, not a
+continuously-refreshed "last subagent touch" timestamp: a chatty subagent
+writes roughly once a second (`remote-activity.js`'s `DEFAULT_IPC_MIN_MS`
+throttle), which would otherwise keep re-arming the window for the entire
+run and permanently suppress a genuinely concurrent busy parent. `PRIORITY`
+in `session-state.js` is unchanged — this is a renderer-side demotion of
+which events reach `apply()`, not a reordering of the ladder.
+
 ### Row ownership: attached vs unattached (issue #273)
 
 An attached remote row (a tab open on it) is owned by the local-pty path —
diff --git a/.ai/contexts/subagent-observability.md b/.ai/contexts/subagent-observability.md
index 976eeadf..e2b5e35e 100644
--- a/.ai/contexts/subagent-observability.md
+++ b/.ai/contexts/subagent-observability.md
@@ -93,6 +93,42 @@ This is the **#1 fork-specific feature** (upstream PR #47 still pending). It per
   prune until PR #137. Keep cross-file names distinct;
   `test/dom-grid-sidebar-prune-collision.test.js` pins the pair.
 
+## The child row's own `.running` dot, for every source (issue #285)
+
+`activeSubagentsByParent` (above) used to be fed only by the local
+`subagent-spawned`/`subagent-completed` IPC pair, so a remote or
+local-transcript subagent's own row never got `.running` — not even after a
+full rebuild — even though both sources' `kind:'subagent'` payload already
+carries `agentId` (`remote-activity.js`, `local-transcript-activity.js`).
+`noteSubagentActivity(parentSessionId, agentId)` (`public/sidebar.js`) is now
+the single write path into that map: the local IPC handler, `onRemoteActivityEvent`'s
+subagent branch (`remote-activity-ui.js`) and `onLocalTranscriptSubagentActivity`
+(`local-transcript-adapter.js`) all call it, so all three share the same 60s
+TTL/decay convention `isSubagentActive`/`pruneStaleSubagents` already
+implement — no second, independently-tuned decay was added.
+
+A suspected second cause (`reflectSubagentRunningState`'s DOM lookup,
+`subagentDomId(parent, agentId)` vs. the row's own id) turned out not to
+reproduce: every subagent row's `sessionId` is built by
+`subagentSessionId(parent, agentId)` = `'sub:'+parent+':'+agentId`
+(`read-session-file.js`), for local, remote-mirrored and legacy-layout rows
+alike, so `'si-' + session.sessionId` and `subagentDomId(parent, agentId)`
+are byte-identical by construction. `test/dom-sidebar-subagent-running.test.js`
+already pinned this for the local IPC path with no rebuild; the actual gap
+was purely the missing feed, not the lookup.
+
+One landmine found while wiring this: `reflectSubagentRunningState` also
+repaints the **parent's** icon slot via `paintSessionIcon`, which paints from
+the local-pty adapter's snapshot (`snapshotForLocal` auto-vivifies a
+`localPtyState` entry). Calling it for a remote/local-transcript parent would
+have overwritten the icon the remote-ssh/local-transcript adapter's own
+`projectRemoteState`/`projectLocalTranscriptState` had just painted, with an
+empty local-pty snapshot. `reflectSubagentRunningState` now skips that
+repaint when `remoteSessionStates`/`localTranscriptStates` already holds an
+entry for the parent — the calling adapter has already repainted its own
+slot by that point (it creates the entry before calling
+`noteSubagentActivity`).
+
 ## Attribution across sources (issue #247)
 
 `.has-busy-agents` used to light only for a parent reachable from
diff --git a/eslint.config.js b/eslint.config.js
index 2da2def3..52d399cb 100644
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -186,6 +186,8 @@ const rendererCrossFileGlobals = {
   // public/sidebar.js, consumed by session-activity-dom.js's snapshotForLocal
   // (see .ai/contexts/session-state.md, "The icon slot (step 3b)")
   parentHasActiveSubagent: 'readonly',
+  // public/sidebar.js — see .ai/contexts/subagent-observability.md
+  noteSubagentActivity: 'readonly',
 
   // Third-party renderer libs loaded as <script>
   morphdom: 'readonly',
diff --git a/public/local-transcript-adapter.js b/public/local-transcript-adapter.js
index d23c0c47..f71d6244 100644
--- a/public/local-transcript-adapter.js
+++ b/public/local-transcript-adapter.js
@@ -105,6 +105,11 @@ function onLocalTranscriptSubagentActivity(payload) {
   seedLocalTranscriptDescriptor(parentSessionId);
   projectLocalTranscriptState(parentSessionId);
   armLocalTranscriptAgentsDecayTimer(parentSessionId);
+  // per-(parent, agentId) running set for the child row's own dot — see .ai/contexts/subagent-observability.md
+  const agentId = payload.agentId;
+  if (typeof agentId === 'string' && agentId && typeof noteSubagentActivity === 'function') {
+    noteSubagentActivity(parentSessionId, agentId);
+  }
 }
 
 // called once a row gains a PTY; the local-pty path takes over from here — see .ai/contexts/session-state.md
diff --git a/public/remote-activity-ui.js b/public/remote-activity-ui.js
index 0b115ffc..11f37f82 100644
--- a/public/remote-activity-ui.js
+++ b/public/remote-activity-ui.js
@@ -7,6 +7,10 @@ const remoteActivityDecayTimers = new Map();
 // separate decay for subagent attribution (agentsBusy) — see .ai/contexts/subagent-observability.md
 const remoteAgentsDecayTimers = new Map();
 
+// coincidence window for a Task-tool invocation's parent-file touch — see .ai/contexts/session-state.md (issue #284)
+const SUBAGENT_BUSY_COINCIDENCE_MS = 3000;
+const remoteSubagentSpawnAt = new Map();
+
 // remote-ssh adapter: one persistent state per remote session id — see .ai/contexts/session-state.md
 const remoteSessionStates = new Map();
 
@@ -50,7 +54,15 @@ function clearRemoteAgentsTimer(sessionId) {
 function markRemoteBusy(sessionId, via, at) {
   const state = remoteState(sessionId);
   if (state.snapshot().attached) return;
-  state.apply({ type: 'transcriptTouched', at: at || Date.now(), source: via });
+  const t = at || Date.now();
+  const spawnAt = remoteSubagentSpawnAt.get(sessionId);
+  if (spawnAt !== undefined && state.snapshot().agentsBusy && t - spawnAt <= SUBAGENT_BUSY_COINCIDENCE_MS) {
+    // see .ai/contexts/session-state.md (issue #284)
+    state.apply({ type: 'transcriptTouched', at: t, source: via });
+    projectRemoteState(sessionId);
+    return;
+  }
+  state.apply({ type: 'transcriptTouched', at: t, source: via });
   state.apply({ type: 'busy', active: true });
   setActivity(sessionId, true, via);
   projectRemoteState(sessionId);
@@ -91,7 +103,16 @@ function armRemoteAgentsDecayTimer(sessionId) {
 // attributes a subagent write to its parent's own state — see .ai/contexts/subagent-observability.md
 function markRemoteSubagentBusy(sessionId) {
   const state = remoteState(sessionId);
+  const wasAgentsBusy = state.snapshot().agentsBusy;
   state.apply({ type: 'subagentSpawned' });
+  if (!wasAgentsBusy) {
+    // see .ai/contexts/session-state.md (issue #284)
+    remoteSubagentSpawnAt.set(sessionId, Date.now());
+    if (state.snapshot().busy) {
+      clearRemoteActivityTimer(sessionId);
+      state.apply({ type: 'busy', active: false, armReady: false });
+    }
+  }
   projectRemoteState(sessionId);
   armRemoteAgentsDecayTimer(sessionId);
 }
@@ -109,6 +130,9 @@ function pruneRemoteActivityTimers() {
   for (const sessionId of remoteSeedFloors.keys()) {
     if (!sessionItemEl(sessionId)) remoteSeedFloors.delete(sessionId);
   }
+  for (const sessionId of remoteSubagentSpawnAt.keys()) {
+    if (!sessionItemEl(sessionId)) remoteSubagentSpawnAt.delete(sessionId);
+  }
 }
 
 function onRemoteActivityEvent(payload) {
@@ -116,6 +140,11 @@ function onRemoteActivityEvent(payload) {
     const parentSessionId = payload.parentSessionId;
     if (typeof parentSessionId !== 'string' || !parentSessionId) return;
     markRemoteSubagentBusy(parentSessionId);
+    // per-(parent, agentId) running set for the child row's own dot — see .ai/contexts/subagent-observability.md
+    const agentId = payload.agentId;
+    if (typeof agentId === 'string' && agentId && typeof noteSubagentActivity === 'function') {
+      noteSubagentActivity(parentSessionId, agentId);
+    }
     return;
   }
   const sessionId = payload && payload.sessionId;
@@ -158,6 +187,8 @@ function setRemoteAttached(sessionId, attached) {
 function applyRemoteStopped(sessionId) {
   clearRemoteActivityTimer(sessionId);
   clearRemoteAgentsTimer(sessionId);
+  remoteSubagentSpawnAt.delete(sessionId);
+  if (typeof clearActiveSubagentsFor === 'function') clearActiveSubagentsFor(sessionId);
   const state = remoteState(sessionId);
   state.apply({ type: 'busy', active: false, armReady: false });
   state.apply({ type: 'attention', active: false });
diff --git a/public/sidebar.js b/public/sidebar.js
index cb025de6..5c80630f 100644
--- a/public/sidebar.js
+++ b/public/sidebar.js
@@ -261,11 +261,25 @@ function reflectSubagentRunningState(parentSessionId, agentId) {
   // precedence over it.
   const parentEl = document.getElementById('si-' + parentSessionId);
   setHasBusyAgents(parentEl, parentHasActiveSubagent(parentSessionId));
-  // Re-paint the parent's icon slot too — see .ai/contexts/session-state.md
-  if (parentEl) paintSessionIcon(parentEl.querySelector('.session-icon'), parentSessionId);
+  // parent slot repainted only when local-pty owns it — see .ai/contexts/subagent-observability.md
+  const remoteOwned = typeof remoteSessionStates !== 'undefined' && remoteSessionStates.has(parentSessionId);
+  const localTranscriptOwned = typeof localTranscriptStates !== 'undefined' && localTranscriptStates.has(parentSessionId);
+  if (parentEl && !remoteOwned && !localTranscriptOwned) paintSessionIcon(parentEl.querySelector('.session-icon'), parentSessionId);
   if (window.ATRACE) window.atrace('class.subagent', parentSessionId, { agentId, running, childEl: el ? el.id : null, caretEl: caret ? caret.id : null, parentEl: parentEl ? parentEl.id : null, 'has-busy-agents': parentHasActiveSubagent(parentSessionId), fn: 'reflectSubagentRunningState' });
 }
 
+// single write path into activeSubagentsByParent — see .ai/contexts/subagent-observability.md
+function noteSubagentActivity(parentSessionId, agentId) {
+  let map = activeSubagentsByParent.get(parentSessionId);
+  if (!map) {
+    map = new Map();
+    activeSubagentsByParent.set(parentSessionId, map);
+  }
+  map.set(agentId, Date.now());
+  scheduleSubagentTtlTick();
+  reflectSubagentRunningState(parentSessionId, agentId);
+}
+
 (function initSubagentLiveListeners() {
   if (!window.api) return; // guard for test/non-Electron contexts without preload
 
@@ -273,21 +287,15 @@ function reflectSubagentRunningState(parentSessionId, agentId) {
     window.api.onSubagentSpawned((payload) => {
       const { parentSessionId, agentId, _heartbeat } = payload || {};
       if (!parentSessionId || !agentId) return;
-      let map = activeSubagentsByParent.get(parentSessionId);
+      const map = activeSubagentsByParent.get(parentSessionId);
       // A heartbeat means "still alive", never "started": it must not create
       // an entry for an agent we are not tracking.
       if (_heartbeat && !(map && map.has(agentId))) {
         if (window.ATRACE) window.atrace('recv.subagent-spawned', parentSessionId, { map: 'activeSubagentsByParent', op: 'ignore', agentId, heartbeat: true, applied: false, reason: 'heartbeat-for-untracked-agent', fn: 'onSubagentSpawned' });
         return;
       }
-      if (!map) {
-        map = new Map();
-        activeSubagentsByParent.set(parentSessionId, map);
-      }
-      if (window.ATRACE) window.atrace('recv.subagent-spawned', parentSessionId, { map: 'activeSubagentsByParent', op: 'set', agentId, from: map.get(agentId) ?? null, applied: true, bootstrap: !!payload._bootstrap, heartbeat: !!_heartbeat, fn: 'onSubagentSpawned' });
-      map.set(agentId, Date.now());
-      scheduleSubagentTtlTick();
-      reflectSubagentRunningState(parentSessionId, agentId);
+      if (window.ATRACE) window.atrace('recv.subagent-spawned', parentSessionId, { map: 'activeSubagentsByParent', op: 'set', agentId, from: map ? (map.get(agentId) ?? null) : null, applied: true, bootstrap: !!payload._bootstrap, heartbeat: !!_heartbeat, fn: 'onSubagentSpawned' });
+      noteSubagentActivity(parentSessionId, agentId);
     });
   }
 
diff --git a/test/dom-sidebar-subagent-running-parity.test.js b/test/dom-sidebar-subagent-running-parity.test.js
new file mode 100644
index 00000000..c7d9ffec
--- /dev/null
+++ b/test/dom-sidebar-subagent-running-parity.test.js
@@ -0,0 +1,180 @@
+// Issue #285 — a running subagent's own row never got the green `.running`
+// dot when its activity came from the remote watch channel or the
+// local-transcript adapter, even after a full sidebar rebuild. Both adapters
+// received `agentId` in their payload already (public/remote-activity.js,
+// local-transcript-activity.js) but only fed the parent's own agentsBusy
+// field. See .ai/contexts/subagent-observability.md ("Attribution across
+// sources") and .ai/contexts/session-state.md.
+//
+// B2 (the DOM-id lookup) was investigated separately and does not reproduce
+// for a real subagent row: buildSubagentItem ids the row 'si-' + session.
+// sessionId, and every subagent session.sessionId in session_cache is built
+// via subagentSessionId(parent, agentId) = 'sub:'+parent+':'+agentId
+// (read-session-file.js), for local, remote-mirrored and legacy-layout rows
+// alike — byte-identical to subagentDomId(parent, agentId) =
+// 'si-sub:'+parent+':'+agentId. test/dom-sidebar-subagent-running.test.js
+// already pins the local IPC path landing .running with no rebuild; test 4
+// below re-confirms it in this file for completeness.
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const { setupSidebarDom, makeSampleProject } = require('./dom-setup');
+
+function projectWithRemoteSubagent() {
+  return makeSampleProject({
+    remoteAlias: 'vps',
+    sessions: [
+      {
+        sessionId: 'r-top-1',
+        remoteAlias: 'vps',
+        name: 'remote main session',
+        summary: 'remote top level',
+        modified: '2026-05-22T10:00:00.000Z',
+        starred: false,
+        archived: 0,
+        messageCount: 1,
+      },
+      {
+        sessionId: 'sub:r-top-1:agent-1',
+        parentSessionId: 'r-top-1',
+        agentId: 'agent-1',
+        remoteAlias: 'vps',
+        subagentType: 'explore',
+        description: 'explore subagent',
+        modified: '2026-05-22T09:59:00.000Z',
+        messageCount: 1,
+      },
+    ],
+  });
+}
+
+function projectWithLocalTranscriptSubagent() {
+  return makeSampleProject({
+    sessions: [
+      {
+        sessionId: 'l-top-1',
+        name: 'local main session, no PTY',
+        summary: 'local top level',
+        modified: '2026-05-22T10:00:00.000Z',
+        starred: false,
+        archived: 0,
+        messageCount: 1,
+      },
+      {
+        sessionId: 'sub:l-top-1:agent-1',
+        parentSessionId: 'l-top-1',
+        agentId: 'agent-1',
+        subagentType: 'explore',
+        description: 'explore subagent',
+        modified: '2026-05-22T09:59:00.000Z',
+        messageCount: 1,
+      },
+    ],
+  });
+}
+
+function projectWithLocalSubagent() {
+  return makeSampleProject({
+    sessions: [
+      {
+        sessionId: 's-top-1',
+        name: 'main session',
+        summary: 'top level 1',
+        modified: '2026-05-22T10:00:00.000Z',
+        starred: false,
+        archived: 0,
+        messageCount: 1,
+      },
+      {
+        sessionId: 'sub:s-top-1:agent-1',
+        parentSessionId: 's-top-1',
+        agentId: 'agent-1',
+        subagentType: 'explore',
+        description: 'explore subagent',
+        modified: '2026-05-22T09:59:00.000Z',
+        messageCount: 1,
+      },
+    ],
+  });
+}
+
+test('a remote subagent watch event sets .running on the child row without a full rebuild', () => {
+  const ctx = setupSidebarDom();
+  try {
+    ctx.sidebar.renderProjects([projectWithRemoteSubagent()], true);
+    const item = ctx.document.getElementById('si-sub:r-top-1:agent-1');
+    assert.ok(item, 'remote subagent item must be rendered');
+    assert.ok(!item.classList.contains('running'), 'not running before the event');
+
+    assert.equal(typeof ctx.window.onRemoteActivityEvent, 'function');
+    ctx.window.onRemoteActivityEvent({ alias: 'vps', parentSessionId: 'r-top-1', agentId: 'agent-1', at: Date.now(), kind: 'subagent' });
+
+    assert.ok(item.classList.contains('running'), '.running set on the remote subagent item after the watch event, no rebuild needed');
+    const dot = item.querySelector('.session-icon');
+    assert.ok(dot.classList.contains('running'), '.running set on the dot too');
+
+    // The parent's own icon slot must still reflect the remote-ssh adapter's
+    // own snapshot (agentsBusy), not get overwritten by a local-pty snapshot —
+    // see .ai/contexts/subagent-observability.md.
+    const parent = ctx.document.getElementById('si-r-top-1');
+    assert.ok(parent.classList.contains('has-busy-agents'), 'parent still shows has-busy-agents');
+    assert.ok(parent.querySelector('.session-icon').classList.contains('session-icon--agents-busy'),
+      'parent icon slot still resolves to the agents-busy rung, not reset by the child update');
+  } finally {
+    ctx.destroy();
+  }
+});
+
+test('a local-transcript subagent activity event sets .running on the child row without a full rebuild', () => {
+  const ctx = setupSidebarDom();
+  try {
+    ctx.sidebar.renderProjects([projectWithLocalTranscriptSubagent()], true);
+    const item = ctx.document.getElementById('si-sub:l-top-1:agent-1');
+    assert.ok(item, 'local-transcript subagent item must be rendered');
+    assert.ok(!item.classList.contains('running'), 'not running before the event');
+
+    ctx.emitSessionTranscriptActivity({ parentSessionId: 'l-top-1', agentId: 'agent-1', at: Date.now(), kind: 'subagent' });
+
+    assert.ok(item.classList.contains('running'), '.running set on the local-transcript subagent item, no rebuild needed');
+    assert.ok(item.querySelector('.session-icon').classList.contains('running'), '.running set on the dot too');
+  } finally {
+    ctx.destroy();
+  }
+});
+
+test('decay: a remote subagent stops being reported and the TTL prune clears .running', () => {
+  const ctx = setupSidebarDom();
+  try {
+    ctx.sidebar.renderProjects([projectWithRemoteSubagent()], true);
+    ctx.window.onRemoteActivityEvent({ alias: 'vps', parentSessionId: 'r-top-1', agentId: 'agent-1', at: Date.now(), kind: 'subagent' });
+
+    const item = ctx.document.getElementById('si-sub:r-top-1:agent-1');
+    assert.ok(item.classList.contains('running'), 'running right after the event');
+
+    const t0 = ctx.window.Date.now();
+    ctx.window.Date.now = () => t0 + 61000; // past the 60s TTL shared with the local IPC path
+
+    ctx.sidebar.renderProjects([projectWithRemoteSubagent()], false);
+
+    const after = ctx.document.getElementById('si-sub:r-top-1:agent-1');
+    assert.ok(!after.classList.contains('running'), '.running cleared by the same TTL prune used for local subagents');
+  } finally {
+    ctx.destroy();
+  }
+});
+
+test('local IPC subagent-spawned still sets .running on the child row immediately (no rebuild)', () => {
+  const ctx = setupSidebarDom();
+  try {
+    ctx.sidebar.renderProjects([projectWithLocalSubagent()], true);
+    const item = ctx.document.getElementById('si-sub:s-top-1:agent-1');
+    assert.ok(!item.classList.contains('running'), 'not running before spawn');
+
+    ctx.emitSubagentSpawned({ parentSessionId: 's-top-1', agentId: 'agent-1', subagentType: 'explore' });
+
+    assert.ok(item.classList.contains('running'), '.running set immediately — subagentDomId matches the rendered row id');
+  } finally {
+    ctx.destroy();
+  }
+});
diff --git a/test/remote-session-adapter.test.js b/test/remote-session-adapter.test.js
index 8b417abb..3899e957 100644
--- a/test/remote-session-adapter.test.js
+++ b/test/remote-session-adapter.test.js
@@ -208,3 +208,55 @@ test('a mutant subagent decay that leaves agentsBusy stillActive would be caught
   assert.equal(t.snapshot('s1').agentsBusy, false);
   t.destroy();
 });
+
+// Issue #284 — a Task-tool invocation touches the parent's own transcript as
+// well as the subagent leg; the parent-file touch used to win the busy rung
+// for its full 20s decay even though the top-level agent was really just
+// idle waiting on the subagent. See .ai/contexts/session-state.md.
+
+test('a parent-file busy touch immediately followed by a fresh subagent spawn is demoted — the rung lands on agentsBusy', () => {
+  const t = setup(['s1']);
+  t.emit({ sessionId: 's1', at: Date.now() });
+  assert.equal(t.snapshot('s1').busy, true, 'precondition: the parent-file touch marks busy');
+
+  t.emit({ alias: 'vps', parentSessionId: 's1', agentId: 'agent-1', at: Date.now(), kind: 'subagent' });
+  const snap = t.snapshot('s1');
+  assert.equal(snap.busy, false, 'the coincident spawn demotes the busy it just won');
+  assert.equal(snap.agentsBusy, true);
+
+  const { renderSessionIcon } = require('../public/session-state.js');
+  assert.ok(renderSessionIcon(snap).slotClasses.includes('session-icon--agents-busy'),
+    'rung is agentsBusy, not busy');
+  t.destroy();
+});
+
+test('a fresh subagent spawn immediately followed by a parent-file busy touch keeps the rung on agentsBusy', () => {
+  const t = setup(['s1']);
+  t.emit({ alias: 'vps', parentSessionId: 's1', agentId: 'agent-1', at: Date.now(), kind: 'subagent' });
+  assert.equal(t.snapshot('s1').agentsBusy, true);
+
+  t.emit({ sessionId: 's1', at: Date.now() });
+  const snap = t.snapshot('s1');
+  assert.equal(snap.busy, false, 'the busy touch coincident with the fresh spawn is suppressed');
+  assert.equal(snap.agentsBusy, true);
+
+  const { renderSessionIcon } = require('../public/session-state.js');
+  assert.ok(renderSessionIcon(snap).slotClasses.includes('session-icon--agents-busy'),
+    'rung is agentsBusy, not busy');
+  t.destroy();
+});
+
+test('a busy touch well after the coincidence window still wins the rung — a genuinely busy parent must still show busy', () => {
+  const t = setup(['s1']);
+  const t0 = 1000000;
+  t.window.Date.now = () => t0;
+  t.emit({ alias: 'vps', parentSessionId: 's1', agentId: 'agent-1', at: t0, kind: 'subagent' });
+  assert.equal(t.snapshot('s1').agentsBusy, true);
+
+  t.window.Date.now = () => t0 + 5000; // past the 3s coincidence window
+  t.emit({ sessionId: 's1', at: t0 + 5000 });
+  const snap = t.snapshot('s1');
+  assert.equal(snap.busy, true, 'a later, non-coincident busy touch is not suppressed');
+  assert.equal(snap.agentsBusy, true, 'agentsBusy is unaffected');
+  t.destroy();
+});

From 3fa5d85caca84990d860c8a901452b385137e7a0 Mon Sep 17 00:00:00 2001
From: Jean-Baptiste <jean-baptiste@konvex-it.fr>
Date: Sun, 13 Sep 2026 13:35:23 +0200
Subject: [PATCH 2/3] (session-state): shorten the remote parent's busy decay
 while a subagent runs; ownership guard honours attach

Replaces the coincidence window: a remote parent's busy decay is 3 s
instead of 20 s whenever agentsBusy is set, on every subagent touch rather
than the first spawn edge, and busy is never cleared synchronously. A parent
that really works keeps writing at the 1 s throttle and stays busy; one
merely bookending a Task-tool call lands on agentsBusy within seconds.

reflectSubagentRunningState now repaints the parent slot unless the row is
genuinely remote-owned (present and not attached), so an attached remote
row gets the same live repaint as a local one.
---
 .ai/contexts/session-state.md                 |  54 ++++--
 .ai/contexts/subagent-observability.md        |  23 ++-
 eslint.config.js                              |   2 +
 public/remote-activity-ui.js                  |  59 ++++---
 public/sidebar.js                             |   2 +-
 ...om-sidebar-subagent-running-parity.test.js |  76 ++++++++
 test/remote-session-adapter.test.js           | 162 ++++++++++++++----
 7 files changed, 292 insertions(+), 86 deletions(-)

diff --git a/.ai/contexts/session-state.md b/.ai/contexts/session-state.md
index 876c0900..b31dfff2 100644
--- a/.ai/contexts/session-state.md
+++ b/.ai/contexts/session-state.md
@@ -189,7 +189,7 @@ per remote session id in `remoteSessionStates` (a `Map`, pruned in
 `projectLocalPtyState`, see "The local-pty adapter" below), just fed from the
 remote-ssh adapter's own snapshot instead.
 
-### A coincident parent-file touch must not outrank a fresh subagent spawn (issue #284)
+### A parent's busy decay shortens while a subagent is running (issue #284)
 
 A Task-tool invocation typically appends to the parent's own top-level
 transcript (recording the tool_use/tool_result around the spawn) at almost
@@ -198,22 +198,42 @@ adapter this used to mean a plain `busy` edge could win the icon rung over
 `agentsBusy` for its full 20s decay, even though the top-level agent was
 really just idle waiting on the subagent — visibly different from a local-pty
 row, which reflects the OSC-driven busy edge instantly and clears it just as
-fast. Fixed with a **3s coincidence window** (`SUBAGENT_BUSY_COINCIDENCE_MS`,
-`public/remote-activity-ui.js`) keyed off the moment `agentsBusy` transitions
-false→true (`remoteSubagentSpawnAt`), not every subsequent subagent touch: a
-plain busy touch inside that window of a fresh spawn is recorded
-(`transcriptTouched`) but not applied as `busy`, and a spawn arriving shortly
-after an already-live busy touch retroactively demotes it (cancels its decay
-timer, applies `busy:false`). A busy touch outside the window — the top-level
-agent genuinely still producing output — is unaffected and wins the rung
-normally, tinted violet by the existing `.has-busy-agents .session-icon--busy::before`
-rule. The window is deliberately keyed off the *spawn edge*, not a
-continuously-refreshed "last subagent touch" timestamp: a chatty subagent
-writes roughly once a second (`remote-activity.js`'s `DEFAULT_IPC_MIN_MS`
-throttle), which would otherwise keep re-arming the window for the entire
-run and permanently suppress a genuinely concurrent busy parent. `PRIORITY`
-in `session-state.js` is unchanged — this is a renderer-side demotion of
-which events reach `apply()`, not a reordering of the ladder.
+fast.
+
+**First attempt (reverted in review): a 3s coincidence window keyed off the
+`agentsBusy` false→true edge.** Two adversarial-review findings killed it.
+First, a genuinely busy parent that spawns a subagent lost `busy` outright:
+every touch inside the post-spawn window was swallowed and never re-applied,
+so a parent writing every ~1s could sit at `agentsBusy` even while it was
+still producing output itself. Second, the edge only fires once — a second
+subagent spawned while the first was still running had no edge to key off,
+`remoteSubagentSpawnAt` stayed stale, and its coincident parent-file touch
+armed the full 20s `busy` decay again: the original bug, for the ordinary
+sequential-agents case.
+
+**Current design: no window, no edge — the decay *length* itself depends on
+`agentsBusy`.** `remoteBusyDecayMs(sessionId)` (`public/remote-activity-ui.js`)
+returns `SUBAGENT_PARENT_DECAY_MS` (3000ms) when `agentsBusy` is true,
+`PIP_DECAY_MS` (20000ms) otherwise; `onRemoteActivityEvent`'s plain-touch
+branch arms the decay with whichever value applies at that instant. Every
+`busy` touch still applies `busy:true` unconditionally — nothing is ever
+swallowed or synchronously cleared. `markRemoteSubagentBusy` runs on **every**
+subagent touch, not only the first: if a busy decay is currently pending with
+more than `SUBAGENT_PARENT_DECAY_MS` left, it reschedules that pending timer
+down to 3s from now (`remoteActivityDecayRemaining`, tracked as `fireAt` on
+`remoteActivityDecayTimers`'s entries) — it never touches `busy` itself,
+only how soon its decay fires. The outcome: a parent genuinely still writing
+while a subagent runs re-touches at the ~1s IPC throttle, always inside the
+3s window, so `busy` never lapses — it keeps the same violet-tinted spinner a
+local row would show in the same situation
+(`.has-busy-agents .session-icon--busy::before`). A parent that only
+bookends the spawn (one touch at spawn, one at completion) has its single
+post-spawn touch decay in 3s instead of 20s, landing on `agentsBusy` — the
+same rung as the local row — within a few seconds instead of up to 20. A
+parent with **no** subagent keeps the full 20s decay unchanged (a long silent
+tool call must not read as idle). `PRIORITY` in `session-state.js` is
+unchanged — this only changes which decay duration a renderer-side timer
+picks, never the priority ladder.
 
 ### Row ownership: attached vs unattached (issue #273)
 
diff --git a/.ai/contexts/subagent-observability.md b/.ai/contexts/subagent-observability.md
index e2b5e35e..7393a188 100644
--- a/.ai/contexts/subagent-observability.md
+++ b/.ai/contexts/subagent-observability.md
@@ -123,11 +123,24 @@ the local-pty adapter's snapshot (`snapshotForLocal` auto-vivifies a
 `localPtyState` entry). Calling it for a remote/local-transcript parent would
 have overwritten the icon the remote-ssh/local-transcript adapter's own
 `projectRemoteState`/`projectLocalTranscriptState` had just painted, with an
-empty local-pty snapshot. `reflectSubagentRunningState` now skips that
-repaint when `remoteSessionStates`/`localTranscriptStates` already holds an
-entry for the parent — the calling adapter has already repainted its own
-slot by that point (it creates the entry before calling
-`noteSubagentActivity`).
+empty local-pty snapshot.
+
+**Corrected in review**: the first pass skipped that repaint whenever
+`remoteSessionStates.has(parentSessionId)` was true — wrong, because
+`setRemoteAttached` never deletes the entry, so it stays true for the rest of
+the row's life whether or not a tab is currently attached. An **attached**
+remote row is owned by the local-pty path (#273: OSC busy/idle governs it,
+exactly like an ordinary local row), so it still needs this repaint — with
+the old check it never got one on a live subagent toggle, leaving
+`has-busy-agents` set on the row while the icon itself stayed
+`session-icon--idle` until the next full rebuild. The guard is now
+`isRemoteRowOwned(parentSessionId)` (`remote-activity-ui.js`) — remote state
+exists **and** is not attached — matching the exact ownership test #273
+already established (`projectRemoteState`, `markRemoteBusy`,
+`decayRemoteBusy` all gate on `snapshot().attached` the same way).
+`localTranscriptStates` needs no equivalent check: there is no "attached"
+state for that kind — `localTranscriptPtyTakeover` deletes the entry outright
+once a PTY takes the row over, so `.has()` alone stays correct.
 
 ## Attribution across sources (issue #247)
 
diff --git a/eslint.config.js b/eslint.config.js
index 52d399cb..dd9edff6 100644
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -179,6 +179,8 @@ const rendererCrossFileGlobals = {
   stopBeforeArchive: 'readonly',
   // read by sidebar.js's parentHasActiveSubagent() — see .ai/contexts/subagent-observability.md
   remoteSessionStates: 'readonly',
+  // see .ai/contexts/subagent-observability.md
+  isRemoteRowOwned: 'readonly',
   // public/local-transcript-adapter.js (local-transcript adapter, see .ai/contexts/session-state.md)
   localTranscriptPtyTakeover: 'readonly',
   pruneLocalTranscriptTimers: 'readonly',
diff --git a/public/remote-activity-ui.js b/public/remote-activity-ui.js
index 11f37f82..429c1885 100644
--- a/public/remote-activity-ui.js
+++ b/public/remote-activity-ui.js
@@ -2,14 +2,14 @@
 // and .ai/contexts/session-state.md (migration step 3: the remote-ssh adapter).
 
 const PIP_DECAY_MS = 20000;
+// value: { handle, fireAt } — see .ai/contexts/session-state.md (issue #284)
 const remoteActivityDecayTimers = new Map();
 
 // separate decay for subagent attribution (agentsBusy) — see .ai/contexts/subagent-observability.md
 const remoteAgentsDecayTimers = new Map();
 
-// coincidence window for a Task-tool invocation's parent-file touch — see .ai/contexts/session-state.md (issue #284)
-const SUBAGENT_BUSY_COINCIDENCE_MS = 3000;
-const remoteSubagentSpawnAt = new Map();
+// short busy decay while a subagent is running — see .ai/contexts/session-state.md (issue #284)
+const SUBAGENT_PARENT_DECAY_MS = 3000;
 
 // remote-ssh adapter: one persistent state per remote session id — see .ai/contexts/session-state.md
 const remoteSessionStates = new Map();
@@ -26,6 +26,12 @@ function remoteState(sessionId) {
   return state;
 }
 
+// see .ai/contexts/session-state.md ("Row ownership: attached vs unattached")
+function isRemoteRowOwned(sessionId) {
+  const state = remoteSessionStates.get(sessionId);
+  return !!state && !state.snapshot().attached;
+}
+
 // An attached row is owned by the local-pty path (#273) — see .ai/contexts/session-state.md
 function projectRemoteState(sessionId) {
   const snapshot = remoteState(sessionId).snapshot();
@@ -34,13 +40,18 @@ function projectRemoteState(sessionId) {
 }
 
 function clearRemoteActivityTimer(sessionId) {
-  const t = remoteActivityDecayTimers.get(sessionId);
-  if (t) {
-    clearTimeout(t);
+  const entry = remoteActivityDecayTimers.get(sessionId);
+  if (entry) {
+    clearTimeout(entry.handle);
     remoteActivityDecayTimers.delete(sessionId);
   }
 }
 
+function remoteActivityDecayRemaining(sessionId) {
+  const entry = remoteActivityDecayTimers.get(sessionId);
+  return entry ? entry.fireAt - Date.now() : null;
+}
+
 function clearRemoteAgentsTimer(sessionId) {
   const t = remoteAgentsDecayTimers.get(sessionId);
   if (t) {
@@ -49,19 +60,17 @@ function clearRemoteAgentsTimer(sessionId) {
   }
 }
 
+// see .ai/contexts/session-state.md (issue #284)
+function remoteBusyDecayMs(sessionId) {
+  return remoteState(sessionId).snapshot().agentsBusy ? SUBAGENT_PARENT_DECAY_MS : PIP_DECAY_MS;
+}
+
 // Maps still fed in parallel for sidebar initial paint and grid dot — see session-state.md "migration status"
 // An attached row is owned by the local-pty path (#273): a no-op here.
 function markRemoteBusy(sessionId, via, at) {
   const state = remoteState(sessionId);
   if (state.snapshot().attached) return;
   const t = at || Date.now();
-  const spawnAt = remoteSubagentSpawnAt.get(sessionId);
-  if (spawnAt !== undefined && state.snapshot().agentsBusy && t - spawnAt <= SUBAGENT_BUSY_COINCIDENCE_MS) {
-    // see .ai/contexts/session-state.md (issue #284)
-    state.apply({ type: 'transcriptTouched', at: t, source: via });
-    projectRemoteState(sessionId);
-    return;
-  }
   state.apply({ type: 'transcriptTouched', at: t, source: via });
   state.apply({ type: 'busy', active: true });
   setActivity(sessionId, true, via);
@@ -79,10 +88,11 @@ function decayRemoteBusy(sessionId) {
 }
 
 function armRemoteDecayTimer(sessionId, ms) {
-  remoteActivityDecayTimers.set(sessionId, setTimeout(() => {
+  const handle = setTimeout(() => {
     remoteActivityDecayTimers.delete(sessionId);
     decayRemoteBusy(sessionId);
-  }, ms));
+  }, ms);
+  remoteActivityDecayTimers.set(sessionId, { handle, fireAt: Date.now() + ms });
 }
 
 // silence means the subagent stopped, not finished — see .ai/contexts/subagent-observability.md
@@ -103,15 +113,12 @@ function armRemoteAgentsDecayTimer(sessionId) {
 // attributes a subagent write to its parent's own state — see .ai/contexts/subagent-observability.md
 function markRemoteSubagentBusy(sessionId) {
   const state = remoteState(sessionId);
-  const wasAgentsBusy = state.snapshot().agentsBusy;
   state.apply({ type: 'subagentSpawned' });
-  if (!wasAgentsBusy) {
-    // see .ai/contexts/session-state.md (issue #284)
-    remoteSubagentSpawnAt.set(sessionId, Date.now());
-    if (state.snapshot().busy) {
-      clearRemoteActivityTimer(sessionId);
-      state.apply({ type: 'busy', active: false, armReady: false });
-    }
+  // see .ai/contexts/session-state.md (issue #284)
+  const remaining = remoteActivityDecayRemaining(sessionId);
+  if (remaining !== null && remaining > SUBAGENT_PARENT_DECAY_MS) {
+    clearRemoteActivityTimer(sessionId);
+    armRemoteDecayTimer(sessionId, SUBAGENT_PARENT_DECAY_MS);
   }
   projectRemoteState(sessionId);
   armRemoteAgentsDecayTimer(sessionId);
@@ -130,9 +137,6 @@ function pruneRemoteActivityTimers() {
   for (const sessionId of remoteSeedFloors.keys()) {
     if (!sessionItemEl(sessionId)) remoteSeedFloors.delete(sessionId);
   }
-  for (const sessionId of remoteSubagentSpawnAt.keys()) {
-    if (!sessionItemEl(sessionId)) remoteSubagentSpawnAt.delete(sessionId);
-  }
 }
 
 function onRemoteActivityEvent(payload) {
@@ -151,7 +155,7 @@ function onRemoteActivityEvent(payload) {
   if (typeof sessionId !== 'string' || !sessionId) return;
   markRemoteBusy(sessionId, 'remote-watch', payload.at);
   clearRemoteActivityTimer(sessionId);
-  armRemoteDecayTimer(sessionId, PIP_DECAY_MS);
+  armRemoteDecayTimer(sessionId, remoteBusyDecayMs(sessionId));
 }
 
 // descriptor ports; absence stays 'unknown', never 'dead' — see session-state.md ports table
@@ -187,7 +191,6 @@ function setRemoteAttached(sessionId, attached) {
 function applyRemoteStopped(sessionId) {
   clearRemoteActivityTimer(sessionId);
   clearRemoteAgentsTimer(sessionId);
-  remoteSubagentSpawnAt.delete(sessionId);
   if (typeof clearActiveSubagentsFor === 'function') clearActiveSubagentsFor(sessionId);
   const state = remoteState(sessionId);
   state.apply({ type: 'busy', active: false, armReady: false });
diff --git a/public/sidebar.js b/public/sidebar.js
index 5c80630f..a13f52b4 100644
--- a/public/sidebar.js
+++ b/public/sidebar.js
@@ -262,7 +262,7 @@ function reflectSubagentRunningState(parentSessionId, agentId) {
   const parentEl = document.getElementById('si-' + parentSessionId);
   setHasBusyAgents(parentEl, parentHasActiveSubagent(parentSessionId));
   // parent slot repainted only when local-pty owns it — see .ai/contexts/subagent-observability.md
-  const remoteOwned = typeof remoteSessionStates !== 'undefined' && remoteSessionStates.has(parentSessionId);
+  const remoteOwned = typeof isRemoteRowOwned === 'function' && isRemoteRowOwned(parentSessionId);
   const localTranscriptOwned = typeof localTranscriptStates !== 'undefined' && localTranscriptStates.has(parentSessionId);
   if (parentEl && !remoteOwned && !localTranscriptOwned) paintSessionIcon(parentEl.querySelector('.session-icon'), parentSessionId);
   if (window.ATRACE) window.atrace('class.subagent', parentSessionId, { agentId, running, childEl: el ? el.id : null, caretEl: caret ? caret.id : null, parentEl: parentEl ? parentEl.id : null, 'has-busy-agents': parentHasActiveSubagent(parentSessionId), fn: 'reflectSubagentRunningState' });
diff --git a/test/dom-sidebar-subagent-running-parity.test.js b/test/dom-sidebar-subagent-running-parity.test.js
index c7d9ffec..87f5ac9e 100644
--- a/test/dom-sidebar-subagent-running-parity.test.js
+++ b/test/dom-sidebar-subagent-running-parity.test.js
@@ -178,3 +178,79 @@ test('local IPC subagent-spawned still sets .running on the child row immediatel
     ctx.destroy();
   }
 });
+
+// Adversarial-review MAJOR finding: reflectSubagentRunningState's parent-icon
+// repaint guard checked mere presence in remoteSessionStates, which stays
+// true for the rest of a remote row's life once touched — attached or not,
+// since setRemoteAttached never deletes the entry. An attached remote row is
+// owned by the local-pty path (#273) and DOES need this repaint; only an
+// unattached one must skip it. Fixed with isRemoteRowOwned(sessionId)
+// (remote-activity-ui.js): remote state exists AND is not attached. See
+// .ai/contexts/subagent-observability.md.
+
+test('(5) an attached remote parent gets its icon repainted by a local subagent-spawned IPC, immediately', () => {
+  const ctx = setupSidebarDom();
+  try {
+    const project = makeSampleProject({
+      remoteAlias: 'vps',
+      sessions: [{
+        sessionId: 'r-attached-1',
+        remoteAlias: 'vps',
+        name: 'attached remote session',
+        summary: 'attached',
+        modified: '2026-05-22T10:00:00.000Z',
+        starred: false,
+        archived: 0,
+        messageCount: 1,
+      }],
+    });
+    ctx.sidebar.renderProjects([project], true);
+
+    // A real attach marks the row attached (#273) and, via the OSC busy/idle
+    // stream, already carries a local-pty entry before any subagent event.
+    ctx.window.setRemoteAttached('r-attached-1', true);
+    ctx.setActivity('r-attached-1', false, 'seed');
+
+    ctx.emitSubagentSpawned({ parentSessionId: 'r-attached-1', agentId: 'agent-1' });
+
+    const icon = ctx.document.getElementById('si-r-attached-1').querySelector('.session-icon');
+    assert.ok(icon.classList.contains('session-icon--agents-busy'),
+      'attached row is local-pty owned — its icon slot must repaint immediately, no rebuild');
+  } finally {
+    ctx.destroy();
+  }
+});
+
+test('(6) an unattached remote parent icon, once painted by the remote adapter, survives a local subagent-spawned IPC', () => {
+  const ctx = setupSidebarDom();
+  try {
+    const project = makeSampleProject({
+      remoteAlias: 'vps',
+      sessions: [{
+        sessionId: 'r-unattached-1',
+        remoteAlias: 'vps',
+        name: 'unattached remote session',
+        summary: 'unattached',
+        modified: '2026-05-22T10:00:00.000Z',
+        starred: false,
+        archived: 0,
+        messageCount: 1,
+      }],
+    });
+    ctx.sidebar.renderProjects([project], true);
+
+    // The remote watch channel already lit agentsBusy and painted the slot.
+    ctx.window.onRemoteActivityEvent({ alias: 'vps', parentSessionId: 'r-unattached-1', agentId: 'agent-1', at: Date.now(), kind: 'subagent' });
+    const icon = ctx.document.getElementById('si-r-unattached-1').querySelector('.session-icon');
+    assert.ok(icon.classList.contains('session-icon--agents-busy'), 'precondition: remote adapter painted agents-busy');
+
+    // Adversarial: a local subagent-spawned IPC for the same parent must not
+    // let the local-pty repaint run and overwrite it with an empty snapshot.
+    ctx.emitSubagentSpawned({ parentSessionId: 'r-unattached-1', agentId: 'agent-2' });
+
+    assert.ok(icon.classList.contains('session-icon--agents-busy'),
+      'unattached remote row stays owned by the remote-ssh adapter — the local-pty repaint must not run');
+  } finally {
+    ctx.destroy();
+  }
+});
diff --git a/test/remote-session-adapter.test.js b/test/remote-session-adapter.test.js
index 3899e957..b7983dc0 100644
--- a/test/remote-session-adapter.test.js
+++ b/test/remote-session-adapter.test.js
@@ -210,53 +210,145 @@ test('a mutant subagent decay that leaves agentsBusy stillActive would be caught
 });
 
 // Issue #284 — a Task-tool invocation touches the parent's own transcript as
-// well as the subagent leg; the parent-file touch used to win the busy rung
-// for its full 20s decay even though the top-level agent was really just
-// idle waiting on the subagent. See .ai/contexts/session-state.md.
+// well as the subagent leg. Two designs were tried and rejected before this
+// one (see .ai/contexts/session-state.md for why): the current fix shortens
+// the parent's busy DECAY to SUBAGENT_PARENT_DECAY_MS (3s) while agentsBusy is
+// true, instead of a coincidence window keyed off the spawn edge — no edge,
+// so a second/third spawned agent is covered exactly like the first, and
+// `busy` is never cleared synchronously, only its pending decay rescheduled.
+//
+// These tests need a clock genuinely independent of wall time: `advance(ms)`
+// below moves a virtual clock, backs both `Date.now()` and `setTimeout`'s
+// scheduled fire time, and fires any timer whose deadline has been crossed —
+// the same shape as dom-sidebar-remote-activity-pip.test.js's
+// installFakeTimers, plus the Date.now stub these assertions also need.
 
-test('a parent-file busy touch immediately followed by a fresh subagent spawn is demoted — the rung lands on agentsBusy', () => {
-  const t = setup(['s1']);
-  t.emit({ sessionId: 's1', at: Date.now() });
-  assert.equal(t.snapshot('s1').busy, true, 'precondition: the parent-file touch marks busy');
+function setupWithClock(sessionIds = ['s1']) {
+  const items = sessionIds
+    .map(id => `<div class="session-item" data-session-id="${id}"><span class="session-status-dot"></span></div>`)
+    .join('');
+  const dom = new JSDOM(`<!DOCTYPE html><html><body>${items}</body></html>`,
+    { url: 'http://localhost/', runScripts: 'outside-only' });
+  const { window } = dom;
 
-  t.emit({ alias: 'vps', parentSessionId: 's1', agentId: 'agent-1', at: Date.now(), kind: 'subagent' });
-  const snap = t.snapshot('s1');
-  assert.equal(snap.busy, false, 'the coincident spawn demotes the busy it just won');
-  assert.equal(snap.agentsBusy, true);
+  Object.defineProperty(window, 'activeSessionId', { value: null, writable: true, configurable: true });
 
-  const { renderSessionIcon } = require('../public/session-state.js');
-  assert.ok(renderSessionIcon(snap).slotClasses.includes('session-icon--agents-busy'),
-    'rung is agentsBusy, not busy');
+  let onRemoteActivityCb = null;
+  Object.defineProperty(window, 'api', {
+    value: { onRemoteActivity: (cb) => { onRemoteActivityCb = cb; } },
+    writable: true, configurable: true,
+  });
+
+  let clock = 0;
+  window.Date.now = () => clock;
+
+  const timers = [];
+  let nextId = 1;
+  Object.defineProperty(window, 'setTimeout', {
+    value: (fn, ms) => {
+      const t = { id: nextId++, at: clock + ms, fn, cleared: false, fired: false };
+      timers.push(t);
+      return t.id;
+    },
+    writable: true, configurable: true,
+  });
+  Object.defineProperty(window, 'clearTimeout', {
+    value: (id) => {
+      const t = timers.find(t => t.id === id);
+      if (t) t.cleared = true;
+    },
+    writable: true, configurable: true,
+  });
+
+  const ctx = dom.getInternalVMContext();
+  vm.runInContext(fs.readFileSync(STATE_SRC, 'utf8'), ctx, { filename: STATE_SRC });
+  vm.runInContext(fs.readFileSync(DOM_SRC, 'utf8'), ctx, { filename: DOM_SRC });
+  vm.runInContext(fs.readFileSync(ACTIVITY_SRC, 'utf8'), ctx, { filename: ACTIVITY_SRC });
+  vm.runInContext(fs.readFileSync(SRC, 'utf8'), ctx, { filename: SRC });
+
+  return {
+    window,
+    now: () => clock,
+    emit: (payload) => onRemoteActivityCb(payload),
+    snapshot: (id) => vm.runInContext(`remoteState(${JSON.stringify(id)}).snapshot()`, ctx),
+    advance(ms) {
+      clock += ms;
+      for (const t of timers) {
+        if (!t.cleared && !t.fired && t.at <= clock) { t.fired = true; t.fn(); }
+      }
+    },
+    destroy: () => window.close(),
+  };
+}
+
+test('(1) a genuinely busy parent (touch every ~1s) with a running subagent never lets busy lapse', () => {
+  const t = setupWithClock(['s1']);
+  t.emit({ sessionId: 's1', at: t.now() }); // touch @0
+
+  t.advance(1000); // -> 1000
+  t.emit({ sessionId: 's1', at: t.now() }); // touch @1000
+  t.emit({ alias: 'vps', parentSessionId: 's1', agentId: 'agent-1', at: t.now(), kind: 'subagent' }); // spawn @1000
+
+  t.advance(200); // -> 1200
+  assert.equal(t.snapshot('s1').busy, true, 'busy at t=1200');
+
+  t.advance(800); // -> 2000
+  t.emit({ sessionId: 's1', at: t.now() }); // touch @2000
+  t.advance(500); // -> 2500
+  assert.equal(t.snapshot('s1').busy, true, 'busy at t=2500');
+
+  t.advance(500); // -> 3000
+  t.emit({ sessionId: 's1', at: t.now() }); // touch @3000
+  t.advance(1000); // -> 4000
+  t.emit({ sessionId: 's1', at: t.now() }); // touch @4000
+  assert.equal(t.snapshot('s1').busy, true, 'busy at t=4000');
   t.destroy();
 });
 
-test('a fresh subagent spawn immediately followed by a parent-file busy touch keeps the rung on agentsBusy', () => {
-  const t = setup(['s1']);
-  t.emit({ alias: 'vps', parentSessionId: 's1', agentId: 'agent-1', at: Date.now(), kind: 'subagent' });
-  assert.equal(t.snapshot('s1').agentsBusy, true);
+test('(2) a touch coincident with a fresh spawn still shows busy briefly, then decays to agentsBusy alone', () => {
+  const t = setupWithClock(['s1']);
+  t.emit({ alias: 'vps', parentSessionId: 's1', agentId: 'agent-1', at: t.now(), kind: 'subagent' }); // spawn @0
 
-  t.emit({ sessionId: 's1', at: Date.now() });
-  const snap = t.snapshot('s1');
-  assert.equal(snap.busy, false, 'the busy touch coincident with the fresh spawn is suppressed');
+  t.advance(100); // -> 100
+  t.emit({ sessionId: 's1', at: t.now() }); // touch @100
+
+  t.advance(900); // -> 1000
+  let snap = t.snapshot('s1');
+  assert.equal(snap.busy, true, 'busy at t=1000');
   assert.equal(snap.agentsBusy, true);
 
-  const { renderSessionIcon } = require('../public/session-state.js');
-  assert.ok(renderSessionIcon(snap).slotClasses.includes('session-icon--agents-busy'),
-    'rung is agentsBusy, not busy');
+  t.advance(2200); // -> 3200, the 3s decay armed at t=100 (fires at 3100) has elapsed
+  snap = t.snapshot('s1');
+  assert.equal(snap.busy, false, 'busy false at t=3200');
+  assert.equal(snap.agentsBusy, true, 'agentsBusy stays true — only busy decayed');
   t.destroy();
 });
 
-test('a busy touch well after the coincidence window still wins the rung — a genuinely busy parent must still show busy', () => {
-  const t = setup(['s1']);
-  const t0 = 1000000;
-  t.window.Date.now = () => t0;
-  t.emit({ alias: 'vps', parentSessionId: 's1', agentId: 'agent-1', at: t0, kind: 'subagent' });
-  assert.equal(t.snapshot('s1').agentsBusy, true);
+test('(3) a second subagent spawned while the first still runs still shortens a coincident touch\'s decay — no edge needed', () => {
+  const t = setupWithClock(['s1']);
+  t.emit({ alias: 'vps', parentSessionId: 's1', agentId: 'agent-1', at: t.now(), kind: 'subagent' }); // 1st spawn @0
 
-  t.window.Date.now = () => t0 + 5000; // past the 3s coincidence window
-  t.emit({ sessionId: 's1', at: t0 + 5000 });
-  const snap = t.snapshot('s1');
-  assert.equal(snap.busy, true, 'a later, non-coincident busy touch is not suppressed');
-  assert.equal(snap.agentsBusy, true, 'agentsBusy is unaffected');
+  t.advance(10000); // -> 10000, well before the 1st spawn's own 20s agentsBusy decay
+  assert.equal(t.snapshot('s1').agentsBusy, true, 'precondition: agentsBusy already true, no edge available');
+
+  t.emit({ alias: 'vps', parentSessionId: 's1', agentId: 'agent-2', at: t.now(), kind: 'subagent' }); // 2nd spawn @10000
+
+  t.advance(100); // -> 10100
+  t.emit({ sessionId: 's1', at: t.now() }); // touch @10100
+
+  t.advance(3100); // -> 13200, past the 3s decay armed at t=10100 (fires at 13100)
+  assert.equal(t.snapshot('s1').busy, false, 'busy false at t=13200 — the touch got the short decay despite no edge');
+  t.destroy();
+});
+
+test('(4) a parent with no subagent keeps the full 20s decay', () => {
+  const t = setupWithClock(['s1']);
+  t.emit({ sessionId: 's1', at: t.now() }); // touch @0
+
+  t.advance(15000); // -> 15000
+  assert.equal(t.snapshot('s1').busy, true, 'busy still true at t=15000, well inside 20s');
+
+  t.advance(5001); // -> 20001, past the 20s decay
+  assert.equal(t.snapshot('s1').busy, false, 'busy false once the 20s decay elapses');
   t.destroy();
 });

From d39a7fd7df483ac1bedfebf7aeeac54fbb32fd3c Mon Sep 17 00:00:00 2001
From: Jean-Baptiste <jean-baptiste@konvex-it.fr>
Date: Sun, 13 Sep 2026 13:49:50 +0200
Subject: [PATCH 3/3] (session-state): a sidebar rebuild seeds the remote
 parent with the same short decay while a subagent runs

seedRemoteActivity computed its remaining window from PIP_DECAY_MS, so a
rebuild triggered by the subagent's own writes put a waiting parent back on
the busy rung for up to 20 s after its short decay had fired.
---
 .ai/contexts/session-state.md       | 36 ++++++++++++++++++++++
 public/remote-activity-ui.js        |  3 +-
 test/remote-session-adapter.test.js | 46 +++++++++++++++++++++++++++++
 3 files changed, 84 insertions(+), 1 deletion(-)

diff --git a/.ai/contexts/session-state.md b/.ai/contexts/session-state.md
index b31dfff2..80acd851 100644
--- a/.ai/contexts/session-state.md
+++ b/.ai/contexts/session-state.md
@@ -235,6 +235,42 @@ tool call must not read as idle). `PRIORITY` in `session-state.js` is
 unchanged — this only changes which decay duration a renderer-side timer
 picks, never the priority ladder.
 
+**`seedRemoteActivity` (cold-start / rebuild paint) is migrated too, not just
+the live-touch path.** Its own arm used to stay `PIP_DECAY_MS`-based
+regardless of `agentsBusy`, computing `remaining = remoteActiveAt +
+PIP_DECAY_MS - now`. `renderProjects()` calls `seedRemoteActivity` on every
+full sidebar rebuild, and a rebuild is itself commonly provoked by the
+subagent's own writes — so a parent whose short decay had *already* fired
+got put back on the animated busy rung for up to 20s at the very next
+rebuild (measured: touch t=0, spawn t=1000 reschedules the decay to fire at
+t=4000, busy correctly false at t=4000, then a rebuild at t=5000 re-armed
+busy for another ~15s). Fixed by using `remoteBusyDecayMs(sessionId)` in that
+same arithmetic (`remaining = remoteActiveAt + remoteBusyDecayMs(sessionId) -
+now`) — with `agentsBusy` true the seed window is 3s from `remoteActiveAt`
+instead of 20s, so a seed older than that does nothing, exactly mirroring
+what the live-touch path already does. A seed with `agentsBusy` false is
+byte-identical to before (`remoteBusyDecayMs` returns `PIP_DECAY_MS`), which
+is why `test/dom-sidebar-remote-activity-pip.test.js` (no subagent in any of
+its fixtures) needed no changes.
+
+**Accepted trade-off, not a bug: with a subagent running, a genuinely busy
+parent can visibly flap between the `busy` and `agentsBusy` rungs.** If the
+parent's own transcript stays silent for more than `SUBAGENT_PARENT_DECAY_MS`
+(3s) — a long tool call — its `busy` decays to `agentsBusy` until the next
+write brings it back to `busy`. Both rungs are violet-tinted
+(`.has-busy-agents .session-icon--busy::before` / `.session-icon--agents-busy::before`),
+so the visible change is animation only (spinner vs. static diamond), not a
+color or row-class change. This is deliberate: the alternative — decaying at
+the full `PIP_DECAY_MS` (20s) whenever `agentsBusy` is true — is exactly
+issue #284's original symptom, a parent idling on `busy` long after it
+stopped producing output. **The local-pty row has no equivalent gap**: its
+busy signal is the OSC title stream, edge-triggered on the CLI's own
+idle/busy transitions rather than decayed from silence, so it never flaps
+while genuinely idle-but-subagent-running. This asymmetry between local and
+remote is a known, accepted consequence of the remote-ssh adapter having no
+edge-triggered signal to key off — only transcript touches — not an
+oversight to fix later.
+
 ### Row ownership: attached vs unattached (issue #273)
 
 An attached remote row (a tab open on it) is owned by the local-pty path —
diff --git a/public/remote-activity-ui.js b/public/remote-activity-ui.js
index 429c1885..8c0dbd48 100644
--- a/public/remote-activity-ui.js
+++ b/public/remote-activity-ui.js
@@ -210,7 +210,8 @@ function seedRemoteActivity(session) {
   const sessionId = session.sessionId;
   const floor = remoteSeedFloors.get(sessionId);
   if (floor !== undefined && session.remoteActiveAt <= floor) return; // stale — see setRemoteAttached, #273
-  const remaining = session.remoteActiveAt + PIP_DECAY_MS - Date.now();
+  // see .ai/contexts/session-state.md (issue #284)
+  const remaining = session.remoteActiveAt + remoteBusyDecayMs(sessionId) - Date.now();
   if (remaining <= 0) return;
   markRemoteBusy(sessionId, 'remote-seed', session.remoteActiveAt);
   if (remoteActivityDecayTimers.has(sessionId)) return;
diff --git a/test/remote-session-adapter.test.js b/test/remote-session-adapter.test.js
index b7983dc0..6b8100ee 100644
--- a/test/remote-session-adapter.test.js
+++ b/test/remote-session-adapter.test.js
@@ -266,11 +266,16 @@ function setupWithClock(sessionIds = ['s1']) {
   vm.runInContext(fs.readFileSync(ACTIVITY_SRC, 'utf8'), ctx, { filename: ACTIVITY_SRC });
   vm.runInContext(fs.readFileSync(SRC, 'utf8'), ctx, { filename: SRC });
 
+  const call = (fnName, ...args) => vm.runInContext(
+    `${fnName}(${args.map((a) => JSON.stringify(a)).join(',')})`, ctx
+  );
+
   return {
     window,
     now: () => clock,
     emit: (payload) => onRemoteActivityCb(payload),
     snapshot: (id) => vm.runInContext(`remoteState(${JSON.stringify(id)}).snapshot()`, ctx),
+    seedRemoteActivity: (session) => call('seedRemoteActivity', session),
     advance(ms) {
       clock += ms;
       for (const t of timers) {
@@ -352,3 +357,44 @@ test('(4) a parent with no subagent keeps the full 20s decay', () => {
   assert.equal(t.snapshot('s1').busy, false, 'busy false once the 20s decay elapses');
   t.destroy();
 });
+
+// seedRemoteActivity's own arm used to stay PIP_DECAY_MS-based regardless of
+// agentsBusy — renderProjects calls it on every full rebuild, and rebuilds
+// are themselves triggered by the subagent's own writes, so a waiting parent
+// whose short decay had already fired got re-armed onto the animated busy
+// rung for up to 20s at the very next rebuild. See .ai/contexts/session-state.md.
+
+test('(5) a rebuild after the short decay already fired must not re-arm busy for 20s', () => {
+  const t = setupWithClock(['s1']);
+  t.emit({ sessionId: 's1', at: t.now() }); // touch @0
+  t.advance(1000); // -> 1000
+  t.emit({ alias: 'vps', parentSessionId: 's1', agentId: 'agent-1', at: t.now(), kind: 'subagent' }); // spawn @1000, reschedules the decay to fire @4000
+
+  t.advance(3000); // -> 4000, the short decay fires
+  let snap = t.snapshot('s1');
+  assert.equal(snap.busy, false, 'precondition: the short decay already cleared busy at t=4000');
+
+  t.advance(1000); // -> 5000, renderProjects rebuilds (often provoked by the subagent's own write)
+  t.seedRemoteActivity({ sessionId: 's1', remoteAlias: 'vps', remoteActiveAt: 1000, remoteDescriptorSeen: true });
+
+  snap = t.snapshot('s1');
+  assert.equal(snap.busy, false, 'a rebuild at t=5000 must not re-arm busy for another 20s');
+  assert.equal(snap.agentsBusy, true, 'agentsBusy is untouched by the seed path');
+  t.destroy();
+});
+
+test('(6) a rebuild inside the short window re-arms only for what is left of it, not the full 20s', () => {
+  const t = setupWithClock(['s1']);
+  t.emit({ alias: 'vps', parentSessionId: 's1', agentId: 'agent-1', at: t.now(), kind: 'subagent' }); // spawn @0, no busy touch emitted live
+
+  t.advance(2000); // -> 2000, a rebuild seeds from the descriptor's last-seen activity at t=0
+  t.seedRemoteActivity({ sessionId: 's1', remoteAlias: 'vps', remoteActiveAt: 0, remoteDescriptorSeen: true });
+  assert.equal(t.snapshot('s1').busy, true, 'seed arms busy from the short window (0 + 3000 - 2000 = 1000ms left)');
+
+  t.advance(999); // -> 2999, just before the window (0 + 3000) closes
+  assert.equal(t.snapshot('s1').busy, true, 'busy still held just before t=3000');
+
+  t.advance(2); // -> 3001, past t=3000
+  assert.equal(t.snapshot('s1').busy, false, 'busy decays at t=3000 — the short window, not the full 20s');
+  t.destroy();
+});