@adhdev/daemon-core 0.9.82-rc.142 → 0.9.82-rc.144

package/src/providers/sdk/v1/schemas/primitives/tui-approval-squash-v1.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "adhdev:tui/approval-squash@1",
+  "title": "tui/approval-squash — v1",
+  "description": "Recognises approval modals whose buttons + cues have been collapsed by the terminal renderer into a single squashed lowercase-alnum string (e.g. `1yescontinue2noquit`, `doyoutrustthecontentsofthisdirectory`). Codex is the canonical example: when the terminal re-flows the modal across narrow widths, the rendered text loses whitespace/punctuation but the byte order is preserved. The builder applies the manifest's `cues` to detect the modal, then the `buttonRules` to reconstruct labels.\n\nThe normalisation function is fixed: `String(value).toLowerCase().replace(/[^a-z0-9]+/g, '')`. Authors only declare which compact substrings count as cues and how to map known compact button runs back into labels.",
+  "type": "object",
+  "required": ["$schema", "cues", "buttonRules"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "const": "adhdev:tui/approval-squash@1" },
+    "cues": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Compact substrings or regexes that, if found in the compacted text, identify this as an approval modal. Mix freely — daemon tries every cue.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["compact"],
+        "properties": {
+          "compact": { "type": "string", "description": "Compacted (lowercase-alnum) substring." },
+          "kind": { "enum": ["substring", "regex"], "default": "substring" },
+          "label": { "type": "string", "description": "Optional category label, e.g. 'trust-folder'." },
+          "messageWhenMatched": { "type": "string", "description": "Human-readable message the modal builder returns when this cue matches. Use this to recover the original prose from the compacted form." }
+        }
+      }
+    },
+    "footers": {
+      "type": "array",
+      "description": "Optional compact substrings that must also be present in the compacted text to count as a real modal (e.g. 'pressentertocontinue'). Default: at least one cue is sufficient.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["compact"],
+        "properties": {
+          "compact": { "type": "string" },
+          "kind": { "enum": ["substring", "regex"], "default": "substring" }
+        }
+      },
+      "default": []
+    },
+    "buttonRules": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Rules that map a recognised compact substring to the original labels. Tried in order; first match wins. Use this for the cases where the terminal collapsed both buttons into one rendering blob.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["compact", "labels"],
+        "properties": {
+          "compact": { "type": "string", "description": "Compact substring (e.g. '1yescontinue2noquit') OR regex source when kind=regex." },
+          "kind": { "enum": ["substring", "regex"], "default": "substring" },
+          "labels": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "type": "string" },
+            "description": "Original human-readable labels in display order."
+          }
+        }
+      }
+    },
+    "scope": {
+      "default": "tail-window",
+      "enum": ["tail-window", "whole-screen"]
+    },
+    "tailWindowLines": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 64,
+      "default": 24
+    }
+  },
+  "examples": [
+    {
+      "$schema": "adhdev:tui/approval-squash@1",
+      "cues": [
+        { "compact": "doyoutrustthecontentsofthisdirectory", "label": "trust-folder", "messageWhenMatched": "Do you trust the contents of this directory?" },
+        { "compact": "workingwithuntrustedcontents",          "label": "untrusted-content", "messageWhenMatched": "Working with untrusted contents" },
+        { "compact": "switchtogpt",                            "kind": "regex", "label": "rate-limit" }
+      ],
+      "footers": [
+        { "compact": "pressentertocontinue" },
+        { "compact": "esctocancel" }
+      ],
+      "buttonRules": [
+        { "compact": "1yescontinue2noquit",       "labels": ["Yes, continue", "No, quit"] },
+        { "compact": "1approveandrun2deny",       "labels": ["Approve and run", "Deny"] },
+        { "compact": "1alwaysapprove2approve3deny", "labels": ["Always approve", "Approve", "Deny"] }
+      ]
+    }
+  ]
+}

