codex-autorunner 1.1.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

codex_autorunner/core/about_car.py

@@ -13,9 +13,19 @@ from .config import (
 
 ABOUT_CAR_BASENAME = "ABOUT_CAR.md"
 ABOUT_CAR_REL_PATH = Path(".codex-autorunner") / ABOUT_CAR_BASENAME
+TICKET_FLOW_QUICKSTART_BASENAME = "TICKET_FLOW_QUICKSTART.md"
+TICKET_FLOW_QUICKSTART_REL_PATH = (
+    Path(".codex-autorunner") / TICKET_FLOW_QUICKSTART_BASENAME
+)
+TICKETS_AGENTS_BASENAME = "AGENTS.md"
+TICKETS_AGENTS_REL_PATH = (
+    Path(".codex-autorunner") / "tickets" / TICKETS_AGENTS_BASENAME
+)
 
 # If this marker is present, codex-autorunner may safely refresh the file content.
 ABOUT_CAR_GENERATED_MARKER = "<!-- CAR:AUTOGENERATED -->"
+TICKET_FLOW_QUICKSTART_GENERATED_MARKER = "<!-- CAR:TICKET_FLOW_QUICKSTART -->"
+TICKETS_AGENTS_GENERATED_MARKER = "<!-- CAR:TICKETS_AGENTS -->"
 
 CAR_CONTEXT_KEYWORDS = (
     "car",
@@ -76,8 +86,11 @@ def build_about_car_markdown(
         "You are running inside **Codex Autorunner (CAR)**.\n\n"
         "CAR uses a ticket-first workflow.\n\n"
         "## Required for operation\n"
-        "- Tickets live under `.codex-autorunner/tickets/`.\n"
+        "- Tickets live under `.codex-autorunner/tickets/` (per-repo/worktree).\n"
+        "- If the user provides ticket files, place them in the repo's `.codex-autorunner/tickets/` folder.\n"
         "- Lint ticket frontmatter after edits (runs against all tickets): `python3 .codex-autorunner/bin/lint_tickets.py`.\n\n"
+        "## Ticket flow quickstart\n"
+        f"- Read `{_display_path(repo_root, TICKET_FLOW_QUICKSTART_REL_PATH)}` for CLI entrypoints + gotchas.\n\n"
         "## Optional workspace docs\n"
         "- **Active context**: "
         f"`{active_context_disp}`\n"
@@ -96,6 +109,12 @@ def build_about_car_markdown(
         "- Use `.codex-autorunner/bin/ticket_tool.py` to list/create/insert/move tickets; it is portable and venv-free.\n"
         '- Common workflows: insert gap before N (`python3 .codex-autorunner/bin/ticket_tool.py insert --before N`); move a block (`... move --start A --end B --to T`); create with auto-quoted frontmatter (`... create --title "Fix #123" --agent codex`).\n'
         "- After any ticket edits, lint all tickets: `python3 .codex-autorunner/bin/lint_tickets.py`.\n\n"
+        "## Ticket templates (optional)\n"
+        "- CAR can fetch ticket templates from configured git repos (treat templates as code).\n"
+        "- Fetch (prints template to stdout): `car templates fetch <repo_id>:<path>[@<ref>]`\n"
+        "- Pin to a commit for determinism: `...@<commit_sha>`\n"
+        "- Trusted repos skip scanning. Untrusted repos are scanned (cached by blob SHA) before content is returned.\n"
+        "- If fetch or scan fails, pause and notify the user rather than guessing.\n\n"
         "## How CAR works (short)\n"
         "- The web UI provides ticket editing + unified file chat.\n"
         "- `car serve` starts the hub web UI. The **Terminal** tab launches the configured `codex` binary in a PTY.\n"
@@ -144,6 +163,54 @@ def ensure_about_car_file_for_repo(
     return path
 
 
+def build_ticket_flow_quickstart_markdown(*, repo_root: Path) -> str:
+    ticket_dir = ".codex-autorunner/tickets/"
+    return (
+        f"{TICKET_FLOW_QUICKSTART_GENERATED_MARKER}\n"
+        "# Ticket Flow Quickstart\n\n"
+        "## Start ticket flow via CLI\n"
+        "- Bootstrap the first run (creates TICKET-001 if needed):\n"
+        "  `car flow ticket_flow bootstrap --repo <path>`\n"
+        "  (alias: `car ticket-flow bootstrap --repo <path>`)\n"
+        "- Start/resume without seeding tickets:\n"
+        "  `car flow ticket_flow start --repo <path>`\n"
+        "- Check status:\n"
+        "  `car flow ticket_flow status --repo <path> [--run-id <uuid>]`\n"
+        "- Resume/stop:\n"
+        "  `car flow ticket_flow resume --repo <path> [--run-id <uuid>]`\n"
+        "  `car flow ticket_flow stop --repo <path> [--run-id <uuid>]`\n\n"
+        "## Where tickets live\n"
+        f"- Tickets are per-repo/worktree under `{ticket_dir}`.\n"
+        "- If the user provides ticket files, save them directly into that folder.\n\n"
+        "## Common gotchas\n"
+        "- Hub vs repo: ticket flows run per-repo; CLI commands need a repo path.\n"
+        "- `--repo` expects a filesystem path, not a hub repo_id.\n"
+        "- Each worktree has its own `.codex-autorunner/` directory.\n"
+        "- If this repo/worktree lives under a hub, it must be registered in the hub manifest to show up in the hub UI. Run: `car hub scan` (or create it via `car hub worktree create`).\n"
+    )
+
+
+def build_tickets_agents_markdown(*, repo_root: Path) -> str:
+    quickstart_path = _display_path(repo_root, TICKET_FLOW_QUICKSTART_REL_PATH)
+    return (
+        f"{TICKETS_AGENTS_GENERATED_MARKER}\n"
+        "# Tickets — AGENTS\n\n"
+        "This folder is the authoritative ticket queue for this repo/worktree.\n\n"
+        "## Ticket files\n"
+        "- Store work items as `TICKET-###*.md` (ordered by number).\n"
+        "- Keep frontmatter `done: true|false` in sync with completion.\n"
+        "- After edits, lint tickets: `python3 .codex-autorunner/bin/lint_tickets.py`.\n\n"
+        "## Ticket CLI (portable)\n"
+        "- List: `python3 .codex-autorunner/bin/ticket_tool.py list`\n"
+        '- Create: `python3 .codex-autorunner/bin/ticket_tool.py create --title "..." --agent codex`\n'
+        "- Insert gap: `python3 .codex-autorunner/bin/ticket_tool.py insert --before N`\n"
+        "- Move block: `python3 .codex-autorunner/bin/ticket_tool.py move --start A --end B --to T`\n"
+        "- Lint: `python3 .codex-autorunner/bin/ticket_tool.py lint`\n\n"
+        "## Ticket flow (runner)\n"
+        f"- See `{quickstart_path}` for `car flow ticket_flow ...` commands.\n"
+    )
+
+
 def ensure_about_car_file(config: Config, *, force: bool = False) -> Path:
     """Config-aware wrapper that uses configured doc paths."""
     repo_root = config.root
@@ -153,3 +220,49 @@ def ensure_about_car_file(config: Config, *, force: bool = False) -> Path:
         "spec": config.doc_path("spec"),
     }
     return ensure_about_car_file_for_repo(repo_root, doc_paths=docs, force=force)
+
+
+def ensure_ticket_flow_quickstart_file_for_repo(
+    repo_root: Path, *, force: bool = False
+) -> Path:
+    path = repo_root / TICKET_FLOW_QUICKSTART_REL_PATH
+    path.parent.mkdir(parents=True, exist_ok=True)
+    content = build_ticket_flow_quickstart_markdown(repo_root=repo_root)
+    if content and not content.endswith("\n"):
+        content += "\n"
+
+    if path.exists() and not force:
+        try:
+            existing = path.read_text(encoding="utf-8")
+        except OSError:
+            existing = ""
+        if TICKET_FLOW_QUICKSTART_GENERATED_MARKER not in existing:
+            return path
+        if existing == content:
+            return path
+
+    path.write_text(content, encoding="utf-8")
+    return path
+
+
+def ensure_tickets_agents_file_for_repo(
+    repo_root: Path, *, force: bool = False
+) -> Path:
+    path = repo_root / TICKETS_AGENTS_REL_PATH
+    path.parent.mkdir(parents=True, exist_ok=True)
+    content = build_tickets_agents_markdown(repo_root=repo_root)
+    if content and not content.endswith("\n"):
+        content += "\n"
+
+    if path.exists() and not force:
+        try:
+            existing = path.read_text(encoding="utf-8")
+        except OSError:
+            existing = ""
+        if TICKETS_AGENTS_GENERATED_MARKER not in existing:
+            return path
+        if existing == content:
+            return path
+
+    path.write_text(content, encoding="utf-8")
+    return path

codex_autorunner/core/app_server_threads.py

@@ -17,6 +17,8 @@ FILE_CHAT_KEY = "file_chat"
 FILE_CHAT_OPENCODE_KEY = "file_chat.opencode"
 FILE_CHAT_PREFIX = "file_chat."
 FILE_CHAT_OPENCODE_PREFIX = "file_chat.opencode."
+PMA_KEY = "pma"
+PMA_OPENCODE_KEY = "pma.opencode"
 
 LOGGER = logging.getLogger("codex_autorunner.app_server")
 
@@ -24,6 +26,8 @@ LOGGER = logging.getLogger("codex_autorunner.app_server")
 FEATURE_KEYS = {
     FILE_CHAT_KEY,
     FILE_CHAT_OPENCODE_KEY,
+    PMA_KEY,
+    PMA_OPENCODE_KEY,
     "autorunner",
     "autorunner.opencode",
 }
@@ -92,6 +96,8 @@ class AppServerThreadRegistry:
             "file_chat_opencode": threads.get(FILE_CHAT_OPENCODE_KEY),
             "autorunner": threads.get("autorunner"),
             "autorunner_opencode": threads.get("autorunner.opencode"),
+            "pma": threads.get(PMA_KEY),
+            "pma_opencode": threads.get(PMA_OPENCODE_KEY),
         }
         notice = self.corruption_notice()
         if notice:

codex_autorunner/core/config.py

@@ -12,6 +12,7 @@ import yaml
 
 from ..housekeeping import HousekeepingConfig, parse_housekeeping_config
 from .path_utils import ConfigPathError, resolve_config_path
+from .utils import atomic_write
 
 logger = logging.getLogger("codex_autorunner.core.config")
 
@@ -138,6 +139,7 @@ DEFAULT_REPO_CONFIG: Dict[str, Any] = {
         "approval_mode": "yolo",
         # Keep ticket_flow deterministic by default; surfaces can tighten this.
         "default_approval_decision": "accept",
+        "include_previous_ticket_context": False,
     },
     "git": {
         "auto_commit": False,
@@ -197,6 +199,7 @@ DEFAULT_REPO_CONFIG: Dict[str, Any] = {
     },
     "opencode": {
         "session_stall_timeout_seconds": 60,
+        "max_text_chars": 20000,
     },
     "usage": {
         "cache_scope": "global",
@@ -425,6 +428,9 @@ DEFAULT_REPO_CONFIG: Dict[str, Any] = {
             },
         ],
     },
+    "storage": {
+        "durable_writes": False,
+    },
 }
 
 REPO_DEFAULT_KEYS = {
@@ -460,12 +466,38 @@ REPO_SHARED_KEYS = {
     "housekeeping",
     "update",
     "usage",
+    "templates",
 }
 
 DEFAULT_HUB_CONFIG: Dict[str, Any] = {
     "version": CONFIG_VERSION,
     "mode": "hub",
     "repo_defaults": DEFAULT_REPO_DEFAULTS,
+    "pma": {
+        "enabled": True,
+        "default_agent": "codex",
+        "model": None,
+        "reasoning": None,
+        "max_upload_bytes": 10_000_000,
+        "max_repos": 25,
+        "max_messages": 10,
+        "max_text_chars": 800,
+        # PMA durable workspace docs (hub-level)
+        "docs_max_chars": 12_000,
+        "active_context_max_lines": 200,
+        "context_log_tail_lines": 120,
+    },
+    "templates": {
+        "enabled": True,
+        "repos": [
+            {
+                "id": "blessed",
+                "url": "https://github.com/Git-on-my-level/car-ticket-templates",
+                "trusted": True,
+                "default_ref": "main",
+            }
+        ],
+    },
     "agents": {
         "codex": {
             "binary": "codex",
@@ -618,6 +650,7 @@ DEFAULT_HUB_CONFIG: Dict[str, Any] = {
     },
     "opencode": {
         "session_stall_timeout_seconds": 60,
+        "max_text_chars": 20000,
     },
     "usage": {
         "cache_scope": "global",
@@ -724,6 +757,9 @@ DEFAULT_HUB_CONFIG: Dict[str, Any] = {
             },
         ],
     },
+    "storage": {
+        "durable_writes": False,
+    },
 }
 
 
@@ -810,6 +846,24 @@ class AppServerConfig:
 @dataclasses.dataclass
 class OpenCodeConfig:
     session_stall_timeout_seconds: Optional[float]
+    max_text_chars: Optional[int]
+
+
+@dataclasses.dataclass
+class PmaConfig:
+    enabled: bool
+    default_agent: str
+    model: Optional[str]
+    reasoning: Optional[str]
+    max_upload_bytes: int
+    max_repos: int
+    max_messages: int
+    max_text_chars: int
+    # Hub-level PMA durable workspace docs
+    docs_max_chars: int = 12_000
+    active_context_max_lines: int = 200
+    context_log_tail_lines: int = 120
+    dispatch_interception_enabled: bool = False
 
 
 @dataclasses.dataclass
@@ -827,6 +881,20 @@ class AgentConfig:
     subagent_models: Optional[Dict[str, str]]
 
 
+@dataclasses.dataclass(frozen=True)
+class TemplateRepoConfig:
+    id: str
+    url: str
+    trusted: bool
+    default_ref: str
+
+
+@dataclasses.dataclass(frozen=True)
+class TemplatesConfig:
+    enabled: bool
+    repos: List[TemplateRepoConfig]
+
+
 @dataclasses.dataclass
 class RepoConfig:
     raw: Dict[str, Any]
@@ -869,6 +937,8 @@ class RepoConfig:
     voice: Dict[str, Any]
     static_assets: StaticAssetsConfig
     housekeeping: HousekeepingConfig
+    durable_writes: bool
+    templates: TemplatesConfig
 
     def doc_path(self, key: str) -> Path:
         return self.root / self.docs[key]
@@ -894,6 +964,7 @@ class HubConfig:
     mode: str
     repo_defaults: Dict[str, Any]
     agents: Dict[str, AgentConfig]
+    templates: TemplatesConfig
     repos_root: Path
     worktrees_root: Path
     manifest_path: Path
@@ -905,6 +976,7 @@ class HubConfig:
     update_skip_checks: bool
     app_server: AppServerConfig
     opencode: OpenCodeConfig
+    pma: PmaConfig
     usage: UsageConfig
     server_host: str
     server_port: int
@@ -917,6 +989,7 @@ class HubConfig:
     server_log: LogConfig
     static_assets: StaticAssetsConfig
     housekeeping: HousekeepingConfig
+    durable_writes: bool
 
     def agent_binary(self, agent_id: str) -> str:
         agent = self.agents.get(agent_id)
@@ -977,6 +1050,23 @@ def _load_root_config(root: Path) -> Dict[str, Any]:
     return merged
 
 
+def update_override_templates(repo_root: Path, repos: List[Dict[str, Any]]) -> None:
+    """
+    Update templates.repos in the root override file, preserving other settings.
+
+    This writes to `codex-autorunner.override.yml` (gitignored) at the provided repo_root.
+    """
+    override_path = repo_root / ROOT_OVERRIDE_FILENAME
+    data = _load_yaml_dict(override_path)
+    templates = data.get("templates")
+    if templates is None or not isinstance(templates, dict):
+        templates = {}
+        data["templates"] = templates
+    templates["repos"] = list(repos or [])
+    rendered = yaml.safe_dump(data, sort_keys=False).rstrip() + "\n"
+    atomic_write(override_path, rendered)
+
+
 def load_root_defaults(root: Path) -> Dict[str, Any]:
     """Load hub defaults from the root config + override file."""
     return _load_root_config(root)
@@ -1271,7 +1361,77 @@ def _parse_opencode_config(
     )
     if stall_timeout_seconds is not None and stall_timeout_seconds <= 0:
         stall_timeout_seconds = None
-    return OpenCodeConfig(session_stall_timeout_seconds=stall_timeout_seconds)
+    max_text_chars_raw = cfg.get("max_text_chars", defaults.get("max_text_chars"))
+    max_text_chars = (
+        int(max_text_chars_raw)
+        if isinstance(max_text_chars_raw, int) and max_text_chars_raw > 0
+        else None
+    )
+    return OpenCodeConfig(
+        session_stall_timeout_seconds=stall_timeout_seconds,
+        max_text_chars=max_text_chars,
+    )
+
+
+def _parse_pma_config(
+    cfg: Optional[Dict[str, Any]],
+    _root: Path,
+    defaults: Optional[Dict[str, Any]],
+) -> PmaConfig:
+    cfg = cfg if isinstance(cfg, dict) else {}
+    defaults = defaults if isinstance(defaults, dict) else {}
+    enabled = bool(cfg.get("enabled", defaults.get("enabled", True)))
+    default_agent = str(
+        cfg.get("default_agent", defaults.get("default_agent", "codex"))
+    )
+    model_raw = cfg.get("model", defaults.get("model"))
+    model = str(model_raw).strip() or None if model_raw else None
+    reasoning_raw = cfg.get("reasoning", defaults.get("reasoning"))
+    reasoning = str(reasoning_raw).strip() or None if reasoning_raw else None
+    max_upload_bytes_raw = cfg.get(
+        "max_upload_bytes", defaults.get("max_upload_bytes", 10_000_000)
+    )
+    try:
+        max_upload_bytes = int(max_upload_bytes_raw)
+    except (ValueError, TypeError):
+        max_upload_bytes = 10_000_000
+    if max_upload_bytes <= 0:
+        max_upload_bytes = 10_000_000
+
+    def _parse_positive_int(key: str, fallback: int) -> int:
+        raw = cfg.get(key, defaults.get(key, fallback))
+        try:
+            value = int(raw)
+        except (ValueError, TypeError):
+            return fallback
+        return value if value > 0 else fallback
+
+    max_repos = _parse_positive_int("max_repos", 25)
+    max_messages = _parse_positive_int("max_messages", 10)
+    max_text_chars = _parse_positive_int("max_text_chars", 800)
+    docs_max_chars = _parse_positive_int("docs_max_chars", 12_000)
+    active_context_max_lines = _parse_positive_int("active_context_max_lines", 200)
+    context_log_tail_lines = _parse_positive_int("context_log_tail_lines", 120)
+    dispatch_interception_enabled = bool(
+        cfg.get(
+            "dispatch_interception_enabled",
+            defaults.get("dispatch_interception_enabled", False),
+        )
+    )
+    return PmaConfig(
+        enabled=enabled,
+        default_agent=default_agent,
+        model=model,
+        reasoning=reasoning,
+        max_upload_bytes=max_upload_bytes,
+        max_repos=max_repos,
+        max_messages=max_messages,
+        max_text_chars=max_text_chars,
+        docs_max_chars=docs_max_chars,
+        active_context_max_lines=active_context_max_lines,
+        context_log_tail_lines=context_log_tail_lines,
+        dispatch_interception_enabled=dispatch_interception_enabled,
+    )
 
 
 def _parse_usage_config(
@@ -1337,6 +1497,55 @@ def _parse_agents_config(
     return agents
 
 
+def _parse_templates_config(
+    cfg: Optional[Dict[str, Any]],
+    defaults: Optional[Dict[str, Any]],
+) -> TemplatesConfig:
+    cfg = cfg if isinstance(cfg, dict) else {}
+    defaults = defaults if isinstance(defaults, dict) else {}
+    enabled_raw = cfg.get("enabled", defaults.get("enabled", True))
+    if "enabled" in cfg and not isinstance(enabled_raw, bool):
+        raise ConfigError("templates.enabled must be boolean")
+    enabled = bool(enabled_raw)
+    repos_raw = cfg.get("repos", defaults.get("repos", []))
+    if repos_raw is None:
+        repos_raw = []
+    if not isinstance(repos_raw, list):
+        raise ConfigError("templates.repos must be a list")
+    repos: List[TemplateRepoConfig] = []
+    seen_ids: set[str] = set()
+    for idx, repo in enumerate(repos_raw):
+        if not isinstance(repo, dict):
+            raise ConfigError(f"templates.repos[{idx}] must be a mapping")
+        repo_id = repo.get("id")
+        if not isinstance(repo_id, str) or not repo_id.strip():
+            raise ConfigError(f"templates.repos[{idx}].id must be a non-empty string")
+        repo_id = repo_id.strip()
+        if repo_id in seen_ids:
+            raise ConfigError(f"templates.repos[{idx}].id must be unique")
+        seen_ids.add(repo_id)
+        url = repo.get("url")
+        if not isinstance(url, str) or not url.strip():
+            raise ConfigError(f"templates.repos[{idx}].url must be a non-empty string")
+        trusted = repo.get("trusted", False)
+        if "trusted" in repo and not isinstance(trusted, bool):
+            raise ConfigError(f"templates.repos[{idx}].trusted must be boolean")
+        default_ref = repo.get("default_ref", "main")
+        if not isinstance(default_ref, str) or not default_ref.strip():
+            raise ConfigError(
+                f"templates.repos[{idx}].default_ref must be a non-empty string"
+            )
+        repos.append(
+            TemplateRepoConfig(
+                id=repo_id,
+                url=url.strip(),
+                trusted=bool(trusted),
+                default_ref=default_ref.strip(),
+            )
+        )
+    return TemplatesConfig(enabled=enabled, repos=repos)
+
+
 def _parse_static_assets_config(
     cfg: Optional[Dict[str, Any]],
     root: Path,
@@ -1628,6 +1837,11 @@ def _build_repo_config(config_path: Path, cfg: Dict[str, Any]) -> RepoConfig:
     autorunner_reuse_session = (
         bool(reuse_session_value) if reuse_session_value is not None else False
     )
+    storage_cfg = cfg.get("storage")
+    storage_cfg = cast(
+        Dict[str, Any], storage_cfg if isinstance(storage_cfg, dict) else {}
+    )
+    durable_writes = bool(storage_cfg.get("durable_writes", False))
     return RepoConfig(
         raw=cfg,
         root=root,
@@ -1701,6 +1915,10 @@ def _build_repo_config(config_path: Path, cfg: Dict[str, Any]) -> RepoConfig:
             cfg.get("static_assets"), root, DEFAULT_REPO_CONFIG["static_assets"]
         ),
         housekeeping=parse_housekeeping_config(cfg.get("housekeeping")),
+        durable_writes=durable_writes,
+        templates=_parse_templates_config(
+            cfg.get("templates"), DEFAULT_HUB_CONFIG.get("templates")
+        ),
     )
 
 
@@ -1738,6 +1956,11 @@ def _build_hub_config(config_path: Path, cfg: Dict[str, Any]) -> HubConfig:
         Dict[str, Any], update_cfg if isinstance(update_cfg, dict) else {}
     )
     update_skip_checks = bool(update_cfg.get("skip_checks", False))
+    storage_cfg = cfg.get("storage")
+    storage_cfg = cast(
+        Dict[str, Any], storage_cfg if isinstance(storage_cfg, dict) else {}
+    )
+    durable_writes = bool(storage_cfg.get("durable_writes", False))
 
     return HubConfig(
         raw=cfg,
@@ -1746,6 +1969,9 @@ def _build_hub_config(config_path: Path, cfg: Dict[str, Any]) -> HubConfig:
         mode="hub",
         repo_defaults=cast(Dict[str, Any], cfg.get("repo_defaults") or {}),
         agents=_parse_agents_config(cfg, DEFAULT_HUB_CONFIG),
+        templates=_parse_templates_config(
+            cfg.get("templates"), DEFAULT_HUB_CONFIG.get("templates")
+        ),
         repos_root=(root / hub_cfg["repos_root"]).resolve(),
         worktrees_root=(root / hub_cfg["worktrees_root"]).resolve(),
         manifest_path=root / hub_cfg["manifest"],
@@ -1755,6 +1981,7 @@ def _build_hub_config(config_path: Path, cfg: Dict[str, Any]) -> HubConfig:
         update_repo_url=str(hub_cfg.get("update_repo_url", "")),
         update_repo_ref=str(hub_cfg.get("update_repo_ref", "main")),
         update_skip_checks=update_skip_checks,
+        durable_writes=durable_writes,
         app_server=_parse_app_server_config(
             cfg.get("app_server"),
             root,
@@ -1763,6 +1990,7 @@ def _build_hub_config(config_path: Path, cfg: Dict[str, Any]) -> HubConfig:
         opencode=_parse_opencode_config(
             cfg.get("opencode"), root, DEFAULT_HUB_CONFIG.get("opencode")
         ),
+        pma=_parse_pma_config(cfg.get("pma"), root, DEFAULT_HUB_CONFIG.get("pma")),
         usage=_parse_usage_config(
             cfg.get("usage"), root, DEFAULT_HUB_CONFIG.get("usage")
         ),
@@ -1969,6 +2197,13 @@ def _validate_opencode_config(cfg: Dict[str, Any]) -> None:
             raise ConfigError(
                 "opencode.session_stall_timeout_seconds must be a number or null"
             )
+    if (
+        "max_text_chars" in opencode_cfg
+        and opencode_cfg.get("max_text_chars") is not None
+    ):
+        max_text_chars = opencode_cfg.get("max_text_chars")
+        if not isinstance(max_text_chars, int):
+            raise ConfigError("opencode.max_text_chars must be an integer or null")
 
 
 def _validate_update_config(cfg: Dict[str, Any]) -> None:

codex_autorunner/core/context_awareness.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from typing import Literal
+
+CAR_AWARENESS_BLOCK = """<injected context>
+You are operating inside a Codex Autorunner (CAR) managed repo.
+
+CAR’s durable control-plane lives under `.codex-autorunner/`:
+- `.codex-autorunner/ABOUT_CAR.md` — short repo-local briefing (ticket/workspace conventions + helper scripts).
+- `.codex-autorunner/tickets/` — ordered ticket queue (`TICKET-###*.md`) used by the ticket flow runner.
+- `.codex-autorunner/workspace/` — shared context docs:
+  - `active_context.md` — current “north star” context; kept fresh for ongoing work.
+  - `spec.md` — longer spec / acceptance criteria when needed.
+  - `decisions.md` — prior decisions / tradeoffs when relevant.
+
+Intent signals: if the user mentions tickets, “dispatch”, “resume”, workspace docs, or `.codex-autorunner/`, they are likely referring to CAR artifacts/workflow rather than generic repo files.
+
+Use the above as orientation. If you need the operational details (exact helper commands, what CAR auto-generates), read `.codex-autorunner/ABOUT_CAR.md`.
+</injected context>"""
+
+ROLE_ADDENDUM_START = "<role addendum>"
+ROLE_ADDENDUM_END = "</role addendum>"
+
+
+def format_file_role_addendum(
+    kind: Literal["ticket", "workspace", "other"],
+    rel_path: str,
+) -> str:
+    """Format a short role-specific addendum for prompts."""
+    if kind == "ticket":
+        text = f"This target is a CAR ticket at `{rel_path}`."
+    elif kind == "workspace":
+        text = f"This target is a CAR workspace doc at `{rel_path}`."
+    elif kind == "other":
+        text = f"This target file is `{rel_path}`."
+    else:
+        raise ValueError(f"Unsupported role addendum kind: {kind}")
+    return f"{ROLE_ADDENDUM_START}\n{text}\n{ROLE_ADDENDUM_END}"