@phenx-inc/ctlsurf 0.9.0 → 0.11.0

package/out/renderer/assets/{javascript-B2niCouI.js → javascript-CsGLsswK.js}

@@ -1,5 +1,5 @@
-import { conf as conf$1, language as language$1 } from "./typescript-rdwAjCi4.js";
-import "./index-Cj7K9-Ba.js";
+import { conf as conf$1, language as language$1 } from "./typescript-oxBn_Vcw.js";
+import "./index-BDlCPzCG.js";
 const conf = conf$1;
 const language = {
   // Set defaultToken to invalid to see what you do not tokenize yet

package/out/renderer/assets/{jsonMode-BgCUHaFo.js → jsonMode-CTuGgRvC.js}

@@ -1,6 +1,6 @@
-import { c as createWebWorker, l as languages, e as editor } from "./index-Cj7K9-Ba.js";
-import { f as DocumentFormattingEditProvider, g as DocumentRangeFormattingEditProvider, C as CompletionAdapter, H as HoverAdapter, b as DocumentSymbolAdapter, d as DocumentColorAdapter, F as FoldingRangeAdapter, S as SelectionRangeAdapter, e as DiagnosticsAdapter } from "./lspLanguageFeatures-8SIcRAMh.js";
-import { a, D, h, R, c, i, j, t, k } from "./lspLanguageFeatures-8SIcRAMh.js";
+import { c as createWebWorker, l as languages, e as editor } from "./index-BDlCPzCG.js";
+import { f as DocumentFormattingEditProvider, g as DocumentRangeFormattingEditProvider, C as CompletionAdapter, H as HoverAdapter, b as DocumentSymbolAdapter, d as DocumentColorAdapter, F as FoldingRangeAdapter, S as SelectionRangeAdapter, e as DiagnosticsAdapter } from "./lspLanguageFeatures-Bhdn2Eqy.js";
+import { a, D, h, R, c, i, j, t, k } from "./lspLanguageFeatures-Bhdn2Eqy.js";
 const STOP_WHEN_IDLE_FOR = 2 * 60 * 1e3;
 class WorkerManager {
   constructor(defaults) {

package/out/renderer/assets/{liquid-DOQmSo4G.js → liquid-BrrN4uul.js}

@@ -1,4 +1,4 @@
-import { l as languages } from "./index-Cj7K9-Ba.js";
+import { l as languages } from "./index-BDlCPzCG.js";
 const EMPTY_ELEMENTS = [
   "area",
   "base",

package/out/renderer/assets/{lspLanguageFeatures-8SIcRAMh.js → lspLanguageFeatures-Bhdn2Eqy.js}

@@ -1,4 +1,4 @@
-import { R as Range$1, l as languages, e as editor, U as Uri, M as MarkerSeverity } from "./index-Cj7K9-Ba.js";
+import { R as Range$1, l as languages, e as editor, U as Uri, M as MarkerSeverity } from "./index-BDlCPzCG.js";
 var DocumentUri;
 (function(DocumentUri2) {
   function is(value) {

package/out/renderer/assets/{mdx-DuKdGNKE.js → mdx-DJo-gax4.js}

@@ -1,4 +1,4 @@
-import { l as languages } from "./index-Cj7K9-Ba.js";
+import { l as languages } from "./index-BDlCPzCG.js";
 const conf = {
   comments: {
     blockComment: ["{/*", "*/}"]

package/out/renderer/assets/{python-BUa4XFG-.js → python-DYHeg5b2.js}

@@ -1,4 +1,4 @@
-import { l as languages } from "./index-Cj7K9-Ba.js";
+import { l as languages } from "./index-BDlCPzCG.js";
 const conf = {
   comments: {
     lineComment: "#",

package/out/renderer/assets/{razor-BUw8jho0.js → razor-Cqcks14K.js}

@@ -1,4 +1,4 @@
-import { l as languages } from "./index-Cj7K9-Ba.js";
+import { l as languages } from "./index-BDlCPzCG.js";
 const EMPTY_ELEMENTS = [
   "area",
   "base",

package/out/renderer/assets/{tsMode-8FLRnobw.js → tsMode-YTLgCayh.js}

@@ -1,4 +1,4 @@
-import { c as createWebWorker, e as editor, U as Uri, a as MarkerTag, M as MarkerSeverity, l as languages, t as typescriptDefaults, R as Range } from "./index-Cj7K9-Ba.js";
+import { c as createWebWorker, e as editor, U as Uri, a as MarkerTag, M as MarkerSeverity, l as languages, t as typescriptDefaults, R as Range } from "./index-BDlCPzCG.js";
 class WorkerManager {
   constructor(_modeId, _defaults) {
     this._modeId = _modeId;

package/out/renderer/assets/{typescript-rdwAjCi4.js → typescript-oxBn_Vcw.js}

@@ -1,4 +1,4 @@
-import { l as languages } from "./index-Cj7K9-Ba.js";
+import { l as languages } from "./index-BDlCPzCG.js";
 const conf = {
   wordPattern: /(-?\d*\.\d\w*)|([^\`\~\!\@\#\%\^\&\*\(\)\-\=\+\[\{\]\}\\\|\;\:\'\"\,\.\<\>\/\?\s]+)/g,
   comments: {

package/out/renderer/assets/{xml-HOzT59Qg.js → xml-BEqGMCTc.js}

@@ -1,4 +1,4 @@
-import { l as languages } from "./index-Cj7K9-Ba.js";
+import { l as languages } from "./index-BDlCPzCG.js";
 const conf = {
   comments: {
     blockComment: ["<!--", "-->"]

package/out/renderer/assets/{yaml-B81JfLsW.js → yaml-BGSrk5HC.js}

@@ -1,4 +1,4 @@
-import { l as languages } from "./index-Cj7K9-Ba.js";
+import { l as languages } from "./index-BDlCPzCG.js";
 const conf = {
   comments: {
     lineComment: "#"

package/out/renderer/index.html

@@ -49,8 +49,8 @@
       color: #565f89;
     }
   </style>
-  <script type="module" crossorigin src="./assets/index-Cj7K9-Ba.js"></script>
-  <link rel="stylesheet" crossorigin href="./assets/index-nvsNYP5c.css">
+  <script type="module" crossorigin src="./assets/index-BDlCPzCG.js"></script>
+  <link rel="stylesheet" crossorigin href="./assets/index-CGHeDwZa.css">
 </head>
 <body>
   <div id="boot-splash">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phenx-inc/ctlsurf",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Agent-agnostic terminal and desktop app for ctlsurf — run Claude Code, Codex, or any coding agent with live session logging and remote control",
   "main": "out/main/index.js",
   "bin": {

package/src/main/agentState.ts

@@ -0,0 +1,329 @@
+/**
+ * Agent State Monitor
+ *
+ * Detects, in real time, whether a coding agent is BUSY (actively working) or
+ * AWAITING the user — either waiting for the next prompt (`awaiting_input`) or
+ * blocked on an approval/permission decision (`awaiting_decision`).
+ *
+ * This is the cross-platform "PTY backbone": it watches the raw terminal byte
+ * stream (which every agent produces regardless of OS) and infers state from
+ * the TUI's own affordances — the busy spinner (`esc to interrupt`) and
+ * approval prompts. It is deliberately independent of chat logging and of the
+ * ConversationBridge, whose transcript cleaner actively *discards* the spinner
+ * lines this monitor needs.
+ *
+ * Agents with native hooks (Claude Code, Codex) can deliver an authoritative
+ * state via `applyHookEvent()`, which overrides the heuristic for a short
+ * window. See agentHooks.ts.
+ */
+
+export type AgentState = 'idle' | 'busy' | 'awaiting_input' | 'awaiting_decision'
+
+export type AgentStateSink = (info: {
+  tabId: string
+  state: AgentState
+  /** True when any tracked tab is awaiting the user (drives the dock/taskbar). */
+  anyAwaiting: boolean
+}) => void
+
+// The spinner ticks roughly once per second; allow a couple of missed ticks
+// before we stop considering the agent busy.
+const BUSY_GRACE_MS = 2_500
+// Output must be quiet this long after the spinner stops before we declare the
+// agent is awaiting the user (avoids flagging mid-stream pauses).
+const SETTLE_MS = 1_200
+// How long a seen approval prompt keeps a tab in `awaiting_decision`.
+const DECISION_TTL_MS = 4_000
+// Evaluation cadence.
+const TICK_MS = 400
+// A hook-delivered state is authoritative for this long, suppressing the
+// heuristic for that tab.
+const HOOK_AUTHORITY_MS = 6_000
+// Only the trailing slice of each tab's output is kept, enough to catch a
+// marker split across two PTY chunks.
+const TAIL_KEEP_CHARS = 240
+
+// Claude Code's working spinner: a cycling star glyph followed by a gerund that
+// ends in an ellipsis, e.g. "✶ Tempering…" or "✳ Cogitating...". The completion
+// line ("✻ Worked for 2s") has the glyph but no ellipsis, so it doesn't match —
+// letting the agent settle to `awaiting_input`. Newer Claude builds (Opus 4.8)
+// don't always print "esc to interrupt" for fast turns, so this is the primary
+// Claude signal; the older hints are kept for other builds and Codex.
+const CLAUDE_SPINNER = /[✶✻✳✺✢✷✸✹❋][^\n]{0,60}(?:…|\.\.\.)/
+
+/** Busy markers — the spinner/working hints a TUI shows while actively working. */
+function hasBusyMarker(text: string): boolean {
+  return (
+    /esc to interrupt/i.test(text) ||
+    /\bWorking \(\d+s/i.test(text) ||
+    CLAUDE_SPINNER.test(text)
+  )
+}
+
+/**
+ * Approval / permission prompts. Conservative on purpose: a false positive only
+ * mislabels the sub-state (the dock fires on either awaiting state anyway), but
+ * we still avoid obviously-noisy matches.
+ */
+const APPROVAL_PATTERNS: RegExp[] = [
+  /\bDo you want to (proceed|continue|create|make this edit|run)\b/i, // Claude Code
+  /❯\s*\d+\.\s*Yes\b/i, // Claude numbered-choice prompt
+  /\bAllow command\b/i, // Codex
+  /\bRun this command\?/i, // Codex
+  /\bApprove\b[^\n]*\?/i,
+  /\(y\/n\)/i,
+  /\[y\/N\]/i,
+]
+
+function hasApprovalMarker(text: string): boolean {
+  return APPROVAL_PATTERNS.some((re) => re.test(text))
+}
+
+/** Strip CSI/OSC escape sequences so markers aren't hidden behind color codes. */
+function stripAnsi(str: string): string {
+  return str
+    // eslint-disable-next-line no-control-regex
+    .replace(/\x1b\[[\x30-\x3f]*[\x20-\x2f]*[\x40-\x7e]/g, '')
+    // eslint-disable-next-line no-control-regex
+    .replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, '')
+    // eslint-disable-next-line no-control-regex
+    .replace(/\x1b/g, '')
+}
+
+interface TabRecord {
+  /** Agent id (e.g. 'claude', 'codex'); reserved for future per-agent tuning. */
+  agentId: string
+  cwd: string
+  state: AgentState
+  /** True once a busy spinner has been seen since the last user input. */
+  everBusy: boolean
+  lastBusyAt: number
+  lastOutputAt: number
+  lastDecisionAt: number
+  /** Authoritative state from a hook, and when it was delivered. */
+  hookState: AgentState | null
+  hookAt: number
+  /** Trailing output slice, to catch markers split across PTY chunks. */
+  tail: string
+}
+
+export class AgentStateMonitor {
+  private readonly sink: AgentStateSink
+  private readonly now: () => number
+  private tabs = new Map<string, TabRecord>()
+  private timer: ReturnType<typeof setInterval> | null = null
+  private lastAnyAwaiting = false
+
+  constructor(sink: AgentStateSink, now: () => number = Date.now) {
+    this.sink = sink
+    this.now = now
+  }
+
+  start(): void {
+    if (this.timer) return
+    this.timer = setInterval(() => this.tick(), TICK_MS)
+  }
+
+  stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer)
+      this.timer = null
+    }
+    this.tabs.clear()
+    this.lastAnyAwaiting = false
+  }
+
+  /** Register a tab so its raw PTY output can be classified. */
+  trackTab(tabId: string, agentId: string, cwd: string): void {
+    const now = this.now()
+    this.tabs.set(tabId, {
+      agentId,
+      cwd,
+      state: 'idle',
+      everBusy: false,
+      lastBusyAt: 0,
+      lastOutputAt: now,
+      lastDecisionAt: 0,
+      hookState: null,
+      hookAt: 0,
+      tail: '',
+    })
+  }
+
+  removeTab(tabId: string): void {
+    if (this.tabs.delete(tabId)) this.emitAggregate()
+  }
+
+  /** Feed a raw PTY output chunk for a tab. */
+  feed(tabId: string, data: string): void {
+    const rec = this.tabs.get(tabId)
+    if (!rec) return
+    const now = this.now()
+    rec.lastOutputAt = now
+
+    const text = rec.tail + stripAnsi(data)
+    rec.tail = text.length > TAIL_KEEP_CHARS ? text.slice(-TAIL_KEEP_CHARS) : text
+
+    if (hasBusyMarker(text)) {
+      rec.lastBusyAt = now
+      rec.everBusy = true
+    }
+    if (hasApprovalMarker(text)) {
+      rec.lastDecisionAt = now
+    }
+  }
+
+  /**
+   * Note input written to a tab's PTY. Only a *submit* (data containing a
+   * newline) counts as the user engaging — clearing any awaiting state and
+   * resetting the "has worked" flag so a leftover idle box doesn't re-flag.
+   *
+   * Individual keystrokes and, crucially, the terminal's own auto-responses
+   * (cursor-position / device-attribute replies that TUIs constantly trigger,
+   * which xterm.js writes straight back to the PTY) are ignored — otherwise
+   * the state would churn busy↔idle on every control-sequence handshake.
+   */
+  noteInput(tabId: string, data: string): void {
+    if (!/[\r\n]/.test(data)) return
+    const rec = this.tabs.get(tabId)
+    if (!rec) return
+    const now = this.now()
+    rec.everBusy = false
+    rec.lastBusyAt = now // a submit means work is coming → busy, not awaiting
+    rec.lastDecisionAt = 0
+    rec.hookState = null
+    this.setState(rec, tabId, 'busy')
+  }
+
+  /**
+   * Apply an authoritative state from an agent hook, addressed by cwd. Overrides
+   * the heuristic for HOOK_AUTHORITY_MS. `kind`:
+   *   'awaiting_input'    — turn done / idle prompt (Stop, idle_prompt, agent-turn-complete)
+   *   'awaiting_decision' — permission/approval prompt (PermissionRequest, permission_prompt)
+   *   'busy'              — user submitted a prompt (UserPromptSubmit)
+   */
+  applyHookEvent(cwd: string, kind: AgentState): void {
+    const target = stripTrailingSep(cwd)
+    const now = this.now()
+    for (const [tabId, rec] of this.tabs) {
+      if (stripTrailingSep(rec.cwd) !== target) continue
+      rec.hookState = kind
+      rec.hookAt = now
+      if (kind === 'busy') {
+        rec.everBusy = false
+        rec.lastBusyAt = now
+      }
+      this.setState(rec, tabId, kind)
+    }
+  }
+
+  private tick(): void {
+    const now = this.now()
+    for (const [tabId, rec] of this.tabs) {
+      // Hook state wins while fresh.
+      if (rec.hookState && now - rec.hookAt < HOOK_AUTHORITY_MS) {
+        this.setState(rec, tabId, rec.hookState)
+        continue
+      }
+
+      // `> 0` guards the "never seen" sentinel so a small/zero clock value
+      // doesn't read as recent activity.
+      const busyRecently = rec.lastBusyAt > 0 && now - rec.lastBusyAt < BUSY_GRACE_MS
+      const settled = now - rec.lastOutputAt >= SETTLE_MS
+      const decisionRecent = rec.lastDecisionAt > 0 && now - rec.lastDecisionAt < DECISION_TTL_MS
+
+      let next: AgentState | null = null
+      if (busyRecently) {
+        next = 'busy'
+      } else if (settled && rec.everBusy) {
+        // Awaiting the user. Keep the sub-state stable: once we're showing
+        // awaiting_decision it sticks (and awaiting_input may upgrade to it),
+        // but we never flap back down — the agent's screen repaints make an
+        // approval marker match only intermittently, which otherwise flickers
+        // the indicator between amber and red.
+        next = rec.state === 'awaiting_decision' || decisionRecent
+          ? 'awaiting_decision'
+          : 'awaiting_input'
+      } else if (settled && !rec.everBusy) {
+        next = 'idle'
+      }
+      // next === null → output still streaming after spinner stopped; hold the
+      // current state until it settles.
+      if (next) this.setState(rec, tabId, next)
+    }
+    this.emitAggregate()
+  }
+
+  private setState(rec: TabRecord, tabId: string, state: AgentState): void {
+    if (rec.state === state) return
+    rec.state = state
+    this.sink({ tabId, state, anyAwaiting: this.computeAnyAwaiting() })
+    this.lastAnyAwaiting = this.computeAnyAwaiting()
+  }
+
+  private emitAggregate(): void {
+    const anyAwaiting = this.computeAnyAwaiting()
+    if (anyAwaiting === this.lastAnyAwaiting) return
+    this.lastAnyAwaiting = anyAwaiting
+    // Re-emit with a representative tab so the dock/aggregate listener updates
+    // even when no single tab's state label changed this tick.
+    const tabId = this.firstAwaitingTabId() ?? ''
+    const state = tabId ? (this.tabs.get(tabId)!.state) : 'idle'
+    this.sink({ tabId, state, anyAwaiting })
+  }
+
+  private computeAnyAwaiting(): boolean {
+    for (const rec of this.tabs.values()) {
+      if (rec.state === 'awaiting_input' || rec.state === 'awaiting_decision') return true
+    }
+    return false
+  }
+
+  private firstAwaitingTabId(): string | null {
+    for (const [tabId, rec] of this.tabs) {
+      if (rec.state === 'awaiting_input' || rec.state === 'awaiting_decision') return tabId
+    }
+    return null
+  }
+}
+
+function stripTrailingSep(p: string): string {
+  return p.length > 1 ? p.replace(/[/\\]+$/, '') : p
+}
+
+/**
+ * Decides whether the dock/taskbar "awaiting input" attention (blink + bounce)
+ * should currently be active. Pure boolean logic, separated from the Electron
+ * bindings in index.ts so it can be tested without a window.
+ *
+ * Rules:
+ *  - Attention is active only while an agent is awaiting AND the window is
+ *    unfocused AND the current awaiting episode hasn't been acknowledged.
+ *  - Focusing the window during an episode acknowledges it; so does already
+ *    being focused at the moment the episode begins (you saw it happen).
+ *  - Acknowledgement lasts for the whole episode: blurring again does NOT
+ *    re-nag. A fresh episode (agent works, then waits again) starts unack'd.
+ */
+export class AttentionController {
+  private awaiting = false
+  private focused = false
+  private acknowledged = false
+
+  /** Update awaiting state; returns whether attention should be active. */
+  setAwaiting(on: boolean): boolean {
+    if (on && !this.awaiting) this.acknowledged = this.focused // new episode
+    this.awaiting = on
+    return this.active()
+  }
+
+  /** Update window focus; returns whether attention should be active. */
+  setFocused(focused: boolean): boolean {
+    this.focused = focused
+    if (focused && this.awaiting) this.acknowledged = true
+    return this.active()
+  }
+
+  private active(): boolean {
+    return this.awaiting && !this.focused && !this.acknowledged
+  }
+}

package/src/main/index.ts

@@ -24,6 +24,7 @@ function log(...args: unknown[]): void {
 import { AgentConfig, getDefaultAgent, getAvailableAgents } from './agents'
 import { getSettingsDir } from './settingsDir'
 import { Orchestrator } from './orchestrator'
+import { AttentionController } from './agentState'
 
 let mainWindow: BrowserWindow | null = null
 
@@ -50,43 +51,85 @@ function getProjectAbbrev(cwdPath: string): string {
   return word.slice(0, 2).toUpperCase()
 }
 
-function createOverlayIcon(text: string): Electron.NativeImage {
-  // Create a 32x32 overlay with text for Windows/Linux
+// Draw a 32x32 filled circle overlay (Windows taskbar). `ready` switches between
+// the project-badge blue and the green "ready for you" dot.
+function createDotOverlay(ready: boolean): Electron.NativeImage {
   const size = 32
   const canvas = Buffer.alloc(size * size * 4, 0) // RGBA
-
-  // Fill with a semi-transparent dark background circle
+  const [r, g, b] = ready ? [52, 199, 89] : [122, 162, 247]
   for (let y = 0; y < size; y++) {
     for (let x = 0; x < size; x++) {
       const cx = x - size / 2
       const cy = y - size / 2
-      const dist = Math.sqrt(cx * cx + cy * cy)
-      if (dist <= size / 2) {
+      if (Math.sqrt(cx * cx + cy * cy) <= size / 2) {
         const idx = (y * size + x) * 4
-        canvas[idx] = 122     // R (blue-ish)
-        canvas[idx + 1] = 162 // G
-        canvas[idx + 2] = 247 // B
-        canvas[idx + 3] = 220 // A
+        canvas[idx] = r
+        canvas[idx + 1] = g
+        canvas[idx + 2] = b
+        canvas[idx + 3] = 235
       }
     }
   }
-
   return nativeImage.createFromBuffer(canvas, { width: size, height: size })
 }
 
-function updateProjectBadge(cwdPath: string | null): void {
-  if (!cwdPath) return
-  const abbrev = getProjectAbbrev(cwdPath)
+// The plain dock icon (macOS), loaded once at startup. Reused to composite the
+// green "ready" dot on top, and to restore the clean icon when it clears.
+let baseDockIcon: Electron.NativeImage | null = null
+
+// Composite a green "ready for you" dot (with a soft dark ring for contrast) into
+// the lower-right of the dock icon. Reads/writes the bitmap as a matched
+// toBitmap()/createFromBitmap() pair, which share the same (BGRA) byte order.
+function dockIconWithReadyDot(base: Electron.NativeImage): Electron.NativeImage {
+  const { width, height } = base.getSize()
+  if (!width || !height) return base
+  const bmp = base.toBitmap()
+  const r = Math.round(Math.min(width, height) * 0.17)   // dot radius
+  const ring = Math.max(2, Math.round(r * 0.22))         // ring thickness
+  const cx = width - r - Math.round(width * 0.05)
+  const cy = height - r - Math.round(height * 0.05)
+  const put = (x: number, y: number, b: number, g: number, rr: number) => {
+    const idx = (y * width + x) * 4
+    bmp[idx] = b; bmp[idx + 1] = g; bmp[idx + 2] = rr; bmp[idx + 3] = 255
+  }
+  for (let y = cy - r - ring; y <= cy + r + ring; y++) {
+    if (y < 0 || y >= height) continue
+    for (let x = cx - r - ring; x <= cx + r + ring; x++) {
+      if (x < 0 || x >= width) continue
+      const d = Math.sqrt((x - cx) ** 2 + (y - cy) ** 2)
+      if (d <= r) put(x, y, 89, 199, 52)        // green #34c759 (BGRA)
+      else if (d <= r + ring) put(x, y, 24, 26, 31) // dark ring #1f1a18
+    }
+  }
+  return nativeImage.createFromBitmap(bmp, { width, height })
+}
+
+// Show/clear the green "ready" dot on the macOS dock icon.
+function setDockReadyDot(on: boolean): void {
+  if (process.platform !== 'darwin' || !app.dock || !baseDockIcon) return
+  app.dock.setIcon(on ? dockIconWithReadyDot(baseDockIcon) : baseDockIcon)
+}
 
-  // macOS: dock badge shows text directly
+// Last project abbreviation, so the steady badge can be restored after the
+// "awaiting input" indicator clears.
+let projectAbbrev = ''
+
+function applySteadyBadge(): void {
   if (process.platform === 'darwin' && app.dock) {
-    app.dock.setBadge(abbrev)
+    app.dock.setBadge(projectAbbrev)
   }
-
-  // Windows: overlay icon on taskbar
   if (process.platform === 'win32' && mainWindow) {
-    mainWindow.setOverlayIcon(createOverlayIcon(abbrev), abbrev)
+    mainWindow.setOverlayIcon(projectAbbrev ? createDotOverlay(false) : null, projectAbbrev)
   }
+}
+
+function updateProjectBadge(cwdPath: string | null): void {
+  if (!cwdPath) return
+  projectAbbrev = getProjectAbbrev(cwdPath)
+
+  // The project badge and the "ready" dot are now independent surfaces (badge
+  // vs dock icon), so the badge can always update.
+  applySteadyBadge()
 
   // All platforms: update window title
   if (mainWindow) {
@@ -95,6 +138,66 @@ function updateProjectBadge(cwdPath: string | null): void {
   }
 }
 
+// ─── "Ready for you" attention indicator (cross-platform) ──────────
+//
+// The detection is OS-independent; only the visual differs:
+//   macOS   — steady green dot composited on the dock icon + one bounce
+//   Windows — green overlay icon on the taskbar button + flash the button
+//   Linux   — badge count where supported + flash (window urgency hint)
+// While the window is focused the dock/taskbar nag is suppressed (the in-app
+// dot is enough); the renderer always gets `agent:state` regardless of OS.
+
+const attention = new AttentionController()
+let attentionActive = false
+let bounceId = -1
+
+function setAwaitingIndicator(on: boolean): void {
+  applyAttention(attention.setAwaiting(on))
+}
+
+function applyAttention(active: boolean): void {
+  if (active) startAttention()
+  else stopAttention()
+}
+
+function startAttention(): void {
+  if (attentionActive) return
+  attentionActive = true
+  log('[agent-state] attention START (green ready dot + bounce)')
+
+  if (process.platform === 'darwin' && app.dock) {
+    setDockReadyDot(true)
+    bounceId = app.dock.bounce('informational')
+  }
+  if (process.platform === 'win32' && mainWindow) {
+    mainWindow.setOverlayIcon(createDotOverlay(true), 'Ready for you')
+    mainWindow.flashFrame(true)
+  }
+  if (process.platform === 'linux') {
+    if (typeof app.badgeCount === 'number') app.badgeCount = 1
+    mainWindow?.flashFrame(true)
+  }
+}
+
+function stopAttention(): void {
+  if (!attentionActive) return
+  attentionActive = false
+  log('[agent-state] attention STOP')
+
+  if (process.platform === 'darwin' && app.dock) {
+    setDockReadyDot(false)
+    if (bounceId >= 0) { app.dock.cancelBounce(bounceId); bounceId = -1 }
+  }
+  if (process.platform === 'win32' && mainWindow) {
+    mainWindow.flashFrame(false)
+  }
+  if (process.platform === 'linux') {
+    if (typeof app.badgeCount === 'number') app.badgeCount = 0
+    mainWindow?.flashFrame(false)
+  }
+  applySteadyBadge()
+}
+
 // ─── Orchestrator (shared logic) ──────────────────
 
 const orchestrator = new Orchestrator(
@@ -107,6 +210,11 @@ const orchestrator = new Orchestrator(
     onWorkerRegistered: (data) => mainWindow?.webContents.send('worker:registered', data),
     onProjectChanged: (name) => mainWindow?.webContents.send('app:projectChanged', name),
     onAgentMessage: (text) => mainWindow?.webContents.send('agent:message', text),
+    onAgentStateChange: (tabId, state, anyAwaiting) => {
+      log(`[agent-state] tab=${tabId} state=${state} anyAwaiting=${anyAwaiting}`)
+      mainWindow?.webContents.send('agent:state', tabId, state, anyAwaiting)
+      setAwaitingIndicator(anyAwaiting)
+    },
     onCwdChanged: () => {
       mainWindow?.webContents.send('app:cwdChanged')
       updateProjectBadge(orchestrator.cwd)
@@ -146,6 +254,12 @@ function createWindow(): void {
     mainWindow.loadFile(path.join(__dirname, '../renderer/index.html'))
   }
 
+  // Focusing the window means the user is here — drop the dock/taskbar nag (the
+  // in-app dot still shows the state). Re-arm it if the agent is still awaiting
+  // when focus is lost again.
+  mainWindow.on('focus', () => applyAttention(attention.setFocused(true)))
+  mainWindow.on('blur', () => applyAttention(attention.setFocused(false)))
+
   mainWindow.on('closed', () => {
     mainWindow = null
   })
@@ -496,7 +610,8 @@ app.whenReady().then(() => {
   if (process.platform === 'darwin' && app.dock) {
     const iconPath = path.join(__dirname, '../../resources/icon.png')
     try {
-      app.dock.setIcon(nativeImage.createFromPath(iconPath))
+      baseDockIcon = nativeImage.createFromPath(iconPath)
+      app.dock.setIcon(baseDockIcon)
     } catch { /* ignore */ }
   }