package/src/providers/sdk/v1/schemas/primitives/tui-assistant-block-v1.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "adhdev:tui/assistant-block@1",
+  "title": "tui/assistant-block — v1",
+  "description": "Declares how to extract assistant turns from the rendered transcript. The block starts at a marker (e.g. Claude `⏺`, Codex `Codex` heading) and ends at either the next user prompt or the next block marker. Each captured block becomes one assistant chat message.",
+  "type": "object",
+  "required": ["$schema", "startMarker"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "const": "adhdev:tui/assistant-block@1" },
+    "startMarker": {
+      "description": "Where an assistant block begins. Can be a plain substring or a regex.",
+      "oneOf": [
+        { "type": "string", "description": "Plain substring." },
+        {
+          "type": "object",
+          "required": ["regex"],
+          "additionalProperties": false,
+          "properties": {
+            "regex": { "type": "string" },
+            "flags": { "type": "string", "pattern": "^[gimsuy]*$", "default": "m" }
+          }
+        }
+      ]
+    },
+    "endMarker": {
+      "description": "Where the block ends. Common: next prompt marker or another startMarker. Defaults to \"next-user-prompt\".",
+      "default": "next-user-prompt",
+      "oneOf": [
+        { "const": "next-user-prompt", "title": "Stop at the next prompt marker line" },
+        { "const": "next-start-marker", "title": "Stop at the next startMarker" },
+        { "type": "string", "title": "Plain substring marker" },
+        {
+          "type": "object",
+          "required": ["regex"],
+          "additionalProperties": false,
+          "properties": {
+            "regex": { "type": "string" },
+            "flags": { "type": "string", "pattern": "^[gimsuy]*$", "default": "m" }
+          }
+        }
+      ]
+    },
+    "skipKinds": {
+      "type": "array",
+      "description": "Which sub-blocks to skip when classifying assistant turns. Tool calls and thinking blocks are usually classified separately via tui/tool-block and tui/thinking-block.",
+      "items": { "enum": ["tool", "thinking", "system"] },
+      "default": ["tool"]
+    },
+    "headerLines": {
+      "type": "integer",
+      "minimum": 0,
+      "default": 0,
+      "description": "Number of header lines after the startMarker to skip when extracting content (e.g. Codex's `Codex\\n<timestamp>` header)."
+    },
+    "trimEmptyLeading": {
+      "type": "boolean",
+      "default": true,
+      "description": "Whether to strip leading whitespace-only lines from the captured content."
+    },
+    "trimEmptyTrailing": {
+      "type": "boolean",
+      "default": true
+    },
+    "kind": {
+      "type": "string",
+      "default": "standard",
+      "description": "The CliChatMessage.kind value to stamp on captured blocks."
+    },
+    "minLength": {
+      "type": "integer",
+      "minimum": 1,
+      "default": 1,
+      "description": "Discard blocks whose captured content is shorter than this. Set higher if you have noisy short blocks (e.g. single-character paints)."
+    }
+  },
+  "examples": [
+    {
+      "$schema": "adhdev:tui/assistant-block@1",
+      "startMarker": "⏺",
+      "endMarker": "next-user-prompt",
+      "skipKinds": ["tool", "thinking"]
+    },
+    {
+      "$schema": "adhdev:tui/assistant-block@1",
+      "startMarker": { "regex": "^Codex\\s*$" },
+      "endMarker": "next-start-marker",
+      "headerLines": 1
+    }
+  ]
+}

package/src/providers/sdk/v1/schemas/primitives/tui-cue-ordering-v1.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "adhdev:tui/cue-ordering@1",
+  "title": "TUI cue ordering",
+  "description": "Declares the relative spatial order cues must occur in to be considered evidence of a state. Addresses the canonical 'idle-while-Working-still-visible' regression: spinner cue near bottom + settled prompt cue ABOVE spinner → still generating; spinner ABOVE settled prompt → stale.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["rules"],
+  "properties": {
+    "$schema": { "const": "adhdev:tui/cue-ordering@1" },
+    "rules": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "cues", "verdict"],
+        "properties": {
+          "name": { "type": "string" },
+          "cues": {
+            "type": "array",
+            "minItems": 2,
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["primitive", "position"],
+              "properties": {
+                "primitive": {
+                  "type": "string",
+                  "description": "Reference to another primitive $id (e.g. adhdev:tui/spinner@1)."
+                },
+                "position": {
+                  "enum": ["above", "below", "same-line", "any"],
+                  "description": "Spatial relation to the NEXT cue in this array."
+                }
+              }
+            }
+          },
+          "verdict": {
+            "enum": ["generating", "idle", "approval", "ignore"],
+            "description": "What to return when this ordering matches."
+          }
+        }
+      }
+    }
+  }
+}

