diff --git a/.agents/skills/ln-build/SKILL.md b/.agents/skills/ln-build/SKILL.md
index 40f166d1..df012268 100644
--- a/.agents/skills/ln-build/SKILL.md
+++ b/.agents/skills/ln-build/SKILL.md
@@ -150,12 +150,19 @@ Before finishing reconciliation, perform a quick cross-skill check: if a later a
 
 ### Retire derivative artifacts
 
-After reconciliation, garbage-collect exhausted temporary files instead of leaving breadcrumbs or tombstones:
+After reconciliation, garbage-collect exhausted temporary files instead of leaving breadcrumbs or tombstones, but deletion is narrowly scoped.
 
-- `HANDOFF.md` — keep only if unfinished volatile transfer state still exists; otherwise delete it
-- `memory/CARDS.md` — keep only while queued scope cards still remain; otherwise delete it
-- `memory/REFACTOR.md` — keep only while unfinished refactor steps still depend on it; otherwise delete it
-- Do not create archive copies, numbered handoffs, or completion-pointer files
+Default deletion target:
+
+- `memory/CARDS.md` — delete only when the execution queue is fully exhausted, superseded, or empty after reconciliation.
+
+Other volatile artifacts are **review-before-delete**, not automatic cleanup:
+
+- `HANDOFF.md` — delete only when it contains no unfinished transfer state and no future-context inventory that is not already captured in `memory/SPEC.md`, `memory/PLAN.md`, an active scope card, or a stable design memo.
+- `memory/REFACTOR.md` — delete only when every listed refactor step is done/dropped and no future sequence depends on it.
+- Provisional docs outside `memory/` (for example `docs/**/provisional*.md`, handoff plans, spike plans, or exploration inventories) — do **not** delete during `ln-build` cleanup unless the user explicitly asks or you first prove that all remaining future-facing inventory has been absorbed elsewhere. If only the current card is done but the artifact still contains later affordances, open questions, or scoping input, update it instead of deleting it.
+
+Before deleting anything other than `memory/CARDS.md`, name the file, state why no future agent would need it, and prefer asking the user when uncertain. Do not create archive copies, numbered handoffs, or completion-pointer files.
 
 ## Routing
 
diff --git a/.pi/components/.gitkeep b/.pi/components/.gitkeep
new file mode 100644
index 00000000..e69de29b
diff --git a/.pi/extensions/.gitkeep b/.pi/extensions/.gitkeep
new file mode 100644
index 00000000..e69de29b
diff --git a/@types/oxfmt_configuration_schema.json b/@types/oxfmt_configuration_schema.json
new file mode 100644
index 00000000..ee3ded8a
--- /dev/null
+++ b/@types/oxfmt_configuration_schema.json
@@ -0,0 +1,648 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Oxfmtrc",
+  "description": "Configuration options for the Oxfmt.\n\nMost options are the same as Prettier's options, but not all of them.\nIn addition, some options are our own extensions.",
+  "type": "object",
+  "properties": {
+    "arrowParens": {
+      "description": "Include parentheses around a sole arrow function parameter.\n\n- Default: `\"always\"`",
+      "allOf": [
+        {
+          "$ref": "#/definitions/ArrowParensConfig"
+        }
+      ],
+      "markdownDescription": "Include parentheses around a sole arrow function parameter.\n\n- Default: `\"always\"`"
+    },
+    "bracketSameLine": {
+      "description": "Put the `>` of a multi-line HTML (HTML, JSX, Vue, Angular) element at the end of the last line,\ninstead of being alone on the next line (does not apply to self closing elements).\n\n- Default: `false`",
+      "type": "boolean",
+      "markdownDescription": "Put the `>` of a multi-line HTML (HTML, JSX, Vue, Angular) element at the end of the last line,\ninstead of being alone on the next line (does not apply to self closing elements).\n\n- Default: `false`"
+    },
+    "bracketSpacing": {
+      "description": "Print spaces between brackets in object literals.\n\n- Default: `true`",
+      "type": "boolean",
+      "markdownDescription": "Print spaces between brackets in object literals.\n\n- Default: `true`"
+    },
+    "embeddedLanguageFormatting": {
+      "description": "Control whether to format embedded parts (For example, CSS-in-JS, or JS-in-Vue, etc.) in the file.\n\nNOTE: XXX-in-JS support is incomplete.\n\n- Default: `\"auto\"`",
+      "allOf": [
+        {
+          "$ref": "#/definitions/EmbeddedLanguageFormattingConfig"
+        }
+      ],
+      "markdownDescription": "Control whether to format embedded parts (For example, CSS-in-JS, or JS-in-Vue, etc.) in the file.\n\nNOTE: XXX-in-JS support is incomplete.\n\n- Default: `\"auto\"`"
+    },
+    "endOfLine": {
+      "description": "Which end of line characters to apply.\n\nNOTE: `\"auto\"` is not supported.\n\n- Default: `\"lf\"`\n- Overrides `.editorconfig.end_of_line`",
+      "allOf": [
+        {
+          "$ref": "#/definitions/EndOfLineConfig"
+        }
+      ],
+      "markdownDescription": "Which end of line characters to apply.\n\nNOTE: `\"auto\"` is not supported.\n\n- Default: `\"lf\"`\n- Overrides `.editorconfig.end_of_line`"
+    },
+    "htmlWhitespaceSensitivity": {
+      "description": "Specify the global whitespace sensitivity for HTML, Vue, Angular, and Handlebars.\n\n- Default: `\"css\"`",
+      "allOf": [
+        {
+          "$ref": "#/definitions/HtmlWhitespaceSensitivityConfig"
+        }
+      ],
+      "markdownDescription": "Specify the global whitespace sensitivity for HTML, Vue, Angular, and Handlebars.\n\n- Default: `\"css\"`"
+    },
+    "ignorePatterns": {
+      "description": "Ignore files matching these glob patterns.\nPatterns are based on the location of the Oxfmt configuration file.\n\n- Default: `[]`",
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "markdownDescription": "Ignore files matching these glob patterns.\nPatterns are based on the location of the Oxfmt configuration file.\n\n- Default: `[]`"
+    },
+    "insertFinalNewline": {
+      "description": "Whether to insert a final newline at the end of the file.\n\n- Default: `true`\n- Overrides `.editorconfig.insert_final_newline`",
+      "type": "boolean",
+      "markdownDescription": "Whether to insert a final newline at the end of the file.\n\n- Default: `true`\n- Overrides `.editorconfig.insert_final_newline`"
+    },
+    "jsxSingleQuote": {
+      "description": "Use single quotes instead of double quotes in JSX.\n\n- Default: `false`",
+      "type": "boolean",
+      "markdownDescription": "Use single quotes instead of double quotes in JSX.\n\n- Default: `false`"
+    },
+    "objectWrap": {
+      "description": "How to wrap object literals when they could fit on one line or span multiple lines.\n\nBy default, formats objects as multi-line if there is a newline prior to the first property.\nAuthors can use this heuristic to contextually improve readability, though it has some downsides.\n\n- Default: `\"preserve\"`",
+      "allOf": [
+        {
+          "$ref": "#/definitions/ObjectWrapConfig"
+        }
+      ],
+      "markdownDescription": "How to wrap object literals when they could fit on one line or span multiple lines.\n\nBy default, formats objects as multi-line if there is a newline prior to the first property.\nAuthors can use this heuristic to contextually improve readability, though it has some downsides.\n\n- Default: `\"preserve\"`"
+    },
+    "overrides": {
+      "description": "File-specific overrides.\nWhen a file matches multiple overrides, the later override takes precedence (array order matters).\n\n- Default: `[]`",
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/OxfmtOverrideConfig"
+      },
+      "markdownDescription": "File-specific overrides.\nWhen a file matches multiple overrides, the later override takes precedence (array order matters).\n\n- Default: `[]`"
+    },
+    "printWidth": {
+      "description": "Specify the line length that the printer will wrap on.\n\nIf you don't want line wrapping when formatting Markdown, you can set the `proseWrap` option to disable it.\n\n- Default: `100`\n- Overrides `.editorconfig.max_line_length`",
+      "type": "integer",
+      "format": "uint16",
+      "minimum": 0.0,
+      "markdownDescription": "Specify the line length that the printer will wrap on.\n\nIf you don't want line wrapping when formatting Markdown, you can set the `proseWrap` option to disable it.\n\n- Default: `100`\n- Overrides `.editorconfig.max_line_length`"
+    },
+    "proseWrap": {
+      "description": "How to wrap prose.\n\nBy default, formatter will not change wrapping in markdown text since some services use a linebreak-sensitive renderer, e.g. GitHub comments and BitBucket.\nTo wrap prose to the print width, change this option to \"always\".\nIf you want to force all prose blocks to be on a single line and rely on editor/viewer soft wrapping instead, you can use \"never\".\n\n- Default: `\"preserve\"`",
+      "allOf": [
+        {
+          "$ref": "#/definitions/ProseWrapConfig"
+        }
+      ],
+      "markdownDescription": "How to wrap prose.\n\nBy default, formatter will not change wrapping in markdown text since some services use a linebreak-sensitive renderer, e.g. GitHub comments and BitBucket.\nTo wrap prose to the print width, change this option to \"always\".\nIf you want to force all prose blocks to be on a single line and rely on editor/viewer soft wrapping instead, you can use \"never\".\n\n- Default: `\"preserve\"`"
+    },
+    "quoteProps": {
+      "description": "Change when properties in objects are quoted.\n\n- Default: `\"as-needed\"`",
+      "allOf": [
+        {
+          "$ref": "#/definitions/QuotePropsConfig"
+        }
+      ],
+      "markdownDescription": "Change when properties in objects are quoted.\n\n- Default: `\"as-needed\"`"
+    },
+    "semi": {
+      "description": "Print semicolons at the ends of statements.\n\n- Default: `true`",
+      "type": "boolean",
+      "markdownDescription": "Print semicolons at the ends of statements.\n\n- Default: `true`"
+    },
+    "singleAttributePerLine": {
+      "description": "Enforce single attribute per line in HTML, Vue, and JSX.\n\n- Default: `false`",
+      "type": "boolean",
+      "markdownDescription": "Enforce single attribute per line in HTML, Vue, and JSX.\n\n- Default: `false`"
+    },
+    "singleQuote": {
+      "description": "Use single quotes instead of double quotes.\n\nFor JSX, you can set the `jsxSingleQuote` option.\n\n- Default: `false`",
+      "type": "boolean",
+      "markdownDescription": "Use single quotes instead of double quotes.\n\nFor JSX, you can set the `jsxSingleQuote` option.\n\n- Default: `false`"
+    },
+    "sortImports": {
+      "description": "Sort import statements.\n\nUsing the similar algorithm as [eslint-plugin-perfectionist/sort-imports](https://perfectionist.dev/rules/sort-imports).\nFor details, see each field's documentation.\n\n- Default: Disabled",
+      "allOf": [
+        {
+          "$ref": "#/definitions/SortImportsConfig"
+        }
+      ],
+      "markdownDescription": "Sort import statements.\n\nUsing the similar algorithm as [eslint-plugin-perfectionist/sort-imports](https://perfectionist.dev/rules/sort-imports).\nFor details, see each field's documentation.\n\n- Default: Disabled"
+    },
+    "sortPackageJson": {
+      "description": "Sort `package.json` keys.\n\nThe algorithm is NOT compatible with [prettier-plugin-sort-packagejson](https://github.com/matzkoh/prettier-plugin-packagejson).\nBut we believe it is clearer and easier to navigate.\nFor details, see each field's documentation.\n\n- Default: `true`",
+      "allOf": [
+        {
+          "$ref": "#/definitions/SortPackageJsonUserConfig"
+        }
+      ],
+      "markdownDescription": "Sort `package.json` keys.\n\nThe algorithm is NOT compatible with [prettier-plugin-sort-packagejson](https://github.com/matzkoh/prettier-plugin-packagejson).\nBut we believe it is clearer and easier to navigate.\nFor details, see each field's documentation.\n\n- Default: `true`"
+    },
+    "sortTailwindcss": {
+      "description": "Sort Tailwind CSS classes.\n\nUsing the same algorithm as [prettier-plugin-tailwindcss](https://github.com/tailwindlabs/prettier-plugin-tailwindcss).\nOption names omit the `tailwind` prefix used in the original plugin (e.g., `config` instead of `tailwindConfig`).\nFor details, see each field's documentation.\n\n- Default: Disabled",
+      "allOf": [
+        {
+          "$ref": "#/definitions/SortTailwindcssConfig"
+        }
+      ],
+      "markdownDescription": "Sort Tailwind CSS classes.\n\nUsing the same algorithm as [prettier-plugin-tailwindcss](https://github.com/tailwindlabs/prettier-plugin-tailwindcss).\nOption names omit the `tailwind` prefix used in the original plugin (e.g., `config` instead of `tailwindConfig`).\nFor details, see each field's documentation.\n\n- Default: Disabled"
+    },
+    "tabWidth": {
+      "description": "Specify the number of spaces per indentation-level.\n\n- Default: `2`\n- Overrides `.editorconfig.indent_size`",
+      "type": "integer",
+      "format": "uint8",
+      "minimum": 0.0,
+      "markdownDescription": "Specify the number of spaces per indentation-level.\n\n- Default: `2`\n- Overrides `.editorconfig.indent_size`"
+    },
+    "trailingComma": {
+      "description": "Print trailing commas wherever possible in multi-line comma-separated syntactic structures.\n\nA single-line array, for example, never gets trailing commas.\n\n- Default: `\"all\"`",
+      "allOf": [
+        {
+          "$ref": "#/definitions/TrailingCommaConfig"
+        }
+      ],
+      "markdownDescription": "Print trailing commas wherever possible in multi-line comma-separated syntactic structures.\n\nA single-line array, for example, never gets trailing commas.\n\n- Default: `\"all\"`"
+    },
+    "useTabs": {
+      "description": "Indent lines with tabs instead of spaces.\n\n- Default: `false`\n- Overrides `.editorconfig.indent_style`",
+      "type": "boolean",
+      "markdownDescription": "Indent lines with tabs instead of spaces.\n\n- Default: `false`\n- Overrides `.editorconfig.indent_style`"
+    },
+    "vueIndentScriptAndStyle": {
+      "description": "Whether or not to indent the code inside `<script>` and `<style>` tags in Vue files.\n\n- Default: `false`",
+      "type": "boolean",
+      "markdownDescription": "Whether or not to indent the code inside `<script>` and `<style>` tags in Vue files.\n\n- Default: `false`"
+    }
+  },
+  "allowComments": true,
+  "allowTrailingCommas": true,
+  "definitions": {
+    "ArrowParensConfig": {
+      "type": "string",
+      "enum": [
+        "always",
+        "avoid"
+      ]
+    },
+    "CustomGroupItemConfig": {
+      "type": "object",
+      "properties": {
+        "elementNamePattern": {
+          "description": "List of glob patterns to match import sources for this group.",
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "markdownDescription": "List of glob patterns to match import sources for this group."
+        },
+        "groupName": {
+          "description": "Name of the custom group, used in the `groups` option.",
+          "default": "",
+          "type": "string",
+          "markdownDescription": "Name of the custom group, used in the `groups` option."
+        },
+        "modifiers": {
+          "description": "Modifiers to match the import characteristics.\nAll specified modifiers must be present (AND logic).\n\nPossible values: `\"side_effect\"`, `\"type\"`, `\"value\"`, `\"default\"`, `\"wildcard\"`, `\"named\"`",
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "markdownDescription": "Modifiers to match the import characteristics.\nAll specified modifiers must be present (AND logic).\n\nPossible values: `\"side_effect\"`, `\"type\"`, `\"value\"`, `\"default\"`, `\"wildcard\"`, `\"named\"`"
+        },
+        "selector": {
+          "description": "Selector to match the import kind.\n\nPossible values: `\"type\"`, `\"side_effect_style\"`, `\"side_effect\"`, `\"style\"`, `\"index\"`,\n`\"sibling\"`, `\"parent\"`, `\"subpath\"`, `\"internal\"`, `\"builtin\"`, `\"external\"`, `\"import\"`",
+          "type": "string",
+          "markdownDescription": "Selector to match the import kind.\n\nPossible values: `\"type\"`, `\"side_effect_style\"`, `\"side_effect\"`, `\"style\"`, `\"index\"`,\n`\"sibling\"`, `\"parent\"`, `\"subpath\"`, `\"internal\"`, `\"builtin\"`, `\"external\"`, `\"import\"`"
+        }
+      }
+    },
+    "EmbeddedLanguageFormattingConfig": {
+      "type": "string",
+      "enum": [
+        "auto",
+        "off"
+      ]
+    },
+    "EndOfLineConfig": {
+      "type": "string",
+      "enum": [
+        "lf",
+        "crlf",
+        "cr"
+      ]
+    },
+    "FormatConfig": {
+      "type": "object",
+      "properties": {
+        "arrowParens": {
+          "description": "Include parentheses around a sole arrow function parameter.\n\n- Default: `\"always\"`",
+          "allOf": [
+            {
+              "$ref": "#/definitions/ArrowParensConfig"
+            }
+          ],
+          "markdownDescription": "Include parentheses around a sole arrow function parameter.\n\n- Default: `\"always\"`"
+        },
+        "bracketSameLine": {
+          "description": "Put the `>` of a multi-line HTML (HTML, JSX, Vue, Angular) element at the end of the last line,\ninstead of being alone on the next line (does not apply to self closing elements).\n\n- Default: `false`",
+          "type": "boolean",
+          "markdownDescription": "Put the `>` of a multi-line HTML (HTML, JSX, Vue, Angular) element at the end of the last line,\ninstead of being alone on the next line (does not apply to self closing elements).\n\n- Default: `false`"
+        },
+        "bracketSpacing": {
+          "description": "Print spaces between brackets in object literals.\n\n- Default: `true`",
+          "type": "boolean",
+          "markdownDescription": "Print spaces between brackets in object literals.\n\n- Default: `true`"
+        },
+        "embeddedLanguageFormatting": {
+          "description": "Control whether to format embedded parts (For example, CSS-in-JS, or JS-in-Vue, etc.) in the file.\n\nNOTE: XXX-in-JS support is incomplete.\n\n- Default: `\"auto\"`",
+          "allOf": [
+            {
+              "$ref": "#/definitions/EmbeddedLanguageFormattingConfig"
+            }
+          ],
+          "markdownDescription": "Control whether to format embedded parts (For example, CSS-in-JS, or JS-in-Vue, etc.) in the file.\n\nNOTE: XXX-in-JS support is incomplete.\n\n- Default: `\"auto\"`"
+        },
+        "endOfLine": {
+          "description": "Which end of line characters to apply.\n\nNOTE: `\"auto\"` is not supported.\n\n- Default: `\"lf\"`\n- Overrides `.editorconfig.end_of_line`",
+          "allOf": [
+            {
+              "$ref": "#/definitions/EndOfLineConfig"
+            }
+          ],
+          "markdownDescription": "Which end of line characters to apply.\n\nNOTE: `\"auto\"` is not supported.\n\n- Default: `\"lf\"`\n- Overrides `.editorconfig.end_of_line`"
+        },
+        "htmlWhitespaceSensitivity": {
+          "description": "Specify the global whitespace sensitivity for HTML, Vue, Angular, and Handlebars.\n\n- Default: `\"css\"`",
+          "allOf": [
+            {
+              "$ref": "#/definitions/HtmlWhitespaceSensitivityConfig"
+            }
+          ],
+          "markdownDescription": "Specify the global whitespace sensitivity for HTML, Vue, Angular, and Handlebars.\n\n- Default: `\"css\"`"
+        },
+        "insertFinalNewline": {
+          "description": "Whether to insert a final newline at the end of the file.\n\n- Default: `true`\n- Overrides `.editorconfig.insert_final_newline`",
+          "type": "boolean",
+          "markdownDescription": "Whether to insert a final newline at the end of the file.\n\n- Default: `true`\n- Overrides `.editorconfig.insert_final_newline`"
+        },
+        "jsxSingleQuote": {
+          "description": "Use single quotes instead of double quotes in JSX.\n\n- Default: `false`",
+          "type": "boolean",
+          "markdownDescription": "Use single quotes instead of double quotes in JSX.\n\n- Default: `false`"
+        },
+        "objectWrap": {
+          "description": "How to wrap object literals when they could fit on one line or span multiple lines.\n\nBy default, formats objects as multi-line if there is a newline prior to the first property.\nAuthors can use this heuristic to contextually improve readability, though it has some downsides.\n\n- Default: `\"preserve\"`",
+          "allOf": [
+            {
+              "$ref": "#/definitions/ObjectWrapConfig"
+            }
+          ],
+          "markdownDescription": "How to wrap object literals when they could fit on one line or span multiple lines.\n\nBy default, formats objects as multi-line if there is a newline prior to the first property.\nAuthors can use this heuristic to contextually improve readability, though it has some downsides.\n\n- Default: `\"preserve\"`"
+        },
+        "printWidth": {
+          "description": "Specify the line length that the printer will wrap on.\n\nIf you don't want line wrapping when formatting Markdown, you can set the `proseWrap` option to disable it.\n\n- Default: `100`\n- Overrides `.editorconfig.max_line_length`",
+          "type": "integer",
+          "format": "uint16",
+          "minimum": 0.0,
+          "markdownDescription": "Specify the line length that the printer will wrap on.\n\nIf you don't want line wrapping when formatting Markdown, you can set the `proseWrap` option to disable it.\n\n- Default: `100`\n- Overrides `.editorconfig.max_line_length`"
+        },
+        "proseWrap": {
+          "description": "How to wrap prose.\n\nBy default, formatter will not change wrapping in markdown text since some services use a linebreak-sensitive renderer, e.g. GitHub comments and BitBucket.\nTo wrap prose to the print width, change this option to \"always\".\nIf you want to force all prose blocks to be on a single line and rely on editor/viewer soft wrapping instead, you can use \"never\".\n\n- Default: `\"preserve\"`",
+          "allOf": [
+            {
+              "$ref": "#/definitions/ProseWrapConfig"
+            }
+          ],
+          "markdownDescription": "How to wrap prose.\n\nBy default, formatter will not change wrapping in markdown text since some services use a linebreak-sensitive renderer, e.g. GitHub comments and BitBucket.\nTo wrap prose to the print width, change this option to \"always\".\nIf you want to force all prose blocks to be on a single line and rely on editor/viewer soft wrapping instead, you can use \"never\".\n\n- Default: `\"preserve\"`"
+        },
+        "quoteProps": {
+          "description": "Change when properties in objects are quoted.\n\n- Default: `\"as-needed\"`",
+          "allOf": [
+            {
+              "$ref": "#/definitions/QuotePropsConfig"
+            }
+          ],
+          "markdownDescription": "Change when properties in objects are quoted.\n\n- Default: `\"as-needed\"`"
+        },
+        "semi": {
+          "description": "Print semicolons at the ends of statements.\n\n- Default: `true`",
+          "type": "boolean",
+          "markdownDescription": "Print semicolons at the ends of statements.\n\n- Default: `true`"
+        },
+        "singleAttributePerLine": {
+          "description": "Enforce single attribute per line in HTML, Vue, and JSX.\n\n- Default: `false`",
+          "type": "boolean",
+          "markdownDescription": "Enforce single attribute per line in HTML, Vue, and JSX.\n\n- Default: `false`"
+        },
+        "singleQuote": {
+          "description": "Use single quotes instead of double quotes.\n\nFor JSX, you can set the `jsxSingleQuote` option.\n\n- Default: `false`",
+          "type": "boolean",
+          "markdownDescription": "Use single quotes instead of double quotes.\n\nFor JSX, you can set the `jsxSingleQuote` option.\n\n- Default: `false`"
+        },
+        "sortImports": {
+          "description": "Sort import statements.\n\nUsing the similar algorithm as [eslint-plugin-perfectionist/sort-imports](https://perfectionist.dev/rules/sort-imports).\nFor details, see each field's documentation.\n\n- Default: Disabled",
+          "allOf": [
+            {
+              "$ref": "#/definitions/SortImportsConfig"
+            }
+          ],
+          "markdownDescription": "Sort import statements.\n\nUsing the similar algorithm as [eslint-plugin-perfectionist/sort-imports](https://perfectionist.dev/rules/sort-imports).\nFor details, see each field's documentation.\n\n- Default: Disabled"
+        },
+        "sortPackageJson": {
+          "description": "Sort `package.json` keys.\n\nThe algorithm is NOT compatible with [prettier-plugin-sort-packagejson](https://github.com/matzkoh/prettier-plugin-packagejson).\nBut we believe it is clearer and easier to navigate.\nFor details, see each field's documentation.\n\n- Default: `true`",
+          "allOf": [
+            {
+              "$ref": "#/definitions/SortPackageJsonUserConfig"
+            }
+          ],
+          "markdownDescription": "Sort `package.json` keys.\n\nThe algorithm is NOT compatible with [prettier-plugin-sort-packagejson](https://github.com/matzkoh/prettier-plugin-packagejson).\nBut we believe it is clearer and easier to navigate.\nFor details, see each field's documentation.\n\n- Default: `true`"
+        },
+        "sortTailwindcss": {
+          "description": "Sort Tailwind CSS classes.\n\nUsing the same algorithm as [prettier-plugin-tailwindcss](https://github.com/tailwindlabs/prettier-plugin-tailwindcss).\nOption names omit the `tailwind` prefix used in the original plugin (e.g., `config` instead of `tailwindConfig`).\nFor details, see each field's documentation.\n\n- Default: Disabled",
+          "allOf": [
+            {
+              "$ref": "#/definitions/SortTailwindcssConfig"
+            }
+          ],
+          "markdownDescription": "Sort Tailwind CSS classes.\n\nUsing the same algorithm as [prettier-plugin-tailwindcss](https://github.com/tailwindlabs/prettier-plugin-tailwindcss).\nOption names omit the `tailwind` prefix used in the original plugin (e.g., `config` instead of `tailwindConfig`).\nFor details, see each field's documentation.\n\n- Default: Disabled"
+        },
+        "tabWidth": {
+          "description": "Specify the number of spaces per indentation-level.\n\n- Default: `2`\n- Overrides `.editorconfig.indent_size`",
+          "type": "integer",
+          "format": "uint8",
+          "minimum": 0.0,
+          "markdownDescription": "Specify the number of spaces per indentation-level.\n\n- Default: `2`\n- Overrides `.editorconfig.indent_size`"
+        },
+        "trailingComma": {
+          "description": "Print trailing commas wherever possible in multi-line comma-separated syntactic structures.\n\nA single-line array, for example, never gets trailing commas.\n\n- Default: `\"all\"`",
+          "allOf": [
+            {
+              "$ref": "#/definitions/TrailingCommaConfig"
+            }
+          ],
+          "markdownDescription": "Print trailing commas wherever possible in multi-line comma-separated syntactic structures.\n\nA single-line array, for example, never gets trailing commas.\n\n- Default: `\"all\"`"
+        },
+        "useTabs": {
+          "description": "Indent lines with tabs instead of spaces.\n\n- Default: `false`\n- Overrides `.editorconfig.indent_style`",
+          "type": "boolean",
+          "markdownDescription": "Indent lines with tabs instead of spaces.\n\n- Default: `false`\n- Overrides `.editorconfig.indent_style`"
+        },
+        "vueIndentScriptAndStyle": {
+          "description": "Whether or not to indent the code inside `<script>` and `<style>` tags in Vue files.\n\n- Default: `false`",
+          "type": "boolean",
+          "markdownDescription": "Whether or not to indent the code inside `<script>` and `<style>` tags in Vue files.\n\n- Default: `false`"
+        }
+      }
+    },
+    "HtmlWhitespaceSensitivityConfig": {
+      "type": "string",
+      "enum": [
+        "css",
+        "strict",
+        "ignore"
+      ]
+    },
+    "NewlinesBetweenMarker": {
+      "description": "A marker object for overriding `newlinesBetween` at a specific group boundary.",
+      "type": "object",
+      "required": [
+        "newlinesBetween"
+      ],
+      "properties": {
+        "newlinesBetween": {
+          "type": "boolean"
+        }
+      },
+      "markdownDescription": "A marker object for overriding `newlinesBetween` at a specific group boundary."
+    },
+    "ObjectWrapConfig": {
+      "type": "string",
+      "enum": [
+        "preserve",
+        "collapse"
+      ]
+    },
+    "OxfmtOverrideConfig": {
+      "type": "object",
+      "required": [
+        "files"
+      ],
+      "properties": {
+        "excludeFiles": {
+          "description": "Glob patterns to exclude from this override.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "markdownDescription": "Glob patterns to exclude from this override."
+        },
+        "files": {
+          "description": "Glob patterns to match files for this override.\nAll patterns are relative to the Oxfmt configuration file.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "markdownDescription": "Glob patterns to match files for this override.\nAll patterns are relative to the Oxfmt configuration file."
+        },
+        "options": {
+          "description": "Format options to apply for matched files.",
+          "default": {},
+          "allOf": [
+            {
+              "$ref": "#/definitions/FormatConfig"
+            }
+          ],
+          "markdownDescription": "Format options to apply for matched files."
+        }
+      }
+    },
+    "ProseWrapConfig": {
+      "type": "string",
+      "enum": [
+        "always",
+        "never",
+        "preserve"
+      ]
+    },
+    "QuotePropsConfig": {
+      "type": "string",
+      "enum": [
+        "as-needed",
+        "consistent",
+        "preserve"
+      ]
+    },
+    "SortGroupItemConfig": {
+      "anyOf": [
+        {
+          "description": "A `{ \"newlinesBetween\": bool }` marker object that overrides the global `newlinesBetween`\nsetting for the boundary between the previous and next groups.",
+          "allOf": [
+            {
+              "$ref": "#/definitions/NewlinesBetweenMarker"
+            }
+          ],
+          "markdownDescription": "A `{ \"newlinesBetween\": bool }` marker object that overrides the global `newlinesBetween`\nsetting for the boundary between the previous and next groups."
+        },
+        {
+          "description": "A single group name string (e.g. `\"value-builtin\"`).",
+          "type": "string",
+          "markdownDescription": "A single group name string (e.g. `\"value-builtin\"`)."
+        },
+        {
+          "description": "Multiple group names treated as one group (e.g. `[\"value-builtin\", \"value-external\"]`).",
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "markdownDescription": "Multiple group names treated as one group (e.g. `[\"value-builtin\", \"value-external\"]`)."
+        }
+      ]
+    },
+    "SortImportsConfig": {
+      "type": "object",
+      "properties": {
+        "customGroups": {
+          "description": "Define your own groups for matching very specific imports.\n\nThe `customGroups` list is ordered: The first definition that matches an element will be used.\nCustom groups have a higher priority than any predefined group.\n\nIf you want a predefined group to take precedence over a custom group,\nyou must write a custom group definition that does the same as what the predefined group does, and put it first in the list.\n\nIf you specify multiple conditions like `elementNamePattern`, `selector`, and `modifiers`,\nall conditions must be met for an import to match the custom group (AND logic).\n\n- Default: `[]`",
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/CustomGroupItemConfig"
+          },
+          "markdownDescription": "Define your own groups for matching very specific imports.\n\nThe `customGroups` list is ordered: The first definition that matches an element will be used.\nCustom groups have a higher priority than any predefined group.\n\nIf you want a predefined group to take precedence over a custom group,\nyou must write a custom group definition that does the same as what the predefined group does, and put it first in the list.\n\nIf you specify multiple conditions like `elementNamePattern`, `selector`, and `modifiers`,\nall conditions must be met for an import to match the custom group (AND logic).\n\n- Default: `[]`"
+        },
+        "groups": {
+          "description": "Specifies a list of predefined import groups for sorting.\n\nEach import will be assigned a single group specified in the groups option (or the `unknown` group if no match is found).\nThe order of items in the `groups` option determines how groups are ordered.\n\nWithin a given group, members will be sorted according to the type, order, ignoreCase, etc. options.\n\nIndividual groups can be combined together by placing them in an array.\nThe order of groups in that array does not matter.\nAll members of the groups in the array will be sorted together as if they were part of a single group.\n\nPredefined groups are characterized by a single selector and potentially multiple modifiers.\nYou may enter modifiers in any order, but the selector must always come at the end.\n\nThe list of selectors is sorted from most to least important:\n- `type` — TypeScript type imports.\n- `side_effect_style` — Side effect style imports.\n- `side_effect` — Side effect imports.\n- `style` — Style imports.\n- `index` — Main file from the current directory.\n- `sibling` — Modules from the same directory.\n- `parent` — Modules from the parent directory.\n- `subpath` — Node.js subpath imports.\n- `internal` — Your internal modules.\n- `builtin` — Node.js Built-in Modules.\n- `external` — External modules installed in the project.\n- `import` — Any import.\n\nThe list of modifiers is sorted from most to least important:\n- `side_effect` — Side effect imports.\n- `type` — TypeScript type imports.\n- `value` — Value imports.\n- `default` — Imports containing the default specifier.\n- `wildcard` — Imports containing the wildcard (`* as`) specifier.\n- `named` — Imports containing at least one named specifier.\n\n- Default: See below\n```json\n[\n\"builtin\",\n\"external\",\n[\"internal\", \"subpath\"],\n[\"parent\", \"sibling\", \"index\"],\n\"style\",\n\"unknown\"\n]\n```\n\nAlso, you can override the global `newlinesBetween` setting for specific group boundaries\nby including a `{ \"newlinesBetween\": boolean }` marker object in the `groups` list at the desired position.",
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/SortGroupItemConfig"
+          },
+          "markdownDescription": "Specifies a list of predefined import groups for sorting.\n\nEach import will be assigned a single group specified in the groups option (or the `unknown` group if no match is found).\nThe order of items in the `groups` option determines how groups are ordered.\n\nWithin a given group, members will be sorted according to the type, order, ignoreCase, etc. options.\n\nIndividual groups can be combined together by placing them in an array.\nThe order of groups in that array does not matter.\nAll members of the groups in the array will be sorted together as if they were part of a single group.\n\nPredefined groups are characterized by a single selector and potentially multiple modifiers.\nYou may enter modifiers in any order, but the selector must always come at the end.\n\nThe list of selectors is sorted from most to least important:\n- `type` — TypeScript type imports.\n- `side_effect_style` — Side effect style imports.\n- `side_effect` — Side effect imports.\n- `style` — Style imports.\n- `index` — Main file from the current directory.\n- `sibling` — Modules from the same directory.\n- `parent` — Modules from the parent directory.\n- `subpath` — Node.js subpath imports.\n- `internal` — Your internal modules.\n- `builtin` — Node.js Built-in Modules.\n- `external` — External modules installed in the project.\n- `import` — Any import.\n\nThe list of modifiers is sorted from most to least important:\n- `side_effect` — Side effect imports.\n- `type` — TypeScript type imports.\n- `value` — Value imports.\n- `default` — Imports containing the default specifier.\n- `wildcard` — Imports containing the wildcard (`* as`) specifier.\n- `named` — Imports containing at least one named specifier.\n\n- Default: See below\n```json\n[\n\"builtin\",\n\"external\",\n[\"internal\", \"subpath\"],\n[\"parent\", \"sibling\", \"index\"],\n\"style\",\n\"unknown\"\n]\n```\n\nAlso, you can override the global `newlinesBetween` setting for specific group boundaries\nby including a `{ \"newlinesBetween\": boolean }` marker object in the `groups` list at the desired position."
+        },
+        "ignoreCase": {
+          "description": "Specifies whether sorting should be case-sensitive.\n\n- Default: `true`",
+          "type": "boolean",
+          "markdownDescription": "Specifies whether sorting should be case-sensitive.\n\n- Default: `true`"
+        },
+        "internalPattern": {
+          "description": "Specifies a prefix for identifying internal imports.\n\nThis is useful for distinguishing your own modules from external dependencies.\n\n- Default: `[\"~/\", \"@/\"]`",
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "markdownDescription": "Specifies a prefix for identifying internal imports.\n\nThis is useful for distinguishing your own modules from external dependencies.\n\n- Default: `[\"~/\", \"@/\"]`"
+        },
+        "newlinesBetween": {
+          "description": "Specifies whether to add newlines between groups.\n\nWhen `false`, no newlines are added between groups.\n\n- Default: `true`",
+          "type": "boolean",
+          "markdownDescription": "Specifies whether to add newlines between groups.\n\nWhen `false`, no newlines are added between groups.\n\n- Default: `true`"
+        },
+        "order": {
+          "description": "Specifies whether to sort items in ascending or descending order.\n\n- Default: `\"asc\"`",
+          "allOf": [
+            {
+              "$ref": "#/definitions/SortOrderConfig"
+            }
+          ],
+          "markdownDescription": "Specifies whether to sort items in ascending or descending order.\n\n- Default: `\"asc\"`"
+        },
+        "partitionByComment": {
+          "description": "Enables the use of comments to separate imports into logical groups.\n\nWhen `true`, all comments will be treated as delimiters, creating partitions.\n\n```js\nimport { b1, b2 } from 'b'\n// PARTITION\nimport { a } from 'a'\nimport { c } from 'c'\n```\n\n- Default: `false`",
+          "type": "boolean",
+          "markdownDescription": "Enables the use of comments to separate imports into logical groups.\n\nWhen `true`, all comments will be treated as delimiters, creating partitions.\n\n```js\nimport { b1, b2 } from 'b'\n// PARTITION\nimport { a } from 'a'\nimport { c } from 'c'\n```\n\n- Default: `false`"
+        },
+        "partitionByNewline": {
+          "description": "Enables the empty line to separate imports into logical groups.\n\nWhen `true`, formatter will not sort imports if there is an empty line between them.\nThis helps maintain the defined order of logically separated groups of members.\n\n```js\nimport { b1, b2 } from 'b'\n\nimport { a } from 'a'\nimport { c } from 'c'\n```\n\n- Default: `false`",
+          "type": "boolean",
+          "markdownDescription": "Enables the empty line to separate imports into logical groups.\n\nWhen `true`, formatter will not sort imports if there is an empty line between them.\nThis helps maintain the defined order of logically separated groups of members.\n\n```js\nimport { b1, b2 } from 'b'\n\nimport { a } from 'a'\nimport { c } from 'c'\n```\n\n- Default: `false`"
+        },
+        "sortSideEffects": {
+          "description": "Specifies whether side effect imports should be sorted.\n\nBy default, sorting side-effect imports is disabled for security reasons.\n\n- Default: `false`",
+          "type": "boolean",
+          "markdownDescription": "Specifies whether side effect imports should be sorted.\n\nBy default, sorting side-effect imports is disabled for security reasons.\n\n- Default: `false`"
+        }
+      }
+    },
+    "SortOrderConfig": {
+      "type": "string",
+      "enum": [
+        "asc",
+        "desc"
+      ]
+    },
+    "SortPackageJsonConfig": {
+      "type": "object",
+      "properties": {
+        "sortScripts": {
+          "description": "Sort the `scripts` field alphabetically.\n\n- Default: `false`",
+          "type": "boolean",
+          "markdownDescription": "Sort the `scripts` field alphabetically.\n\n- Default: `false`"
+        }
+      }
+    },
+    "SortPackageJsonUserConfig": {
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "$ref": "#/definitions/SortPackageJsonConfig"
+        }
+      ]
+    },
+    "SortTailwindcssConfig": {
+      "type": "object",
+      "properties": {
+        "attributes": {
+          "description": "List of additional attributes to sort beyond `class` and `className` (exact match).\n\nNOTE: Regex patterns are not yet supported.\n\n- Default: `[]`\n- Example: `[\"myClassProp\", \":class\"]`",
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "markdownDescription": "List of additional attributes to sort beyond `class` and `className` (exact match).\n\nNOTE: Regex patterns are not yet supported.\n\n- Default: `[]`\n- Example: `[\"myClassProp\", \":class\"]`"
+        },
+        "config": {
+          "description": "Path to your Tailwind CSS configuration file (v3).\n\nNOTE: Paths are resolved relative to the Oxfmt configuration file.\n\n- Default: Automatically find `\"tailwind.config.js\"`",
+          "type": "string",
+          "markdownDescription": "Path to your Tailwind CSS configuration file (v3).\n\nNOTE: Paths are resolved relative to the Oxfmt configuration file.\n\n- Default: Automatically find `\"tailwind.config.js\"`"
+        },
+        "functions": {
+          "description": "List of custom function names whose arguments should be sorted (exact match).\n\nNOTE: Regex patterns are not yet supported.\n\n- Default: `[]`\n- Example: `[\"clsx\", \"cn\", \"cva\", \"tw\"]`",
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "markdownDescription": "List of custom function names whose arguments should be sorted (exact match).\n\nNOTE: Regex patterns are not yet supported.\n\n- Default: `[]`\n- Example: `[\"clsx\", \"cn\", \"cva\", \"tw\"]`"
+        },
+        "preserveDuplicates": {
+          "description": "Preserve duplicate classes.\n\n- Default: `false`",
+          "type": "boolean",
+          "markdownDescription": "Preserve duplicate classes.\n\n- Default: `false`"
+        },
+        "preserveWhitespace": {
+          "description": "Preserve whitespace around classes.\n\n- Default: `false`",
+          "type": "boolean",
+          "markdownDescription": "Preserve whitespace around classes.\n\n- Default: `false`"
+        },
+        "stylesheet": {
+          "description": "Path to your Tailwind CSS stylesheet (v4).\n\nNOTE: Paths are resolved relative to the Oxfmt configuration file.\n\n- Default: Installed Tailwind CSS's `theme.css`",
+          "type": "string",
+          "markdownDescription": "Path to your Tailwind CSS stylesheet (v4).\n\nNOTE: Paths are resolved relative to the Oxfmt configuration file.\n\n- Default: Installed Tailwind CSS's `theme.css`"
+        }
+      }
+    },
+    "TrailingCommaConfig": {
+      "type": "string",
+      "enum": [
+        "all",
+        "es5",
+        "none"
+      ]
+    }
+  },
+  "markdownDescription": "Configuration options for the Oxfmt.\n\nMost options are the same as Prettier's options, but not all of them.\nIn addition, some options are our own extensions."
+}
diff --git a/@types/oxlint_configuration_schema.json b/@types/oxlint_configuration_schema.json
new file mode 100644
index 00000000..f5c144f7
--- /dev/null
+++ b/@types/oxlint_configuration_schema.json
@@ -0,0 +1,554 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Oxlintrc",
+  "description": "Oxlint Configuration File\n\nThis configuration is aligned with ESLint v8's configuration schema (`eslintrc.json`).\n\nUsage: `oxlint -c oxlintrc.json --import-plugin`\n\n::: danger NOTE\n\nOnly the `.json` format is supported. You can use comments in configuration files.\n\n:::\n\nExample\n\n`.oxlintrc.json`\n\n```json\n{\n\"$schema\": \"./node_modules/oxlint/configuration_schema.json\",\n\"plugins\": [\"import\", \"typescript\", \"unicorn\"],\n\"env\": {\n\"browser\": true\n},\n\"globals\": {\n\"foo\": \"readonly\"\n},\n\"settings\": {\n},\n\"rules\": {\n\"eqeqeq\": \"warn\",\n\"import/no-cycle\": \"error\",\n\"react/self-closing-comp\": [\"error\", { \"html\": false }]\n},\n\"overrides\": [\n{\n\"files\": [\"*.test.ts\", \"*.spec.ts\"],\n\"rules\": {\n\"@typescript-eslint/no-explicit-any\": \"off\"\n}\n}\n]\n}\n```",
+  "type": "object",
+  "properties": {
+    "categories": {
+      "default": {},
+      "allOf": [
+        {
+          "$ref": "#/definitions/OxlintCategories"
+        }
+      ]
+    },
+    "env": {
+      "description": "Environments enable and disable collections of global variables.",
+      "default": {
+        "builtin": true
+      },
+      "allOf": [
+        {
+          "$ref": "#/definitions/OxlintEnv"
+        }
+      ]
+    },
+    "extends": {
+      "description": "Paths of configuration files that this configuration file extends (inherits from). The files\nare resolved relative to the location of the configuration file that contains the `extends`\nproperty. The configuration files are merged from the first to the last, with the last file\noverriding the previous ones.",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "globals": {
+      "description": "Enabled or disabled specific global variables.",
+      "default": {},
+      "allOf": [
+        {
+          "$ref": "#/definitions/OxlintGlobals"
+        }
+      ]
+    },
+    "ignorePatterns": {
+      "description": "Globs to ignore during linting. These are resolved from the configuration file path.",
+      "default": [],
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "overrides": {
+      "description": "Add, remove, or otherwise reconfigure rules for specific files or groups of files.",
+      "allOf": [
+        {
+          "$ref": "#/definitions/OxlintOverrides"
+        }
+      ]
+    },
+    "plugins": {
+      "default": null,
+      "anyOf": [
+        {
+          "$ref": "#/definitions/LintPlugins"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "rules": {
+      "description": "Example\n\n`.oxlintrc.json`\n\n```json\n{\n\"$schema\": \"./node_modules/oxlint/configuration_schema.json\",\n\"rules\": {\n\"eqeqeq\": \"warn\",\n\"import/no-cycle\": \"error\",\n\"prefer-const\": [\"error\", { \"ignoreReadBeforeAssign\": true }]\n}\n}\n```\n\nSee [Oxlint Rules](https://oxc.rs/docs/guide/usage/linter/rules.html) for the list of\nrules.",
+      "default": {},
+      "allOf": [
+        {
+          "$ref": "#/definitions/OxlintRules"
+        }
+      ]
+    },
+    "settings": {
+      "default": {
+        "jsx-a11y": {
+          "polymorphicPropName": null,
+          "components": {}
+        },
+        "next": {
+          "rootDir": []
+        },
+        "react": {
+          "formComponents": [],
+          "linkComponents": []
+        },
+        "jsdoc": {
+          "ignorePrivate": false,
+          "ignoreInternal": false,
+          "ignoreReplacesDocs": true,
+          "overrideReplacesDocs": true,
+          "augmentsExtendsReplacesDocs": false,
+          "implementsReplacesDocs": false,
+          "exemptDestructuredRootsFromChecks": false,
+          "tagNamePreference": {}
+        }
+      },
+      "allOf": [
+        {
+          "$ref": "#/definitions/OxlintSettings"
+        }
+      ]
+    }
+  },
+  "definitions": {
+    "AllowWarnDeny": {
+      "oneOf": [
+        {
+          "description": "Oxlint rule.\n- \"allow\" or \"off\": Turn off the rule.\n- \"warn\": Turn the rule on as a warning (doesn't affect exit code).\n- \"error\" or \"deny\": Turn the rule on as an error (will exit with a failure code).",
+          "type": "string",
+          "enum": [
+            "allow",
+            "off",
+            "warn",
+            "error",
+            "deny"
+          ]
+        },
+        {
+          "description": "Oxlint rule.\n    \n- 0: Turn off the rule.\n- 1: Turn the rule on as a warning (doesn't affect exit code).\n- 2: Turn the rule on as an error (will exit with a failure code).",
+          "type": "integer",
+          "format": "uint32",
+          "maximum": 2.0,
+          "minimum": 0.0
+        }
+      ]
+    },
+    "CustomComponent": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "object",
+          "required": [
+            "attribute",
+            "name"
+          ],
+          "properties": {
+            "attribute": {
+              "type": "string"
+            },
+            "name": {
+              "type": "string"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": [
+            "attributes",
+            "name"
+          ],
+          "properties": {
+            "attributes": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "name": {
+              "type": "string"
+            }
+          }
+        }
+      ]
+    },
+    "DummyRule": {
+      "anyOf": [
+        {
+          "$ref": "#/definitions/AllowWarnDeny"
+        },
+        {
+          "type": "array",
+          "items": true
+        }
+      ]
+    },
+    "DummyRuleMap": {
+      "description": "See [Oxlint Rules](https://oxc.rs/docs/guide/usage/linter/rules.html)",
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/DummyRule"
+      }
+    },
+    "GlobSet": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "GlobalValue": {
+      "type": "string",
+      "enum": [
+        "readonly",
+        "writeable",
+        "off"
+      ]
+    },
+    "JSDocPluginSettings": {
+      "type": "object",
+      "properties": {
+        "augmentsExtendsReplacesDocs": {
+          "description": "Only for `require-(yields|returns|description|example|param|throws)` rule",
+          "default": false,
+          "type": "boolean"
+        },
+        "exemptDestructuredRootsFromChecks": {
+          "description": "Only for `require-param-type` and `require-param-description` rule",
+          "default": false,
+          "type": "boolean"
+        },
+        "ignoreInternal": {
+          "description": "For all rules but NOT apply to `empty-tags` rule",
+          "default": false,
+          "type": "boolean"
+        },
+        "ignorePrivate": {
+          "description": "For all rules but NOT apply to `check-access` and `empty-tags` rule",
+          "default": false,
+          "type": "boolean"
+        },
+        "ignoreReplacesDocs": {
+          "description": "Only for `require-(yields|returns|description|example|param|throws)` rule",
+          "default": true,
+          "type": "boolean"
+        },
+        "implementsReplacesDocs": {
+          "description": "Only for `require-(yields|returns|description|example|param|throws)` rule",
+          "default": false,
+          "type": "boolean"
+        },
+        "overrideReplacesDocs": {
+          "description": "Only for `require-(yields|returns|description|example|param|throws)` rule",
+          "default": true,
+          "type": "boolean"
+        },
+        "tagNamePreference": {
+          "default": {},
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/TagNamePreference"
+          }
+        }
+      }
+    },
+    "JSXA11yPluginSettings": {
+      "description": "Configure JSX A11y plugin rules.\n\nSee\n[eslint-plugin-jsx-a11y](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y#configurations)'s\nconfiguration for a full reference.",
+      "type": "object",
+      "properties": {
+        "components": {
+          "description": "To have your custom components be checked as DOM elements, you can\nprovide a mapping of your component names to the DOM element name.\n\nExample:\n\n```json\n{\n\"settings\": {\n\"jsx-a11y\": {\n\"components\": {\n\"Link\": \"a\",\n\"IconButton\": \"button\"\n}\n}\n}\n}\n```",
+          "default": {},
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "polymorphicPropName": {
+          "description": "An optional setting that define the prop your code uses to create polymorphic components.\nThis setting will be used to determine the element type in rules that\nrequire semantic context.\n\nFor example, if you set the `polymorphicPropName` to `as`, then this element:\n\n```jsx\n<Box as=\"h3\">Hello</Box>\n```\n\nWill be treated as an `h3`. If not set, this component will be treated\nas a `Box`.",
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    },
+    "LintPluginOptionsSchema": {
+      "type": "string",
+      "enum": [
+        "eslint",
+        "react",
+        "unicorn",
+        "typescript",
+        "oxc",
+        "import",
+        "jsdoc",
+        "jest",
+        "vitest",
+        "jsx-a11y",
+        "nextjs",
+        "react-perf",
+        "promise",
+        "node"
+      ]
+    },
+    "LintPlugins": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/LintPluginOptionsSchema"
+      }
+    },
+    "NextPluginSettings": {
+      "description": "Configure Next.js plugin rules.",
+      "type": "object",
+      "properties": {
+        "rootDir": {
+          "description": "The root directory of the Next.js project.\n\nThis is particularly useful when you have a monorepo and your Next.js\nproject is in a subfolder.\n\nExample:\n\n```json\n{\n\"settings\": {\n\"next\": {\n\"rootDir\": \"apps/dashboard/\"\n}\n}\n}\n```",
+          "default": [],
+          "allOf": [
+            {
+              "$ref": "#/definitions/OneOrMany_for_String"
+            }
+          ]
+        }
+      }
+    },
+    "OneOrMany_for_String": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      ]
+    },
+    "OxlintCategories": {
+      "title": "Rule Categories",
+      "description": "Configure an entire category of rules all at once.\n\nRules enabled or disabled this way will be overwritten by individual rules in the `rules` field.\n\nExample\n```json\n{\n    \"$schema\": \"./node_modules/oxlint/configuration_schema.json\",\n    \"categories\": {\n        \"correctness\": \"warn\"\n    },\n    \"rules\": {\n        \"eslint/no-unused-vars\": \"error\"\n    }\n}\n```",
+      "examples": [
+        {
+          "correctness": "warn"
+        }
+      ],
+      "type": "object",
+      "properties": {
+        "correctness": {
+          "$ref": "#/definitions/AllowWarnDeny"
+        },
+        "nursery": {
+          "$ref": "#/definitions/AllowWarnDeny"
+        },
+        "pedantic": {
+          "$ref": "#/definitions/AllowWarnDeny"
+        },
+        "perf": {
+          "$ref": "#/definitions/AllowWarnDeny"
+        },
+        "restriction": {
+          "$ref": "#/definitions/AllowWarnDeny"
+        },
+        "style": {
+          "$ref": "#/definitions/AllowWarnDeny"
+        },
+        "suspicious": {
+          "$ref": "#/definitions/AllowWarnDeny"
+        }
+      }
+    },
+    "OxlintEnv": {
+      "description": "Predefine global variables.\n\nEnvironments specify what global variables are predefined. See [ESLint's\nlist of\nenvironments](https://eslint.org/docs/v8.x/use/configure/language-options#specifying-environments)\nfor what environments are available and what each one provides.",
+      "type": "object",
+      "additionalProperties": {
+        "type": "boolean"
+      }
+    },
+    "OxlintGlobals": {
+      "description": "Add or remove global variables.\n\nFor each global variable, set the corresponding value equal to `\"writable\"`\nto allow the variable to be overwritten or `\"readonly\"` to disallow overwriting.\n\nGlobals can be disabled by setting their value to `\"off\"`. For example, in\nan environment where most Es2015 globals are available but `Promise` is unavailable,\nyou might use this config:\n\n```json\n\n{\n\"$schema\": \"./node_modules/oxlint/configuration_schema.json\",\n\"env\": {\n\"es6\": true\n},\n\"globals\": {\n\"Promise\": \"off\"\n}\n}\n\n```\n\nYou may also use `\"readable\"` or `false` to represent `\"readonly\"`, and\n`\"writeable\"` or `true` to represent `\"writable\"`.",
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/GlobalValue"
+      }
+    },
+    "OxlintOverride": {
+      "type": "object",
+      "required": [
+        "files"
+      ],
+      "properties": {
+        "env": {
+          "description": "Environments enable and disable collections of global variables.",
+          "anyOf": [
+            {
+              "$ref": "#/definitions/OxlintEnv"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "files": {
+          "description": "A list of glob patterns to override.\n\n## Example\n`[ \"*.test.ts\", \"*.spec.ts\" ]`",
+          "allOf": [
+            {
+              "$ref": "#/definitions/GlobSet"
+            }
+          ]
+        },
+        "globals": {
+          "description": "Enabled or disabled specific global variables.",
+          "anyOf": [
+            {
+              "$ref": "#/definitions/OxlintGlobals"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "plugins": {
+          "description": "Optionally change what plugins are enabled for this override. When\nomitted, the base config's plugins are used.",
+          "default": null,
+          "anyOf": [
+            {
+              "$ref": "#/definitions/LintPlugins"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "rules": {
+          "default": {},
+          "allOf": [
+            {
+              "$ref": "#/definitions/OxlintRules"
+            }
+          ]
+        }
+      }
+    },
+    "OxlintOverrides": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/OxlintOverride"
+      }
+    },
+    "OxlintRules": {
+      "$ref": "#/definitions/DummyRuleMap"
+    },
+    "OxlintSettings": {
+      "title": "Oxlint Plugin Settings",
+      "description": "Configure the behavior of linter plugins.\n\nHere's an example if you're using Next.js in a monorepo:\n\n```json\n{\n\"settings\": {\n\"next\": {\n\"rootDir\": \"apps/dashboard/\"\n},\n\"react\": {\n\"linkComponents\": [\n{ \"name\": \"Link\", \"linkAttribute\": \"to\" }\n]\n},\n\"jsx-a11y\": {\n\"components\": {\n\"Link\": \"a\",\n\"Button\": \"button\"\n}\n}\n}\n}\n```",
+      "type": "object",
+      "properties": {
+        "jsdoc": {
+          "default": {
+            "ignorePrivate": false,
+            "ignoreInternal": false,
+            "ignoreReplacesDocs": true,
+            "overrideReplacesDocs": true,
+            "augmentsExtendsReplacesDocs": false,
+            "implementsReplacesDocs": false,
+            "exemptDestructuredRootsFromChecks": false,
+            "tagNamePreference": {}
+          },
+          "allOf": [
+            {
+              "$ref": "#/definitions/JSDocPluginSettings"
+            }
+          ]
+        },
+        "jsx-a11y": {
+          "default": {
+            "polymorphicPropName": null,
+            "components": {}
+          },
+          "allOf": [
+            {
+              "$ref": "#/definitions/JSXA11yPluginSettings"
+            }
+          ]
+        },
+        "next": {
+          "default": {
+            "rootDir": []
+          },
+          "allOf": [
+            {
+              "$ref": "#/definitions/NextPluginSettings"
+            }
+          ]
+        },
+        "react": {
+          "default": {
+            "formComponents": [],
+            "linkComponents": []
+          },
+          "allOf": [
+            {
+              "$ref": "#/definitions/ReactPluginSettings"
+            }
+          ]
+        }
+      }
+    },
+    "ReactPluginSettings": {
+      "description": "Configure React plugin rules.\n\nDerived from [eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react#configuration-legacy-eslintrc-)",
+      "type": "object",
+      "properties": {
+        "formComponents": {
+          "description": "Components used as alternatives to `<form>` for forms, such as `<Formik>`.\n\nExample:\n\n```jsonc\n{\n\"settings\": {\n\"react\": {\n\"formComponents\": [\n\"CustomForm\",\n// OtherForm is considered a form component and has an endpoint attribute\n{ \"name\": \"OtherForm\", \"formAttribute\": \"endpoint\" },\n// allows specifying multiple properties if necessary\n{ \"name\": \"Form\", \"formAttribute\": [\"registerEndpoint\", \"loginEndpoint\"] }\n]\n}\n}\n}\n```",
+          "default": [],
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/CustomComponent"
+          }
+        },
+        "linkComponents": {
+          "description": "Components used as alternatives to `<a>` for linking, such as `<Link>`.\n\nExample:\n\n```jsonc\n{\n\"settings\": {\n\"react\": {\n\"linkComponents\": [\n\"HyperLink\",\n// Use `linkAttribute` for components that use a different prop name\n// than `href`.\n{ \"name\": \"MyLink\", \"linkAttribute\": \"to\" },\n// allows specifying multiple properties if necessary\n{ \"name\": \"Link\", \"linkAttribute\": [\"to\", \"href\"] }\n]\n}\n}\n}\n```",
+          "default": [],
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/CustomComponent"
+          }
+        }
+      }
+    },
+    "TagNamePreference": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "object",
+          "required": [
+            "message",
+            "replacement"
+          ],
+          "properties": {
+            "message": {
+              "type": "string"
+            },
+            "replacement": {
+              "type": "string"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": [
+            "message"
+          ],
+          "properties": {
+            "message": {
+              "type": "string"
+            }
+          }
+        },
+        {
+          "type": "boolean"
+        }
+      ]
+    }
+  }
+}
\ No newline at end of file
diff --git a/AGENTS.md b/AGENTS.md
index aa62f7ad..87cb1bfd 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -79,6 +79,10 @@ Verification boundary: /ln-spec owns inner-loop verification (commands, policy).
 
 Tooling: oxlint (lint + type-aware + type-check via tsgolint), oxfmt (format). Verification strategy details in SPEC.md §Verification Design.
 
+## critical file-safety rule
+
+Do not delete untracked files or directories without explicit user confirmation. Do not overwrite, revert, reset, reformat, or otherwise clobber uncommitted changes unless you know they are yours from this session or the user explicitly approves. Treat any uncommitted work from the user or another agent as protected. This includes newly-created local files, ignored files, scratch directories, generated-looking folders, empty placeholder directories, and modified tracked files. If cleanup or rollback seems appropriate, ask first and name the exact path(s) and action you propose.
+
 ## operational protocols
 
 Read these before the relevant activity:
diff --git a/bin/brunch.js b/bin/brunch.js
index e00d8b2a..740c69df 100755
--- a/bin/brunch.js
+++ b/bin/brunch.js
@@ -1,2 +1,12 @@
 #!/usr/bin/env node
-import "../dist/brunch.js"
+import { runBrunchCli } from "../dist/brunch.js"
+
+runBrunchCli()
+  .then((code) => {
+    process.exitCode = code
+  })
+  .catch((error) => {
+    const message = error instanceof Error ? error.message : String(error)
+    process.stderr.write(`${message}\n`)
+    process.exitCode = 1
+  })
diff --git a/docs/architecture/fixture-strategy.md b/docs/architecture/fixture-strategy.md
index 94c24cbe..aa2eb0f7 100644
--- a/docs/architecture/fixture-strategy.md
+++ b/docs/architecture/fixture-strategy.md
@@ -159,8 +159,8 @@ A run for brief #7 that terminates with kernels active but with none of `product
 The agent-as-user is a thin driver that exercises the JSON-RPC stdio surface end to end. It does three things:
 
 1. Opens a JSON-RPC stdio connection to `brunch --mode rpc`.
-2. Subscribes to the session's offer stream (`brunch.offer` custom messages per [pi-seam-extensions §4](file:///Users/lunelson/Code/hashintel/brunch-next/docs/architecture/pi-seam-extensions.md#4-assistant--and-system-offer-first-interaction-with-multi-choice-answers)).
-3. For each offer, calls an LLM with the brief, the persona dials, and the offer envelope; collects the response (`brunch.offer_response`); posts it back over RPC.
+2. Subscribes to Brunch's pending structured-interaction stream (structured-question tool calls/results and product-native offer/proposal entries per [pi-seam-extensions §4](file:///Users/lunelson/Code/hashintel/brunch-next/docs/architecture/pi-seam-extensions.md#4-assistant--and-system-offer-first-structured-interaction)).
+3. For each pending interaction, calls an LLM with the brief, the persona dials, and the interaction payload; collects a terminal structured response; posts it back over Brunch RPC (or through the private Pi-RPC extension UI relay when the driver is proving that seam).
 
 ### Termination conditions
 
@@ -200,7 +200,7 @@ A captured run produces four artefacts under `.brunch-fixtures/<brief-id>/<run-i
 
 | File | Contents |
 | --- | --- |
-| `<run-id>.jsonl` | The full pi JSONL session transcript including all custom entries (`brunch.offer`, `brunch.offer_response`, `brunch.lens_switch`, `brunch.spec_switch`, `brunch.kernel_activation`, `brunch.side_task_result`, `worldUpdate`) |
+| `<run-id>.jsonl` | The full pi JSONL session transcript including structured-question tool results and Brunch custom entries (`brunch.establishment_offer`, `brunch.review_set_proposal`, `brunch.elicitor_intent_hint`, `brunch.lens_switch`, `brunch.spec_switch`, `brunch.kernel_activation`, `brunch.side_task_result`, `worldUpdate`) |
 | `<run-id>.graph.json` | A snapshot of all spec-workspace graph planes at run termination: nodes, edges, per-entity versions, current graph LSN |
 | `<run-id>.coherence.json` | Coherence verdict at termination, including per-plane status and any open violations |
 | `<run-id>.meta.json` | Run metadata: brief id, persona dials, model, timestamps, total turns, total tokens, terminal reason, agent-as-user prompt hash |
diff --git a/docs/architecture/pi-seam-extensions.md b/docs/architecture/pi-seam-extensions.md
index 1262c755..c6f96e56 100644
--- a/docs/architecture/pi-seam-extensions.md
+++ b/docs/architecture/pi-seam-extensions.md
@@ -7,7 +7,7 @@ The four affordances:
 1. Async "side-chain" sub-agents whose results return at a later turn boundary.
 2. Switchable lenses / strategies for the primary interviewing agent.
 3. A TUI spec selector for opening or switching between specifications.
-4. An assistant-/system-offer-first interaction model with multi-choice answers.
+4. An assistant-/system-offer-first structured interaction model with typed answers.
 
 For each one this document records the pi seams it relies on, the Brunch-owned work it forces, and the residual risks.
 
@@ -128,72 +128,73 @@ Implications:
 - Pi's `SessionManager` is one-directory-per-process. If the POC needs spec-roots outside `.brunch/sessions/`, Brunch must either reconfigure `SessionManager.create(cwd, customDir)` per spec or maintain its own indirection layer above pi's session resolution. This couples directly to the JSONL viability proof in M2.
 - The selector overlay competes with other overlays (model picker, confirmation dialogs). Brunch must own a small overlay-priority policy so a spec switch does not stomp an in-flight confirmation.
 
-## 4. Assistant- and system-offer-first interaction with multi-choice answers
+## 4. Assistant- and system-offer-first structured interaction
 
 ### Need
 
-Every Brunch session should open with a concrete action or answer surface rather than an empty prompt. The user should always be able to either choose from offered actions or answer an offered question, where answers may be single-choice, multi-choice, or freeform-plus-choice. This is a product stance: Brunch is a guided-elicitation product, not an open chat.
+Every Brunch session should open with a concrete action or answer surface rather than an empty prompt. The user should always be responding to a system/assistant-originated question, questionnaire, offer, or proposal, where answers may be single-choice, multi-choice, questionnaire, or freeform-plus-choice. This is a product stance: Brunch is a guided-elicitation product, not an open chat.
 
 ### Pi seams used
 
-- `pi.registerMessageRenderer(customType, renderer)` for rendering a Brunch offer envelope inline in the transcript across TUI, web, and RPC.
-- `pi.sendMessage(...)` and `pi.appendEntry(...)` with `deliverAs: "followUp"` for posting the user's selection back into the active turn without inventing a new transport.
-- `ExtensionUIContext.select`, `confirm`, `input` for the simple cases.
-- `ExtensionUIContext.custom<T>(...)` for the multi-select and freeform-plus-choice cases. The API is generic on `T`, so a multi-select overlay legitimately returns `string[]`.
-- The RPC mode's `extension_ui_request` channel for routing the same UI requests to the web client.
+- Registered Pi tools for basic structured questions/questionnaires. The assistant `toolCall` supplies causal/positional prompt context; the toolResult `content` supplies the model-readable summary; the toolResult `details` can carry Brunch's self-contained structured response payload.
+- `ExtensionUIContext.select`, `confirm`, and `input` for simple RPC-compatible cases.
+- `ExtensionUIContext.custom<T>(...)` for rich TUI response surfaces. Pi's `question.ts` and `questionnaire.ts` examples prove editor-area replacement for single-choice, optional freeform, and tabbed questionnaire flows.
+- `ExtensionUIContext.editor(...)` as the raw Pi-RPC fallback for complex shapes: the tool can send schema-tagged JSON prefill and validate the returned JSON.
+- The RPC mode's documented `extension_ui_request` / `extension_ui_response` channel for routing supported Pi UI requests through a private Brunch adapter.
+- `pi.registerMessageRenderer(customType, renderer)` and Brunch custom entries remain available for establishment offers, review-set proposals, annotations, and product-native displays where a tool result is not the thinnest transcript representation.
 
 ### Brunch-owned work
 
-- A `brunch.offer` custom-message envelope: `{ kind: "actions" | "question", prompt?, options: [{ id, label, value }], multi: boolean, freeform: boolean, allowSkip: boolean, expiresOn?: TurnId | Timestamp, captureHint?: TurnCaptureHint }`.
-- A `brunch.offer_response` custom-message envelope with the user's selection, freeform text, or skip outcome.
-- A single Brunch-owned renderer for `brunch.offer` per mode: TUI overlay, web component, RPC `extension_ui_request` extension method.
-- A `MultiSelectOverlay` component built once on `pi-tui` primitives, returning `string[]`. The same overlay machinery covers both interaction shapes: a **radio** variant (`multi: false`, exactly one selection enforced) and a **checkbox** variant (`multi: true`, any subset including empty if `allowSkip: true`). These are not separate overlays; the visual affordance (`◉ / ◯` vs `☑ / ☐`) is driven by the `multi` field on `brunch.offer`. Keybindings, freeform-plus-choice composition, and `expiresOn` handling are identical across the two variants.
-- A `session_start` hook that synthesizes an initial offer when no transcript history exists, so every fresh session opens with a surface.
-- A protocol extension to the RPC `extension_ui_request` family for `multiSelect` and `freeformWithChoice`, with a corresponding web client implementation. This is additive, not a replacement.
+- A structured-question result details payload carrying enough projection data to stand alone: schema/version, status (`answered | skipped | cancelled | unavailable`), mode, prompt/questions, options, answers, and transport metadata.
+- A Brunch-owned TUI helper built on Pi custom UI patterns for radio, checkbox, questionnaire, and optional freeform input.
+- JSON-prefill / validation helpers for RPC editor fallback. This is a compatibility seam over Pi RPC, not a second Brunch product API.
+- A private Pi RPC adapter that translates `extension_ui_request(editor)` into product-shaped pending elicitation state for Brunch public clients, then translates the product response back into Pi's documented `extension_ui_response`.
+- Elicitation-exchange projection that treats terminal structured-question toolResults as response-side entries when their details carry the typed Brunch payload; ordinary toolResults remain prompt-side by default.
+- Brunch custom entry schemas for product-native offers that are not ordinary questions, such as `brunch.establishment_offer`, `brunch.review_set_proposal`, and later review-cycle responses.
 
-### Capture-aware offer envelope
+### Capture-aware response payload
 
-The `captureHint` field on `brunch.offer` is a **private side-channel** the interviewer attaches to substantive questions so the observer (the graph-capture pass that processes the user's response) has explicit priors instead of free-associating over the whole graph. The hint is invisible to the user but visible in the transcript.
+For substantive elicitation questions, the structured result may carry observer priors so the graph-capture pass can process the user's response without free-associating over the whole graph. These hints are advisory and visible in transcript truth when present; they are not commands.
 
 ```ts
-type TurnCaptureHint = {
-  expectedKinds: IntentKind[];         // kinds the response is likely to produce
-  candidateRelations?: RelationKind[]; // edges the response may motivate
-  targetItems?: NodeRef[];             // graph items the question is about
-  captureMode:
-    | 'new_item'
-    | 'clarify_existing'
-    | 'choose_option'
-    | 'rank_priority'
-    | 'resolve_need'
-    | 'provide_example';
-  resolvesNeedId?: string;             // reconciliation_need this offer is resolving
-  options?: Array<{
-    label: string;                     // mirrors the user-visible option label
-    mapsTo?: {
-      nodeKind?: IntentKind;
-      relationKind?: RelationKind;
-      targetRef?: NodeRef;
-      framingAs?: string;              // see Product-framing modality
-    };
+type StructuredQuestionResultDetails = {
+  schema: "brunch.structured_question_result";
+  version: 1;
+  status: "answered" | "skipped" | "cancelled" | "unavailable";
+  mode: "single" | "multiple" | "questionnaire" | "freeform_plus_choice";
+  prompt?: string;
+  questions?: Array<{
+    id: string;
+    prompt: string;
+    options?: Array<{ id: string; label: string; description?: string }>;
   }>;
+  answers: Array<{
+    questionId?: string;
+    selectedOptionIds?: string[];
+    freeform?: string;
+  }>;
+  captureHint?: TurnCaptureHint;
+  transport: {
+    surface: "tui_custom" | "rpc_select" | "rpc_input" | "rpc_editor_json" | "product_relay" | "none";
+  };
 };
 ```
 
-The observer treats hints as priors, not commands. The user retains escape hatches (`allowSkip`, freeform) and the observer's abstention rule still applies — if the response does not match any hint, the observer may emit zero mutations rather than force a fit.
+The observer treats `captureHint` as priors, not authority. The user retains escape hatches (`skipped`, `cancelled`, freeform), and the observer's abstention rule still applies — if the response does not match any hint, the observer may emit zero mutations rather than force a fit.
 
 ### Posture
 
-- The offer envelope is durable transcript truth, not ephemeral UI state. Selections are written back as custom messages so the agent can reason over them on the next turn and the transcript reload faithfully reproduces what was offered and what was chosen.
-- The agent is allowed to refuse to chat without an offer. The Brunch system prompt should require the agent to either produce an offer or emit `brunch.needs_human` for cases the agent cannot resolve.
-- In print mode an offer either resolves via an explicit auto-policy or returns a structured `needs_human` outcome. It does not block.
-- Multi-choice answers are first-class. Single-choice is a degenerate multi-choice with `multi: false`.
-- Capture hints are advisory. The observer must abstain rather than force a graph mutation when the user's response does not match the hint.
+- Structured interaction is durable transcript truth, not ephemeral UI state. For ordinary questions/questionnaires, self-contained toolResult details may be the canonical structured response. For product-native offers/proposals, Brunch custom entries remain appropriate.
+- The agent is allowed to refuse ambient chat without an elicitation surface. The Brunch system prompt should require the agent to either produce an elicitation prompt/offer or emit `brunch.needs_human` for cases the agent cannot resolve.
+- In print mode a structured interaction either resolves via an explicit auto-policy or returns a structured `needs_human` / unavailable outcome. It does not block.
+- Multi-choice answers are first-class. Single-choice is a degenerate multi-choice with one selected option.
+- Public clients speak Brunch RPC method families; raw Pi RPC is hidden behind the adapter used for agent-loop mechanics and extension UI.
 
 ### Residual risks
 
-- The offer envelope risks being treated as a replacement for the LLM's natural narrative. Brunch should keep offers as the *interaction* surface while the assistant's prose remains the *explanation* surface. A lens that bypasses offers is allowed only for explicitly free-chat moments.
-- Pi's RPC `extension_ui_request` types are currently fixed. Adding `multiSelect` and `freeformWithChoice` is a Brunch-side protocol extension that the web client must agree on; this is small but non-zero coupling that should be tracked.
+- ToolResult details can become too heavy if every result repeats full prompt/question/option state. Default to self-contained payloads for POC projection clarity; trim only after projection helpers prove a safe prompt-side correlation rule.
+- Schema-tagged JSON in `ctx.ui.editor()` is a compatibility fallback, not acceptable final UX for Brunch-aware clients. The public Brunch relay should render native forms where possible.
+- The offer/proposal envelope risks being treated as a replacement for the LLM's natural narrative. Brunch should keep offers as the *interaction* surface while assistant prose remains the *explanation* surface. A lens that bypasses offers is allowed only for explicitly free-chat moments.
 
 ## 5. Graph-entity mentions and mention staleness
 
@@ -203,27 +204,28 @@ The user (and the agent, on the user's behalf) should be able to refer to graph
 
 ### Pi seams used
 
-- `pi-tui` input components (the prompt-editor surface), augmented with a Brunch-owned `MentionAutocompleteOverlay` mounted via `ExtensionUIContext.custom<T>(...)`.
-- The custom-entry transcript surface (`pi.appendEntry`, `pi.registerMessageRenderer`) for representing mentions inside user messages as structured spans rather than as raw text.
+- `ctx.ui.addAutocompleteProvider((current) => ...)` over Pi's prompt editor. The autocomplete item's `value` is inserted into the editor; Pi does not persist hidden autocomplete metadata.
+- `before_agent_start` system-prompt injection for teaching the active agent how to interpret Brunch `#` handles and when to call a lookup/re-read tool. The inserted handle is just transcript text unless Brunch adds a later parser/indexer.
+- Brunch custom transcript entries (`pi.appendEntry`, `pi.registerMessageRenderer`) for future mention ledger/staleness records and resolved entity snapshots; these are separate from the autocomplete insertion itself.
 - `prepareNextTurn` for injecting mention-staleness hints into the agent's next-turn context, alongside the existing `worldUpdate` flow.
 - The reconciliation-need substrate and global LSN (see §Reconciliation-need substrate and §Graph clock) for comparing the LSN at which a mention was last *snapshotted into the model's working context* against the entity's current LSN.
 
 ### Brunch-owned work
 
-- A `MentionAutocompleteOverlay` triggered by `#` in the input area, sourced from `SpecRegistry` + current spec's graph index, that resolves either against stable graph `ID` or (fallback) against the entity's current `title`. ID resolution is canonical; title resolution is a UX affordance that always rewrites to an ID-anchored mention on insertion.
-- A `brunch.mention` payload shape attached to user message entries (e.g. as a span array in the message custom payload): `{ id: NodeId, title_at_mention: string, lsn_at_mention: number }`. The `title_at_mention` and `lsn_at_mention` are frozen at insertion time so the transcript carries the historical reference even if the entity is later renamed.
-- A renderer (per mode: TUI, web, RPC) that displays mentions as `#<title>` (current title, not the frozen one) with an indicator when the current title differs from the frozen one.
+- A `#` autocomplete provider sourced from `SpecRegistry` + current spec's graph index. It may search current titles and descriptions, but the inserted `value` must be a stable handle such as `#A12` or `#<node-id>`; popup `label`/`description` are UI-only and are not session metadata.
+- A Brunch mention indexer that parses user/assistant text for stable `#` handles after input and resolves them to `{ id: NodeId, title_at_mention: string, lsn_at_mention: number }` for the session mention ledger. This parsing/indexing step, not Pi autocomplete, is what creates structured mention state.
+- A graph lookup/re-read tool (for example `brunch.entity_reread`) whose prompt guidance tells the agent to resolve `#A12` by passing the handle without the `#` when deeper entity detail matters.
 - A `SessionMentionLedger` in the session-scoped state: for each `id` ever mentioned in this session, the highest `snapshotted_lsn` — i.e. the LSN at which the agent most recently received the full entity payload (either via initial context, a `worldUpdate` cascade, or an explicit re-read tool call). The ledger persists with the session and survives compaction.
 - A staleness check executed during `prepareNextTurn`:
   1. Walk the session's `SessionMentionLedger`.
   2. For every entry where the entity's current LSN > `snapshotted_lsn`, the entity is **stale-in-context** for this session.
   3. Brunch synthesizes a `brunch.mention_staleness_hint` entry (custom message, `deliverAs: "nextTurn"`) summarising the stale set. The hint is **discretionary advice to the agent**, not a forced re-read: it tells the agent "if you intend to reason over `#foo` again, re-read it; the snapshot you have is from LSN 412, current is LSN 487."
   4. The agent decides whether to invoke a re-read tool (which then updates `snapshotted_lsn`) or to proceed with the existing snapshot, accepting the staleness.
-- A `brunch.entity_reread` command (through the shared command layer) that re-snapshots a named entity and updates `snapshotted_lsn` to the LSN observed at re-read.
+- A `brunch.entity_reread` command/tool (through the shared command layer) that re-snapshots a named entity and updates `snapshotted_lsn` to the LSN observed at re-read.
 
 ### Posture
 
-- Mentions are anchored to stable IDs, never to titles. Title-based autocomplete is a UX affordance only.
+- Mentions are anchored to stable handles/IDs, never to titles. Title-based autocomplete is a UX affordance only; the transcript persists the inserted textual handle, not the popup label/description.
 - The mention ledger is **session-scoped**, not transcript-scoped: the question "what has this agent seen at what LSN" is a per-session model-context question, and crossing sessions (via `switchSession`) legitimately resets it.
 - Staleness hints are **discretionary**. The agent's autonomy over its own context is preserved; Brunch merely surfaces the gap. The product stance is that re-read is cheap and worth doing when in doubt, but the framework does not mandate it.
 - Staleness hints reuse the same `worldUpdate` machinery and the same global LSN as the rest of the change-log / reconciliation substrate; this is not a parallel staleness mechanism.
@@ -528,7 +530,7 @@ Concretely, Flue has **no equivalent** for any of:
 
 - `prepareNextTurn` injection of `worldUpdate` between turns.
 - `pi.appendEntry({ deliverAs: "nextTurn" })` for side-chain result delivery. Flue's `session.task()` is awaited inline.
-- Custom-message entry types + `registerMessageRenderer` for `brunch.offer`, `brunch.lens_switch`, `brunch.spec_switch`, `brunch.side_task_result`.
+- Custom-message/tool-result transcript types plus renderers for Brunch structured interaction state (`brunch.establishment_offer`, `brunch.review_set_proposal`, `brunch.lens_switch`, `brunch.spec_switch`, `brunch.side_task_result`, and structured-question toolResult details).
 - `pi.registerCommand` for `/lens`, `/spec`, `/compact`-style affordances.
 - `ExtensionUIContext.select | confirm | input | custom` for confirmation-gated writes and overlay UIs.
 - `pi-tui` primitives, including `SessionSelectorComponent` as a model for `SpecSelectorComponent`.
@@ -788,9 +790,9 @@ By M5/M6, if formal-verification consumers need to query, rebind, or review reas
 
 1. Whether a lens may register its own pi tools at load time or must declare them up front. Up-front declaration keeps `setActiveTools` sufficient but constrains lens authorship.
 2. Whether spec switching is always a session switch or whether one transcript may span several spec roots with lens-mediated framing.
-3. Whether the offer envelope should be a single `brunch.offer` type with a `kind` discriminator or several types (`brunch.action_menu`, `brunch.question`, `brunch.question_freeform`) for sharper renderer typing.
+3. Which product-native structured offers still deserve Brunch custom-entry types now that ordinary questions/questionnaires can use self-contained toolResult details.
 4. Whether side-task results should always go through the shared command layer or whether read-only "advice" side tasks are allowed to produce custom-message results without touching graph state.
-5. Whether the RPC `multiSelect` and `freeformWithChoice` protocol extensions should live in Brunch's own JSON-RPC surface from day one rather than as an extension of pi's `extension_ui_request` family.
+5. What the thinnest Brunch public method/event family should be for relaying Pi extension UI requests (`elicitation.*`, `agent.ui.*`, or another scoped family), while keeping raw Pi RPC private.
 6. Whether before-images should be stored from M4 to simplify later coherence work, accepting the doubled write-time read cost, or deferred to M8 when their consumers exist.
 7. Whether the change-log `op` payload should be free-form JSON keyed only by `target_kind`, or a discriminated union of typed op shapes per graph plane to make change-log replay strongly typed.
 8. When (M-number or brief-count signal) to promote framings from `framing_as` to first-class node kinds. The current rule is "only when a framing repeatedly demands unique relation-policy or coherence behaviour across multiple briefs"; the operational signal for this remains under-specified.
diff --git a/docs/architecture/pi-ui-extension-patterns-provisional-plan.md b/docs/architecture/pi-ui-extension-patterns-provisional-plan.md
new file mode 100644
index 00000000..7128f6df
--- /dev/null
+++ b/docs/architecture/pi-ui-extension-patterns-provisional-plan.md
@@ -0,0 +1,91 @@
+# Pi UI Extension Patterns — Structured Elicitation Working Plan
+
+This file is a trimmed working inventory for the remaining FE-744 gap. It is not canonical product contract; durable conclusions belong in `memory/SPEC.md`, `memory/PLAN.md`, and `docs/architecture/pi-ui-extension-patterns.md`.
+
+## Why this is still live
+
+Command containment, Brunch chrome, startup no-resume, and the `/brunch` menu/workspace switch flow are proven enough for now. The unresolved POC seam is different:
+
+> Brunch sessions must work elicitation-first: a system/assistant-originated question, questionnaire, or offer should own the response surface, persist a terminal structured result in Pi JSONL, and be projectable as a prompt/response elicitation exchange before the next agent turn.
+
+The latest planning decision narrows the first proof away from a Brunch-only `brunch.offer` envelope. Basic structured questions should use Pi's registered-tool transcript seam when it is thinner: assistant `toolCall` for causal/positional context, toolResult `content` for the model-readable answer summary, and toolResult `details` as Brunch's self-contained structured response payload. Brunch custom entries remain valid for establishment offers, review-set proposals, annotations, and shapes that are not naturally tool questions.
+
+## Pi evidence already relevant
+
+- `docs/usage.md`: the editor can be replaced temporarily by built-in UI or custom extension UI.
+- `docs/tui.md`: `ctx.ui.custom<T>()` can replace the editor area with a custom component and return typed data; overlays are optional, not required.
+- `docs/tui.md` Pattern 7: `ctx.ui.setEditorComponent()` can replace the main input editor with a custom editor implementation if a future persistent pending-interaction surface needs it.
+- `examples/extensions/question.ts`: single-choice options plus a "Type something" escape hatch using `ctx.ui.custom()`, returning answer data in `toolResult.details`.
+- `examples/extensions/questionnaire.ts`: multi-question/tabbed choice UI with optional custom text answers, returning a full questionnaire result in `toolResult.details`.
+- `examples/extensions/rpc-demo.ts`: `ctx.ui.editor()` emits Pi RPC `extension_ui_request` / `extension_ui_response` traffic.
+- `examples/rpc-extension-ui.ts`: a non-Pi client can translate Pi RPC extension UI requests into its own prompt/dialog components and respond through the documented protocol.
+- `examples/extensions/message-renderer.ts`: custom transcript display is available, but display rendering alone does not collect a response.
+
+## Target seam to prove
+
+### Structured-question result + JSON-editor RPC fallback
+
+1. A registered Pi tool asks a structured Brunch question or questionnaire.
+2. The assistant tool call is preserved as prompt-side transcript context; it is not the only semantic source for projection.
+3. In TUI mode, the tool replaces the default input surface with Brunch-owned custom UI supporting the POC interaction kernels:
+   - single-choice selection,
+   - multi-choice selection,
+   - questionnaire / multiple questions,
+   - optional freeform additional input,
+   - cancel/skip/unavailable where allowed.
+4. In raw Pi RPC mode, complex shapes degrade through `ctx.ui.editor()` with schema-tagged JSON prefill; simple shapes may use Pi-supported `select`, `confirm`, or `input` where sufficient.
+5. A Brunch-aware public client can render the pending interaction as a product form and translate the answer back into Pi's documented `extension_ui_response`.
+6. The tool returns one terminal result whose `content` is generated from the same details and whose `details` are self-contained: schema/version, status, mode, prompt/questions, options, answers, and transport metadata.
+7. Elicitation-exchange projection classifies terminal structured-question toolResults as response-side entries, while ordinary toolResults remain prompt-side unless typed markers say otherwise.
+8. No graph mutation or review acceptance bypasses `CommandExecutor`; this slice proves interaction capture, not graph writes.
+
+## Active slice candidate
+
+**Name:** Structured-question result + JSON-editor RPC fallback
+
+**Goal:** Prove that a transcript-native structured question can replace ambient free input in TUI, stay controllable over Pi RPC, and persist a response payload that Brunch can project without rehydrating semantics solely from assistant tool-call arguments.
+
+**Likely implementation shape:**
+
+- Define a minimal structured-question result details payload with `schema`, `status`, `mode`, `prompt` or `questions`, `options`, `answers`, and `transport`.
+- Add a Brunch-owned TUI helper modeled on Pi's `question.ts` / `questionnaire.ts` examples.
+- Add JSON-prefill / validation helpers for RPC editor fallback.
+- Add a Brunch Pi-RPC relay shim that maps Pi `extension_ui_request(editor)` to public Brunch pending-elicitation events/methods and maps the product answer back to `extension_ui_response`.
+- Update elicitation-exchange projection to recognize typed terminal structured-question toolResults as response-side entries.
+
+**Acceptance:**
+
+- A fixture/demo session can ask a system/assistant-originated structured question with no ambient user prompt.
+- The default freeform editor is replaced while the question is pending in TUI.
+- The user can answer single-choice, multi-choice, questionnaire, and optional-freeform shapes.
+- Raw Pi RPC can round-trip a complex response through schema-tagged JSON over `ctx.ui.editor()`.
+- The terminal Pi JSONL toolResult includes self-contained structured details and model-readable content derived from those details.
+- Elicitation exchange projection treats the prompt-side tool/custom entry and terminal structured result as one exchange.
+- Public Brunch clients do not coordinate raw Pi RPC and Brunch RPC as two product APIs; raw Pi RPC remains behind an adapter.
+
+## Residual catalog still carried forward
+
+| Need | Status after current evidence | Carry-forward |
+| --- | --- | --- |
+| Single-choice question UI | Pi example-proven; Brunch loop not yet proven | Active slice |
+| Multi-choice UI | Needs Brunch helper; Pi questionnaire patterns can be adapted | Active slice |
+| Questionnaire | Pi example-proven; Brunch details schema/projection not yet proven | Active slice |
+| Freeform-plus-choice | Pi `question.ts` proves the pattern | Active slice |
+| JSON-editor fallback | Pi RPC editor evidence exists; Brunch schema/relay not yet proven | Active slice |
+| Structured custom entries | Still valid for establishment offers, review sets, and product-native displays | Use only where thinner than toolResult details |
+| Review-set approve/request/reject | Depends on terminal structured-response discipline and graph commands | M5 follow-up when `acceptReviewSet` exists |
+| Establishment-offer orientation expansion | Must remain user-invoked, not a default exhaustive menu | M5/M7 follow-up |
+| Mouse-clickable action buttons | Unproven and not required for POC if keyboard navigation works | Defer |
+| Strict built-in command suppression | Requires Pi command/keybinding policy | Separate follow-up, not this slice |
+
+## Open questions
+
+- Which details schema name/version should become canonical for structured-question toolResults?
+- Does every structured toolResult carry all options, or can simple cases store only selected options while richer projection references a prompt-side entry? Current SPEC posture says self-contained enough for projection, so default to carrying all prompt/question/option data until evidence says it is too heavy.
+- Should unavailable/no-UI contexts return `status: "unavailable"` instead of an error-shaped content string?
+- What is the thinnest Brunch method/event family for pending elicitation discovery and response submission: `elicitation.pending/respond`, `agent.ui.*`, or a private relay under `agent.*`?
+- How much of the schema-tagged JSON editor prefill should be user-visible in raw Pi RPC versus hidden by Brunch-aware clients?
+
+## Retirement rule
+
+Retire this file only after the structured-question / RPC-relay loop is either implemented and reconciled into `docs/architecture/pi-ui-extension-patterns.md` / SPEC / PLAN, or intentionally moved into a named M5 frontier slice. Do not delete it merely because command containment or chrome work is complete.
diff --git a/docs/architecture/pi-ui-extension-patterns.md b/docs/architecture/pi-ui-extension-patterns.md
new file mode 100644
index 00000000..27611ade
--- /dev/null
+++ b/docs/architecture/pi-ui-extension-patterns.md
@@ -0,0 +1,271 @@
+# Pi UI Extension Patterns
+
+This memo records evidence for the `pi-ui-extension-patterns` frontier. It is intentionally evidence-tiered: source audit, raw Pi harness observations, Brunch-host proof, RPC controllability, and remaining assumptions are separate.
+
+## Current verdicts
+
+| Area | Verdict | Required before downstream work? | Evidence tier |
+| --- | --- | --- | --- |
+| Built-in slash autocomplete allowlist | feasible-with-cost | desirable before M5 UI polish; not enough for policy | source audit |
+| Built-in exact slash execution allowlist | requires-pi-change for strict suppression | required before claiming strict product-shell containment; not required for graph-command safety if dangerous effects are blocked separately | source audit + raw RPC probe |
+| Branch-flow effect blocking (`/fork`, `/clone`, `/tree`) | proven for lifecycle/API effect cancellation; residual pre-cancel UI exposure remains | required for I19-L and already partly used by Brunch | source audit + raw RPC probe |
+| Extension command collision override | not-feasible | product commands must avoid built-in names unless Pi adds policy | source audit |
+| RPC-visible chrome/status degradation | proven for status/widget/title; no-op for header/footer/working indicator | informs fixture-driver expectations | Brunch wrapper unit oracle + raw RPC probe |
+| Dynamic Brunch chrome wrapper | proven for deterministic product-state projection and TUI mounting | required before downstream M5/M6/M7 affordance wrappers call Pi UI primitives | Brunch-host tests + raw TUI transcript proof |
+| Startup spec/session picker | proven for Brunch-owned pre-Pi activation with no implicit transcript resume | required for I22-L | Brunch coordinator/UI tests + `runbooks/verify-startup-no-resume.sh` pty oracle |
+| In-session spec/session picker command | implemented/proven at command-handler seam; manual TUI walkthrough still useful | unlocks reusable spec/session selection beyond startup | Brunch extension command tests + coordinator store oracle |
+| Structured-question response loop | partially proven; product relay pending | required before M5 lens/review affordances depend on structured elicitation | Brunch schema/TUI/editor tests + live Pi RPC editor proof + JSONL exchange-projection tests |
+
+## Evidence inventory
+
+- **Pi version/source:** `pi --version` reports `0.75.4`; audited installed docs under `npm-mariozechner-pi-coding-agent/0.73.1` whose package version is `0.75.4`, plus source at `~/Clones/earendil-works/pi/packages/coding-agent`.
+- **Source audit oracle:** `src/core/slash-commands.ts`, `src/modes/interactive/interactive-mode.ts`, `src/core/agent-session.ts`, `src/core/extensions/runner.ts`, `docs/extensions.md`, `docs/rpc.md`, and `docs/keybindings.md`.
+- **Raw Pi harness oracle:** a temporary project-local Pi extension was loaded with `pi --mode rpc --no-session -e ...`, then deleted after probing. This proves extension command handling, `input` handling, lifecycle cancellation, and RPC-visible `setStatus` / string `setWidget` events. It does **not** prove interactive autocomplete visual behavior.
+- **Brunch-host oracle:** FE-744 now exposes a thin internal extension entrypoint at `src/pi-extensions.ts`, with product modules for chrome (`src/pi-extensions/chrome.ts`), session-lifecycle binding (`session-lifecycle.ts`), command policy (`command-policy.ts`), the spec/session picker (`workspace-dialog.ts` plus private `src/pi-components/workspace-dialog/*` compatibility paths), operational-mode policy (`operational-mode.ts`), fixture-backed mention autocomplete (`mention-autocomplete.ts`), and alternatives cards (`alternatives.ts`). Tests prove one Brunch-owned wrapper drives `setHeader`, owns a live TUI footer compositor over product facts plus Pi footer telemetry, filters out a chrome-owned status key while rendering foreign status entries, publishes diagnostic `setWidget` content, and sets the terminal title from one product-state snapshot. Existing branch-cancellation coverage still protects `I19-L`; spec/session picker tests prove decision UI remains separate from coordinator activation and runs as the same centered overlay component at startup and in-session.
+- **Raw TUI visual oracle:** a temporary extension loaded with `script -q /tmp/brunch-chrome-tui-proof.typescript /bin/bash -lc "pi --no-session -e <temp-extension>"`; the transcript contained `BRUNCH HEADER PROOF`, `BRUNCH FOOTER PROOF`, `Spec: Proof Spec`, `observer: running`, and `lens: problem-framing`, proving header/footer/widget text is actually visible in a live Pi TUI render. The temp extension was deleted after the run.
+- **Raw RPC chrome oracle:** a temporary extension loaded with `pi --mode rpc --no-session -e <temp-extension>` emitted `extension_ui_request` events for `setStatus`, `setWidget`, and `notify`; header/footer/working-indicator calls produced no RPC events as expected from Pi's RPC implementation. The temp extension was deleted after the run.
+- **Live structured-question RPC oracle:** `npm run test:structured-question-rpc-proof` launches a real Pi RPC subprocess with a minimal Brunch structured-question proof extension, observes the documented `extension_ui_request(method: "editor")`, responds with `extension_ui_response(value: schema-tagged JSON)`, and asserts the persisted terminal result details use the same self-contained `brunch.structured_question.result` payload as the TUI/helper path.
+
+## Command inventory and containment matrix
+
+Policy buckets:
+
+- **allow/product-owned:** acceptable only when routed through Brunch-owned behavior or harmless in product shell.
+- **hide:** should not appear as a default Brunch affordance.
+- **block effect:** dangerous downstream effect must be cancelled even if UI exposure remains.
+- **requires Pi policy:** strict command suppression needs a Pi upstream/API seam.
+
+| Command / source | Pi execution path | Brunch policy | Suppression seam | Blocker seam | Residual exposure | API ask |
+| --- | --- | --- | --- | --- | --- | --- |
+| `/settings` | `InteractiveMode.setupEditorSubmitHandler()` opens generic Pi settings | hide | autocomplete wrapper can hide suggestions | none found | exact command still opens settings in interactive mode | command policy needed for strict block |
+| `/model` | interactive built-in; `Ctrl+L` also opens selector; `Ctrl+P` cycles model | hide or replace with Brunch policy | autocomplete/keybinding config can reduce visibility | no extension cancel hook; `model_select` is notification-only | exact slash and keybindings can expose model policy surface | command/keybinding policy needed if strict |
+| `/scoped-models` | interactive built-in selector | hide | autocomplete wrapper | none found | exact command opens Pi selector | command policy needed |
+| `/export` | interactive built-in export | hide unless Brunch adopts it deliberately | autocomplete wrapper | none found | exact command can export Pi session | command policy needed if disallowed |
+| `/import` | interactive built-in import/resume flow | hide/block until Brunch validates session binding | autocomplete wrapper | no general import hook found; switch hooks may cover resulting session switch only | import UI can start before any cancel path | command policy needed |
+| `/share` | interactive built-in gist share | hide/block | autocomplete wrapper | none found | exact command exposes non-Brunch sharing | command policy needed |
+| `/copy` | interactive built-in clipboard copy | allow-with-low-risk or hide | autocomplete wrapper | none found | harmless but Pi-branded | optional |
+| `/name` | interactive built-in session naming | hide/replace with Brunch session naming | autocomplete wrapper | none found | can mutate Pi display name outside Brunch vocabulary | command policy desirable |
+| `/session` | interactive info pane | hide or allow diagnostic-only | autocomplete wrapper | none found | exposes Pi session stats/identity | optional/desirable |
+| `/changelog` | interactive Pi changelog | hide | autocomplete wrapper | none found | exact command exposes Pi product surface | command policy desirable |
+| `/hotkeys` | interactive Pi hotkeys | hide or replace with Brunch hotkeys | autocomplete wrapper | none found | exact command exposes Pi actions including branch actions | command policy desirable |
+| `/fork` | interactive built-in branch creation after selector | hide + block effect | autocomplete wrapper | `session_before_fork` can cancel | selector/UI may appear before cancel depending path; exact command remains visible | command policy desirable; effect block available |
+| `/clone` | interactive built-in branch duplication | hide + block effect | autocomplete wrapper | `session_before_fork` can cancel | command accepted before cancellation notice | command policy desirable; effect block available |
+| `/tree` | interactive built-in branch navigator | hide + block effect | autocomplete wrapper | `session_before_tree` can cancel/customize | tree UI may start before cancellation path | command policy desirable; effect block available |
+| `/login` / `/logout` | interactive OAuth selectors | hide unless Brunch owns provider setup | autocomplete wrapper | none found | exposes Pi provider auth surface | command policy needed if disallowed |
+| `/new` | interactive session replacement | replace with Brunch same-spec coordinator flow | autocomplete wrapper | `session_before_switch` can cancel raw new-session effect | exact command still starts Pi new-session path before cancellation | command policy or Brunch command replacement needed |
+| `/compact` | interactive/manual compaction | allow only after Brunch context policy exists | autocomplete wrapper | `session_before_compact` can cancel/customize | exact command starts Pi compaction UI/path before cancellation | command policy desirable |
+| `/resume` | interactive session picker | hide/block unless Brunch validates binding | autocomplete wrapper | `session_before_switch` can cancel selected switch | generic picker exposure remains | command policy desirable |
+| `/reload` | interactive resource reload | allow for dev, hide in product | autocomplete wrapper | none found; extension command `ctx.reload()` exists for custom reload | exact command reloads Pi resources/extensions | command policy optional for POC, desirable for product shell |
+| `/quit` | interactive shutdown | allow | autocomplete wrapper not needed | n/a | Pi command name acceptable or replace later | no |
+| Hidden debug/easter egg commands (`/debug`, `/arminsayshi`, `/dementedelves`) | hardcoded in `setupEditorSubmitHandler()` but not advertised in `BUILTIN_SLASH_COMMANDS` | hide/block | not in normal autocomplete inventory | none found | exact command remains callable if known | command policy needed for strict block |
+| Extension commands | `AgentSession.prompt()` checks extension commands before `input` | allow only Brunch-owned names | register only Brunch commands | handler routes writes through Brunch handlers / `CommandExecutor` | built-in name collisions do not override built-ins | no if product-named |
+| Prompt templates | autocomplete + expansion after `input` | hide unless Brunch owns prompt surface | settings/resources policy; `input` can handle before expansion | `input` can intercept template text before expansion | not built-in interactive command risk | optional |
+| Skill commands (`/skill:name`) | autocomplete if `enableSkillCommands`; expansion after `input` | hide in Brunch POC | disable skill commands or autocomplete wrapper | `input` can intercept before expansion | generic Pi skill surface | optional if disabled |
+| RPC-only session commands (`new_session`, `switch_session`, `fork`, `clone`, `compact`) | RPC command handlers | Brunch RPC should expose named product methods instead | not slash autocomplete | lifecycle hooks cancel session replacement/fork effects | raw Pi RPC is not Brunch public API | Brunch wrapper/policy, not Pi interactive policy |
+| Keybindings: model select/cycle, session new/tree/fork/resume, double-Escape tree/fork | `setupKeyHandlers()` and settings | hide/block branch/model/session generic flows | keybindings config can unbind some defaults; settings can set double-Escape to `none` | lifecycle hooks for session replacement/fork/tree | keyboard route can bypass slash autocomplete visibility | command/keybinding policy desirable |
+
+## Autocomplete and execution findings
+
+### Autocomplete filtering
+
+`InteractiveMode.createBaseAutocompleteProvider()` builds a `CombinedAutocompleteProvider` from:
+
+1. `BUILTIN_SLASH_COMMANDS`,
+2. prompt templates,
+3. extension commands that do not conflict with built-ins,
+4. skill commands when `settingsManager.getEnableSkillCommands()` is true.
+
+`setupAutocompleteProvider()` then applies extension-provided autocomplete wrappers. `docs/extensions.md` documents `ctx.ui.addAutocompleteProvider((current) => ...)`, including delegation to the previous provider for file/path completion and custom `#` completions. Therefore a Brunch allowlist wrapper should be able to hide disallowed slash suggestions while delegating file/path and future `#` mention completion.
+
+**Limit:** this is visibility suppression only. It does not change exact slash execution.
+
+### Autocomplete persistence and reference interpretation
+
+Pi autocomplete persists only the text inserted into the editor. For both file completion and custom providers such as Pi's `github-issue-autocomplete.ts`, the `AutocompleteItem.value` becomes ordinary user-message text in the session transcript; the popup `label` and `description` are display-only and do not become hidden session metadata. The GitHub example inserts `#123`; it does not persist issue title/state, nor provide a resolver tool by itself.
+
+Brunch `#` mentions must therefore use a stable inserted handle (`#A12`, `#I7`, or a stable node id) as the durable transcript reference. If the agent needs deeper detail, Brunch must teach that convention through `before_agent_start` system-prompt injection and provide a read-only lookup/re-read tool that resolves the handle against the local graph DB. Any structured mention ledger or staleness state is Brunch-owned parsing/indexing work layered after insertion; it is not supplied by Pi autocomplete.
+
+The product `src/pi-extensions/mention-autocomplete.ts` follows this model: it inserts stable graph-code handles from an injectable Brunch mention source, explains via `before_agent_start` that labels/descriptions are UI-only, and leaves deeper detail lookup to future Brunch graph read tools.
+
+### Exact slash execution
+
+`InteractiveMode.setupEditorSubmitHandler()` handles built-ins directly before normal `AgentSession.prompt()` flow. `AgentSession.prompt()` handles extension commands first, then emits `input`, then expands skills/templates. Therefore extension `input` interception cannot reliably block exact interactive built-ins such as `/settings`, `/model`, `/fork`, `/tree`, `/new`, `/compact`, `/resume`, or `/quit`, because they have already been consumed by interactive mode.
+
+Raw RPC probe corroborates the order split rather than replacing the source audit:
+
+- `/brunch-probe` extension command executed immediately and emitted RPC `extension_ui_request` events for `setStatus`, `setWidget`, and `notify`.
+- `/brunch-block-me` was not an extension command; the `input` hook handled it and skipped agent execution.
+- `/settings` in RPC mode was not a built-in command; it entered normal prompt flow as user text. This confirms built-ins are interactive-only; it does not prove interactive suppression.
+
+### Extension command collisions
+
+`InteractiveMode.getBuiltInCommandConflictDiagnostics()` warns on extension commands with built-in names and skips conflicting built-in-name extension commands from autocomplete. `ExtensionRunner.resolveRegisteredCommands()` suffixes duplicate extension commands (`name:1`, `name:2`). Extension commands therefore cannot override `/model`, `/settings`, or other built-ins. Brunch commands should use product names unless Pi grows a command-policy seam.
+
+## Branch-flow guard evidence
+
+Lifecycle hooks provide effect blocking for branch/session transitions even though they do not fully suppress the generic Pi UI surface.
+
+- `session_before_fork` cancels `/fork`, `/clone`, and RPC `fork`/`clone` effects.
+- `session_before_tree` cancels `/tree` navigation effects.
+- `session_before_switch` cancels `/new`, `/resume`, RPC `new_session`, and RPC `switch_session` effects.
+- `session_before_compact` can cancel/customize `/compact`, but compaction policy is not identical to branch policy.
+
+Raw RPC probe results with the temporary extension:
+
+```json
+{"id":"new","type":"response","command":"new_session","success":true,"data":{"cancelled":true}}
+{"id":"clone","type":"response","command":"clone","success":true,"data":{"cancelled":true}}
+```
+
+The same probe emitted corresponding `notify` requests (`cancel switch new`, `cancel fork/clone`). No Brunch product transcript fixture was created; the probe used `--no-session`.
+
+## Brunch extension layout and dynamic chrome proof
+
+The Brunch extension entrypoint is intentionally a registration map. `src/pi-extensions.ts` composes flat product-owned modules by Pi surface/responsibility:
+
+- `chrome.ts` owns `BrunchChromeState`, reusable formatting helpers, and `renderBrunchChrome()`.
+- `session-lifecycle.ts` owns coordinator refresh calls on Pi session lifecycle events.
+- `command-policy.ts` owns branch/session effect blocking for unsupported Pi flows.
+- `workspace-dialog.ts` owns `/brunch`, `ctrl+shift+b`, and the in-session spec/session picker activation adapter.
+- `operational-mode.ts` owns the current `elicit` read-only tool policy pending transcript-backed runtime state.
+- `mention-autocomplete.ts` owns fixture-backed `#` mention autocomplete.
+- `alternatives.ts` owns the transcript-persistent alternatives/card primitive, using reusable widgets from `src/pi-components/*`.
+
+`renderBrunchChrome(ctx.ui, state)` is the product-named wrapper downstream affordances should call instead of scattering raw Pi UI calls. The current code renders only facts present in `BrunchChromeState`:
+
+- header: plain wordmark plus runtime-state initialization summary, active spec, real activated session id/label, and phase;
+- footer: a live TUI compositor that combines product facts from `BrunchChromeState` with Pi footer telemetry (`footerData.getGitBranch()` and foreign `ctx.ui.setStatus()` entries);
+- widget: cwd, spec, session, runtime, context, and chat-mode diagnostics;
+- title: compact Brunch-owned terminal title derived from activated workspace state.
+
+The wrapper uses plain, narrow-terminal-safe text/glyphs (`brunch`, `·`) and does not depend on Pi branding/footer text as the primary product surface. Header/footer rendering is TUI-only; widget/title provide deterministic state strings for tests and RPC-compatible clients. `ctx.ui.setStatus(key, text)` remains available as a lateral contribution channel for other extensions and future dynamic Brunch state; the chrome wrapper does not publish a `brunch.chrome` status key and filters that key if a stale producer contributes it. The wrapper deliberately does not fabricate build version, worker state, coherence verdicts, establishment offers, or a working-indicator abstraction until those producers exist. `session_start` reconstructs chrome from the supplied product snapshot, and replacement-session binding still runs through the existing session-lifecycle hooks before rendering. Reload/session replacement therefore requires callers to provide a fresh product snapshot; the wrapper does not own durable state.
+
+Observed behavior:
+
+| Scenario | Result | Evidence |
+| --- | --- | --- |
+| Idle TUI mount | Header, footer, status, diagnostic widget, and title are called from one snapshot; tests assert the same formatter output used by the wrapper. | `src/brunch-tui.test.ts` |
+| `/reload` / extension reload | Chrome is not durable inside Pi UI; reload must rerun extension setup and call `renderBrunchChrome` with a fresh Brunch snapshot. | source/API behavior; wrapper is stateless by design |
+| Session replacement / selected-session reopen | Existing Brunch extension calls the session-lifecycle binding hook on `session_start`, `before_agent_start`, and assistant `message_start`; `session_start` then renders chrome for the supplied workspace snapshot. The `/brunch` settings-switcher action activates decisions through the coordinator, calls `ctx.switchSession()`, and renders fresh chrome/notification only through `withSession` replacement context. | `src/brunch-tui.test.ts` |
+| RPC degradation | `setStatus`, string-array `setWidget`, `setTitle`, and `notify` emit RPC `extension_ui_request` events; `setHeader`, `setFooter`, and `setWorkingIndicator` are RPC no-ops. Brunch chrome currently uses TUI-only header/footer plus diagnostic widget/title; fixture drivers should not assert TUI-only header/footer or a chrome-owned status key. | Pi RPC source + temp RPC JSONL probe |
+
+## Startup/splash logo asset decision
+
+Brunch should render the startup/splash logo as TUI chrome, not as a session message, so it does not persist in the transcript/log. For the preferred blocky aesthetic, the selected rendering is a pre-generated Chafa Unicode-symbol asset rather than runtime image rendering:
+
+- Source PNG copied from the legacy Brunch app to `src/pi-components/workspace-dialog/assets/brunch.png`.
+- Preferred splash asset: `src/pi-components/workspace-dialog/assets/brunch-logo-quad-56x18.ansi`.
+- Lower-color fallback asset: `src/pi-components/workspace-dialog/assets/brunch-logo-quad-56x18-240.ansi`.
+- The build copies those assets to `dist/pi-components/workspace-dialog/assets` so runtime code can read them beside the compiled component.
+
+The selected generator command for the preferred asset is:
+
+```sh
+chafa -f symbols \
+  --symbols=quad \
+  --colors=full \
+  --color-space=din99d \
+  --color-extractor=median \
+  --bg=black \
+  --size=56x18 \
+  src/pi-components/workspace-dialog/assets/brunch.png > src/pi-components/workspace-dialog/assets/brunch-logo-quad-56x18.ansi
+```
+
+Runtime should **not** invoke Chafa on startup. The logo should be deterministic, cheap to render, and independent of host-installed CLI tools. Chafa is therefore a maintainer/dev tool at most, not a runtime dependency. Startup chrome should choose `brunch-logo-quad-56x18.ansi` when truecolor is available, otherwise `brunch-logo-quad-56x18-240.ansi`; for very limited terminals, a plain `brunch` wordmark is sufficient rather than carrying 16-color or 8-color assets.
+
+## Workspace dialog implementation evidence
+
+Startup now runs through Brunch-owned inventory and activation before Pi `InteractiveMode` starts. `.brunch/state.json` accelerates defaults but does not implicitly resume the prior transcript; the pure spec/session picker UI returns `continue` / `openSession` / `newSession` / `newSpec` / `cancel`, and `WorkspaceSessionCoordinator.activateWorkspace()` owns all session creation/opening, binding, and state-file effects.
+
+The executable pty oracle is `runbooks/verify-startup-no-resume.sh`. It builds the project, seeds a scratch workspace with a unique stale transcript sentinel, launches `brunch --mode tui` under `script`, strips ANSI/control sequences, and asserts the first captured startup screen contains spec/session picker markers and not the stale transcript text. This is a middle-loop/manual oracle, not part of `npm run verify`, because pty behavior is host-sensitive.
+
+The in-session product command is `/brunch` with `ctrl+shift+b`. It waits for idle, inspects inventory, renders the same typed centered spec/session picker with `ctx.ui.custom(..., { overlay: true })`, activates the returned decision through the coordinator, and then calls `ctx.switchSession()` only for the already-activated target file. Post-switch chrome and notification use the `withSession` replacement context only; cancel and `needs_human` decisions notify without switching. This does not override `/resume`, `/new`, or other built-ins; it is the Brunch-owned workspace adapter over Pi's session-replacement API.
+
+## Pi example evidence not yet Brunch integration proof
+
+Reviewed Pi docs/examples remain useful for downstream M5/M6/M7 affordance design, but they are not interchangeable with Brunch-host proof:
+
+| Example/source affordance | Evidence status | Brunch interpretation |
+| --- | --- | --- |
+| `question` / `questionnaire` typed UI patterns | Pi example/source evidence | Suitable model for future structured elicitation/review surfaces; Brunch has only proven typed custom spec/session decisions so far. |
+| `shutdown-command` | Pi example evidence | Confirms commands can drive lifecycle actions; Brunch has not added a product shutdown command beyond allowing Pi quit. |
+| `structured-output` | Pi example evidence | Relevant to future agent/tool result rendering, not current workspace-dialog proof. |
+| `titlebar-spinner` / working indicator examples | Pi example evidence only | Brunch leaves Pi's working indicator untouched; custom spinner styling is deferred until a live side-task/reviewer spinner is product-proven. |
+| `custom-header` / `custom-footer` | Raw Pi TUI proof plus Brunch wrapper tests | Brunch uses header for product identity and restores the default footer; replacing the footer should remain intentional. |
+| `status-line` / `border-status-editor` | Pi example plus Brunch wrapper tests | Supports lateral extension status contributions; Brunch chrome currently renders foreign statuses in the TUI footer and uses widget diagnostics rather than publishing its own status key or replacing the editor/border. |
+
+## RPC controllability observations relevant to command containment and chrome
+
+Raw Pi RPC success is not Brunch integration proof, but it matters for the fixture-driver oracle:
+
+- Extension command handlers are RPC-invocable via `prompt` for extension command names.
+- `ctx.ui.setStatus()` emits RPC `extension_ui_request` with method `setStatus`.
+- `ctx.ui.setWidget()` emits RPC `extension_ui_request` with method `setWidget` when the widget is a string array.
+- `ctx.ui.setTitle()` emits RPC `extension_ui_request` with method `setTitle`.
+- `ctx.ui.notify()` emits RPC `extension_ui_request` with method `notify`.
+- `ctx.ui.setHeader()`, `ctx.ui.setFooter()`, and `ctx.ui.setWorkingIndicator()` are TUI-only in current Pi RPC mode and should be treated as no-ops for fixture-driver expectations.
+- Built-in interactive slash commands are not included in RPC `prompt` handling as built-ins; Brunch must not infer interactive command safety from RPC prompt behavior.
+
+## Minimum Pi API ask
+
+Strict Brunch product-shell containment needs an upstream command/keybinding policy seam. A minimal shape would be either session/interactive-mode options or extension API:
+
+```ts
+pi.setCommandPolicy({
+  hiddenBuiltins: ["settings", "model", "scoped-models", "export", "import", "share", "fork", "clone", "tree", "login", "logout", "new", "resume"],
+  blockedBuiltins: ["fork", "clone", "tree", "new", "resume", "settings", "model"],
+  onBlockedBuiltin: async (name, ctx) => ctx.ui.notify(`/${name} is not available in Brunch`, "warning"),
+});
+```
+
+Equivalent launch-time option:
+
+```ts
+allowedBuiltInCommands: ["compact", "reload", "quit"]
+```
+
+The policy must run before interactive-mode built-in dispatch and before autocomplete construction. Ideally it should also expose a keybinding-action policy for `app.model.*` and `app.session.*` actions so keyboard paths cannot bypass slash visibility.
+
+## Structured-question / RPC-relay gap
+
+The remaining live FE-744 gap is not generic UI polish. Brunch has now proven the private adapter/projection parts of the loop: the structured-question helper produces self-contained terminal result details, rich TUI paths can collect answers through `ctx.ui.custom()`, raw Pi RPC can round-trip schema-tagged JSON through `ctx.ui.editor()` in a live subprocess proof, and elicitation-exchange projection classifies terminal structured-question `toolResult.details` as response-side transcript entries while preserving ordinary tool results as prompt-side. The remaining gap is the public Brunch product relay: exposing pending Pi extension-UI requests as product-shaped RPC state/events for web/CLI clients, then translating product responses back into Pi's documented `extension_ui_response` messages.
+
+Pi source/docs already give strong evidence for the primitive:
+
+- `docs/usage.md` states that the editor can be temporarily replaced by custom extension UI.
+- `docs/tui.md` documents `ctx.ui.custom<T>()` for editor-area replacement and `ctx.ui.setEditorComponent()` for replacing the main input editor.
+- `examples/extensions/question.ts` proves a registered tool can ask a single-choice question with optional freeform input and persist the answer in `toolResult.details`.
+- `examples/extensions/questionnaire.ts` proves a registered tool can ask a multi-question questionnaire and persist the full answer set in `toolResult.details`.
+- `examples/extensions/rpc-demo.ts` and `examples/rpc-extension-ui.ts` prove Pi RPC can carry supported extension UI requests, including `editor`, through `extension_ui_request` / `extension_ui_response`.
+- `examples/extensions/message-renderer.ts` proves custom transcript display, but display alone does not collect a response.
+
+The seam Brunch must still prove is the public product relay around that composition: assistant tool/custom prompt → pending Brunch elicitation state/event over the single public RPC surface → product response from web/CLI probe → Pi `extension_ui_response` → self-contained structured result in Pi JSONL → existing response-side exchange projection. The trimmed working plan remains in `docs/architecture/pi-ui-extension-patterns-provisional-plan.md` until that relay is implemented or deliberately moved into a named M5 slice.
+
+| Residual affordance | Current posture | Carry-forward obligation |
+| --- | --- | --- |
+| Elicitation-first session loop | Missing and POC-critical. | A session can begin from a system/assistant question or offer without ambient user chat; unresolved interactions own the response surface until answered, skipped, cancelled, or marked unavailable. |
+| Registered structured-question tool seam | Brunch result-builder/schema tests cover self-contained `toolResult.details`; exchange projection now classifies terminal structured-question results as response-side entries. | Continue classifying by typed details, not tool name, so unrelated tool results remain prompt-side. |
+| TUI input replacement | Brunch adapter tests prove `ctx.ui.custom()` collection for text, single-select, multi-select, questionnaire, and terminal statuses. | Keep UX refinements separate from the proof seam; future richer surfaces should reuse the same terminal-result discipline. |
+| JSON-editor RPC fallback | Brunch helper tests and `npm run test:structured-question-rpc-proof` prove schema-tagged JSON over Pi RPC `ctx.ui.editor` at the adapter level; public product relay is still missing. | Treat JSON-over-editor as a Pi adapter behind Brunch public RPC, not as a second product API or raw UX contract. |
+| Review-set decisions | Depends on the same terminal structured-result discipline. | Approve routes to one `acceptReviewSet` command; request-changes appends a successor proposal; reject persists a terminal response. |
+| Pickers and orientation views | Workspace switcher proves pure decision UI. | Reuse the same decision-returning shape; coordinator or command-layer code owns mutations. |
+| Live Pi harness probes | Useful for fast source/API validation but not Brunch-host proof. | Keep scratch extensions temporary, record evidence tier, and promote only product-named wrappers that survive the spike. |
+
+## Downstream posture
+
+- For the POC, Brunch can plausibly proceed if it hides disallowed commands from autocomplete and blocks branch/session effects with lifecycle hooks, **provided product documentation does not claim strict built-in suppression**.
+- Dynamic Brunch chrome is strong enough to make the primary idle/working TUI surface read as Brunch-owned in a local proof, but exact built-in commands remain a residual shell-containment risk for product review.
+- `I19-L` remains protected by effect blocking and transcript-reader fail-fast behavior, not by complete command invisibility.
+- M5/M6/M7 should route Brunch actions through Brunch-owned command names and handlers; extension command collisions are not an override mechanism.
+- M5/M6/M7 chrome/status affordances should call Brunch product wrappers (`renderBrunchChrome` or successors) instead of raw Pi `ctx.ui.*` primitives.
+- Future switcher/review/elicitation commands should follow the `/brunch` menu pattern: product-owned names, typed default `ctx.ui.custom()` decision components unless richer modal behavior is specifically needed, coordinator/command-layer activation, and replacement-session work only through `withSession` contexts.
+- A strict upstream Pi command-policy API is required before Brunch can honestly claim Pi's generic shell is unavailable rather than merely discouraged/guarded.
+
+## Open evidence gaps
+
+- Interactive autocomplete filtering was source-proven but not visually observed in a TUI session from this API-only run.
+- Exact interactive `/fork`, `/tree`, `/new`, and `/resume` pre-cancel UI exposure should be manually observed in Brunch TUI or a controlled Pi TUI before product signoff.
+- Keybinding unbinding/configuration strategy remains source-audited only; no Brunch-owned keybinding settings wrapper has been tested.
+- The startup no-resume oracle is executable and passed locally, but it is intentionally not a default CI gate because pty/script behavior is host-sensitive.
+- The in-session `/brunch` menu and workspace/session action are unit-proven at the handler/replacement-context seam; a qualitative manual TUI walkthrough should still confirm interaction feel and final chrome/session id in a live Pi runtime.
+- Dynamic chrome was visually proven in a raw Pi TUI harness and unit-proven in Brunch; a full Brunch-host manual walkthrough remains useful before product signoff because the temp TUI proof did not exercise real coordinator-derived graph/lens/coherence data.
diff --git a/archive/docs/archive/PLAN_HISTORY.md b/docs/archive/PLAN_HISTORY.md
similarity index 100%
rename from archive/docs/archive/PLAN_HISTORY.md
rename to docs/archive/PLAN_HISTORY.md
diff --git a/docs/reference/pi-extensions.md b/docs/reference/pi-extensions.md
new file mode 100644
index 00000000..6426096f
--- /dev/null
+++ b/docs/reference/pi-extensions.md
@@ -0,0 +1,2596 @@
+> pi can create extensions. Ask it to build one for your use case.
+
+# Extensions
+
+Extensions are TypeScript modules that extend pi's behavior. They can subscribe to lifecycle events, register custom tools callable by the LLM, add commands, and more.
+
+> **Placement for /reload:** Put extensions in `~/.pi/agent/extensions/` (global) or `.pi/extensions/` (project-local) for auto-discovery. Use `pi -e ./path.ts` only for quick tests. Extensions in auto-discovered locations can be hot-reloaded with `/reload`.
+
+**Key capabilities:**
+- **Custom tools** - Register tools the LLM can call via `pi.registerTool()`
+- **Event interception** - Block or modify tool calls, inject context, customize compaction
+- **User interaction** - Prompt users via `ctx.ui` (select, confirm, input, notify)
+- **Custom UI components** - Full TUI components with keyboard input via `ctx.ui.custom()` for complex interactions
+- **Custom commands** - Register commands like `/mycommand` via `pi.registerCommand()`
+- **Session persistence** - Store state that survives restarts via `pi.appendEntry()`
+- **Custom rendering** - Control how tool calls/results and messages appear in TUI
+
+**Example use cases:**
+- Permission gates (confirm before `rm -rf`, `sudo`, etc.)
+- Git checkpointing (stash at each turn, restore on branch)
+- Path protection (block writes to `.env`, `node_modules/`)
+- Custom compaction (summarize conversation your way)
+- Conversation summaries (see `summarize.ts` example)
+- Interactive tools (questions, wizards, custom dialogs)
+- Stateful tools (todo lists, connection pools)
+- External integrations (file watchers, webhooks, CI triggers)
+- Games while you wait (see `snake.ts` example)
+
+See [examples/extensions/](../examples/extensions/) for working implementations.
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Extension Locations](#extension-locations)
+- [Available Imports](#available-imports)
+- [Writing an Extension](#writing-an-extension)
+  - [Extension Styles](#extension-styles)
+- [Events](#events)
+  - [Lifecycle Overview](#lifecycle-overview)
+  - [Resource Events](#resource-events)
+  - [Session Events](#session-events)
+  - [Agent Events](#agent-events)
+  - [Model Events](#model-events)
+  - [Tool Events](#tool-events)
+- [ExtensionContext](#extensioncontext)
+- [ExtensionCommandContext](#extensioncommandcontext)
+- [ExtensionAPI Methods](#extensionapi-methods)
+- [State Management](#state-management)
+- [Custom Tools](#custom-tools)
+- [Custom UI](#custom-ui)
+- [Error Handling](#error-handling)
+- [Mode Behavior](#mode-behavior)
+- [Examples Reference](#examples-reference)
+
+## Quick Start
+
+Create `~/.pi/agent/extensions/my-extension.ts`:
+
+```typescript
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+export default function (pi: ExtensionAPI) {
+  // React to events
+  pi.on("session_start", async (_event, ctx) => {
+    ctx.ui.notify("Extension loaded!", "info");
+  });
+
+  pi.on("tool_call", async (event, ctx) => {
+    if (event.toolName === "bash" && event.input.command?.includes("rm -rf")) {
+      const ok = await ctx.ui.confirm("Dangerous!", "Allow rm -rf?");
+      if (!ok) return { block: true, reason: "Blocked by user" };
+    }
+  });
+
+  // Register a custom tool
+  pi.registerTool({
+    name: "greet",
+    label: "Greet",
+    description: "Greet someone by name",
+    parameters: Type.Object({
+      name: Type.String({ description: "Name to greet" }),
+    }),
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      return {
+        content: [{ type: "text", text: `Hello, ${params.name}!` }],
+        details: {},
+      };
+    },
+  });
+
+  // Register a command
+  pi.registerCommand("hello", {
+    description: "Say hello",
+    handler: async (args, ctx) => {
+      ctx.ui.notify(`Hello ${args || "world"}!`, "info");
+    },
+  });
+}
+```
+
+Test with `--extension` (or `-e`) flag:
+
+```bash
+pi -e ./my-extension.ts
+```
+
+## Extension Locations
+
+> **Security:** Extensions run with your full system permissions and can execute arbitrary code. Only install from sources you trust.
+
+Extensions are auto-discovered from:
+
+| Location                            | Scope                        |
+| ----------------------------------- | ---------------------------- |
+| `~/.pi/agent/extensions/*.ts`       | Global (all projects)        |
+| `~/.pi/agent/extensions/*/index.ts` | Global (subdirectory)        |
+| `.pi/extensions/*.ts`               | Project-local                |
+| `.pi/extensions/*/index.ts`         | Project-local (subdirectory) |
+
+Additional paths via `settings.json`:
+
+```json
+{
+  "packages": [
+    "npm:@foo/bar@1.0.0",
+    "git:github.com/user/repo@v1"
+  ],
+  "extensions": [
+    "/path/to/local/extension.ts",
+    "/path/to/local/extension/dir"
+  ]
+}
+```
+
+To share extensions via npm or git as pi packages, see [packages.md](packages.md).
+
+## Available Imports
+
+| Package                           | Purpose                                                      |
+| --------------------------------- | ------------------------------------------------------------ |
+| `@earendil-works/pi-coding-agent` | Extension types (`ExtensionAPI`, `ExtensionContext`, events) |
+| `typebox`                         | Schema definitions for tool parameters                       |
+| `@earendil-works/pi-ai`           | AI utilities (`StringEnum` for Google-compatible enums)      |
+| `@earendil-works/pi-tui`          | TUI components for custom rendering                          |
+
+npm dependencies work too. Add a `package.json` next to your extension (or in a parent directory), run `npm install`, and imports from `node_modules/` are resolved automatically.
+
+For distributed pi packages installed with `pi install` (npm or git), runtime deps must be in `dependencies`. Package installation uses production installs (`npm install --omit=dev`) by default, so `devDependencies` are not available at runtime; when `npmCommand` is configured, git packages use plain `install` for compatibility with wrappers.
+
+Node.js built-ins (`node:fs`, `node:path`, etc.) are also available.
+
+## Writing an Extension
+
+An extension exports a default factory function that receives `ExtensionAPI`. The factory can be synchronous or asynchronous:
+
+```typescript
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+  // Subscribe to events
+  pi.on("event_name", async (event, ctx) => {
+    // ctx.ui for user interaction
+    const ok = await ctx.ui.confirm("Title", "Are you sure?");
+    ctx.ui.notify("Done!", "info");
+    ctx.ui.setStatus("my-ext", "Processing...");  // Footer status
+    ctx.ui.setWidget("my-ext", ["Line 1", "Line 2"]);  // Widget above editor (default)
+  });
+
+  // Register tools, commands, shortcuts, flags
+  pi.registerTool({ ... });
+  pi.registerCommand("name", { ... });
+  pi.registerShortcut("ctrl+x", { ... });
+  pi.registerFlag("my-flag", { ... });
+}
+```
+
+Extensions are loaded via [jiti](https://github.com/unjs/jiti), so TypeScript works without compilation.
+
+If the factory returns a `Promise`, pi awaits it before continuing startup. That means async initialization completes before `session_start`, before `resources_discover`, and before provider registrations queued via `pi.registerProvider()` are flushed.
+
+### Async factory functions
+
+Use an async factory for one-time startup work such as fetching remote configuration or dynamically discovering available models.
+
+```typescript
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export default async function (pi: ExtensionAPI) {
+  const response = await fetch("http://localhost:1234/v1/models");
+  const payload = (await response.json()) as {
+    data: Array<{
+      id: string;
+      name?: string;
+      context_window?: number;
+      max_tokens?: number;
+    }>;
+  };
+
+  pi.registerProvider("local-openai", {
+    baseUrl: "http://localhost:1234/v1",
+    apiKey: "LOCAL_OPENAI_API_KEY",
+    api: "openai-completions",
+    models: payload.data.map((model) => ({
+      id: model.id,
+      name: model.name ?? model.id,
+      reasoning: false,
+      input: ["text"],
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+      contextWindow: model.context_window ?? 128000,
+      maxTokens: model.max_tokens ?? 4096,
+    })),
+  });
+}
+```
+
+This pattern makes the fetched models available during normal startup and to `pi --list-models`.
+
+### Extension Styles
+
+**Single file** - simplest, for small extensions:
+
+```
+~/.pi/agent/extensions/
+└── my-extension.ts
+```
+
+**Directory with index.ts** - for multi-file extensions:
+
+```
+~/.pi/agent/extensions/
+└── my-extension/
+    ├── index.ts        # Entry point (exports default function)
+    ├── tools.ts        # Helper module
+    └── utils.ts        # Helper module
+```
+
+**Package with dependencies** - for extensions that need npm packages:
+
+```
+~/.pi/agent/extensions/
+└── my-extension/
+    ├── package.json    # Declares dependencies and entry points
+    ├── package-lock.json
+    ├── node_modules/   # After npm install
+    └── src/
+        └── index.ts
+```
+
+```json
+// package.json
+{
+  "name": "my-extension",
+  "dependencies": {
+    "zod": "^3.0.0",
+    "chalk": "^5.0.0"
+  },
+  "pi": {
+    "extensions": ["./src/index.ts"]
+  }
+}
+```
+
+Run `npm install` in the extension directory, then imports from `node_modules/` work automatically.
+
+## Events
+
+### Lifecycle Overview
+
+```
+pi starts
+  │
+  ├─► session_start { reason: "startup" }
+  └─► resources_discover { reason: "startup" }
+      │
+      ▼
+user sends prompt ─────────────────────────────────────────┐
+  │                                                        │
+  ├─► (extension commands checked first, bypass if found)  │
+  ├─► input (can intercept, transform, or handle)          │
+  ├─► (skill/template expansion if not handled)            │
+  ├─► before_agent_start (can inject message, modify system prompt)
+  ├─► agent_start                                          │
+  ├─► message_start / message_update / message_end         │
+  │                                                        │
+  │   ┌─── turn (repeats while LLM calls tools) ───┐       │
+  │   │                                            │       │
+  │   ├─► turn_start                               │       │
+  │   ├─► context (can modify messages)            │       │
+  │   ├─► before_provider_request (can inspect or replace payload)
+  │   ├─► after_provider_response (status + headers, before stream consume)
+  │   │                                            │       │
+  │   │   LLM responds, may call tools:            │       │
+  │   │     ├─► tool_execution_start               │       │
+  │   │     ├─► tool_call (can block)              │       │
+  │   │     ├─► tool_execution_update              │       │
+  │   │     ├─► tool_result (can modify)           │       │
+  │   │     └─► tool_execution_end                 │       │
+  │   │                                            │       │
+  │   └─► turn_end                                 │       │
+  │                                                        │
+  └─► agent_end                                            │
+                                                           │
+user sends another prompt ◄────────────────────────────────┘
+
+/new (new session) or /resume (switch session)
+  ├─► session_before_switch (can cancel)
+  ├─► session_shutdown
+  ├─► session_start { reason: "new" | "resume", previousSessionFile? }
+  └─► resources_discover { reason: "startup" }
+
+/fork or /clone
+  ├─► session_before_fork (can cancel)
+  ├─► session_shutdown
+  ├─► session_start { reason: "fork", previousSessionFile }
+  └─► resources_discover { reason: "startup" }
+
+/compact or auto-compaction
+  ├─► session_before_compact (can cancel or customize)
+  └─► session_compact
+
+/tree navigation
+  ├─► session_before_tree (can cancel or customize)
+  └─► session_tree
+
+/model or Ctrl+P (model selection/cycling)
+  ├─► thinking_level_select (if model change changes/clamps thinking level)
+  └─► model_select
+
+thinking level changes (settings, keybinding, pi.setThinkingLevel())
+  └─► thinking_level_select
+
+exit (Ctrl+C, Ctrl+D, SIGHUP, SIGTERM)
+  └─► session_shutdown
+```
+
+### Resource Events
+
+#### resources_discover
+
+Fired after `session_start` so extensions can contribute additional skill, prompt, and theme paths.
+The startup path uses `reason: "startup"`. Reload uses `reason: "reload"`.
+
+```typescript
+pi.on("resources_discover", async (event, _ctx) => {
+  // event.cwd - current working directory
+  // event.reason - "startup" | "reload"
+  return {
+    skillPaths: ["/path/to/skills"],
+    promptPaths: ["/path/to/prompts"],
+    themePaths: ["/path/to/themes"],
+  };
+});
+```
+
+### Session Events
+
+See [Session Format](session-format.md) for session storage internals and the SessionManager API.
+
+#### session_start
+
+Fired when a session is started, loaded, or reloaded.
+
+```typescript
+pi.on("session_start", async (event, ctx) => {
+  // event.reason - "startup" | "reload" | "new" | "resume" | "fork"
+  // event.previousSessionFile - present for "new", "resume", and "fork"
+  ctx.ui.notify(`Session: ${ctx.sessionManager.getSessionFile() ?? "ephemeral"}`, "info");
+});
+```
+
+#### session_before_switch
+
+Fired before starting a new session (`/new`) or switching sessions (`/resume`).
+
+```typescript
+pi.on("session_before_switch", async (event, ctx) => {
+  // event.reason - "new" or "resume"
+  // event.targetSessionFile - session we're switching to (only for "resume")
+
+  if (event.reason === "new") {
+    const ok = await ctx.ui.confirm("Clear?", "Delete all messages?");
+    if (!ok) return { cancel: true };
+  }
+});
+```
+
+After a successful switch or new-session action, pi emits `session_shutdown` for the old extension instance, reloads and rebinds extensions for the new session, then emits `session_start` with `reason: "new" | "resume"` and `previousSessionFile`.
+Do cleanup work in `session_shutdown`, then reestablish any in-memory state in `session_start`.
+
+#### session_before_fork
+
+Fired when forking via `/fork` or cloning via `/clone`.
+
+```typescript
+pi.on("session_before_fork", async (event, ctx) => {
+  // event.entryId - ID of the selected entry
+  // event.position - "before" for /fork, "at" for /clone
+  return { cancel: true }; // Cancel fork/clone
+  // OR
+  return { skipConversationRestore: true }; // Reserved for future conversation restore control
+});
+```
+
+After a successful fork or clone, pi emits `session_shutdown` for the old extension instance, reloads and rebinds extensions for the new session, then emits `session_start` with `reason: "fork"` and `previousSessionFile`.
+Do cleanup work in `session_shutdown`, then reestablish any in-memory state in `session_start`.
+
+#### session_before_compact / session_compact
+
+Fired on compaction. See [compaction.md](compaction.md) for details.
+
+```typescript
+pi.on("session_before_compact", async (event, ctx) => {
+  const { preparation, branchEntries, customInstructions, signal } = event;
+
+  // Cancel:
+  return { cancel: true };
+
+  // Custom summary:
+  return {
+    compaction: {
+      summary: "...",
+      firstKeptEntryId: preparation.firstKeptEntryId,
+      tokensBefore: preparation.tokensBefore,
+    }
+  };
+});
+
+pi.on("session_compact", async (event, ctx) => {
+  // event.compactionEntry - the saved compaction
+  // event.fromExtension - whether extension provided it
+});
+```
+
+#### session_before_tree / session_tree
+
+Fired on `/tree` navigation. See [Sessions](sessions.md) for tree navigation concepts.
+
+```typescript
+pi.on("session_before_tree", async (event, ctx) => {
+  const { preparation, signal } = event;
+  return { cancel: true };
+  // OR provide custom summary:
+  return { summary: { summary: "...", details: {} } };
+});
+
+pi.on("session_tree", async (event, ctx) => {
+  // event.newLeafId, oldLeafId, summaryEntry, fromExtension
+});
+```
+
+#### session_shutdown
+
+Fired before an extension runtime is torn down.
+
+```typescript
+pi.on("session_shutdown", async (event, ctx) => {
+  // event.reason - "quit" | "reload" | "new" | "resume" | "fork"
+  // event.targetSessionFile - destination session for session replacement flows
+  // Cleanup, save state, etc.
+});
+```
+
+### Agent Events
+
+#### before_agent_start
+
+Fired after user submits prompt, before agent loop. Can inject a message and/or modify the system prompt.
+
+```typescript
+pi.on("before_agent_start", async (event, ctx) => {
+  // event.prompt - user's prompt text
+  // event.images - attached images (if any)
+  // event.systemPrompt - current chained system prompt for this handler
+  //   (includes changes from earlier before_agent_start handlers)
+  // event.systemPromptOptions - structured options used to build the system prompt
+  //   .customPrompt - any custom system prompt (from --system-prompt, SYSTEM.md, or custom templates)
+  //   .selectedTools - tools currently active in the prompt
+  //   .toolSnippets - one-line descriptions for each tool
+  //   .promptGuidelines - custom guideline bullets
+  //   .appendSystemPrompt - text from --append-system-prompt flags
+  //   .cwd - working directory
+  //   .contextFiles - AGENTS.md files and other loaded context files
+  //   .skills - loaded skills
+
+  return {
+    // Inject a persistent message (stored in session, sent to LLM)
+    message: {
+      customType: "my-extension",
+      content: "Additional context for the LLM",
+      display: true,
+    },
+    // Replace the system prompt for this turn (chained across extensions)
+    systemPrompt: event.systemPrompt + "\n\nExtra instructions for this turn...",
+  };
+});
+```
+
+The `systemPromptOptions` field gives extensions access to the same structured data Pi uses to build the system prompt. This lets you inspect what Pi has loaded — custom prompts, guidelines, tool snippets, context files, skills — without re-discovering resources or re-parsing flags. Use it when your extension needs to make deep, informed changes to the system prompt while respecting user-provided configuration.
+
+Inside `before_agent_start`, `event.systemPrompt` and `ctx.getSystemPrompt()` both reflect the chained system prompt as of the current handler. Later `before_agent_start` handlers can still modify it again.
+
+#### agent_start / agent_end
+
+Fired once per user prompt.
+
+```typescript
+pi.on("agent_start", async (_event, ctx) => {});
+
+pi.on("agent_end", async (event, ctx) => {
+  // event.messages - messages from this prompt
+});
+```
+
+#### turn_start / turn_end
+
+Fired for each turn (one LLM response + tool calls).
+
+```typescript
+pi.on("turn_start", async (event, ctx) => {
+  // event.turnIndex, event.timestamp
+});
+
+pi.on("turn_end", async (event, ctx) => {
+  // event.turnIndex, event.message, event.toolResults
+});
+```
+
+#### message_start / message_update / message_end
+
+Fired for message lifecycle updates.
+
+- `message_start` and `message_end` fire for user, assistant, and toolResult messages.
+- `message_update` fires for assistant streaming updates.
+- `message_end` handlers can return `{ message }` to replace the finalized message. The replacement must keep the same `role`.
+
+```typescript
+pi.on("message_start", async (event, ctx) => {
+  // event.message
+});
+
+pi.on("message_update", async (event, ctx) => {
+  // event.message
+  // event.assistantMessageEvent (token-by-token stream event)
+});
+
+pi.on("message_end", async (event, ctx) => {
+  if (event.message.role !== "assistant") return;
+
+  return {
+    message: {
+      ...event.message,
+      usage: {
+        ...event.message.usage,
+        cost: {
+          ...event.message.usage.cost,
+          total: 0.123,
+        },
+      },
+    },
+  };
+});
+```
+
+#### tool_execution_start / tool_execution_update / tool_execution_end
+
+Fired for tool execution lifecycle updates.
+
+In parallel tool mode:
+- `tool_execution_start` is emitted in assistant source order during the preflight phase
+- `tool_execution_update` events may interleave across tools
+- `tool_execution_end` is emitted in tool completion order after each tool is finalized
+- final `toolResult` message events are still emitted later in assistant source order
+
+```typescript
+pi.on("tool_execution_start", async (event, ctx) => {
+  // event.toolCallId, event.toolName, event.args
+});
+
+pi.on("tool_execution_update", async (event, ctx) => {
+  // event.toolCallId, event.toolName, event.args, event.partialResult
+});
+
+pi.on("tool_execution_end", async (event, ctx) => {
+  // event.toolCallId, event.toolName, event.result, event.isError
+});
+```
+
+#### context
+
+Fired before each LLM call. Modify messages non-destructively. See [Session Format](session-format.md) for message types.
+
+```typescript
+pi.on("context", async (event, ctx) => {
+  // event.messages - deep copy, safe to modify
+  const filtered = event.messages.filter(m => !shouldPrune(m));
+  return { messages: filtered };
+});
+```
+
+#### before_provider_request
+
+Fired after the provider-specific payload is built, right before the request is sent. Handlers run in extension load order. Returning `undefined` keeps the payload unchanged. Returning any other value replaces the payload for later handlers and for the actual request.
+
+This hook can rewrite provider-level system instructions or remove them entirely. Those payload-level changes are not reflected by `ctx.getSystemPrompt()`, which reports Pi's system prompt string rather than the final serialized provider payload.
+
+```typescript
+pi.on("before_provider_request", (event, ctx) => {
+  console.log(JSON.stringify(event.payload, null, 2));
+
+  // Optional: replace payload
+  // return { ...event.payload, temperature: 0 };
+});
+```
+
+This is mainly useful for debugging provider serialization and cache behavior.
+
+#### after_provider_response
+
+Fired after an HTTP response is received and before its stream body is consumed. Handlers run in extension load order.
+
+```typescript
+pi.on("after_provider_response", (event, ctx) => {
+  // event.status - HTTP status code
+  // event.headers - normalized response headers
+  if (event.status === 429) {
+    console.log("rate limited", event.headers["retry-after"]);
+  }
+});
+```
+
+Header availability depends on provider and transport. Providers that abstract HTTP responses may not expose headers.
+
+### Model Events
+
+#### model_select
+
+Fired when the model changes via `/model` command, model cycling (`Ctrl+P`), or session restore.
+
+```typescript
+pi.on("model_select", async (event, ctx) => {
+  // event.model - newly selected model
+  // event.previousModel - previous model (undefined if first selection)
+  // event.source - "set" | "cycle" | "restore"
+
+  const prev = event.previousModel
+    ? `${event.previousModel.provider}/${event.previousModel.id}`
+    : "none";
+  const next = `${event.model.provider}/${event.model.id}`;
+
+  ctx.ui.notify(`Model changed (${event.source}): ${prev} -> ${next}`, "info");
+});
+```
+
+Use this to update UI elements (status bars, footers) or perform model-specific initialization when the active model changes.
+
+#### thinking_level_select
+
+Fired when the thinking level changes. This is notification-only; handler return values are ignored.
+
+```typescript
+pi.on("thinking_level_select", async (event, ctx) => {
+  // event.level - newly selected thinking level
+  // event.previousLevel - previous thinking level
+
+  ctx.ui.setStatus("thinking", `thinking: ${event.level}`);
+});
+```
+
+Use this to update extension UI when `pi.setThinkingLevel()`, model changes, or built-in thinking-level controls change the active thinking level.
+
+### Tool Events
+
+#### tool_call
+
+Fired after `tool_execution_start`, before the tool executes. **Can block.** Use `isToolCallEventType` to narrow and get typed inputs.
+
+Before `tool_call` runs, pi waits for previously emitted Agent events to finish draining through `AgentSession`. This means `ctx.sessionManager` is up to date through the current assistant tool-calling message.
+
+In the default parallel tool execution mode, sibling tool calls from the same assistant message are preflighted sequentially, then executed concurrently. `tool_call` is not guaranteed to see sibling tool results from that same assistant message in `ctx.sessionManager`.
+
+`event.input` is mutable. Mutate it in place to patch tool arguments before execution.
+
+Behavior guarantees:
+- Mutations to `event.input` affect the actual tool execution
+- Later `tool_call` handlers see mutations made by earlier handlers
+- No re-validation is performed after your mutation
+- Return values from `tool_call` only control blocking via `{ block: true, reason?: string }`
+
+```typescript
+import { isToolCallEventType } from "@earendil-works/pi-coding-agent";
+
+pi.on("tool_call", async (event, ctx) => {
+  // event.toolName - "bash", "read", "write", "edit", etc.
+  // event.toolCallId
+  // event.input - tool parameters (mutable)
+
+  // Built-in tools: no type params needed
+  if (isToolCallEventType("bash", event)) {
+    // event.input is { command: string; timeout?: number }
+    event.input.command = `source ~/.profile\n${event.input.command}`;
+
+    if (event.input.command.includes("rm -rf")) {
+      return { block: true, reason: "Dangerous command" };
+    }
+  }
+
+  if (isToolCallEventType("read", event)) {
+    // event.input is { path: string; offset?: number; limit?: number }
+    console.log(`Reading: ${event.input.path}`);
+  }
+});
+```
+
+#### Typing custom tool input
+
+Custom tools should export their input type:
+
+```typescript
+// my-extension.ts
+export type MyToolInput = Static<typeof myToolSchema>;
+```
+
+Use `isToolCallEventType` with explicit type parameters:
+
+```typescript
+import { isToolCallEventType } from "@earendil-works/pi-coding-agent";
+import type { MyToolInput } from "my-extension";
+
+pi.on("tool_call", (event) => {
+  if (isToolCallEventType<"my_tool", MyToolInput>("my_tool", event)) {
+    event.input.action;  // typed
+  }
+});
+```
+
+#### tool_result
+
+Fired after tool execution finishes and before `tool_execution_end` plus the final tool result message events are emitted. **Can modify result.**
+
+In parallel tool mode, `tool_result` and `tool_execution_end` may interleave in tool completion order, while final `toolResult` message events are still emitted later in assistant source order.
+
+`tool_result` handlers chain like middleware:
+- Handlers run in extension load order
+- Each handler sees the latest result after previous handler changes
+- Handlers can return partial patches (`content`, `details`, or `isError`); omitted fields keep their current values
+
+Use `ctx.signal` for nested async work inside the handler. This lets Esc cancel model calls, `fetch()`, and other abort-aware operations started by the extension.
+
+```typescript
+import { isBashToolResult } from "@earendil-works/pi-coding-agent";
+
+pi.on("tool_result", async (event, ctx) => {
+  // event.toolName, event.toolCallId, event.input
+  // event.content, event.details, event.isError
+
+  if (isBashToolResult(event)) {
+    // event.details is typed as BashToolDetails
+  }
+
+  const response = await fetch("https://example.com/summarize", {
+    method: "POST",
+    body: JSON.stringify({ content: event.content }),
+    signal: ctx.signal,
+  });
+
+  // Modify result:
+  return { content: [...], details: {...}, isError: false };
+});
+```
+
+### User Bash Events
+
+#### user_bash
+
+Fired when user executes `!` or `!!` commands. **Can intercept.**
+
+```typescript
+import { createLocalBashOperations } from "@earendil-works/pi-coding-agent";
+
+pi.on("user_bash", (event, ctx) => {
+  // event.command - the bash command
+  // event.excludeFromContext - true if !! prefix
+  // event.cwd - working directory
+
+  // Option 1: Provide custom operations (e.g., SSH)
+  return { operations: remoteBashOps };
+
+  // Option 2: Wrap pi's built-in local bash backend
+  const local = createLocalBashOperations();
+  return {
+    operations: {
+      exec(command, cwd, options) {
+        return local.exec(`source ~/.profile\n${command}`, cwd, options);
+      }
+    }
+  };
+
+  // Option 3: Full replacement - return result directly
+  return { result: { output: "...", exitCode: 0, cancelled: false, truncated: false } };
+});
+```
+
+### Input Events
+
+#### input
+
+Fired when user input is received, after extension commands are checked but before skill and template expansion. The event sees the raw input text, so `/skill:foo` and `/template` are not yet expanded.
+
+**Processing order:**
+1. Extension commands (`/cmd`) checked first - if found, handler runs and input event is skipped
+2. `input` event fires - can intercept, transform, or handle
+3. If not handled: skill commands (`/skill:name`) expanded to skill content
+4. If not handled: prompt templates (`/template`) expanded to template content
+5. Agent processing begins (`before_agent_start`, etc.)
+
+```typescript
+pi.on("input", async (event, ctx) => {
+  // event.text - raw input (before skill/template expansion)
+  // event.images - attached images, if any
+  // event.source - "interactive" (typed), "rpc" (API), or "extension" (via sendUserMessage)
+
+  // Transform: rewrite input before expansion
+  if (event.text.startsWith("?quick "))
+    return { action: "transform", text: `Respond briefly: ${event.text.slice(7)}` };
+
+  // Handle: respond without LLM (extension shows its own feedback)
+  if (event.text === "ping") {
+    ctx.ui.notify("pong", "info");
+    return { action: "handled" };
+  }
+
+  // Route by source: skip processing for extension-injected messages
+  if (event.source === "extension") return { action: "continue" };
+
+  // Intercept skill commands before expansion
+  if (event.text.startsWith("/skill:")) {
+    // Could transform, block, or let pass through
+  }
+
+  return { action: "continue" };  // Default: pass through to expansion
+});
+```
+
+**Results:**
+- `continue` - pass through unchanged (default if handler returns nothing)
+- `transform` - modify text/images, then continue to expansion
+- `handled` - skip agent entirely (first handler to return this wins)
+
+Transforms chain across handlers. See [input-transform.ts](../examples/extensions/input-transform.ts).
+
+## ExtensionContext
+
+All handlers receive `ctx: ExtensionContext`.
+
+### ctx.ui
+
+UI methods for user interaction. See [Custom UI](#custom-ui) for full details.
+
+### ctx.hasUI
+
+`false` in print mode (`-p`) and JSON mode. `true` in interactive and RPC mode. In RPC mode, dialog methods (`select`, `confirm`, `input`, `editor`) work via the extension UI sub-protocol, and fire-and-forget methods (`notify`, `setStatus`, `setWidget`, `setTitle`, `setEditorText`) emit requests to the client. Some TUI-specific methods are no-ops or return defaults (see [rpc.md](rpc.md#extension-ui-protocol)).
+
+### ctx.cwd
+
+Current working directory.
+
+### ctx.sessionManager
+
+Read-only access to session state. See [Session Format](session-format.md) for the full SessionManager API and entry types.
+
+For `tool_call`, this state is synchronized through the current assistant message before handlers run. In parallel tool execution mode it is still not guaranteed to include sibling tool results from the same assistant message.
+
+```typescript
+ctx.sessionManager.getEntries()       // All entries
+ctx.sessionManager.getBranch()        // Current branch
+ctx.sessionManager.getLeafId()        // Current leaf entry ID
+```
+
+### ctx.modelRegistry / ctx.model
+
+Access to models and API keys.
+
+### ctx.signal
+
+The current agent abort signal, or `undefined` when no agent turn is active.
+
+Use this for abort-aware nested work started by extension handlers, for example:
+- `fetch(..., { signal: ctx.signal })`
+- model calls that accept `signal`
+- file or process helpers that accept `AbortSignal`
+
+`ctx.signal` is typically defined during active turn events such as `tool_call`, `tool_result`, `message_update`, and `turn_end`.
+It is usually `undefined` in idle or non-turn contexts such as session events, extension commands, and shortcuts fired while pi is idle.
+
+```typescript
+pi.on("tool_result", async (event, ctx) => {
+  const response = await fetch("https://example.com/api", {
+    method: "POST",
+    body: JSON.stringify(event),
+    signal: ctx.signal,
+  });
+
+  const data = await response.json();
+  return { details: data };
+});
+```
+
+### ctx.isIdle() / ctx.abort() / ctx.hasPendingMessages()
+
+Control flow helpers.
+
+### ctx.shutdown()
+
+Request a graceful shutdown of pi.
+
+- **Interactive mode:** Deferred until the agent becomes idle (after processing all queued steering and follow-up messages).
+- **RPC mode:** Deferred until the next idle state (after completing the current command response, when waiting for the next command).
+- **Print mode:** No-op. The process exits automatically when all prompts are processed.
+
+Emits `session_shutdown` event to all extensions before exiting. Available in all contexts (event handlers, tools, commands, shortcuts).
+
+```typescript
+pi.on("tool_call", (event, ctx) => {
+  if (isFatal(event.input)) {
+    ctx.shutdown();
+  }
+});
+```
+
+### ctx.getContextUsage()
+
+Returns current context usage for the active model. Uses last assistant usage when available, then estimates tokens for trailing messages.
+
+```typescript
+const usage = ctx.getContextUsage();
+if (usage && usage.tokens > 100_000) {
+  // ...
+}
+```
+
+### ctx.compact()
+
+Trigger compaction without awaiting completion. Use `onComplete` and `onError` for follow-up actions.
+
+```typescript
+ctx.compact({
+  customInstructions: "Focus on recent changes",
+  onComplete: (result) => {
+    ctx.ui.notify("Compaction completed", "info");
+  },
+  onError: (error) => {
+    ctx.ui.notify(`Compaction failed: ${error.message}`, "error");
+  },
+});
+```
+
+### ctx.getSystemPrompt()
+
+Returns Pi's current system prompt string.
+
+- During `before_agent_start`, this reflects chained system-prompt changes made so far for the current turn.
+- It does not include later `context` message mutations.
+- It does not include `before_provider_request` payload rewrites.
+- If later-loaded extensions run after yours, they can still change what is ultimately sent.
+
+```typescript
+pi.on("before_agent_start", (event, ctx) => {
+  const prompt = ctx.getSystemPrompt();
+  console.log(`System prompt length: ${prompt.length}`);
+});
+```
+
+## ExtensionCommandContext
+
+Command handlers receive `ExtensionCommandContext`, which extends `ExtensionContext` with session control methods. These are only available in commands because they can deadlock if called from event handlers.
+
+### ctx.waitForIdle()
+
+Wait for the agent to finish streaming:
+
+```typescript
+pi.registerCommand("my-cmd", {
+  handler: async (args, ctx) => {
+    await ctx.waitForIdle();
+    // Agent is now idle, safe to modify session
+  },
+});
+```
+
+### ctx.newSession(options?)
+
+Create a new session:
+
+```typescript
+const parentSession = ctx.sessionManager.getSessionFile();
+const kickoff = "Continue in the replacement session";
+
+const result = await ctx.newSession({
+  parentSession,
+  setup: async (sm) => {
+    sm.appendMessage({
+      role: "user",
+      content: [{ type: "text", text: "Context from previous session..." }],
+      timestamp: Date.now(),
+    });
+  },
+  withSession: async (ctx) => {
+    // Use only the replacement-session ctx here.
+    await ctx.sendUserMessage(kickoff);
+  },
+});
+
+if (result.cancelled) {
+  // An extension cancelled the new session
+}
+```
+
+Options:
+- `parentSession`: parent session file to record in the new session header
+- `setup`: mutate the new session's `SessionManager` before `withSession` runs
+- `withSession`: run post-switch work against a fresh replacement-session context. Do not use captured old `pi` / command `ctx`; see [Session replacement lifecycle and footguns](#session-replacement-lifecycle-and-footguns).
+
+### ctx.fork(entryId, options?)
+
+Fork from a specific entry, creating a new session file:
+
+```typescript
+const result = await ctx.fork("entry-id-123", {
+  withSession: async (ctx) => {
+    // Use only the replacement-session ctx here.
+    ctx.ui.notify("Now in the forked session", "info");
+  },
+});
+if (result.cancelled) {
+  // An extension cancelled the fork
+}
+
+const cloneResult = await ctx.fork("entry-id-456", { position: "at" });
+if (cloneResult.cancelled) {
+  // An extension cancelled the clone
+}
+```
+
+Options:
+- `position`: `"before"` (default) forks before the selected user message, restoring that prompt into the editor
+- `position`: `"at"` duplicates the active path through the selected entry without restoring editor text
+- `withSession`: run post-switch work against a fresh replacement-session context. Do not use captured old `pi` / command `ctx`; see [Session replacement lifecycle and footguns](#session-replacement-lifecycle-and-footguns).
+
+### ctx.navigateTree(targetId, options?)
+
+Navigate to a different point in the session tree:
+
+```typescript
+const result = await ctx.navigateTree("entry-id-456", {
+  summarize: true,
+  customInstructions: "Focus on error handling changes",
+  replaceInstructions: false, // true = replace default prompt entirely
+  label: "review-checkpoint",
+});
+```
+
+Options:
+- `summarize`: Whether to generate a summary of the abandoned branch
+- `customInstructions`: Custom instructions for the summarizer
+- `replaceInstructions`: If true, `customInstructions` replaces the default prompt instead of being appended
+- `label`: Label to attach to the branch summary entry (or target entry if not summarizing)
+
+### ctx.switchSession(sessionPath, options?)
+
+Switch to a different session file:
+
+```typescript
+const result = await ctx.switchSession("/path/to/session.jsonl", {
+  withSession: async (ctx) => {
+    await ctx.sendUserMessage("Resume work in the replacement session");
+  },
+});
+if (result.cancelled) {
+  // An extension cancelled the switch via session_before_switch
+}
+```
+
+Options:
+- `withSession`: run post-switch work against a fresh replacement-session context. Do not use captured old `pi` / command `ctx`; see [Session replacement lifecycle and footguns](#session-replacement-lifecycle-and-footguns).
+
+To discover available sessions, use the static `SessionManager.list()` or `SessionManager.listAll()` methods:
+
+```typescript
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+
+pi.registerCommand("switch", {
+  description: "Switch to another session",
+  handler: async (args, ctx) => {
+    const sessions = await SessionManager.list(ctx.cwd);
+    if (sessions.length === 0) return;
+    const choice = await ctx.ui.select(
+      "Pick session:",
+      sessions.map(s => s.file),
+    );
+    if (choice) {
+      await ctx.switchSession(choice, {
+        withSession: async (ctx) => {
+          ctx.ui.notify("Switched session", "info");
+        },
+      });
+    }
+  },
+});
+```
+
+### Session replacement lifecycle and footguns
+
+`withSession` receives a fresh `ReplacedSessionContext`, which extends `ExtensionCommandContext` with async `sendMessage()` and `sendUserMessage()` helpers bound to the replacement session.
+
+Lifecycle and footguns:
+- `withSession` runs only after the old session has emitted `session_shutdown`, the old runtime has been torn down, the replacement session has been rebound, and the new extension instance has already received `session_start`.
+- The callback still executes in the original closure, not inside the new extension instance. That means your old extension instance may already have run its shutdown cleanup before `withSession` starts.
+- Captured old `pi` / old command `ctx` session-bound objects are stale after replacement and will throw if used. Use only the `ctx` passed to `withSession` for session-bound work.
+- Previously extracted raw objects are still your responsibility. For example, if you capture `const sm = ctx.sessionManager` before replacement, `sm` is still the old `SessionManager` object. Do not reuse it after replacement.
+- Code in `withSession` should assume any state invalidated by your `session_shutdown` handler is already gone. Only capture plain data that survives shutdown cleanly, such as strings, ids, and serialized config.
+
+Safe pattern:
+
+```typescript
+pi.registerCommand("handoff", {
+  handler: async (_args, ctx) => {
+    const kickoff = "Continue from the replacement session";
+    await ctx.newSession({
+      withSession: async (ctx) => {
+        await ctx.sendUserMessage(kickoff);
+      },
+    });
+  },
+});
+```
+
+Unsafe pattern:
+
+```typescript
+pi.registerCommand("handoff", {
+  handler: async (_args, ctx) => {
+    const oldSessionManager = ctx.sessionManager;
+    await ctx.newSession({
+      withSession: async (_ctx) => {
+        // stale old objects: do not do this
+        oldSessionManager.getSessionFile();
+        pi.sendUserMessage("wrong");
+      },
+    });
+  },
+});
+```
+
+### ctx.reload()
+
+Run the same reload flow as `/reload`.
+
+```typescript
+pi.registerCommand("reload-runtime", {
+  description: "Reload extensions, skills, prompts, and themes",
+  handler: async (_args, ctx) => {
+    await ctx.reload();
+    return;
+  },
+});
+```
+
+Important behavior:
+- `await ctx.reload()` emits `session_shutdown` for the current extension runtime
+- It then reloads resources and emits `session_start` with `reason: "reload"` and `resources_discover` with reason `"reload"`
+- The currently running command handler still continues in the old call frame
+- Code after `await ctx.reload()` still runs from the pre-reload version
+- Code after `await ctx.reload()` must not assume old in-memory extension state is still valid
+- After the handler returns, future commands/events/tool calls use the new extension version
+
+For predictable behavior, treat reload as terminal for that handler (`await ctx.reload(); return;`).
+
+Tools run with `ExtensionContext`, so they cannot call `ctx.reload()` directly. Use a command as the reload entrypoint, then expose a tool that queues that command as a follow-up user message.
+
+Example tool the LLM can call to trigger reload:
+
+```typescript
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+export default function (pi: ExtensionAPI) {
+  pi.registerCommand("reload-runtime", {
+    description: "Reload extensions, skills, prompts, and themes",
+    handler: async (_args, ctx) => {
+      await ctx.reload();
+      return;
+    },
+  });
+
+  pi.registerTool({
+    name: "reload_runtime",
+    label: "Reload Runtime",
+    description: "Reload extensions, skills, prompts, and themes",
+    parameters: Type.Object({}),
+    async execute() {
+      pi.sendUserMessage("/reload-runtime", { deliverAs: "followUp" });
+      return {
+        content: [{ type: "text", text: "Queued /reload-runtime as a follow-up command." }],
+      };
+    },
+  });
+}
+```
+
+## ExtensionAPI Methods
+
+### pi.on(event, handler)
+
+Subscribe to events. See [Events](#events) for event types and return values.
+
+### pi.registerTool(definition)
+
+Register a custom tool callable by the LLM. See [Custom Tools](#custom-tools) for full details.
+
+`pi.registerTool()` works both during extension load and after startup. You can call it inside `session_start`, command handlers, or other event handlers. New tools are refreshed immediately in the same session, so they appear in `pi.getAllTools()` and are callable by the LLM without `/reload`.
+
+Use `pi.setActiveTools()` to enable or disable tools (including dynamically added tools) at runtime.
+
+Use `promptSnippet` to opt a custom tool into a one-line entry in `Available tools`, and `promptGuidelines` to append tool-specific bullets to the default `Guidelines` section when the tool is active.
+
+**Important:** `promptGuidelines` bullets are appended flat to the `Guidelines` section with no tool name prefix. Each guideline must name the tool it refers to — avoid "Use this tool when..." because the LLM cannot tell which tool "this" means. Write "Use my_tool when..." instead.
+
+See [dynamic-tools.ts](../examples/extensions/dynamic-tools.ts) for a full example.
+
+```typescript
+import { Type } from "typebox";
+import { StringEnum } from "@earendil-works/pi-ai";
+
+pi.registerTool({
+  name: "my_tool",
+  label: "My Tool",
+  description: "What this tool does",
+  promptSnippet: "Summarize or transform text according to action",
+  promptGuidelines: ["Use my_tool when the user asks to summarize previously generated text."],
+  parameters: Type.Object({
+    action: StringEnum(["list", "add"] as const),
+    text: Type.Optional(Type.String()),
+  }),
+  prepareArguments(args) {
+    // Optional compatibility shim. Runs before schema validation.
+    // Return the current schema shape, for example to fold legacy fields
+    // into the modern parameter object.
+    return args;
+  },
+
+  async execute(toolCallId, params, signal, onUpdate, ctx) {
+    // Stream progress
+    onUpdate?.({ content: [{ type: "text", text: "Working..." }] });
+
+    return {
+      content: [{ type: "text", text: "Done" }],
+      details: { result: "..." },
+    };
+  },
+
+  // Optional: Custom rendering
+  renderCall(args, theme, context) { ... },
+  renderResult(result, options, theme, context) { ... },
+});
+```
+
+### pi.sendMessage(message, options?)
+
+Inject a custom message into the session.
+
+```typescript
+pi.sendMessage({
+  customType: "my-extension",
+  content: "Message text",
+  display: true,
+  details: { ... },
+}, {
+  triggerTurn: true,
+  deliverAs: "steer",
+});
+```
+
+**Options:**
+- `deliverAs` - Delivery mode:
+  - `"steer"` (default) - Queues the message while streaming. Delivered after the current assistant turn finishes executing its tool calls, before the next LLM call.
+  - `"followUp"` - Waits for agent to finish. Delivered only when agent has no more tool calls.
+  - `"nextTurn"` - Queued for next user prompt. Does not interrupt or trigger anything.
+- `triggerTurn: true` - If agent is idle, trigger an LLM response immediately. Only applies to `"steer"` and `"followUp"` modes (ignored for `"nextTurn"`).
+
+### pi.sendUserMessage(content, options?)
+
+Send a user message to the agent. Unlike `sendMessage()` which sends custom messages, this sends an actual user message that appears as if typed by the user. Always triggers a turn.
+
+```typescript
+// Simple text message
+pi.sendUserMessage("What is 2+2?");
+
+// With content array (text + images)
+pi.sendUserMessage([
+  { type: "text", text: "Describe this image:" },
+  { type: "image", source: { type: "base64", mediaType: "image/png", data: "..." } },
+]);
+
+// During streaming - must specify delivery mode
+pi.sendUserMessage("Focus on error handling", { deliverAs: "steer" });
+pi.sendUserMessage("And then summarize", { deliverAs: "followUp" });
+```
+
+**Options:**
+- `deliverAs` - Required when agent is streaming:
+  - `"steer"` - Queues the message for delivery after the current assistant turn finishes executing its tool calls
+  - `"followUp"` - Waits for agent to finish all tools
+
+When not streaming, the message is sent immediately and triggers a new turn. When streaming without `deliverAs`, throws an error.
+
+See [send-user-message.ts](../examples/extensions/send-user-message.ts) for a complete example.
+
+### pi.appendEntry(customType, data?)
+
+Persist extension state (does NOT participate in LLM context).
+
+```typescript
+pi.appendEntry("my-state", { count: 42 });
+
+// Restore on reload
+pi.on("session_start", async (_event, ctx) => {
+  for (const entry of ctx.sessionManager.getEntries()) {
+    if (entry.type === "custom" && entry.customType === "my-state") {
+      // Reconstruct from entry.data
+    }
+  }
+});
+```
+
+### pi.setSessionName(name)
+
+Set the session display name (shown in session selector instead of first message).
+
+```typescript
+pi.setSessionName("Refactor auth module");
+```
+
+### pi.getSessionName()
+
+Get the current session name, if set.
+
+```typescript
+const name = pi.getSessionName();
+if (name) {
+  console.log(`Session: ${name}`);
+}
+```
+
+### pi.setLabel(entryId, label)
+
+Set or clear a label on an entry. Labels are user-defined markers for bookmarking and navigation (shown in `/tree` selector).
+
+```typescript
+// Set a label
+pi.setLabel(entryId, "checkpoint-before-refactor");
+
+// Clear a label
+pi.setLabel(entryId, undefined);
+
+// Read labels via sessionManager
+const label = ctx.sessionManager.getLabel(entryId);
+```
+
+Labels persist in the session and survive restarts. Use them to mark important points (turns, checkpoints) in the conversation tree.
+
+### pi.registerCommand(name, options)
+
+Register a command.
+
+If multiple extensions register the same command name, pi keeps them all and assigns numeric invocation suffixes in load order, for example `/review:1` and `/review:2`.
+
+```typescript
+pi.registerCommand("stats", {
+  description: "Show session statistics",
+  handler: async (args, ctx) => {
+    const count = ctx.sessionManager.getEntries().length;
+    ctx.ui.notify(`${count} entries`, "info");
+  }
+});
+```
+
+Optional: add argument auto-completion for `/command ...`:
+
+```typescript
+import type { AutocompleteItem } from "@earendil-works/pi-tui";
+
+pi.registerCommand("deploy", {
+  description: "Deploy to an environment",
+  getArgumentCompletions: (prefix: string): AutocompleteItem[] | null => {
+    const envs = ["dev", "staging", "prod"];
+    const items = envs.map((e) => ({ value: e, label: e }));
+    const filtered = items.filter((i) => i.value.startsWith(prefix));
+    return filtered.length > 0 ? filtered : null;
+  },
+  handler: async (args, ctx) => {
+    ctx.ui.notify(`Deploying: ${args}`, "info");
+  },
+});
+```
+
+### pi.getCommands()
+
+Get the slash commands available for invocation via `prompt` in the current session. Includes extension commands, prompt templates, and skill commands.
+The list matches the RPC `get_commands` ordering: extensions first, then templates, then skills.
+
+```typescript
+const commands = pi.getCommands();
+const bySource = commands.filter((command) => command.source === "extension");
+const userScoped = commands.filter((command) => command.sourceInfo.scope === "user");
+```
+
+Each entry has this shape:
+
+```typescript
+{
+  name: string; // Invokable command name without the leading slash. May be suffixed like "review:1"
+  description?: string;
+  source: "extension" | "prompt" | "skill";
+  sourceInfo: {
+    path: string;
+    source: string;
+    scope: "user" | "project" | "temporary";
+    origin: "package" | "top-level";
+    baseDir?: string;
+  };
+}
+```
+
+Use `sourceInfo` as the canonical provenance field. Do not infer ownership from command names or from ad hoc path parsing.
+
+Built-in interactive commands (like `/model` and `/settings`) are not included here. They are handled only in interactive
+mode and would not execute if sent via `prompt`.
+
+### pi.registerMessageRenderer(customType, renderer)
+
+Register a custom TUI renderer for messages with your `customType`. See [Custom UI](#custom-ui).
+
+### pi.registerShortcut(shortcut, options)
+
+Register a keyboard shortcut. See [keybindings.md](keybindings.md) for the shortcut format and built-in keybindings.
+
+```typescript
+pi.registerShortcut("ctrl+shift+p", {
+  description: "Toggle plan mode",
+  handler: async (ctx) => {
+    ctx.ui.notify("Toggled!");
+  },
+});
+```
+
+### pi.registerFlag(name, options)
+
+Register a CLI flag.
+
+```typescript
+pi.registerFlag("plan", {
+  description: "Start in plan mode",
+  type: "boolean",
+  default: false,
+});
+
+// Check value
+if (pi.getFlag("plan")) {
+  // Plan mode enabled
+}
+```
+
+### pi.exec(command, args, options?)
+
+Execute a shell command.
+
+```typescript
+const result = await pi.exec("git", ["status"], { signal, timeout: 5000 });
+// result.stdout, result.stderr, result.code, result.killed
+```
+
+### pi.getActiveTools() / pi.getAllTools() / pi.setActiveTools(names)
+
+Manage active tools. This works for both built-in tools and dynamically registered tools.
+
+```typescript
+const active = pi.getActiveTools();
+const all = pi.getAllTools();
+// [{
+//   name: "read",
+//   description: "Read file contents...",
+//   parameters: ..., 
+//   sourceInfo: { path: "<builtin:read>", source: "builtin", scope: "temporary", origin: "top-level" }
+// }, ...]
+const names = all.map(t => t.name);
+const builtinTools = all.filter((t) => t.sourceInfo.source === "builtin");
+const extensionTools = all.filter((t) => t.sourceInfo.source !== "builtin" && t.sourceInfo.source !== "sdk");
+pi.setActiveTools(["read", "bash"]); // Switch to read-only
+```
+
+`pi.getAllTools()` returns `name`, `description`, `parameters`, and `sourceInfo`.
+
+Typical `sourceInfo.source` values:
+- `builtin` for built-in tools
+- `sdk` for tools passed via `createAgentSession({ customTools })`
+- extension source metadata for tools registered by extensions
+
+### pi.setModel(model)
+
+Set the current model. Returns `false` if no API key is available for the model. See [models.md](models.md) for configuring custom models.
+
+```typescript
+const model = ctx.modelRegistry.find("anthropic", "claude-sonnet-4-5");
+if (model) {
+  const success = await pi.setModel(model);
+  if (!success) {
+    ctx.ui.notify("No API key for this model", "error");
+  }
+}
+```
+
+### pi.getThinkingLevel() / pi.setThinkingLevel(level)
+
+Get or set the thinking level. Level is clamped to model capabilities (non-reasoning models always use "off"). Changes emit `thinking_level_select`.
+
+```typescript
+const current = pi.getThinkingLevel();  // "off" | "minimal" | "low" | "medium" | "high" | "xhigh"
+pi.setThinkingLevel("high");
+```
+
+### pi.events
+
+Shared event bus for communication between extensions:
+
+```typescript
+pi.events.on("my:event", (data) => { ... });
+pi.events.emit("my:event", { ... });
+```
+
+### pi.registerProvider(name, config)
+
+Register or override a model provider dynamically. Useful for proxies, custom endpoints, or team-wide model configurations.
+
+Calls made during the extension factory function are queued and applied once the runner initialises. Calls made after that — for example from a command handler following a user setup flow — take effect immediately without requiring a `/reload`.
+
+If you need to discover models from a remote endpoint, prefer an async extension factory over deferring the fetch to `session_start`. pi waits for the factory before startup continues, so the registered models are available immediately, including to `pi --list-models`.
+
+```typescript
+// Register a new provider with custom models
+pi.registerProvider("my-proxy", {
+  name: "My Proxy",
+  baseUrl: "https://proxy.example.com",
+  apiKey: "PROXY_API_KEY",  // env var name or literal
+  api: "anthropic-messages",
+  models: [
+    {
+      id: "claude-sonnet-4-20250514",
+      name: "Claude 4 Sonnet (proxy)",
+      reasoning: false,
+      input: ["text", "image"],
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+      contextWindow: 200000,
+      maxTokens: 16384
+    }
+  ]
+});
+
+// Override baseUrl for an existing provider (keeps all models)
+pi.registerProvider("anthropic", {
+  baseUrl: "https://proxy.example.com"
+});
+
+// Register provider with OAuth support for /login
+pi.registerProvider("corporate-ai", {
+  baseUrl: "https://ai.corp.com",
+  api: "openai-responses",
+  models: [...],
+  oauth: {
+    name: "Corporate AI (SSO)",
+    async login(callbacks) {
+      // Custom OAuth flow
+      callbacks.onAuth({ url: "https://sso.corp.com/..." });
+      const code = await callbacks.onPrompt({ message: "Enter code:" });
+      return { refresh: code, access: code, expires: Date.now() + 3600000 };
+    },
+    async refreshToken(credentials) {
+      // Refresh logic
+      return credentials;
+    },
+    getApiKey(credentials) {
+      return credentials.access;
+    }
+  }
+});
+```
+
+**Config options:**
+- `name` - Display name for the provider in UI such as `/login`.
+- `baseUrl` - API endpoint URL. Required when defining models.
+- `apiKey` - API key or environment variable name. Required when defining models (unless `oauth` provided).
+- `api` - API type: `"anthropic-messages"`, `"openai-completions"`, `"openai-responses"`, etc.
+- `headers` - Custom headers to include in requests.
+- `authHeader` - If true, adds `Authorization: Bearer` header automatically.
+- `models` - Array of model definitions. If provided, replaces all existing models for this provider. Model definitions can set `baseUrl` to override the provider endpoint for that model.
+- `oauth` - OAuth provider config for `/login` support. When provided, the provider appears in the login menu.
+- `streamSimple` - Custom streaming implementation for non-standard APIs.
+
+See [custom-provider.md](custom-provider.md) for advanced topics: custom streaming APIs, OAuth details, model definition reference.
+
+### pi.unregisterProvider(name)
+
+Remove a previously registered provider and its models. Built-in models that were overridden by the provider are restored. Has no effect if the provider was not registered.
+
+Like `registerProvider`, this takes effect immediately when called after the initial load phase, so a `/reload` is not required.
+
+```typescript
+pi.registerCommand("my-setup-teardown", {
+  description: "Remove the custom proxy provider",
+  handler: async (_args, _ctx) => {
+    pi.unregisterProvider("my-proxy");
+  },
+});
+```
+
+## State Management
+
+Extensions with state should store it in tool result `details` for proper branching support:
+
+```typescript
+export default function (pi: ExtensionAPI) {
+  let items: string[] = [];
+
+  // Reconstruct state from session
+  pi.on("session_start", async (_event, ctx) => {
+    items = [];
+    for (const entry of ctx.sessionManager.getBranch()) {
+      if (entry.type === "message" && entry.message.role === "toolResult") {
+        if (entry.message.toolName === "my_tool") {
+          items = entry.message.details?.items ?? [];
+        }
+      }
+    }
+  });
+
+  pi.registerTool({
+    name: "my_tool",
+    // ...
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      items.push("new item");
+      return {
+        content: [{ type: "text", text: "Added" }],
+        details: { items: [...items] },  // Store for reconstruction
+      };
+    },
+  });
+}
+```
+
+## Custom Tools
+
+Register tools the LLM can call via `pi.registerTool()`. Tools appear in the system prompt and can have custom rendering.
+
+Use `promptSnippet` for a short one-line entry in the `Available tools` section in the default system prompt. If omitted, custom tools are left out of that section.
+
+Use `promptGuidelines` to add tool-specific bullets to the default system prompt `Guidelines` section. These bullets are included only while the tool is active (for example, after `pi.setActiveTools([...])`).
+
+**Important:** `promptGuidelines` bullets are appended flat to the `Guidelines` section with no tool name prefix or grouping. Each guideline must name the tool it refers to — avoid "Use this tool when..." because the LLM cannot tell which tool "this" means. Write "Use my_tool when..." instead.
+
+Note: Some models are idiots and include the @ prefix in tool path arguments. Built-in tools strip a leading @ before resolving paths. If your custom tool accepts a path, normalize a leading @ as well.
+
+If your custom tool mutates files, use `withFileMutationQueue()` so it participates in the same per-file queue as built-in `edit` and `write`. This matters because tool calls run in parallel by default. Without the queue, two tools can read the same old file contents, compute different updates, and then whichever write lands last overwrites the other.
+
+Example failure case: your custom tool edits `foo.ts` while built-in `edit` also changes `foo.ts` in the same assistant turn. If your tool does not participate in the queue, both can read the original `foo.ts`, apply separate changes, and one of those changes is lost.
+
+Pass the real target file path to `withFileMutationQueue()`, not the raw user argument. Resolve it to an absolute path first, relative to `ctx.cwd` or your tool's working directory. For existing files, the helper canonicalizes through `realpath()`, so symlink aliases for the same file share one queue. For new files, it falls back to the resolved absolute path because there is nothing to `realpath()` yet.
+
+Queue the entire mutation window on that target path. That includes read-modify-write logic, not just the final write.
+
+```typescript
+import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+
+async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+  const absolutePath = resolve(ctx.cwd, params.path);
+
+  return withFileMutationQueue(absolutePath, async () => {
+    await mkdir(dirname(absolutePath), { recursive: true });
+    const current = await readFile(absolutePath, "utf8");
+    const next = current.replace(params.oldText, params.newText);
+    await writeFile(absolutePath, next, "utf8");
+
+    return {
+      content: [{ type: "text", text: `Updated ${params.path}` }],
+      details: {},
+    };
+  });
+}
+```
+
+### Tool Definition
+
+```typescript
+import { Type } from "typebox";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Text } from "@earendil-works/pi-tui";
+
+pi.registerTool({
+  name: "my_tool",
+  label: "My Tool",
+  description: "What this tool does (shown to LLM)",
+  promptSnippet: "List or add items in the project todo list",
+  promptGuidelines: [
+    "Use my_tool for todo planning instead of direct file edits when the user asks for a task list."
+  ],
+  parameters: Type.Object({
+    action: StringEnum(["list", "add"] as const),  // Use StringEnum for Google compatibility
+    text: Type.Optional(Type.String()),
+  }),
+  prepareArguments(args) {
+    if (!args || typeof args !== "object") return args;
+    const input = args as { action?: string; oldAction?: string };
+    if (typeof input.oldAction === "string" && input.action === undefined) {
+      return { ...input, action: input.oldAction };
+    }
+    return args;
+  },
+
+  async execute(toolCallId, params, signal, onUpdate, ctx) {
+    // Check for cancellation
+    if (signal?.aborted) {
+      return { content: [{ type: "text", text: "Cancelled" }] };
+    }
+
+    // Stream progress updates
+    onUpdate?.({
+      content: [{ type: "text", text: "Working..." }],
+      details: { progress: 50 },
+    });
+
+    // Run commands via pi.exec (captured from extension closure)
+    const result = await pi.exec("some-command", [], { signal });
+
+    // Return result
+    return {
+      content: [{ type: "text", text: "Done" }],  // Sent to LLM
+      details: { data: result },                   // For rendering & state
+      // Optional: stop after this tool batch when every finalized tool result
+      // in the batch also returns terminate: true.
+      terminate: true,
+    };
+  },
+
+  // Optional: Custom rendering
+  renderCall(args, theme, context) { ... },
+  renderResult(result, options, theme, context) { ... },
+});
+```
+
+**Signaling errors:** To mark a tool execution as failed (sets `isError: true` on the result and reports it to the LLM), throw an error from `execute`. Returning a value never sets the error flag regardless of what properties you include in the return object.
+
+**Early termination:** Return `terminate: true` from `execute()` to hint that the automatic follow-up LLM call should be skipped after the current tool batch. This only takes effect when every finalized tool result in that batch is terminating. See [examples/extensions/structured-output.ts](../examples/extensions/structured-output.ts) for a minimal example where the agent ends on a final structured-output tool call.
+
+```typescript
+// Correct: throw to signal an error
+async execute(toolCallId, params) {
+  if (!isValid(params.input)) {
+    throw new Error(`Invalid input: ${params.input}`);
+  }
+  return { content: [{ type: "text", text: "OK" }], details: {} };
+}
+```
+
+**Important:** Use `StringEnum` from `@earendil-works/pi-ai` for string enums. `Type.Union`/`Type.Literal` doesn't work with Google's API.
+
+**Argument preparation:** `prepareArguments(args)` is optional. If defined, it runs before schema validation and before `execute()`. Use it to mimic an older accepted input shape when pi resumes an older session whose stored tool call arguments no longer match the current schema. Return the object you want validated against `parameters`. Keep the public schema strict. Do not add deprecated compatibility fields to `parameters` just to keep old resumed sessions working.
+
+Example: an older session may contain an `edit` tool call with top-level `oldText` and `newText`, while the current schema only accepts `edits: [{ oldText, newText }]`.
+
+```typescript
+pi.registerTool({
+  name: "edit",
+  label: "Edit",
+  description: "Edit a single file using exact text replacement",
+  parameters: Type.Object({
+    path: Type.String(),
+    edits: Type.Array(
+      Type.Object({
+        oldText: Type.String(),
+        newText: Type.String(),
+      }),
+    ),
+  }),
+  prepareArguments(args) {
+    if (!args || typeof args !== "object") return args;
+
+    const input = args as {
+      path?: string;
+      edits?: Array<{ oldText: string; newText: string }>;
+      oldText?: unknown;
+      newText?: unknown;
+    };
+
+    if (typeof input.oldText !== "string" || typeof input.newText !== "string") {
+      return args;
+    }
+
+    return {
+      ...input,
+      edits: [...(input.edits ?? []), { oldText: input.oldText, newText: input.newText }],
+    };
+  },
+  async execute(toolCallId, params, signal, onUpdate, ctx) {
+    // params now matches the current schema
+    return {
+      content: [{ type: "text", text: `Applying ${params.edits.length} edit block(s)` }],
+      details: {},
+    };
+  },
+});
+```
+
+### Overriding Built-in Tools
+
+Extensions can override built-in tools (`read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`) by registering a tool with the same name. Interactive mode displays a warning when this happens.
+
+```bash
+# Extension's read tool replaces built-in read
+pi -e ./tool-override.ts
+```
+
+Alternatively, use `--no-builtin-tools` to start without any built-in tools while keeping extension tools enabled:
+```bash
+# No built-in tools, only extension tools
+pi --no-builtin-tools -e ./my-extension.ts
+```
+
+See [examples/extensions/tool-override.ts](../examples/extensions/tool-override.ts) for a complete example that overrides `read` with logging and access control.
+
+**Rendering:** Built-in renderer inheritance is resolved per slot. Execution override and rendering override are independent. If your override omits `renderCall`, the built-in `renderCall` is used. If your override omits `renderResult`, the built-in `renderResult` is used. If your override omits both, the built-in renderer is used automatically (syntax highlighting, diffs, etc.). This lets you wrap built-in tools for logging or access control without reimplementing the UI.
+
+**Prompt metadata:** `promptSnippet` and `promptGuidelines` are not inherited from the built-in tool. If your override should keep those prompt instructions, define them on the override explicitly.
+
+**Your implementation must match the exact result shape**, including the `details` type. The UI and session logic depend on these shapes for rendering and state tracking.
+
+Built-in tool implementations:
+- [read.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/read.ts) - `ReadToolDetails`
+- [bash.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/bash.ts) - `BashToolDetails`
+- [edit.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/edit.ts)
+- [write.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/write.ts)
+- [grep.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/grep.ts) - `GrepToolDetails`
+- [find.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/find.ts) - `FindToolDetails`
+- [ls.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/ls.ts) - `LsToolDetails`
+
+### Remote Execution
+
+Built-in tools support pluggable operations for delegating to remote systems (SSH, containers, etc.):
+
+```typescript
+import { createReadTool, createBashTool, type ReadOperations } from "@earendil-works/pi-coding-agent";
+
+// Create tool with custom operations
+const remoteRead = createReadTool(cwd, {
+  operations: {
+    readFile: (path) => sshExec(remote, `cat ${path}`),
+    access: (path) => sshExec(remote, `test -r ${path}`).then(() => {}),
+  }
+});
+
+// Register, checking flag at execution time
+pi.registerTool({
+  ...remoteRead,
+  async execute(id, params, signal, onUpdate, _ctx) {
+    const ssh = getSshConfig();
+    if (ssh) {
+      const tool = createReadTool(cwd, { operations: createRemoteOps(ssh) });
+      return tool.execute(id, params, signal, onUpdate);
+    }
+    return localRead.execute(id, params, signal, onUpdate);
+  },
+});
+```
+
+**Operations interfaces:** `ReadOperations`, `WriteOperations`, `EditOperations`, `BashOperations`, `LsOperations`, `GrepOperations`, `FindOperations`
+
+For `user_bash`, extensions can reuse pi's local shell backend via `createLocalBashOperations()` instead of reimplementing local process spawning, shell resolution, and process-tree termination.
+
+The bash tool also supports a spawn hook to adjust the command, cwd, or env before execution:
+
+```typescript
+import { createBashTool } from "@earendil-works/pi-coding-agent";
+
+const bashTool = createBashTool(cwd, {
+  spawnHook: ({ command, cwd, env }) => ({
+    command: `source ~/.profile\n${command}`,
+    cwd: `/mnt/sandbox${cwd}`,
+    env: { ...env, CI: "1" },
+  }),
+});
+```
+
+See [examples/extensions/ssh.ts](../examples/extensions/ssh.ts) for a complete SSH example with `--ssh` flag.
+
+### Output Truncation
+
+**Tools MUST truncate their output** to avoid overwhelming the LLM context. Large outputs can cause:
+- Context overflow errors (prompt too long)
+- Compaction failures
+- Degraded model performance
+
+The built-in limit is **50KB** (~10k tokens) and **2000 lines**, whichever is hit first. Use the exported truncation utilities:
+
+```typescript
+import {
+  truncateHead,      // Keep first N lines/bytes (good for file reads, search results)
+  truncateTail,      // Keep last N lines/bytes (good for logs, command output)
+  truncateLine,      // Truncate a single line to maxBytes with ellipsis
+  formatSize,        // Human-readable size (e.g., "50KB", "1.5MB")
+  DEFAULT_MAX_BYTES, // 50KB
+  DEFAULT_MAX_LINES, // 2000
+} from "@earendil-works/pi-coding-agent";
+
+async execute(toolCallId, params, signal, onUpdate, ctx) {
+  const output = await runCommand();
+
+  // Apply truncation
+  const truncation = truncateHead(output, {
+    maxLines: DEFAULT_MAX_LINES,
+    maxBytes: DEFAULT_MAX_BYTES,
+  });
+
+  let result = truncation.content;
+
+  if (truncation.truncated) {
+    // Write full output to temp file
+    const tempFile = writeTempFile(output);
+
+    // Inform the LLM where to find complete output
+    result += `\n\n[Output truncated: ${truncation.outputLines} of ${truncation.totalLines} lines`;
+    result += ` (${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)}).`;
+    result += ` Full output saved to: ${tempFile}]`;
+  }
+
+  return { content: [{ type: "text", text: result }] };
+}
+```
+
+**Key points:**
+- Use `truncateHead` for content where the beginning matters (search results, file reads)
+- Use `truncateTail` for content where the end matters (logs, command output)
+- Always inform the LLM when output is truncated and where to find the full version
+- Document the truncation limits in your tool's description
+
+See [examples/extensions/truncated-tool.ts](../examples/extensions/truncated-tool.ts) for a complete example wrapping `rg` (ripgrep) with proper truncation.
+
+### Multiple Tools
+
+One extension can register multiple tools with shared state:
+
+```typescript
+export default function (pi: ExtensionAPI) {
+  let connection = null;
+
+  pi.registerTool({ name: "db_connect", ... });
+  pi.registerTool({ name: "db_query", ... });
+  pi.registerTool({ name: "db_close", ... });
+
+  pi.on("session_shutdown", async () => {
+    connection?.close();
+  });
+}
+```
+
+### Custom Rendering
+
+Tools can provide `renderCall` and `renderResult` for custom TUI display. See [tui.md](tui.md) for the full component API and [tool-execution.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/modes/interactive/components/tool-execution.ts) for how tool rows are composed.
+
+By default, tool output is wrapped in a `Box` that handles padding and background. A defined `renderCall` or `renderResult` must return a `Component`. If a slot renderer is not defined, `tool-execution.ts` uses fallback rendering for that slot.
+
+Set `renderShell: "self"` when the tool should render its own shell instead of using the default `Box`. This is useful for tools that need complete control over framing or background behavior, for example large previews that must stay visually stable after the tool settles.
+
+```typescript
+pi.registerTool({
+  name: "my_tool",
+  label: "My Tool",
+  description: "Custom shell example",
+  parameters: Type.Object({}),
+  renderShell: "self",
+  async execute() {
+    return { content: [{ type: "text", text: "ok" }], details: undefined };
+  },
+  renderCall(args, theme, context) {
+    return new Text(theme.fg("accent", "my custom shell"), 0, 0);
+  },
+});
+```
+
+`renderCall` and `renderResult` each receive a `context` object with:
+- `args` - the current tool call arguments
+- `state` - shared row-local state across `renderCall` and `renderResult`
+- `lastComponent` - the previously returned component for that slot, if any
+- `invalidate()` - request a rerender of this tool row
+- `toolCallId`, `cwd`, `executionStarted`, `argsComplete`, `isPartial`, `expanded`, `showImages`, `isError`
+
+Use `context.state` for cross-slot shared state. Keep slot-local caches on the returned component instance when you want to reuse and mutate the same component across renders.
+
+#### renderCall
+
+Renders the tool call or header:
+
+```typescript
+import { Text } from "@earendil-works/pi-tui";
+
+renderCall(args, theme, context) {
+  const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+  let content = theme.fg("toolTitle", theme.bold("my_tool "));
+  content += theme.fg("muted", args.action);
+  if (args.text) {
+    content += " " + theme.fg("dim", `"${args.text}"`);
+  }
+  text.setText(content);
+  return text;
+}
+```
+
+#### renderResult
+
+Renders the tool result or output:
+
+```typescript
+renderResult(result, { expanded, isPartial }, theme, context) {
+  if (isPartial) {
+    return new Text(theme.fg("warning", "Processing..."), 0, 0);
+  }
+
+  if (result.details?.error) {
+    return new Text(theme.fg("error", `Error: ${result.details.error}`), 0, 0);
+  }
+
+  let text = theme.fg("success", "✓ Done");
+  if (expanded && result.details?.items) {
+    for (const item of result.details.items) {
+      text += "\n  " + theme.fg("dim", item);
+    }
+  }
+  return new Text(text, 0, 0);
+}
+```
+
+If a slot intentionally has no visible content, return an empty `Component` such as an empty `Container`.
+
+#### Keybinding Hints
+
+Use `keyHint()` to display keybinding hints that respect the active keybinding configuration:
+
+```typescript
+import { keyHint } from "@earendil-works/pi-coding-agent";
+
+renderResult(result, { expanded }, theme, context) {
+  let text = theme.fg("success", "✓ Done");
+  if (!expanded) {
+    text += ` (${keyHint("app.tools.expand", "to expand")})`;
+  }
+  return new Text(text, 0, 0);
+}
+```
+
+Available functions:
+- `keyHint(keybinding, description)` - Formats a configured keybinding id such as `"app.tools.expand"` or `"tui.select.confirm"`
+- `keyText(keybinding)` - Returns the raw configured key text for a keybinding id
+- `rawKeyHint(key, description)` - Format a raw key string
+
+Use namespaced keybinding ids:
+- Coding-agent ids use the `app.*` namespace, for example `app.tools.expand`, `app.editor.external`, `app.session.rename`
+- Shared TUI ids use the `tui.*` namespace, for example `tui.select.confirm`, `tui.select.cancel`, `tui.input.tab`
+
+For the exhaustive list of keybinding ids and defaults, see [keybindings.md](keybindings.md). `keybindings.json` uses those same namespaced ids.
+
+Custom editors and `ctx.ui.custom()` components receive `keybindings: KeybindingsManager` as an injected argument. They should use that injected manager directly instead of calling `getKeybindings()` or `setKeybindings()`.
+
+#### Best Practices
+
+- Use `Text` with padding `(0, 0)`. The default Box handles padding.
+- Use `\n` for multi-line content.
+- Handle `isPartial` for streaming progress.
+- Support `expanded` for detail on demand.
+- Keep default view compact.
+- Read `context.args` in `renderResult` instead of copying args into `context.state`.
+- Use `context.state` only for data that must be shared across call and result slots.
+- Reuse `context.lastComponent` when the same component instance can be updated in place.
+- Use `renderShell: "self"` only when the default boxed shell gets in the way. In self-shell mode the tool is responsible for its own framing, padding, and background.
+
+#### Fallback
+
+If a slot renderer is not defined or throws:
+- `renderCall`: Shows the tool name
+- `renderResult`: Shows raw text from `content`
+
+## Custom UI
+
+Extensions can interact with users via `ctx.ui` methods and customize how messages/tools render.
+
+**For custom components, see [tui.md](tui.md)** which has copy-paste patterns for:
+- Selection dialogs (SelectList)
+- Async operations with cancel (BorderedLoader)
+- Settings toggles (SettingsList)
+- Status indicators (setStatus)
+- Working message, visibility, and indicator during streaming (`setWorkingMessage`, `setWorkingVisible`, `setWorkingIndicator`)
+- Widgets above/below editor (setWidget)
+- Autocomplete providers layered on top of built-in slash/path completion (addAutocompleteProvider)
+- Custom footers (setFooter)
+
+### Dialogs
+
+```typescript
+// Select from options
+const choice = await ctx.ui.select("Pick one:", ["A", "B", "C"]);
+
+// Confirm dialog
+const ok = await ctx.ui.confirm("Delete?", "This cannot be undone");
+
+// Text input
+const name = await ctx.ui.input("Name:", "placeholder");
+
+// Multi-line editor
+const text = await ctx.ui.editor("Edit:", "prefilled text");
+
+// Notification (non-blocking)
+ctx.ui.notify("Done!", "info");  // "info" | "warning" | "error"
+```
+
+#### Timed Dialogs with Countdown
+
+Dialogs support a `timeout` option that auto-dismisses with a live countdown display:
+
+```typescript
+// Dialog shows "Title (5s)" → "Title (4s)" → ... → auto-dismisses at 0
+const confirmed = await ctx.ui.confirm(
+  "Timed Confirmation",
+  "This dialog will auto-cancel in 5 seconds. Confirm?",
+  { timeout: 5000 }
+);
+
+if (confirmed) {
+  // User confirmed
+} else {
+  // User cancelled or timed out
+}
+```
+
+**Return values on timeout:**
+- `select()` returns `undefined`
+- `confirm()` returns `false`
+- `input()` returns `undefined`
+
+#### Manual Dismissal with AbortSignal
+
+For more control (e.g., to distinguish timeout from user cancel), use `AbortSignal`:
+
+```typescript
+const controller = new AbortController();
+const timeoutId = setTimeout(() => controller.abort(), 5000);
+
+const confirmed = await ctx.ui.confirm(
+  "Timed Confirmation",
+  "This dialog will auto-cancel in 5 seconds. Confirm?",
+  { signal: controller.signal }
+);
+
+clearTimeout(timeoutId);
+
+if (confirmed) {
+  // User confirmed
+} else if (controller.signal.aborted) {
+  // Dialog timed out
+} else {
+  // User cancelled (pressed Escape or selected "No")
+}
+```
+
+See [examples/extensions/timed-confirm.ts](../examples/extensions/timed-confirm.ts) for complete examples.
+
+### Widgets, Status, and Footer
+
+```typescript
+// Status in footer (persistent until cleared)
+ctx.ui.setStatus("my-ext", "Processing...");
+ctx.ui.setStatus("my-ext", undefined);  // Clear
+
+// Working loader (shown during streaming)
+ctx.ui.setWorkingMessage("Thinking deeply...");
+ctx.ui.setWorkingMessage();  // Restore default
+ctx.ui.setWorkingVisible(false);  // Hide the built-in working loader row entirely
+ctx.ui.setWorkingVisible(true);   // Show the built-in working loader row
+
+// Working indicator (shown during streaming)
+ctx.ui.setWorkingIndicator({ frames: [ctx.ui.theme.fg("accent", "●")] });  // Static dot
+ctx.ui.setWorkingIndicator({
+  frames: [
+    ctx.ui.theme.fg("dim", "·"),
+    ctx.ui.theme.fg("muted", "•"),
+    ctx.ui.theme.fg("accent", "●"),
+    ctx.ui.theme.fg("muted", "•"),
+  ],
+  intervalMs: 120,
+});
+ctx.ui.setWorkingIndicator({ frames: [] });  // Hide indicator
+ctx.ui.setWorkingIndicator();  // Restore default spinner
+
+// Widget above editor (default)
+ctx.ui.setWidget("my-widget", ["Line 1", "Line 2"]);
+// Widget below editor
+ctx.ui.setWidget("my-widget", ["Line 1", "Line 2"], { placement: "belowEditor" });
+ctx.ui.setWidget("my-widget", (tui, theme) => new Text(theme.fg("accent", "Custom"), 0, 0));
+ctx.ui.setWidget("my-widget", undefined);  // Clear
+
+// Custom footer (replaces built-in footer entirely)
+ctx.ui.setFooter((tui, theme) => ({
+  render(width) { return [theme.fg("dim", "Custom footer")]; },
+  invalidate() {},
+}));
+ctx.ui.setFooter(undefined);  // Restore built-in footer
+
+// Terminal title
+ctx.ui.setTitle("pi - my-project");
+
+// Editor text
+ctx.ui.setEditorText("Prefill text");
+const current = ctx.ui.getEditorText();
+
+// Paste into editor (triggers paste handling, including collapse for large content)
+ctx.ui.pasteToEditor("pasted content");
+
+// Stack custom autocomplete behavior on top of the built-in provider
+ctx.ui.addAutocompleteProvider((current) => ({
+  async getSuggestions(lines, line, col, options) {
+    const beforeCursor = (lines[line] ?? "").slice(0, col);
+    const match = beforeCursor.match(/(?:^|[ \t])#([^\s#]*)$/);
+    if (!match) {
+      return current.getSuggestions(lines, line, col, options);
+    }
+
+    return {
+      prefix: `#${match[1] ?? ""}`,
+      items: [{ value: "#2983", label: "#2983", description: "Extension API for autocomplete" }],
+    };
+  },
+  applyCompletion(lines, line, col, item, prefix) {
+    return current.applyCompletion(lines, line, col, item, prefix);
+  },
+  shouldTriggerFileCompletion(lines, line, col) {
+    return current.shouldTriggerFileCompletion?.(lines, line, col) ?? true;
+  },
+}));
+
+// Tool output expansion
+const wasExpanded = ctx.ui.getToolsExpanded();
+ctx.ui.setToolsExpanded(true);
+ctx.ui.setToolsExpanded(wasExpanded);
+
+// Custom editor (vim mode, emacs mode, etc.)
+ctx.ui.setEditorComponent((tui, theme, keybindings) => new VimEditor(tui, theme, keybindings));
+const currentEditor = ctx.ui.getEditorComponent();
+ctx.ui.setEditorComponent((tui, theme, keybindings) =>
+  new WrappedEditor(tui, theme, keybindings, currentEditor?.(tui, theme, keybindings))
+);
+ctx.ui.setEditorComponent(undefined);  // Restore default editor
+
+// Theme management (see themes.md for creating themes)
+const themes = ctx.ui.getAllThemes();  // [{ name: "dark", path: "/..." | undefined }, ...]
+const lightTheme = ctx.ui.getTheme("light");  // Load without switching
+const result = ctx.ui.setTheme("light");  // Switch by name
+if (!result.success) {
+  ctx.ui.notify(`Failed: ${result.error}`, "error");
+}
+ctx.ui.setTheme(lightTheme!);  // Or switch by Theme object
+ctx.ui.theme.fg("accent", "styled text");  // Access current theme
+```
+
+Custom working-indicator frames are rendered verbatim. If you want colors, add them to the frame strings yourself, for example with `ctx.ui.theme.fg(...)`.
+
+### Autocomplete Providers
+
+Use `ctx.ui.addAutocompleteProvider()` to stack custom autocomplete logic on top of the built-in slash-command and path provider.
+
+Typical pattern:
+
+- inspect the text before the cursor
+- return your own suggestions when your extension-specific syntax matches
+- otherwise delegate to `current.getSuggestions(...)`
+- delegate `applyCompletion(...)` unless you need custom insertion behavior
+
+```typescript
+pi.on("session_start", (_event, ctx) => {
+  ctx.ui.addAutocompleteProvider((current) => ({
+    async getSuggestions(lines, cursorLine, cursorCol, options) {
+      const line = lines[cursorLine] ?? "";
+      const beforeCursor = line.slice(0, cursorCol);
+      const match = beforeCursor.match(/(?:^|[ \t])#([^\s#]*)$/);
+      if (!match) {
+        return current.getSuggestions(lines, cursorLine, cursorCol, options);
+      }
+
+      return {
+        prefix: `#${match[1] ?? ""}`,
+        items: [
+          { value: "#2983", label: "#2983", description: "Extension API for registering custom @ autocomplete providers" },
+          { value: "#2753", label: "#2753", description: "Reload stale resource settings" },
+        ],
+      };
+    },
+
+    applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
+      return current.applyCompletion(lines, cursorLine, cursorCol, item, prefix);
+    },
+
+    shouldTriggerFileCompletion(lines, cursorLine, cursorCol) {
+      return current.shouldTriggerFileCompletion?.(lines, cursorLine, cursorCol) ?? true;
+    },
+  }));
+});
+```
+
+See [github-issue-autocomplete.ts](../examples/extensions/github-issue-autocomplete.ts) for a complete example that preloads the latest open GitHub issues with `gh issue list` and filters them locally for fast `#...` completion. It requires GitHub CLI (`gh`) and a GitHub repository checkout.
+
+### Custom Components
+
+For complex UI, use `ctx.ui.custom()`. This temporarily replaces the editor with your component until `done()` is called:
+
+```typescript
+import { Text, Component } from "@earendil-works/pi-tui";
+
+const result = await ctx.ui.custom<boolean>((tui, theme, keybindings, done) => {
+  const text = new Text("Press Enter to confirm, Escape to cancel", 1, 1);
+
+  text.onKey = (key) => {
+    if (key === "return") done(true);
+    if (key === "escape") done(false);
+    return true;
+  };
+
+  return text;
+});
+
+if (result) {
+  // User pressed Enter
+}
+```
+
+The callback receives:
+- `tui` - TUI instance (for screen dimensions, focus management)
+- `theme` - Current theme for styling
+- `keybindings` - App keybinding manager (for checking shortcuts)
+- `done(value)` - Call to close component and return value
+
+See [tui.md](tui.md) for the full component API.
+
+#### Overlay Mode (Experimental)
+
+Pass `{ overlay: true }` to render the component as a floating modal on top of existing content, without clearing the screen:
+
+```typescript
+const result = await ctx.ui.custom<string | null>(
+  (tui, theme, keybindings, done) => new MyOverlayComponent({ onClose: done }),
+  { overlay: true }
+);
+```
+
+For advanced positioning (anchors, margins, percentages, responsive visibility), pass `overlayOptions`. Use `onHandle` to control visibility programmatically:
+
+```typescript
+const result = await ctx.ui.custom<string | null>(
+  (tui, theme, keybindings, done) => new MyOverlayComponent({ onClose: done }),
+  {
+    overlay: true,
+    overlayOptions: { anchor: "top-right", width: "50%", margin: 2 },
+    onHandle: (handle) => { /* handle.setHidden(true/false) */ }
+  }
+);
+```
+
+See [tui.md](tui.md) for the full `OverlayOptions` API and [overlay-qa-tests.ts](../examples/extensions/overlay-qa-tests.ts) for examples.
+
+### Custom Editor
+
+Replace the main input editor with a custom implementation (vim mode, emacs mode, etc.):
+
+```typescript
+import { CustomEditor, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { matchesKey } from "@earendil-works/pi-tui";
+
+class VimEditor extends CustomEditor {
+  private mode: "normal" | "insert" = "insert";
+
+  handleInput(data: string): void {
+    if (matchesKey(data, "escape") && this.mode === "insert") {
+      this.mode = "normal";
+      return;
+    }
+    if (this.mode === "normal" && data === "i") {
+      this.mode = "insert";
+      return;
+    }
+    super.handleInput(data);  // App keybindings + text editing
+  }
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.on("session_start", (_event, ctx) => {
+    ctx.ui.setEditorComponent((_tui, theme, keybindings) =>
+      new VimEditor(theme, keybindings)
+    );
+  });
+}
+```
+
+**Key points:**
+- Extend `CustomEditor` (not base `Editor`) to get app keybindings (escape to abort, ctrl+d, model switching)
+- Call `super.handleInput(data)` for keys you don't handle
+- Factory receives `theme` and `keybindings` from the app
+- Use `ctx.ui.getEditorComponent()` before `setEditorComponent()` to wrap the previously configured custom editor
+- Pass `undefined` to restore default: `ctx.ui.setEditorComponent(undefined)`
+
+To compose with another extension that already replaced the editor, capture the previous factory before setting yours:
+
+```typescript
+const previous = ctx.ui.getEditorComponent();
+ctx.ui.setEditorComponent((tui, theme, keybindings) =>
+  new MyEditor(tui, theme, keybindings, { base: previous?.(tui, theme, keybindings) })
+);
+```
+
+See [tui.md](tui.md) Pattern 7 for a complete example with mode indicator.
+
+### Message Rendering
+
+Register a custom renderer for messages with your `customType`:
+
+```typescript
+import { Text } from "@earendil-works/pi-tui";
+
+pi.registerMessageRenderer("my-extension", (message, options, theme) => {
+  const { expanded } = options;
+  let text = theme.fg("accent", `[${message.customType}] `);
+  text += message.content;
+
+  if (expanded && message.details) {
+    text += "\n" + theme.fg("dim", JSON.stringify(message.details, null, 2));
+  }
+
+  return new Text(text, 0, 0);
+});
+```
+
+Messages are sent via `pi.sendMessage()`:
+
+```typescript
+pi.sendMessage({
+  customType: "my-extension",  // Matches registerMessageRenderer
+  content: "Status update",
+  display: true,               // Show in TUI
+  details: { ... },            // Available in renderer
+});
+```
+
+### Theme Colors
+
+All render functions receive a `theme` object. See [themes.md](themes.md) for creating custom themes and the full color palette.
+
+```typescript
+// Foreground colors
+theme.fg("toolTitle", text)   // Tool names
+theme.fg("accent", text)      // Highlights
+theme.fg("success", text)     // Success (green)
+theme.fg("error", text)       // Errors (red)
+theme.fg("warning", text)     // Warnings (yellow)
+theme.fg("muted", text)       // Secondary text
+theme.fg("dim", text)         // Tertiary text
+
+// Text styles
+theme.bold(text)
+theme.italic(text)
+theme.strikethrough(text)
+```
+
+For syntax highlighting in custom tool renderers:
+
+```typescript
+import { highlightCode, getLanguageFromPath } from "@earendil-works/pi-coding-agent";
+
+// Highlight code with explicit language
+const highlighted = highlightCode("const x = 1;", "typescript", theme);
+
+// Auto-detect language from file path
+const lang = getLanguageFromPath("/path/to/file.rs");  // "rust"
+const highlighted = highlightCode(code, lang, theme);
+```
+
+## Error Handling
+
+- Extension errors are logged, agent continues
+- `tool_call` errors block the tool (fail-safe)
+- Tool `execute` errors must be signaled by throwing; the thrown error is caught, reported to the LLM with `isError: true`, and execution continues
+
+## Mode Behavior
+
+| Mode                 | UI Methods    | Notes                                          |
+| -------------------- | ------------- | ---------------------------------------------- |
+| Interactive          | Full TUI      | Normal operation                               |
+| RPC (`--mode rpc`)   | JSON protocol | Host handles UI, see [rpc.md](rpc.md)          |
+| JSON (`--mode json`) | No-op         | Event stream to stdout, see [json.md](json.md) |
+| Print (`-p`)         | No-op         | Extensions run but can't prompt                |
+
+In non-interactive modes, check `ctx.hasUI` before using UI methods.
+
+## Examples Reference
+
+All examples in [examples/extensions/](~/Clones/earendil-works/pi/packages/pi-coding-agent/examples/extensions/).
+
+| Example                        | Description                                                                                                         | Key APIs                                                                                                                          |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| **Tools**                      |                                                                                                                     |                                                                                                                                   |
+| `hello.ts`                     | Minimal tool registration                                                                                           | `registerTool`                                                                                                                    |
+| `question.ts`                  | Tool with user interaction                                                                                          | `registerTool`, `ui.select`                                                                                                       |
+| `questionnaire.ts`             | Multi-step wizard tool                                                                                              | `registerTool`, `ui.custom`                                                                                                       |
+| `todo.ts`                      | Stateful tool with persistence                                                                                      | `registerTool`, `appendEntry`, `renderResult`, session events                                                                     |
+| `dynamic-tools.ts`             | Register tools after startup and during commands                                                                    | `registerTool`, `session_start`, `registerCommand`                                                                                |
+| `structured-output.ts`         | Final structured-output tool with `terminate: true`                                                                 | `registerTool`, terminating tool results                                                                                          |
+| `truncated-tool.ts`            | Output truncation example                                                                                           | `registerTool`, `truncateHead`                                                                                                    |
+| `tool-override.ts`             | Override built-in read tool                                                                                         | `registerTool` (same name as built-in)                                                                                            |
+| **Commands**                   |                                                                                                                     |                                                                                                                                   |
+| `pirate.ts`                    | Modify system prompt per-turn                                                                                       | `registerCommand`, `before_agent_start`                                                                                           |
+| `summarize.ts`                 | Conversation summary command                                                                                        | `registerCommand`, `ui.custom`                                                                                                    |
+| `handoff.ts`                   | Cross-provider model handoff                                                                                        | `registerCommand`, `ui.editor`, `ui.custom`                                                                                       |
+| `qna.ts`                       | Q&A with custom UI                                                                                                  | `registerCommand`, `ui.custom`, `setEditorText`                                                                                   |
+| `send-user-message.ts`         | Inject user messages                                                                                                | `registerCommand`, `sendUserMessage`                                                                                              |
+| `reload-runtime.ts`            | Reload command and LLM tool handoff                                                                                 | `registerCommand`, `ctx.reload()`, `sendUserMessage`                                                                              |
+| `shutdown-command.ts`          | Graceful shutdown command                                                                                           | `registerCommand`, `shutdown()`                                                                                                   |
+| **Events & Gates**             |                                                                                                                     |                                                                                                                                   |
+| `permission-gate.ts`           | Block dangerous commands                                                                                            | `on("tool_call")`, `ui.confirm`                                                                                                   |
+| `protected-paths.ts`           | Block writes to specific paths                                                                                      | `on("tool_call")`                                                                                                                 |
+| `confirm-destructive.ts`       | Confirm session changes                                                                                             | `on("session_before_switch")`, `on("session_before_fork")`                                                                        |
+| `dirty-repo-guard.ts`          | Warn on dirty git repo                                                                                              | `on("session_before_*")`, `exec`                                                                                                  |
+| `input-transform.ts`           | Transform user input                                                                                                | `on("input")`                                                                                                                     |
+| `model-status.ts`              | React to model changes                                                                                              | `on("model_select")`, `setStatus`                                                                                                 |
+| `provider-payload.ts`          | Inspect payloads and provider response headers                                                                      | `on("before_provider_request")`, `on("after_provider_response")`                                                                  |
+| `system-prompt-header.ts`      | Display system prompt info                                                                                          | `on("agent_start")`, `getSystemPrompt`                                                                                            |
+| `claude-rules.ts`              | Load rules from files                                                                                               | `on("session_start")`, `on("before_agent_start")`                                                                                 |
+| `prompt-customizer.ts`         | Add context-aware tool guidance using `systemPromptOptions`                                                         | `on("before_agent_start")`, `BuildSystemPromptOptions`                                                                            |
+| `file-trigger.ts`              | File watcher triggers messages                                                                                      | `sendMessage`                                                                                                                     |
+| **Compaction & Sessions**      |                                                                                                                     |                                                                                                                                   |
+| `custom-compaction.ts`         | Custom compaction summary                                                                                           | `on("session_before_compact")`                                                                                                    |
+| `trigger-compact.ts`           | Trigger compaction manually                                                                                         | `compact()`                                                                                                                       |
+| `git-checkpoint.ts`            | Git stash on turns                                                                                                  | `on("turn_start")`, `on("session_before_fork")`, `exec`                                                                           |
+| `auto-commit-on-exit.ts`       | Commit on shutdown                                                                                                  | `on("session_shutdown")`, `exec`                                                                                                  |
+| **UI Components**              |                                                                                                                     |                                                                                                                                   |
+| `status-line.ts`               | Footer status indicator                                                                                             | `setStatus`, session events                                                                                                       |
+| `working-indicator.ts`         | Customize the streaming working indicator                                                                           | `setWorkingIndicator`, `registerCommand`                                                                                          |
+| `github-issue-autocomplete.ts` | Add `#1234` issue completions on top of built-in autocomplete by preloading recent open issues from `gh issue list` | `addAutocompleteProvider`, `on("session_start")`, `exec`                                                                          |
+| `custom-footer.ts`             | Replace footer entirely                                                                                             | `registerCommand`, `setFooter`                                                                                                    |
+| `custom-header.ts`             | Replace startup header                                                                                              | `on("session_start")`, `setHeader`                                                                                                |
+| `modal-editor.ts`              | Vim-style modal editor                                                                                              | `setEditorComponent`, `CustomEditor`                                                                                              |
+| `rainbow-editor.ts`            | Custom editor styling                                                                                               | `setEditorComponent`                                                                                                              |
+| `widget-placement.ts`          | Widget above/below editor                                                                                           | `setWidget`                                                                                                                       |
+| `overlay-test.ts`              | Overlay components                                                                                                  | `ui.custom` with overlay options                                                                                                  |
+| `overlay-qa-tests.ts`          | Comprehensive overlay tests                                                                                         | `ui.custom`, all overlay options                                                                                                  |
+| `notify.ts`                    | Simple notifications                                                                                                | `ui.notify`                                                                                                                       |
+| `timed-confirm.ts`             | Dialogs with timeout                                                                                                | `ui.confirm` with timeout/signal                                                                                                  |
+| `mac-system-theme.ts`          | Auto-switch theme                                                                                                   | `setTheme`, `exec`                                                                                                                |
+| **Complex Extensions**         |                                                                                                                     |                                                                                                                                   |
+| `plan-mode/`                   | Full plan mode implementation                                                                                       | All event types, `registerCommand`, `registerShortcut`, `registerFlag`, `setStatus`, `setWidget`, `sendMessage`, `setActiveTools` |
+| `preset.ts`                    | Saveable presets (model, tools, thinking)                                                                           | `registerCommand`, `registerShortcut`, `registerFlag`, `setModel`, `setActiveTools`, `setThinkingLevel`, `appendEntry`            |
+| `tools.ts`                     | Toggle tools on/off UI                                                                                              | `registerCommand`, `setActiveTools`, `SettingsList`, session events                                                               |
+| **Remote & Sandbox**           |                                                                                                                     |                                                                                                                                   |
+| `ssh.ts`                       | SSH remote execution                                                                                                | `registerFlag`, `on("user_bash")`, `on("before_agent_start")`, tool operations                                                    |
+| `interactive-shell.ts`         | Persistent shell session                                                                                            | `on("user_bash")`                                                                                                                 |
+| `sandbox/`                     | Sandboxed tool execution                                                                                            | Tool operations                                                                                                                   |
+| `subagent/`                    | Spawn sub-agents                                                                                                    | `registerTool`, `exec`                                                                                                            |
+| **Games**                      |                                                                                                                     |                                                                                                                                   |
+| `snake.ts`                     | Snake game                                                                                                          | `registerCommand`, `ui.custom`, keyboard handling                                                                                 |
+| `space-invaders.ts`            | Space Invaders game                                                                                                 | `registerCommand`, `ui.custom`                                                                                                    |
+| `doom-overlay/`                | Doom in overlay                                                                                                     | `ui.custom` with overlay                                                                                                          |
+| **Providers**                  |                                                                                                                     |                                                                                                                                   |
+| `custom-provider-anthropic/`   | Custom Anthropic proxy                                                                                              | `registerProvider`                                                                                                                |
+| `custom-provider-gitlab-duo/`  | GitLab Duo integration                                                                                              | `registerProvider` with OAuth                                                                                                     |
+| **Messages & Communication**   |                                                                                                                     |                                                                                                                                   |
+| `message-renderer.ts`          | Custom message rendering                                                                                            | `registerMessageRenderer`, `sendMessage`                                                                                          |
+| `event-bus.ts`                 | Inter-extension events                                                                                              | `pi.events`                                                                                                                       |
+| **Session Metadata**           |                                                                                                                     |                                                                                                                                   |
+| `session-name.ts`              | Name sessions for selector                                                                                          | `setSessionName`, `getSessionName`                                                                                                |
+| `bookmark.ts`                  | Bookmark entries for /tree                                                                                          | `setLabel`                                                                                                                        |
+| **Misc**                       |                                                                                                                     |                                                                                                                                   |
+| `inline-bash.ts`               | Inline bash in tool calls                                                                                           | `on("tool_call")`                                                                                                                 |
+| `bash-spawn-hook.ts`           | Adjust bash command, cwd, and env before execution                                                                  | `createBashTool`, `spawnHook`                                                                                                     |
+| `with-deps/`                   | Extension with npm dependencies                                                                                     | Package structure with `package.json`                                                                                             |
diff --git a/memory/PLAN.md b/memory/PLAN.md
index 815473fa..c163c6f5 100644
--- a/memory/PLAN.md
+++ b/memory/PLAN.md
@@ -14,23 +14,25 @@
 
 ## Context
 
-Brunch-next is starting from a deliberately razed slate on the `next` branch (tag `next-baseline`). Implementation, planning memory, and pre-POC docs have been archived under `archive/`. The new line is a thin layer over `pi-coding-agent` whose milestone ladder M0–M9 (from `prd.md`) is the planning spine. M0 (walking skeleton) is the first frontier to land — it also doubles as the Phase-3 infra bootstrap. Fixture capture starts at M1 and grows with every later milestone.
+Brunch-next is proceeding on the razed `next` line (tag `next-baseline`) as a thin product layer over `pi-coding-agent`. M0–M3 proved the basic host, JSONL transcript viability, fixture/RPC substrate, and read-only web shell. The active risk is now Pi wrapping: FE-744 must finish the structured-question / Pi-RPC JSON-editor fallback proof, then the new sealed-profile/runtime-state frontier must lock down ambient Pi isolation plus transcript-backed operational mode / role preset / strategy / lens state before graph tools and authority-gated agent work depend on those seams. The M4 graph data plane remains structurally next after those harness/control-plane risks are scoped.
 
 ## Sequencing
 
 ### Active
 
-1. `graph-data-plane` — M4. SQLite-backed graph persistence; intent-plane nodes/edges; graph clock; change log; coherence-state homes.
+1. `pi-ui-extension-patterns` — Continue FE-744 for the POC-critical structured elicitation loop: Pi-native structured question/tool exchange → input-replacing TUI custom UI or Pi-RPC JSON-editor fallback → self-contained `toolResult.details` / linked structured response → elicitation-exchange projection through Brunch's single public RPC surface.
 
 ### Next
 
-1. `agent-graph-integration` — M5. Graph tools and observer extraction through pi extension seams; all writes via the shared command layer.
+1. `sealed-pi-profile-runtime-state` — Seal Brunch's embedded Pi profile and transcript-backed runtime-bundle state before future agent-loop work depends on ambient-safe settings, prompt composition, or tool gating.
+2. `graph-data-plane` — M4 remains structurally next after the offer-first UI seam is proven; do not return to it until FE-744 has a credible elicitation input loop for POC sessions and the sealed-profile/runtime-state follow-up is scoped.
+3. `agent-graph-integration` — M5. Graph tools and observer extraction through pi extension seams; all writes via the shared command layer.
 
 ### Parallel / Low-conflict
 
 - `brief-library-curation` — Author and review briefs #4–#7 plus the adversarial second tier; can proceed independently once `walking-skeleton` exists. Briefs are text, no code dependency.
 - `fixture-strategy-evolution` — Iterate `fixture-strategy.md` (property invariants, brief expectations) as fixtures are captured. Doc-only.
-- `pi-ui-extension-patterns` — Prove the Pi extension seams Brunch needs for lens/review-set UX: custom slash commands, styled persistent chrome (color/glyphs), modal/popover overlays, radio/checkbox/select prompts, clickable/navigable action buttons, picker/list-selection modals, and ambient establishment-offer rendering that stays orientation-first rather than becoming a default lens menu. Spike-shaped probe whose output is a feasibility matrix + minimum-viable wrappers that downstream frontiers (M5 lenses/review-sets, M6 authority gates, M7 turn-boundary delivery) can build on. Can run in parallel with `graph-data-plane` and ahead of `agent-graph-integration`.
+- `subagents-for-proposal-diversity` — Optional enhancement to candidate-proposal generation (D44-L). Lands when `agent-and-graph-integration` (M5) is far enough along that generative-lens proposal flow exists and would benefit from parallel data-gathering; never a blocker.
 
 ### Horizon
 
@@ -54,7 +56,7 @@ Brunch-next is starting from a deliberately razed slate on the `next` branch (ta
 - **Status:** done (bootstrap slice landed on `next` as commit `b104fc40`; coordinator/runbook and TUI boot/chrome slices landed on the frontier branch; manual M0 smoke + store-only runbook oracle passed)
 - **Objective:** Prove the wrapping model works at all: a `brunch` binary launches a pi-backed TUI session through the `WorkspaceSessionCoordinator`, scopes durable state to `.brunch/`, hardcodes Brunch's prompt and curated toolset, and mounts the persistent TUI chrome and spec-selector gate.
 - **Why now / unlocks:** First architectural proof of D1-L (depend on `pi-coding-agent`) and D2-L (opinionated product, not pi shell). Unlocks every subsequent milestone. Also doubles as the Phase-3 infra bootstrap (package.json, tsconfig, oxlint/oxfmt, vitest).
-- **Acceptance:** `brunch` launches a TUI session in a project directory; `.brunch/` is created; boot routes through a `WorkspaceSessionCoordinator` that returns `ready | select_spec | needs_human`; the spec-selector is presented before any agent loop runs when no bound spec is ready; the selected spec is written as the session's `brunch.session_binding`; `/new` creates another session bound to the same spec rather than mutating the current session's spec; the chrome region displays cwd / spec / phase / chat-mode at all times; `npm run verify` is green.
+- **Acceptance:** `brunch` launches a TUI session in a project directory; `.brunch/` is created; boot routes through a `WorkspaceSessionCoordinator` that returns `ready | select_spec | needs_human`; the spec-selector is presented before any agent loop runs when no bound spec is ready; the selected spec is written as the session's `brunch.session_binding`; `/new` creates another session bound to the same spec rather than mutating the current session's spec; the chrome region displays cwd / spec / phase / runtime bundle at all times; `npm run verify` is green.
 - **Verification:** Inner — `npm run fix` / `npm run verify` plus coordinator state/unit tests. Middle — M0 runbook oracle: manual TUI smoke against a scratch project paired with artifact/query postconditions for `.brunch/`, `brunch.session_binding`, same-spec `/new`, and chrome/workspace state (SPEC §Runbook Oracle Design). Outer — defer; first replay-regression fixture lands in M1.
 - **Cross-cutting obligations:** Preserve the `cwd → spec → session` hierarchy, one-spec-per-session binding, and persistent chrome region as durable product surfaces, not temporary bootstrapping hacks. Do not let TUI, RPC, or fixture code create/open Pi sessions or write `brunch.session_binding` directly; route boot, spec selection, and `/new` through the workspace-session seam.
 - **Traceability:** R1, R2, R3, R4, R19 / D1-L, D2-L, D6-L, D11-L, D21-L / I8-L, I13-L / A1-L, A10-L
@@ -72,7 +74,7 @@ Brunch-next is starting from a deliberately razed slate on the `next` branch (ta
 - **Why now / unlocks:** Proves D5-L (JSON-RPC primary) and unlocks the fixture-driven feedback loop. Without this milestone, every downstream milestone has only manual TUI evidence.
 - **Acceptance:** `brunch --mode print` and `brunch --mode rpc` boot from the same host setup; the first `session.*` / `workspace.*` RPC handlers are named product methods rather than a generic read gateway; an agent-as-user driver completes at least one brief end-to-end over stdio by responding to elicitation prompts; captured JSONL can be projected into prompt/response elicitation exchanges; a `.jsonl` + `.meta.json` bundle is written under `.brunch-fixtures/`; the first three curated briefs are captured.
 - **Verification:** Inner — verify gate plus projection-handler unit tests for elicitation exchange ranges. Middle — deterministic first captured run, stdio RPC handler contract tests, replay-regression fixture(s) asserting transcript reproduction/projection parity, and `./runbooks/verify-m1.sh` for store/projection/manual-smoke evidence (SPEC §Oracle Strategy by Loop Tier). Outer — the three-layer fixture model is established in skeleton form here; property and adversarial layers come online as later milestones supply graph/coherence substrates; brief quality and golden-capture representativeness remain explicit human review prompts in the runbook.
-- **Cross-cutting obligations:** Keep transport mode distinct from agent modes/lenses; do not make print mode select or imply an agent strategy in M1. Keep the captured-run format forward-compatible with later `.graph.json` and `.coherence.json` artefacts; establish exchange projection over Pi JSONL without creating canonical chat/turn tables; keep read/subscription architecture thin — named RPC method families and projection handlers over canonical stores, not a generic read-model platform; this frontier establishes the first layer of the canonical replay/property/adversarial fixture architecture rather than a one-off harness.
+- **Cross-cutting obligations:** Keep transport mode distinct from agent roles/lenses; do not make print mode select or imply an agent strategy in M1. Keep the captured-run format forward-compatible with later `.graph.json` and `.coherence.json` artefacts; establish exchange projection over Pi JSONL without creating canonical chat/turn tables; keep read/subscription architecture thin — named RPC method families and projection handlers over canonical stores, not a generic read-model platform; this frontier establishes the first layer of the canonical replay/property/adversarial fixture architecture rather than a one-off harness.
 - **Traceability:** R4, R5, R11, R16, R17, R20 / D5-L, D12-L, D13-L, D18-L, D19-L / I3-L, I10-L, I13-L / A1-L, A5-L
 - **Design docs:** [fixture-strategy.md](file:///Users/lunelson/Code/hashintel/brunch-next/docs/architecture/fixture-strategy.md)
 - **Current execution pointer:** complete after M1 review fixes; proceed to `jsonl-session-viability`.
@@ -109,21 +111,36 @@ Brunch-next is starting from a deliberately razed slate on the `next` branch (ta
 - **Design docs:** [prd.md §M3, §Frontend Architecture](file:///Users/lunelson/Code/hashintel/brunch-next/docs/architecture/prd.md)
 - **Current execution pointer:** complete. M3 tied off with shared JSON-RPC protocol helpers/dispatch semantics, `ws`-backed `/rpc` transport, persistent browser RPC client with protocol-failure hardening, canonical built asset serving with traversal-safe asset resolution, stable React runtime, explicit read-only session projection by durable session id through a canonical Brunch session-envelope reader with strict self-description validation, explicit transcript custom-entry classifiers, and read-only browser transcript rendering of assistant/user rows plus transcript-native prompt display rows from typed `{ sessionId, specId }` targets. Automated verification and direct HTTP/WebSocket projection postconditions pass. Accepted outer-loop deferral: qualitative browser-open smoke remains environment-blocked because `agent-browser` cannot create its socket directory under the current macOS sandbox (`Operation not permitted`); this does not block M3 tie-off because static HTML serving, absence of HTTP product reads, explicit `{ sessionId, specId }` WebSocket RPC reads, transcript-display text including custom prompt rows, and exchange projection were rechecked directly against the host.
 
+### sealed-pi-profile-runtime-state
+
+- **Name:** Sealed Pi profile and transcript-backed runtime state
+- **Linear:** unassigned
+- **Kind:** structural hardening
+- **Status:** not-started
+- **Objective:** Turn the discussion-locked Brunch Pi Profile and runtime-bundle model into code/tests by porting the useful `.pi/` probe extensions into flat product modules under `src/pi-extensions/*.ts` plus aggregate `src/pi-extensions.ts`: Brunch-owned programmatic settings/resource/tool/prompt/keybinding policy isolates product behavior from ambient user/project `.pi/`; operational mode / role preset / strategy / lens state is appended to Pi JSONL as Brunch custom entries and reconstructed at turn boundaries.
+- **Why now / unlocks:** FE-744 proved multiple Pi extension seams and exposed the exact weak point: ambient resource discovery is mostly disabled, but `SettingsManager.create(cwd, agentDir)` can still leak behavior-shaping settings, and future `elicit` vs `execute` work needs prompt/tool posture to be stateful without hidden extension memory. This frontier de-risks M5/M6/M7 before graph tools, observer/reviewer jobs, and authority gating depend on the embedded harness.
+- **Acceptance:** A `BrunchPiProfile` (or equivalent module boundary) owns settings policy, resource-loader options, extension factories, keybinding/command policy, tool policy, and prompt policy; tests prove ambient context files/extensions/skills/prompt templates/themes do not load while explicit Brunch-owned extension-discovered resources can load intentionally through Pi `resources_discover`; settings that affect product behavior are overridden/sealed or documented as a Pi upstream seam; runtime extension factories now load from flat product modules under `src/pi-extensions.ts` / `src/pi-extensions/*` and reusable TUI components under `src/pi-components/*`, with no project-local Pi discovery path as product runtime. Full selected-state transcript entries under `brunch.agent_runtime_state` can be appended by Brunch helpers and replayed to reconstruct active operational mode, role preset/runtime bundle, strategy, and lens; turn prep composes prompt packs from base Brunch prompt + operational mode + role preset + strategy + lens + spec phase/maturity/gates + current graph/coherence/world state + pending structured-interaction rules; `elicit` suppresses execute/dangerous tools such as raw `bash`/`write` unless explicitly allowed by the active bundle.
+- **Verification:** Inner — profile/runtimestate unit tests, prompt-composition snapshot tests, and tool-policy contract tests. Middle — ambient `.pi/` fixture/audit tests proving disabled discovery and sealed settings; explicit Brunch resource-injection test proving extension factories may inject Brunch-owned skills/prompts despite ambient `noSkills`/`noPromptTemplates`; JSONL reload/projection tests for runtime init/switch entries; before-agent-start/tool-call policy tests for `elicit`. Outer — manual TUI/RPC smoke that active role/lens/strategy changes are inspectable in transcript and reflected in prompt/tool posture rather than hidden UI state.
+- **Cross-cutting obligations:** Do not expose Pi's generic extension/skill/prompt/theme configuration to Brunch users; do not make Pi skills the primary authority for core operational prompts; keep raw Pi RPC behind Brunch adapters; keep runtime state linear-transcript-backed and compatible with compaction/session-boundary lifecycle hooks (`session_start`, `resources_discover`, `before_agent_start`, `context`, `tool_call`, `session_before_switch`, `session_before_compact`, `session_shutdown`).
+- **Traceability:** R25, R26 / D2-L, D23-L, D39-L, D40-L / I24-L, I25-L / A19-L
+- **Design docs:** [pi-seam-extensions.md](file:///Users/lunelson/Code/hashintel/brunch-next/docs/architecture/pi-seam-extensions.md), [pi-ui-extension-patterns.md](file:///Users/lunelson/Code/hashintel/brunch-next/docs/architecture/pi-ui-extension-patterns.md)
+- **Current execution pointer:** product extension/component port queue and runtime-state card queue complete: `src/pi-extensions.ts` now aggregates flat product modules for command policy, session lifecycle, chrome, workspace dialog, operational-mode tool policy, mention autocomplete, and alternatives; reusable TUI components live under `src/pi-components`; operational-mode owns `brunch.agent_runtime_state` projection, prompt/tool posture, init snapshots, and validated switch snapshots. Immediate UI correction before continuing profile audit: rename/reframe the current workspace dialog around SPEC D11-L/D36-L terminology (`workspace(cwd) → spec → session`) and reshape it into the hierarchical spec/session selection model: optional continue-last fast path; create spec → name it → implicit first session; resume existing spec → choose spec from a scrollable selector → create new session or resume existing session → choose session. Preserve RPC/headless startup as structured initial-selection state/results, not a TUI picker. Follow-up in the same frontier: add best-effort lifecycle-generated session display names over Pi `session_info`, likely triggered from `session_shutdown` and modeled after the local `summarize.ts` extension's cheap-model summarization pattern, so picker lists can distinguish sessions by meaning rather than UUID alone. Then scope the settings/resource audit: preserve current `noContextFiles`/`noExtensions`/`noPromptTemplates`/`noSkills`/`noThemes` posture, prove extension-factory resource injection is intentional, then seal or document the remaining `SettingsManager` leakage.
+
 ### graph-data-plane
 
 - **Name:** Graph data plane (intent-first, workspace-graph-ready) (M4)
 - **Linear:** [FE-741](https://linear.app/hash/issue/FE-741/graph-data-plane-intent-first-workspace-graph-ready-m4)
 - **Branch:** `ln/fe-741-graph-data-plane` (stacked on `ln/fe-737-web-shell`)
 - **Kind:** structural
-- **Status:** active
+- **Status:** next / paused until FE-744 structured-question proof and the sealed-profile/runtime-state follow-up are scoped
 - **Objective:** Stand up SQLite-backed graph persistence; durable intent-plane nodes and edges; a single global LSN per commit; the change log; the reconciliation-need substrate; named homes for coherence state (verdicts and violations) — all forward-compatible with oracle, design, and plan planes.
 - **Why now / unlocks:** Pins I1-L, I6-L. Unlocks all agent ↔ graph work (M5+) and lets oracle / design / plan planes be added later without re-foundation.
 - **Acceptance:** Graph CRUD + change-log replay tests pass through the `CommandExecutor` public mutation boundary; command results already include success, `needs_human`, `policy_blocked`, `version_conflict`, and `structural_illegal` shapes even if pre-M6 policy classification is minimal; reconciliation-need substrate accepts inserts/updates/resolutions with LSN invariants enforced; oracle-plane stub tables exist (Check, Validation Method, Evidence, Obligation) even if unused; the persistence layer proves the one-transaction protocol that couples authority/result classification, version checks, structural validation, LSN allocation, change-log append, and any coherence updates.
 - **Verification:** Inner gate plus command/result schema/type tests. Middle — property/model-based tests on LSN monotonicity, graph replay, reconciliation invariants, framing matrix, and `CommandExecutor` transaction/result behavior; architectural no-bypass tests. Outer — fixture property invariants on reconciliation-substrate begin running.
-- **Cross-cutting obligations:** Establish the Drizzle + `better-sqlite3` persistence shape, `CommandExecutor` result contract, and no-bypass transaction rule as shared infrastructure for later direct-agent, observer-job, side-task, migration, and UI-attributed writes.
-- **Traceability:** R7, R9, R13 / D3-L, D4-L, D6-L, D8-L, D9-L, D16-L, D20-L / I1-L, I6-L, I7-L, I11-L / A3-L, A4-L
+- **Cross-cutting obligations:** Establish the Drizzle + `better-sqlite3` persistence shape, `CommandExecutor` result contract, and no-bypass transaction rule as shared infrastructure for later direct-agent, observer-job, side-task, migration, and UI-attributed writes. Derive row/insert/update runtime schemas from Drizzle table definitions via TypeBox (`drizzle-orm/typebox` if A20-L resolves to the Drizzle 1.0 beta line; standalone `drizzle-typebox` + `drizzle-orm/typebox-legacy` otherwise) — do not hand-author parallel row schemas. Land the I26-L grep-based architectural test alongside the first Drizzle import so the single-schema-vocabulary boundary stays enforced.
+- **Traceability:** R7, R9, R13 / D3-L, D4-L, D6-L, D8-L, D9-L, D16-L, D20-L, D41-L / I1-L, I6-L, I7-L, I11-L, I26-L / A3-L, A4-L, A20-L
 - **Design docs:** [pi-seam-extensions.md §1 Async side-chain sub-agents](file:///Users/lunelson/Code/hashintel/brunch-next/docs/architecture/pi-seam-extensions.md#1-async-side-chain-sub-agents), [pi-seam-extensions.md §Graph clock, §Reconciliation-need substrate, §Oracle plane](file:///Users/lunelson/Code/hashintel/brunch-next/docs/architecture/pi-seam-extensions.md)
-- **Current execution pointer:** start by scoping the narrow `CommandExecutor` result contract and one-transaction LSN/change-log skeleton before widening CRUD or coherence homes.
+- **Current execution pointer:** start by scoping the narrow `CommandExecutor` result contract and one-transaction LSN/change-log skeleton before widening CRUD or coherence homes. Pair the first slice with an A20-L spike (Drizzle 1.0 beta + `drizzle-orm/typebox` + `better-sqlite3` + Pi `registerTool` round-trip) so the version pin and schema-derivation path are settled before later slices import them broadly.
 
 ### agent-graph-integration
 
@@ -138,6 +155,19 @@ Brunch-next is starting from a deliberately razed slate on the `next` branch (ta
 - **Traceability:** R10, R13, R17, R21, R22, R23 / D4-L, D13-L, D15-L, D18-L, D20-L, D25-L, D26-L, D27-L, D28-L, D29-L, D30-L, D32-L / I2-L, I11-L, I14-L, I15-L, I16-L, I17-L, I18-L, I20-L / A3-L, A11-L, A13-L, A14-L, A16-L
 - **Design docs:** [prd.md §M5, §Authority Model](file:///Users/lunelson/Code/hashintel/brunch-next/docs/architecture/prd.md), [pi-seam-extensions.md §1 Async side-chain sub-agents](file:///Users/lunelson/Code/hashintel/brunch-next/docs/architecture/pi-seam-extensions.md#1-async-side-chain-sub-agents), [ELICITATION_LENSES.md](file:///Users/lunelson/Code/hashintel/brunch-next/docs/design/ELICITATION_LENSES.md), [REVIEW_SETS.md](file:///Users/lunelson/Code/hashintel/brunch-next/docs/design/REVIEW_SETS.md)
 
+### subagents-for-proposal-diversity
+
+- **Name:** Subagents for candidate-proposal diversity (optional enhancement)
+- **Linear:** unassigned
+- **Kind:** optional enhancement
+- **Status:** deferred (lands when `agent-and-graph-integration` is far enough along to benefit; never a blocker for M0–M9)
+- **Objective:** Register a single `subagent` Pi tool per D44-L so the main agent can (a) fan out blocking data-gathering calls (scout / researcher / graph-reader) in parallel to ground proposals, then (b) fan out parallel `proposer` invocations to generate diverse candidate variants — the subagent realization of `ln-design`'s "design it twice" pattern and `ln-oracles`'s parallel-fan-out — and finally compose `brunch.review_set_proposal` entries from those variants via the D31-L meta-rubric. Subagent results return as tool content; no `CommandExecutor` access; no Brunch RPC access; isolated `pi --no-session --no-skills --no-extensions` subprocesses inheriting Brunch Pi Profile sealing.
+- **Acceptance:** `subagent` tool registered with `{ agent, task }` and `{ tasks: [] }` parameters; starter agents scout/researcher/graph-reader/proposer land as markdown files with TypeBox-validated frontmatter under `src/pi-extensions/subagents/agents/`; proposer is system-prompt-only (no tools) and produces exactly one variant per invocation; argv shape per spawned subprocess includes `--no-session --no-skills --no-extensions` plus an explicit per-agent tool allowlist / model / system-prompt path; concurrency cap honored from [src/pi-extensions/subagents/config.json](file:///Users/lunelson/Code/hashintel/brunch-next/src/pi-extensions/subagents/config.json); subagents have no inherited conversation context so the task string must carry everything; result text returns as tool result content with no transcript side-effects; at least one generative-lens fixture exercises a `tasks: []` parallel `proposer` fan-out (≥ 2 variants) feeding a single `brunch.review_set_proposal` composed by the main agent via the D31-L meta-rubric.
+- **Verification:** Inner — `subagent` tool argv-shape tests; TypeBox schema validation of agent frontmatter and `config.json`; per-starter-agent tool-allowlist conformance (proposer must have an empty tool set). Middle — isolation audit (no ambient `.pi/` resources reachable; parent `CommandExecutor` / Brunch RPC handlers absent from subprocess environment); subprocess streaming / abort propagation tests; parallel-fan-out independence test (two `proposer` invocations with distinct framings produce structurally distinct outputs). Outer — proposal-generation fixture invokes scout/researcher/graph-reader to ground, then parallel `proposer` variants, and surfaces the composed review-set proposal with grounding-bundle coverage and `epistemic_status` consistent with the gathered evidence; meta-rubric application visible in the comparison rendering.
+- **Cross-cutting obligations:** Preserve the single-authority mutation rule (`CommandExecutor` only — subagents never bypass it) and the sealed Pi Profile (no ambient `.pi/` leakage through the subprocess boundary). Cross-extension agent registration (Amos's `globalThis.__pi_subagents` bridge) is deferred because it conflicts with profile sealing; the POC registry is Brunch-owned only. Worker-style write-capable subagents are deferred until an execute operational mode exists.
+- **Traceability:** R20 / D2-L, D26-L, D27-L, D30-L, D31-L, D39-L, D41-L, D44-L / I2-L, I11-L, I24-L, I29-L
+- **Design docs:** [pi-seam-extensions.md §1 Async side-chain sub-agents](file:///Users/lunelson/Code/hashintel/brunch-next/docs/architecture/pi-seam-extensions.md#1-async-side-chain-sub-agents), [ELICITATION_LENSES.md](file:///Users/lunelson/Code/hashintel/brunch-next/docs/design/ELICITATION_LENSES.md), [REVIEW_SETS.md](file:///Users/lunelson/Code/hashintel/brunch-next/docs/design/REVIEW_SETS.md)
+
 ### authority-model
 
 - **Name:** Authority model and gated tools (M6)
@@ -182,11 +212,11 @@ Brunch-next is starting from a deliberately razed slate on the `next` branch (ta
 - **Linear:** unassigned
 - **Kind:** structural
 - **Status:** not-started
-- **Objective:** Compaction preserves graph and coherence anchors; interest sets can widen beyond direct reads when needed; conflict signaling remains intelligible at long horizons.
-- **Acceptance:** Long-horizon adversarial brief (50+ turns) replays through compaction with `lastSeenLsn`, interest set, and session binding preserved; spec/session changes across compaction boundaries do not desync; active spec and any in-flight side-task, observer-job, reviewer-job, or lens bookkeeping remain intelligible after compaction; the latest `brunch.establishment_offer` entry remains reconstructable across compaction so ambient-affordance chrome continues to render the current offer.
-- **Verification:** Inner gate plus continuity-metadata unit tests. Middle — compaction round-trip/property tests for `lastSeenLsn`, interest set, session binding, graph/coherence anchors, active side-task/observer/reviewer bookkeeping, and latest-establishment-offer reconstruction. Outer — long-horizon fixture passes, including continuity checks for side-task, interest-set, and establishment-offer state when present.
-- **Cross-cutting obligations:** Preserve the coherence anchors, session binding, session continuity metadata, and side-task/observer/spec state that earlier milestones attached to the shared transcript/event substrate; preserve lens state only if a lens subsystem has landed by then.
-- **Traceability:** R15 / D6-L, D15-L / I12-L
+- **Objective:** Compaction preserves graph, coherence, and continuity anchors per D43-L; interest sets can widen beyond direct reads when needed; conflict signaling remains intelligible at long horizons.
+- **Acceptance:** Long-horizon adversarial brief (50+ turns) replays through compaction with `lastSeenLsn`, interest set, and session binding preserved; spec/session changes across compaction boundaries do not desync; the auto-compaction extension renders the configured preserved-anchor set byte-stable so active spec, in-flight side-task / observer-job / reviewer-job bookkeeping, latest `brunch.agent_runtime_state`, latest `brunch.establishment_offer`, latest `brunch.lens_switch`, unresolved staleness hints, and active review-set leaves remain intelligible after compaction; ambient-affordance chrome continues to render the current offer; auto-compaction failure falls through to Pi default compaction rather than dropping anchors silently.
+- **Verification:** Inner gate plus continuity-metadata unit tests and TypeBox schema validation of [src/pi-extensions/auto-compaction-anchors.json](file:///Users/lunelson/Code/hashintel/brunch-next/src/pi-extensions/auto-compaction-anchors.json). Middle — compaction round-trip/property tests for `lastSeenLsn`, interest set, session binding, graph/coherence anchors, active side-task/observer/reviewer bookkeeping, latest-establishment-offer/lens/runtime-state reconstruction; deterministic anchor-rendering tests (same branch + same config → same header bytes); fallback-to-Pi-default behavior under simulated auth failure, empty LLM output, and thrown error. Outer — long-horizon fixture passes, including continuity checks for side-task, interest-set, runtime-state, and establishment-offer state when present.
+- **Cross-cutting obligations:** Preserve the coherence anchors, session binding, session continuity metadata, and side-task/observer/spec state that earlier milestones attached to the shared transcript/event substrate; preserve lens state only if a lens subsystem has landed by then. The auto-compaction extension is the canonical owner of `session_before_compact`; product code paths that touch compaction must compose with it rather than register a parallel hook.
+- **Traceability:** R15 / D6-L, D15-L, D43-L / I12-L, I28-L
 - **Design docs:** [prd.md §Continuity, Divergence, and Coherence](file:///Users/lunelson/Code/hashintel/brunch-next/docs/architecture/prd.md)
 
 ### brief-library-curation
@@ -218,16 +248,18 @@ Brunch-next is starting from a deliberately razed slate on the `next` branch (ta
 ### pi-ui-extension-patterns
 
 - **Name:** Prove Pi extension patterns for Brunch UI affordances
-- **Linear:** unassigned
+- **Linear:** [FE-744](https://linear.app/hash/issue/FE-744/pi-ui-extension-patterns)
+- **Branch:** `ln/fe-744-pi-ui-extension-patterns` (off `ln/fe-737-web-shell`, parallel to `ln/fe-741-graph-data-plane`)
 - **Kind:** structural (spike-flavored)
-- **Status:** not-started
-- **Objective:** Demonstrate that Pi's extension seams can host the UI affordances Brunch needs for elicitation-lens and review-set flows without forking Pi or building a parallel rendering substrate. Catalog and prototype: custom slash commands routed through Brunch handlers; persistent chrome with TUI styling/color/glyphs beyond the current minimal status line; modal/popover overlays for proposal review; radio/checkbox/select prompts for multi-choice answers and user-invoked orientation/selection affordances; clickable/navigable action buttons for accept/request-changes/reject affordances; picker/list-selection modals for spec switching and entity selection; ambient rendering of the latest `brunch.establishment_offer`. The output is a feasibility matrix mapping each affordance to (a) the Pi seam(s) used, (b) Brunch-owned wrapper code required, (c) controllability cost for the agent-as-user driver, and (d) residual risks — plus minimum-viable wrappers that later frontiers can call directly.
-- **Acceptance:** A short design memo (`docs/architecture/pi-ui-extension-patterns.md` or section in `pi-seam-extensions.md`) catalogs the affordance matrix with verdicts (`proven` / `feasible-with-cost` / `requires-pi-change` / `not-feasible`); the matrix distinguishes ambient establishment-offer rendering from any user-invoked orientation view and records that Brunch is not building a default exhaustive lens menu; a runnable demo wires at least one representative of each viable category through Brunch's TUI host (custom slash command, styled chrome element, modal/popover, multi-choice prompt, action button, picker modal, establishment-offer chrome rendering); the agent-as-user driver can controllably exercise the multi-choice and action-button affordances (informs the controllability/cost answer in `D27-L` and reviewer-flow oracle design); the matrix explicitly records which affordances are unviable so downstream UX design does not assume them; SPEC.md and PLAN.md links to the memo are added where M5/M6/M7 verification depends on a charted affordance.
-- **Verification:** Inner — verify gate plus unit tests for any extension wrappers added. Middle — runbook oracles per affordance category (manual checklist + executable postcondition checker on chrome state, JSONL custom entries emitted, or command-result discriminants); contract tests for any new Brunch handler shape introduced (slash command router, modal request/response, picker selection). Outer — manual TUI walkthrough validating visual quality and interaction feel; comparative walkthrough between scripted-driver and manual paths to record controllability cost.
-- **Cross-cutting obligations:** Preserve the linear-transcript invariant (`I19-L`) — affordance prototypes must not introduce branch creation, mid-turn state mutations outside the command layer, or a parallel chat/turn store. Multi-choice affordances must integrate with the existing capture-aware offer envelope (`pi-seam-extensions.md §4`) and the structured elicitation-entry shape. Slash commands and action buttons must route writes through the `CommandExecutor`. Any new custom-entry kinds must declare `lens` per `I18-L` if elicitor-emitted. Establishment-offer affordances must stay orientation-first and user-invoked when expanded, rather than turning the full offer tree into a default next-action menu.
+- **Status:** in-progress (command-containment, dynamic chrome, hierarchical spec/session picker startup + in-session flow, RPC/headless initial-selection contract, pty startup oracle, centered branded overlay reuse, and evidence-memo reconciliation have landed; current missing seam is the structured-question / RPC-relay loop)
+- **Objective:** Demonstrate the Pi extension seams Brunch needs before M5/M6/M7 depend on them: product-named commands routed through Brunch handlers; effect blocking for unsupported branch/session flows; dynamic Brunch-owned chrome through one wrapper; Brunch-owned startup/session selection; and, now active, a structured elicitation loop where a system/assistant-originated question or questionnaire can use Pi's registered-tool transcript seam, replace the default TUI input surface with single-choice / multi-choice / questionnaire / optional-freeform custom UI, degrade over Pi RPC through schema-tagged JSON in `ctx.ui.editor`, and persist a self-contained structured result in `toolResult.details` (or a linked custom entry where that is the thinner seam).
+- **Acceptance:** `docs/architecture/pi-ui-extension-patterns.md` catalogs the evidence with verdicts (`proven` / `feasible-with-cost` / `requires-pi-change` / `not-feasible`), distinguishes strict command suppression from lifecycle effect blocking, records the minimum upstream Pi command/keybinding policy ask, and captures the RPC degradation profile for chrome/custom UI. Brunch code exposes a product-named extension entrypoint plus wrappers for chrome, command policy, session lifecycle binding, and `/brunch`; the centered spec/session picker supports an optional continue-last fast path plus hierarchical create-spec/resume-spec/create-session/resume-session decisions without UI-owned session mutation and is shared by startup plus in-session adapters; TUI startup runs a Brunch-owned pre-Pi gate before `InteractiveMode` so prior transcript rendering is opt-in rather than implicit; creating a new session lands in a binding-only session for the selected spec; chrome receives the activated session id instead of fabricating `unbound`; the startup no-resume pty oracle proves stale transcript text is absent before explicit activation. The remaining active acceptance is a structured-question / RPC-relay proof: a registered Pi tool can collect text, single-select, multi-select, questionnaire, and optional-freeform answers; rich TUI paths use `ctx.ui.custom()` while raw Pi RPC paths use supported dialogs or schema-tagged JSON over `ctx.ui.editor`; the returned `toolResult.details` echoes enough prompt/question/option/answer/mode/status/transport data for Brunch projection without rehydrating semantics solely from assistant tool-call arguments; the model-readable `content` is generated from the same details; elicitation-exchange projection recognizes the structured tool exchange; and Brunch exposes one public product RPC surface that can wrap Pi RPC extension-UI requests for agent-as-user probes and web relay clients.
+- **Verification:** Inner — verify gate plus unit tests for any extension wrappers added; coordinator inventory/activation tests for switch decisions; source/contract tests that switcher UI returns decisions rather than mutating sessions; schema tests for structured question result details and JSON-editor request/response parsing. Middle — runbook oracles per affordance category (manual checklist + executable postcondition checker on chrome state, JSONL tool results/custom entries emitted, or command-result discriminants); contract tests for any new Brunch handler shape introduced (slash command router, modal request/response, picker selection, elicitation pending/response relay); pty/ANSI-stripped startup oracle proving no prior transcript appears before an explicit resume/open decision; raw Pi RPC probe demonstrating `ctx.ui.editor` JSON fallback round-trips through the documented extension UI protocol. Outer — manual TUI walkthrough validating visual quality, full-screen startup feel, interaction feel, and controllability cost between scripted-driver and manual paths.
+- **Cross-cutting obligations:** Preserve the linear-transcript invariant (`I19-L`) — affordance prototypes must not introduce branch creation, mid-turn state mutations outside the command layer, or a parallel chat/turn store. Preserve the workspace hierarchy and startup invariant (`R19` / `I22-L`): the workspace is the cwd, not a user-created selectable object; `.brunch/state.json` is default acceleration, not implicit resume; no prior transcript or agent loop may run before an explicit spec/session activation decision. Spec/session picker UI must remain pure decision rendering; `WorkspaceSessionCoordinator` owns inventory, activation, state writes, session creation/opening, and binding. RPC/headless startup must expose structured initial-selection state/results, not invoke the TUI picker. Structured question/questionnaire affordances must use Pi transcript truth first: `toolResult.details` may be the canonical structured response payload, while assistant tool-call args are positional/causal context. Slash commands and action buttons must route writes through the `CommandExecutor`; the JSON-editor RPC fallback is an adapter over Pi's supported extension UI protocol, not a new public Pi command family and not a bypass around Brunch's product RPC surface. Any new custom-entry kinds must declare `lens` per `I18-L` if elicitor-emitted. Establishment-offer affordances must stay orientation-first and user-invoked when expanded, rather than turning the full offer tree into a default next-action menu. TUI chrome/status affordances should call Brunch product wrappers rather than raw Pi `ctx.ui.*` primitives; the chrome wrapper must not publish its own `brunch.chrome` status key, and RPC fixtures should assert only chrome events that Pi actually emits for the current wrapper (diagnostic string-array `setWidget`, `setTitle`, notifications, and any future explicit status adapter rather than TUI-only header/footer).
 - **Why now / unlocks:** Lens/review-set/reviewer UX in M5 and authority gating in M6 both assume Brunch can render rich interactive affordances over Pi without forking it. Proving the affordance set early de-risks those frontiers and lets the agent-as-user-driver extension question (controllability vs cost trade flagged in `ln-oracles` pass) be answered with evidence rather than estimation. Can run in parallel with `graph-data-plane` because TUI seams are independent of graph persistence.
-- **Traceability:** R4, R14, R16, R20, R21 / D2-L, D11-L, D24-L, D25-L, D26-L, D27-L, D29-L, D32-L / I18-L, I19-L / A10-L, A14-L, A17-L
-- **Design docs:** [pi-seam-extensions.md](file:///Users/lunelson/Code/hashintel/brunch-next/docs/architecture/pi-seam-extensions.md), [ELICITATION_LENSES.md](file:///Users/lunelson/Code/hashintel/brunch-next/docs/design/ELICITATION_LENSES.md), [REVIEW_SETS.md](file:///Users/lunelson/Code/hashintel/brunch-next/docs/design/REVIEW_SETS.md); new memo to be created during the spike.
+- **Traceability:** R4, R14, R16, R17, R19, R20, R21 / D2-L, D5-L, D11-L, D12-L, D13-L, D17-L, D19-L, D21-L, D22-L, D24-L, D25-L, D26-L, D27-L, D29-L, D32-L, D33-L, D34-L, D35-L, D36-L, D37-L, D38-L, D39-L, D40-L / I10-L, I13-L, I18-L, I19-L, I22-L, I23-L, I24-L, I25-L / A10-L, A14-L, A17-L, A18-L, A19-L
+- **Design docs:** [pi-seam-extensions.md](file:///Users/lunelson/Code/hashintel/brunch-next/docs/architecture/pi-seam-extensions.md), [pi-ui-extension-patterns.md](file:///Users/lunelson/Code/hashintel/brunch-next/docs/architecture/pi-ui-extension-patterns.md), [pi-ui-extension-patterns-provisional-plan.md](file:///Users/lunelson/Code/hashintel/brunch-next/docs/architecture/pi-ui-extension-patterns-provisional-plan.md), [ELICITATION_LENSES.md](file:///Users/lunelson/Code/hashintel/brunch-next/docs/design/ELICITATION_LENSES.md), [REVIEW_SETS.md](file:///Users/lunelson/Code/hashintel/brunch-next/docs/design/REVIEW_SETS.md).
+- **Current execution pointer:** Spec/session picker correction is complete: the pure model and TUI component now use the hierarchical create-spec/resume-spec/create-session/resume-session flow, RPC/headless startup exposes TypeBox-validated `workspace.selectionState` / `workspace.activate` without importing TUI picker code, the startup no-resume pty oracle passes with the new spec/session copy, and the structured-question result schema/builder plus TUI/editor adapters now prove self-contained `toolResult.details`, model-readable `content`, input-replacing TUI answer collection, schema-tagged JSON-over-`ctx.ui.editor` validation for text/single/multi/questionnaire and terminal statuses, live Pi RPC editor fallback at the adapter layer (`npm run test:structured-question-rpc-proof`), and response-side elicitation-exchange projection for terminal structured-question results. Continue the structured-question proof with Brunch product-surface relay semantics before returning to `graph-data-plane`.
 
 ### flue-pattern-adoption
 
@@ -282,7 +314,7 @@ Brunch-next is starting from a deliberately razed slate on the `next` branch (ta
 - 2026-05-21 `jsonl-session-viability` — Done: Pi JSONL reload preserves coordinator-created binding-only sessions, first assistant/user flushes without duplicate prefixes, `/new` same-spec bindings, raw user/assistant payloads, representative Brunch custom entries, context-participating custom messages, continuity/compaction metadata, structured elicitation entries, defensive active-branch projection behavior, and M1 bundle-local replay parity for briefs #1–#3. Verified: `npm run verify` after each slice. Watch: M2 validates JSONL as sufficient for Brunch-supported linear sessions on current POC terms; branch-aware Brunch sessions are intentionally unsupported per D24-L, and later side-task, mention, and continuity frontiers still own their final payload semantics.
 - 2026-05-21 `mode-shell-and-fixture-driver` — Done: print and RPC transport modes boot through the Brunch host; named `workspace.snapshot` and `session.elicitationExchanges` handlers project coordinator-selected session state; fixture capture copies the same selected Pi JSONL session projected by RPC; brief metadata is Brunch-owned and marks graph/coherence artifacts deferred; briefs #1–#3 have scripted deterministic replay bundles under `.brunch-fixtures/<brief-id>/scripted-001/`. Verified: `npm run verify`, RPC/print parity smoke, exchange projection tests, fixture replay/projection parity tests, `./runbooks/verify-m1.sh`, and human inspection that briefs/captures/product-shaped outputs are good on their current terms. Watch: M2 used these captured transcripts as JSONL reload evidence without turning them into a parallel chat/turn store; later elicitation work must revisit the encoded interaction logic, expectations, and knowledge-flow assumptions rather than treating the scripted M1 exchange shape as final product behavior.
 
-Older history: `archive/docs/archive/PLAN_HISTORY.md`
+Older history: `docs/archive/PLAN_HISTORY.md`
 
 ## Dependencies
 
@@ -293,25 +325,27 @@ walking-skeleton
    │      │
    │      ├── jsonl-session-viability
    │      │      │
-   │      │      ├── graph-data-plane
-   │      │      │      │
-   │      │      │      ├── agent-graph-integration
-   │      │      │      │      │
-   │      │      │      │      ├── authority-model
-   │      │      │      │      │
-   │      │      │      │      └── turn-boundary-reconciliation
-   │      │      │      │             │
-   │      │      │      │             └── coherence-first-class
-   │      │      │      │                    │
-   │      │      │      │                    └── compaction-and-conflict-widening
-   │      │      │      │
-   │      │      │      └── (oracle-design-plan-graphs — horizon)
-   │      │      │
    │      │      ├── web-shell  (M3, can run parallel after M2)
    │      │      │
-   │      │      └── pi-ui-extension-patterns  (parallel after M2; informs M5/M6/M7)
-   │      │
-   │      └── brief-library-curation   (parallel after M0)
+   │      │      ├── pi-ui-extension-patterns  (parallel after M2; informs profile/M5/M6/M7)
+   │      │      │      │
+   │      │      │      └── sealed-pi-profile-runtime-state
+   │      │      │             │
+   │      │      │             ├── graph-data-plane
+   │      │      │             │      │
+   │      │      │             │      ├── agent-graph-integration
+   │      │      │             │      │      │
+   │      │      │             │      │      ├── authority-model
+   │      │      │             │      │      │
+   │      │      │             │      │      └── turn-boundary-reconciliation
+   │      │      │             │      │             │
+   │      │      │             │      │             └── coherence-first-class
+   │      │      │             │      │                    │
+   │      │      │             │      │                    └── compaction-and-conflict-widening
+   │      │      │             │      │
+   │      │      │             │      └── (oracle-design-plan-graphs — horizon)
+   │      │      │
+   │      │      └── brief-library-curation   (parallel after M0)
    │
    └── fixture-strategy-evolution     (continuous, doc-only)
 
diff --git a/memory/SPEC.md b/memory/SPEC.md
index be240a57..c875d050 100644
--- a/memory/SPEC.md
+++ b/memory/SPEC.md
@@ -18,7 +18,7 @@
 
 ### Concept
 
-Brunch is an opinionated local product that helps a human and an agent co-author a **specification workspace** as a graph-native artifact. It runs as a single installable CLI over the `pi-coding-agent` harness and exposes one host through four presentation modes (TUI, web, RPC, print). The intent graph is canonical specification meaning; oracle, design, and plan graphs are accountable downstream planes. Coherence is shared product state, not an implicit hope.
+Brunch is an opinionated local product that helps a human and an agent co-author a **specification** as a graph-native artifact inside the current working directory. It runs as a single installable CLI over the `pi-coding-agent` harness and exposes one host through four presentation modes (TUI, web, RPC, print). The intent graph is canonical specification meaning; oracle, design, and plan graphs are accountable downstream planes. Coherence is shared product state, not an implicit hope.
 
 The POC's purpose is to prove three things: (a) that pi's coding-agent harness can be the substrate without forking it; (b) that a graph-native spec workspace plus a JSONL-first transcript can coexist coherently under one mutation authority; (c) that elicitation-first sessions can project inspectable prompt/response exchanges for observer extraction, replay, and fixture pressure without reintroducing a parallel chat/turn store.
 
@@ -47,7 +47,7 @@ The POC's purpose is to prove three things: (a) that pi's coding-agent harness c
 #### Modes & authority
 
 4. Brunch must expose TUI, web, RPC, and print modes over the same local host authority.
-5. Brunch must support structured `needs_human` outcomes for human-only actions in headless modes.
+5. Brunch must support structured `needs_human` outcomes for human-only actions in headless modes, and headless/RPC clients must receive product-shaped initial spec/session selection or creation requirements instead of TUI-only dialogs.
 6. Brunch must support three authority tiers (autonomous / requires confirmation / human-only) with consistent enforcement across modes.
 
 #### Persistence & data model
@@ -67,15 +67,15 @@ The POC's purpose is to prove three things: (a) that pi's coding-agent harness c
 
 13. Brunch must detect relevant cross-session graph changes between turns and surface them via a `worldUpdate` custom-message role.
 14. Brunch must surface coherence as shared product state to both user and agent.
-15. Brunch must preserve graph and coherence anchors across compaction.
+15. Brunch must preserve graph, coherence, and continuity anchors across compaction; the continuity-anchor list is the externalized auto-compaction anchor contract.
 
 #### Elicitation product shape
 
-16. Brunch must keep sessions elicitation-first: at idle, the user is responding to a system/assistant-originated elicitation prompt rather than initiating ambient free chat.
-17. Brunch must support action, radio (single-select), checkbox (multi-select), and freeform-plus-choice response surfaces as optional typed transcript entries, and must be able to project elicitation exchanges from Pi JSONL for observer extraction.
+16. Brunch must keep sessions elicitation-first and offer-first: at idle, the user is responding to a system/assistant-originated elicitation prompt or structured offer rather than initiating ambient free chat.
+17. Brunch must support action, radio (single-select), checkbox (multi-select), questionnaire, and freeform-plus-choice response surfaces as typed transcript-backed interactions. In TUI mode a pending structured interaction may replace the default input surface with custom UI; in RPC/probe/web-relay contexts the same semantic interaction may travel through Brunch product handlers or Pi's supported extension UI dialogs, including schema-tagged JSON over `ctx.ui.editor` for complex shapes. Brunch must be able to project elicitation exchanges from Pi JSONL for observer extraction, including registered structured-question tool results whose `toolResult.details` is the self-contained structured response payload.
 18. Brunch must support `#`-mentions of graph entities anchored to stable IDs, with session-scoped staleness tracking that produces discretionary re-read hints during `prepareNextTurn`.
-19. Brunch must enforce a workspace state hierarchy `cwd → spec → session`, where the active spec is selected before any agent loop runs, persists across `/new`, and binds each session to exactly one spec.
-20. Brunch must support multiple elicitation lenses within the `elicitor` agent-mode, with the agent owning lens selection and offer through transcript-native establishment offers; lens metadata is carried on elicitor-emitted custom entries for downstream routing.
+19. Brunch must enforce a workspace state hierarchy `workspace(cwd) → spec → session`, where the workspace is only the current working directory invocation root, the user explicitly picks or creates one spec within that workspace before any agent loop runs, and then picks or creates a session within that spec. Spec selection persists across `/new`, and each session binds to exactly one spec.
+20. Brunch must support multiple elicitation lenses within the `elicitor` agent role, with the agent owning lens selection and offer through transcript-native establishment offers; lens metadata is carried on elicitor-emitted custom entries for downstream routing.
 21. Brunch must distinguish *extractive* lenses (single-exchange, observer-extracted) from *generative* lenses (batch-proposal, captured at proposal time as structured entity-draft payloads, reviewer-analyzed post-acceptance).
 22. Brunch must establish a minimum grounding bundle (domain, protagonist, pain/pull, and constraint anchors) before generative lenses produce non-speculative output; lenses remain always-available with epistemic-status signaling honestly reflecting grounding density.
 23. Brunch must support a review-cycle acceptance pattern for generative-lens proposals — approve / request changes (triggering regeneration) / reject — with batch acceptance committed atomically as one CommandExecutor call; partial acceptance is not representable.
@@ -84,6 +84,11 @@ The POC's purpose is to prove three things: (a) that pi's coding-agent harness c
 
 24. Brunch must ship a brief library and an agent-as-user driver over the JSON-RPC stdio surface to capture replayable golden runs and property-checkable fixtures.
 
+#### Runtime profile & prompting
+
+25. Brunch must run the embedded Pi harness through a sealed Brunch Pi Profile: programmatic settings, resource-loader, extension-factory, keybinding, tool, and prompt policy must determine product behavior; ambient user/project `.pi/` resources must not influence Brunch sessions unless Brunch deliberately imports them.
+26. Brunch must distinguish transport modes from operational modes and agent roles: operational modes such as `elicit` and future `execute` gate tool authority and prompt posture, while role presets/bundles select the active top-level role, model/thinking posture, prompt packs, allowed strategies/lenses, and tool policy.
+
 ## Live Architecture Register
 
 ### Open Assumptions
@@ -100,13 +105,16 @@ The POC's purpose is to prove three things: (a) that pi's coding-agent harness c
 | A7-L | `framing_as` as an orthogonal modality on existing node kinds is sufficient for product-intent ontology (problem, persona, JTBD, etc.) and does not need to become first-class node kinds in the POC. | medium | open | D7-L | Fixture runs across briefs #1–#7: if a framing repeatedly demands unique relation policy, promote per the seam-extensions Open Question #8. |
 | A8-L | One reconciliation-need substrate, sharing the same global LSN as the change log, can absorb impasses, conflicts, gaps, and process debt without needing finer kind subtypes in the POC. | medium | open | D8-L | M8 + adversarial fixtures ("contradictory requirements") exercise the substrate; subtype split deferred per Open Question #10. |
 | A9-L | A session-scoped mention ledger of (`entity_id`, `snapshotted_lsn`) is the right granularity for staleness hints; transcript-scoped or graph-scoped ledgers are not needed for the POC. | low | open | I7-L | M7 — turn-boundary reconciliation slice; observed via fixture runs that stress re-read decisions. |
-| A10-L | A persistent TUI chrome region showing cwd / spec / phase / chat-mode can be added on top of `pi-tui`'s root layout without modifying pi. | medium | open | D2-L | M0 — walking skeleton attempts to mount the chrome; escalates to a pi upstream issue only if blocked. |
+| A10-L | A persistent TUI chrome region showing cwd / spec / phase / runtime bundle can be added on top of `pi-tui`'s root layout without modifying pi. | high | validated | D2-L, D35-L | M0 mounted initial chrome through the widget seam; `pi-ui-extension-patterns` Card 2 proved header/footer/status/widget dynamic chrome through a Brunch wrapper plus raw TUI transcript evidence. |
 | A11-L | Pi's `prepareNextTurn` plus custom-message delivery are sufficient to express side-task result delivery without inventing a second event plane or forking pi. | medium | open | D15-L | M5 + M7: side-task registry wiring and next-turn delivery proof. |
 | A13-L | A durable observer-job queue keyed by session id and elicitation-exchange entry range can recover async extraction after process interruption without reintroducing canonical chat/turn tables; whether this shares storage with a generalized work-item/reconciliation table can be deferred. | medium | open | D18-L, I14-L | M5: observer extraction tests exercise restart/idempotence once graph writes exist. |
 | A14-L | LLM elicitor agents can reliably produce graph-structurally-legal intent-graph proposals (well-formed entity drafts and semantic edges that pass `CommandExecutor` structural validation) for generative lenses. | medium | open | D27-L | Fixture replay across briefs that exercise `propose-scenarios-with-tradeoffs`-shaped lenses; dry-run `CommandExecutor` validation at proposal time before user review. Fallback (constrained generation, retry-with-feedback, or NL-parse-at-accept) preserves the user-facing review-cycle if reliability is insufficient. |
 | A15-L | Establishment hints as transcript-native custom entries (`brunch.establishment_offer`) provide sufficient inspectability, fixture-ability, and ambient-affordance source without a separate establishment-needs graph substrate; whether such a substrate ever shares storage with reconciliation needs can be deferred. | medium | open | D25-L, D30-L | M5+: fixture inspection confirms lens offers are reconstructable from transcript; chrome region renders ambient affordances from the latest such entry. |
 | A16-L | Reviewer triggering policy (always-on vs lens-keyed) and reviewer scope (batch + how-far-neighborhood) can be deferred to per-lens decisions without architectural commitment now. | low | open | D29-L | M5+: empirical — observer/reviewer integration reveals which policy avoids unacceptable next-turn latency without losing relevant findings. |
 | A17-L | A user-level temperamental preference for extractive vs generative lenses meaningfully affects adoption and eventually warrants expression as a user-level setting. | low | open | D25-L, D26-L | Deferred; surfaces from outer-loop walkthroughs and adversarial fixtures once both lens families exist in product. |
+| A18-L | Hiding unsupported Pi built-ins from autocomplete plus blocking dangerous session effects is sufficient for the POC product shell even though exact interactive built-ins remain callable until Pi exposes command policy. | medium | open | D2-L, D24-L, D34-L, D35-L | `pi-ui-extension-patterns` product-shell review after command-containment and dynamic Brunch chrome evidence; strict suppression requires a Pi upstream/API change if residual exposure is unacceptable. |
+| A19-L | Pi's current settings/resource lifecycle can be made product-safe through a sealed Brunch Pi Profile without forking Pi: ambient discovery remains disabled, Brunch-owned extension factories may inject explicit resources, and remaining settings/keybinding leakage can be eliminated through programmatic policy or a narrow upstream seam. | medium | open | D39-L | FE-744/profile audit: source-backed resource-loader/settings audit, tests proving no ambient `.pi/` skills/prompts/themes/extensions/context files affect Brunch, and product-owned resources still load when intentionally injected. |
+| A20-L | The Drizzle 1.0 beta line (specifically `drizzle-orm@^1.0.0-beta.15` or later, with the built-in `drizzle-orm/typebox` path that consumes the new `typebox` package) is stable enough for Brunch to depend on for M4 graph persistence and beyond. | medium | open | D16-L, D41-L | M4 scoping spike: round-trip `drizzle-orm@1.0.0-beta.*` + `drizzle-orm/typebox` + `better-sqlite3` + Pi `registerTool` over a representative intent-plane table; if beta blocks land (migrations, SQLite type fidelity, or schema-derivation bugs), fall back to Drizzle 0.x + standalone `drizzle-typebox` + `drizzle-orm/typebox-legacy` and re-evaluate per release. |
 
 ### Active Decisions
 
@@ -114,6 +122,10 @@ The POC's purpose is to prove three things: (a) that pi's coding-agent harness c
 
 - **D1-L — Depend on `pi-coding-agent`, not only `pi-agent-core`.** The POC reuses the coding-agent service bundle, TUI/print adapters, RPC machinery, session logging, and tool plumbing. Dropping down to `pi-agent-core` is a fallback if Brunch proves too different. Depends on: A1-L. Supersedes: —.
 - **D2-L — Brunch is an opinionated product, not a pi platform shell.** The POC hardcodes its toolset, system prompt, and policy doctrine; scopes state to `.brunch/`; and hides pi's generic extension surface from end users. Depends on: A1-L. Supersedes: —.
+- **D39-L — Brunch owns a sealed Pi Profile around the embedded harness.** Product behavior must come from Brunch-owned programmatic policy, not ambient Pi discovery. The profile includes settings policy, resource-loader policy, extension factories, keybinding/command policy, tool policy, and prompt policy. Current known posture disables ambient context files, extensions, prompt templates, skills, and themes while loading Brunch's inline extension shell; Pi source confirms extension `resources_discover` can still inject explicit Brunch-owned skill/prompt/theme paths even when `noSkills`/`noPromptTemplates`/`noThemes` disable ambient discovery. Brunch-owned Pi extensions now live as product modules under flat `src/pi-extensions/*.ts` plus aggregate `src/pi-extensions.ts`, with reusable Pi TUI widgets under `src/pi-components/*`; project-local `.pi/` probe runtime files are retired and must not be treated as product configuration. The remaining weak point is settings leakage through `SettingsManager.create(cwd, agentDir)`, currently only overriding quiet startup; Brunch must audit and either override/seal settings that affect product behavior (shell path/prefix, compaction/retry, image handling, keybindings if exposed) or request a narrow Pi seam. Depends on: D1-L, D2-L, A19-L. Supersedes: treating `noSkills: true` as full profile isolation, relying on user/project `.pi/` defaults to be harmless, or nesting Brunch's product extension modules under `src/pi-extensions/brunch/`.
+- **D40-L — Runtime posture is a transcript-backed Brunch state machine, not hidden extension memory.** Brunch distinguishes operational modes (`elicit`, future `execute`) from agent roles (`elicitor`, `observer`, `reviewer`, `reconciler`, future `executor/orchestrator`, `scout`, `researcher`) and from strategies/lenses. The active top-level role is selected through a role preset/runtime bundle that derives model, thinking level, prompt packs, allowed strategies/lenses, and tool policy rather than storing each knob independently. Brunch runtime helpers append full selected-state product custom entries under `brunch.agent_runtime_state` with `reason: "init" | "switch"`; turn preparation projects the latest valid linear transcript snapshot into prompt and tool posture. The Pi extension module that owns this initial posture is `src/pi-extensions/operational-mode.ts`, not a generic permanent read-only tool-policy toggle. Depends on: D17-L, D23-L, D25-L, D39-L. Supersedes: mode-only vocabulary and extension-local mutable state as authority for agent behavior.
+- **D34-L — Command containment separates visibility suppression from effect blocking.** Current Pi extension seams can hide unsupported slash suggestions with autocomplete wrapping and can cancel branch/session effects through lifecycle hooks, but they cannot strictly suppress exact interactive built-in commands before `InteractiveMode` dispatches them. Brunch-owned commands must use product-specific names and route writes through Brunch handlers/`CommandExecutor`; extension command collisions are not an override mechanism. Strict built-in command/keybinding policy is a Pi upstream/API ask, while POC safety relies on hiding generic affordances, blocking dangerous effects (`/fork`, `/clone`, `/tree`, raw session replacement), and failing fast on branched transcripts. Brunch's command-policy code should live in `src/pi-extensions/command-policy.ts`, merging branch/session-effect blocking with any product command allow/deny behavior instead of preserving a branch-only module. Depends on: D2-L, D24-L, A18-L. Supersedes: treating extension `input` handlers or command-name collisions as built-in command allowlisting.
+- **D35-L — Dynamic TUI chrome is a Brunch projection wrapper over Pi UI primitives.** Downstream TUI affordances should call a Brunch-owned renderer (`renderBrunchChrome` or its successor) with one activated product-state snapshot rather than scattering raw `ctx.ui.setHeader`, `setFooter`, `setWidget`, title, or working-indicator calls. The wrapper is stateless projection over canonical workspace/session/graph facts, including the real activated session id, while its TUI footer compositor may read Pi footer telemetry (`getGitBranch`, foreign `getExtensionStatuses`) at render time. Brunch chrome does not publish a `brunch.chrome` status key; `ctx.ui.setStatus(key, text)` remains a lateral contribution channel for other extensions and future dynamic Brunch state. RPC clients should rely only on surfaces Pi actually emits for the wrapper (currently diagnostic widget/title, plus any future explicit status adapter) because header/footer/working-indicator are TUI-only in current Pi RPC mode. Session display names are likewise product projections over Pi session metadata: Brunch may append Pi `session_info` entries, but generated names must characterize the selected spec/session transcript rather than replace spec identity or graph truth. Depends on: D2-L, D21-L, D34-L, A10-L, A18-L. Supersedes: treating Pi UI methods as direct downstream affordance APIs, rendering placeholder session state such as `unbound` after a session is activated, or consuming the status-key namespace for chrome's own static summary.
 
 #### Data model & vocabulary
 
@@ -130,36 +142,88 @@ The POC's purpose is to prove three things: (a) that pi's coding-agent harness c
 
 #### Transport & client
 
-- **D5-L — JSON-RPC is the primary product protocol.** Same command surface over stdio (RPC mode), WebSocket (browser), and in-process handler calls (TUI/agent tools). HTTP exists only as a transport shim (static bundle, health, uploads, webhooks). The RPC stdio surface is also the agent-as-user fixture-capture interface. Depends on: A5-L. Supersedes: —.
+- **D5-L — Brunch JSON-RPC is the single public product protocol.** Brunch exposes one public product RPC surface over stdio, WebSocket, and in-process handlers. Product clients — web UI, CLI probes, TUI adapters, and future relays — call Brunch method families and should not coordinate raw Pi RPC plus Brunch product RPC themselves. Pi RPC may be used behind a Brunch adapter for agent-loop mechanics and Pi extension UI, but it is not a second public product API. HTTP exists only as a transport shim (static bundle, health, uploads, webhooks). The Brunch stdio surface is also the agent-as-user fixture-capture interface, even when that driver internally relays Pi RPC events. Depends on: A5-L. Supersedes: treating raw Pi RPC as the product API for Brunch data.
 - **D10-L — Web client is a native Brunch React app over one WebSocket RPC client.** TanStack Router + TanStack Query + Brunch-owned elicitation/transcript primitives (Vercel AI SDK UI or TanStack AI style). `pi-web-ui` is not reused. The browser is a thin remote head over Brunch RPC method families, not a second product runtime or REST-backed data client. Depends on: D5-L. Supersedes: —.
-- **D17-L — Brunch semantics ride one event substrate, not parallel channels.** Custom-message transcript entries plus `deliverAs: "nextTurn" | "followUp"` and `prepareNextTurn` are the load-bearing mechanism for structured elicitation prompts/responses, `worldUpdate`, mention-staleness hints, and side-task-result delivery. New product semantics should compose onto this substrate before inventing a second event plane. Depends on: D5-L, D6-L, D12-L, D15-L. Supersedes: —.
-- **D19-L — Keep transport/read architecture thin: named RPC method families over projection handlers.** Brunch exposes named method families such as `session.*`, `workspace.*`, `graph.*`, and `coherence.*`; each handler projects from the canonical store that owns the fact (Pi JSONL, `.brunch/state.json`, or SQLite graph/change log). Subscriptions are first-class and may provide initial state plus updates, but Brunch must not create a generic read-gateway platform, REST read model, DB-backed chat/turn projection, or canonical cross-store event spine merely to keep clients in sync. Depends on: D5-L, D6-L, D10-L, D16-L. Supersedes: the heavier “unified read gateway” mental model.
-- **D23-L — Transport modes are distinct from agent modes and lenses.** TUI, RPC, print, and web are transport modes: ways of driving or observing the same Brunch host through Pi/Brunch harness seams. Agent modes are coarse operational strategies such as `elicitor`, `observer`, `reviewer`, `reconciler`, or future `generalist`; lenses are narrower perspectives such as technical-design, verification-design, or disambiguation that may later be skill-driven. M1 print mode is therefore only a transport proof-of-life: it boots through the same host/coordinator, renders a snapshot of product-shaped state, and exits without running an agent turn. A future single-turn headless print run is deferred until agent-mode selection/defaults are explicit. Depends on: D1-L, D5-L, D19-L, D21-L. Supersedes: overloading “mode” to mean both transport and agent strategy.
+- **D17-L — Brunch semantics ride one transcript/event substrate, not parallel channels.** Pi JSONL transcript entries — ordinary messages, assistant tool-call/toolResult exchanges, and custom messages/entries — plus `deliverAs: "nextTurn" | "followUp"` and `prepareNextTurn` are the load-bearing mechanism for structured elicitation prompts/responses, `worldUpdate`, mention-staleness hints, and side-task-result delivery. New product semantics should compose onto this substrate before inventing a second event plane or a parallel chat/turn store. Depends on: D5-L, D6-L, D12-L, D15-L. Supersedes: custom-message-only interpretations of structured elicitation.
+- **D19-L — Keep product RPC/read architecture thin: named method families over projection handlers.** Brunch exposes named method families such as `workspace.*`, `session.*`, `graph.*`, `coherence.*`, `command.*`, and later `elicitation.*`; each read handler projects from the canonical store that owns the fact (Pi JSONL, `.brunch/state.json`, or SQLite graph/change log), and each mutation handler routes to the Brunch command layer. Subscriptions are first-class and may provide initial state plus updates, and adapter-only agent/UI events may be relayed into product-shaped notifications, but Brunch must not create a generic read-gateway platform, REST read model, DB-backed chat/turn projection, or canonical cross-store event spine merely to keep clients in sync. Depends on: D5-L, D6-L, D10-L, D16-L. Supersedes: the heavier “unified read gateway” mental model and any two-public-RPC-surface split.
+- **D23-L — Transport modes, operational modes, agent roles, strategies, and lenses are separate axes.** TUI, RPC, print, and web are transport modes: ways of driving or observing the same Brunch host through Pi/Brunch harness seams. Operational modes are top-level authority/tooling postures such as `elicit` and future `execute`. Agent roles are active workers within an operational mode (`elicitor`, `observer`, `reviewer`, `reconciler`, future `executor/orchestrator`, `scout`, `researcher`). Strategies are interaction plans; lenses are narrower interpretive/extraction/review framings. M1 print mode is therefore only a transport proof-of-life: it boots through the same host/coordinator, renders a snapshot of product-shaped state, and exits without running an agent turn. A future single-turn headless print run is deferred until runtime bundle selection/defaults are explicit. Depends on: D1-L, D5-L, D19-L, D21-L, D40-L. Supersedes: overloading “mode” to mean both transport and agent strategy, or using “agent mode” for role/preset/lens interchangeably.
 - **D33-L — Transport connections are client attachments, not Brunch sessions.** A Brunch session is a durable linear Pi JSONL transcript bound to exactly one spec; WebSocket connections, stdio streams, TUI instances, and browser tabs are ephemeral presentation attachments to product resources. Session-specific RPC methods should name their target spec/session explicitly or operate through an explicit client attachment; they must not infer durable session identity merely from the transport connection. `.brunch/state.json` remains launch/default acceleration, not concurrency authority. During the POC, Brunch targets a one-writer/many-observer local model: one interactive driver (typically TUI/agent) may write while web clients attach read-only for visual projections. Depends on: D5-L, D10-L, D11-L, D19-L, D21-L, D24-L. Supersedes: treating `/rpc`, a WebSocket, or workspace default state as the active session itself.
 
+  Product RPC / Pi relay model:
+
+  ```text
+  Web UI / CLI probe / TUI adapter
+            │
+            ▼
+  Brunch public JSON-RPC surface
+    ├─ workspace.* / session.* / graph.* / coherence.* reads
+    ├─ command.* named mutations ──► CommandExecutor ──► SQLite graph/change log
+    └─ agent.* / elicitation UI relay ──► Pi adapter
+                                          └─► Pi AgentSession or pi --mode rpc
+                                                 └─► Pi JSONL transcript
+  ```
+
+  Pi extension UI relay for complex questions:
+
+  ```text
+  Assistant tool call asks a structured question
+      │
+      ├─ TUI: tool uses ctx.ui.custom() for rich input replacement
+      │
+      └─ Pi RPC: tool uses ctx.ui.editor(prefill = schema-tagged JSON)
+                 │
+                 ▼
+          Brunch Pi adapter receives extension_ui_request(editor)
+                 │
+                 ▼
+          Brunch public surface exposes product-shaped pending elicitation
+                 │
+                 ▼
+          Web/CLI responds through Brunch (e.g. elicitation.respond)
+                 │
+                 ▼
+          Adapter replies to Pi with extension_ui_response(value = JSON)
+                 │
+                 ▼
+          Tool returns toolResult.content + self-contained toolResult.details
+  ```
+
 #### Persistence
 
 - **D6-L — JSONL-first transcript persistence in `.brunch/sessions/`; SQLite-backed graph persistence in `.brunch/`.** Two durability surfaces with distinct responsibilities. Transcript starts on pi `SessionManager` redirected to the project-local directory; graph plane is SQLite from M4. Brunch does not recreate canonical `chat` or `turn` tables while Pi JSONL remains viable for Brunch-supported linear sessions. Validated by M2. Supersedes: —.
-- **D15-L — Side tasks are a first-class Brunch subsystem delivered through the same transcript/event substrate.** Background sub-agents are tracked by a Brunch-owned `SideTaskRegistry`; results are never injected mid-turn and instead arrive at the next-turn boundary through the existing custom-message plus `prepareNextTurn` path. Side-task writes remain subject to the same command-layer authority as primary-agent writes. Depends on: A11-L, D4-L. Supersedes: —.
-- **D16-L — Graph persistence uses Drizzle over `better-sqlite3`, with one-LSN-per-commit and no bypass paths.** The command layer owns precondition checks, structural validation, entity writes, LSN allocation, change-log append, and any coherence updates inside one transaction. This rule applies equally to migrations and maintenance code; there is no privileged write path outside the command-executor protocol. Depends on: A3-L, A4-L. Supersedes: —.
+- **D15-L — Side tasks are a first-class Brunch subsystem delivered through the same transcript/event substrate.** Side tasks are main-agent-invoked, non-blocking work items: the main agent fires them and continues without awaiting a return value. A Brunch-owned `SideTaskRegistry` tracks status; the only path a side task influences the main agent is by appending a custom-message status update to the session log that arrives at the next-turn boundary through the existing `prepareNextTurn` path — never mid-turn. Side-task writes remain subject to the same command-layer authority as primary-agent writes. This is distinct from D44-L Subagent (main-agent-invoked **blocking** tool call whose result is returned directly as tool content). Depends on: A11-L, D4-L. Supersedes: —.
+- **D16-L — Graph persistence uses Drizzle over `better-sqlite3`, with one-LSN-per-commit and no bypass paths.** The command layer owns precondition checks, structural validation, entity writes, LSN allocation, change-log append, and any coherence updates inside one transaction. This rule applies equally to migrations and maintenance code; there is no privileged write path outside the command-executor protocol. Runtime row/insert/update schemas are derived from Drizzle table definitions via TypeBox per D41-L; the Drizzle version pin is open per A20-L. Depends on: A3-L, A4-L. Refined by: D41-L. Supersedes: —.
 - **D18-L — Observer extraction is exchange-keyed durable work, not a chat/turn store.** After a user response closes an elicitation exchange, Brunch may enqueue an observer job keyed by session id plus exchange entry ids; jobs survive process restart and graph writes still route through the command layer. Routine observer jobs are operational queue state, not reconciliation needs by default; low-confidence or conflicting findings may create reconciliation needs. Depends on: A13-L, D4-L, D13-L, D16-L. Supersedes: the old DB-backed `chat` / `turn` mental model.
 - **D28-L — Regenerated review-set proposals are appended as successor entries in the linear Pi JSONL session; projection helpers filter to the accepted set for context economy.** When the user requests changes, the agent appends a successor proposal entry that references its predecessor via `supersedes`; prior proposals are *not* deleted from JSONL but remain visible as raw transcript history. This stays within Brunch's linear transcript policy — no Pi branching is created. Pi JSONL is treated as a "capture everything" store for replay and audit. Projection helpers used to drive the agent (context injection, summarization) walk the `supersedes` chain and surface only the latest (or ultimately accepted) proposal — the agent does not re-process every superseded proposal as live context. The reviewer likewise sees only the accepted set, not the regeneration history. Depends on: D6-L, D12-L, D17-L, D24-L, D27-L. Supersedes: any "in-place edit" or "fork-on-regenerate" mental model.
-- **D29-L — Reviewer is an `observer`-shaped agent-mode with narrow write authority.** After a batch acceptance closes, Brunch may enqueue a reviewer job keyed by session id plus the batch-acceptance entry id; the job survives process restart and analyzes the accepted batch plus its graph neighborhood for coherence, completeness, and gaps. **Reviewer writes only `reconciliation_need` records via the `CommandExecutor`**; it never writes graph entities, edges, change-log entries directly, or any other record class. Findings reach the user through next-turn delivery as advisory items on the reconciliation-need surface — the batch acceptance remains the user's atomic commitment and the reviewer cannot amend it. (Suggestion-shaped findings may later route to candidate-artefacts when that substrate exists; the POC routes everything to reconciliation needs.) Depends on: A16-L, D4-L, D8-L, D15-L, D17-L, D18-L, D20-L, D27-L. Supersedes: any "reviewer may quietly amend the graph" mental model.
+- **D29-L — Reviewer is an `observer`-shaped agent role with narrow write authority.** After a batch acceptance closes, Brunch may enqueue a reviewer job keyed by session id plus the batch-acceptance entry id; the job survives process restart and analyzes the accepted batch plus its graph neighborhood for coherence, completeness, and gaps. **Reviewer writes only `reconciliation_need` records via the `CommandExecutor`**; it never writes graph entities, edges, change-log entries directly, or any other record class. Findings reach the user through next-turn delivery as advisory items on the reconciliation-need surface — the batch acceptance remains the user's atomic commitment and the reviewer cannot amend it. (Suggestion-shaped findings may later route to candidate-artefacts when that substrate exists; the POC routes everything to reconciliation needs.) Depends on: A16-L, D4-L, D8-L, D15-L, D17-L, D18-L, D20-L, D27-L. Supersedes: any "reviewer may quietly amend the graph" mental model.
 - **D24-L — Brunch POC enforces a linear transcript policy over Pi JSONL.** Pi's session tree is a substrate capability, not a Brunch product surface. Until branch-aware continuity/coherence is explicitly designed, Brunch-controlled interactive/runtime flows block `/tree`, `/fork`, and `/clone` through the thinnest available Pi hooks; transcript readers reject non-linear session files instead of flattening, adapting, migrating, or selecting a branch. This is intentional fail-fast pre-release posture: avoid compatibility debt with Pi internals or earlier Brunch revisions, and keep wrapper/adapter layers minimal. Depends on: D6-L, D11-L, D13-L. Supersedes: treating active-branch projection as Brunch product semantics.
+- **D43-L — Auto-compaction is a Brunch-owned `session_before_compact` extension whose anchor preservation contract is an externalized JSON config.** Brunch always owns this hook because Pi's default summary cannot know about Brunch's transcript-native continuity entries. The extension composes a deterministic preserved-anchor header (rendered byte-stable from the configured anchor set against the pre-compaction branch) with an LLM-generated narrative summary, then returns Pi's standard `{ compaction: { summary, firstKeptEntryId, tokensBefore } }` shape. The summarization model is resolved through the active runtime bundle (D40-L) — typically a cheap/fast "compaction" preset (e.g. Gemini Flash, Haiku) — with fallback to Pi's default compaction on missing auth, empty output, or unexpected error so compaction is never gated on extension success. The anchor contract lives in [src/pi-extensions/auto-compaction-anchors.json](file:///Users/lunelson/Code/hashintel/brunch-next/src/pi-extensions/auto-compaction-anchors.json) as `{ kind, select, rationale }` rules (`select ∈ first | latest | active-leaves | all-unresolved`) so it can be reviewed and updated without SPEC churn; the file is validated through a TypeBox schema per D41-L when the module lands. Brunch-initiated proactive compaction (post-`acceptReviewSet`, on shutdown) and reactor-side compaction triggers are deferred. Session-scoped continuity metadata (`lastSeenLsn`, interest sets) is *projected* from the change log plus the preserved anchor entries — it is not itself an anchor and never appears in the JSON. Depends on: D6-L, D15-L, D17-L, D40-L, D41-L. Supersedes: relying on Pi's default `session_before_compact` summary to keep Brunch-specific continuity intelligible.
+
+#### Schema & validation
+
+- **D41-L — TypeBox is Brunch's single runtime schema vocabulary; Drizzle is the source of truth for persisted shapes.** Every Brunch boundary that needs a runtime schema speaks TypeBox: Pi tool parameters (Pi's `registerTool` already requires JSON-Schema-shaped objects, as in [src/pi-extensions/alternatives.ts](file:///Users/lunelson/Code/hashintel/brunch-next/src/pi-extensions/alternatives.ts)), `brunch.*` custom-entry payloads, Brunch JSON-RPC request/response payloads, observer/reviewer-job result shapes, and SQLite row/insert/update validation projected from Drizzle. Drizzle table definitions remain canonical for persisted shapes; row/insert/update schemas are derived via `drizzle-orm/typebox` (or `drizzle-typebox` while on Drizzle 0.x — see A20-L) rather than hand-authored alongside the table. The runtime library is the new `typebox` package (matching the existing `alternatives.ts` import and `drizzle-orm/typebox` modern path), not `@sinclair/typebox`; `drizzle-orm/typebox-legacy` is permitted only as a temporary fallback if A20-L resolves toward staying on Drizzle 0.x. Static TS types come from `Static<typeof Schema>`; runtime parsing/validation uses `typebox/value` (`Value.Parse`, `Value.Check`, `Value.Errors`). Zod is not adopted. If a downstream library that ships only Zod adapters lands later (for example a TanStack Router search-param validator), Zod stays scoped to that adapter and must not leak into command, RPC, custom-entry, or DB layers. Depends on: D4-L, D5-L, D16-L. Supersedes: an implicit "any runtime schema library is fine" posture, and the existing ambiguity between `typebox` and `@sinclair/typebox`.
 
 #### Interaction & UI shape
 
-- **D11-L — Workspace state hierarchy `cwd → spec → session`, with spec selection gated before any agent loop.** Spec selection is durable across `/new` and persisted in `.brunch/state.json`. Each Pi session is bound to exactly one spec by a `brunch.session_binding` custom entry at session start; switching specs selects or creates another session rather than mutating the spec of the current session. Depends on: A10-L. Supersedes: —.
-- **D21-L — Workspace session coordination is the spec/session boot seam.** Brunch owns a narrow `WorkspaceSessionCoordinator` for boot, spec selection, selected-session reopening, and `/new` session creation. It is the only product module allowed to create or open Pi sessions for Brunch user flows and the only module allowed to write `brunch.session_binding`; callers receive `ready | select_spec | needs_human` workspace-session state and never mutate a session's bound spec. The coordinator hides `SessionManager.create/open/continueRecent(cwd, ".brunch/sessions/")`, internal session-start binding for pi-created replacement sessions, `.brunch/state.json` current-spec and current-session-file acceleration, binding validation, and chrome-state derivation. Because pi defers appending session JSONL until an assistant message exists, the coordinator flushes Brunch's binding when it is created, refreshes it at `before_agent_start`, and performs the final pre-assistant flush from Brunch's internal assistant `message_start` hook after pi has persisted the user message but before assistant persistence; each flush reloads the session file so pi's next assistant append does not duplicate the already-written prefix. Depends on: D6-L, D11-L. Supersedes: the loose `SpecRegistry` + caller-orchestrated session-binding mental model.
-- **D22-L — M0 TUI chrome rides pi's extension UI widget seam.** Brunch's initial persistent chrome is mounted by an internal Brunch extension using pi's public `ExtensionUIContext.setWidget(..., { placement: "aboveEditor" })`, while spec selection remains a Brunch-owned boot gate before `InteractiveMode.run()`. Brunch does not fork pi, monkeypatch `InteractiveMode`, or expose generic pi extension configuration to users for M0 chrome. Depends on: A10-L, D2-L, D21-L. Supersedes: private-header/monkeypatch approaches for M0 chrome.
+- **D11-L — Workspace state hierarchy `workspace(cwd) → spec → session`, with spec and session selection gated before any agent loop.** A Brunch workspace is the single cwd where the CLI is invoked; it is not a user-created container and there is only one per launch context. The cwd's human-readable label may be derived by `src/project-identity.ts` from shallow project manifests (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`) or directory basename, but that label is presentation metadata, not a second selectable container. The first durable choice is the spec: create a new spec, or resume an existing spec. Within an existing spec, the second durable choice is the session: create a new session or resume an existing session. Creating a new spec implicitly creates its first session. Spec selection is durable across `/new` and persisted in `.brunch/state.json`. Each Pi session is bound to exactly one spec by a `brunch.session_binding` custom entry at session start; switching specs selects or creates another session rather than mutating the spec of the current session. Depends on: A10-L. Supersedes: treating “workspace” as the user-created product object in the boot dialog.
+- **D21-L — Workspace session coordination is the spec/session boot seam.** Brunch owns a narrow `WorkspaceSessionCoordinator` for boot, spec inventory, spec/session selection, selected-session reopening, and `/new` session creation. It is the only product module allowed to create or open Pi sessions for Brunch user flows and the only module allowed to write `brunch.session_binding`; callers inspect workspace inventory and activate a product decision rather than mutating a session's bound spec directly. The coordinator hides `SessionManager.create/open/continueRecent(cwd, ".brunch/sessions/")`, internal session-start binding for pi-created replacement sessions, `.brunch/state.json` current-spec and current-session-file acceleration, binding validation, and chrome-state derivation. Because pi defers appending session JSONL until an assistant message exists, the coordinator flushes Brunch's binding when it is created, refreshes it at `before_agent_start`, and performs the final pre-assistant flush from Brunch's internal assistant `message_start` hook after pi has persisted the user message but before assistant persistence; each flush reloads the session file so pi's next assistant append does not duplicate the already-written prefix. Depends on: D6-L, D11-L. Supersedes: the loose `SpecRegistry` + caller-orchestrated session-binding mental model, and treating `.brunch/state.json` as an implicit instruction to resume without user-visible Brunch flow.
+- **D22-L — TUI boot is Brunch-owned before Pi interactive runtime begins.** Brunch's TUI mode may use `@earendil-works/pi-tui` directly for a pre-Pi startup gate that selects or creates the active spec/session before `InteractiveMode.run()`. After activation, persistent chrome is mounted by an internal Brunch extension through Pi's public UI seams. Brunch does not fork pi, monkeypatch `InteractiveMode`, or expose generic pi extension configuration to users for product boot/chrome. Depends on: A10-L, D2-L, D21-L, D36-L. Supersedes: private-header/monkeypatch approaches for M0 chrome and raw readline-only spec selection as the durable TUI product flow.
 - **D12-L — Elicitation-first interaction, transcript-native structured prompts.** Brunch treats system/assistant prompts and user responses as Pi transcript truth. Structured action/choice/freeform surfaces may be represented by Brunch custom entries when needed, but there is no DB-owned prompt/response entity; at idle, the session waits on a system/assistant-originated elicitation prompt. Depends on: D6-L, D11-L. Supersedes: —.
-- **D13-L — Capture-aware elicitation exchange projection.** Observer extraction consumes derived elicitation exchanges: a prompt-side span (all system/assistant/tool-side entries since the previous user response, including any structured/internal prompt content) plus a response-side span (user text and/or structured action entries). Role/span alternation is the default projection in Brunch-supported linear sessions; typed markers are added only where structure/actions need deterministic replay. Depends on: D12-L, D24-L. Supersedes: —.
-- **D14-L — `#`-mentions are ID-anchored, with a session-scoped mention ledger.** Autocomplete may resolve by title but insertion always rewrites to ID-anchored. Per-session `(entity_id, snapshotted_lsn)` ledger drives discretionary `brunch.mention_staleness_hint` entries in `prepareNextTurn`. Depends on: A9-L, I4-L. Supersedes: —.
-- **D25-L — Elicitation strategies are *lenses* within the `elicitor` agent-mode, not separate agent-modes.** Lens is metadata on elicitor-emitted custom transcript entries (`brunch.elicitor_intent_hint`, `brunch.establishment_offer`, `brunch.review_set_proposal`, etc.); agent-modes (`elicitor`, `observer`, `reviewer`, `reconciler`) remain orthogonal. The known starter lens set is `step-by-step`, `disambiguate-via-examples`, `propose-scenarios-with-tradeoffs`, `propose-design-shapes`, `propose-oracle-ensembles`, and `project-requirements-from-upstream`; the catalogue is expected to grow. Observer-job and reviewer-job routing filters on lens. Depends on: D12-L, D17-L, D23-L. Supersedes: collapsing strategy and agent-mode into one vocabulary axis.
-- **D26-L — Lenses split into *extractive* and *generative* families by capture mechanism.** Extractive lenses produce single-exchange interactions whose implicit content is captured by the `observer` agent-mode post-exchange (e.g. `step-by-step`, `disambiguate-via-examples`). Generative lenses produce batch proposals whose entity-draft payloads are captured by the elicitor *at proposal time*, with the `reviewer` agent-mode running advisory analysis post-acceptance (e.g. `propose-scenarios-with-tradeoffs`, `propose-design-shapes`, `propose-oracle-ensembles`, `project-requirements-from-upstream`). The family distinction is durable; the specific lens list is expected to evolve. Depends on: D18-L, D25-L. Supersedes: a single uniform "agent asks questions" mental model.
+- **D37-L — Structured elicitation is Pi-transcript-native; toolResult details may be the canonical structured response.** A system/assistant-originated structured interaction may be represented through the thinnest Pi-supported transcript seam for its shape. For basic structured questions and questionnaires, the preferred seam is a registered Pi tool exchange: the assistant `toolCall` supplies causal/positional context, the toolResult `content` supplies the human/model-readable answer summary, and the toolResult `details` supplies Brunch's self-contained structured response payload (status, mode, prompts/questions, options, answers, transport metadata). Brunch custom messages/entries remain valid for establishment offers, review-set proposals, annotations, and future product-native displays, but they are not mandatory for every structured question. In TUI mode, the tool may replace the default Pi editor with Brunch custom UI supporting single-choice, multi-choice, questionnaire, and optional freeform input. RPC/web paths answer the same semantic pending interaction through Brunch product handlers or Pi-supported dialog fallbacks rather than depending on TUI-only `ctx.ui.custom()`. Depends on: D12-L, D13-L, D17-L, D19-L, D38-L. Supersedes: treating all structured offers as Brunch custom entries or as ephemeral dialog results detached from transcript truth.
+- **D38-L — JSON-over-editor is the Pi-RPC compatibility seam for complex extension UI, not a second product API.** Pi RPC supports `ctx.ui.select`, `confirm`, `input`, and `editor`, but not `ctx.ui.custom()`. When a structured-question tool needs a complex shape (multi-select, questionnaire, review-style response) over raw Pi RPC, the tool may call `ctx.ui.editor()` with schema-tagged JSON prefill and validate the returned JSON before producing normal `toolResult.content` plus self-contained `toolResult.details`. A Brunch-aware adapter may render that JSON as a native product form and translate the user response back into Pi's documented `extension_ui_response`; public clients still speak Brunch RPC methods/events, not ad hoc raw Pi RPC extensions. Depends on: D5-L, D19-L, D33-L, D37-L. Supersedes: inventing unsupported Pi RPC command types for Brunch interactions or exposing raw editor JSON as the product UX.
+- **D13-L — Capture-aware elicitation exchange projection.** Observer extraction consumes derived elicitation exchanges: a prompt-side span (system/assistant/tool-side entries since the previous response, including structured/internal prompt content) plus a response-side span (user text, linked structured response entries, and/or terminal structured-question toolResults whose `details` encode the answer). Role/span alternation is the default projection in Brunch-supported linear sessions, but typed structured-question results override the naive "all toolResults are prompt side" rule where needed for deterministic replay. Depends on: D12-L, D24-L, D37-L. Supersedes: treating Pi message role alone as sufficient to classify structured elicitation response spans.
+- **D14-L — `#`-mentions are stable-handle text references resolved by Brunch, with a session-scoped mention ledger.** Pi autocomplete persists only the inserted `AutocompleteItem.value` as ordinary transcript text; popup labels/descriptions are UI-only. Brunch autocomplete may search by title/description, but insertion must rewrite to a stable handle (`#A12`, `#I7`, or equivalent node handle) that Brunch can resolve to the graph entity id through a read-only lookup/re-read tool when the agent needs detail. Brunch prompt injection (`before_agent_start`) teaches agents how to interpret the handles; Brunch-owned parsing/indexing, not Pi autocomplete, creates mention-ledger state. Per-session `(entity_id, snapshotted_lsn)` ledger drives discretionary `brunch.mention_staleness_hint` entries in `prepareNextTurn`. Depends on: A9-L, I4-L. Supersedes: assuming Pi autocomplete persists hidden mention metadata.
+- **D25-L — Elicitation strategies are *lenses* within the `elicitor` agent role, not separate roles or operational modes.** Lens is metadata on elicitor-emitted custom transcript entries (`brunch.elicitor_intent_hint`, `brunch.establishment_offer`, `brunch.review_set_proposal`, etc.); roles (`elicitor`, `observer`, `reviewer`, `reconciler`) remain orthogonal. The known starter lens set is `step-by-step`, `disambiguate-via-examples`, `propose-scenarios-with-tradeoffs`, `propose-design-shapes`, `propose-oracle-ensembles`, and `project-requirements-from-upstream`; the catalogue is expected to grow. Observer-job and reviewer-job routing filters on lens. Depends on: D12-L, D17-L, D23-L. Supersedes: collapsing strategy and agent role into one vocabulary axis.
+- **D26-L — Lenses split into *extractive* and *generative* families by capture mechanism.** Extractive lenses produce single-exchange interactions whose implicit content is captured by the `observer` role post-exchange (e.g. `step-by-step`, `disambiguate-via-examples`). Generative lenses produce batch proposals whose entity-draft payloads are captured by the elicitor *at proposal time*, with the `reviewer` role running advisory analysis post-acceptance (e.g. `propose-scenarios-with-tradeoffs`, `propose-design-shapes`, `propose-oracle-ensembles`, `project-requirements-from-upstream`). The family distinction is durable; the specific lens list is expected to evolve. Depends on: D18-L, D25-L. Supersedes: a single uniform "agent asks questions" mental model.
 - **D30-L — Grounding is a precondition gate for generative-lens output, with epistemic-status signaling honestly tracking grounding density; lenses themselves are always available.** A minimum grounding bundle — *domain anchor*, *protagonist anchor*, *pain/pull anchor*, *constraint anchor* — must be established before generative lenses produce non-speculative output. Generative-lens proposals declare `epistemic_status` (`inferred | assumed | asserted | observed`) consistent with grounding density at proposal time, and proposal/offer payloads carry explicit grounding-bundle coverage for those four anchors so UI copy, fixture assertions, and reviewer/debug tooling can justify that status rather than infer it from free text. UI renderings reflect this status so low-status proposals *feel* speculative (visible hedging, lower visual weight, explicit "speculative — based on N anchors so far" footers). The lens is never refused: the agent always produces *some form* of what was asked for, but its output resolution and epistemic load honestly reflect what grounding supports. Rendering mode scales with density: empty/thin → framing proposals (Shape Up pitches); moderate → scenario sketches; rich → completion proposals; mature → refactor proposals. Depends on: D26-L. Supersedes: gating-by-refusal as a UX move.
 - **D32-L — Establishment offers are orientation artifacts, not a default next-action menu.** `brunch.establishment_offer` records the agent's current offer tree and recommended next move as durable transcript state. Ambient chrome or web affordances may render the latest offer, and Brunch may expose a user-invoked orientation view summarizing what is established vs open, but Brunch does not surface an exhaustive lens/offer chooser by default; the agent still owns next-move selection unless the user explicitly asks to inspect alternatives. Depends on: D25-L, D30-L, A15-L. Supersedes: UI interpretations that turn establishment offers into a persistent strategy menu.
 - **D31-L — A four-axis meta-rubric is a soft heuristic for fan-out comparison rubrics across all three flows; not architecturally enforced.** When generating comparison rubrics for fan-out alternatives across candidate-spec, technical-design, and verification-design flows, the elicitor attempts to express each axis in terms of (*legibility / cost-of-knowing*, *failure modes*, *coverage / range*, *commitment*). Project-specific axes are allowed alongside; the meta-frame is dropped when it doesn't fit. The hypothesis (uniform comparison UI across all three flows) is testable via fixture comparison; promote to schema/UI only if it holds up. Depends on: D25-L, D26-L. Supersedes: a hardcoded per-flow rubric.
+- **D44-L — Subagents are main-agent-invoked, blocking Pi tool calls that gather data and propose variants for candidate-proposal generation.** Brunch may register a single `subagent` Pi tool whose parameters are `{ agent, task }` or `{ tasks: [] }` (parallel). Each invocation runs as an isolated `pi --mode json -p --no-session --no-skills --no-extensions` subprocess inheriting Brunch's sealed Pi Profile (D39-L); the subagent has no inherited conversation context so the task string must carry everything it needs. Agent definitions are declarative markdown files under `src/pi-extensions/subagents/agents/*.md` with TypeBox-validated frontmatter (`name`, `description`, `tools`, `model`) plus a system-prompt body. Concurrency cap lives in an externalized [src/pi-extensions/subagents/config.json](file:///Users/lunelson/Code/hashintel/brunch-next/src/pi-extensions/subagents/config.json) (default 4) so it can be reviewed and updated without SPEC churn. The subagent's result text is returned directly to the main agent as tool result content; subagents do not append custom messages to the session log on their own behalf, do not invoke the `CommandExecutor`, and do not gain access to the parent's Brunch RPC handlers. POC starter agents split into two families:
+  - **Data gatherers** — read-only context fetchers whose output grounds proposals: **scout** (codebase recon: `read`, `grep`, `find`, `ls`), **researcher** (web research: `web_search`, `web_fetch`), and **graph-reader** (read-only Brunch graph projection tools).
+  - **Variant proposer** — **proposer** (no tools): given a grounding bundle plus a generative-lens-shaped frame, emits exactly one well-formed variant of a candidate proposal. The main agent achieves diversity by issuing parallel `tasks: []` invocations of `proposer` with intentionally distinct framings — the subagent realization of the "design it twice" pattern from `ln-design` and the parallel fan-out anticipated by `ln-oracles`. Each `proposer` invocation runs in its own isolated context so variants don't cross-contaminate; the main agent collects N outputs and composes the comparison via the D31-L meta-rubric (and/or project-specific axes) before writing a `brunch.review_set_proposal` entry through the elicitor flow. `proposer` is system-prompt-only by design: its grounding inputs come entirely through the task string the main agent assembles from preceding `scout` / `researcher` / `graph-reader` calls.
+  This division mirrors the generative-lens family in D26-L: `propose-scenarios-with-tradeoffs`, `propose-design-shapes`, and `propose-oracle-ensembles` are the natural lenses that delegate to fan-out `proposer` invocations; `project-requirements-from-upstream` may stay main-agent-only. Worker-style write-capable subagents are deferred until an execute operational mode lands. Cross-extension agent registration (Amos's `globalThis.__pi_subagents` bridge) is deferred because it conflicts with profile sealing; the POC registry is Brunch-owned only. NDJSON stream events from the subprocess drive TUI tool-progress UI; a `subagent.progress` RPC subscription for headless/web is deferred. Subagents are an optional enhancement to candidate-proposal diversity, not a load-bearing M0–M9 substrate: they enhance R20/D27-L proposal generation when bandwidth permits. Depends on: D2-L, D26-L, D27-L, D30-L, D31-L, D39-L, D41-L. Distinct from: D15-L Side task (non-blocking, status-via-custom-message), the deferred Side chat (user-invoked overlay; see Future Direction Register). Supersedes: —.
+- **D36-L — Spec/session selection is a reusable hierarchical decision model with transport-specific presentations.** Brunch owns a pure spec/session selection model that renders cwd-scoped inventory without calling the user-created object a “workspace”. In TUI mode, the model may present a fast “continue last session” affordance when `.brunch/state.json` points to a valid spec+session; otherwise, or after “other spec/session”, the durable tree is: `create new spec → provide spec name → session created automatically`; `resume existing spec → choose existing spec → create a new session OR resume existing session → choose existing session`. The UI should not list every spec as a top-level action label; “resume existing spec” is the top-level intent, and the spec list is the next screen/scrollable selector. The model returns a product decision (`new spec`, `new session for spec`, `open session`, `continue selected session`, `cancel/quit`) without opening Pi sessions or mutating `.brunch/state.json` itself. The `WorkspaceSessionCoordinator` activates that decision and owns all persistence/session-binding effects. TUI startup and in-session paths share branded `pi-tui` components and colocated logo assets under `src/pi-components/workspace-dialog`; adapters differ only in terminal lifecycle and Pi session-replacement mechanics (`ProcessTerminal`/`TUI.showOverlay` before Pi starts, `ctx.ui.custom(..., { overlay: true })` inside Pi), not in product semantics. RPC/headless transports must not invoke the TUI picker; they expose the same initial-selection requirement and activation decisions as JSON-RPC/product results so CLI JSON-RPC clients can select or create spec/session correctly. Depends on: D11-L, D21-L, D24-L, D33-L. Supersedes: implicit resume of `.brunch/state.json` on TUI launch, Pi `/resume`/`/new` as Brunch's product session chooser, one-off startup-only picker implementations, a flat action list that says “workspace” for specs, top-level `resume spec X` labels, and a separate intermediate action chooser for switching.
+- **D42-L — Session naming is a lifecycle side task over Pi `session_info`, not spec identity.** Brunch should use Pi session lifecycle hooks to opportunistically generate a short human-readable session name that characterizes what happened in the transcript. The preferred trigger is `session_shutdown` for `quit`, `new`, and `resume` replacements because it sees the just-finished transcript and can name it before later picker lists need to distinguish sessions; `session_before_compact` or post-compaction (`session_compact`) may be used to refresh names after major summarization, and a manual command can force regeneration for debugging. The naming call should mirror the model-selection pattern in the local `summarize.ts` extension example: choose a cheap/fast authorized model, extract user/assistant text plus salient tool calls from the current branch, ask for a concise title, and append a Pi `session_info` entry through `SessionManager.appendSessionInfo`. Naming must be best-effort and non-blocking with a tight budget: failures, missing auth, empty transcripts, or shutdown aborts leave the session unnamed rather than blocking session replacement or exit. Generated names label sessions in pickers and chrome, but do not affect spec ids, session bindings, graph truth, or replay semantics. Depends on: D6-L, D17-L, D21-L, D35-L. Supersedes: using spec title or session UUID alone as the only durable display label once transcripts have meaningful content.
 
 ### Critical Invariants
 
@@ -173,7 +237,7 @@ The POC's purpose is to prove three things: (a) that pi's coding-agent harness c
 | I6-L | Every reconciliation need has `created_at_lsn ≤` current global LSN; `kind='impasse'` needs reference at least two graph nodes; resolved needs carry a strictly later `resolved_at_lsn`. | planned (M8 property test) | D8-L, I1-L |
 | I7-L | Every `framing_as` value belongs to the allowed matrix for that node's base kind. | planned (fixture property check) | D7-L |
 | I8-L | Spec selection persists across pi `switchSession` (i.e. `/new`); the selected session file is reopened consistently by headless projection/capture paths; each session has exactly one `brunch.session_binding`, and a session's bound spec never changes. | partially covered (M0 coordinator/TUI boot integration tests + store-only runbook checker; M1 no-injected-coordinator capture regression; M2 coordinator-created JSONL reload tests; manual TUI smoke still planned) | D11-L, D21-L |
-| I9-L | Every `brunch.mention` payload is anchored to a stable `id`; the ledger never stores title-anchored references. | planned (M7 invariant) | D14-L |
+| I9-L | Every `brunch.mention` payload resolves a transcript `#` handle to a stable graph entity id; the ledger never stores title-anchored references or relies on autocomplete popup metadata. | planned (M7 invariant) | D14-L |
 | I10-L | Structured elicitation prompts/responses live in the Pi transcript when structure is needed; Brunch-supported elicitation exchanges are projected only from linear coordinator-bound sessions, and no parallel canonical chat/turn table carries elicitation state. | covered for projection shape and current read surfaces (M1 exchange projection tests, M2 JSONL/RPC projection tests, M3 canonical Brunch session-envelope validation and explicit custom-entry classifiers) | D12-L, D13-L, D18-L, D24-L |
 | I11-L | No durable graph mutation path — including migrations, maintenance scripts, observer-job writes, or side-task-attributed writes — may bypass the `CommandExecutor` path that performs authority/result classification, version checks, structural validation, transaction execution, LSN allocation, and change-log append. | planned (M4 architectural + migration invariants; M5 caller-boundary tests) | D4-L, D15-L, D16-L, D20-L |
 | I12-L | Side-task results are delivered only at turn boundaries; no side-task result may steer or mutate the active turn outside the next-turn delivery path. | planned (M7 side-task delivery invariant) | D15-L |
@@ -183,12 +247,24 @@ The POC's purpose is to prove three things: (a) that pi's coding-agent harness c
 | I16-L | Reviewer-attributed writes target only the `reconciliation_need` substrate; no reviewer-attributed `CommandExecutor` call writes graph entities, edges, change-log entries directly, or any other record class. | planned (M5+ architectural test on reviewer command writers; reviewer-attributed command-result audit) | D29-L; I2-L, I11-L |
 | I17-L | Every generative-lens proposal entry (`brunch.review_set_proposal`) declares an `epistemic_status` (`inferred | assumed | asserted | observed`) and explicit grounding-bundle coverage for the four grounding anchors, with the status consistent with that coverage at proposal time; UI renderings honor this status as a presentation contract. | planned (M5+ proposal-entry schema test; fixture asserts status under thin and rich grounding) | D30-L; A14-L |
 | I18-L | Every elicitor-emitted prompt or proposal custom entry (`brunch.elicitor_intent_hint`, `brunch.establishment_offer`, `brunch.review_set_proposal`) carries a `lens` field; observer-job and reviewer-job routing filters on this field. | planned (M5+ observer/reviewer routing tests; transcript-shape contract test) | D25-L, D26-L, D29-L |
-| I19-L | Brunch-controlled flows do not create or navigate Pi session branches, and Brunch transcript readers fail fast on non-linear JSONL rather than flattening, migrating, or branch-selecting. | partially covered (M3 transcript loader requires exactly one Pi session header, rejects malformed non-header entry shapes, and rejects non-linear child graphs, `parentSession`, and `branch_summary`; product-facing exchange projection helper preserves the non-linear error discriminant and is used by RPC and fixture replay assertions; `session.elicitationExchanges` returns a product-shaped error for non-linear selected sessions over stdio and WebSocket JSON-RPC; Brunch TUI extension cancels `session_before_tree` and `session_before_fork`) | D24-L, D6-L, D11-L, D13-L |
+| I19-L | Brunch-controlled flows do not create or navigate Pi session branches, and Brunch transcript readers fail fast on non-linear JSONL rather than flattening, migrating, or branch-selecting. | partially covered (M3 transcript loader requires exactly one Pi session header, rejects malformed non-header entry shapes, and rejects non-linear child graphs, `parentSession`, and `branch_summary`; product-facing exchange projection helper preserves the non-linear error discriminant and is used by RPC and fixture replay assertions; `session.elicitationExchanges` returns a product-shaped error for non-linear selected sessions over stdio and WebSocket JSON-RPC; Brunch TUI extension cancels `session_before_tree` and `session_before_fork`; Pi command-containment source/RPC evidence shows `session_before_fork` can also cancel clone/fork effects but exact interactive built-ins still need product-shell policy if visibility must be strict; dynamic chrome remains projection-only and does not add branch or mutation authority) | D24-L, D6-L, D11-L, D13-L, D34-L, D35-L |
 | I20-L | Every user-reviewable generative-lens proposal has already passed proposal-time dry-run structural/policy validation against `CommandExecutor`; proposals that fail dry-run validation do not surface as reviewable review sets. | planned (M5+ proposal-validation contract + differential tests) | D27-L; A14-L |
 | I21-L | WebSocket/stdio/TUI client attachment state never becomes the canonical spec/session binding: every session-consuming projection validates the durable `brunch.session_binding`, and write-capable session operations must target an explicit session or future write lease rather than whichever transport connection happens to be open. | partially covered (M3 RPC/WebSocket explicit session projection tests validate durable `brunch.session_binding` for read paths; future write-lease tests remain planned when web input lands) | D10-L, D19-L, D21-L, D33-L |
+| I22-L | Brunch TUI startup must not render prior session transcript entries or enter an agent loop until the user has explicitly activated a spec/session decision; creating a new spec implicitly creates its first session, creating a new session for an existing spec lands in a binding-only session, resuming a prior transcript is opt-in, and RPC/headless startup exposes structured initial-selection state rather than invoking TUI picker code. | covered (FE-744 coordinator tests; hierarchical spec/session picker model + component tests; `workspace.selectionState` / `workspace.activate` JSON-RPC contract tests with source assertion that RPC does not import TUI picker code; `runbooks/verify-startup-no-resume.sh` pty/ANSI-stripped TUI oracle proving stale transcript text is absent before explicit activation) | D11-L, D21-L, D22-L, D36-L |
+| I23-L | Every structured elicitation interaction that owns the response surface persists exactly one terminal structured result (`answered`, `skipped`, `cancelled`, or `unavailable`) in Pi JSONL before the next agent turn consumes it. For structured-question/questionnaire tools, `toolResult.details` is self-contained enough for Brunch projection (status, mode, prompts/questions, options, answers, and transport metadata); the assistant tool-call args are correlation/position rather than the only semantic source. | partial (FE-744 structured-question result schema/builder tests cover self-contained `toolResult.details` and model-readable `content` for text/single/multi/questionnaire plus terminal statuses; TUI adapter tests cover input replacement and builder reuse; JSON-over-editor helper tests cover schema-tagged prefill, validation, and deterministic invalid-response handling; `npm run test:structured-question-rpc-proof` live-proves Pi RPC `extension_ui_request(editor)` / `extension_ui_response(value)` at the adapter layer; elicitation-exchange projection tests cover terminal structured-question tool results as response-side JSONL entries while ordinary tool results remain prompt-side. Brunch public product relay remains pending.) | D12-L, D13-L, D17-L, D37-L, D38-L |
+| I24-L | A Brunch-launched Pi runtime does not load ambient user/project Pi context files, extensions, skills, prompt templates, themes, or behavior-shaping settings unless the Brunch Pi Profile explicitly allows them; Brunch-owned extension-discovered resources are identified as intentional product resources. | planned (sealed-profile audit and resource/settings isolation tests) | D2-L, D39-L |
+| I25-L | The active operational mode, role preset/runtime bundle, strategy, and lens are reconstructable from linear transcript entries at turn start; tool gating follows the reconstructed operational mode so `elicit` cannot use execute/dangerous tools such as raw `bash`/`write` unless explicitly permitted by the bundle. | planned (runtime-state projection tests plus before-agent-start/tool-policy contract tests) | D17-L, D23-L, D40-L |
+| I27-L | Session-name generation is best-effort presentation metadata only: lifecycle hooks may append Pi `session_info` entries, but naming failures never block shutdown/session replacement and generated names never mutate spec identity, session binding, or graph truth. | planned (session-lifecycle naming tests with empty transcript/auth failure/success paths; picker projection tests read session names when present) | D6-L, D21-L, D35-L, D42-L |
+| I26-L | No source module under `src/` imports a runtime schema library other than `typebox` (and `drizzle-orm/typebox` once M4 lands); `zod`, `@sinclair/typebox`, `valibot`, `arktype`, and `effect/schema` do not appear as direct imports in `src/` except behind a deliberately-scoped third-party adapter that the SPEC has acknowledged. Drizzle row/insert/update schemas are not hand-authored alongside their target tables. | planned (grep-based architectural test landing with M4; manual code review until then) | D41-L |
+| I28-L | Auto-compaction output preserves the configured anchor set byte-stable: every entry kind listed in [src/pi-extensions/auto-compaction-anchors.json](file:///Users/lunelson/Code/hashintel/brunch-next/src/pi-extensions/auto-compaction-anchors.json) is reconstructable post-compaction according to its `select` rule (`first | latest | active-leaves | all-unresolved`); LLM-generated narrative summary never replaces or rephrases preserved-anchor content; extension failure falls through to Pi default compaction rather than dropping anchors silently. | planned (compaction round-trip property tests at M9 plus inner-loop anchor-rendering unit tests and TypeBox schema validation of the anchor config) | D43-L; R15, R13; I3-L, I4-L, I8-L, I12-L |
+| I29-L | Subagent subprocesses inherit Brunch Pi Profile sealing: every `subagent` tool invocation spawns `pi --mode json -p --no-session --no-skills --no-extensions` with an explicit per-agent tool allowlist and per-agent model; subagents never load ambient user/project `.pi/` skills, prompts, themes, extensions, context files, or behavior-shaping settings; subagents never gain direct access to the parent's `CommandExecutor`, Brunch RPC handlers, or graph persistence; subagent results return to the main agent only as tool result content (no side-effect transcript writes). | planned (subagent subprocess argv tests; isolation audit asserting absent ambient-resource leakage; tool-allowlist conformance test per starter agent) | D2-L, D39-L, D44-L; I2-L, I11-L, I24-L |
 
 ## Future Direction Register
 
+### Workspace identity and configuration
+
+- **Local Brunch config.** A future `.brunch/config.json` may identify the project root and provide a UI-readable project name, superseding shallow manifest/directory-name inference for display. This would let Brunch launch from subdirectories while still resolving the intended workspace root, but it must preserve the invariant that workspace is a filesystem root/cwd scope rather than a user-created object alongside specs.
+
 ### Framework alignment & deferred subsystems
 
 - **Geolog (TA1.2 data store).** Datalog-shaped logical store eventually backing intent/oracle queries. Domain modelling itself is non-trivial and parallel to Brunch. See pi-seam-extensions §Framework alignment.
@@ -203,6 +279,12 @@ The POC's purpose is to prove three things: (a) that pi's coding-agent harness c
 - Remote deployment shape (headless HTTP/SSE host) modeled on Flue, as a later mode beyond TUI/web/RPC/print.
 - MCP adapter style and per-run event-stream style — Flue's patterns observed and selectively adopted post-POC.
 
+### Prompt/runtime profile architecture
+
+- Brunch prompt composition should be explicit and layered: base Brunch product prompt + operational-mode prompt pack + top-level role preset + strategy prompt pack + lens prompt pack + spec phase/maturity/gates + current graph/coherence/world state + pending structured-interaction rules.
+- Spec phase/maturity is provisionally elicitor-assigned with heuristic assistance rather than purely hidden state or purely derived inference; later validators may warn when transcript/graph evidence and assigned maturity diverge.
+- Core role/lens prompting should usually be product prompt packs rather than Pi skills. Pi skills remain available as Brunch-owned explicit resources when progressive disclosure is the right mechanism, but they are not the primary authority for operational mode/tool policy.
+
 ### Vocabulary evolution
 
 - Whether public graph commands eventually split from one `graph.*` umbrella into `intent.*` / `oracle.*` / `design.*` / `plan.*` namespaces is deferred; current posture is unified `graph.*` for the POC.
@@ -221,26 +303,43 @@ The POC's purpose is to prove three things: (a) that pi's coding-agent harness c
 
 - Whether the elicitation/transcript UI leans more heavily on Vercel AI SDK, TanStack AI primitives, or a thin Brunch-owned spanning abstraction is a post-M3 decision.
 
+### Side chat (deferred)
+
+- **Side chat** is a non-priority user-invoked overlay (slash commands like `/btw` or `/aside`) where the user reasons about something in a separate context without derailing the main session. On close, a **summary** of the side conversation is inserted into the main Pi JSONL transcript as a single custom entry, in the same spirit as Pi branch-summaries or compaction summaries — the full thread is not merged, only its condensed residue. Authority is read-only; the side chat does not write graph, invoke `CommandExecutor`, or affect runtime posture. Reference implementations in the design space: `btw`, `pi-side-chat`, `pi-ghost`, and `oracle` (the last as the single-shot degenerate case). Persistence shape (in-memory vs `.brunch/sessions/<parent>/side/`), model selection, and `peek_main`-style affordances are all deferred until product pressure justifies the feature. Side chat is *not* a candidate-proposal mechanism (that role belongs to D44-L Subagent); it is a user-productivity affordance.
+
 ### Durable state framing
 
 - Brunch's durable state is intentionally split across four semantic substrates: graph truth (nodes/edges), `change_log` audit/history, `coherence_state` verdict, and `reconciliation_need` actionable semantic queue. Routine async work such as observer jobs may use a separate operational queue; if later generalized, table naming may become `work_item` with subtypes, but the POC should not make every observer job a reconciliation need.
 
+### Chrome surface evolution
+
+- **Title and hidden-thinking-label as state-indicative chrome.** Pi exposes `ctx.ui.setTitle()` and `ctx.ui.setHiddenThinkingLabel()` as small dynamic chrome surfaces. Brunch defers wiring them until the question of *what state they should indicate* is sharper. Candidate signals once a canonical chrome-state snapshot exists: terminal title carries spec/session identity with optional working-state tied to the active agent role (e.g. eliciting / observing / reviewing / reconciling) rather than raw `agent_start`/`agent_end`; hidden-thinking label varies by agent role or lens (e.g. "Eliciting…", "Reviewing batch…", "Reconciling…"). Both depend on stable producers for those signals — the chrome wrapper must not synthesize state it doesn't have, so wiring is deferred until the relevant subsystems (agent-role dispatcher, lens registry) land. Until then, Brunch's chrome owns header and footer projection only; title and hidden-thinking-label remain Pi defaults.
+- **Status keys as the dynamic contribution channel.** `ctx.ui.setStatus(key, text)` remains the multi-extension-friendly seam for other Brunch extensions and future dynamic Brunch state to surface in the footer's status row. Brunch's chrome wrapper does not contribute its own status key by default; it merges all foreign status entries via `footerData.getExtensionStatuses()` into the footer's right column so contributions surface without anyone owning the whole footer.
+
 ## Lexicon
 
 | Term | Definition |
 | --- | --- |
 | **Brunch host** | The local process-level authority. Owns `.brunch/` resolution, agent session lifecycle, mode dispatch, and event fanout. |
 | **Transport mode** | One of TUI, web, RPC, print. All four drive the same host; they are presentation/protocol surfaces, not separate products or agent strategies. |
-| **Agent mode** | A coarse operational strategy/persona for an agent run, such as `elicitor`, `observer`, `reviewer`, `reconciler`, or a future `generalist`. Agent modes are selected independently from transport modes. |
-| **Lens** | A narrower interpretive or task perspective applied within or alongside an agent mode, such as technical-design, verification-design, or disambiguation. Lenses may eventually be driven by skills, but are not part of M1 transport-mode proof. |
+| **Operational mode** | A top-level Brunch authority/tooling posture such as `elicit` or future `execute`. It determines what kind of work is allowed and which tools/prompt posture are available. Distinct from Pi's transport mode concept. |
+| **Agent role** | A worker identity within an operational mode. Top-level roles drive the main turn (`elicitor`, future `executor/orchestrator`); side roles run async or advisory work (`observer`, `reviewer`, `reconciler`, future `scout` / `researcher`). |
+| **Runtime bundle / role preset** | The transcript-backed Brunch selection that derives active operational mode, top-level role, model, thinking level, prompt packs, allowed strategies/lenses, and tool policy. Commands switch bundles instead of mutating hidden extension memory. |
+| **Strategy** | A conversation or work tactic selected within the active runtime bundle. Strategies control interaction plan; lenses control interpretive/extraction/review framing. |
+| **Lens** | A narrower interpretive, extraction, or review framing applied within a role/strategy, such as technical-design, verification-design, or disambiguation. Lenses may eventually be driven by Brunch-owned prompt packs or skills. |
+| **Brunch Pi Profile** | The sealed programmatic wrapper around embedded Pi: settings policy, resource-loader policy, extension factories, keybinding/command policy, tool policy, and prompt policy. It allows Brunch-owned resources while suppressing ambient `.pi/` behavior. |
+| **Prompt pack** | A Brunch-owned prompt fragment selected by operational mode, role preset, strategy, lens, or spec phase/maturity. Prompt packs compose at turn boundaries; they are product control-plane state, not ambient Pi prompt templates. |
 | **Print snapshot** | The M1 meaning of the print transport mode: boot the Brunch host, resolve workspace/spec/session state through the coordinator, render product-shaped state, and exit without running an agent turn. |
-| **Spec** | A specification workspace, identified by its intent-graph root. Lives under `.brunch/`. Multiple specs may coexist per project. |
+| **Workspace** | The current working directory where the Brunch CLI was invoked. It scopes `.brunch/` state for the launch context. It is not user-created, not selectable within the dialog, and there is only one active workspace per Brunch process. The UI may display a project identity/name derived from cwd-local manifests or directory basename, but that name labels the cwd; it does not create a separate workspace object. |
+| **Spec / specification** | The user-created specification container within a workspace, identified by its intent-graph root. Multiple specs may coexist under one workspace. A spec contains sessions and the graph data gathered through those sessions (intent nodes, design nodes, oracle/plan data as they land). Future plan-execution mode operates on a selected spec. |
 | **Session** | An elicitation transcript belonging to one spec. Backed by a linear pi JSONL session under `.brunch/sessions/`. A spec may have many sessions over time; a session never changes specs. Pi branch/tree mechanics are unsupported Brunch product behavior in the POC. |
+| **Session display name** | Optional human-readable label for a session, stored as Pi `session_info` metadata and used by pickers/chrome to distinguish sessions. It may be user-set or Brunch-generated from transcript content; it is not canonical spec/session identity. |
 | **Session binding** | The first Brunch custom entry in a session that binds the Pi session id to exactly one spec id and schema version. Makes JSONL self-describing; registry/index state is an acceleration, not the canonical binding. |
 | **Client attachment** | An ephemeral TUI instance, browser tab, stdio stream, or WebSocket connection attached to one or more Brunch product resources for viewing or driving. Client attachment state may guide subscriptions and UI routing, but it is not durable spec/session truth. |
-| **Workspace session coordinator** | The Brunch boot seam that returns `ready | select_spec | needs_human` workspace-session state for a cwd/mode, owns spec selection, selected-session reopening, and `/new`, creates/opens Pi sessions through `SessionManager`, writes `brunch.session_binding`, persists current spec/session acceleration in `.brunch/state.json`, and derives chrome state for callers. |
-| **Workspace state hierarchy** | `cwd → spec → session`. Each level scopes the one below it; spec is selected before any agent loop runs and persists across `/new`. |
-| **Workspace default state** | Lightweight `.brunch/state.json` acceleration for reopening the last selected spec/session in a cwd. It is a launch/default convenience, not the canonical binding of a session and not a multi-client concurrency authority. |
+| **Workspace session coordinator** | The Brunch boot seam that returns `ready | select_spec | needs_human` workspace-session state for a cwd/mode, owns spec selection, selected-session reopening, and `/new`, creates/opens Pi sessions through `SessionManager`, writes `brunch.session_binding`, persists current spec/session acceleration in `.brunch/state.json`, and derives chrome state for callers. “Workspace” in this name refers to cwd scope, not a selectable product object. |
+| **Workspace state hierarchy** | `workspace(cwd) → spec → session`. Each level scopes the one below it; active spec/session activation is Brunch-owned before any agent loop runs, and spec selection persists across `/new`. |
+| **Workspace default state** | Lightweight `.brunch/state.json` acceleration for reopening the last selected spec/session in a cwd. It is a launch/default convenience, not the canonical binding of a session, not an instruction to resume without product flow, and not a multi-client concurrency authority. |
+| **Spec/session selection model** | Brunch-owned hierarchy over cwd-scoped inventory. In TUI, it can render as a picker with a continue-last fast path, then a tree: create new spec → name it → implicit first session; resume existing spec → choose spec → create session or resume existing session → choose session. In RPC/headless modes, the same requirement is exposed as structured product state and activation methods, not a TUI dialog. The model returns a decision; the `WorkspaceSessionCoordinator` activates it and owns all Pi session and binding effects. |
 | **Intent graph** | The canonical specification-meaning plane. Authority over what the system is for. |
 | **Oracle graph** | Verification-strategy plane accountable to intent. Houses Checks, Validation Methods, Evidence, Obligations. |
 | **Design graph** | Modules, interfaces, seams, and adapters accountable to intent. Stubbed in POC. |
@@ -251,18 +350,33 @@ The POC's purpose is to prove three things: (a) that pi's coding-agent harness c
 | **Coherence verdict** | Per-spec product state (`coherent` / `incoherent`) emitted by validators and visible to both UI and agent. |
 | **Command layer** | The single Brunch-owned mutation surface. Validates, gates concurrency, audits, emits events, triggers coherence. Its public mutation entry point is the `CommandExecutor`, not direct ORM calls or caller-side authority gates. |
 | **Command executor** | The deep module that accepts Brunch product commands plus execution context and returns structured command results (`ok`, `needs_human`, `policy_blocked`, `version_conflict`, `structural_illegal`). It hides attribution, minimal pre-M6 authority classification, validation, transaction, LSN, change-log, and coherence-trigger mechanics from callers. |
-| **RPC method family** | A named group of JSON-RPC methods (`session.*`, `workspace.*`, `graph.*`, `coherence.*`) that exposes product behavior through stdio, WebSocket, or in-process handler calls without creating a second API surface. |
+| **Brunch public RPC surface** | The one product-facing JSON-RPC surface exposed over stdio, WebSocket, and in-process handlers. Product clients use this surface for workspace, session, graph, coherence, command, agent, and elicitation behavior; raw Pi RPC is hidden behind adapters when needed. |
+| **RPC method family** | A named group of Brunch JSON-RPC methods (`workspace.*`, `session.*`, `graph.*`, `coherence.*`, `command.*`, later `elicitation.*`) that exposes product behavior through stdio, WebSocket, or in-process handler calls without creating a second public API surface. |
 | **Projection handler** | A thin handler that reads or subscribes to a canonical store and returns product-shaped state for a mode/client. It is not a canonical store itself. |
 | **Subscription** | A long-lived RPC operation that delivers live updates, often with an initial snapshot, for views that must stay current with session, workspace, graph, or coherence state. |
-| **Transport adapter** | The stdio, WebSocket, HTTP-shim, or in-process wrapper around the same Brunch handlers. Transport adapters do not own product semantics. |
+| **Transport adapter** | The stdio, WebSocket, HTTP-shim, Pi-RPC relay, or in-process wrapper around the same Brunch handlers. Transport adapters do not own product semantics. |
+| **Pi RPC adapter** | A private Brunch adapter that speaks Pi's RPC protocol for agent-loop mechanics and extension UI requests, translating Pi events/dialogs into Brunch product-shaped events or method results for public clients. |
 | **Canonical store** | The persistence surface that owns a fact: Pi JSONL for session transcript truth, `.brunch/state.json` for lightweight workspace binding state, SQLite graph/change log for graph truth and coherence substrates. |
 | **Elicitation prompt** | System- or assistant-originated transcript span that prompts/directs the user's next response. At idle, a Brunch-supported linear session ends with an unresolved elicitation prompt. |
 | **User response** | User-originated text and/or structured action selection responding to the current elicitation prompt. There is no ambient chat input in the POC model. |
-| **Elicitation exchange** | A derived projection over Brunch-supported linear Pi JSONL: prompt-side span (system/assistant/tool-side entries since the prior user response) plus response-side span (the user's text and/or structured action entries). This is the observer's default extraction unit. |
-| **Structured elicitation entry** | Optional Brunch custom transcript entry used when an elicitation prompt or response carries actions, choices, or other deterministic UI structure. Plain generative prompts can remain ordinary Pi messages. |
+| **Elicitation exchange** | A derived projection over Brunch-supported linear Pi JSONL: prompt-side span (system/assistant/tool-side entries since the prior response, excluding terminal structured-question results) plus response-side span (the user's text, linked structured action entries, and/or terminal structured-question toolResult details). This is the observer's default extraction unit. |
+| **Structured elicitation entry** | Optional Brunch custom transcript entry used when an elicitation prompt/offer or response carries actions, choices, or other deterministic UI structure. Plain generative prompts can remain ordinary Pi messages. |
+| **Structured offer** | A system/assistant-originated prompt, proposal, or question that owns the response surface until answered, skipped, cancelled, or marked unavailable. Depending on shape, it may be represented by a Brunch custom entry/message, a review-set proposal entry, or a registered Pi tool call whose result details carry the structured response. |
+| **Structured question tool** | A registered Pi tool used by the assistant to ask a typed question or questionnaire. Its toolResult `content` is the model-readable answer summary; its toolResult `details` is Brunch's projection payload. |
+| **Question result details** | The self-contained structured payload in a structured-question/questionnaire toolResult: schema/version, status, mode, prompt/questions, options, answers, and transport metadata. Brunch projection should not need to rehydrate unselected options solely from the assistant tool-call args. |
+| **Offer response** | The terminal structured answer to a structured offer, represented either as a linked Brunch custom entry or as self-contained toolResult details for structured-question tools. It is transcript truth, not an ephemeral UI return value. |
+| **JSON-editor fallback** | A Pi-RPC-compatible adapter for complex interactive shapes: the tool calls `ctx.ui.editor()` with schema-tagged JSON prefill; a Brunch-aware client renders a real form and returns filled JSON through Pi's documented `extension_ui_response`; the tool validates and persists a normal structured result. |
+| **Elicitation UI relay** | The adapter path that translates Pi extension UI requests (including JSON-editor fallback) into Brunch public RPC pending-elicitation events/methods, then translates product responses back into Pi `extension_ui_response` messages. |
 | **Observer job** | Durable async work item keyed by session id and elicitation-exchange entry-range ids. It analyzes an exchange for graph mutations or low-confidence suggestions, and survives process restart. |
 | **Lens switch** | A durable `brunch.lens_switch` transcript entry recording that the active agent/session changed lenses. The switch event is distinct from the lens concept itself. |
-| **Side task** | A scoped sub-agent invocation whose result returns through the shared command layer. |
+| **Side task** | Main-agent-invoked, non-blocking work item tracked by the Brunch `SideTaskRegistry`. The main agent fires it and does not await a return value; the only path it influences the main agent is by appending a custom-message status update to the session log that arrives at the next-turn boundary via `prepareNextTurn`. Side-task writes route through the `CommandExecutor`. Distinct from Subagent (blocking) and Side chat (user-invoked). |
+| **Subagent** | Main-agent-invoked, **blocking** Pi tool call (`subagent`) that runs an isolated `pi` subprocess with a per-agent tool allowlist and per-agent model. Has no inherited conversation context, no `CommandExecutor` access, and no Brunch RPC access. Result text returns directly as tool result content. POC starter agents split into **data gatherers** (scout / researcher / graph-reader — read-only context fetchers that ground proposals) and a **variant proposer** (proposer — system-prompt-only; one variant per invocation, fan-out via parallel mode realizes the "design it twice" pattern). |
+| **Proposer subagent** | The system-prompt-only starter subagent that emits exactly one well-formed candidate-proposal variant per invocation given a grounding bundle plus a generative-lens-shaped frame. Diversity arises from parallel `tasks: []` invocations with intentionally distinct framings; the main agent assembles outputs into a `brunch.review_set_proposal` via the D31-L meta-rubric. Realizes the "design it twice" / parallel-fan-out pattern from `ln-design` and `ln-oracles` skills in subagent form. |
+| **Subagent registry** | The set of registered subagent definitions loaded from `src/pi-extensions/subagents/agents/*.md` at extension activation. Brunch-owned only for the POC; cross-extension agent registration is deferred. |
+| **Subagent agent definition** | A markdown file with TypeBox-validated frontmatter (`name`, `description`, `tools`, `model`) plus a system-prompt body. The frontmatter is the registry contract; the body is the subagent's standing instructions. |
+| **Auto-compaction extension** | The Brunch-owned `session_before_compact` extension (`src/pi-extensions/auto-compaction.ts`) that renders the preserved anchor set as a deterministic markdown header and prepends it to an LLM-generated narrative summary. Resolves its summarization model through the active runtime bundle; falls through to Pi default compaction on auth/empty-output/unexpected errors. |
+| **Preserved anchor set** | The configured list of transcript entry kinds and selection rules that must survive compaction byte-stable. Canonical source is [src/pi-extensions/auto-compaction-anchors.json](file:///Users/lunelson/Code/hashintel/brunch-next/src/pi-extensions/auto-compaction-anchors.json); each rule is `{ kind, select, rationale }` where `select ∈ first | latest | active-leaves | all-unresolved`. Externalized so it can be reviewed and updated for correctness without SPEC churn. |
+| **Anchor contract** | The data inside the preserved-anchor JSON config — distinct from the rendering policy (which lives in code) and the LLM summarization (which is bundle-resolved). |
 | **World update** | `worldUpdate` custom message synthesised in `prepareNextTurn` summarising relevant graph changes since the session's `lastSeenLsn`. |
 | **Mention ledger** | Per-session `(entity_id, snapshotted_lsn)` record driving discretionary staleness hints when an entity has changed since the agent last saw it. |
 | **Authority** | Source of a node's claim: `stakeholder | technical | external | derived`. |
@@ -271,16 +385,16 @@ The POC's purpose is to prove three things: (a) that pi's coding-agent harness c
 | **Kernel** | A behavioural elicitation pattern from `docs/design/BEHAVIORAL_KERNELS.md` (state/lifecycle, containment, concurrency, etc.). |
 | **Brief** | A short curated product brief in `.brunch-fixtures/briefs/`, run by the agent-as-user driver to produce golden captures. Dev-only fixture input; distinct from runtime user-facing **scenarios**. |
 | **Capture / Run / Fixture** | A captured agent-as-user run produces a `.jsonl` transcript, `.graph.json`, `.coherence.json`, and `.meta.json` bundle under `.brunch-fixtures/<brief-id>/<run-id>/`. |
-| **Elicitation lens** | A narrower interpretive strategy applied within the `elicitor` agent-mode — e.g. `step-by-step`, `disambiguate-via-examples`, `propose-scenarios-with-tradeoffs`, `propose-design-shapes`, `propose-oracle-ensembles`, `project-requirements-from-upstream`. Lens is metadata on elicitor-emitted custom transcript entries. Agent-modes (`elicitor` / `observer` / `reviewer` / `reconciler`) remain orthogonal. |
-| **Extractive lens** | A lens producing single-question / single-answer exchanges; implicit content is captured post-exchange by the `observer` agent-mode. Low cognitive load per move; small graph mutations. |
-| **Generative lens** | A lens producing batch proposals (structured entity-draft payloads in `brunch.review_set_proposal` entries); proposals are captured by the elicitor at proposal time, with the `reviewer` agent-mode running advisory analysis post-acceptance. Higher cognitive load per move; large graph mutations on acceptance. |
+| **Elicitation lens** | A narrower interpretive strategy applied within the `elicitor` agent role — e.g. `step-by-step`, `disambiguate-via-examples`, `propose-scenarios-with-tradeoffs`, `propose-design-shapes`, `propose-oracle-ensembles`, `project-requirements-from-upstream`. Lens is metadata on elicitor-emitted custom transcript entries. Agent-modes (`elicitor` / `observer` / `reviewer` / `reconciler`) remain orthogonal. |
+| **Extractive lens** | A lens producing single-question / single-answer exchanges; implicit content is captured post-exchange by the `observer` role. Low cognitive load per move; small graph mutations. |
+| **Generative lens** | A lens producing batch proposals (structured entity-draft payloads in `brunch.review_set_proposal` entries); proposals are captured by the elicitor at proposal time, with the `reviewer` role running advisory analysis post-acceptance. Higher cognitive load per move; large graph mutations on acceptance. |
 | **Grounding bundle** | The minimum set of session-level anchors required before generative lenses produce non-speculative output: a *domain anchor*, a *protagonist anchor*, a *pain/pull anchor*, and a *constraint anchor*. Captured technical constraints land in the constraint anchor and bound subsequent technical-design fan-outs. |
 | **Grounding anchor** | One sentence-scale fact captured during early elicitation that contributes to the grounding bundle. |
 | **Establishment offer** | A `brunch.establishment_offer` custom transcript entry summarising the elicitor's perceived gaps, the available lens strategies for the next move, the recommended lens, and the agent's confidence. Source of ambient affordances rendered in the chrome region; inspectable post-hoc and fixture-able. Orientation artifact, not a default exhaustive strategy menu. |
 | **Elicitor intent hint** | A `brunch.elicitor_intent_hint` custom transcript entry emitted alongside a prompt or proposal, declaring `lens` and semantic targets (e.g. expected ontological sub-type) for downstream observer/reviewer routing and extraction guidance. |
 | **Review set** | A batch proposal generated by a generative lens, presented to the user for review-cycle acceptance (approve / request changes / reject), modeled on the GitHub PR-review-cycle. |
 | **Batch acceptance** | The single `CommandExecutor` call (`acceptReviewSet`) that commits an entire review set atomically as one LSN and one change-log entry, attributed to the user. The only mutation a generative-lens acceptance produces. |
-| **Reviewer** | An agent-mode that runs async after batch acceptance, scoped to the accepted batch plus graph neighborhood, analyzing for coherence / completeness / gaps. Authority is narrow: writes only `reconciliation_need` records via `CommandExecutor`. Architecturally a mirror of `observer`. |
+| **Reviewer** | An agent role that runs async after batch acceptance, scoped to the accepted batch plus graph neighborhood, analyzing for coherence / completeness / gaps. Authority is narrow: writes only `reconciliation_need` records via `CommandExecutor`. Architecturally a mirror of `observer`. |
 | **Anchor scenario** | A particular vignette embedded inside one alternative pitch to ground its framing. Transcript-rendered; not persisted as a graph entity. |
 | **Contrastive scenario** | A particular vignette distinguishing two alternatives, surfaced in comparison UI. Transcript-rendered. |
 | **Probing scenario** | A particular vignette posed by the elicitor to force a user response that disambiguates intent. Transcript-rendered; user response persists per existing elicitation mechanics. |
@@ -342,14 +456,14 @@ Infrastructure is not yet fully laid (Phase 3 of POC bootstrapping). Commands fo
 | --- | --- | --- | --- |
 | Inner | Type-aware lint, type checks, fast unit tests | Local module correctness, typed command/result shapes (including `acceptReviewSet` and reviewer-writable record-class types), projection helper behavior (including `supersedes`-chain filtering). | D12-L, D13-L, D20-L, D21-L, D27-L, D28-L, D29-L. |
 | Inner | Schema/shape validation at boundaries | JSON-RPC payloads, command results, structured elicitation entries, fixture metadata, graph exports, `brunch.review_set_proposal` / `brunch.establishment_offer` / `brunch.elicitor_intent_hint` custom-entry payloads (lens presence, `epistemic_status`, grounding coverage, entity-draft shape). | R8, R10, R11, R17, R20, R21, R23; I3-L, I10-L, I11-L, I17-L, I18-L. |
-| Middle | **Runbook oracles**: prose manual actions plus executable postcondition checkers | Interactive seams leave correct durable state. Early M0 checkers may inspect stores only; once handlers exist, prefer projection-including checks. Extends to in-flight reviewer-signal chrome behavior and ambient-affordance rendering from latest establishment-offer entry. | D11-L, D21-L, D25-L, D29-L; I8-L, I13-L; A10-L. |
+| Middle | **Runbook oracles**: prose manual actions plus executable postcondition checkers | Interactive seams leave correct durable state. Early M0 checkers may inspect stores only; once handlers exist, prefer projection-including checks. Extends to workspace-dialog startup behavior, in-flight reviewer-signal chrome behavior, and ambient-affordance rendering from latest establishment-offer entry. | D11-L, D21-L, D22-L, D25-L, D29-L, D36-L; I8-L, I13-L, I22-L; A10-L. |
 | Middle | Round-trip tests | JSONL reload, linear transcript validation, elicitation exchange projection, compaction, graph export/import, command result serialization, `supersedes`-chain reconstruction across regeneration. | D6-L, D13-L, D24-L, D28-L; I3-L, I8-L, I10-L, I19-L. |
 | Middle | Property-based / model-based tests | LSN monotonicity, change-log replay, reconciliation-need invariants, mention staleness, interest-set recomputation, side-task delivery ordering, **batch-acceptance atomicity (one LSN / one change-log entry, partial-batch impossible even under mid-batch validation failure)**, **`supersedes`-chain acyclicity and unique-leaf-per-thread**, **lens-routing correctness (generated elicitor entries route to the right consumer)**, **reviewer-finding turn-boundary delivery ordering**. | A4-L, A8-L, A9-L, A11-L; I1-L, I4-L, I5-L, I6-L, I9-L, I12-L, I15-L, I16-L, I18-L. |
 | Middle | Contract tests | Named RPC method families and transport adapters share handler semantics; subscriptions deliver initial snapshot plus ordered updates; `CommandExecutor` hides policy/transaction details; `acceptReviewSet` returns expected structured discriminants; only prevalidated proposals become reviewable review sets. | D5-L, D19-L, D20-L, D27-L; R11, R12. |
-| Middle | Architectural boundary tests | No direct ORM/SQLite mutation outside `CommandExecutor`; no canonical chat/turn store; TUI/RPC/fixture code does not write `brunch.session_binding`; Brunch wrappers do not expose Pi branch creation/navigation as product behavior; reviewer-attributed writes target only `reconciliation_need`. | D4-L, D6-L, D18-L, D21-L, D24-L, D29-L; I2-L, I10-L, I11-L, I16-L, I19-L. |
+| Middle | Architectural boundary tests | No direct ORM/SQLite mutation outside `CommandExecutor`; no canonical chat/turn store; TUI/RPC/fixture code does not write `brunch.session_binding`; spec/session picker UI returns decisions rather than opening/mutating sessions; RPC/headless boot exposes structured initial-selection state instead of invoking TUI picker code; Brunch wrappers do not expose Pi branch creation/navigation as product behavior; reviewer-attributed writes target only `reconciliation_need`; Brunch-launched Pi runtimes do not load ambient `.pi/` resources or behavior-shaping settings outside the Brunch Pi Profile. | D4-L, D6-L, D18-L, D21-L, D24-L, D29-L, D36-L, D39-L; I2-L, I10-L, I11-L, I16-L, I19-L, I22-L, I24-L. |
 | Middle | **Differential testing** | Dry-run validation at proposal time matches real-run validation at acceptance time (no drift between modes); free-form-generation vs constrained-generation legality rates (informs whether fallback path is needed per A14-L). | D27-L; A14-L. |
 | Middle | Fixture replay and property assertions | Brief-driven sessions still produce structurally valid transcript/graph/coherence artifacts despite model drift. For generative lenses: **structural-legality rate of LLM proposals tracked per-run in fixture metadata as POC-phase fitness, not a merge gate**; first-attempt vs retry-with-feedback rates surfaced for human review. | A5-L, A6-L, A7-L, A14-L; I7-L; R20, R21, R22, R23. |
-| Outer | Manual walkthrough with checklist | UX/presentation life: TUI chrome, spec selector, web shell feel, coherence visibility, elicitation usefulness. Adds: ambient-affordance rendering from establishment-offer entries; proposal/framing quality review; lens-recommendation appropriateness; review-cycle UX (approve / request-changes / reject); meta-rubric comparative-usefulness review (D31-L hypothesis test). | A10-L, A17-L; R4, R14, R16, R20, R21. |
+| Outer | Manual walkthrough with checklist | UX/presentation life: TUI chrome, spec/session picker, web shell feel, coherence visibility, elicitation usefulness. Adds: ambient-affordance rendering from establishment-offer entries; proposal/framing quality review; lens-recommendation appropriateness; review-cycle UX (approve / request-changes / reject); meta-rubric comparative-usefulness review (D31-L hypothesis test). | A10-L, A17-L; R4, R14, R16, R20, R21. |
 | Outer | Adversarial / generative fixture probes | Elicitation quality, human-gated `needs_human`, contradictory requirements, cross-session updates, long-horizon compaction, **reviewer-finding precision via small targeted set of briefs designed to produce *known* coherence problems** (POC-scope: 1–2 known-bad scenarios per relevant invariant, not exhaustive coverage). | A5-L, A8-L, A9-L, A11-L, A14-L; I4-L, I6-L, I12-L, I13-L, I16-L. |
 
 ### Runbook Oracle Design
@@ -361,7 +475,7 @@ A **runbook oracle** is the preferred bridge for seams that require human intera
 
 Runbook postconditions should be boring and product-shaped: paths exist, JSON fields match, JSONL entries are present and unique, projections reconstruct the same state, command results carry expected discriminants. Store-only checks are acceptable before projection handlers exist; projection-including checks become the default once `workspace.*`, `session.*`, `graph.*`, or `coherence.*` handlers exist.
 
-The first required runbook is M0: after manual TUI interaction, a checker proves `.brunch/` creation, `.brunch/state.json` current spec acceleration, Pi session JSONL files, exactly one `brunch.session_binding` per session, same-spec `/new`, and workspace/session reconstruction when available.
+The first required runbook is M0: after manual TUI interaction, a checker proves `.brunch/` creation, `.brunch/state.json` current spec acceleration, Pi session JSONL files, exactly one `brunch.session_binding` per session, same-spec `/new`, and workspace/session reconstruction when available. FE-744 extends this with a startup-switcher runbook: launch Brunch against a workspace with an existing selected transcript, assert the pre-Pi switcher appears before transcript rendering, choose new-session vs resume paths explicitly, and pair the visual capture with store/projection checks for activated spec/session state.
 
 ### Invariant Oracle Coverage
 
@@ -387,6 +501,13 @@ The first required runbook is M0: after manual TUI interaction, a checker proves
 | I18-L | M5+ inner-loop schema validation on elicitor-emitted custom entries (must declare `lens`); paired with middle-loop property test that generated entries route to the correct observer/reviewer consumer. |
 | I19-L | Brunch extension/runtime guard tests for `/tree`/`/fork`/`/clone` blocking plus transcript-reader non-linearity rejection tests. |
 | I20-L | M5+ proposal-validation contract and differential tests proving only dry-run-valid proposals become reviewable review sets. |
+| I21-L | M3 RPC/WebSocket explicit-session projection tests; future write-lease tests when browser writes land. |
+| I22-L | FE-744 coordinator inventory/activation tests plus pty/ANSI-stripped TUI runbook assertions: no stale transcript before explicit resume, new-spec path creates an implicit first session, new-session path yields binding-only JSONL, resume path renders the chosen transcript, chrome includes activated session id, and RPC/headless boot exposes structured initial-selection state instead of invoking TUI picker code. |
+| I23-L | FE-744 structured-question tests: pending interaction mounts an input-replacing TUI response surface when available; single/multi/questionnaire/freeform answers persist as self-contained toolResult details or linked custom entries; RPC/fixture paths submit the same semantic response through JSON-editor fallback or Brunch product handlers; elicitation-exchange projection pairs the prompt-side tool/custom entry with the terminal structured result. |
+| I24-L | Sealed-profile tests: resource-loader options disable ambient discovery; inline Brunch extension resources still load intentionally through `resources_discover`; settings/keybinding/tool/prompt policy audit proves no ambient user/project `.pi/` setting changes Brunch product behavior. |
+| I25-L | Runtime-state tests: append init/switch custom entries, reload the linear transcript, reconstruct the active operational mode/role preset/strategy/lens, and verify before-agent-start/tool-call policy suppresses disallowed tools for `elicit`. |
+| I28-L | Inner — TypeBox schema validation of [src/pi-extensions/auto-compaction-anchors.json](file:///Users/lunelson/Code/hashintel/brunch-next/src/pi-extensions/auto-compaction-anchors.json) shape; deterministic anchor-rendering unit tests (same branch + same config → same header bytes). Middle (M9) — compaction round-trip property tests across all configured anchors and selection rules; fallback-to-Pi-default behavior under simulated auth failure, empty LLM output, and thrown error. Outer (M9) — long-horizon adversarial fixture confirms session binding, latest runtime state, latest establishment offer, in-flight side-task results, and unresolved staleness hints remain agent-intelligible post-compaction. |
+| I29-L | Inner — argv-shape tests for the `subagent` tool prove every spawned subprocess includes `--no-session --no-skills --no-extensions` plus an explicit per-agent `--tools`/`--extension`/`--models`/`--append-system-prompt` set; TypeBox schema validation of `src/pi-extensions/subagents/agents/*.md` frontmatter and `src/pi-extensions/subagents/config.json`. Middle — isolation audit (no ambient `.pi/` resources reachable inside the subprocess; tool-allowlist conformance per starter agent; parent `CommandExecutor`/Brunch RPC handlers absent from subprocess environment). Outer — fixture-driven proposal-generation runs invoking scout/researcher/graph-reader confirm grounding inputs flow through subagent outputs into review-set proposals without bypassing primary authority. |
 
 ### Design Notes
 
@@ -399,7 +520,7 @@ The first required runbook is M0: after manual TUI interaction, a checker proves
 
 | Blind spot | Reason | Mitigation | Revisit trigger |
 | --- | --- | --- | --- |
-| Full TUI automation | Cost exceeds value before the product state seams are proven. | Manual checklist plus artifact/query runbook oracle. | Manual TUI steps become frequent/flaky or block CI confidence. |
+| Full TUI automation | Cost exceeds value before the product state seams are proven, but startup-switcher regressions need a stronger visual signal than store-only checks. | Manual checklist plus artifact/query runbook oracle; for FE-744 startup, add pty/ANSI-stripped capture assertions for the pre-Pi decision surface and absence of stale transcript before explicit resume. | Manual TUI steps become frequent/flaky or block CI confidence. |
 | LLM elicitation quality and interaction flow | No stable deterministic ground truth for “good interview” early in the POC, and M1 scripted exchanges intentionally encode only a thin current exchange model. | Brief library, human-reviewed golden captures, adversarial probes, expected structural coverage, and later review of knowledge flow through real elicitation loops. | Repeated fixture failures where structure passes but elicitation is judged poor, or M2/M3 reveals that prompt/response markers, offer envelopes, or knowledge-flow assumptions need sharper transcript semantics. |
 | Subscription reconnect/resume | POC can prove snapshot + live update without hardening network recovery yet. | Contract tests for initial snapshot and ordered update sequence. | Web/RPC clients need robust reconnect semantics or long-running fixture runs expose drift. |
 | Performance and scale | Local POC graph/session sizes are small; premature budgets may distort design. | Keep exports/checkers text-native and simple; add budgets when slow tests appear. | `npm run verify` or fixture runs exceed acceptable local iteration time. |
diff --git a/package-lock.json b/package-lock.json
index 777c4cf7..226eb984 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,14 +1,15 @@
 {
-	"name": "brunch",
+	"name": "brunch-next",
 	"version": "0.0.0",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
-			"name": "brunch",
+			"name": "brunch-next",
 			"version": "0.0.0",
 			"dependencies": {
 				"@earendil-works/pi-coding-agent": "^0.75.3",
+				"@earendil-works/pi-tui": "^0.75.4",
 				"@tanstack/react-query": "^5.100.11",
 				"@tanstack/react-router": "^1.170.6",
 				"react": "^19.2.6",
@@ -16,7 +17,7 @@
 				"ws": "^8.20.1"
 			},
 			"bin": {
-				"brunch": "bin/brunch.js"
+				"brunch-next": "bin/brunch.js"
 			},
 			"devDependencies": {
 				"@testing-library/dom": "^10.4.1",
@@ -1059,19 +1060,19 @@
 			}
 		},
 		"node_modules/@earendil-works/pi-tui": {
-			"version": "0.75.3",
-			"resolved": "https://registry.npmjs.org/@earendil-works/pi-tui/-/pi-tui-0.75.3.tgz",
-			"integrity": "sha512-UbhtCsae+b3Y8/ZxtBPhiOrkD66gOHvJbfvLZwhBBsNtQuvUkZY5t9MQwmb8QcDYkFRnXHaq3FcEy1hjRSfj6w==",
+			"version": "0.75.4",
+			"resolved": "https://registry.npmjs.org/@earendil-works/pi-tui/-/pi-tui-0.75.4.tgz",
+			"integrity": "sha512-PDhKU7u6fmEcvHUFHzrRwGc/Ytokj/hO+X4RPf+MWKEGpvg3B1vHv88Ee+Dy33004tYkQF5YeXV4btJZcp5x1g==",
 			"license": "MIT",
 			"dependencies": {
-				"get-east-asian-width": "^1.3.0",
-				"marked": "^15.0.12"
+				"get-east-asian-width": "1.6.0",
+				"marked": "15.0.12"
 			},
 			"engines": {
 				"node": ">=22.19.0"
 			},
 			"optionalDependencies": {
-				"koffi": "^2.9.0"
+				"koffi": "2.16.2"
 			}
 		},
 		"node_modules/@esbuild/aix-ppc64": {
diff --git a/package.json b/package.json
index 0a30eb52..82f440e4 100644
--- a/package.json
+++ b/package.json
@@ -1,35 +1,40 @@
 {
-	"name": "brunch",
+	"name": "brunch-next",
 	"version": "0.0.0",
-	"description": "Brunch — opinionated specification-workspace product over pi-coding-agent.",
+	"description": "Brunch \u2014 opinionated specification-workspace product over pi-coding-agent.",
 	"private": true,
 	"type": "module",
 	"main": "./dist/brunch.js",
 	"types": "./dist/brunch.d.ts",
 	"bin": {
-		"brunch": "./bin/brunch.js"
+		"brunch-next": "./bin/brunch.js"
 	},
 	"files": [
 		"dist",
 		"dist-web",
-		"bin"
+		"bin",
+		"assets"
 	],
 	"scripts": {
 		"dev": "tsx src/brunch.ts",
-		"build": "tsc -p tsconfig.json && npm run build:web",
+		"build": "tsc -p tsconfig.build.json && npm run build:pi-assets && npm run build:web",
+		"build:pi-assets": "mkdir -p dist/pi-components/workspace-dialog && cp -R src/pi-components/workspace-dialog/assets dist/pi-components/workspace-dialog/",
 		"build:web": "vite build",
 		"test": "vitest --run",
+		"test:structured-question-rpc-proof": "vitest --run src/structured-question-rpc-proof.test.ts",
 		"test:watch": "vitest",
-		"lint": "oxlint src",
-		"lint:fix": "oxlint --fix src",
-		"fmt": "oxfmt src",
-		"fmt:check": "oxfmt --check src",
+		"lint": "oxlint src .pi/extensions",
+		"lint:fix": "oxlint --fix src .pi/extensions",
+		"fmt": "oxfmt src .pi/extensions",
+		"fmt:check": "oxfmt --check src .pi/extensions",
 		"fix": "npm run lint:fix && npm run fmt",
-		"check": "npm run fmt:check && npm run lint",
-		"verify": "npm run check && npm run test && npm run build"
+		"check": "npm run fmt:check && npm run lint && npm run typecheck",
+		"verify": "npm run check && npm run test && npm run build",
+		"typecheck": "tsc -p tsconfig.json"
 	},
 	"dependencies": {
 		"@earendil-works/pi-coding-agent": "^0.75.3",
+		"@earendil-works/pi-tui": "^0.75.4",
 		"@tanstack/react-query": "^5.100.11",
 		"@tanstack/react-router": "^1.170.6",
 		"react": "^19.2.6",
diff --git a/runbooks/verify-m1.sh b/runbooks/verify-m1.sh
index 71e2f279..23f6aa32 100755
--- a/runbooks/verify-m1.sh
+++ b/runbooks/verify-m1.sh
@@ -100,14 +100,14 @@ import { createWorkspaceSessionCoordinator } from "./src/workspace-session-coord
 
 const cwd = process.env.TMP_WORKSPACE
 const coordinator = createWorkspaceSessionCoordinator({ cwd })
-const workspace = await coordinator.startOrCreate({ specTitle: "M1 runbook smoke" })
+const workspace = await coordinator.createSetupSession({ specTitle: "M1 runbook smoke" })
 workspace.session.manager.appendCustomMessageEntry(
   "brunch.elicitation_prompt",
   "Runbook prompt: confirm the M1 mode shell is product-shaped.",
   true,
 )
 workspace.session.manager.appendMessage({ role: "user", content: "Runbook response" })
-await coordinator.bindCurrentSpecToSession(workspace.session.manager)
+await coordinator.bindCurrentSpecToReplacementSession(workspace.session.manager)
 NODE
 
 run_check "Print-mode smoke output" \
diff --git a/runbooks/verify-startup-no-resume.sh b/runbooks/verify-startup-no-resume.sh
new file mode 100755
index 00000000..9a8bf44d
--- /dev/null
+++ b/runbooks/verify-startup-no-resume.sh
@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Proves FE-744/I22 at the terminal boundary: Brunch TUI startup shows the
+# spec/session picker before any prior transcript is rendered. This runbook uses
+# a real pty via `script`; it is intended as a manual/middle-loop oracle rather
+# than part of the default verify gate.
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+WORK_DIR="${WORK_DIR:-$(mktemp -d "${TMPDIR:-/tmp}/brunch-startup-oracle.XXXXXX")}"
+CAPTURE_RAW="$WORK_DIR/startup.raw"
+CAPTURE_STRIPPED="$WORK_DIR/startup.stripped"
+STALE_TEXT="BRUNCH_STALE_TRANSCRIPT_SENTINEL_$(date +%s)_$$"
+
+cd "$ROOT_DIR"
+npm run build >/dev/null
+
+STALE_TEXT="$STALE_TEXT" WORK_DIR="$WORK_DIR" node --input-type=module <<'NODE'
+import { createWorkspaceSessionCoordinator } from './dist/workspace-session-coordinator.js'
+
+const cwd = process.env.WORK_DIR
+const staleText = process.env.STALE_TEXT
+const coordinator = createWorkspaceSessionCoordinator({ cwd })
+const workspace = await coordinator.createSetupSession({
+  specTitle: 'Startup Oracle Spec',
+})
+workspace.session.manager.appendMessage({
+  role: 'assistant',
+  content: staleText,
+})
+console.log(`Seeded stale transcript: ${workspace.session.file}`)
+NODE
+
+BRUNCH_CMD="cd '$WORK_DIR' && PI_OFFLINE=1 node '$ROOT_DIR/dist/brunch.js' --mode tui"
+
+set +e
+if script --version >/dev/null 2>&1; then
+  perl -e 'alarm shift; exec @ARGV' 3 script -q -f -c "$BRUNCH_CMD" "$CAPTURE_RAW"
+else
+  perl -e 'alarm shift; exec @ARGV' 3 script -q -F "$CAPTURE_RAW" /bin/sh -lc "$BRUNCH_CMD"
+fi
+set -e
+
+perl -CS -pe 's/\e\[[0-?]*[ -\/]*[@-~]//g; s/\e\][^\a]*(\a|\e\\)//g; s/\eP.*?(\a|\e\\)//g; s/\r/\n/g' \
+  "$CAPTURE_RAW" > "$CAPTURE_STRIPPED"
+
+if grep -Fq "$STALE_TEXT" "$CAPTURE_STRIPPED"; then
+  echo "FAILED: startup rendered stale transcript text before explicit activation" >&2
+  echo "Capture: $CAPTURE_STRIPPED" >&2
+  exit 1
+fi
+
+if ! grep -Eq "Choose a specification|Create new specification|New specification title" "$CAPTURE_STRIPPED"; then
+  echo "FAILED: startup capture did not show a stable spec/session picker marker" >&2
+  echo "Capture: $CAPTURE_STRIPPED" >&2
+  exit 1
+fi
+
+cat <<EOF
+Startup no-resume oracle passed.
+
+Workspace: $WORK_DIR
+Raw capture: $CAPTURE_RAW
+Stripped capture: $CAPTURE_STRIPPED
+Assertion: stale transcript sentinel was absent before explicit activation.
+EOF
diff --git a/src/brunch-tui.test.ts b/src/brunch-tui.test.ts
index 53181275..ed6c3eaa 100644
--- a/src/brunch-tui.test.ts
+++ b/src/brunch-tui.test.ts
@@ -1,3 +1,4 @@
+import { userMessage } from "./test-helpers.js"
 import { mkdtemp, readFile } from "node:fs/promises"
 import { tmpdir } from "node:os"
 import { join } from "node:path"
@@ -6,16 +7,34 @@ import { describe, expect, it } from "vitest"
 
 import {
   SessionManager,
+  type ExtensionCommandContext,
   type ExtensionContext,
   type ExtensionUIContext,
+  type RegisteredCommand,
 } from "@earendil-works/pi-coding-agent"
 
 import {
-  createBrunchChromeExtension,
-  formatChromeWidgetLines,
+  applyBrunchOfflineDefault,
+  brunchResourceLoaderOptions,
+  createBrunchSettingsManager,
   runBrunchTui,
 } from "./brunch-tui.js"
-import { verifyWorkspaceSessionStores } from "./workspace-session-coordinator.js"
+import {
+  BRUNCH_WORKSPACE_COMMAND,
+  BRUNCH_WORKSPACE_SHORTCUT,
+  chromeStateForWorkspace,
+  createBrunchPiExtensionShell,
+  registerBrunchAlternatives,
+  registerBrunchOperationalModePolicy,
+  runBrunchWorkspaceCommand,
+  runBrunchWorkspaceAction,
+} from "./pi-extensions.js"
+import {
+  createWorkspaceSessionCoordinator,
+  verifyWorkspaceSessionStores,
+  type WorkspaceLaunchInventory,
+  type WorkspaceSessionReadyState,
+} from "./workspace-session-coordinator.js"
 
 describe("Brunch TUI boot", () => {
   it("gates spec selection through the coordinator before launching interactive mode", async () => {
@@ -44,18 +63,121 @@ describe("Brunch TUI boot", () => {
     }
   })
 
-  it("passes coordinator chrome state to the persistent chrome widget", async () => {
-    const lines = formatChromeWidgetLines({
+  it("runs inspect, preflight, and activation before launching interactive mode", async () => {
+    const events: string[] = []
+    const workspace = readyWorkspace("/tmp/project", "session-ready")
+
+    await runBrunchTui({
       cwd: "/tmp/project",
-      spec: { id: "spec-1", title: "Spec One" },
-      phase: "elicitation",
-      chatMode: "responding-to-elicitation",
+      coordinator: {
+        inspectWorkspace: async () => {
+          events.push("inspect")
+          return {
+            cwd: "/tmp/project",
+            currentSpec: workspace.spec,
+            currentSessionFile: workspace.session.file,
+            needsNewSpec: false,
+            specs: [],
+            unavailableSessions: [],
+          }
+        },
+        activateWorkspace: async (decision) => {
+          events.push(`activate:${decision.action}`)
+          return workspace
+        },
+        bindCurrentSpecToReplacementSession: async () => workspace,
+      },
+      runWorkspaceDialogPreflight: async () => {
+        events.push("preflight")
+        return {
+          action: "continue",
+          specId: workspace.spec.id,
+          sessionFile: workspace.session.file,
+        }
+      },
+      launchInteractive: async ({ workspace: launched }) => {
+        events.push(`launch:${launched.session.id}`)
+      },
+    })
+
+    expect(events).toEqual([
+      "inspect",
+      "preflight",
+      "activate:continue",
+      "launch:session-ready",
+    ])
+  })
+
+  it("does not launch interactive mode when startup preflight is cancelled", async () => {
+    const events: string[] = []
+    const workspace = readyWorkspace("/tmp/project", "session-ready")
+
+    await runBrunchTui({
+      cwd: "/tmp/project",
+      coordinator: {
+        inspectWorkspace: async () => {
+          events.push("inspect")
+          return {
+            cwd: "/tmp/project",
+            currentSpec: workspace.spec,
+            currentSessionFile: workspace.session.file,
+            needsNewSpec: false,
+            specs: [],
+            unavailableSessions: [],
+          }
+        },
+        activateWorkspace: async () => {
+          events.push("activate")
+          return {
+            status: "cancelled",
+            cwd: "/tmp/project",
+            chrome: workspace.chrome,
+          }
+        },
+        bindCurrentSpecToReplacementSession: async () => workspace,
+      },
+      runWorkspaceDialogPreflight: async () => {
+        events.push("preflight")
+        return { action: "cancel" }
+      },
+      launchInteractive: async () => {
+        events.push("launch")
+      },
     })
 
-    expect(lines.join("\n")).toContain("cwd: /tmp/project")
-    expect(lines.join("\n")).toContain("spec: Spec One")
-    expect(lines.join("\n")).toContain("phase: elicitation")
-    expect(lines.join("\n")).toContain("chat: responding-to-elicitation")
+    expect(events).toEqual(["inspect", "preflight", "activate"])
+  })
+
+  it("chooses a new binding-only session instead of implicitly resuming stale transcript", async () => {
+    const cwd = await mkdtemp(join(tmpdir(), "brunch-tui-"))
+    const coordinator = createWorkspaceSessionCoordinator({ cwd })
+    const first = await coordinator.createSetupSession({
+      specTitle: "Spec One",
+    })
+    first.session.manager.appendMessage(userMessage("stale transcript"))
+    const firstContent = await readFile(first.session.file, "utf8")
+    let launchedSessionFile: string | undefined
+
+    await runBrunchTui({
+      cwd,
+      coordinator,
+      runWorkspaceDialogPreflight: async () => ({
+        action: "newSession",
+        specId: first.spec.id,
+      }),
+      launchInteractive: async ({ workspace }) => {
+        launchedSessionFile = workspace.session.file
+      },
+    })
+
+    expect(launchedSessionFile).toBeDefined()
+    expect(launchedSessionFile).not.toBe(first.session.file)
+    await expect(readFile(first.session.file, "utf8")).resolves.toBe(
+      firstContent,
+    )
+    expect(await readFile(launchedSessionFile!, "utf8")).not.toContain(
+      "stale transcript",
+    )
   })
 
   it("binds replacement sessions through internal session boundary events", async () => {
@@ -63,70 +185,317 @@ describe("Brunch TUI boot", () => {
     const manager = SessionManager.create(cwd, join(cwd, ".brunch", "sessions"))
     const boundSessionIds: string[] = []
     const widgets = new Map<string, string[]>()
+    const titles: string[] = []
     const ui: FakeExtensionUi = {
+      setHeader: (_factory) => {},
+      setFooter: (_factory) => {},
+      setStatus: (_key, _text) => {},
       setWidget: (key: string, content: unknown) => {
         if (isStringArray(content)) {
           widgets.set(key, content)
         }
       },
-      setTitle: (_title: string) => {},
+      setWorkingIndicator: (_options) => {},
+      setTitle: (title: string) => titles.push(title),
       notify: (_message: string, _type?: "info" | "warning" | "error") => {},
     }
     const ctx: FakeExtensionContext = { sessionManager: manager, ui }
-    let sessionStart: ((
+    const sessionStart: Array<(
       event: unknown,
       ctx: FakeExtensionContext,
-    ) => Promise<void>) | undefined
-    let beforeAgentStart: ((
+    ) => Promise<void>> = []
+    const beforeAgentStart: Array<(
       event: unknown,
       ctx: FakeExtensionContext,
-    ) => Promise<void>) | undefined
-    let messageStart: ((
+    ) => Promise<void>> = []
+    const messageStart: Array<(
       event: unknown,
       ctx: FakeExtensionContext,
-    ) => Promise<void>) | undefined
+    ) => Promise<void>> = []
 
-    createBrunchChromeExtension(
-      {
-        cwd,
-        spec: { id: "spec-1", title: "Spec One" },
-        phase: "elicitation",
-        chatMode: "responding-to-elicitation",
-      },
+    createBrunchPiExtensionShell(
+      chromeStateForWorkspace(readyWorkspace(cwd, manager.getSessionId())),
       (sessionManager) => {
         boundSessionIds.push(sessionManager.getSessionId())
       },
+      { coordinator: noOpWorkspaceCoordinator(cwd) },
     )({
-      on: (event: string, handler: typeof sessionStart) => {
+      on: (event: string, handler: never) => {
         if (event === "session_start") {
-          sessionStart = handler
+          sessionStart.push(handler)
         }
         if (event === "before_agent_start") {
-          beforeAgentStart = handler
+          beforeAgentStart.push(handler)
         }
         if (event === "message_start") {
-          messageStart = handler
+          messageStart.push(handler)
         }
       },
+      registerCommand: (_name: string, _options: unknown) => {},
     } as never)
 
-    await sessionStart?.({}, ctx)
-    await beforeAgentStart?.({}, ctx)
-    await messageStart?.(
-      { type: "message_start", message: { role: "user" } },
-      ctx,
-    )
-    await messageStart?.(
-      { type: "message_start", message: { role: "assistant" } },
-      ctx,
-    )
+    for (const handler of sessionStart) await handler({}, ctx)
+    for (const handler of beforeAgentStart) await handler({}, ctx)
+    for (const handler of messageStart) {
+      await handler({ type: "message_start", message: { role: "user" } }, ctx)
+    }
+    for (const handler of messageStart) {
+      await handler(
+        { type: "message_start", message: { role: "assistant" } },
+        ctx,
+      )
+    }
 
     expect(boundSessionIds).toEqual([
       manager.getSessionId(),
       manager.getSessionId(),
       manager.getSessionId(),
     ])
-    expect(widgets.get("brunch.chrome")?.join("\n")).toContain("Spec One")
+    expect(widgets.get("brunch.chrome")?.join("\n")).toContain(
+      "chat mode: responding-to-elicitation",
+    )
+    expect(titles).toEqual(["brunch — Spec One"])
+  })
+
+  it("registers the Brunch spec/session picker command and shortcut", async () => {
+    const commands =
+      new Map<string, Omit<RegisteredCommand, "name" | "sourceInfo">>()
+    const shortcuts =
+      new Map<string, Omit<RegisteredCommand, "name" | "sourceInfo">>()
+    const registeredTools: string[] = []
+
+    createBrunchPiExtensionShell(
+      chromeStateForWorkspace(readyWorkspace("/tmp/project", "session-1")),
+      undefined,
+      {
+        coordinator: {
+          inspectWorkspace: async () => emptyInventory("/tmp/project"),
+          activateWorkspace: async () =>
+            readyWorkspace("/tmp/project", "session-1"),
+        },
+      },
+    )({
+      on: (_event: string, _handler: unknown) => {},
+      registerCommand: (name: string, opts: unknown) =>
+        commands.set(name, opts as never),
+      registerShortcut: (name: string, opts: unknown) =>
+        shortcuts.set(name, opts as never),
+      registerTool: (tool: { name: string }) => registeredTools.push(tool.name),
+      registerMessageRenderer: (_type: string) => {},
+      sendMessage: (_message: unknown) => {},
+      getAllTools: () =>
+        ["read", "grep", "find", "ls", "bash"].map((name) => ({ name })),
+      setActiveTools: (_tools: string[]) => {},
+    } as never)
+
+    expect(registeredTools).toEqual([
+      "read",
+      "grep",
+      "find",
+      "ls",
+      "present_alternatives",
+      "brunch_structured_question",
+    ])
+    expect(commands.get(BRUNCH_WORKSPACE_COMMAND)?.description).toBe(
+      "Open the Brunch spec/session picker",
+    )
+    const retiredWorkspaceCommand = ["brunch", "workspace"].join("-")
+    expect(commands.has(retiredWorkspaceCommand)).toBe(false)
+    expect(shortcuts.get(BRUNCH_WORKSPACE_SHORTCUT)?.description).toBe(
+      "Open the Brunch spec/session picker",
+    )
+    expect(shortcuts.has("ctrl+b")).toBe(false)
+
+    const shortcutEvents: string[] = []
+    const shortcut = shortcuts.get(BRUNCH_WORKSPACE_SHORTCUT)
+    expect(shortcut).toBeDefined()
+    const shortcutHandler = shortcut!.handler as (
+      ctx: unknown,
+    ) => Promise<void> | void
+    await shortcutHandler({
+      ui: fakeUi((method, type) => shortcutEvents.push(`${method}:${type}`)),
+    })
+    expect(shortcutEvents).toEqual(["notify:warning"])
+  })
+
+  it("opens the spec/session picker from the Brunch command", async () => {
+    const events: string[] = []
+    const target = readyWorkspace("/tmp/project", "session-target")
+    const ctx = fakeCommandContext({
+      currentSessionFile: "/sessions/session-old.jsonl",
+      decisions: [
+        {
+          action: "openSession",
+          specId: target.spec.id,
+          sessionFile: target.session.file,
+        },
+      ],
+      onEvent: (event) => events.push(event),
+    })
+
+    await runBrunchWorkspaceCommand(ctx, {
+      inspectWorkspace: async () => {
+        events.push("inspect")
+        return inventoryWithWorkspace(target)
+      },
+      activateWorkspace: async (decision) => {
+        events.push(`activate:${decision.action}`)
+        return target
+      },
+    })
+
+    expect(events).toEqual([
+      "waitForIdle",
+      "inspect",
+      "custom",
+      "activate:openSession",
+      `switch:${target.session.file}`,
+      "notify:info",
+    ])
+  })
+
+  it("runs the in-session workspace switch through coordinator activation and replacement context", async () => {
+    const events: string[] = []
+    const customOptions: unknown[] = []
+    const target = readyWorkspace("/tmp/project", "session-target")
+    const replacementUi = fakeUi((method) =>
+      events.push(`replacement:${method}`),
+    )
+    const ctx = fakeCommandContext({
+      currentSessionFile: "/sessions/session-old.jsonl",
+      decision: {
+        action: "openSession",
+        specId: target.spec.id,
+        sessionFile: target.session.file,
+      },
+      onCustomOptions: (options) => customOptions.push(options),
+      onEvent: (event) => events.push(event),
+      replacementUi,
+    })
+
+    await runBrunchWorkspaceAction(ctx, {
+      inspectWorkspace: async () => {
+        events.push("inspect")
+        return inventoryWithWorkspace(target)
+      },
+      activateWorkspace: async (decision) => {
+        events.push(`activate:${decision.action}`)
+        return target
+      },
+    })
+
+    expect(events).toEqual([
+      "waitForIdle",
+      "inspect",
+      "custom",
+      "activate:openSession",
+      `switch:${target.session.file}`,
+      "replacement:setHeader",
+      "replacement:setFooter",
+      "replacement:setWidget",
+      "replacement:setTitle",
+      "replacement:notify",
+    ])
+    expect(customOptions).toEqual([
+      {
+        overlay: true,
+        overlayOptions: {
+          anchor: "center",
+          width: 80,
+          maxHeight: "90%",
+          margin: 1,
+        },
+      },
+    ])
+  })
+
+  it("opens the spec/session picker from shortcut contexts without waitForIdle", async () => {
+    const events: string[] = []
+    const target = readyWorkspace("/tmp/project", "session-target")
+    const ctx = fakeCommandContext({
+      currentSessionFile: "/sessions/session-old.jsonl",
+      decision: {
+        action: "openSession",
+        specId: target.spec.id,
+        sessionFile: target.session.file,
+      },
+      onEvent: (event) => events.push(event),
+    })
+    delete (ctx as Partial<ExtensionCommandContext>).waitForIdle
+
+    await runBrunchWorkspaceAction(ctx, {
+      inspectWorkspace: async () => {
+        events.push("inspect")
+        return inventoryWithWorkspace(target)
+      },
+      activateWorkspace: async (decision) => {
+        events.push(`activate:${decision.action}`)
+        return target
+      },
+    })
+
+    expect(events).toEqual([
+      "inspect",
+      "custom",
+      "activate:openSession",
+      `switch:${target.session.file}`,
+      "notify:info",
+    ])
+  })
+
+  it("leaves the current session untouched when workspace switch is cancelled", async () => {
+    const events: string[] = []
+    const ctx = fakeCommandContext({
+      currentSessionFile: "/sessions/session-old.jsonl",
+      decision: { action: "cancel" },
+      onEvent: (event) => events.push(event),
+    })
+
+    await runBrunchWorkspaceAction(ctx, {
+      inspectWorkspace: async () => emptyInventory("/tmp/project"),
+      activateWorkspace: async () => ({
+        status: "cancelled",
+        cwd: "/tmp/project",
+        chrome: {
+          cwd: "/tmp/project",
+          spec: null,
+          phase: "select_spec",
+          chatMode: "select-spec",
+        },
+      }),
+    })
+
+    expect(events).toEqual(["waitForIdle", "custom", "notify:info"])
+  })
+
+  it("reports needs-human workspace switch decisions without switching sessions", async () => {
+    const events: string[] = []
+    const ctx = fakeCommandContext({
+      currentSessionFile: "/sessions/session-old.jsonl",
+      decision: {
+        action: "openSession",
+        specId: "missing",
+        sessionFile: "/sessions/missing.jsonl",
+      },
+      onEvent: (event) => events.push(event),
+    })
+
+    await runBrunchWorkspaceAction(ctx, {
+      inspectWorkspace: async () => emptyInventory("/tmp/project"),
+      activateWorkspace: async () => ({
+        status: "needs_human",
+        cwd: "/tmp/project",
+        reason: "Selected session is not available.",
+        chrome: {
+          cwd: "/tmp/project",
+          spec: null,
+          phase: "select_spec",
+          chatMode: "select-spec",
+        },
+      }),
+    })
+
+    expect(events).toEqual(["waitForIdle", "custom", "notify:warning"])
   })
 
   it("cancels Pi branch-flow hooks with a stable user-facing reason", async () => {
@@ -139,7 +508,11 @@ describe("Brunch TUI boot", () => {
     const ctx: FakeExtensionContext = {
       sessionManager: manager,
       ui: {
+        setHeader: (_factory) => {},
+        setFooter: (_factory) => {},
+        setStatus: (_key, _text) => {},
         setWidget: (_key: string, _content: unknown) => {},
+        setWorkingIndicator: (_options) => {},
         setTitle: (_title: string) => {},
         notify: (message, type) => notifications.push({ message, type }),
       },
@@ -149,18 +522,18 @@ describe("Brunch TUI boot", () => {
       ctx: FakeExtensionContext,
     ) => unknown>()
 
-    createBrunchChromeExtension({
-      cwd,
-      spec: { id: "spec-1", title: "Spec One" },
-      phase: "elicitation",
-      chatMode: "responding-to-elicitation",
-    })({
+    createBrunchPiExtensionShell(
+      chromeStateForWorkspace(readyWorkspace(cwd, manager.getSessionId())),
+      undefined,
+      { coordinator: noOpWorkspaceCoordinator(cwd) },
+    )({
       on: (
         event: string,
         handler: (event: unknown, ctx: FakeExtensionContext) => unknown,
       ) => {
         handlers.set(event, handler)
       },
+      registerCommand: (_name: string, _options: unknown) => {},
     } as never)
 
     await expect(
@@ -193,23 +566,335 @@ describe("Brunch TUI boot", () => {
     ])
   })
 
-  it("keeps session creation and binding out of the TUI boot adapter", async () => {
-    const source = await readFile(
-      new URL("./brunch-tui.ts", import.meta.url),
-      "utf8",
-    )
+  it("registers alternatives cards as a transcript primitive without demo commands", async () => {
+    const commands: string[] = []
+    const renderers: string[] = []
+    const tools = new Map<string, {
+      execute: (id: string, params: never) => unknown
+    }>()
+    const messages: unknown[] = []
+
+    registerBrunchAlternatives({
+      registerMessageRenderer: (type: string) => renderers.push(type),
+      registerTool: (tool: {
+        name: string
+        execute: (id: string, params: never) => unknown
+      }) => tools.set(tool.name, tool),
+      registerCommand: (name: string) => commands.push(name),
+      sendMessage: (message: unknown) => messages.push(message),
+    } as never)
+
+    await expect(
+      Promise.resolve(tools.get("present_alternatives")?.execute("tool-1", {
+          headline: "Choose",
+          alternatives: [{ title: "A", body: "Alpha", flavor: "accent" }],
+        } as never)),
+    ).resolves.toMatchObject({
+      content: [{ type: "text", text: "Presented 1 alternative." }],
+      details: { count: 1 },
+      terminate: true,
+    })
 
-    expect(source).not.toContain("SessionManager.create")
-    expect(source).not.toContain("appendCustomEntry")
-    expect(source).not.toContain("brunch.session_binding")
+    expect(renderers).toEqual(["alternatives-card-set"])
+    expect(messages).toEqual([
+      {
+        customType: "alternatives-card-set",
+        content: "## Choose\n\n---\n\n### A\n\nAlpha",
+        display: true,
+        details: {
+          headline: "Choose",
+          alternatives: [{ title: "A", body: "Alpha", flavor: "accent" }],
+        },
+      },
+    ])
+    expect(commands).toEqual([])
+  })
+
+  it("wires the fixture graph-code mention source through the Brunch shell", async () => {
+    let providerFactory: ((
+      current: FakeAutocompleteProvider,
+    ) => FakeAutocompleteProvider) | undefined
+    const sessionStart: Array<(
+      event: unknown,
+      ctx: FakeExtensionContext,
+    ) => Promise<void> | void> = []
+
+    createBrunchPiExtensionShell(
+      chromeStateForWorkspace(readyWorkspace("/tmp/project", "session-1")),
+      undefined,
+      { coordinator: noOpWorkspaceCoordinator("/tmp/project") },
+    )({
+      on: (event: string, handler: never) => {
+        if (event === "session_start") sessionStart.push(handler)
+      },
+      registerCommand: (_name: string, _options: unknown) => {},
+      registerShortcut: (_name: string, _options: unknown) => {},
+      registerTool: (_tool: unknown) => {},
+      registerMessageRenderer: (_type: string) => {},
+      sendMessage: (_message: unknown) => {},
+      getAllTools: () => [],
+      setActiveTools: (_tools: string[]) => {},
+    } as never)
+
+    const ctx: FakeExtensionContext = {
+      sessionManager: {
+        getEntries: () => [],
+      } as unknown as FakeExtensionContext["sessionManager"],
+      ui: {
+        setHeader: (_factory) => {},
+        setFooter: (_factory) => {},
+        setStatus: (_key, _text) => {},
+        setWidget: (_key: string, _content: unknown) => {},
+        setWorkingIndicator: (_options) => {},
+        setTitle: (_title: string) => {},
+        notify: (_message: string, _type?: "info" | "warning" | "error") => {},
+        addAutocompleteProvider: (factory: typeof providerFactory) => {
+          providerFactory = factory
+        },
+      } as FakeExtensionUi & {
+        addAutocompleteProvider: (factory: typeof providerFactory) => void
+      },
+    }
+
+    for (const handler of sessionStart) await handler({}, ctx)
+
+    const fallback: FakeAutocompleteProvider = {
+      getSuggestions: async () => ({ items: [], prefix: "" }),
+      applyCompletion: (lines) => ({ lines, cursorLine: 0, cursorCol: 0 }),
+      shouldTriggerFileCompletion: () => true,
+    }
+    const provider = providerFactory?.(fallback)
+
+    await expect(
+      provider?.getSuggestions(["Discuss #"], 0, 9, {} as never),
+    ).resolves.toMatchObject({
+      prefix: "#",
+      items: expect.arrayContaining([
+        expect.objectContaining({ value: "#D12" }),
+      ]),
+    })
+  })
+
+  it("loads the elicit operational-mode tool policy from product code", async () => {
+    const events: Record<string, (event: never) => unknown> = {}
+    const activeTools: string[][] = []
+    const registeredTools: string[] = []
+
+    registerBrunchOperationalModePolicy({
+      registerTool: (tool: { name: string }) => registeredTools.push(tool.name),
+      getAllTools: () =>
+        ["read", "grep", "find", "ls", "bash", "write"].map((name) => ({
+          name,
+        })),
+      setActiveTools: (tools: string[]) => activeTools.push(tools),
+      on: (event: string, handler: (event: never) => unknown) => {
+        events[event] = handler
+      },
+    } as never)
+
+    expect(registeredTools).toEqual(["read", "grep", "find", "ls"])
+    await events.session_start?.({} as never)
+    expect(activeTools).toEqual([["read", "grep", "find", "ls"]])
+    await expect(
+      Promise.resolve(
+        events.before_agent_start?.({ systemPrompt: "base" } as never),
+      ),
+    ).resolves.toMatchObject({
+      systemPrompt: expect.stringContaining(
+        "Brunch exposes only read-only tools: read, grep, find, ls.",
+      ),
+    })
+    await expect(
+      Promise.resolve(events.tool_call?.({ toolName: "write" } as never)),
+    ).resolves.toMatchObject({ block: true })
+    expect(events.user_bash?.({ command: "rm -rf ." } as never)).toMatchObject({
+      result: {
+        exitCode: 1,
+        output: "Brunch tool policy blocks shell commands: rm -rf .",
+      },
+    })
+  })
+
+  it("suppresses generic Pi startup resources for the Brunch shell", async () => {
+    const cwd = await mkdtemp(join(tmpdir(), "brunch-tui-"))
+    const settingsManager = createBrunchSettingsManager(cwd, cwd)
+    const extension = () => {}
+    const resourceOptions = brunchResourceLoaderOptions([extension])
+    const env: { PI_OFFLINE?: string } = {}
+
+    applyBrunchOfflineDefault(env)
+
+    expect(settingsManager.getQuietStartup()).toBe(true)
+    expect(resourceOptions).toEqual({
+      noContextFiles: true,
+      noExtensions: true,
+      noPromptTemplates: true,
+      noSkills: true,
+      noThemes: true,
+      extensionFactories: [extension],
+    })
+    expect(env.PI_OFFLINE).toBe("1")
   })
 })
 
+function readyWorkspace(
+  cwd: string,
+  sessionId: string,
+): WorkspaceSessionReadyState {
+  const spec = { id: "spec-1", title: "Spec One" }
+  return {
+    status: "ready",
+    cwd,
+    spec,
+    session: {
+      id: sessionId,
+      file: `/sessions/${sessionId}.jsonl`,
+      manager: {} as WorkspaceSessionReadyState["session"]["manager"],
+    },
+    chrome: {
+      cwd,
+      spec,
+      phase: "elicitation",
+      chatMode: "responding-to-elicitation",
+    },
+  }
+}
+
+function emptyInventory(cwd: string): WorkspaceLaunchInventory {
+  return {
+    cwd,
+    currentSpec: null,
+    currentSessionFile: null,
+    needsNewSpec: true,
+    specs: [],
+    unavailableSessions: [],
+  }
+}
+
+function inventoryWithWorkspace(
+  workspace: WorkspaceSessionReadyState,
+): WorkspaceLaunchInventory {
+  return {
+    cwd: workspace.cwd,
+    currentSpec: workspace.spec,
+    currentSessionFile: workspace.session.file,
+    needsNewSpec: false,
+    specs: [
+      {
+        spec: workspace.spec,
+        sessions: [
+          {
+            id: workspace.session.id,
+            file: workspace.session.file,
+            specId: workspace.spec.id,
+            specTitle: workspace.spec.title,
+            available: true,
+          },
+        ],
+      },
+    ],
+    unavailableSessions: [],
+  }
+}
+
+function noOpWorkspaceCoordinator(cwd: string) {
+  return {
+    inspectWorkspace: async () => emptyInventory(cwd),
+    activateWorkspace: async () => readyWorkspace(cwd, "session-1"),
+  }
+}
+
+function fakeCommandContext(options: {
+  currentSessionFile: string
+  decision?: Awaited<ReturnType<ExtensionUIContext["custom"]>>
+  decisions?: Array<Awaited<ReturnType<ExtensionUIContext["custom"]>>>
+  onCustomOptions?: (customOptions: unknown) => void
+  onEvent: (event: string) => void
+  replacementUi?: FakeExtensionUi
+}): ExtensionCommandContext {
+  const ui = fakeUi((method, type) => {
+    if (method === "notify") {
+      options.onEvent(`notify:${type}`)
+    }
+  })
+  const decisions = [...(options.decisions ?? [options.decision])]
+  const ctx = {
+    cwd: "/tmp/project",
+    sessionManager: {
+      getSessionFile: () => options.currentSessionFile,
+    },
+    ui: {
+      ...ui,
+      custom: async (_component: unknown, customOptions?: unknown) => {
+        options.onEvent("custom")
+        if (customOptions !== undefined) {
+          options.onCustomOptions?.(customOptions)
+        }
+        return decisions.shift()
+      },
+    },
+    waitForIdle: async () => options.onEvent("waitForIdle"),
+    switchSession: async (
+      sessionPath: string,
+      switchOptions?: Parameters<ExtensionCommandContext["switchSession"]>[1],
+    ) => {
+      options.onEvent(`switch:${sessionPath}`)
+      await switchOptions?.withSession?.({
+        ...ctx,
+        ui: options.replacementUi ?? ui,
+        sessionManager: { getSessionFile: () => sessionPath },
+      } as never)
+      return { cancelled: false }
+    },
+  }
+  return ctx as unknown as ExtensionCommandContext
+}
+
+function fakeUi(
+  onCall: (method: string, notifyType?: "info" | "warning" | "error") => void,
+): FakeExtensionUi {
+  return {
+    setHeader: (_factory) => onCall("setHeader"),
+    setFooter: (_factory) => onCall("setFooter"),
+    setStatus: (_key, _text) => onCall("setStatus"),
+    setWidget: (_key, _content, _options) => onCall("setWidget"),
+    setWorkingIndicator: (_options) => onCall("setWorkingIndicator"),
+    setTitle: (_title) => onCall("setTitle"),
+    notify: (_message, type) => onCall("notify", type),
+  }
+}
+
 type FakeExtensionContext = Pick<ExtensionContext, "sessionManager"> & {
   ui: FakeExtensionUi
 }
 
-type FakeExtensionUi = Pick<ExtensionUIContext, "setWidget" | "setTitle" | "notify">
+interface FakeAutocompleteItem {
+  value: string
+  label: string
+}
+
+interface FakeAutocompleteProvider {
+  getSuggestions(
+    lines: string[],
+    cursorLine: number,
+    cursorCol: number,
+    options: never,
+  ): Promise<unknown>
+  applyCompletion(
+    lines: string[],
+    cursorLine: number,
+    cursorCol: number,
+    item: FakeAutocompleteItem,
+    prefix: string,
+  ): unknown
+  shouldTriggerFileCompletion(
+    lines: string[],
+    cursorLine: number,
+    cursorCol: number,
+  ): boolean
+}
+
+type FakeExtensionUi = Pick<ExtensionUIContext, "setFooter" | "setHeader" | "setStatus" | "setWidget" | "setWorkingIndicator" | "setTitle" | "notify">
 
 function isStringArray(value: unknown): value is string[] {
   return Array.isArray(value) && value.every((item) => typeof item === "string")
diff --git a/src/brunch-tui.ts b/src/brunch-tui.ts
index b818ea81..bf2be7c5 100644
--- a/src/brunch-tui.ts
+++ b/src/brunch-tui.ts
@@ -1,4 +1,3 @@
-import { createInterface } from "node:readline/promises"
 import process from "node:process"
 
 import {
@@ -7,33 +6,55 @@ import {
   createAgentSessionServices,
   getAgentDir,
   InteractiveMode,
-  SessionManager,
+  SettingsManager,
   type CreateAgentSessionRuntimeFactory,
   type ExtensionFactory,
 } from "@earendil-works/pi-coding-agent"
 
 import {
   createWorkspaceSessionCoordinator,
-  type WorkspaceSessionChromeState,
-  type WorkspaceSessionCoordinator,
+  type WorkspaceLaunchInventory,
+  type WorkspaceSessionBoundaryCoordinator,
   type WorkspaceSessionReadyState,
+  type SpecSessionActivationCoordinator,
+  type SpecSessionActivationDecision,
 } from "./workspace-session-coordinator.js"
+import {
+  chromeStateForWorkspace,
+  createBrunchPiExtensionShell,
+} from "./pi-extensions.js"
+import { runWorkspaceDialogPreflight } from "./pi-components/workspace-dialog.js"
+export {
+  BRUNCH_BRANCH_FLOW_BLOCKED_MESSAGE,
+  chromeStateForWorkspace,
+  createBrunchPiExtensionShell,
+  projectBrunchChromeFooterLines,
+  renderBrunchChrome,
+  type BrunchChromeCoherenceVerdict,
+  type BrunchChromeFooterTelemetry,
+  type BrunchChromeStage,
+  type BrunchChromeState,
+  type BrunchChromeWorkerStatus,
+} from "./pi-extensions.js"
+export { runWorkspaceDialogPreflight } from "./pi-components/workspace-dialog.js"
+
+export type BrunchTuiCoordinator = SpecSessionActivationCoordinator & WorkspaceSessionBoundaryCoordinator
 
 export interface BrunchTuiLaunchContext {
   workspace: WorkspaceSessionReadyState
-  coordinator: WorkspaceSessionCoordinator
+  coordinator: BrunchTuiCoordinator
 }
 
 export interface BrunchTuiOptions {
   cwd?: string
-  coordinator?: WorkspaceSessionCoordinator
+  coordinator?: BrunchTuiCoordinator
   selectSpecTitle?: () => Promise<string | undefined>
+  runWorkspaceDialogPreflight?: (
+    inventory: WorkspaceLaunchInventory,
+  ) => Promise<SpecSessionActivationDecision>
   launchInteractive?: (context: BrunchTuiLaunchContext) => Promise<void>
 }
 
-export const BRUNCH_BRANCH_FLOW_BLOCKED_MESSAGE =
-  "Brunch does not support Pi session branches in this POC. Use /new to continue within the selected spec."
-
 export async function runBrunchTui(
   options: BrunchTuiOptions = {},
 ): Promise<void> {
@@ -41,15 +62,13 @@ export async function runBrunchTui(
   const coordinator =
     options.coordinator ?? createWorkspaceSessionCoordinator({ cwd })
 
-  let workspaceState = await coordinator.openExisting()
-  if (workspaceState.status === "select_spec") {
-    const title = await (options.selectSpecTitle ?? promptForSpecTitle)()
-    if (!title) {
-      return
-    }
-    workspaceState = await coordinator.startOrCreate({ specTitle: title })
-  }
+  const inventory = await coordinator.inspectWorkspace()
+  const decision = await chooseSpecSessionActivationDecision(inventory, options)
+  const workspaceState = await coordinator.activateWorkspace(decision)
 
+  if (workspaceState.status === "cancelled") {
+    return
+  }
   if (workspaceState.status === "needs_human") {
     throw new Error(workspaceState.reason)
   }
@@ -60,56 +79,18 @@ export async function runBrunchTui(
   })
 }
 
-export function formatChromeWidgetLines(
-  chrome: WorkspaceSessionChromeState,
-): string[] {
-  const spec = chrome.spec ? chrome.spec.title : "<none>"
-  return [
-    `brunch  cwd: ${chrome.cwd}`,
-    `        spec: ${spec}  phase: ${chrome.phase}  chat: ${chrome.chatMode}`,
-  ]
-}
-
-export function createBrunchChromeExtension(
-  chrome: WorkspaceSessionChromeState,
-  onSessionBoundary?: (sessionManager: SessionManager) => Promise<void> | void,
-): ExtensionFactory {
-  return (pi) => {
-    pi.on("session_start", async (_event, ctx) => {
-      await onSessionBoundary?.(ctx.sessionManager as SessionManager)
-      ctx.ui.setWidget("brunch.chrome", formatChromeWidgetLines(chrome), {
-        placement: "aboveEditor",
-      })
-      ctx.ui.setTitle(`brunch — ${chrome.spec?.title ?? chrome.cwd}`)
-    })
-    pi.on("before_agent_start", async (_event, ctx) => {
-      await onSessionBoundary?.(ctx.sessionManager as SessionManager)
-    })
-    pi.on("message_start", async (event, ctx) => {
-      if (event.message.role === "assistant") {
-        await onSessionBoundary?.(ctx.sessionManager as SessionManager)
-      }
-    })
-    pi.on("session_before_tree", (_event, ctx) => {
-      ctx.ui.notify(BRUNCH_BRANCH_FLOW_BLOCKED_MESSAGE, "warning")
-      return { cancel: true }
-    })
-    pi.on("session_before_fork", (_event, ctx) => {
-      ctx.ui.notify(BRUNCH_BRANCH_FLOW_BLOCKED_MESSAGE, "warning")
-      return { cancel: true }
-    })
+async function chooseSpecSessionActivationDecision(
+  inventory: WorkspaceLaunchInventory,
+  options: BrunchTuiOptions,
+): Promise<SpecSessionActivationDecision> {
+  if (options.runWorkspaceDialogPreflight) {
+    return options.runWorkspaceDialogPreflight(inventory)
   }
-}
-
-async function promptForSpecTitle(): Promise<string | undefined> {
-  const rl = createInterface({ input: process.stdin, output: process.stdout })
-  try {
-    const answer = await rl.question("Create/select Brunch spec title: ")
-    const title = answer.trim()
-    return title.length > 0 ? title : undefined
-  } finally {
-    rl.close()
+  if (options.selectSpecTitle && inventory.needsNewSpec) {
+    const title = await options.selectSpecTitle()
+    return title ? { action: "newSpec", title } : { action: "cancel" }
   }
+  return runWorkspaceDialogPreflight(inventory)
 }
 
 async function launchPiInteractive({
@@ -122,19 +103,22 @@ async function launchPiInteractive({
     agentDir: runtimeAgentDir,
     sessionManager,
   }) => {
+    const settingsManager = createBrunchSettingsManager(cwd, runtimeAgentDir)
     const services = await createAgentSessionServices({
       cwd,
       agentDir: runtimeAgentDir,
-      resourceLoaderOptions: {
-        extensionFactories: [
-          createBrunchChromeExtension(
-            workspace.chrome,
-            async (sessionManager) => {
-              await coordinator.bindCurrentSpecToSession(sessionManager)
-            },
-          ),
-        ],
-      },
+      settingsManager,
+      resourceLoaderOptions: brunchResourceLoaderOptions([
+        createBrunchPiExtensionShell(
+          chromeStateForWorkspace(workspace),
+          async (sessionManager) => {
+            await coordinator.bindCurrentSpecToReplacementSession(
+              sessionManager,
+            )
+          },
+          { coordinator },
+        ),
+      ]),
     })
     const created = await createAgentSessionFromServices({
       services,
@@ -153,5 +137,34 @@ async function launchPiInteractive({
     sessionManager: workspace.session.manager,
   })
 
+  applyBrunchOfflineDefault()
   await new InteractiveMode(runtime).run()
 }
+
+export function brunchResourceLoaderOptions(
+  extensionFactories: ExtensionFactory[],
+) {
+  return {
+    noContextFiles: true,
+    noExtensions: true,
+    noPromptTemplates: true,
+    noSkills: true,
+    noThemes: true,
+    extensionFactories,
+  }
+}
+
+export function applyBrunchOfflineDefault(
+  env: { PI_OFFLINE?: string } = process.env,
+): void {
+  env.PI_OFFLINE ??= "1"
+}
+
+export function createBrunchSettingsManager(
+  cwd: string,
+  agentDir: string,
+): SettingsManager {
+  const settingsManager = SettingsManager.create(cwd, agentDir)
+  settingsManager.getQuietStartup = () => true
+  return settingsManager
+}
diff --git a/src/brunch.test.ts b/src/brunch.test.ts
index 4cd19672..e5f1861f 100644
--- a/src/brunch.test.ts
+++ b/src/brunch.test.ts
@@ -7,8 +7,9 @@ import { describe, expect, it } from "vitest"
 
 import { SessionManager } from "@earendil-works/pi-coding-agent"
 
-import { runBrunchCli } from "./brunch.js"
+import { runBrunchCli, type WebHostRunnerOptions } from "./brunch.js"
 import { createSessionBindingData } from "./session-binding.js"
+import { assistantMessage, userMessage } from "./test-helpers.js"
 import {
   createWorkspaceSessionCoordinator,
   type WorkspaceSessionCoordinator,
@@ -16,7 +17,7 @@ import {
 
 function coordinator(sessionFile?: string): WorkspaceSessionCoordinator {
   return {
-    async openExisting() {
+    async openDefaultWorkspace() {
       return {
         ...(sessionFile
           ? {
@@ -46,19 +47,19 @@ function coordinator(sessionFile?: string): WorkspaceSessionCoordinator {
         cwd: "/tmp/brunch-project",
       }
     },
-    async startOrCreate() {
+    async createSetupSession() {
       throw new Error("print must not create a session")
     },
-    async createNewSessionForCurrentSpec() {
+    async createSetupSessionForCurrentSpec() {
       throw new Error("not used")
     },
-    async bindCurrentSpecToSession() {
+    async bindCurrentSpecToReplacementSession() {
       throw new Error("not used")
     },
-    async deriveChromeState() {
+    async deriveDefaultChromeState() {
       throw new Error("not used")
     },
-  }
+  } as unknown as WorkspaceSessionCoordinator
 }
 
 function rpcRequest(method: string, id = 1): PassThrough {
@@ -75,10 +76,7 @@ function collectStream(stream: PassThrough): string[] {
 
 describe("Brunch CLI dispatch", () => {
   it("routes --mode web through an injectable web host runner", async () => {
-    let launchedWith: {
-      cwd: string
-      coordinator: WorkspaceSessionCoordinator
-    } | null = null
+    let launchedWith: WebHostRunnerOptions | null = null
 
     const code = await runBrunchCli({
       argv: ["--mode=web"],
@@ -121,8 +119,8 @@ describe("Brunch CLI dispatch", () => {
         specTitle: "Spec",
       }),
     )
-    manager.appendMessage({ role: "assistant", content: "Question" })
-    manager.appendMessage({ role: "user", content: "Answer" })
+    manager.appendMessage(assistantMessage("Question"))
+    manager.appendMessage(userMessage("Answer"))
     const stdout = new PassThrough()
     const chunks = collectStream(stdout)
 
@@ -167,7 +165,7 @@ describe("Brunch CLI dispatch", () => {
 
   it("exposes matching print and RPC workspace snapshots from a real coordinator store", async () => {
     const cwd = await mkdtemp(join(tmpdir(), "brunch-parity-"))
-    await createWorkspaceSessionCoordinator({ cwd }).startOrCreate({
+    await createWorkspaceSessionCoordinator({ cwd }).createSetupSession({
       specTitle: "Parity spec",
     })
     let printOutput = ""
diff --git a/src/brunch.ts b/src/brunch.ts
index c858e834..7e69439a 100644
--- a/src/brunch.ts
+++ b/src/brunch.ts
@@ -38,7 +38,7 @@ export async function runBrunchCli(
     options.coordinator ?? createWorkspaceSessionCoordinator({ cwd })
 
   if (mode === "print") {
-    const state = await coordinator.openExisting()
+    const state = await coordinator.openDefaultWorkspace()
     const snapshot = workspaceSnapshotFromState(state)
     writeStdout(options.stdout, renderWorkspaceSnapshot(snapshot))
     return 0
diff --git a/src/elicitation-exchange.test.ts b/src/elicitation-exchange.test.ts
index ca4b73c1..d5b4bc08 100644
--- a/src/elicitation-exchange.test.ts
+++ b/src/elicitation-exchange.test.ts
@@ -6,6 +6,8 @@ import { describe, expect, it } from "vitest"
 import { SessionManager } from "@earendil-works/pi-coding-agent"
 
 import { createSessionBindingData } from "./session-binding.js"
+import { buildStructuredQuestionResult } from "./structured-question.js"
+import { assistantMessage, userMessage } from "./test-helpers.js"
 import {
   loadJsonlTranscriptEntries,
   loadLinearElicitationExchangeProjection,
@@ -18,7 +20,7 @@ import {
 const assistant = {
   id: "a1",
   type: "message",
-  message: { role: "assistant", content: "Pick one" },
+  message: assistantMessage("Pick one"),
 }
 const structuredPrompt = {
   id: "p1",
@@ -37,10 +39,54 @@ const toolResult = {
     isError: false,
   },
 }
+const structuredQuestionToolResult = {
+  id: "sq1",
+  type: "message",
+  message: {
+    role: "toolResult",
+    toolCallId: "call-sq-1",
+    toolName: "brunch_structured_question",
+    content: [{ type: "text", text: "Domain?: Developer tooling" }],
+    details: buildStructuredQuestionResult({
+      params: {
+        id: "domain",
+        mode: "text",
+        prompt: "Domain?",
+      },
+      status: "answered",
+      answers: [
+        { questionId: "domain", mode: "text", value: "Developer tooling" },
+      ],
+      transport: { surface: "rpc-editor" },
+    }).details,
+    isError: false,
+  },
+}
+const unavailableStructuredQuestionToolResult = {
+  id: "sq-unavailable",
+  type: "message",
+  message: {
+    role: "toolResult",
+    toolCallId: "call-sq-2",
+    toolName: "brunch_structured_question",
+    content: [{ type: "text", text: "Structured question unavailable." }],
+    details: buildStructuredQuestionResult({
+      params: {
+        id: "domain",
+        mode: "text",
+        prompt: "Domain?",
+      },
+      status: "unavailable",
+      transport: { surface: "headless" },
+      message: "Structured question UI is unavailable.",
+    }).details,
+    isError: false,
+  },
+}
 const user = {
   id: "u1",
   type: "message",
-  message: { role: "user", content: "A" },
+  message: userMessage("A"),
 }
 const structuredResponse = {
   id: "r1",
@@ -70,12 +116,12 @@ describe("elicitation exchange projection", () => {
       {
         id: "a2",
         type: "message",
-        message: { role: "assistant", content: "Why?" },
+        message: assistantMessage("Why?"),
       },
       {
         id: "u2",
         type: "message",
-        message: { role: "user", content: "Because" },
+        message: userMessage("Because"),
       },
     ])
 
@@ -167,6 +213,34 @@ describe("elicitation exchange projection", () => {
     })
   })
 
+  it("classifies terminal structured-question tool results as response-side entries", () => {
+    const projection = projectElicitationExchanges([
+      assistant,
+      structuredQuestionToolResult,
+    ])
+
+    expect(projection.exchanges[0]?.promptEntryIds).toEqual(["a1"])
+    expect(projection.exchanges[0]?.responseEntryIds).toEqual(["sq1"])
+    expect(projection.exchanges[0]?.responseRange).toEqual({
+      start: "sq1",
+      end: "sq1",
+    })
+    expect(projection.openPrompt).toBeNull()
+  })
+
+  it("keeps non-terminal structured-question tool results on the prompt side", () => {
+    const projection = projectElicitationExchanges([
+      assistant,
+      unavailableStructuredQuestionToolResult,
+    ])
+
+    expect(projection.exchanges).toEqual([])
+    expect(projection.openPrompt?.promptEntryIds).toEqual([
+      "a1",
+      "sq-unavailable",
+    ])
+  })
+
   it("returns an explicit empty/open shape for incomplete transcripts", () => {
     expect(projectElicitationExchanges([])).toEqual({
       status: "empty",
@@ -190,7 +264,7 @@ describe("elicitation exchange projection", () => {
       {
         id: "a2",
         type: "message",
-        message: { role: "assistant", content: "Later prompt" },
+        message: assistantMessage("Later prompt"),
       },
     ])
 
@@ -208,8 +282,8 @@ describe("elicitation exchange projection", () => {
     const cwd = await mkdtemp(join(tmpdir(), "brunch-pi-jsonl-"))
     const manager = SessionManager.create(cwd, join(cwd, ".brunch/sessions"))
     appendBinding(manager)
-    manager.appendMessage({ role: "assistant", content: "Question" })
-    manager.appendMessage({ role: "user", content: "Answer" })
+    manager.appendMessage(assistantMessage("Question"))
+    manager.appendMessage(userMessage("Answer"))
 
     const projection = await loadLinearElicitationExchangeProjection(
       manager.getSessionFile()!,
@@ -225,12 +299,50 @@ describe("elicitation exchange projection", () => {
     )
   })
 
+  it("loads and projects terminal structured-question tool results as JSONL responses", async () => {
+    const cwd = await mkdtemp(join(tmpdir(), "brunch-pi-structured-question-"))
+    const manager = SessionManager.create(cwd, join(cwd, ".brunch/sessions"))
+    appendBinding(manager)
+    manager.appendMessage(
+      assistantMessage("Please answer the structured question."),
+    )
+    manager.appendMessage({
+      role: "toolResult",
+      toolCallId: "call-sq-jsonl",
+      toolName: "brunch_structured_question",
+      content: [{ type: "text", text: "Domain?: Developer tooling" }],
+      details: buildStructuredQuestionResult({
+        params: {
+          id: "domain",
+          mode: "text",
+          prompt: "Domain?",
+        },
+        status: "answered",
+        answers: [
+          { questionId: "domain", mode: "text", value: "Developer tooling" },
+        ],
+        transport: { surface: "rpc-editor" },
+      }).details,
+      isError: false,
+      timestamp: 0,
+    })
+
+    const projection = await loadLinearElicitationExchangeProjection(
+      manager.getSessionFile()!,
+    )
+
+    expect(projection.status).toBe("ready")
+    expect(projection.exchanges).toHaveLength(1)
+    expect(projection.exchanges[0]?.promptEntryIds).toHaveLength(1)
+    expect(projection.exchanges[0]?.responseEntryIds).toHaveLength(1)
+  })
+
   it("loads displayable assistant and user transcript rows", async () => {
     const cwd = await mkdtemp(join(tmpdir(), "brunch-pi-display-"))
     const manager = SessionManager.create(cwd, join(cwd, ".brunch/sessions"))
     appendBinding(manager)
-    manager.appendMessage({ role: "assistant", content: "Question" })
-    manager.appendMessage({ role: "user", content: "Answer" })
+    manager.appendMessage(assistantMessage("Question"))
+    manager.appendMessage(userMessage("Answer"))
 
     const projection = await loadLinearTranscriptDisplayProjection(
       manager.getSessionFile()!,
@@ -251,11 +363,8 @@ describe("elicitation exchange projection", () => {
       "Choose the better framing.",
       true,
     )
-    manager.appendMessage({
-      role: "assistant",
-      content: "Persistence sentinel",
-    })
-    manager.appendMessage({ role: "user", content: "Option A" })
+    manager.appendMessage(assistantMessage("Persistence sentinel"))
+    manager.appendMessage(userMessage("Option A"))
 
     const projection = await loadLinearTranscriptDisplayProjection(
       manager.getSessionFile()!,
@@ -312,10 +421,10 @@ describe("elicitation exchange projection", () => {
     const cwd = await mkdtemp(join(tmpdir(), "brunch-pi-helper-branch-"))
     const manager = SessionManager.create(cwd, join(cwd, ".brunch/sessions"))
     appendBinding(manager)
-    manager.appendMessage({ role: "assistant", content: "Abandoned prompt" })
-    manager.appendMessage({ role: "user", content: "Abandoned answer" })
+    manager.appendMessage(assistantMessage("Abandoned prompt"))
+    manager.appendMessage(userMessage("Abandoned answer"))
     manager.resetLeaf()
-    manager.appendMessage({ role: "assistant", content: "Active prompt" })
+    manager.appendMessage(assistantMessage("Active prompt"))
 
     await expect(
       loadLinearElicitationExchangeProjection(manager.getSessionFile()!),
@@ -325,11 +434,11 @@ describe("elicitation exchange projection", () => {
   it("rejects a Pi JSONL file with multiple children from one parent", async () => {
     const cwd = await mkdtemp(join(tmpdir(), "brunch-pi-branch-"))
     const manager = SessionManager.create(cwd, join(cwd, ".brunch/sessions"))
-    manager.appendMessage({ role: "assistant", content: "Abandoned prompt" })
-    manager.appendMessage({ role: "user", content: "Abandoned answer" })
+    manager.appendMessage(assistantMessage("Abandoned prompt"))
+    manager.appendMessage(userMessage("Abandoned answer"))
     manager.resetLeaf()
-    manager.appendMessage({ role: "assistant", content: "Active prompt" })
-    manager.appendMessage({ role: "user", content: "Active answer" })
+    manager.appendMessage(assistantMessage("Active prompt"))
+    manager.appendMessage(userMessage("Active answer"))
 
     await expect(
       loadJsonlTranscriptEntries(manager.getSessionFile()!),
@@ -339,13 +448,12 @@ describe("elicitation exchange projection", () => {
   it("rejects a Pi JSONL file with branched sibling responses", async () => {
     const cwd = await mkdtemp(join(tmpdir(), "brunch-pi-branch-"))
     const manager = SessionManager.create(cwd, join(cwd, ".brunch/sessions"))
-    const sharedPromptId = manager.appendMessage({
-      role: "assistant",
-      content: "Choose a path",
-    })
-    manager.appendMessage({ role: "user", content: "Old path" })
+    const sharedPromptId = manager.appendMessage(
+      assistantMessage("Choose a path"),
+    )
+    manager.appendMessage(userMessage("Old path"))
     manager.branch(sharedPromptId)
-    manager.appendMessage({ role: "user", content: "Selected path" })
+    manager.appendMessage(userMessage("Selected path"))
 
     await expect(
       loadJsonlTranscriptEntries(manager.getSessionFile()!),
@@ -424,7 +532,7 @@ describe("elicitation exchange projection", () => {
         {
           id: "u1",
           type: "message",
-          message: { role: "user", content: "A" },
+          message: userMessage("A"),
         },
       )}\n`,
     )
diff --git a/src/elicitation-exchange.ts b/src/elicitation-exchange.ts
index 297927c9..09340a64 100644
--- a/src/elicitation-exchange.ts
+++ b/src/elicitation-exchange.ts
@@ -12,6 +12,7 @@ import {
   readBrunchSessionEnvelope,
   type BrunchSessionEnvelope,
 } from "./brunch-session-envelope.js"
+import { isTerminalStructuredQuestionResultDetails } from "./structured-question.js"
 
 const PROMPT_SIDE_CUSTOM_TYPES = new Set([
   "brunch.elicitation_prompt",
@@ -226,6 +227,9 @@ function isPromptSideEntry(entry: SessionEntry): boolean {
   }
 
   const role = roleOf(entry)
+  if (role === "toolResult" && isTerminalStructuredQuestionToolResult(entry)) {
+    return false
+  }
   return role === "assistant" || role === "toolResult"
 }
 
@@ -233,12 +237,25 @@ function isResponseSideEntry(entry: SessionEntry): boolean {
   if (roleOf(entry) === "user") {
     return true
   }
+  if (isTerminalStructuredQuestionToolResult(entry)) {
+    return true
+  }
   return (
     isCustomTranscriptEntry(entry) &&
     STRUCTURED_RESPONSE_TYPES.has(entry.customType)
   )
 }
 
+function isTerminalStructuredQuestionToolResult(entry: SessionEntry): boolean {
+  return (
+    isMessageEntry(entry) &&
+    entry.message.role === "toolResult" &&
+    isTerminalStructuredQuestionResultDetails(
+      (entry.message as { details?: unknown }).details,
+    )
+  )
+}
+
 function isCustomTranscriptEntry(
   entry: SessionEntry,
 ): entry is CustomEntry | CustomMessageEntry {
diff --git a/src/fixture-capture.test.ts b/src/fixture-capture.test.ts
index b0e37b2f..7b676aff 100644
--- a/src/fixture-capture.test.ts
+++ b/src/fixture-capture.test.ts
@@ -3,9 +3,12 @@ import { tmpdir } from "node:os"
 import { join } from "node:path"
 import { describe, expect, it } from "vitest"
 
-import type { WorkspaceSessionCoordinator } from "./workspace-session-coordinator.js"
-import { createWorkspaceSessionCoordinator } from "./workspace-session-coordinator.js"
+import {
+  createWorkspaceSessionCoordinator,
+  type WorkspaceSessionCoordinator,
+} from "./workspace-session-coordinator.js"
 import { loadLinearElicitationExchangeProjection } from "./elicitation-exchange.js"
+import { assistantMessage, userMessage } from "./test-helpers.js"
 import {
   captureDeterministicBriefRuns,
   captureFixtureRun,
@@ -16,17 +19,13 @@ describe("fixture capture", () => {
     const cwd = await mkdtemp(join(tmpdir(), "brunch-fixture-real-"))
     const workspace = await createWorkspaceSessionCoordinator({
       cwd,
-    }).startOrCreate({
+    }).createSetupSession({
       specTitle: "Fixture spec",
     })
-    workspace.session.manager.appendMessage({
-      role: "assistant",
-      content: "Real selected question",
-    })
-    workspace.session.manager.appendMessage({
-      role: "user",
-      content: "Real selected answer",
-    })
+    workspace.session.manager.appendMessage(
+      assistantMessage("Real selected question"),
+    )
+    workspace.session.manager.appendMessage(userMessage("Real selected answer"))
 
     const result = await captureFixtureRun({
       cwd,
@@ -65,14 +64,11 @@ describe("fixture capture", () => {
     )
     const workspace = await createWorkspaceSessionCoordinator({
       cwd,
-    }).startOrCreate({
+    }).createSetupSession({
       specTitle: "Fixture spec",
     })
-    workspace.session.manager.appendMessage({
-      role: "assistant",
-      content: "Question",
-    })
-    workspace.session.manager.appendMessage({ role: "user", content: "Answer" })
+    workspace.session.manager.appendMessage(assistantMessage("Question"))
+    workspace.session.manager.appendMessage(userMessage("Answer"))
 
     const result = await captureFixtureRun({
       cwd,
@@ -95,31 +91,17 @@ describe("fixture capture", () => {
     const cwd = await mkdtemp(join(tmpdir(), "brunch-fixture-"))
     const workspace = await createWorkspaceSessionCoordinator({
       cwd,
-    }).startOrCreate({
+    }).createSetupSession({
       specTitle: "Fixture spec",
     })
-    workspace.session.manager.appendMessage({
-      role: "assistant",
-      content: "Question",
-    })
-    workspace.session.manager.appendMessage({ role: "user", content: "Answer" })
+    workspace.session.manager.appendMessage(assistantMessage("Question"))
+    workspace.session.manager.appendMessage(userMessage("Answer"))
 
     const coordinator: WorkspaceSessionCoordinator = {
-      async openExisting() {
+      ...createWorkspaceSessionCoordinator({ cwd }),
+      async openDefaultWorkspace() {
         return workspace
       },
-      async startOrCreate() {
-        return workspace
-      },
-      async createNewSessionForCurrentSpec() {
-        return workspace
-      },
-      async bindCurrentSpecToSession() {
-        return workspace
-      },
-      async deriveChromeState() {
-        return workspace.chrome
-      },
     }
 
     const result = await captureFixtureRun({
diff --git a/src/fixture-capture.ts b/src/fixture-capture.ts
index 154e4499..e8e82e92 100644
--- a/src/fixture-capture.ts
+++ b/src/fixture-capture.ts
@@ -4,13 +4,15 @@ import { PassThrough } from "node:stream"
 import { fileURLToPath } from "node:url"
 
 import { loadBriefLibrary, type FixtureBrief } from "./brief-library.js"
-import { runBrunchCli } from "./brunch.js"
+import { createRpcHandlers, runJsonRpcLineServer } from "./rpc.js"
 import type { ElicitationExchangeProjection } from "./elicitation-exchange.js"
 import type { WorkspaceSnapshot } from "./print-snapshot.js"
 import type { JsonRpcResponse } from "./json-rpc-protocol.js"
 import {
   createWorkspaceSessionCoordinator,
+  type WorkspaceSessionBoundaryCoordinator,
   type WorkspaceSessionCoordinator,
+  type WorkspaceSetupCoordinator,
 } from "./workspace-session-coordinator.js"
 
 export interface FixtureCaptureOptions {
@@ -117,7 +119,9 @@ export async function captureDeterministicBriefRuns(
       content: brief.scriptedUserNotes.join("\n"),
       timestamp: Date.parse(options.timestamp ?? new Date().toISOString()),
     })
-    await coordinator.bindCurrentSpecToSession(workspace.session.manager)
+    await coordinator.bindCurrentSpecToReplacementSession(
+      workspace.session.manager,
+    )
 
     results.push(
       await captureFixtureRun({
@@ -133,10 +137,10 @@ export async function captureDeterministicBriefRuns(
 }
 
 async function openScriptedBriefSession(
-  coordinator: WorkspaceSessionCoordinator,
+  coordinator: WorkspaceSetupCoordinator & WorkspaceSessionBoundaryCoordinator,
   brief: FixtureBrief,
 ) {
-  return coordinator.startOrCreate({
+  return coordinator.createSetupSession({
     specTitle: brief.title,
     createNewSpec: true,
   })
@@ -152,12 +156,15 @@ async function callRpc<T>(
   stdout.on("data", (chunk) => chunks.push(String(chunk)))
   stdin.end(`${JSON.stringify({ jsonrpc: "2.0", id: 1, method })}\n`)
 
-  await runBrunchCli({
-    argv: ["--mode=rpc"],
-    cwd: options.cwd,
-    ...(options.coordinator ? { coordinator: options.coordinator } : {}),
-    stdin,
-    stdout,
+  await runJsonRpcLineServer({
+    input: stdin,
+    output: stdout,
+    handlers: createRpcHandlers({
+      coordinator:
+        options.coordinator ??
+        createWorkspaceSessionCoordinator({ cwd: options.cwd }),
+      cwd: options.cwd,
+    }),
   })
 
   const response = JSON.parse(chunks.join("")) as JsonRpcResponse<T>
diff --git a/src/jsonl-session-viability.test.ts b/src/jsonl-session-viability.test.ts
index 28f292e0..b7a04c76 100644
--- a/src/jsonl-session-viability.test.ts
+++ b/src/jsonl-session-viability.test.ts
@@ -7,6 +7,7 @@ import { describe, expect, it } from "vitest"
 
 import {
   SessionManager,
+  type CustomEntry,
   type CustomMessageEntry,
   type SessionEntry,
   type SessionMessageEntry,
@@ -17,6 +18,7 @@ import {
   type ElicitationExchangeProjection,
 } from "./elicitation-exchange.js"
 import { isSessionBindingEntry } from "./session-binding.js"
+import { assistantMessage, userMessage } from "./test-helpers.js"
 
 const M1_FIXTURE_IDS = ["brief-001", "brief-002", "brief-003"] as const
 const M1_RUN_ID = "scripted-001"
@@ -60,25 +62,26 @@ interface M1FixtureBundle {
 describe("Pi JSONL transcript viability", () => {
   it("jsonl raw user assistant payload survival", async () => {
     const { file, manager } = createPersistedSession()
-    const userContent = [
-      { type: "text" as const, text: "Describe this image" },
-      {
-        type: "image" as const,
-        image: "data:image/png;base64,ZmFrZQ==",
-        mimeType: "image/png",
-      },
-    ]
-    const assistantContent = [
-      { type: "text" as const, text: "Here is a structured answer." },
+    const userContent: (import("@earendil-works/pi-ai").TextContent | import("@earendil-works/pi-ai").ImageContent)[] =
+      [
+        { type: "text", text: "Describe this image" },
+        {
+          type: "image",
+          data: "data:image/png;base64,ZmFrZQ==",
+          mimeType: "image/png",
+        },
+      ]
+    const assistantContent: import("@earendil-works/pi-ai").TextContent[] = [
+      { type: "text", text: "Here is a structured answer." },
     ]
 
-    manager.appendMessage({ role: "user", content: userContent })
-    manager.appendMessage({ role: "assistant", content: assistantContent })
+    manager.appendMessage(userMessage(userContent))
+    manager.appendMessage(assistantMessage(assistantContent))
 
     const reloaded = SessionManager.open(file)
     const messages = reloaded.getEntries().filter(isMessageEntry)
 
-    expect(messages.map((entry) => entry.message)).toEqual([
+    expect(messages.map((entry) => entry.message)).toMatchObject([
       { role: "user", content: userContent },
       { role: "assistant", content: assistantContent },
     ])
@@ -225,10 +228,9 @@ describe("Pi JSONL transcript viability", () => {
 
   it("jsonl continuity metadata survival", async () => {
     const { file, manager } = createPersistedSession()
-    const anchorEntryId = manager.appendMessage({
-      role: "assistant",
-      content: "Anchor before compaction",
-    })
+    const anchorEntryId = manager.appendMessage(
+      assistantMessage("Anchor before compaction"),
+    )
     const continuity = {
       lastSeenLsn: 42,
       interestSet: ["node-a", "node-b"],
@@ -275,7 +277,7 @@ describe("Pi JSONL transcript viability", () => {
       true,
       promptDetails,
     )
-    manager.appendMessage({ role: "user", content: "I choose safety." })
+    manager.appendMessage(userMessage("I choose safety."))
     manager.appendCustomEntry("brunch.elicitation_response", responseData)
     flushPreAssistantEntries(manager)
 
@@ -300,7 +302,7 @@ describe("Pi JSONL transcript viability", () => {
     })
     expect(ordinaryUser).toMatchObject({
       type: "message",
-      message: { role: "user", content: "I choose safety." },
+      message: userMessage("I choose safety."),
     })
     expect(structuredResponse).toMatchObject({
       type: "custom",
@@ -415,7 +417,7 @@ function createPersistedSession(): PersistedSessionFixture {
 }
 
 function flushPreAssistantEntries(manager: SessionManager): void {
-  manager.appendMessage({ role: "assistant", content: "Persistence sentinel" })
+  manager.appendMessage(assistantMessage("Persistence sentinel"))
 }
 
 function isMessageEntry(entry: SessionEntry): entry is SessionMessageEntry {
diff --git a/src/pi-components/cards.ts b/src/pi-components/cards.ts
new file mode 100644
index 00000000..b80dd0c3
--- /dev/null
+++ b/src/pi-components/cards.ts
@@ -0,0 +1,130 @@
+/**
+ * Cards — pi-tui rendering primitives for bordered card layouts.
+ *
+ * Pure library module. It registers nothing with Pi; product extensions import
+ * these primitives when they need transcript-rendered card layouts.
+ *
+ * Components here should remain stateless and stitch only pi-tui primitives.
+ */
+
+import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent"
+import { getMarkdownTheme } from "@earendil-works/pi-coding-agent"
+import {
+  type Component,
+  Markdown,
+  visibleWidth,
+  truncateToWidth,
+} from "@earendil-works/pi-tui"
+
+/**
+ * Lay components out side-by-side and fall back to vertical stacking once the
+ * per-column width drops below `minChildWidth`.
+ */
+export class ResponsiveColumns implements Component {
+  constructor(
+    private children: Component[],
+    private minChildWidth: number = 40,
+    private gap: number = 2,
+  ) {}
+
+  invalidate(): void {}
+
+  render(width: number): string[] {
+    if (this.children.length === 0) return []
+    if (this.children.length === 1) return this.children[0]!.render(width)
+
+    const n = this.children.length
+    const totalGap = this.gap * (n - 1)
+    const perChild = Math.floor((width - totalGap) / n)
+
+    // Too narrow for columns — stack vertically.
+    if (perChild < this.minChildWidth) {
+      const lines: string[] = []
+      this.children.forEach((c, i) => {
+        if (i > 0) lines.push("")
+        lines.push(...c.render(width))
+      })
+      return lines
+    }
+
+    const grids = this.children.map((c) => c.render(perChild))
+    const rowCount = Math.max(...grids.map((g) => g.length))
+
+    // Pad shorter columns with blank lines so all columns share rowCount.
+    const blank = " ".repeat(perChild)
+    const padded = grids.map((g) => {
+      const result = [...g]
+      while (result.length < rowCount) result.push(blank)
+      return result
+    })
+
+    // Stitch rows. Each line is padded to perChild visible width before joining.
+    const gapStr = " ".repeat(this.gap)
+    const lines: string[] = []
+    for (let r = 0; r < rowCount; r++) {
+      const parts = padded.map((g) => {
+        const line = g[r] ?? blank
+        const vis = visibleWidth(line)
+        const padding = vis < perChild ? " ".repeat(perChild - vis) : ""
+        return line + padding
+      })
+      lines.push(parts.join(gapStr))
+    }
+    return lines
+  }
+}
+
+/**
+ * A titled, bordered card with a Markdown body. The title sits inside the top
+ * border and the body fills the inner column at the requested width.
+ */
+export class CardComponent implements Component {
+  constructor(
+    private title: string,
+    private body: string,
+    private theme: Theme,
+    private accent: ThemeColor = "accent",
+  ) {}
+
+  invalidate(): void {
+    // Stateless render: nothing to invalidate.
+  }
+
+  render(width: number): string[] {
+    // 4 = "│ " (2) + " │" (2). Markdown fills the inner column.
+    const innerWidth = Math.max(10, width - 4)
+    const bodyLines = new Markdown(this.body, 0, 0, getMarkdownTheme()).render(
+      innerWidth,
+    )
+
+    const c = (s: string) => this.theme.fg(this.accent, s)
+    const titleText = ` ${this.theme.bold(this.title)} `
+    const titleVis = visibleWidth(titleText)
+
+    // Top: ╭─ Title ──...──╮
+    const topFiller = Math.max(0, width - 2 - 1 - titleVis) // border corners (2) + opening dash (1)
+    const top = c("╭─") + titleText + c("─".repeat(topFiller) + "╮")
+
+    // Bottom: ╰────────────╯
+    const bottom = c("╰" + "─".repeat(Math.max(0, width - 2)) + "╯")
+
+    // Body: │ <line padded to innerWidth> │
+    const sided = bodyLines.map((line) => {
+      const vis = visibleWidth(line)
+      const padding = vis < innerWidth ? " ".repeat(innerWidth - vis) : ""
+      // If a markdown line exceeds innerWidth, truncate to avoid wrapping.
+      const safeLine =
+        vis > innerWidth ? truncateToWidth(line, innerWidth) : line + padding
+      return c("│ ") + safeLine + c(" │")
+    })
+
+    return [top, ...sided, bottom]
+  }
+}
+
+/** Split an array into fixed-size chunks; last chunk may be shorter. */
+export function chunk<T>(arr: T[], size: number): T[][] {
+  const out: T[][] = []
+  for (let i = 0; i < arr.length; i += size) out.push(arr.slice(i, i + size))
+  return out
+}
diff --git a/src/pi-components/workspace-dialog.ts b/src/pi-components/workspace-dialog.ts
new file mode 100644
index 00000000..003080da
--- /dev/null
+++ b/src/pi-components/workspace-dialog.ts
@@ -0,0 +1,5 @@
+export {
+  createWorkspaceDialogComponent,
+  runWorkspaceDialogPreflight,
+  type WorkspaceDialogComponentOptions,
+} from "./workspace-dialog/index.js"
diff --git a/src/pi-components/workspace-dialog/assets/brunch-logo-quad-56x18-240.ansi b/src/pi-components/workspace-dialog/assets/brunch-logo-quad-56x18-240.ansi
new file mode 100644
index 00000000..b5dc6e78
--- /dev/null
+++ b/src/pi-components/workspace-dialog/assets/brunch-logo-quad-56x18-240.ansi
@@ -0,0 +1,19 @@
+[?25l                                                        
+                                                        
+                                                        
+                     ▀▀▀▘ ▀▀▀▀ ▝▀▀▀                     
+          ▀▀▀▘    ▗▀▘     ▀▀▀▀▀▀▀▘▘  ▀▀▀▀▀▀▖            
+        ▘▝▀▀▀▀▀▀▗▗   ▀▀     ▀▀▀   ▀▀▀ ▖    ▀  ▀▀        
+        ▀  ▀     ▐    ▀▀▀    ▀▀▀   ▀▀▀▐▐    ▗▀▀▀ ▀▖     
+       ▐▀▀▀▀ ▖  ▐▐▀▀    ▀▀   ▀▀▀▀▀▀▀  ▐▐   ▗▘ ▀▀▀ ▝     
+       ▝▀ ▀▀▀▀▀▀▀ ▖▀▀   ▀▀▀▀▀▀  ▀▀▀  ▗▘ ▀ ▀▀▀▀▀▀▀▀▗     
+      ▘▀▀▀▀▀▀▀▀▀▀▀ ▀▀   ▀  ▀▀      ▀▀  ▀▀▀▀▀▀▀▀▀▀▗      
+     ▘▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▝▝▀▀▀▀▀▀▀▀▀▀▘▘ ▀▀▀▀▀▀▀▀▀▀▀ ▀       
+     ▝▀      ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ▀         
+           ▀▀▀▀▀▀▀  ▝▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▗▗▀           
+                      ▀ ▀▀▀▀▀▀▀▀▀▀▀▀     ▀              
+                         ▀    ▀▀▀▀▖   ▀                 
+                                                        
+                                                        
+                                                        
+[?25h
\ No newline at end of file
diff --git a/src/pi-components/workspace-dialog/assets/brunch-logo-quad-56x18.ansi b/src/pi-components/workspace-dialog/assets/brunch-logo-quad-56x18.ansi
new file mode 100644
index 00000000..0dbafe1b
--- /dev/null
+++ b/src/pi-components/workspace-dialog/assets/brunch-logo-quad-56x18.ansi
@@ -0,0 +1,19 @@
+[?25l                                                        
+                                                        
+                                                        
+                     ▀▀▀▘▘▀▀▀▀▝▝▀▀▀                     
+          ▀▀▀▀▘▘▘ ▗▀▝▘▗▀▀▀▀▀▀▀▀▀▀▀▀▝ ▀▀▀▀▀▀▖            
+        ▘▝▀▀▀▀▀▀▀▗▘▝▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▝▖▀▀▀▀▀  ▀▀        
+       ▗▀▀▀▀▀▖▝▀▐▐▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▐▐▝▖▐▗▗▀▀▀▗▝▖     
+       ▐▀▀▀▀▀▀▀▀▐▐▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▖▐▐ ▐▐▗▘▀▀▀▀▀▝     
+       ▝▀▀▀▀▀▀▀▀▀▝▖▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▗▗▘▝▀▀▀▀▀▀▀▀▀▀▗     
+      ▘▀▀▀▀▀▀▀▀▀▀▀▖▝▀ ▖▀▀▀▀▀▀▀▀▘▗▗▝▀▘▘▀▀▀▀▀▀▀▀▀▀▀▗      
+     ▘▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▝▝▀▀▀▀▀▀▀▀▀▀▘▝▗▀▀▀▀▀▀▀▀▀▀▀▝▀       
+     ▝▀ ▖▖▗▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▝▀         
+           ▀▀▀▀▀▀▀  ▝▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▗▗▀           
+                      ▀▗ ▀▀▀▀▀▀▀▀▀▀▀     ▀              
+                         ▀    ▀▀▀▀    ▀                 
+                                                        
+                                                        
+                                                        
+[?25h
\ No newline at end of file
diff --git a/src/pi-components/workspace-dialog/assets/brunch.png b/src/pi-components/workspace-dialog/assets/brunch.png
new file mode 100644
index 00000000..c24918a0
Binary files /dev/null and b/src/pi-components/workspace-dialog/assets/brunch.png differ
diff --git a/src/pi-components/workspace-dialog/component.ts b/src/pi-components/workspace-dialog/component.ts
new file mode 100644
index 00000000..4ca2064f
--- /dev/null
+++ b/src/pi-components/workspace-dialog/component.ts
@@ -0,0 +1,418 @@
+import { execSync } from "node:child_process"
+import { readFileSync } from "node:fs"
+import { fileURLToPath } from "node:url"
+
+import { VERSION as PI_VERSION } from "@earendil-works/pi-coding-agent"
+import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent"
+import {
+  Key,
+  matchesKey,
+  truncateToWidth,
+  visibleWidth,
+  type Component,
+} from "@earendil-works/pi-tui"
+
+import type {
+  WorkspaceLaunchInventory,
+  SpecSessionActivationDecision,
+} from "../../workspace-session-coordinator.js"
+import {
+  buildWorkspaceSelectionView,
+  selectWorkspaceSelectionOption,
+  type WorkspaceSelectionStage,
+  type WorkspaceSelectionView,
+} from "./model.js"
+
+export const WORKSPACE_DIALOG_WIDTH = 80
+const ESC = String.fromCharCode(27)
+const CTRL_C = "\x03"
+const ANSI_SEQUENCE = new RegExp(`^${ESC}\\[[0-9;?]*[ -/]*[@-~]`)
+const ANSI_SEQUENCE_GLOBAL = new RegExp(`${ESC}\\[[0-9;?]*[ -/]*[@-~]`, "g")
+const ASSET_DIR = new URL("./assets/", import.meta.url)
+const PACKAGE_JSON_URL = new URL("../../../package.json", import.meta.url)
+const LOCAL_BUILD_TIME = formatBuildTime(new Date())
+
+// Letterform copied from: cfonts "brunch" -f tiny -c candy
+const BRUNCH_WORDMARK = ["█▄▄ █▀█ █ █ █▄ █ █▀▀ █ █", "█▄█ █▀▄ █▄█ █ ▀█ █▄▄ █▀█"]
+
+export type WorkspaceDialogTheme = Pick<Theme, "fg">
+
+export interface WorkspaceDialogComponentOptions {
+  inventory: WorkspaceLaunchInventory
+  onDecision: (decision: SpecSessionActivationDecision) => void
+  theme?: WorkspaceDialogTheme
+  includeContinue?: boolean
+}
+
+export function createWorkspaceDialogComponent(
+  options: WorkspaceDialogComponentOptions,
+): Component {
+  return new WorkspaceDialogComponent(options)
+}
+
+class WorkspaceDialogComponent implements Component {
+  #inventory: WorkspaceLaunchInventory
+  #onDecision: (decision: SpecSessionActivationDecision) => void
+  #theme: WorkspaceDialogTheme | undefined
+  #includeContinue: boolean
+  #selectedIndex = 0
+  #stage: WorkspaceSelectionStage = { stage: "home" }
+  #history: WorkspaceSelectionStage[] = []
+  #title = ""
+
+  constructor(options: WorkspaceDialogComponentOptions) {
+    this.#inventory = options.inventory
+    this.#onDecision = options.onDecision
+    this.#theme = options.theme
+    this.#includeContinue = options.includeContinue ?? true
+  }
+
+  handleInput(data: string): void {
+    if (data === CTRL_C) {
+      this.#onDecision({ action: "cancel" })
+      return
+    }
+
+    if (this.#stage.stage === "newSpecTitle") {
+      this.#handleTitleInput(data)
+      return
+    }
+
+    const view = this.#view()
+
+    if (matchesKey(data, Key.up)) {
+      this.#selectedIndex = Math.max(0, this.#selectedIndex - 1)
+      return
+    }
+    if (matchesKey(data, Key.down)) {
+      this.#selectedIndex = Math.min(
+        view.options.length - 1,
+        this.#selectedIndex + 1,
+      )
+      return
+    }
+    if (matchesKey(data, Key.escape)) {
+      this.#backOrCancel()
+      return
+    }
+    if (matchesKey(data, Key.enter)) {
+      this.#selectCurrentOption()
+    }
+  }
+
+  render(width: number): string[] {
+    const dialogWidth = Math.max(24, Math.min(width, WORKSPACE_DIALOG_WIDTH))
+    const content = this.#contentLines()
+    return renderFrame(content, dialogWidth, this.#theme)
+  }
+
+  invalidate(): void {}
+
+  #contentLines(): string[] {
+    const view = this.#view()
+    const title = style(this.#theme, "accent", view.title)
+    const subtitle = style(
+      this.#theme,
+      "dim",
+      "Choose or create the spec/session before the agent loop runs.",
+    )
+    const logo = readLogo()
+    const version = brunchVersion()
+    const versionLine = style(
+      this.#theme,
+      "accent",
+      `brunch ${version.version}`,
+    )
+    const devLine = version.dev
+      ? style(this.#theme, "success", version.dev)
+      : null
+    const piLine = style(this.#theme, "dim", `built on Pi v${PI_VERSION}`)
+    const lines = [
+      ...logo,
+      ...(logo.length > 0 ? [""] : []),
+      ...BRUNCH_WORDMARK.map((line) => style(this.#theme, "muted", line)),
+      "",
+      versionLine,
+      ...(devLine ? [devLine] : []),
+      piLine,
+      "",
+      title,
+      subtitle,
+      "",
+    ]
+
+    if (this.#stage.stage === "newSpecTitle") {
+      lines.push("New specification title:", `› ${this.#title}`)
+      lines.push("", style(this.#theme, "dim", "enter create • esc back"))
+      return lines
+    }
+
+    for (const [index, option] of view.options.entries()) {
+      const selected = index === this.#selectedIndex
+      const prefix = selected ? style(this.#theme, "accent", "› ") : "  "
+      const label = selected
+        ? style(this.#theme, "accent", option.label)
+        : option.label
+      lines.push(`${prefix}${label}`)
+      lines.push(`    ${style(this.#theme, "dim", option.description)}`)
+    }
+    lines.push(
+      "",
+      style(this.#theme, "dim", "↑↓ navigate • enter select • esc cancel"),
+    )
+    return lines
+  }
+
+  #selectCurrentOption(): void {
+    const result = selectWorkspaceSelectionOption(
+      this.#view(),
+      this.#selectedIndex,
+      this.#inventory,
+      { includeContinue: this.#includeContinue },
+    )
+    if ("decision" in result) {
+      this.#onDecision(result.decision)
+      return
+    }
+    this.#history.push(this.#stage)
+    this.#stage = viewToStage(result.view)
+    this.#selectedIndex = 0
+    if (this.#stage.stage === "newSpecTitle") this.#title = ""
+  }
+
+  #handleTitleInput(data: string): void {
+    if (matchesKey(data, Key.escape)) {
+      this.#backOrCancel()
+      return
+    }
+    if (matchesKey(data, Key.backspace)) {
+      this.#title = this.#title.slice(0, -1)
+      return
+    }
+    if (matchesKey(data, Key.enter)) {
+      const title = this.#title.trim()
+      if (title.length > 0) {
+        this.#onDecision({ action: "newSpec", title })
+      }
+      return
+    }
+    if (isPrintableInput(data)) {
+      this.#title += data
+    }
+  }
+
+  #view(): WorkspaceSelectionView {
+    return buildWorkspaceSelectionView(this.#inventory, this.#stage, {
+      includeContinue: this.#includeContinue,
+    })
+  }
+
+  #backOrCancel(): void {
+    const previous = this.#history.pop()
+    if (!previous) {
+      this.#onDecision({ action: "cancel" })
+      return
+    }
+    this.#stage = previous
+    this.#selectedIndex = 0
+    this.#title = ""
+  }
+}
+
+function viewToStage(view: WorkspaceSelectionView): WorkspaceSelectionStage {
+  if (view.stage === "newSpecTitle") return { stage: "newSpecTitle", title: "" }
+  if (view.stage === "specAction" && view.specId)
+    return { stage: "specAction", specId: view.specId }
+  if (view.stage === "sessionList" && view.specId)
+    return { stage: "sessionList", specId: view.specId }
+  if (view.stage === "specList") return { stage: "specList" }
+  return { stage: "home" }
+}
+
+function renderFrame(
+  content: string[],
+  width: number,
+  theme: WorkspaceDialogTheme | undefined,
+): string[] {
+  return [
+    topBorderLine(width, theme),
+    emptyLine(width, theme),
+    ...content.map((line) => contentLine(line, width, theme)),
+    emptyLine(width, theme),
+    bottomBorderLine(width, theme),
+  ]
+}
+
+interface PackageJson {
+  version?: unknown
+  private?: unknown
+}
+
+interface BrunchVersionInfo {
+  version: string
+  dev: string | null
+}
+
+function formatBuildTime(date: Date): string {
+  return date
+    .toISOString()
+    .replace("T", " ")
+    .replace(/\.\d+Z$/, " UTC")
+}
+
+function readPackage(): PackageJson {
+  try {
+    return JSON.parse(
+      readFileSync(fileURLToPath(PACKAGE_JSON_URL), "utf8"),
+    ) as PackageJson
+  } catch {
+    return {}
+  }
+}
+
+function getGitSha(): string {
+  try {
+    return execSync("git rev-parse --short=7 HEAD", {
+      cwd: fileURLToPath(new URL("../../../", import.meta.url)),
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim()
+  } catch {
+    return ""
+  }
+}
+
+function brunchVersion(): BrunchVersionInfo {
+  const pkg = readPackage()
+  const version = typeof pkg.version === "string" ? pkg.version : "0.0.0"
+  const isLocalDev = pkg.private === true || version === "0.0.0"
+  if (!isLocalDev) return { version: `v${version}`, dev: null }
+
+  const gitSha = getGitSha()
+  const devMeta = [gitSha, `@ ${LOCAL_BUILD_TIME}`].filter(Boolean).join(" ")
+  return { version: `v${version}`, dev: devMeta ? `(dev ${devMeta})` : "(dev)" }
+}
+
+function contentLine(
+  content: string,
+  width: number,
+  theme: WorkspaceDialogTheme | undefined,
+): string {
+  if (width <= 4) return truncateToWidth(content, width)
+  const innerWidth = width - 4
+  const inner = truncateToWidth(content, innerWidth)
+  const padding = " ".repeat(Math.max(0, innerWidth - visibleWidth(inner)))
+  const vertical = style(theme, "borderMuted", "│")
+  return `${vertical} ${inner}${padding} ${vertical}`
+}
+
+function emptyLine(
+  width: number,
+  theme: WorkspaceDialogTheme | undefined,
+): string {
+  if (width <= 2) return " ".repeat(Math.max(0, width))
+  const vertical = style(theme, "borderMuted", "│")
+  return `${vertical}${" ".repeat(width - 2)}${vertical}`
+}
+
+function topBorderLine(
+  width: number,
+  theme: WorkspaceDialogTheme | undefined,
+): string {
+  if (width <= 2) return " ".repeat(Math.max(0, width))
+  return style(theme, "borderMuted", `╭${"─".repeat(width - 2)}╮`)
+}
+
+function bottomBorderLine(
+  width: number,
+  theme: WorkspaceDialogTheme | undefined,
+): string {
+  if (width <= 2) return " ".repeat(Math.max(0, width))
+  return style(theme, "borderMuted", `╰${"─".repeat(width - 2)}╯`)
+}
+
+function readLogo(): string[] {
+  const asset = supportsTruecolor()
+    ? "brunch-logo-quad-56x18.ansi"
+    : "brunch-logo-quad-56x18-240.ansi"
+  try {
+    return cropLogo(
+      readFileSync(fileURLToPath(new URL(asset, ASSET_DIR)), "utf8")
+        .replace(new RegExp(`${ESC}\\[\\?25[lh]`, "g"), "")
+        .replace(new RegExp(`${ESC}\\[0m$`, "g"), "")
+        .split("\n"),
+    )
+  } catch {
+    return []
+  }
+}
+
+function supportsTruecolor(): boolean {
+  const colorterm = process.env.COLORTERM?.toLowerCase() ?? ""
+  const term = process.env.TERM?.toLowerCase() ?? ""
+  return (
+    colorterm === "truecolor" ||
+    colorterm === "24bit" ||
+    term.includes("truecolor")
+  )
+}
+
+function cropLogo(lines: string[]): string[] {
+  const cropped = [...lines]
+  while (cropped.length > 0 && stripAnsi(cropped[0]!).trim().length === 0)
+    cropped.shift()
+  while (
+    cropped.length > 0 &&
+    stripAnsi(cropped[cropped.length - 1]!).trim().length === 0
+  )
+    cropped.pop()
+  if (cropped.length === 0) return []
+
+  const commonLeft = Math.min(...cropped.map(visibleLeadingSpaces))
+  return cropped.map((line) => removeVisibleColumns(line, commonLeft))
+}
+
+function stripAnsi(text: string): string {
+  return text.replace(ANSI_SEQUENCE_GLOBAL, "")
+}
+
+function visibleLeadingSpaces(line: string): number {
+  const match = stripAnsi(line).match(/^ */)
+  return match?.[0].length ?? 0
+}
+
+function removeVisibleColumns(line: string, columns: number): string {
+  if (columns <= 0) return line
+
+  let output = ""
+  let removed = 0
+  for (let index = 0; index < line.length; index += 1) {
+    if (line[index] === ESC) {
+      const match = line.slice(index).match(ANSI_SEQUENCE)
+      if (match) {
+        output += match[0]
+        index += match[0].length - 1
+        continue
+      }
+    }
+
+    if (removed < columns) {
+      removed += 1
+      continue
+    }
+    output += line[index]!
+  }
+  return output
+}
+
+function style(
+  theme: WorkspaceDialogTheme | undefined,
+  color: ThemeColor,
+  text: string,
+): string {
+  return theme ? theme.fg(color, text) : text
+}
+
+function isPrintableInput(data: string): boolean {
+  return data.length === 1 && data >= " " && data !== "\u007f"
+}
diff --git a/src/pi-components/workspace-dialog/index.ts b/src/pi-components/workspace-dialog/index.ts
new file mode 100644
index 00000000..98f9d4e8
--- /dev/null
+++ b/src/pi-components/workspace-dialog/index.ts
@@ -0,0 +1,14 @@
+export {
+  WORKSPACE_DIALOG_WIDTH,
+  createWorkspaceDialogComponent,
+  type WorkspaceDialogComponentOptions,
+} from "./component.js"
+export {
+  buildWorkspaceSelectionView,
+  selectWorkspaceSelectionOption,
+  type WorkspaceSelectionOption,
+  type WorkspaceSelectionResult,
+  type WorkspaceSelectionStage,
+  type WorkspaceSelectionView,
+} from "./model.js"
+export { runWorkspaceDialogPreflight } from "./preflight.js"
diff --git a/src/pi-components/workspace-dialog/model.ts b/src/pi-components/workspace-dialog/model.ts
new file mode 100644
index 00000000..7c022c39
--- /dev/null
+++ b/src/pi-components/workspace-dialog/model.ts
@@ -0,0 +1,247 @@
+import type {
+  WorkspaceLaunchInventory,
+  WorkspaceLaunchSession,
+  SpecSessionActivationDecision,
+} from "../../workspace-session-coordinator.js"
+
+export type WorkspaceSelectionStage = { stage: "home" } | {
+  stage: "newSpecTitle"
+  title: string
+} | { stage: "specList" } | {
+  stage: "specAction"
+  specId: string
+} | {
+  stage: "sessionList"
+  specId: string
+}
+
+export interface WorkspaceSelectionOption {
+  id: string
+  label: string
+  description: string
+  kind: "continue" | "newSpec" | "resumeSpec" | "cancel" | "spec" | "newSession" | "resumeSession" | "session"
+  decision?: SpecSessionActivationDecision
+  nextStage?: WorkspaceSelectionStage
+}
+
+export interface WorkspaceSelectionView {
+  stage: WorkspaceSelectionStage["stage"]
+  title: string
+  options: WorkspaceSelectionOption[]
+  specId?: string
+}
+
+export interface WorkspaceSelectionViewOptions {
+  includeContinue?: boolean
+}
+
+export type WorkspaceSelectionResult = {
+  decision: SpecSessionActivationDecision
+} | {
+  view: WorkspaceSelectionView
+}
+
+export function buildWorkspaceSelectionView(
+  inventory: WorkspaceLaunchInventory,
+  stage: WorkspaceSelectionStage = { stage: "home" },
+  options: WorkspaceSelectionViewOptions = {},
+): WorkspaceSelectionView {
+  if (stage.stage === "newSpecTitle") {
+    return {
+      stage: "newSpecTitle",
+      title: "Create new specification",
+      options: [],
+    }
+  }
+
+  if (stage.stage === "specList") {
+    return {
+      stage: "specList",
+      title: "Choose a specification",
+      options: inventory.specs.map(({ spec }) => ({
+        id: `spec:${spec.id}`,
+        label: spec.title,
+        description: "Choose how to continue this specification",
+        kind: "spec",
+        nextStage: { stage: "specAction", specId: spec.id },
+      })),
+    }
+  }
+
+  if (stage.stage === "specAction") {
+    const spec = findSpec(inventory, stage.specId)
+    const options: WorkspaceSelectionOption[] = [
+      {
+        id: `new-session:${stage.specId}`,
+        label: "Create new session",
+        description: "Start a binding-only session for this specification",
+        kind: "newSession",
+        decision: { action: "newSession", specId: stage.specId },
+      },
+    ]
+    if ((spec?.sessions.length ?? 0) > 0) {
+      options.push({
+        id: `resume-session:${stage.specId}`,
+        label: "Resume existing session",
+        description: "Choose a prior session transcript explicitly",
+        kind: "resumeSession",
+        nextStage: { stage: "sessionList", specId: stage.specId },
+      })
+    }
+    return {
+      stage: "specAction",
+      specId: stage.specId,
+      title: spec ? `Continue ${spec.spec.title}` : "Continue specification",
+      options,
+    }
+  }
+
+  if (stage.stage === "sessionList") {
+    const spec = findSpec(inventory, stage.specId)
+    return {
+      stage: "sessionList",
+      specId: stage.specId,
+      title: spec
+        ? `Choose a session for ${spec.spec.title}`
+        : "Choose a session",
+      options: (spec?.sessions ?? []).map((session) => ({
+        id: `session:${session.file}`,
+        label: session.name ?? session.id,
+        description: sessionDescription(session, "Open existing session"),
+        kind: "session",
+        decision: {
+          action: "openSession",
+          specId: stage.specId,
+          sessionFile: session.file,
+        },
+      })),
+    }
+  }
+
+  return buildHomeSelectionView(inventory, options)
+}
+
+export function selectWorkspaceSelectionOption(
+  view: WorkspaceSelectionView,
+  index: number,
+  inventory?: WorkspaceLaunchInventory,
+  options: WorkspaceSelectionViewOptions = {},
+): WorkspaceSelectionResult {
+  const option = view.options[index]
+  if (!option) return { decision: { action: "cancel" } }
+  if (option.decision) return { decision: option.decision }
+  if (!inventory) {
+    return { view: stageOnlyView(option.nextStage ?? { stage: "home" }) }
+  }
+  return {
+    view: buildWorkspaceSelectionView(inventory, option.nextStage, options),
+  }
+}
+
+function stageOnlyView(stage: WorkspaceSelectionStage): WorkspaceSelectionView {
+  return {
+    stage: stage.stage,
+    title: stage.stage === "newSpecTitle" ? stage.title : "",
+    ...("specId" in stage ? { specId: stage.specId } : {}),
+    options: [],
+  }
+}
+
+function buildHomeSelectionView(
+  inventory: WorkspaceLaunchInventory,
+  viewOptions: WorkspaceSelectionViewOptions,
+): WorkspaceSelectionView {
+  const selectionOptions: WorkspaceSelectionOption[] = []
+  const currentSession = findCurrentSession(inventory)
+
+  if (
+    viewOptions.includeContinue !== false &&
+    currentSession &&
+    inventory.currentSpec
+  ) {
+    selectionOptions.push({
+      id: `continue:${currentSession.file}`,
+      label: "Continue your latest spec and session",
+      description: `${inventory.currentSpec.title} · ${currentSession.id}`,
+      kind: "continue",
+      decision: {
+        action: "continue",
+        specId: inventory.currentSpec.id,
+        sessionFile: currentSession.file,
+      },
+    })
+  }
+
+  const newSpecOption: WorkspaceSelectionOption = {
+    id: "new-spec",
+    label: "Start a new specification",
+    description: "Name a new spec and create its first session",
+    kind: "newSpec",
+    nextStage: { stage: "newSpecTitle", title: "" },
+  }
+  const resumeSpecOption: WorkspaceSelectionOption | null =
+    inventory.specs.length > 0
+      ? {
+          id: "resume-spec",
+          label:
+            viewOptions.includeContinue === false
+              ? "Switch to another specification"
+              : "Continue another existing specification",
+          description: "Choose a spec, then create or resume a session",
+          kind: "resumeSpec",
+          nextStage: { stage: "specList" },
+        }
+      : null
+  const cancelOption: WorkspaceSelectionOption = {
+    id: "cancel",
+    label: "Cancel",
+    description: "Exit without activating a spec/session",
+    kind: "cancel",
+    decision: { action: "cancel" },
+  }
+
+  if (viewOptions.includeContinue === false) {
+    if (resumeSpecOption) selectionOptions.push(resumeSpecOption)
+    selectionOptions.push(newSpecOption, cancelOption)
+  } else {
+    if (resumeSpecOption) selectionOptions.push(resumeSpecOption)
+    selectionOptions.push(newSpecOption, cancelOption)
+  }
+
+  return {
+    stage: "home",
+    title: "Choose a specification",
+    options: selectionOptions,
+  }
+}
+
+function findCurrentSession(
+  inventory: WorkspaceLaunchInventory,
+): WorkspaceLaunchSession | undefined {
+  if (!inventory.currentSessionFile) {
+    return undefined
+  }
+  for (const spec of inventory.specs) {
+    const session = spec.sessions.find(
+      (candidate) => candidate.file === inventory.currentSessionFile,
+    )
+    if (session) {
+      return session
+    }
+  }
+  return undefined
+}
+
+function findSpec(
+  inventory: WorkspaceLaunchInventory,
+  specId: string,
+): WorkspaceLaunchInventory["specs"][number] | undefined {
+  return inventory.specs.find((candidate) => candidate.spec.id === specId)
+}
+
+function sessionDescription(
+  session: WorkspaceLaunchSession,
+  prefix: string,
+): string {
+  return `${prefix} · ${session.id}`
+}
diff --git a/src/pi-components/workspace-dialog/preflight.ts b/src/pi-components/workspace-dialog/preflight.ts
new file mode 100644
index 00000000..01a7cae6
--- /dev/null
+++ b/src/pi-components/workspace-dialog/preflight.ts
@@ -0,0 +1,88 @@
+import type { ThemeColor } from "@earendil-works/pi-coding-agent"
+import { ProcessTerminal, TUI, type Terminal } from "@earendil-works/pi-tui"
+
+import type {
+  WorkspaceLaunchInventory,
+  SpecSessionActivationDecision,
+} from "../../workspace-session-coordinator.js"
+import {
+  WORKSPACE_DIALOG_WIDTH,
+  createWorkspaceDialogComponent,
+  type WorkspaceDialogTheme,
+} from "./component.js"
+
+interface WorkspaceDialogPreflightOptions {
+  terminal?: Terminal
+  theme?: WorkspaceDialogTheme
+}
+
+export async function runWorkspaceDialogPreflight(
+  inventory: WorkspaceLaunchInventory,
+  options: WorkspaceDialogPreflightOptions = {},
+): Promise<SpecSessionActivationDecision> {
+  const terminal = options.terminal ?? new ProcessTerminal()
+  const tui = new TUI(terminal)
+  const dialogTheme = options.theme ?? resolveStartupDialogTheme()
+
+  return await new Promise<SpecSessionActivationDecision>((resolve) => {
+    const finish = (decision: SpecSessionActivationDecision) => {
+      overlay.hide()
+      tui.stop()
+      terminal.clearScreen()
+      resolve(decision)
+    }
+    const component = createWorkspaceDialogComponent({
+      inventory,
+      theme: dialogTheme,
+      onDecision: finish,
+    })
+    const overlay = tui.showOverlay(component, {
+      anchor: "center",
+      width: WORKSPACE_DIALOG_WIDTH,
+      maxHeight: "90%",
+      margin: 1,
+    })
+    terminal.clearScreen()
+    tui.start()
+  })
+}
+
+function resolveStartupDialogTheme(): WorkspaceDialogTheme {
+  const colors = startupPalette(detectStartupThemeName())
+  return {
+    fg(color: ThemeColor, text: string) {
+      const ansi = colors[color]
+      return ansi ? `${ansi}${text}\x1B[39m` : text
+    },
+  }
+}
+
+function detectStartupThemeName(): "dark" | "light" {
+  const colorfgbg = process.env.COLORFGBG ?? ""
+  const background = Number.parseInt(colorfgbg.split(";").at(-1) ?? "", 10)
+  if (!Number.isNaN(background)) {
+    return background < 8 ? "dark" : "light"
+  }
+  return "dark"
+}
+
+function startupPalette(
+  themeName: "dark" | "light",
+): Partial<Record<ThemeColor, string>> {
+  if (themeName === "light") {
+    return {
+      accent: "\x1B[38;2;90;128;128m",
+      borderMuted: "\x1B[38;2;176;176;176m",
+      dim: "\x1B[38;2;118;118;118m",
+      muted: "\x1B[38;2;108;108;108m",
+      success: "\x1B[38;2;88;132;88m",
+    }
+  }
+  return {
+    accent: "\x1B[38;2;138;190;183m",
+    borderMuted: "\x1B[38;2;80;80;80m",
+    dim: "\x1B[38;2;102;102;102m",
+    muted: "\x1B[38;2;128;128;128m",
+    success: "\x1B[38;2;181;189;104m",
+  }
+}
diff --git a/src/pi-extensions.ts b/src/pi-extensions.ts
new file mode 100644
index 00000000..a74934e6
--- /dev/null
+++ b/src/pi-extensions.ts
@@ -0,0 +1,118 @@
+import {
+  SessionManager,
+  type ExtensionFactory,
+} from "@earendil-works/pi-coding-agent"
+
+import { registerBrunchAlternatives } from "./pi-extensions/alternatives.js"
+import { registerBrunchBranchPolicyHandlers } from "./pi-extensions/command-policy.js"
+import {
+  FIXTURE_GRAPH_MENTION_SOURCE,
+  registerBrunchMentionAutocomplete,
+  type GraphMentionSource,
+} from "./pi-extensions/mention-autocomplete.js"
+import { registerBrunchOperationalModePolicy } from "./pi-extensions/operational-mode.js"
+import { registerBrunchStructuredQuestion } from "./pi-extensions/structured-question.js"
+import {
+  renderBrunchChrome,
+  type BrunchChromeState,
+} from "./pi-extensions/chrome.js"
+import {
+  bindBrunchSessionBoundary,
+  registerBrunchSessionBoundaryRefreshHandlers,
+  type BrunchSessionBoundaryHandler,
+} from "./pi-extensions/session-lifecycle.js"
+import {
+  registerBrunchWorkspaceDialog,
+  type BrunchSpecSessionPickerOptions,
+} from "./pi-extensions/workspace-dialog.js"
+
+export { registerBrunchAlternatives } from "./pi-extensions/alternatives.js"
+export { BRUNCH_BRANCH_FLOW_BLOCKED_MESSAGE } from "./pi-extensions/command-policy.js"
+export {
+  registerBrunchMentionAutocomplete,
+  type GraphMentionCandidate,
+  type GraphMentionSource,
+} from "./pi-extensions/mention-autocomplete.js"
+export {
+  BRUNCH_AGENT_RUNTIME_STATE_CUSTOM_TYPE,
+  DEFAULT_BRUNCH_AGENT_STATE,
+  appendBrunchAgentRuntimeInit,
+  appendBrunchAgentRuntimeSwitch,
+  projectBrunchAgentState,
+  registerBrunchOperationalModePolicy,
+  type AgentLensId,
+  type AgentRoleDefinition,
+  type AgentRoleId,
+  type AgentStrategyId,
+  type BrunchAgentState,
+  type BrunchAgentStateEntryData,
+  type BrunchAgentStateEntrySessionManager,
+  type OperationalModeDefinition,
+  type OperationalModeId,
+  type ResolvedBrunchAgentState,
+} from "./pi-extensions/operational-mode.js"
+export {
+  chromeStateForWorkspace,
+  projectBrunchChromeFooterLines,
+  renderBrunchChrome,
+  type BrunchChromeCoherenceVerdict,
+  type BrunchChromeFooterTelemetry,
+  type BrunchChromeStage,
+  type BrunchChromeState,
+  type BrunchChromeUi,
+  type BrunchChromeWorkerStatus,
+} from "./pi-extensions/chrome.js"
+export {
+  bindBrunchSessionBoundary,
+  registerBrunchSessionBoundaryRefreshHandlers,
+  type BrunchSessionBoundaryHandler,
+} from "./pi-extensions/session-lifecycle.js"
+export {
+  STRUCTURED_QUESTION_TOOL,
+  answerStructuredQuestionWithTui,
+  buildStructuredQuestionEditorPrefill,
+  createStructuredQuestionTuiComponent,
+  parseStructuredQuestionEditorResponse,
+  registerBrunchStructuredQuestion,
+  structuredQuestionResultFromEditor,
+  type StructuredQuestionTuiResponse,
+} from "./pi-extensions/structured-question.js"
+export {
+  BRUNCH_WORKSPACE_COMMAND,
+  BRUNCH_WORKSPACE_SHORTCUT,
+  registerBrunchWorkspaceDialog,
+  runBrunchWorkspaceAction,
+  runBrunchWorkspaceCommand,
+  type BrunchSpecSessionPickerOptions,
+} from "./pi-extensions/workspace-dialog.js"
+
+export interface BrunchPiExtensionShellOptions
+  extends BrunchSpecSessionPickerOptions {
+  graphMentionSource?: GraphMentionSource
+}
+
+export function createBrunchPiExtensionShell(
+  chrome: BrunchChromeState,
+  onSessionBoundary: BrunchSessionBoundaryHandler | undefined,
+  options: BrunchPiExtensionShellOptions,
+): ExtensionFactory {
+  return (pi) => {
+    pi.on("session_start", async (_event, ctx) => {
+      await bindBrunchSessionBoundary(
+        ctx.sessionManager as SessionManager,
+        onSessionBoundary,
+      )
+      renderBrunchChrome(ctx.ui, chrome)
+    })
+    registerBrunchSessionBoundaryRefreshHandlers(pi, onSessionBoundary)
+    registerBrunchBranchPolicyHandlers(pi)
+    registerBrunchOperationalModePolicy(pi)
+    registerBrunchMentionAutocomplete(
+      pi,
+      options.graphMentionSource ?? FIXTURE_GRAPH_MENTION_SOURCE,
+    )
+    registerBrunchAlternatives(pi)
+    registerBrunchStructuredQuestion(pi)
+    registerBrunchWorkspaceDialog(pi, options)
+  }
+}
diff --git a/src/pi-extensions/alternatives.ts b/src/pi-extensions/alternatives.ts
new file mode 100644
index 00000000..f0c8cdd3
--- /dev/null
+++ b/src/pi-extensions/alternatives.ts
@@ -0,0 +1,211 @@
+/**
+ * Brunch alternatives transcript primitive.
+ *
+ * Owns the `alternatives-card-set` custom message type end-to-end:
+ *   - registerMessageRenderer to draw bordered cards in the transcript
+ *   - registerTool (`present_alternatives`) so the LLM can emit a card set
+ *
+ * Compared with an ephemeral picker (e.g. `ctx.ui.custom`), this surface
+ * presents alternatives via `pi.sendMessage`: persistent, immediately returned,
+ * and visible to transcript replay/RPC clients through markdown fallback text.
+ */
+
+import type { ExtensionAPI, ThemeColor } from "@earendil-works/pi-coding-agent"
+import { Container, Text } from "@earendil-works/pi-tui"
+import { StringEnum } from "@earendil-works/pi-ai"
+import { Type } from "typebox"
+
+import {
+  CardComponent,
+  ResponsiveColumns,
+  chunk,
+} from "../pi-components/cards.js"
+
+// ── Types & schema ─────────────────────────────────────────────────────
+const FLAVOR = StringEnum(["accent", "success", "warning", "muted"] as const)
+type Flavor = "accent" | "success" | "warning" | "muted"
+
+interface Alternative {
+  title: string
+  body: string
+  flavor?: Flavor
+}
+
+type Layout = "stack" | "columns"
+
+interface AlternativesDetails {
+  headline?: string | undefined
+  alternatives: Alternative[]
+  layout?: Layout | undefined
+  columnCount?: number | undefined
+  minColumnWidth?: number | undefined
+}
+
+const AlternativeSchema = Type.Object({
+  title: Type.String({ description: "Short label for the card header" }),
+  body: Type.String({
+    description: "Markdown content rendered inside the card",
+  }),
+  flavor: Type.Optional(FLAVOR),
+})
+
+const LAYOUT = StringEnum(["stack", "columns"] as const)
+
+const PresentAlternativesParams = Type.Object({
+  headline: Type.Optional(
+    Type.String({ description: "Optional headline shown above the cards" }),
+  ),
+  alternatives: Type.Array(AlternativeSchema, { minItems: 1, maxItems: 6 }),
+  layout: Type.Optional(LAYOUT),
+  columnCount: Type.Optional(
+    Type.Integer({
+      minimum: 1,
+      maximum: 4,
+      description: "Cards per row when layout is 'columns'. Default 2.",
+    }),
+  ),
+  minColumnWidth: Type.Optional(
+    Type.Integer({
+      minimum: 20,
+      maximum: 200,
+      description:
+        "Minimum width per card before falling back to vertical stack. Default 40.",
+    }),
+  ),
+})
+
+function flavorToColor(flavor: Flavor | undefined): ThemeColor {
+  switch (flavor) {
+    case "success":
+      return "success"
+    case "warning":
+      return "warning"
+    case "muted":
+      return "muted"
+    default:
+      return "accent"
+  }
+}
+
+// Plain-markdown fallback so RPC clients without the renderer still see
+// coherent content. Also persisted as the message `content` field.
+function alternativesToMarkdown(details: AlternativesDetails): string {
+  const sections: string[] = []
+  if (details.headline) sections.push(`## ${details.headline}`)
+  for (const alt of details.alternatives) {
+    sections.push(`### ${alt.title}\n\n${alt.body}`)
+  }
+  return sections.join("\n\n---\n\n")
+}
+
+function supportsAlternativesPrimitive(pi: ExtensionAPI): boolean {
+  const candidate = pi as Partial<ExtensionAPI>
+  return (
+    typeof candidate.registerMessageRenderer === "function" &&
+    typeof candidate.registerTool === "function" &&
+    typeof candidate.sendMessage === "function"
+  )
+}
+
+export function registerBrunchAlternatives(pi: ExtensionAPI) {
+  if (!supportsAlternativesPrimitive(pi)) {
+    return
+  }
+
+  // ── Renderer ────────────────────────────────────────────────────────
+  pi.registerMessageRenderer(
+    "alternatives-card-set",
+    (message, _opts, theme) => {
+      const details = message.details as AlternativesDetails | undefined
+      if (!details) {
+        // Fallback: if details is missing, render the raw content string.
+        return new Text(
+          typeof message.content === "string" ? message.content : "",
+          0,
+          0,
+        )
+      }
+
+      const container = new Container()
+      if (details.headline) {
+        container.addChild(
+          new Text(
+            theme.fg("customMessageLabel", theme.bold(details.headline)),
+            1,
+            1,
+          ),
+        )
+      }
+
+      const layout = details.layout ?? "stack"
+      const columnCount = Math.max(1, Math.min(4, details.columnCount ?? 2))
+      const minColumnWidth = details.minColumnWidth ?? 40
+
+      const makeCard = (alt: Alternative) =>
+        new CardComponent(alt.title, alt.body, theme, flavorToColor(alt.flavor))
+
+      if (layout === "columns" && details.alternatives.length > 1) {
+        const groups = chunk(details.alternatives, columnCount)
+        groups.forEach((group, gi) => {
+          container.addChild(
+            new ResponsiveColumns(group.map(makeCard), minColumnWidth),
+          )
+          if (gi < groups.length - 1) container.addChild(new Text("", 0, 0))
+        })
+      } else {
+        details.alternatives.forEach((alt, i) => {
+          container.addChild(makeCard(alt))
+          if (i < details.alternatives.length - 1)
+            container.addChild(new Text("", 0, 0))
+        })
+      }
+      return container
+    },
+  )
+
+  // ── Tool ────────────────────────────────────────────────────────────
+  pi.registerTool({
+    name: "present_alternatives",
+    label: "Present Alternatives",
+    description:
+      "Present 1–6 alternative options to the user as bordered cards. Each alternative has a short title and a markdown body. Optional `flavor` (accent/success/warning/muted) styles the card border. Use when comparing options, surfacing draft variants, or laying out trade-offs.",
+    promptSnippet:
+      "Present comparable alternatives as bordered cards in the transcript",
+    promptGuidelines: [
+      "Use present_alternatives when the user needs to compare 2–6 options side by side.",
+      "Each alternative's body should be self-contained markdown — headings, lists, code blocks all work.",
+      "After present_alternatives, ask the user which one they prefer rather than picking yourself.",
+    ],
+    parameters: PresentAlternativesParams,
+
+    async execute(_toolCallId, params) {
+      const details: AlternativesDetails = {
+        headline: params.headline,
+        alternatives: params.alternatives,
+        layout: params.layout,
+        columnCount: params.columnCount,
+        minColumnWidth: params.minColumnWidth,
+      }
+
+      pi.sendMessage({
+        customType: "alternatives-card-set",
+        content: alternativesToMarkdown(details), // fallback / replay
+        display: true,
+        details,
+      })
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Presented ${params.alternatives.length} alternative${
+              params.alternatives.length === 1 ? "" : "s"
+            }.`,
+          },
+        ],
+        details: { count: params.alternatives.length },
+        terminate: true,
+      }
+    },
+  })
+}
diff --git a/src/pi-extensions/auto-compaction-anchors.json b/src/pi-extensions/auto-compaction-anchors.json
new file mode 100644
index 00000000..82017563
--- /dev/null
+++ b/src/pi-extensions/auto-compaction-anchors.json
@@ -0,0 +1,46 @@
+{
+  "$comment": "Canonical anchor preservation contract for the auto-compaction extension (D43-L, I28-L). Reviewable and editable without SPEC churn. Validated through a TypeBox schema when src/pi-extensions/auto-compaction.ts lands; until then, treat additions as SPEC-aware data changes. Selection rules: 'first' = first matching entry in branch order (singletons like session_binding); 'latest' = most recent matching entry (singleton-by-recency); 'active-leaves' = matching entries that are leaves of their supersedes chain and not yet terminal; 'all-unresolved' = matching entries whose effect has not yet been consumed by the agent or settled by user action.",
+  "version": 1,
+  "anchors": [
+    {
+      "kind": "brunch.session_binding",
+      "select": "first",
+      "rationale": "I8-L — exactly one binding per session; must survive compaction byte-stable to keep the JSONL self-describing."
+    },
+    {
+      "kind": "brunch.agent_runtime_state",
+      "select": "latest",
+      "rationale": "D40-L — turn preparation reconstructs operational mode / role preset / strategy / lens from the latest valid runtime-state snapshot; losing it after compaction breaks I25-L."
+    },
+    {
+      "kind": "brunch.establishment_offer",
+      "select": "latest",
+      "rationale": "PLAN compaction-and-conflict-widening — ambient-affordance chrome reads the latest establishment offer to render the current orientation surface."
+    },
+    {
+      "kind": "brunch.lens_switch",
+      "select": "latest",
+      "rationale": "D25-L — observer/reviewer routing and prompt composition depend on the active lens; the latest switch is the authoritative lens marker post-compaction."
+    },
+    {
+      "kind": "brunch.review_set_proposal",
+      "select": "active-leaves",
+      "rationale": "D27-L, D28-L — proposals not yet accepted/rejected and not superseded must remain reviewable after compaction; superseded ancestors do not."
+    },
+    {
+      "kind": "brunch.side_task_result",
+      "select": "all-unresolved",
+      "rationale": "D15-L, I12-L — succeeded side-task results awaiting next-turn-boundary delivery must remain deliverable after compaction; mid-turn delivery remains forbidden."
+    },
+    {
+      "kind": "brunch.mention_staleness_hint",
+      "select": "all-unresolved",
+      "rationale": "D14-L, I9-L — staleness hints the agent has not yet acted upon must survive so the re-read affordance is not silently dropped."
+    },
+    {
+      "kind": "worldUpdate",
+      "select": "latest",
+      "rationale": "R13, I4-L — the latest cross-session graph delta must remain available so the agent does not re-derive world state from an outdated snapshot."
+    }
+  ]
+}
diff --git a/src/pi-extensions/chrome.test.ts b/src/pi-extensions/chrome.test.ts
new file mode 100644
index 00000000..a13da6a7
--- /dev/null
+++ b/src/pi-extensions/chrome.test.ts
@@ -0,0 +1,228 @@
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent"
+
+import { describe, expect, it } from "vitest"
+
+import type { WorkspaceSessionReadyState } from "../workspace-session-coordinator.js"
+import {
+  chromeStateForWorkspace,
+  formatBrunchChromeHeaderLines,
+  formatChromeWidgetLines,
+  projectBrunchChromeFooterLines,
+  renderBrunchChrome,
+} from "./chrome.js"
+
+describe("Brunch chrome projection", () => {
+  it("uses activated session state instead of fabricating unbound", async () => {
+    const state = chromeStateForWorkspace(
+      readyWorkspace("/tmp/project", "session-real"),
+    )
+
+    expect(formatBrunchChromeHeaderLines(state).join("\n")).toContain(
+      "session-real",
+    )
+  })
+
+  it("formats chrome header as wordmark plus runtime-state summary", async () => {
+    const state = {
+      cwd: "/tmp/project",
+      spec: { id: "spec-1", title: "Spec One" },
+      session: { id: "session-1", label: "Interview #1" },
+      phase: "elicitation" as const,
+      chatMode: "responding-to-elicitation" as const,
+      runtime: {
+        bundle: "elicit-default",
+        role: "elicitor",
+        model: "claude-sonnet",
+        thinking: "medium",
+        lens: "step-by-step",
+      },
+    }
+
+    expect(formatBrunchChromeHeaderLines(state)).toEqual([
+      "brunch",
+      "runtime: elicit-default · role elicitor · claude-sonnet · thinking medium · lens step-by-step",
+      "spec: Spec One · session: Interview #1 · phase: elicitation",
+    ])
+  })
+
+  it("formats honest Brunch chrome from one product-state snapshot", async () => {
+    const state = {
+      cwd: "/tmp/project",
+      spec: { id: "spec-1", title: "Spec One" },
+      session: { id: "session-1", label: "Interview #1" },
+      phase: "elicitation" as const,
+      chatMode: "responding-to-elicitation" as const,
+    }
+
+    expect(formatBrunchChromeHeaderLines(state)).toEqual([
+      "brunch",
+      "runtime: not reported",
+      "spec: Spec One · session: Interview #1 · phase: elicitation",
+    ])
+    expect(projectBrunchChromeFooterLines(state)).toEqual([
+      "runtime: not reported · build: not reported",
+      "context: not reported",
+      "state: responding-to-elicitation · coherence: unknown · worker: not reported",
+      "spec: Spec One · session: Interview #1",
+      "",
+    ])
+    expect(formatChromeWidgetLines(state)).toEqual([
+      "cwd: /tmp/project",
+      "spec: Spec One",
+      "session: Interview #1",
+      "runtime: not reported",
+      "context: not reported",
+      "chat mode: responding-to-elicitation",
+    ])
+  })
+
+  it("formats rich optional runtime and context metadata without fabricating missing fields", () => {
+    const state = {
+      cwd: "/tmp/project",
+      spec: { id: "spec-1", title: "Spec One" },
+      session: { id: "session-1", label: "Interview #1" },
+      phase: "elicitation" as const,
+      chatMode: "responding-to-elicitation" as const,
+      runtime: {
+        bundle: "elicit-default",
+        role: "elicitor",
+        model: "claude-sonnet",
+        thinking: "medium",
+        lens: "step-by-step",
+      },
+      build: { version: "v0.0.0", dev: "dev abc123" },
+      contextUsage: { usedTokens: 1024, maxTokens: 2048 },
+      worker: { stage: "observer-review" as const, status: "queued" as const },
+      coherence: "needs_review" as const,
+    }
+
+    expect(projectBrunchChromeFooterLines(state)).toEqual([
+      "runtime: elicit-default · role elicitor · claude-sonnet · thinking medium · lens step-by-step · build: v0.0.0 dev abc123",
+      "context: [█████░░░░░] 1,024/2,048 tokens (50%)",
+      "state: responding-to-elicitation · coherence: needs_review · worker: observer-review/queued",
+      "spec: Spec One · session: Interview #1",
+      "",
+    ])
+    expect(formatChromeWidgetLines(state)).toContain(
+      "context: [█████░░░░░] 1,024/2,048 tokens (50%)",
+    )
+  })
+
+  it("projects footer telemetry and foreign statuses without publishing a chrome status key", async () => {
+    const footer = projectBrunchChromeFooterLines(
+      {
+        cwd: "/tmp/project",
+        spec: { id: "spec-1", title: "Spec One" },
+        session: { id: "session-1", label: "Interview #1" },
+        phase: "elicitation",
+        chatMode: "responding-to-elicitation",
+        runtime: {
+          bundle: "elicit-default",
+          role: "elicitor",
+          model: "claude-sonnet",
+          thinking: "medium",
+        },
+        contextUsage: { usedTokens: 1024, maxTokens: 2048 },
+      },
+      {
+        gitBranch: "main",
+        statuses: new Map([
+          ["brunch.reviewer", "reviewer queued"],
+          ["brunch.chrome", "should not echo"],
+        ]),
+      },
+      200,
+    ).join("\n")
+
+    expect(footer).toContain("Spec One")
+    expect(footer).toContain("Interview #1")
+    expect(footer).toContain("main")
+    expect(footer).toContain("claude-sonnet")
+    expect(footer).toContain("thinking medium")
+    expect(footer).toContain("[█████░░░░░] 1,024/2,048 tokens (50%)")
+    expect(footer).toContain("reviewer queued")
+    expect(footer).not.toContain("should not echo")
+  })
+
+  it("renders Brunch chrome through one wrapper over Pi UI calls", async () => {
+    const calls: FakeUiCall[] = []
+    const ui: FakeExtensionUi = {
+      setHeader: (...args: unknown[]) =>
+        calls.push({ method: "setHeader", args }),
+      setFooter: (...args: unknown[]) =>
+        calls.push({ method: "setFooter", args }),
+      setStatus: (...args: unknown[]) =>
+        calls.push({ method: "setStatus", args }),
+      setWidget: (...args: unknown[]) =>
+        calls.push({ method: "setWidget", args }),
+      setWorkingIndicator: (_options) => {},
+      setTitle: (...args: unknown[]) =>
+        calls.push({ method: "setTitle", args }),
+      notify: (_message: string, _type?: "info" | "warning" | "error") => {},
+    }
+
+    renderBrunchChrome(ui, {
+      cwd: "/tmp/project",
+      spec: { id: "spec-1", title: "Spec One" },
+      session: { id: "session-1" },
+      phase: "elicitation",
+      chatMode: "responding-to-elicitation",
+    })
+
+    expect(calls.map((call) => call.method)).toEqual([
+      "setHeader",
+      "setFooter",
+      "setWidget",
+      "setTitle",
+    ])
+    expect(calls.find((call) => call.method === "setFooter")?.args[0]).toEqual(
+      expect.any(Function),
+    )
+    expect(calls.some((call) => call.method === "setStatus")).toBe(false)
+    expect(calls.find((call) => call.method === "setWidget")?.args).toEqual([
+      "brunch.chrome",
+      [
+        "cwd: /tmp/project",
+        "spec: Spec One",
+        "session: session-1",
+        "runtime: not reported",
+        "context: not reported",
+        "chat mode: responding-to-elicitation",
+      ],
+      { placement: "aboveEditor" },
+    ])
+    expect(calls.find((call) => call.method === "setTitle")?.args).toEqual([
+      "brunch — Spec One",
+    ])
+  })
+})
+
+function readyWorkspace(
+  cwd: string,
+  sessionId: string,
+): WorkspaceSessionReadyState {
+  const spec = { id: "spec-1", title: "Spec One" }
+  return {
+    status: "ready",
+    cwd,
+    spec,
+    session: {
+      id: sessionId,
+      file: `/sessions/${sessionId}.jsonl`,
+      manager: {} as WorkspaceSessionReadyState["session"]["manager"],
+    },
+    chrome: {
+      cwd,
+      spec,
+      phase: "elicitation",
+      chatMode: "responding-to-elicitation",
+    },
+  }
+}
+
+interface FakeUiCall {
+  method: string
+  args: unknown[]
+}
+
+type FakeExtensionUi = Pick<ExtensionUIContext, "setFooter" | "setHeader" | "setStatus" | "setWidget" | "setWorkingIndicator" | "setTitle" | "notify">
diff --git a/src/pi-extensions/chrome.ts b/src/pi-extensions/chrome.ts
new file mode 100644
index 00000000..97731718
--- /dev/null
+++ b/src/pi-extensions/chrome.ts
@@ -0,0 +1,208 @@
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent"
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui"
+
+import type {
+  WorkspaceSessionChromeState,
+  WorkspaceSessionReadyState,
+} from "../workspace-session-coordinator.js"
+
+export type BrunchChromeStage = "idle" | "streaming" | "observer-review"
+export type BrunchChromeWorkerStatus = "idle" | "queued" | "running" | "blocked"
+export type BrunchChromeCoherenceVerdict = "unknown" | "coherent" | "needs_review" | "incoherent"
+
+export interface BrunchChromeContextUsage {
+  usedTokens: number
+  maxTokens: number
+}
+
+export interface BrunchChromeRuntimeState {
+  bundle?: string
+  role?: string
+  model?: string
+  thinking?: string
+  lens?: string
+}
+
+export interface BrunchChromeBuildState {
+  version?: string
+  dev?: string
+}
+
+export interface BrunchChromeFooterTelemetry {
+  gitBranch?: string | null
+  statuses?: ReadonlyMap<string, string>
+}
+
+export interface BrunchChromeState extends WorkspaceSessionChromeState {
+  session: {
+    id: string
+    label?: string
+  }
+  runtime?: BrunchChromeRuntimeState
+  build?: BrunchChromeBuildState
+  contextUsage?: BrunchChromeContextUsage
+  worker?: {
+    stage?: BrunchChromeStage
+    status?: BrunchChromeWorkerStatus
+  }
+  coherence?: BrunchChromeCoherenceVerdict
+}
+
+export type BrunchChromeUi = Pick<ExtensionUIContext, "setFooter" | "setHeader" | "setWidget" | "setTitle">
+
+export function formatBrunchChromeHeaderLines(
+  chrome: BrunchChromeState,
+): string[] {
+  return [
+    "brunch",
+    `runtime: ${formatRuntime(chrome)}`,
+    `${formatChromeIdentity(chrome)} · phase: ${chrome.phase}`,
+  ]
+}
+
+export function projectBrunchChromeFooterLines(
+  chrome: BrunchChromeState,
+  telemetry?: BrunchChromeFooterTelemetry,
+  width?: number,
+): string[] {
+  const statuses = sanitizeChromeStatuses(telemetry?.statuses)
+  const branch = telemetry?.gitBranch
+  const identity = `${formatChromeIdentity(chrome)}${
+    branch ? ` · branch: ${branch}` : ""
+  }`
+  const runtime = `runtime: ${formatRuntime(chrome)} · build: ${formatBuild(chrome)}`
+  const context = `context: ${formatContextUsage(chrome.contextUsage)}`
+  return [
+    width === undefined ? runtime : alignChromeColumns(runtime, context, width),
+    ...(width === undefined ? [context] : []),
+    `state: ${chrome.chatMode} · coherence: ${chrome.coherence ?? "unknown"} · worker: ${formatWorker(chrome)}`,
+    identity,
+    statuses.length > 0 ? `status: ${statuses.join(" · ")}` : "",
+  ]
+}
+
+export function formatChromeWidgetLines(chrome: BrunchChromeState): string[] {
+  return [
+    `cwd: ${chrome.cwd}`,
+    `spec: ${formatSpec(chrome)}`,
+    `session: ${formatSession(chrome)}`,
+    `runtime: ${formatRuntime(chrome)}`,
+    `context: ${formatContextUsage(chrome.contextUsage)}`,
+    `chat mode: ${chrome.chatMode}`,
+  ]
+}
+
+function formatChromeIdentity(chrome: BrunchChromeState): string {
+  return `spec: ${formatSpec(chrome)} · session: ${formatSession(chrome)}`
+}
+
+function sanitizeChromeStatuses(
+  statuses: ReadonlyMap<string, string> | undefined,
+): string[] {
+  return [...(statuses ?? new Map())]
+    .filter(
+      ([key, value]) => key !== "brunch.chrome" && value.trim().length > 0,
+    )
+    .map(([, value]) => value.trim())
+}
+
+function alignChromeColumns(
+  left: string,
+  right: string,
+  width: number,
+): string {
+  const available = Math.max(0, width)
+  const gap = Math.max(1, available - visibleWidth(left) - visibleWidth(right))
+  return truncateToWidth(`${left}${" ".repeat(gap)}${right}`, available)
+}
+
+export function chromeStateForWorkspace(
+  workspace: WorkspaceSessionReadyState,
+): BrunchChromeState {
+  return {
+    ...workspace.chrome,
+    session: {
+      id: workspace.session.id,
+      label: workspace.session.id,
+    },
+  }
+}
+
+export function renderBrunchChrome(
+  ui: BrunchChromeUi,
+  chrome: BrunchChromeState,
+): void {
+  ui.setHeader(() => ({
+    render: () => formatBrunchChromeHeaderLines(chrome),
+    invalidate: () => {},
+  }))
+  ui.setFooter((tui, _theme, footerData) => {
+    const unsubscribe = footerData.onBranchChange(() => tui.requestRender())
+    return {
+      render: (width: number) =>
+        projectBrunchChromeFooterLines(
+          chrome,
+          {
+            gitBranch: footerData.getGitBranch(),
+            statuses: footerData.getExtensionStatuses(),
+          },
+          width,
+        ),
+      invalidate: () => {},
+      dispose: unsubscribe,
+    }
+  })
+  ui.setWidget("brunch.chrome", formatChromeWidgetLines(chrome), {
+    placement: "aboveEditor",
+  })
+  ui.setTitle(`brunch — ${chrome.spec?.title ?? chrome.cwd}`)
+}
+
+function formatSpec(chrome: BrunchChromeState): string {
+  return chrome.spec?.title ?? "no spec selected"
+}
+
+function formatSession(chrome: BrunchChromeState): string {
+  return chrome.session.label ?? chrome.session.id
+}
+
+function formatRuntime(chrome: BrunchChromeState): string {
+  const runtime = chrome.runtime
+  if (!runtime) return "not reported"
+  const parts = [
+    runtime.bundle,
+    runtime.role ? `role ${runtime.role}` : undefined,
+    runtime.model,
+    runtime.thinking ? `thinking ${runtime.thinking}` : undefined,
+    runtime.lens ? `lens ${runtime.lens}` : undefined,
+  ].filter((part): part is string => Boolean(part))
+  return parts.length > 0 ? parts.join(" · ") : "not reported"
+}
+
+function formatBuild(chrome: BrunchChromeState): string {
+  const build = chrome.build
+  if (!build) return "not reported"
+  return [build.version, build.dev].filter(Boolean).join(" ") || "not reported"
+}
+
+function formatContextUsage(
+  usage: BrunchChromeContextUsage | undefined,
+): string {
+  if (!usage) return "not reported"
+  const max = Math.max(0, usage.maxTokens)
+  const used = Math.max(0, usage.usedTokens)
+  if (max === 0) return `${used.toLocaleString()} tokens · no limit reported`
+  const ratio = Math.min(1, used / max)
+  const filled = Math.round(ratio * 10)
+  const bar = `${"█".repeat(filled)}${"░".repeat(10 - filled)}`
+  const percent = Math.round(ratio * 100)
+  return `[${bar}] ${used.toLocaleString()}/${max.toLocaleString()} tokens (${percent}%)`
+}
+
+function formatWorker(chrome: BrunchChromeState): string {
+  const worker = chrome.worker
+  if (!worker) return "not reported"
+  return (
+    [worker.stage, worker.status].filter(Boolean).join("/") || "not reported"
+  )
+}
diff --git a/src/pi-extensions/command-policy.ts b/src/pi-extensions/command-policy.ts
new file mode 100644
index 00000000..e2eaff13
--- /dev/null
+++ b/src/pi-extensions/command-policy.ts
@@ -0,0 +1,15 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"
+
+export const BRUNCH_BRANCH_FLOW_BLOCKED_MESSAGE =
+  "Brunch does not support Pi session branches in this POC. Use /new to continue within the selected spec."
+
+export function registerBrunchBranchPolicyHandlers(pi: ExtensionAPI): void {
+  pi.on("session_before_tree", (_event, ctx) => {
+    ctx.ui.notify(BRUNCH_BRANCH_FLOW_BLOCKED_MESSAGE, "warning")
+    return { cancel: true }
+  })
+  pi.on("session_before_fork", (_event, ctx) => {
+    ctx.ui.notify(BRUNCH_BRANCH_FLOW_BLOCKED_MESSAGE, "warning")
+    return { cancel: true }
+  })
+}
diff --git a/src/pi-extensions/mention-autocomplete.test.ts b/src/pi-extensions/mention-autocomplete.test.ts
new file mode 100644
index 00000000..7e1ec0a2
--- /dev/null
+++ b/src/pi-extensions/mention-autocomplete.test.ts
@@ -0,0 +1,143 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent"
+
+import { describe, expect, it } from "vitest"
+
+import {
+  extractHashPrefix,
+  registerBrunchMentionAutocomplete,
+  type GraphMentionSource,
+} from "./mention-autocomplete.js"
+
+describe("Brunch mention autocomplete", () => {
+  it("adds graph mention prompt guidance", async () => {
+    const beforeAgentStart: Array<(
+      event: { systemPrompt: string },
+      ctx: FakeExtensionContext,
+    ) => Promise<unknown> | unknown> = []
+
+    registerBrunchMentionAutocomplete({
+      on: (event: string, handler: never) => {
+        if (event === "before_agent_start") beforeAgentStart.push(handler)
+      },
+    } as never)
+
+    const promptUpdates = await Promise.all(
+      beforeAgentStart.map((handler) =>
+        Promise.resolve(handler({ systemPrompt: "base" }, fakeContext())),
+      ),
+    )
+
+    expect(
+      promptUpdates.some(
+        (update) =>
+          typeof update === "object" &&
+          update !== null &&
+          "systemPrompt" in update &&
+          String(update.systemPrompt).includes("Brunch graph mention handles"),
+      ),
+    ).toBe(true)
+  })
+
+  it("registers graph-code mention autocomplete without fixture tag JSON", async () => {
+    let providerFactory: ((
+      current: FakeAutocompleteProvider,
+    ) => FakeAutocompleteProvider) | undefined
+    const source: GraphMentionSource = {
+      listMentionCandidates: () => [
+        {
+          code: "D12",
+          title: "Command containment",
+          description: "Blocks branchy Pi flows",
+          plane: "design",
+        },
+        { code: "I9", title: "Mention ledger", plane: "intent" },
+      ],
+    }
+
+    registerBrunchMentionAutocomplete(
+      {
+        on: (event: string, handler: (event: never, ctx: never) => unknown) => {
+          if (event === "session_start") {
+            void handler({} as never, {
+              ui: {
+                addAutocompleteProvider: (factory: typeof providerFactory) => {
+                  providerFactory = factory
+                },
+              },
+            } as never)
+          }
+        },
+      } as never,
+      source,
+    )
+
+    const fallback: FakeAutocompleteProvider = {
+      getSuggestions: async () => ({ items: [], prefix: "" }),
+      applyCompletion: (lines) => ({ lines, cursorLine: 0, cursorCol: 0 }),
+      shouldTriggerFileCompletion: () => true,
+    }
+    const provider = providerFactory?.(fallback)
+
+    expect(extractHashPrefix("See #D1", 7)).toBe("#D1")
+    await expect(
+      provider?.getSuggestions(["See #D1"], 0, 7, {} as never),
+    ).resolves.toEqual({
+      prefix: "#D1",
+      items: [
+        {
+          value: "#D12",
+          label: "#D12 Command containment",
+          description: "Blocks branchy Pi flows",
+        },
+      ],
+    })
+    expect(
+      provider?.applyCompletion(
+        ["See #D"],
+        0,
+        6,
+        { value: "#D12", label: "#D12 Command containment" },
+        "#D",
+      ),
+    ).toEqual({ lines: ["See #D12"], cursorLine: 0, cursorCol: 8 })
+  })
+})
+
+function fakeContext(): FakeExtensionContext {
+  return {
+    sessionManager: {
+      getEntries: () => [],
+    } as unknown as FakeExtensionContext["sessionManager"],
+    ui: {} as never,
+  }
+}
+
+type FakeExtensionContext = Pick<ExtensionContext, "sessionManager"> & {
+  ui: unknown
+}
+
+interface FakeAutocompleteItem {
+  value: string
+  label: string
+}
+
+interface FakeAutocompleteProvider {
+  getSuggestions(
+    lines: string[],
+    cursorLine: number,
+    cursorCol: number,
+    options: never,
+  ): Promise<unknown>
+  applyCompletion(
+    lines: string[],
+    cursorLine: number,
+    cursorCol: number,
+    item: FakeAutocompleteItem,
+    prefix: string,
+  ): unknown
+  shouldTriggerFileCompletion(
+    lines: string[],
+    cursorLine: number,
+    cursorCol: number,
+  ): boolean
+}
diff --git a/src/pi-extensions/mention-autocomplete.ts b/src/pi-extensions/mention-autocomplete.ts
new file mode 100644
index 00000000..5c3142a6
--- /dev/null
+++ b/src/pi-extensions/mention-autocomplete.ts
@@ -0,0 +1,155 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent"
+import type {
+  AutocompleteItem,
+  AutocompleteSuggestions,
+} from "@earendil-works/pi-tui"
+
+export interface GraphMentionCandidate {
+  code: string
+  title: string
+  description?: string
+  plane?: "intent" | "oracle" | "design" | "plan"
+}
+
+export interface GraphMentionSource {
+  listMentionCandidates(
+    ctx: ExtensionContext,
+  ): Promise<GraphMentionCandidate[]> | GraphMentionCandidate[]
+}
+
+const EMPTY_GRAPH_MENTION_SOURCE: GraphMentionSource = {
+  listMentionCandidates: () => [],
+}
+
+export const FIXTURE_GRAPH_MENTION_SOURCE: GraphMentionSource = {
+  listMentionCandidates: () => [
+    {
+      code: "D12",
+      title: "Transcript-native structured prompts",
+      description:
+        "Structured elicitation prompt/response entries stay visible in Pi JSONL.",
+      plane: "design",
+    },
+    {
+      code: "I9",
+      title: "Mention ledger uses stable handles",
+      description:
+        "Inserted # handles are transcript text; labels are UI-only.",
+      plane: "intent",
+    },
+    {
+      code: "A10",
+      title: "Persistent TUI chrome seam",
+      description:
+        "Brunch chrome renders through Pi UI primitives without forking Pi.",
+      plane: "intent",
+    },
+  ],
+}
+
+export function registerBrunchMentionAutocomplete(
+  pi: ExtensionAPI,
+  source: GraphMentionSource = EMPTY_GRAPH_MENTION_SOURCE,
+): void {
+  pi.on("before_agent_start", async (event) => ({
+    systemPrompt:
+      event.systemPrompt +
+      `\n\n[Brunch graph references]\n` +
+      `- Tokens like #D12 are Brunch graph mention handles inserted as visible transcript text.\n` +
+      `- Treat the inserted handle as the only durable reference; autocomplete labels/descriptions are UI-only and are not hidden metadata.\n` +
+      `- Resolve deeper graph detail only through Brunch graph lookup/read tools when those are available.`,
+  }))
+
+  pi.on("session_start", async (_event, ctx) => {
+    if (typeof ctx.ui.addAutocompleteProvider !== "function") {
+      return
+    }
+
+    ctx.ui.addAutocompleteProvider((current) => ({
+      async getSuggestions(lines, cursorLine, cursorCol, options) {
+        const line = lines[cursorLine] ?? ""
+        const prefix = extractHashPrefix(line, cursorCol)
+
+        if (prefix === null) {
+          return current.getSuggestions(lines, cursorLine, cursorCol, options)
+        }
+
+        const query = prefix.slice(1).toLowerCase()
+        const candidates = await source.listMentionCandidates(ctx)
+        const items: AutocompleteItem[] = candidates
+          .filter((candidate) => candidateMatches(candidate, query))
+          .map(candidateToAutocompleteItem)
+
+        const result: AutocompleteSuggestions = { items, prefix }
+        return result
+      },
+
+      applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
+        if (!prefix.startsWith("#")) {
+          return current.applyCompletion(
+            lines,
+            cursorLine,
+            cursorCol,
+            item,
+            prefix,
+          )
+        }
+
+        const line = lines[cursorLine] ?? ""
+        const before = line.slice(0, cursorCol)
+        const after = line.slice(cursorCol)
+        const newBefore = before.slice(0, -prefix.length) + item.value
+        return {
+          lines: lines.map((candidateLine, index) =>
+            index === cursorLine ? newBefore + after : candidateLine,
+          ),
+          cursorLine,
+          cursorCol: newBefore.length,
+        }
+      },
+
+      shouldTriggerFileCompletion(lines, cursorLine, cursorCol) {
+        return (
+          current.shouldTriggerFileCompletion?.(lines, cursorLine, cursorCol) ??
+          false
+        )
+      },
+    }))
+  })
+}
+
+export function extractHashPrefix(
+  line: string,
+  cursorCol: number,
+): string | null {
+  const before = line.slice(0, cursorCol)
+  const match = before.match(/(?:^|\s)(#[\w-]*)$/)
+  return match?.[1] ?? null
+}
+
+function candidateMatches(
+  candidate: GraphMentionCandidate,
+  query: string,
+): boolean {
+  if (query.length === 0) {
+    return true
+  }
+  return [candidate.code, candidate.title, candidate.description]
+    .filter((value): value is string => typeof value === "string")
+    .some((value) => value.toLowerCase().includes(query))
+}
+
+function candidateToAutocompleteItem(
+  candidate: GraphMentionCandidate,
+): AutocompleteItem {
+  return {
+    value: `#${candidate.code}`,
+    label: `#${candidate.code} ${candidate.title}`,
+    ...(candidate.description !== undefined
+      ? { description: candidate.description }
+      : {}),
+  }
+}
diff --git a/src/pi-extensions/operational-mode.test.ts b/src/pi-extensions/operational-mode.test.ts
new file mode 100644
index 00000000..e8e1ae38
--- /dev/null
+++ b/src/pi-extensions/operational-mode.test.ts
@@ -0,0 +1,300 @@
+import { mkdtemp } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+
+import { describe, expect, it } from "vitest"
+
+import { SessionManager } from "@earendil-works/pi-coding-agent"
+
+import {
+  BRUNCH_AGENT_RUNTIME_STATE_CUSTOM_TYPE,
+  DEFAULT_BRUNCH_AGENT_STATE,
+  appendBrunchAgentRuntimeInit,
+  appendBrunchAgentRuntimeSwitch,
+  projectBrunchAgentState,
+  registerBrunchOperationalModePolicy,
+  type BrunchAgentState,
+  type BrunchAgentStateEntryData,
+} from "./operational-mode.js"
+
+function runtimeEntry(
+  state: BrunchAgentState,
+  data: Record<string, unknown> = {},
+) {
+  return {
+    type: "custom",
+    customType: BRUNCH_AGENT_RUNTIME_STATE_CUSTOM_TYPE,
+    data: {
+      schemaVersion: 1,
+      reason: "switch",
+      state,
+      source: "user",
+      ...data,
+    },
+  }
+}
+
+class FakeRuntimeStateSessionManager {
+  entries: Array<{
+    type: "custom"
+    customType: string
+    data: BrunchAgentStateEntryData
+  }> = []
+
+  getEntries() {
+    return this.entries
+  }
+
+  appendCustomEntry(customType: string, data: BrunchAgentStateEntryData) {
+    this.entries.push({ type: "custom", customType, data })
+    return `entry-${this.entries.length}`
+  }
+}
+
+describe("Brunch agent runtime-state projection", () => {
+  it("projects the deterministic elicit/elicitor default when no runtime entries exist", () => {
+    expect(projectBrunchAgentState([])).toMatchObject({
+      ...DEFAULT_BRUNCH_AGENT_STATE,
+      operationalModeDefinition: {
+        id: "elicit",
+        defaultRole: "elicitor",
+        toolPolicyId: "elicit-read-only",
+      },
+      agentRoleDefinition: {
+        id: "elicitor",
+        operationalMode: "elicit",
+        defaultStrategy: DEFAULT_BRUNCH_AGENT_STATE.agentStrategy,
+        defaultLens: DEFAULT_BRUNCH_AGENT_STATE.agentLens,
+      },
+    })
+  })
+
+  it("uses the last valid runtime-state snapshot without mutating earlier transcript entries", () => {
+    const first = runtimeEntry(DEFAULT_BRUNCH_AGENT_STATE)
+    const latestState: BrunchAgentState = {
+      schemaVersion: 1,
+      operationalMode: "elicit",
+      agentRole: "elicitor",
+      agentStrategy: "disambiguate-via-examples",
+      agentLens: "disambiguate-via-examples",
+    }
+    const latest = runtimeEntry(latestState)
+
+    expect(projectBrunchAgentState([first, latest])).toMatchObject(latestState)
+    expect(first.data.state).toEqual(DEFAULT_BRUNCH_AGENT_STATE)
+  })
+
+  it("ignores malformed and invalid runtime entries instead of guessing", () => {
+    const valid = runtimeEntry(DEFAULT_BRUNCH_AGENT_STATE)
+    const invalidCombination = runtimeEntry({
+      schemaVersion: 1,
+      operationalMode: "elicit",
+      agentRole: "elicitor",
+      agentStrategy: "not-a-strategy",
+      agentLens: "step-by-step",
+    } as unknown as BrunchAgentState)
+    const malformed = {
+      type: "custom",
+      customType: BRUNCH_AGENT_RUNTIME_STATE_CUSTOM_TYPE,
+      data: { schemaVersion: 1, reason: "switch", source: "user" },
+    }
+
+    expect(
+      projectBrunchAgentState([valid, invalidCombination, malformed]),
+    ).toMatchObject(DEFAULT_BRUNCH_AGENT_STATE)
+  })
+
+  it("applies resolved elicit state to active tools, prompt, and blockers", async () => {
+    const latestState: BrunchAgentState = {
+      schemaVersion: 1,
+      operationalMode: "elicit",
+      agentRole: "elicitor",
+      agentStrategy: "disambiguate-via-examples",
+      agentLens: "disambiguate-via-examples",
+    }
+    const events: Record<string, (event: never, ctx?: never) => unknown> = {}
+    const activeTools: string[][] = []
+
+    registerBrunchOperationalModePolicy({
+      registerTool: (_tool: { name: string }) => {},
+      getAllTools: () =>
+        ["read", "grep", "find", "ls", "bash", "edit", "write"].map((name) => ({
+          name,
+        })),
+      setActiveTools: (tools: string[]) => activeTools.push(tools),
+      on: (event: string, handler: (event: never, ctx?: never) => unknown) => {
+        events[event] = handler
+      },
+    } as never)
+
+    const promptResult = await Promise.resolve(
+      events.before_agent_start?.({ systemPrompt: "base" } as never, {
+        sessionManager: {
+          getEntries: () => [runtimeEntry(latestState)],
+        },
+      } as never),
+    )
+
+    expect(activeTools).toEqual([["read", "grep", "find", "ls"]])
+    expect(promptResult).toMatchObject({
+      systemPrompt: expect.stringContaining("Operational mode: elicit."),
+    })
+    expect(promptResult).toMatchObject({
+      systemPrompt: expect.stringContaining("Agent role: elicitor."),
+    })
+    expect(promptResult).toMatchObject({
+      systemPrompt: expect.stringContaining(
+        "Agent strategy: disambiguate-via-examples.",
+      ),
+    })
+    expect(promptResult).toMatchObject({
+      systemPrompt: expect.stringContaining(
+        "Brunch exposes only read-only tools: read, grep, find, ls.",
+      ),
+    })
+    await expect(
+      Promise.resolve(events.tool_call?.({ toolName: "write" } as never)),
+    ).resolves.toMatchObject({
+      block: true,
+      reason: expect.stringContaining('Brunch tool policy blocks "write"'),
+    })
+    expect(events.user_bash?.({ command: "rm -rf ." } as never)).toMatchObject({
+      result: {
+        exitCode: 1,
+        output: "Brunch tool policy blocks shell commands: rm -rf .",
+      },
+    })
+  })
+
+  it("appends init only when the transcript has no valid runtime state", () => {
+    const manager = new FakeRuntimeStateSessionManager()
+
+    expect(appendBrunchAgentRuntimeInit(manager)).toBe("entry-1")
+    expect(appendBrunchAgentRuntimeInit(manager)).toBeUndefined()
+    expect(manager.entries).toHaveLength(1)
+    expect(manager.entries[0]?.data).toEqual({
+      schemaVersion: 1,
+      reason: "init",
+      state: DEFAULT_BRUNCH_AGENT_STATE,
+      source: "extension",
+    })
+  })
+
+  it("appends validated runtime switches as full state snapshots", () => {
+    const manager = new FakeRuntimeStateSessionManager()
+    appendBrunchAgentRuntimeInit(manager)
+    const latestState: BrunchAgentState = {
+      schemaVersion: 1,
+      operationalMode: "elicit",
+      agentRole: "elicitor",
+      agentStrategy: "disambiguate-via-examples",
+      agentLens: "disambiguate-via-examples",
+    }
+
+    expect(appendBrunchAgentRuntimeSwitch(manager, latestState, "user")).toBe(
+      "entry-2",
+    )
+
+    expect(manager.entries[1]?.data).toEqual({
+      schemaVersion: 1,
+      reason: "switch",
+      state: latestState,
+      previous: DEFAULT_BRUNCH_AGENT_STATE,
+      source: "user",
+    })
+    expect(projectBrunchAgentState(manager.getEntries())).toMatchObject(
+      latestState,
+    )
+  })
+
+  it("rejects invalid runtime switch combinations before appending", () => {
+    const manager = new FakeRuntimeStateSessionManager()
+
+    expect(() =>
+      appendBrunchAgentRuntimeSwitch(manager, {
+        schemaVersion: 1,
+        operationalMode: "elicit",
+        agentRole: "elicitor",
+        agentStrategy: "not-a-strategy",
+        agentLens: "step-by-step",
+      } as unknown as BrunchAgentState),
+    ).toThrow("Invalid BrunchAgentState runtime selection.")
+    expect(manager.entries).toEqual([])
+  })
+
+  it("appends runtime init from the extension session-start hook", async () => {
+    const manager = new FakeRuntimeStateSessionManager()
+    const events: Record<string, (event: never, ctx?: never) => unknown> = {}
+
+    registerBrunchOperationalModePolicy({
+      registerTool: (_tool: { name: string }) => {},
+      getAllTools: () => ["read"].map((name) => ({ name })),
+      setActiveTools: (_tools: string[]) => {},
+      on: (event: string, handler: (event: never, ctx?: never) => unknown) => {
+        events[event] = handler
+      },
+    } as never)
+
+    await events.session_start?.({} as never, {
+      sessionManager: manager,
+    } as never)
+
+    expect(manager.entries[0]?.data.reason).toBe("init")
+  })
+
+  it("reprojects runtime-state snapshots after Pi JSONL reload", async () => {
+    const cwd = await mkdtemp(join(tmpdir(), "brunch-agent-state-"))
+    const sessionDir = join(cwd, ".brunch", "sessions")
+    const manager = SessionManager.create(cwd, sessionDir)
+    const latestState: BrunchAgentState = {
+      schemaVersion: 1,
+      operationalMode: "elicit",
+      agentRole: "elicitor",
+      agentStrategy: "disambiguate-via-examples",
+      agentLens: "disambiguate-via-examples",
+    }
+
+    manager.appendCustomEntry(BRUNCH_AGENT_RUNTIME_STATE_CUSTOM_TYPE, {
+      schemaVersion: 1,
+      reason: "init",
+      state: DEFAULT_BRUNCH_AGENT_STATE,
+      source: "extension",
+    })
+    manager.appendMessage({
+      role: "assistant",
+      content: [{ type: "text", text: "runtime initialized" }],
+      api: "test",
+      provider: "test",
+      model: "test",
+      usage: {
+        input: 0,
+        output: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+        totalTokens: 0,
+        cost: {
+          input: 0,
+          output: 0,
+          cacheRead: 0,
+          cacheWrite: 0,
+          total: 0,
+        },
+      },
+      stopReason: "stop",
+      timestamp: Date.now(),
+    } as never)
+    manager.appendCustomEntry(BRUNCH_AGENT_RUNTIME_STATE_CUSTOM_TYPE, {
+      schemaVersion: 1,
+      reason: "switch",
+      state: latestState,
+      previous: DEFAULT_BRUNCH_AGENT_STATE,
+      source: "user",
+    })
+
+    const reloaded = SessionManager.open(manager.getSessionFile()!, sessionDir)
+
+    expect(projectBrunchAgentState(reloaded.getEntries())).toMatchObject(
+      latestState,
+    )
+  })
+})
diff --git a/src/pi-extensions/operational-mode.ts b/src/pi-extensions/operational-mode.ts
new file mode 100644
index 00000000..87351356
--- /dev/null
+++ b/src/pi-extensions/operational-mode.ts
@@ -0,0 +1,601 @@
+/**
+ * Brunch operational-mode policy.
+ *
+ * The current product runtime has one safe state: `elicit`. In that state the
+ * embedded Pi harness exposes only Brunch's read-only inspection tools and
+ * blocks side-effecting tools (`bash`, `edit`, `write`, etc.) at multiple Pi
+ * seams. Later cards replace this fixed posture with transcript-backed
+ * BrunchAgentState projection, but the policy remains operational-mode owned.
+ */
+
+import { homedir } from "node:os"
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"
+import {
+  createFindTool,
+  createGrepTool,
+  createLsTool,
+  createReadTool,
+} from "@earendil-works/pi-coding-agent"
+import { Text } from "@earendil-works/pi-tui"
+
+const READ_ONLY_TOOLS = [
+  "read",
+  "grep",
+  "find",
+  "ls",
+  "present_alternatives",
+] as const
+type ReadOnlyToolName = typeof READ_ONLY_TOOLS[number]
+
+export const BRUNCH_AGENT_RUNTIME_STATE_CUSTOM_TYPE =
+  "brunch.agent_runtime_state"
+
+export type OperationalModeId = "elicit"
+export type AgentRoleId = "elicitor"
+export type AgentStrategyId = "step-by-step" | "disambiguate-via-examples"
+export type AgentLensId = AgentStrategyId
+export type ToolPolicyId = "elicit-read-only"
+export type PromptPackId = "brunch-base" | "elicit" | "elicitor"
+export type ModelPreference = "default"
+export type ThinkingLevel = "low" | "medium" | "high"
+
+export interface BrunchAgentState {
+  schemaVersion: 1
+  operationalMode: OperationalModeId
+  agentRole: AgentRoleId
+  agentStrategy: AgentStrategyId
+  agentLens: AgentLensId | null
+}
+
+export interface OperationalModeDefinition {
+  id: OperationalModeId
+  defaultRole: AgentRoleId
+  allowedRoles: readonly AgentRoleId[]
+  toolPolicyId: ToolPolicyId
+  promptPackIds: readonly PromptPackId[]
+}
+
+export interface AgentRoleDefinition {
+  id: AgentRoleId
+  operationalMode: OperationalModeId
+  defaultStrategy: AgentStrategyId
+  allowedStrategies: readonly AgentStrategyId[]
+  defaultLens: AgentLensId | null
+  allowedLenses: readonly AgentLensId[]
+  promptPackIds: readonly PromptPackId[]
+  modelPreference?: ModelPreference
+  thinkingLevel?: ThinkingLevel
+}
+
+export interface ResolvedBrunchAgentState extends BrunchAgentState {
+  operationalModeDefinition: OperationalModeDefinition
+  agentRoleDefinition: AgentRoleDefinition
+}
+
+export interface BrunchAgentStateEntryData {
+  schemaVersion: 1
+  reason: "init" | "switch"
+  state: BrunchAgentState
+  previous?: BrunchAgentState
+  source: "system" | "user" | "agent" | "extension"
+}
+
+export const DEFAULT_BRUNCH_AGENT_STATE: BrunchAgentState = {
+  schemaVersion: 1,
+  operationalMode: "elicit",
+  agentRole: "elicitor",
+  agentStrategy: "step-by-step",
+  agentLens: "step-by-step",
+}
+
+export const OPERATIONAL_MODE_DEFINITIONS: Record<OperationalModeId, OperationalModeDefinition> =
+  {
+    elicit: {
+      id: "elicit",
+      defaultRole: "elicitor",
+      allowedRoles: ["elicitor"],
+      toolPolicyId: "elicit-read-only",
+      promptPackIds: ["brunch-base", "elicit"],
+    },
+  }
+
+export const AGENT_ROLE_DEFINITIONS: Record<AgentRoleId, AgentRoleDefinition> =
+  {
+    elicitor: {
+      id: "elicitor",
+      operationalMode: "elicit",
+      defaultStrategy: "step-by-step",
+      allowedStrategies: ["step-by-step", "disambiguate-via-examples"],
+      defaultLens: "step-by-step",
+      allowedLenses: ["step-by-step", "disambiguate-via-examples"],
+      promptPackIds: ["elicitor"],
+    },
+  }
+
+interface CustomEntryLike {
+  type?: unknown
+  customType?: unknown
+  data?: unknown
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null
+}
+
+function isOneOf<T extends string>(
+  value: unknown,
+  allowed: readonly T[],
+): value is T {
+  return typeof value === "string" && allowed.includes(value as T)
+}
+
+function parseBrunchAgentState(value: unknown): BrunchAgentState | undefined {
+  if (!isRecord(value)) return undefined
+  const operationalModes = Object.keys(
+    OPERATIONAL_MODE_DEFINITIONS,
+  ) as OperationalModeId[]
+  const agentRoles = Object.keys(AGENT_ROLE_DEFINITIONS) as AgentRoleId[]
+
+  if (value.schemaVersion !== 1) return undefined
+  if (!isOneOf(value.operationalMode, operationalModes)) return undefined
+  if (!isOneOf(value.agentRole, agentRoles)) return undefined
+
+  const mode = OPERATIONAL_MODE_DEFINITIONS[value.operationalMode]
+  const role = AGENT_ROLE_DEFINITIONS[value.agentRole]
+  if (!mode.allowedRoles.includes(value.agentRole)) return undefined
+  if (role.operationalMode !== value.operationalMode) return undefined
+  if (!isOneOf(value.agentStrategy, role.allowedStrategies)) return undefined
+  if (
+    value.agentLens !== null &&
+    !isOneOf(value.agentLens, role.allowedLenses)
+  ) {
+    return undefined
+  }
+
+  return {
+    schemaVersion: 1,
+    operationalMode: value.operationalMode,
+    agentRole: value.agentRole,
+    agentStrategy: value.agentStrategy,
+    agentLens: value.agentLens,
+  }
+}
+
+function parseBrunchAgentStateEntryData(
+  value: unknown,
+): BrunchAgentStateEntryData | undefined {
+  if (!isRecord(value)) return undefined
+  if (value.schemaVersion !== 1) return undefined
+  if (value.reason !== "init" && value.reason !== "switch") return undefined
+  if (
+    value.source !== "system" &&
+    value.source !== "user" &&
+    value.source !== "agent" &&
+    value.source !== "extension"
+  ) {
+    return undefined
+  }
+  const state = parseBrunchAgentState(value.state)
+  if (!state) return undefined
+  const previous =
+    value.previous === undefined
+      ? undefined
+      : parseBrunchAgentState(value.previous)
+  if (value.previous !== undefined && !previous) return undefined
+
+  return {
+    schemaVersion: 1,
+    reason: value.reason,
+    state,
+    ...(previous ? { previous } : {}),
+    source: value.source,
+  }
+}
+
+function resolveBrunchAgentState(
+  state: BrunchAgentState,
+): ResolvedBrunchAgentState {
+  return {
+    ...state,
+    operationalModeDefinition:
+      OPERATIONAL_MODE_DEFINITIONS[state.operationalMode],
+    agentRoleDefinition: AGENT_ROLE_DEFINITIONS[state.agentRole],
+  }
+}
+
+function latestValidBrunchAgentStateEntryData(
+  entries: readonly CustomEntryLike[],
+): BrunchAgentStateEntryData | undefined {
+  let latest: BrunchAgentStateEntryData | undefined
+
+  for (const entry of entries) {
+    if (
+      entry.type !== "custom" ||
+      entry.customType !== BRUNCH_AGENT_RUNTIME_STATE_CUSTOM_TYPE
+    ) {
+      continue
+    }
+    const data = parseBrunchAgentStateEntryData(entry.data)
+    if (data) latest = data
+  }
+
+  return latest
+}
+
+export function projectBrunchAgentState(
+  entries: readonly CustomEntryLike[],
+): ResolvedBrunchAgentState {
+  return resolveBrunchAgentState(
+    latestValidBrunchAgentStateEntryData(entries)?.state ??
+      DEFAULT_BRUNCH_AGENT_STATE,
+  )
+}
+
+export interface BrunchAgentStateEntrySessionManager {
+  getEntries(): readonly CustomEntryLike[]
+  appendCustomEntry(customType: string, data: BrunchAgentStateEntryData): string
+}
+
+function requireValidBrunchAgentState(
+  state: BrunchAgentState,
+): BrunchAgentState {
+  const valid = parseBrunchAgentState(state)
+  if (!valid) {
+    throw new Error("Invalid BrunchAgentState runtime selection.")
+  }
+  return valid
+}
+
+export function appendBrunchAgentRuntimeInit(
+  sessionManager: BrunchAgentStateEntrySessionManager,
+  source: BrunchAgentStateEntryData["source"] = "extension",
+): string | undefined {
+  if (latestValidBrunchAgentStateEntryData(sessionManager.getEntries())) {
+    return undefined
+  }
+
+  return sessionManager.appendCustomEntry(
+    BRUNCH_AGENT_RUNTIME_STATE_CUSTOM_TYPE,
+    {
+      schemaVersion: 1,
+      reason: "init",
+      state: DEFAULT_BRUNCH_AGENT_STATE,
+      source,
+    },
+  )
+}
+
+export function appendBrunchAgentRuntimeSwitch(
+  sessionManager: BrunchAgentStateEntrySessionManager,
+  state: BrunchAgentState,
+  source: BrunchAgentStateEntryData["source"] = "user",
+): string {
+  const validState = requireValidBrunchAgentState(state)
+  const previous = projectBrunchAgentState(sessionManager.getEntries())
+
+  return sessionManager.appendCustomEntry(
+    BRUNCH_AGENT_RUNTIME_STATE_CUSTOM_TYPE,
+    {
+      schemaVersion: 1,
+      reason: "switch",
+      state: validState,
+      previous: {
+        schemaVersion: previous.schemaVersion,
+        operationalMode: previous.operationalMode,
+        agentRole: previous.agentRole,
+        agentStrategy: previous.agentStrategy,
+        agentLens: previous.agentLens,
+      },
+      source,
+    },
+  )
+}
+
+function shortenPath(path: string): string {
+  const home = homedir()
+  if (path.startsWith(home)) return `~${path.slice(home.length)}`
+  return path
+}
+
+function availableReadOnlyToolNames(pi: ExtensionAPI): ReadOnlyToolName[] {
+  const allToolNames = new Set(pi.getAllTools().map((tool) => tool.name))
+  return READ_ONLY_TOOLS.filter((name) => allToolNames.has(name))
+}
+
+interface SessionManagerLike {
+  getEntries(): readonly CustomEntryLike[]
+}
+
+function projectBrunchAgentStateFromSessionManager(
+  sessionManager: SessionManagerLike | undefined,
+): ResolvedBrunchAgentState {
+  return projectBrunchAgentState(sessionManager?.getEntries() ?? [])
+}
+
+function supportsBrunchAgentStateEntries(
+  sessionManager: SessionManagerLike | undefined,
+): sessionManager is BrunchAgentStateEntrySessionManager {
+  return (
+    sessionManager !== undefined &&
+    typeof (sessionManager as Partial<BrunchAgentStateEntrySessionManager>)
+      .appendCustomEntry === "function"
+  )
+}
+
+function activeToolNamesForState(
+  pi: ExtensionAPI,
+  state: ResolvedBrunchAgentState,
+): ReadOnlyToolName[] {
+  if (state.operationalModeDefinition.toolPolicyId === "elicit-read-only") {
+    return availableReadOnlyToolNames(pi)
+  }
+  return []
+}
+
+function applyBrunchToolPolicy(
+  pi: ExtensionAPI,
+  state: ResolvedBrunchAgentState,
+): void {
+  pi.setActiveTools(activeToolNamesForState(pi, state))
+}
+
+function composeBrunchAgentStatePrompt(
+  state: ResolvedBrunchAgentState,
+  activeTools: readonly string[],
+): string {
+  const tools = activeTools.join(", ") || "none"
+  const lens = state.agentLens ?? "none"
+
+  return (
+    `\n\n[Brunch agent state]\n` +
+    `- Operational mode: ${state.operationalMode}.\n` +
+    `- Agent role: ${state.agentRole}.\n` +
+    `- Agent strategy: ${state.agentStrategy}.\n` +
+    `- Agent lens: ${lens}.\n` +
+    `- Prompt packs: ${[
+      ...state.operationalModeDefinition.promptPackIds,
+      ...state.agentRoleDefinition.promptPackIds,
+    ].join(", ")}.\n` +
+    `\n[Brunch tool policy]\n` +
+    `- Brunch exposes only read-only tools: ${tools}.\n` +
+    `- Do not attempt to write files, edit code, run shell commands, change git state, install dependencies, start processes, or mutate external systems.\n` +
+    `- If the user asks for a side-effecting action, explain that this Brunch prototype is read-only for now.`
+  )
+}
+
+interface TextLikeContent {
+  type: string
+  text?: string
+}
+
+interface TextToolResultLike {
+  content?: TextLikeContent[]
+}
+
+interface TextContent {
+  type: "text"
+  text: string
+}
+
+function firstText(result: TextToolResultLike): TextContent | undefined {
+  return result.content?.find(
+    (content): content is TextContent =>
+      content.type === "text" && typeof content.text === "string",
+  )
+}
+
+function nonEmptyLineCount(text: string): number {
+  return text
+    .trim()
+    .split("\n")
+    .filter((line) => line.trim().length > 0).length
+}
+
+function emptyResult() {
+  return new Text("", 0, 0)
+}
+
+const toolCache = new Map<string, ReturnType<typeof createReadOnlyTools>>()
+
+function createReadOnlyTools(cwd: string) {
+  return {
+    read: createReadTool(cwd),
+    grep: createGrepTool(cwd),
+    find: createFindTool(cwd),
+    ls: createLsTool(cwd),
+  }
+}
+
+function getReadOnlyTools(cwd: string) {
+  let tools = toolCache.get(cwd)
+  if (!tools) {
+    tools = createReadOnlyTools(cwd)
+    toolCache.set(cwd, tools)
+  }
+  return tools
+}
+
+function supportsOperationalModePolicy(pi: ExtensionAPI): boolean {
+  const candidate = pi as Partial<ExtensionAPI>
+  return (
+    typeof candidate.registerTool === "function" &&
+    typeof candidate.getAllTools === "function" &&
+    typeof candidate.setActiveTools === "function"
+  )
+}
+
+export function registerBrunchOperationalModePolicy(pi: ExtensionAPI) {
+  if (!supportsOperationalModePolicy(pi)) {
+    return
+  }
+
+  pi.registerTool({
+    ...getReadOnlyTools(process.cwd()).read,
+    label: "read",
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      return getReadOnlyTools(ctx.cwd).read.execute(
+        toolCallId,
+        params,
+        signal,
+        onUpdate,
+      )
+    },
+    renderCall(args, theme) {
+      const path = shortenPath(args.path || "")
+      const range =
+        args.offset !== undefined || args.limit !== undefined
+          ? theme.fg(
+              "muted",
+              `:${args.offset ?? 1}${
+                args.limit !== undefined
+                  ? `-${(args.offset ?? 1) + args.limit - 1}`
+                  : ""
+              }`,
+            )
+          : ""
+      return new Text(
+        `${theme.fg("toolTitle", theme.bold("read"))} ${theme.fg("accent", path || "…")}${range}`,
+        0,
+        0,
+      )
+    },
+    renderResult() {
+      return emptyResult()
+    },
+  })
+
+  pi.registerTool({
+    ...getReadOnlyTools(process.cwd()).grep,
+    label: "grep",
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      return getReadOnlyTools(ctx.cwd).grep.execute(
+        toolCallId,
+        params,
+        signal,
+        onUpdate,
+      )
+    },
+    renderCall(args, theme) {
+      const path = shortenPath(args.path || ".")
+      const glob = args.glob ? theme.fg("muted", ` ${args.glob}`) : ""
+      return new Text(
+        `${theme.fg("toolTitle", theme.bold("grep"))} ${theme.fg("accent", `/${args.pattern || "…"}/`)} ${theme.fg("muted", path)}${glob}`,
+        0,
+        0,
+      )
+    },
+    renderResult(result, { expanded }, theme) {
+      const text = firstText(result)?.text ?? ""
+      if (expanded && text.trim().length > 0) {
+        return new Text(`\n${theme.fg("toolOutput", text.trim())}`, 0, 0)
+      }
+      const count = nonEmptyLineCount(text)
+      return count > 0
+        ? new Text(theme.fg("muted", `→ ${count} matches`), 0, 0)
+        : emptyResult()
+    },
+  })
+
+  pi.registerTool({
+    ...getReadOnlyTools(process.cwd()).find,
+    label: "find",
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      return getReadOnlyTools(ctx.cwd).find.execute(
+        toolCallId,
+        params,
+        signal,
+        onUpdate,
+      )
+    },
+    renderCall(args, theme) {
+      const path = shortenPath(args.path || ".")
+      return new Text(
+        `${theme.fg("toolTitle", theme.bold("find"))} ${theme.fg("accent", args.pattern || "…")} ${theme.fg("muted", path)}`,
+        0,
+        0,
+      )
+    },
+    renderResult(result, { expanded }, theme) {
+      const text = firstText(result)?.text ?? ""
+      if (expanded && text.trim().length > 0) {
+        return new Text(`\n${theme.fg("toolOutput", text.trim())}`, 0, 0)
+      }
+      const count = nonEmptyLineCount(text)
+      return count > 0
+        ? new Text(theme.fg("muted", `→ ${count} files`), 0, 0)
+        : emptyResult()
+    },
+  })
+
+  pi.registerTool({
+    ...getReadOnlyTools(process.cwd()).ls,
+    label: "ls",
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      return getReadOnlyTools(ctx.cwd).ls.execute(
+        toolCallId,
+        params,
+        signal,
+        onUpdate,
+      )
+    },
+    renderCall(args, theme) {
+      const path = shortenPath(args.path || ".")
+      return new Text(
+        `${theme.fg("toolTitle", theme.bold("ls"))} ${theme.fg("accent", path)}`,
+        0,
+        0,
+      )
+    },
+    renderResult(result, { expanded }, theme) {
+      const text = firstText(result)?.text ?? ""
+      if (expanded && text.trim().length > 0) {
+        return new Text(`\n${theme.fg("toolOutput", text.trim())}`, 0, 0)
+      }
+      const count = nonEmptyLineCount(text)
+      return count > 0
+        ? new Text(theme.fg("muted", `→ ${count} entries`), 0, 0)
+        : emptyResult()
+    },
+  })
+
+  pi.on("session_start", async (_event, ctx) => {
+    if (supportsBrunchAgentStateEntries(ctx?.sessionManager)) {
+      appendBrunchAgentRuntimeInit(ctx.sessionManager)
+    }
+    const state = projectBrunchAgentStateFromSessionManager(ctx?.sessionManager)
+    applyBrunchToolPolicy(pi, state)
+  })
+
+  pi.on("before_agent_start", async (event, ctx) => {
+    const state = projectBrunchAgentStateFromSessionManager(ctx?.sessionManager)
+    const activeTools = activeToolNamesForState(pi, state)
+    applyBrunchToolPolicy(pi, state)
+
+    return {
+      systemPrompt:
+        event.systemPrompt + composeBrunchAgentStatePrompt(state, activeTools),
+    }
+  })
+
+  pi.on("tool_call", async (event) => {
+    const allowedToolNames = new Set(availableReadOnlyToolNames(pi))
+    if (allowedToolNames.has(event.toolName as ReadOnlyToolName)) return
+
+    return {
+      block: true,
+      reason:
+        `Brunch tool policy blocks "${event.toolName}". ` +
+        `Allowed tools: ${Array.from(allowedToolNames).join(", ") || "none"}.`,
+    }
+  })
+
+  pi.on("user_bash", (event) => ({
+    result: {
+      output: `Brunch tool policy blocks shell commands: ${event.command}`,
+      exitCode: 1,
+      cancelled: false,
+      truncated: false,
+    },
+  }))
+}
diff --git a/src/pi-extensions/session-lifecycle.ts b/src/pi-extensions/session-lifecycle.ts
new file mode 100644
index 00000000..4e49f8c1
--- /dev/null
+++ b/src/pi-extensions/session-lifecycle.ts
@@ -0,0 +1,35 @@
+import {
+  SessionManager,
+  type ExtensionAPI,
+} from "@earendil-works/pi-coding-agent"
+
+export type BrunchSessionBoundaryHandler = (
+  sessionManager: SessionManager,
+) => Promise<void> | void
+
+export async function bindBrunchSessionBoundary(
+  sessionManager: SessionManager,
+  onSessionBoundary?: BrunchSessionBoundaryHandler,
+): Promise<void> {
+  await onSessionBoundary?.(sessionManager)
+}
+
+export function registerBrunchSessionBoundaryRefreshHandlers(
+  pi: ExtensionAPI,
+  onSessionBoundary?: BrunchSessionBoundaryHandler,
+): void {
+  pi.on("before_agent_start", async (_event, ctx) => {
+    await bindBrunchSessionBoundary(
+      ctx.sessionManager as SessionManager,
+      onSessionBoundary,
+    )
+  })
+  pi.on("message_start", async (event, ctx) => {
+    if (event.message.role === "assistant") {
+      await bindBrunchSessionBoundary(
+        ctx.sessionManager as SessionManager,
+        onSessionBoundary,
+      )
+    }
+  })
+}
diff --git a/src/pi-extensions/structured-question.test.ts b/src/pi-extensions/structured-question.test.ts
new file mode 100644
index 00000000..7d32501b
--- /dev/null
+++ b/src/pi-extensions/structured-question.test.ts
@@ -0,0 +1,319 @@
+import { describe, expect, it } from "vitest"
+
+import {
+  STRUCTURED_QUESTION_TOOL,
+  answerStructuredQuestionWithTui,
+  buildStructuredQuestionEditorPrefill,
+  createStructuredQuestionTuiComponent,
+  parseStructuredQuestionEditorResponse,
+  registerBrunchStructuredQuestion,
+  structuredQuestionResultFromEditor,
+  type StructuredQuestionTuiResponse,
+} from "./structured-question.js"
+import type { StructuredQuestionParams } from "../structured-question.js"
+
+interface EditorOptionForTest {
+  id: string
+  label: string
+}
+
+interface EditorPayloadForTest {
+  schema: string
+  schemaVersion: number
+  mode: string
+  prompt: string
+  instructions: string[]
+  params: { options: EditorOptionForTest[] }
+  response: { status: string }
+}
+
+describe("Brunch structured-question TUI adapter", () => {
+  it("registers a structured-question tool", () => {
+    const tools: Array<{ name: string }> = []
+
+    registerBrunchStructuredQuestion({
+      registerTool: (tool: { name: string }) => tools.push({ name: tool.name }),
+    } as never)
+
+    expect(tools).toEqual([{ name: STRUCTURED_QUESTION_TOOL }])
+  })
+
+  it("returns unavailable details when rich UI is missing", async () => {
+    const result = await answerStructuredQuestionWithTui(textParams(), {
+      hasUI: false,
+      ui: {} as never,
+    })
+
+    expect(result.details).toMatchObject({
+      status: "unavailable",
+      transport: { surface: "headless" },
+      answers: [],
+    })
+    expect(result.content[0]?.text).toContain("unavailable")
+  })
+
+  it("uses ctx.ui.custom and the shared result builder for text answers", async () => {
+    const result = await answerStructuredQuestionWithTui(
+      textParams(),
+      fakeContext({
+        status: "answered",
+        answers: [
+          { questionId: "q-text", mode: "text", value: "A typed answer" },
+        ],
+      }),
+    )
+
+    expect(result.details).toMatchObject({
+      status: "answered",
+      mode: "text",
+      answers: [{ value: "A typed answer" }],
+      transport: { surface: "tui-custom" },
+    })
+    expect(result.content[0]?.text).toBe("Say something: A typed answer")
+  })
+
+  it("uses ctx.ui.custom and the shared result builder for single and multi select answers", async () => {
+    const single = await answerStructuredQuestionWithTui(
+      singleParams(),
+      fakeContext({
+        status: "answered",
+        answers: [
+          {
+            questionId: "q-single",
+            mode: "singleSelect",
+            selectedOption: { id: "b", label: "Beta" },
+          },
+        ],
+      }),
+    )
+    const multi = await answerStructuredQuestionWithTui(
+      multiParams(),
+      fakeContext({
+        status: "answered",
+        answers: [
+          {
+            questionId: "q-multi",
+            mode: "multiSelect",
+            selectedOptions: [
+              { id: "a", label: "Alpha" },
+              { id: "b", label: "Beta" },
+            ],
+          },
+        ],
+      }),
+    )
+
+    expect(single.details.answers[0]).toMatchObject({
+      selectedOption: { id: "b", label: "Beta" },
+    })
+    expect(multi.details.answers[0]).toMatchObject({
+      selectedOptions: [
+        { id: "a", label: "Alpha" },
+        { id: "b", label: "Beta" },
+      ],
+    })
+  })
+
+  it("builds schema-tagged JSON editor prefill for raw RPC fallback", () => {
+    const prefill = JSON.parse(
+      buildStructuredQuestionEditorPrefill(singleParams()),
+    ) as EditorPayloadForTest
+
+    expect(prefill).toMatchObject({
+      schema: "brunch.structured_question.editor",
+      schemaVersion: 1,
+      mode: "singleSelect",
+      prompt: "Pick one",
+      response: { status: "skipped" },
+    })
+    expect(prefill.instructions.join("\n")).toContain("response.answers")
+    expect(prefill.params.options).toEqual([
+      { id: "a", label: "Alpha" },
+      { id: "b", label: "Beta" },
+    ])
+  })
+
+  it("parses valid edited JSON into the same result-details shape as TUI", async () => {
+    const edited = JSON.parse(
+      buildStructuredQuestionEditorPrefill(singleParams()),
+    ) as Record<string, unknown>
+    edited.response = {
+      status: "answered",
+      answers: [
+        {
+          questionId: "q-single",
+          mode: "singleSelect",
+          selectedOption: { id: "b", label: "Beta" },
+        },
+      ],
+    }
+
+    const result = structuredQuestionResultFromEditor(
+      singleParams(),
+      JSON.stringify(edited),
+    )
+
+    expect(
+      parseStructuredQuestionEditorResponse(JSON.stringify(edited)),
+    ).toEqual(edited.response)
+    expect(result.details).toMatchObject({
+      status: "answered",
+      mode: "singleSelect",
+      answers: [
+        {
+          questionId: "q-single",
+          selectedOption: { id: "b", label: "Beta" },
+        },
+      ],
+      transport: { surface: "rpc-editor" },
+    })
+  })
+
+  it("fails malformed or schema-invalid edited JSON deterministically", () => {
+    expect(parseStructuredQuestionEditorResponse("not json")).toBeNull()
+
+    const invalid = JSON.parse(
+      buildStructuredQuestionEditorPrefill(textParams()),
+    ) as Record<string, unknown>
+    invalid.response = { status: "answered", answers: [{ mode: "text" }] }
+
+    const result = structuredQuestionResultFromEditor(
+      textParams(),
+      JSON.stringify(invalid),
+    )
+
+    expect(result.details).toMatchObject({
+      status: "unavailable",
+      transport: { surface: "rpc-editor" },
+    })
+    expect(result.content[0]?.text).toContain("invalid JSON")
+  })
+
+  it("uses ctx.ui.editor when custom UI is unavailable", async () => {
+    const edited = JSON.parse(
+      buildStructuredQuestionEditorPrefill(textParams()),
+    ) as Record<string, unknown>
+    edited.response = {
+      status: "answered",
+      answers: [{ questionId: "q-text", mode: "text", value: "RPC answer" }],
+    }
+
+    const result = await answerStructuredQuestionWithTui(textParams(), {
+      hasUI: true,
+      ui: {
+        editor: async () => JSON.stringify(edited),
+      } as never,
+    })
+
+    expect(result.details).toMatchObject({
+      status: "answered",
+      transport: { surface: "rpc-editor" },
+      answers: [{ value: "RPC answer" }],
+    })
+  })
+
+  it("keeps required empty text answers in the input-replacing component", () => {
+    const decisions: StructuredQuestionTuiResponse[] = []
+    const component = createStructuredQuestionTuiComponent(
+      textParams(),
+      (response) => decisions.push(response),
+    )
+
+    component.handleInput?.("\r")
+    expect(decisions).toEqual([])
+
+    for (const char of "Done") component.handleInput?.(char)
+    component.handleInput?.("\r")
+
+    expect(decisions).toEqual([
+      {
+        status: "answered",
+        answers: [{ questionId: "q-text", mode: "text", value: "Done" }],
+      },
+    ])
+  })
+
+  it("supports questionnaire answers through the input-replacing component", () => {
+    const decisions: StructuredQuestionTuiResponse[] = []
+    const component = createStructuredQuestionTuiComponent(
+      questionnaireParams(),
+      (response) => decisions.push(response),
+    )
+
+    for (const char of "Domain") component.handleInput?.(char)
+    component.handleInput?.("\r")
+    component.handleInput?.("\r")
+
+    expect(decisions).toEqual([
+      {
+        status: "answered",
+        answers: [
+          { questionId: "q-domain", mode: "text", value: "Domain" },
+          {
+            questionId: "q-risk",
+            mode: "singleSelect",
+            selectedOption: { id: "a", label: "Alpha" },
+          },
+        ],
+      },
+    ])
+  })
+})
+
+function fakeContext(response: StructuredQuestionTuiResponse) {
+  return {
+    hasUI: true,
+    ui: {
+      custom: async () => response,
+    },
+  } as never
+}
+
+function textParams(): StructuredQuestionParams {
+  return {
+    id: "q-text",
+    mode: "text",
+    prompt: "Say something",
+  }
+}
+
+function singleParams(): StructuredQuestionParams {
+  return {
+    id: "q-single",
+    mode: "singleSelect",
+    prompt: "Pick one",
+    options: [
+      { id: "a", label: "Alpha" },
+      { id: "b", label: "Beta" },
+    ],
+  }
+}
+
+function multiParams(): StructuredQuestionParams {
+  return {
+    id: "q-multi",
+    mode: "multiSelect",
+    prompt: "Pick many",
+    options: [
+      { id: "a", label: "Alpha" },
+      { id: "b", label: "Beta" },
+    ],
+  }
+}
+
+function questionnaireParams(): StructuredQuestionParams {
+  return {
+    id: "q-all",
+    mode: "questionnaire",
+    prompt: "Questionnaire",
+    questions: [
+      { id: "q-domain", mode: "text", prompt: "Domain" },
+      {
+        id: "q-risk",
+        mode: "singleSelect",
+        prompt: "Risk",
+        options: [{ id: "a", label: "Alpha" }],
+      },
+    ],
+  }
+}
diff --git a/src/pi-extensions/structured-question.ts b/src/pi-extensions/structured-question.ts
new file mode 100644
index 00000000..4648dc03
--- /dev/null
+++ b/src/pi-extensions/structured-question.ts
@@ -0,0 +1,334 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent"
+import { Key, matchesKey, type Component } from "@earendil-works/pi-tui"
+import { Type } from "typebox"
+import { Value } from "typebox/value"
+
+import {
+  StructuredQuestionAnswerSchema,
+  StructuredQuestionParamsSchema,
+  buildStructuredQuestionResult,
+  type StructuredQuestion,
+  type StructuredQuestionAnswer,
+  type StructuredQuestionParams,
+  type StructuredQuestionStatus,
+  type StructuredQuestionToolResult,
+} from "../structured-question.js"
+
+export const STRUCTURED_QUESTION_TOOL = "brunch_structured_question"
+
+export interface StructuredQuestionTuiResponse {
+  status: Exclude<StructuredQuestionStatus, "unavailable">
+  answers?: StructuredQuestionAnswer[]
+}
+
+const StructuredQuestionModeSchema = Type.Union([
+  Type.Literal("text"),
+  Type.Literal("singleSelect"),
+  Type.Literal("multiSelect"),
+  Type.Literal("questionnaire"),
+])
+
+const StructuredQuestionEditorResponseSchema = Type.Object(
+  {
+    status: Type.Union([
+      Type.Literal("answered"),
+      Type.Literal("skipped"),
+      Type.Literal("cancelled"),
+    ]),
+    answers: Type.Optional(Type.Array(StructuredQuestionAnswerSchema)),
+  },
+  { additionalProperties: false },
+)
+
+const StructuredQuestionEditorPayloadSchema = Type.Object(
+  {
+    schema: Type.Literal("brunch.structured_question.editor"),
+    schemaVersion: Type.Literal(1),
+    mode: StructuredQuestionModeSchema,
+    prompt: Type.String(),
+    instructions: Type.Array(Type.String()),
+    params: StructuredQuestionParamsSchema,
+    response: StructuredQuestionEditorResponseSchema,
+  },
+  { additionalProperties: false },
+)
+
+export function registerBrunchStructuredQuestion(pi: ExtensionAPI): void {
+  if (typeof (pi as Partial<ExtensionAPI>).registerTool !== "function") {
+    return
+  }
+  pi.registerTool({
+    name: STRUCTURED_QUESTION_TOOL,
+    label: "Structured question",
+    description:
+      "Ask the user a Brunch structured question and persist a self-contained structured result.",
+    parameters: StructuredQuestionParamsSchema,
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      return answerStructuredQuestionWithTui(params, ctx)
+    },
+  })
+}
+
+export async function answerStructuredQuestionWithTui(
+  params: StructuredQuestionParams,
+  ctx: Pick<ExtensionContext, "hasUI" | "ui">,
+): Promise<StructuredQuestionToolResult> {
+  if (!ctx.hasUI) {
+    return unavailableStructuredQuestionResult(params)
+  }
+
+  if (typeof ctx.ui.custom === "function") {
+    const response = await ctx.ui.custom<StructuredQuestionTuiResponse>(
+      (_tui, _theme, _keybindings, done) =>
+        createStructuredQuestionTuiComponent(params, done),
+    )
+
+    return buildStructuredQuestionResult({
+      params,
+      status: response.status,
+      answers: response.status === "answered" ? (response.answers ?? []) : [],
+      transport: { surface: "tui-custom" },
+    })
+  }
+
+  if (typeof ctx.ui.editor === "function") {
+    const edited = await ctx.ui.editor(
+      "Answer structured question as JSON",
+      buildStructuredQuestionEditorPrefill(params),
+    )
+    return structuredQuestionResultFromEditor(params, edited)
+  }
+
+  return unavailableStructuredQuestionResult(params)
+}
+
+export function buildStructuredQuestionEditorPrefill(
+  params: StructuredQuestionParams,
+): string {
+  return `${JSON.stringify(
+    Value.Parse(StructuredQuestionEditorPayloadSchema, {
+      schema: "brunch.structured_question.editor",
+      schemaVersion: 1,
+      mode: params.mode,
+      prompt: params.prompt,
+      instructions: [
+        "Edit response.status to answered, skipped, or cancelled.",
+        "For answered responses, fill response.answers using the question ids and answer shapes shown by params.",
+        "Do not change schema, schemaVersion, params, prompt, or mode.",
+      ],
+      params,
+      response: { status: "skipped" },
+    }),
+    null,
+    2,
+  )}\n`
+}
+
+export function parseStructuredQuestionEditorResponse(
+  edited: string | undefined,
+): StructuredQuestionTuiResponse | null {
+  if (edited === undefined) return { status: "cancelled" }
+  try {
+    const payload = Value.Parse(
+      StructuredQuestionEditorPayloadSchema,
+      JSON.parse(edited),
+    )
+    return payload.response
+  } catch {
+    return null
+  }
+}
+
+export function structuredQuestionResultFromEditor(
+  params: StructuredQuestionParams,
+  edited: string | undefined,
+): StructuredQuestionToolResult {
+  const response = parseStructuredQuestionEditorResponse(edited)
+  if (!response) {
+    return buildStructuredQuestionResult({
+      params,
+      status: "unavailable",
+      transport: { surface: "rpc-editor" },
+      message:
+        "Structured question editor response was invalid JSON or failed schema validation.",
+    })
+  }
+  return buildStructuredQuestionResult({
+    params,
+    status: response.status,
+    answers: response.status === "answered" ? (response.answers ?? []) : [],
+    transport: { surface: "rpc-editor" },
+  })
+}
+
+function unavailableStructuredQuestionResult(
+  params: StructuredQuestionParams,
+): StructuredQuestionToolResult {
+  return buildStructuredQuestionResult({
+    params,
+    status: "unavailable",
+    transport: { surface: "headless" },
+    message: "Structured question UI is unavailable.",
+  })
+}
+
+export function createStructuredQuestionTuiComponent(
+  params: StructuredQuestionParams,
+  done: (response: StructuredQuestionTuiResponse) => void,
+): Component {
+  return new StructuredQuestionTuiComponent(params, done)
+}
+
+class StructuredQuestionTuiComponent implements Component {
+  readonly #params: StructuredQuestionParams
+  readonly #questions: StructuredQuestion[]
+  readonly #done: (response: StructuredQuestionTuiResponse) => void
+  #questionIndex = 0
+  #optionIndex = 0
+  #text = ""
+  #selectedOptionIds = new Set<string>()
+  #answers: StructuredQuestionAnswer[] = []
+
+  constructor(
+    params: StructuredQuestionParams,
+    done: (response: StructuredQuestionTuiResponse) => void,
+  ) {
+    this.#params = params
+    this.#questions =
+      params.mode === "questionnaire" ? params.questions : [params]
+    this.#done = done
+  }
+
+  handleInput(data: string): void {
+    const question = this.#currentQuestion()
+    if (!question) return
+
+    if (matchesKey(data, Key.escape)) {
+      this.#done({ status: "cancelled" })
+      return
+    }
+
+    if (question.mode === "text") {
+      this.#handleTextInput(data, question)
+      return
+    }
+
+    if (matchesKey(data, Key.up)) {
+      this.#optionIndex = Math.max(0, this.#optionIndex - 1)
+      return
+    }
+    if (matchesKey(data, Key.down)) {
+      this.#optionIndex = Math.min(
+        question.options.length - 1,
+        this.#optionIndex + 1,
+      )
+      return
+    }
+
+    if (question.mode === "multiSelect" && data === " ") {
+      const option = question.options[this.#optionIndex]
+      if (!option) return
+      if (this.#selectedOptionIds.has(option.id)) {
+        this.#selectedOptionIds.delete(option.id)
+      } else {
+        this.#selectedOptionIds.add(option.id)
+      }
+      return
+    }
+
+    if (matchesKey(data, Key.enter)) {
+      if (question.mode === "singleSelect") {
+        const option = question.options[this.#optionIndex]
+        if (!option) return
+        this.#completeAnswer({
+          questionId: question.id,
+          mode: "singleSelect",
+          selectedOption: { id: option.id, label: option.label },
+        })
+        return
+      }
+      const selectedOptions = question.options
+        .filter((option) => this.#selectedOptionIds.has(option.id))
+        .map((option) => ({ id: option.id, label: option.label }))
+      if (selectedOptions.length === 0 && question.required !== false) return
+      this.#completeAnswer({
+        questionId: question.id,
+        mode: "multiSelect",
+        selectedOptions,
+      })
+    }
+  }
+
+  render(_width: number): string[] {
+    const question = this.#currentQuestion()
+    if (!question) return ["Structured question"]
+    const prefix =
+      this.#params.mode === "questionnaire"
+        ? `Question ${this.#questionIndex + 1}/${this.#questions.length}: `
+        : ""
+    const lines = [`${prefix}${question.prompt}`]
+    if (question.mode === "text") {
+      lines.push(`› ${this.#text}`)
+      lines.push("Enter submit • Esc cancel")
+      return lines
+    }
+    for (const [index, option] of question.options.entries()) {
+      const cursor = index === this.#optionIndex ? "›" : " "
+      const checked =
+        question.mode === "multiSelect"
+          ? this.#selectedOptionIds.has(option.id)
+            ? "[x]"
+            : "[ ]"
+          : `${index + 1}.`
+      lines.push(`${cursor} ${checked} ${option.label}`)
+      if (option.description) lines.push(`    ${option.description}`)
+    }
+    lines.push(
+      question.mode === "multiSelect"
+        ? "Space toggle • Enter submit • Esc cancel"
+        : "↑↓ navigate • Enter select • Esc cancel",
+    )
+    return lines
+  }
+
+  invalidate(): void {}
+
+  #handleTextInput(data: string, question: StructuredQuestion): void {
+    if (matchesKey(data, Key.backspace)) {
+      this.#text = this.#text.slice(0, -1)
+      return
+    }
+    if (matchesKey(data, Key.enter)) {
+      const value = this.#text.trim()
+      if (!value && question.required !== false) return
+      this.#completeAnswer({ questionId: question.id, mode: "text", value })
+      return
+    }
+    if (data.length === 1 && data >= " " && data !== "\u007f") {
+      this.#text += data
+    }
+  }
+
+  #completeAnswer(answer: StructuredQuestionAnswer): void {
+    if (this.#params.mode !== "questionnaire") {
+      this.#done({ status: "answered", answers: [answer] })
+      return
+    }
+    this.#answers.push(answer)
+    if (this.#questionIndex < this.#questions.length - 1) {
+      this.#questionIndex += 1
+      this.#optionIndex = 0
+      this.#text = ""
+      this.#selectedOptionIds.clear()
+      return
+    }
+    this.#done({ status: "answered", answers: this.#answers })
+  }
+
+  #currentQuestion(): StructuredQuestion | undefined {
+    return this.#questions[this.#questionIndex]
+  }
+}
diff --git a/src/pi-extensions/subagents/config.json b/src/pi-extensions/subagents/config.json
new file mode 100644
index 00000000..88e47a01
--- /dev/null
+++ b/src/pi-extensions/subagents/config.json
@@ -0,0 +1,5 @@
+{
+  "$comment": "Subagent extension config (D44-L). Reviewable and editable without SPEC churn. Validated through a TypeBox schema when src/pi-extensions/subagents/index.ts lands.",
+  "version": 1,
+  "maxConcurrency": 4
+}
diff --git a/src/pi-extensions/workspace-dialog.ts b/src/pi-extensions/workspace-dialog.ts
new file mode 100644
index 00000000..15e277d4
--- /dev/null
+++ b/src/pi-extensions/workspace-dialog.ts
@@ -0,0 +1,134 @@
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent"
+
+import {
+  type WorkspaceSessionReadyState,
+  type SpecSessionActivationCoordinator,
+  type SpecSessionActivationDecision,
+} from "../workspace-session-coordinator.js"
+import {
+  WORKSPACE_DIALOG_WIDTH,
+  createWorkspaceDialogComponent,
+} from "../pi-components/workspace-dialog/index.js"
+import { chromeStateForWorkspace, renderBrunchChrome } from "./chrome.js"
+
+export const BRUNCH_WORKSPACE_COMMAND = "brunch"
+export const BRUNCH_WORKSPACE_SHORTCUT = "ctrl+shift+b"
+
+export interface BrunchSpecSessionPickerOptions {
+  coordinator: SpecSessionActivationCoordinator
+}
+
+export function registerBrunchWorkspaceDialog(
+  pi: ExtensionAPI,
+  { coordinator }: BrunchSpecSessionPickerOptions,
+): void {
+  pi.registerCommand(BRUNCH_WORKSPACE_COMMAND, {
+    description: "Open the Brunch spec/session picker",
+    handler: async (_args, ctx) => {
+      await runBrunchWorkspaceCommand(ctx, coordinator)
+    },
+  })
+  pi.registerShortcut?.(BRUNCH_WORKSPACE_SHORTCUT, {
+    description: "Open the Brunch spec/session picker",
+    handler: async (ctx) => {
+      ctx.ui.notify(
+        "Use /brunch to switch specs or sessions; Pi shortcut contexts cannot switch sessions yet.",
+        "warning",
+      )
+    },
+  })
+}
+
+export async function runBrunchWorkspaceCommand(
+  ctx: ExtensionCommandContext,
+  coordinator: SpecSessionActivationCoordinator,
+): Promise<void> {
+  await runBrunchWorkspaceAction(ctx, coordinator)
+}
+
+export async function runBrunchWorkspaceAction(
+  ctx: ExtensionCommandContext,
+  coordinator: SpecSessionActivationCoordinator,
+  options: { waitForIdle?: boolean } = {},
+): Promise<void> {
+  if (options.waitForIdle !== false && canWaitForIdle(ctx)) {
+    await ctx.waitForIdle()
+  }
+  const inventory = await coordinator.inspectWorkspace()
+  const decision = await ctx.ui.custom<SpecSessionActivationDecision>(
+    (_tui, theme, _keybindings, done) =>
+      createWorkspaceDialogComponent({
+        inventory,
+        theme,
+        onDecision: done,
+        includeContinue: false,
+      }),
+    {
+      overlay: true,
+      overlayOptions: {
+        anchor: "center",
+        width: WORKSPACE_DIALOG_WIDTH,
+        maxHeight: "90%",
+        margin: 1,
+      },
+    },
+  )
+  const activated = await coordinator.activateWorkspace(decision)
+
+  if (activated.status === "cancelled") {
+    ctx.ui.notify("Spec/session switch cancelled.", "info")
+    return
+  }
+  if (activated.status === "needs_human") {
+    ctx.ui.notify(activated.reason, "warning")
+    return
+  }
+
+  await switchToActivatedWorkspace(ctx, activated)
+}
+
+function canWaitForIdle(
+  ctx: ExtensionCommandContext,
+): ctx is ExtensionCommandContext & { waitForIdle: () => Promise<void> } {
+  return typeof ctx.waitForIdle === "function"
+}
+
+async function switchToActivatedWorkspace(
+  ctx: ExtensionCommandContext,
+  activated: WorkspaceSessionReadyState,
+): Promise<void> {
+  if (typeof ctx.switchSession !== "function") {
+    ctx.ui.notify(
+      "Use /brunch to switch specs or sessions; this Pi context cannot switch sessions.",
+      "warning",
+    )
+    return
+  }
+  const targetFile = activated.session.file
+  if (ctx.sessionManager.getSessionFile() === targetFile) {
+    renderBrunchChrome(ctx.ui, chromeStateForWorkspace(activated))
+    ctx.ui.notify("Already using the selected Brunch spec/session.", "info")
+    return
+  }
+
+  const targetSessionId = activated.session.id
+  const targetSpecTitle = activated.spec.title
+  const targetChrome = chromeStateForWorkspace(activated)
+
+  const result = await ctx.switchSession(targetFile, {
+    withSession: async (replacementCtx) => {
+      renderBrunchChrome(replacementCtx.ui, targetChrome)
+      replacementCtx.ui.notify(
+        `Switched Brunch spec/session to ${targetSpecTitle} (${targetSessionId}).`,
+        "info",
+      )
+    },
+  })
+
+  if (result.cancelled) {
+    ctx.ui.notify("Spec/session switch was cancelled by Pi.", "warning")
+  }
+}
diff --git a/src/project-identity.test.ts b/src/project-identity.test.ts
new file mode 100644
index 00000000..169bdd69
--- /dev/null
+++ b/src/project-identity.test.ts
@@ -0,0 +1,147 @@
+import { mkdtemp, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { afterEach, beforeEach, describe, expect, it } from "vitest"
+
+import { discoverProjectIdentity, slugify } from "./project-identity.js"
+
+describe("slugify", () => {
+  it("lowercases and collapses non-alphanumeric runs to single dashes", () => {
+    expect(slugify("Acme Control Plane")).toBe("acme-control-plane")
+    expect(slugify("Foo___Bar  Baz!!")).toBe("foo-bar-baz")
+  })
+
+  it("strips leading and trailing dashes", () => {
+    expect(slugify("---wrap-around---")).toBe("wrap-around")
+  })
+
+  it("handles scoped npm package names", () => {
+    expect(slugify("@hashintel/brunch")).toBe("hashintel-brunch")
+  })
+
+  it("returns 'project' for inputs with no alphanumerics", () => {
+    expect(slugify("!!!")).toBe("project")
+    expect(slugify("")).toBe("project")
+  })
+})
+
+describe("discoverProjectIdentity", () => {
+  let dir: string
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), "brunch-project-identity-"))
+  })
+
+  afterEach(() => {
+    // Temp dirs are reaped by the OS; leaving them is acceptable for tests.
+  })
+
+  it("prefers package.json over every other signal", async () => {
+    await writeFile(
+      join(dir, "package.json"),
+      JSON.stringify({ name: "@hashintel/brunch" }),
+    )
+    await writeFile(
+      join(dir, "pyproject.toml"),
+      '[project]\nname = "pythonic"\n',
+    )
+    await writeFile(join(dir, "Cargo.toml"), '[package]\nname = "rusty"\n')
+    await writeFile(join(dir, "go.mod"), "module example.com/golang\n")
+
+    const identity = await discoverProjectIdentity(dir)
+
+    expect(identity).toEqual({
+      name: "@hashintel/brunch",
+      slug: "hashintel-brunch",
+      source: "package.json",
+    })
+  })
+
+  it("reads pyproject.toml [project].name when package.json is absent", async () => {
+    await writeFile(
+      join(dir, "pyproject.toml"),
+      '# comment\n[build-system]\nrequires = ["hatch"]\n\n[project]\nname = "snake_case_app"\nversion = "0.1.0"\n',
+    )
+
+    const identity = await discoverProjectIdentity(dir)
+
+    expect(identity).toEqual({
+      name: "snake_case_app",
+      slug: "snake-case-app",
+      source: "pyproject.toml",
+    })
+  })
+
+  it("falls back to [tool.poetry].name in pyproject.toml", async () => {
+    await writeFile(
+      join(dir, "pyproject.toml"),
+      '[tool.poetry]\nname = "poetry-app"\n',
+    )
+
+    const identity = await discoverProjectIdentity(dir)
+
+    expect(identity.name).toBe("poetry-app")
+    expect(identity.source).toBe("pyproject.toml")
+  })
+
+  it("reads Cargo.toml [package].name", async () => {
+    await writeFile(
+      join(dir, "Cargo.toml"),
+      '[package]\nname = "rustacean"\nversion = "0.1.0"\nedition = "2021"\n',
+    )
+
+    const identity = await discoverProjectIdentity(dir)
+
+    expect(identity).toEqual({
+      name: "rustacean",
+      slug: "rustacean",
+      source: "cargo.toml",
+    })
+  })
+
+  it("uses the final segment of the module path in go.mod", async () => {
+    await writeFile(
+      join(dir, "go.mod"),
+      "module github.com/hashintel/widget-service\n\ngo 1.22\n",
+    )
+
+    const identity = await discoverProjectIdentity(dir)
+
+    expect(identity).toEqual({
+      name: "widget-service",
+      slug: "widget-service",
+      source: "go.mod",
+    })
+  })
+
+  it("falls back to the directory basename when no manifest is present", async () => {
+    const identity = await discoverProjectIdentity(dir)
+
+    expect(identity.source).toBe("directory")
+    expect(identity.name).toBe(dir.split("/").pop())
+    expect(identity.slug.length).toBeGreaterThan(0)
+  })
+
+  it("falls back past a malformed package.json to the next signal", async () => {
+    await writeFile(join(dir, "package.json"), "{ this is not json")
+    await writeFile(join(dir, "Cargo.toml"), '[package]\nname = "rusty"\n')
+
+    const identity = await discoverProjectIdentity(dir)
+
+    expect(identity.name).toBe("rusty")
+    expect(identity.source).toBe("cargo.toml")
+  })
+
+  it("ignores package.json with a missing or empty name field", async () => {
+    await writeFile(
+      join(dir, "package.json"),
+      JSON.stringify({ version: "1.0.0" }),
+    )
+    await writeFile(join(dir, "go.mod"), "module example.com/fallback\n")
+
+    const identity = await discoverProjectIdentity(dir)
+
+    expect(identity.name).toBe("fallback")
+    expect(identity.source).toBe("go.mod")
+  })
+})
diff --git a/src/project-identity.ts b/src/project-identity.ts
new file mode 100644
index 00000000..b419ae1d
--- /dev/null
+++ b/src/project-identity.ts
@@ -0,0 +1,164 @@
+import { readFile } from "node:fs/promises"
+import { basename, join } from "node:path"
+
+export type ProjectIdentitySource = "package.json" | "pyproject.toml" | "cargo.toml" | "go.mod" | "directory"
+
+export interface ProjectIdentity {
+  /** Human-facing project name, as written in the source artifact. */
+  name: string
+  /** Stable, filesystem/URL-safe identifier derived from `name`. */
+  slug: string
+  /** Which artifact in `cwd` produced `name`. */
+  source: ProjectIdentitySource
+}
+
+/**
+ * Discover the identity of the project rooted at `cwd`.
+ *
+ * The search is intentionally shallow — only files directly in `cwd` are
+ * consulted, and the directory basename is the final fallback. Brunch treats
+ * the launch directory as the project boundary and does not support monorepo
+ * walking; users working in a monorepo should launch the tool inside the
+ * sub-package they intend to work on.
+ *
+ * Precedence (first hit wins):
+ *   1. package.json   — `name` field
+ *   2. pyproject.toml — `[project].name` or `[tool.poetry].name`
+ *   3. Cargo.toml     — `[package].name`
+ *   4. go.mod         — final segment of the `module` directive
+ *   5. directory basename
+ */
+export async function discoverProjectIdentity(
+  cwd: string,
+): Promise<ProjectIdentity> {
+  const detectors: Array<() => Promise<DetectedName<ProjectIdentitySource> | null>> =
+    [
+      () => readPackageJsonName(cwd),
+      () => readPyprojectName(cwd),
+      () => readCargoTomlName(cwd),
+      () => readGoModName(cwd),
+    ]
+
+  for (const detect of detectors) {
+    const hit = await detect()
+    if (hit)
+      return { name: hit.name, slug: slugify(hit.name), source: hit.source }
+  }
+
+  const name = basename(cwd)
+  return { name, slug: slugify(name), source: "directory" }
+}
+
+/**
+ * Normalize a project name into a stable slug suitable for filenames, URL
+ * path segments, and persistent identifiers.
+ *
+ * - Lowercased.
+ * - Non-alphanumeric runs collapse to a single `-`.
+ * - Leading and trailing `-` trimmed.
+ * - Empty input returns `"project"` so callers always get a non-empty slug.
+ */
+export function slugify(name: string): string {
+  const slug = name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+  return slug.length > 0 ? slug : "project"
+}
+
+async function readFileOrNull(path: string): Promise<string | null> {
+  try {
+    return await readFile(path, "utf8")
+  } catch {
+    return null
+  }
+}
+
+interface DetectedName<S extends ProjectIdentitySource> {
+  name: string
+  source: S
+}
+
+async function readPackageJsonName(
+  cwd: string,
+): Promise<DetectedName<"package.json"> | null> {
+  const raw = await readFileOrNull(join(cwd, "package.json"))
+  if (!raw) return null
+  try {
+    const parsed = JSON.parse(raw) as { name?: unknown }
+    if (typeof parsed.name === "string" && parsed.name.trim().length > 0) {
+      return { name: parsed.name.trim(), source: "package.json" }
+    }
+  } catch {
+    // Malformed package.json — skip this signal rather than throwing.
+  }
+  return null
+}
+
+async function readPyprojectName(
+  cwd: string,
+): Promise<DetectedName<"pyproject.toml"> | null> {
+  const raw = await readFileOrNull(join(cwd, "pyproject.toml"))
+  if (!raw) return null
+  const fromProject = extractTomlNameInTable(raw, "project")
+  if (fromProject) return { name: fromProject, source: "pyproject.toml" }
+  const fromPoetry = extractTomlNameInTable(raw, "tool.poetry")
+  if (fromPoetry) return { name: fromPoetry, source: "pyproject.toml" }
+  return null
+}
+
+async function readCargoTomlName(
+  cwd: string,
+): Promise<DetectedName<"cargo.toml"> | null> {
+  const raw = await readFileOrNull(join(cwd, "Cargo.toml"))
+  if (!raw) return null
+  const name = extractTomlNameInTable(raw, "package")
+  return name ? { name, source: "cargo.toml" } : null
+}
+
+async function readGoModName(
+  cwd: string,
+): Promise<DetectedName<"go.mod"> | null> {
+  const raw = await readFileOrNull(join(cwd, "go.mod"))
+  if (!raw) return null
+  for (const rawLine of raw.split(/\r?\n/)) {
+    const line = rawLine.trim()
+    if (!line.startsWith("module")) continue
+    const match = line.match(/^module\s+(\S+)/)
+    const captured = match?.[1]
+    if (!captured) continue
+    const modulePath = captured.replace(/^["']|["']$/g, "")
+    const tail = modulePath.split("/").filter(Boolean).pop()
+    if (tail && tail.length > 0) {
+      return { name: tail, source: "go.mod" }
+    }
+  }
+  return null
+}
+
+/**
+ * Minimal TOML extraction: find `name = "..."` inside `[tableName]`, stopping
+ * at the next top-level table header. Not a real TOML parser — sufficient for
+ * the well-formed manifests we care about and cheaper than a dependency.
+ */
+function extractTomlNameInTable(
+  content: string,
+  tableName: string,
+): string | null {
+  const lines = content.split(/\r?\n/)
+  const header = `[${tableName}]`
+  let inTable = false
+  for (const rawLine of lines) {
+    const line = rawLine.trim()
+    if (line.startsWith("#") || line.length === 0) continue
+    if (line.startsWith("[") && line.endsWith("]")) {
+      inTable = line === header
+      continue
+    }
+    if (!inTable) continue
+    const match = line.match(/^name\s*=\s*(["'])(.*?)\1/)
+    const captured = match?.[2]
+    if (captured && captured.length > 0) return captured
+  }
+  return null
+}
diff --git a/src/rpc.test.ts b/src/rpc.test.ts
index a59cc4a7..cb14c51f 100644
--- a/src/rpc.test.ts
+++ b/src/rpc.test.ts
@@ -9,36 +9,83 @@ import { SessionManager } from "@earendil-works/pi-coding-agent"
 import { createRpcHandlers, runJsonRpcLineServer } from "./rpc.js"
 import { createSessionBindingData } from "./session-binding.js"
 import { createWorkspaceSessionCoordinator } from "./workspace-session-coordinator.js"
+import { assistantMessage, userMessage } from "./test-helpers.js"
 import type {
-  WorkspaceSessionCoordinator,
+  DefaultWorkspaceCoordinator,
+  WorkspaceActivationState,
+  WorkspaceLaunchInventory,
+  WorkspaceSessionReadyState,
   WorkspaceSessionState,
+  SpecSessionActivationCoordinator,
+  SpecSessionActivationDecision,
 } from "./workspace-session-coordinator.js"
 
 function coordinator(
   state: WorkspaceSessionState = readyState(
     "/tmp/brunch-project/.brunch/sessions/session-1.jsonl",
   ),
-): WorkspaceSessionCoordinator {
+): DefaultWorkspaceCoordinator & SpecSessionActivationCoordinator {
+  const inventory = launchInventory()
   return {
-    async openExisting() {
+    async openDefaultWorkspace() {
       return state
     },
-    async startOrCreate() {
-      throw new Error("not used")
+    async inspectWorkspace() {
+      return inventory
     },
-    async createNewSessionForCurrentSpec() {
-      throw new Error("not used")
+    async activateWorkspace(
+      decision: SpecSessionActivationDecision,
+    ): Promise<WorkspaceActivationState> {
+      if (decision.action === "cancel") return cancelledState()
+      return readyState("/tmp/brunch-project/.brunch/sessions/session-1.jsonl")
     },
-    async bindCurrentSpecToSession() {
-      throw new Error("not used")
-    },
-    async deriveChromeState() {
-      throw new Error("not used")
+  }
+}
+
+function launchInventory(): WorkspaceLaunchInventory {
+  return {
+    cwd: "/tmp/brunch-project",
+    currentSpec: { id: "spec-1", title: "Alpha spec" },
+    currentSessionFile: "/tmp/brunch-project/.brunch/sessions/session-1.jsonl",
+    needsNewSpec: false,
+    specs: [
+      {
+        spec: { id: "spec-1", title: "Alpha spec" },
+        sessions: [
+          {
+            id: "session-1",
+            file: "/tmp/brunch-project/.brunch/sessions/session-1.jsonl",
+            specId: "spec-1",
+            specTitle: "Alpha spec",
+            available: true,
+          },
+        ],
+      },
+    ],
+    unavailableSessions: [
+      {
+        file: "/tmp/missing.jsonl",
+        reason: "missing_header",
+        available: false,
+      },
+    ],
+  }
+}
+
+function cancelledState(): WorkspaceActivationState {
+  return {
+    status: "cancelled",
+    cwd: "/tmp/brunch-project",
+    chrome: {
+      cwd: "/tmp/brunch-project",
+      spec: { id: "spec-1", title: "Alpha spec" },
+      phase: "elicitation",
+      chatMode: "responding-to-elicitation",
     },
   }
 }
 
-function readyState(sessionFile: string): WorkspaceSessionState {
+function readyState(sessionFile: string): WorkspaceSessionReadyState {
   return {
     status: "ready",
     cwd: "/tmp/brunch-project",
@@ -74,8 +121,8 @@ async function createSessionFile(): Promise<string> {
   const cwd = await mkdtemp(join(tmpdir(), "brunch-rpc-session-"))
   const manager = SessionManager.create(cwd, join(cwd, ".brunch/sessions"))
   appendBinding(manager)
-  manager.appendMessage({ role: "assistant", content: "Question" })
-  manager.appendMessage({ role: "user", content: "Answer" })
+  manager.appendMessage(assistantMessage("Question"))
+  manager.appendMessage(userMessage("Answer"))
   return manager.getSessionFile()!
 }
 
@@ -83,11 +130,11 @@ async function createBranchedSessionFile(): Promise<string> {
   const cwd = await mkdtemp(join(tmpdir(), "brunch-rpc-branch-"))
   const manager = SessionManager.create(cwd, join(cwd, ".brunch/sessions"))
   appendBinding(manager)
-  manager.appendMessage({ role: "assistant", content: "Abandoned prompt" })
-  manager.appendMessage({ role: "user", content: "Abandoned answer" })
+  manager.appendMessage(assistantMessage("Abandoned prompt"))
+  manager.appendMessage(userMessage("Abandoned answer"))
   manager.resetLeaf()
-  manager.appendMessage({ role: "assistant", content: "Active prompt" })
-  manager.appendMessage({ role: "user", content: "Active answer" })
+  manager.appendMessage(assistantMessage("Active prompt"))
+  manager.appendMessage(userMessage("Active answer"))
   return manager.getSessionFile()!
 }
 
@@ -129,6 +176,117 @@ function sessionBindingEntry(sessionId = "session-1", specId = "spec-1") {
 }
 
 describe("JSON-RPC handlers", () => {
+  it("serves structured workspace selection state without invoking the TUI picker", async () => {
+    const handlers = createRpcHandlers({
+      coordinator: coordinator(selectSpecState()),
+      cwd: "/tmp/brunch-project",
+    })
+
+    await expect(
+      handlers.handle({
+        jsonrpc: "2.0",
+        id: 20,
+        method: "workspace.selectionState",
+      }),
+    ).resolves.toMatchObject({
+      jsonrpc: "2.0",
+      id: 20,
+      result: {
+        status: "select_spec",
+        requiresSelection: true,
+        cwd: "/tmp/brunch-project",
+        currentSpec: { id: "spec-1", title: "Alpha spec" },
+        currentSessionFile:
+          "/tmp/brunch-project/.brunch/sessions/session-1.jsonl",
+        specs: [{ spec: { id: "spec-1" }, sessions: [{ id: "session-1" }] }],
+        unavailableSessions: [{ reason: "missing_header" }],
+      },
+    })
+  })
+
+  it("activates valid spec/session decisions and returns serializable product snapshots", async () => {
+    const decisions: SpecSessionActivationDecision[] = []
+    const handlers = createRpcHandlers({
+      cwd: "/tmp/brunch-project",
+      coordinator: {
+        ...coordinator(),
+        async activateWorkspace(decision): Promise<WorkspaceActivationState> {
+          decisions.push(decision)
+          return decision.action === "cancel"
+            ? cancelledState()
+            : readyState("/tmp/brunch-project/.brunch/sessions/session-1.jsonl")
+        },
+      },
+    })
+
+    const validDecisions: SpecSessionActivationDecision[] = [
+      { action: "cancel" },
+      { action: "newSpec", title: "New spec" },
+      { action: "newSession", specId: "spec-1" },
+      {
+        action: "continue",
+        specId: "spec-1",
+        sessionFile: "session-1.jsonl",
+      },
+      {
+        action: "openSession",
+        specId: "spec-1",
+        sessionFile: "session-2.jsonl",
+      },
+    ]
+
+    for (const [index, decision] of validDecisions.entries()) {
+      await expect(
+        handlers.handle({
+          jsonrpc: "2.0",
+          id: 21 + index,
+          method: "workspace.activate",
+          params: { decision },
+        }),
+      ).resolves.toMatchObject({
+        jsonrpc: "2.0",
+        id: 21 + index,
+        result:
+          decision.action === "cancel"
+            ? { status: "cancelled", spec: { id: "spec-1" } }
+            : {
+                status: "ready",
+                spec: { id: "spec-1" },
+                session: { id: "session-1" },
+              },
+      })
+      expect(decisions).toHaveLength(index + 1)
+      expect(decisions[index]).toEqual(decision)
+    }
+  })
+
+  it("rejects invalid workspace activation params", async () => {
+    const handlers = createRpcHandlers({
+      coordinator: coordinator(),
+      cwd: "/tmp/brunch-project",
+    })
+
+    await expect(
+      handlers.handle({
+        jsonrpc: "2.0",
+        id: 22,
+        method: "workspace.activate",
+        params: { decision: { action: "openSession", specId: "spec-1" } },
+      }),
+    ).resolves.toMatchObject({
+      jsonrpc: "2.0",
+      id: 22,
+      error: { code: -32602, message: "Invalid params" },
+    })
+  })
+
+  it("keeps RPC initial selection independent from TUI picker imports", async () => {
+    const source = await readFile(new URL("./rpc.ts", import.meta.url), "utf8")
+
+    expect(source).not.toContain("workspace-dialog")
+    expect(source).not.toContain("createWorkspaceDialogComponent")
+  })
+
   it("serves a named workspace snapshot method", async () => {
     const handlers = createRpcHandlers({
       coordinator: coordinator(),
@@ -201,25 +359,19 @@ describe("JSON-RPC handlers", () => {
   it("serves session elicitation exchanges by durable session id without opening the selected workspace session", async () => {
     const cwd = await mkdtemp(join(tmpdir(), "brunch-rpc-explicit-session-"))
     const coordinatorInstance = createWorkspaceSessionCoordinator({ cwd })
-    const first = await coordinatorInstance.startOrCreate({
+    const first = await coordinatorInstance.createSetupSession({
       specTitle: "Explicit spec",
     })
-    first.session.manager.appendMessage({
-      role: "assistant",
-      content: "First question",
-    })
-    first.session.manager.appendMessage({
-      role: "user",
-      content: "First answer",
-    })
-    const second = await coordinatorInstance.createNewSessionForCurrentSpec()
+    first.session.manager.appendMessage(assistantMessage("First question"))
+    first.session.manager.appendMessage(userMessage("First answer"))
+    const second = await coordinatorInstance.createSetupSessionForCurrentSpec()
     if (second.status !== "ready") {
       throw new Error("expected a ready second session")
     }
     const handlers = createRpcHandlers({
       coordinator: {
         ...coordinatorInstance,
-        async openExisting() {
+        async openDefaultWorkspace() {
           throw new Error("explicit reads must not open selected session")
         },
       },
@@ -246,21 +398,17 @@ describe("JSON-RPC handlers", () => {
   it("serves transcript display rows by durable session id without opening the selected workspace session", async () => {
     const cwd = await mkdtemp(join(tmpdir(), "brunch-rpc-display-"))
     const coordinatorInstance = createWorkspaceSessionCoordinator({ cwd })
-    const workspace = await coordinatorInstance.startOrCreate({
+    const workspace = await coordinatorInstance.createSetupSession({
       specTitle: "Display spec",
     })
-    workspace.session.manager.appendMessage({
-      role: "assistant",
-      content: "Display question",
-    })
-    workspace.session.manager.appendMessage({
-      role: "user",
-      content: "Display answer",
-    })
+    workspace.session.manager.appendMessage(
+      assistantMessage("Display question"),
+    )
+    workspace.session.manager.appendMessage(userMessage("Display answer"))
     const handlers = createRpcHandlers({
       coordinator: {
         ...coordinatorInstance,
-        async openExisting() {
+        async openDefaultWorkspace() {
           throw new Error("explicit reads must not open selected session")
         },
       },
@@ -286,17 +434,10 @@ describe("JSON-RPC handlers", () => {
     })
   })
 
-  it("does not parse durable session bindings inside the RPC handler module", async () => {
-    const source = await readFile(new URL("./rpc.ts", import.meta.url), "utf8")
-
-    expect(source).not.toContain("brunch.session_binding")
-    expect(source).not.toContain("customType")
-  })
-
   it("validates explicit session projection against a requested spec id", async () => {
     const cwd = await mkdtemp(join(tmpdir(), "brunch-rpc-explicit-spec-"))
     const coordinatorInstance = createWorkspaceSessionCoordinator({ cwd })
-    const workspace = await coordinatorInstance.startOrCreate({
+    const workspace = await coordinatorInstance.createSetupSession({
       specTitle: "Explicit spec",
     })
     const handlers = createRpcHandlers({
@@ -435,7 +576,7 @@ describe("JSON-RPC handlers", () => {
   it("returns a product-shaped error for unknown explicit sessions", async () => {
     const cwd = await mkdtemp(join(tmpdir(), "brunch-rpc-missing-session-"))
     const coordinatorInstance = createWorkspaceSessionCoordinator({ cwd })
-    await coordinatorInstance.startOrCreate({ specTitle: "Explicit spec" })
+    await coordinatorInstance.createSetupSession({ specTitle: "Explicit spec" })
     const handlers = createRpcHandlers({
       coordinator: coordinatorInstance,
       cwd,
@@ -461,14 +602,14 @@ describe("JSON-RPC handlers", () => {
   it("returns a product-shaped error for non-linear explicit sessions", async () => {
     const cwd = await mkdtemp(join(tmpdir(), "brunch-rpc-explicit-branch-"))
     const coordinatorInstance = createWorkspaceSessionCoordinator({ cwd })
-    const workspace = await coordinatorInstance.startOrCreate({
+    const workspace = await coordinatorInstance.createSetupSession({
       specTitle: "Explicit branch spec",
     })
     const manager = SessionManager.open(workspace.session.file)
-    manager.appendMessage({ role: "assistant", content: "Abandoned prompt" })
-    manager.appendMessage({ role: "user", content: "Abandoned answer" })
+    manager.appendMessage(assistantMessage("Abandoned prompt"))
+    manager.appendMessage(userMessage("Abandoned answer"))
     manager.resetLeaf()
-    manager.appendMessage({ role: "assistant", content: "Active prompt" })
+    manager.appendMessage(assistantMessage("Active prompt"))
     const handlers = createRpcHandlers({
       coordinator: coordinatorInstance,
       cwd,
diff --git a/src/rpc.ts b/src/rpc.ts
index 03c69059..b442c074 100644
--- a/src/rpc.ts
+++ b/src/rpc.ts
@@ -1,6 +1,9 @@
 import { createInterface } from "node:readline/promises"
 import type { Readable, Writable } from "node:stream"
 
+import { Type, type Static } from "typebox"
+import { Value } from "typebox/value"
+
 import {
   readBrunchSessionEnvelope,
   NonLinearTranscriptError,
@@ -25,14 +28,21 @@ import {
   type ExplicitSessionProjectionParams,
   type SessionProjectionTarget,
 } from "./session-projection-reader.js"
-import type { WorkspaceSessionCoordinator } from "./workspace-session-coordinator.js"
+import type {
+  DefaultWorkspaceCoordinator,
+  WorkspaceActivationState,
+  WorkspaceLaunchInventory,
+  WorkspaceSessionState,
+  SpecSessionActivationCoordinator,
+  SpecSessionActivationDecision,
+} from "./workspace-session-coordinator.js"
 
 export interface RpcHandlers {
   handle(request: unknown): Promise<JsonRpcResponse>
 }
 
 export function createRpcHandlers(options: {
-  coordinator: WorkspaceSessionCoordinator
+  coordinator: DefaultWorkspaceCoordinator & SpecSessionActivationCoordinator
   cwd: string
 }): RpcHandlers {
   return {
@@ -47,13 +57,41 @@ export function createRpcHandlers(options: {
         if (request.params !== undefined) {
           return createJsonRpcFailure(requestId, -32602, "Invalid params")
         }
-        const state = await options.coordinator.openExisting()
+        const state = await options.coordinator.openDefaultWorkspace()
         return createJsonRpcSuccess(
           requestId,
           workspaceSnapshotFromState(state),
         )
       }
 
+      if (request.method === "workspace.selectionState") {
+        if (request.params !== undefined) {
+          return createJsonRpcFailure(requestId, -32602, "Invalid params")
+        }
+        const [state, inventory] = await Promise.all([
+          options.coordinator.openDefaultWorkspace(),
+          options.coordinator.inspectWorkspace(),
+        ])
+        return createJsonRpcSuccess(
+          requestId,
+          workspaceSelectionStateFromInventory(state, inventory),
+        )
+      }
+
+      if (request.method === "workspace.activate") {
+        const decision = parseWorkspaceActivationParams(request.params)
+        if (!decision.ok) {
+          return createJsonRpcFailure(requestId, -32602, "Invalid params")
+        }
+        const state = await options.coordinator.activateWorkspace(
+          decision.value,
+        )
+        return createJsonRpcSuccess(
+          requestId,
+          workspaceActivationSnapshotFromState(state),
+        )
+      }
+
       if (request.method === "session.elicitationExchanges") {
         return handleSessionProjection(
           requestId,
@@ -77,11 +115,118 @@ export function createRpcHandlers(options: {
   }
 }
 
+function workspaceSelectionStateFromInventory(
+  state: WorkspaceSessionState,
+  inventory: WorkspaceLaunchInventory,
+): WorkspaceLaunchInventory & {
+  status: WorkspaceSessionState["status"]
+  requiresSelection: boolean
+} {
+  return {
+    ...inventory,
+    status: state.status,
+    requiresSelection: state.status !== "ready",
+  }
+}
+
+function workspaceActivationSnapshotFromState(
+  state: WorkspaceActivationState,
+): ReturnType<typeof workspaceSnapshotFromState> | {
+  status: "cancelled"
+  cwd: string
+  spec: WorkspaceActivationState["chrome"]["spec"]
+  chrome: {
+    phase: "select_spec" | "elicitation"
+    chatMode: "select-spec" | "responding-to-elicitation"
+  }
+} {
+  if (state.status === "cancelled") {
+    return {
+      status: "cancelled",
+      cwd: state.cwd,
+      spec: state.chrome.spec,
+      chrome: {
+        phase: state.chrome.phase,
+        chatMode: state.chrome.chatMode,
+      },
+    }
+  }
+  return workspaceSnapshotFromState(state)
+}
+
+const NonBlankStringSchema = Type.String({ minLength: 1, pattern: "\\S" })
+
+export const SpecSessionActivationDecisionSchema = Type.Union([
+  Type.Object(
+    {
+      action: Type.Literal("continue"),
+      specId: NonBlankStringSchema,
+      sessionFile: NonBlankStringSchema,
+    },
+    { additionalProperties: false },
+  ),
+  Type.Object(
+    {
+      action: Type.Literal("openSession"),
+      specId: NonBlankStringSchema,
+      sessionFile: NonBlankStringSchema,
+    },
+    { additionalProperties: false },
+  ),
+  Type.Object(
+    {
+      action: Type.Literal("newSession"),
+      specId: NonBlankStringSchema,
+    },
+    { additionalProperties: false },
+  ),
+  Type.Object(
+    {
+      action: Type.Literal("newSpec"),
+      title: NonBlankStringSchema,
+    },
+    { additionalProperties: false },
+  ),
+  Type.Object(
+    {
+      action: Type.Literal("cancel"),
+    },
+    { additionalProperties: false },
+  ),
+])
+
+const WorkspaceActivationParamsSchema = Type.Object(
+  {
+    decision: SpecSessionActivationDecisionSchema,
+  },
+  { additionalProperties: false },
+)
+
+type WorkspaceActivationParams = Static<typeof WorkspaceActivationParamsSchema>
+
+type WorkspaceActivationParamsParseResult = {
+  ok: true
+  value: SpecSessionActivationDecision
+} | { ok: false }
+
+function parseWorkspaceActivationParams(
+  value: unknown,
+): WorkspaceActivationParamsParseResult {
+  if (!Value.Check(WorkspaceActivationParamsSchema, value)) {
+    return { ok: false }
+  }
+  const params: WorkspaceActivationParams = Value.Parse(
+    WorkspaceActivationParamsSchema,
+    value,
+  )
+  return { ok: true, value: params.decision }
+}
+
 async function handleSessionProjection<T>(
   requestId: JsonRpcId,
   rawParams: unknown,
   options: {
-    coordinator: WorkspaceSessionCoordinator
+    coordinator: DefaultWorkspaceCoordinator
     cwd: string
   },
   loadProjection: (envelope: BrunchSessionEnvelope) => T,
@@ -93,7 +238,9 @@ async function handleSessionProjection<T>(
 
   const target = params.value
     ? await resolveExplicitSessionProjectionTarget(options.cwd, params.value)
-    : await selectedSessionFile(await options.coordinator.openExisting())
+    : await selectedSessionFile(
+        await options.coordinator.openDefaultWorkspace(),
+      )
   if (!target.ok) {
     return createJsonRpcFailure(requestId, target.code, target.message)
   }
@@ -146,7 +293,7 @@ function parseSessionProjectionParams(
 }
 
 async function selectedSessionFile(
-  state: Awaited<ReturnType<WorkspaceSessionCoordinator["openExisting"]>>,
+  state: WorkspaceSessionState,
 ): Promise<SessionProjectionTarget> {
   if (state.status !== "ready") {
     return { ok: false, code: -32001, message: "No selected Brunch session" }
diff --git a/src/structured-question-rpc-proof.test.ts b/src/structured-question-rpc-proof.test.ts
new file mode 100644
index 00000000..8e3e9be7
--- /dev/null
+++ b/src/structured-question-rpc-proof.test.ts
@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest"
+
+import { runStructuredQuestionRpcProof } from "./structured-question-rpc-proof.js"
+
+describe("structured-question RPC proof", () => {
+  it("round-trips an editor fallback through Pi RPC extension UI", async () => {
+    const proof = await runStructuredQuestionRpcProof()
+
+    expect(proof.editorRequest).toMatchObject({
+      type: "extension_ui_request",
+      method: "editor",
+      title: "Answer structured question as JSON",
+    })
+    expect(JSON.parse(proof.editorRequest.prefill ?? "{}")).toMatchObject({
+      schema: "brunch.structured_question.editor",
+      schemaVersion: 1,
+      response: { status: "skipped" },
+      params: {
+        id: "q-rpc-proof",
+        mode: "text",
+        prompt: "What did the RPC proof answer?",
+      },
+    })
+    expect(proof.details).toMatchObject({
+      schema: "brunch.structured_question.result",
+      schemaVersion: 1,
+      status: "answered",
+      mode: "text",
+      prompt: "What did the RPC proof answer?",
+      questions: [
+        {
+          id: "q-rpc-proof",
+          mode: "text",
+          prompt: "What did the RPC proof answer?",
+        },
+      ],
+      answers: [
+        {
+          questionId: "q-rpc-proof",
+          mode: "text",
+          value: "RPC editor fallback works",
+        },
+      ],
+      transport: { surface: "rpc-editor" },
+    })
+    expect(proof.sessionFile).toContain(".brunch/sessions")
+  }, 20_000)
+})
diff --git a/src/structured-question-rpc-proof.ts b/src/structured-question-rpc-proof.ts
new file mode 100644
index 00000000..edf403d2
--- /dev/null
+++ b/src/structured-question-rpc-proof.ts
@@ -0,0 +1,325 @@
+import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process"
+
+import { Value } from "typebox/value"
+
+import {
+  StructuredQuestionResultDetailsSchema,
+  type StructuredQuestionResultDetails,
+} from "./structured-question.js"
+
+export interface StructuredQuestionRpcProofResult {
+  editorRequest: {
+    type: "extension_ui_request"
+    id: string
+    method: "editor"
+    title?: string
+    prefill?: string
+  }
+  details: StructuredQuestionResultDetails
+  sessionFile: string
+  stdout: unknown[]
+}
+
+interface StructuredQuestionRpcProofOptions {
+  cwd?: string
+  timeoutMs?: number
+}
+
+const PROOF_CUSTOM_TYPE = "brunch.structured_question_rpc_proof_result"
+
+export async function runStructuredQuestionRpcProof(
+  options: StructuredQuestionRpcProofOptions = {},
+): Promise<StructuredQuestionRpcProofResult> {
+  const cwd =
+    options.cwd ?? (await mkdtemp(join(tmpdir(), "brunch-rpc-proof-")))
+  const timeoutMs = options.timeoutMs ?? 10_000
+  const extensionPath = await writeProofExtension(cwd)
+  const sessionDir = join(cwd, ".brunch", "sessions")
+  await mkdir(sessionDir, { recursive: true })
+
+  const child = spawn(
+    process.execPath,
+    [
+      piCliPath(),
+      "--mode",
+      "rpc",
+      "--no-extensions",
+      "--extension",
+      extensionPath,
+      "--session-dir",
+      sessionDir,
+    ],
+    {
+      cwd,
+      stdio: ["pipe", "pipe", "pipe"],
+      env: { ...process.env, NO_COLOR: "1" },
+    },
+  )
+
+  const client = new RpcProbeClient(child, timeoutMs)
+  try {
+    const promptAccepted = client.waitFor(
+      (event): event is RpcResponse =>
+        isRpcResponse(event) && event.command === "prompt",
+    )
+    child.stdin.write(
+      `${JSON.stringify({ id: "proof", type: "prompt", message: "/brunch-structured-question-rpc-proof" })}\n`,
+    )
+
+    const editorRequest = await client.waitFor(
+      (event): event is StructuredQuestionRpcProofResult["editorRequest"] =>
+        isEditorRequest(event),
+    )
+    child.stdin.write(
+      `${JSON.stringify({
+        type: "extension_ui_response",
+        id: editorRequest.id,
+        value: answeredEditorPayload(editorRequest.prefill),
+      })}\n`,
+    )
+
+    const promptResponse = await promptAccepted
+    if (!promptResponse.success) {
+      throw new Error(
+        `Proof command failed: ${promptResponse.error ?? "unknown error"}`,
+      )
+    }
+
+    const stateResponse = client.waitFor(
+      (event): event is RpcResponse<{ sessionFile?: string }> =>
+        isRpcResponse(event) && event.id === "state",
+    )
+    child.stdin.write(`${JSON.stringify({ id: "state", type: "get_state" })}\n`)
+    const state = await stateResponse
+    const sessionFile = state.data?.sessionFile
+    if (!state.success || typeof sessionFile !== "string") {
+      throw new Error("RPC proof did not expose a persisted session file")
+    }
+
+    const details = await readProofDetails(sessionFile)
+    return {
+      editorRequest,
+      details,
+      sessionFile,
+      stdout: client.events,
+    }
+  } finally {
+    client.dispose()
+  }
+}
+
+async function writeProofExtension(cwd: string): Promise<string> {
+  const extensionPath = join(cwd, "structured-question-rpc-proof-extension.ts")
+  const adapterPath = resolve("src/pi-extensions/structured-question.ts")
+  const content = `
+    import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"
+    import {
+      buildStructuredQuestionEditorPrefill,
+      structuredQuestionResultFromEditor,
+    } from ${JSON.stringify(adapterPath)}
+
+    const params = {
+      id: "q-rpc-proof",
+      mode: "text",
+      prompt: "What did the RPC proof answer?",
+      required: true,
+    } as const
+
+    export default function(pi: ExtensionAPI): void {
+      pi.registerCommand("brunch-structured-question-rpc-proof", {
+        description: "Exercise Brunch structured-question RPC editor fallback.",
+        handler: async (_args, ctx) => {
+          const edited = await ctx.ui.editor(
+            "Answer structured question as JSON",
+            buildStructuredQuestionEditorPrefill(params),
+          )
+          const result = structuredQuestionResultFromEditor(params, edited)
+          ctx.sessionManager.appendMessage({
+            role: "assistant",
+            content: [{ type: "text", text: "Structured-question RPC proof completed." }],
+            api: "openai-completions",
+            provider: "openai",
+            model: "test-model",
+            usage: {
+              input: 0,
+              output: 0,
+              cacheRead: 0,
+              cacheWrite: 0,
+              totalTokens: 0,
+              cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+            },
+            stopReason: "stop",
+            timestamp: Date.now(),
+          })
+          pi.appendEntry(${JSON.stringify(PROOF_CUSTOM_TYPE)}, result.details)
+          ctx.ui.notify(result.content[0]?.text ?? "Structured question completed.", "info")
+        },
+      })
+    }
+  `
+  await writeFile(extensionPath, content, "utf8")
+  return extensionPath
+}
+
+function answeredEditorPayload(prefill: string | undefined): string {
+  if (!prefill) throw new Error("RPC editor request did not include a prefill")
+  const payload = JSON.parse(prefill) as {
+    response?: unknown
+  }
+  payload.response = {
+    status: "answered",
+    answers: [
+      {
+        questionId: "q-rpc-proof",
+        mode: "text",
+        value: "RPC editor fallback works",
+      },
+    ],
+  }
+  return `${JSON.stringify(payload, null, 2)}\n`
+}
+
+async function readProofDetails(
+  sessionFile: string,
+): Promise<StructuredQuestionResultDetails> {
+  const entries = (await readFile(sessionFile, "utf8"))
+    .split("\n")
+    .filter((line) => line.trim().length > 0)
+    .map((line) => JSON.parse(line) as unknown)
+  const proofEntry = entries.find(
+    (entry): entry is ProofResultEntry =>
+      typeof entry === "object" &&
+      entry !== null &&
+      (entry as { customType?: unknown }).customType === PROOF_CUSTOM_TYPE &&
+      "data" in entry,
+  )
+  if (!proofEntry) {
+    throw new Error("RPC proof result entry was not written to the session")
+  }
+  return Value.Parse(StructuredQuestionResultDetailsSchema, proofEntry.data)
+}
+
+function piCliPath(): string {
+  return fileURLToPath(
+    new URL(
+      "../node_modules/@earendil-works/pi-coding-agent/dist/cli.js",
+      import.meta.url,
+    ),
+  )
+}
+
+interface RpcResponse<T = unknown> {
+  type: "response"
+  id?: string
+  command: string
+  success: boolean
+  data?: T
+  error?: string
+}
+
+interface ProofResultEntry {
+  customType: string
+  data: unknown
+}
+
+function isRpcResponse(value: unknown): value is RpcResponse {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { type?: unknown }).type === "response" &&
+    typeof (value as { command?: unknown }).command === "string" &&
+    typeof (value as { success?: unknown }).success === "boolean"
+  )
+}
+
+function isEditorRequest(
+  value: unknown,
+): value is StructuredQuestionRpcProofResult["editorRequest"] {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { type?: unknown }).type === "extension_ui_request" &&
+    typeof (value as { id?: unknown }).id === "string" &&
+    (value as { method?: unknown }).method === "editor"
+  )
+}
+
+class RpcProbeClient {
+  readonly events: unknown[] = []
+  readonly #child: ChildProcessWithoutNullStreams
+  readonly #timeoutMs: number
+  #stdout = ""
+  #stderr = ""
+  #waiters: Array<{
+    predicate: (event: unknown) => boolean
+    resolve: (event: unknown) => void
+  }> = []
+
+  constructor(child: ChildProcessWithoutNullStreams, timeoutMs: number) {
+    this.#child = child
+    this.#timeoutMs = timeoutMs
+    child.stdout.on("data", (chunk) => this.#ingestStdout(String(chunk)))
+    child.stderr.on("data", (chunk) => {
+      this.#stderr += String(chunk)
+    })
+  }
+
+  waitFor<T,>(predicate: (event: unknown) => event is T): Promise<T> {
+    const existing = this.events.find(predicate)
+    if (existing) return Promise.resolve(existing)
+
+    return new Promise<T>((resolve, reject) => {
+      const timeout = setTimeout(
+        () => {
+          reject(
+            new Error(
+              `Timed out waiting for RPC proof event. Stderr:\n${this.#stderr}`,
+            ),
+          )
+        },
+        this.#timeoutMs,
+      )
+      this.#waiters.push({
+        predicate,
+        resolve: (event) => {
+          clearTimeout(timeout)
+          resolve(event as T)
+        },
+      })
+    })
+  }
+
+  dispose(): void {
+    this.#child.kill("SIGTERM")
+  }
+
+  #ingestStdout(chunk: string): void {
+    this.#stdout += chunk
+    while (true) {
+      const newline = this.#stdout.indexOf("\n")
+      if (newline === -1) return
+      const line = this.#stdout.slice(0, newline).replace(/\r$/, "")
+      this.#stdout = this.#stdout.slice(newline + 1)
+      if (line.trim().length === 0) continue
+      let event: unknown
+      try {
+        event = JSON.parse(line)
+      } catch {
+        continue
+      }
+      this.events.push(event)
+      const waiters = this.#waiters.slice()
+      for (const waiter of waiters) {
+        if (!waiter.predicate(event)) continue
+        this.#waiters = this.#waiters.filter(
+          (candidate) => candidate !== waiter,
+        )
+        waiter.resolve(event)
+      }
+    }
+  }
+}
diff --git a/src/structured-question.test.ts b/src/structured-question.test.ts
new file mode 100644
index 00000000..3c50157f
--- /dev/null
+++ b/src/structured-question.test.ts
@@ -0,0 +1,258 @@
+import { describe, expect, it } from "vitest"
+import { Value } from "typebox/value"
+
+import {
+  StructuredQuestionResultDetailsSchema,
+  buildStructuredQuestionResult,
+  isTerminalStructuredQuestionResultDetails,
+  parseStructuredQuestionParams,
+  structuredQuestionSummary,
+  type StructuredQuestionAnswer,
+  type StructuredQuestionParams,
+} from "./structured-question.js"
+
+const transport = { surface: "test" as const, requestId: "req-1" }
+
+describe("structured-question result model", () => {
+  it("builds self-contained text answer details and content", () => {
+    const params: StructuredQuestionParams = {
+      id: "q-domain",
+      mode: "text",
+      prompt: "What domain are we in?",
+      required: true,
+    }
+
+    const result = buildStructuredQuestionResult({
+      params,
+      status: "answered",
+      transport,
+      answers: [
+        { questionId: "q-domain", mode: "text", value: "Local-first devtools" },
+      ],
+    })
+
+    expect(
+      Value.Check(StructuredQuestionResultDetailsSchema, result.details),
+    ).toBe(true)
+    expect(result.details).toMatchObject({
+      schema: "brunch.structured_question.result",
+      schemaVersion: 1,
+      status: "answered",
+      mode: "text",
+      prompt: "What domain are we in?",
+      questions: [{ id: "q-domain", mode: "text" }],
+      answers: [{ questionId: "q-domain", value: "Local-first devtools" }],
+      transport,
+    })
+    expect(result.content).toEqual([
+      {
+        type: "text",
+        text: "What domain are we in?: Local-first devtools",
+      },
+    ])
+  })
+
+  it("builds single-select details with options and optional freeform", () => {
+    const params: StructuredQuestionParams = {
+      id: "q-risk",
+      mode: "singleSelect",
+      prompt: "Which risk dominates?",
+      options: [
+        { id: "ux", label: "UX ambiguity", description: "User cannot choose" },
+        { id: "rpc", label: "RPC mismatch" },
+      ],
+      allowFreeform: true,
+    }
+
+    const result = buildStructuredQuestionResult({
+      params,
+      status: "answered",
+      transport,
+      answers: [
+        {
+          questionId: "q-risk",
+          mode: "singleSelect",
+          selectedOption: { id: "rpc", label: "RPC mismatch" },
+          freeform: "Editor fallback must match TUI semantics.",
+        },
+      ],
+    })
+
+    expect(result.details.questions[0]).toMatchObject({
+      options: [
+        { id: "ux", label: "UX ambiguity" },
+        { id: "rpc", label: "RPC mismatch" },
+      ],
+      allowFreeform: true,
+    })
+    expect(result.details.answers[0]).toMatchObject({
+      selectedOption: { id: "rpc", label: "RPC mismatch" },
+      freeform: "Editor fallback must match TUI semantics.",
+    })
+    expect(result.content[0]?.text).toBe(
+      "Which risk dominates?: RPC mismatch; freeform: Editor fallback must match TUI semantics.",
+    )
+  })
+
+  it("builds multi-select details with selected option labels", () => {
+    const params: StructuredQuestionParams = {
+      id: "q-oracles",
+      mode: "multiSelect",
+      prompt: "Which oracles apply?",
+      options: [
+        { id: "unit", label: "Unit" },
+        { id: "rpc", label: "RPC contract" },
+        { id: "pty", label: "PTY smoke" },
+      ],
+    }
+
+    const result = buildStructuredQuestionResult({
+      params,
+      status: "answered",
+      transport,
+      answers: [
+        {
+          questionId: "q-oracles",
+          mode: "multiSelect",
+          selectedOptions: [
+            { id: "rpc", label: "RPC contract" },
+            { id: "pty", label: "PTY smoke" },
+          ],
+        },
+      ],
+    })
+
+    expect(result.details.answers[0]).toMatchObject({
+      mode: "multiSelect",
+      selectedOptions: [
+        { id: "rpc", label: "RPC contract" },
+        { id: "pty", label: "PTY smoke" },
+      ],
+    })
+    expect(result.content[0]?.text).toBe(
+      "Which oracles apply?: RPC contract, PTY smoke",
+    )
+  })
+
+  it("builds questionnaire details with each prompt, option set, and answer", () => {
+    const params: StructuredQuestionParams = {
+      id: "q-grounding",
+      mode: "questionnaire",
+      prompt: "Grounding bundle",
+      questions: [
+        {
+          id: "domain",
+          mode: "text",
+          prompt: "Domain?",
+        },
+        {
+          id: "pressure",
+          mode: "singleSelect",
+          prompt: "Main pressure?",
+          options: [
+            { id: "speed", label: "Speed" },
+            { id: "trust", label: "Trust" },
+          ],
+        },
+      ],
+    }
+    const answers: StructuredQuestionAnswer[] = [
+      { questionId: "domain", mode: "text", value: "Developer tooling" },
+      {
+        questionId: "pressure",
+        mode: "singleSelect",
+        selectedOption: { id: "trust", label: "Trust" },
+      },
+    ]
+
+    const result = buildStructuredQuestionResult({
+      params,
+      status: "answered",
+      transport,
+      answers,
+    })
+
+    expect(result.details.mode).toBe("questionnaire")
+    expect(result.details.questions.map((question) => question.prompt)).toEqual(
+      ["Domain?", "Main pressure?"],
+    )
+    expect(result.details.answers).toEqual(answers)
+    expect(result.content[0]?.text).toBe(
+      "Domain?: Developer tooling\nMain pressure?: Trust",
+    )
+  })
+
+  it("builds terminal skipped, cancelled, and unavailable details without answers", () => {
+    const params = parseStructuredQuestionParams({
+      id: "q-terminal",
+      mode: "text",
+      prompt: "Can you answer?",
+    })
+
+    for (const status of ["skipped", "cancelled", "unavailable"] as const) {
+      const result = buildStructuredQuestionResult({
+        params,
+        status,
+        transport: { surface: "headless" },
+        ...(status === "unavailable" ? { message: "UI unavailable" } : {}),
+      })
+
+      expect(result.details).toMatchObject({
+        status,
+        answers: [],
+        questions: [{ id: "q-terminal", prompt: "Can you answer?" }],
+        transport: { surface: "headless" },
+      })
+      expect(structuredQuestionSummary(result.details)).toContain(status)
+    }
+  })
+
+  it("recognizes terminal structured-question result details without matching unrelated tool output", () => {
+    const params = parseStructuredQuestionParams({
+      id: "q-terminal",
+      mode: "text",
+      prompt: "Can you answer?",
+    })
+    const answered = buildStructuredQuestionResult({
+      params,
+      status: "answered",
+      answers: [{ questionId: "q-terminal", mode: "text", value: "Yes" }],
+      transport,
+    })
+    const skipped = buildStructuredQuestionResult({
+      params,
+      status: "skipped",
+      transport,
+    })
+    const cancelled = buildStructuredQuestionResult({
+      params,
+      status: "cancelled",
+      transport,
+    })
+    const unavailable = buildStructuredQuestionResult({
+      params,
+      status: "unavailable",
+      transport: { surface: "headless" },
+      message: "No UI surface is available.",
+    })
+
+    expect(isTerminalStructuredQuestionResultDetails(answered.details)).toBe(
+      true,
+    )
+    expect(isTerminalStructuredQuestionResultDetails(skipped.details)).toBe(
+      true,
+    )
+    expect(isTerminalStructuredQuestionResultDetails(cancelled.details)).toBe(
+      true,
+    )
+    expect(isTerminalStructuredQuestionResultDetails(unavailable.details)).toBe(
+      false,
+    )
+    expect(
+      isTerminalStructuredQuestionResultDetails({
+        status: "answered",
+        content: [{ type: "text", text: "ordinary tool output" }],
+      }),
+    ).toBe(false)
+  })
+})
diff --git a/src/structured-question.ts b/src/structured-question.ts
new file mode 100644
index 00000000..7a05cfb3
--- /dev/null
+++ b/src/structured-question.ts
@@ -0,0 +1,260 @@
+import { Type, type Static } from "typebox"
+import { Value } from "typebox/value"
+
+const NonBlankStringSchema = Type.String({ minLength: 1, pattern: "\\S" })
+
+export const StructuredQuestionOptionSchema = Type.Object(
+  {
+    id: NonBlankStringSchema,
+    label: NonBlankStringSchema,
+    description: Type.Optional(Type.String()),
+  },
+  { additionalProperties: false },
+)
+
+const TextQuestionSchema = Type.Object(
+  {
+    id: NonBlankStringSchema,
+    mode: Type.Literal("text"),
+    prompt: NonBlankStringSchema,
+    required: Type.Optional(Type.Boolean()),
+  },
+  { additionalProperties: false },
+)
+
+const SingleSelectQuestionSchema = Type.Object(
+  {
+    id: NonBlankStringSchema,
+    mode: Type.Literal("singleSelect"),
+    prompt: NonBlankStringSchema,
+    options: Type.Array(StructuredQuestionOptionSchema, { minItems: 1 }),
+    allowFreeform: Type.Optional(Type.Boolean()),
+    required: Type.Optional(Type.Boolean()),
+  },
+  { additionalProperties: false },
+)
+
+const MultiSelectQuestionSchema = Type.Object(
+  {
+    id: NonBlankStringSchema,
+    mode: Type.Literal("multiSelect"),
+    prompt: NonBlankStringSchema,
+    options: Type.Array(StructuredQuestionOptionSchema, { minItems: 1 }),
+    allowFreeform: Type.Optional(Type.Boolean()),
+    required: Type.Optional(Type.Boolean()),
+  },
+  { additionalProperties: false },
+)
+
+export const StructuredQuestionSchema = Type.Union([
+  TextQuestionSchema,
+  SingleSelectQuestionSchema,
+  MultiSelectQuestionSchema,
+])
+
+export const StructuredQuestionParamsSchema = Type.Union([
+  TextQuestionSchema,
+  SingleSelectQuestionSchema,
+  MultiSelectQuestionSchema,
+  Type.Object(
+    {
+      id: NonBlankStringSchema,
+      mode: Type.Literal("questionnaire"),
+      prompt: NonBlankStringSchema,
+      questions: Type.Array(StructuredQuestionSchema, { minItems: 1 }),
+    },
+    { additionalProperties: false },
+  ),
+])
+
+const SelectedOptionSchema = Type.Object(
+  {
+    id: NonBlankStringSchema,
+    label: NonBlankStringSchema,
+  },
+  { additionalProperties: false },
+)
+
+const TextAnswerSchema = Type.Object(
+  {
+    questionId: NonBlankStringSchema,
+    mode: Type.Literal("text"),
+    value: Type.String(),
+  },
+  { additionalProperties: false },
+)
+
+const SingleSelectAnswerSchema = Type.Object(
+  {
+    questionId: NonBlankStringSchema,
+    mode: Type.Literal("singleSelect"),
+    selectedOption: Type.Optional(SelectedOptionSchema),
+    freeform: Type.Optional(Type.String()),
+  },
+  { additionalProperties: false },
+)
+
+const MultiSelectAnswerSchema = Type.Object(
+  {
+    questionId: NonBlankStringSchema,
+    mode: Type.Literal("multiSelect"),
+    selectedOptions: Type.Array(SelectedOptionSchema),
+    freeform: Type.Optional(Type.String()),
+  },
+  { additionalProperties: false },
+)
+
+export const StructuredQuestionAnswerSchema = Type.Union([
+  TextAnswerSchema,
+  SingleSelectAnswerSchema,
+  MultiSelectAnswerSchema,
+])
+
+export const StructuredQuestionTransportSchema = Type.Object(
+  {
+    surface: Type.Union([
+      Type.Literal("tui-custom"),
+      Type.Literal("rpc-editor"),
+      Type.Literal("rpc-dialog"),
+      Type.Literal("headless"),
+      Type.Literal("test"),
+    ]),
+    requestId: Type.Optional(Type.String()),
+  },
+  { additionalProperties: false },
+)
+
+export const StructuredQuestionResultDetailsSchema = Type.Object(
+  {
+    schema: Type.Literal("brunch.structured_question.result"),
+    schemaVersion: Type.Literal(1),
+    status: Type.Union([
+      Type.Literal("answered"),
+      Type.Literal("skipped"),
+      Type.Literal("cancelled"),
+      Type.Literal("unavailable"),
+    ]),
+    mode: Type.Union([
+      Type.Literal("text"),
+      Type.Literal("singleSelect"),
+      Type.Literal("multiSelect"),
+      Type.Literal("questionnaire"),
+    ]),
+    prompt: NonBlankStringSchema,
+    questions: Type.Array(StructuredQuestionSchema, { minItems: 1 }),
+    answers: Type.Array(StructuredQuestionAnswerSchema),
+    transport: StructuredQuestionTransportSchema,
+    message: Type.Optional(Type.String()),
+  },
+  { additionalProperties: false },
+)
+
+export type StructuredQuestionParams = Static<typeof StructuredQuestionParamsSchema>
+export type StructuredQuestion = Static<typeof StructuredQuestionSchema>
+export type StructuredQuestionAnswer = Static<typeof StructuredQuestionAnswerSchema>
+export type StructuredQuestionTransport = Static<typeof StructuredQuestionTransportSchema>
+export type StructuredQuestionResultDetails = Static<typeof StructuredQuestionResultDetailsSchema>
+export type StructuredQuestionStatus = StructuredQuestionResultDetails["status"]
+
+export interface StructuredQuestionContentPart {
+  type: "text"
+  text: string
+}
+
+export interface StructuredQuestionToolResult {
+  content: StructuredQuestionContentPart[]
+  details: StructuredQuestionResultDetails
+}
+
+export function parseStructuredQuestionParams(
+  value: unknown,
+): StructuredQuestionParams {
+  return Value.Parse(StructuredQuestionParamsSchema, value)
+}
+
+export function isTerminalStructuredQuestionResultDetails(
+  value: unknown,
+): value is StructuredQuestionResultDetails {
+  if (!Value.Check(StructuredQuestionResultDetailsSchema, value)) {
+    return false
+  }
+  return (
+    value.status === "answered" ||
+    value.status === "skipped" ||
+    value.status === "cancelled"
+  )
+}
+
+export function buildStructuredQuestionResult(input: {
+  params: StructuredQuestionParams
+  status: StructuredQuestionStatus
+  answers?: StructuredQuestionAnswer[]
+  transport: StructuredQuestionTransport
+  message?: string
+}): StructuredQuestionToolResult {
+  const details = Value.Parse(StructuredQuestionResultDetailsSchema, {
+    schema: "brunch.structured_question.result",
+    schemaVersion: 1,
+    status: input.status,
+    mode: input.params.mode,
+    prompt: input.params.prompt,
+    questions: questionsFromParams(input.params),
+    answers: input.answers ?? [],
+    transport: input.transport,
+    ...(input.message ? { message: input.message } : {}),
+  })
+  return {
+    content: structuredQuestionContent(details),
+    details,
+  }
+}
+
+export function structuredQuestionContent(
+  details: StructuredQuestionResultDetails,
+): StructuredQuestionContentPart[] {
+  return [{ type: "text", text: structuredQuestionSummary(details) }]
+}
+
+export function structuredQuestionSummary(
+  details: StructuredQuestionResultDetails,
+): string {
+  if (details.status !== "answered") {
+    return details.message
+      ? `Structured question ${details.status}: ${details.message}`
+      : `Structured question ${details.status}.`
+  }
+
+  if (details.answers.length === 0) return "Structured question answered."
+
+  const lines = details.answers.map((answer) => {
+    const question = details.questions.find(
+      (candidate) => candidate.id === answer.questionId,
+    )
+    const label = question ? question.prompt : answer.questionId
+    return `${label}: ${formatAnswer(answer)}`
+  })
+  return lines.join("\n")
+}
+
+function questionsFromParams(
+  params: StructuredQuestionParams,
+): StructuredQuestion[] {
+  if (params.mode === "questionnaire") return params.questions
+  return [params]
+}
+
+function formatAnswer(answer: StructuredQuestionAnswer): string {
+  if (answer.mode === "text") return answer.value || "(empty response)"
+  if (answer.mode === "singleSelect") {
+    const selected = answer.selectedOption?.label
+    const freeform = answer.freeform ? `freeform: ${answer.freeform}` : null
+    return [selected, freeform].filter(Boolean).join("; ") || "(no selection)"
+  }
+  const selected = answer.selectedOptions
+    .map((option) => option.label)
+    .join(", ")
+  const freeform = answer.freeform ? `freeform: ${answer.freeform}` : null
+  return (
+    [selected || null, freeform].filter(Boolean).join("; ") || "(no selections)"
+  )
+}
diff --git a/src/test-helpers.ts b/src/test-helpers.ts
new file mode 100644
index 00000000..aa6ce216
--- /dev/null
+++ b/src/test-helpers.ts
@@ -0,0 +1,67 @@
+/**
+ * Test helpers — typed factory functions for fixture construction.
+ *
+ * Tests historically built `Message` objects inline as `{ role, content }`
+ * which omits required fields like `timestamp` and (for assistants) wraps
+ * string content where the canonical type wants `(TextContent | ...)[]`. The
+ * runtime tolerated this; strict TS does not. These factories produce
+ * canonical messages so test fixtures stay aligned with production types.
+ */
+
+import type {
+  AssistantMessage,
+  ImageContent,
+  TextContent,
+  ThinkingContent,
+  ToolCall,
+  UserMessage,
+} from "@earendil-works/pi-ai"
+import type {
+  CustomEntry,
+  CustomMessageEntry,
+  SessionEntry,
+} from "@earendil-works/pi-coding-agent"
+
+const ZERO_USAGE = {
+  input: 0,
+  output: 0,
+  cacheRead: 0,
+  cacheWrite: 0,
+  totalTokens: 0,
+  cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+} as const
+
+export function userMessage(
+  content: string | (TextContent | ImageContent)[],
+  timestamp = 0,
+): UserMessage {
+  return { role: "user", content, timestamp }
+}
+
+export function assistantMessage(
+  text: string | (TextContent | ThinkingContent | ToolCall)[],
+  timestamp = 0,
+): AssistantMessage {
+  const content: (TextContent | ThinkingContent | ToolCall)[] =
+    typeof text === "string" ? [{ type: "text", text }] : text
+  return {
+    role: "assistant",
+    content,
+    api: "openai-completions",
+    provider: "openai",
+    model: "test-model",
+    usage: { ...ZERO_USAGE, cost: { ...ZERO_USAGE.cost } },
+    stopReason: "stop",
+    timestamp,
+  }
+}
+
+export function isCustomEntry(entry: SessionEntry): entry is CustomEntry {
+  return entry.type === "custom"
+}
+
+export function isCustomMessageEntry(
+  entry: SessionEntry,
+): entry is CustomMessageEntry {
+  return entry.type === "custom_message"
+}
diff --git a/src/web-client/app.test.tsx b/src/web-client/app.test.tsx
index 681e5756..f648793b 100644
--- a/src/web-client/app.test.tsx
+++ b/src/web-client/app.test.tsx
@@ -52,21 +52,21 @@ function rpcClient(options?: {
   const projection = options?.projection ?? readyProjection
   const calls = options?.calls
   return {
-    async request(method, params) {
+    async request<T,>(method: string, params?: unknown): Promise<T> {
       calls?.push(params === undefined ? { method } : { method, params })
       if (method === "workspace.snapshot") {
-        return snapshot
+        return snapshot as T
       }
       if (method === "session.transcriptDisplay") {
         if (options?.projectionError) {
           throw options.projectionError
         }
-        return projection
+        return projection as T
       }
       throw new Error(`unexpected RPC method ${method}`)
     },
     close: vi.fn(),
-  }
+  } as unknown as WebSocketRpcClient
 }
 
 afterEach(() => cleanup())
diff --git a/src/web-client/rpc-client.test.ts b/src/web-client/rpc-client.test.ts
index 13403990..f4a9b6ab 100644
--- a/src/web-client/rpc-client.test.ts
+++ b/src/web-client/rpc-client.test.ts
@@ -31,7 +31,7 @@ class FakeWebSocket {
 
   emit(event: string, data?: string) {
     for (const listener of this.listeners.get(event) ?? []) {
-      listener({ data })
+      listener(data === undefined ? {} : { data })
     }
   }
 }
diff --git a/src/web-host.test.ts b/src/web-host.test.ts
index a9b8f32b..80c25967 100644
--- a/src/web-host.test.ts
+++ b/src/web-host.test.ts
@@ -12,6 +12,7 @@ import {
   type WorkspaceSessionCoordinator,
 } from "./workspace-session-coordinator.js"
 import { startWebHost } from "./web-host.js"
+import { assistantMessage, userMessage } from "./test-helpers.js"
 
 function text(response: Response): Promise<string> {
   return response.text()
@@ -33,7 +34,9 @@ async function rawGet(url: string, path: string): Promise<Response> {
         res.on("end", () => {
           resolve(
             new Response(Buffer.concat(chunks), {
-              status: res.statusCode,
+              ...(res.statusCode !== undefined
+                ? { status: res.statusCode }
+                : {}),
               headers: res.headers as Record<string, string>,
             }),
           )
@@ -170,14 +173,11 @@ describe("web host", () => {
     const cwd = await mkdtemp(join(tmpdir(), "brunch-web-rpc-"))
     const workspace = await createWorkspaceSessionCoordinator({
       cwd,
-    }).startOrCreate({
+    }).createSetupSession({
       specTitle: "Web spec",
     })
-    workspace.session.manager.appendMessage({
-      role: "assistant",
-      content: "Question",
-    })
-    workspace.session.manager.appendMessage({ role: "user", content: "Answer" })
+    workspace.session.manager.appendMessage(assistantMessage("Question"))
+    workspace.session.manager.appendMessage(userMessage("Answer"))
     const host = await startWebHost({
       cwd,
       port: 0,
@@ -216,23 +216,17 @@ describe("web host", () => {
   it("serves explicit session projection over WebSocket", async () => {
     const cwd = await mkdtemp(join(tmpdir(), "brunch-web-rpc-explicit-"))
     const coordinator = createWorkspaceSessionCoordinator({ cwd })
-    const first = await coordinator.startOrCreate({
+    const first = await coordinator.createSetupSession({
       specTitle: "Explicit web spec",
     })
-    first.session.manager.appendMessage({
-      role: "assistant",
-      content: "First question",
-    })
+    first.session.manager.appendMessage(assistantMessage("First question"))
     first.session.manager.appendCustomMessageEntry(
       "brunch.elicitation_prompt",
       "Pick an explicit session direction.",
       true,
     )
-    first.session.manager.appendMessage({
-      role: "user",
-      content: "First answer",
-    })
-    await coordinator.createNewSessionForCurrentSpec()
+    first.session.manager.appendMessage(userMessage("First answer"))
+    await coordinator.createSetupSessionForCurrentSpec()
     const host = await startWebHost({
       cwd,
       port: 0,
@@ -280,7 +274,7 @@ describe("web host", () => {
 
   it("multiplexes two JSON-RPC requests over one WebSocket", async () => {
     const cwd = await mkdtemp(join(tmpdir(), "brunch-web-rpc-multiplex-"))
-    await createWorkspaceSessionCoordinator({ cwd }).startOrCreate({
+    await createWorkspaceSessionCoordinator({ cwd }).createSetupSession({
       specTitle: "Multiplex spec",
     })
     const host = await startWebHost({
@@ -308,7 +302,7 @@ describe("web host", () => {
 
   it("returns a parse error for malformed WebSocket JSON without killing the host", async () => {
     const cwd = await mkdtemp(join(tmpdir(), "brunch-web-rpc-malformed-"))
-    await createWorkspaceSessionCoordinator({ cwd }).startOrCreate({
+    await createWorkspaceSessionCoordinator({ cwd }).createSetupSession({
       specTitle: "Malformed spec",
     })
     const host = await startWebHost({
@@ -378,14 +372,14 @@ describe("web host", () => {
     const cwd = await mkdtemp(join(tmpdir(), "brunch-web-rpc-branch-"))
     const workspace = await createWorkspaceSessionCoordinator({
       cwd,
-    }).startOrCreate({
+    }).createSetupSession({
       specTitle: "Branch spec",
     })
     const manager = SessionManager.open(workspace.session.file)
-    manager.appendMessage({ role: "assistant", content: "Abandoned prompt" })
-    manager.appendMessage({ role: "user", content: "Abandoned answer" })
+    manager.appendMessage(assistantMessage("Abandoned prompt"))
+    manager.appendMessage(userMessage("Abandoned answer"))
     manager.resetLeaf()
-    manager.appendMessage({ role: "assistant", content: "Active prompt" })
+    manager.appendMessage(assistantMessage("Active prompt"))
     const host = await startWebHost({
       cwd,
       port: 0,
@@ -493,20 +487,9 @@ function openWebSocket(url: string): Promise<WebSocket> {
 
 function throwingCoordinator(): WorkspaceSessionCoordinator {
   return {
-    async openExisting() {
+    ...createWorkspaceSessionCoordinator({ cwd: "/tmp/brunch-project" }),
+    async openDefaultWorkspace() {
       throw new Error("boom")
     },
-    async startOrCreate() {
-      throw new Error("not used")
-    },
-    async createNewSessionForCurrentSpec() {
-      throw new Error("not used")
-    },
-    async bindCurrentSpecToSession() {
-      throw new Error("not used")
-    },
-    async deriveChromeState() {
-      throw new Error("not used")
-    },
   }
 }
diff --git a/src/workspace-dialog.test.ts b/src/workspace-dialog.test.ts
new file mode 100644
index 00000000..e7238b05
--- /dev/null
+++ b/src/workspace-dialog.test.ts
@@ -0,0 +1,438 @@
+import { readFile } from "node:fs/promises"
+
+import { type Terminal } from "@earendil-works/pi-tui"
+
+import { describe, expect, it } from "vitest"
+
+import {
+  buildWorkspaceSelectionView,
+  createWorkspaceDialogComponent,
+  selectWorkspaceSelectionOption,
+  runWorkspaceDialogPreflight,
+} from "./pi-components/workspace-dialog/index.js"
+import type { WorkspaceLaunchInventory } from "./workspace-session-coordinator.js"
+
+describe("spec/session picker", () => {
+  it("builds a hierarchical spec/session selection home without per-spec top-level actions", () => {
+    const view = buildWorkspaceSelectionView(inventory())
+
+    expect(view.stage).toBe("home")
+    expect(view.options.map((option) => option.kind)).toEqual([
+      "continue",
+      "resumeSpec",
+      "newSpec",
+      "cancel",
+    ])
+    expect(view.options.map((option) => option.label)).toEqual([
+      "Continue your latest spec and session",
+      "Continue another existing specification",
+      "Start a new specification",
+      "Cancel",
+    ])
+    expect(view.options.map((option) => option.label).join("\n")).not.toMatch(
+      /Resume Alpha|Open Alpha|Start new session in Alpha/,
+    )
+    expect(selectWorkspaceSelectionOption(view, 0)).toEqual({
+      decision: {
+        action: "continue",
+        specId: "spec-alpha",
+        sessionFile: "/sessions/alpha-current.jsonl",
+      },
+    })
+  })
+
+  it("navigates resume-existing-spec to spec actions without emitting activation early", () => {
+    const currentInventory = inventory()
+    const home = buildWorkspaceSelectionView(currentInventory)
+    const specList = selectWorkspaceSelectionOption(home, 1, currentInventory)
+
+    expect(specList).toMatchObject({ view: { stage: "specList" } })
+    if (!("view" in specList)) throw new Error("expected spec list")
+    expect(specList.view.options.map((option) => option.label)).toEqual([
+      "Alpha",
+      "Beta",
+    ])
+
+    const specAction = selectWorkspaceSelectionOption(
+      specList.view,
+      0,
+      currentInventory,
+    )
+
+    expect(specAction).toMatchObject({ view: { stage: "specAction" } })
+    if (!("view" in specAction)) throw new Error("expected spec action")
+    expect(specAction.view.options.map((option) => option.label)).toEqual([
+      "Create new session",
+      "Resume existing session",
+    ])
+    expect(selectWorkspaceSelectionOption(specAction.view, 0)).toEqual({
+      decision: { action: "newSession", specId: "spec-alpha" },
+    })
+  })
+
+  it("emits open-session only after a session is selected", () => {
+    const sessionList = buildWorkspaceSelectionView(inventory(), {
+      stage: "sessionList",
+      specId: "spec-alpha",
+    })
+
+    expect(sessionList.options.map((option) => option.label)).toEqual([
+      "session-alpha-current",
+      "session-alpha-older",
+    ])
+    expect(selectWorkspaceSelectionOption(sessionList, 1)).toEqual({
+      decision: {
+        action: "openSession",
+        specId: "spec-alpha",
+        sessionFile: "/sessions/alpha-older.jsonl",
+      },
+    })
+  })
+
+  it("enters new-spec title state before emitting a new-spec decision", () => {
+    const home = buildWorkspaceSelectionView(inventory())
+
+    expect(selectWorkspaceSelectionOption(home, 2)).toMatchObject({
+      view: { stage: "newSpecTitle", title: "", options: [] },
+    })
+  })
+
+  it("only shows logical home options in an empty workspace", () => {
+    const view = buildWorkspaceSelectionView(emptyInventory())
+
+    expect(view.options.map((option) => option.label)).toEqual([
+      "Start a new specification",
+      "Cancel",
+    ])
+  })
+
+  it("only shows resume-existing-session when the chosen spec has sessions", () => {
+    const view = buildWorkspaceSelectionView(emptySessionInventory(), {
+      stage: "specAction",
+      specId: "spec-empty",
+    })
+
+    expect(view.options.map((option) => option.label)).toEqual([
+      "Create new session",
+    ])
+  })
+
+  it("renders specification copy without user-created workspace wording", () => {
+    const component = createWorkspaceDialogComponent({
+      inventory: inventory(),
+      onDecision: () => {},
+    })
+
+    const text = component.render(80).join("\n")
+
+    expect(text).toContain("Choose a specification")
+    expect(text).toContain("Start a new specification")
+    expect(text).toContain("Continue another existing specification")
+    expect(text).not.toContain("Brunch workspace")
+    expect(text).not.toContain("Create workspace")
+    expect(text).not.toContain("Open workspace")
+  })
+
+  it("omits continue-latest from in-session picker contexts", () => {
+    const component = createWorkspaceDialogComponent({
+      inventory: inventory(),
+      includeContinue: false,
+      onDecision: () => {},
+    })
+
+    const text = component.render(80).join("\n")
+
+    expect(text).not.toContain("Continue your latest spec and session")
+    expect(text).toContain("Switch to another specification")
+    expect(text).toContain("Start a new specification")
+    expect(text.indexOf("Switch to another specification")).toBeLessThan(
+      text.indexOf("Start a new specification"),
+    )
+  })
+
+  it("selects current continue as a typed decision", () => {
+    const decisions: unknown[] = []
+    const component = createWorkspaceDialogComponent({
+      inventory: inventory(),
+      onDecision: (decision) => decisions.push(decision),
+    })
+
+    component.handleInput!("\r")
+
+    expect(decisions).toEqual([
+      {
+        action: "continue",
+        specId: "spec-alpha",
+        sessionFile: "/sessions/alpha-current.jsonl",
+      },
+    ])
+  })
+
+  it("returns new-session through the hierarchical keyboard path", () => {
+    const decisions: unknown[] = []
+    const component = createWorkspaceDialogComponent({
+      inventory: inventory(),
+      onDecision: (decision) => decisions.push(decision),
+    })
+
+    component.handleInput!("\x1B[B")
+    component.handleInput!("\r")
+    component.handleInput!("\r")
+    component.handleInput!("\r")
+
+    expect(decisions).toEqual([{ action: "newSession", specId: "spec-alpha" }])
+  })
+
+  it("returns open-session through the hierarchical keyboard path", () => {
+    const decisions: unknown[] = []
+    const component = createWorkspaceDialogComponent({
+      inventory: inventory(),
+      onDecision: (decision) => decisions.push(decision),
+    })
+
+    component.handleInput!("\x1B[B")
+    component.handleInput!("\r")
+    component.handleInput!("\r")
+    component.handleInput!("\x1B[B")
+    component.handleInput!("\r")
+    component.handleInput!("\x1B[B")
+    component.handleInput!("\r")
+
+    expect(decisions).toEqual([
+      {
+        action: "openSession",
+        specId: "spec-alpha",
+        sessionFile: "/sessions/alpha-older.jsonl",
+      },
+    ])
+  })
+
+  it("returns new-spec decisions from title entry and cancel on escape", () => {
+    const decisions: unknown[] = []
+    const component = createWorkspaceDialogComponent({
+      inventory: inventory(),
+      onDecision: (decision) => decisions.push(decision),
+    })
+
+    component.handleInput!("\x1B[B")
+    component.handleInput!("\x1B[B")
+    component.handleInput!("\r")
+    for (const char of "Gamma") {
+      component.handleInput!(char)
+    }
+    component.handleInput!("\r")
+    const cancelComponent = createWorkspaceDialogComponent({
+      inventory: inventory(),
+      onDecision: (decision) => decisions.push(decision),
+    })
+    cancelComponent.handleInput!("\x1B")
+
+    expect(decisions).toEqual([
+      { action: "newSpec", title: "Gamma" },
+      { action: "cancel" },
+    ])
+  })
+
+  it("backs out one picker stage on escape and cancels from the home stage", () => {
+    const decisions: unknown[] = []
+    const component = createWorkspaceDialogComponent({
+      inventory: inventory(),
+      onDecision: (decision) => decisions.push(decision),
+    })
+
+    component.handleInput!("\x1B[B")
+    component.handleInput!("\r")
+    expect(component.render(80).join("\n")).toContain("Choose a specification")
+    component.handleInput!("\x1B")
+    expect(component.render(80).join("\n")).toContain(
+      "Continue your latest spec and session",
+    )
+    component.handleInput!("\x1B")
+
+    expect(decisions).toEqual([{ action: "cancel" }])
+  })
+
+  it("cancels from startup preflight on ctrl-c", async () => {
+    const terminal = new FakeTerminal()
+    const decision = runWorkspaceDialogPreflight(inventory(), { terminal })
+
+    terminal.emit("\x03")
+
+    await expect(decision).resolves.toEqual({ action: "cancel" })
+    expect(terminal.events.at(-2)).toBe("stop")
+    expect(terminal.events.at(-1)).toBe("clearScreen")
+  })
+
+  it("renders a branded centered-dialog frame with separately styled version metadata", () => {
+    const component = createWorkspaceDialogComponent({
+      inventory: inventory(),
+      onDecision: () => {},
+      theme: {
+        fg: (color, text) => `[${color}]${text}[/${color}]`,
+      },
+    })
+
+    const lines = component.render(80)
+
+    expect(lines[0]).toContain("╭")
+    expect(lines[1]).toMatch(
+      /^\[borderMuted\]│\[\/borderMuted\]\s+\[borderMuted\]│\[\/borderMuted\]$/,
+    )
+    expect(lines.some((line) => line.includes("Choose a specification"))).toBe(
+      true,
+    )
+    expect(
+      lines.some((line) => line.includes("[accent]brunch v0.0.0[/accent]")),
+    ).toBe(true)
+    expect(lines.some((line) => line.includes("[success](dev"))).toBe(true)
+    expect(lines.some((line) => line.includes("built on Pi v"))).toBe(true)
+  })
+
+  it("keeps logo assets colocated with the private picker component", async () => {
+    const source = await readFile(
+      new URL(
+        "./pi-components/workspace-dialog/assets/brunch-logo-quad-56x18.ansi",
+        import.meta.url,
+      ),
+      "utf8",
+    )
+
+    expect(source).toContain("\x1B[")
+  })
+
+  it("declares pi-tui as a direct dependency", async () => {
+    const manifest = JSON.parse(
+      await readFile(new URL("../package.json", import.meta.url), "utf8"),
+    ) as { dependencies?: Record<string, string> }
+
+    expect(manifest.dependencies).toHaveProperty("@earendil-works/pi-tui")
+  })
+
+  it("clears the startup preflight frame after a spec/session decision", async () => {
+    const terminal = new FakeTerminal()
+    const decision = runWorkspaceDialogPreflight(inventory(), { terminal })
+
+    terminal.emit("\r")
+
+    await expect(decision).resolves.toMatchObject({ action: "continue" })
+    expect(terminal.events.at(-2)).toBe("stop")
+    expect(terminal.events.at(-1)).toBe("clearScreen")
+  })
+})
+
+class FakeTerminal implements Terminal {
+  events: string[] = []
+  #onInput: ((data: string) => void) | undefined
+
+  get columns(): number {
+    return 100
+  }
+
+  get rows(): number {
+    return 32
+  }
+
+  get kittyProtocolActive(): boolean {
+    return false
+  }
+
+  start(onInput: (data: string) => void): void {
+    this.events.push("start")
+    this.#onInput = onInput
+  }
+
+  stop(): void {
+    this.events.push("stop")
+  }
+
+  async drainInput(): Promise<void> {}
+
+  write(_data: string): void {}
+
+  moveBy(_lines: number): void {}
+
+  hideCursor(): void {}
+
+  showCursor(): void {}
+
+  clearLine(): void {}
+
+  clearFromCursor(): void {}
+
+  clearScreen(): void {
+    this.events.push("clearScreen")
+  }
+
+  setTitle(_title: string): void {}
+
+  setProgress(_active: boolean): void {}
+
+  emit(data: string): void {
+    this.#onInput?.(data)
+  }
+}
+
+function emptyInventory(): WorkspaceLaunchInventory {
+  return {
+    cwd: "/project",
+    currentSpec: null,
+    currentSessionFile: null,
+    needsNewSpec: true,
+    specs: [],
+    unavailableSessions: [],
+  }
+}
+
+function emptySessionInventory(): WorkspaceLaunchInventory {
+  return {
+    cwd: "/project",
+    currentSpec: { id: "spec-empty", title: "Empty" },
+    currentSessionFile: null,
+    needsNewSpec: false,
+    specs: [{ spec: { id: "spec-empty", title: "Empty" }, sessions: [] }],
+    unavailableSessions: [],
+  }
+}
+
+function inventory(): WorkspaceLaunchInventory {
+  return {
+    cwd: "/project",
+    currentSpec: { id: "spec-alpha", title: "Alpha" },
+    currentSessionFile: "/sessions/alpha-current.jsonl",
+    needsNewSpec: false,
+    specs: [
+      {
+        spec: { id: "spec-alpha", title: "Alpha" },
+        sessions: [
+          {
+            id: "session-alpha-current",
+            file: "/sessions/alpha-current.jsonl",
+            specId: "spec-alpha",
+            specTitle: "Alpha",
+            available: true,
+          },
+          {
+            id: "session-alpha-older",
+            file: "/sessions/alpha-older.jsonl",
+            specId: "spec-alpha",
+            specTitle: "Alpha",
+            available: true,
+          },
+        ],
+      },
+      {
+        spec: { id: "spec-beta", title: "Beta" },
+        sessions: [
+          {
+            id: "session-beta",
+            file: "/sessions/beta.jsonl",
+            specId: "spec-beta",
+            specTitle: "Beta",
+            available: true,
+          },
+        ],
+      },
+    ],
+    unavailableSessions: [],
+  }
+}
diff --git a/src/workspace-session-coordinator.test.ts b/src/workspace-session-coordinator.test.ts
index 2df1b026..81b864fd 100644
--- a/src/workspace-session-coordinator.test.ts
+++ b/src/workspace-session-coordinator.test.ts
@@ -1,13 +1,17 @@
-import { mkdir, mkdtemp, readFile } from "node:fs/promises"
+import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises"
 import { tmpdir } from "node:os"
 import { join } from "node:path"
 
 import { describe, expect, it } from "vitest"
 
-import { SessionManager } from "@earendil-works/pi-coding-agent"
+import {
+  SessionManager,
+  type SessionEntry,
+} from "@earendil-works/pi-coding-agent"
 
 import { projectElicitationExchanges } from "./elicitation-exchange.js"
 import { SESSION_BINDING_TYPE } from "./session-binding.js"
+import { assistantMessage, userMessage, isCustomEntry } from "./test-helpers.js"
 import {
   createWorkspaceSessionCoordinator,
   verifyWorkspaceSessionStores,
@@ -23,7 +27,7 @@ describe("WorkspaceSessionCoordinator", () => {
     const cwd = await mkdtemp(join(tmpdir(), "brunch-ws-"))
     const coordinator = createWorkspaceSessionCoordinator({ cwd })
 
-    const result = await coordinator.startOrCreate({
+    const result = await coordinator.createSetupSession({
       specTitle: "Scratch spec",
     })
 
@@ -52,8 +56,10 @@ describe("WorkspaceSessionCoordinator", () => {
     const cwd = await mkdtemp(join(tmpdir(), "brunch-ws-"))
     const coordinator = createWorkspaceSessionCoordinator({ cwd })
 
-    const first = await coordinator.startOrCreate({ specTitle: "Scratch spec" })
-    const second = await coordinator.createNewSessionForCurrentSpec()
+    const first = await coordinator.createSetupSession({
+      specTitle: "Scratch spec",
+    })
+    const second = await coordinator.createSetupSessionForCurrentSpec()
 
     expect(second.status).toBe("ready")
     if (second.status !== "ready") {
@@ -74,10 +80,16 @@ describe("WorkspaceSessionCoordinator", () => {
     )
     const firstBinding = reloadedFirst
       .getEntries()
-      .find((entry) => entry.customType === SESSION_BINDING_TYPE)
+      .find(
+        (entry) =>
+          isCustomEntry(entry) && entry.customType === SESSION_BINDING_TYPE,
+      )
     const secondBinding = reloadedSecond
       .getEntries()
-      .find((entry) => entry.customType === SESSION_BINDING_TYPE)
+      .find(
+        (entry) =>
+          isCustomEntry(entry) && entry.customType === SESSION_BINDING_TYPE,
+      )
 
     expect(firstBinding).toMatchObject({
       data: { specId: first.spec.id, specTitle: "Scratch spec" },
@@ -108,13 +120,16 @@ describe("WorkspaceSessionCoordinator", () => {
     const cwd = await mkdtemp(join(tmpdir(), "brunch-ws-"))
     const coordinator = createWorkspaceSessionCoordinator({ cwd })
 
-    const result = await coordinator.startOrCreate({
+    const result = await coordinator.createSetupSession({
       specTitle: "Scratch spec",
     })
     const reloaded = SessionManager.open(result.session.file, undefined, cwd)
     const bindings = reloaded
       .getEntries()
-      .filter((entry) => entry.customType === SESSION_BINDING_TYPE)
+      .filter(
+        (entry) =>
+          isCustomEntry(entry) && entry.customType === SESSION_BINDING_TYPE,
+      )
 
     expect(bindings).toHaveLength(1)
     expect(bindings[0]).toMatchObject({
@@ -131,12 +146,12 @@ describe("WorkspaceSessionCoordinator", () => {
     const cwd = await mkdtemp(join(tmpdir(), "brunch-ws-"))
     const coordinator = createWorkspaceSessionCoordinator({ cwd })
 
-    const result = await coordinator.startOrCreate({
+    const result = await coordinator.createSetupSession({
       specTitle: "Scratch spec",
     })
     const reloaded = SessionManager.open(result.session.file, undefined, cwd)
-    reloaded.appendMessage({ role: "assistant", content: "hello" })
-    reloaded.appendMessage({ role: "user", content: "hi" })
+    reloaded.appendMessage(assistantMessage("hello"))
+    reloaded.appendMessage(userMessage("hi"))
 
     const content = await readFile(result.session.file, "utf8")
     const lines = content
@@ -146,7 +161,11 @@ describe("WorkspaceSessionCoordinator", () => {
 
     expect(lines.filter((entry) => entry.type === "session")).toHaveLength(1)
     expect(
-      lines.filter((entry) => entry.customType === SESSION_BINDING_TYPE),
+      lines.filter(
+        (entry) =>
+          isCustomEntry(entry as unknown as SessionEntry) &&
+          (entry as JsonlLine).customType === SESSION_BINDING_TYPE,
+      ),
     ).toHaveLength(1)
   })
 
@@ -154,19 +173,19 @@ describe("WorkspaceSessionCoordinator", () => {
     const cwd = await mkdtemp(join(tmpdir(), "brunch-ws-"))
     const coordinator = createWorkspaceSessionCoordinator({ cwd })
 
-    const result = await coordinator.startOrCreate({
+    const result = await coordinator.createSetupSession({
       specTitle: "Scratch spec",
     })
-    result.session.manager.appendMessage({
-      role: "assistant",
-      content: "hello",
-    })
-    result.session.manager.appendMessage({ role: "user", content: "answer" })
+    result.session.manager.appendMessage(assistantMessage("hello"))
+    result.session.manager.appendMessage(userMessage("answer"))
 
     const reloaded = SessionManager.open(result.session.file, undefined, cwd)
     const bindings = reloaded
       .getEntries()
-      .filter((entry) => entry.customType === SESSION_BINDING_TYPE)
+      .filter(
+        (entry) =>
+          isCustomEntry(entry) && entry.customType === SESSION_BINDING_TYPE,
+      )
 
     expect(bindings).toHaveLength(1)
     expect(bindings[0]).toMatchObject({
@@ -182,15 +201,19 @@ describe("WorkspaceSessionCoordinator", () => {
     const cwd = await mkdtemp(join(tmpdir(), "brunch-ws-"))
     const coordinator = createWorkspaceSessionCoordinator({ cwd })
 
-    const result = await coordinator.startOrCreate({
+    const result = await coordinator.createSetupSession({
       specTitle: "Scratch spec",
     })
     result.session.manager.appendModelChange("test-provider", "test-model")
     result.session.manager.appendThinkingLevelChange("high")
-    await coordinator.bindCurrentSpecToSession(result.session.manager)
-    result.session.manager.appendMessage({ role: "user", content: "hello" })
-    await coordinator.bindCurrentSpecToSession(result.session.manager)
-    result.session.manager.appendMessage({ role: "assistant", content: "hi" })
+    await coordinator.bindCurrentSpecToReplacementSession(
+      result.session.manager,
+    )
+    result.session.manager.appendMessage(userMessage("hello"))
+    await coordinator.bindCurrentSpecToReplacementSession(
+      result.session.manager,
+    )
+    result.session.manager.appendMessage(assistantMessage("hi"))
 
     const content = await readFile(result.session.file, "utf8")
     const sessionHeaderCount = content
@@ -212,14 +235,11 @@ describe("WorkspaceSessionCoordinator", () => {
     const cwd = await mkdtemp(join(tmpdir(), "brunch-ws-"))
     const coordinator = createWorkspaceSessionCoordinator({ cwd })
 
-    const result = await coordinator.startOrCreate({
+    const result = await coordinator.createSetupSession({
       specTitle: "Scratch spec",
     })
-    result.session.manager.appendMessage({
-      role: "assistant",
-      content: "Question",
-    })
-    result.session.manager.appendMessage({ role: "user", content: "Answer" })
+    result.session.manager.appendMessage(assistantMessage("Question"))
+    result.session.manager.appendMessage(userMessage("Answer"))
 
     const beforeReload = projectElicitationExchanges(
       result.session.manager.getBranch(),
@@ -236,9 +256,11 @@ describe("WorkspaceSessionCoordinator", () => {
     const cwd = await mkdtemp(join(tmpdir(), "brunch-ws-"))
     const coordinator = createWorkspaceSessionCoordinator({ cwd })
 
-    const first = await coordinator.startOrCreate({ specTitle: "Scratch spec" })
+    const first = await coordinator.createSetupSession({
+      specTitle: "Scratch spec",
+    })
     const replacementFile = first.session.manager.newSession()
-    await coordinator.bindCurrentSpecToSession(first.session.manager)
+    await coordinator.bindCurrentSpecToReplacementSession(first.session.manager)
 
     expect(replacementFile).toBeDefined()
     const oracle = await verifyWorkspaceSessionStores({
@@ -260,12 +282,284 @@ describe("WorkspaceSessionCoordinator", () => {
     )
   })
 
+  it("inspects current defaults, bound specs, and sessions without activation writes", async () => {
+    const cwd = await mkdtemp(join(tmpdir(), "brunch-ws-"))
+    const coordinator = createWorkspaceSessionCoordinator({ cwd })
+
+    const first = await coordinator.createSetupSession({ specTitle: "Alpha" })
+    first.session.manager.appendMessage(userMessage("first"))
+    const second = await coordinator.createSetupSession({
+      specTitle: "Beta",
+      createNewSpec: true,
+    })
+    const beforeState = await readFile(
+      join(cwd, ".brunch", "state.json"),
+      "utf8",
+    )
+    const beforeFirst = await readFile(first.session.file, "utf8")
+    const beforeSecond = await readFile(second.session.file, "utf8")
+
+    const inventory = await coordinator.inspectWorkspace()
+
+    expect(inventory.cwd).toBe(cwd)
+    expect(inventory.needsNewSpec).toBe(false)
+    expect(inventory.currentSpec).toEqual(second.spec)
+    expect(inventory.currentSessionFile).toBe(second.session.file)
+    expect(inventory.specs.map(({ spec }) => spec.title)).toEqual([
+      "Alpha",
+      "Beta",
+    ])
+    expect(inventory.specs[0]?.sessions).toEqual([
+      expect.objectContaining({
+        id: first.session.id,
+        file: first.session.file,
+        specId: first.spec.id,
+        specTitle: "Alpha",
+        available: true,
+      }),
+    ])
+    expect(inventory.specs[1]?.sessions).toEqual([
+      expect.objectContaining({
+        id: second.session.id,
+        file: second.session.file,
+        specId: second.spec.id,
+        specTitle: "Beta",
+        available: true,
+      }),
+    ])
+    expect(inventory.unavailableSessions).toEqual([])
+    await expect(
+      readFile(join(cwd, ".brunch", "state.json"), "utf8"),
+    ).resolves.toBe(beforeState)
+    await expect(readFile(first.session.file, "utf8")).resolves.toBe(
+      beforeFirst,
+    )
+    await expect(readFile(second.session.file, "utf8")).resolves.toBe(
+      beforeSecond,
+    )
+  })
+
+  it("inspects an empty workspace without creating session files", async () => {
+    const cwd = await mkdtemp(join(tmpdir(), "brunch-ws-"))
+    const coordinator = createWorkspaceSessionCoordinator({ cwd })
+
+    const inventory = await coordinator.inspectWorkspace()
+
+    expect(inventory).toMatchObject({
+      cwd,
+      currentSpec: null,
+      currentSessionFile: null,
+      needsNewSpec: true,
+      specs: [],
+      unavailableSessions: [],
+    })
+    await expect(
+      readFile(join(cwd, ".brunch", "sessions", "missing.jsonl"), "utf8"),
+    ).rejects.toMatchObject({ code: "ENOENT" })
+  })
+
+  it("marks unbound or incompatible sessions unavailable during inventory", async () => {
+    const cwd = await mkdtemp(join(tmpdir(), "brunch-ws-"))
+    const coordinator = createWorkspaceSessionCoordinator({ cwd })
+    const ready = await coordinator.createSetupSession({ specTitle: "Alpha" })
+    const unboundFile = join(cwd, ".brunch", "sessions", "unbound.jsonl")
+    const mismatchedFile = join(cwd, ".brunch", "sessions", "mismatched.jsonl")
+    await writeFile(
+      unboundFile,
+      `${JSON.stringify({ type: "session", id: "unbound-session", cwd })}\n`,
+      "utf8",
+    )
+    await writeFile(
+      mismatchedFile,
+      `${JSON.stringify({ type: "session", id: "header-session", cwd })}\n${JSON.stringify(
+        {
+          type: "custom",
+          customType: SESSION_BINDING_TYPE,
+          data: {
+            schemaVersion: 1,
+            sessionId: "other-session",
+            specId: ready.spec.id,
+            specTitle: ready.spec.title,
+          },
+        },
+      )}\n`,
+      "utf8",
+    )
+    const beforeUnbound = await readFile(unboundFile, "utf8")
+    const beforeMismatched = await readFile(mismatchedFile, "utf8")
+
+    const inventory = await coordinator.inspectWorkspace()
+
+    expect(inventory.specs).toHaveLength(1)
+    expect(inventory.specs[0]?.sessions).toHaveLength(1)
+    expect(inventory.unavailableSessions).toEqual([
+      expect.objectContaining({
+        file: mismatchedFile,
+        reason: "incompatible_binding",
+      }),
+      expect.objectContaining({ file: unboundFile, reason: "missing_binding" }),
+    ])
+    await expect(readFile(unboundFile, "utf8")).resolves.toBe(beforeUnbound)
+    await expect(readFile(mismatchedFile, "utf8")).resolves.toBe(
+      beforeMismatched,
+    )
+  })
+
+  it("activates explicit open and continue decisions as the current workspace", async () => {
+    const cwd = await mkdtemp(join(tmpdir(), "brunch-ws-"))
+    const coordinator = createWorkspaceSessionCoordinator({ cwd })
+    const first = await coordinator.createSetupSession({ specTitle: "Alpha" })
+    const second = await coordinator.createSetupSession({
+      specTitle: "Beta",
+      createNewSpec: true,
+    })
+
+    const opened = await coordinator.activateWorkspace({
+      action: "openSession",
+      specId: first.spec.id,
+      sessionFile: first.session.file,
+    })
+
+    expect(opened.status).toBe("ready")
+    if (opened.status !== "ready") {
+      return
+    }
+    expect(opened.spec).toEqual(first.spec)
+    expect(opened.session.id).toBe(first.session.id)
+    expect(opened.session.file).toBe(first.session.file)
+    expect(opened.chrome.spec).toEqual(first.spec)
+
+    const continued = await coordinator.activateWorkspace({
+      action: "continue",
+      specId: second.spec.id,
+      sessionFile: second.session.file,
+    })
+
+    expect(continued.status).toBe("ready")
+    if (continued.status !== "ready") {
+      return
+    }
+    expect(continued.spec).toEqual(second.spec)
+    expect(continued.session.id).toBe(second.session.id)
+    expect(
+      JSON.parse(await readFile(join(cwd, ".brunch", "state.json"), "utf8")),
+    ).toMatchObject({
+      currentSpec: second.spec,
+      currentSessionFile: second.session.file,
+    })
+  })
+
+  it("activates a new session decision as a binding-only session for the selected spec", async () => {
+    const cwd = await mkdtemp(join(tmpdir(), "brunch-ws-"))
+    const coordinator = createWorkspaceSessionCoordinator({ cwd })
+    const first = await coordinator.createSetupSession({ specTitle: "Alpha" })
+    first.session.manager.appendMessage(userMessage("preserve me"))
+    const beforeFirst = await readFile(first.session.file, "utf8")
+
+    const created = await coordinator.activateWorkspace({
+      action: "newSession",
+      specId: first.spec.id,
+    })
+
+    expect(created.status).toBe("ready")
+    if (created.status !== "ready") {
+      return
+    }
+    expect(created.spec).toEqual(first.spec)
+    expect(created.session.id).not.toBe(first.session.id)
+    await expect(readFile(first.session.file, "utf8")).resolves.toBe(
+      beforeFirst,
+    )
+    const createdContent = await readFile(created.session.file, "utf8")
+    expect(createdContent).toContain(SESSION_BINDING_TYPE)
+    expect(createdContent).not.toContain("preserve me")
+    const oracle = await verifyWorkspaceSessionStores({
+      cwd,
+      expectedSessionCount: 2,
+    })
+    expect(oracle.ok).toBe(true)
+  })
+
+  it("activates a new spec decision by creating a bound current session", async () => {
+    const cwd = await mkdtemp(join(tmpdir(), "brunch-ws-"))
+    const coordinator = createWorkspaceSessionCoordinator({ cwd })
+
+    const created = await coordinator.activateWorkspace({
+      action: "newSpec",
+      title: "Gamma",
+    })
+
+    expect(created.status).toBe("ready")
+    if (created.status !== "ready") {
+      return
+    }
+    expect(created.spec.title).toBe("Gamma")
+    expect(created.session.id).toMatch(/[\da-f-]+/iu)
+    const oracle = await verifyWorkspaceSessionStores({
+      cwd,
+      expectedSessionCount: 1,
+    })
+    expect(oracle.ok).toBe(true)
+  })
+
+  it("activates cancel without mutating workspace state or session files", async () => {
+    const cwd = await mkdtemp(join(tmpdir(), "brunch-ws-"))
+    const coordinator = createWorkspaceSessionCoordinator({ cwd })
+    const ready = await coordinator.createSetupSession({ specTitle: "Alpha" })
+    const beforeState = await readFile(
+      join(cwd, ".brunch", "state.json"),
+      "utf8",
+    )
+    const beforeSession = await readFile(ready.session.file, "utf8")
+
+    const result = await coordinator.activateWorkspace({ action: "cancel" })
+
+    expect(result.status).toBe("cancelled")
+    await expect(
+      readFile(join(cwd, ".brunch", "state.json"), "utf8"),
+    ).resolves.toBe(beforeState)
+    await expect(readFile(ready.session.file, "utf8")).resolves.toBe(
+      beforeSession,
+    )
+  })
+
+  it("refuses to activate mismatched or unavailable sessions", async () => {
+    const cwd = await mkdtemp(join(tmpdir(), "brunch-ws-"))
+    const coordinator = createWorkspaceSessionCoordinator({ cwd })
+    const ready = await coordinator.createSetupSession({ specTitle: "Alpha" })
+    const unavailableFile = join(
+      cwd,
+      ".brunch",
+      "sessions",
+      "unavailable.jsonl",
+    )
+    await writeFile(
+      unavailableFile,
+      `${JSON.stringify({ type: "session", id: "unavailable-session", cwd })}\n`,
+      "utf8",
+    )
+
+    const unavailable = await coordinator.activateWorkspace({
+      action: "openSession",
+      specId: ready.spec.id,
+      sessionFile: unavailableFile,
+    })
+    const mismatched = await coordinator.activateWorkspace({
+      action: "openSession",
+      specId: "spec-missing",
+      sessionFile: ready.session.file,
+    })
+
+    expect(unavailable.status).toBe("needs_human")
+    expect(mismatched.status).toBe("needs_human")
+  })
+
   it("asks for spec selection when no current spec exists and creation is not allowed", async () => {
     const cwd = await mkdtemp(join(tmpdir(), "brunch-ws-"))
     await mkdir(join(cwd, ".brunch"), { recursive: true })
 
     const coordinator = createWorkspaceSessionCoordinator({ cwd })
-    const result = await coordinator.openExisting()
+    const result = await coordinator.openDefaultWorkspace()
 
     expect(result.status).toBe("select_spec")
     expect(result.chrome.cwd).toBe(cwd)
diff --git a/src/workspace-session-coordinator.ts b/src/workspace-session-coordinator.ts
index b2a63588..9dd0ea8b 100644
--- a/src/workspace-session-coordinator.ts
+++ b/src/workspace-session-coordinator.ts
@@ -62,21 +62,111 @@ export interface WorkspaceSessionNeedsHumanState {
   chrome: WorkspaceSessionChromeState
 }
 
+export interface WorkspaceSessionCancelledState {
+  status: "cancelled"
+  cwd: string
+  chrome: WorkspaceSessionChromeState
+}
+
 export type WorkspaceSessionState = WorkspaceSessionReadyState | WorkspaceSessionSelectSpecState | WorkspaceSessionNeedsHumanState
 
-export interface WorkspaceSessionCoordinator {
-  openExisting(): Promise<WorkspaceSessionState>
-  startOrCreate(options?: {
+export interface WorkspaceContinueDecision {
+  action: "continue"
+  specId: string
+  sessionFile: string
+}
+
+export interface WorkspaceOpenSessionDecision {
+  action: "openSession"
+  specId: string
+  sessionFile: string
+}
+
+export interface WorkspaceNewSessionDecision {
+  action: "newSession"
+  specId: string
+}
+
+export interface WorkspaceNewSpecDecision {
+  action: "newSpec"
+  title: string
+}
+
+export interface WorkspaceCancelDecision {
+  action: "cancel"
+}
+
+export type SpecSessionActivationDecision = WorkspaceContinueDecision | WorkspaceOpenSessionDecision | WorkspaceNewSessionDecision | WorkspaceNewSpecDecision | WorkspaceCancelDecision
+
+export type WorkspaceActivationState = WorkspaceSessionReadyState | WorkspaceSessionNeedsHumanState | WorkspaceSessionCancelledState
+
+export interface WorkspaceLaunchSession {
+  id: string
+  file: string
+  specId: string
+  specTitle: string
+  name?: string
+  available: true
+}
+
+export interface WorkspaceLaunchSpec {
+  spec: WorkspaceSpecState
+  sessions: WorkspaceLaunchSession[]
+}
+
+export type WorkspaceUnavailableSessionReason = "missing_header" | "missing_binding" | "incompatible_binding"
+
+export interface WorkspaceUnavailableSession {
+  file: string
+  reason: WorkspaceUnavailableSessionReason
+  available: false
+}
+
+export interface WorkspaceLaunchInventory {
+  cwd: string
+  currentSpec: WorkspaceSpecState | null
+  currentSessionFile: string | null
+  needsNewSpec: boolean
+  specs: WorkspaceLaunchSpec[]
+  unavailableSessions: WorkspaceUnavailableSession[]
+}
+
+export interface SpecSessionActivationCoordinator {
+  inspectWorkspace(): Promise<WorkspaceLaunchInventory>
+  activateWorkspace(
+    decision: SpecSessionActivationDecision,
+  ): Promise<WorkspaceActivationState>
+}
+
+export interface DefaultWorkspaceCoordinator {
+  openDefaultWorkspace(): Promise<WorkspaceSessionState>
+}
+
+export interface WorkspaceSetupCoordinator {
+  createSetupSession(options?: {
     specTitle?: string
     createNewSpec?: boolean
   }): Promise<WorkspaceSessionReadyState>
-  createNewSessionForCurrentSpec(): Promise<WorkspaceSessionState>
-  bindCurrentSpecToSession(
+  createSetupSessionForCurrentSpec(): Promise<WorkspaceSessionState>
+}
+
+export interface WorkspaceSessionBoundaryCoordinator {
+  bindCurrentSpecToReplacementSession(
     manager: SessionManager,
   ): Promise<WorkspaceSessionReadyState>
-  deriveChromeState(): Promise<WorkspaceSessionChromeState>
 }
 
+export interface WorkspaceDefaultChromeCoordinator {
+  deriveDefaultChromeState(): Promise<WorkspaceSessionChromeState>
+}
+
+export interface WorkspaceSessionCoordinator
+  extends SpecSessionActivationCoordinator,
+    DefaultWorkspaceCoordinator,
+    WorkspaceSetupCoordinator,
+    WorkspaceSessionBoundaryCoordinator,
+    WorkspaceDefaultChromeCoordinator {}
+
 export function createWorkspaceSessionCoordinator(options?: {
   cwd?: string
 }): WorkspaceSessionCoordinator {
@@ -91,7 +181,70 @@ class FileWorkspaceSessionCoordinator implements WorkspaceSessionCoordinator {
     this.#cwd = cwd
   }
 
-  async openExisting(): Promise<WorkspaceSessionState> {
+  async inspectWorkspace(): Promise<WorkspaceLaunchInventory> {
+    return inspectWorkspaceInventory(this.#cwd)
+  }
+
+  async activateWorkspace(
+    decision: SpecSessionActivationDecision,
+  ): Promise<WorkspaceActivationState> {
+    if (decision.action === "cancel") {
+      const state = await readWorkspaceState(this.#cwd)
+      return {
+        status: "cancelled",
+        cwd: this.#cwd,
+        chrome: chromeState(this.#cwd, state?.currentSpec ?? null),
+      }
+    }
+
+    if (decision.action === "newSpec") {
+      return this.createSetupSession({
+        specTitle: decision.title,
+        createNewSpec: true,
+      })
+    }
+
+    const inventory = await inspectWorkspaceInventory(this.#cwd)
+    const spec = inventory.specs.find(
+      (candidate) => candidate.spec.id === decision.specId,
+    )
+
+    if (!spec) {
+      return needsHumanState(
+        this.#cwd,
+        inventory.currentSpec,
+        "Selected spec is not available in this workspace.",
+      )
+    }
+
+    if (decision.action === "newSession") {
+      const session = await createBoundSession(this.#cwd, spec.spec)
+      await writeCurrentWorkspaceState(this.#cwd, spec.spec, session.file)
+      return readyState(this.#cwd, spec.spec, session)
+    }
+
+    const session = spec.sessions.find(
+      (candidate) => candidate.file === decision.sessionFile,
+    )
+    if (!session) {
+      return needsHumanState(
+        this.#cwd,
+        inventory.currentSpec,
+        "Selected session is not available for the selected spec.",
+      )
+    }
+
+    const manager = SessionManager.open(
+      session.file,
+      sessionDir(this.#cwd),
+      this.#cwd,
+    )
+    const opened = bindSessionToSpec(manager, spec.spec)
+    await writeCurrentWorkspaceState(this.#cwd, spec.spec, opened.file)
+    return readyState(this.#cwd, spec.spec, opened)
+  }
+
+  async openDefaultWorkspace(): Promise<WorkspaceSessionState> {
     const state = await readWorkspaceState(this.#cwd)
     if (!state) {
       return {
@@ -110,7 +263,7 @@ class FileWorkspaceSessionCoordinator implements WorkspaceSessionCoordinator {
     return readyState(this.#cwd, state.currentSpec, session)
   }
 
-  async startOrCreate(options?: {
+  async createSetupSession(options?: {
     specTitle?: string
     createNewSpec?: boolean
   }): Promise<WorkspaceSessionReadyState> {
@@ -125,7 +278,7 @@ class FileWorkspaceSessionCoordinator implements WorkspaceSessionCoordinator {
     return readyState(this.#cwd, spec, session)
   }
 
-  async createNewSessionForCurrentSpec(): Promise<WorkspaceSessionState> {
+  async createSetupSessionForCurrentSpec(): Promise<WorkspaceSessionState> {
     const state = await readWorkspaceState(this.#cwd)
     if (!state) {
       return {
@@ -141,7 +294,7 @@ class FileWorkspaceSessionCoordinator implements WorkspaceSessionCoordinator {
     return readyState(this.#cwd, state.currentSpec, session)
   }
 
-  async bindCurrentSpecToSession(
+  async bindCurrentSpecToReplacementSession(
     manager: SessionManager,
   ): Promise<WorkspaceSessionReadyState> {
     const state = await readWorkspaceState(this.#cwd)
@@ -154,7 +307,7 @@ class FileWorkspaceSessionCoordinator implements WorkspaceSessionCoordinator {
     return readyState(this.#cwd, state.currentSpec, session)
   }
 
-  async deriveChromeState(): Promise<WorkspaceSessionChromeState> {
+  async deriveDefaultChromeState(): Promise<WorkspaceSessionChromeState> {
     const state = await readWorkspaceState(this.#cwd)
     return chromeState(this.#cwd, state?.currentSpec ?? null)
   }
@@ -280,6 +433,96 @@ async function readWorkspaceState(
   }
 }
 
+async function inspectWorkspaceInventory(
+  cwd: string,
+): Promise<WorkspaceLaunchInventory> {
+  const state = await readWorkspaceState(cwd)
+  const files = await listSessionFiles(cwd)
+  const specsById = new Map<string, WorkspaceLaunchSpec>()
+  const unavailableSessions: WorkspaceUnavailableSession[] = []
+
+  if (state) {
+    specsById.set(state.currentSpec.id, {
+      spec: state.currentSpec,
+      sessions: [],
+    })
+  }
+
+  for (const file of files) {
+    const session = await inspectSessionFile(file)
+    if (session.available) {
+      const spec = getOrCreateLaunchSpec(specsById, {
+        id: session.specId,
+        title: session.specTitle,
+      })
+      spec.sessions.push(session)
+    } else {
+      unavailableSessions.push(session)
+    }
+  }
+
+  const specs = [...specsById.values()]
+    .map((spec) => ({
+      ...spec,
+      sessions: spec.sessions.sort((left, right) =>
+        left.file.localeCompare(right.file),
+      ),
+    }))
+    .sort((left, right) => left.spec.title.localeCompare(right.spec.title))
+
+  return {
+    cwd,
+    currentSpec: state?.currentSpec ?? null,
+    currentSessionFile: state?.currentSessionFile ?? null,
+    needsNewSpec: specs.length === 0,
+    specs,
+    unavailableSessions: unavailableSessions.sort((left, right) =>
+      left.file.localeCompare(right.file),
+    ),
+  }
+}
+
+type InspectedSessionFile = WorkspaceLaunchSession | WorkspaceUnavailableSession
+
+async function inspectSessionFile(file: string): Promise<InspectedSessionFile> {
+  const entries = await readJsonl(file)
+  const header = entries.find(isSessionHeader)
+  if (!header) {
+    return { file, reason: "missing_header", available: false }
+  }
+
+  const bindings = entries.filter(isSessionBindingEntry)
+  if (bindings.length === 0) {
+    return { file, reason: "missing_binding", available: false }
+  }
+
+  const binding = bindings[0]!
+  if (bindings.length !== 1 || binding.data.sessionId !== header.id) {
+    return { file, reason: "incompatible_binding", available: false }
+  }
+
+  return {
+    id: header.id,
+    file,
+    specId: binding.data.specId,
+    specTitle: binding.data.specTitle,
+    available: true,
+  }
+}
+
+function getOrCreateLaunchSpec(
+  specsById: Map<string, WorkspaceLaunchSpec>,
+  spec: WorkspaceSpecState,
+): WorkspaceLaunchSpec {
+  const existing = specsById.get(spec.id)
+  if (existing) {
+    return existing
+  }
+  const created = { spec, sessions: [] }
+  specsById.set(spec.id, created)
+  return created
+}
+
 async function writeWorkspaceState(
   cwd: string,
   state: WorkspaceStateFile,
@@ -314,6 +557,19 @@ function readyState(
   }
 }
 
+function needsHumanState(
+  cwd: string,
+  spec: WorkspaceSpecState | null,
+  reason: string,
+): WorkspaceSessionNeedsHumanState {
+  return {
+    status: "needs_human",
+    cwd,
+    reason,
+    chrome: chromeState(cwd, spec),
+  }
+}
+
 function chromeState(
   cwd: string,
   spec: WorkspaceSpecState | null,
diff --git a/tsconfig.build.json b/tsconfig.build.json
new file mode 100644
index 00000000..76f63146
--- /dev/null
+++ b/tsconfig.build.json
@@ -0,0 +1,13 @@
+{
+	"extends": "./tsconfig.json",
+	"compilerOptions": {
+		"noEmit": false,
+		"rootDir": "./src",
+		"outDir": "./dist",
+		"declaration": true,
+		"declarationMap": true,
+		"sourceMap": true
+	},
+	"include": ["src/**/*"],
+	"exclude": ["node_modules", "dist", "archive", "src/**/*.test.ts", "src/**/*.test.tsx", ".pi"]
+}
diff --git a/tsconfig.json b/tsconfig.json
index 21d28cf6..ba1bf396 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -3,10 +3,13 @@
 		"target": "ES2022",
 		"module": "NodeNext",
 		"moduleResolution": "NodeNext",
-		"lib": ["ES2022", "DOM", "DOM.Iterable"],
+		"lib": [
+			"ES2022",
+			"DOM",
+			"DOM.Iterable"
+		],
 		"jsx": "react-jsx",
-		"outDir": "./dist",
-		"rootDir": "./src",
+		"noEmit": true,
 		"strict": true,
 		"noImplicitAny": true,
 		"noImplicitOverride": true,
@@ -19,22 +22,16 @@
 		"forceConsistentCasingInFileNames": true,
 		"skipLibCheck": true,
 		"resolveJsonModule": true,
-		"declaration": true,
-		"declarationMap": true,
-		"sourceMap": true,
 		"isolatedModules": true,
 		"verbatimModuleSyntax": true
 	},
-	"include": ["src/**/*"],
+	"include": [
+		"src/**/*",
+		".pi/extensions/**/*.ts"
+	],
 	"exclude": [
-		"src/**/*.test.ts",
-		"src/**/*.test.tsx",
 		"node_modules",
 		"dist",
-		"archive",
-		"docs",
-		"memory",
-		"scripts",
-		".brunch-fixtures"
+		"archive"
 	]
 }