From a0993221acc1caf1f5d1fb77db8f2bd0e7df7d4f Mon Sep 17 00:00:00 2001
From: SamsonCJ <cs3507529000@gmail.com>
Date: Fri, 7 Aug 2026 01:17:26 -0700
Subject: [PATCH 01/19] Fix repeated Canvas link activation

---
 docs/components/canvas.md                     |  2 +
 .../Models/CanvasInteractionPolicy.swift      | 23 ++++++
 .../Features/Canvas/Views/CanvasView.swift    | 23 ++++--
 .../CanvasInteractionPolicyTests.swift        | 77 +++++++++++++++++++
 4 files changed, 119 insertions(+), 6 deletions(-)
 create mode 100644 supacode/Features/Canvas/Models/CanvasInteractionPolicy.swift
 create mode 100644 supacodeTests/CanvasInteractionPolicyTests.swift

diff --git a/docs/components/canvas.md b/docs/components/canvas.md
index e36da24f..6b472623 100644
--- a/docs/components/canvas.md
+++ b/docs/components/canvas.md
@@ -32,6 +32,8 @@ Canvas lets you **type a command once and send it to many agents at once**:
 
 Selection controls:
 - `⌘`-click a card body → toggle it in/out of the selection.
+- `⌘`-click a terminal link → open it. Recognized links take priority over card
+  multi-selection, including when `⌘` is held across repeated clicks.
 - **Click (without `⌘`)** an already-selected card → make it the **primary** (the
   one you type into) without deselecting the rest. (`⌘`-clicking a selected card
   instead *removes* it from the selection.)
diff --git a/supacode/Features/Canvas/Models/CanvasInteractionPolicy.swift b/supacode/Features/Canvas/Models/CanvasInteractionPolicy.swift
new file mode 100644
index 00000000..21eb6575
--- /dev/null
+++ b/supacode/Features/Canvas/Models/CanvasInteractionPolicy.swift
@@ -0,0 +1,23 @@
+enum CanvasInteractionPolicy {
+  static func linkActivationRequested(
+    hasHoveredLink: Bool,
+    isCommandModifierActive: Bool
+  ) -> Bool {
+    hasHoveredLink && isCommandModifierActive
+  }
+
+  static func showsSelectionShield(
+    commandSelectionActive: Bool,
+    selectionModeActive: Bool,
+    broadcastFollower: Bool,
+    linkActivationRequested: Bool
+  ) -> Bool {
+    if linkActivationRequested {
+      return false
+    }
+    if commandSelectionActive || selectionModeActive {
+      return true
+    }
+    return broadcastFollower
+  }
+}
diff --git a/supacode/Features/Canvas/Views/CanvasView.swift b/supacode/Features/Canvas/Views/CanvasView.swift
index a11c31cb..815396f0 100644
--- a/supacode/Features/Canvas/Views/CanvasView.swift
+++ b/supacode/Features/Canvas/Views/CanvasView.swift
@@ -256,11 +256,22 @@ struct CanvasView: View {
     .onDisappear { deactivateCanvas() }
   }
 
-  func showsSelectionShield(for tabID: TerminalTabID) -> Bool {
-    if commandKeyObserver.isPressed { return true }
-    if selectionState.isSelecting { return true }
-    if selectionState.isBroadcasting, selectionState.primaryTabID != tabID { return true }
-    return false
+  func showsSelectionShield(
+    for tabID: TerminalTabID,
+    in tree: SplitTree<GhosttySurfaceView>
+  ) -> Bool {
+    let hasHoveredLink = tree.leaves().contains {
+      $0.bridge.state.mouseOverLink?.isEmpty == false
+    }
+    return CanvasInteractionPolicy.showsSelectionShield(
+      commandSelectionActive: commandKeyObserver.isPressed,
+      selectionModeActive: selectionState.isSelecting,
+      broadcastFollower: selectionState.isBroadcasting && selectionState.primaryTabID != tabID,
+      linkActivationRequested: CanvasInteractionPolicy.linkActivationRequested(
+        hasHoveredLink: hasHoveredLink,
+        isCommandModifierActive: NSEvent.modifierFlags.contains(.command)
+      )
+    )
   }
 
   // MARK: - Cards Layer
@@ -358,7 +369,7 @@ struct CanvasView: View {
         isExpanded: isCardExpanded,
         expandHelp: expandHelp,
         canvasScale: isCardExpanded ? 1 : canvasScale,
-        showsSelectionShield: showsSelectionShield(for: tab.id),
+        showsSelectionShield: showsSelectionShield(for: tab.id, in: tree),
         onTap: {
           let cmdHeld = NSEvent.modifierFlags.contains(.command)
           if cmdHeld {
diff --git a/supacodeTests/CanvasInteractionPolicyTests.swift b/supacodeTests/CanvasInteractionPolicyTests.swift
new file mode 100644
index 00000000..ae6c3051
--- /dev/null
+++ b/supacodeTests/CanvasInteractionPolicyTests.swift
@@ -0,0 +1,77 @@
+import Testing
+
+@testable import supacode
+
+struct CanvasInteractionPolicyTests {
+  @Test func hoveredLinkTakesPriorityOverCommandSelection() {
+    let linkActivationRequested = CanvasInteractionPolicy.linkActivationRequested(
+      hasHoveredLink: true,
+      isCommandModifierActive: true
+    )
+    let showsShield = CanvasInteractionPolicy.showsSelectionShield(
+      commandSelectionActive: true,
+      selectionModeActive: true,
+      broadcastFollower: true,
+      linkActivationRequested: linkActivationRequested
+    )
+
+    #expect(linkActivationRequested)
+    #expect(showsShield == false)
+  }
+
+  @Test func commandSelectionStillShieldsNonLinkContent() {
+    let showsShield = CanvasInteractionPolicy.showsSelectionShield(
+      commandSelectionActive: true,
+      selectionModeActive: false,
+      broadcastFollower: false,
+      linkActivationRequested: false
+    )
+
+    #expect(showsShield)
+  }
+
+  @Test func selectionModeStillShieldsNonLinkContent() {
+    let showsShield = CanvasInteractionPolicy.showsSelectionShield(
+      commandSelectionActive: false,
+      selectionModeActive: true,
+      broadcastFollower: false,
+      linkActivationRequested: false
+    )
+
+    #expect(showsShield)
+  }
+
+  @Test func broadcastingOnlyShieldsFollowerCards() {
+    let primaryShowsShield = CanvasInteractionPolicy.showsSelectionShield(
+      commandSelectionActive: false,
+      selectionModeActive: false,
+      broadcastFollower: false,
+      linkActivationRequested: false
+    )
+    let followerShowsShield = CanvasInteractionPolicy.showsSelectionShield(
+      commandSelectionActive: false,
+      selectionModeActive: false,
+      broadcastFollower: true,
+      linkActivationRequested: false
+    )
+
+    #expect(primaryShowsShield == false)
+    #expect(followerShowsShield)
+  }
+
+  @Test func hoveredLinkWithoutCommandStillUsesSelectionPolicy() {
+    let linkActivationRequested = CanvasInteractionPolicy.linkActivationRequested(
+      hasHoveredLink: true,
+      isCommandModifierActive: false
+    )
+    let showsShield = CanvasInteractionPolicy.showsSelectionShield(
+      commandSelectionActive: false,
+      selectionModeActive: true,
+      broadcastFollower: false,
+      linkActivationRequested: linkActivationRequested
+    )
+
+    #expect(linkActivationRequested == false)
+    #expect(showsShield)
+  }
+}
-- 
2.51.2


From 8aec608586dbb4ba11505fe2ddef8e916fe344d8 Mon Sep 17 00:00:00 2001
From: Simon Heimlicher <simon.github@heimlicher.com>
Date: Fri, 7 Aug 2026 11:52:51 +0200
Subject: [PATCH 02/19] Detect two live Claude states the typed profile still
 reports idle
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Both survived the #684-#688 profile migration because no captured screen
reaches the rules that carry them. `claude.elapsedStatus` and
`claude.backgroundWork` are exercised only by inline synthetic screens
written from the same assumptions as the predicates, so those screens
cannot falsify them, and `claude.spinner` matches first on every captured
working fixture.

Captured live against Claude Code 2.1.224 with `prowl read --source
detection`, sampling `prowl agents` at the same instant:

  ● Perusing… (1m 38s · ↓ 187 tokens)        -> agents reported done
  ✻ Waiting for 1 background agent to finish -> agents reported done

The status label is free text and is not always one word; the elapsed
segment becomes several tokens past a minute, so a correctly shaped row
detects for 59 seconds and then flips to idle for the rest of the turn.

The background wait row carries a spinner glyph but no ellipsis, which
hasSpinnerActivity requires, and the old marker matched the literal
"agents done" that only the workflow variant of the row prints.

The switcher block below the prompt looks like a better signal and is not
one: a subagent that returns control while awaiting collection keeps its
row with the elapsed frozen, so matching the row shape holds the pane at
working after the work stopped. Observed live, and pinned by a test.

Add AgentScreenRuleCoverageTests, which fails when a typed rule has no
captured witness. It would have flagged both rules the day the corpus
landed. One Codex rule is carried as explicit, documented debt.
---
 docs/components/agent-detection.md            |  36 +++--
 .../AgentDetection/ClaudeScreenProfile.swift  |  74 +++++++--
 .../AgentDetection/ScreenHeuristics.swift     |  19 ++-
 .../AgentScreenRuleCoverageTests.swift        |  61 ++++++++
 .../ClaudeBackgroundAgentDetectionTests.swift | 143 ++++++++++++++++++
 supacodeTests/ClaudeScreenProfileTests.swift  |   6 +
 .../676-background-agent-wait.metadata.json   |  16 ++
 .../working/676-background-agent-wait.txt     |  59 ++++++++
 .../676-compound-elapsed-status.metadata.json |  16 ++
 .../working/676-compound-elapsed-status.txt   |  35 +++++
 10 files changed, 430 insertions(+), 35 deletions(-)
 create mode 100644 supacodeTests/AgentScreenRuleCoverageTests.swift
 create mode 100644 supacodeTests/ClaudeBackgroundAgentDetectionTests.swift
 create mode 100644 supacodeTests/Fixtures/AgentScreenDetection/claude/2.1.224/working/676-background-agent-wait.metadata.json
 create mode 100644 supacodeTests/Fixtures/AgentScreenDetection/claude/2.1.224/working/676-background-agent-wait.txt
 create mode 100644 supacodeTests/Fixtures/AgentScreenDetection/claude/2.1.224/working/676-compound-elapsed-status.metadata.json
 create mode 100644 supacodeTests/Fixtures/AgentScreenDetection/claude/2.1.224/working/676-compound-elapsed-status.txt

diff --git a/docs/components/agent-detection.md b/docs/components/agent-detection.md
index f32fbc92..8c29a9b4 100644
--- a/docs/components/agent-detection.md
+++ b/docs/components/agent-detection.md
@@ -48,10 +48,18 @@ at a `~/.grok/` install (so Cursor's own `agent` entrypoint stays Cursor).
    Other agent families keep their own patterns (including Oh My Pi's
    `Working… ⟦esc⟧` loader, braille frames, symbol cycles, Cursor's
    hexagons, Kimi's moon phases, etc.).
-   For Claude, a running **background workflow** keeps a status line *below* the
-   input box (e.g. `3/5 agents done · 7m 29s · ↓ 288.5k tokens`) after the turn has
-   ended; Prowl reads that footer as **Working**, so a churning workflow isn't
-   mistaken for idle.
+   Claude's live status row (`● <label>… (<elapsed> · …)`) accepts a multi-word
+   label and a compound elapsed segment such as `28m 34s` or `1h 4m 2s`, so a turn
+   keeps reporting **Working** after it passes a minute.
+   For Claude, **background agents** end the main turn while they run, leaving
+   `✻ Waiting for 1 background agent to finish` above the input box — a spinner
+   glyph with no ellipsis, which the spinner pattern alone rejects. Prowl reads
+   that wait row as **Working**, along with the older background-workflow footer
+   (`3/5 agents done · 7m 29s · ↓ 288.5k tokens`) below the box.
+   The agent switcher block below the box (`⏺ main` plus one `◯` row per agent) is
+   deliberately *not* read as activity: a subagent that returns control while it
+   still awaits collection keeps its row with the elapsed frozen, so the rows
+   cannot distinguish running work from finished work on a single frame.
 
 For diagnostics and sanitized regression captures, `prowl read --source detection`
 returns the exact active-screen buffer used by stage 2. It is explicitly requested
@@ -81,12 +89,12 @@ showing their chrome keep the last trusted state instead of forcing idle.
 
 **Display states** (what you see):
 
-| Display | Derived from | Meaning |
-|---------|--------------|---------|
-| **Working** | raw `working` | actively processing |
-| **Blocked** | raw `blocked` | waiting for the user (a prompt) |
-| **Done** | raw `idle` + **unseen** | just finished; you haven't looked yet |
-| **Idle** | raw `idle` + **seen** | nothing running |
+| Display     | Derived from            | Meaning                               |
+| ----------- | ----------------------- | ------------------------------------- |
+| **Working** | raw `working`           | actively processing                   |
+| **Blocked** | raw `blocked`           | waiting for the user (a prompt)       |
+| **Done**    | raw `idle` + **unseen** | just finished; you haven't looked yet |
+| **Idle**    | raw `idle` + **seen**   | nothing running                       |
 
 A **Done** pane becomes **Idle** the moment you focus it.
 
@@ -116,11 +124,11 @@ The sidebar worktree row spinner and `prowl list`'s `task.status` report
 
 - a terminal command reports progress (OSC 9;4 / ConEmu-style, e.g. a long shell
   command), **or**
-- a detected agent is **Working** or **Blocked** — including Claude running a
-  background **workflow**, detected from its below-prompt `… agents done …` status
-  line even while the input box looks idle.
+- a detected agent is **Working** or **Blocked** — including Claude waiting on
+  **background agents**, detected from the `✻ Waiting for … background agent …`
+  row even while the input box looks idle.
 
-It's a single coarse running/idle bit (it can't distinguish a background workflow
+It's a single coarse running/idle bit (it can't distinguish background agents
 from a long command). For the agent's finer state use the
 [Active Agents panel](active-agents.md) or [`prowl agents`](cli.md). Expect up to
 ~2 s before it lights on a warm pane, and the ~3 s working-hold before it clears.
diff --git a/supacode/Infrastructure/AgentDetection/ClaudeScreenProfile.swift b/supacode/Infrastructure/AgentDetection/ClaudeScreenProfile.swift
index dc398265..1e82d589 100644
--- a/supacode/Infrastructure/AgentDetection/ClaudeScreenProfile.swift
+++ b/supacode/Infrastructure/AgentDetection/ClaudeScreenProfile.swift
@@ -35,7 +35,9 @@ enum ClaudeScreenProfile {
     if hasElapsedStatusLine(regions.liveStatus) {
       return AgentScreenDetection(state: .working, reason: .matched(RuleID.elapsedStatus))
     }
-    if regions.belowPromptLower.contains("agents done") {
+    if hasBackgroundAgentWait(regions.liveStatus)
+      || regions.belowPromptLines.joined(separator: "\n").lowercased().contains("agents done")
+    {
       return AgentScreenDetection(state: .working, reason: .matched(RuleID.backgroundWork))
     }
     if regions.hasIdleComposer {
@@ -99,6 +101,13 @@ enum ClaudeScreenProfile {
     }
   }
 
+  // Claude's live status row is "● <label>… (<elapsed> · <detail>)". The label is
+  // free text and is not always a single word — "Running gates and merge
+  // lifecycle…" is as common as "Forging…" — so only the trailing ellipsis is
+  // structural. The elapsed segment grows with the turn and becomes several
+  // tokens once it passes a minute: "45s", "28m 34s", "1h 4m 2s". Both parts stay
+  // strict about completeness so transcript prose such as "(1st attempt)" or
+  // "(10seconds)" still cannot pass as a live status row.
   nonisolated private static func hasElapsedStatusLine(_ content: String) -> Bool {
     content.split(separator: "\n").contains { line in
       let trimmed = line.trimmingCharacters(in: .whitespaces)
@@ -107,19 +116,55 @@ enum ClaudeScreenProfile {
       guard let open = body.firstIndex(of: "(") else { return false }
 
       let label = body[..<open].trimmingCharacters(in: .whitespaces)
-      guard label.hasSuffix("…"), label.split(whereSeparator: { $0.isWhitespace }).count == 1 else {
-        return false
-      }
+      guard label.hasSuffix("…") else { return false }
+
+      return hasCompleteElapsedSegment(body[body.index(after: open)...])
+    }
+  }
 
-      let elapsed = body[body.index(after: open)...]
-      let digits = elapsed.prefix(while: \.isNumber)
-      guard !digits.isEmpty else { return false }
-      let afterDigits = elapsed.dropFirst(digits.count)
-      guard let unit = afterDigits.first, unit == "s" || unit == "m" || unit == "h" else {
+  // One or more "<digits><unit>" tokens separated by single spaces, terminated by
+  // the closing paren or by the " · " that separates elapsed from the rest of the
+  // row. A partial token ("10seconds", "1st") fails the terminator check.
+  nonisolated private static func hasCompleteElapsedSegment(_ elapsed: Substring) -> Bool {
+    var remainder = elapsed
+    var tokenCount = 0
+
+    while true {
+      let digits = remainder.prefix(while: \.isNumber)
+      guard !digits.isEmpty else { break }
+      let afterDigits = remainder.dropFirst(digits.count)
+      guard let unit = afterDigits.first, unit == "s" || unit == "m" || unit == "h" else { break }
+      tokenCount += 1
+      remainder = afterDigits.dropFirst()
+      guard remainder.hasPrefix(" "), remainder.dropFirst().first?.isNumber == true else { break }
+      remainder = remainder.dropFirst()
+    }
+
+    guard tokenCount > 0 else { return false }
+    return remainder.hasPrefix(")") || remainder.hasPrefix(" · ")
+  }
+
+  // When Claude delegates to a background agent, its own turn ends first: the
+  // spinner above the prompt is replaced by "✻ Waiting for 1 background agent to
+  // finish". That row carries a spinner glyph but no "…", so hasSpinnerActivity
+  // rejects it and the pane reports finished while the agent is still running.
+  //
+  // The agent switcher block below the input box ("⏺ main" plus one "◯" row per
+  // agent) looks like a better signal but is not one. A subagent that returns
+  // control while still awaiting collection keeps its row, with the elapsed value
+  // frozen — a single screen cannot separate that from a running agent, so
+  // matching the row shape would hold the pane at working after the work stopped.
+  // The wait row is only painted while Claude is genuinely blocked on an agent,
+  // and it is scoped to the live status region so a transcript quoting it cannot
+  // trip the rule.
+  nonisolated private static func hasBackgroundAgentWait(_ liveStatus: String) -> Bool {
+    liveStatus.split(separator: "\n").contains { line in
+      let trimmed = line.trimmingCharacters(in: .whitespaces)
+      guard let first = trimmed.unicodeScalars.first, isAgentSpinnerScalar(first) else {
         return false
       }
-      let trailing = afterDigits.dropFirst()
-      return trailing.hasPrefix(")") || trailing.hasPrefix(" · ")
+      let lower = trimmed.lowercased()
+      return lower.contains("waiting for") && lower.contains("background agent")
     }
   }
 }
@@ -128,7 +173,7 @@ private struct ClaudeScreenRegions: Sendable {
   let currentInteractionLines: [String]
   let currentInteractionLower: String
   let liveStatus: String
-  let belowPromptLower: String
+  let belowPromptLines: [String]
   let bottomChromeLines: [String]
   let bottomViewerLines: [String]
   let hasIdleComposer: Bool
@@ -146,8 +191,9 @@ private struct ClaudeScreenRegions: Sendable {
       Self.contentAbovePrompt(screenLines: lines, promptIndex: promptIndex),
       limit: 3
     )
-    self.belowPromptLower = Self.contentBelowPrompt(screenLines: lines, promptIndex: promptIndex)
-      .lowercased()
+    self.belowPromptLines = Self.contentBelowPrompt(screenLines: lines, promptIndex: promptIndex)
+      .split(separator: "\n", omittingEmptySubsequences: false)
+      .map(String.init)
 
     let nonEmptyLines = lines.map { $0.trimmingCharacters(in: .whitespaces) }.filter { !$0.isEmpty }
     self.bottomChromeLines = Array(nonEmptyLines.suffix(3))
diff --git a/supacode/Infrastructure/AgentDetection/ScreenHeuristics.swift b/supacode/Infrastructure/AgentDetection/ScreenHeuristics.swift
index 33c2f55e..f5f63eb9 100644
--- a/supacode/Infrastructure/AgentDetection/ScreenHeuristics.swift
+++ b/supacode/Infrastructure/AgentDetection/ScreenHeuristics.swift
@@ -353,17 +353,22 @@ nonisolated private func hasInterruptPattern(_ lower: String) -> Bool {
     || (lower.contains("esc") && lower.contains("interrupt"))
 }
 
+private nonisolated let agentSpinnerScalars: Set<UnicodeScalar> = [
+  "·", "✱", "✲", "✳", "✴", "✵", "✶", "✷", "✸", "✹", "✺", "✻", "✼", "✽", "✾", "✿",
+  "❀", "❁", "❂", "❃", "❇", "❈", "❉", "❊", "❋", "✢", "✣", "✤", "✥", "✦", "✧", "✨",
+  "⊛", "⊕", "⊙", "◉", "◎", "◍", "⁂", "⁕", "※", "⍟", "☼", "★", "☆",
+]
+
+nonisolated func isAgentSpinnerScalar(_ scalar: UnicodeScalar) -> Bool {
+  agentSpinnerScalars.contains(scalar)
+}
+
 nonisolated func hasSpinnerActivity(_ content: String) -> Bool {
-  let spinnerScalars: Set<UnicodeScalar> = [
-    "·", "✱", "✲", "✳", "✴", "✵", "✶", "✷", "✸", "✹", "✺", "✻", "✼", "✽", "✾", "✿",
-    "❀", "❁", "❂", "❃", "❇", "❈", "❉", "❊", "❋", "✢", "✣", "✤", "✥", "✦", "✧", "✨",
-    "⊛", "⊕", "⊙", "◉", "◎", "◍", "⁂", "⁕", "※", "⍟", "☼", "★", "☆",
-  ]
-  return content.split(separator: "\n").contains { line in
+  content.split(separator: "\n").contains { line in
     let trimmed = line.trimmingCharacters(in: .whitespaces)
     guard let first = trimmed.unicodeScalars.first else { return false }
     let rest = String(trimmed.unicodeScalars.dropFirst())
-    return spinnerScalars.contains(first)
+    return isAgentSpinnerScalar(first)
       && rest.hasPrefix(" ")
       && rest.contains("…")
       && rest.contains(where: \.isLetter)
diff --git a/supacodeTests/AgentScreenRuleCoverageTests.swift b/supacodeTests/AgentScreenRuleCoverageTests.swift
new file mode 100644
index 00000000..528aba97
--- /dev/null
+++ b/supacodeTests/AgentScreenRuleCoverageTests.swift
@@ -0,0 +1,61 @@
+import Testing
+
+@testable import supacode
+
+/// Every typed rule must be witnessed by a captured screen.
+///
+/// `ClaudeScreenProfileTests` and `CodexScreenProfileTests` already assert that
+/// each rule ID is unique and runtime-prefixed, and inline synthetic screens
+/// exercise the predicates. Synthetic screens are written from the same mental
+/// model as the predicate they test, so they cannot falsify that model — only a
+/// capture can. This test makes the corpus an obligation rather than a sample:
+/// a rule with no captured witness is a rule whose shape has never been checked
+/// against a real agent.
+///
+/// Quarantined fixtures do not count. They document a state the detector gets
+/// wrong, so the rule they currently fire is the wrong one.
+struct AgentScreenRuleCoverageTests {
+  /// Rules that no captured screen reaches yet. Shrink this list by capturing the
+  /// missing screen; never grow it to make a red test green.
+  ///
+  /// - `codex.confirmationChoices`: not merely uncaptured — possibly unreachable.
+  ///   The captured command-permission screen satisfies this rule's structure
+  ///   (numbered selection, "Would you like…", Yes and No options) but ends with
+  ///   "Press enter to confirm or esc to cancel", so `codex.confirmationFooter`
+  ///   matches first and this rule never runs. Deleting that one footer line from
+  ///   the fixture flips the reason to `codex.confirmationChoices`, which is how
+  ///   the shadowing was confirmed. Reaching it needs a Codex confirmation whose
+  ///   last three lines after the selection carry none of the five footer markers,
+  ///   and no such screen has been seen on 0.146.1. If none exists, the rule is
+  ///   dead and should be removed rather than witnessed.
+  private static let knownUnwitnessed: Set<String> = [
+    "codex.confirmationChoices"
+  ]
+
+  @Test func everyTypedRuleHasACapturedWitness() throws {
+    let witnessed = Set(
+      try AgentScreenFixtureCorpus.load()
+        .filter { !$0.isQuarantined }
+        .map { $0.agent.detectScreen(in: $0.text).reason.identifier }
+    )
+
+    let typedRules =
+      ClaudeScreenProfile.RuleID.all.map(\.rawValue)
+      + CodexScreenProfile.RuleID.all.map(\.rawValue)
+
+    let unwitnessed = Set(typedRules.filter { !witnessed.contains($0) })
+
+    let regressed = unwitnessed.subtracting(Self.knownUnwitnessed).sorted()
+    #expect(
+      regressed.isEmpty,
+      """
+      Typed rules that lost their captured witness: \(regressed).
+      Capture a screen that fires each one with `prowl read --source detection`,
+      or quarantine it under known-misdetection if the detector gets it wrong.
+      """
+    )
+
+    let stale = Self.knownUnwitnessed.subtracting(unwitnessed).sorted()
+    #expect(stale.isEmpty, "These rules are witnessed now; drop them from knownUnwitnessed: \(stale)")
+  }
+}
diff --git a/supacodeTests/ClaudeBackgroundAgentDetectionTests.swift b/supacodeTests/ClaudeBackgroundAgentDetectionTests.swift
new file mode 100644
index 00000000..b6c728e0
--- /dev/null
+++ b/supacodeTests/ClaudeBackgroundAgentDetectionTests.swift
@@ -0,0 +1,143 @@
+import Testing
+
+@testable import supacode
+
+/// Reconstructed screens for the background-agent lifecycle.
+///
+/// The captured evidence lives in the fixture corpus; these are the synthetic
+/// boundary cases around it, kept inline per the corpus README.
+struct ClaudeBackgroundAgentDetectionTests {
+  private func detect(_ screen: String) -> AgentScreenDetection {
+    DetectedAgent.claude.detectScreen(in: screen)
+  }
+
+  @Test func waitRowReportsWorkingWithoutASpinnerEllipsis() {
+    // Claude Code 2.1.224. The turn has ended, so the only live marker is the wait
+    // row. It carries a spinner glyph but no "…", which hasSpinnerActivity requires.
+    let detection = detect(
+      """
+      ⏺ Subagent launched in the background, running sleep 300.
+
+      ✻ Waiting for 1 background agent to finish
+      ─────────
+      ❯
+      ─────────
+        ⏵⏵ auto mode on · 1 shell
+
+        ⏺ main
+        ◯ general-purpose  Sleep 300 then reply    1m 5s · ↓ 21.4k tokens
+      """
+    )
+
+    #expect(detection.state == .working)
+    #expect(detection.reason == .matched(ClaudeScreenProfile.RuleID.backgroundWork))
+  }
+
+  @Test func retainedAgentRowAloneDoesNotReportWorking() {
+    // Claude Code 2.1.224, observed live. A subagent that returned control but is
+    // still awaiting collection keeps its switcher row, with the elapsed value
+    // frozen at the moment it stopped. Nothing is running, so the pane must not
+    // report working — matching the "◯" row shape alone would pin it there.
+    let detection = detect(
+      """
+      ⏺ Agent "Sleep 300 then reply" finished · 1m 54s
+
+        Ran 3 shell commands
+
+      ✻ Churned for 2m 49s · 2 shells still running
+      ─────────
+      ❯
+      ─────────
+        ⏵⏵ auto mode on · 2 shells
+
+        ⏺ main
+        ◯ general-purpose  Sleep 300 then reply    1m 54s · ↓ 23.0k tokens
+      """
+    )
+
+    #expect(detection.state == .idle)
+  }
+
+  @Test func waitRowQuotedEarlierInTheTranscriptDoesNotReportWorking() {
+    // The rule reads the live status region, which is the last three non-blank
+    // lines above the prompt box. A wait row quoted further back in the
+    // transcript falls outside that window and stays idle.
+    //
+    // A quote inside the window is indistinguishable from live chrome on a single
+    // screen and does report working; the same limit applies to every rule scoped
+    // this way, including the pre-existing spinner rule.
+    let detection = detect(
+      """
+      ⏺ Earlier the screen showed:
+
+        ✻ Waiting for 1 background agent to finish
+
+      ⏺ That row is the one the detector keys on.
+      ⏺ It is quoted here, four lines above the box.
+      ⏺ Nothing is running now.
+      ─────────
+      ❯
+      ─────────
+        ⏵⏵ auto mode on (shift+tab to cycle)
+      """
+    )
+
+    #expect(detection.state == .idle)
+  }
+
+  @Test func workflowFooterVariantStillReportsWorking() {
+    // The pre-existing "agents done" workflow row keeps its behaviour and reason.
+    let detection = detect(
+      """
+      Task complete.
+      ─────────
+      ❯
+      ─────────
+      ◯ scout  Map idle detection  3/5 agents done · 7m 29s
+      """
+    )
+
+    #expect(detection.state == .working)
+    #expect(detection.reason == .matched(ClaudeScreenProfile.RuleID.backgroundWork))
+  }
+
+  @Test func elapsedStatusAcceptsMultiWordLabelsAndCompoundElapsed() {
+    let working = [
+      "● Running gates and merge lifecycle… (45s · ↓ 13.2k tokens)",
+      "● Actioning… (28m 34s · ↓ 47.7k tokens)",
+      "● Actioning… (1h 4m 2s · ↓ 47.7k tokens)",
+      "● Perusing… (3s · ↓ 77 tokens)",
+    ]
+    for row in working {
+      let detection = detect(
+        """
+        \(row)
+        ─────────
+        ❯
+        ─────────
+        """
+      )
+      #expect(detection.state == .working, "expected working for: \(row)")
+      #expect(detection.reason == .matched(ClaudeScreenProfile.RuleID.elapsedStatus))
+    }
+  }
+
+  @Test func incompleteElapsedSegmentsStayIdle() {
+    let notWorking = [
+      "● Retrying the merge lifecycle… (1st attempt)",
+      "● Actioning… (10seconds · ↓ 47.7k tokens)",
+      "● Actioning… (28m 34 · ↓ 47.7k tokens)",
+    ]
+    for row in notWorking {
+      let detection = detect(
+        """
+        \(row)
+        ─────────
+        ❯
+        ─────────
+        """
+      )
+      #expect(detection.state == .idle, "expected idle for: \(row)")
+    }
+  }
+}
diff --git a/supacodeTests/ClaudeScreenProfileTests.swift b/supacodeTests/ClaudeScreenProfileTests.swift
index 5ed61562..af592445 100644
--- a/supacodeTests/ClaudeScreenProfileTests.swift
+++ b/supacodeTests/ClaudeScreenProfileTests.swift
@@ -34,6 +34,12 @@ struct ClaudeScreenProfileTests {
       "claude/2.1.223/working/subagent-active.txt": .matched(
         ClaudeScreenProfile.RuleID.spinner
       ),
+      "claude/2.1.224/working/676-background-agent-wait.txt": .matched(
+        ClaudeScreenProfile.RuleID.backgroundWork
+      ),
+      "claude/2.1.224/working/676-compound-elapsed-status.txt": .matched(
+        ClaudeScreenProfile.RuleID.elapsedStatus
+      ),
     ]
     let fixtures = try AgentScreenFixtureCorpus.load().filter { $0.agent == .claude }
 
diff --git a/supacodeTests/Fixtures/AgentScreenDetection/claude/2.1.224/working/676-background-agent-wait.metadata.json b/supacodeTests/Fixtures/AgentScreenDetection/claude/2.1.224/working/676-background-agent-wait.metadata.json
new file mode 100644
index 00000000..8fec5a19
--- /dev/null
+++ b/supacodeTests/Fixtures/AgentScreenDetection/claude/2.1.224/working/676-background-agent-wait.metadata.json
@@ -0,0 +1,16 @@
+{
+  "schema_version": 1,
+  "captured_at": "2026-08-07T09:30:00Z",
+  "cli_version": "2.1.224",
+  "capture_source": "prowl-read-detection",
+  "terminal": {
+    "columns": 195,
+    "rows": 63
+  },
+  "redactions": [
+    "account and organization identifiers replaced with synthetic values",
+    "usage balances and plan labels replaced with placeholders",
+    "terminal right-edge padding removed without changing line wrapping"
+  ],
+  "issue": null
+}
diff --git a/supacodeTests/Fixtures/AgentScreenDetection/claude/2.1.224/working/676-background-agent-wait.txt b/supacodeTests/Fixtures/AgentScreenDetection/claude/2.1.224/working/676-background-agent-wait.txt
new file mode 100644
index 00000000..6106b7da
--- /dev/null
+++ b/supacodeTests/Fixtures/AgentScreenDetection/claude/2.1.224/working/676-background-agent-wait.txt
@@ -0,0 +1,59 @@
+│                                                    │ ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── │
+│                       ▐▛███▜▌                      │ What's new                                                                                                                                 │
+│                      ▝▜█████▛▘                     │ Added self-hosted environments: `claude self-hosted-runner` turns your own machines or containers into a place Claude Code web, mobile, a… │
+│                        ▘▘ ▝▝                       │ Added `archive` plugin source: install plugins from a zip over HTTPS without git or npm, with optional SHA-256 pinning                     │
+│   Opus 5 (1M context) with high… · Claude XXX ·    │ Added a cancel-and-confirm step when removing an unavailable paste changes a command's text                                                │
+│   <ACCOUNT_ID_0000>'s Org                          │ /release-notes for more                                                                                                                    │
+│              /…/scratchpad/fixture-ws              │                                                                                                                                            │
+╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+
+
+❯ Launch exactly one general-purpose subagent whose only job is to run the shell command `sleep 300` and then reply DONE. Run that subagent in the background. Then wait for it to finish and
+  report its reply. Do nothing else at all while waiting.
+
+⏺ I'll launch the subagent now.
+
+⏺ Agent(Sleep 300 then reply)
+  ⎿  Backgrounded agent (↓ to manage · ctrl+o to expand)
+  ⎿  Allowed by auto mode classifier
+
+⏺ Subagent launched in the background, running sleep 300. Waiting for its completion notification.
+
+✻ Waiting for 1 background agent to finish
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+❯
+───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+  ⚠ Transcript saving is off — inherited CLAUDE_CODE_CHILD_SESSION marker · restart with CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1 to keep future transcripts
+  [Opus 5 (1M context)] | --------------------  3% | $X.XX | ⏱️ 0m 54s | 🟢                                                                                                             /rc active
+  ⏵⏵ auto mode on · 1 shell
+
+  ⏺ main
+  ◯ general-purpose  Sleep 300 then reply                                                                                                                                    1m 5s · ↓ 21.4k tokens
\ No newline at end of file
diff --git a/supacodeTests/Fixtures/AgentScreenDetection/claude/2.1.224/working/676-compound-elapsed-status.metadata.json b/supacodeTests/Fixtures/AgentScreenDetection/claude/2.1.224/working/676-compound-elapsed-status.metadata.json
new file mode 100644
index 00000000..8b968e1a
--- /dev/null
+++ b/supacodeTests/Fixtures/AgentScreenDetection/claude/2.1.224/working/676-compound-elapsed-status.metadata.json
@@ -0,0 +1,16 @@
+{
+  "schema_version": 1,
+  "captured_at": "2026-08-07T09:50:00Z",
+  "cli_version": "2.1.224",
+  "capture_source": "prowl-read-detection",
+  "terminal": {
+    "columns": 167,
+    "rows": 47
+  },
+  "redactions": [
+    "capture root and account path segments replaced with equal-width synthetic values",
+    "usage balances and plan labels replaced with placeholders",
+    "terminal right-edge padding removed without changing line wrapping"
+  ],
+  "issue": null
+}
diff --git a/supacodeTests/Fixtures/AgentScreenDetection/claude/2.1.224/working/676-compound-elapsed-status.txt b/supacodeTests/Fixtures/AgentScreenDetection/claude/2.1.224/working/676-compound-elapsed-status.txt
new file mode 100644
index 00000000..7de6e8cc
--- /dev/null
+++ b/supacodeTests/Fixtures/AgentScreenDetection/claude/2.1.224/working/676-compound-elapsed-status.txt
@@ -0,0 +1,35 @@
+  281–290: 1823(3)1831(3)1847(3)1861(1)1867(3)1871(3)1873(1)1877(1)1879(3)1889(1)
+  291–300: 1901(1)1907(3)1913(1)1931(3)1933(1)1949(1)1951(3)1973(1)1979(3)1987(3)
+
+  Tally: 145 primes ≡ 1 (mod 4), 154 ≡ 3 (mod 4), plus 2. The 3-mod-4 lead through the whole range is Chebyshev's bias; the race first favors 1 mod 4 at 26861, well
+  past this list.
+
+  Generated from memory without computation tools, so the arithmetic carries no independent check.
+
+✻ Worked for 2m 5s
+
+❯ Run the script ./spin.sh in the foreground with a 200 second timeout and wait for it to finish. Reply DONE with its output. Use exactly one tool call and emit no
+  text before it.
+
+  Ran 1 shell command
+
+⏺ ./spin.sh does not exist in /Users/usr/Code/fixtureco/prowl/prowl (exit 127). Give me the correct path and I'll run it.
+
+✻ Churned for 6s
+
+❯ Run this exact command in the foreground with a 200 second timeout, using exactly one tool call and no text before it: bash
+  /private/tmp/claude-502/-Users-usr-Code-fixtureco-prowl-prowl/00000000-0000-0000-0000-000000000000/scratchpad/fixture-ws/spin.sh
+
+  Running 1 shell command · 1m 35s…
+  ⎿  $ bash /private/tmp/claude-502/-Users-usr-Code-fixtureco-prowl-prowl/00000000-0000-0000-0000-000000000000/scratchpad/fixture-ws/spin.sh (1m 32s)
+     (ctrl+b to run in background)
+
+● Perusing… (1m 38s · ↓ 187 tokens)
+  ⎿  Tip: Dynamic workflows let Claude write a script that orchestrates many agents for you. Mention the keyword ultracode or ask Claude to use a workflow directly.
+
+───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+❯
+───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+  ⚠ Transcript saving is off — inherited CLAUDE_CODE_CHILD_SESSION marker · restart with CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1 to keep future transcripts
+  [Opus 5 (1M context)] | #-------------------  6% | $X.XX | ⏱️ 16m 23s | 🟢                                                                                /rc active
+  ⏵⏵ auto mode on (shift+tab to cycle)
\ No newline at end of file
-- 
2.51.2


From 4b4fbcf4b0aa4583b3a8de8a3504b8b762a851c7 Mon Sep 17 00:00:00 2001
From: Simon Heimlicher <simon.github@heimlicher.com>
Date: Sat, 8 Aug 2026 14:23:56 +0200
Subject: [PATCH 03/19] Read wrapped rows and locate elapsed from the end of
 the row
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review on onevcat/Prowl#691 reproduced three reachable cases that still
classified an actively working session as idle. All three confirmed on
this branch before fixing.

Every rule read one physical line. Claude wraps a row too wide for the
pane onto continuation lines indented two spaces — observed at 40 columns
on Claude Code 2.1.225:

  ✻ Waiting for 1 background agent to
    finish

Narrow split panes are ordinary in Prowl, so both rules missed their own
screens at realistic widths. Rows are assembled into logical rows before
matching: an adjacent line indented past its head and starting with
ordinary text continues it, while a line carrying its own marker starts a
new row. That bound keeps joining from stitching together rows that were
never on screen, and a test asserts it.

The elapsed segment is now located from the END of the logical row. The
label is free text and contains parentheses, so anchoring at the first
'(' read 'focused)… (1m 38s' as the elapsed and rejected a live row.

The same narrow session showed a shape the review did not mention: at 32
columns Claude shortens the row rather than wrapping it, dropping the
detail segments so the elapsed terminates on ')' with no ' · ' at all.

Amends the design record per the repository guidelines: 012 states that no
subagent-wait rule was added for want of a failing screen, which is no
longer true. 013 records the failing screen, the retained-row trap, and
the wrapping defect, and is linked from 000-plan.md.
---
 .../030-agent-status-detection/000-plan.md    |  4 +
 ...-background-agent-wait-and-wrapped-rows.md | 92 +++++++++++++++++++
 .../AgentDetection/ClaudeScreenProfile.swift  | 74 ++++++++++++---
 .../ClaudeBackgroundAgentDetectionTests.swift | 83 +++++++++++++++++
 4 files changed, 241 insertions(+), 12 deletions(-)
 create mode 100644 docs-ai/030-agent-status-detection/013-background-agent-wait-and-wrapped-rows.md

diff --git a/docs-ai/030-agent-status-detection/000-plan.md b/docs-ai/030-agent-status-detection/000-plan.md
index 3996ed9e..43141473 100644
--- a/docs-ai/030-agent-status-detection/000-plan.md
+++ b/docs-ai/030-agent-status-detection/000-plan.md
@@ -142,3 +142,7 @@ the failed attempt to extend the first signal to plain commands is
   history-search viewer chrome was fixed from captured evidence, and the third-runtime
   adoption gate stopped further migration — see
   [012-claude-screen-profile.md](012-claude-screen-profile.md)
+- Updated 2026-08-08: a captured failing screen supports the subagent-wait rule that
+  012 deferred; adding it exposed that every row rule read one physical line, which
+  misses Claude's wrapped rows on narrow panes — see
+  [013-background-agent-wait-and-wrapped-rows.md](013-background-agent-wait-and-wrapped-rows.md)
diff --git a/docs-ai/030-agent-status-detection/013-background-agent-wait-and-wrapped-rows.md b/docs-ai/030-agent-status-detection/013-background-agent-wait-and-wrapped-rows.md
new file mode 100644
index 00000000..e2cb71c9
--- /dev/null
+++ b/docs-ai/030-agent-status-detection/013-background-agent-wait-and-wrapped-rows.md
@@ -0,0 +1,92 @@
+# 013 — Background-agent wait rule and wrapped status rows
+
+Amends [012-claude-screen-profile.md](012-claude-screen-profile.md), which states that
+"No subagent-wait rule was added because no captured failing screen supports one." A
+failing screen now exists, and adding the rule exposed a second defect that affects every
+row-based rule in the Claude profile.
+
+## The failing screen
+
+Captured with `prowl read --source detection` against Claude Code 2.1.224, sampling
+`prowl agents --json` at the same instant as the read:
+
+```text
+● Perusing… (1m 38s · ↓ 187 tokens)          ->  agents: done
+✻ Waiting for 1 background agent to finish   ->  agents: done
+```
+
+The corpus subagent fixtures retain a live spinner because Claude was still working
+alongside the subagent. The failing state is the one *after* its own turn ends: the
+spinner is replaced by the wait row, which carries a spinner glyph but no `…`, so
+`hasSpinnerActivity` rejects it.
+
+The second row is a separate defect. `hasElapsedStatusLine` required a one-word label and
+a single `<digits><unit>` token, so a correctly shaped row detected for 59 seconds and
+then reported idle for the rest of the turn.
+
+## Why the profile migration preserved both
+
+Neither rule had a captured witness. `claude.elapsedStatus` and `claude.backgroundWork`
+were exercised only by inline synthetic screens, and those screens were written from the
+same assumptions as the predicates they test — a single-word label with a single elapsed
+token, and a row containing the literal `agents done`. A test that restates its
+implementation cannot falsify it.
+
+Meanwhile every captured Claude working fixture retains a spinner, so `claude.spinner`
+returns first and shadows `claude.elapsedStatus` before it can be observed being wrong.
+
+`AgentScreenRuleCoverageTests` now asserts that every typed rule is fired by at least one
+non-quarantined captured fixture. It would have flagged both rules on the day the corpus
+landed.
+
+## The switcher block is not a liveness signal
+
+The `⏺ main` plus `◯` block below the prompt is the obvious way to detect background
+agents, and it is wrong. A subagent that returns control while it still awaits collection
+keeps its row, with the elapsed value frozen at the moment it stopped:
+
+```text
+⏺ Agent "Sleep 300 then reply" finished · 1m 54s
+...
+  ⏺ main
+  ◯ general-purpose  Sleep 300 then reply    1m 54s · ↓ 23.0k tokens
+```
+
+Observed live on 2.1.224. A single frame cannot separate that from a running agent, so
+matching the row shape holds the pane at working after the work has stopped — a worse
+failure than the one being fixed, because it is wrong in the direction that hides real
+idleness. The rule keys on the wait row instead, and the retained-row case is pinned by
+`ClaudeBackgroundAgentDetectionTests.retainedAgentRowAloneDoesNotReportWorking`.
+
+## Wrapped rows
+
+Every rule in the profile read one physical line. Claude wraps a row too wide for the pane
+onto continuation lines indented two spaces. Observed at 40 columns on 2.1.225:
+
+```text
+✻ Waiting for 1 background agent to
+  finish
+```
+
+Narrow split panes are ordinary in Prowl, so both rules missed their own captured screens
+at realistic widths. Rows are now assembled into logical rows before matching: an adjacent
+line indented past its head and starting with ordinary text is a continuation, while a
+line opening with its own marker starts a new row. That bound keeps continuation joining
+from stitching together rows that were never on screen.
+
+Two related shapes came out of the same narrow-terminal session and are covered by tests:
+
+- At 32 columns Claude *shortens* the row instead of wrapping it, dropping the detail
+  segments entirely and leaving `● Razzle-dazzling… (1m 7s)` — an elapsed terminated by
+  the closing paren with no `" · "` at all.
+- The label is free text and contains parentheses, so the elapsed segment is located from
+  the end of the row. Anchoring at the first `(` reads `focused)… (1m 38s` as the elapsed
+  and rejects `● Running tests (focused)… (1m 38s · ↓ 187 tokens)`.
+
+## Result
+
+`claude.backgroundWork` matches the wait row in the live status region, keeping the
+existing below-prompt `agents done` workflow marker. `claude.elapsedStatus` accepts a
+free-text label and a compound elapsed segment, located from the end of the logical row.
+Both read logical rows rather than physical lines. Two captured fixtures under
+`claude/2.1.224/working/` witness the rules, and a narrow capture covers the wrapped shape.
diff --git a/supacode/Infrastructure/AgentDetection/ClaudeScreenProfile.swift b/supacode/Infrastructure/AgentDetection/ClaudeScreenProfile.swift
index 1e82d589..3fbd5966 100644
--- a/supacode/Infrastructure/AgentDetection/ClaudeScreenProfile.swift
+++ b/supacode/Infrastructure/AgentDetection/ClaudeScreenProfile.swift
@@ -108,18 +108,69 @@ enum ClaudeScreenProfile {
   // tokens once it passes a minute: "45s", "28m 34s", "1h 4m 2s". Both parts stay
   // strict about completeness so transcript prose such as "(1st attempt)" or
   // "(10seconds)" still cannot pass as a live status row.
+  // Free-text labels contain parentheses — "Running tests (focused)…" — so the
+  // elapsed segment is located from the END of the row. Candidate openings are
+  // tried right to left, and the first one whose contents parse as a complete
+  // elapsed segment wins. Anchoring at the first "(" instead would read
+  // "focused)… (1m 38s" as the elapsed and reject a live row.
   nonisolated private static func hasElapsedStatusLine(_ content: String) -> Bool {
-    content.split(separator: "\n").contains { line in
-      let trimmed = line.trimmingCharacters(in: .whitespaces)
-      guard trimmed.first == "●" else { return false }
-      let body = trimmed.dropFirst().trimmingCharacters(in: .whitespaces)
-      guard let open = body.firstIndex(of: "(") else { return false }
+    logicalRows(content).contains { row in
+      guard row.first == "●" else { return false }
+      let body = row.dropFirst().trimmingCharacters(in: .whitespaces)
+
+      for open in body.indices.reversed() where body[open] == "(" {
+        let label = body[..<open].trimmingCharacters(in: .whitespaces)
+        guard label.hasSuffix("…") else { continue }
+        if hasCompleteElapsedSegment(body[body.index(after: open)...]) {
+          return true
+        }
+      }
+      return false
+    }
+  }
+
+  // Claude wraps a row too wide for the pane onto indented continuation lines —
+  // observed at 40 columns on 2.1.225:
+  //
+  //   "✻ Waiting for 1 background agent to"
+  //   "  finish"
+  //
+  // Narrow split panes are ordinary, so every rule that reads a row has to see the
+  // logical row rather than the first physical one. Only an adjacent line indented
+  // past its head and starting with ordinary text is a continuation: a line opening
+  // with its own marker starts a new row, which keeps this from swallowing the
+  // whole region and inventing rows that were never on screen.
+  nonisolated private static func logicalRows(_ content: String) -> [String] {
+    var rows: [String] = []
+    var current: String?
+    var headIndent = 0
 
-      let label = body[..<open].trimmingCharacters(in: .whitespaces)
-      guard label.hasSuffix("…") else { return false }
+    for line in content.split(separator: "\n", omittingEmptySubsequences: false) {
+      let trimmed = line.trimmingCharacters(in: .whitespaces)
+      guard !trimmed.isEmpty else {
+        if let row = current { rows.append(row) }
+        current = nil
+        continue
+      }
+      let indent = line.prefix(while: { $0 == " " }).count
 
-      return hasCompleteElapsedSegment(body[body.index(after: open)...])
+      if current != nil, indent > headIndent, !startsNewRow(trimmed) {
+        current?.append(" ")
+        current?.append(trimmed)
+        continue
+      }
+      if let row = current { rows.append(row) }
+      current = trimmed
+      headIndent = indent
     }
+    if let row = current { rows.append(row) }
+    return rows
+  }
+
+  nonisolated private static func startsNewRow(_ trimmed: String) -> Bool {
+    guard let first = trimmed.unicodeScalars.first else { return false }
+    if isAgentSpinnerScalar(first) { return true }
+    return "●⏺◯⎿❯─-".unicodeScalars.contains(first)
   }
 
   // One or more "<digits><unit>" tokens separated by single spaces, terminated by
@@ -158,12 +209,11 @@ enum ClaudeScreenProfile {
   // and it is scoped to the live status region so a transcript quoting it cannot
   // trip the rule.
   nonisolated private static func hasBackgroundAgentWait(_ liveStatus: String) -> Bool {
-    liveStatus.split(separator: "\n").contains { line in
-      let trimmed = line.trimmingCharacters(in: .whitespaces)
-      guard let first = trimmed.unicodeScalars.first, isAgentSpinnerScalar(first) else {
+    logicalRows(liveStatus).contains { row in
+      guard let first = row.unicodeScalars.first, isAgentSpinnerScalar(first) else {
         return false
       }
-      let lower = trimmed.lowercased()
+      let lower = row.lowercased()
       return lower.contains("waiting for") && lower.contains("background agent")
     }
   }
diff --git a/supacodeTests/ClaudeBackgroundAgentDetectionTests.swift b/supacodeTests/ClaudeBackgroundAgentDetectionTests.swift
index b6c728e0..9699ed6b 100644
--- a/supacodeTests/ClaudeBackgroundAgentDetectionTests.swift
+++ b/supacodeTests/ClaudeBackgroundAgentDetectionTests.swift
@@ -122,11 +122,94 @@ struct ClaudeBackgroundAgentDetectionTests {
     }
   }
 
+  @Test func wrappedRowsAreReadAsOneLogicalRow() {
+    // Claude Code 2.1.225 at 40 columns. Both shapes were observed on a real
+    // narrow pane; the continuation is indented two spaces.
+    let wrappedWait = detect(
+      """
+      ⏺ The subagent is running; waiting for its reply.
+
+      ✻ Waiting for 1 background agent to
+        finish
+      ────────
+      ❯
+      ────────
+      """
+    )
+    #expect(wrappedWait.state == .working)
+    #expect(wrappedWait.reason == .matched(ClaudeScreenProfile.RuleID.backgroundWork))
+
+    let wrappedElapsed = detect(
+      """
+      ● Running gates and merge lifecycle…
+        (1m 38s · ↓ 187 tokens)
+      ────────
+      ❯
+      ────────
+      """
+    )
+    #expect(wrappedElapsed.state == .working)
+    #expect(wrappedElapsed.reason == .matched(ClaudeScreenProfile.RuleID.elapsedStatus))
+  }
+
+  @Test func continuationJoiningDoesNotInventRows() {
+    // A following line that carries its own marker starts a new row rather than
+    // continuing the previous one, so nothing is stitched into a status row that
+    // was never on screen.
+    let detection = detect(
+      """
+      ⏺ Wrote the report.
+        ⎿  Waiting for 1 background agent to finish is what it said earlier
+      ⏺ Nothing is running now.
+      ────────
+      ❯
+      ────────
+      """
+    )
+
+    #expect(detection.state == .idle)
+  }
+
+  @Test func labelContainingParenthesesStillParses() {
+    // The label is free text, so the elapsed segment is located from the end of
+    // the row. Anchoring at the first "(" reads "focused)… (1m 38s" as elapsed.
+    let detection = detect(
+      """
+      ● Running tests (focused)… (1m 38s · ↓ 187 tokens)
+      ────────
+      ❯
+      ────────
+      """
+    )
+
+    #expect(detection.state == .working)
+    #expect(detection.reason == .matched(ClaudeScreenProfile.RuleID.elapsedStatus))
+  }
+
+  @Test func narrowPaneDropsDetailSegmentsAndStillParses() {
+    // At 32 columns Claude shortens the row rather than wrapping it, leaving the
+    // elapsed terminated by the closing paren with no " · " detail at all.
+    let detection = detect(
+      """
+      ● Razzle-dazzling… (1m 7s)
+      ────────
+      ❯
+      ────────
+      """
+    )
+
+    #expect(detection.state == .working)
+    #expect(detection.reason == .matched(ClaudeScreenProfile.RuleID.elapsedStatus))
+  }
+
   @Test func incompleteElapsedSegmentsStayIdle() {
     let notWorking = [
       "● Retrying the merge lifecycle… (1st attempt)",
       "● Actioning… (10seconds · ↓ 47.7k tokens)",
       "● Actioning… (28m 34 · ↓ 47.7k tokens)",
+      // Incomplete elapsed carried across a wrapped row stays incomplete.
+      "● Running gates and merge lifecycle…\n  (1st attempt)",
+      "● Running tests (focused)…\n  (10seconds · ↓ 187 tokens)",
     ]
     for row in notWorking {
       let detection = detect(
-- 
2.51.2


From 555be9c498828260a80fcd7f6cfd9ac6063c1a18 Mon Sep 17 00:00:00 2001
From: Simon Heimlicher <simon.github@heimlicher.com>
Date: Sat, 8 Aug 2026 14:34:44 +0200
Subject: [PATCH 04/19] Add a narrow real-terminal capture of the wrapped wait
 row
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Captured with prowl read --source detection on a 36-column Prowl pane,
Claude Code 2.1.226, sampling prowl agents at the same instant:

  ✻ Waiting for 1 background agent to
    finish

agents reported working, so this is the wrapping fix observed end to end
on a real pane rather than on a reconstruction. The earlier attempt forced
a narrow pty with tmux, which pads the unused width, adds a status bar and
masks the foreground process — not a screen the detector would ever see.

The wait row is 41 characters, so any pane under 41 columns reproduces the
wrap on demand. The elapsed row is less controllable: with a short label
Claude shortens the row instead of wrapping it.
---
 supacodeTests/ClaudeScreenProfileTests.swift  |  3 +
 ...rapped-background-agent-wait.metadata.json | 14 ++++
 .../676-wrapped-background-agent-wait.txt     | 70 +++++++++++++++++++
 3 files changed, 87 insertions(+)
 create mode 100644 supacodeTests/Fixtures/AgentScreenDetection/claude/2.1.226/working/676-wrapped-background-agent-wait.metadata.json
 create mode 100644 supacodeTests/Fixtures/AgentScreenDetection/claude/2.1.226/working/676-wrapped-background-agent-wait.txt

diff --git a/supacodeTests/ClaudeScreenProfileTests.swift b/supacodeTests/ClaudeScreenProfileTests.swift
index af592445..e5c124be 100644
--- a/supacodeTests/ClaudeScreenProfileTests.swift
+++ b/supacodeTests/ClaudeScreenProfileTests.swift
@@ -40,6 +40,9 @@ struct ClaudeScreenProfileTests {
       "claude/2.1.224/working/676-compound-elapsed-status.txt": .matched(
         ClaudeScreenProfile.RuleID.elapsedStatus
       ),
+      "claude/2.1.226/working/676-wrapped-background-agent-wait.txt": .matched(
+        ClaudeScreenProfile.RuleID.backgroundWork
+      ),
     ]
     let fixtures = try AgentScreenFixtureCorpus.load().filter { $0.agent == .claude }
 
diff --git a/supacodeTests/Fixtures/AgentScreenDetection/claude/2.1.226/working/676-wrapped-background-agent-wait.metadata.json b/supacodeTests/Fixtures/AgentScreenDetection/claude/2.1.226/working/676-wrapped-background-agent-wait.metadata.json
new file mode 100644
index 00000000..722cb705
--- /dev/null
+++ b/supacodeTests/Fixtures/AgentScreenDetection/claude/2.1.226/working/676-wrapped-background-agent-wait.metadata.json
@@ -0,0 +1,14 @@
+{
+  "schema_version": 1,
+  "captured_at": "2026-08-08T12:32:00Z",
+  "cli_version": "2.1.226",
+  "capture_source": "prowl-read-detection",
+  "terminal": {
+    "columns": 36,
+    "rows": 83
+  },
+  "redactions": [
+    "terminal right-edge padding removed without changing line wrapping"
+  ],
+  "issue": null
+}
diff --git a/supacodeTests/Fixtures/AgentScreenDetection/claude/2.1.226/working/676-wrapped-background-agent-wait.txt b/supacodeTests/Fixtures/AgentScreenDetection/claude/2.1.226/working/676-wrapped-background-agent-wait.txt
new file mode 100644
index 00000000..ec24dcad
--- /dev/null
+++ b/supacodeTests/Fixtures/AgentScreenDetection/claude/2.1.226/working/676-wrapped-background-agent-wait.txt
@@ -0,0 +1,70 @@
+╰──────────────────────────────────╯
+
+
+❯ Launch exactly one
+  general-purpose subagent whose
+  only job is to run bash spin.sh
+  and reply DONE. Background it,
+  then wait for it and report its
+  reply. Do nothing else while
+  waiting.
+
+⏺ I'll launch the subagent now.
+
+⏺ Agent(Run spin.sh script)
+  ⎿  Backgrounded agent (↓ to
+  ⎿  Allowed by auto mode
+
+⏺ Agent is running. Waiting for its
+  reply.
+
+✻ Waiting for 1 background agent to
+  finish
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+────────────────────────────────────
+❯
+────────────────────────────────────
+  ⚠ Transcript saving is off — inhe…
+  [Opus 5 (1M context)] | --------…
+  ⏵⏵ auto mode on (shift+tab to
+
+  ⏺ main
+  ◯ general-purpose 55s · ↓ 15.0k
\ No newline at end of file
-- 
2.51.2


From d4caf058ba102cdc18fdb83cf807338b43dd4766 Mon Sep 17 00:00:00 2001
From: Simon Heimlicher <simon.github@heimlicher.com>
Date: Sun, 9 Aug 2026 07:23:10 +0200
Subject: [PATCH 05/19] Assemble live status rows before limiting the region

The live status region took the last three non-blank physical lines above
the prompt box and only then assembled them into logical rows. A row that
wraps onto three or more continuations pushes its own head out of that
window, and the head carries the glyph every rule keys on, so an active
session reported idle. Roughly twenty columns is enough for the
background-agent wait row to wrap that far.

Assemble the region into logical rows first, then keep the last three.
With nothing wrapped these are the same three rows as before.

Claude-Session: https://claude.ai/code/session_01RcYVV3zEDZwrqMEZ4s4cef
---
 ...-background-agent-wait-and-wrapped-rows.md |  13 ++-
 .../AgentDetection/ClaudeScreenProfile.swift  | 107 ++++++++++--------
 .../ClaudeBackgroundAgentDetectionTests.swift |  41 +++++++
 3 files changed, 111 insertions(+), 50 deletions(-)

diff --git a/docs-ai/030-agent-status-detection/013-background-agent-wait-and-wrapped-rows.md b/docs-ai/030-agent-status-detection/013-background-agent-wait-and-wrapped-rows.md
index e2cb71c9..cc0cb8b1 100644
--- a/docs-ai/030-agent-status-detection/013-background-agent-wait-and-wrapped-rows.md
+++ b/docs-ai/030-agent-status-detection/013-background-agent-wait-and-wrapped-rows.md
@@ -83,10 +83,21 @@ Two related shapes came out of the same narrow-terminal session and are covered
   the end of the row. Anchoring at the first `(` reads `focused)… (1m 38s` as the elapsed
   and rejects `● Running tests (focused)… (1m 38s · ↓ 187 tokens)`.
 
+Assembling rows is not enough on its own, because the region that selects which rows the
+rules see was still counted in physical lines. `ClaudeScreenRegions.liveStatus` took the
+last three non-blank lines above the box and only then handed them to the row assembler,
+so a row wrapping onto three or more continuations pushed its own head out of the window.
+The head is what carries the `●` or the spinner, so the reconstructed row could not match
+and the pane reported idle. Surfaces that narrow are reachable, and the shape is not
+exotic: `✻ Waiting for 1 background agent to finish` needs only about twenty columns to
+wrap that far. The region is now assembled into logical rows first and limited to the last
+three of those, which is the same three rows whenever nothing wraps.
+
 ## Result
 
 `claude.backgroundWork` matches the wait row in the live status region, keeping the
 existing below-prompt `agents done` workflow marker. `claude.elapsedStatus` accepts a
 free-text label and a compound elapsed segment, located from the end of the logical row.
-Both read logical rows rather than physical lines. Two captured fixtures under
+Both read logical rows rather than physical lines, and so does the live status region that
+feeds them. Two captured fixtures under
 `claude/2.1.224/working/` witness the rules, and a narrow capture covers the wrapped shape.
diff --git a/supacode/Infrastructure/AgentDetection/ClaudeScreenProfile.swift b/supacode/Infrastructure/AgentDetection/ClaudeScreenProfile.swift
index 3fbd5966..d51a693c 100644
--- a/supacode/Infrastructure/AgentDetection/ClaudeScreenProfile.swift
+++ b/supacode/Infrastructure/AgentDetection/ClaudeScreenProfile.swift
@@ -114,7 +114,7 @@ enum ClaudeScreenProfile {
   // elapsed segment wins. Anchoring at the first "(" instead would read
   // "focused)… (1m 38s" as the elapsed and reject a live row.
   nonisolated private static func hasElapsedStatusLine(_ content: String) -> Bool {
-    logicalRows(content).contains { row in
+    claudeLogicalRows(content).contains { row in
       guard row.first == "●" else { return false }
       let body = row.dropFirst().trimmingCharacters(in: .whitespaces)
 
@@ -129,50 +129,6 @@ enum ClaudeScreenProfile {
     }
   }
 
-  // Claude wraps a row too wide for the pane onto indented continuation lines —
-  // observed at 40 columns on 2.1.225:
-  //
-  //   "✻ Waiting for 1 background agent to"
-  //   "  finish"
-  //
-  // Narrow split panes are ordinary, so every rule that reads a row has to see the
-  // logical row rather than the first physical one. Only an adjacent line indented
-  // past its head and starting with ordinary text is a continuation: a line opening
-  // with its own marker starts a new row, which keeps this from swallowing the
-  // whole region and inventing rows that were never on screen.
-  nonisolated private static func logicalRows(_ content: String) -> [String] {
-    var rows: [String] = []
-    var current: String?
-    var headIndent = 0
-
-    for line in content.split(separator: "\n", omittingEmptySubsequences: false) {
-      let trimmed = line.trimmingCharacters(in: .whitespaces)
-      guard !trimmed.isEmpty else {
-        if let row = current { rows.append(row) }
-        current = nil
-        continue
-      }
-      let indent = line.prefix(while: { $0 == " " }).count
-
-      if current != nil, indent > headIndent, !startsNewRow(trimmed) {
-        current?.append(" ")
-        current?.append(trimmed)
-        continue
-      }
-      if let row = current { rows.append(row) }
-      current = trimmed
-      headIndent = indent
-    }
-    if let row = current { rows.append(row) }
-    return rows
-  }
-
-  nonisolated private static func startsNewRow(_ trimmed: String) -> Bool {
-    guard let first = trimmed.unicodeScalars.first else { return false }
-    if isAgentSpinnerScalar(first) { return true }
-    return "●⏺◯⎿❯─-".unicodeScalars.contains(first)
-  }
-
   // One or more "<digits><unit>" tokens separated by single spaces, terminated by
   // the closing paren or by the " · " that separates elapsed from the rest of the
   // row. A partial token ("10seconds", "1st") fails the terminator check.
@@ -209,7 +165,7 @@ enum ClaudeScreenProfile {
   // and it is scoped to the live status region so a transcript quoting it cannot
   // trip the rule.
   nonisolated private static func hasBackgroundAgentWait(_ liveStatus: String) -> Bool {
-    logicalRows(liveStatus).contains { row in
+    claudeLogicalRows(liveStatus).contains { row in
       guard let first = row.unicodeScalars.first, isAgentSpinnerScalar(first) else {
         return false
       }
@@ -237,10 +193,15 @@ private struct ClaudeScreenRegions: Sendable {
     )
     self.currentInteractionLines = currentInteractionLines
     self.currentInteractionLower = currentInteractionLines.joined(separator: "\n").lowercased()
-    self.liveStatus = agentDetectionRecentLines(
-      Self.contentAbovePrompt(screenLines: lines, promptIndex: promptIndex),
-      limit: 3
+    // Reconstruct rows before limiting the region. Counting the limit in physical
+    // lines drops the head of any row that wraps onto three or more continuations,
+    // and the head is what carries the "●" or spinner glyph the rules key on.
+    // Widths that narrow are reachable: a surface can be as few as five columns.
+    self.liveStatus = claudeLogicalRows(
+      Self.contentAbovePrompt(screenLines: lines, promptIndex: promptIndex)
     )
+    .suffix(3)
+    .joined(separator: "\n")
     self.belowPromptLines = Self.contentBelowPrompt(screenLines: lines, promptIndex: promptIndex)
       .split(separator: "\n", omittingEmptySubsequences: false)
       .map(String.init)
@@ -298,6 +259,54 @@ private struct ClaudeScreenRegions: Sendable {
   }
 }
 
+// Claude wraps a row too wide for the pane onto indented continuation lines —
+// observed at 40 columns on 2.1.225:
+//
+//   "✻ Waiting for 1 background agent to"
+//   "  finish"
+//
+// Narrow split panes are ordinary, so every rule that reads a row has to see the
+// logical row rather than the first physical one, and so does the region that
+// selects which rows the rules see. Only an adjacent line indented past its head
+// and starting with ordinary text is a continuation: a line opening with its own
+// marker starts a new row, which keeps this from swallowing the whole region and
+// inventing rows that were never on screen.
+//
+// Rows arrive already trimmed and unindented, so running this over its own output
+// returns that output unchanged.
+nonisolated private func claudeLogicalRows(_ content: String) -> [String] {
+  var rows: [String] = []
+  var current: String?
+  var headIndent = 0
+
+  for line in content.split(separator: "\n", omittingEmptySubsequences: false) {
+    let trimmed = line.trimmingCharacters(in: .whitespaces)
+    guard !trimmed.isEmpty else {
+      if let row = current { rows.append(row) }
+      current = nil
+      continue
+    }
+    let indent = line.prefix(while: { $0 == " " }).count
+
+    if current != nil, indent > headIndent, !claudeRowStartsNewRow(trimmed) {
+      current?.append(" ")
+      current?.append(trimmed)
+      continue
+    }
+    if let row = current { rows.append(row) }
+    current = trimmed
+    headIndent = indent
+  }
+  if let row = current { rows.append(row) }
+  return rows
+}
+
+nonisolated private func claudeRowStartsNewRow(_ trimmed: String) -> Bool {
+  guard let first = trimmed.unicodeScalars.first else { return false }
+  if isAgentSpinnerScalar(first) { return true }
+  return "●⏺◯⎿❯─-".unicodeScalars.contains(first)
+}
+
 nonisolated private func isClaudeNumberedSelectionLine(_ line: String) -> Bool {
   let trimmed = line.trimmingCharacters(in: .whitespaces)
   guard trimmed.first == "❯" else { return false }
diff --git a/supacodeTests/ClaudeBackgroundAgentDetectionTests.swift b/supacodeTests/ClaudeBackgroundAgentDetectionTests.swift
index 9699ed6b..0583e10e 100644
--- a/supacodeTests/ClaudeBackgroundAgentDetectionTests.swift
+++ b/supacodeTests/ClaudeBackgroundAgentDetectionTests.swift
@@ -152,6 +152,47 @@ struct ClaudeBackgroundAgentDetectionTests {
     #expect(wrappedElapsed.reason == .matched(ClaudeScreenProfile.RuleID.elapsedStatus))
   }
 
+  @Test func rowWrappedPastTheRegionLimitKeepsItsHead() {
+    // The live status region is the last three rows above the box. A row narrow
+    // enough to wrap onto four or more physical lines pushes its own head out of
+    // a window counted in physical lines, and the head carries the glyph every
+    // rule keys on. The region is therefore reconstructed into logical rows
+    // before the limit applies.
+    let wrappedWait = detect(
+      """
+      ⏺ Launched it.
+
+      ✻ Waiting
+        for 1
+        background
+        agent to
+        finish
+      ────
+      ❯
+      ────
+      """
+    )
+    #expect(wrappedWait.state == .working)
+    #expect(wrappedWait.reason == .matched(ClaudeScreenProfile.RuleID.backgroundWork))
+
+    let wrappedElapsed = detect(
+      """
+      ⏺ Started.
+
+      ● Running
+        gates…
+        (1m 38s ·
+        ↓ 187
+        tokens)
+      ────
+      ❯
+      ────
+      """
+    )
+    #expect(wrappedElapsed.state == .working)
+    #expect(wrappedElapsed.reason == .matched(ClaudeScreenProfile.RuleID.elapsedStatus))
+  }
+
   @Test func continuationJoiningDoesNotInventRows() {
     // A following line that carries its own marker starts a new row rather than
     // continuing the previous one, so nothing is stitched into a status row that
-- 
2.51.2


From 6ad3d2fbe3d80cc8198aee1847211572d16b3701 Mon Sep 17 00:00:00 2001
From: SamsonCJ <cs3507529000@gmail.com>
Date: Sun, 9 Aug 2026 19:27:23 -0700
Subject: [PATCH 06/19] Fix Canvas follower link event routing

---
 .../Models/CanvasInteractionPolicy.swift      |  22 +++
 .../Canvas/Views/CanvasCardView.swift         |  12 +-
 .../Features/Canvas/Views/CanvasView.swift    |  23 +--
 .../CanvasCardEventRoutingTests.swift         | 179 ++++++++++++++++++
 .../CanvasInteractionPolicyTests.swift        |  38 ++++
 5 files changed, 262 insertions(+), 12 deletions(-)
 create mode 100644 supacodeTests/CanvasCardEventRoutingTests.swift

diff --git a/supacode/Features/Canvas/Models/CanvasInteractionPolicy.swift b/supacode/Features/Canvas/Models/CanvasInteractionPolicy.swift
index 21eb6575..1cc63fb8 100644
--- a/supacode/Features/Canvas/Models/CanvasInteractionPolicy.swift
+++ b/supacode/Features/Canvas/Models/CanvasInteractionPolicy.swift
@@ -6,6 +6,16 @@ enum CanvasInteractionPolicy {
     hasHoveredLink && isCommandModifierActive
   }
 
+  /// Whether any terminal pane of a card that is actually on screen currently
+  /// has a hovered link. Only `visibleLeaves()` are scanned: a pane hidden by
+  /// split zoom can otherwise retain a stale `mouseOverLink` and incorrectly
+  /// disable the selection shield for the visible pane.
+  static func hasHoveredLink(in tree: SplitTree<GhosttySurfaceView>) -> Bool {
+    tree.visibleLeaves().contains {
+      $0.bridge.state.mouseOverLink?.isEmpty == false
+    }
+  }
+
   static func showsSelectionShield(
     commandSelectionActive: Bool,
     selectionModeActive: Bool,
@@ -20,4 +30,16 @@ enum CanvasInteractionPolicy {
     }
     return broadcastFollower
   }
+
+  /// Whether a card's terminal surface should receive mouse events. Focused
+  /// cards are always interactive; for every other card (e.g. broadcast
+  /// followers) a link activation is the only interaction allowed through —
+  /// anything else must keep routing to the selection callbacks.
+  static func terminalHitTestingEnabled(
+    isFocused: Bool,
+    linkActivationRequested: Bool,
+    showsSelectionShield: Bool
+  ) -> Bool {
+    (isFocused || linkActivationRequested) && !showsSelectionShield
+  }
 }
diff --git a/supacode/Features/Canvas/Views/CanvasCardView.swift b/supacode/Features/Canvas/Views/CanvasCardView.swift
index 44d2fa12..e17f94d9 100644
--- a/supacode/Features/Canvas/Views/CanvasCardView.swift
+++ b/supacode/Features/Canvas/Views/CanvasCardView.swift
@@ -35,6 +35,10 @@ struct CanvasCardView: View {
   /// parent resolves it since CanvasCardView has no keybindings context).
   let expandHelp: String
   let canvasScale: CGFloat
+  /// Whether a terminal link is currently hovered while Command is held, so
+  /// the click must reach Ghostty even on non-focused cards (broadcast
+  /// followers) instead of falling through to the selection callbacks.
+  let linkActivationRequested: Bool
   let showsSelectionShield: Bool
   let onTap: () -> Void
   let onSelectionTap: () -> Void
@@ -269,7 +273,13 @@ struct CanvasCardView: View {
     // withAnimation (expand/restore, resize commit, arrange), so the terminal
     // refit stays in lock-step with the card's offset/scale. Without a wrapping
     // animation (live resize drag) the size tracks the gesture 1:1.
-    .allowsHitTesting(isFocused && !showsSelectionShield)
+    .allowsHitTesting(
+      CanvasInteractionPolicy.terminalHitTestingEnabled(
+        isFocused: isFocused,
+        linkActivationRequested: linkActivationRequested,
+        showsSelectionShield: showsSelectionShield
+      )
+    )
   }
 
   private var selectionShield: some View {
diff --git a/supacode/Features/Canvas/Views/CanvasView.swift b/supacode/Features/Canvas/Views/CanvasView.swift
index 815396f0..f9b66f1b 100644
--- a/supacode/Features/Canvas/Views/CanvasView.swift
+++ b/supacode/Features/Canvas/Views/CanvasView.swift
@@ -256,22 +256,21 @@ struct CanvasView: View {
     .onDisappear { deactivateCanvas() }
   }
 
-  func showsSelectionShield(
+  func interactionState(
     for tabID: TerminalTabID,
     in tree: SplitTree<GhosttySurfaceView>
-  ) -> Bool {
-    let hasHoveredLink = tree.leaves().contains {
-      $0.bridge.state.mouseOverLink?.isEmpty == false
-    }
-    return CanvasInteractionPolicy.showsSelectionShield(
+  ) -> (linkActivationRequested: Bool, showsSelectionShield: Bool) {
+    let linkActivationRequested = CanvasInteractionPolicy.linkActivationRequested(
+      hasHoveredLink: CanvasInteractionPolicy.hasHoveredLink(in: tree),
+      isCommandModifierActive: NSEvent.modifierFlags.contains(.command)
+    )
+    let showsSelectionShield = CanvasInteractionPolicy.showsSelectionShield(
       commandSelectionActive: commandKeyObserver.isPressed,
       selectionModeActive: selectionState.isSelecting,
       broadcastFollower: selectionState.isBroadcasting && selectionState.primaryTabID != tabID,
-      linkActivationRequested: CanvasInteractionPolicy.linkActivationRequested(
-        hasHoveredLink: hasHoveredLink,
-        isCommandModifierActive: NSEvent.modifierFlags.contains(.command)
-      )
+      linkActivationRequested: linkActivationRequested
     )
+    return (linkActivationRequested, showsSelectionShield)
   }
 
   // MARK: - Cards Layer
@@ -341,6 +340,7 @@ struct CanvasView: View {
     let splitDivider = terminalManager.splitDividerAppearance()
     let repositoryAppearance = appearance(for: state.repositoryRootURL)
     let resolvedRepositoryName = repositoryDisplayName(for: state.repositoryRootURL)
+    let interaction = interactionState(for: tab.id, in: tree)
 
     AnimatedExpandableCard(
       progress: isCardExpanded ? 1 : 0,
@@ -369,7 +369,8 @@ struct CanvasView: View {
         isExpanded: isCardExpanded,
         expandHelp: expandHelp,
         canvasScale: isCardExpanded ? 1 : canvasScale,
-        showsSelectionShield: showsSelectionShield(for: tab.id, in: tree),
+        linkActivationRequested: interaction.linkActivationRequested,
+        showsSelectionShield: interaction.showsSelectionShield,
         onTap: {
           let cmdHeld = NSEvent.modifierFlags.contains(.command)
           if cmdHeld {
diff --git a/supacodeTests/CanvasCardEventRoutingTests.swift b/supacodeTests/CanvasCardEventRoutingTests.swift
new file mode 100644
index 00000000..e0245ce0
--- /dev/null
+++ b/supacodeTests/CanvasCardEventRoutingTests.swift
@@ -0,0 +1,179 @@
+import AppKit
+import GhosttyKit
+import SwiftUI
+import Testing
+
+@testable import supacode
+
+@MainActor
+struct CanvasCardEventRoutingTests {
+  @Test func commandClickOnFollowerLinkRoutesToGhosttyWithoutChangingSelection() async throws {
+    let fixture = CanvasCardEventRoutingFixture(hasHoveredLink: true)
+    defer { fixture.close() }
+    await fixture.prepareForHitTesting()
+
+    let target = try #require(fixture.sendCommandClick())
+    await fixture.drainMainQueue()
+
+    #expect(target === fixture.surfaceView)
+    #expect(fixture.tapRecorder.selectionTapCount == 0)
+    #expect(fixture.tapRecorder.outerTapCount == 0)
+  }
+
+  @Test func commandClickOnFollowerNonLinkContentStillRoutesToSelection() async throws {
+    let fixture = CanvasCardEventRoutingFixture(hasHoveredLink: false)
+    defer { fixture.close() }
+    await fixture.prepareForHitTesting()
+
+    let target = try #require(fixture.sendCommandClick())
+    await fixture.drainMainQueue()
+
+    #expect(target !== fixture.surfaceView)
+    #expect(fixture.tapRecorder.selectionTapCount == 1)
+    #expect(fixture.tapRecorder.outerTapCount == 0)
+  }
+}
+
+@MainActor
+private final class CanvasCardEventRoutingFixture {
+  let surfaceView: GhosttySurfaceView
+  let tapRecorder = CanvasCardTapRecorder()
+
+  private let cardSize = CGSize(width: 320, height: 200)
+  private let window: NSWindow
+  private let hostingView: NSHostingView<CanvasCardView>
+
+  init(hasHoveredLink: Bool) {
+    let runtime = GhosttyRuntime()
+    let surfaceView = GhosttySurfaceView(
+      runtime: runtime,
+      workingDirectory: nil,
+      context: GHOSTTY_SURFACE_CONTEXT_TAB,
+      skipsSurfaceCreationForTesting: true
+    )
+    self.surfaceView = surfaceView
+    surfaceView.bridge.state.mouseOverLink = hasHoveredLink ? "https://example.com" : nil
+
+    let tab = TerminalTabItem(title: "Follower", icon: nil)
+    let linkActivationRequested = CanvasInteractionPolicy.linkActivationRequested(
+      hasHoveredLink: CanvasInteractionPolicy.hasHoveredLink(in: SplitTree(view: surfaceView)),
+      isCommandModifierActive: true
+    )
+    let showsSelectionShield = CanvasInteractionPolicy.showsSelectionShield(
+      commandSelectionActive: true,
+      selectionModeActive: true,
+      broadcastFollower: true,
+      linkActivationRequested: linkActivationRequested
+    )
+    let card = CanvasCardView(
+      repositoryName: "Prowl",
+      worktreeName: tab.displayTitle,
+      tree: SplitTree(view: surfaceView),
+      activeSurfaceID: surfaceView.id,
+      unfocusedSplitOverlay: (nil, 0),
+      isFocused: false,
+      isSelected: true,
+      hasUnseenNotification: false,
+      tabIcon: nil,
+      tabId: tab.id,
+      tabs: [tab],
+      tabContextMenuActions: TerminalTabContextMenuActions(
+        renameTab: { _ in },
+        changeIcon: { _ in },
+        closeTab: { _ in },
+        closeOthers: { _ in },
+        closeToRight: { _ in },
+        closeAll: {}
+      ),
+      cardSize: cardSize,
+      isExpanded: false,
+      expandHelp: "Expand card",
+      canvasScale: 1,
+      linkActivationRequested: linkActivationRequested,
+      showsSelectionShield: showsSelectionShield,
+      onTap: { [tapRecorder] in tapRecorder.outerTapCount += 1 },
+      onSelectionTap: { [tapRecorder] in tapRecorder.selectionTapCount += 1 },
+      onDragCommit: { _ in },
+      onResize: { _, _ in },
+      onResizeEnd: {},
+      onSplitOperation: { _ in },
+      onTitleBarTap: {},
+      onExpand: {},
+      onClose: {}
+    )
+
+    let contentSize = CGSize(width: cardSize.width, height: cardSize.height + 28)
+    window = NSWindow(
+      contentRect: NSRect(origin: .zero, size: contentSize),
+      styleMask: [.borderless],
+      backing: .buffered,
+      defer: false
+    )
+    hostingView = NSHostingView(rootView: card)
+    hostingView.frame = NSRect(origin: .zero, size: contentSize)
+    window.contentView = hostingView
+  }
+
+  func prepareForHitTesting() async {
+    window.orderFront(nil)
+    hostingView.layoutSubtreeIfNeeded()
+    await drainMainQueue()
+    hostingView.layoutSubtreeIfNeeded()
+  }
+
+  func sendCommandClick() -> NSView? {
+    let point = NSPoint(x: cardSize.width / 2, y: cardSize.height / 2)
+    let target = hostingView.hitTest(point)
+    let locationInWindow = hostingView.convert(point, to: nil)
+    let timestamp = ProcessInfo.processInfo.systemUptime
+
+    guard
+      let mouseDown = NSEvent.mouseEvent(
+        with: .leftMouseDown,
+        location: locationInWindow,
+        modifierFlags: .command,
+        timestamp: timestamp,
+        windowNumber: window.windowNumber,
+        context: nil,
+        eventNumber: 1,
+        clickCount: 1,
+        pressure: 1
+      ),
+      let mouseUp = NSEvent.mouseEvent(
+        with: .leftMouseUp,
+        location: locationInWindow,
+        modifierFlags: .command,
+        timestamp: timestamp,
+        windowNumber: window.windowNumber,
+        context: nil,
+        eventNumber: 2,
+        clickCount: 1,
+        pressure: 0
+      )
+    else {
+      return nil
+    }
+
+    window.sendEvent(mouseDown)
+    window.sendEvent(mouseUp)
+    return target
+  }
+
+  func close() {
+    window.orderOut(nil)
+  }
+
+  func drainMainQueue() async {
+    await withCheckedContinuation { continuation in
+      DispatchQueue.main.async {
+        continuation.resume()
+      }
+    }
+  }
+}
+
+@MainActor
+private final class CanvasCardTapRecorder {
+  var outerTapCount = 0
+  var selectionTapCount = 0
+}
diff --git a/supacodeTests/CanvasInteractionPolicyTests.swift b/supacodeTests/CanvasInteractionPolicyTests.swift
index ae6c3051..8b001231 100644
--- a/supacodeTests/CanvasInteractionPolicyTests.swift
+++ b/supacodeTests/CanvasInteractionPolicyTests.swift
@@ -1,3 +1,4 @@
+import GhosttyKit
 import Testing
 
 @testable import supacode
@@ -74,4 +75,41 @@ struct CanvasInteractionPolicyTests {
     #expect(linkActivationRequested == false)
     #expect(showsShield)
   }
+
+  @Test @MainActor func hiddenZoomedPaneDoesNotContributeStaleHoveredLink() throws {
+    let runtime = GhosttyRuntime()
+    let hiddenPane = makeSurface(runtime: runtime)
+    let visiblePane = makeSurface(runtime: runtime)
+    hiddenPane.bridge.state.mouseOverLink = "https://example.com/stale"
+
+    let tree = try SplitTree(view: hiddenPane)
+      .inserting(view: visiblePane, at: hiddenPane, direction: .right)
+    let zoomedTree = tree.settingZoomed(try #require(tree.find(id: visiblePane.id)))
+    let linkActivationRequested = CanvasInteractionPolicy.linkActivationRequested(
+      hasHoveredLink: CanvasInteractionPolicy.hasHoveredLink(in: zoomedTree),
+      isCommandModifierActive: true
+    )
+    let showsShield = CanvasInteractionPolicy.showsSelectionShield(
+      commandSelectionActive: true,
+      selectionModeActive: false,
+      broadcastFollower: false,
+      linkActivationRequested: linkActivationRequested
+    )
+
+    #expect(linkActivationRequested == false)
+    #expect(showsShield)
+
+    visiblePane.bridge.state.mouseOverLink = "https://example.com/visible"
+    #expect(CanvasInteractionPolicy.hasHoveredLink(in: zoomedTree))
+  }
+
+  @MainActor
+  private func makeSurface(runtime: GhosttyRuntime) -> GhosttySurfaceView {
+    GhosttySurfaceView(
+      runtime: runtime,
+      workingDirectory: nil,
+      context: GHOSTTY_SURFACE_CONTEXT_TAB,
+      skipsSurfaceCreationForTesting: true
+    )
+  }
 }
-- 
2.51.2


From 3e77c8bb7a03c4a1ccd3ef6bdb18299832cd710b Mon Sep 17 00:00:00 2001
From: onevcat <onevcat@gmail.com>
Date: Tue, 11 Aug 2026 22:45:23 +0900
Subject: [PATCH 07/19] feat(cli): add agent transcript snapshots

---
 ProwlCLI/Commands/AgentsCommand.swift         |   3 +-
 ProwlCLI/Commands/AgentsReadCommand.swift     |  60 +++++
 ProwlCLI/Output/OutputRenderer.swift          |  51 ++++
 .../Transport/SocketTransportClient.swift     |   4 +-
 .../AgentReadOutputRendererTests.swift        |  61 +++++
 ProwlCLITests/AgentsCommandParsingTests.swift |  27 ++
 .../013-prowl-cli/contracts/agents-read.md    | 130 ++++++++++
 docs-ai/013-prowl-cli/contracts/input.md      |  28 ++-
 docs-ai/013-prowl-cli/contracts/schema.md     | 111 ++++++++-
 .../000-plan.md                               | 158 ++++++++++++
 .../001-action.md                             |  54 ++++
 docs-ai/README.md                             |   1 +
 docs/components/cli.md                        |  54 +++-
 skills/prowl-cli/SKILL.md                     |  31 ++-
 supacode/App/supacodeApp.swift                | 125 ++++++++++
 .../CLIService/AgentReadCommandHandler.swift  | 168 +++++++++++++
 supacode/CLIService/CLICommandRouter.swift    |   4 +
 supacode/CLIService/CLISocketServer.swift     |   5 +-
 .../Shared/AgentReadCommandPayload.swift      | 121 +++++++++
 .../Shared/AgentsCommandPayload.swift         |   2 +-
 .../CLIService/Shared/CommandEnvelope.swift   |   2 +
 supacode/CLIService/Shared/ErrorCodes.swift   |   8 +
 supacode/CLIService/Shared/InputModels.swift  |  21 ++
 .../AgentDetection/AgentSessionResolver.swift |  50 +++-
 .../AgentTranscriptResultReader.swift         | 233 ++++++++++++++++++
 .../AgentDetection/ClaudeScreenProfile.swift  |  10 +
 .../AgentDetection/CodexScreenProfile.swift   |  11 +
 .../AgentReadCommandHandlerTests.swift        | 121 +++++++++
 .../AgentTranscriptResultReaderTests.swift    | 178 +++++++++++++
 supacodeTests/CLICommandEnvelopeTests.swift   |  19 ++
 supacodeTests/CLICommandRouterTests.swift     |  13 +
 supacodeTests/CLITransportProtocolTests.swift |   4 +-
 supacodeTests/ClaudeScreenProfileTests.swift  |  13 +
 supacodeTests/CodexScreenProfileTests.swift   |  13 +
 supacodeTests/SupacodeAppCLITests.swift       |   5 +
 35 files changed, 1876 insertions(+), 23 deletions(-)
 create mode 100644 ProwlCLI/Commands/AgentsReadCommand.swift
 create mode 100644 ProwlCLITests/AgentReadOutputRendererTests.swift
 create mode 100644 ProwlCLITests/AgentsCommandParsingTests.swift
 create mode 100644 docs-ai/013-prowl-cli/contracts/agents-read.md
 create mode 100644 docs-ai/059-agent-transcript-snapshots/000-plan.md
 create mode 100644 docs-ai/059-agent-transcript-snapshots/001-action.md
 create mode 100644 supacode/CLIService/AgentReadCommandHandler.swift
 create mode 100644 supacode/CLIService/Shared/AgentReadCommandPayload.swift
 create mode 100644 supacode/Infrastructure/AgentDetection/AgentTranscriptResultReader.swift
 create mode 100644 supacodeTests/AgentReadCommandHandlerTests.swift
 create mode 100644 supacodeTests/AgentTranscriptResultReaderTests.swift

diff --git a/ProwlCLI/Commands/AgentsCommand.swift b/ProwlCLI/Commands/AgentsCommand.swift
index 5ccfa532..b4ab3232 100644
--- a/ProwlCLI/Commands/AgentsCommand.swift
+++ b/ProwlCLI/Commands/AgentsCommand.swift
@@ -6,7 +6,8 @@ import ProwlCLIShared
 struct AgentsCommand: ParsableCommand {
   static let configuration = CommandConfiguration(
     commandName: "agents",
-    abstract: "List detected agent panes."
+    abstract: "List detected agent panes.",
+    subcommands: [AgentsReadCommand.self]
   )
 
   @OptionGroup var options: GlobalOptions
diff --git a/ProwlCLI/Commands/AgentsReadCommand.swift b/ProwlCLI/Commands/AgentsReadCommand.swift
new file mode 100644
index 00000000..b7f8cc9f
--- /dev/null
+++ b/ProwlCLI/Commands/AgentsReadCommand.swift
@@ -0,0 +1,60 @@
+import ArgumentParser
+import Foundation
+import ProwlCLIShared
+
+struct AgentsReadCommand: ParsableCommand {
+  static let configuration = CommandConfiguration(
+    commandName: "read",
+    abstract: "Read an immediate semantic snapshot of a Codex or Claude Code agent."
+  )
+
+  @Argument(help: "Target agent pane handle (pN) or pane UUID from prowl agents.")
+  var pane: String
+
+  @Option(
+    name: .long,
+    help: "Maximum result size in bytes (1–4194304, default: 1048576)."
+  )
+  var maxBytes = AgentReadInput.defaultMaxBytes
+
+  @Flag(name: .long, help: "Write only a complete trusted result, with no snapshot header.")
+  var resultOnly = false
+
+  @OptionGroup var options: GlobalOptions
+
+  mutating func run() throws {
+    try CLIExecution.run(command: "agents.read", output: options.outputMode, colorEnabled: options.colorEnabled) {
+      try validateOutputMode()
+      let envelope = CommandEnvelope(
+        output: options.outputMode,
+        command: .agentsRead(AgentReadInput(pane: pane, maxBytes: maxBytes, resultOnly: resultOnly))
+      )
+      try CLIRunner.execute(envelope)
+    }
+  }
+
+  func validate() throws {
+    guard Self.isExplicitPaneTarget(pane) else {
+      throw ValidationError("agents read requires a pane handle (pN) or pane UUID.")
+    }
+    guard (1...AgentReadInput.maximumMaxBytes).contains(maxBytes) else {
+      throw ValidationError("--max-bytes must be between 1 and \(AgentReadInput.maximumMaxBytes).")
+    }
+  }
+
+  func validateOutputMode() throws {
+    guard !(resultOnly && options.json) else {
+      throw ExitError(code: CLIErrorCode.invalidArgument, message: "--result-only cannot be combined with --json.")
+    }
+  }
+
+  private static func isExplicitPaneTarget(_ value: String) -> Bool {
+    if UUID(uuidString: value) != nil { return true }
+    let normalized = value.lowercased()
+    guard normalized.hasPrefix("p") else { return false }
+    let digits = normalized.dropFirst()
+    return !digits.isEmpty
+      && digits.allSatisfy { $0.isASCII && $0.isNumber }
+      && Int(digits).map({ $0 > 0 }) == true
+  }
+}
diff --git a/ProwlCLI/Output/OutputRenderer.swift b/ProwlCLI/Output/OutputRenderer.swift
index ee32c4b8..54a958bf 100644
--- a/ProwlCLI/Output/OutputRenderer.swift
+++ b/ProwlCLI/Output/OutputRenderer.swift
@@ -68,6 +68,14 @@ enum OutputRenderer {
         return
       }
 
+      if response.command == "agents.read",
+         let data = response.data,
+         let payload = try? data.decode(as: AgentReadCommandPayload.self)
+      {
+        renderAgentsRead(payload)
+        return
+      }
+
       if response.command == "focus",
          let data = response.data,
          let payload = try? data.decode(as: FocusCommandPayload.self)
@@ -251,6 +259,49 @@ enum OutputRenderer {
     }.joined(separator: "\n")
   }
 
+  private static func renderAgentsRead(_ payload: AgentReadCommandPayload) {
+    if let data = agentReadResultOnlyData(payload) {
+      FileHandle.standardOutput.write(data)
+      return
+    }
+    print(agentReadSnapshotText(payload))
+  }
+
+  static func agentReadResultOnlyData(_ payload: AgentReadCommandPayload) -> Data? {
+    guard payload.outputMode == .resultOnly, let text = payload.result.text else { return nil }
+    return Data(text.utf8)
+  }
+
+  static func agentReadSnapshotText(_ payload: AgentReadCommandPayload) -> String {
+    var lines = [
+      "Agent: \(payload.agent.type)",
+      "Status: \(payload.agent.status.rawValue)",
+    ]
+    if let reason = payload.agent.detectionReason {
+      lines.append("Reason: \(reason)")
+    }
+    lines.append("Changed: \(payload.agent.lastChangedAt)")
+
+    let result = payload.result
+    if let error = result.error {
+      lines.append("Result: \(result.state.rawValue) (\(error.code))")
+    } else {
+      lines.append("Result: \(result.state.rawValue)")
+    }
+
+    if let blocker = payload.blocker {
+      lines.append("")
+      lines.append("## Blocker")
+      lines.append(blocker.text)
+    }
+    if let text = result.text {
+      lines.append("")
+      lines.append("## Latest result")
+      lines.append(text)
+    }
+    return lines.joined(separator: "\n")
+  }
+
   private static func agentStatusLabel(_ status: AgentsCommandStatus) -> String {
     switch status {
     case .blocked:
diff --git a/ProwlCLI/Transport/SocketTransportClient.swift b/ProwlCLI/Transport/SocketTransportClient.swift
index b685b79b..2f7420f6 100644
--- a/ProwlCLI/Transport/SocketTransportClient.swift
+++ b/ProwlCLI/Transport/SocketTransportClient.swift
@@ -11,6 +11,8 @@ import ProwlCLIShared
 #endif
 
 enum SocketTransportClient {
+  private static let maximumResponseLength = 32 * 1_024 * 1_024
+
   /// Send a command envelope to the Prowl app and receive a response.
   static func send(_ envelope: CommandEnvelope) throws -> Data {
     let socketPath = ProwlSocket.defaultPath
@@ -46,7 +48,7 @@ enum SocketTransportClient {
       UInt32(bigEndian: $0.load(as: UInt32.self))
     }
 
-    guard responseLength > 0, responseLength < 10_000_000 else {
+    guard responseLength > 0, responseLength <= maximumResponseLength else {
       throw ExitError(
         code: CLIErrorCode.transportFailed,
         message: "Invalid response length from app."
diff --git a/ProwlCLITests/AgentReadOutputRendererTests.swift b/ProwlCLITests/AgentReadOutputRendererTests.swift
new file mode 100644
index 00000000..f4191ae1
--- /dev/null
+++ b/ProwlCLITests/AgentReadOutputRendererTests.swift
@@ -0,0 +1,61 @@
+import Foundation
+import ProwlCLIShared
+import XCTest
+
+@testable import prowl
+
+final class AgentReadOutputRendererTests: XCTestCase {
+  func testResultOnlyDataIsVerbatimWithoutSyntheticNewline() {
+    let payload = makePayload(
+      outputMode: .resultOnly,
+      status: .done,
+      blocker: nil,
+      result: AgentReadResult(state: .complete, text: "Final result")
+    )
+
+    XCTAssertEqual(OutputRenderer.agentReadResultOnlyData(payload), Data("Final result".utf8))
+  }
+
+  func testSnapshotTextIncludesStatusAndVerbatimBlocker() {
+    let payload = makePayload(
+      status: .blocked,
+      blocker: "Do you want to proceed?\n❯ 1. Yes\n  2. No",
+      result: AgentReadResult(
+        state: .unavailable,
+        error: AgentReadResultError(code: "SESSION_UNRESOLVED", message: "No trusted session.")
+      )
+    )
+
+    let text = OutputRenderer.agentReadSnapshotText(payload)
+
+    XCTAssertTrue(text.contains("Status: blocked"))
+    XCTAssertTrue(text.contains("Result: unavailable (SESSION_UNRESOLVED)"))
+    XCTAssertTrue(text.contains("## Blocker\nDo you want to proceed?\n❯ 1. Yes\n  2. No"))
+  }
+
+  private func makePayload(
+    outputMode: AgentReadOutputMode = .snapshot,
+    status: AgentsCommandStatus,
+    blocker: String?,
+    result: AgentReadResult
+  ) -> AgentReadCommandPayload {
+    AgentReadCommandPayload(
+      outputMode: outputMode,
+      target: ReadTarget(
+        worktree: ReadTargetWorktree(id: "/tmp/project", name: "main", path: "/tmp/project", rootPath: "/tmp/project", kind: "git"),
+        tab: ReadTargetTab(id: "2FC00CF0-3974-4E1B-BEF8-7A08A8E3B7C0", title: "Agent", selected: true),
+        pane: ReadTargetPane(id: "6E1A2A10-D99F-4E3F-920C-D93AA3C05764", title: "Claude", cwd: nil, focused: false)
+      ),
+      agent: AgentReadAgent(
+        type: "claude",
+        status: status,
+        rawState: status.rawValue,
+        detectionReason: "claude.blockedPrompt",
+        lastChangedAt: "2026-08-11T12:00:00Z",
+        session: nil
+      ),
+      blocker: blocker.map(AgentReadBlocker.init(text:)),
+      result: result
+    )
+  }
+}
diff --git a/ProwlCLITests/AgentsCommandParsingTests.swift b/ProwlCLITests/AgentsCommandParsingTests.swift
new file mode 100644
index 00000000..47a36046
--- /dev/null
+++ b/ProwlCLITests/AgentsCommandParsingTests.swift
@@ -0,0 +1,27 @@
+import XCTest
+
+@testable import prowl
+
+final class AgentsCommandParsingTests: XCTestCase {
+  func testListParsesWithoutSubcommand() throws {
+    _ = try AgentsCommand.parse([])
+  }
+
+  func testReadParsesExplicitPaneAndResultOptions() throws {
+    let command = try AgentsReadCommand.parse(["p7", "--max-bytes", "1024", "--result-only"])
+
+    XCTAssertEqual(command.pane, "p7")
+    XCTAssertEqual(command.maxBytes, 1024)
+    XCTAssertTrue(command.resultOnly)
+  }
+
+  func testReadRequiresPaneHandleOrUUID() {
+    XCTAssertThrowsError(try AgentsReadCommand.parse(["main"]))
+  }
+
+  func testReadRejectsResultOnlyJSONCombination() throws {
+    let command = try AgentsReadCommand.parse(["p7", "--result-only", "--json"])
+
+    XCTAssertThrowsError(try command.validateOutputMode())
+  }
+}
diff --git a/docs-ai/013-prowl-cli/contracts/agents-read.md b/docs-ai/013-prowl-cli/contracts/agents-read.md
new file mode 100644
index 00000000..0c1c3f82
--- /dev/null
+++ b/docs-ai/013-prowl-cli/contracts/agents-read.md
@@ -0,0 +1,130 @@
+# CLI Contract: `prowl agents read`
+
+> Living normative contract of entry 013.
+
+This file defines the immediate agent-snapshot command:
+
+```bash
+prowl agents read <pN|pane-uuid> [--max-bytes <1...4194304>] [--result-only] [--json]
+```
+
+## Scope
+
+V1 supports only a currently active **Codex** or **Claude Code** pane. The target is
+always explicit: use the `pN` shown by text `prowl agents`, or the canonical
+`.data.agents[].pane.id` from JSON `prowl agents`. Worktree/tab selectors, focus-derived
+targets, wait mode, and timeouts are deliberately unsupported.
+
+The command takes one immediate snapshot. It is read-only; respond to a blocker with
+the existing `prowl key --pane …` or `prowl send --pane …` commands. The read and a
+later write are not atomic, so automation should re-read before a consequential action.
+
+## Snapshot semantics
+
+A successful snapshot always reports the currently observed agent status. A transcript
+result is separate evidence and may be unavailable without invalidating the live
+snapshot. This prevents an unresolvable transcript from hiding a useful blocker.
+
+- `status` is Prowl's stabilized `working`, `blocked`, `done`, or `idle` display state.
+- `raw_state` and `detection_reason` are from the fresh active-screen classifier.
+- `blocker.text`, when present, is the current typed-profile interaction region. It
+  preserves the question, visible options, current selection marker, and keyboard hints;
+  it is not a reconstructed or generic terminal viewport.
+- Transcript access requires a fresh `exact` or `high` native session resolution. A
+  `medium` candidate is never read.
+
+## Success payload
+
+```json
+{
+  "ok": true,
+  "command": "agents.read",
+  "schema_version": "prowl.cli.agents.read.v1",
+  "data": {
+    "output_mode": "snapshot",
+    "target": {
+      "worktree": { "id": "/Projects/App", "name": "main", "path": "/Projects/App", "root_path": "/Projects/App", "kind": "git" },
+      "tab": { "id": "2FC00CF0-3974-4E1B-BEF8-7A08A8E3B7C0", "title": "Agent", "selected": true },
+      "pane": { "id": "6E1A2A10-D99F-4E3F-920C-D93AA3C05764", "title": "Claude", "cwd": "/Projects/App", "focused": false }
+    },
+    "agent": {
+      "type": "claude",
+      "status": "blocked",
+      "raw_state": "blocked",
+      "detection_reason": "claude.blockedPrompt",
+      "last_changed_at": "2026-08-11T12:00:00Z"
+    },
+    "blocker": {
+      "text": "Do you want to proceed?\n❯ 1. Yes\n  2. No\nEsc to cancel · Tab to amend"
+    },
+    "result": {
+      "state": "unavailable",
+      "error": {
+        "code": "SESSION_UNRESOLVED",
+        "message": "No exact or high-confidence transcript session is available."
+      }
+    }
+  }
+}
+```
+
+`target` follows the shared resolved-target shape in `read.md`. `agent.session` is
+present only when the transcript result used an eligible session; it contains `id`,
+`confidence` (`exact` or `high`), and `source`, never a local transcript path.
+
+### `result`
+
+| `state` | `text` | Meaning |
+| --- | --- | --- |
+| `complete` | required | A final answer from a complete, attributable native transcript turn. |
+| `pending` | absent | The agent is working or blocked and has no earlier completed turn. |
+| `unavailable` | absent | No exact/high transcript session is available. |
+| `missing` | absent | Idle/done agent has no completed final answer in its trusted transcript. |
+| `incomplete` | absent | The candidate turn is max-token-limited, malformed, unsupported, or not closed. |
+| `too_large` | absent | A complete answer exceeds the requested `max_bytes`. |
+
+Non-`complete` states include `result.error` with the stable code
+`SESSION_UNRESOLVED`, `RESULT_NOT_FOUND`, `RESULT_INCOMPLETE`, or
+`RESULT_TOO_LARGE`, except `pending`, which is ordinary live activity rather than an
+error. Partial text is never returned.
+
+Codex accepts only `event_msg.payload.type == "task_complete"` records with
+`turn_id`, `completed_at`, and `last_agent_message`. Claude Code accepts a
+`system/turn_duration` close record and a bounded same-session parent chain to an
+assistant message containing only text blocks with `end_turn` or `stop_sequence`.
+
+## Text output
+
+Without `--json`, default output is uncoloured Markdown-like text. It always includes
+`Agent`, `Status`, `Reason` when known, `Changed`, and `Result`; it then appends
+`## Blocker` and/or `## Latest result` as applicable.
+
+`--result-only` is text-only and is mutually exclusive with `--json`. It succeeds only
+for `result.state == "complete"`, writes the result bytes exactly to stdout (no heading
+or synthetic trailing newline), and otherwise exits non-zero with the corresponding
+result error code.
+
+## Limits
+
+`--max-bytes` defaults to 1,048,576 and accepts `1...4,194,304`. The limit applies to
+the UTF-8 result text before response encoding. Oversized results are not truncated and
+are never written to an output file. Socket frames permit up to 32 MiB, independently
+of the smaller result limit.
+
+## Error payload and codes
+
+Normal snapshot failures use the standard error envelope with command
+`"agents.read"` and schema `"prowl.cli.agents.read.v1"`.
+
+| Code | Meaning |
+| --- | --- |
+| `INVALID_ARGUMENT` | Invalid pane form, `max_bytes`, or `--result-only --json`. |
+| `TARGET_NOT_FOUND` | The explicit pane handle/UUID no longer resolves. |
+| `AGENT_NOT_FOUND` | The pane no longer hosts an active agent. |
+| `AGENT_UNSUPPORTED` | The active agent is not Codex or Claude Code. |
+| `AGENT_READ_FAILED` | Prowl cannot capture the active screen. |
+| `BLOCKER_UNREADABLE` | A blocked screen was detected but no coherent interaction region could be extracted. |
+| `SESSION_UNRESOLVED` | `--result-only` requested a result without exact/high session evidence. |
+| `RESULT_NOT_FOUND` | `--result-only` requested a result but no completed answer exists. |
+| `RESULT_INCOMPLETE` | `--result-only` requested a non-final or unsupported result. |
+| `RESULT_TOO_LARGE` | `--result-only` requested a result over `max_bytes`. |
diff --git a/docs-ai/013-prowl-cli/contracts/input.md b/docs-ai/013-prowl-cli/contracts/input.md
index ebd83317..502fab35 100644
--- a/docs-ai/013-prowl-cli/contracts/input.md
+++ b/docs-ai/013-prowl-cli/contracts/input.md
@@ -8,12 +8,13 @@ This file defines **input-side** rules for the phase-1 CLI commands:
 
 - `open`
 - `list`
+- `agents` (including `agents read`)
 - `focus`
 - `send`
 - `key`
 - `read`
 
-It complements output contracts under `docs-ai/013-prowl-cli/contracts/{open,list,focus,send,key,read}.md`.
+It complements output contracts under `docs-ai/013-prowl-cli/contracts/{open,list,focus,send,key,read,agents-read}.md`.
 
 ---
 
@@ -38,6 +39,7 @@ prowl <subcommand> [target-selector] [command-args] [output-options]
 
 - `open`
 - `list`
+- `agents`
 - `focus`
 - `send`
 - `key`
@@ -188,6 +190,26 @@ prowl list [--json]
 - `list` MUST NOT accept target selectors in v1 (it is global discovery).
 - Extra positional args: `INVALID_ARGUMENT`.
 
+## 5.2.1 `agents`
+
+### Grammar
+
+```bash
+prowl agents [--json]
+prowl agents read <pN|pane-uuid> [--max-bytes <1...4194304>] [--result-only] [--json]
+```
+
+### Rules
+
+- Plain `agents` remains global roster discovery and accepts no target selector.
+- `agents read` requires exactly one positional pane handle (`pN`) or pane UUID. It
+  intentionally accepts neither worktree/tab/focus targeting nor selector flags.
+- `pN` is the current-process handle from text `agents`; JSON callers use the canonical
+  `.data.agents[].pane.id` UUID.
+- `agents read` is an immediate snapshot: it has no timeout, wait flag, or polling mode.
+- `--max-bytes` defaults to 1,048,576 and is bounded by 1...4,194,304.
+- `--result-only` is text-only and cannot combine with `--json`.
+
 ## 5.3 `focus`
 
 ### Grammar
@@ -280,6 +302,7 @@ These tokens are reserved as first command token:
 - `send`
 - `key`
 - `read`
+- `agents`
 
 If first token matches a reserved command, CLI MUST parse as subcommand unless forced by `--` path form.
 
@@ -302,6 +325,8 @@ struct CommandEnvelope {
 enum Command {
   case open(OpenInput)
   case list(ListInput)
+  case agents(AgentsInput)
+  case agentsRead(AgentReadInput)
   case focus(FocusInput)
   case send(SendInput)
   case key(KeyInput)
@@ -325,6 +350,7 @@ prowl focus --pane 6E1A2A10-D99F-4E3F-920C-D93AA3C05764    # explicit pane
 prowl read --pane p3 --last 200                             # explicit pane handle
 prowl tab close --tab t4 --force                            # explicit tab handle
 prowl focus main                                            # auto-resolve worktree name
+prowl agents read p7 --json                                 # immediate semantic agent snapshot
 prowl send "echo hello"                                     # text to current pane
 prowl send 6E1A2A10-D99F-4E3F-920C-D93AA3C05764 "echo hi"  # target + text
 printf 'git status' | prowl send --worktree Prowl --json
diff --git a/docs-ai/013-prowl-cli/contracts/schema.md b/docs-ai/013-prowl-cli/contracts/schema.md
index c43e9c20..d60a6c83 100644
--- a/docs-ai/013-prowl-cli/contracts/schema.md
+++ b/docs-ai/013-prowl-cli/contracts/schema.md
@@ -12,11 +12,12 @@ This file provides machine-validatable JSON Schema definitions for the v1 CLI ou
 - `send.md`
 - `key.md`
 - `read.md`
+- `agents-read.md`
 
 ## Scope
 
 - JSON Schema dialect: **Draft 2020-12**
-- Commands covered: `open`, `list`, `focus`, `send`, `key`, `read`
+- Commands covered: `open`, `list`, `focus`, `send`, `key`, `read`, `agents.read`
 - Each command schema is represented as `oneOf(success, error)`
 - Shared objects are centralized in `$defs` and reused by command schemas
 
@@ -719,6 +720,113 @@ This file provides machine-validatable JSON Schema definitions for the v1 CLI ou
         { "$ref": "#/$defs/readSuccess" },
         { "$ref": "#/$defs/readError" }
       ]
+    },
+
+    "agentsReadSuccess": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ok", "command", "schema_version", "data"],
+      "properties": {
+        "ok": { "const": true },
+        "command": { "const": "agents.read" },
+        "schema_version": { "const": "prowl.cli.agents.read.v1" },
+        "data": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["output_mode", "target", "agent", "result"],
+          "properties": {
+            "output_mode": { "const": "snapshot" },
+            "target": { "$ref": "#/$defs/resolvedTarget" },
+            "agent": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["type", "status", "raw_state", "last_changed_at"],
+              "properties": {
+                "type": { "type": "string", "enum": ["claude", "codex"] },
+                "status": { "type": "string", "enum": ["blocked", "working", "done", "idle"] },
+                "raw_state": { "type": "string", "enum": ["blocked", "working", "idle", "unknown"] },
+                "detection_reason": { "type": "string" },
+                "last_changed_at": { "type": "string", "format": "date-time" },
+                "session": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["id", "confidence", "source"],
+                  "properties": {
+                    "id": { "type": "string", "minLength": 1 },
+                    "confidence": { "type": "string", "enum": ["exact", "high"] },
+                    "source": { "type": "string", "enum": ["open_file", "transcript_match", "recent_file"] }
+                  }
+                }
+              }
+            },
+            "blocker": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["text"],
+              "properties": {
+                "text": { "type": "string", "minLength": 1 }
+              }
+            },
+            "result": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["state"],
+              "properties": {
+                "state": {
+                  "type": "string",
+                  "enum": ["complete", "pending", "unavailable", "missing", "incomplete", "too_large"]
+                },
+                "text": { "type": "string" },
+                "error": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["code", "message"],
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": ["SESSION_UNRESOLVED", "RESULT_NOT_FOUND", "RESULT_INCOMPLETE", "RESULT_TOO_LARGE"]
+                    },
+                    "message": { "type": "string", "minLength": 1 }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "agentsReadError": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ok", "command", "schema_version", "error"],
+      "properties": {
+        "ok": { "const": false },
+        "command": { "const": "agents.read" },
+        "schema_version": { "const": "prowl.cli.agents.read.v1" },
+        "error": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["code", "message"],
+          "properties": {
+            "code": {
+              "type": "string",
+              "enum": [
+                "APP_NOT_RUNNING", "INVALID_ARGUMENT", "TARGET_NOT_FOUND", "AGENT_NOT_FOUND",
+                "AGENT_UNSUPPORTED", "AGENT_READ_FAILED", "BLOCKER_UNREADABLE", "SESSION_UNRESOLVED",
+                "RESULT_NOT_FOUND", "RESULT_INCOMPLETE", "RESULT_TOO_LARGE"
+              ]
+            },
+            "message": { "type": "string", "minLength": 1 },
+            "details": { "$ref": "#/$defs/errorDetails" }
+          }
+        }
+      }
+    },
+    "agentsReadResponse": {
+      "oneOf": [
+        { "$ref": "#/$defs/agentsReadSuccess" },
+        { "$ref": "#/$defs/agentsReadError" }
+      ]
     }
   }
 }
@@ -732,6 +840,7 @@ This file provides machine-validatable JSON Schema definitions for the v1 CLI ou
 - Validate `prowl send --json` output against `#/$defs/sendResponse`
 - Validate `prowl key --json` output against `#/$defs/keyResponse`
 - Validate `prowl read --json` output against `#/$defs/readResponse`
+- Validate `prowl agents read <pane> --json` output against `#/$defs/agentsReadResponse`
 
 ## Non-goals (v1)
 
diff --git a/docs-ai/059-agent-transcript-snapshots/000-plan.md b/docs-ai/059-agent-transcript-snapshots/000-plan.md
new file mode 100644
index 00000000..54dc7474
--- /dev/null
+++ b/docs-ai/059-agent-transcript-snapshots/000-plan.md
@@ -0,0 +1,158 @@
+# 059 — Agent Transcript Snapshots: Plan
+
+| | |
+| --- | --- |
+| **Status** | Implemented |
+| **Anchor date** | 2026-08-11 |
+| **Primary PRs** | (fill in as they merge) |
+| **Related** | [013 — Prowl CLI](../013-prowl-cli/000-plan.md), [045 — Native agent session detection](../045-native-agent-session-detection/000-plan.md), [issue #473](https://github.com/onevcat/Prowl/issues/473), [relay-tracker #53](https://github.com/onevcat/relay-tracker/issues/53) |
+
+## Background
+
+`prowl agents` identifies the detected coding-agent panes, but its only follow-up is
+`prowl read`, which exposes rendered terminal text rather than the agent's current
+semantic state or a trustworthy final answer. A coordinating agent therefore has to
+screen-scrape a TUI, poll ambiguously, and cannot distinguish a completed result from
+an in-progress transcript fragment.
+
+The command should be a snapshot, not a result waiter. Live state and a transcript
+result are independent evidence: a session-resolution failure must not hide a current
+blocker, while an untrusted session must never yield another agent's answer.
+
+## Goals
+
+- Add immediate, read-only `prowl agents read <pN|pane-uuid>` for Codex and Claude
+  Code, with clear `--help` and direct reuse of handles from `prowl agents`.
+- Return the live detected status on every successful snapshot, and return the raw,
+  actionable current interaction region for a blocked agent.
+- Return a latest final answer only after fresh, exact/high session attribution and a
+  complete native transcript turn; never use the sticky `PaneAgentState.session` as
+  authority and never return partial output.
+- Keep a machine-readable, versioned JSON contract and a concise, uncoloured Markdown
+  text snapshot. Provide `--result-only` for exact raw-result stdout pipelines.
+- Bound results to 1 MiB by default and 4 MiB maximum, and make the socket response
+  ceiling 32 MiB so a permitted payload can travel safely.
+
+### Non-goals
+
+- Do not alter `prowl read` viewport/scrollback semantics or add a terminal-text
+  fallback for this command.
+- Do not add `agents send`/`agents answer`; writes remain `prowl send` and `prowl key`
+  operations and are not atomic with a prior read.
+- Do not extend `AgentRuntimeAdapter`, `AgentSessionProfile`, or
+  `TranscriptFragmentCache`, and do not support transcript results for other detected
+  runtimes in this release.
+- Do not promise cross-runtime elapsed-time or token accounting; existing screen
+  status timestamps remain the only common activity metadata.
+
+## Command and response contract
+
+```bash
+prowl agents
+prowl agents read <pN|pane-uuid> [--max-bytes <1...4194304>] [--result-only] [--json]
+```
+
+`agents read` accepts exactly one explicit pane handle or UUID: no focus-derived target,
+worktree/tab target, `--timeout`, or wait mode. It captures one immediate snapshot.
+`pN` comes directly from text `prowl agents`; JSON callers pass
+`.data.agents[].pane.id`. `--max-bytes` defaults to 1,048,576. `--result-only` is
+text-mode only; it is invalid with `--json` and writes exactly `result.text` without a
+header or synthetic newline.
+
+The default text renderer is a plain Markdown snapshot with `Agent`, `Status`,
+`Reason`, and `Changed` fields, followed by either `Blocker` or `Latest result`. A
+blocker preserves the current active-screen interaction region verbatim enough to show
+the question, numbered choices, selected marker, and keyboard hints; V1 deliberately
+does not invent a lossy structured-choice schema.
+
+The JSON response uses `prowl.cli.agents.read.v1` and carries resolved target metadata,
+agent type/status/raw state/detection reason/last change, the trusted session evidence,
+an optional blocker, and an independent result object. `result.state` is one of:
+
+| State | Meaning |
+| --- | --- |
+| `complete` | Exact/high session attribution and one verified, closed turn; includes `text`. |
+| `pending` | Working agent has no earlier completed result. |
+| `unavailable` | No exact/high current session can be established. |
+| `missing` | Idle/done agent has no completed answer in its trusted transcript. |
+| `incomplete` | A candidate terminal turn is incomplete, malformed, unsupported, or max-token limited. |
+| `too_large` | A complete answer exceeds `max_bytes`; no text is returned. |
+
+A normal snapshot succeeds for every state above: state observation remains useful even
+when transcript evidence is absent. `--result-only` asserts `complete`; every other
+state is a non-zero error using `SESSION_UNRESOLVED`, `RESULT_NOT_FOUND`,
+`RESULT_INCOMPLETE`, or `RESULT_TOO_LARGE`. Snapshot failures remain reserved for an
+invalid/missing pane, no longer-active agent, unsupported runtime, unreadable active
+screen, or unreadable blocker region.
+
+## Design / Approach
+
+1. Extend the nested `AgentsCommand` CLI grammar, shared input/envelope/router models,
+   payload models, error constants, response renderer, and app router composition for a
+   distinct `agents.read` wire command. Resolve only `TargetSelector.pane`, run an
+   on-demand detection pass for the resolved live surface, and preserve the established
+   display status (`working`, `blocked`, `done`, `idle`) alongside the freshly captured
+   raw detection/reason.
+2. Add a small on-demand agent-read capture at the terminal/app boundary. It re-identifies
+   the foreground process, reads `readActiveContentsForCLI()`, records the matched
+   Codex/Claude screen rule, captures the relevant profile launch root and cwd, and
+   asks the session resolver for a fresh resolution. A new resolver entry point bypasses
+   the pid-result cache but may retain safe file/root parsing caches; only `exact` and
+   `high` resolutions are eligible for transcript reading.
+3. Promote the existing Codex and Claude typed screen regions into narrowly scoped
+   blocker extractors. They must be gated by their current blocked rule and return the
+   raw interaction region, not a viewport or reconstructed prose. If no coherent
+   interaction region is available, fail with `BLOCKER_UNREADABLE` rather than claim an
+   actionable blocker.
+4. Add an independent transcript-result reader beside the existing agent-detection
+   infrastructure. It reads a bounded, race-checked JSONL snapshot and has separate
+   Codex and Claude decoders:
+   - Codex accepts only a closed `event_msg.payload.type == "task_complete"` record
+     with a usable `turn_id`, `completed_at`, and `last_agent_message`.
+   - Claude accepts `system/turn_duration` as a close marker, follows its bounded
+     same-session parent chain back through summaries to an assistant message, and
+     accepts text-only content with `end_turn` or `stop_sequence`.
+   The reader makes no partial return: malformed/unclosed records, broken chains,
+   unsupported schema, unfinished tool turns, and `max_tokens` are `incomplete`.
+   A file mutation during reading gets one bounded retry before classification.
+5. Use the reader only after exact/high attribution. For working/blocked snapshots, a
+   missing trusted session yields `unavailable` while preserving status/blocker; a
+   missing prior closed turn is `pending`. Idle/done snapshots retain their status and
+   report `missing`, `unavailable`, `incomplete`, or `too_large` rather than turning a
+   usable observation into a transport failure.
+6. Lift both client and server framed-response validation from 10 MB to 32 MiB, while
+   applying the smaller per-result byte limit before payload encoding. The command never
+   writes overflow output to disk and never truncates a result.
+7. Update the living CLI input/schema contracts, add the `agents read` contract, and
+   update the user manual and bundled `prowl-cli` skill with discovery, blocker,
+   `--result-only`, result-state, and non-atomic write examples.
+
+## Verification
+
+- Add Swift Testing coverage for envelope round trips, router dispatch, parser validation,
+  handler state/error mapping, text rendering, result-only byte-exact output, and the
+  32 MiB transport boundary.
+- Extend the existing Codex/Claude screen-profile fixture tests to assert blocker-region
+  extraction for permission, trust, hook-review, sign-in, and generic confirmation
+  screens, including quoted historical prompts that must not become blockers.
+- Add redacted, version-pinned JSONL fixtures and pure decoder tests for valid terminal
+  turns; earlier-result lookup while working; Claude parent-summary traversal; missing
+  text; malformed/truncated JSONL; broken parent chains; unclosed tool turns;
+  `max_tokens`; oversized answers; and files changed during a read.
+- Add app-composition tests proving the new handler is wired, only pane selectors are
+  accepted, fresh exact/high identity is required before transcript access, and the
+  normal snapshot still preserves a blocked screen when result evidence is unavailable.
+- Run `make check`, focused test classes, `make test`, and `make build-app` after
+  implementation. Record actual commands and outcomes in `001-action.md`.
+
+## Alternatives & decisions
+
+| Alternative | Decision |
+| --- | --- |
+| Wait for a new final result and return old text on timeout | Rejected. The command is immediate snapshot inspection; no default wait or timeout exists. |
+| Treat transcript failure as a top-level failure for every state | Rejected. It hides the useful current status/blocker; result availability is an independent JSON state. |
+| Accept a freshly resolved `medium` session | Rejected. It can silently attribute another concurrent or stale same-cwd conversation. |
+| Return generic terminal viewport text | Rejected. It cannot distinguish agent output from TUI chrome and violates the result completeness guarantee. |
+| Parse structured blocker options | Deferred. Raw typed-profile interaction text is more complete and remains usable with existing `prowl key`/`prowl send`. |
+
+## Amendments
diff --git a/docs-ai/059-agent-transcript-snapshots/001-action.md b/docs-ai/059-agent-transcript-snapshots/001-action.md
new file mode 100644
index 00000000..69ea24b1
--- /dev/null
+++ b/docs-ai/059-agent-transcript-snapshots/001-action.md
@@ -0,0 +1,54 @@
+# 059 — Agent Transcript Snapshots: Action Log
+
+## Timeline
+
+| Date | Change | Ref |
+| --- | --- | --- |
+| 2026-08-11 | Wrote the snapshot-first plan and established the CLI/result-state contract. | This entry |
+| 2026-08-11 | Added `prowl agents read` for explicit Codex/Claude panes, live blocker extraction, fresh transcript attribution, bounded decoders, contracts, and user guidance. | Pending PR |
+
+## Outcome & current state (as of 2026-08-11)
+
+- `ProwlCLI/Commands/AgentsCommand.swift` and
+  `ProwlCLI/Commands/AgentsReadCommand.swift` expose `prowl agents read <pN|uuid>`
+  with immediate-only targeting, a 1–4 MiB result cap, and text-only `--result-only`.
+- `supacode/CLIService/AgentReadCommandHandler.swift` keeps live snapshot evidence
+  independent from transcript result evidence. It returns `complete`, `pending`,
+  `unavailable`, `missing`, `incomplete`, or `too_large` in `AgentReadResult`; only
+  `--result-only` turns non-complete states into command errors.
+- `supacode/App/supacodeApp.swift` performs an on-demand active-screen detection pass,
+  re-identifies the foreground process, and calls the fresh resolver path. It permits
+  only exact/high transcript-backed Codex/Claude sessions.
+- `supacode/Infrastructure/AgentDetection/AgentTranscriptResultReader.swift` reads a
+  bounded, stable JSONL tail with one mutation retry; it decodes closed Codex
+  `task_complete` and Claude `turn_duration` parent-chain results without returning
+  partial text. `AgentSessionResolver.resolveFresh` bypasses only the pid-result cache.
+- `ClaudeScreenProfile` and `CodexScreenProfile` now export the raw blocked interaction
+  region used by the command. `ProwlCLI/Output/OutputRenderer.swift` renders the normal
+  status snapshot or writes result-only bytes directly without a synthetic newline.
+- Shared models, routing, 32 MiB socket-frame guards, normative contracts, the user CLI
+  guide, and the bundled `prowl-cli` skill were updated together.
+
+## Verification
+
+| Command | Observed result |
+| --- | --- |
+| `make check` | Passed: changed-file formatting, strict swift-format lint, and SwiftLint. |
+| `make test` | Passed: xcresult reported 2,313 tests with zero failures. |
+| `make build-cli` | Passed. |
+| `make test-cli-smoke` | Passed. |
+| `make test-cli-integration` | Passed: 68 tests. |
+| `make build-app` | Passed: Debug macOS app build with zero warnings. |
+
+## Deviations from plan
+
+- The decoder tests use compact synthetic JSONL records in
+  `supacodeTests/AgentTranscriptResultReaderTests.swift` instead of committing captured
+  transcript fixture files. They cover the observed Codex 0.146.1 and Claude Code
+  2.1.226 completion shapes without recording user transcript content.
+
+## Open questions
+
+- Native transcript schemas are intentionally narrow. A future Codex or Claude Code
+  release that changes its completion markers must add a captured/redacted regression
+  case before broadening the decoder.
diff --git a/docs-ai/README.md b/docs-ai/README.md
index abee77c0..8c569df9 100644
--- a/docs-ai/README.md
+++ b/docs-ai/README.md
@@ -110,3 +110,4 @@ agent-facing manual for that).
 | 056 | [performance-optimization-2026-08](056-performance-optimization-2026-08/000-plan.md) | 2026-08-01 | August performance review series: exact cached line counts, opt-in Debug TCA logging, and agent screen-scan memoization |
 | 057 | [performance-benchmark-suite](057-performance-benchmark-suite/000-plan.md) | 2026-08-02 | Ratio-assertion benchmarks pinning the #644–#665 hot paths, `make bench` absolute-number reporting, and live measurement wrappers |
 | 058 | [unified-toolbar-layout](058-unified-toolbar-layout/000-plan.md) | 2026-08-07 | Remove redundant branch/title toolbar items and align the Agents + notifications cluster across Normal, Shelf, and Canvas |
+| 059 | [agent-transcript-snapshots](059-agent-transcript-snapshots/000-plan.md) | 2026-08-11 | Immediate Codex/Claude agent snapshots with trustworthy transcript results and actionable blocker text |
diff --git a/docs/components/cli.md b/docs/components/cli.md
index 5c88b15e..d3d8b3cd 100644
--- a/docs/components/cli.md
+++ b/docs/components/cli.md
@@ -4,7 +4,7 @@
 > an agent) can list panes, read their screens, run commands and capture output,
 > send keystrokes, focus, and open/close tabs and panes programmatically.
 
-**Keywords:** prowl cli, command line, prowl list, prowl agents, prowl read, prowl send, prowl key, prowl focus, prowl tab, prowl pane, prowl open, prowl handoff, pane id, agent, automation, json, capture, socket
+**Keywords:** prowl cli, command line, prowl list, prowl agents, prowl agents read, prowl read, prowl send, prowl key, prowl focus, prowl tab, prowl pane, prowl open, prowl handoff, pane id, agent, automation, json, capture, socket
 
 **Related:** [terminal](terminal.md) · [concepts](../concepts.md) · [active-agents](active-agents.md) · [agent-detection](agent-detection.md) · the bundled **`prowl-cli` skill** (`skills/prowl-cli/SKILL.md`)
 
@@ -139,19 +139,49 @@ Each agent contains:
   `medium` session id must not be used for automatic resume without
   additional confirmation.
 
-`prowl agents` is read-only. To jump to or operate on an agent, resolve
-`.data.agents[].pane.id`, then use existing commands:
+`prowl agents` is read-only. Text output is sorted for triage: `Blocked`,
+`Working`, `Done`, then `Idle`. It prints a pane handle such as `p7`; JSON keeps
+the canonical pane UUID. Either form now feeds the semantic snapshot command:
 
 ```bash
+prowl agents read p7
+prowl agents read p7 --json
 pane="$(prowl agents --json | jq -r '.data.agents[] | select(.status=="blocked") | .pane.id' | head -n1)"
-prowl focus --pane "$pane"
-prowl read --pane "$pane" --last 120 --wait-stable
+prowl agents read "$pane" --json
 ```
 
-Text output is sorted for triage: `Blocked`, `Working`, `Done`, then `Idle`.
-It prints a pane handle such as `p7` for each agent; use it as
-`prowl read --pane p7`, not as an `agents` subcommand. Empty output prints
-`No agents found.`.
+### `prowl agents read <pN|pane-uuid>`
+Immediate, read-only semantic snapshot for a currently active **Codex** or
+**Claude Code** pane. It requires an explicit `pN` handle or UUID from `agents`;
+it never guesses from focus, accepts no worktree/tab selector, and has no wait or
+timeout mode.
+
+Default text output always reports current `Status`, classifier `Reason`, last
+state-change time, and a result state. A blocked snapshot includes the raw current
+interaction under `## Blocker`, preserving the question, numbered choices, selected
+row, and Enter/Esc hints. It is the right command for deciding what another agent is
+waiting on; use `prowl key --pane "$pane" ...` to navigate/confirm a menu or
+`prowl send --pane "$pane" ...` for free-form input. Those writes are not atomic with
+the read, so re-read before a consequential choice.
+
+```bash
+prowl agents read p7
+prowl agents read "$pane" --max-bytes 2097152 --json
+prowl agents read p7 --result-only > /tmp/agent-result.txt
+```
+
+JSON is `prowl.cli.agents.read.v1`. `.data.result.state` is independent from live
+agent state: `complete` includes trusted `text`; `pending` means a working/blocked
+agent has not completed a turn; `unavailable`, `missing`, `incomplete`, and
+`too_large` retain a successful live snapshot but include a reason under
+`.data.result.error`. Prowl reads a transcript only after a fresh `exact` or `high`
+session resolution — never a `medium` candidate — and never returns partial text.
+
+`--max-bytes` defaults to 1 MiB and accepts up to 4 MiB. `--result-only` is mutually
+exclusive with `--json`; it writes exactly a complete trusted result to stdout, with
+no heading or added newline. For every other result state it exits non-zero with
+`SESSION_UNRESOLVED`, `RESULT_NOT_FOUND`, `RESULT_INCOMPLETE`, or
+`RESULT_TOO_LARGE`. Empty `agents` roster output remains `No agents found.`.
 
 ### `prowl read [target]`
 Read a pane's content.
@@ -370,6 +400,9 @@ artifacts and terminal excerpts do not appear in `git status`.
 | `SOCKET_PERMISSION_DENIED` | The socket exists but the client cannot connect, usually because a sandbox blocked the Unix socket. Allowlist the socket path, run outside the sandbox, or use matching `PROWL_CLI_SOCKET` values for both app and CLI. |
 | `TARGET_NOT_FOUND` | Selector matched nothing — re-run `list` and pick a UUID or current short handle. |
 | `TARGET_NOT_UNIQUE` | Selector matched several — be more specific (use `--pane`). |
+| `AGENT_NOT_FOUND` / `AGENT_UNSUPPORTED` | `agents read` target no longer hosts an agent, or it is not Codex/Claude Code. Re-run `agents`. |
+| `BLOCKER_UNREADABLE` | A blocked screen was detected but Prowl could not safely extract its current interaction text. Re-run `agents read` or inspect with `read`. |
+| `SESSION_UNRESOLVED` / `RESULT_NOT_FOUND` / `RESULT_INCOMPLETE` / `RESULT_TOO_LARGE` | `agents read --result-only` could not provide one trustworthy complete result. Drop `--result-only` to retain the live snapshot and inspect `.data.result`. |
 | `NO_ACTIVE_PANE` | No pane for focused-target; pass an explicit `--pane`. |
 | `EMPTY_INPUT` | `send` got neither argv nor stdin (or both). |
 | `INVALID_ARGUMENT` | Bad flag/combo (e.g. `--capture --no-wait`) or out-of-range value. |
@@ -404,7 +437,8 @@ prowl pane close --pane "$pane" --json
 
 - Resolve a UUID `pane.id` or current text `pN` before `read`/`send`/`key`/
   `focus`/close — never trust tab titles.
-- Use `prowl agents --json` when you need agent status; use `prowl list --json`
+- Use `prowl agents --json` for discovery, then `prowl agents read <pN|uuid>` for
+  a supported agent's status, blocker, and trustworthy result state; use `prowl list --json`
   when you need all panes, including ordinary shells.
 - `--capture` needs shell integration; otherwise `read --wait-stable` or file
   redirection.
diff --git a/skills/prowl-cli/SKILL.md b/skills/prowl-cli/SKILL.md
index b84e490b..4a2fc6b7 100644
--- a/skills/prowl-cli/SKILL.md
+++ b/skills/prowl-cli/SKILL.md
@@ -24,7 +24,16 @@ When you specifically need active agent status, prefer the agent roster:
 prowl agents --json
 ```
 
-`prowl agents` lists detected agent panes only. It is the right starting point for "which agents are blocked/working/done?", while `prowl list` remains the all-pane inventory, including ordinary shells.
+`prowl agents` lists detected agent panes only. It is the right starting point for "which agents are blocked/working/done?", while `prowl list` remains the all-pane inventory, including ordinary shells. For a currently active Codex or Claude Code agent, follow it with an immediate semantic snapshot:
+
+```bash
+prowl agents read p7 --json
+# Or use the canonical UUID from .data.agents[].pane.id.
+```
+
+`agents read` has no focus fallback, timeout, or wait mode. Its JSON always contains the current
+`.data.agent.status` and independent `.data.result.state`; do not assume `idle`/`done` means a
+trusted result exists unless `result.state == "complete"`.
 
 If your session was launched from a Prowl pane, the focused pane is often you. Treat focused pane IDs as something to identify and avoid unless you intentionally want to operate on yourself.
 
@@ -134,10 +143,24 @@ Key fields by command (see `docs/components/cli.md` for the full contract):
 - `read` → `.data.text`, `.data.line_count`, `.data.truncated`, `.data.mode` (`snapshot`|`last`), `.data.source` (`screen`|`scrollback`|`mixed`|`detection`), plus `.data.stabilized` / `.data.waited_ms` / `.data.samples` when `--wait-stable`.
 - `send` → `.data.input` (source/characters/bytes/trailing_enter_sent); `.data.wait.exit_code` and `.data.wait.duration_ms` when waiting; `.data.capture.text` / `.data.capture.line_count` / `.data.capture.truncated` when `--capture`.
 - `list` / `agents` → `.data.items[]` / `.data.agents[]`, each with `.pane.id`, `.tab.id`, and `.worktree.{id,name,path}`. Agent entries also include `.status`, `.raw_state`, and optional `.detection_reason`; list entries include `.task.status`.
+- `agents read` → `.data.agent` (current status/reason), `.data.blocker.text` when blocked, and `.data.result`. Only `.data.result.state == "complete"` carries `.data.result.text`; `pending`, `unavailable`, `missing`, `incomplete`, and `too_large` deliberately carry no partial text.
 - `tab create` / `open` → `.data.target.{pane,tab,worktree}`.
 
 ## Reading Agent Output
 
+For an active Codex or Claude Code pane, prefer `agents read` over terminal scraping:
+
+```bash
+snapshot="$(prowl agents read p7 --json)"
+printf '%s\n' "$snapshot" | jq -e '.ok == true and .data.agent.status == "blocked"' >/dev/null
+printf '%s\n' "$snapshot" | jq -r '.data.blocker.text // empty'
+```
+
+The command is an immediate snapshot. A blocker is raw current TUI interaction text, so inspect it
+before using `prowl key --pane p7 ...` or `prowl send --pane p7 ...`; read and write are not atomic.
+Use `--result-only` only for a strict pipeline that needs exact raw result bytes and should fail on
+anything except a complete, exact/high-attributed result. It cannot combine with `--json`.
+
 `task.status` is useful for coordination but is not enough to prove the screen finished rendering. `idle` can arrive before a TUI has painted its final response.
 
 Prefer `read --wait-stable` for screen snapshots:
@@ -224,7 +247,7 @@ pane="$(prowl agents --json | jq -r '
   | select(.status == "blocked")
   | .pane.id
 ' | head -n 1)"
-prowl read --pane "$pane" --last 120 --wait-stable --json
+prowl agents read "$pane" --json
 ```
 
 When no agent is blocked, use the same pattern with `working`, `done`, or `idle` depending on the task. The JSON payload also includes `.project.name`, `.project.branch`, `.worktree.path`, `.tab.title`, and `.pane.focused`, so automation can filter by human project label while still targeting the concrete pane.
@@ -263,7 +286,7 @@ Avoid outer double quotes around payloads containing `$PWD`, `$VAR`, backticks,
 
 - Never target by tab title alone; use `pane.id` plus path/cwd.
 - Never omit `--pane` for `send`, `key`, `read`, or `focus` in automation.
-- Use `prowl agents --json` for detected agent status; use `prowl list --json` for all panes and worktree-level `task.status`.
+- Use `prowl agents --json` for discovery and `prowl agents read <pN|uuid> --json` for a supported agent's current semantic snapshot; use `prowl list --json` for all panes and worktree-level `task.status`.
 - `open /path` is a project/path navigation command. It may refocus an existing pane and is not a deterministic create command.
 - Use `tab create` when automation needs a fresh shell, and capture the returned `pane.id` before sending input.
 - Focused pane is not stable; `open` and `focus` change it.
@@ -331,4 +354,4 @@ Write the briefing from your current working knowledge — required sections are
 
 ## Command Set
 
-Current commands: `list`, `agents`, `read`, `send`, `key`, `focus`, `tab create`, `tab close`, `pane close`, `handoff to`, `handoff save`, and `open` (default). There is no CLI `quit`; close temporary tabs or panes with explicit `tab close` / `pane close` targets.
+Current commands: `list`, `agents`, `agents read`, `read`, `send`, `key`, `focus`, `tab create`, `tab close`, `pane close`, `handoff to`, `handoff save`, and `open` (default). There is no CLI `quit`; close temporary tabs or panes with explicit `tab close` / `pane close` targets.
diff --git a/supacode/App/supacodeApp.swift b/supacode/App/supacodeApp.swift
index 1ea911f5..84383cf9 100644
--- a/supacode/App/supacodeApp.swift
+++ b/supacode/App/supacodeApp.swift
@@ -550,6 +550,116 @@ struct SupacodeApp: App {
     }
   }
 
+  private static func makeAgentReadRuntimeSnapshot(
+    pane: String,
+    appStore: StoreOf<AppFeature>,
+    terminalManager: WorktreeTerminalManager
+  ) async -> Result<AgentReadRuntimeSnapshot, AgentReadSnapshotError> {
+    let resolver = makeTargetResolver(appStore: appStore, terminalManager: terminalManager)
+    let resolved: ResolvedTarget
+    switch resolver.resolve(.pane(pane)) {
+    case .success(let target):
+      resolved = target
+    case .failure(let error):
+      let message =
+        switch error {
+        case .notFound(let message), .notUnique(let message): message
+        }
+      return .failure(.targetNotFound(message))
+    }
+
+    guard let state = terminalManager.stateIfExists(for: resolved.worktreeID),
+      let surface = state.surfaceView(for: resolved.paneID),
+      let tabID = state.tabId(containing: resolved.paneID)
+    else {
+      return .failure(.targetNotFound("Pane '\(pane)' is no longer available."))
+    }
+
+    _ = await state.detectAgentState(for: surface, tabId: tabID)
+    guard let agentState = state.surfaceAgentStates[resolved.paneID],
+      let detectedAgent = agentState.detectedAgent
+    else {
+      return .failure(.agentNotFound("Pane '\(pane)' does not host an active agent."))
+    }
+    guard detectedAgent == .codex || detectedAgent == .claude else {
+      return .failure(.unsupportedAgent("Agent '\(detectedAgent.rawValue)' is not supported by agents read."))
+    }
+    guard let activeText = surface.readActiveContentsForCLI() else {
+      return .failure(.activeScreenUnreadable)
+    }
+
+    let detection = detectedAgent.detectScreen(in: activeText)
+    let canonicalScreen = AgentScreenSnapshot(canonicalText: agentDetectionRecentText(activeText))
+    let blockerText: String? =
+      switch detectedAgent {
+      case .codex: CodexScreenProfile.blockerText(in: canonicalScreen)
+      case .claude: ClaudeScreenProfile.blockerText(in: canonicalScreen)
+      default: nil
+      }
+    if detection.state == .blocked, blockerText == nil {
+      return .failure(.blockerUnreadable)
+    }
+
+    let job = await AgentProcessProbe.shared.foregroundJob(
+      processGroupID: surface.bridge.foregroundProcessGroupID(),
+      childPID: surface.bridge.childPID()
+    )
+    guard let identified = job.flatMap(identifyAgentInJob), identified.agent == detectedAgent else {
+      return .failure(.agentNotFound("Pane '\(pane)' no longer hosts the selected agent."))
+    }
+
+    let freshResolution = await AgentSessionResolver.shared.resolveFresh(
+      identified: identified,
+      workingDirectory: state.activeAgentWorkingDirectory(surfaceID: resolved.paneID),
+      activeText: activeText,
+      configRoot: state.launchProfilesBySurface[resolved.paneID]?.configRoot(forDetected: detectedAgent)
+    )
+    let transcriptSession = freshResolution.session.flatMap { session -> AgentSession? in
+      guard session.confidence == .exact || session.confidence == .high,
+        session.transcriptPath != nil
+      else {
+        return nil
+      }
+      return session
+    }
+
+    let formatter = ISO8601DateFormatter()
+    formatter.formatOptions = [.withInternetDateTime]
+    formatter.timeZone = TimeZone(secondsFromGMT: 0)
+    let status = AgentsCommandStatus(rawValue: agentState.displayState.rawValue) ?? .idle
+    return .success(
+      AgentReadRuntimeSnapshot(
+        target: agentReadTarget(from: resolved),
+        agent: detectedAgent,
+        status: status,
+        rawState: detection.state.rawValue,
+        detectionReason: detection.reason.identifier,
+        lastChangedAt: formatter.string(from: agentState.lastChangedAt),
+        blockerText: blockerText,
+        transcriptSession: transcriptSession
+      )
+    )
+  }
+
+  private static func agentReadTarget(from target: ResolvedTarget) -> ReadTarget {
+    ReadTarget(
+      worktree: ReadTargetWorktree(
+        id: target.worktreeID,
+        name: target.worktreeName,
+        path: target.worktreePath,
+        rootPath: target.worktreeRootPath,
+        kind: target.worktreeKind.rawValue
+      ),
+      tab: ReadTargetTab(id: target.tabID.uuidString, title: target.tabTitle, selected: target.tabSelected),
+      pane: ReadTargetPane(
+        id: target.paneID.uuidString,
+        title: target.paneTitle,
+        cwd: target.paneCWD,
+        focused: target.paneFocused
+      )
+    )
+  }
+
   // swiftlint:disable:next function_body_length
   static func makeCLICommandRouter(
     appStore: StoreOf<AppFeature>,
@@ -579,6 +689,20 @@ struct SupacodeApp: App {
         screenDetectionsBySurfaceID: screenDetectionsBySurfaceID
       )
     }
+    let agentReadHandler = AgentReadCommandHandler(
+      snapshotProvider: { pane in
+        await Self.makeAgentReadRuntimeSnapshot(
+          pane: pane,
+          appStore: appStore,
+          terminalManager: terminalManager
+        )
+      },
+      resultProvider: { agent, path, maxBytes in
+        await Task.detached(priority: .userInitiated) {
+          AgentTranscriptResultReader.read(agent: agent, at: path, maxBytes: maxBytes)
+        }.value
+      }
+    )
     let sendHandler = SendCommandHandler(
       resolveProvider: { selector in
         let resolver = TargetResolver {
@@ -819,6 +943,7 @@ struct SupacodeApp: App {
       openHandler: openHandler,
       listHandler: listHandler,
       agentsHandler: agentsHandler,
+      agentsReadHandler: agentReadHandler,
       focusHandler: focusHandler,
       sendHandler: sendHandler,
       keyHandler: keyHandler,
diff --git a/supacode/CLIService/AgentReadCommandHandler.swift b/supacode/CLIService/AgentReadCommandHandler.swift
new file mode 100644
index 00000000..27ac0d82
--- /dev/null
+++ b/supacode/CLIService/AgentReadCommandHandler.swift
@@ -0,0 +1,168 @@
+import Foundation
+
+nonisolated struct AgentReadRuntimeSnapshot: Sendable {
+  let target: ReadTarget
+  let agent: DetectedAgent
+  let status: AgentsCommandStatus
+  let rawState: String
+  let detectionReason: String?
+  let lastChangedAt: String
+  let blockerText: String?
+  /// Only an exact/high, transcript-backed fresh resolution belongs here.
+  let transcriptSession: AgentSession?
+}
+
+nonisolated enum AgentReadSnapshotError: Error, Sendable {
+  case targetNotFound(String)
+  case agentNotFound(String)
+  case unsupportedAgent(String)
+  case activeScreenUnreadable
+  case blockerUnreadable
+}
+
+@MainActor
+final class AgentReadCommandHandler: CommandHandler {
+  typealias SnapshotProvider = @MainActor (String) async -> Result<AgentReadRuntimeSnapshot, AgentReadSnapshotError>
+  typealias ResultProvider = @Sendable (DetectedAgent, URL, Int) async -> AgentTranscriptResult
+
+  private let snapshotProvider: SnapshotProvider
+  private let resultProvider: ResultProvider
+
+  init(
+    snapshotProvider: @escaping SnapshotProvider,
+    resultProvider: @escaping ResultProvider
+  ) {
+    self.snapshotProvider = snapshotProvider
+    self.resultProvider = resultProvider
+  }
+
+  func handle(envelope: CommandEnvelope) async -> CommandResponse {
+    guard case .agentsRead(let input) = envelope.command else {
+      return errorResponse(code: CLIErrorCode.agentReadFailed, message: "Invalid command.")
+    }
+    guard (1...AgentReadInput.maximumMaxBytes).contains(input.maxBytes) else {
+      return errorResponse(
+        code: CLIErrorCode.invalidArgument,
+        message: "--max-bytes must be between 1 and \(AgentReadInput.maximumMaxBytes)."
+      )
+    }
+
+    let snapshot: AgentReadRuntimeSnapshot
+    switch await snapshotProvider(input.pane) {
+    case .success(let resolved):
+      snapshot = resolved
+    case .failure(let error):
+      return mapSnapshotError(error)
+    }
+
+    let result = await makeResult(from: snapshot, maxBytes: input.maxBytes)
+    if input.resultOnly, result.state != .complete {
+      let error = result.error ?? error(for: result.state)
+      return errorResponse(code: error.code, message: error.message)
+    }
+
+    let payload = AgentReadCommandPayload(
+      outputMode: input.resultOnly ? .resultOnly : .snapshot,
+      target: snapshot.target,
+      agent: AgentReadAgent(
+        type: snapshot.agent.rawValue,
+        status: snapshot.status,
+        rawState: snapshot.rawState,
+        detectionReason: snapshot.detectionReason,
+        lastChangedAt: snapshot.lastChangedAt,
+        session: snapshot.transcriptSession.map {
+          AgentReadSession(id: $0.id, confidence: $0.confidence.rawValue, source: $0.source.rawValue)
+        }
+      ),
+      blocker: snapshot.blockerText.map(AgentReadBlocker.init(text:)),
+      result: result
+    )
+
+    do {
+      return try CommandResponse(
+        ok: true,
+        command: "agents.read",
+        schemaVersion: "prowl.cli.agents.read.v1",
+        data: RawJSON(encoding: payload)
+      )
+    } catch {
+      return errorResponse(code: CLIErrorCode.agentReadFailed, message: "Failed to encode agent snapshot.")
+    }
+  }
+
+  private func makeResult(from snapshot: AgentReadRuntimeSnapshot, maxBytes: Int) async -> AgentReadResult {
+    guard let session = snapshot.transcriptSession, let path = session.transcriptPath else {
+      return failedResult(.unavailable)
+    }
+
+    let transcript = await resultProvider(snapshot.agent, path, maxBytes)
+    switch transcript.state {
+    case .complete:
+      guard let text = transcript.text else { return failedResult(.incomplete) }
+      return AgentReadResult(state: .complete, text: text)
+    case .missing:
+      switch snapshot.status {
+      case .working, .blocked:
+        return AgentReadResult(state: .pending)
+      case .idle, .done:
+        return failedResult(.missing)
+      }
+    case .incomplete:
+      return failedResult(.incomplete)
+    case .tooLarge:
+      return failedResult(.tooLarge)
+    }
+  }
+
+  private func failedResult(_ state: AgentReadResultState) -> AgentReadResult {
+    AgentReadResult(state: state, error: error(for: state))
+  }
+
+  private func error(for state: AgentReadResultState) -> AgentReadResultError {
+    switch state {
+    case .complete:
+      AgentReadResultError(code: CLIErrorCode.agentReadFailed, message: "Missing complete agent result.")
+    case .pending, .missing:
+      AgentReadResultError(code: CLIErrorCode.resultNotFound, message: "No completed agent result is available.")
+    case .unavailable:
+      AgentReadResultError(
+        code: CLIErrorCode.sessionUnresolved,
+        message: "No exact or high-confidence transcript session is available."
+      )
+    case .incomplete:
+      AgentReadResultError(
+        code: CLIErrorCode.resultIncomplete,
+        message: "The latest agent result is incomplete or unsupported."
+      )
+    case .tooLarge:
+      AgentReadResultError(
+        code: CLIErrorCode.resultTooLarge,
+        message: "The latest agent result exceeds --max-bytes."
+      )
+    }
+  }
+
+  private func mapSnapshotError(_ error: AgentReadSnapshotError) -> CommandResponse {
+    switch error {
+    case .targetNotFound(let message):
+      errorResponse(code: CLIErrorCode.targetNotFound, message: message)
+    case .agentNotFound(let message):
+      errorResponse(code: CLIErrorCode.agentNotFound, message: message)
+    case .unsupportedAgent(let message):
+      errorResponse(code: CLIErrorCode.agentUnsupported, message: message)
+    case .activeScreenUnreadable:
+      errorResponse(code: CLIErrorCode.agentReadFailed, message: "Failed to read the agent's active screen.")
+    case .blockerUnreadable:
+      errorResponse(code: CLIErrorCode.blockerUnreadable, message: "Failed to read the current agent blocker.")
+    }
+  }
+
+  private func errorResponse(code: String, message: String) -> CommandResponse {
+    CommandResponse(
+      ok: false,
+      command: "agents.read",
+      schemaVersion: "prowl.cli.agents.read.v1",
+      error: CommandError(code: code, message: message)
+    )
+  }
+}
diff --git a/supacode/CLIService/CLICommandRouter.swift b/supacode/CLIService/CLICommandRouter.swift
index e4698e0f..18dd3350 100644
--- a/supacode/CLIService/CLICommandRouter.swift
+++ b/supacode/CLIService/CLICommandRouter.swift
@@ -8,6 +8,7 @@ final class CLICommandRouter {
   private let openHandler: any CommandHandler
   private let listHandler: any CommandHandler
   private let agentsHandler: any CommandHandler
+  private let agentsReadHandler: any CommandHandler
   private let focusHandler: any CommandHandler
   private let sendHandler: any CommandHandler
   private let keyHandler: any CommandHandler
@@ -20,6 +21,7 @@ final class CLICommandRouter {
     openHandler: any CommandHandler = StubCommandHandler(command: "open"),
     listHandler: any CommandHandler = StubCommandHandler(command: "list"),
     agentsHandler: any CommandHandler = StubCommandHandler(command: "agents"),
+    agentsReadHandler: any CommandHandler = StubCommandHandler(command: "agents.read"),
     focusHandler: any CommandHandler = StubCommandHandler(command: "focus"),
     sendHandler: any CommandHandler = StubCommandHandler(command: "send"),
     keyHandler: any CommandHandler = StubCommandHandler(command: "key"),
@@ -31,6 +33,7 @@ final class CLICommandRouter {
     self.openHandler = openHandler
     self.listHandler = listHandler
     self.agentsHandler = agentsHandler
+    self.agentsReadHandler = agentsReadHandler
     self.focusHandler = focusHandler
     self.sendHandler = sendHandler
     self.keyHandler = keyHandler
@@ -49,6 +52,7 @@ final class CLICommandRouter {
     case .open: handler = openHandler
     case .list: handler = listHandler
     case .agents: handler = agentsHandler
+    case .agentsRead: handler = agentsReadHandler
     case .focus: handler = focusHandler
     case .send: handler = sendHandler
     case .key: handler = keyHandler
diff --git a/supacode/CLIService/CLISocketServer.swift b/supacode/CLIService/CLISocketServer.swift
index b2721cbe..b46078d7 100644
--- a/supacode/CLIService/CLISocketServer.swift
+++ b/supacode/CLIService/CLISocketServer.swift
@@ -11,6 +11,8 @@ import Foundation
 
 @MainActor
 final class CLISocketServer {
+  private static let maximumFrameLength = 32 * 1_024 * 1_024
+
   private let router: CLICommandRouter
   private let socketPath: String
   private let lockPath: String
@@ -199,7 +201,7 @@ final class CLISocketServer {
       let length = lengthData.withUnsafeBytes {
         UInt32(bigEndian: $0.load(as: UInt32.self))
       }
-      guard length > 0, length < 10_000_000 else { return }
+      guard length > 0, length <= Self.maximumFrameLength else { return }
 
       let requestData = try Self.fdRead(fildes: clientFD, count: Int(length))
 
@@ -215,6 +217,7 @@ final class CLISocketServer {
       let encoder = JSONEncoder()
       encoder.outputFormatting = [.sortedKeys]
       let responseData = try encoder.encode(response)
+      guard responseData.count > 0, responseData.count <= Self.maximumFrameLength else { return }
 
       var responseLength = UInt32(responseData.count).bigEndian
       try withUnsafeBytes(of: &responseLength) { try Self.fdWrite(fildes: clientFD, buffer: $0) }
diff --git a/supacode/CLIService/Shared/AgentReadCommandPayload.swift b/supacode/CLIService/Shared/AgentReadCommandPayload.swift
new file mode 100644
index 00000000..c45d649b
--- /dev/null
+++ b/supacode/CLIService/Shared/AgentReadCommandPayload.swift
@@ -0,0 +1,121 @@
+import Foundation
+
+public struct AgentReadCommandPayload: Codable, Equatable, Sendable {
+  public let outputMode: AgentReadOutputMode
+  public let target: ReadTarget
+  public let agent: AgentReadAgent
+  public let blocker: AgentReadBlocker?
+  public let result: AgentReadResult
+
+  enum CodingKeys: String, CodingKey {
+    case outputMode = "output_mode"
+    case target
+    case agent
+    case blocker
+    case result
+  }
+
+  public init(
+    outputMode: AgentReadOutputMode,
+    target: ReadTarget,
+    agent: AgentReadAgent,
+    blocker: AgentReadBlocker?,
+    result: AgentReadResult
+  ) {
+    self.outputMode = outputMode
+    self.target = target
+    self.agent = agent
+    self.blocker = blocker
+    self.result = result
+  }
+}
+
+public enum AgentReadOutputMode: String, Codable, Equatable, Sendable {
+  case snapshot
+  case resultOnly = "result_only"
+}
+
+public struct AgentReadAgent: Codable, Equatable, Sendable {
+  public let type: String
+  public let status: AgentsCommandStatus
+  public let rawState: String
+  public let detectionReason: String?
+  public let lastChangedAt: String
+  public let session: AgentReadSession?
+
+  enum CodingKeys: String, CodingKey {
+    case type
+    case status
+    case rawState = "raw_state"
+    case detectionReason = "detection_reason"
+    case lastChangedAt = "last_changed_at"
+    case session
+  }
+
+  public init(
+    type: String,
+    status: AgentsCommandStatus,
+    rawState: String,
+    detectionReason: String?,
+    lastChangedAt: String,
+    session: AgentReadSession?
+  ) {
+    self.type = type
+    self.status = status
+    self.rawState = rawState
+    self.detectionReason = detectionReason
+    self.lastChangedAt = lastChangedAt
+    self.session = session
+  }
+}
+
+public struct AgentReadSession: Codable, Equatable, Sendable {
+  public let id: String
+  public let confidence: String
+  public let source: String
+
+  public init(id: String, confidence: String, source: String) {
+    self.id = id
+    self.confidence = confidence
+    self.source = source
+  }
+}
+
+public struct AgentReadBlocker: Codable, Equatable, Sendable {
+  public let text: String
+
+  public init(text: String) {
+    self.text = text
+  }
+}
+
+public struct AgentReadResult: Codable, Equatable, Sendable {
+  public let state: AgentReadResultState
+  public let text: String?
+  public let error: AgentReadResultError?
+
+  public init(state: AgentReadResultState, text: String? = nil, error: AgentReadResultError? = nil) {
+    self.state = state
+    self.text = text
+    self.error = error
+  }
+}
+
+public enum AgentReadResultState: String, Codable, Equatable, Sendable {
+  case complete
+  case pending
+  case unavailable
+  case missing
+  case incomplete
+  case tooLarge = "too_large"
+}
+
+public struct AgentReadResultError: Codable, Equatable, Sendable {
+  public let code: String
+  public let message: String
+
+  public init(code: String, message: String) {
+    self.code = code
+    self.message = message
+  }
+}
diff --git a/supacode/CLIService/Shared/AgentsCommandPayload.swift b/supacode/CLIService/Shared/AgentsCommandPayload.swift
index a1038874..b3397f24 100644
--- a/supacode/CLIService/Shared/AgentsCommandPayload.swift
+++ b/supacode/CLIService/Shared/AgentsCommandPayload.swift
@@ -82,7 +82,7 @@ public struct AgentsCommandSession: Codable, Equatable {
   }
 }
 
-public enum AgentsCommandStatus: String, Codable, Equatable {
+public enum AgentsCommandStatus: String, Codable, Equatable, Sendable {
   case blocked
   case working
   case done
diff --git a/supacode/CLIService/Shared/CommandEnvelope.swift b/supacode/CLIService/Shared/CommandEnvelope.swift
index c252d0c3..ad0f07c9 100644
--- a/supacode/CLIService/Shared/CommandEnvelope.swift
+++ b/supacode/CLIService/Shared/CommandEnvelope.swift
@@ -17,6 +17,7 @@ public enum Command: Codable, Sendable {
   case open(OpenInput)
   case list(ListInput)
   case agents(AgentsInput)
+  case agentsRead(AgentReadInput)
   case focus(FocusInput)
   case send(SendInput)
   case key(KeyInput)
@@ -30,6 +31,7 @@ public enum Command: Codable, Sendable {
     case .open: "open"
     case .list: "list"
     case .agents: "agents"
+    case .agentsRead: "agents.read"
     case .focus: "focus"
     case .send: "send"
     case .key: "key"
diff --git a/supacode/CLIService/Shared/ErrorCodes.swift b/supacode/CLIService/Shared/ErrorCodes.swift
index 1dbc5a6b..6171d4b0 100644
--- a/supacode/CLIService/Shared/ErrorCodes.swift
+++ b/supacode/CLIService/Shared/ErrorCodes.swift
@@ -22,6 +22,14 @@ public enum CLIErrorCode {
 
   // Agents
   public static let agentsFailed = "AGENTS_FAILED"
+  public static let agentNotFound = "AGENT_NOT_FOUND"
+  public static let agentUnsupported = "AGENT_UNSUPPORTED"
+  public static let agentReadFailed = "AGENT_READ_FAILED"
+  public static let blockerUnreadable = "BLOCKER_UNREADABLE"
+  public static let sessionUnresolved = "SESSION_UNRESOLVED"
+  public static let resultNotFound = "RESULT_NOT_FOUND"
+  public static let resultIncomplete = "RESULT_INCOMPLETE"
+  public static let resultTooLarge = "RESULT_TOO_LARGE"
 
   // Focus
   public static let focusFailed = "FOCUS_FAILED"
diff --git a/supacode/CLIService/Shared/InputModels.swift b/supacode/CLIService/Shared/InputModels.swift
index 9adff204..b69457cf 100644
--- a/supacode/CLIService/Shared/InputModels.swift
+++ b/supacode/CLIService/Shared/InputModels.swift
@@ -30,6 +30,27 @@ public struct AgentsInput: Codable, Sendable {
   public init() {}
 }
 
+public struct AgentReadInput: Codable, Sendable {
+  public static let defaultMaxBytes = 1_024 * 1_024
+  public static let maximumMaxBytes = 4 * 1_024 * 1_024
+
+  public let pane: String
+  public let maxBytes: Int
+  public let resultOnly: Bool
+
+  enum CodingKeys: String, CodingKey {
+    case pane
+    case maxBytes = "max_bytes"
+    case resultOnly = "result_only"
+  }
+
+  public init(pane: String, maxBytes: Int = Self.defaultMaxBytes, resultOnly: Bool = false) {
+    self.pane = pane
+    self.maxBytes = maxBytes
+    self.resultOnly = resultOnly
+  }
+}
+
 public struct FocusInput: Codable, Sendable {
   public let selector: TargetSelector
 
diff --git a/supacode/Infrastructure/AgentDetection/AgentSessionResolver.swift b/supacode/Infrastructure/AgentDetection/AgentSessionResolver.swift
index 6fae15af..bdc65749 100644
--- a/supacode/Infrastructure/AgentDetection/AgentSessionResolver.swift
+++ b/supacode/Infrastructure/AgentDetection/AgentSessionResolver.swift
@@ -221,6 +221,14 @@ actor AgentSessionResolver {
     let now: Date
   }
 
+  private struct ResolveInput {
+    let identified: IdentifiedAgentProcess
+    let workingDirectory: URL?
+    let activeText: String
+    let configRoot: URL?
+    let now: Date
+  }
+
   /// Unresolved lookups retry quickly while the narrow scan stays cheap, then
   /// back off exponentially while the pane stays ambiguous; wide fallback
   /// scans (full history trees) start at the slow end. 15 s cap keeps a
@@ -311,13 +319,53 @@ actor AgentSessionResolver {
     configRoot: URL? = nil,
     now: Date = Date()
   ) -> AgentSessionResolution {
+    resolve(
+      ResolveInput(
+        identified: identified,
+        workingDirectory: workingDirectory,
+        activeText: activeText,
+        configRoot: configRoot,
+        now: now
+      ),
+      bypassResultCache: false
+    )
+  }
+
+  /// Recomputes session attribution from current process/screen evidence instead
+  /// of replaying a `PaneAgentState` or pid-result cache entry. File/root parsing
+  /// caches remain valid optimizations because they are keyed by file identity.
+  func resolveFresh(
+    identified: IdentifiedAgentProcess,
+    workingDirectory: URL?,
+    activeText: String,
+    configRoot: URL? = nil,
+    now: Date = Date()
+  ) -> AgentSessionResolution {
+    resolve(
+      ResolveInput(
+        identified: identified,
+        workingDirectory: workingDirectory,
+        activeText: activeText,
+        configRoot: configRoot,
+        now: now
+      ),
+      bypassResultCache: true
+    )
+  }
+
+  private func resolve(_ input: ResolveInput, bypassResultCache: Bool) -> AgentSessionResolution {
+    let identified = input.identified
+    let workingDirectory = input.workingDirectory
+    let activeText = input.activeText
+    let configRoot = input.configRoot
+    let now = input.now
     let process = identified.process
     guard let startedAt = ProcessDetection.processStartDate(pid: process.pid) else {
       return AgentSessionResolution(session: nil, isFresh: true)
     }
     let key = CacheKey(pid: process.pid, startedAt: startedAt)
     let cached = cache[key]
-    if let cached {
+    if !bypassResultCache, let cached {
       let lifetime = Self.cacheLifetime(
         hasSession: cached.session != nil,
         usedWideScan: cached.usedWideScan,
diff --git a/supacode/Infrastructure/AgentDetection/AgentTranscriptResultReader.swift b/supacode/Infrastructure/AgentDetection/AgentTranscriptResultReader.swift
new file mode 100644
index 00000000..77e13c71
--- /dev/null
+++ b/supacode/Infrastructure/AgentDetection/AgentTranscriptResultReader.swift
@@ -0,0 +1,233 @@
+import Foundation
+
+nonisolated enum AgentTranscriptResultState: Equatable, Sendable {
+  case complete
+  case missing
+  case incomplete
+  case tooLarge
+}
+
+nonisolated struct AgentTranscriptResult: Equatable, Sendable {
+  let state: AgentTranscriptResultState
+  let text: String?
+
+  static func complete(_ text: String) -> Self {
+    Self(state: .complete, text: text)
+  }
+
+  static func failure(_ state: AgentTranscriptResultState) -> Self {
+    Self(state: state, text: nil)
+  }
+}
+
+/// Reads a closed, final agent response from a single native transcript snapshot.
+///
+/// This intentionally accepts only the narrow, observed Codex and Claude Code
+/// completion schemas. Unknown or partially-written JSONL is not a weaker form of
+/// success: callers must preserve the live snapshot while withholding transcript text.
+nonisolated enum AgentTranscriptResultReader {
+  /// Reads a stable file snapshot. A concurrent append gets one immediate retry;
+  /// accepting a moving file would make a JSONL boundary ambiguous.
+  static func read(agent: DetectedAgent, at url: URL, maxBytes: Int) -> AgentTranscriptResult {
+    let fileManager = FileManager.default
+    for _ in 0..<2 {
+      guard let before = attributes(at: url, fileManager: fileManager),
+        let tail = tailData(at: url, byteLimit: tailByteLimit(for: maxBytes)),
+        let after = attributes(at: url, fileManager: fileManager),
+        before.size == after.size,
+        before.modifiedAt == after.modifiedAt,
+        let jsonl = completeJSONL(tail)
+      else {
+        continue
+      }
+      return decode(agent: agent, jsonl: jsonl, maxBytes: maxBytes)
+    }
+    return .failure(.incomplete)
+  }
+
+  static func decode(
+    agent: DetectedAgent,
+    jsonl: String,
+    maxBytes: Int
+  ) -> AgentTranscriptResult {
+    guard maxBytes > 0 else { return .failure(.tooLarge) }
+    guard jsonl.isEmpty || jsonl.hasSuffix("\n") else { return .failure(.incomplete) }
+    let records = decodeRecords(jsonl)
+    guard let records else { return .failure(.incomplete) }
+
+    switch agent {
+    case .codex:
+      return decodeCodex(records: records, maxBytes: maxBytes)
+    case .claude:
+      return decodeClaude(records: records, maxBytes: maxBytes)
+    default:
+      return .failure(.incomplete)
+    }
+  }
+
+  private struct TranscriptTail {
+    let data: Data
+    let startsMidRecord: Bool
+  }
+
+  /// A JSON string can be larger than its UTF-8 result after escaping. Three
+  /// times the requested result plus 1 MiB leaves room for one maximal latest
+  /// record and its close markers, while the 16 MiB cap keeps giant histories
+  /// out of the process even when callers request the 4 MiB result maximum.
+  private static func tailByteLimit(for maxBytes: Int) -> UInt64 {
+    let scaled = max(0, maxBytes) * 3 + 1_024 * 1_024
+    return UInt64(min(16 * 1_024 * 1_024, max(1_024 * 1_024, scaled)))
+  }
+
+  private static func tailData(at url: URL, byteLimit: UInt64) -> TranscriptTail? {
+    guard let handle = try? FileHandle(forReadingFrom: url) else { return nil }
+    defer { try? handle.close() }
+    guard let size = try? handle.seekToEnd() else { return nil }
+    let offset = size > byteLimit ? size - byteLimit : 0
+    do {
+      try handle.seek(toOffset: offset)
+      guard let data = try handle.readToEnd() else { return nil }
+      return TranscriptTail(data: data, startsMidRecord: offset > 0)
+    } catch {
+      return nil
+    }
+  }
+
+  private static func completeJSONL(_ tail: TranscriptTail) -> String? {
+    let data: Data
+    if tail.startsMidRecord {
+      guard let firstNewline = tail.data.firstIndex(of: 0x0A) else { return nil }
+      data = tail.data.suffix(from: tail.data.index(after: firstNewline))
+    } else {
+      data = tail.data
+    }
+    return String(data: data, encoding: .utf8)
+  }
+
+  private static func attributes(
+    at url: URL,
+    fileManager: FileManager
+  ) -> (size: UInt64, modifiedAt: Date)? {
+    guard let attributes = try? fileManager.attributesOfItem(atPath: url.path),
+      let size = attributes[.size] as? NSNumber,
+      let modifiedAt = attributes[.modificationDate] as? Date
+    else {
+      return nil
+    }
+    return (size.uint64Value, modifiedAt)
+  }
+
+  private static func decodeRecords(_ jsonl: String) -> [[String: Any]]? {
+    var records: [[String: Any]] = []
+    for line in jsonl.split(separator: "\n", omittingEmptySubsequences: true) {
+      guard let data = line.data(using: .utf8),
+        let object = try? JSONSerialization.jsonObject(with: data) as? [String: Any]
+      else {
+        return nil
+      }
+      records.append(object)
+    }
+    return records
+  }
+
+  private static func decodeCodex(records: [[String: Any]], maxBytes: Int) -> AgentTranscriptResult {
+    guard let payload = records.reversed().compactMap(codexCompletionPayload).first else {
+      return .failure(.missing)
+    }
+    guard !containsMaxTokens(payload),
+      payload["turn_id"] is String,
+      payload["completed_at"] is String,
+      let text = payload["last_agent_message"] as? String
+    else {
+      return .failure(.incomplete)
+    }
+    return bounded(text, maxBytes: maxBytes)
+  }
+
+  private static func codexCompletionPayload(_ record: [String: Any]) -> [String: Any]? {
+    guard record["type"] as? String == "event_msg",
+      let payload = record["payload"] as? [String: Any],
+      payload["type"] as? String == "task_complete"
+    else {
+      return nil
+    }
+    return payload
+  }
+
+  private static func decodeClaude(records: [[String: Any]], maxBytes: Int) -> AgentTranscriptResult {
+    guard let closeRecord = records.reversed().first(where: isClaudeTurnDuration) else {
+      return .failure(.missing)
+    }
+    guard let closeSessionID = closeRecord["sessionId"] as? String,
+      var parentID = closeRecord["parentUuid"] as? String
+    else {
+      return .failure(.incomplete)
+    }
+
+    var recordsByUUID: [String: [String: Any]] = [:]
+    for record in records {
+      guard let uuid = record["uuid"] as? String else { continue }
+      guard recordsByUUID[uuid] == nil else { return .failure(.incomplete) }
+      recordsByUUID[uuid] = record
+    }
+
+    for _ in 0..<32 {
+      guard let record = recordsByUUID[parentID], record["sessionId"] as? String == closeSessionID else {
+        return .failure(.incomplete)
+      }
+      if record["type"] as? String == "assistant" {
+        return decodeClaudeAssistant(record, maxBytes: maxBytes)
+      }
+      guard let nextParentID = record["parentUuid"] as? String, nextParentID != parentID else {
+        return .failure(.incomplete)
+      }
+      parentID = nextParentID
+    }
+    return .failure(.incomplete)
+  }
+
+  private static func isClaudeTurnDuration(_ record: [String: Any]) -> Bool {
+    record["type"] as? String == "system" && record["subtype"] as? String == "turn_duration"
+  }
+
+  private static func decodeClaudeAssistant(
+    _ record: [String: Any],
+    maxBytes: Int
+  ) -> AgentTranscriptResult {
+    guard let message = record["message"] as? [String: Any],
+      let stopReason = message["stop_reason"] as? String,
+      stopReason == "end_turn" || stopReason == "stop_sequence",
+      let content = message["content"] as? [[String: Any]],
+      !content.isEmpty
+    else {
+      return .failure(.incomplete)
+    }
+
+    var text = ""
+    for block in content {
+      guard block["type"] as? String == "text", let value = block["text"] as? String else {
+        return .failure(.incomplete)
+      }
+      text += value
+    }
+    guard !text.isEmpty else { return .failure(.incomplete) }
+    return bounded(text, maxBytes: maxBytes)
+  }
+
+  private static func bounded(_ text: String, maxBytes: Int) -> AgentTranscriptResult {
+    text.utf8.count <= maxBytes ? .complete(text) : .failure(.tooLarge)
+  }
+
+  private static func containsMaxTokens(_ value: Any) -> Bool {
+    if let text = value as? String {
+      return text.lowercased().contains("max_tokens")
+    }
+    if let array = value as? [Any] {
+      return array.contains(where: containsMaxTokens)
+    }
+    if let object = value as? [String: Any] {
+      return object.values.contains(where: containsMaxTokens)
+    }
+    return false
+  }
+}
diff --git a/supacode/Infrastructure/AgentDetection/ClaudeScreenProfile.swift b/supacode/Infrastructure/AgentDetection/ClaudeScreenProfile.swift
index dc398265..8b2e6413 100644
--- a/supacode/Infrastructure/AgentDetection/ClaudeScreenProfile.swift
+++ b/supacode/Infrastructure/AgentDetection/ClaudeScreenProfile.swift
@@ -44,6 +44,16 @@ enum ClaudeScreenProfile {
     return AgentScreenDetection(state: .idle, reason: .noRuleMatched)
   }
 
+  /// Raw current interaction text for an actionable blocked screen. Keep the
+  /// rendered choices and keyboard hints intact rather than inventing option fields.
+  nonisolated static func blockerText(in snapshot: AgentScreenSnapshot) -> String? {
+    let regions = ClaudeScreenRegions(snapshot: snapshot)
+    guard hasBlockedPrompt(regions) else { return nil }
+    let lines =
+      regions.currentInteractionLines.isEmpty ? Array(snapshot.lines.suffix(18)) : regions.currentInteractionLines
+    return lines.joined(separator: "\n").trimmingCharacters(in: .newlines)
+  }
+
   nonisolated private static func hasViewerChrome(_ regions: ClaudeScreenRegions) -> Bool {
     if regions.bottomChromeLines.contains(where: { line in
       line.contains("⌕ Search…") || line.lowercased().contains("ctrl+r to toggle")
diff --git a/supacode/Infrastructure/AgentDetection/CodexScreenProfile.swift b/supacode/Infrastructure/AgentDetection/CodexScreenProfile.swift
index 4d4d7ea0..c3d5537b 100644
--- a/supacode/Infrastructure/AgentDetection/CodexScreenProfile.swift
+++ b/supacode/Infrastructure/AgentDetection/CodexScreenProfile.swift
@@ -44,6 +44,17 @@ enum CodexScreenProfile {
     return AgentScreenDetection(state: .idle, reason: .noRuleMatched)
   }
 
+  /// Raw current interaction text for an actionable blocked screen. This deliberately
+  /// preserves TUI selection markers and keyboard hints instead of reconstructing options.
+  nonisolated static func blockerText(in snapshot: AgentScreenSnapshot) -> String? {
+    let regions = CodexScreenRegions(snapshot: snapshot)
+    guard detect(in: snapshot).state == .blocked else { return nil }
+    if regions.selectedChoice != nil || hasSignInPrompt(regions) {
+      return snapshot.text.trimmingCharacters(in: .newlines)
+    }
+    return nil
+  }
+
   nonisolated private static func hasDirectoryTrustPrompt(_ regions: CodexScreenRegions) -> Bool {
     hasSelectedChoice(
       regions,
diff --git a/supacodeTests/AgentReadCommandHandlerTests.swift b/supacodeTests/AgentReadCommandHandlerTests.swift
new file mode 100644
index 00000000..1ae01edf
--- /dev/null
+++ b/supacodeTests/AgentReadCommandHandlerTests.swift
@@ -0,0 +1,121 @@
+import Foundation
+import Testing
+
+@testable import supacode
+
+@MainActor
+struct AgentReadCommandHandlerTests {
+  @Test func blockedSnapshotPreservesBlockerWhenTranscriptIsUnavailable() async throws {
+    let handler = AgentReadCommandHandler(
+      snapshotProvider: { _ in
+        .success(self.makeSnapshot(status: .blocked, blockerText: "Do you want to proceed?\n❯ 1. Yes\n  2. No"))
+      },
+      resultProvider: { _, _, _ in
+        Issue.record("Unexpected transcript read")
+        return .failure(.incomplete)
+      }
+    )
+
+    let response = await handler.handle(
+      envelope: CommandEnvelope(output: .json, command: .agentsRead(AgentReadInput(pane: "p7")))
+    )
+
+    #expect(response.ok)
+    let payload = try #require(try response.data?.decode(as: AgentReadCommandPayload.self))
+    #expect(payload.agent.status == .blocked)
+    #expect(payload.blocker?.text.contains("1. Yes") == true)
+    #expect(payload.result.state == .unavailable)
+    #expect(payload.result.error?.code == CLIErrorCode.sessionUnresolved)
+  }
+
+  @Test func workingSnapshotMapsMissingTrustedHistoryToPending() async throws {
+    let handler = AgentReadCommandHandler(
+      snapshotProvider: { _ in .success(self.makeSnapshot(status: .working, session: self.makeSession())) },
+      resultProvider: { _, _, _ in .failure(.missing) }
+    )
+
+    let response = await handler.handle(
+      envelope: CommandEnvelope(output: .json, command: .agentsRead(AgentReadInput(pane: "p7")))
+    )
+
+    #expect(response.ok)
+    let payload = try #require(try response.data?.decode(as: AgentReadCommandPayload.self))
+    #expect(payload.result.state == .pending)
+    #expect(payload.result.text == nil)
+    #expect(payload.result.error == nil)
+  }
+
+  @Test func resultOnlyTurnsUnavailableSnapshotResultIntoCommandFailure() async {
+    let handler = AgentReadCommandHandler(
+      snapshotProvider: { _ in .success(self.makeSnapshot(status: .idle)) },
+      resultProvider: { _, _, _ in
+        Issue.record("Unexpected transcript read")
+        return .failure(.incomplete)
+      }
+    )
+
+    let response = await handler.handle(
+      envelope: CommandEnvelope(
+        output: .text,
+        command: .agentsRead(AgentReadInput(pane: "p7", resultOnly: true))
+      )
+    )
+
+    #expect(response.ok == false)
+    #expect(response.error?.code == CLIErrorCode.sessionUnresolved)
+  }
+
+  @Test func resultOnlySucceedsForCompleteTrustedResult() async throws {
+    let handler = AgentReadCommandHandler(
+      snapshotProvider: { _ in .success(self.makeSnapshot(status: .done, session: self.makeSession())) },
+      resultProvider: { _, _, _ in .complete("Final result") }
+    )
+
+    let response = await handler.handle(
+      envelope: CommandEnvelope(
+        output: .text,
+        command: .agentsRead(AgentReadInput(pane: "p7", resultOnly: true))
+      )
+    )
+
+    #expect(response.ok)
+    let payload = try #require(try response.data?.decode(as: AgentReadCommandPayload.self))
+    #expect(payload.outputMode == .resultOnly)
+    #expect(payload.result.state == .complete)
+    #expect(payload.result.text == "Final result")
+  }
+
+  private func makeSnapshot(
+    status: AgentsCommandStatus,
+    blockerText: String? = nil,
+    session: AgentSession? = nil
+  ) -> AgentReadRuntimeSnapshot {
+    AgentReadRuntimeSnapshot(
+      target: ReadTarget(
+        worktree: ReadTargetWorktree(
+          id: "/tmp/project", name: "main", path: "/tmp/project", rootPath: "/tmp/project", kind: "git"
+        ),
+        tab: ReadTargetTab(id: "2FC00CF0-3974-4E1B-BEF8-7A08A8E3B7C0", title: "Agent", selected: true),
+        pane: ReadTargetPane(
+          id: "6E1A2A10-D99F-4E3F-920C-D93AA3C05764", title: "Claude", cwd: "/tmp/project", focused: false
+        )
+      ),
+      agent: .claude,
+      status: status,
+      rawState: status == .done ? "idle" : status.rawValue,
+      detectionReason: "claude.blockedPrompt",
+      lastChangedAt: "2026-08-11T12:00:00Z",
+      blockerText: blockerText,
+      transcriptSession: session
+    )
+  }
+
+  private func makeSession() -> AgentSession {
+    AgentSession(
+      id: "019f4f1b-3650-7661-a56d-351f02f01139",
+      transcriptPath: URL(fileURLWithPath: "/tmp/session.jsonl"),
+      source: .openFile,
+      confidence: .exact
+    )
+  }
+}
diff --git a/supacodeTests/AgentTranscriptResultReaderTests.swift b/supacodeTests/AgentTranscriptResultReaderTests.swift
new file mode 100644
index 00000000..6959af46
--- /dev/null
+++ b/supacodeTests/AgentTranscriptResultReaderTests.swift
@@ -0,0 +1,178 @@
+import Foundation
+import Testing
+
+@testable import supacode
+
+struct AgentTranscriptResultReaderTests {
+  @Test func decodesLatestClosedCodexTaskCompletion() throws {
+    let result = AgentTranscriptResultReader.decode(
+      agent: .codex,
+      jsonl: try jsonl([
+        codexCompletion(turnID: "turn-1", completedAt: "2026-08-11T12:00:00Z", text: "First result"),
+        codexCompletion(turnID: "turn-2", completedAt: "2026-08-11T12:01:00Z", text: "Final result"),
+      ]),
+      maxBytes: 1_024
+    )
+
+    #expect(result.state == .complete)
+    #expect(result.text == "Final result")
+  }
+
+  @Test func reportsCodexMaxTokensAsIncompleteWithoutText() throws {
+    let result = AgentTranscriptResultReader.decode(
+      agent: .codex,
+      jsonl: try jsonl([
+        codexCompletion(
+          turnID: "turn-1",
+          completedAt: "2026-08-11T12:00:00Z",
+          text: "Partial result",
+          status: "max_tokens"
+        )
+      ]),
+      maxBytes: 1_024
+    )
+
+    #expect(result.state == .incomplete)
+    #expect(result.text == nil)
+  }
+
+  @Test func followsClaudeTurnDurationParentChainToClosedAssistantText() throws {
+    let result = AgentTranscriptResultReader.decode(
+      agent: .claude,
+      jsonl: try jsonl([
+        claudeAssistant(uuid: "assistant-1", sessionID: "session-1", text: "Claude final result"),
+        claudeSystem(
+          subtype: "stop_hook_summary",
+          uuid: "summary-1",
+          sessionID: "session-1",
+          parentUUID: "assistant-1"
+        ),
+        claudeSystem(
+          subtype: "turn_duration",
+          uuid: "duration-1",
+          sessionID: "session-1",
+          parentUUID: "summary-1"
+        ),
+      ]),
+      maxBytes: 1_024
+    )
+
+    #expect(result.state == .complete)
+    #expect(result.text == "Claude final result")
+  }
+
+  @Test func rejectsClaudeToolOnlyAssistantTurnAsIncomplete() throws {
+    let result = AgentTranscriptResultReader.decode(
+      agent: .claude,
+      jsonl: try jsonl([
+        claudeAssistant(uuid: "assistant-1", sessionID: "session-1", content: [["type": "tool_use", "name": "Bash"]]),
+        claudeSystem(
+          subtype: "turn_duration",
+          uuid: "duration-1",
+          sessionID: "session-1",
+          parentUUID: "assistant-1"
+        ),
+      ]),
+      maxBytes: 1_024
+    )
+
+    #expect(result.state == .incomplete)
+    #expect(result.text == nil)
+  }
+
+  @Test func rejectsUnclosedJSONLWithoutReturningPartialText() throws {
+    let jsonl =
+      try jsonl([
+        codexCompletion(turnID: "turn-1", completedAt: "2026-08-11T12:00:00Z", text: "Final result")
+      ]) + "{\"type\":\"event_msg\"\n"
+    let result = AgentTranscriptResultReader.decode(agent: .codex, jsonl: jsonl, maxBytes: 1_024)
+
+    #expect(result.state == .incomplete)
+    #expect(result.text == nil)
+  }
+
+  @Test func reportsOversizedCompleteResultWithoutTruncatingIt() throws {
+    let result = AgentTranscriptResultReader.decode(
+      agent: .codex,
+      jsonl: try jsonl([
+        codexCompletion(turnID: "turn-1", completedAt: "2026-08-11T12:00:00Z", text: "0123456789")
+      ]),
+      maxBytes: 5
+    )
+
+    #expect(result.state == .tooLarge)
+    #expect(result.text == nil)
+  }
+
+  @Test func readsOnlyTheBoundedTranscriptTail() throws {
+    let url = FileManager.default.temporaryDirectory.appending(path: "prowl-result-\(UUID().uuidString).jsonl")
+    defer { try? FileManager.default.removeItem(at: url) }
+    let oversizedHistory =
+      "{\"type\":\"event_msg\",\"payload\":{\"type\":\"agent_message\",\"text\":\""
+      + String(repeating: "x", count: 1_100_000) + "\"}}\n"
+    let completion = try jsonl([
+      codexCompletion(turnID: "turn-1", completedAt: "2026-08-11T12:00:00Z", text: "Final result")
+    ])
+    try (oversizedHistory + completion).write(to: url, atomically: true, encoding: .utf8)
+
+    let result = AgentTranscriptResultReader.read(agent: .codex, at: url, maxBytes: 1_024)
+
+    #expect(result.state == .complete)
+    #expect(result.text == "Final result")
+  }
+
+  private func codexCompletion(
+    turnID: String,
+    completedAt: String,
+    text: String,
+    status: String? = nil
+  ) -> [String: Any] {
+    var payload: [String: Any] = [
+      "type": "task_complete",
+      "turn_id": turnID,
+      "completed_at": completedAt,
+      "last_agent_message": text,
+    ]
+    payload["status"] = status
+    return ["type": "event_msg", "payload": payload]
+  }
+
+  private func claudeAssistant(
+    uuid: String,
+    sessionID: String,
+    text: String? = nil,
+    content: [[String: Any]]? = nil
+  ) -> [String: Any] {
+    [
+      "type": "assistant",
+      "uuid": uuid,
+      "sessionId": sessionID,
+      "message": [
+        "stop_reason": "end_turn",
+        "content": content ?? [["type": "text", "text": text ?? ""]],
+      ],
+    ]
+  }
+
+  private func claudeSystem(
+    subtype: String,
+    uuid: String,
+    sessionID: String,
+    parentUUID: String
+  ) -> [String: Any] {
+    [
+      "type": "system",
+      "subtype": subtype,
+      "uuid": uuid,
+      "sessionId": sessionID,
+      "parentUuid": parentUUID,
+    ]
+  }
+
+  private func jsonl(_ records: [[String: Any]]) throws -> String {
+    try records.map { record in
+      let data = try JSONSerialization.data(withJSONObject: record, options: [.sortedKeys])
+      return try #require(String(data: data, encoding: .utf8)) + "\n"
+    }.joined()
+  }
+}
diff --git a/supacodeTests/CLICommandEnvelopeTests.swift b/supacodeTests/CLICommandEnvelopeTests.swift
index 65db6dfb..c71e3953 100644
--- a/supacodeTests/CLICommandEnvelopeTests.swift
+++ b/supacodeTests/CLICommandEnvelopeTests.swift
@@ -71,6 +71,23 @@ struct CLICommandEnvelopeTests {
     }
   }
 
+  @Test func envelopeAgentsReadRoundTrips() throws {
+    let envelope = CommandEnvelope(
+      output: .text,
+      command: .agentsRead(AgentReadInput(pane: "p7", maxBytes: 1_024, resultOnly: true))
+    )
+    let data = try JSONEncoder().encode(envelope)
+    let decoded = try JSONDecoder().decode(CommandEnvelope.self, from: data)
+
+    if case .agentsRead(let input) = decoded.command {
+      #expect(input.pane == "p7")
+      #expect(input.maxBytes == 1_024)
+      #expect(input.resultOnly)
+    } else {
+      Issue.record("Expected .agentsRead command")
+    }
+  }
+
   @Test func envelopeSendWithSelectorRoundTrips() throws {
     let envelope = CommandEnvelope(
       output: .json,
@@ -247,6 +264,7 @@ struct CLICommandEnvelopeTests {
       (.open(OpenInput(path: nil)), "open"),
       (.list(ListInput()), "list"),
       (.agents(AgentsInput()), "agents"),
+      (.agentsRead(AgentReadInput(pane: "p7")), "agents.read"),
       (.focus(FocusInput()), "focus"),
       (.send(SendInput(text: "x")), "send"),
       (.key(KeyInput(rawToken: "tab", token: "tab")), "key"),
@@ -266,6 +284,7 @@ struct CLICommandEnvelopeTests {
       .open(OpenInput(path: "/tmp")),
       .list(ListInput()),
       .agents(AgentsInput()),
+      .agentsRead(AgentReadInput(pane: "p7")),
       .focus(FocusInput()),
       .send(SendInput(text: "test")),
       .key(KeyInput(rawToken: "enter", token: "enter")),
diff --git a/supacodeTests/CLICommandRouterTests.swift b/supacodeTests/CLICommandRouterTests.swift
index 4cc7e9cd..9f7afea2 100644
--- a/supacodeTests/CLICommandRouterTests.swift
+++ b/supacodeTests/CLICommandRouterTests.swift
@@ -67,6 +67,18 @@ struct CLICommandRouterTests {
     #expect(response.error?.code == "NOT_IMPLEMENTED")
   }
 
+  @MainActor
+  @Test func routerDispatchesAgentsReadToAgentsReadHandler() async {
+    let router = CLICommandRouter()
+    let envelope = CommandEnvelope(
+      output: .json,
+      command: .agentsRead(AgentReadInput(pane: "p7"))
+    )
+    let response = await router.route(envelope)
+    #expect(response.command == "agents.read")
+    #expect(response.error?.code == "NOT_IMPLEMENTED")
+  }
+
   @MainActor
   @Test func routerDispatchesKeyToKeyHandler() async {
     let router = CLICommandRouter()
@@ -137,6 +149,7 @@ struct CLICommandRouterTests {
       .open(OpenInput()),
       .list(ListInput()),
       .agents(AgentsInput()),
+      .agentsRead(AgentReadInput(pane: "p7")),
       .focus(FocusInput()),
       .send(SendInput(text: "x")),
       .key(KeyInput(rawToken: "tab", token: "tab")),
diff --git a/supacodeTests/CLITransportProtocolTests.swift b/supacodeTests/CLITransportProtocolTests.swift
index 87001e00..dd31c823 100644
--- a/supacodeTests/CLITransportProtocolTests.swift
+++ b/supacodeTests/CLITransportProtocolTests.swift
@@ -83,8 +83,8 @@ struct CLITransportProtocolTests {
   }
 
   @Test func maxReasonablePayloadLengthEncodes() {
-    // 10MB is the max accepted by both client and server
-    let maxLength: UInt32 = 9_999_999
+    // 32 MiB is the max accepted by both client and server.
+    let maxLength: UInt32 = 32 * 1_024 * 1_024
     var encoded = UInt32(maxLength).bigEndian
     var data = Data()
     withUnsafeBytes(of: &encoded) { data.append(contentsOf: $0) }
diff --git a/supacodeTests/ClaudeScreenProfileTests.swift b/supacodeTests/ClaudeScreenProfileTests.swift
index 5ed61562..62e79637 100644
--- a/supacodeTests/ClaudeScreenProfileTests.swift
+++ b/supacodeTests/ClaudeScreenProfileTests.swift
@@ -91,6 +91,19 @@ struct ClaudeScreenProfileTests {
     #expect(detection.reason == .matched(ClaudeScreenProfile.RuleID.blockedPrompt))
   }
 
+  @Test func blockerTextPreservesClaudeQuestionChoicesAndKeyboardHints() throws {
+    let fixture = try AgentScreenFixtureCorpus.load()
+      .first { $0.relativePath == "claude/2.1.223/blocked/command-permission.txt" }
+    let text = try #require(fixture).text
+
+    let blocker = ClaudeScreenProfile.blockerText(in: AgentScreenSnapshot(canonicalText: text))
+
+    #expect(blocker?.contains("Do you want to proceed?") == true)
+    #expect(blocker?.contains("❯ 1. Yes") == true)
+    #expect(blocker?.contains("3. No") == true)
+    #expect(blocker?.contains("Esc to cancel · Tab to amend · ctrl+e to explain") == true)
+  }
+
   @Test func unstructuredScreenUsesExplicitFallback() {
     let detection = ClaudeScreenProfile.detect(
       in: AgentScreenSnapshot(canonicalText: "screen without live Claude chrome")
diff --git a/supacodeTests/CodexScreenProfileTests.swift b/supacodeTests/CodexScreenProfileTests.swift
index e670b356..d27a5a2d 100644
--- a/supacodeTests/CodexScreenProfileTests.swift
+++ b/supacodeTests/CodexScreenProfileTests.swift
@@ -50,4 +50,17 @@ struct CodexScreenProfileTests {
     #expect(detection.state == .blocked)
     #expect(detection.reason == .matched(CodexScreenProfile.RuleID.confirmationChoices))
   }
+
+  @Test func blockerTextPreservesCodexQuestionChoicesAndKeyboardHints() throws {
+    let fixture = try AgentScreenFixtureCorpus.load()
+      .first { $0.relativePath == "codex/0.146.1/blocked/command-permission.txt" }
+    let text = try #require(fixture).text
+
+    let blocker = CodexScreenProfile.blockerText(in: AgentScreenSnapshot(canonicalText: text))
+
+    #expect(blocker?.contains("Would you like to run the following command?") == true)
+    #expect(blocker?.contains("› 1. Yes, proceed (y)") == true)
+    #expect(blocker?.contains("3. No, and tell Codex what to do differently (esc)") == true)
+    #expect(blocker?.contains("Press enter to confirm or esc to cancel") == true)
+  }
 }
diff --git a/supacodeTests/SupacodeAppCLITests.swift b/supacodeTests/SupacodeAppCLITests.swift
index c4c8826e..0ac1fede 100644
--- a/supacodeTests/SupacodeAppCLITests.swift
+++ b/supacodeTests/SupacodeAppCLITests.swift
@@ -17,6 +17,9 @@ struct SupacodeAppCLITests {
     let agentsResponse = await router.route(
       CommandEnvelope(output: .json, command: .agents(AgentsInput()))
     )
+    let agentReadResponse = await router.route(
+      CommandEnvelope(output: .json, command: .agentsRead(AgentReadInput(pane: "p7")))
+    )
     let keyResponse = await router.route(
       CommandEnvelope(output: .json, command: .key(KeyInput(rawToken: "enter", token: "enter")))
     )
@@ -25,9 +28,11 @@ struct SupacodeAppCLITests {
     )
 
     #expect(agentsResponse.command == "agents")
+    #expect(agentReadResponse.command == "agents.read")
     #expect(keyResponse.command == "key")
     #expect(readResponse.command == "read")
     #expect(agentsResponse.error?.code != "NOT_IMPLEMENTED")
+    #expect(agentReadResponse.error?.code != "NOT_IMPLEMENTED")
     #expect(keyResponse.error?.code != "NOT_IMPLEMENTED")
     #expect(readResponse.error?.code != "NOT_IMPLEMENTED")
   }
-- 
2.51.2


From 95066bf52ed1c1d057dc765d3c8f35fcbe0f6697 Mon Sep 17 00:00:00 2001
From: onevcat <onevcat@gmail.com>
Date: Tue, 11 Aug 2026 22:47:32 +0900
Subject: [PATCH 08/19] docs: record agent snapshot PR

---
 docs-ai/059-agent-transcript-snapshots/000-plan.md   | 2 +-
 docs-ai/059-agent-transcript-snapshots/001-action.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs-ai/059-agent-transcript-snapshots/000-plan.md b/docs-ai/059-agent-transcript-snapshots/000-plan.md
index 54dc7474..fabf33fb 100644
--- a/docs-ai/059-agent-transcript-snapshots/000-plan.md
+++ b/docs-ai/059-agent-transcript-snapshots/000-plan.md
@@ -4,7 +4,7 @@
 | --- | --- |
 | **Status** | Implemented |
 | **Anchor date** | 2026-08-11 |
-| **Primary PRs** | (fill in as they merge) |
+| **Primary PRs** | #696 |
 | **Related** | [013 — Prowl CLI](../013-prowl-cli/000-plan.md), [045 — Native agent session detection](../045-native-agent-session-detection/000-plan.md), [issue #473](https://github.com/onevcat/Prowl/issues/473), [relay-tracker #53](https://github.com/onevcat/relay-tracker/issues/53) |
 
 ## Background
diff --git a/docs-ai/059-agent-transcript-snapshots/001-action.md b/docs-ai/059-agent-transcript-snapshots/001-action.md
index 69ea24b1..990e41f4 100644
--- a/docs-ai/059-agent-transcript-snapshots/001-action.md
+++ b/docs-ai/059-agent-transcript-snapshots/001-action.md
@@ -5,7 +5,7 @@
 | Date | Change | Ref |
 | --- | --- | --- |
 | 2026-08-11 | Wrote the snapshot-first plan and established the CLI/result-state contract. | This entry |
-| 2026-08-11 | Added `prowl agents read` for explicit Codex/Claude panes, live blocker extraction, fresh transcript attribution, bounded decoders, contracts, and user guidance. | Pending PR |
+| 2026-08-11 | Added `prowl agents read` for explicit Codex/Claude panes, live blocker extraction, fresh transcript attribution, bounded decoders, contracts, and user guidance. | #696 |
 
 ## Outcome & current state (as of 2026-08-11)
 
-- 
2.51.2


From 918d2bef962c9baf331a456dc164e90ded8c455a Mon Sep 17 00:00:00 2001
From: onevcat <onevcat@gmail.com>
Date: Tue, 11 Aug 2026 23:00:41 +0900
Subject: [PATCH 09/19] Fix Canvas interaction test warning

---
 supacodeTests/CanvasInteractionPolicyTests.swift | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/supacodeTests/CanvasInteractionPolicyTests.swift b/supacodeTests/CanvasInteractionPolicyTests.swift
index 8b001231..d9a91bf3 100644
--- a/supacodeTests/CanvasInteractionPolicyTests.swift
+++ b/supacodeTests/CanvasInteractionPolicyTests.swift
@@ -84,7 +84,7 @@ struct CanvasInteractionPolicyTests {
 
     let tree = try SplitTree(view: hiddenPane)
       .inserting(view: visiblePane, at: hiddenPane, direction: .right)
-    let zoomedTree = tree.settingZoomed(try #require(tree.find(id: visiblePane.id)))
+    let zoomedTree = tree.settingZoomed(tree.find(id: visiblePane.id))
     let linkActivationRequested = CanvasInteractionPolicy.linkActivationRequested(
       hasHoveredLink: CanvasInteractionPolicy.hasHoveredLink(in: zoomedTree),
       isCommandModifierActive: true
-- 
2.51.2


From 5e1cd60158682af88ff542156193294c739469d4 Mon Sep 17 00:00:00 2001
From: onevcat <onevcat@gmail.com>
Date: Thu, 13 Aug 2026 15:46:38 +0900
Subject: [PATCH 10/19] fix(cli): harden agent transcript snapshots

---
 .../013-prowl-cli/contracts/agents-read.md    |   6 +-
 .../000-plan.md                               |   5 +-
 .../001-action.md                             |  25 ++-
 .../AgentTranscriptResultReader.swift         |  44 ++---
 .../AgentDetection/CodexScreenProfile.swift   |  33 +++-
 .../AgentTranscriptResultReaderTests.swift    | 160 +++++++++++++++---
 supacodeTests/CodexScreenProfileTests.swift   |  58 +++++++
 7 files changed, 273 insertions(+), 58 deletions(-)

diff --git a/docs-ai/013-prowl-cli/contracts/agents-read.md b/docs-ai/013-prowl-cli/contracts/agents-read.md
index 0c1c3f82..2ef929fb 100644
--- a/docs-ai/013-prowl-cli/contracts/agents-read.md
+++ b/docs-ai/013-prowl-cli/contracts/agents-read.md
@@ -88,8 +88,10 @@ Non-`complete` states include `result.error` with the stable code
 `RESULT_TOO_LARGE`, except `pending`, which is ordinary live activity rather than an
 error. Partial text is never returned.
 
-Codex accepts only `event_msg.payload.type == "task_complete"` records with
-`turn_id`, `completed_at`, and `last_agent_message`. Claude Code accepts a
+Codex accepts only a latest terminal `event_msg.payload.type == "task_complete"`
+record with a non-empty `turn_id`, integer Unix-seconds `completed_at`, non-empty
+`last_agent_message`, and no `error`. A newer `turn_aborted` terminal event makes
+the result incomplete instead of exposing an earlier answer. Claude Code accepts a
 `system/turn_duration` close record and a bounded same-session parent chain to an
 assistant message containing only text blocks with `end_turn` or `stop_sequence`.
 
diff --git a/docs-ai/059-agent-transcript-snapshots/000-plan.md b/docs-ai/059-agent-transcript-snapshots/000-plan.md
index fabf33fb..1d04b3f7 100644
--- a/docs-ai/059-agent-transcript-snapshots/000-plan.md
+++ b/docs-ai/059-agent-transcript-snapshots/000-plan.md
@@ -107,8 +107,9 @@ screen, or unreadable blocker region.
 4. Add an independent transcript-result reader beside the existing agent-detection
    infrastructure. It reads a bounded, race-checked JSONL snapshot and has separate
    Codex and Claude decoders:
-   - Codex accepts only a closed `event_msg.payload.type == "task_complete"` record
-     with a usable `turn_id`, `completed_at`, and `last_agent_message`.
+   - Codex accepts only the latest terminal `event_msg.payload.type == "task_complete"`
+     record with a non-empty `turn_id`, integer Unix-seconds `completed_at`, non-empty
+     `last_agent_message`, and no error; a newer `turn_aborted` remains incomplete.
    - Claude accepts `system/turn_duration` as a close marker, follows its bounded
      same-session parent chain back through summaries to an assistant message, and
      accepts text-only content with `end_turn` or `stop_sequence`.
diff --git a/docs-ai/059-agent-transcript-snapshots/001-action.md b/docs-ai/059-agent-transcript-snapshots/001-action.md
index 990e41f4..a2c3e247 100644
--- a/docs-ai/059-agent-transcript-snapshots/001-action.md
+++ b/docs-ai/059-agent-transcript-snapshots/001-action.md
@@ -6,8 +6,9 @@
 | --- | --- | --- |
 | 2026-08-11 | Wrote the snapshot-first plan and established the CLI/result-state contract. | This entry |
 | 2026-08-11 | Added `prowl agents read` for explicit Codex/Claude panes, live blocker extraction, fresh transcript attribution, bounded decoders, contracts, and user guidance. | #696 |
+| 2026-08-13 | Corrected Codex terminal-event decoding, cropped blockers, and hardened result bounds from live E2E findings. | #696 |
 
-## Outcome & current state (as of 2026-08-11)
+## Outcome & current state (as of 2026-08-13)
 
 - `ProwlCLI/Commands/AgentsCommand.swift` and
   `ProwlCLI/Commands/AgentsReadCommand.swift` expose `prowl agents read <pN|uuid>`
@@ -20,9 +21,11 @@
   re-identifies the foreground process, and calls the fresh resolver path. It permits
   only exact/high transcript-backed Codex/Claude sessions.
 - `supacode/Infrastructure/AgentDetection/AgentTranscriptResultReader.swift` reads a
-  bounded, stable JSONL tail with one mutation retry; it decodes closed Codex
-  `task_complete` and Claude `turn_duration` parent-chain results without returning
-  partial text. `AgentSessionResolver.resolveFresh` bypasses only the pid-result cache.
+  bounded, stable JSONL tail with one mutation retry; it decodes the latest Codex
+  terminal event and Claude `turn_duration` parent-chain results without returning
+  partial text. Codex timestamps follow the native integer Unix-seconds schema,
+  aborted turns withhold earlier answers, and the tail budget covers worst-case JSON
+  escaping. `AgentSessionResolver.resolveFresh` bypasses only the pid-result cache.
 - `ClaudeScreenProfile` and `CodexScreenProfile` now export the raw blocked interaction
   region used by the command. `ProwlCLI/Output/OutputRenderer.swift` renders the normal
   status snapshot or writes result-only bytes directly without a synthetic newline.
@@ -34,12 +37,24 @@
 | Command | Observed result |
 | --- | --- |
 | `make check` | Passed: changed-file formatting, strict swift-format lint, and SwiftLint. |
-| `make test` | Passed: xcresult reported 2,313 tests with zero failures. |
+| `make test` | Passed: xcresult verified 2,322 tests with zero failures. |
 | `make build-cli` | Passed. |
 | `make test-cli-smoke` | Passed. |
 | `make test-cli-integration` | Passed: 68 tests. |
 | `make build-app` | Passed: Debug macOS app build with zero warnings. |
 
+## Follow-up verification
+
+- Live Codex 0.147.0 E2E confirmed numeric `completed_at`, exact final-result output,
+  cropped permission blockers, literal `max_tokens` answer text, and withholding an
+  earlier answer after a real `turn_aborted/interrupted` event.
+- Live Claude Code 2.1.228 E2E confirmed exact latest-result output and trusted
+  transcript attribution.
+- The final production reader matched an independent terminal-marker oracle across
+  310 stable transcripts from the prior 30 days with zero mismatches: Codex reported
+  59 complete, 11 incomplete, and 3 missing; Claude reported 108 complete, 2
+  incomplete, and 127 missing.
+
 ## Deviations from plan
 
 - The decoder tests use compact synthetic JSONL records in
diff --git a/supacode/Infrastructure/AgentDetection/AgentTranscriptResultReader.swift b/supacode/Infrastructure/AgentDetection/AgentTranscriptResultReader.swift
index 77e13c71..b021e484 100644
--- a/supacode/Infrastructure/AgentDetection/AgentTranscriptResultReader.swift
+++ b/supacode/Infrastructure/AgentDetection/AgentTranscriptResultReader.swift
@@ -70,13 +70,12 @@ nonisolated enum AgentTranscriptResultReader {
     let startsMidRecord: Bool
   }
 
-  /// A JSON string can be larger than its UTF-8 result after escaping. Three
-  /// times the requested result plus 1 MiB leaves room for one maximal latest
-  /// record and its close markers, while the 16 MiB cap keeps giant histories
-  /// out of the process even when callers request the 4 MiB result maximum.
+  /// JSON escaping can expand one UTF-8 control byte to six ASCII bytes.
+  /// Six times the requested result plus 1 MiB therefore preserves one
+  /// maximal latest record while keeping the 4 MiB request bounded to 25 MiB.
   private static func tailByteLimit(for maxBytes: Int) -> UInt64 {
-    let scaled = max(0, maxBytes) * 3 + 1_024 * 1_024
-    return UInt64(min(16 * 1_024 * 1_024, max(1_024 * 1_024, scaled)))
+    let scaled = max(0, maxBytes) * 6 + 1_024 * 1_024
+    return UInt64(min(25 * 1_024 * 1_024, max(1_024 * 1_024, scaled)))
   }
 
   private static func tailData(at url: URL, byteLimit: UInt64) -> TranscriptTail? {
@@ -131,23 +130,29 @@ nonisolated enum AgentTranscriptResultReader {
   }
 
   private static func decodeCodex(records: [[String: Any]], maxBytes: Int) -> AgentTranscriptResult {
-    guard let payload = records.reversed().compactMap(codexCompletionPayload).first else {
+    guard let payload = records.reversed().lazy.compactMap(codexTerminalPayload).first else {
       return .failure(.missing)
     }
-    guard !containsMaxTokens(payload),
-      payload["turn_id"] is String,
-      payload["completed_at"] is String,
-      let text = payload["last_agent_message"] as? String
+    guard payload["type"] as? String == "task_complete",
+      let turnID = payload["turn_id"] as? String,
+      !turnID.isEmpty,
+      let completedAt = payload["completed_at"] as? NSNumber,
+      CFGetTypeID(completedAt) != CFBooleanGetTypeID(),
+      !CFNumberIsFloatType(completedAt),
+      payload["error"] == nil,
+      let text = payload["last_agent_message"] as? String,
+      !text.isEmpty
     else {
       return .failure(.incomplete)
     }
     return bounded(text, maxBytes: maxBytes)
   }
 
-  private static func codexCompletionPayload(_ record: [String: Any]) -> [String: Any]? {
+  private static func codexTerminalPayload(_ record: [String: Any]) -> [String: Any]? {
     guard record["type"] as? String == "event_msg",
       let payload = record["payload"] as? [String: Any],
-      payload["type"] as? String == "task_complete"
+      let type = payload["type"] as? String,
+      type == "task_complete" || type == "turn_aborted"
     else {
       return nil
     }
@@ -217,17 +222,4 @@ nonisolated enum AgentTranscriptResultReader {
   private static func bounded(_ text: String, maxBytes: Int) -> AgentTranscriptResult {
     text.utf8.count <= maxBytes ? .complete(text) : .failure(.tooLarge)
   }
-
-  private static func containsMaxTokens(_ value: Any) -> Bool {
-    if let text = value as? String {
-      return text.lowercased().contains("max_tokens")
-    }
-    if let array = value as? [Any] {
-      return array.contains(where: containsMaxTokens)
-    }
-    if let object = value as? [String: Any] {
-      return object.values.contains(where: containsMaxTokens)
-    }
-    return false
-  }
 }
diff --git a/supacode/Infrastructure/AgentDetection/CodexScreenProfile.swift b/supacode/Infrastructure/AgentDetection/CodexScreenProfile.swift
index c3d5537b..c05fa9c6 100644
--- a/supacode/Infrastructure/AgentDetection/CodexScreenProfile.swift
+++ b/supacode/Infrastructure/AgentDetection/CodexScreenProfile.swift
@@ -49,8 +49,11 @@ enum CodexScreenProfile {
   nonisolated static func blockerText(in snapshot: AgentScreenSnapshot) -> String? {
     let regions = CodexScreenRegions(snapshot: snapshot)
     guard detect(in: snapshot).state == .blocked else { return nil }
-    if regions.selectedChoice != nil || hasSignInPrompt(regions) {
-      return snapshot.text.trimmingCharacters(in: .newlines)
+    if let selectedChoice = regions.selectedChoice {
+      return selectedChoice.interactionText
+    }
+    if hasSignInPrompt(regions) {
+      return regions.signInInteractionText
     }
     return nil
   }
@@ -173,16 +176,26 @@ private struct CodexScreenRegions: Sendable {
     let afterLower: String
     let footerLower: String
     let interactionLower: String
+    let interactionText: String
     let options: [String]
   }
 
   let selectedChoice: SelectedChoice?
   let signInMenuLines: [String]
+  let signInInteractionText: String
   let workingFooter: String
 
   nonisolated init(snapshot: AgentScreenSnapshot) {
     self.selectedChoice = Self.makeSelectedChoice(from: snapshot.lines)
-    self.signInMenuLines = Array(snapshot.lines.suffix(18))
+    let signInMenuLines = Array(snapshot.lines.suffix(18))
+    self.signInMenuLines = signInMenuLines
+    let signInStart =
+      signInMenuLines.lastIndex { line in
+        line.lowercased().contains("welcome to codex, openai's command-line coding agent")
+      } ?? signInMenuLines.startIndex
+    self.signInInteractionText = signInMenuLines[signInStart...]
+      .joined(separator: "\n")
+      .trimmingCharacters(in: .newlines)
     self.workingFooter = agentDetectionRecentLines(snapshot.text, limit: 3)
   }
 
@@ -192,9 +205,12 @@ private struct CodexScreenRegions: Sendable {
     }
 
     let lowerBound = max(lines.startIndex, promptIndex - 6)
+    let interactionStart =
+      lines[...promptIndex]
+      .lastIndex(where: isCodexInteractionStart) ?? lowerBound
     let afterStart = lines.index(after: promptIndex)
     let afterEnd = min(lines.endIndex, afterStart + 6)
-    let interactionLines = lines[lowerBound..<lines.endIndex]
+    let interactionLines = lines[interactionStart..<lines.endIndex]
     let footerText = lines[afterStart..<lines.endIndex].joined(separator: "\n")
     return SelectedChoice(
       choice: normalizedCodexChoice(lines[promptIndex]),
@@ -203,11 +219,20 @@ private struct CodexScreenRegions: Sendable {
       afterLower: lines[afterStart..<afterEnd].joined(separator: "\n").lowercased(),
       footerLower: agentDetectionRecentLines(footerText, limit: 3).lowercased(),
       interactionLower: interactionLines.joined(separator: "\n").lowercased(),
+      interactionText: interactionLines.joined(separator: "\n").trimmingCharacters(in: .newlines),
       options: interactionLines.map(normalizedCodexChoice)
     )
   }
 }
 
+nonisolated private func isCodexInteractionStart(_ line: String) -> Bool {
+  let lower = line.trimmingCharacters(in: .whitespaces).lowercased()
+  return lower.hasPrefix("do you trust ")
+    || lower.hasPrefix("do you want ")
+    || lower.hasPrefix("would you like ")
+    || lower == "hooks need review"
+}
+
 nonisolated private func isCodexPromptLine(_ line: String) -> Bool {
   let trimmed = line.trimmingCharacters(in: .whitespaces)
   guard trimmed.first == "›" else { return false }
diff --git a/supacodeTests/AgentTranscriptResultReaderTests.swift b/supacodeTests/AgentTranscriptResultReaderTests.swift
index 6959af46..f8dd51a1 100644
--- a/supacodeTests/AgentTranscriptResultReaderTests.swift
+++ b/supacodeTests/AgentTranscriptResultReaderTests.swift
@@ -8,8 +8,8 @@ struct AgentTranscriptResultReaderTests {
     let result = AgentTranscriptResultReader.decode(
       agent: .codex,
       jsonl: try jsonl([
-        codexCompletion(turnID: "turn-1", completedAt: "2026-08-11T12:00:00Z", text: "First result"),
-        codexCompletion(turnID: "turn-2", completedAt: "2026-08-11T12:01:00Z", text: "Final result"),
+        codexCompletion(turnID: "turn-1", completedAt: 1_786_435_200, text: "First result"),
+        codexCompletion(turnID: "turn-2", completedAt: 1_786_435_260, text: "Final result"),
       ]),
       maxBytes: 1_024
     )
@@ -18,20 +18,112 @@ struct AgentTranscriptResultReaderTests {
     #expect(result.text == "Final result")
   }
 
-  @Test func reportsCodexMaxTokensAsIncompleteWithoutText() throws {
+  @Test func decodesCodexCompletionWithNumericTimestamp() throws {
+    let result = AgentTranscriptResultReader.decode(
+      agent: .codex,
+      jsonl: try jsonl([
+        codexCompletion(turnID: "turn-1", completedAt: 1_786_438_335, text: "Final result")
+      ]),
+      maxBytes: 1_024
+    )
+
+    #expect(result.state == .complete)
+    #expect(result.text == "Final result")
+  }
+
+  @Test func rejectsCodexCompletionWithoutUsableIdentityOrText() throws {
+    let emptyTurnID = AgentTranscriptResultReader.decode(
+      agent: .codex,
+      jsonl: try jsonl([
+        codexCompletion(turnID: "", completedAt: 1_786_438_335, text: "Final result")
+      ]),
+      maxBytes: 1_024
+    )
+    let emptyText = AgentTranscriptResultReader.decode(
+      agent: .codex,
+      jsonl: try jsonl([
+        codexCompletion(turnID: "turn-1", completedAt: 1_786_438_335, text: "")
+      ]),
+      maxBytes: 1_024
+    )
+
+    #expect(emptyTurnID.state == .incomplete)
+    #expect(emptyText.state == .incomplete)
+  }
+
+  @Test func rejectsCodexCompletionWithNonIntegerTimestamp() throws {
+    let result = AgentTranscriptResultReader.decode(
+      agent: .codex,
+      jsonl: try jsonl([
+        codexCompletion(turnID: "turn-1", completedAt: 1_786_438_335.5, text: "Final result")
+      ]),
+      maxBytes: 1_024
+    )
+
+    #expect(result.state == .incomplete)
+    #expect(result.text == nil)
+  }
+
+  @Test func rejectsCodexCompletionWithErrorOrMissingMessage() throws {
+    var errorPayload =
+      codexCompletion(
+        turnID: "turn-1",
+        completedAt: 1_786_438_335,
+        text: "Partial result"
+      )["payload"] as? [String: Any] ?? [:]
+    errorPayload["error"] = ["message": "stream disconnected"]
+    let errored = AgentTranscriptResultReader.decode(
+      agent: .codex,
+      jsonl: try jsonl([["type": "event_msg", "payload": errorPayload]]),
+      maxBytes: 1_024
+    )
+    let missingMessage = AgentTranscriptResultReader.decode(
+      agent: .codex,
+      jsonl: try jsonl([
+        [
+          "type": "event_msg",
+          "payload": [
+            "type": "task_complete",
+            "turn_id": "turn-1",
+            "completed_at": 1_786_438_335,
+            "last_agent_message": NSNull(),
+          ],
+        ]
+      ]),
+      maxBytes: 1_024
+    )
+
+    #expect(errored.state == .incomplete)
+    #expect(missingMessage.state == .incomplete)
+  }
+
+  @Test func acceptsCompletedCodexResultMentioningMaxTokens() throws {
     let result = AgentTranscriptResultReader.decode(
       agent: .codex,
       jsonl: try jsonl([
         codexCompletion(
           turnID: "turn-1",
-          completedAt: "2026-08-11T12:00:00Z",
-          text: "Partial result",
-          status: "max_tokens"
+          completedAt: 1_786_435_200,
+          text: "Use max_tokens to configure the output limit."
         )
       ]),
       maxBytes: 1_024
     )
 
+    #expect(result.state == .complete)
+    #expect(result.text == "Use max_tokens to configure the output limit.")
+  }
+
+  @Test func rejectsLatestBudgetLimitedCodexTurnWithoutReturningEarlierResult() throws {
+    let result = AgentTranscriptResultReader.decode(
+      agent: .codex,
+      jsonl: try jsonl([
+        codexCompletion(turnID: "turn-1", completedAt: 1_786_435_200, text: "Earlier result"),
+        codexAbort(turnID: "turn-2", completedAt: 1_786_435_260, reason: "budget_limited"),
+      ]),
+      maxBytes: 1_024
+    )
+
     #expect(result.state == .incomplete)
     #expect(result.text == nil)
   }
@@ -83,7 +175,7 @@ struct AgentTranscriptResultReaderTests {
   @Test func rejectsUnclosedJSONLWithoutReturningPartialText() throws {
     let jsonl =
       try jsonl([
-        codexCompletion(turnID: "turn-1", completedAt: "2026-08-11T12:00:00Z", text: "Final result")
+        codexCompletion(turnID: "turn-1", completedAt: 1_786_435_200, text: "Final result")
       ]) + "{\"type\":\"event_msg\"\n"
     let result = AgentTranscriptResultReader.decode(agent: .codex, jsonl: jsonl, maxBytes: 1_024)
 
@@ -95,7 +187,7 @@ struct AgentTranscriptResultReaderTests {
     let result = AgentTranscriptResultReader.decode(
       agent: .codex,
       jsonl: try jsonl([
-        codexCompletion(turnID: "turn-1", completedAt: "2026-08-11T12:00:00Z", text: "0123456789")
+        codexCompletion(turnID: "turn-1", completedAt: 1_786_435_200, text: "0123456789")
       ]),
       maxBytes: 5
     )
@@ -104,6 +196,20 @@ struct AgentTranscriptResultReaderTests {
     #expect(result.text == nil)
   }
 
+  @Test func readsCompleteResultAtWorstCaseJSONEscapingSize() throws {
+    let url = FileManager.default.temporaryDirectory.appending(path: "prowl-result-\(UUID().uuidString).jsonl")
+    defer { try? FileManager.default.removeItem(at: url) }
+    let text = String(repeating: "\u{1}", count: 400_000)
+    try jsonl([
+      codexCompletion(turnID: "turn-1", completedAt: 1_786_435_200, text: text)
+    ]).write(to: url, atomically: true, encoding: .utf8)
+
+    let result = AgentTranscriptResultReader.read(agent: .codex, at: url, maxBytes: 400_000)
+
+    #expect(result.state == .complete)
+    #expect(result.text == text)
+  }
+
   @Test func readsOnlyTheBoundedTranscriptTail() throws {
     let url = FileManager.default.temporaryDirectory.appending(path: "prowl-result-\(UUID().uuidString).jsonl")
     defer { try? FileManager.default.removeItem(at: url) }
@@ -111,7 +217,7 @@ struct AgentTranscriptResultReaderTests {
       "{\"type\":\"event_msg\",\"payload\":{\"type\":\"agent_message\",\"text\":\""
       + String(repeating: "x", count: 1_100_000) + "\"}}\n"
     let completion = try jsonl([
-      codexCompletion(turnID: "turn-1", completedAt: "2026-08-11T12:00:00Z", text: "Final result")
+      codexCompletion(turnID: "turn-1", completedAt: 1_786_435_200, text: "Final result")
     ])
     try (oversizedHistory + completion).write(to: url, atomically: true, encoding: .utf8)
 
@@ -123,18 +229,34 @@ struct AgentTranscriptResultReaderTests {
 
   private func codexCompletion(
     turnID: String,
-    completedAt: String,
-    text: String,
-    status: String? = nil
+    completedAt: Any,
+    text: String
   ) -> [String: Any] {
-    var payload: [String: Any] = [
-      "type": "task_complete",
-      "turn_id": turnID,
-      "completed_at": completedAt,
-      "last_agent_message": text,
+    [
+      "type": "event_msg",
+      "payload": [
+        "type": "task_complete",
+        "turn_id": turnID,
+        "completed_at": completedAt,
+        "last_agent_message": text,
+      ],
+    ]
+  }
+
+  private func codexAbort(
+    turnID: String,
+    completedAt: Any,
+    reason: String
+  ) -> [String: Any] {
+    [
+      "type": "event_msg",
+      "payload": [
+        "type": "turn_aborted",
+        "turn_id": turnID,
+        "completed_at": completedAt,
+        "reason": reason,
+      ],
     ]
-    payload["status"] = status
-    return ["type": "event_msg", "payload": payload]
   }
 
   private func claudeAssistant(
diff --git a/supacodeTests/CodexScreenProfileTests.swift b/supacodeTests/CodexScreenProfileTests.swift
index d27a5a2d..7f09d357 100644
--- a/supacodeTests/CodexScreenProfileTests.swift
+++ b/supacodeTests/CodexScreenProfileTests.swift
@@ -51,6 +51,60 @@ struct CodexScreenProfileTests {
     #expect(detection.reason == .matched(CodexScreenProfile.RuleID.confirmationChoices))
   }
 
+  @Test func blockerTextCropsEveryCapturedBlockedFixture() throws {
+    let fixtures = try AgentScreenFixtureCorpus.load().filter {
+      $0.agent == .codex && $0.expectedState == .blocked
+    }
+
+    for fixture in fixtures {
+      let blocker = CodexScreenProfile.blockerText(
+        in: AgentScreenSnapshot(canonicalText: agentDetectionRecentText(fixture.text))
+      )
+
+      #expect(blocker != nil)
+      #expect(blocker?.contains("OpenAI Codex (v") == false)
+      #expect(blocker?.contains("<USAGE_STATUS>") == false)
+    }
+  }
+
+  @Test func blockerTextRejectsQuotedHistoricalPrompt() throws {
+    let fixture = try #require(
+      AgentScreenFixtureCorpus.load().first {
+        $0.relativePath == "codex/0.146.1/idle/quoted-directory-trust.txt"
+      }
+    )
+
+    let blocker = CodexScreenProfile.blockerText(
+      in: AgentScreenSnapshot(canonicalText: agentDetectionRecentText(fixture.text))
+    )
+
+    #expect(blocker == nil)
+  }
+
+  @Test func blockerTextKeepsQuestionAboveLongWrappedInteraction() {
+    let filler = (1...14).map { "  wrapped command detail \($0)" }.joined(separator: "\n")
+    let snapshot = AgentScreenSnapshot(
+      canonicalText: agentDetectionRecentText(
+        """
+        Historical output that must not be returned.
+
+          Would you like to run the following command?
+        \(filler)
+        › 1. Yes, proceed (y)
+          2. No, cancel (esc)
+
+          Press enter to confirm or esc to cancel
+        """
+      )
+    )
+
+    let blocker = CodexScreenProfile.blockerText(in: snapshot)
+
+    #expect(blocker?.contains("Would you like to run the following command?") == true)
+    #expect(blocker?.contains("wrapped command detail 14") == true)
+    #expect(blocker?.contains("Historical output") == false)
+  }
+
   @Test func blockerTextPreservesCodexQuestionChoicesAndKeyboardHints() throws {
     let fixture = try AgentScreenFixtureCorpus.load()
       .first { $0.relativePath == "codex/0.146.1/blocked/command-permission.txt" }
@@ -59,8 +113,12 @@ struct CodexScreenProfileTests {
     let blocker = CodexScreenProfile.blockerText(in: AgentScreenSnapshot(canonicalText: text))
 
     #expect(blocker?.contains("Would you like to run the following command?") == true)
+    #expect(blocker?.contains("Environment: local") == true)
+    #expect(blocker?.contains("$ touch permission-probe.txt") == true)
     #expect(blocker?.contains("› 1. Yes, proceed (y)") == true)
     #expect(blocker?.contains("3. No, and tell Codex what to do differently (esc)") == true)
     #expect(blocker?.contains("Press enter to confirm or esc to cancel") == true)
+    #expect(blocker?.contains("OpenAI Codex") == false)
+    #expect(blocker?.contains("Run touch permission-probe.txt using the shell now.") == false)
   }
 }
-- 
2.51.2


From e57579c7a296091c1e0e4ebfd2b73a8d5fbba1e9 Mon Sep 17 00:00:00 2001
From: onevcat <wei.wang@linecorp.com>
Date: Fri, 14 Aug 2026 11:44:55 +0900
Subject: [PATCH 11/19] fix(detection): feed Claude detection the full active
 screen

The shared recent-line tail is measured from the bottom of the screen,
so a long todo list plus the composer and a multi-line status line can
push the live spinner row past the 24-line limit, and a working Claude
session reads as idle via the idle-composer rule.

Claude's rules are all region-anchored (live status from the last
logical rows above the composer, blockers from around the prompt,
chrome from the bottom lines), so the bounded tail adds no
false-positive protection there. Make the detector tail per-agent:
Claude consumes the full active screen, while the whole-text legacy
detectors keep the bounded tail as their guard against transcript
history.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 supacode/App/supacodeApp.swift                |  2 +-
 .../AgentDetection/AgentScreenSnapshot.swift  | 13 +++---
 .../AgentDetection/ScreenHeuristics.swift     | 19 +++++++--
 .../AgentScreenFixtureCorpusTests.swift       |  8 +---
 supacodeTests/ClaudeScreenProfileTests.swift  | 41 ++++++++++++++++---
 supacodeTests/CodexScreenProfileTests.swift   | 10 ++---
 6 files changed, 66 insertions(+), 27 deletions(-)

diff --git a/supacode/App/supacodeApp.swift b/supacode/App/supacodeApp.swift
index 84383cf9..03ac7e1c 100644
--- a/supacode/App/supacodeApp.swift
+++ b/supacode/App/supacodeApp.swift
@@ -589,7 +589,7 @@ struct SupacodeApp: App {
     }
 
     let detection = detectedAgent.detectScreen(in: activeText)
-    let canonicalScreen = AgentScreenSnapshot(canonicalText: agentDetectionRecentText(activeText))
+    let canonicalScreen = AgentScreenSnapshot(text: detectedAgent.detectionScreenText(from: activeText))
     let blockerText: String? =
       switch detectedAgent {
       case .codex: CodexScreenProfile.blockerText(in: canonicalScreen)
diff --git a/supacode/Domain/AgentDetection/AgentScreenSnapshot.swift b/supacode/Domain/AgentDetection/AgentScreenSnapshot.swift
index 801a1f6d..9c69816a 100644
--- a/supacode/Domain/AgentDetection/AgentScreenSnapshot.swift
+++ b/supacode/Domain/AgentDetection/AgentScreenSnapshot.swift
@@ -2,12 +2,11 @@ struct AgentScreenSnapshot: Equatable, Sendable {
   let text: String
   let lines: [String]
 
-  nonisolated init(canonicalText: String) {
-    assert(
-      canonicalText == agentDetectionRecentText(canonicalText),
-      "AgentScreenSnapshot requires canonical detector-tail text."
-    )
-    self.text = canonicalText
-    self.lines = canonicalText.split(separator: "\n", omittingEmptySubsequences: false).map(String.init)
+  /// `text` must be the exact detector input for the agent consuming this
+  /// snapshot — produce it with `DetectedAgent.detectionScreenText(from:)` so
+  /// state detection and blocker extraction always read the same screen.
+  nonisolated init(text: String) {
+    self.text = text
+    self.lines = text.split(separator: "\n", omittingEmptySubsequences: false).map(String.init)
   }
 }
diff --git a/supacode/Infrastructure/AgentDetection/ScreenHeuristics.swift b/supacode/Infrastructure/AgentDetection/ScreenHeuristics.swift
index f5f63eb9..c2e23049 100644
--- a/supacode/Infrastructure/AgentDetection/ScreenHeuristics.swift
+++ b/supacode/Infrastructure/AgentDetection/ScreenHeuristics.swift
@@ -7,8 +7,21 @@ extension DetectedAgent {
     detectScreen(in: screen).state
   }
 
+  /// The slice of the active screen this agent's detector consumes.
+  ///
+  /// Claude reads the full active screen: its rules are all region-anchored
+  /// (live status from the last rows above the composer, blockers from around
+  /// the prompt, chrome from the bottom lines), while the shared recent-line
+  /// tail is measured from the bottom — a long todo list plus a multi-line
+  /// status line pushes the live spinner row past the limit and a working
+  /// agent reads as idle. Every other detector matches with whole-text scans,
+  /// so the bounded tail stays on as their guard against transcript history.
+  nonisolated func detectionScreenText(from screen: String) -> String {
+    self == .claude ? screen : agentDetectionRecentText(screen)
+  }
+
   nonisolated func detectScreen(in screen: String) -> AgentScreenDetection {
-    let text = agentDetectionRecentText(screen)
+    let text = detectionScreenText(from: screen)
     let state: AgentRawState
     switch self {
     case .pi:
@@ -16,9 +29,9 @@ extension DetectedAgent {
     case .omp:
       state = detectOMP(text)
     case .claude:
-      return ClaudeScreenProfile.detect(in: AgentScreenSnapshot(canonicalText: text))
+      return ClaudeScreenProfile.detect(in: AgentScreenSnapshot(text: text))
     case .codex:
-      return CodexScreenProfile.detect(in: AgentScreenSnapshot(canonicalText: text))
+      return CodexScreenProfile.detect(in: AgentScreenSnapshot(text: text))
     case .gemini:
       state = detectGemini(text)
     case .cursor:
diff --git a/supacodeTests/AgentScreenFixtureCorpusTests.swift b/supacodeTests/AgentScreenFixtureCorpusTests.swift
index 1d189ac4..81e2c185 100644
--- a/supacodeTests/AgentScreenFixtureCorpusTests.swift
+++ b/supacodeTests/AgentScreenFixtureCorpusTests.swift
@@ -67,8 +67,8 @@ struct AgentScreenFixtureCorpusTests {
     #expect(!fixtures.isEmpty, "The captured screen corpus must not be empty.")
     for fixture in fixtures {
       #expect(
-        fixture.text == AgentScreenFixtureCorpus.canonicalTail(fixture.text),
-        "Fixture is not the canonical 24-non-empty-line detector tail: \(fixture.relativePath)"
+        fixture.text == fixture.agent.detectionScreenText(from: fixture.text),
+        "Fixture is not the exact detector input for its agent: \(fixture.relativePath)"
       )
 
       let actualState = fixture.agent.detectState(in: fixture.text)
@@ -148,10 +148,6 @@ enum AgentScreenFixtureCorpus {
     return fixtures
   }
 
-  static func canonicalTail(_ content: String) -> String {
-    agentDetectionRecentText(content)
-  }
-
   private static func loadFixture(at screenURL: URL, root: URL) throws -> AgentScreenFixture {
     let relativePath = relativePath(for: screenURL, root: root)
     let components = relativePath.split(separator: "/").map(String.init)
diff --git a/supacodeTests/ClaudeScreenProfileTests.swift b/supacodeTests/ClaudeScreenProfileTests.swift
index 9382ea5a..46977bd9 100644
--- a/supacodeTests/ClaudeScreenProfileTests.swift
+++ b/supacodeTests/ClaudeScreenProfileTests.swift
@@ -57,7 +57,7 @@ struct ClaudeScreenProfileTests {
   @Test func elapsedAndBackgroundWorkHaveDistinctReasons() {
     let elapsed = ClaudeScreenProfile.detect(
       in: AgentScreenSnapshot(
-        canonicalText: """
+        text: """
             ● Forging… (10s · thinking with high effort)
             ─────────
             ❯
@@ -70,7 +70,7 @@ struct ClaudeScreenProfileTests {
 
     let background = ClaudeScreenProfile.detect(
       in: AgentScreenSnapshot(
-        canonicalText: """
+        text: """
             Task complete.
             ─────────
             ❯
@@ -86,7 +86,7 @@ struct ClaudeScreenProfileTests {
   @Test func blockerOutranksRetainedSpinner() {
     let detection = ClaudeScreenProfile.detect(
       in: AgentScreenSnapshot(
-        canonicalText: """
+        text: """
             ✻ Tempering… (12s · esc to interrupt)
             Do you want to proceed?
             ❯ 1. Yes
@@ -105,7 +105,7 @@ struct ClaudeScreenProfileTests {
       .first { $0.relativePath == "claude/2.1.223/blocked/command-permission.txt" }
     let text = try #require(fixture).text
 
-    let blocker = ClaudeScreenProfile.blockerText(in: AgentScreenSnapshot(canonicalText: text))
+    let blocker = ClaudeScreenProfile.blockerText(in: AgentScreenSnapshot(text: text))
 
     #expect(blocker?.contains("Do you want to proceed?") == true)
     #expect(blocker?.contains("❯ 1. Yes") == true)
@@ -113,9 +113,40 @@ struct ClaudeScreenProfileTests {
     #expect(blocker?.contains("Esc to cancel · Tab to amend · ctrl+e to explain") == true)
   }
 
+  @Test func spinnerAboveLongTodoListStaysWorking() {
+    // Regression: the shared recent-line tail is measured from the bottom of the
+    // screen, so a long todo list plus the composer and a multi-line status line
+    // pushed the live spinner row out of the detector window and a working agent
+    // was reported idle (via the idle-composer rule).
+    var lines = [
+      "✻ Implementing hybridTopK… (5m 5s · ↓ 21.1k tokens)",
+      "  ⎿ \u{00A0}✔ Write failing tests for hybridTopK and per-scope pickCandidates",
+    ]
+    for index in 2...16 {
+      lines.append("     ◻ Todo item number \(index) still pending")
+    }
+    lines.append(
+      contentsOf: [
+        "──────────────────────────────────────────",
+        "❯ ",
+        "──────────────────────────────────────────",
+        "  [Fable 5 | Enterprise] ██░░░░░░░░ 16% | will git:(master*)",
+        "  ███░░░░░░░ 34% (4h 3m / 5h) | ███░░░░░░░ 29% (4d 19h / 7d)",
+        "  ✓ Bash ×7 | ✓ Read ×6 | ✓ Edit ×5",
+        "  ▸ Implement hybridTopK in similarity.ts (2/16)",
+        "  ⏵⏵ bypass permissions on (shift+tab to cycle) · ← for agents",
+      ]
+    )
+
+    let detection = DetectedAgent.claude.detectScreen(in: lines.joined(separator: "\n"))
+
+    #expect(detection.state == .working)
+    #expect(detection.reason == .matched(ClaudeScreenProfile.RuleID.spinner))
+  }
+
   @Test func unstructuredScreenUsesExplicitFallback() {
     let detection = ClaudeScreenProfile.detect(
-      in: AgentScreenSnapshot(canonicalText: "screen without live Claude chrome")
+      in: AgentScreenSnapshot(text: "screen without live Claude chrome")
     )
 
     #expect(detection.state == .idle)
diff --git a/supacodeTests/CodexScreenProfileTests.swift b/supacodeTests/CodexScreenProfileTests.swift
index 7f09d357..f59a583c 100644
--- a/supacodeTests/CodexScreenProfileTests.swift
+++ b/supacodeTests/CodexScreenProfileTests.swift
@@ -39,7 +39,7 @@ struct CodexScreenProfileTests {
   @Test func structuredChoicesExplainBlockedWithoutAFooter() {
     let detection = CodexScreenProfile.detect(
       in: AgentScreenSnapshot(
-        canonicalText: """
+        text: """
             Would you like to run the following command?
           › 1. Yes, proceed
             2. No, cancel
@@ -58,7 +58,7 @@ struct CodexScreenProfileTests {
 
     for fixture in fixtures {
       let blocker = CodexScreenProfile.blockerText(
-        in: AgentScreenSnapshot(canonicalText: agentDetectionRecentText(fixture.text))
+        in: AgentScreenSnapshot(text: agentDetectionRecentText(fixture.text))
       )
 
       #expect(blocker != nil)
@@ -75,7 +75,7 @@ struct CodexScreenProfileTests {
     )
 
     let blocker = CodexScreenProfile.blockerText(
-      in: AgentScreenSnapshot(canonicalText: agentDetectionRecentText(fixture.text))
+      in: AgentScreenSnapshot(text: agentDetectionRecentText(fixture.text))
     )
 
     #expect(blocker == nil)
@@ -84,7 +84,7 @@ struct CodexScreenProfileTests {
   @Test func blockerTextKeepsQuestionAboveLongWrappedInteraction() {
     let filler = (1...14).map { "  wrapped command detail \($0)" }.joined(separator: "\n")
     let snapshot = AgentScreenSnapshot(
-      canonicalText: agentDetectionRecentText(
+      text: agentDetectionRecentText(
         """
         Historical output that must not be returned.
 
@@ -110,7 +110,7 @@ struct CodexScreenProfileTests {
       .first { $0.relativePath == "codex/0.146.1/blocked/command-permission.txt" }
     let text = try #require(fixture).text
 
-    let blocker = CodexScreenProfile.blockerText(in: AgentScreenSnapshot(canonicalText: text))
+    let blocker = CodexScreenProfile.blockerText(in: AgentScreenSnapshot(text: text))
 
     #expect(blocker?.contains("Would you like to run the following command?") == true)
     #expect(blocker?.contains("Environment: local") == true)
-- 
2.51.2


From 5fea2d7836a2d9aa5d50be0e5e1ef83c9c095779 Mon Sep 17 00:00:00 2001
From: onevcat <onevcat@gmail.com>
Date: Sat, 15 Aug 2026 01:43:35 +0900
Subject: [PATCH 12/19] fix(detection): bound the Claude live status block by
 shape
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The full-screen change left the inner region cap in place: liveStatus
was still the last 3 logical rows above the composer, so one extra
queued message or tip row displaced the live spinner and a working
agent read as idle — the committed foreground-spinner fixture already
had zero slack. Removing the tail also let suffix(3) reach a status row
quoted inside a transcript block, pinning an idle pane at working.

Walk the block bottom-up from the composer instead, taking rows while
they keep live-chrome shape (spinner/"●" heads, "⎿" attachments, queued
"❯" messages, todo checkboxes) and stopping at the first
transcript-shaped row, which is what replaces the tail's false-positive
guard.

Also harden the seams the earlier commit loosened:
- DetectedAgent.detectionSnapshot(from:) is the one production entry
  point for building profile snapshots; the CLI read path and the codex
  tests go through it instead of hand-rolled slices.
- The corpus exactness check was x == x for Claude; check the
  full-screen invariant (line count <= captured terminal rows) instead,
  and keep the tail check for every other agent.
- Correct the detectionScreenText comment (codex's structured profile
  is region-anchored, not a whole-text scan) and pin the per-agent
  slice asymmetry with a direct test.
- Update the fixture capture README, docs/components/agent-detection.md,
  and amend docs-ai/030 (new 014 record).

New regression tests are red before this change: a spinner above a tip,
queued messages, and effort chrome read idle; a quoted spinner above a
transcript block read working.

Claude-Session: https://claude.ai/code/session_01N4XHurPXHrN2azgy3Rq7Q9
---
 .../009-captured-screen-fixture-corpus.md     |  4 ++
 .../012-claude-screen-profile.md              |  5 ++
 .../014-claude-full-screen-live-block.md      | 64 ++++++++++++++++++
 docs/components/agent-detection.md            | 12 +++-
 supacode/App/supacodeApp.swift                |  6 +-
 .../AgentDetection/AgentScreenSnapshot.swift  |  6 +-
 .../AgentDetection/ClaudeScreenProfile.swift  | 38 +++++++++--
 .../AgentDetection/ScreenHeuristics.swift     | 27 ++++++--
 .../AgentScreenFixtureCorpusTests.swift       | 22 +++++--
 supacodeTests/ClaudeScreenProfileTests.swift  | 66 +++++++++++++++++--
 supacodeTests/CodexScreenProfileTests.swift   | 12 ++--
 .../Fixtures/AgentScreenDetection/README.md   | 12 +++-
 supacodeTests/ScreenHeuristicsTests.swift     | 12 ++++
 13 files changed, 247 insertions(+), 39 deletions(-)
 create mode 100644 docs-ai/030-agent-status-detection/014-claude-full-screen-live-block.md

diff --git a/docs-ai/030-agent-status-detection/009-captured-screen-fixture-corpus.md b/docs-ai/030-agent-status-detection/009-captured-screen-fixture-corpus.md
index 47d0fcb0..ff10d8ac 100644
--- a/docs-ai/030-agent-status-detection/009-captured-screen-fixture-corpus.md
+++ b/docs-ai/030-agent-status-detection/009-captured-screen-fixture-corpus.md
@@ -1,5 +1,9 @@
 # 030.009 — Captured Screen Fixture Corpus and Baseline
 
+> Amended by [014-claude-full-screen-live-block.md](014-claude-full-screen-live-block.md):
+> the canonical-tail reduction below now applies to non-Claude fixtures only. Claude
+> fixtures are committed as full active screens, bounded by the captured terminal rows.
+
 | | |
 | --- | --- |
 | **Status** | Implemented |
diff --git a/docs-ai/030-agent-status-detection/012-claude-screen-profile.md b/docs-ai/030-agent-status-detection/012-claude-screen-profile.md
index 2037f659..84b8d8b3 100644
--- a/docs-ai/030-agent-status-detection/012-claude-screen-profile.md
+++ b/docs-ai/030-agent-status-detection/012-claude-screen-profile.md
@@ -1,5 +1,10 @@
 # 030.012 — Claude Screen Profile: Action
 
+> Amended by [014-claude-full-screen-live-block.md](014-claude-full-screen-live-block.md):
+> Claude now consumes the full active screen and the live status region is bounded by
+> row shape instead of `suffix(3)`; the canonical-tail contract and the Debug
+> canonical-tail assert described below no longer apply to Claude.
+
 | | |
 | --- | --- |
 | **Status** | Implemented |
diff --git a/docs-ai/030-agent-status-detection/014-claude-full-screen-live-block.md b/docs-ai/030-agent-status-detection/014-claude-full-screen-live-block.md
new file mode 100644
index 00000000..22c8e16d
--- /dev/null
+++ b/docs-ai/030-agent-status-detection/014-claude-full-screen-live-block.md
@@ -0,0 +1,64 @@
+# 014 — Claude full-screen input and the shape-bounded live status block
+
+Amends [009-captured-screen-fixture-corpus.md](009-captured-screen-fixture-corpus.md) and
+[012-claude-screen-profile.md](012-claude-screen-profile.md): the "canonical 24-line
+detector tail" contract those records describe now applies to **non-Claude agents
+only**. Claude detection consumes the full active screen, and the Debug canonical-tail
+assert on `AgentScreenSnapshot` was replaced by a single production construction seam.
+
+## Problem
+
+Two bottom-measured budgets could each cut the live signal off:
+
+1. The shared detector tail (`agentDetectionRecentText`, 24 non-empty lines from the
+   bottom). On a Claude screen the bottom is fixed chrome — composer, multi-line
+   statusline — plus the todo block under the spinner row. Past ~16 todo lines the
+   spinner fell out of the window and a working agent read as idle
+   (`claude.idleComposer`).
+2. The live status region itself, previously `claudeLogicalRows(above prompt).suffix(3)`.
+   The committed 2.1.223 `foreground-spinner` fixture already had zero slack (spinner,
+   queued `❯` message, `◉ xhigh · /effort`): one more queued message or `⎿ Tip:` row
+   displaced the spinner even with the tail removed.
+
+Both are the same defect: bounding a region the TUI sizes dynamically by a fixed count
+measured from the bottom.
+
+## Fix
+
+- `DetectedAgent.detectionScreenText(from:)` forks the slice policy: Claude gets the
+  full active screen (naturally bounded by terminal height via `GHOSTTY_POINT_ACTIVE`);
+  every other agent keeps the bounded tail as its guard against transcript history.
+- `DetectedAgent.detectionSnapshot(from:)` is the one production entry point for
+  building a profile snapshot, so state detection and blocker extraction always read
+  the same slice (`detectScreen` and the `agents read` CLI path both go through it).
+- The Claude live status region is bounded by **shape, not count**
+  (`ClaudeScreenRegions.liveStatusBlock`): logical rows above the composer are taken
+  bottom-up while they look like live chrome — spinner-scalar heads, `●` status rows,
+  `⎿` attachments, queued `❯` messages, todo checkboxes — and the scan stops at the
+  first transcript-shaped row (`⏺` blocks, `◯` rows, prose, borders).
+
+The stop condition is what replaces the tail's false-positive guard: a status row
+quoted inside a `⏺` block or prose sits above a non-chrome row, so the walk never
+reaches it. Known residual (accepted, present in every prior version too): a quoted
+status row that is itself the bottom-most logical row above the composer — with only
+chrome-shaped rows below it — still reads as live. Rules stay strict (`…` + complete
+elapsed segment), so completed rows like `✻ Crunched for 7s` never match.
+
+## Codex
+
+Codex's structured profile is region-anchored like Claude's and shares the
+bounded-bottom exposure in principle (its working footer has zero slack; a ~17-line
+approval dialog can push the question out of the tail). It keeps the tail until its
+regions are bounded by shape the same way; the `detectionScreenText` doc comment
+records this, and `detectionScreenTextSlicesPerAgent` pins the current asymmetry.
+
+## Corpus contract
+
+- Claude fixtures are full active screens: commit captures as read, never trimmed
+  (trimming can delete the row above the window that reproduces the bug). The corpus
+  check enforces the one mechanical invariant — line count ≤ captured terminal rows.
+- Non-Claude fixtures remain exact `agentDetectionRecentText` tails, checked as before.
+- The existing 2.1.22x Claude fixtures predate this change and are tail-shaped; they
+  stay valid as detector inputs (the detector accepts any screen) but new Claude
+  captures must be full screens. Capture step 6 in the fixture README describes the
+  per-agent reduction.
diff --git a/docs/components/agent-detection.md b/docs/components/agent-detection.md
index 8c29a9b4..a7afab95 100644
--- a/docs/components/agent-detection.md
+++ b/docs/components/agent-detection.md
@@ -33,11 +33,17 @@ at a `~/.grok/` install (so Cursor's own `agent` entrypoint stays Cursor).
 1. **Process probe.** Prowl reads the pane's foreground process group and matches
    process names / argv against known agent executables, scoring argv[0] highest,
    then process name, then command-line tokens.
-2. **Screen heuristics.** It starts from the last ~24 non-blank lines, then selects
+2. **Screen heuristics.** Claude detection consumes the full active screen (bounded
+   by the terminal height); every other agent starts from the last ~24 non-blank
+   lines as a guard against transcript history. The classifier then selects
    agent-specific live UI regions rather than treating every transcript line as current
    state. Structured confirmation/permission chrome is **Blocked**; status rows and
-   spinners are **Working**. Claude working rows are scoped to the lines immediately above
-   its prompt box, while confirmation text is consulted only around a current numbered
+   spinners are **Working**. Claude working rows come from a live status block walked
+   bottom-up from its prompt box by row shape — the spinner or `●` status row, `⎿`
+   attachments such as todo lists and tips, queued `❯` messages, and right-aligned
+   chrome — stopping at the first transcript-shaped row, so a long todo list cannot
+   push the live row out of view and a status row quoted inside a `⏺` block cannot
+   read as live. Confirmation text is consulted only around a current numbered
    selection row such as `❯ 1. Yes`; a bare input prompt cuts off the preceding transcript.
    Codex uses an exact bottom-of-screen `•`/`◦ Working (... esc to interrupt)` footer
    fallback. Its confirmation detector requires a numbered selected row such as `› 1. Yes`
diff --git a/supacode/App/supacodeApp.swift b/supacode/App/supacodeApp.swift
index 03ac7e1c..fd8ef05a 100644
--- a/supacode/App/supacodeApp.swift
+++ b/supacode/App/supacodeApp.swift
@@ -589,11 +589,11 @@ struct SupacodeApp: App {
     }
 
     let detection = detectedAgent.detectScreen(in: activeText)
-    let canonicalScreen = AgentScreenSnapshot(text: detectedAgent.detectionScreenText(from: activeText))
+    let detectorScreen = detectedAgent.detectionSnapshot(from: activeText)
     let blockerText: String? =
       switch detectedAgent {
-      case .codex: CodexScreenProfile.blockerText(in: canonicalScreen)
-      case .claude: ClaudeScreenProfile.blockerText(in: canonicalScreen)
+      case .codex: CodexScreenProfile.blockerText(in: detectorScreen)
+      case .claude: ClaudeScreenProfile.blockerText(in: detectorScreen)
       default: nil
       }
     if detection.state == .blocked, blockerText == nil {
diff --git a/supacode/Domain/AgentDetection/AgentScreenSnapshot.swift b/supacode/Domain/AgentDetection/AgentScreenSnapshot.swift
index 9c69816a..2058be41 100644
--- a/supacode/Domain/AgentDetection/AgentScreenSnapshot.swift
+++ b/supacode/Domain/AgentDetection/AgentScreenSnapshot.swift
@@ -3,8 +3,10 @@ struct AgentScreenSnapshot: Equatable, Sendable {
   let lines: [String]
 
   /// `text` must be the exact detector input for the agent consuming this
-  /// snapshot — produce it with `DetectedAgent.detectionScreenText(from:)` so
-  /// state detection and blocker extraction always read the same screen.
+  /// snapshot. Production call sites go through
+  /// `DetectedAgent.detectionSnapshot(from:)` so state detection and blocker
+  /// extraction always read the same slice; constructing one directly is for
+  /// tests feeding already-sliced synthetic screens.
   nonisolated init(text: String) {
     self.text = text
     self.lines = text.split(separator: "\n", omittingEmptySubsequences: false).map(String.init)
diff --git a/supacode/Infrastructure/AgentDetection/ClaudeScreenProfile.swift b/supacode/Infrastructure/AgentDetection/ClaudeScreenProfile.swift
index 5b5000eb..af1123e2 100644
--- a/supacode/Infrastructure/AgentDetection/ClaudeScreenProfile.swift
+++ b/supacode/Infrastructure/AgentDetection/ClaudeScreenProfile.swift
@@ -203,14 +203,22 @@ private struct ClaudeScreenRegions: Sendable {
     )
     self.currentInteractionLines = currentInteractionLines
     self.currentInteractionLower = currentInteractionLines.joined(separator: "\n").lowercased()
-    // Reconstruct rows before limiting the region. Counting the limit in physical
-    // lines drops the head of any row that wraps onto three or more continuations,
+    // Reconstruct rows before selecting the region. Counting in physical lines
+    // drops the head of any row that wraps onto three or more continuations,
     // and the head is what carries the "●" or spinner glyph the rules key on.
     // Widths that narrow are reachable: a surface can be as few as five columns.
-    self.liveStatus = claudeLogicalRows(
-      Self.contentAbovePrompt(screenLines: lines, promptIndex: promptIndex)
+    //
+    // The block is then bounded by shape, not by count. The TUI paints live
+    // status as a trailing run of chrome-headed rows directly above the
+    // composer, so rows are taken bottom-up while they keep that shape. A
+    // fixed row count put an upper bound on the block — one extra queued "❯"
+    // message or "⎿" tip row displaced the live spinner and a working agent
+    // read as idle — while stopping at the first transcript-shaped row keeps
+    // a status row quoted inside a "⏺" block or prose from matching now that
+    // Claude detection reads the full active screen.
+    self.liveStatus = Self.liveStatusBlock(
+      claudeLogicalRows(Self.contentAbovePrompt(screenLines: lines, promptIndex: promptIndex))
     )
-    .suffix(3)
     .joined(separator: "\n")
     self.belowPromptLines = Self.contentBelowPrompt(screenLines: lines, promptIndex: promptIndex)
       .split(separator: "\n", omittingEmptySubsequences: false)
@@ -222,6 +230,14 @@ private struct ClaudeScreenRegions: Sendable {
     self.hasIdleComposer = Self.hasIdleComposer(screenLines: lines, promptIndex: promptIndex)
   }
 
+  nonisolated private static func liveStatusBlock(_ rows: [String]) -> ArraySlice<String> {
+    var start = rows.endIndex
+    while start > rows.startIndex, isClaudeLiveChromeRow(rows[start - 1]) {
+      start -= 1
+    }
+    return rows[start...]
+  }
+
   nonisolated private static func currentInteractionLines(
     screenLines: [String],
     promptIndex: Int?
@@ -317,6 +333,18 @@ nonisolated private func claudeRowStartsNewRow(_ trimmed: String) -> Bool {
   return "●⏺◯⎿❯─-".unicodeScalars.contains(first)
 }
 
+// Rows the TUI paints below the transcript while a turn is live: the spinner
+// or "●" status row, "⎿" attachments (todo lists, tips), queued "❯" messages,
+// todo checkboxes when they surface as their own rows, and right-aligned
+// chrome such as "◉ xhigh · /effort" (whose head is a spinner scalar). "⏺"
+// transcript blocks, "◯" agent-switcher rows, prose, and borders end the live
+// block: everything above them is history, however status-shaped it looks.
+nonisolated private func isClaudeLiveChromeRow(_ row: String) -> Bool {
+  guard let first = row.unicodeScalars.first else { return false }
+  if isAgentSpinnerScalar(first) { return true }
+  return "●⎿❯◻☐✔✘".unicodeScalars.contains(first)
+}
+
 nonisolated private func isClaudeNumberedSelectionLine(_ line: String) -> Bool {
   let trimmed = line.trimmingCharacters(in: .whitespaces)
   guard trimmed.first == "❯" else { return false }
diff --git a/supacode/Infrastructure/AgentDetection/ScreenHeuristics.swift b/supacode/Infrastructure/AgentDetection/ScreenHeuristics.swift
index c2e23049..485f6f71 100644
--- a/supacode/Infrastructure/AgentDetection/ScreenHeuristics.swift
+++ b/supacode/Infrastructure/AgentDetection/ScreenHeuristics.swift
@@ -9,17 +9,30 @@ extension DetectedAgent {
 
   /// The slice of the active screen this agent's detector consumes.
   ///
-  /// Claude reads the full active screen: its rules are all region-anchored
-  /// (live status from the last rows above the composer, blockers from around
-  /// the prompt, chrome from the bottom lines), while the shared recent-line
-  /// tail is measured from the bottom — a long todo list plus a multi-line
-  /// status line pushes the live spinner row past the limit and a working
-  /// agent reads as idle. Every other detector matches with whole-text scans,
-  /// so the bounded tail stays on as their guard against transcript history.
+  /// Claude reads the full active screen: its rules are region-anchored (the
+  /// live status block is walked bottom-up from the composer by row shape,
+  /// blockers around the prompt, viewer chrome from the bottom lines), so a
+  /// bottom-measured line budget added no false-positive guard — it only cut
+  /// the live signal off when a long todo list plus a multi-line status line
+  /// pushed the spinner row past the limit and a working agent read as idle.
+  ///
+  /// Every other detector keeps the bounded tail as its guard against
+  /// transcript history. For the legacy scanners the tail is load-bearing —
+  /// they match with whole-text scans. Codex's structured profile anchors
+  /// its windows inside the tail instead; it shares Claude's bounded-bottom
+  /// exposure in principle and keeps the tail until its regions are bounded
+  /// by shape the same way.
   nonisolated func detectionScreenText(from screen: String) -> String {
     self == .claude ? screen : agentDetectionRecentText(screen)
   }
 
+  /// The one production entry point for building a profile snapshot. State
+  /// detection and blocker extraction must read the same slice; going through
+  /// this keeps a call site from pairing a profile with the wrong one.
+  nonisolated func detectionSnapshot(from screen: String) -> AgentScreenSnapshot {
+    AgentScreenSnapshot(text: detectionScreenText(from: screen))
+  }
+
   nonisolated func detectScreen(in screen: String) -> AgentScreenDetection {
     let text = detectionScreenText(from: screen)
     let state: AgentRawState
diff --git a/supacodeTests/AgentScreenFixtureCorpusTests.swift b/supacodeTests/AgentScreenFixtureCorpusTests.swift
index 81e2c185..6be5abb0 100644
--- a/supacodeTests/AgentScreenFixtureCorpusTests.swift
+++ b/supacodeTests/AgentScreenFixtureCorpusTests.swift
@@ -66,10 +66,24 @@ struct AgentScreenFixtureCorpusTests {
 
     #expect(!fixtures.isEmpty, "The captured screen corpus must not be empty.")
     for fixture in fixtures {
-      #expect(
-        fixture.text == fixture.agent.detectionScreenText(from: fixture.text),
-        "Fixture is not the exact detector input for its agent: \(fixture.relativePath)"
-      )
+      // The corpus must hold exact production detector inputs. For agents
+      // that consume the bounded tail this is checkable directly; for Claude
+      // the tail check is x == x, so the enforceable invariant is that a
+      // full-active-screen capture cannot exceed the captured viewport.
+      if fixture.agent == .claude {
+        let lineCount = fixture.text
+          .split(separator: "\n", omittingEmptySubsequences: false)
+          .count
+        #expect(
+          lineCount <= fixture.metadata.terminal.rows,
+          "Claude fixtures are full screens and cannot exceed the captured terminal rows: \(fixture.relativePath)"
+        )
+      } else {
+        #expect(
+          fixture.text == fixture.agent.detectionScreenText(from: fixture.text),
+          "Fixture is not the exact detector input for its agent: \(fixture.relativePath)"
+        )
+      }
 
       let actualState = fixture.agent.detectState(in: fixture.text)
       let mismatchMessage =
diff --git a/supacodeTests/ClaudeScreenProfileTests.swift b/supacodeTests/ClaudeScreenProfileTests.swift
index 46977bd9..de67816d 100644
--- a/supacodeTests/ClaudeScreenProfileTests.swift
+++ b/supacodeTests/ClaudeScreenProfileTests.swift
@@ -114,15 +114,16 @@ struct ClaudeScreenProfileTests {
   }
 
   @Test func spinnerAboveLongTodoListStaysWorking() {
-    // Regression: the shared recent-line tail is measured from the bottom of the
-    // screen, so a long todo list plus the composer and a multi-line status line
-    // pushed the live spinner row out of the detector window and a working agent
-    // was reported idle (via the idle-composer rule).
+    // Regression: a bottom-measured line budget (the shared recent-line tail)
+    // let a long todo list plus the composer and a multi-line status line push
+    // the live spinner row out of the detector window, so a working agent was
+    // reported idle via the idle-composer rule. The todo block is sized from
+    // the tail limit so this screen keeps overflowing it if the limit moves.
     var lines = [
       "✻ Implementing hybridTopK… (5m 5s · ↓ 21.1k tokens)",
       "  ⎿ \u{00A0}✔ Write failing tests for hybridTopK and per-scope pickCandidates",
     ]
-    for index in 2...16 {
+    for index in 2...(agentDetectionRecentLineLimit + 2) {
       lines.append("     ◻ Todo item number \(index) still pending")
     }
     lines.append(
@@ -137,6 +138,8 @@ struct ClaudeScreenProfileTests {
         "  ⏵⏵ bypass permissions on (shift+tab to cycle) · ← for agents",
       ]
     )
+    let nonBlankCount = lines.count { $0.contains { !$0.isWhitespace } }
+    #expect(nonBlankCount > agentDetectionRecentLineLimit)
 
     let detection = DetectedAgent.claude.detectScreen(in: lines.joined(separator: "\n"))
 
@@ -144,6 +147,59 @@ struct ClaudeScreenProfileTests {
     #expect(detection.reason == .matched(ClaudeScreenProfile.RuleID.spinner))
   }
 
+  @Test func spinnerAboveQueuedMessagesAndTipStaysWorking() {
+    // The live status block is bounded by row shape, not by a fixed row
+    // count: a "⎿" tip attachment, queued "❯" messages, and the right-aligned
+    // effort chrome all belong to the block and must not displace the spinner.
+    let text = """
+      ⏺ Running 1 shell command…
+        ⎿  $ touch permission-probe.txt
+
+      ✻ Slithering… (16s · ↓ 21.1k tokens)
+        ⎿  Tip: Use ctrl+v to paste images from your clipboard
+
+        ❯ Run the shell command `sleep 8`, then reply exactly DONE.
+        ❯ Then summarize the diff in one line.
+                                                        ◉ xhigh · /effort
+      ──────────────────────────────────────────
+      ❯ Press up to edit queued messages
+      ──────────────────────────────────────────
+      """
+
+    let detection = DetectedAgent.claude.detectScreen(in: text)
+
+    #expect(detection.state == .working)
+    #expect(detection.reason == .matched(ClaudeScreenProfile.RuleID.spinner))
+  }
+
+  @Test func spinnerQuotedAboveTranscriptBlockStaysIdle() {
+    // A status row quoted in the transcript sits above a "⏺" block head. The
+    // live block scan stops at that head, so reading the full active screen
+    // must not resurrect the quoted spinner as live activity.
+    var lines = [
+      "✻ Tempering… (12s · esc to interrupt)",
+      "",
+      "⏺ Here is the analysis:",
+    ]
+    lines.append(contentsOf: (1...20).map { "    analysis detail line \($0)" })
+    lines.append(
+      contentsOf: [
+        "",
+        "✻ Crunched for 7s",
+        "",
+        "──────────────────────────────────────────",
+        "❯ ",
+        "──────────────────────────────────────────",
+        "  ⏸ manual mode on · ← for agents",
+      ]
+    )
+
+    let detection = DetectedAgent.claude.detectScreen(in: lines.joined(separator: "\n"))
+
+    #expect(detection.state == .idle)
+    #expect(detection.reason == .matched(ClaudeScreenProfile.RuleID.idleComposer))
+  }
+
   @Test func unstructuredScreenUsesExplicitFallback() {
     let detection = ClaudeScreenProfile.detect(
       in: AgentScreenSnapshot(text: "screen without live Claude chrome")
diff --git a/supacodeTests/CodexScreenProfileTests.swift b/supacodeTests/CodexScreenProfileTests.swift
index f59a583c..535c6257 100644
--- a/supacodeTests/CodexScreenProfileTests.swift
+++ b/supacodeTests/CodexScreenProfileTests.swift
@@ -58,7 +58,7 @@ struct CodexScreenProfileTests {
 
     for fixture in fixtures {
       let blocker = CodexScreenProfile.blockerText(
-        in: AgentScreenSnapshot(text: agentDetectionRecentText(fixture.text))
+        in: DetectedAgent.codex.detectionSnapshot(from: fixture.text)
       )
 
       #expect(blocker != nil)
@@ -75,7 +75,7 @@ struct CodexScreenProfileTests {
     )
 
     let blocker = CodexScreenProfile.blockerText(
-      in: AgentScreenSnapshot(text: agentDetectionRecentText(fixture.text))
+      in: DetectedAgent.codex.detectionSnapshot(from: fixture.text)
     )
 
     #expect(blocker == nil)
@@ -83,9 +83,8 @@ struct CodexScreenProfileTests {
 
   @Test func blockerTextKeepsQuestionAboveLongWrappedInteraction() {
     let filler = (1...14).map { "  wrapped command detail \($0)" }.joined(separator: "\n")
-    let snapshot = AgentScreenSnapshot(
-      text: agentDetectionRecentText(
-        """
+    let snapshot = DetectedAgent.codex.detectionSnapshot(
+      from: """
         Historical output that must not be returned.
 
           Would you like to run the following command?
@@ -95,7 +94,6 @@ struct CodexScreenProfileTests {
 
           Press enter to confirm or esc to cancel
         """
-      )
     )
 
     let blocker = CodexScreenProfile.blockerText(in: snapshot)
@@ -110,7 +108,7 @@ struct CodexScreenProfileTests {
       .first { $0.relativePath == "codex/0.146.1/blocked/command-permission.txt" }
     let text = try #require(fixture).text
 
-    let blocker = CodexScreenProfile.blockerText(in: AgentScreenSnapshot(text: text))
+    let blocker = CodexScreenProfile.blockerText(in: DetectedAgent.codex.detectionSnapshot(from: text))
 
     #expect(blocker?.contains("Would you like to run the following command?") == true)
     #expect(blocker?.contains("Environment: local") == true)
diff --git a/supacodeTests/Fixtures/AgentScreenDetection/README.md b/supacodeTests/Fixtures/AgentScreenDetection/README.md
index 01dfd8a3..34ef3d86 100644
--- a/supacodeTests/Fixtures/AgentScreenDetection/README.md
+++ b/supacodeTests/Fixtures/AgentScreenDetection/README.md
@@ -32,9 +32,15 @@ derived from `idle + unseen` and is never a fixture state.
 4. Keep the raw response under the ignored `.local/agent-screen-captures/` directory.
 5. Record exact CLI version, capture timestamp, terminal rows/columns, and the redaction
    summary in a same-basename metadata file.
-6. Reduce the capture with the production `agentDetectionRecentText` helper: start at
-   the 24th non-empty line from the bottom when at least 24 exist; otherwise retain the
-   whole screen. Keep blank lines and trailing screen rows inside that window.
+6. Reduce the capture to the exact production detector input for the agent
+   (`DetectedAgent.detectionScreenText(from:)`):
+   - `claude` consumes the full active screen. Commit the capture as read, without
+     trimming; it must not exceed the terminal rows recorded in metadata. Trimming a
+     Claude capture can delete the very row above the window that reproduces a bug.
+   - Every other agent consumes the bounded tail produced by the production
+     `agentDetectionRecentText` helper: start at the 24th non-empty line from the
+     bottom when at least 24 exist; otherwise retain the whole screen. Keep blank
+     lines and trailing screen rows inside that window.
 7. Redact paths, repositories, account identifiers, and all real-session prompts/model
    output without changing runtime chrome, line ordering, markers, wrapping, or blank-line
    boundaries. Deliberately scripted probe interactions from disposable workspaces may
diff --git a/supacodeTests/ScreenHeuristicsTests.swift b/supacodeTests/ScreenHeuristicsTests.swift
index 04b283c2..1706e48a 100644
--- a/supacodeTests/ScreenHeuristicsTests.swift
+++ b/supacodeTests/ScreenHeuristicsTests.swift
@@ -8,6 +8,18 @@ struct ScreenHeuristicsTests {
     #expect(agent?.detectState(in: "Working...") ?? .unknown == .unknown)
   }
 
+  @Test func detectionScreenTextSlicesPerAgent() {
+    // Pin the slice asymmetry: Claude consumes the full active screen, every
+    // other detector consumes the bounded tail. Widening the full-screen
+    // branch to a whole-text scanner must fail here, not ship silently.
+    let screen = (1...(agentDetectionRecentLineLimit * 2)).map { "line \($0)" }.joined(separator: "\n")
+
+    #expect(DetectedAgent.claude.detectionScreenText(from: screen) == screen)
+    #expect(DetectedAgent.codex.detectionScreenText(from: screen) == agentDetectionRecentText(screen))
+    #expect(DetectedAgent.codex.detectionScreenText(from: screen) != screen)
+    #expect(DetectedAgent.gemini.detectionScreenText(from: screen) == agentDetectionRecentText(screen))
+  }
+
   @Test func piDetection() {
     #expect(DetectedAgent.pi.detectState(in: "Working...") == .working)
     #expect(DetectedAgent.pi.detectState(in: "⠹ Working...") == .working)
-- 
2.51.2


From df663079da639ef1cd7267895adca1908c0bec7e Mon Sep 17 00:00:00 2001
From: onevcat <onevcat@gmail.com>
Date: Sat, 15 Aug 2026 09:31:08 +0900
Subject: [PATCH 13/19] Sync docs for 2026.8.15

Claude-Session: https://claude.ai/code/session_01LnVsnEMTfYf9rpRqjPdXvR
---
 docs/.sync-meta.json | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/.sync-meta.json b/docs/.sync-meta.json
index cce7cc5c..d4bcaa23 100644
--- a/docs/.sync-meta.json
+++ b/docs/.sync-meta.json
@@ -1,6 +1,6 @@
 {
   "_comment": "Metadata for the docs/ manual. The last_synced_commit is the commit at which docs/ was last verified against the implementation; the sync-docs skill (.claude/skills/sync-docs/SKILL.md) diffs HEAD against it and updates this file. Committed to git on purpose so the baseline persists across sessions and machines. A dotfile + .json so a future docs website does not render it as a page.",
-  "last_synced_commit": "4c2239257b235f89924d9207e73664ef3a480caa",
-  "last_synced_date": "2026-08-09",
-  "note": "Verified the agent-detection profile stack + unified toolbar range (PRs #683-#689): user-facing changes (prowl read --source detection, agents detection_reason JSON field, toolbar branch-item removal, Rename Branch context-menu entry) had docs maintained in-branch; no doc edits needed, baseline bump only."
+  "last_synced_commit": "ab7470396f2c04744e58a8d4ed966375be04ede5",
+  "last_synced_date": "2026-08-15",
+  "note": "Verified the agent transcript snapshots + Claude detection + Canvas link range (PRs #691, #696-#698): user-facing changes (prowl agents read, --result-only/--max-bytes, Claude live status block shape walk, Canvas cmd-click link priority) had docs maintained in-branch; no doc edits needed, baseline bump only."
 }
-- 
2.51.2


From e44303be5512d1213daa3b818db0fc8ceb1349a7 Mon Sep 17 00:00:00 2001
From: onevcat <onevcat@gmail.com>
Date: Sat, 15 Aug 2026 09:32:51 +0900
Subject: [PATCH 14/19] bump v2026.8.15

---
 supacode.xcodeproj/project.pbxproj            | 16 ++++++++--------
 supacode/CLIService/Shared/ProwlVersion.swift |  2 +-
 2 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/supacode.xcodeproj/project.pbxproj b/supacode.xcodeproj/project.pbxproj
index d24e4e9c..6d74461d 100644
--- a/supacode.xcodeproj/project.pbxproj
+++ b/supacode.xcodeproj/project.pbxproj
@@ -477,7 +477,7 @@
 				CODE_SIGN_STYLE = Automatic;
 				COMBINE_HIDPI_IMAGES = YES;
 				COMPILATION_CACHE_ENABLE_CACHING = YES;
-				CURRENT_PROJECT_VERSION = 20260809;
+				CURRENT_PROJECT_VERSION = 20260815;
 				DEAD_CODE_STRIPPING = YES;
 				DEBUG_INFORMATION_FORMAT = dwarf;
 				DEVELOPMENT_TEAM = "";
@@ -502,7 +502,7 @@
 					"@executable_path/../Frameworks",
 				);
 				MACOSX_DEPLOYMENT_TARGET = 26.0;
-				MARKETING_VERSION = 2026.8.9;
+				MARKETING_VERSION = 2026.8.15;
 				OTHER_LDFLAGS = (
 					"$(inherited)",
 					"-lc++",
@@ -537,7 +537,7 @@
 				CODE_SIGN_STYLE = Automatic;
 				COMBINE_HIDPI_IMAGES = YES;
 				COMPILATION_CACHE_ENABLE_CACHING = NO;
-				CURRENT_PROJECT_VERSION = 20260809;
+				CURRENT_PROJECT_VERSION = 20260815;
 				DEAD_CODE_STRIPPING = YES;
 				DEBUG_INFORMATION_FORMAT = "dwarf-with-dsym";
 				DEVELOPMENT_TEAM = "";
@@ -560,7 +560,7 @@
 					"@executable_path/../Frameworks",
 				);
 				MACOSX_DEPLOYMENT_TARGET = 26.0;
-				MARKETING_VERSION = 2026.8.9;
+				MARKETING_VERSION = 2026.8.15;
 				OTHER_LDFLAGS = (
 					"$(inherited)",
 					"-lc++",
@@ -590,12 +590,12 @@
 			buildSettings = {
 				BUNDLE_LOADER = "$(TEST_HOST)";
 				CODE_SIGN_STYLE = Automatic;
-				CURRENT_PROJECT_VERSION = 20260809;
+				CURRENT_PROJECT_VERSION = 20260815;
 				DEAD_CODE_STRIPPING = YES;
 				DEVELOPMENT_TEAM = "";
 				GENERATE_INFOPLIST_FILE = YES;
 				MACOSX_DEPLOYMENT_TARGET = 26.1;
-				MARKETING_VERSION = 2026.8.9;
+				MARKETING_VERSION = 2026.8.15;
 				PRODUCT_BUNDLE_IDENTIFIER = com.onevcat.prowlTests;
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				STRING_CATALOG_GENERATE_SYMBOLS = NO;
@@ -612,12 +612,12 @@
 			buildSettings = {
 				BUNDLE_LOADER = "$(TEST_HOST)";
 				CODE_SIGN_STYLE = Automatic;
-				CURRENT_PROJECT_VERSION = 20260809;
+				CURRENT_PROJECT_VERSION = 20260815;
 				DEAD_CODE_STRIPPING = YES;
 				DEVELOPMENT_TEAM = "";
 				GENERATE_INFOPLIST_FILE = YES;
 				MACOSX_DEPLOYMENT_TARGET = 26.1;
-				MARKETING_VERSION = 2026.8.9;
+				MARKETING_VERSION = 2026.8.15;
 				PRODUCT_BUNDLE_IDENTIFIER = com.onevcat.prowlTests;
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				STRING_CATALOG_GENERATE_SYMBOLS = NO;
diff --git a/supacode/CLIService/Shared/ProwlVersion.swift b/supacode/CLIService/Shared/ProwlVersion.swift
index be62ed0a..2c7a70a9 100644
--- a/supacode/CLIService/Shared/ProwlVersion.swift
+++ b/supacode/CLIService/Shared/ProwlVersion.swift
@@ -1,5 +1,5 @@
 // Auto-generated by Makefile (sync-cli-version). Do not edit.
 
 public enum ProwlVersion {
-  public static let current = "2026.8.9"
+  public static let current = "2026.8.15"
 }
-- 
2.51.2


From 739e860009c8ee1031654d1735c26534decff6e3 Mon Sep 17 00:00:00 2001
From: onevcat <onevcat@gmail.com>
Date: Sat, 15 Aug 2026 09:32:53 +0900
Subject: [PATCH 15/19] Update CHANGELOG for 2026.8.15

---
 CHANGELOG.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 246e36be..36605756 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,17 @@
 # Changelog
 
+## [2026.8.15](https://github.com/onevcat/Prowl/releases/tag/v2026.8.15)
+
+Improved detection accuracy for Claude Code sessions, plus a new CLI command for reading agent results.
+
+### New
+- `prowl agents read <pane>` (CLI): get an immediate, read-only snapshot of a Codex or Claude Code pane's current status and completed result text. Use `--result-only` to pull just the trusted final output, e.g. for piping into scripts.
+
+### Fixed
+- Claude Code panes with a long todo list no longer flash to Idle while a spinner is still actively running.
+- Claude Code panes waiting on a background agent, or showing multi-word elapsed-time status text, are now correctly detected as working instead of Idle.
+- Cmd-clicking a terminal link in Canvas no longer requires repeated clicks or misfires on the wrong link.
+
 ## [2026.8.9](https://github.com/onevcat/Prowl/releases/tag/v2026.8.9)
 
 This release streamlines the toolbar layout and improves the accuracy of agent status detection for Claude and Codex.
-- 
2.51.2


From 7ed4e158418bd9ad31ceea340d0819a744d0009e Mon Sep 17 00:00:00 2001
From: onevcat <onevcat@gmail.com>
Date: Sun, 16 Aug 2026 13:45:03 +0900
Subject: [PATCH 16/19] docs: plan CLI target contract governance

---
 .../000-plan.md                               | 332 ++++++++++++++++++
 docs-ai/README.md                             |   1 +
 2 files changed, 333 insertions(+)
 create mode 100644 docs-ai/060-prowl-cli-targeting-and-contract-governance/000-plan.md

diff --git a/docs-ai/060-prowl-cli-targeting-and-contract-governance/000-plan.md b/docs-ai/060-prowl-cli-targeting-and-contract-governance/000-plan.md
new file mode 100644
index 00000000..d5ce6a5e
--- /dev/null
+++ b/docs-ai/060-prowl-cli-targeting-and-contract-governance/000-plan.md
@@ -0,0 +1,332 @@
+# 060 — Prowl CLI Targeting and Contract Governance: Plan
+
+| | |
+| --- | --- |
+| **Status** | Proposed — pending product/API alignment |
+| **Anchor date** | 2026-08-16 |
+| **Primary PRs** | TBD |
+| **Related** | [013 — Prowl CLI](../013-prowl-cli/000-plan.md), [046 — CLI Short Handles](../046-cli-short-handles/000-plan.md), [047 — Cross-Agent Handoff](../047-cross-agent-handoff/000-plan.md), [059 — Agent Transcript Snapshots](../059-agent-transcript-snapshots/000-plan.md), [`docs/components/cli.md`](../../docs/components/cli.md) |
+
+## Background
+
+Prowl's local CLI began with UUID-oriented, app-side target resolution. The original
+contract goals were one grammar for humans and agents, typed parsing, a stable JSON
+surface, and no hidden selector precedence. The implementation retains those useful
+foundations, but capability growth split the public targeting language:
+
+- `--pane <uuid|pN|N>` and `--tab <uuid|tN|N>` accept short handles.
+- `--target` and positional auto-targets accept only pane/tab UUIDs or worktree
+  id/name/path; `pN` and `tN` are not recognized there.
+- `prowl agents read <pN|pane-uuid>` intentionally accepts a positional `pN` so a
+  caller can directly consume text `prowl agents` output, but accepts no selector flags.
+- `send` and `key` also overload positional argument count: one argument is payload for
+  the focused pane, while two arguments make the first an auto-target.
+
+Consequently, a user can run `prowl agents read p12`, but must write
+`prowl read --pane p12`; `prowl read p12` does not resolve the pane. Worse, a generic
+`p12` is still eligible to match a worktree named `p12`. This is an avoidable mismatch
+between the handle Prowl displays and the target syntax users naturally try.
+
+This entry governs the target-language correction and the contract/documentation
+rebaseline required to keep it correct as the CLI expands. It does not itself change
+runtime behavior. Until implementation lands, the shipped binary and
+`docs/components/cli.md` describe current behavior.
+
+## Current State
+
+### Command surface
+
+The current binary exposes these executable forms:
+
+| Area | Forms | Target behavior |
+| --- | --- | --- |
+| Entry and discovery | `prowl [path]`, `prowl open [path]`, `prowl list`, `prowl agents` | `open` consumes a path; discovery commands are global. |
+| Pane interaction | `focus`, `read`, `send`, `key` | Shared selectors; selected forms also accept an auto-target position. |
+| Semantic agent inspection | `agents read <pN|pane-uuid>` | Required explicit agent pane; no focus/worktree/tab fallback. |
+| Terminal lifecycle | `tab create`, `tab close`, `pane close` | Shared selectors; close requires one explicit selector. |
+| Handoff | `handoff save`, `handoff to <agent>` | Shared selectors or an auto-target positional source; absent selector means the calling pane, not UI focus. |
+
+`--json` and `--no-color` are common leaf-command output options. `send` adds
+`--no-enter`, `--no-wait`, `--capture`, and `--timeout`; `key` adds `--repeat`; `read`
+adds snapshot/stability options; close adds `--force`; and handoff adds briefing and
+launch options.
+
+### Current shared selector model
+
+| Form | Current accepted values |
+| --- | --- |
+| `--pane` | pane UUID, `pN`, bare `N` |
+| `--tab` | tab UUID, `tN`, bare `N` |
+| `--worktree` | worktree id, name, or path |
+| `-t` / `--target` | pane UUID, tab UUID, or worktree id/name/path |
+| Existing positional auto-targets | pane UUID, tab UUID, or worktree id/name/path |
+
+Selectors are mutually exclusive. The current implementation rejects a positional target
+combined with any selector flag. This is stricter than older contract text that said a
+flag would override the positional value.
+
+No-selector behavior is intentionally command-specific:
+
+- `focus`, `read`, `send`, `key`, and `tab create` resolve the current UI focus.
+- `tab close` and `pane close` reject an omitted selector.
+- `handoff` resolves the pane that spawned the CLI process; it never guesses UI focus.
+- `agents read` requires an explicit agent pane.
+
+### How the inconsistency arose
+
+1. **013 — v1 CLI** established `TargetSelector`, typed CLI parsing, app-owned
+   resolution, UUID JSON identity, and positional/flag auto-targets.
+2. **Auto-target follow-up** added target-first forms such as
+   `prowl send <uuid> "text"` and `prowl read <uuid>`.
+3. **046 — short handles** correctly preserved UUID JSON identity and made handles
+   process-scoped and non-reusable. To preserve a worktree named with a bare number,
+   it restricted *both* bare numeric handles and prefixed `pN`/`tN` to `--pane` and
+   `--tab`.
+4. **059 — agent snapshots** deliberately made `agents read <pN|uuid>` a narrow,
+   immediate semantic-inspection command. This was locally ergonomic, but made the
+   global discrepancy visible.
+5. **047 handoff hardening** changed selector-plus-positional parsing from precedence to
+   rejection for target isolation. The code and tests changed, but the older input
+   contract still describes precedence in several places.
+
+The important correction is not to abandon short handles or UUIDs. It is to distinguish
+an unambiguous prefixed handle from an ambiguous bare number.
+
+## Goals
+
+- Give every command that accepts a **generic target** one shared, documented target
+  language.
+- Make `pN` and `tN` work wherever the existing generic auto-target language works:
+  `--target`, target-first positional forms, and future generic-target commands.
+- Preserve UUIDs as the stable JSON and scripting identity; short handles remain
+  process-scoped interaction shorthand.
+- Preserve the safety reasons for command-specific exceptions: explicit agent inspection,
+  explicit close, and caller-pane handoff source resolution.
+- Re-establish a complete, current, testable contract set covering the actual command
+  surface and make the user manual, CLI help, and agent skill agree.
+- Establish an ownership and verification workflow so later CLI growth cannot introduce
+  another undocumented grammar fork.
+
+### Non-goals
+
+- Replacing UUIDs in JSON with handles, persisting handles, or making them valid across
+  a Prowl restart.
+- Adding a selector query language, title-based targeting, remote transport, streaming
+  reads, or a new agent-control namespace.
+- Changing `agents read` from an immediate semantic snapshot into a generic terminal
+  reader.
+- Changing handoff's caller-pane source rule or weakening explicit-close protections.
+- Broadening this work into terminal layout, agent-session, or worktree lifecycle
+  redesign.
+
+## Proposed Targeting Model
+
+### One lexical target reference language
+
+For every existing or future generic auto-target position, define:
+
+```text
+GenericTarget ::= PaneUUID | TabUUID | PaneHandle | TabHandle | WorktreeRef
+PaneHandle    ::= "p" PositiveInteger
+TabHandle     ::= "t" PositiveInteger
+WorktreeRef   ::= worktree id | name | path
+```
+
+Resolution is type-directed for prefixed handles, then preserves the current UUID and
+worktree behavior:
+
+1. `pN` resolves only as a pane handle.
+2. `tN` resolves only as a tab handle.
+3. A UUID tries pane, then tab.
+4. Any other value resolves as a worktree id, name, or path.
+
+A bare `N` is deliberately **not** a generic handle. It remains eligible as a worktree
+reference, while typed flags retain their existing convenience:
+
+```text
+--pane <uuid|pN|N>
+--tab  <uuid|tN|N>
+```
+
+The recommended compatibility policy is to reserve valid `pN` and `tN` spellings for
+handles in generic contexts. A stale `pN` must fail as a stale pane handle; it must not
+silently act on a worktree named `pN`. A worktree with such a name remains addressable
+unambiguously as `--worktree p12`. This is a narrowly scoped behavior change that
+prevents stale interactive handles from retargeting a command.
+
+### Command grammar after the correction
+
+The existing command shapes stay intact; only their `GenericTarget` slots expand:
+
+```bash
+prowl focus p12
+prowl read p12 --last 120
+prowl send p12 'git status --short'
+prowl key p12 enter
+printf '%s\n' 'git status --short' | prowl send --target p12
+prowl handoff save p12 --brief -
+prowl agents read p12
+```
+
+`prowl send p12` remains text input to the focused pane because `send` still lacks a
+payload target/value boundary with one positional argument. The correct target-first
+form is `prowl send p12 'text'`; stdin callers use `--target p12` or `--pane p12`.
+This is an inherent and documentable arity rule, not a target-resolution exception.
+
+`agents read` continues to accept a required pane-only positional argument and no
+selector flags. It shares the same `PaneHandle` lexical definition, but remains a
+semantic agent command rather than a generic terminal read.
+
+### Resource-specific operations
+
+The first implementation scope keeps current lifecycle command shapes:
+
+```bash
+prowl tab create --worktree MyApp --path /path/inside/MyApp
+prowl tab close --tab t6 --force
+prowl pane close --pane p12
+```
+
+Whether `tab create`, `tab close`, and `pane close` should additionally gain positional
+target shorthand is intentionally deferred. Close commands currently require an explicit
+selector as a safety posture; an explicit positional target could be safe, but it would
+be a separate public-grammar expansion rather than a prerequisite for fixing handle
+consistency.
+
+## Contract and Documentation Governance
+
+The current `docs-ai/013-prowl-cli/contracts/` directory is a living normative contract
+set, but it no longer covers the whole shipped CLI or all current fields. This work must
+rebaseline it in the same implementation change as the runtime behavior.
+
+### Contract set to reconcile
+
+1. Add a shared `targeting.md` contract that owns target syntax, handle lifetime,
+   resolution order, no-target semantics, selector exclusivity, and the distinction
+   between typed and generic references. Command contracts must link to it rather than
+   duplicate target rules.
+2. Reduce `input.md` to root command parsing and per-command argv/stdin arity. Correct
+   its selector-plus-positional rule to match runtime rejection, and add the current
+   `tab`, `pane`, `handoff`, and `agents read` grammar.
+3. Update existing output contracts for shipped behavior:
+   - `send.md`: document `--capture` and its incompatible combinations.
+   - `read.md`: document `detection`, stable waiting, and all returned metadata.
+   - `focus.md`, `key.md`, `list.md`, and `open.md`: reconcile fields, identifiers, and
+     current error behavior against implementation tests.
+4. Add contracts and schema coverage for commands that currently have only implementation
+   and user-manual coverage: `agents`, `tab`, `pane`, and `handoff`. Keep the existing
+   dedicated `agents-read.md` contract.
+5. Update `schema.md` to enumerate every supported JSON wire response and either validate
+   them in automated tests or explicitly narrow its status to a historical subset. The
+   preferred outcome is complete executable schema validation.
+6. Update `docs/components/cli.md` as the concise current user reference and
+   `.agents/skills/prowl-cli/SKILL.md` as the safety-oriented automation guide. Both must
+   use the shared target language and distinguish current-process handles from UUIDs.
+7. Correct help text inconsistencies, including the `prowl agents --help` synopsis that
+   currently implies a required subcommand despite `prowl agents` being valid.
+
+### Durable ownership rule
+
+- `ProwlCLI` ArgumentParser declarations are the executable source for command spelling
+  and option inventory.
+- `contracts/targeting.md` and command contracts are the normative public semantic source.
+- `docs/components/cli.md` is the human-oriented reference derived from those contracts.
+- The `prowl-cli` skill is an opinionated safety guide, never an independent behavior
+  specification.
+
+A new command or public flag is incomplete until all four layers have been updated and
+validated together.
+
+## Implementation Plan
+
+### Phase 0 — Align the public policy
+
+Confirm the prefixed-handle reservation policy, the lifecycle shorthand boundary, and
+whether the current focused-pane fallback remains acceptable for non-destructive commands.
+Freeze the target-language contract before changing resolver behavior.
+
+### Phase 1 — Centralize generic handle resolution
+
+- Extend `TargetResolver.resolveAuto` to recognize `pN` and `tN` before UUID/worktree
+  resolution, using the same handle validation as typed pane/tab selectors.
+- Keep typed `--pane` / `--tab` behavior unchanged, including their bare-number support.
+- Keep app-side target resolution; the CLI parser continues to transport a normalized
+  `TargetSelector` without inspecting live state.
+- Ensure a stale prefixed handle returns a typed target-not-found error and cannot fall
+  through to a worktree selector.
+
+### Phase 2 — Prove command parity and safety
+
+Add parser, resolver, handler, and socket integration coverage for the target matrix:
+
+| Form | Expected target interpretation |
+| --- | --- |
+| `read p12`, `focus p12` | pane `p12` |
+| `send p12 'text'`, `key p12 enter` | pane `p12` |
+| `send --target p12` with stdin | pane `p12` |
+| `handoff save p12` / `handoff to codex p12` | source pane `p12` |
+| `agents read p12` | semantic snapshot of pane `p12` |
+| `--pane 12`, `--tab 12` | existing typed bare-handle behavior |
+| generic `12` | worktree behavior, never an inferred handle |
+| stale `p12` / `t12` | target-not-found, never a worktree fallback |
+| positional target + selector flag | `INVALID_ARGUMENT` |
+
+Maintain tests for close requiring an explicit selector and for handoff's caller-pane
+fallback. Add a targeted check that cross-resource close selectors retain their documented
+behavior until a separately approved lifecycle grammar change.
+
+### Phase 3 — Rebaseline contracts, manuals, and help
+
+Land all contract changes listed above with the runtime change, update examples to use both
+UUID-safe automation and short same-session handoffs, and add a checked command synopsis
+or help snapshot so option changes are mechanically visible in review.
+
+### Phase 4 — Validate the release surface
+
+- Run focused Swift Testing suites for target resolution, command parsing, command handlers,
+  and CLI integration.
+- Run `make build-cli`, `make test-cli-smoke`, and `make test-cli-integration`.
+- Run `make check`, `make test`, and `make build-app`.
+- Manually verify one isolated Prowl session: text `list` → `pN` → generic read/send/key,
+  JSON `list` → UUID automation, stale-handle failure, and explicit close behavior.
+- Record actual outcomes in `001-action.md` after implementation.
+
+## Risks and Compatibility
+
+| Risk | Mitigation |
+| --- | --- |
+| Existing worktree named `p12` or `t6` changes generic auto-target behavior | Reserve prefixed forms; document `--worktree` as the unambiguous spelling and include release notes. |
+| A stale handle silently reaches a different target | Do not fall back from prefixed handles; fail explicitly. |
+| New CLI talks to an older running app | Resolver lives app-side, so retain the established transport/version failure guidance and ship CLI with the matching app. |
+| Documentation re-drifts after this correction | Single target contract, help snapshot/check, and a four-layer completion rule for public CLI changes. |
+| Over-expanding shorthand weakens destructive-command safety | Keep close selector requirements in this scope; decide positional close shorthand separately. |
+
+## Decisions Requiring Alignment
+
+1. **Prefixed-handle compatibility:** adopt the recommended reservation policy, or retain
+   worktree fallback for `pN`/`tN` and accept stale-handle ambiguity.
+2. **Lifecycle shorthand:** keep explicit selector-only close commands, or accept a
+   positional target as an equally explicit future form.
+3. **Focused-target defaults:** retain current convenience for non-destructive terminal
+   operations, or require explicit target selection whenever the caller is outside its
+   own pane.
+4. **Contract enforcement:** require automated JSON-schema validation for every wire
+   command now, or use narrower typed contract tests plus a future schema expansion.
+5. **Compatibility communication:** treat the `pN`/`tN` reservation as a documented
+   behavior correction in the next release, or introduce a deprecation/warning period.
+
+## Definition of Done
+
+The work is complete only when a user can learn one target grammar and accurately predict:
+
+```bash
+prowl agents read p12
+prowl read p12
+prowl send p12 'status'
+prowl key p12 enter
+prowl focus p12
+```
+
+All five address the same live pane; UUID JSON workflows remain stable; explicit close and
+handoff safety rules remain deliberate exceptions; every command and flag has one current
+contract; and tests make future divergence visible before release.
diff --git a/docs-ai/README.md b/docs-ai/README.md
index 8c569df9..76cd8f2e 100644
--- a/docs-ai/README.md
+++ b/docs-ai/README.md
@@ -111,3 +111,4 @@ agent-facing manual for that).
 | 057 | [performance-benchmark-suite](057-performance-benchmark-suite/000-plan.md) | 2026-08-02 | Ratio-assertion benchmarks pinning the #644–#665 hot paths, `make bench` absolute-number reporting, and live measurement wrappers |
 | 058 | [unified-toolbar-layout](058-unified-toolbar-layout/000-plan.md) | 2026-08-07 | Remove redundant branch/title toolbar items and align the Agents + notifications cluster across Normal, Shelf, and Canvas |
 | 059 | [agent-transcript-snapshots](059-agent-transcript-snapshots/000-plan.md) | 2026-08-11 | Immediate Codex/Claude agent snapshots with trustworthy transcript results and actionable blocker text |
+| 060 | [prowl-cli-targeting-and-contract-governance](060-prowl-cli-targeting-and-contract-governance/000-plan.md) | 2026-08-16 | Unified target grammar, CLI contract rebaseline, and durable documentation governance |
-- 
2.51.2


From 508a1a29332735b313c3280d1a0014d087f566e9 Mon Sep 17 00:00:00 2001
From: onevcat <onevcat@gmail.com>
Date: Sun, 16 Aug 2026 23:23:47 +0900
Subject: [PATCH 17/19] docs: align CLI lifecycle grammar

---
 .../000-plan.md                               | 157 +++++++++++++-----
 1 file changed, 111 insertions(+), 46 deletions(-)

diff --git a/docs-ai/060-prowl-cli-targeting-and-contract-governance/000-plan.md b/docs-ai/060-prowl-cli-targeting-and-contract-governance/000-plan.md
index d5ce6a5e..fab01e59 100644
--- a/docs-ai/060-prowl-cli-targeting-and-contract-governance/000-plan.md
+++ b/docs-ai/060-prowl-cli-targeting-and-contract-governance/000-plan.md
@@ -2,10 +2,10 @@
 
 | | |
 | --- | --- |
-| **Status** | Proposed — pending product/API alignment |
+| **Status** | Aligned — implementation pending |
 | **Anchor date** | 2026-08-16 |
 | **Primary PRs** | TBD |
-| **Related** | [013 — Prowl CLI](../013-prowl-cli/000-plan.md), [046 — CLI Short Handles](../046-cli-short-handles/000-plan.md), [047 — Cross-Agent Handoff](../047-cross-agent-handoff/000-plan.md), [059 — Agent Transcript Snapshots](../059-agent-transcript-snapshots/000-plan.md), [`docs/components/cli.md`](../../docs/components/cli.md) |
+| **Related** | [013 — Prowl CLI](../013-prowl-cli/000-plan.md), [046 — CLI Short Handles](../046-cli-short-handles/000-plan.md), [047 — Cross-Agent Handoff](../047-cross-agent-handoff/000-plan.md), [059 — Agent Transcript Snapshots](../059-agent-transcript-snapshots/000-plan.md), [#699 — CLI split-pane creation](https://github.com/onevcat/Prowl/issues/699), [`docs/components/cli.md`](../../docs/components/cli.md) |
 
 ## Background
 
@@ -104,6 +104,9 @@ an unambiguous prefixed handle from an ambiguous bare number.
   explicit close, and caller-pane handoff source resolution.
 - Re-establish a complete, current, testable contract set covering the actual command
   surface and make the user manual, CLI help, and agent skill agree.
+- Make terminal lifecycle action-first: `create tab`, future `create pane`, and `close`.
+  The existing `tab` and `pane` command groups become explicitly deprecated compatibility
+  aliases rather than the vocabulary for new automation.
 - Establish an ownership and verification workflow so later CLI growth cannot introduce
   another undocumented grammar fork.
 
@@ -116,6 +119,9 @@ an unambiguous prefixed handle from an ambiguous bare number.
 - Changing `agents read` from an immediate semantic snapshot into a generic terminal
   reader.
 - Changing handoff's caller-pane source rule or weakening explicit-close protections.
+- Implementing split-pane creation itself. Its action-first public shape and contract
+  boundary are owned by [#699](https://github.com/onevcat/Prowl/issues/699); this work
+  establishes the parent `create` grammar it will extend.
 - Broadening this work into terminal layout, agent-session, or worktree lifecycle
   redesign.
 
@@ -177,21 +183,49 @@ This is an inherent and documentable arity rule, not a target-resolution excepti
 selector flags. It shares the same `PaneHandle` lexical definition, but remains a
 semantic agent command rather than a generic terminal read.
 
-### Resource-specific operations
+### Lifecycle operations use an action-first grammar
 
-The first implementation scope keeps current lifecycle command shapes:
+Terminal lifecycle operations are part of the same orchestration language as `read`,
+`send`, and `focus`; they are not namespaces mirroring app implementation types. Their
+new public forms are:
 
 ```bash
-prowl tab create --worktree MyApp --path /path/inside/MyApp
-prowl tab close --tab t6 --force
-prowl pane close --pane p12
+prowl create tab MyApp --path /path/inside/MyApp
+prowl create pane p12 --direction right      # owned by #699, not implemented here
+prowl close t6 --force
+prowl close p12
 ```
 
-Whether `tab create`, `tab close`, and `pane close` should additionally gain positional
-target shorthand is intentionally deferred. Close commands currently require an explicit
-selector as a safety posture; an explicit positional target could be safe, but it would
-be a separate public-grammar expansion rather than a prerequisite for fixing handle
-consistency.
+The resource noun gives each action a typed target grammar:
+
+```text
+CreateTabTarget  ::= WorktreeRef
+CreatePaneTarget ::= PaneUUID | PaneHandle
+CloseTarget      ::= PaneUUID | TabUUID | PaneHandle | TabHandle
+```
+
+`create tab` accepts exactly one worktree reference, positionally or as `--worktree`.
+`create pane` accepts exactly one pane reference, positionally or as `--pane`, and
+requires an explicit direction. `close` accepts exactly one tab or pane reference,
+positionally or with `--tab` / `--pane`; it accepts neither `--worktree` nor `--target`.
+A positional target and a selector flag remain mutually exclusive. Thus `pN` and `tN`
+route `close` without a selector projection rule, while a UUID resolves as a pane or tab.
+All close forms remain explicit and retain `--force` for protected panes.
+
+The former resource-first forms are deprecated compatibility aliases:
+
+```bash
+prowl tab create ...
+prowl tab close ...
+prowl pane close ...
+```
+
+They must be marked deprecated in help and emit a stderr migration warning on every
+invocation without corrupting `--json` stdout. During one shipped-release compatibility
+window, aliases retain their existing parser and selector behavior, including legacy
+cross-resource projection, so existing automation does not silently change effect.
+New contracts, documentation, examples, and automation must use the action-first forms;
+the aliases may be removed after that window.
 
 ## Contract and Documentation Governance
 
@@ -206,16 +240,16 @@ rebaseline it in the same implementation change as the runtime behavior.
    between typed and generic references. Command contracts must link to it rather than
    duplicate target rules.
 2. Reduce `input.md` to root command parsing and per-command argv/stdin arity. Correct
-   its selector-plus-positional rule to match runtime rejection, and add the current
-   `tab`, `pane`, `handoff`, and `agents read` grammar.
+   its selector-plus-positional rule to match runtime rejection; define `create tab` and
+   `close`; and document deprecated `tab` / `pane` aliases, `handoff`, and `agents read`.
 3. Update existing output contracts for shipped behavior:
    - `send.md`: document `--capture` and its incompatible combinations.
    - `read.md`: document `detection`, stable waiting, and all returned metadata.
    - `focus.md`, `key.md`, `list.md`, and `open.md`: reconcile fields, identifiers, and
      current error behavior against implementation tests.
 4. Add contracts and schema coverage for commands that currently have only implementation
-   and user-manual coverage: `agents`, `tab`, `pane`, and `handoff`. Keep the existing
-   dedicated `agents-read.md` contract.
+   and user-manual coverage: `agents`, `create`, `close`, deprecated `tab` / `pane`, and
+   `handoff`. Keep the existing dedicated `agents-read.md` contract.
 5. Update `schema.md` to enumerate every supported JSON wire response and either validate
    them in automated tests or explicitly narrow its status to a historical subset. The
    preferred outcome is complete executable schema validation.
@@ -239,11 +273,11 @@ validated together.
 
 ## Implementation Plan
 
-### Phase 0 — Align the public policy
+### Phase 0 — Record the aligned public policy
 
-Confirm the prefixed-handle reservation policy, the lifecycle shorthand boundary, and
-whether the current focused-pane fallback remains acceptable for non-destructive commands.
-Freeze the target-language contract before changing resolver behavior.
+Record the confirmed prefixed-handle reservation, action-first lifecycle grammar,
+deprecation policy, and focused-pane fallback boundary in the shared contract before
+changing parser or resolver behavior.
 
 ### Phase 1 — Centralize generic handle resolution
 
@@ -255,7 +289,25 @@ Freeze the target-language contract before changing resolver behavior.
 - Ensure a stale prefixed handle returns a typed target-not-found error and cannot fall
   through to a worktree selector.
 
-### Phase 2 — Prove command parity and safety
+### Phase 2 — Migrate lifecycle commands without breaking aliases
+
+- Introduce top-level `create` and `close` parser groups. `create tab` owns a worktree-only
+  target; `close` owns a pane-or-tab-only target. Reserve `create pane` for #699 rather
+  than exposing an incomplete command.
+- Add typed lifecycle selector parsing so the new commands reject `--target`,
+  `--worktree` for close, cross-resource selectors, and worktree-like positional values
+  before transport. Keep generic UUID resolution only where a UUID is valid for the
+  action's resource type.
+- Add versioned `create` and `close` wire inputs, responses, output rendering, schemas,
+  and handlers. Preserve the existing `tab` and `pane` wire commands and response shapes
+  for deprecated aliases, so their JSON output remains byte-compatible in the window.
+- Mark `tab` and `pane` deprecated in generated help and write a single migration warning
+  to stderr at invocation. The warning must name the precise replacement and never enter
+  JSON stdout.
+- Make the new commands delegate to shared lifecycle operation logic rather than creating
+  a second set of close/create side effects.
+
+### Phase 3 — Prove command parity and safety
 
 Add parser, resolver, handler, and socket integration coverage for the target matrix:
 
@@ -266,22 +318,27 @@ Add parser, resolver, handler, and socket integration coverage for the target ma
 | `send --target p12` with stdin | pane `p12` |
 | `handoff save p12` / `handoff to codex p12` | source pane `p12` |
 | `agents read p12` | semantic snapshot of pane `p12` |
+| `create tab MyApp` / `create tab --worktree MyApp` | a new tab in that worktree |
+| `close p12`, `close t6` | close the typed pane or tab, respectively |
+| `close --pane p12`, `close --tab t6` | equivalent typed-selector close forms |
 | `--pane 12`, `--tab 12` | existing typed bare-handle behavior |
 | generic `12` | worktree behavior, never an inferred handle |
 | stale `p12` / `t12` | target-not-found, never a worktree fallback |
 | positional target + selector flag | `INVALID_ARGUMENT` |
 
-Maintain tests for close requiring an explicit selector and for handoff's caller-pane
-fallback. Add a targeted check that cross-resource close selectors retain their documented
-behavior until a separately approved lifecycle grammar change.
+Maintain tests for explicit close, legacy alias warnings and byte-compatible alias
+behavior, and handoff's caller-pane fallback. The new action-first lifecycle commands
+must reject cross-resource selectors before transport.
 
-### Phase 3 — Rebaseline contracts, manuals, and help
+### Phase 4 — Rebaseline contracts, manuals, and help
 
 Land all contract changes listed above with the runtime change, update examples to use both
-UUID-safe automation and short same-session handoffs, and add a checked command synopsis
-or help snapshot so option changes are mechanically visible in review.
+UUID-safe automation and short same-session handoffs, replace lifecycle examples with
+`create tab` / `close`, document the legacy aliases and their removal policy, and add a
+checked command synopsis or help snapshot so option changes are mechanically visible in
+review.
 
-### Phase 4 — Validate the release surface
+### Phase 5 — Validate the release surface
 
 - Run focused Swift Testing suites for target resolution, command parsing, command handlers,
   and CLI integration.
@@ -299,21 +356,28 @@ or help snapshot so option changes are mechanically visible in review.
 | A stale handle silently reaches a different target | Do not fall back from prefixed handles; fail explicitly. |
 | New CLI talks to an older running app | Resolver lives app-side, so retain the established transport/version failure guidance and ship CLI with the matching app. |
 | Documentation re-drifts after this correction | Single target contract, help snapshot/check, and a four-layer completion rule for public CLI changes. |
-| Over-expanding shorthand weakens destructive-command safety | Keep close selector requirements in this scope; decide positional close shorthand separately. |
-
-## Decisions Requiring Alignment
-
-1. **Prefixed-handle compatibility:** adopt the recommended reservation policy, or retain
-   worktree fallback for `pN`/`tN` and accept stale-handle ambiguity.
-2. **Lifecycle shorthand:** keep explicit selector-only close commands, or accept a
-   positional target as an equally explicit future form.
-3. **Focused-target defaults:** retain current convenience for non-destructive terminal
-   operations, or require explicit target selection whenever the caller is outside its
-   own pane.
-4. **Contract enforcement:** require automated JSON-schema validation for every wire
-   command now, or use narrower typed contract tests plus a future schema expansion.
-5. **Compatibility communication:** treat the `pN`/`tN` reservation as a documented
-   behavior correction in the next release, or introduce a deprecation/warning period.
+| A generic `close` weakens destructive-command safety | Require one explicit typed tab/pane target; reject worktree, UI-focus fallback, and cross-resource selector projection. |
+| Existing lifecycle scripts break during grammar correction | Keep `tab` / `pane` aliases byte-compatible for one shipped release, mark them deprecated in help, and emit stderr migration warnings. |
+
+## Confirmed Public Decisions
+
+1. **Prefixed handles:** `pN` and `tN` are reserved typed handles in every generic target
+   context. A stale handle fails and never falls through to a same-named worktree.
+2. **Lifecycle grammar:** new lifecycle commands are action-first: `create tab`, future
+   `create pane`, and `close <pane-or-tab>`. The resource noun constrains selector type;
+   new commands reject cross-resource selectors.
+3. **Destructive targeting:** `close` always requires an explicit tab or pane target.
+   Positional handles/UUIDs and typed `--tab` / `--pane` are equally explicit; worktree
+   and UI-focus fallback are not accepted.
+4. **Deprecated resource groups:** `tab` / `pane` are one-release compatibility aliases,
+   visibly deprecated and warning on stderr. They preserve legacy behavior during that
+   window, then may be removed.
+5. **Focused-target defaults:** retain current convenience for non-destructive terminal
+   operations. `handoff` continues to default to the calling pane, not UI focus.
+6. **Contract enforcement:** every wire command has a complete versioned JSON Schema and
+   automated validation against actual socket responses.
+7. **Pane creation:** do not mix the runtime feature into this change. [#699](https://github.com/onevcat/Prowl/issues/699)
+   owns `prowl create pane <pane> --direction <direction>`.
 
 ## Definition of Done
 
@@ -327,6 +391,7 @@ prowl key p12 enter
 prowl focus p12
 ```
 
-All five address the same live pane; UUID JSON workflows remain stable; explicit close and
-handoff safety rules remain deliberate exceptions; every command and flag has one current
-contract; and tests make future divergence visible before release.
+All five address the same live pane; `create tab` and `close pN` / `close tN` follow the
+same action-first language; UUID JSON workflows remain stable; explicit close and handoff
+safety rules remain deliberate exceptions; every command and flag has one current contract;
+and tests make future divergence visible before release.
-- 
2.51.2


From 7d8b05fe52e898a09d386fe2e65da2a3647a6d1a Mon Sep 17 00:00:00 2001
From: onevcat <onevcat@gmail.com>
Date: Sun, 16 Aug 2026 23:59:26 +0900
Subject: [PATCH 18/19] feat(cli): unify target grammar

---
 Package.resolved                              |   29 +-
 Package.swift                                 |    8 +
 ProwlCLI/Commands/CloseCommand.swift          |   30 +
 ProwlCLI/Commands/CreateCommand.swift         |   65 +
 ProwlCLI/Commands/DeprecationWarning.swift    |    8 +
 .../Commands/LifecycleSelectorOptions.swift   |  118 +
 ProwlCLI/Commands/PaneCommand.swift           |    5 +-
 ProwlCLI/Commands/ProwlCommand.swift          |    2 +
 ProwlCLI/Commands/TabCommand.swift            |    8 +-
 ProwlCLI/Output/OutputRenderer.swift          |   25 +
 ProwlCLIContracts/ContractBundle.swift        |   14 +
 .../Resources/cli-output-schema.json          | 2032 +++++++++++++++++
 ProwlCLITests/ProwlCLIIntegrationTests.swift  |  244 +-
 docs-ai/013-prowl-cli/contracts/agents.md     |   18 +
 .../013-prowl-cli/contracts/architecture.md   |   25 +-
 docs-ai/013-prowl-cli/contracts/close.md      |   50 +
 docs-ai/013-prowl-cli/contracts/create.md     |   49 +
 docs-ai/013-prowl-cli/contracts/focus.md      |   10 +-
 docs-ai/013-prowl-cli/contracts/handoff.md    |   19 +
 docs-ai/013-prowl-cli/contracts/input.md      |  408 +---
 docs-ai/013-prowl-cli/contracts/key.md        |    7 +-
 docs-ai/013-prowl-cli/contracts/list.md       |    5 +-
 docs-ai/013-prowl-cli/contracts/pane.md       |   16 +
 docs-ai/013-prowl-cli/contracts/read.md       |   24 +-
 docs-ai/013-prowl-cli/contracts/schema.md     |  890 +-------
 docs-ai/013-prowl-cli/contracts/send.md       |   22 +-
 docs-ai/013-prowl-cli/contracts/tab.md        |   15 +
 docs-ai/013-prowl-cli/contracts/targeting.md  |   68 +
 .../000-plan.md                               |    2 +-
 .../001-action.md                             |   58 +
 docs/components/cli.md                        |   58 +-
 docs/components/terminal.md                   |    2 +-
 skills/prowl-cli/SKILL.md                     |   26 +-
 supacode/App/supacodeApp.swift                |  134 +-
 supacode/CLIService/CLICommandRouter.swift    |    8 +
 .../CLIService/LifecycleCommandHandler.swift  |  202 ++
 .../CLIService/Shared/CommandEnvelope.swift   |    4 +
 supacode/CLIService/Shared/ErrorCodes.swift   |    4 +
 supacode/CLIService/Shared/InputModels.swift  |   27 +
 .../Shared/LifecycleCommandPayload.swift      |   11 +
 supacode/CLIService/TargetResolver.swift      |   51 +-
 .../CLILifecycleCommandHandlerTests.swift     |  106 +
 supacodeTests/CLITargetResolverTests.swift    |   70 +-
 43 files changed, 3612 insertions(+), 1365 deletions(-)
 create mode 100644 ProwlCLI/Commands/CloseCommand.swift
 create mode 100644 ProwlCLI/Commands/CreateCommand.swift
 create mode 100644 ProwlCLI/Commands/DeprecationWarning.swift
 create mode 100644 ProwlCLI/Commands/LifecycleSelectorOptions.swift
 create mode 100644 ProwlCLIContracts/ContractBundle.swift
 create mode 100644 ProwlCLIContracts/Resources/cli-output-schema.json
 create mode 100644 docs-ai/013-prowl-cli/contracts/agents.md
 create mode 100644 docs-ai/013-prowl-cli/contracts/close.md
 create mode 100644 docs-ai/013-prowl-cli/contracts/create.md
 create mode 100644 docs-ai/013-prowl-cli/contracts/handoff.md
 create mode 100644 docs-ai/013-prowl-cli/contracts/pane.md
 create mode 100644 docs-ai/013-prowl-cli/contracts/tab.md
 create mode 100644 docs-ai/013-prowl-cli/contracts/targeting.md
 create mode 100644 docs-ai/060-prowl-cli-targeting-and-contract-governance/001-action.md
 create mode 100644 supacode/CLIService/LifecycleCommandHandler.swift
 create mode 100644 supacode/CLIService/Shared/LifecycleCommandPayload.swift
 create mode 100644 supacodeTests/CLILifecycleCommandHandlerTests.swift

diff --git a/Package.resolved b/Package.resolved
index 6b684d44..77f579ad 100644
--- a/Package.resolved
+++ b/Package.resolved
@@ -1,5 +1,5 @@
 {
-  "originHash" : "6a83eb824bb8cc817831017cf72468c234a2d99470f15d658e3a30b8bddccd4c",
+  "originHash" : "f754db8301c9da1c2526e397dc4b099bee8a678f1e853a4f2b121df3ef3fd4b3",
   "pins" : [
     {
       "identity" : "rainbow",
@@ -18,6 +18,33 @@
         "revision" : "626b5b7b2f45e1b0b1c6f4a309296d1d21d7311b",
         "version" : "1.7.1"
       }
+    },
+    {
+      "identity" : "swift-collections",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-collections.git",
+      "state" : {
+        "revision" : "a0cb0954ecb21e4e31b0070e6ed5674e8556685a",
+        "version" : "1.6.0"
+      }
+    },
+    {
+      "identity" : "swift-json-schema",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/ajevans99/swift-json-schema",
+      "state" : {
+        "revision" : "f299eb1cce78b2dd736d9a390ec0779d28678416",
+        "version" : "0.13.1"
+      }
+    },
+    {
+      "identity" : "swift-syntax",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/swiftlang/swift-syntax.git",
+      "state" : {
+        "revision" : "79e4b74a295b6eb74a8b585e3a39d29e70c1dbd1",
+        "version" : "603.0.2"
+      }
     }
   ],
   "version" : 3
diff --git a/Package.swift b/Package.swift
index 68750949..2f282580 100644
--- a/Package.swift
+++ b/Package.swift
@@ -19,6 +19,7 @@ let package = Package(
   ],
   dependencies: [
     .package(url: "https://github.com/apple/swift-argument-parser", from: "1.3.0"),
+    .package(url: "https://github.com/ajevans99/swift-json-schema", from: "0.13.1"),
     .package(url: "https://github.com/onevcat/Rainbow", from: "4.0.0"),
   ],
   targets: [
@@ -35,11 +36,18 @@ let package = Package(
       ],
       path: "ProwlCLI"
     ),
+    .target(
+      name: "ProwlCLIContracts",
+      path: "ProwlCLIContracts",
+      resources: [.process("Resources")]
+    ),
     .testTarget(
       name: "ProwlCLITests",
       dependencies: [
+        "ProwlCLIContracts",
         "ProwlCLIShared",
         "prowl",
+        .product(name: "JSONSchema", package: "swift-json-schema"),
       ],
       path: "ProwlCLITests"
     ),
diff --git a/ProwlCLI/Commands/CloseCommand.swift b/ProwlCLI/Commands/CloseCommand.swift
new file mode 100644
index 00000000..71d3f4e5
--- /dev/null
+++ b/ProwlCLI/Commands/CloseCommand.swift
@@ -0,0 +1,30 @@
+// ProwlCLI/Commands/CloseCommand.swift
+
+import ArgumentParser
+import ProwlCLIShared
+
+struct CloseCommand: ParsableCommand {
+  static let configuration = CommandConfiguration(
+    commandName: "close",
+    abstract: "Close a terminal pane or tab."
+  )
+
+  @Argument(help: "Pane/tab UUID or prefixed handle (pN or tN).")
+  var target: String?
+
+  @OptionGroup var selector: LifecycleSelectorOptions
+  @OptionGroup var options: GlobalOptions
+
+  @Flag(name: .long, help: "Close without prompting for protected panes.")
+  var force = false
+
+  mutating func run() throws {
+    try CLIExecution.run(command: "close", output: options.outputMode, colorEnabled: options.colorEnabled) {
+      let envelope = CommandEnvelope(
+        output: options.outputMode,
+        command: .close(CloseInput(selector: try selector.resolveTerminalTarget(positionalTarget: target), force: force))
+      )
+      try CLIRunner.execute(envelope)
+    }
+  }
+}
diff --git a/ProwlCLI/Commands/CreateCommand.swift b/ProwlCLI/Commands/CreateCommand.swift
new file mode 100644
index 00000000..4eecab4c
--- /dev/null
+++ b/ProwlCLI/Commands/CreateCommand.swift
@@ -0,0 +1,65 @@
+// ProwlCLI/Commands/CreateCommand.swift
+
+import ArgumentParser
+import Foundation
+import ProwlCLIShared
+
+struct CreateCommand: ParsableCommand {
+  static let configuration = CommandConfiguration(
+    commandName: "create",
+    abstract: "Create a terminal resource.",
+    subcommands: [
+      CreateTabCommand.self,
+    ]
+  )
+}
+
+struct CreateTabCommand: ParsableCommand {
+  static let configuration = CommandConfiguration(
+    commandName: "tab",
+    abstract: "Create a new terminal tab."
+  )
+
+  @Argument(help: "Worktree id, name, or path.")
+  var worktree: String?
+
+  @OptionGroup var selector: LifecycleSelectorOptions
+  @OptionGroup var options: GlobalOptions
+
+  @Option(name: .long, help: "Working directory for the new tab.")
+  var path: String?
+
+  mutating func run() throws {
+    try CLIExecution.run(command: "create", output: options.outputMode, colorEnabled: options.colorEnabled) {
+      let envelope = CommandEnvelope(
+        output: options.outputMode,
+        command: .create(
+          CreateInput(
+            resource: .tab,
+            selector: try selector.resolveWorktree(positionalTarget: worktree),
+            path: normalizedPath()
+          )
+        )
+      )
+      try CLIRunner.execute(envelope)
+    }
+  }
+
+  private func normalizedPath() -> String? {
+    guard let path else { return nil }
+    return URL(fileURLWithPath: path, isDirectory: true)
+      .standardizedFileURL
+      .path(percentEncoded: false)
+      .trimmingTrailingSlash()
+  }
+}
+
+private extension String {
+  func trimmingTrailingSlash() -> String {
+    var value = self
+    while value.count > 1, value.hasSuffix("/") {
+      value.removeLast()
+    }
+    return value
+  }
+}
diff --git a/ProwlCLI/Commands/DeprecationWarning.swift b/ProwlCLI/Commands/DeprecationWarning.swift
new file mode 100644
index 00000000..d3170730
--- /dev/null
+++ b/ProwlCLI/Commands/DeprecationWarning.swift
@@ -0,0 +1,8 @@
+// ProwlCLI/Commands/DeprecationWarning.swift
+
+import Foundation
+
+func emitDeprecationWarning(command: String, replacement: String) {
+  let message = "warning: `prowl \(command)` is deprecated; use `prowl \(replacement)`.\n"
+  FileHandle.standardError.write(Data(message.utf8))
+}
diff --git a/ProwlCLI/Commands/LifecycleSelectorOptions.swift b/ProwlCLI/Commands/LifecycleSelectorOptions.swift
new file mode 100644
index 00000000..0fcd55e8
--- /dev/null
+++ b/ProwlCLI/Commands/LifecycleSelectorOptions.swift
@@ -0,0 +1,118 @@
+// ProwlCLI/Commands/LifecycleSelectorOptions.swift
+// Typed target selectors for action-first lifecycle commands.
+
+import ArgumentParser
+import Foundation
+import ProwlCLIShared
+
+struct LifecycleSelectorOptions: ParsableArguments {
+  @Option(name: .long, help: "Target worktree by id, name, or path.")
+  var worktree: String?
+
+  @Option(name: .long, help: "Target tab by UUID or short handle (for example, t4).")
+  var tab: String?
+
+  @Option(name: .long, help: "Target pane by UUID or short handle (for example, p3).")
+  var pane: String?
+
+  func resolveWorktree(positionalTarget: String?) throws -> TargetSelector {
+    try resolve(positionalTarget: positionalTarget, acceptedSelector: .worktree)
+  }
+
+  func resolveTerminalTarget(positionalTarget: String?) throws -> TargetSelector {
+    let provided = [worktree, tab, pane].compactMap { $0 }
+    guard provided.count <= 1 else {
+      throw ExitError(
+        code: CLIErrorCode.invalidArgument,
+        message: "At most one target selector (--worktree, --tab, --pane) is allowed."
+      )
+    }
+
+    if let positionalTarget {
+      guard provided.isEmpty else {
+        throw ExitError(
+          code: CLIErrorCode.invalidArgument,
+          message: "Use either a positional target or one selector flag (--tab, --pane)."
+        )
+      }
+      guard isTerminalReference(positionalTarget) else {
+        throw ExitError(
+          code: CLIErrorCode.invalidArgument,
+          message: "close requires a pane/tab UUID or prefixed handle (pN or tN)."
+        )
+      }
+      return .auto(positionalTarget)
+    }
+
+    if worktree != nil {
+      throw ExitError(
+        code: CLIErrorCode.invalidArgument,
+        message: "close accepts only --tab or --pane, not --worktree."
+      )
+    }
+    if let tab { return .tab(tab) }
+    if let pane { return .pane(pane) }
+    throw ExitError(
+      code: CLIErrorCode.invalidArgument,
+      message: "close requires an explicit pane or tab target."
+    )
+  }
+
+  private enum AcceptedSelector {
+    case worktree
+  }
+
+  private func resolve(positionalTarget: String?, acceptedSelector: AcceptedSelector) throws -> TargetSelector {
+    let provided = [worktree, tab, pane].compactMap { $0 }
+    guard provided.count <= 1 else {
+      throw ExitError(
+        code: CLIErrorCode.invalidArgument,
+        message: "At most one target selector (--worktree, --tab, --pane) is allowed."
+      )
+    }
+
+    if let positionalTarget {
+      guard provided.isEmpty else {
+        throw ExitError(
+          code: CLIErrorCode.invalidArgument,
+          message: "Use either a positional target or one selector flag (--worktree)."
+        )
+      }
+      return .worktree(positionalTarget)
+    }
+
+    switch acceptedSelector {
+    case .worktree:
+      if let worktree { return .worktree(worktree) }
+      if tab != nil || pane != nil {
+        throw ExitError(
+          code: CLIErrorCode.invalidArgument,
+          message: "create tab accepts only a worktree target."
+        )
+      }
+      throw ExitError(
+        code: CLIErrorCode.invalidArgument,
+        message: "create tab requires an explicit worktree target."
+      )
+    }
+  }
+
+  private func isTerminalReference(_ value: String) -> Bool {
+    UUID(uuidString: value) != nil || isPrefixedHandle(value, prefix: "p") || isPrefixedHandle(value, prefix: "t")
+  }
+
+  private func isPrefixedHandle(_ value: String, prefix: Character) -> Bool {
+    let normalized = value.lowercased()
+    guard normalized.first == prefix else { return false }
+    let digits = normalized.dropFirst()
+    guard
+      !digits.isEmpty,
+      digits.allSatisfy({ $0.isASCII && $0.isNumber }),
+      let handle = Int(digits),
+      handle > 0
+    else {
+      return false
+    }
+    return true
+  }
+}
diff --git a/ProwlCLI/Commands/PaneCommand.swift b/ProwlCLI/Commands/PaneCommand.swift
index 4fe0a065..2b540ef5 100644
--- a/ProwlCLI/Commands/PaneCommand.swift
+++ b/ProwlCLI/Commands/PaneCommand.swift
@@ -6,7 +6,7 @@ import ProwlCLIShared
 struct PaneCommand: ParsableCommand {
   static let configuration = CommandConfiguration(
     commandName: "pane",
-    abstract: "Manage terminal panes.",
+    abstract: "[Deprecated] Manage terminal panes. Use `prowl close`.",
     subcommands: [
       PaneCloseCommand.self,
     ]
@@ -16,7 +16,7 @@ struct PaneCommand: ParsableCommand {
 struct PaneCloseCommand: ParsableCommand {
   static let configuration = CommandConfiguration(
     commandName: "close",
-    abstract: "Close a terminal pane."
+    abstract: "[Deprecated] Close a terminal pane. Use `prowl close <pane>`."
   )
 
   @OptionGroup var selector: SelectorOptions
@@ -26,6 +26,7 @@ struct PaneCloseCommand: ParsableCommand {
   var force = false
 
   mutating func run() throws {
+    emitDeprecationWarning(command: "pane close", replacement: "close <pane>")
     try CLIExecution.run(command: "pane", output: options.outputMode, colorEnabled: options.colorEnabled) {
       let resolvedSelector = try selector.resolve()
       guard !resolvedSelector.isNone else {
diff --git a/ProwlCLI/Commands/ProwlCommand.swift b/ProwlCLI/Commands/ProwlCommand.swift
index 26350a13..eab5ad4a 100644
--- a/ProwlCLI/Commands/ProwlCommand.swift
+++ b/ProwlCLI/Commands/ProwlCommand.swift
@@ -18,6 +18,8 @@ struct ProwlCommand: ParsableCommand {
       SendCommand.self,
       KeyCommand.self,
       ReadCommand.self,
+      CreateCommand.self,
+      CloseCommand.self,
       TabCommand.self,
       PaneCommand.self,
       HandoffCommand.self,
diff --git a/ProwlCLI/Commands/TabCommand.swift b/ProwlCLI/Commands/TabCommand.swift
index 01344502..ab9a4a70 100644
--- a/ProwlCLI/Commands/TabCommand.swift
+++ b/ProwlCLI/Commands/TabCommand.swift
@@ -7,7 +7,7 @@ import ProwlCLIShared
 struct TabCommand: ParsableCommand {
   static let configuration = CommandConfiguration(
     commandName: "tab",
-    abstract: "Create or close terminal tabs.",
+    abstract: "[Deprecated] Create or close terminal tabs. Use `prowl create tab` or `prowl close`.",
     subcommands: [
       TabCreateCommand.self,
       TabCloseCommand.self,
@@ -18,7 +18,7 @@ struct TabCommand: ParsableCommand {
 struct TabCreateCommand: ParsableCommand {
   static let configuration = CommandConfiguration(
     commandName: "create",
-    abstract: "Create a new terminal tab."
+    abstract: "[Deprecated] Create a new terminal tab. Use `prowl create tab`."
   )
 
   @OptionGroup var selector: SelectorOptions
@@ -28,6 +28,7 @@ struct TabCreateCommand: ParsableCommand {
   var path: String?
 
   mutating func run() throws {
+    emitDeprecationWarning(command: "tab create", replacement: "create tab <worktree>")
     try CLIExecution.run(command: "tab", output: options.outputMode, colorEnabled: options.colorEnabled) {
       let envelope = CommandEnvelope(
         output: options.outputMode,
@@ -49,7 +50,7 @@ struct TabCreateCommand: ParsableCommand {
 struct TabCloseCommand: ParsableCommand {
   static let configuration = CommandConfiguration(
     commandName: "close",
-    abstract: "Close a terminal tab."
+    abstract: "[Deprecated] Close a terminal tab. Use `prowl close <tab>`."
   )
 
   @OptionGroup var selector: SelectorOptions
@@ -59,6 +60,7 @@ struct TabCloseCommand: ParsableCommand {
   var force = false
 
   mutating func run() throws {
+    emitDeprecationWarning(command: "tab close", replacement: "close <tab>")
     try CLIExecution.run(command: "tab", output: options.outputMode, colorEnabled: options.colorEnabled) {
       let resolvedSelector = try selector.resolve()
       guard !resolvedSelector.isNone else {
diff --git a/ProwlCLI/Output/OutputRenderer.swift b/ProwlCLI/Output/OutputRenderer.swift
index 54a958bf..ed1a1800 100644
--- a/ProwlCLI/Output/OutputRenderer.swift
+++ b/ProwlCLI/Output/OutputRenderer.swift
@@ -100,6 +100,14 @@ enum OutputRenderer {
         return
       }
 
+      if response.command == "create" || response.command == "close",
+         let data = response.data,
+         let payload = try? data.decode(as: LifecycleCommandPayload.self)
+      {
+        print(renderLifecycle(payload, command: response.command))
+        return
+      }
+
       if response.command == "tab",
          let data = response.data,
          let payload = try? data.decode(as: TabCommandPayload.self)
@@ -338,6 +346,23 @@ enum OutputRenderer {
     return lines.joined(separator: "\n")
   }
 
+  private static func renderLifecycle(_ payload: LifecycleCommandPayload, command: String) -> String {
+    let wt = payload.target.worktree
+    let tab = payload.target.tab
+    let pane = payload.target.pane
+    let projectName = projectName(from: wt.path)
+    let verb = command == "create" ? "Created" : "Closed"
+
+    switch payload.resource {
+    case .tab:
+      return "\(verb) tab \(projectName.cyan.bold)\(":".dim)\(wt.name) → \(tab.title.yellow)"
+        + "  \(tab.id.dim)\n  \("pane:".dim) \(pane.title.green)  \(pane.id.dim)"
+    case .pane:
+      return "\(verb) pane \(projectName.cyan.bold)\(":".dim)\(wt.name) → \(pane.title.green)"
+        + "  \(pane.id.dim)"
+    }
+  }
+
   private static func renderHandoff(_ payload: HandoffCommandPayload) -> String {
     var lines: [String] = []
 
diff --git a/ProwlCLIContracts/ContractBundle.swift b/ProwlCLIContracts/ContractBundle.swift
new file mode 100644
index 00000000..5750e5f3
--- /dev/null
+++ b/ProwlCLIContracts/ContractBundle.swift
@@ -0,0 +1,14 @@
+import Foundation
+
+public enum ProwlCLIContractBundle {
+  public static let schemaData: Data = {
+    guard let url = Bundle.module.url(forResource: "cli-output-schema", withExtension: "json") else {
+      preconditionFailure("Missing Prowl CLI JSON Schema bundle resource.")
+    }
+    do {
+      return try Data(contentsOf: url)
+    } catch {
+      preconditionFailure("Failed to load Prowl CLI JSON Schema bundle: \(error)")
+    }
+  }()
+}
diff --git a/ProwlCLIContracts/Resources/cli-output-schema.json b/ProwlCLIContracts/Resources/cli-output-schema.json
new file mode 100644
index 00000000..eb8b3c2f
--- /dev/null
+++ b/ProwlCLIContracts/Resources/cli-output-schema.json
@@ -0,0 +1,2032 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://prowl.onev.cat/contracts/cli/v1/schema-bundle.json",
+  "title": "Prowl CLI Output Contract Schemas",
+  "description": "Versioned JSON schemas for every Prowl CLI wire response.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/openResponse"
+    },
+    {
+      "$ref": "#/$defs/listResponse"
+    },
+    {
+      "$ref": "#/$defs/agentsResponse"
+    },
+    {
+      "$ref": "#/$defs/agentsReadResponse"
+    },
+    {
+      "$ref": "#/$defs/focusResponse"
+    },
+    {
+      "$ref": "#/$defs/sendResponse"
+    },
+    {
+      "$ref": "#/$defs/keyResponse"
+    },
+    {
+      "$ref": "#/$defs/readResponse"
+    },
+    {
+      "$ref": "#/$defs/createResponse"
+    },
+    {
+      "$ref": "#/$defs/closeResponse"
+    },
+    {
+      "$ref": "#/$defs/tabResponse"
+    },
+    {
+      "$ref": "#/$defs/paneResponse"
+    },
+    {
+      "$ref": "#/$defs/handoffResponse"
+    }
+  ],
+  "$defs": {
+    "error": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "code",
+        "message"
+      ],
+      "properties": {
+        "code": {
+          "type": "string",
+          "minLength": 1
+        },
+        "message": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "worktree": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "name",
+        "path",
+        "root_path",
+        "kind"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "path": {
+          "type": "string",
+          "minLength": 1
+        },
+        "root_path": {
+          "type": "string",
+          "minLength": 1
+        },
+        "kind": {
+          "enum": [
+            "git",
+            "plain",
+            "workspace"
+          ]
+        }
+      }
+    },
+    "tab": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "title",
+        "selected"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "title": {
+          "type": "string"
+        },
+        "selected": {
+          "type": "boolean"
+        }
+      }
+    },
+    "pane": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "title",
+        "cwd",
+        "focused"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "title": {
+          "type": "string"
+        },
+        "cwd": {
+          "anyOf": [
+            {
+              "type": "string",
+              "minLength": 1
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "focused": {
+          "type": "boolean"
+        }
+      }
+    },
+    "target": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "worktree",
+        "tab",
+        "pane"
+      ],
+      "properties": {
+        "worktree": {
+          "$ref": "#/$defs/worktree"
+        },
+        "tab": {
+          "$ref": "#/$defs/tab"
+        },
+        "pane": {
+          "$ref": "#/$defs/pane"
+        }
+      }
+    },
+    "lifecycleData": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "resource",
+        "target"
+      ],
+      "properties": {
+        "resource": {
+          "enum": [
+            "tab",
+            "pane"
+          ]
+        },
+        "target": {
+          "$ref": "#/$defs/target"
+        }
+      }
+    },
+    "tabData": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "action",
+        "target"
+      ],
+      "properties": {
+        "action": {
+          "enum": [
+            "create",
+            "close"
+          ]
+        },
+        "target": {
+          "$ref": "#/$defs/target"
+        }
+      }
+    },
+    "paneData": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "action",
+        "target"
+      ],
+      "properties": {
+        "action": {
+          "const": "close"
+        },
+        "target": {
+          "$ref": "#/$defs/target"
+        }
+      }
+    },
+    "listTab": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "title",
+        "selected"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "handle": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "title": {
+          "type": "string"
+        },
+        "selected": {
+          "type": "boolean"
+        }
+      }
+    },
+    "listPane": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "title",
+        "cwd",
+        "focused"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "handle": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "title": {
+          "type": "string"
+        },
+        "cwd": {
+          "anyOf": [
+            {
+              "type": "string",
+              "minLength": 1
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "focused": {
+          "type": "boolean"
+        },
+        "agent": {
+          "anyOf": [
+            {
+              "type": "string",
+              "minLength": 1
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      }
+    },
+    "listItem": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "worktree",
+        "tab",
+        "pane",
+        "task"
+      ],
+      "properties": {
+        "worktree": {
+          "$ref": "#/$defs/worktree"
+        },
+        "tab": {
+          "$ref": "#/$defs/listTab"
+        },
+        "pane": {
+          "$ref": "#/$defs/listPane"
+        },
+        "task": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "status"
+          ],
+          "properties": {
+            "status": {
+              "anyOf": [
+                {
+                  "enum": [
+                    "running",
+                    "idle"
+                  ]
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            }
+          }
+        }
+      }
+    },
+    "listData": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "count",
+        "items"
+      ],
+      "properties": {
+        "count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "items": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/listItem"
+          }
+        }
+      }
+    },
+    "agentsSession": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "path",
+        "confidence",
+        "source"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "path": {
+          "anyOf": [
+            {
+              "type": "string",
+              "minLength": 1
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "confidence": {
+          "type": "string",
+          "minLength": 1
+        },
+        "source": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "agentsPane": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "index",
+        "title",
+        "cwd",
+        "focused"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "handle": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "index": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "title": {
+          "type": "string"
+        },
+        "cwd": {
+          "anyOf": [
+            {
+              "type": "string",
+              "minLength": 1
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "focused": {
+          "type": "boolean"
+        }
+      }
+    },
+    "agent": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "type",
+        "name",
+        "status",
+        "raw_state",
+        "last_changed_at",
+        "project",
+        "worktree",
+        "tab",
+        "pane"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "type": {
+          "type": "string",
+          "minLength": 1
+        },
+        "name": {
+          "type": "string"
+        },
+        "status": {
+          "enum": [
+            "blocked",
+            "working",
+            "done",
+            "idle"
+          ]
+        },
+        "raw_state": {
+          "type": "string",
+          "minLength": 1
+        },
+        "detection_reason": {
+          "type": "string"
+        },
+        "last_changed_at": {
+          "type": "string",
+          "minLength": 1
+        },
+        "project": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "name",
+            "branch",
+            "path"
+          ],
+          "properties": {
+            "name": {
+              "type": "string",
+              "minLength": 1
+            },
+            "branch": {
+              "type": "string"
+            },
+            "path": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        },
+        "worktree": {
+          "$ref": "#/$defs/worktree"
+        },
+        "tab": {
+          "$ref": "#/$defs/tab"
+        },
+        "pane": {
+          "$ref": "#/$defs/agentsPane"
+        },
+        "session": {
+          "$ref": "#/$defs/agentsSession"
+        }
+      }
+    },
+    "agentsData": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "count",
+        "agents"
+      ],
+      "properties": {
+        "count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "agents": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/agent"
+          }
+        }
+      }
+    },
+    "agentReadSession": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "confidence",
+        "source"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "confidence": {
+          "type": "string",
+          "minLength": 1
+        },
+        "source": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "agentReadData": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "output_mode",
+        "target",
+        "agent",
+        "result"
+      ],
+      "properties": {
+        "output_mode": {
+          "enum": [
+            "snapshot",
+            "result_only"
+          ]
+        },
+        "target": {
+          "$ref": "#/$defs/target"
+        },
+        "agent": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "type",
+            "status",
+            "raw_state",
+            "last_changed_at"
+          ],
+          "properties": {
+            "type": {
+              "type": "string",
+              "minLength": 1
+            },
+            "status": {
+              "enum": [
+                "blocked",
+                "working",
+                "done",
+                "idle"
+              ]
+            },
+            "raw_state": {
+              "type": "string",
+              "minLength": 1
+            },
+            "detection_reason": {
+              "type": "string"
+            },
+            "last_changed_at": {
+              "type": "string",
+              "minLength": 1
+            },
+            "session": {
+              "$ref": "#/$defs/agentReadSession"
+            }
+          }
+        },
+        "blocker": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "text"
+          ],
+          "properties": {
+            "text": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        },
+        "result": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "state"
+          ],
+          "properties": {
+            "state": {
+              "enum": [
+                "complete",
+                "pending",
+                "unavailable",
+                "missing",
+                "incomplete",
+                "too_large"
+              ]
+            },
+            "text": {
+              "type": "string"
+            },
+            "error": {
+              "$ref": "#/$defs/error"
+            }
+          }
+        }
+      }
+    },
+    "focusData": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "requested",
+        "resolved_via",
+        "brought_to_front",
+        "target"
+      ],
+      "properties": {
+        "requested": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "selector",
+            "value"
+          ],
+          "properties": {
+            "selector": {
+              "enum": [
+                "worktree",
+                "tab",
+                "pane",
+                "auto",
+                "current"
+              ]
+            },
+            "value": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            }
+          }
+        },
+        "resolved_via": {
+          "enum": [
+            "worktree",
+            "tab",
+            "pane"
+          ]
+        },
+        "brought_to_front": {
+          "type": "boolean"
+        },
+        "target": {
+          "$ref": "#/$defs/target"
+        }
+      }
+    },
+    "sendData": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "target",
+        "input",
+        "created_tab"
+      ],
+      "properties": {
+        "target": {
+          "$ref": "#/$defs/target"
+        },
+        "input": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "source",
+            "characters",
+            "bytes",
+            "trailing_enter_sent"
+          ],
+          "properties": {
+            "source": {
+              "enum": [
+                "argv",
+                "stdin"
+              ]
+            },
+            "characters": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "bytes": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "trailing_enter_sent": {
+              "type": "boolean"
+            }
+          }
+        },
+        "created_tab": {
+          "type": "boolean"
+        },
+        "wait": {
+          "anyOf": [
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "exit_code",
+                "duration_ms"
+              ],
+              "properties": {
+                "exit_code": {
+                  "anyOf": [
+                    {
+                      "type": "integer"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "duration_ms": {
+                  "type": "integer",
+                  "minimum": 0
+                }
+              }
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "capture": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "text",
+            "line_count",
+            "source",
+            "truncated"
+          ],
+          "properties": {
+            "text": {
+              "type": "string"
+            },
+            "line_count": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "source": {
+              "const": "screen_diff"
+            },
+            "truncated": {
+              "type": "boolean"
+            }
+          }
+        }
+      }
+    },
+    "keyData": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "requested",
+        "key",
+        "delivery",
+        "target"
+      ],
+      "properties": {
+        "requested": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "token",
+            "repeat"
+          ],
+          "properties": {
+            "token": {
+              "type": "string",
+              "minLength": 1
+            },
+            "repeat": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 100
+            }
+          }
+        },
+        "key": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "normalized",
+            "category"
+          ],
+          "properties": {
+            "normalized": {
+              "type": "string",
+              "minLength": 1
+            },
+            "category": {
+              "enum": [
+                "navigation",
+                "editing",
+                "control",
+                "shortcut",
+                "function"
+              ]
+            }
+          }
+        },
+        "delivery": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "attempted",
+            "delivered",
+            "mode"
+          ],
+          "properties": {
+            "attempted": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 100
+            },
+            "delivered": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 100
+            },
+            "mode": {
+              "const": "keyDownUp"
+            }
+          }
+        },
+        "target": {
+          "$ref": "#/$defs/target"
+        }
+      }
+    },
+    "readData": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "target",
+        "mode",
+        "source",
+        "truncated",
+        "line_count",
+        "text"
+      ],
+      "properties": {
+        "target": {
+          "$ref": "#/$defs/target"
+        },
+        "mode": {
+          "enum": [
+            "snapshot",
+            "last"
+          ]
+        },
+        "last": {
+          "anyOf": [
+            {
+              "type": "integer",
+              "minimum": 1
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "source": {
+          "enum": [
+            "screen",
+            "scrollback",
+            "mixed",
+            "detection"
+          ]
+        },
+        "truncated": {
+          "type": "boolean"
+        },
+        "line_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "text": {
+          "type": "string"
+        },
+        "stabilized": {
+          "type": "boolean"
+        },
+        "waited_ms": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "samples": {
+          "type": "integer",
+          "minimum": 1
+        }
+      }
+    },
+    "handoffRepo": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "branch",
+        "is_git",
+        "changed_file_count",
+        "insertions",
+        "deletions"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "branch": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "is_git": {
+          "type": "boolean"
+        },
+        "changed_file_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "insertions": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "deletions": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "handoffSession": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "agent",
+        "pane_id",
+        "pane_title",
+        "source",
+        "confidence",
+        "excerpt_path",
+        "transcript_path"
+      ],
+      "properties": {
+        "agent": {
+          "anyOf": [
+            {
+              "type": "string",
+              "minLength": 1
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "session_id": {
+          "anyOf": [
+            {
+              "type": "string",
+              "minLength": 1
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "pane_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "pane_title": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "source": {
+          "type": "string",
+          "minLength": 1
+        },
+        "confidence": {
+          "type": "string",
+          "minLength": 1
+        },
+        "excerpt_path": {
+          "anyOf": [
+            {
+              "type": "string",
+              "minLength": 1
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "transcript_path": {
+          "anyOf": [
+            {
+              "type": "string",
+              "minLength": 1
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      }
+    },
+    "handoffPane": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "worktree_id",
+        "worktree_name",
+        "tab_id",
+        "pane_id",
+        "pane_title"
+      ],
+      "properties": {
+        "worktree_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "worktree_name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "tab_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "pane_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "pane_title": {
+          "type": "string"
+        }
+      }
+    },
+    "handoffData": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "action",
+        "artifact_path",
+        "repos",
+        "changed_file_count",
+        "has_briefing"
+      ],
+      "properties": {
+        "action": {
+          "enum": [
+            "save",
+            "to"
+          ]
+        },
+        "artifact_path": {
+          "type": "string",
+          "minLength": 1
+        },
+        "outgoing_agent": {
+          "anyOf": [
+            {
+              "type": "string",
+              "minLength": 1
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "to_agent": {
+          "anyOf": [
+            {
+              "type": "string",
+              "minLength": 1
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "repos": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/handoffRepo"
+          }
+        },
+        "changed_file_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "archived_path": {
+          "anyOf": [
+            {
+              "type": "string",
+              "minLength": 1
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "session_context": {
+          "$ref": "#/$defs/handoffSession"
+        },
+        "briefing": {
+          "anyOf": [
+            {
+              "enum": [
+                "inline",
+                "fork",
+                "none",
+                "failed"
+              ]
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "has_briefing": {
+          "type": "boolean"
+        },
+        "launched_pane": {
+          "$ref": "#/$defs/handoffPane"
+        }
+      }
+    },
+    "openTarget": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "worktree",
+        "tab",
+        "pane"
+      ],
+      "properties": {
+        "worktree": {
+          "$ref": "#/$defs/worktree"
+        },
+        "tab": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "id",
+            "title",
+            "cwd"
+          ],
+          "properties": {
+            "id": {
+              "type": "string",
+              "minLength": 1
+            },
+            "title": {
+              "type": "string"
+            },
+            "cwd": {
+              "anyOf": [
+                {
+                  "type": "string",
+                  "minLength": 1
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            }
+          }
+        },
+        "pane": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "id",
+            "title",
+            "cwd"
+          ],
+          "properties": {
+            "id": {
+              "type": "string",
+              "minLength": 1
+            },
+            "title": {
+              "type": "string"
+            },
+            "cwd": {
+              "anyOf": [
+                {
+                  "type": "string",
+                  "minLength": 1
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            }
+          }
+        }
+      }
+    },
+    "openData": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "invocation",
+        "requested_path",
+        "resolved_path",
+        "resolution",
+        "app_launched",
+        "brought_to_front",
+        "created_tab",
+        "target"
+      ],
+      "properties": {
+        "invocation": {
+          "enum": [
+            "bare",
+            "implicit-open",
+            "open-subcommand"
+          ]
+        },
+        "requested_path": {
+          "anyOf": [
+            {
+              "type": "string",
+              "minLength": 1
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "resolved_path": {
+          "anyOf": [
+            {
+              "type": "string",
+              "minLength": 1
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "resolution": {
+          "enum": [
+            "no-argument",
+            "exact-root",
+            "inside-root",
+            "new-root"
+          ]
+        },
+        "app_launched": {
+          "type": "boolean"
+        },
+        "brought_to_front": {
+          "type": "boolean"
+        },
+        "created_tab": {
+          "type": "boolean"
+        },
+        "target": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/openTarget"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      }
+    },
+    "openResponse": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "ok",
+            "command",
+            "schema_version",
+            "data"
+          ],
+          "properties": {
+            "ok": {
+              "const": true
+            },
+            "command": {
+              "const": "open"
+            },
+            "schema_version": {
+              "const": "prowl.cli.open.v1"
+            },
+            "data": {
+              "$ref": "#/$defs/openData"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "ok",
+            "command",
+            "schema_version",
+            "error"
+          ],
+          "properties": {
+            "ok": {
+              "const": false
+            },
+            "command": {
+              "const": "open"
+            },
+            "schema_version": {
+              "const": "prowl.cli.open.v1"
+            },
+            "error": {
+              "$ref": "#/$defs/error"
+            }
+          }
+        }
+      ]
+    },
+    "listResponse": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "ok",
+            "command",
+            "schema_version",
+            "data"
+          ],
+          "properties": {
+            "ok": {
+              "const": true
+            },
+            "command": {
+              "const": "list"
+            },
+            "schema_version": {
+              "const": "prowl.cli.list.v1"
+            },
+            "data": {
+              "$ref": "#/$defs/listData"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "ok",
+            "command",
+            "schema_version",
+            "error"
+          ],
+          "properties": {
+            "ok": {
+              "const": false
+            },
+            "command": {
+              "const": "list"
+            },
+            "schema_version": {
+              "const": "prowl.cli.list.v1"
+            },
+            "error": {
+              "$ref": "#/$defs/error"
+            }
+          }
+        }
+      ]
+    },
+    "agentsResponse": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "ok",
+            "command",
+            "schema_version",
+            "data"
+          ],
+          "properties": {
+            "ok": {
+              "const": true
+            },
+            "command": {
+              "const": "agents"
+            },
+            "schema_version": {
+              "const": "prowl.cli.agents.v1"
+            },
+            "data": {
+              "$ref": "#/$defs/agentsData"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "ok",
+            "command",
+            "schema_version",
+            "error"
+          ],
+          "properties": {
+            "ok": {
+              "const": false
+            },
+            "command": {
+              "const": "agents"
+            },
+            "schema_version": {
+              "const": "prowl.cli.agents.v1"
+            },
+            "error": {
+              "$ref": "#/$defs/error"
+            }
+          }
+        }
+      ]
+    },
+    "agentsReadResponse": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "ok",
+            "command",
+            "schema_version",
+            "data"
+          ],
+          "properties": {
+            "ok": {
+              "const": true
+            },
+            "command": {
+              "const": "agents.read"
+            },
+            "schema_version": {
+              "const": "prowl.cli.agents.read.v1"
+            },
+            "data": {
+              "$ref": "#/$defs/agentReadData"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "ok",
+            "command",
+            "schema_version",
+            "error"
+          ],
+          "properties": {
+            "ok": {
+              "const": false
+            },
+            "command": {
+              "const": "agents.read"
+            },
+            "schema_version": {
+              "const": "prowl.cli.agents.read.v1"
+            },
+            "error": {
+              "$ref": "#/$defs/error"
+            }
+          }
+        }
+      ]
+    },
+    "focusResponse": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "ok",
+            "command",
+            "schema_version",
+            "data"
+          ],
+          "properties": {
+            "ok": {
+              "const": true
+            },
+            "command": {
+              "const": "focus"
+            },
+            "schema_version": {
+              "const": "prowl.cli.focus.v1"
+            },
+            "data": {
+              "$ref": "#/$defs/focusData"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "ok",
+            "command",
+            "schema_version",
+            "error"
+          ],
+          "properties": {
+            "ok": {
+              "const": false
+            },
+            "command": {
+              "const": "focus"
+            },
+            "schema_version": {
+              "const": "prowl.cli.focus.v1"
+            },
+            "error": {
+              "$ref": "#/$defs/error"
+            }
+          }
+        }
+      ]
+    },
+    "sendResponse": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "ok",
+            "command",
+            "schema_version",
+            "data"
+          ],
+          "properties": {
+            "ok": {
+              "const": true
+            },
+            "command": {
+              "const": "send"
+            },
+            "schema_version": {
+              "const": "prowl.cli.send.v1"
+            },
+            "data": {
+              "$ref": "#/$defs/sendData"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "ok",
+            "command",
+            "schema_version",
+            "error"
+          ],
+          "properties": {
+            "ok": {
+              "const": false
+            },
+            "command": {
+              "const": "send"
+            },
+            "schema_version": {
+              "const": "prowl.cli.send.v1"
+            },
+            "error": {
+              "$ref": "#/$defs/error"
+            }
+          }
+        }
+      ]
+    },
+    "keyResponse": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "ok",
+            "command",
+            "schema_version",
+            "data"
+          ],
+          "properties": {
+            "ok": {
+              "const": true
+            },
+            "command": {
+              "const": "key"
+            },
+            "schema_version": {
+              "const": "prowl.cli.key.v1"
+            },
+            "data": {
+              "$ref": "#/$defs/keyData"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "ok",
+            "command",
+            "schema_version",
+            "error"
+          ],
+          "properties": {
+            "ok": {
+              "const": false
+            },
+            "command": {
+              "const": "key"
+            },
+            "schema_version": {
+              "const": "prowl.cli.key.v1"
+            },
+            "error": {
+              "$ref": "#/$defs/error"
+            }
+          }
+        }
+      ]
+    },
+    "readResponse": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "ok",
+            "command",
+            "schema_version",
+            "data"
+          ],
+          "properties": {
+            "ok": {
+              "const": true
+            },
+            "command": {
+              "const": "read"
+            },
+            "schema_version": {
+              "const": "prowl.cli.read.v1"
+            },
+            "data": {
+              "$ref": "#/$defs/readData"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "ok",
+            "command",
+            "schema_version",
+            "error"
+          ],
+          "properties": {
+            "ok": {
+              "const": false
+            },
+            "command": {
+              "const": "read"
+            },
+            "schema_version": {
+              "const": "prowl.cli.read.v1"
+            },
+            "error": {
+              "$ref": "#/$defs/error"
+            }
+          }
+        }
+      ]
+    },
+    "createResponse": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "ok",
+            "command",
+            "schema_version",
+            "data"
+          ],
+          "properties": {
+            "ok": {
+              "const": true
+            },
+            "command": {
+              "const": "create"
+            },
+            "schema_version": {
+              "const": "prowl.cli.create.v1"
+            },
+            "data": {
+              "$ref": "#/$defs/lifecycleData"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "ok",
+            "command",
+            "schema_version",
+            "error"
+          ],
+          "properties": {
+            "ok": {
+              "const": false
+            },
+            "command": {
+              "const": "create"
+            },
+            "schema_version": {
+              "const": "prowl.cli.create.v1"
+            },
+            "error": {
+              "$ref": "#/$defs/error"
+            }
+          }
+        }
+      ]
+    },
+    "closeResponse": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "ok",
+            "command",
+            "schema_version",
+            "data"
+          ],
+          "properties": {
+            "ok": {
+              "const": true
+            },
+            "command": {
+              "const": "close"
+            },
+            "schema_version": {
+              "const": "prowl.cli.close.v1"
+            },
+            "data": {
+              "$ref": "#/$defs/lifecycleData"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "ok",
+            "command",
+            "schema_version",
+            "error"
+          ],
+          "properties": {
+            "ok": {
+              "const": false
+            },
+            "command": {
+              "const": "close"
+            },
+            "schema_version": {
+              "const": "prowl.cli.close.v1"
+            },
+            "error": {
+              "$ref": "#/$defs/error"
+            }
+          }
+        }
+      ]
+    },
+    "tabResponse": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "ok",
+            "command",
+            "schema_version",
+            "data"
+          ],
+          "properties": {
+            "ok": {
+              "const": true
+            },
+            "command": {
+              "const": "tab"
+            },
+            "schema_version": {
+              "const": "prowl.cli.tab.v1"
+            },
+            "data": {
+              "$ref": "#/$defs/tabData"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "ok",
+            "command",
+            "schema_version",
+            "error"
+          ],
+          "properties": {
+            "ok": {
+              "const": false
+            },
+            "command": {
+              "const": "tab"
+            },
+            "schema_version": {
+              "const": "prowl.cli.tab.v1"
+            },
+            "error": {
+              "$ref": "#/$defs/error"
+            }
+          }
+        }
+      ]
+    },
+    "paneResponse": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "ok",
+            "command",
+            "schema_version",
+            "data"
+          ],
+          "properties": {
+            "ok": {
+              "const": true
+            },
+            "command": {
+              "const": "pane"
+            },
+            "schema_version": {
+              "const": "prowl.cli.pane.v1"
+            },
+            "data": {
+              "$ref": "#/$defs/paneData"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "ok",
+            "command",
+            "schema_version",
+            "error"
+          ],
+          "properties": {
+            "ok": {
+              "const": false
+            },
+            "command": {
+              "const": "pane"
+            },
+            "schema_version": {
+              "const": "prowl.cli.pane.v1"
+            },
+            "error": {
+              "$ref": "#/$defs/error"
+            }
+          }
+        }
+      ]
+    },
+    "handoffResponse": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "ok",
+            "command",
+            "schema_version",
+            "data"
+          ],
+          "properties": {
+            "ok": {
+              "const": true
+            },
+            "command": {
+              "const": "handoff"
+            },
+            "schema_version": {
+              "const": "prowl.cli.handoff.v2"
+            },
+            "data": {
+              "$ref": "#/$defs/handoffData"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "ok",
+            "command",
+            "schema_version",
+            "error"
+          ],
+          "properties": {
+            "ok": {
+              "const": false
+            },
+            "command": {
+              "const": "handoff"
+            },
+            "schema_version": {
+              "const": "prowl.cli.handoff.v2"
+            },
+            "error": {
+              "$ref": "#/$defs/error"
+            }
+          }
+        }
+      ]
+    }
+  }
+}
diff --git a/ProwlCLITests/ProwlCLIIntegrationTests.swift b/ProwlCLITests/ProwlCLIIntegrationTests.swift
index 4a31e55d..46d31fe4 100644
--- a/ProwlCLITests/ProwlCLIIntegrationTests.swift
+++ b/ProwlCLITests/ProwlCLIIntegrationTests.swift
@@ -4,6 +4,8 @@ import Darwin
 import Glibc
 #endif
 import Foundation
+import JSONSchema
+import ProwlCLIContracts
 import ProwlCLIShared
 import XCTest
 
@@ -37,6 +39,18 @@ final class ProwlCLIIntegrationTests: XCTestCase {
     let help = try runProwl(args: ["--help"])
     XCTAssertEqual(help.exitCode, 0)
     XCTAssertTrue(help.stdout.contains("USAGE:"))
+    XCTAssertTrue(help.stdout.contains("create"))
+    XCTAssertTrue(help.stdout.contains("close"))
+  }
+
+  func testLegacyLifecycleHelpIsMarkedDeprecated() throws {
+    let tabHelp = try runProwl(args: ["tab", "--help"])
+    XCTAssertEqual(tabHelp.exitCode, 0)
+    XCTAssertTrue(tabHelp.stdout.contains("[Deprecated]"))
+
+    let paneHelp = try runProwl(args: ["pane", "--help"])
+    XCTAssertEqual(paneHelp.exitCode, 0)
+    XCTAssertTrue(paneHelp.stdout.contains("[Deprecated]"))
   }
 
   func testListReturnsAppNotRunningWhenSocketUnavailable() throws {
@@ -330,6 +344,172 @@ final class ProwlCLIIntegrationTests: XCTestCase {
     }
   }
 
+  func testReadPositionalPrefixedPaneHandleRoundTripsOverSocket() throws {
+    let socketPath = temporarySocketPath(suffix: "read-pane-handle")
+    let response = CommandResponse(
+      ok: true,
+      command: "read",
+      schemaVersion: "prowl.cli.read.v1"
+    )
+
+    let (requestData, result) = try runWithMockServer(
+      socketPath: socketPath,
+      response: response,
+      args: ["read", "p12", "--json"]
+    )
+
+    XCTAssertEqual(result.exitCode, 0)
+    let envelope = try JSONDecoder().decode(CommandEnvelope.self, from: requestData)
+    if case .read(let input) = envelope.command {
+      XCTAssertEqual(input.selector, .auto("p12"))
+    } else {
+      XCTFail("Expected read command envelope")
+    }
+  }
+
+  func testCreateTabCommandRoundTripsOverSocket() throws {
+    let socketPath = temporarySocketPath(suffix: "create-tab")
+    let response = try CommandResponse(
+      ok: true,
+      command: "create",
+      schemaVersion: "prowl.cli.create.v1",
+      data: RawJSON(encoding: makeLifecyclePayload(resource: .tab))
+    )
+
+    let (requestData, result) = try runWithMockServer(
+      socketPath: socketPath,
+      response: response,
+      args: ["create", "tab", "App", "--path", "/Projects/App", "--json"]
+    )
+
+    XCTAssertEqual(result.exitCode, 0)
+    let envelope = try JSONDecoder().decode(CommandEnvelope.self, from: requestData)
+    if case .create(let input) = envelope.command {
+      XCTAssertEqual(input.resource, .tab)
+      XCTAssertEqual(input.selector, .worktree("App"))
+      XCTAssertEqual(input.path, "/Projects/App")
+    } else {
+      XCTFail("Expected create command envelope")
+    }
+  }
+
+  func testCloseCommandRoundTripsOverSocket() throws {
+    let socketPath = temporarySocketPath(suffix: "close-pane")
+    let response = try CommandResponse(
+      ok: true,
+      command: "close",
+      schemaVersion: "prowl.cli.close.v1",
+      data: RawJSON(encoding: makeLifecyclePayload(resource: .pane))
+    )
+
+    let (requestData, result) = try runWithMockServer(
+      socketPath: socketPath,
+      response: response,
+      args: ["close", "p12", "--force", "--json"]
+    )
+
+    XCTAssertEqual(result.exitCode, 0)
+    let envelope = try JSONDecoder().decode(CommandEnvelope.self, from: requestData)
+    if case .close(let input) = envelope.command {
+      XCTAssertEqual(input.selector, .auto("p12"))
+      XCTAssertTrue(input.force)
+    } else {
+      XCTFail("Expected close command envelope")
+    }
+  }
+
+  func testCloseAcceptsTypedTabSelector() throws {
+    let socketPath = temporarySocketPath(suffix: "close-tab")
+    let response = try CommandResponse(
+      ok: true,
+      command: "close",
+      schemaVersion: "prowl.cli.close.v1",
+      data: RawJSON(encoding: makeLifecyclePayload(resource: .tab))
+    )
+
+    let (requestData, result) = try runWithMockServer(
+      socketPath: socketPath,
+      response: response,
+      args: ["close", "--tab", "t6", "--json"]
+    )
+
+    XCTAssertEqual(result.exitCode, 0)
+    let envelope = try JSONDecoder().decode(CommandEnvelope.self, from: requestData)
+    if case .close(let input) = envelope.command {
+      XCTAssertEqual(input.selector, .tab("t6"))
+    } else {
+      XCTFail("Expected close command envelope")
+    }
+  }
+
+  func testCloseRejectsMissingTargetBeforeTransport() throws {
+    let result = try runProwl(args: ["close", "--json"])
+
+    XCTAssertNotEqual(result.exitCode, 0)
+    let payload = try jsonObject(from: result.stdout)
+    XCTAssertEqual(payload["ok"] as? Bool, false)
+    XCTAssertEqual(payload["command"] as? String, "close")
+    let error = try XCTUnwrap(payload["error"] as? [String: Any])
+    XCTAssertEqual(error["code"] as? String, CLIErrorCode.invalidArgument)
+  }
+
+  func testCloseRejectsWorktreeBeforeTransport() throws {
+    let result = try runProwl(args: ["close", "App", "--json"])
+
+    XCTAssertNotEqual(result.exitCode, 0)
+    let payload = try jsonObject(from: result.stdout)
+    XCTAssertEqual(payload["ok"] as? Bool, false)
+    XCTAssertEqual(payload["command"] as? String, "close")
+    let error = try XCTUnwrap(payload["error"] as? [String: Any])
+    XCTAssertEqual(error["code"] as? String, CLIErrorCode.invalidArgument)
+  }
+
+  func testCloseRejectsWorktreeSelectorBeforeTransport() throws {
+    let result = try runProwl(args: ["close", "--worktree", "App", "--json"])
+
+    XCTAssertNotEqual(result.exitCode, 0)
+    let payload = try jsonObject(from: result.stdout)
+    XCTAssertEqual(payload["ok"] as? Bool, false)
+    XCTAssertEqual(payload["command"] as? String, "close")
+    let error = try XCTUnwrap(payload["error"] as? [String: Any])
+    XCTAssertEqual(error["code"] as? String, CLIErrorCode.invalidArgument)
+  }
+
+  func testCreateTabRejectsPaneSelectorBeforeTransport() throws {
+    let result = try runProwl(args: ["create", "tab", "--pane", "p12", "--json"])
+
+    XCTAssertNotEqual(result.exitCode, 0)
+    let payload = try jsonObject(from: result.stdout)
+    XCTAssertEqual(payload["ok"] as? Bool, false)
+    XCTAssertEqual(payload["command"] as? String, "create")
+    let error = try XCTUnwrap(payload["error"] as? [String: Any])
+    XCTAssertEqual(error["code"] as? String, CLIErrorCode.invalidArgument)
+  }
+
+  func testDeprecatedTabCreateWarnsWithoutChangingLegacyEnvelope() throws {
+    let socketPath = temporarySocketPath(suffix: "deprecated-tab-create")
+    let response = CommandResponse(
+      ok: true,
+      command: "tab",
+      schemaVersion: "prowl.cli.tab.v1"
+    )
+
+    let (requestData, result) = try runWithMockServer(
+      socketPath: socketPath,
+      response: response,
+      args: ["tab", "create", "--worktree", "App", "--json"]
+    )
+
+    XCTAssertEqual(result.exitCode, 0)
+    XCTAssertTrue(result.stderr.contains("deprecated"))
+    let envelope = try JSONDecoder().decode(CommandEnvelope.self, from: requestData)
+    if case .tab = envelope.command {
+      // Expected legacy transport contract during the deprecation window.
+    } else {
+      XCTFail("Expected tab command envelope")
+    }
+  }
+
   func testTabCreateCommandRoundTripsOverSocket() throws {
     let socketPath = temporarySocketPath(suffix: "tab-create")
     let response = try CommandResponse(
@@ -1992,6 +2172,7 @@ final class ProwlCLIIntegrationTests: XCTestCase {
     responseData: Data,
     args: [String]
   ) throws -> (Data, CommandResult) {
+    try assertResponseMatchesSchema(responseData)
     let server = try MockSocketServer(socketPath: socketPath, responseData: responseData)
     defer { server.stop() }
     try server.start()
@@ -2005,6 +2186,24 @@ final class ProwlCLIIntegrationTests: XCTestCase {
     return (requestData, result)
   }
 
+  private func assertResponseMatchesSchema(_ responseData: Data) throws {
+    let response = try JSONDecoder().decode(CommandResponse.self, from: responseData)
+    guard response.data != nil || response.ok == false else { return }
+
+    let schemaText = try XCTUnwrap(String(data: ProwlCLIContractBundle.schemaData, encoding: .utf8))
+    let responseText = try XCTUnwrap(String(data: responseData, encoding: .utf8))
+    let schema = try Schema(instance: schemaText)
+    let result = try schema.validate(instance: responseText)
+    XCTAssertTrue(
+      result.isValid,
+      "Socket response violates JSON Schema for \(response.command) \(response.schemaVersion)."
+    )
+  }
+
+  private func makeLifecyclePayload(resource: LifecycleResource) -> LifecycleCommandPayload {
+    LifecycleCommandPayload(resource: resource, target: makeTabTarget())
+  }
+
   private func makeTabPayload(action: TabAction) -> TabCommandPayload {
     TabCommandPayload(action: action, target: makeTabTarget())
   }
@@ -2197,9 +2396,43 @@ private struct OpenResponseData: Encodable {
     case resolution
     case appLaunched = "app_launched"
     case broughtToFront = "brought_to_front"
+    case createdTab = "created_tab"
+    case target
   }
 
   let broughtToFront: Bool
+  let createdTab = false
+  let target: OpenResponseTarget? = nil
+
+  func encode(to encoder: Encoder) throws {
+    var container = encoder.container(keyedBy: CodingKeys.self)
+    try container.encode(invocation, forKey: .invocation)
+    try container.encode(requestedPath, forKey: .requestedPath)
+    try container.encode(resolvedPath, forKey: .resolvedPath)
+    try container.encode(resolution, forKey: .resolution)
+    try container.encode(appLaunched, forKey: .appLaunched)
+    try container.encode(broughtToFront, forKey: .broughtToFront)
+    try container.encode(createdTab, forKey: .createdTab)
+    try container.encode(target, forKey: .target)
+  }
+}
+
+private struct OpenResponseTarget: Encodable {
+  let worktree: ListWorktree
+  let tab: OpenResponseTab
+  let pane: OpenResponsePane
+}
+
+private struct OpenResponseTab: Encodable {
+  let id: String
+  let title: String
+  let cwd: String?
+}
+
+private struct OpenResponsePane: Encodable {
+  let id: String
+  let title: String
+  let cwd: String?
 }
 
 
@@ -2252,13 +2485,22 @@ private struct ListPane: Encodable {
   let title: String
   let cwd: String?
   let focused: Bool
+  let agent: String?
 
-  init(id: String, handle: Int? = nil, title: String, cwd: String?, focused: Bool) {
+  init(
+    id: String,
+    handle: Int? = nil,
+    title: String,
+    cwd: String?,
+    focused: Bool,
+    agent: String? = nil
+  ) {
     self.id = id
     self.handle = handle
     self.title = title
     self.cwd = cwd
     self.focused = focused
+    self.agent = agent
   }
 }
 
diff --git a/docs-ai/013-prowl-cli/contracts/agents.md b/docs-ai/013-prowl-cli/contracts/agents.md
new file mode 100644
index 00000000..20444307
--- /dev/null
+++ b/docs-ai/013-prowl-cli/contracts/agents.md
@@ -0,0 +1,18 @@
+# `prowl agents` Contract
+
+Current version: `prowl.cli.agents.v1`.
+
+```bash
+prowl agents [--json]
+```
+
+The command is global discovery and accepts no target selector. It returns
+`count` and an `agents` array. Each entry has its canonical pane `id`, detected
+agent `type`/`name`, `status`, `raw_state`, optional `detection_reason`,
+`last_changed_at`, project/worktree/tab/pane metadata, and optional session
+attribution. Text output additionally shows a current-process `pN` handle.
+
+Use `prowl agents read <pN|pane-uuid>` for a semantic agent snapshot; that command
+has its own [contract](agents-read.md). The complete roster response schema is
+`#/$defs/agentsResponse` in
+[`schema-bundle.json`](../../../ProwlCLIContracts/Resources/cli-output-schema.json).
diff --git a/docs-ai/013-prowl-cli/contracts/architecture.md b/docs-ai/013-prowl-cli/contracts/architecture.md
index 4f0be0e8..ea2d933f 100644
--- a/docs-ai/013-prowl-cli/contracts/architecture.md
+++ b/docs-ai/013-prowl-cli/contracts/architecture.md
@@ -83,6 +83,9 @@ Phase-1 commands are **remote-control actions on running app state**.
   - `SendCommandHandler`
   - `KeyCommandHandler`
   - `ReadCommandHandler`
+  - `LifecycleCommandHandler` (`create`, `close`)
+  - legacy `TabCommandHandler` / `PaneCommandHandler` during deprecation
+  - `AgentsCommandHandler`, `AgentReadCommandHandler`, and `HandoffCommandHandler`
 - Shared services
   - `TargetResolver`
   - `TerminalCommandBridge`
@@ -140,18 +143,14 @@ Resolution belongs to app runtime (state-aware), with CLI only enforcing selecto
 
 ## 7) Mapping to existing contracts
 
-- Input normalization rules: `input.md`
-- Output contracts:
-  - `open.md`
-  - `list.md`
-  - `focus.md`
-  - `send.md`
-  - `key.md`
-  - `read.md`
-- JSON schema validation source:
-  - `schema.md`
+- Input normalization rules: `input.md` and `targeting.md`
+- Output contracts: one document per wire command, including `create.md`, `close.md`,
+  deprecated `tab.md` / `pane.md`, `agents.md`, and `handoff.md`.
+- JSON schema validation source: the machine-readable bundle linked by `schema.md`.
 
-Implementation MUST be validated against `schema.md` for `--json` mode.
+Every payload-bearing mock socket response is validated against that Draft 2020-12
+bundle in `ProwlCLIIntegrationTests`; typed model tests are supplementary, not a
+replacement for schema validation.
 
 ---
 
@@ -181,7 +180,7 @@ Implementation MUST be validated against `schema.md` for `--json` mode.
 ## M4 — test and harden
 
 - parser unit tests (argv matrix)
-- contract tests (`--json` payload schema validation)
+- contract tests (Draft 2020-12 validation of raw socket-response bytes)
 - integration tests for `list->focus->send/key->read` loops
 
 ---
@@ -194,7 +193,7 @@ Implementation MUST be validated against `schema.md` for `--json` mode.
   - stdin/argv source rules for `send`
   - `--last` and `--repeat` constraints
 - Contract tests:
-  - validate JSON against `schema.md` refs per subcommand
+  - validate every payload-bearing socket response against the executable schema bundle
 - Runtime integration tests:
   - open exact-root / inside-root / new-root
   - key alias normalization and repeat delivery counters
diff --git a/docs-ai/013-prowl-cli/contracts/close.md b/docs-ai/013-prowl-cli/contracts/close.md
new file mode 100644
index 00000000..5d8b75fc
--- /dev/null
+++ b/docs-ai/013-prowl-cli/contracts/close.md
@@ -0,0 +1,50 @@
+# `prowl close` Contract
+
+## Status
+
+Current version: `prowl.cli.close.v1`.
+
+`close` is the action-first destructive lifecycle command. Its target spelling
+selects the resource to close; it never projects a worktree to a focused tab/pane.
+
+## Input
+
+```bash
+prowl close <pane-or-tab> [--force] [--json]
+prowl close --pane <pane> [--force] [--json]
+prowl close --tab <tab> [--force] [--json]
+```
+
+The positional form accepts only a UUID, `pN`, or `tN`. A prefixed handle routes to
+that resource type; an unprefixed UUID resolves pane first, then tab. `--pane` and
+`--tab` retain typed bare-number handles. A target is mandatory.
+
+Reject `--target`, `--worktree`, bare-number positionals, cross-selector mixing,
+and positional-plus-selector mixing with `INVALID_ARGUMENT` before transport.
+
+Without `--force`, protected agent work or a running command may trigger the same
+GUI confirmation policy as an app-originated close. `--force` skips that policy and
+must only be used after identifying the target.
+
+## Success
+
+```json
+{
+  "ok": true,
+  "command": "close",
+  "schema_version": "prowl.cli.close.v1",
+  "data": {
+    "resource": "pane",
+    "target": { "worktree": { "id": "…" }, "tab": { "id": "…" }, "pane": { "id": "…" } }
+  }
+}
+```
+
+`resource` is `pane` or `tab`; `target` describes the resource immediately before
+it was closed.
+
+## Errors
+
+`INVALID_ARGUMENT`, `TARGET_NOT_FOUND`, `TARGET_NOT_UNIQUE`, and `CLOSE_FAILED`
+use the common response envelope in
+[`schema-bundle.json`](../../../ProwlCLIContracts/Resources/cli-output-schema.json).
diff --git a/docs-ai/013-prowl-cli/contracts/create.md b/docs-ai/013-prowl-cli/contracts/create.md
new file mode 100644
index 00000000..372d27b4
--- /dev/null
+++ b/docs-ai/013-prowl-cli/contracts/create.md
@@ -0,0 +1,49 @@
+# `prowl create` Contract
+
+## Status
+
+Current version: `prowl.cli.create.v1`.
+
+`create` is the action-first lifecycle namespace. V1 exposes only `create tab`;
+`create pane` is reserved for [#699](https://github.com/onevcat/Prowl/issues/699).
+
+## Input
+
+```bash
+prowl create tab <worktree> [--path <directory>] [--json]
+prowl create tab --worktree <worktree> [--path <directory>] [--json]
+```
+
+Exactly one positional worktree reference or `--worktree` is required. `--pane`,
+`--tab`, `--target`, and a positional-plus-flag combination fail before transport
+with `INVALID_ARGUMENT`.
+
+`--path` is normalized by the CLI and must be the resolved worktree root or a
+subdirectory of it. A path outside the worktree fails with `PATH_NOT_ALLOWED`.
+
+## Success
+
+```json
+{
+  "ok": true,
+  "command": "create",
+  "schema_version": "prowl.cli.create.v1",
+  "data": {
+    "resource": "tab",
+    "target": {
+      "worktree": { "id": "…", "name": "App", "path": "/…", "root_path": "/…", "kind": "git" },
+      "tab": { "id": "…", "title": "zsh", "selected": true },
+      "pane": { "id": "…", "title": "zsh", "cwd": "/…", "focused": true }
+    }
+  }
+}
+```
+
+`target` identifies the newly created tab and its initial pane. Its UUID fields
+are the automation-safe output of this command.
+
+## Errors
+
+`INVALID_ARGUMENT`, `TARGET_NOT_FOUND`, `TARGET_NOT_UNIQUE`, `PATH_NOT_ALLOWED`,
+and `CREATE_FAILED` use the common error envelope in
+[`schema-bundle.json`](../../../ProwlCLIContracts/Resources/cli-output-schema.json).
diff --git a/docs-ai/013-prowl-cli/contracts/focus.md b/docs-ai/013-prowl-cli/contracts/focus.md
index 309d1b75..ad38450e 100644
--- a/docs-ai/013-prowl-cli/contracts/focus.md
+++ b/docs-ai/013-prowl-cli/contracts/focus.md
@@ -16,10 +16,10 @@ This file defines the **JSON output contract** for:
 
 ## Supported selectors
 
-- `--worktree <id|name|path>`
-- `--tab <id>`
-- `--pane <id>`
-- no selector, meaning “focus current target”
+`focus` uses [targeting.md](targeting.md): `--pane` / `--tab` accept typed handles,
+and `--target` or the optional positional target accept UUIDs, worktree references,
+and prefixed `pN` / `tN` handles. A positional target plus selector flag is invalid;
+no selector means “focus current target”.
 
 ## Success payload
 
@@ -70,7 +70,7 @@ This file defines the **JSON output contract** for:
 
 ### `requested`
 
-- `selector`: `"worktree"` | `"tab"` | `"pane"` | `"current"`
+- `selector`: `"worktree"` | `"tab"` | `"pane"` | `"auto"` | `"current"`
 - `value`: string or `null`
   - `null` only when `selector == "current"`.
 
diff --git a/docs-ai/013-prowl-cli/contracts/handoff.md b/docs-ai/013-prowl-cli/contracts/handoff.md
new file mode 100644
index 00000000..222379e1
--- /dev/null
+++ b/docs-ai/013-prowl-cli/contracts/handoff.md
@@ -0,0 +1,19 @@
+# `prowl handoff` Contract
+
+Current version: `prowl.cli.handoff.v2`.
+
+```bash
+prowl handoff save [source] [--brief -|--no-brief] [--note <text>] [--json]
+prowl handoff to <agent> [source] [--brief -|--no-brief] [--note <text>] [--no-launch] [--json]
+```
+
+An explicit generic target follows [targeting.md](targeting.md). With no source,
+handoff resolves the pane that spawned the CLI process; it never uses unstable UI
+focus. `--brief -` reads a validated briefing from stdin, while `--no-brief` is the
+explicit context-only mode.
+
+The success payload reports `action`, `artifact_path`, source/destination agents,
+repository summary, change count, briefing state, optional archived path/session
+context, and optional launched pane. The complete response contract, including the
+v2 schema discriminator, is `#/$defs/handoffResponse` in
+[`schema-bundle.json`](../../../ProwlCLIContracts/Resources/cli-output-schema.json).
diff --git a/docs-ai/013-prowl-cli/contracts/input.md b/docs-ai/013-prowl-cli/contracts/input.md
index 502fab35..895aa8ae 100644
--- a/docs-ai/013-prowl-cli/contracts/input.md
+++ b/docs-ai/013-prowl-cli/contracts/input.md
@@ -1,379 +1,67 @@
-# CLI Input Contract: `prowl` (v1)
+# Prowl CLI Input Contract
 
-> Living normative contract of entry 013. Migrated from `doc-onevcat/contracts/cli/input.md` on 2026-07-12; update in place.
+This document owns argv/stdin grammar. Shared target semantics live in
+[targeting.md](targeting.md); JSON response contracts live in the command documents
+and the executable [schema bundle](schema.md).
 
-Status: draft truth source for `#70` implementation.
+## Root grammar
 
-This file defines **input-side** rules for the phase-1 CLI commands:
-
-- `open`
-- `list`
-- `agents` (including `agents read`)
-- `focus`
-- `send`
-- `key`
-- `read`
-
-It complements output contracts under `docs-ai/013-prowl-cli/contracts/{open,list,focus,send,key,read,agents-read}.md`.
-
----
-
-## 1) Design goals
-
-- One stable command grammar for both humans and agents.
-- No hidden priority chains that make scripts nondeterministic.
-- Parse once in CLI layer; app layer should receive already-normalized typed requests.
-- Keep command behavior composable: `list -> focus/send/key/read`.
-
----
-
-## 2) Global command model
-
-### 2.1 Canonical form
-
-```bash
-prowl <subcommand> [target-selector] [command-args] [output-options]
-```
-
-### 2.2 Supported subcommands (v1)
-
-- `open`
-- `list`
-- `agents`
-- `focus`
-- `send`
-- `key`
-- `read`
-
-Global options (not subcommands):
-
-- `--help`
-- `--version`
-
-### 2.3 Bare path entry
-
-These are equivalent to `open` entry:
-
-- `prowl`
-- `prowl <path-like-first-arg>`
-- `prowl open <path>`
-
-Path-like first arg (v1):
-
-- `/...`
-- `./...`
-- `../...`
-- `~/...`
-- `file://...`
-- `.`
-- `..`
-
-### 2.4 `--` handling
-
-`--` stops option parsing and forces following token parsing as positional arguments.
-
-- `prowl -- ./focus` MUST be treated as path entry (`open`), not subcommand `focus`.
-- `prowl open -- --weird-dir` MUST treat `--weird-dir` as path.
-
----
-
-## 3) Target selector contract (shared)
-
-### 3.1 Selector flags
-
-- `-t <value>` / `--target <value>` — auto-resolve: try pane UUID → tab UUID → worktree id/name/path.
-- `--worktree <id|name|path>` — explicit worktree selector.
-- `--tab <id>` — explicit tab UUID or current short handle (`tN` or bare `N`).
-- `--pane <id>` — explicit pane UUID or current short handle (`pN` or bare `N`).
-
-Short handles are process-scoped, globally monotonic, and never reused after a
-target closes. They are intentionally unsupported for `--target` and positional
-auto-targeting, where a bare number can be a worktree name. JSON `id` fields
-remain canonical UUIDs.
-
-### 3.2 Positional target shorthand
-
-`focus` and `read` accept an optional positional argument as auto-target:
-
-```bash
-prowl focus <target>
-prowl read <target> --last 50
-```
-
-`send` and `key` use argument count to disambiguate:
-
-- `prowl send "text"` — 1 arg → text to current pane.
-- `prowl send <target> "text"` — 2 args → auto-target + text.
-- `prowl key enter` — 1 arg → key token to current pane.
-- `prowl key <target> enter` — 2 args → auto-target + key token.
-
-Positional targets are ignored when flag selectors (`-t`, `--worktree`, `--tab`, `--pane`) are present.
-
-### 3.3 Mutual exclusivity (hard rule)
-
-Exactly **zero or one** selector is allowed.
-
-- `0 selector`: operate on current focused target (where command allows it).
-- `1 selector`: resolve with that selector.
-- `>1 selector`: error `INVALID_ARGUMENT`.
-
-This is preferred over implicit precedence because it is easier to reason about in scripts.
-
-### 3.4 Resolution rules
-
-- `--pane`: exact pane.
-- `--tab`: current focused pane of target tab.
-- `--worktree`: selected tab + focused pane in target worktree.
-- `-t` / `--target` / positional: auto-resolve in order pane → tab → worktree.
-- none: currently focused pane in current context.
-
-If required context does not exist:
-
-- return command-specific not-found / no-active-pane error.
-
----
-
-## 4) Common output flags
-
-### 4.1 `--json`
-
-All phase-1 commands MUST support `--json`.
-
-- With `--json`, output MUST match corresponding schema in `schema.md`.
-- Without `--json`, output is human-readable text.
-
-### 4.2 Exit behavior
-
-- Success: exit code `0`
-- Failure: non-zero
-- Error payload shape in JSON mode MUST follow command contract (`error.code`, `error.message`, optional `error.details`).
-
-(Exact numeric non-zero codes can be refined later; error `code` string is the machine contract.)
-
----
-
-## 5) Per-command input rules
-
-## 5.1 `open`
-
-### Grammar
-
-```bash
-prowl
-prowl <path-like>
-prowl open <path>
+```text
+prowl [path]
+prowl open [path]
+prowl list | agents | focus | read | send | key | handoff | create | close
 ```
 
-### Rules
+Bare path forms (`/`, `./`, `../`, `~/`, `file://`, `.`, `..`) enter `open`.
+`--` stops option parsing. `--json` and `--no-color` are leaf-command output
+options; JSON stdout always contains exactly one response envelope when parsing
+succeeds.
 
-- `prowl` without path is valid and means “open app / bring to front”.
-- `prowl <path-like>` is first-class, not shorthand hack.
-- `prowl open <path>` is explicit equivalent for scripts.
-- For all open-entry forms, if app is not running, CLI MUST launch Prowl and complete the open/focus flow.
-- Path MUST be normalized by CLI:
-  - expand `~`
-  - resolve relative path to absolute path
-  - resolve `file://`
-  - normalize `.` / `..`
-- If provided path does not exist or is not a directory: error (`PATH_NOT_FOUND` / `PATH_NOT_DIRECTORY`).
+## Shared target rules
 
-## 5.2 `list`
+- Generic target positions use `GenericTarget` from [targeting.md](targeting.md).
+  Prefixed `pN`/`tN` handles work in `--target` and positional auto-targets.
+- Typed selectors are mutually exclusive. A positional target plus selector flag is
+  `INVALID_ARGUMENT`; no selector silently overrides another.
+- `send` and `key` retain count-sensitive positional grammar:
 
-### Grammar
+| Command | 0 args | 1 arg | 2 args |
+| --- | --- | --- | --- |
+| `send` | stdin → focused pane | text → focused pane | target + text |
+| `key` | invalid | token → focused pane | target + token |
 
-```bash
-prowl list [--json]
-```
-
-### Rules
-
-- `list` MUST NOT accept target selectors in v1 (it is global discovery).
-- Extra positional args: `INVALID_ARGUMENT`.
-
-## 5.2.1 `agents`
-
-### Grammar
-
-```bash
-prowl agents [--json]
-prowl agents read <pN|pane-uuid> [--max-bytes <1...4194304>] [--result-only] [--json]
-```
-
-### Rules
-
-- Plain `agents` remains global roster discovery and accepts no target selector.
-- `agents read` requires exactly one positional pane handle (`pN`) or pane UUID. It
-  intentionally accepts neither worktree/tab/focus targeting nor selector flags.
-- `pN` is the current-process handle from text `agents`; JSON callers use the canonical
-  `.data.agents[].pane.id` UUID.
-- `agents read` is an immediate snapshot: it has no timeout, wait flag, or polling mode.
-- `--max-bytes` defaults to 1,048,576 and is bounded by 1...4,194,304.
-- `--result-only` is text-only and cannot combine with `--json`.
-
-## 5.3 `focus`
-
-### Grammar
-
-```bash
-prowl focus [<target>] [--json]
-prowl focus [-t <...> | --worktree <...> | --tab <...> | --pane <...>] [--json]
-```
-
-### Rules
-
-- Optional positional `<target>` is auto-resolved (pane → tab → worktree).
-- Flag selectors override positional target.
-- No selector means “focus current target and bring app front”.
-- More than one selector is invalid.
-
-## 5.4 `send`
-
-### Grammar
-
-```bash
-prowl send [flags] <text>
-prowl send [flags] <target> <text>
-printf '...' | prowl send [flags]
-printf '...' | prowl send [flags] -t <target>
-```
-
-Where `[flags]` includes `[--no-enter] [--no-wait] [--capture] [--timeout <seconds>] [--json]` and optional selector flags (`-t`, `--worktree`, `--tab`, `--pane`).
-
-### Rules
-
-- Positional argument count determines interpretation:
-  - 0 args: read text from stdin, send to current pane.
-  - 1 arg: text to current pane.
-  - 2 args: first is auto-resolved target, second is text.
-- Flag selector (`-t`, `--worktree`, `--tab`, `--pane`) overrides positional target.
-- Input source is exactly one of positional text or stdin. Both: `INVALID_ARGUMENT`. Neither: `EMPTY_INPUT`.
-- Default sends trailing Enter; `--no-enter` disables it.
-- Default waits for command completion (requires shell integration); `--no-wait` disables it and returns immediately after delivery.
-- `--timeout <seconds>` sets the maximum wait duration (default: 30, range: 1–300). Ignored when `--no-wait` is used.
-- If the wait times out: `WAIT_TIMEOUT`.
-
-## 5.5 `key`
-
-### Grammar
-
-```bash
-prowl key [flags] <token>
-prowl key [flags] <target> <token>
-```
-
-Where `[flags]` includes `[--repeat <n>] [--json]` and optional selector flags (`-t`, `--worktree`, `--tab`, `--pane`).
-
-### Rules
+`send p12` remains text to the focused pane. Use `send p12 'text'`, or stdin with
+`--target p12`, for a target-first send.
 
-- Positional argument count determines interpretation:
-  - 1 arg: key token to current pane.
-  - 2 args: first is auto-resolved target, second is key token.
-- Flag selector overrides positional target.
-- Exactly one key token required.
-- Token parsing is case-insensitive; canonical output token is lowercase kebab-case.
-- Alias normalization follows `key.md`.
-- `--repeat` default is `1`, range `1...100`.
-- `--repeat` out of range: `INVALID_REPEAT`.
-
-## 5.6 `read`
-
-### Grammar
+## Lifecycle grammar
 
 ```bash
-prowl read [<target>] [--last <n>] [--json]
-prowl read [-t <...> | --worktree <...> | --tab <...> | --pane <...>] [--last <n>] [--json]
+prowl create tab <worktree> [--path <directory>]
+prowl create tab --worktree <worktree> [--path <directory>]
+prowl close <pN|tN|uuid> [--force]
+prowl close --pane <uuid|pN|N> [--force]
+prowl close --tab <uuid|tN|N> [--force]
 ```
 
-### Rules
-
-- `--last` optional; if omitted, mode is `snapshot`.
-- `--last <n>` requires integer `n >= 1`; otherwise `INVALID_ARGUMENT`.
-- At most one `--last` value.
-
----
-
-## 6) Reserved command tokens (v1)
-
-These tokens are reserved as first command token:
-
-- `open`
-- `list`
-- `focus`
-- `send`
-- `key`
-- `read`
-- `agents`
-
-If first token matches a reserved command, CLI MUST parse as subcommand unless forced by `--` path form.
-
-`--help` / `--version` are handled as global options, not subcommands.
-
----
-
-## 7) Normalized request model (input -> typed request)
+`create tab` requires a worktree-only target. `close` requires a pane-or-tab-only
+target and rejects `--target`, `--worktree`, bare-number positions, and focus
+fallback. See [create.md](create.md) and [close.md](close.md).
 
-CLI parser MUST produce one normalized typed request before transport.
+`tab create`, `tab close`, and `pane close` remain deprecated aliases for one
+shipped release. They keep their legacy parser/transport behavior while emitting a
+stderr warning; new automation must use the lifecycle grammar above.
 
-Example shape:
-
-```swift
-struct CommandEnvelope {
-  var output: OutputMode // text | json
-  var command: Command
-}
-
-enum Command {
-  case open(OpenInput)
-  case list(ListInput)
-  case agents(AgentsInput)
-  case agentsRead(AgentReadInput)
-  case focus(FocusInput)
-  case send(SendInput)
-  case key(KeyInput)
-  case read(ReadInput)
-}
-```
-
-This model is the handoff contract to app/transport layer.
-
----
-
-## 8) Examples (valid / invalid)
-
-Valid:
-
-```bash
-prowl .
-prowl open ~/Projects/Prowl
-prowl focus 6E1A2A10-D99F-4E3F-920C-D93AA3C05764          # auto-resolve pane UUID
-prowl focus --pane 6E1A2A10-D99F-4E3F-920C-D93AA3C05764    # explicit pane
-prowl read --pane p3 --last 200                             # explicit pane handle
-prowl tab close --tab t4 --force                            # explicit tab handle
-prowl focus main                                            # auto-resolve worktree name
-prowl agents read p7 --json                                 # immediate semantic agent snapshot
-prowl send "echo hello"                                     # text to current pane
-prowl send 6E1A2A10-D99F-4E3F-920C-D93AA3C05764 "echo hi"  # target + text
-printf 'git status' | prowl send --worktree Prowl --json
-prowl key enter                                             # key to current pane
-prowl key 6E1A2A10-D99F-4E3F-920C-D93AA3C05764 ctrl-c      # target + key
-prowl read 6E1A2A10-D99F-4E3F-920C-D93AA3C05764 --last 200 # positional target + flag
-```
-
-Invalid:
-
-```bash
-prowl focus --pane <id> --tab <id>        # multiple selectors
-prowl focus --pane <id> <positional>      # flag + positional (flag wins, positional ignored)
-prowl send "echo hi" < /tmp/input.txt     # two input sources
-prowl key --repeat 0 enter                 # repeat out of range
-prowl list --pane <id>                     # list does not accept selector
-```
+## Command-specific exceptions
 
----
+- `agents read <pN|pane-uuid>` is a pane-only semantic snapshot, no selectors or
+  focus fallback.
+- `handoff` defaults to the calling pane, not UI focus.
+- `list` and `agents` are global discovery commands with no target selector.
+- `open` consumes a path rather than a target.
 
-## 9) Non-goals (v1)
+## Transport request model
 
-- No complex selector query language (`--where ...`).
-- No streaming mode for `read`.
-- No macro system for `key`.
-- No dual parser implementations in v1.
+The CLI sends one typed `CommandEnvelope` over the local socket. Command spelling is
+owned by `ProwlCLI` ArgumentParser declarations; target state resolution remains
+app-side. Parser and handler both enforce destructive lifecycle constraints so a
+malformed direct socket request cannot gain a focus fallback.
diff --git a/docs-ai/013-prowl-cli/contracts/key.md b/docs-ai/013-prowl-cli/contracts/key.md
index 47021afb..0c575598 100644
--- a/docs-ai/013-prowl-cli/contracts/key.md
+++ b/docs-ai/013-prowl-cli/contracts/key.md
@@ -45,10 +45,9 @@ Compared with the initial draft, this version makes `key` broader and more scrip
 
 ## Supported targeting
 
-- `--worktree <id|name|path>`
-- `--tab <id>`
-- `--pane <id>`
-- no selector, meaning current focused pane
+`key` uses [targeting.md](targeting.md). Its two-positional form accepts a generic
+target first, so `key p12 enter` targets that pane; a single token still acts on the
+current pane for interactive use.
 
 ## Input contract (v1)
 
diff --git a/docs-ai/013-prowl-cli/contracts/list.md b/docs-ai/013-prowl-cli/contracts/list.md
index 2e53ee9b..6d1c9cf9 100644
--- a/docs-ai/013-prowl-cli/contracts/list.md
+++ b/docs-ai/013-prowl-cli/contracts/list.md
@@ -99,20 +99,23 @@ Every item in `data.items` represents exactly one actionable pane.
 - `name`: string
 - `path`: string, absolute path to the worktree or plain folder shown in the UI
 - `root_path`: string, absolute repository root or plain-folder root
-- `kind`: `"git"` | `"plain"`
+- `kind`: `"git"` | `"plain"` | `"workspace"`
 
 ### `tab`
 
 - `id`: string, UUID text form
+- `handle`: optional current-process integer handle
 - `title`: string
 - `selected`: boolean
 
 ### `pane`
 
 - `id`: string, UUID text form
+- `handle`: optional current-process integer handle
 - `title`: string
 - `cwd`: string or `null`
 - `focused`: boolean
+- `agent`: optional detected-agent machine token when available
 
 ### `task`
 
diff --git a/docs-ai/013-prowl-cli/contracts/pane.md b/docs-ai/013-prowl-cli/contracts/pane.md
new file mode 100644
index 00000000..5a5457c1
--- /dev/null
+++ b/docs-ai/013-prowl-cli/contracts/pane.md
@@ -0,0 +1,16 @@
+# Deprecated `prowl pane` Contract
+
+`prowl pane close` is a deprecated compatibility alias for `prowl close <pane>`.
+It is retained for one shipped release only.
+
+- Help labels the group and leaf command `[Deprecated]`.
+- Every invocation writes a migration warning to stderr without contaminating JSON
+  stdout.
+- During the window it preserves its legacy parser, selector projection, wire command
+  (`pane`), response schema (`prowl.cli.pane.v1`), and output payload.
+- New docs and automation must use `prowl close pN`, `prowl close --pane <uuid>`,
+  or the equivalent tab form.
+
+The legacy success payload remains `{ "action": "close", "target": … }`; the
+complete schema is `#/$defs/paneResponse` in
+[`schema-bundle.json`](../../../ProwlCLIContracts/Resources/cli-output-schema.json).
diff --git a/docs-ai/013-prowl-cli/contracts/read.md b/docs-ai/013-prowl-cli/contracts/read.md
index 854feae9..7975d389 100644
--- a/docs-ai/013-prowl-cli/contracts/read.md
+++ b/docs-ai/013-prowl-cli/contracts/read.md
@@ -17,10 +17,9 @@ This file defines the **JSON output contract** for:
 
 ## Supported targeting
 
-- `--worktree <id|name|path>`
-- `--tab <id>`
-- `--pane <id>`
-- no selector, meaning current focused pane
+`read` uses the shared generic target grammar in [targeting.md](targeting.md), so
+`read p12` and `read --target t6` resolve the displayed current-process handles.
+No selector retains the interactive current-focus fallback.
 
 ## Success payload
 
@@ -95,10 +94,10 @@ This file defines the **JSON output contract** for:
 - `mode`: `"snapshot"` | `"last"`
   - `"snapshot"` for plain `prowl read`
   - `"last"` for `prowl read --last N`
-- `last`: integer or `null`
-  - required as an integer when `mode == "last"`
-  - must be `null` when `mode == "snapshot"`
-- `source`: `"screen"` | `"scrollback"` | `"mixed"`
+- `last`: optional integer
+  - present as an integer when `mode == "last"`
+  - omitted for a snapshot
+- `source`: `"screen"` | `"scrollback"` | `"mixed"` | `"detection"`
   - `"screen"`: visible screen snapshot only
   - `"scrollback"`: satisfied from scrollback/history
   - `"mixed"`: combined view when the runtime had to stitch sources together
@@ -118,6 +117,15 @@ This file defines the **JSON output contract** for:
   - UTF-8 text payload
   - may be empty if the target pane currently has no readable text
 
+## Stable wait and detection extensions
+
+- `--source detection` returns the exact active-screen buffer used by agent
+  detection; an incompatible older app fails rather than substituting viewport text.
+- `--wait-stable` samples until output stabilizes or the timeout is reached.
+  `stabilized`, `waited_ms`, and `samples` are present only when waiting was
+  requested.
+- `--stable-interval`, `--stable-period`, and `--wait-timeout` tune that wait.
+
 ## Output invariants
 
 - `text` is always present on success, even when empty.
diff --git a/docs-ai/013-prowl-cli/contracts/schema.md b/docs-ai/013-prowl-cli/contracts/schema.md
index d60a6c83..3296016a 100644
--- a/docs-ai/013-prowl-cli/contracts/schema.md
+++ b/docs-ai/013-prowl-cli/contracts/schema.md
@@ -1,849 +1,41 @@
-# Prowl CLI JSON Schema Definitions (v1)
-
-> Living normative contract of entry 013. Migrated from `doc-onevcat/contracts/cli/schema.md` on 2026-07-12; update in place.
-
-Status: draft truth source for #96.
-
-This file provides machine-validatable JSON Schema definitions for the v1 CLI output contracts described in:
-
-- `open.md`
-- `list.md`
-- `focus.md`
-- `send.md`
-- `key.md`
-- `read.md`
-- `agents-read.md`
-
-## Scope
-
-- JSON Schema dialect: **Draft 2020-12**
-- Commands covered: `open`, `list`, `focus`, `send`, `key`, `read`, `agents.read`
-- Each command schema is represented as `oneOf(success, error)`
-- Shared objects are centralized in `$defs` and reused by command schemas
-
-## Schema bundle
-
-```json
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://prowl.onev.cat/contracts/cli/v1/schema-bundle.json",
-  "title": "Prowl CLI Output Contract Schemas (v1)",
-  "description": "Bundle of output JSON schemas for prowl open/list/focus/send/key/read v1",
-  "type": "object",
-  "additionalProperties": false,
-  "$defs": {
-    "uuid": {
-      "type": "string",
-      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
-    },
-    "absolutePath": {
-      "type": "string",
-      "minLength": 1,
-      "pattern": "^/.*"
-    },
-    "worktreeKind": {
-      "type": "string",
-      "enum": ["git", "plain"]
-    },
-    "worktree": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["id", "name", "path", "root_path", "kind"],
-      "properties": {
-        "id": { "type": "string", "minLength": 1 },
-        "name": { "type": "string", "minLength": 1 },
-        "path": { "$ref": "#/$defs/absolutePath" },
-        "root_path": { "$ref": "#/$defs/absolutePath" },
-        "kind": { "$ref": "#/$defs/worktreeKind" }
-      }
-    },
-    "tabBasic": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["id", "title"],
-      "properties": {
-        "id": { "$ref": "#/$defs/uuid" },
-        "title": { "type": "string" }
-      }
-    },
-    "tabWithCwd": {
-      "allOf": [
-        { "$ref": "#/$defs/tabBasic" },
-        {
-          "type": "object",
-          "additionalProperties": false,
-          "required": ["cwd"],
-          "properties": {
-            "cwd": {
-              "type": ["string", "null"],
-              "pattern": "^/.*"
-            }
-          }
-        }
-      ]
-    },
-    "paneBasic": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["id", "title", "cwd"],
-      "properties": {
-        "id": { "$ref": "#/$defs/uuid" },
-        "title": { "type": "string" },
-        "cwd": {
-          "type": ["string", "null"],
-          "pattern": "^/.*"
-        }
-      }
-    },
-    "tabSelected": {
-      "allOf": [
-        { "$ref": "#/$defs/tabBasic" },
-        {
-          "type": "object",
-          "additionalProperties": false,
-          "required": ["selected"],
-          "properties": {
-            "selected": { "type": "boolean" }
-          }
-        }
-      ]
-    },
-    "paneFocused": {
-      "allOf": [
-        { "$ref": "#/$defs/paneBasic" },
-        {
-          "type": "object",
-          "additionalProperties": false,
-          "required": ["focused"],
-          "properties": {
-            "focused": { "type": "boolean" }
-          }
-        }
-      ]
-    },
-    "openTarget": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["worktree", "tab", "pane"],
-      "properties": {
-        "worktree": { "$ref": "#/$defs/worktree" },
-        "tab": { "$ref": "#/$defs/tabWithCwd" },
-        "pane": { "$ref": "#/$defs/paneBasic" }
-      }
-    },
-    "resolvedTarget": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["worktree", "tab", "pane"],
-      "properties": {
-        "worktree": { "$ref": "#/$defs/worktree" },
-        "tab": { "$ref": "#/$defs/tabSelected" },
-        "pane": { "$ref": "#/$defs/paneFocused" }
-      }
-    },
-    "errorDetails": {
-      "type": "object",
-      "additionalProperties": true
-    },
-
-    "openSuccess": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["ok", "command", "schema_version", "data"],
-      "properties": {
-        "ok": { "const": true },
-        "command": { "const": "open" },
-        "schema_version": { "const": "prowl.cli.open.v1" },
-        "data": {
-          "type": "object",
-          "additionalProperties": false,
-          "required": [
-            "invocation",
-            "requested_path",
-            "resolved_path",
-            "resolution",
-            "app_launched",
-            "brought_to_front",
-            "created_tab",
-            "target"
-          ],
-          "properties": {
-            "invocation": {
-              "type": "string",
-              "enum": ["bare", "implicit-open", "open-subcommand"]
-            },
-            "requested_path": {
-              "anyOf": [
-                { "$ref": "#/$defs/absolutePath" },
-                { "type": "null" }
-              ]
-            },
-            "resolved_path": {
-              "anyOf": [
-                { "$ref": "#/$defs/absolutePath" },
-                { "type": "null" }
-              ]
-            },
-            "resolution": {
-              "type": "string",
-              "enum": ["no-argument", "exact-root", "inside-root", "new-root"]
-            },
-            "app_launched": { "type": "boolean" },
-            "brought_to_front": { "type": "boolean" },
-            "created_tab": { "type": "boolean" },
-            "target": { "$ref": "#/$defs/openTarget" }
-          },
-          "allOf": [
-            {
-              "if": {
-                "properties": { "requested_path": { "type": "null" } },
-                "required": ["requested_path"]
-              },
-              "then": {
-                "properties": {
-                  "resolved_path": { "type": "null" },
-                  "resolution": { "const": "no-argument" }
-                }
-              }
-            },
-            {
-              "if": {
-                "properties": {
-                  "invocation": { "const": "bare" }
-                },
-                "required": ["invocation"]
-              },
-              "then": {
-                "properties": {
-                  "requested_path": { "type": "null" }
-                }
-              }
-            }
-          ]
-        }
-      }
-    },
-    "openError": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["ok", "command", "schema_version", "error"],
-      "properties": {
-        "ok": { "const": false },
-        "command": { "const": "open" },
-        "schema_version": { "const": "prowl.cli.open.v1" },
-        "error": {
-          "type": "object",
-          "additionalProperties": false,
-          "required": ["code", "message"],
-          "properties": {
-            "code": {
-              "type": "string",
-              "enum": [
-                "INVALID_ARGUMENT",
-                "PATH_NOT_FOUND",
-                "PATH_NOT_DIRECTORY",
-                "PATH_NOT_ALLOWED",
-                "LAUNCH_FAILED",
-                "OPEN_FAILED"
-              ]
-            },
-            "message": { "type": "string", "minLength": 1 },
-            "details": { "$ref": "#/$defs/errorDetails" }
-          }
-        }
-      }
-    },
-    "openResponse": {
-      "oneOf": [
-        { "$ref": "#/$defs/openSuccess" },
-        { "$ref": "#/$defs/openError" }
-      ]
-    },
-
-    "listSuccess": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["ok", "command", "schema_version", "data"],
-      "properties": {
-        "ok": { "const": true },
-        "command": { "const": "list" },
-        "schema_version": { "const": "prowl.cli.list.v1" },
-        "data": {
-          "type": "object",
-          "additionalProperties": false,
-          "required": ["count", "items"],
-          "properties": {
-            "count": { "type": "integer", "minimum": 0 },
-            "items": {
-              "type": "array",
-              "items": {
-                "type": "object",
-                "additionalProperties": false,
-                "required": ["worktree", "tab", "pane", "task"],
-                "properties": {
-                  "worktree": { "$ref": "#/$defs/worktree" },
-                  "tab": { "$ref": "#/$defs/tabSelected" },
-                  "pane": { "$ref": "#/$defs/paneFocused" },
-                  "task": {
-                    "type": "object",
-                    "additionalProperties": false,
-                    "required": ["status"],
-                    "properties": {
-                      "status": {
-                        "type": ["string", "null"],
-                        "enum": ["idle", "running", null]
-                      }
-                    }
-                  }
-                }
-              }
-            }
-          }
-        }
-      }
-    },
-    "listError": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["ok", "command", "schema_version", "error"],
-      "properties": {
-        "ok": { "const": false },
-        "command": { "const": "list" },
-        "schema_version": { "const": "prowl.cli.list.v1" },
-        "error": {
-          "type": "object",
-          "additionalProperties": false,
-          "required": ["code", "message"],
-          "properties": {
-            "code": {
-              "type": "string",
-              "enum": ["APP_NOT_RUNNING", "LIST_FAILED"]
-            },
-            "message": { "type": "string", "minLength": 1 },
-            "details": { "$ref": "#/$defs/errorDetails" }
-          }
-        }
-      }
-    },
-    "listResponse": {
-      "oneOf": [
-        { "$ref": "#/$defs/listSuccess" },
-        { "$ref": "#/$defs/listError" }
-      ]
-    },
-
-    "focusSuccess": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["ok", "command", "schema_version", "data"],
-      "properties": {
-        "ok": { "const": true },
-        "command": { "const": "focus" },
-        "schema_version": { "const": "prowl.cli.focus.v1" },
-        "data": {
-          "type": "object",
-          "additionalProperties": false,
-          "required": ["requested", "resolved_via", "brought_to_front", "target"],
-          "properties": {
-            "requested": {
-              "type": "object",
-              "additionalProperties": false,
-              "required": ["selector", "value"],
-              "properties": {
-                "selector": {
-                  "type": "string",
-                  "enum": ["worktree", "tab", "pane", "auto", "current"]
-                },
-                "value": {
-                  "type": ["string", "null"]
-                }
-              },
-              "allOf": [
-                {
-                  "if": {
-                    "properties": { "selector": { "const": "current" } },
-                    "required": ["selector"]
-                  },
-                  "then": {
-                    "properties": {
-                      "value": { "type": "null" }
-                    }
-                  }
-                }
-              ]
-            },
-            "resolved_via": {
-              "type": "string",
-              "enum": ["worktree", "tab", "pane"]
-            },
-            "brought_to_front": { "type": "boolean" },
-            "target": { "$ref": "#/$defs/resolvedTarget" }
-          }
-        }
-      }
-    },
-    "focusError": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["ok", "command", "schema_version", "error"],
-      "properties": {
-        "ok": { "const": false },
-        "command": { "const": "focus" },
-        "schema_version": { "const": "prowl.cli.focus.v1" },
-        "error": {
-          "type": "object",
-          "additionalProperties": false,
-          "required": ["code", "message"],
-          "properties": {
-            "code": {
-              "type": "string",
-              "enum": [
-                "APP_NOT_RUNNING",
-                "INVALID_ARGUMENT",
-                "TARGET_NOT_FOUND",
-                "TARGET_NOT_UNIQUE",
-                "FOCUS_FAILED"
-              ]
-            },
-            "message": { "type": "string", "minLength": 1 },
-            "details": { "$ref": "#/$defs/errorDetails" }
-          }
-        }
-      }
-    },
-    "focusResponse": {
-      "oneOf": [
-        { "$ref": "#/$defs/focusSuccess" },
-        { "$ref": "#/$defs/focusError" }
-      ]
-    },
-
-    "sendSuccess": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["ok", "command", "schema_version", "data"],
-      "properties": {
-        "ok": { "const": true },
-        "command": { "const": "send" },
-        "schema_version": { "const": "prowl.cli.send.v1" },
-        "data": {
-          "type": "object",
-          "additionalProperties": false,
-          "required": ["target", "input", "created_tab", "wait"],
-          "properties": {
-            "target": { "$ref": "#/$defs/resolvedTarget" },
-            "input": {
-              "type": "object",
-              "additionalProperties": false,
-              "required": ["source", "characters", "bytes", "trailing_enter_sent"],
-              "properties": {
-                "source": {
-                  "type": "string",
-                  "enum": ["argv", "stdin"]
-                },
-                "characters": {
-                  "type": "integer",
-                  "minimum": 1
-                },
-                "bytes": {
-                  "type": "integer",
-                  "minimum": 1
-                },
-                "trailing_enter_sent": { "type": "boolean" }
-              }
-            },
-            "created_tab": { "type": "boolean" },
-            "wait": {
-              "oneOf": [
-                { "type": "null" },
-                {
-                  "type": "object",
-                  "additionalProperties": false,
-                  "required": ["exit_code", "duration_ms"],
-                  "properties": {
-                    "exit_code": {
-                      "type": ["integer", "null"]
-                    },
-                    "duration_ms": {
-                      "type": "integer",
-                      "minimum": 0
-                    }
-                  }
-                }
-              ]
-            }
-          }
-        }
-      }
-    },
-    "sendError": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["ok", "command", "schema_version", "error"],
-      "properties": {
-        "ok": { "const": false },
-        "command": { "const": "send" },
-        "schema_version": { "const": "prowl.cli.send.v1" },
-        "error": {
-          "type": "object",
-          "additionalProperties": false,
-          "required": ["code", "message"],
-          "properties": {
-            "code": {
-              "type": "string",
-              "enum": [
-                "APP_NOT_RUNNING",
-                "INVALID_ARGUMENT",
-                "TARGET_NOT_FOUND",
-                "TARGET_NOT_UNIQUE",
-                "EMPTY_INPUT",
-                "SEND_FAILED",
-                "WAIT_TIMEOUT"
-              ]
-            },
-            "message": { "type": "string", "minLength": 1 },
-            "details": { "$ref": "#/$defs/errorDetails" }
-          }
-        }
-      }
-    },
-    "sendResponse": {
-      "oneOf": [
-        { "$ref": "#/$defs/sendSuccess" },
-        { "$ref": "#/$defs/sendError" }
-      ]
-    },
-
-    "keySuccess": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["ok", "command", "schema_version", "data"],
-      "properties": {
-        "ok": { "const": true },
-        "command": { "const": "key" },
-        "schema_version": { "const": "prowl.cli.key.v1" },
-        "data": {
-          "type": "object",
-          "additionalProperties": false,
-          "required": ["requested", "key", "delivery", "target"],
-          "properties": {
-            "requested": {
-              "type": "object",
-              "additionalProperties": false,
-              "required": ["token", "repeat"],
-              "properties": {
-                "token": { "type": "string", "minLength": 1 },
-                "repeat": { "type": "integer", "minimum": 1, "maximum": 100 }
-              }
-            },
-            "key": {
-              "type": "object",
-              "additionalProperties": false,
-              "required": ["normalized", "category"],
-              "properties": {
-                "normalized": {
-                  "type": "string",
-                  "enum": [
-                    "enter",
-                    "esc",
-                    "tab",
-                    "backspace",
-                    "up",
-                    "down",
-                    "left",
-                    "right",
-                    "pageup",
-                    "pagedown",
-                    "home",
-                    "end",
-                    "ctrl-c",
-                    "ctrl-d",
-                    "ctrl-l"
-                  ]
-                },
-                "category": {
-                  "type": "string",
-                  "enum": ["navigation", "editing", "control"]
-                }
-              }
-            },
-            "delivery": {
-              "type": "object",
-              "additionalProperties": false,
-              "required": ["attempted", "delivered", "mode"],
-              "properties": {
-                "attempted": { "type": "integer", "minimum": 1, "maximum": 100 },
-                "delivered": { "type": "integer", "minimum": 1, "maximum": 100 },
-                "mode": { "const": "keyDownUp" }
-              }
-            },
-            "target": { "$ref": "#/$defs/resolvedTarget" }
-          }
-        }
-      }
-    },
-    "keyError": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["ok", "command", "schema_version", "error"],
-      "properties": {
-        "ok": { "const": false },
-        "command": { "const": "key" },
-        "schema_version": { "const": "prowl.cli.key.v1" },
-        "error": {
-          "type": "object",
-          "additionalProperties": false,
-          "required": ["code", "message"],
-          "properties": {
-            "code": {
-              "type": "string",
-              "enum": [
-                "APP_NOT_RUNNING",
-                "INVALID_ARGUMENT",
-                "INVALID_REPEAT",
-                "TARGET_NOT_FOUND",
-                "TARGET_NOT_UNIQUE",
-                "NO_ACTIVE_PANE",
-                "UNSUPPORTED_KEY",
-                "KEY_DELIVERY_FAILED"
-              ]
-            },
-            "message": { "type": "string", "minLength": 1 },
-            "details": { "$ref": "#/$defs/errorDetails" }
-          }
-        }
-      }
-    },
-    "keyResponse": {
-      "oneOf": [
-        { "$ref": "#/$defs/keySuccess" },
-        { "$ref": "#/$defs/keyError" }
-      ]
-    },
-
-    "readSuccess": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["ok", "command", "schema_version", "data"],
-      "properties": {
-        "ok": { "const": true },
-        "command": { "const": "read" },
-        "schema_version": { "const": "prowl.cli.read.v1" },
-        "data": {
-          "type": "object",
-          "additionalProperties": false,
-          "required": [
-            "target",
-            "mode",
-            "last",
-            "source",
-            "truncated",
-            "line_count",
-            "text"
-          ],
-          "properties": {
-            "target": { "$ref": "#/$defs/resolvedTarget" },
-            "mode": {
-              "type": "string",
-              "enum": ["snapshot", "last"]
-            },
-            "last": {
-              "type": ["integer", "null"],
-              "minimum": 1
-            },
-            "source": {
-              "type": "string",
-              "enum": ["screen", "scrollback", "mixed"]
-            },
-            "truncated": { "type": "boolean" },
-            "line_count": { "type": "integer", "minimum": 0 },
-            "text": { "type": "string" }
-          },
-          "allOf": [
-            {
-              "if": {
-                "properties": { "mode": { "const": "snapshot" } },
-                "required": ["mode"]
-              },
-              "then": {
-                "properties": {
-                  "last": { "type": "null" }
-                }
-              }
-            },
-            {
-              "if": {
-                "properties": { "mode": { "const": "last" } },
-                "required": ["mode"]
-              },
-              "then": {
-                "properties": {
-                  "last": { "type": "integer", "minimum": 1 }
-                }
-              }
-            }
-          ]
-        }
-      }
-    },
-    "readError": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["ok", "command", "schema_version", "error"],
-      "properties": {
-        "ok": { "const": false },
-        "command": { "const": "read" },
-        "schema_version": { "const": "prowl.cli.read.v1" },
-        "error": {
-          "type": "object",
-          "additionalProperties": false,
-          "required": ["code", "message"],
-          "properties": {
-            "code": {
-              "type": "string",
-              "enum": [
-                "APP_NOT_RUNNING",
-                "INVALID_ARGUMENT",
-                "TARGET_NOT_FOUND",
-                "TARGET_NOT_UNIQUE",
-                "READ_FAILED"
-              ]
-            },
-            "message": { "type": "string", "minLength": 1 },
-            "details": { "$ref": "#/$defs/errorDetails" }
-          }
-        }
-      }
-    },
-    "readResponse": {
-      "oneOf": [
-        { "$ref": "#/$defs/readSuccess" },
-        { "$ref": "#/$defs/readError" }
-      ]
-    },
-
-    "agentsReadSuccess": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["ok", "command", "schema_version", "data"],
-      "properties": {
-        "ok": { "const": true },
-        "command": { "const": "agents.read" },
-        "schema_version": { "const": "prowl.cli.agents.read.v1" },
-        "data": {
-          "type": "object",
-          "additionalProperties": false,
-          "required": ["output_mode", "target", "agent", "result"],
-          "properties": {
-            "output_mode": { "const": "snapshot" },
-            "target": { "$ref": "#/$defs/resolvedTarget" },
-            "agent": {
-              "type": "object",
-              "additionalProperties": false,
-              "required": ["type", "status", "raw_state", "last_changed_at"],
-              "properties": {
-                "type": { "type": "string", "enum": ["claude", "codex"] },
-                "status": { "type": "string", "enum": ["blocked", "working", "done", "idle"] },
-                "raw_state": { "type": "string", "enum": ["blocked", "working", "idle", "unknown"] },
-                "detection_reason": { "type": "string" },
-                "last_changed_at": { "type": "string", "format": "date-time" },
-                "session": {
-                  "type": "object",
-                  "additionalProperties": false,
-                  "required": ["id", "confidence", "source"],
-                  "properties": {
-                    "id": { "type": "string", "minLength": 1 },
-                    "confidence": { "type": "string", "enum": ["exact", "high"] },
-                    "source": { "type": "string", "enum": ["open_file", "transcript_match", "recent_file"] }
-                  }
-                }
-              }
-            },
-            "blocker": {
-              "type": "object",
-              "additionalProperties": false,
-              "required": ["text"],
-              "properties": {
-                "text": { "type": "string", "minLength": 1 }
-              }
-            },
-            "result": {
-              "type": "object",
-              "additionalProperties": false,
-              "required": ["state"],
-              "properties": {
-                "state": {
-                  "type": "string",
-                  "enum": ["complete", "pending", "unavailable", "missing", "incomplete", "too_large"]
-                },
-                "text": { "type": "string" },
-                "error": {
-                  "type": "object",
-                  "additionalProperties": false,
-                  "required": ["code", "message"],
-                  "properties": {
-                    "code": {
-                      "type": "string",
-                      "enum": ["SESSION_UNRESOLVED", "RESULT_NOT_FOUND", "RESULT_INCOMPLETE", "RESULT_TOO_LARGE"]
-                    },
-                    "message": { "type": "string", "minLength": 1 }
-                  }
-                }
-              }
-            }
-          }
-        }
-      }
-    },
-    "agentsReadError": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["ok", "command", "schema_version", "error"],
-      "properties": {
-        "ok": { "const": false },
-        "command": { "const": "agents.read" },
-        "schema_version": { "const": "prowl.cli.agents.read.v1" },
-        "error": {
-          "type": "object",
-          "additionalProperties": false,
-          "required": ["code", "message"],
-          "properties": {
-            "code": {
-              "type": "string",
-              "enum": [
-                "APP_NOT_RUNNING", "INVALID_ARGUMENT", "TARGET_NOT_FOUND", "AGENT_NOT_FOUND",
-                "AGENT_UNSUPPORTED", "AGENT_READ_FAILED", "BLOCKER_UNREADABLE", "SESSION_UNRESOLVED",
-                "RESULT_NOT_FOUND", "RESULT_INCOMPLETE", "RESULT_TOO_LARGE"
-              ]
-            },
-            "message": { "type": "string", "minLength": 1 },
-            "details": { "$ref": "#/$defs/errorDetails" }
-          }
-        }
-      }
-    },
-    "agentsReadResponse": {
-      "oneOf": [
-        { "$ref": "#/$defs/agentsReadSuccess" },
-        { "$ref": "#/$defs/agentsReadError" }
-      ]
-    }
-  }
-}
-```
-
-## Usage notes
-
-- Validate `prowl open --json` output against `#/$defs/openResponse`
-- Validate `prowl list --json` output against `#/$defs/listResponse`
-- Validate `prowl focus --json` output against `#/$defs/focusResponse`
-- Validate `prowl send --json` output against `#/$defs/sendResponse`
-- Validate `prowl key --json` output against `#/$defs/keyResponse`
-- Validate `prowl read --json` output against `#/$defs/readResponse`
-- Validate `prowl agents read <pane> --json` output against `#/$defs/agentsReadResponse`
-
-## Non-goals (v1)
-
-- This file does **not** define CLI input argument parsing schemas.
-- This file does **not** guarantee order-sensitive invariants that require runtime state checks across array items (for example, uniqueness of focused pane across all rows in `list`).
-- This file does **not** attempt to encode transport-level details (stdout/stderr split, process exit code) beyond payload shape.
+# Prowl CLI JSON Schema Bundle
+
+The normative machine-readable Draft 2020-12 bundle is
+[`cli-output-schema.json`](../../../ProwlCLIContracts/Resources/cli-output-schema.json).
+This document intentionally contains no copied JSON: a Markdown code block cannot
+be executed and was the source of the previous schema drift.
+
+## Coverage
+
+The bundle has one versioned success-or-error response schema for every wire command:
+
+| Command | Schema definition |
+| --- | --- |
+| `open` | `#/$defs/openResponse` |
+| `list` | `#/$defs/listResponse` |
+| `agents` | `#/$defs/agentsResponse` |
+| `agents.read` | `#/$defs/agentsReadResponse` |
+| `focus` | `#/$defs/focusResponse` |
+| `send` | `#/$defs/sendResponse` |
+| `key` | `#/$defs/keyResponse` |
+| `read` | `#/$defs/readResponse` |
+| `create` | `#/$defs/createResponse` |
+| `close` | `#/$defs/closeResponse` |
+| deprecated `tab` | `#/$defs/tabResponse` |
+| deprecated `pane` | `#/$defs/paneResponse` |
+| `handoff` | `#/$defs/handoffResponse` |
+
+The bundle root is a `oneOf` across these responses and is valid for any complete
+socket response.
+
+## Executable verification
+
+`ProwlCLITests/ProwlCLIIntegrationTests.swift` loads the bundle through the
+`ProwlCLIContracts` SwiftPM target and validates every mock socket response that
+contains a command payload or error with the Draft 2020-12 `JSONSchema` validator.
+Those are raw socket bytes, not decoded model assertions. `make test-cli-integration`
+is therefore the contract verification command.
+
+A public wire command is incomplete until its versioned response definition,
+socket fixture, parser/handler test, user manual, and command contract change in the
+same review.
diff --git a/docs-ai/013-prowl-cli/contracts/send.md b/docs-ai/013-prowl-cli/contracts/send.md
index 8fb4afc3..1017b8f4 100644
--- a/docs-ai/013-prowl-cli/contracts/send.md
+++ b/docs-ai/013-prowl-cli/contracts/send.md
@@ -16,16 +16,19 @@ This file defines the **JSON output contract** for:
 
 ## Supported targeting
 
-- `--worktree <id|name|path>`
-- `--tab <id>`
-- `--pane <id>`
-- no selector, meaning current focused pane
+`send` uses the shared generic target grammar in [targeting.md](targeting.md),
+including `pN` / `tN` in `--target` and target-first positional forms. With one
+positional argument, `send p12` remains text for the focused pane; target-first
+send requires `send p12 'text'`.
 
 ## Supported input forms
 
 - positional text argument
 - stdin text
-- `--no-enter`
+- `--no-enter`, `--no-wait`, `--capture`, and `--timeout <1...300>`
+
+`--capture` is shipped behavior. It requires shell integration, sends Enter, and
+cannot combine with `--no-wait` or `--no-enter`.
 
 ## Wait behavior
 
@@ -42,11 +45,11 @@ By default, `send` waits for the delivered command to finish before returning. T
 - `"argv"`
   - means the payload came from the positional text argument of `prowl send`
   - typical trigger: `prowl send "echo hello"`
-  - planned use: short, explicit, human-authored inline sends
+  - use for short, explicit, human-authored inline sends
 - `"stdin"`
   - means the payload came from process stdin, usually via a pipe or redirection
   - typical trigger: `printf 'echo hello\n' | prowl send`
-  - planned use: multiline text, generated text, file/pipe input, or payloads you do not want to expose inline in shell history
+  - use for multiline text, generated text, file/pipe input, or payloads you do not want to expose inline in shell history
 
 ## Success payload
 
@@ -176,6 +179,7 @@ By default, `send` waits for the delivered command to finish before returning. T
 - `EMPTY_INPUT`
 - `SEND_FAILED`
 - `WAIT_TIMEOUT`
+- `CAPTURE_UNSUPPORTED`
 
 ## Notes
 
@@ -184,7 +188,9 @@ By default, `send` waits for the delivered command to finish before returning. T
 - A future implementation may add optional debug echo flags, but v1 default JSON must stay redaction-friendly.
 - Wait behavior depends on shell integration (OSC 133). Without it, `onCommandFinished` never fires and the wait will time out. The `WAIT_TIMEOUT` error message should hint at this possible cause.
 - `--no-wait` combined with `--no-enter` is the purest "paste text" mode — no Enter, no waiting.
-- A future `--capture` flag may return the command's output text alongside `wait`, pending upstream support for reading semantic zone data via the Ghostty C API.
+- `--capture` returns `capture` with `text`, `line_count`, `source: "screen_diff"`,
+  and `truncated`; it is omitted when capture was not requested. Capture requires
+  shell integration and fails with `CAPTURE_UNSUPPORTED` when unavailable.
 
 ## Example: stdin + `--no-enter`
 
diff --git a/docs-ai/013-prowl-cli/contracts/tab.md b/docs-ai/013-prowl-cli/contracts/tab.md
new file mode 100644
index 00000000..3ec23c06
--- /dev/null
+++ b/docs-ai/013-prowl-cli/contracts/tab.md
@@ -0,0 +1,15 @@
+# Deprecated `prowl tab` Contract
+
+`prowl tab create` and `prowl tab close` are deprecated compatibility aliases for
+`prowl create tab` and `prowl close <tab>`. They are retained for one shipped
+release only.
+
+- Help labels the group and leaf commands `[Deprecated]`.
+- Every invocation writes a migration warning to stderr. JSON stdout remains valid.
+- During the window, aliases retain their existing parser, selector projection, wire
+  command (`tab`), response schema (`prowl.cli.tab.v1`), and output payload exactly.
+- New docs and automation must not use them.
+
+`tab` success payloads retain `{ "action": "create"|"close", "target": … }`.
+The complete legacy response schema is `#/$defs/tabResponse` in
+[`schema-bundle.json`](../../../ProwlCLIContracts/Resources/cli-output-schema.json).
diff --git a/docs-ai/013-prowl-cli/contracts/targeting.md b/docs-ai/013-prowl-cli/contracts/targeting.md
new file mode 100644
index 00000000..0a932c19
--- /dev/null
+++ b/docs-ai/013-prowl-cli/contracts/targeting.md
@@ -0,0 +1,68 @@
+# Prowl CLI Targeting Contract
+
+> Normative target-language contract. Command contracts link here rather than redefining resolution rules.
+
+## References
+
+```text
+GenericTarget ::= PaneUUID | TabUUID | PaneHandle | TabHandle | WorktreeRef
+PaneHandle    ::= "p" PositiveInteger
+TabHandle     ::= "t" PositiveInteger
+WorktreeRef   ::= worktree id | name | path
+```
+
+- UUIDs are the canonical JSON and cross-process automation identity.
+- `pN` / `tN` are current-process interaction handles. They are globally monotonic,
+  never reused by a running Prowl process, and invalid after restart or target close.
+- Bare `N` is only a typed `--pane N` / `--tab N` handle. In generic positions it
+  remains a worktree reference.
+- Generic `pN` resolves only as a pane and generic `tN` resolves only as a tab. A
+  stale prefixed handle fails with `TARGET_NOT_FOUND`; it never falls back to a
+  worktree named `pN` or `tN`. Use `--worktree p12` for that worktree.
+
+## Generic resolution
+
+Generic target positions are `--target` and the target-first positional forms of
+`focus`, `read`, `send`, `key`, and `handoff`.
+
+1. `pN` resolves as a pane handle.
+2. `tN` resolves as a tab handle.
+3. A UUID resolves pane first, then tab.
+4. Any other spelling resolves as a worktree id, name, or path.
+
+Typed selectors remain mutually exclusive:
+
+```text
+--target <GenericTarget>
+--worktree <WorktreeRef>
+--tab <TabUUID|tN|N>
+--pane <PaneUUID|pN|N>
+```
+
+A positional target and any selector flag are mutually exclusive and fail with
+`INVALID_ARGUMENT`; flags never silently override a positional target.
+
+## No-target behavior
+
+- `focus`, `read`, `send`, `key`, and legacy `tab create` retain current UI-focus
+  fallback for interactive use.
+- `handoff` defaults to the pane that spawned the CLI process, never UI focus.
+- `agents read` always requires a pane argument.
+- New `create tab` and `close` always require an explicit target.
+
+Automation should use UUIDs or an explicit same-session `pN`/`tN` target; it must
+not rely on a focus fallback.
+
+## Typed lifecycle targeting
+
+Lifecycle commands intentionally do not use generic worktree projection:
+
+```text
+create tab <WorktreeRef> | --worktree <WorktreeRef>
+close <PaneUUID|TabUUID|pN|tN> | --pane <PaneUUID|pN|N> | --tab <TabUUID|tN|N>
+```
+
+`close` rejects `--target`, `--worktree`, bare-number positionals, UI-focus
+fallback, and mixed positional/flag targeting. `create pane` is reserved for
+[#699](https://github.com/onevcat/Prowl/issues/699): it will require a pane-only
+anchor and direction.
diff --git a/docs-ai/060-prowl-cli-targeting-and-contract-governance/000-plan.md b/docs-ai/060-prowl-cli-targeting-and-contract-governance/000-plan.md
index fab01e59..2d446cbb 100644
--- a/docs-ai/060-prowl-cli-targeting-and-contract-governance/000-plan.md
+++ b/docs-ai/060-prowl-cli-targeting-and-contract-governance/000-plan.md
@@ -2,7 +2,7 @@
 
 | | |
 | --- | --- |
-| **Status** | Aligned — implementation pending |
+| **Status** | Implemented |
 | **Anchor date** | 2026-08-16 |
 | **Primary PRs** | TBD |
 | **Related** | [013 — Prowl CLI](../013-prowl-cli/000-plan.md), [046 — CLI Short Handles](../046-cli-short-handles/000-plan.md), [047 — Cross-Agent Handoff](../047-cross-agent-handoff/000-plan.md), [059 — Agent Transcript Snapshots](../059-agent-transcript-snapshots/000-plan.md), [#699 — CLI split-pane creation](https://github.com/onevcat/Prowl/issues/699), [`docs/components/cli.md`](../../docs/components/cli.md) |
diff --git a/docs-ai/060-prowl-cli-targeting-and-contract-governance/001-action.md b/docs-ai/060-prowl-cli-targeting-and-contract-governance/001-action.md
new file mode 100644
index 00000000..fa2c4cb3
--- /dev/null
+++ b/docs-ai/060-prowl-cli-targeting-and-contract-governance/001-action.md
@@ -0,0 +1,58 @@
+# 060 — Prowl CLI Targeting and Contract Governance: Action
+
+## Delivered
+
+- Unified generic target references: `pN` and `tN` now work in `--target` and
+  every existing positional auto-target form. Bare numbers remain worktree
+  references outside typed `--pane` / `--tab` selectors, and stale prefixed
+  handles never fall back to worktrees.
+- Added action-first lifecycle commands:
+
+  ```bash
+  prowl create tab <worktree> [--path <directory>]
+  prowl close <pN|tN|uuid> [--force]
+  prowl close --pane <uuid|pN|N> [--force]
+  prowl close --tab <uuid|tN|N> [--force]
+  ```
+
+  `close` has no worktree or UI-focus fallback. Its resolver returns the typed
+  tab/pane resource, so `pN` and `tN` dispatch without cross-resource selector
+  projection.
+- Kept `tab create`, `tab close`, and `pane close` as one-release deprecated
+  aliases. Help marks them `[Deprecated]`; each invocation emits a stderr
+  migration warning while preserving the legacy wire command and JSON stdout.
+- Added versioned `create` and `close` wire inputs, handlers, payloads, output
+  rendering, error codes, schemas, parser tests, resolver tests, handler tests,
+  and socket integration coverage.
+- Rebased CLI documentation around `targeting.md`, action-first lifecycle
+  grammar, per-command contracts, and a durable pane-creation boundary in
+  [#699](https://github.com/onevcat/Prowl/issues/699).
+- Replaced the non-executable Markdown schema copy with the Draft 2020-12
+  `ProwlCLIContracts` bundle. `ProwlCLIIntegrationTests` validates every mock
+  socket response with payload/error bytes before the CLI receives it. The
+  bundle covers all 13 shipped wire commands, including deprecated aliases.
+
+## Deliberate Boundary
+
+`prowl create pane` remains unimplemented. [#699](https://github.com/onevcat/Prowl/issues/699)
+now owns the action-first `create pane <pane> --direction <right|left|up|down>`
+contract and requires a direct target-surface split primitive rather than a
+focus-dependent implementation.
+
+## Verification
+
+Executed successfully:
+
+```bash
+make format-changed
+make build-cli
+make test-cli-smoke
+make test-cli-integration
+make check
+make test
+make build-app
+```
+
+Focused coverage also exercised prefixed generic resolution, stale-handle
+non-fallback, lifecycle target routing, lifecycle handler behavior, parser
+rejection, deprecated help/warnings, and raw socket JSON-schema validation.
diff --git a/docs/components/cli.md b/docs/components/cli.md
index d3d8b3cd..049ef0c8 100644
--- a/docs/components/cli.md
+++ b/docs/components/cli.md
@@ -4,7 +4,7 @@
 > an agent) can list panes, read their screens, run commands and capture output,
 > send keystrokes, focus, and open/close tabs and panes programmatically.
 
-**Keywords:** prowl cli, command line, prowl list, prowl agents, prowl agents read, prowl read, prowl send, prowl key, prowl focus, prowl tab, prowl pane, prowl open, prowl handoff, pane id, agent, automation, json, capture, socket
+**Keywords:** prowl cli, command line, prowl list, prowl agents, prowl agents read, prowl read, prowl send, prowl key, prowl focus, prowl create, prowl close, prowl open, prowl handoff, pane id, agent, automation, json, capture, socket
 
 **Related:** [terminal](terminal.md) · [concepts](../concepts.md) · [active-agents](active-agents.md) · [agent-detection](agent-detection.md) · the bundled **`prowl-cli` skill** (`skills/prowl-cli/SKILL.md`)
 
@@ -48,8 +48,8 @@ Most commands accept one selector (mutually exclusive):
   short handle shown in text output; bare `N` is accepted too.
 - `--worktree <id|name|path>` — a worktree (its selected/first tab → focused/first
   pane).
-- `-t, --target <value>` — auto-resolve: tries pane UUID, then tab UUID, then
-  worktree id/name/path.
+- `-t, --target <value>` — auto-resolve: `pN` as a pane, `tN` as a tab, then
+  pane UUID, tab UUID, or worktree id/name/path.
 - **No selector** → the *current* focus (focused worktree → selected tab → focused
   pane). Some commands (close) refuse this for safety.
 
@@ -58,10 +58,11 @@ Most commands accept one selector (mutually exclusive):
 
 Text `list` and `agents` output exposes short, type-prefixed handles such as
 `p7` and `t6`. They are valid only for the current app process, are globally
-monotonic, and are never reused after a tab or pane closes. Use them with an
-explicit `--pane` or `--tab`; `--target` and positional targets deliberately do
-not resolve handles because a bare number can be a worktree name. JSON always
-keeps the canonical UUID in `id`; do not cache either form across an app restart.
+monotonic, and are never reused after a tab or pane closes. They work in every
+generic target position (`read p7`, `focus t6`, `send p7 '…'`); bare numbers remain
+worktree references there. A stale prefixed handle fails rather than falling back to
+a same-named worktree. JSON keeps canonical UUIDs in `id`; do not cache handles
+across an app restart.
 
 > **Never target by tab title.** Titles are free-form and can lie. For scripts,
 > resolve a concrete UUID `pane.id` from `prowl list --json`; for an interactive
@@ -93,8 +94,8 @@ with the corresponding explicit selector:
 
 ```bash
 prowl list
-prowl read --pane p7 --last 120 --wait-stable
-prowl tab close --tab t6 --force
+prowl read p7 --last 120 --wait-stable
+prowl close t6 --force
 ```
 
 `task.status` is **running** when any pane in the worktree is busy — a terminal
@@ -268,32 +269,33 @@ prowl focus --pane "$pane" --json
 prowl focus --worktree MyApp --json
 ```
 
-### `prowl tab create`
-Create a new terminal tab (deterministic — unlike `open`).
-
-- `--path <dir>` — working directory (must be inside the worktree root).
-- Selectors choose the worktree (defaults to current).
+### `prowl create tab`
+Create a new terminal tab (deterministic — unlike `open`). A worktree is required,
+either positionally or with `--worktree`; `--path` must remain inside it.
 
 ```bash
-pane="$(prowl tab create --worktree "$wt" --json | jq -r '.data.target.pane.id')"
+pane="$(prowl create tab "$wt" --json | jq -r '.data.target.pane.id')"
 ```
 
-### `prowl tab close` / `prowl pane close`
-Close a tab or a pane. **Require an explicit selector** (`--tab`/`--pane`/
-`--worktree`/`--target`) — they intentionally do **not** default to the focused
-pane. If the target has protected agent work or a long-running command, Prowl may
-ask for GUI confirmation; `--force` skips it (use only after positively
-identifying the target).
+### `prowl close`
+Close one explicit tab or pane. The positional form uses a UUID, `pN`, or `tN`; the
+long forms are `--pane <uuid|pN|N>` and `--tab <uuid|tN|N>`. `close` rejects
+worktree targeting and has no focus fallback. Protected agent work or a long-running
+command may trigger GUI confirmation; `--force` skips it only after positive
+identification.
 
 ```bash
-prowl pane close --pane "$pane" --json
-prowl tab close --tab "$tab" --force --json
+prowl close "$pane" --json
+prowl close --tab "$tab" --force --json
 ```
 
+> `prowl tab create`, `prowl tab close`, and `prowl pane close` are deprecated
+> compatibility aliases. They warn on stderr and will be removed after one release.
+
 ### `prowl open [path]` (the default command)
 Navigate Prowl to a path (or bring it to front with no argument). It may focus an
 existing pane or create a tab — it is **not** a deterministic "new pane" command.
-For a guaranteed fresh shell, use `tab create`.
+For a guaranteed fresh shell, use `create tab`.
 
 ```bash
 prowl open ~/projects/app     # open/focus that project
@@ -409,7 +411,7 @@ artifacts and terminal excerpts do not appear in `git status`.
 | `CAPTURE_UNSUPPORTED` | Target lacks OSC 133 — drop `--capture`, use `read --wait-stable`. |
 | `WAIT_TIMEOUT` | Command didn't finish in time — raise `--timeout` or use `--no-wait`. |
 | `UNSUPPORTED_KEY` / `INVALID_REPEAT` | Check `prowl key --help`. |
-| `PATH_NOT_FOUND` / `PATH_NOT_DIRECTORY` / `PATH_NOT_ALLOWED` | Fix the `open`/`tab create` path. |
+| `PATH_NOT_FOUND` / `PATH_NOT_DIRECTORY` / `PATH_NOT_ALLOWED` | Fix the `open`/`create tab` path. |
 | `LAUNCH_FAILED` | App launch or socket wait failed; the message includes the last socket diagnostic when available. |
 | `TRANSPORT_FAILED` | Socket transport failed for a reason other than app availability or permission, such as `ENOTSOCK` or an invalid `PROWL_CLI_SOCKET` path. |
 | `*_FAILED` (`LIST_FAILED`, `AGENTS_FAILED`, `FOCUS_FAILED`, `SEND_FAILED`, `READ_FAILED`, `TAB_FAILED`, `PANE_FAILED`, `OPEN_FAILED`, `HANDOFF_FAILED`) | The action itself failed. |
@@ -426,11 +428,11 @@ artifacts and terminal excerpts do not appear in `git status`.
 
 ```bash
 self_pane="$(prowl list --json | jq -r '.data.items[]|select(.pane.focused==true)|.pane.id')"
-pane="$(prowl tab create --worktree MyApp --json | jq -r '.data.target.pane.id')"
+pane="$(prowl create tab MyApp --json | jq -r '.data.target.pane.id')"
 test "$pane" != "$self_pane"
 prowl send --pane "$pane" 'swift build' --capture --timeout 300 --json
 prowl read --pane "$pane" --last 100 --wait-stable --json
-prowl pane close --pane "$pane" --json
+prowl close "$pane" --json
 ```
 
 ## Gotchas for agents (quick list)
@@ -442,6 +444,6 @@ prowl pane close --pane "$pane" --json
   when you need all panes, including ordinary shells.
 - `--capture` needs shell integration; otherwise `read --wait-stable` or file
   redirection.
-- `open` is navigation, not a guaranteed new pane — use `tab create`.
+- `open` is navigation, not a guaranteed new pane — use `create tab`.
 - In zsh, don't name a variable `status` (it's readonly).
 - Pass shell values into `jq` with `--arg`.
diff --git a/docs/components/terminal.md b/docs/components/terminal.md
index c32f00aa..159ae220 100644
--- a/docs/components/terminal.md
+++ b/docs/components/terminal.md
@@ -27,7 +27,7 @@ why Prowl is fully native and CJK-correct.
 
 | Operation | How |
 |-----------|-----|
-| New tab | Terminal menu → **New Terminal** (Ghostty `new_tab`, typically `⌘T`); the **+** on a Shelf spine; the [`prowl tab create`](cli.md) CLI |
+| New tab | Terminal menu → **New Terminal** (Ghostty `new_tab`, typically `⌘T`); the **+** on a Shelf spine; the [`prowl create tab`](cli.md) CLI |
 | Select tab 1–9 | `⌘1`–`⌘9` |
 | Previous / Next tab | `⌘⇧[` / `⌘⇧]` |
 | Close focused tab | Terminal menu → **Close Terminal Tab** (Ghostty `close_tab`) |
diff --git a/skills/prowl-cli/SKILL.md b/skills/prowl-cli/SKILL.md
index 4a2fc6b7..ef25ef53 100644
--- a/skills/prowl-cli/SKILL.md
+++ b/skills/prowl-cli/SKILL.md
@@ -10,7 +10,7 @@ Use `prowl` only when the task is to inspect or control the running Prowl GUI ap
 
 ## Safe Default Workflow
 
-For automation, always resolve a concrete pane UUID before `read`, `send`, `key`, `focus`, or destructive close commands. Text `list` and `agents` output also exposes current-process `pN` / `tN` handles for concise same-session handoffs; use them only with explicit `--pane` / `--tab` flags.
+For automation, always resolve a concrete pane UUID before `read`, `send`, `key`, `focus`, or destructive close commands. Text `list` and `agents` also expose current-process `pN` / `tN` handles for concise same-session targeting: `read p7`, `send p7 '…'`, `key p7 enter`, and `close t6` are valid. UUIDs remain the only cross-process identity.
 
 ```bash
 prowl list --json
@@ -61,13 +61,13 @@ worktree="$(prowl list --json | jq -r --arg project "$project" '
   | select((.worktree.path | rtrimstr("/")) == ($project | rtrimstr("/")))
   | .worktree.id
 ' | head -n 1)"
-pane="$(prowl tab create --worktree "$worktree" --json | jq -r '.data.target.pane.id')"
+pane="$(prowl create tab "$worktree" --json | jq -r '.data.target.pane.id')"
 test "$pane" != "$self_pane"
 ```
 
 Prefer a `worktree.id` or `worktree.name` returned by `prowl list` over a hand-typed path; list preserves normalization such as trailing slashes. Use `--path` only for the new tab's working directory inside the selected worktree.
 
-`prowl open /path` opens or focuses a matching project/path and may create a tab when needed. It is not guaranteed to create a new pane. Use `prowl tab create` for deterministic new terminal sessions.
+`prowl open /path` opens or focuses a matching project/path and may create a tab when needed. It is not guaranteed to create a new pane. Use `prowl create tab` for deterministic new terminal sessions.
 
 Run a command and capture its result:
 
@@ -99,14 +99,14 @@ printf '%s\n' 'echo first' 'echo second' | prowl send --pane "$pane" --capture -
 Close a temporary tab/pane when done:
 
 ```bash
-prowl pane close --pane "$pane" --json
-prowl tab close --tab "$tab" --json
+prowl close "$pane" --json
+prowl close --tab "$tab" --json
 ```
 
-`tab close` and `pane close` require an explicit `--tab`, `--pane`, `--worktree`, or `--target`; they intentionally do not default to the currently focused pane. For automation-created tabs, prefer the `tab.id` or `pane.id` returned by `tab create`. If the target has protected agent work or a long-running command, Prowl may ask for GUI confirmation. Use `--force` only after you have positively identified the target:
+`close` requires an explicit pane or tab target and intentionally has no focus or worktree fallback. For automation-created tabs, prefer the `tab.id` or `pane.id` returned by `create tab`. If the target has protected agent work or a long-running command, Prowl may ask for GUI confirmation. Use `--force` only after you have positively identified the target:
 
 ```bash
-prowl pane close --pane "$pane" --force --json
+prowl close "$pane" --force --json
 ```
 
 ## Parsing JSON Output
@@ -124,8 +124,8 @@ out="$(prowl send --pane "$pane" 'git status --short' --capture --timeout 30 --j
 printf '%s\n' "$out" | jq -r '.data.capture.text'
 printf '%s\n' "$out" | jq -r '.data.wait.exit_code'
 
-# tab create / open: new pane and tab ids
-created="$(prowl tab create --worktree "$worktree" --json)"
+# create tab / open: new pane and tab ids
+created="$(prowl create tab "$worktree" --json)"
 printf '%s\n' "$created" | jq -r '.data.target.pane.id'
 printf '%s\n' "$created" | jq -r '.data.target.tab.id'
 
@@ -144,7 +144,7 @@ Key fields by command (see `docs/components/cli.md` for the full contract):
 - `send` → `.data.input` (source/characters/bytes/trailing_enter_sent); `.data.wait.exit_code` and `.data.wait.duration_ms` when waiting; `.data.capture.text` / `.data.capture.line_count` / `.data.capture.truncated` when `--capture`.
 - `list` / `agents` → `.data.items[]` / `.data.agents[]`, each with `.pane.id`, `.tab.id`, and `.worktree.{id,name,path}`. Agent entries also include `.status`, `.raw_state`, and optional `.detection_reason`; list entries include `.task.status`.
 - `agents read` → `.data.agent` (current status/reason), `.data.blocker.text` when blocked, and `.data.result`. Only `.data.result.state == "complete"` carries `.data.result.text`; `pending`, `unavailable`, `missing`, `incomplete`, and `too_large` deliberately carry no partial text.
-- `tab create` / `open` → `.data.target.{pane,tab,worktree}`.
+- `create tab` / `open` → `.data.target.{pane,tab,worktree}`.
 
 ## Reading Agent Output
 
@@ -252,7 +252,7 @@ prowl agents read "$pane" --json
 
 When no agent is blocked, use the same pattern with `working`, `done`, or `idle` depending on the task. The JSON payload also includes `.project.name`, `.project.branch`, `.worktree.path`, `.tab.title`, and `.pane.focused`, so automation can filter by human project label while still targeting the concrete pane.
 
-`-t/--target` can auto-resolve pane UUID, tab UUID, or worktree id/name/path, but not short handles. Explicit `--pane <uuid>` is safer for automation; explicit `--pane <pN>` is useful for a same-session human or agent handoff.
+`-t/--target` and positional generic targets resolve `pN` as a pane, `tN` as a tab, then UUIDs and worktree references. A stale prefixed handle fails rather than falling back to a worktree of the same name. Explicit UUID `--pane` remains safest for automation.
 
 ## Argument Rules
 
@@ -288,7 +288,7 @@ Avoid outer double quotes around payloads containing `$PWD`, `$VAR`, backticks,
 - Never omit `--pane` for `send`, `key`, `read`, or `focus` in automation.
 - Use `prowl agents --json` for discovery and `prowl agents read <pN|uuid> --json` for a supported agent's current semantic snapshot; use `prowl list --json` for all panes and worktree-level `task.status`.
 - `open /path` is a project/path navigation command. It may refocus an existing pane and is not a deterministic create command.
-- Use `tab create` when automation needs a fresh shell, and capture the returned `pane.id` before sending input.
+- Use `create tab` when automation needs a fresh shell, and capture the returned `pane.id` before sending input.
 - Focused pane is not stable; `open` and `focus` change it.
 - `read --wait-stable` sees rendered screen only. It cannot recover content folded by a TUI.
 - `read` returning fewer lines than `--last` requested is normally `truncated: false` — the pane simply has less history and you already have it all, so do not retry for more. `truncated: true` flags a possibly-incomplete result (the full scrollback could not be read).
@@ -354,4 +354,4 @@ Write the briefing from your current working knowledge — required sections are
 
 ## Command Set
 
-Current commands: `list`, `agents`, `agents read`, `read`, `send`, `key`, `focus`, `tab create`, `tab close`, `pane close`, `handoff to`, `handoff save`, and `open` (default). There is no CLI `quit`; close temporary tabs or panes with explicit `tab close` / `pane close` targets.
+Current commands: `list`, `agents`, `agents read`, `read`, `send`, `key`, `focus`, `create tab`, `close`, `handoff to`, `handoff save`, and `open` (default). There is no CLI `quit`; close temporary tabs or panes with an explicit `close` target. `tab create`, `tab close`, and `pane close` remain deprecated aliases for one release.
diff --git a/supacode/App/supacodeApp.swift b/supacode/App/supacodeApp.swift
index fd8ef05a..66836fb9 100644
--- a/supacode/App/supacodeApp.swift
+++ b/supacode/App/supacodeApp.swift
@@ -802,72 +802,84 @@ struct SupacodeApp: App {
         return KeyDeliveryResult(attempted: repeatCount, delivered: delivered)
       }
     )
-    let tabHandler = TabCommandHandler(
-      resolveProvider: { selector in
-        let resolver = TargetResolver {
-          TargetResolutionSnapshotBuilder.makeSnapshot(
-            repositoriesState: appStore.state.repositories,
-            terminalManager: terminalManager
-          )
-        }
-        return resolver.resolve(selector).map { TabResolvedTarget(from: $0) }
-      },
-      createTab: { target, path in
-        let repositories = Array(appStore.state.repositories.repositories)
-        guard let worktree = resolveCLITerminalWorktree(id: target.worktreeID, repositories: repositories) else {
-          return nil
-        }
-        selectCLIWorktreeContext(
-          worktreeID: target.worktreeID,
-          appStore: appStore,
+    let resolveTabTarget: TabCommandHandler.ResolveProvider = { selector in
+      let resolver = TargetResolver {
+        TargetResolutionSnapshotBuilder.makeSnapshot(
+          repositoriesState: appStore.state.repositories,
           terminalManager: terminalManager
         )
-        let state = terminalManager.state(for: worktree)
-        let directory = path.map { URL(fileURLWithPath: $0, isDirectory: true) }
-        guard let tabID = state.createTab(workingDirectoryOverride: directory) else {
-          return nil
-        }
-        let resolver = makeTargetResolver(appStore: appStore, terminalManager: terminalManager)
-        switch resolver.resolve(.tab(tabID.rawValue.uuidString)) {
-        case .success(let resolved):
-          return TabResolvedTarget(from: resolved)
-        case .failure:
-          return nil
-        }
-      },
-      closeTab: { target, force in
-        guard let tabUUID = UUID(uuidString: target.tabID),
-          let state = terminalManager.stateIfExists(for: target.worktreeID)
-        else {
-          return false
-        }
-        return state.closeTab(
-          TerminalTabID(rawValue: tabUUID),
-          confirmation: force ? .skip : .prompt(.tab)
+      }
+      return resolver.resolve(selector).map { TabResolvedTarget(from: $0) }
+    }
+    let resolveLifecycleTarget: LifecycleCommandHandler.ResolveCloseTargetProvider = { selector in
+      let resolver = TargetResolver {
+        TargetResolutionSnapshotBuilder.makeSnapshot(
+          repositoriesState: appStore.state.repositories,
+          terminalManager: terminalManager
         )
       }
+      return resolver.resolveLifecycleTarget(selector)
+    }
+    let createTab: TabCommandHandler.CreateTabProvider = { target, path in
+      let repositories = Array(appStore.state.repositories.repositories)
+      guard let worktree = resolveCLITerminalWorktree(id: target.worktreeID, repositories: repositories) else {
+        return nil
+      }
+      selectCLIWorktreeContext(
+        worktreeID: target.worktreeID,
+        appStore: appStore,
+        terminalManager: terminalManager
+      )
+      let state = terminalManager.state(for: worktree)
+      let directory = path.map { URL(fileURLWithPath: $0, isDirectory: true) }
+      guard let tabID = state.createTab(workingDirectoryOverride: directory) else {
+        return nil
+      }
+      let resolver = makeTargetResolver(appStore: appStore, terminalManager: terminalManager)
+      switch resolver.resolve(.tab(tabID.rawValue.uuidString)) {
+      case .success(let resolved):
+        return TabResolvedTarget(from: resolved)
+      case .failure:
+        return nil
+      }
+    }
+    let closeTab: TabCommandHandler.CloseTabProvider = { target, force in
+      guard let tabUUID = UUID(uuidString: target.tabID),
+        let state = terminalManager.stateIfExists(for: target.worktreeID)
+      else {
+        return false
+      }
+      return state.closeTab(
+        TerminalTabID(rawValue: tabUUID),
+        confirmation: force ? .skip : .prompt(.tab)
+      )
+    }
+    let closePane: PaneCommandHandler.ClosePaneProvider = { target, force in
+      guard let paneID = UUID(uuidString: target.paneID),
+        let state = terminalManager.stateIfExists(for: target.worktreeID)
+      else {
+        return false
+      }
+      return state.closeSurface(
+        id: paneID,
+        confirmation: force ? .skip : .prompt(.pane)
+      )
+    }
+    let lifecycleHandler = LifecycleCommandHandler(
+      resolveCreateTarget: resolveTabTarget,
+      resolveCloseTarget: resolveLifecycleTarget,
+      createTab: createTab,
+      closeTab: closeTab,
+      closePane: closePane
+    )
+    let tabHandler = TabCommandHandler(
+      resolveProvider: resolveTabTarget,
+      createTab: createTab,
+      closeTab: closeTab
     )
     let paneHandler = PaneCommandHandler(
-      resolveProvider: { selector in
-        let resolver = TargetResolver {
-          TargetResolutionSnapshotBuilder.makeSnapshot(
-            repositoriesState: appStore.state.repositories,
-            terminalManager: terminalManager
-          )
-        }
-        return resolver.resolve(selector).map { TabResolvedTarget(from: $0) }
-      },
-      closePane: { target, force in
-        guard let paneID = UUID(uuidString: target.paneID),
-          let state = terminalManager.stateIfExists(for: target.worktreeID)
-        else {
-          return false
-        }
-        return state.closeSurface(
-          id: paneID,
-          confirmation: force ? .skip : .prompt(.pane)
-        )
-      }
+      resolveProvider: resolveTabTarget,
+      closePane: closePane
     )
     let handoffHandler = HandoffCommandHandler(
       resolveProvider: { selector, callerPID in
@@ -948,6 +960,8 @@ struct SupacodeApp: App {
       sendHandler: sendHandler,
       keyHandler: keyHandler,
       readHandler: readHandler,
+      createHandler: lifecycleHandler,
+      closeHandler: lifecycleHandler,
       tabHandler: tabHandler,
       paneHandler: paneHandler,
       handoffHandler: handoffHandler
diff --git a/supacode/CLIService/CLICommandRouter.swift b/supacode/CLIService/CLICommandRouter.swift
index 18dd3350..8367ed8d 100644
--- a/supacode/CLIService/CLICommandRouter.swift
+++ b/supacode/CLIService/CLICommandRouter.swift
@@ -13,6 +13,8 @@ final class CLICommandRouter {
   private let sendHandler: any CommandHandler
   private let keyHandler: any CommandHandler
   private let readHandler: any CommandHandler
+  private let createHandler: any CommandHandler
+  private let closeHandler: any CommandHandler
   private let tabHandler: any CommandHandler
   private let paneHandler: any CommandHandler
   private let handoffHandler: any CommandHandler
@@ -26,6 +28,8 @@ final class CLICommandRouter {
     sendHandler: any CommandHandler = StubCommandHandler(command: "send"),
     keyHandler: any CommandHandler = StubCommandHandler(command: "key"),
     readHandler: any CommandHandler = StubCommandHandler(command: "read"),
+    createHandler: any CommandHandler = StubCommandHandler(command: "create"),
+    closeHandler: any CommandHandler = StubCommandHandler(command: "close"),
     tabHandler: any CommandHandler = StubCommandHandler(command: "tab"),
     paneHandler: any CommandHandler = StubCommandHandler(command: "pane"),
     handoffHandler: any CommandHandler = StubCommandHandler(command: "handoff")
@@ -38,6 +42,8 @@ final class CLICommandRouter {
     self.sendHandler = sendHandler
     self.keyHandler = keyHandler
     self.readHandler = readHandler
+    self.createHandler = createHandler
+    self.closeHandler = closeHandler
     self.tabHandler = tabHandler
     self.paneHandler = paneHandler
     self.handoffHandler = handoffHandler
@@ -57,6 +63,8 @@ final class CLICommandRouter {
     case .send: handler = sendHandler
     case .key: handler = keyHandler
     case .read: handler = readHandler
+    case .create: handler = createHandler
+    case .close: handler = closeHandler
     case .tab: handler = tabHandler
     case .pane: handler = paneHandler
     case .handoff: handler = handoffHandler
diff --git a/supacode/CLIService/LifecycleCommandHandler.swift b/supacode/CLIService/LifecycleCommandHandler.swift
new file mode 100644
index 00000000..0cefa321
--- /dev/null
+++ b/supacode/CLIService/LifecycleCommandHandler.swift
@@ -0,0 +1,202 @@
+import Foundation
+
+struct LifecycleResolvedTarget: Sendable, Equatable {
+  let resource: LifecycleResource
+  let target: TabResolvedTarget
+}
+
+@MainActor
+final class LifecycleCommandHandler: CommandHandler {
+  typealias ResolveCreateTargetProvider = @MainActor (TargetSelector) -> Result<TabResolvedTarget, TargetResolverError>
+  typealias ResolveCloseTargetProvider =
+    @MainActor (TargetSelector) -> Result<LifecycleResolvedTarget, TargetResolverError>
+  typealias CreateTabProvider = @MainActor (TabResolvedTarget, String?) -> TabResolvedTarget?
+  typealias CloseTabProvider = @MainActor (TabResolvedTarget, Bool) -> Bool
+  typealias ClosePaneProvider = @MainActor (TabResolvedTarget, Bool) -> Bool
+
+  private let resolveCreateTarget: ResolveCreateTargetProvider
+  private let resolveCloseTarget: ResolveCloseTargetProvider
+  private let createTab: CreateTabProvider
+  private let closeTab: CloseTabProvider
+  private let closePane: ClosePaneProvider
+
+  init(
+    resolveCreateTarget: @escaping ResolveCreateTargetProvider,
+    resolveCloseTarget: @escaping ResolveCloseTargetProvider,
+    createTab: @escaping CreateTabProvider,
+    closeTab: @escaping CloseTabProvider,
+    closePane: @escaping ClosePaneProvider
+  ) {
+    self.resolveCreateTarget = resolveCreateTarget
+    self.resolveCloseTarget = resolveCloseTarget
+    self.createTab = createTab
+    self.closeTab = closeTab
+    self.closePane = closePane
+  }
+
+  // swiftlint:disable:next async_without_await
+  func handle(envelope: CommandEnvelope) async -> CommandResponse {
+    switch envelope.command {
+    case .create(let input):
+      return handleCreate(input)
+    case .close(let input):
+      return handleClose(input)
+    default:
+      return errorResponse(
+        command: envelope.command.name, code: CLIErrorCode.invalidArgument, message: "Invalid command.")
+    }
+  }
+
+  private func handleCreate(_ input: CreateInput) -> CommandResponse {
+    guard input.resource == .tab else {
+      return errorResponse(
+        command: "create",
+        code: CLIErrorCode.invalidArgument,
+        message: "create pane is not available yet."
+      )
+    }
+    guard case .worktree = input.selector else {
+      return errorResponse(
+        command: "create",
+        code: CLIErrorCode.invalidArgument,
+        message: "create tab requires a worktree target."
+      )
+    }
+
+    let target: TabResolvedTarget
+    switch resolveCreateTarget(input.selector) {
+    case .success(let resolved):
+      target = resolved
+    case .failure(let error):
+      return mapResolverError(command: "create", error: error)
+    }
+
+    let path = normalizedAllowedPath(input.path, worktreePath: target.worktreePath)
+    guard input.path == nil || path != nil else {
+      return errorResponse(
+        command: "create",
+        code: CLIErrorCode.pathNotAllowed,
+        message: "Tab path must be inside the resolved worktree."
+      )
+    }
+    guard let createdTarget = createTab(target, path) else {
+      return errorResponse(command: "create", code: CLIErrorCode.createFailed, message: "Failed to create tab.")
+    }
+    return success(command: "create", resource: .tab, target: createdTarget)
+  }
+
+  private func handleClose(_ input: CloseInput) -> CommandResponse {
+    guard !input.selector.isNone else {
+      return errorResponse(
+        command: "close",
+        code: CLIErrorCode.invalidArgument,
+        message: "close requires an explicit pane or tab target."
+      )
+    }
+
+    let resolved: LifecycleResolvedTarget
+    switch resolveCloseTarget(input.selector) {
+    case .success(let target):
+      resolved = target
+    case .failure(let error):
+      return mapResolverError(command: "close", error: error)
+    }
+
+    let didClose =
+      switch resolved.resource {
+      case .tab:
+        closeTab(resolved.target, input.force)
+      case .pane:
+        closePane(resolved.target, input.force)
+      }
+    guard didClose else {
+      return errorResponse(
+        command: "close",
+        code: CLIErrorCode.closeFailed,
+        message: "Failed to close \(resolved.resource.rawValue)."
+      )
+    }
+    return success(command: "close", resource: resolved.resource, target: resolved.target)
+  }
+
+  private func normalizedAllowedPath(_ path: String?, worktreePath: String) -> String? {
+    guard let path else { return nil }
+    let normalizedPath = normalize(path)
+    let normalizedWorktree = normalize(worktreePath)
+    guard normalizedPath == normalizedWorktree || normalizedPath.hasPrefix(normalizedWorktree + "/") else {
+      return nil
+    }
+    return normalizedPath
+  }
+
+  private func normalize(_ path: String) -> String {
+    URL(fileURLWithPath: path, isDirectory: true)
+      .standardizedFileURL
+      .path(percentEncoded: false)
+      .trimmingTrailingSlash()
+  }
+
+  private func success(command: String, resource: LifecycleResource, target: TabResolvedTarget) -> CommandResponse {
+    do {
+      return try CommandResponse(
+        ok: true,
+        command: command,
+        schemaVersion: "prowl.cli.\(command).v1",
+        data: RawJSON(encoding: LifecycleCommandPayload(resource: resource, target: makePayloadTarget(from: target)))
+      )
+    } catch {
+      return errorResponse(command: command, code: CLIErrorCode.createFailed, message: "Failed to encode response.")
+    }
+  }
+
+  private func makePayloadTarget(from target: TabResolvedTarget) -> TabTarget {
+    TabTarget(
+      worktree: TabTargetWorktree(
+        id: target.worktreeID,
+        name: target.worktreeName,
+        path: target.worktreePath,
+        rootPath: target.worktreeRootPath,
+        kind: target.worktreeKind
+      ),
+      tab: TabTargetTab(
+        id: target.tabID,
+        title: target.tabTitle,
+        selected: target.tabSelected
+      ),
+      pane: TabTargetPane(
+        id: target.paneID,
+        title: target.paneTitle,
+        cwd: target.paneCWD,
+        focused: target.paneFocused
+      )
+    )
+  }
+
+  private func mapResolverError(command: String, error: TargetResolverError) -> CommandResponse {
+    switch error {
+    case .notFound(let message):
+      errorResponse(command: command, code: CLIErrorCode.targetNotFound, message: message)
+    case .notUnique(let message):
+      errorResponse(command: command, code: CLIErrorCode.targetNotUnique, message: message)
+    }
+  }
+
+  private func errorResponse(command: String, code: String, message: String) -> CommandResponse {
+    CommandResponse(
+      ok: false,
+      command: command,
+      schemaVersion: "prowl.cli.\(command).v1",
+      error: CommandError(code: code, message: message)
+    )
+  }
+}
+
+extension String {
+  fileprivate func trimmingTrailingSlash() -> String {
+    var value = self
+    while value.count > 1, value.hasSuffix("/") {
+      value.removeLast()
+    }
+    return value
+  }
+}
diff --git a/supacode/CLIService/Shared/CommandEnvelope.swift b/supacode/CLIService/Shared/CommandEnvelope.swift
index ad0f07c9..10cd9098 100644
--- a/supacode/CLIService/Shared/CommandEnvelope.swift
+++ b/supacode/CLIService/Shared/CommandEnvelope.swift
@@ -22,6 +22,8 @@ public enum Command: Codable, Sendable {
   case send(SendInput)
   case key(KeyInput)
   case read(ReadInput)
+  case create(CreateInput)
+  case close(CloseInput)
   case tab(TabInput)
   case pane(PaneInput)
   case handoff(HandoffInput)
@@ -36,6 +38,8 @@ public enum Command: Codable, Sendable {
     case .send: "send"
     case .key: "key"
     case .read: "read"
+    case .create: "create"
+    case .close: "close"
     case .tab: "tab"
     case .pane: "pane"
     case .handoff: "handoff"
diff --git a/supacode/CLIService/Shared/ErrorCodes.swift b/supacode/CLIService/Shared/ErrorCodes.swift
index 6171d4b0..e28c1375 100644
--- a/supacode/CLIService/Shared/ErrorCodes.swift
+++ b/supacode/CLIService/Shared/ErrorCodes.swift
@@ -49,6 +49,10 @@ public enum CLIErrorCode {
   // Read
   public static let readFailed = "READ_FAILED"
 
+  // Lifecycle
+  public static let createFailed = "CREATE_FAILED"
+  public static let closeFailed = "CLOSE_FAILED"
+
   // Tab
   public static let tabFailed = "TAB_FAILED"
 
diff --git a/supacode/CLIService/Shared/InputModels.swift b/supacode/CLIService/Shared/InputModels.swift
index b69457cf..d4c7ba01 100644
--- a/supacode/CLIService/Shared/InputModels.swift
+++ b/supacode/CLIService/Shared/InputModels.swift
@@ -200,6 +200,33 @@ public struct ReadInput: Codable, Sendable {
   }
 }
 
+public enum LifecycleResource: String, Codable, Sendable, Equatable {
+  case tab
+  case pane
+}
+
+public struct CreateInput: Codable, Sendable {
+  public let resource: LifecycleResource
+  public let selector: TargetSelector
+  public let path: String?
+
+  public init(resource: LifecycleResource, selector: TargetSelector, path: String? = nil) {
+    self.resource = resource
+    self.selector = selector
+    self.path = path
+  }
+}
+
+public struct CloseInput: Codable, Sendable {
+  public let selector: TargetSelector
+  public let force: Bool
+
+  public init(selector: TargetSelector, force: Bool = false) {
+    self.selector = selector
+    self.force = force
+  }
+}
+
 public enum TabAction: String, Codable, Sendable {
   case create
   case close
diff --git a/supacode/CLIService/Shared/LifecycleCommandPayload.swift b/supacode/CLIService/Shared/LifecycleCommandPayload.swift
new file mode 100644
index 00000000..05e119e3
--- /dev/null
+++ b/supacode/CLIService/Shared/LifecycleCommandPayload.swift
@@ -0,0 +1,11 @@
+import Foundation
+
+public struct LifecycleCommandPayload: Codable, Sendable, Equatable {
+  public let resource: LifecycleResource
+  public let target: TabTarget
+
+  public init(resource: LifecycleResource, target: TabTarget) {
+    self.resource = resource
+    self.target = target
+  }
+}
diff --git a/supacode/CLIService/TargetResolver.swift b/supacode/CLIService/TargetResolver.swift
index 5adad53d..49fb654f 100644
--- a/supacode/CLIService/TargetResolver.swift
+++ b/supacode/CLIService/TargetResolver.swift
@@ -55,6 +55,44 @@ final class TargetResolver {
     }
   }
 
+  /// Resolves an explicit pane-or-tab lifecycle target without allowing worktree fallback.
+  func resolveLifecycleTarget(_ selector: TargetSelector) -> Result<LifecycleResolvedTarget, TargetResolverError> {
+    let snapshot = snapshotProvider()
+    switch selector {
+    case .pane(let value):
+      return resolvePane(value, snapshot).map {
+        LifecycleResolvedTarget(resource: .pane, target: TabResolvedTarget(from: $0))
+      }
+    case .tab(let value):
+      return resolveTab(value, snapshot).map {
+        LifecycleResolvedTarget(resource: .tab, target: TabResolvedTarget(from: $0))
+      }
+    case .auto(let value):
+      if isPrefixedShortHandle(value, prefix: "p") {
+        return resolvePane(value, snapshot).map {
+          LifecycleResolvedTarget(resource: .pane, target: TabResolvedTarget(from: $0))
+        }
+      }
+      if isPrefixedShortHandle(value, prefix: "t") {
+        return resolveTab(value, snapshot).map {
+          LifecycleResolvedTarget(resource: .tab, target: TabResolvedTarget(from: $0))
+        }
+      }
+      guard UUID(uuidString: value) != nil else {
+        return .failure(.notFound("Lifecycle target '\(value)' must be a pane/tab UUID or prefixed handle."))
+      }
+      if case .success(let target) = resolvePane(value, snapshot) {
+        return .success(LifecycleResolvedTarget(resource: .pane, target: TabResolvedTarget(from: target)))
+      }
+      if case .success(let target) = resolveTab(value, snapshot) {
+        return .success(LifecycleResolvedTarget(resource: .tab, target: TabResolvedTarget(from: target)))
+      }
+      return .failure(.notFound("Pane or tab '\(value)' not found."))
+    case .none, .worktree:
+      return .failure(.notFound("Lifecycle commands require an explicit pane or tab target."))
+    }
+  }
+
   // MARK: - .none: focused worktree → selected tab → focused pane
 
   private func resolveNone(_ snapshot: TargetResolutionSnapshot) -> Result<ResolvedTarget, TargetResolverError> {
@@ -143,12 +181,19 @@ final class TargetResolver {
     return .failure(.notFound("Pane '\(value)' not found."))
   }
 
-  // MARK: - .auto: try pane → tab → worktree
+  // MARK: - .auto: typed handle → UUID → worktree
 
   private func resolveAuto(
     _ value: String,
     _ snapshot: TargetResolutionSnapshot
   ) -> Result<ResolvedTarget, TargetResolverError> {
+    if isPrefixedShortHandle(value, prefix: "p") {
+      return resolvePane(value, snapshot)
+    }
+    if isPrefixedShortHandle(value, prefix: "t") {
+      return resolveTab(value, snapshot)
+    }
+
     // Try as pane UUID first (most specific)
     if UUID(uuidString: value) != nil {
       if case .success(let target) = resolvePane(value, snapshot) {
@@ -181,6 +226,10 @@ final class TargetResolver {
     return pane.handle == handle
   }
 
+  private func isPrefixedShortHandle(_ selector: String, prefix: Character) -> Bool {
+    selector.lowercased().first == prefix && shortHandle(in: selector, prefix: prefix) != nil
+  }
+
   private func shortHandle(in selector: String, prefix: Character) -> Int? {
     let normalized = selector.lowercased()
     let digits: Substring
diff --git a/supacodeTests/CLILifecycleCommandHandlerTests.swift b/supacodeTests/CLILifecycleCommandHandlerTests.swift
new file mode 100644
index 00000000..58caaff5
--- /dev/null
+++ b/supacodeTests/CLILifecycleCommandHandlerTests.swift
@@ -0,0 +1,106 @@
+import Foundation
+import Testing
+
+@testable import supacode
+
+@MainActor
+struct CLILifecycleCommandHandlerTests {
+  @Test func createTabResolvesWorktreeCreatesTabAndReturnsCreatePayload() async throws {
+    let base = makeTarget(tabID: "base-tab", paneID: "base-pane")
+    let created = makeTarget(tabID: "created-tab", paneID: "created-pane")
+    var resolvedSelector: TargetSelector?
+    var createPath: String?
+    let handler = LifecycleCommandHandler(
+      resolveCreateTarget: { selector in
+        resolvedSelector = selector
+        return .success(base)
+      },
+      resolveCloseTarget: { _ in .success(LifecycleResolvedTarget(resource: .pane, target: base)) },
+      createTab: { _, path in
+        createPath = path
+        return created
+      },
+      closeTab: { _, _ in true },
+      closePane: { _, _ in true }
+    )
+
+    let response = await handler.handle(
+      envelope: CommandEnvelope(
+        output: .json,
+        command: .create(CreateInput(resource: .tab, selector: .worktree("App"), path: "/Projects/App"))
+      )
+    )
+
+    #expect(response.ok)
+    #expect(response.command == "create")
+    #expect(response.schemaVersion == "prowl.cli.create.v1")
+    #expect(resolvedSelector == .worktree("App"))
+    #expect(createPath == "/Projects/App")
+    let data = try #require(response.data)
+    let payload = try data.decode(as: LifecycleCommandPayload.self)
+    #expect(payload.resource == .tab)
+    #expect(payload.target.tab.id == "created-tab")
+  }
+
+  @Test func closeUsesResolvedResourceAndReturnsClosePayload() async throws {
+    let target = makeTarget(tabID: "tab-to-close", paneID: "pane-to-close")
+    var closedPane: TabResolvedTarget?
+    let handler = LifecycleCommandHandler(
+      resolveCreateTarget: { _ in .success(target) },
+      resolveCloseTarget: { selector in
+        #expect(selector == .auto("p12"))
+        return .success(LifecycleResolvedTarget(resource: .pane, target: target))
+      },
+      createTab: { _, _ in nil },
+      closeTab: { _, _ in false },
+      closePane: { target, force in
+        #expect(force)
+        closedPane = target
+        return true
+      }
+    )
+
+    let response = await handler.handle(
+      envelope: CommandEnvelope(output: .json, command: .close(CloseInput(selector: .auto("p12"), force: true)))
+    )
+
+    #expect(response.ok)
+    #expect(response.command == "close")
+    #expect(response.schemaVersion == "prowl.cli.close.v1")
+    #expect(closedPane == target)
+    let data = try #require(response.data)
+    let payload = try data.decode(as: LifecycleCommandPayload.self)
+    #expect(payload.resource == .pane)
+    #expect(payload.target.pane.id == "pane-to-close")
+  }
+
+  private func makeTarget(
+    worktreeID: String = "App:/Projects/App",
+    worktreeName: String = "App",
+    worktreePath: String = "/Projects/App",
+    worktreeRootPath: String = "/Projects/App",
+    worktreeKind: String = "git",
+    tabID: String = "tab-1",
+    tabTitle: String = "App 1",
+    tabSelected: Bool = true,
+    paneID: String = "pane-1",
+    paneTitle: String = "zsh",
+    paneCWD: String? = "/Projects/App",
+    paneFocused: Bool = true
+  ) -> TabResolvedTarget {
+    TabResolvedTarget(
+      worktreeID: worktreeID,
+      worktreeName: worktreeName,
+      worktreePath: worktreePath,
+      worktreeRootPath: worktreeRootPath,
+      worktreeKind: worktreeKind,
+      tabID: tabID,
+      tabTitle: tabTitle,
+      tabSelected: tabSelected,
+      paneID: paneID,
+      paneTitle: paneTitle,
+      paneCWD: paneCWD,
+      paneFocused: paneFocused
+    )
+  }
+}
diff --git a/supacodeTests/CLITargetResolverTests.swift b/supacodeTests/CLITargetResolverTests.swift
index bd896595..d5230b5f 100644
--- a/supacodeTests/CLITargetResolverTests.swift
+++ b/supacodeTests/CLITargetResolverTests.swift
@@ -31,12 +31,14 @@ struct CLITargetResolverTests {
     }
   }
 
-  @Test func autoSelectorKeepsNumericValuesForWorktrees() throws {
+  @Test func autoSelectorResolvesPrefixedHandlesAndKeepsBareNumbersForWorktrees() throws {
+    let tabID = UUID()
+    let paneID = UUID()
     let paneSnapshot = makeSnapshot(
       worktreeID: "pane-worktree",
       worktreeName: "other",
-      tab: (id: UUID(), handle: 1),
-      panes: [(id: UUID(), handle: 3)],
+      tab: (id: tabID, handle: 1),
+      panes: [(id: paneID, handle: 3)],
       focusedPaneID: nil
     )
     let numericWorktreeSnapshot = makeSnapshot(
@@ -53,13 +55,69 @@ struct CLITargetResolverTests {
       )
     }
 
+    let paneTarget = try resolvedTarget(from: resolver.resolve(.auto("p3")))
+    #expect(paneTarget.paneID == paneID)
+
+    let tabTarget = try resolvedTarget(from: resolver.resolve(.auto("t1")))
+    #expect(tabTarget.tabID == tabID)
+
     let numericTarget = try resolvedTarget(from: resolver.resolve(.auto("3")))
     #expect(numericTarget.worktreeID == "numeric-worktree")
+  }
+
+  @Test func lifecycleResolverRoutesOnlyTabsAndPanes() throws {
+    let tabID = UUID()
+    let paneID = UUID()
+    let snapshot = makeSnapshot(
+      worktreeID: "worktree",
+      worktreeName: "main",
+      tab: (id: tabID, handle: 6),
+      panes: [(id: paneID, handle: 12)],
+      focusedPaneID: paneID
+    )
+    let resolver = TargetResolver { snapshot }
 
-    if case .failure(.notFound) = resolver.resolve(.auto("p3")) {
-      // Expected: short handles are explicit-selector-only.
+    let pane = try lifecycleTarget(from: resolver.resolveLifecycleTarget(.auto("p12")))
+    #expect(pane.resource == .pane)
+    #expect(pane.target.paneID == paneID.uuidString)
+
+    let tab = try lifecycleTarget(from: resolver.resolveLifecycleTarget(.auto("t6")))
+    #expect(tab.resource == .tab)
+    #expect(tab.target.tabID == tabID.uuidString)
+
+    if case .failure(.notFound) = resolver.resolveLifecycleTarget(.worktree("main")) {
+      // Expected: lifecycle operations never project a worktree to a tab or pane.
     } else {
-      Issue.record("--target must not resolve a short pane handle")
+      Issue.record("Lifecycle commands must reject worktree targets.")
+    }
+  }
+
+  @Test func stalePrefixedHandleDoesNotFallBackToWorktree() {
+    let snapshot = makeSnapshot(
+      worktreeID: "p3-worktree",
+      worktreeName: "p3",
+      tab: (id: UUID(), handle: 1),
+      panes: [(id: UUID(), handle: 2)],
+      focusedPaneID: nil
+    )
+    let resolver = TargetResolver { snapshot }
+
+    guard case .failure(.notFound(let message)) = resolver.resolve(.auto("p3")) else {
+      Issue.record("A stale prefixed handle must not resolve as a worktree.")
+      return
+    }
+    #expect(message.contains("Pane 'p3' not found"))
+  }
+
+  private func lifecycleTarget(
+    from result: Result<LifecycleResolvedTarget, TargetResolverError>
+  ) throws -> LifecycleResolvedTarget {
+    switch result {
+    case .success(let target):
+      return target
+    case .failure(let error):
+      Issue.record("Unexpected lifecycle resolution failure: \(error)")
+      throw error
     }
   }
 
-- 
2.51.2


From c052825f646357e5595bc81584be53c3f7410d30 Mon Sep 17 00:00:00 2001
From: onevcat <onevcat@gmail.com>
Date: Mon, 17 Aug 2026 20:55:58 +0900
Subject: [PATCH 19/19] Group notification update controls and document toolbar
 standards

---
 AGENTS.md                                     |   1 +
 .../058-unified-toolbar-layout/000-plan.md    |   2 +
 .../058-unified-toolbar-layout/001-action.md  |  22 ++--
 .../002-notification-update-group.md          |  25 ++++
 .../061-native-toolbar-controls/000-plan.md   |  87 +++++++++++++
 .../061-native-toolbar-controls/001-action.md |  52 ++++++++
 .../toolbar-controls.md                       | 120 ++++++++++++++++++
 docs-ai/README.md                             |   1 +
 docs/components/notifications.md              |   5 +-
 docs/components/updates.md                    |   4 +-
 .../Views/AgentsToolbarButton.swift           |   9 +-
 .../ToolbarNotificationsPopoverButton.swift   |  85 ++++++-------
 .../Views/WorktreeDetailToolbarViews.swift    |   6 +-
 .../Views/WorktreeDetailView.swift            |  73 ++++++-----
 14 files changed, 388 insertions(+), 104 deletions(-)
 create mode 100644 docs-ai/058-unified-toolbar-layout/002-notification-update-group.md
 create mode 100644 docs-ai/061-native-toolbar-controls/000-plan.md
 create mode 100644 docs-ai/061-native-toolbar-controls/001-action.md
 create mode 100644 docs-ai/061-native-toolbar-controls/toolbar-controls.md

diff --git a/AGENTS.md b/AGENTS.md
index 8f5866e6..c4594cf2 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -106,6 +106,7 @@ Reducer ← .terminalEvent(Event) ← AsyncStream<Event>
 - Use `@ObservableState` for TCA feature state; use `@Observable` for non-TCA shared stores; never `ObservableObject`
 - Always mark `@Observable` classes with `@MainActor`
 - Modern SwiftUI only: `foregroundStyle()`, `NavigationStack`, `Button` over `onTapGesture()`
+- Before changing a window toolbar control, its grouping, or Liquid Glass, read `docs-ai/061-native-toolbar-controls/toolbar-controls.md` and perform a Debug visual verification.
 - When a new logic changes in the Reducer, always add tests
 - In unit tests, never use `Task.sleep`; use `TestClock` (or an injected clock) and drive time with `advance`.
 - Prefer Swift-native APIs over Foundation where they exist (e.g., `replacing()` not `replacingOccurrences()`)
diff --git a/docs-ai/058-unified-toolbar-layout/000-plan.md b/docs-ai/058-unified-toolbar-layout/000-plan.md
index e5981dd7..4c044419 100644
--- a/docs-ai/058-unified-toolbar-layout/000-plan.md
+++ b/docs-ai/058-unified-toolbar-layout/000-plan.md
@@ -113,3 +113,5 @@ direction while hardening its implementation:
 - Remove the notifications style branch and share leading-control metrics between Agents and Bell.
 - Restore rename prompt submit/tooltip semantics and advertise the configurable shortcut from the context menu.
 - Verify the reported first-focus timing risk at runtime before changing it; do not add speculative focus workarounds.
+
+- Updated 2026-08-17: Grouped the conditional update indicator with Bell in the leading cluster — see [002-notification-update-group.md](002-notification-update-group.md).
diff --git a/docs-ai/058-unified-toolbar-layout/001-action.md b/docs-ai/058-unified-toolbar-layout/001-action.md
index aebd1595..91327d33 100644
--- a/docs-ai/058-unified-toolbar-layout/001-action.md
+++ b/docs-ai/058-unified-toolbar-layout/001-action.md
@@ -17,13 +17,15 @@
   `.toolbar(removing: .title)`, preserving `WindowTitle.compute(...)` for window identity
   without rendering a toolbar title. `AgentNotificationsToolbarContent` is the shared
   leading composition for all three view modes.
-- Agents and Quick Launch remain a native shared-glass group. The bell follows in a
-  separate `.navigation` item with `.sharedBackgroundVisibility(.hidden)` so it keeps the
-  visual gap that previously separated Agents from the branch title.
-- `supacode/Features/Repositories/Views/ToolbarNotificationsPopoverButton.swift` now has
-  one unconditional standalone-capsule presentation. Agents, Quick Launch, and Bell share
-  `LeadingToolbarControlMetrics`; the dead style branch and duplicated label metrics are
-  gone. Notification count, hover, click, and read-state behavior are unchanged.
+- Agents and Quick Launch remain a native shared-glass group. Bell and the conditional update
+  indicator follow in a separate leading capsule, preserving the visual gap that previously
+  separated Agents from the branch title. The implementation is centralized in
+  `AgentNotificationsToolbarContent`; see [002-notification-update-group.md](002-notification-update-group.md).
+- `supacode/Features/Repositories/Views/ToolbarNotificationsPopoverButton.swift` and
+  `ToolbarUpdateButton.swift` retain their original button-owned tint, tooltip, accessibility,
+  and interaction behavior. The isolated owner supplies the shared capsule; see
+  [061 Native Toolbar Controls](../061-native-toolbar-controls/toolbar-controls.md) for the
+  documented macOS 26 exception and review standard.
 - Normal, Shelf, and Canvas receive one assembled `ToolbarSharedState`; only their documented
   `ToolbarContent` structure differs. Canvas resolves the Agents capsule and profile launcher
   from the focused card. With no focused card, Quick Launch/profile rows are omitted instead
@@ -57,7 +59,7 @@
 - `make check`: changed-file formatting, strict `swift-format` lint, and SwiftLint passed.
 - `make build-app`: Debug build passed with zero errors and zero warnings.
 - Live Debug app inspection:
-  - Normal: no branch item; Agents + Quick Launch and Bell render as separate capsules.
+  - Normal: no branch item; Agents + Quick Launch render separately from the Bell + update capsule.
   - Canvas: no visible `Canvas` title; the same leading controls render against the
     focused-card toolbar.
   - Shelf: the same leading order and separation are retained.
@@ -72,8 +74,8 @@
 ## Deviations from plan
 
 - The initial shared-layout implementation placed Bell inside the Agents shared-glass
-  group. During live review, the desired separation was clarified: Bell now uses a
-  standalone glass capsule with the same gap as the removed branch item.
+  group. During live review, the desired separation was clarified: Bell and the conditional
+  update indicator now share a standalone capsule with the same gap as the removed branch item.
 - Removing the toolbar anchor required the rename form to move from a popover to an
   app-level sheet. The form and reducer request model remain intact.
 - Adding Agents to Canvas exposed that Hand Off still resolved only
diff --git a/docs-ai/058-unified-toolbar-layout/002-notification-update-group.md b/docs-ai/058-unified-toolbar-layout/002-notification-update-group.md
new file mode 100644
index 00000000..55abd428
--- /dev/null
+++ b/docs-ai/058-unified-toolbar-layout/002-notification-update-group.md
@@ -0,0 +1,25 @@
+# 058.002 — Notification and Update Group
+
+## Context
+
+Moving the notification bell into the leading orchestration cluster left the background-update
+indicator in the trailing toolbar. The two related controls no longer read as a group.
+
+## Change
+
+`WorktreeDetailView.AgentNotificationsToolbarContent` now keeps Bell and the conditional
+`ToolbarUpdateButton` together immediately after the Agents + Quick Launch group in Normal,
+Shelf, and Canvas. The original button views retain their own tint, tooltip, accessibility, and
+popover behavior.
+
+Adjacent native navigation groups merge on macOS 26, so the bell/update pair is one isolated
+navigation item: it hides the shared toolbar background and owns one outer glass capsule. This
+keeps the pair together while retaining the visual gap after Agents. The durable implementation
+and review standard live in
+[061 Native Toolbar Controls](../061-native-toolbar-controls/toolbar-controls.md).
+
+## Current state
+
+The Command Palette Debug action **[Debug] Simulate Update Found** exposes the update indicator
+for visual verification without contacting Sparkle. `docs/components/updates.md` and
+`docs/components/notifications.md` describe the current leading toolbar behavior.
diff --git a/docs-ai/061-native-toolbar-controls/000-plan.md b/docs-ai/061-native-toolbar-controls/000-plan.md
new file mode 100644
index 00000000..663aab2b
--- /dev/null
+++ b/docs-ai/061-native-toolbar-controls/000-plan.md
@@ -0,0 +1,87 @@
+# 061 — Native Toolbar Controls: Plan
+
+| | |
+| --- | --- |
+| **Status** | Implemented |
+| **Anchor date** | 2026-08-17 |
+| **Primary PRs** | Pending |
+| **Related** | [049-agents-toolbar-entry](../049-agents-toolbar-entry/000-plan.md), [058-unified-toolbar-layout](../058-unified-toolbar-layout/000-plan.md), [`AGENTS.md`](../../AGENTS.md) |
+
+## Background
+
+Moving the update indicator into the leading notification cluster exposed a recurring
+failure mode in Prowl's macOS 26 toolbar work: visual grouping, placement, and Liquid
+Glass are coupled by SwiftUI's toolbar bridge, but their interactions are not obvious from
+individual view code. Iterations that substituted `ControlGroup`, restyled existing buttons,
+or attached glass to the wrong owner lost placement, colors, or the native surface.
+
+The app already contains deliberate toolbar exceptions: the shared Normal/Shelf/Canvas
+leading cluster must keep Agents separate from the notification/update cluster, and Canvas
+keeps its dynamic command controls inside one toolbar item to avoid NSToolbar insert/remove
+animation. These decisions need one current reference rather than scattered comments and
+git archaeology.
+
+## Goals
+
+- Audit every current window-toolbar control and record whether its grouping is native or a
+  deliberate exception.
+- Document the verified native SwiftUI model, including official Apple references and the
+  macOS 26 SDK API boundary.
+- Record the notification/update leading-cluster implementation and the failed approaches
+  that must not be retried.
+- Establish a short, actionable implementation and review standard for future toolbar work.
+- Make the reference mandatory before changes to toolbar controls, grouping, or Liquid Glass.
+- Correct stale toolbar comments discovered during the audit without changing verified UI
+  behavior.
+
+### Non-goals
+
+- Redesigning existing toolbar controls, their actions, or their visual hierarchy.
+- Replacing SwiftUI toolbar APIs with AppKit toolbar management.
+- General documentation for non-toolbar `glassEffect` surfaces such as HUDs, popovers, or
+  terminal tabs.
+
+## Design / Approach
+
+Create a living guide at
+`docs-ai/061-native-toolbar-controls/toolbar-controls.md` with four durable sections:
+
+1. **Official model** — `ToolbarItem`, `ToolbarItemGroup`, `ToolbarSpacer(.fixed)`, and
+   `sharedBackgroundVisibility(_:)`, linked to Apple documentation and WWDC25 guidance.
+2. **Prowl audit** — the Main, Canvas, Diff, Sidebar, and Archived Worktrees toolbars,
+   including the reason for every non-default composition.
+3. **Implementation standard** — native grouping by default; a narrowly scoped leading
+   notification/update exception that preserves the original button views and applies one
+   outer glass surface only after opting out of shared background.
+4. **Review checklist** — visual state matrix, placement/grouping checks, and explicit
+   prohibitions against replacing toolbar grouping with `ControlGroup`, nested glass, or
+   incidental button restyling.
+
+Add a focused `AGENTS.md` instruction that routes toolbar changes to the guide. Keep the
+Normal/Shelf/Canvas composition centralized in
+`WorktreeDetailView.AgentNotificationsToolbarContent`; do not create mode-specific copies.
+
+## Alternatives & decisions
+
+- **Rely only on comments in `WorktreeDetailView.swift`:** rejected. They cannot capture the
+  full audit, official API boundary, historical failure modes, and review matrix.
+- **Use `ControlGroup` as a universal replacement for `ToolbarItemGroup`:** rejected. It is a
+  view container, not toolbar content; in the observed leading-cluster case it altered
+  placement, shared surface, and label-color behavior.
+- **Use `glassEffect` for every related toolbar button:** rejected. Native toolbar grouping is
+  the default; manually layered glass is reserved for the verified isolated composite where
+  a shared toolbar group cannot remain separate from Agents.
+- **Move all toolbar composition into AppKit:** rejected. SwiftUI's native toolbar APIs cover
+  the app's current needs, and the documented exceptions are smaller and safer.
+
+## Verification
+
+- Confirm the audit covers every `ToolbarItem`, `ToolbarItemGroup`, `ToolbarSpacer`, and
+  toolbar-owned `glassEffect` in the app source.
+- Confirm the guide's Apple API claims against both official Apple documentation and the
+  installed macOS 26 SwiftUI interface.
+- Run `make check` and `make build-app`.
+- Live-inspect the Debug app's leading cluster with update simulated: Agents is separate;
+  bell and update share one capsule; unread and update accent colors remain visible.
+
+## Amendments
diff --git a/docs-ai/061-native-toolbar-controls/001-action.md b/docs-ai/061-native-toolbar-controls/001-action.md
new file mode 100644
index 00000000..5b7e1cda
--- /dev/null
+++ b/docs-ai/061-native-toolbar-controls/001-action.md
@@ -0,0 +1,52 @@
+# 061 — Native Toolbar Controls: Action Log
+
+## Timeline
+
+| Date | Change | Ref |
+| --- | --- | --- |
+| 2026-08-17 | Audited every window-toolbar primitive and identified the leading notification/update and Canvas dynamic-command exceptions | Current source tree |
+| 2026-08-17 | Compared the implementation with Apple toolbar guidance and the installed macOS 26 SwiftUI interface | Apple docs / Xcode 26.6 SDK |
+| 2026-08-17 | Added the living native-toolbar control guide and required it from `AGENTS.md` | This record |
+| 2026-08-17 | Updated the leading-cluster implementation comments and corrected stale Canvas trailing-update references | `WorktreeDetailView.swift` |
+| 2026-08-17 | Amended the unified-toolbar record and user docs for the Bell + update capsule | [058.002](../058-unified-toolbar-layout/002-notification-update-group.md) |
+
+## Outcome & current state (as of 2026-08-17)
+
+- `docs-ai/061-native-toolbar-controls/toolbar-controls.md` is the normative implementation
+  map for Prowl window toolbars. It records the official SwiftUI primitives, Prowl's source
+  audit, approved exceptions, rejected approaches, and a review matrix.
+- `AGENTS.md` requires the guide and a Debug visual verification before changes to a window
+  toolbar control, its grouping, or Liquid Glass.
+- `WorktreeDetailView.AgentNotificationsToolbarContent` remains the one shared leading
+  composition for Normal, Shelf, and Canvas. Agents + Quick Launch use native
+  `ToolbarItemGroup`; the isolated Bell + conditional update capsule preserves the original
+  button views' color and behavior while remaining separate from Agents.
+- The Canvas Run/custom-command cluster remains one dynamic `ToolbarItem`; its source comment
+  now accurately describes the animation/overflow constraint without referring to a trailing
+  update control.
+- `docs-ai/058-unified-toolbar-layout` now records the current Bell + update behavior, and
+  `docs/components/notifications.md` describes the visible grouped indicator.
+
+## Verification
+
+- Source audit covered every `ToolbarItem`, `ToolbarItemGroup`, `ToolbarSpacer`,
+  `sharedBackgroundVisibility`, and toolbar-owned `glassEffect` under `supacode/Features/`.
+- Apple documentation confirmed `ToolbarItemGroup` for logical toolbar grouping,
+  `ToolbarSpacer(.fixed)` for group separation, and `sharedBackgroundVisibility(_:)` for
+  shared Liquid Glass ownership. The installed Xcode 26.6 macOS 26.5 SwiftUI interface
+  declares `ToolbarContent.sharedBackgroundVisibility(_:)` as available on macOS 26.
+- Debug visual review confirmed the final leading arrangement: Agents stays separate; Bell and
+  update share one capsule; their unread and update-accent colors remain visible.
+- `make check` and `make build-app` are run for the final change set.
+
+## Deviations from plan
+
+The leading Bell + update capsule cannot be expressed as two adjacent native navigation groups:
+the macOS 26 toolbar bridge merges those groups with Agents. The implementation therefore keeps
+the original button views inside one isolated owner with one outer glass surface. This is a
+narrow, documented exception rather than a replacement for `ToolbarItemGroup`.
+
+## Open questions
+
+- Re-verify the leading-cluster exception when upgrading the Xcode/macOS SDK: a future toolbar
+  bridge may honor a fixed navigation spacer or provide a native separate-group API.
diff --git a/docs-ai/061-native-toolbar-controls/toolbar-controls.md b/docs-ai/061-native-toolbar-controls/toolbar-controls.md
new file mode 100644
index 00000000..d4c5f096
--- /dev/null
+++ b/docs-ai/061-native-toolbar-controls/toolbar-controls.md
@@ -0,0 +1,120 @@
+# Native Toolbar Controls Guide
+
+This is the implementation and review reference for Prowl's macOS window toolbars. Read it
+before changing a toolbar button, placement, control group, `ToolbarSpacer`,
+`sharedBackgroundVisibility`, or toolbar-owned `glassEffect`.
+
+## 1. The native model
+
+| API | Owns | Standard use |
+| --- | --- | --- |
+| `ToolbarItem` | One semantic toolbar item and its placement | A single action, picker, or intentionally stable composite view. |
+| `ToolbarItemGroup` | Related toolbar items | Native group surface, per-item behavior, overflow semantics, and platform spacing. This is the default for related toolbar actions. |
+| `ToolbarSpacer(.fixed)` | Separation between unrelated toolbar groups | Use in placements where the toolbar honors it, especially trailing action clusters. |
+| `sharedBackgroundVisibility(_:)` | Whether toolbar content participates in an adjacent shared glass surface | Use `.hidden` only when the content must not merge with its neighbors. It removes the system-provided shared background. |
+| `glassEffect` | A custom view's own material | Not a replacement for `ToolbarItemGroup`. Use only when one isolated `ToolbarItem` must own a composite visual surface that native toolbar grouping cannot express. |
+
+### Official references
+
+- [Apple: ToolbarItemGroup](https://developer.apple.com/documentation/swiftui/toolbaritemgroup)
+- [Apple: sharedBackgroundVisibility(_:)](https://developer.apple.com/documentation/swiftui/toolbarcontent/sharedbackgroundvisibility(_:))
+- [Apple: Refining the system-provided Liquid Glass effect in toolbars](https://developer.apple.com/documentation/swiftui/landmarks-refining-the-system-provided-glass-effect-in-toolbars)
+- [WWDC25: Build a SwiftUI app with the new design](https://developer.apple.com/videos/play/wwdc2025/323/) — fixed toolbar spacers and hiding shared glass background
+
+The installed macOS 26 SwiftUI interface declares `ToolbarItemGroup` as `ToolbarContent` and
+exposes `ToolbarContent.sharedBackgroundVisibility(_:)` only on macOS 26+. The app's macOS
+26 deployment target satisfies that availability requirement.
+
+## 2. Prowl toolbar audit
+
+| Surface | Source | Current composition | Assessment |
+| --- | --- | --- | --- |
+| Main leading cluster (Normal, Shelf, Canvas) | `supacode/Features/Repositories/Views/WorktreeDetailView.swift` | Agents + Quick Launch use `ToolbarItemGroup(placement: .navigation)`. Bell + update use one isolated `ToolbarItem(placement: .navigation)`. | Native Agents group; verified composite exception for bell/update. |
+| Main principal status | `supacode/Features/Repositories/Views/WorktreeDetailView.swift`, `ToolbarStatusView.swift` | One `.principal` status projection. | Correct: display-only content is not an action group. |
+| Normal/Shelf trailing actions | `supacode/Features/Repositories/Views/WorktreeDetailView.swift`, `WorktreeDetailToolbarViews.swift` | Open action group, fixed spacers, Run item, inline custom-command group, overflow item. | Correct: semantic actions retain native toolbar ownership. |
+| Canvas trailing actions | `supacode/Features/Repositories/Views/WorktreeDetailView.swift` | One `.primaryAction` item with a dynamic Run/custom-command `HStack`. | Approved stability exception: changing the number of toolbar items causes NSToolbar insert/remove animation and visible overflow. |
+| Diff window | `supacode/Features/DiffView/DiffWindowContentView.swift` | Navigation sidebar toggle; principal and primary segmented pickers. | Correct native items; no custom glass. |
+| Sidebar | `supacode/Features/Repositories/Views/SidebarListView.swift` | Automatic Add Repository/Workspace item. | Correct single action. |
+| Archived Worktrees | `supacode/Features/Repositories/Views/ArchivedWorktreesDetailView.swift` | Automatic destructive Delete Selected item. | Correct single action. |
+
+`HandoffHudOverlayView`, `CommandPaletteOverlayView`, and terminal tab backgrounds use
+`glassEffect`, but are not window-toolbar content and are deliberately outside this guide.
+
+## 3. The leading notification/update exception
+
+### Required visible result
+
+```
+[ Agents | Quick Launch ]    [ Bell | Update ]
+```
+
+- Agents and Quick Launch remain one native shared-glass group.
+- Bell and update form a second capsule immediately after it.
+- The two capsules are separate.
+- Bell retains its `.orange` unread state and `.secondary` idle state.
+- Update retains `Color("ProwlAccent")`.
+
+### Why it is an exception
+
+Adjacent `.navigation` toolbar groups merge into one native shared-glass surface. A fixed
+`ToolbarSpacer` does not split that leading cluster in the observed macOS 26 toolbar bridge.
+Hiding the bell/update owner's shared background keeps it independent, but also removes the
+system surface. Therefore `AgentNotificationsToolbarContent` uses exactly one isolated
+`ToolbarItem` with all of the following:
+
+1. `.sharedBackgroundVisibility(.hidden)` on that `ToolbarItem`;
+2. an `HStack(spacing: 0)` containing the existing
+   `ToolbarNotificationsPopoverButton` and conditional `ToolbarUpdateButton` unchanged;
+3. one outer `.glassEffect(.regular.interactive(), in: Capsule())`.
+
+This is an ownership boundary, not a new style system. Do not add a divider, child glass,
+child padding, child frame, `buttonStyle(.plain)`, or a new color while moving these controls.
+The original button views own their labels, tint, tooltip, accessibility label, and popover
+behavior.
+
+### Explicitly rejected approaches
+
+| Approach | Observed failure | Do instead |
+| --- | --- | --- |
+| Put Agents, Bell, and update in adjacent `.navigation` `ToolbarItemGroup`s | The toolbar merges all controls into one shared glass surface. | Keep bell/update in the isolated composite owner. |
+| Use `ControlGroup` as a `ToolbarItemGroup` substitute | It changed the leading controls' surface/placement behavior and unified label rendering, losing bell and update colors. | Preserve the original button views in the approved isolated `HStack`. |
+| Add glass, padding, frames, dividers, or plain button styles to bell/update children | The native proportions, accent colors, and interaction appearance drift. | Apply one glass surface only to the composite owner. |
+| Move update separately to `.primaryAction` | Update appears detached from its related bell. | Keep it conditional inside the bell/update owner. |
+| Duplicate this composition by mode | Normal, Shelf, and Canvas drift. | Use `AgentNotificationsToolbarContent` in every mode. |
+
+## 4. Implementation standard
+
+1. Start with semantic relationship, then choose the native toolbar primitive:
+   - one action → `ToolbarItem`;
+   - related independent actions → `ToolbarItemGroup`;
+   - unrelated trailing groups → `ToolbarSpacer(.fixed)`;
+   - status/display → placement-specific `ToolbarItem`.
+2. Let the toolbar supply button material, hover behavior, padding, separators, and overflow
+   behavior by default.
+3. Treat `.sharedBackgroundVisibility(.hidden)` as an ownership boundary. Verify the resulting
+   background; it may need a documented owner-drawn surface such as the leading
+   notification/update exception.
+4. Keep dynamic Canvas command controls in their existing single `ToolbarItem` until a live
+   regression demonstrates that a multi-item structure no longer animates or overflows.
+5. Centralize shared toolbar content. Do not copy it into Normal, Shelf, and Canvas paths.
+6. Update this guide and the relevant `docs-ai` record when a new verified exception is added,
+   removed, or its rendering changes.
+
+## 5. Review checklist
+
+Before committing a toolbar change:
+
+- [ ] The chosen primitive matches the controls' semantic relationship.
+- [ ] A native `ToolbarItemGroup` is used unless this guide documents the exception.
+- [ ] Each `sharedBackgroundVisibility(.hidden)` has an explicit owner and visual reason.
+- [ ] Existing toolbar button views have not gained incidental padding, sizing, tint, or button
+      styles merely because their placement changed.
+- [ ] All affected modes render the same intended order.
+- [ ] The Debug build has been manually checked at normal width and a constrained width.
+- [ ] For the leading cluster: generic/detected Agents, no update/update available, unread
+      notification, and downloaded-update-ready states retain grouping and color.
+- [ ] Tooltips, accessibility labels, menus, popovers, and shortcuts remain available.
+- [ ] `make check` and `make build-app` pass.
+
+For visual verification, use the Debug Command Palette action **[Debug] Simulate Update Found**
+to expose the update control without querying Sparkle.
diff --git a/docs-ai/README.md b/docs-ai/README.md
index 76cd8f2e..e4e43dd5 100644
--- a/docs-ai/README.md
+++ b/docs-ai/README.md
@@ -112,3 +112,4 @@ agent-facing manual for that).
 | 058 | [unified-toolbar-layout](058-unified-toolbar-layout/000-plan.md) | 2026-08-07 | Remove redundant branch/title toolbar items and align the Agents + notifications cluster across Normal, Shelf, and Canvas |
 | 059 | [agent-transcript-snapshots](059-agent-transcript-snapshots/000-plan.md) | 2026-08-11 | Immediate Codex/Claude agent snapshots with trustworthy transcript results and actionable blocker text |
 | 060 | [prowl-cli-targeting-and-contract-governance](060-prowl-cli-targeting-and-contract-governance/000-plan.md) | 2026-08-16 | Unified target grammar, CLI contract rebaseline, and durable documentation governance |
+| 061 | [native-toolbar-controls](061-native-toolbar-controls/000-plan.md) | 2026-08-17 | Native macOS toolbar grouping, Liquid Glass ownership, and review standards |
diff --git a/docs/components/notifications.md b/docs/components/notifications.md
index 08802b3c..0f1fa9fe 100644
--- a/docs/components/notifications.md
+++ b/docs/components/notifications.md
@@ -41,8 +41,9 @@ sound.
 
 - **Sidebar:** an orange bell next to a worktree with unseen notifications.
 - **Toolbar:** a bell button follows the Agents control in the leading area in
-  Normal, Shelf, and Canvas. Its badge shows the unread count; opening the
-  popover marks items read.
+  Normal, Shelf, and Canvas. When an app update is available, its indicator
+  appears in the same control immediately after the bell. The bell badge shows
+  the unread count; opening the popover marks items read.
 - **Shelf:** orange highlight on the relevant tab slot + a dot on the spine.
 - **Canvas:** the card's title bar turns orange.
 - **Dock:** an optional numeric badge (count of worktrees with unseen
diff --git a/docs/components/updates.md b/docs/components/updates.md
index 3aeb012c..eb4648e3 100644
--- a/docs/components/updates.md
+++ b/docs/components/updates.md
@@ -14,8 +14,8 @@ Prowl uses the **Sparkle** framework for auto-updates. Releases are notarized.
   Updates", or Settings → Updates → "Check for Updates Now".
 - **Background checks:** if `updatesAutomaticallyCheckForUpdates` is on, Prowl
   checks periodically (roughly hourly). When a background check finds an update, a
-  badge appears on the notification bell; clicking it opens the standard Sparkle
-  dialog.
+  badge appears immediately after the notification bell in the same toolbar control;
+  clicking it opens the standard Sparkle dialog.
 - **On quit with a downloaded update:** Prowl offers to install or defer.
 - **Install confirmation:** installing and relaunching always requires an
   explicit confirmation. When an update is ready (or a user-initiated check finds
diff --git a/supacode/Features/Repositories/Views/AgentsToolbarButton.swift b/supacode/Features/Repositories/Views/AgentsToolbarButton.swift
index ce9a79fa..69da146d 100644
--- a/supacode/Features/Repositories/Views/AgentsToolbarButton.swift
+++ b/supacode/Features/Repositories/Views/AgentsToolbarButton.swift
@@ -4,8 +4,6 @@ enum LeadingToolbarControlMetrics {
   static let labelSpacing: CGFloat = 6
   static let iconSize: CGFloat = 20
   static let font: Font = .title3.weight(.medium)
-  static let standaloneHorizontalPadding: CGFloat = 10
-  static let standaloneVerticalPadding: CGFloat = 8
 }
 
 /// What the Agents capsule shows for the selected pane's detected agent.
@@ -50,9 +48,10 @@ struct AgentsLauncherItem: Equatable, Identifiable {
 /// the popover is the durable container here.
 ///
 /// The button carries no background of its own: it sits in a shared-glass
-/// toolbar group next to `AgentsQuickLaunchButton`. Notifications follow as
-/// a separate capsule, preserving the visual gap previously occupied by the
-/// branch item. Normal, Shelf, and Canvas share this leading structure.
+/// toolbar group next to `AgentsQuickLaunchButton`. Notifications and update
+/// status follow in an isolated glass capsule because adjacent navigation
+/// groups merge on macOS 26. See docs-ai 061 before changing that composition.
+/// Normal, Shelf, and Canvas share this leading structure.
 struct AgentsToolbarButton: View {
   let capsule: AgentsCapsuleState?
   let launcherItems: [AgentsLauncherItem]
diff --git a/supacode/Features/Repositories/Views/ToolbarNotificationsPopoverButton.swift b/supacode/Features/Repositories/Views/ToolbarNotificationsPopoverButton.swift
index eda1e4ee..0d64040d 100644
--- a/supacode/Features/Repositories/Views/ToolbarNotificationsPopoverButton.swift
+++ b/supacode/Features/Repositories/Views/ToolbarNotificationsPopoverButton.swift
@@ -21,66 +21,53 @@ struct ToolbarNotificationsPopoverButton: View {
   }
 
   var body: some View {
-    button
-      .buttonStyle(.plain)
-      .glassEffect(.regular.interactive(), in: Capsule())
-      .help("Notifications. Hover or click to show all notifications.")
-      .accessibilityLabel("Notifications")
-      .onHover { hovering in
-        isHoveringButton = hovering
-        updatePresentation()
-      }
-      .popover(isPresented: $isPresented) {
-        ToolbarNotificationsPopoverView(
-          groups: groups,
-          onSelectNotification: { worktreeID, notification in
-            onSelectNotification(worktreeID, notification)
-            closePopover()
-          },
-          onDismissAll: {
-            onDismissAll()
-            closePopover()
-          }
-        )
-        .onHover { hovering in
-          isHoveringPopover = hovering
-          updatePresentation()
-        }
-        .onDisappear {
-          isHoveringPopover = false
-          isPinnedOpen = false
-        }
-      }
-      .onChange(of: groups) { _, newValue in
-        if newValue.isEmpty {
-          closePopover()
-        }
-      }
-      .onDisappear {
-        closeTask?.cancel()
-      }
-  }
-
-  private var button: some View {
     Button {
       togglePresentation()
     } label: {
-      HStack(spacing: LeadingToolbarControlMetrics.labelSpacing) {
+      HStack(spacing: 6) {
         Image(systemName: unseenWorktreeCount > 0 ? "bell.badge.fill" : "bell.fill")
           .foregroundStyle(unseenWorktreeCount > 0 ? .orange : .secondary)
           .accessibilityHidden(true)
-          .frame(
-            width: LeadingToolbarControlMetrics.iconSize,
-            height: LeadingToolbarControlMetrics.iconSize
-          )
         if notificationCount > 0 {
           Text(notificationCount, format: .number)
             .font(.caption.monospacedDigit())
         }
       }
-      .font(LeadingToolbarControlMetrics.font)
-      .padding(.horizontal, LeadingToolbarControlMetrics.standaloneHorizontalPadding)
-      .padding(.vertical, LeadingToolbarControlMetrics.standaloneVerticalPadding)
+    }
+    .help("Notifications. Hover or click to show all notifications.")
+    .accessibilityLabel("Notifications")
+    .onHover { hovering in
+      isHoveringButton = hovering
+      updatePresentation()
+    }
+    .popover(isPresented: $isPresented) {
+      ToolbarNotificationsPopoverView(
+        groups: groups,
+        onSelectNotification: { worktreeID, notification in
+          onSelectNotification(worktreeID, notification)
+          closePopover()
+        },
+        onDismissAll: {
+          onDismissAll()
+          closePopover()
+        }
+      )
+      .onHover { hovering in
+        isHoveringPopover = hovering
+        updatePresentation()
+      }
+      .onDisappear {
+        isHoveringPopover = false
+        isPinnedOpen = false
+      }
+    }
+    .onChange(of: groups) { _, newValue in
+      if newValue.isEmpty {
+        closePopover()
+      }
+    }
+    .onDisappear {
+      closeTask?.cancel()
     }
   }
 
diff --git a/supacode/Features/Repositories/Views/WorktreeDetailToolbarViews.swift b/supacode/Features/Repositories/Views/WorktreeDetailToolbarViews.swift
index 8a4df80c..6a5fd56a 100644
--- a/supacode/Features/Repositories/Views/WorktreeDetailToolbarViews.swift
+++ b/supacode/Features/Repositories/Views/WorktreeDetailToolbarViews.swift
@@ -346,7 +346,11 @@ private struct CanvasToolbarPreview: View {
             onLaunchProfile: { _ in },
             onManageProfiles: {},
             onSelectNotification: { _, _ in },
-            onDismissAllNotifications: {}
+            onDismissAllNotifications: {},
+            isUpdateAvailable: true,
+            isUpdateReadyToInstall: false,
+            availableUpdateVersion: "2026.5.1",
+            onActivateUpdateButton: {}
           )
         }
     }
diff --git a/supacode/Features/Repositories/Views/WorktreeDetailView.swift b/supacode/Features/Repositories/Views/WorktreeDetailView.swift
index 74dfa86a..483478ec 100644
--- a/supacode/Features/Repositories/Views/WorktreeDetailView.swift
+++ b/supacode/Features/Repositories/Views/WorktreeDetailView.swift
@@ -197,7 +197,11 @@ struct WorktreeDetailView: View {
       onSelectNotification: selectToolbarNotification,
       onDismissAllNotifications: {
         dismissAllToolbarNotifications(in: state.notificationGroups)
-      }
+      },
+      isUpdateAvailable: state.isUpdateAvailable,
+      isUpdateReadyToInstall: state.isUpdateReadyToInstall,
+      availableUpdateVersion: state.availableUpdateVersion,
+      onActivateUpdateButton: { store.send(.updates(.activateUpdateButton)) }
     )
 
     ToolbarItem(placement: .principal) {
@@ -209,24 +213,13 @@ struct WorktreeDetailView: View {
       .padding(.horizontal)
     }
 
-    if state.isUpdateAvailable {
-      ToolbarItem(placement: .primaryAction) {
-        ToolbarUpdateButton(
-          availableVersion: state.availableUpdateVersion,
-          isReadyToInstall: state.isUpdateReadyToInstall
-        ) {
-          store.send(.updates(.activateUpdateButton))
-        }
-      }
-    }
-
     let showRunButton =
       state.showRunButtonInToolbar
       && (state.runScriptIsRunning || state.runScriptEnabled)
     let inlineCommands = Array(state.customCommands.enumerated().prefix(3))
     let overflowCommands = Array(state.customCommands.enumerated().dropFirst(3))
-    // A fixed separator keeps the Run + Custom Command cluster distinct from
-    // the trailing update control, mirroring the Normal toolbar.
+    // A fixed separator keeps the dynamic Run + Custom Command cluster distinct
+    // from other trailing actions, mirroring the Normal toolbar spacing.
     //
     // INTENTIONAL DIVERGENCE FROM THE NORMAL TOOLBAR: the whole cluster is a
     // single `ToolbarItem` (an HStack) here, whereas `commandToolbarItems`
@@ -814,8 +807,8 @@ struct WorktreeDetailView: View {
   }
 
   /// Shared leading toolbar cluster for Normal, Shelf, and Canvas. Agents and
-  /// Quick Launch share one native group; the notifications button stays in a
-  /// separate capsule with the same gap the former branch item used.
+  /// Quick Launch share one native group; notifications and update status share
+  /// the trailing group that replaces the former branch item.
   struct AgentNotificationsToolbarContent: ToolbarContent {
     let agentsCapsule: AgentsCapsuleState?
     let agentsLauncherItems: [AgentsLauncherItem]
@@ -826,6 +819,10 @@ struct WorktreeDetailView: View {
     let onManageProfiles: () -> Void
     let onSelectNotification: (Worktree.ID, WorktreeTerminalNotification) -> Void
     let onDismissAllNotifications: () -> Void
+    let isUpdateAvailable: Bool
+    let isUpdateReadyToInstall: Bool
+    let availableUpdateVersion: String?
+    let onActivateUpdateButton: () -> Void
 
     var body: some ToolbarContent {
       ToolbarItemGroup(placement: .navigation) {
@@ -841,13 +838,25 @@ struct WorktreeDetailView: View {
         }
       }
 
+      // Adjacent navigation groups merge on macOS 26. This isolated item owns
+      // the second capsule; see docs-ai 061 before changing its structure.
       ToolbarItem(placement: .navigation) {
-        ToolbarNotificationsPopoverButton(
-          groups: notificationGroups,
-          unseenWorktreeCount: unseenNotificationWorktreeCount,
-          onSelectNotification: onSelectNotification,
-          onDismissAll: onDismissAllNotifications
-        )
+        HStack(spacing: 0) {
+          ToolbarNotificationsPopoverButton(
+            groups: notificationGroups,
+            unseenWorktreeCount: unseenNotificationWorktreeCount,
+            onSelectNotification: onSelectNotification,
+            onDismissAll: onDismissAllNotifications
+          )
+          if isUpdateAvailable {
+            ToolbarUpdateButton(
+              availableVersion: availableUpdateVersion,
+              isReadyToInstall: isUpdateReadyToInstall,
+              onActivate: onActivateUpdateButton
+            )
+          }
+        }
+        .glassEffect(.regular.interactive(), in: Capsule())
       }
       .sharedBackgroundVisibility(.hidden)
     }
@@ -880,7 +889,11 @@ struct WorktreeDetailView: View {
         onLaunchProfile: onLaunchProfile,
         onManageProfiles: onManageProfiles,
         onSelectNotification: onSelectNotification,
-        onDismissAllNotifications: onDismissAllNotifications
+        onDismissAllNotifications: onDismissAllNotifications,
+        isUpdateAvailable: toolbarState.shared.isUpdateAvailable,
+        isUpdateReadyToInstall: toolbarState.shared.isUpdateReadyToInstall,
+        availableUpdateVersion: toolbarState.shared.availableUpdateVersion,
+        onActivateUpdateButton: onActivateUpdateButton
       )
 
       ToolbarItem(placement: .principal) {
@@ -892,16 +905,6 @@ struct WorktreeDetailView: View {
         .padding(.horizontal)
       }
 
-      if toolbarState.shared.isUpdateAvailable {
-        ToolbarItem(placement: .primaryAction) {
-          ToolbarUpdateButton(
-            availableVersion: toolbarState.shared.availableUpdateVersion,
-            isReadyToInstall: toolbarState.shared.isUpdateReadyToInstall,
-            onActivate: onActivateUpdateButton
-          )
-        }
-      }
-
       if toolbarState.showDefaultEditorInToolbar {
         ToolbarSpacer(.fixed)
         ToolbarItemGroup {
@@ -994,8 +997,8 @@ struct WorktreeDetailView: View {
       let overflowEntries = Array(entries.dropFirst(3))
 
       // One fixed separator in front of the whole Run + Custom Command cluster
-      // keeps it distinct from the Open Editor / update controls no matter which
-      // items are hidden. Run and the custom commands share one group (no spacer
+      // keeps it distinct from preceding trailing actions no matter which items
+      // are hidden. Run and the custom commands share one group (no spacer
       // between them), matching the grouping before the toolbar toggles.
       if showRunButton || !inlineEntries.isEmpty || !overflowEntries.isEmpty {
         ToolbarSpacer(.fixed)
-- 
2.51.2