package/src/providers/sdk/v1/schemas/primitives/tui-dispatch-order-v1.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "adhdev:tui/dispatch-order@1",
+  "title": "TUI dispatch order",
+  "description": "Declares the order in which detectStatus consults its primitive groups. Default order — spinner → modal → settled-prompt — is what fixed the sprint-2026-06 'idle while Working visible' regression and must be expressible in declarative manifests.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["order"],
+  "properties": {
+    "$schema": { "const": "adhdev:tui/dispatch-order@1" },
+    "order": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "description": "Ordered list of primitive group identifiers. Daemon evaluates them in this order; first matching group decides the verdict.",
+      "items": {
+        "enum": [
+          "spinner",
+          "modal",
+          "settled-prompt",
+          "cue-ordering",
+          "error-detection",
+          "approval-stitching"
+        ]
+      }
+    },
+    "onNoMatch": {
+      "enum": ["idle", "unknown", "preserve-last"],
+      "default": "idle"
+    }
+  }
+}

package/src/providers/sdk/v1/schemas/primitives/tui-footer-chrome-v1.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "adhdev:tui/footer-chrome@1",
+  "title": "TUI footer chrome",
+  "description": "Declares the lines/regions that constitute the persistent CLI footer (input hint, model badge, token counter, etc.). Used to mask the footer out before running prompt-marker / spinner / settled-prompt matchers, so chrome text never gets misclassified as agent state.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["regions"],
+  "properties": {
+    "$schema": { "const": "adhdev:tui/footer-chrome@1" },
+    "regions": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Ordered list of regions; the first match wins. Each region is identified by a sentinel + bounded line span.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["sentinel"],
+        "properties": {
+          "name": { "type": "string" },
+          "sentinel": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["pattern"],
+            "properties": {
+              "pattern": { "type": "string", "description": "Regex source." },
+              "flags": { "type": "string" }
+            }
+          },
+          "spanLinesBefore": { "type": "integer", "minimum": 0, "default": 0 },
+          "spanLinesAfter": { "type": "integer", "minimum": 0, "default": 0 },
+          "anchor": {
+            "enum": ["bottom", "any"],
+            "default": "bottom",
+            "description": "When 'bottom', region must be within the last N lines of the screen."
+          },
+          "bottomLookbackLines": { "type": "integer", "minimum": 1, "default": 12 }
+        }
+      }
+    }
+  }
+}

package/src/providers/sdk/v1/schemas/primitives/tui-index-finder-v1.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "adhdev:tui/index-finder@1",
+  "title": "TUI index finder",
+  "description": "Locates the most-recent occurrence of a cue inside a rendered screen by line index — exposed as a helper primitive used by cue-ordering, settled-prompt, and visible-region. Authors don't reference this primitive directly in manifests; the runtime uses it internally when evaluating spatial relations.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["strategy"],
+  "properties": {
+    "$schema": { "const": "adhdev:tui/index-finder@1" },
+    "strategy": {
+      "enum": ["last-match", "first-match", "tail-window-only"],
+      "default": "last-match"
+    },
+    "tailWindowLines": {
+      "type": "integer",
+      "minimum": 1,
+      "default": 12,
+      "description": "Used when strategy=tail-window-only."
+    },
+    "ignoreInsideRegions": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Primitive $ids whose matched regions should be ignored (e.g. mask out footer-chrome lines before finding the cue)."
+    }
+  }
+}

