@adhdev/daemon-core 0.9.82-rc.49 → 0.9.82-rc.490

package/src/providers/sdk/v1/schemas/primitives/native-history-codex-rollout-v1.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "adhdev:native-history/codex-rollout@1",
+  "title": "native-history/codex-rollout — v1",
+  "description": "Declares that the provider's chat history is canonically owned by Codex's rollout JSONL files at `~/.codex/sessions/YYYY/MM/DD/rollout-<ts>-<uuid>.jsonl`. The daemon's chat-history layer routes readChat through the configured `scripts.readSession` adapter, which is expected to honour the format contract documented at:\n\n  - One JSONL line per record. First line is `session_meta`; subsequent lines are `response_item` payloads.\n  - Workspace scoping by matching `session_meta.payload.cwd` to the live session's working directory (with symlink expansion via `fs.realpathSync.native`).\n  - spawnAt grace window (default 3000ms): reject workspace-only candidates older than `spawnAt - graceMs`.\n  - excludeInProgressTurn: strip trailing in-flight assistant/tool records when set.\n  - Silent-skip malformed JSONL lines (mirrors codex's concurrent-write tolerance).\n\nThis primitive is currently script-delegated. A daemon-side built-in adapter may replace `_shared/native_history.js` in a later phase; the schema is forward-compatible.",
+  "type": "object",
+  "required": ["$schema", "format", "watchPath", "mode"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "const": "adhdev:native-history/codex-rollout@1" },
+    "format": {
+      "const": "codex-rollout",
+      "description": "Identifies the rollout-jsonl contract version. Sync with `payload.cli_version` interpretation in adapter code."
+    },
+    "watchPath": {
+      "type": "string",
+      "default": "~/.codex/sessions",
+      "description": "Filesystem root the daemon watches for new rollout files. Defaults to the canonical Codex path; override only when the user has a custom CODEX_HOME."
+    },
+    "mode": {
+      "const": "native-source",
+      "description": "Codex JSONL is authoritative for sealed turns; PTY parsing fills the in-flight tail."
+    },
+    "contractVersion": {
+      "type": "string",
+      "default": "1.0",
+      "description": "Adapter contract version; bump in lockstep with breaking changes to Codex's rollout-record schema."
+    },
+    "spawnGraceMs": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 60000,
+      "default": 3000,
+      "description": "Workspace-only candidates with mtime older than `spawnAt - spawnGraceMs` are rejected as stale. Codex's default is 3000ms; only override if you observe a different race window."
+    },
+    "excludeInProgressTurn": {
+      "type": "boolean",
+      "default": true,
+      "description": "When true, trailing assistant/tool records produced mid-turn are stripped so paused approvals don't show as completed."
+    },
+    "scripts": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Pointers to the JS adapter functions (until a daemon-side built-in replaces them).",
+      "properties": {
+        "readSession": { "type": "string", "default": "readCodexNativeHistory" },
+        "listSessions": { "type": "string", "default": "listCodexNativeHistory" }
+      }
+    }
+  },
+  "examples": [
+    {
+      "$schema": "adhdev:native-history/codex-rollout@1",
+      "format": "codex-rollout",
+      "watchPath": "~/.codex/sessions",
+      "mode": "native-source",
+      "contractVersion": "1.0",
+      "spawnGraceMs": 3000,
+      "excludeInProgressTurn": true,
+      "scripts": {
+        "readSession": "readCodexNativeHistory",
+        "listSessions": "listCodexNativeHistory"
+      }
+    }
+  ]
+}

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,125 @@
+{
+  "$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+(.+)$`."
+    },
+    "buttonLabelGroup": {
+      "type": "integer",
+      "minimum": 1,
+      "default": 1,
+      "description": "Capture group number to use as the button label when `buttonPattern` contains non-label groups such as selected-row markers."
+    },
+    "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-session-id-extraction-v1.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "adhdev:tui/session-id-extraction@1",
+  "title": "tui/session-id-extraction — v1",
+  "description": "Declares a regex that captures the provider-issued session UUID off the PTY chrome (e.g. codex footer `gpt-5.5 high · ~/Work/adhdev · 019e8e58-4bd2-7c80-8f5b-b49b6c0e25fa`). The builder runs the regex over the chosen scope's text and exposes the captured group (1) as `providerSessionId` on the parseSession result, so downstream native-history lookup can locate the matching transcript file (`~/.codex/sessions/*-019e8e58-...jsonl`, `~/.claude/projects/*/<uuid>.jsonl`, etc.). Without this primitive a manifest had to ship a scripts/v1 override or fall back to v0 scripts/1.0 just to surface a session id — that's the gap this closes.",
+  "type": "object",
+  "required": ["$schema", "regex"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "const": "adhdev:tui/session-id-extraction@1"
+    },
+    "regex": {
+      "type": "string",
+      "description": "ECMAScript regex source. Capture group 1 must hold the session identifier."
+    },
+    "flags": {
+      "type": "string",
+      "pattern": "^[gimsuy]*$",
+      "default": "i"
+    },
+    "scope": {
+      "default": "tail",
+      "enum": ["screen", "tail", "buffer"],
+      "description": "Which input view to search. `tail` (default) covers the recent buffer where chrome footers usually live; `screen` is just the visible frame; `buffer` is the full scrollback."
+    },
+    "label": {
+      "type": "string",
+      "description": "Optional tag included in debug traces — handy when a manifest declares more than one extraction candidate during authoring."
+    }
+  },
+  "examples": [
+    {
+      "$schema": "adhdev:tui/session-id-extraction@1",
+      "regex": "(?:gpt-|o\\d|codex-)[^·]+·[^·]+·\\s*([0-9a-f-]{36})",
+      "scope": "tail",
+      "label": "codex-footer"
+    },
+    {
+      "$schema": "adhdev:tui/session-id-extraction@1",
+      "regex": "session id:\\s*([0-9a-f-]{36})",
+      "flags": "i",
+      "scope": "buffer"
+    }
+  ]
+}