package/src/providers/sdk/v1/schemas/primitives/tui-modal-v1.json

@@ -0,0 +1,119 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "adhdev:tui/modal@1",
+  "title": "tui/modal — v1",
+  "description": "Declares how to extract an approval modal from the screen. Codex `Do you want to proceed?` + numbered list, Claude approval frame with explicit separators, Antigravity `agy wants to run:` are all expressible. The builder returns null when no modal is visible; daemon then keeps status non-waiting.",
+  "type": "object",
+  "required": ["$schema", "questionPattern", "buttonPattern"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "const": "adhdev:tui/modal@1" },
+    "questionPattern": {
+      "type": "string",
+      "description": "Regex source matching the question line that introduces the modal. Examples: `Do you want to proceed\\?`, `Do you trust the contents of this directory\\?`, `agy wants to run:`."
+    },
+    "questionFlags": {
+      "type": "string",
+      "pattern": "^[gimsuy]*$",
+      "default": "i"
+    },
+    "questionVariants": {
+      "type": "array",
+      "description": "Additional regex sources that count as the same approval kind. Each is tried in order; the first match wins.",
+      "items": {
+        "type": "object",
+        "required": ["regex"],
+        "additionalProperties": false,
+        "properties": {
+          "regex": { "type": "string" },
+          "flags": { "type": "string", "pattern": "^[gimsuy]*$", "default": "i" },
+          "label": { "type": "string", "description": "Optional category label, e.g. \"trust-folder\", \"tool-approval\"." }
+        }
+      },
+      "default": []
+    },
+    "buttonPattern": {
+      "type": "string",
+      "description": "Regex source matching a single button line. Capture group 1 is the button label. Example: `^[\\s❯>]*\\d+\\.\\s+(.+)$`."
+    },
+    "buttonFlags": {
+      "type": "string",
+      "pattern": "^[gimsuy]*$",
+      "default": "m"
+    },
+    "inlineButtonPattern": {
+      "type": "string",
+      "description": "Fallback regex for terminals that render all options on a single line (e.g. Antigravity's `[0] skip [1] yes [2] no [3] still using` survey). Used only when per-line extraction collects fewer than `minButtons`. The `g` flag is forced on by the builder; capture group 1 is the label."
+    },
+    "inlineButtonFlags": {
+      "type": "string",
+      "pattern": "^[gimsuy]*$",
+      "default": "gi"
+    },
+    "scope": {
+      "default": "between-last-two-separators",
+      "description": "Where on the screen the question + buttons must appear together.",
+      "oneOf": [
+        {
+          "const": "between-last-two-separators",
+          "title": "Between last two separators",
+          "description": "Most robust for Claude/Antigravity-style framed modals."
+        },
+        {
+          "const": "window-around-question",
+          "title": "Window around the question line",
+          "description": "Matches when the modal is announced by an explicit question line; collects buttons in the N lines below."
+        },
+        {
+          "const": "whole-screen",
+          "title": "Whole screen",
+          "description": "Use sparingly; tends to false-positive on numbered lists in assistant prose."
+        }
+      ]
+    },
+    "scopeWindowLines": {
+      "type": "integer",
+      "minimum": 2,
+      "maximum": 64,
+      "default": 16,
+      "description": "Lines of context around the question when scope is `window-around-question`."
+    },
+    "contextHeader": {
+      "type": "object",
+      "description": "Optional header line that should be included in the modal message text. Captures the tool name / command being approved.",
+      "additionalProperties": false,
+      "properties": {
+        "regex": { "type": "string" },
+        "flags": { "type": "string", "pattern": "^[gimsuy]*$", "default": "i" }
+      }
+    },
+    "continuationLines": {
+      "type": "boolean",
+      "default": false,
+      "description": "When true, indented lines immediately following a button line are concatenated to the previous label (handles wrapped long options like Antigravity's \"Yes, and always allow ...\")."
+    },
+    "minButtons": {
+      "type": "integer",
+      "minimum": 1,
+      "default": 2,
+      "description": "Minimum buttons required for the modal to be considered valid. Daemon's auto-approve gate also enforces buttons.length > 0."
+    }
+  },
+  "examples": [
+    {
+      "$schema": "adhdev:tui/modal@1",
+      "questionPattern": "Do you want to (?:proceed|allow|run)",
+      "buttonPattern": "^[\\s❯>]*\\d+\\.\\s+(.+)$",
+      "scope": "between-last-two-separators",
+      "minButtons": 2
+    },
+    {
+      "$schema": "adhdev:tui/modal@1",
+      "questionPattern": "agy wants to run:",
+      "buttonPattern": "^\\s*\\d+\\.\\s+(.+)$",
+      "scope": "window-around-question",
+      "continuationLines": true,
+      "contextHeader": { "regex": "agy wants to run:\\s*\\n?(.+)" }
+    }
+  ]
+}

package/src/providers/sdk/v1/schemas/primitives/tui-prompt-marker-v1.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "adhdev:tui/prompt-marker@1",
+  "title": "tui/prompt-marker — v1",
+  "description": "Declares how to recognize the line where the user types prompts. Used by builders to find the last user prompt, slice transcript after it, and detect when the agent is ready for input. Claude `❯`, Codex `>` and `>`, Antigravity `>`, Hermes `>` are all expressible with this primitive.",
+  "type": "object",
+  "required": ["$schema", "regex"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "const": "adhdev:tui/prompt-marker@1"
+    },
+    "regex": {
+      "type": "string",
+      "description": "ECMAScript regex source matching the prompt marker. Common patterns: `^❯\\s`, `^>\\s`, `^[›❯>]\\s*$`."
+    },
+    "flags": {
+      "type": "string",
+      "pattern": "^[gimsuy]*$",
+      "default": "m"
+    },
+    "anchor": {
+      "description": "Where the regex must anchor. `line-start` (default) is the most common; the marker is at column 0. `line-end` is rare. `any` matches anywhere in a line.",
+      "default": "line-start",
+      "enum": ["line-start", "line-end", "any"]
+    },
+    "description": {
+      "type": "string"
+    }
+  },
+  "examples": [
+    {
+      "$schema": "adhdev:tui/prompt-marker@1",
+      "regex": "^❯\\s",
+      "anchor": "line-start",
+      "description": "Claude TUI prompt arrow"
+    },
+    {
+      "$schema": "adhdev:tui/prompt-marker@1",
+      "regex": "^>\\s*$",
+      "anchor": "line-start",
+      "description": "Codex empty prompt"
+    }
+  ]
+}

package/src/providers/sdk/v1/schemas/primitives/tui-settled-prompt-v1.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "adhdev:tui/settled-prompt@1",
+  "title": "tui/settled-prompt — v1",
+  "description": "Declares the screen patterns that indicate the agent is idle and ready for a new prompt. Combined with `tui/spinner` (negated) and `tui/modal` (negated) by the builder to decide `idle`. Codex `❯ <model> · /shortcuts`, Claude `? for shortcuts` + `❯`, Antigravity `>` + `? for shortcuts` are all expressible.",
+  "type": "object",
+  "required": ["$schema", "regex"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "const": "adhdev:tui/settled-prompt@1"
+    },
+    "regex": {
+      "type": "string",
+      "description": "ECMAScript regex source. Matched within the scope window."
+    },
+    "flags": {
+      "type": "string",
+      "pattern": "^[gimsuy]*$",
+      "default": "m"
+    },
+    "withFooter": {
+      "type": "array",
+      "description": "Optional auxiliary substrings or regex sources that must also be present in the scope window for the prompt to count as settled. Use this to disambiguate from mid-stream prompt-like text.",
+      "items": {
+        "type": "object",
+        "required": ["pattern"],
+        "additionalProperties": false,
+        "properties": {
+          "pattern": {
+            "type": "string",
+            "description": "Plain substring (when `kind` is omitted or `substring`) or regex source (when `kind` is `regex`)."
+          },
+          "kind": {
+            "enum": ["substring", "regex"],
+            "default": "substring"
+          },
+          "flags": {
+            "type": "string",
+            "pattern": "^[gimsuy]*$",
+            "default": "i"
+          }
+        }
+      }
+    },
+    "scope": {
+      "default": "last-n-lines",
+      "enum": ["last-n-lines", "whole-screen"]
+    },
+    "scopeWindowLines": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 64,
+      "default": 8
+    }
+  },
+  "examples": [
+    {
+      "$schema": "adhdev:tui/settled-prompt@1",
+      "regex": "^[›❯>]\\s*$",
+      "withFooter": [
+        { "pattern": "? for shortcuts" }
+      ]
+    },
+    {
+      "$schema": "adhdev:tui/settled-prompt@1",
+      "regex": "(?:^|[›❯>]\\s*)\\b(?:gpt-|o\\d\\b|codex-)[\\w._-]*",
+      "scope": "last-n-lines"
+    }
+  ]
+}

package/src/providers/sdk/v1/schemas/primitives/tui-spinner-v1.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "adhdev:tui/spinner@1",
+  "title": "tui/spinner — v1",
+  "description": "Declares which patterns in the PTY/screen text indicate the agent is actively generating. The daemon's status state machine fires `generating` when any pattern matches inside the configured scope window. Codex's `Working (8m 56s • esc to interrupt)`, Claude's braille spinner, and Antigravity's `Thinking…` are all expressible with this primitive.",
+  "type": "object",
+  "required": ["$schema", "patterns"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "const": "adhdev:tui/spinner@1"
+    },
+    "patterns": {
+      "type": "array",
+      "minItems": 1,
+      "description": "List of patterns. Any match within the scope window classifies the screen as generating.",
+      "items": {
+        "type": "object",
+        "required": ["regex"],
+        "additionalProperties": false,
+        "properties": {
+          "regex": {
+            "type": "string",
+            "description": "ECMAScript regex source. Daemon compiles with the flags below."
+          },
+          "flags": {
+            "type": "string",
+            "pattern": "^[gimsuy]*$",
+            "default": "i"
+          },
+          "description": {
+            "type": "string",
+            "description": "Author-facing note explaining when this pattern fires."
+          }
+        }
+      }
+    },
+    "scope": {
+      "description": "Where in the text the patterns are searched. Defaults to `live-frame-tail` which mirrors the safest production behaviour (avoids matching scrollback or earlier turns).",
+      "default": "live-frame-tail",
+      "oneOf": [
+        {
+          "const": "live-frame-tail",
+          "title": "Live frame tail",
+          "description": "Last N lines of the visible screen, where N is `scopeWindowLines` (default 8). Recommended for most providers."
+        },
+        {
+          "const": "whole-screen",
+          "title": "Whole screen",
+          "description": "Match anywhere in the current screen text. Use with caution; tends to false-positive on scrollback."
+        },
+        {
+          "const": "recent-buffer",
+          "title": "Recent buffer",
+          "description": "Last ~1000 chars of accumulated buffer. Useful when the spinner is in raw byte stream but not in the rendered screen yet."
+        }
+      ]
+    },
+    "scopeWindowLines": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 64,
+      "default": 8,
+      "description": "Number of trailing lines considered the live frame when scope is `live-frame-tail`."
+    }
+  },
+  "examples": [
+    {
+      "$schema": "adhdev:tui/spinner@1",
+      "patterns": [
+        { "regex": "(?:Thinking|Working) \\([0-9hms\\s]+", "flags": "i", "description": "Codex/Claude elapsed-time spinner" },
+        { "regex": "esc to (?:cancel|interrupt|stop)", "flags": "i" }
+      ]
+    },
+    {
+      "$schema": "adhdev:tui/spinner@1",
+      "scope": "whole-screen",
+      "patterns": [
+        { "regex": "[⠁-⣿]", "description": "Braille spinner glyphs" }
+      ]
+    }
+  ]
+}