codex-autorunner 1.0.0__tar.gz → 1.1.0__tar.gz

codex_autorunner-1.1.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: codex-autorunner
+Version: 1.1.0
+Summary: Codex autorunner CLI per DESIGN-V1
+Author: Codex
+License: MIT License
+        
+        Copyright (c) 2025 David Zhang
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/Git-on-my-level/codex-autorunner
+Project-URL: Repository, https://github.com/Git-on-my-level/codex-autorunner
+Project-URL: Issues, https://github.com/Git-on-my-level/codex-autorunner/issues
+Keywords: codex,automation,agent,cli,fastapi
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.9
+Requires-Dist: click<8.2
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: fastapi>=0.111
+Requires-Dist: uvicorn[standard]>=0.30
+Requires-Dist: ptyprocess>=0.7
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: tenacity>=8.0
+Provides-Extra: dev
+Requires-Dist: black==25.11.0; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-timeout>=2.0; extra == "dev"
+Requires-Dist: ruff>=0.5.0; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Provides-Extra: telegram
+Requires-Dist: httpx>=0.27; extra == "telegram"
+Provides-Extra: voice
+Requires-Dist: httpx>=0.27; extra == "voice"
+Requires-Dist: python-multipart>=0.0.9; extra == "voice"
+Provides-Extra: github
+Dynamic: license-file
+
+# CAR (codex-autorunner)
+[![PyPI](https://img.shields.io/pypi/v/codex-autorunner.svg)](https://pypi.org/project/codex-autorunner/)
+
+CAR provides a set of low-opinion agent coordination tools for you to run long complex implementations using the agents you already love.
+
+What this looks like in practice:
+- You write a plan, or generate a plan by chatting with your favorite AI
+- You convert the plan (or ask an AI to convert it for you) into CAR compatible tickets (markdown with some frontmatter)
+- Go off and do something else, no need to babysit the agents, they will notify you if they need your input
+
+![CAR Web Hub Screenshot](docs/screenshots/hub.png)
+
+## How it works
+CAR is very simple. At it's core, CAR is a state machine which checks to see if there are any incomplete tickets. If yes, pick the next one and run it against an agent. Tickets can be pre-populated by the user, but agents can also write tickets. _Tickets are the control plane for CAR_.
+
+When each agent wakes up, it gets knowledge about CAR and how to operate within CAR, a pre-defined set of context (workspace files), the current ticket, and optionally the final output of the previous agent. This simple loop ensures that agents know enough to use CAR while also focusing them on the task at hand.
+
+## Philosophy
+The philosophy behind CAR is to let the agents do what they do best, and get out of their way. CAR is _very bitter-lesson-pilled_. As models and agents get more powerful, CAR should serve as a form of leverage, and avoid constraining models and their harnesses. This is why we treat the filesystem as the first class data plane and utilize tools and languages the models are already very familiar with (git, python).
+
+CAR treats tickets as the control plane and models as the execution layer. This means that we rely on agents to follow the instructions written in the tickets. If you use a sufficiently weak model, CAR may not work well for you. CAR is an amplifier for agent capabilities. Agents who like to scope creep (create too many new tickets) or reward hack (mark a ticket as done despite it being incomplete) are not a good fit for CAR.
+
+## Interaction patterns
+CAR's core is a set of python functions surfaced as a CLI, operating on a file system. There are current 2 UIs built on top of this core.
+
+### Web UI
+The web UI is the main control plane for CAR. From here you can set up new repositories or clone existing ones, chat with agents using their TUI, and run the ticket autorunner. There are many quality-of-life features like Whisper integration, editing documents by chatting with AI (useful for mobile), viewing usage analytics, and much more. The Web UI is the most full featured user-facing interface and a good starting point for trying out CAR.
+
+I recommend serving the web UI over Tailscale. There is an auth token option but the system is not very battle tested.
+
+### Telegram
+Telegram is the "on-the-go" and notification hub for CAR. From here you can kick off and monitor existing tickets, set up new tickets, and chat with agents. Your primary UX here is asking the agent to do things for you rather than you doing it yourself like you would on the web UI. This is great for on-the-go work, but it doesn't have full feature parity with the web UI.
+
+## Quickstart
+
+The fastest way to get started is to pass [this setup guide](docs/AGENT_SETUP_GUIDE.md) to your favorite AI agent. The agent will walk you through installation and configuration interactively based on your environment.
+
+**TL;DR for the impatient:**
+
+# Install
+```
+pipx install codex-autorunner
+```
+# Initialize in your repo
+```
+cd /path/to/your/repo
+car init
+```
+# Verify setup
+```
+car doctor
+```
+# Create a ticket and run
+```
+car run
+```
+
+## Supported models
+CAR currently supports:
+- Codex
+- Opencode
+
+CAR is built to easily integrate any reasonable agent built for Agent Client Protocol (ACP). If you would like to see your agent supported, please reach out or open a PR.
+
+## Examples
+Build out complex features and products by providing a series of tickets assigned to various agents.
+![CAR Tickets in Progress Screenshot](docs/screenshots/tickets-in-progress.png)
+
+Tickets are just markdown files that both you and the agent can edit.
+![CAR Ticket Markdown Screenshot](docs/screenshots/ticket-markdown.png)
+
+You don't have to babysit the agents, they inbox you or ping you on Telegram.
+![CAR Inbox Screenshot](docs/screenshots/inbox.png)
+
+You can collaborate with the agents in a shared workspace, independent of the codebase. Drop context there, extract artifacts, it's like a shared scratchpad.
+![CAR Workspace Screenshot](docs/screenshots/workspace.png)
+
+All core workspace documents are also just markdown files, so you and the agent can easily edit them.
+![CAR Workspace New MD Screenshot](docs/screenshots/workspace-new-md.png)
+
+If you need to do something more custom or granular, you can use your favorite agent TUIs in the built-in terminal.
+![CAR Terminal Codex Screenshot](docs/screenshots/terminal-codex.png)
+![CAR Terminal Opencode Screenshot](docs/screenshots/terminal-opencode.png)
+
+On the go? The web UI is mobile responsive, or if you prefer you can type or voice chat with your agents on Telegram.
+![CAR Telegram Media Voice Screenshot](docs/screenshots/telegram-media-voice.PNG)
+![CAR Telegram Media Image Screenshot](docs/screenshots/telegram-media-image.PNG)
+
+## Star history
+[![Star History Chart](https://api.star-history.com/svg?repos=Git-on-my-level/codex-autorunner&type=Date)](https://star-history.com/#Git-on-my-level/codex-autorunner&Date)

codex_autorunner-1.1.0/README.md

@@ -0,0 +1,90 @@
+# CAR (codex-autorunner)
+[![PyPI](https://img.shields.io/pypi/v/codex-autorunner.svg)](https://pypi.org/project/codex-autorunner/)
+
+CAR provides a set of low-opinion agent coordination tools for you to run long complex implementations using the agents you already love.
+
+What this looks like in practice:
+- You write a plan, or generate a plan by chatting with your favorite AI
+- You convert the plan (or ask an AI to convert it for you) into CAR compatible tickets (markdown with some frontmatter)
+- Go off and do something else, no need to babysit the agents, they will notify you if they need your input
+
+![CAR Web Hub Screenshot](docs/screenshots/hub.png)
+
+## How it works
+CAR is very simple. At it's core, CAR is a state machine which checks to see if there are any incomplete tickets. If yes, pick the next one and run it against an agent. Tickets can be pre-populated by the user, but agents can also write tickets. _Tickets are the control plane for CAR_.
+
+When each agent wakes up, it gets knowledge about CAR and how to operate within CAR, a pre-defined set of context (workspace files), the current ticket, and optionally the final output of the previous agent. This simple loop ensures that agents know enough to use CAR while also focusing them on the task at hand.
+
+## Philosophy
+The philosophy behind CAR is to let the agents do what they do best, and get out of their way. CAR is _very bitter-lesson-pilled_. As models and agents get more powerful, CAR should serve as a form of leverage, and avoid constraining models and their harnesses. This is why we treat the filesystem as the first class data plane and utilize tools and languages the models are already very familiar with (git, python).
+
+CAR treats tickets as the control plane and models as the execution layer. This means that we rely on agents to follow the instructions written in the tickets. If you use a sufficiently weak model, CAR may not work well for you. CAR is an amplifier for agent capabilities. Agents who like to scope creep (create too many new tickets) or reward hack (mark a ticket as done despite it being incomplete) are not a good fit for CAR.
+
+## Interaction patterns
+CAR's core is a set of python functions surfaced as a CLI, operating on a file system. There are current 2 UIs built on top of this core.
+
+### Web UI
+The web UI is the main control plane for CAR. From here you can set up new repositories or clone existing ones, chat with agents using their TUI, and run the ticket autorunner. There are many quality-of-life features like Whisper integration, editing documents by chatting with AI (useful for mobile), viewing usage analytics, and much more. The Web UI is the most full featured user-facing interface and a good starting point for trying out CAR.
+
+I recommend serving the web UI over Tailscale. There is an auth token option but the system is not very battle tested.
+
+### Telegram
+Telegram is the "on-the-go" and notification hub for CAR. From here you can kick off and monitor existing tickets, set up new tickets, and chat with agents. Your primary UX here is asking the agent to do things for you rather than you doing it yourself like you would on the web UI. This is great for on-the-go work, but it doesn't have full feature parity with the web UI.
+
+## Quickstart
+
+The fastest way to get started is to pass [this setup guide](docs/AGENT_SETUP_GUIDE.md) to your favorite AI agent. The agent will walk you through installation and configuration interactively based on your environment.
+
+**TL;DR for the impatient:**
+
+# Install
+```
+pipx install codex-autorunner
+```
+# Initialize in your repo
+```
+cd /path/to/your/repo
+car init
+```
+# Verify setup
+```
+car doctor
+```
+# Create a ticket and run
+```
+car run
+```
+
+## Supported models
+CAR currently supports:
+- Codex
+- Opencode
+
+CAR is built to easily integrate any reasonable agent built for Agent Client Protocol (ACP). If you would like to see your agent supported, please reach out or open a PR.
+
+## Examples
+Build out complex features and products by providing a series of tickets assigned to various agents.
+![CAR Tickets in Progress Screenshot](docs/screenshots/tickets-in-progress.png)
+
+Tickets are just markdown files that both you and the agent can edit.
+![CAR Ticket Markdown Screenshot](docs/screenshots/ticket-markdown.png)
+
+You don't have to babysit the agents, they inbox you or ping you on Telegram.
+![CAR Inbox Screenshot](docs/screenshots/inbox.png)
+
+You can collaborate with the agents in a shared workspace, independent of the codebase. Drop context there, extract artifacts, it's like a shared scratchpad.
+![CAR Workspace Screenshot](docs/screenshots/workspace.png)
+
+All core workspace documents are also just markdown files, so you and the agent can easily edit them.
+![CAR Workspace New MD Screenshot](docs/screenshots/workspace-new-md.png)
+
+If you need to do something more custom or granular, you can use your favorite agent TUIs in the built-in terminal.
+![CAR Terminal Codex Screenshot](docs/screenshots/terminal-codex.png)
+![CAR Terminal Opencode Screenshot](docs/screenshots/terminal-opencode.png)
+
+On the go? The web UI is mobile responsive, or if you prefer you can type or voice chat with your agents on Telegram.
+![CAR Telegram Media Voice Screenshot](docs/screenshots/telegram-media-voice.PNG)
+![CAR Telegram Media Image Screenshot](docs/screenshots/telegram-media-image.PNG)
+
+## Star history
+[![Star History Chart](https://api.star-history.com/svg?repos=Git-on-my-level/codex-autorunner&type=Date)](https://star-history.com/#Git-on-my-level/codex-autorunner&Date)

{codex_autorunner-1.0.0 → codex_autorunner-1.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "codex-autorunner"
-version = "1.0.0"
+version = "1.1.0"
 description = "Codex autorunner CLI per DESIGN-V1"
 readme = "README.md"
 license = {file = "LICENSE"}
@@ -82,6 +82,7 @@ completions = true
 cache_dir = ".codex-autorunner/pytest-cache"
 asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "function"
+norecursedirs = ["worktrees", ".git", ".venv", ".codex-autorunner"]
 markers = [
     "integration: marks tests as integration tests that require external dependencies (deselect with '-m \"not integration\"')",
     "timeout(seconds): per-test timeout (provided by pytest-timeout)",
@@ -95,6 +96,7 @@ filterwarnings = [
 [tool.ruff]
 line-length = 88
 target-version = "py39"
+src = ["src"]
 
 [tool.ruff.lint]
 select = ["E", "F", "W", "I", "B"]
@@ -105,8 +107,11 @@ ignore = ["E501"]
 "src/codex_autorunner/pty_session.py" = ["F403"]
 "src/codex_autorunner/static_assets.py" = ["F403"]
 "src/codex_autorunner/cli.py" = ["B008"]
+"src/codex_autorunner/surfaces/cli/cli.py" = ["B008"]
 "src/codex_autorunner/routes/terminal_images.py" = ["B008"]
+"src/codex_autorunner/surfaces/web/routes/terminal_images.py" = ["B008"]
 "src/codex_autorunner/routes/voice.py" = ["B008"]
+"src/codex_autorunner/surfaces/web/routes/voice.py" = ["B008"]
 
 [tool.mypy]
 python_version = "3.9"

codex_autorunner-1.1.0/src/codex_autorunner/__init__.py

@@ -0,0 +1,14 @@
+"""Codex autorunner package."""
+
+__all__ = [
+    "cli",
+    "core",
+    "integrations",
+    "routes",
+    "server",
+    "surfaces",
+    "surfaces.web.routes",
+    "surfaces.web",
+    "voice",
+    "web",
+]

{codex_autorunner-1.0.0 → codex_autorunner-1.1.0}/src/codex_autorunner/agents/codex/harness.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from pathlib import Path
 from typing import Any, AsyncIterator, Optional
 
-from ...core.app_server_events import AppServerEventBuffer
+from ...integrations.app_server.event_buffer import AppServerEventBuffer
 from ...integrations.app_server.supervisor import WorkspaceAppServerSupervisor
 from ..base import AgentHarness
 from ..types import AgentId, ConversationRef, ModelCatalog, ModelSpec, TurnRef

codex_autorunner-1.1.0/src/codex_autorunner/agents/opencode/constants.py

@@ -0,0 +1,3 @@
+DEFAULT_TICKET_MODEL = "zai-coding-plan/glm-4.7"
+
+__all__ = ["DEFAULT_TICKET_MODEL"]

{codex_autorunner-1.0.0 → codex_autorunner-1.1.0}/src/codex_autorunner/agents/opencode/harness.py

@@ -6,9 +6,10 @@ import logging
 from pathlib import Path
 from typing import Any, AsyncIterator, Optional
 
-from ...core.app_server_events import format_sse
+from ...integrations.app_server.event_buffer import format_sse
 from ..base import AgentHarness
 from ..types import AgentId, ConversationRef, ModelCatalog, ModelSpec, TurnRef
+from .constants import DEFAULT_TICKET_MODEL
 from .runtime import (
     build_turn_id,
     extract_session_id,
@@ -168,6 +169,8 @@ class OpenCodeHarness(AgentHarness):
         sandbox_policy: Optional[Any],
     ) -> TurnRef:
         client = await self._supervisor.get_client(workspace_root)
+        if model is None:
+            model = DEFAULT_TICKET_MODEL
         model_payload = split_model_id(model)
         await client.prompt_async(
             conversation_id,
@@ -192,6 +195,8 @@ class OpenCodeHarness(AgentHarness):
         sandbox_policy: Optional[Any],
     ) -> TurnRef:
         client = await self._supervisor.get_client(workspace_root)
+        if model is None:
+            model = DEFAULT_TICKET_MODEL
         arguments = prompt if prompt else ""
 
         async def _send_review() -> None:

{codex_autorunner-1.0.0 → codex_autorunner-1.1.0}/src/codex_autorunner/agents/opencode/runtime.py

@@ -122,6 +122,12 @@ def extract_session_id(
         value = payload.get(key)
         if isinstance(value, str) and value:
             return value
+    info = payload.get("info")
+    if isinstance(info, dict):
+        for key in ("sessionID", "sessionId", "session_id"):
+            value = info.get(key)
+            if isinstance(value, str) and value:
+                return value
     if allow_fallback_id:
         value = payload.get("id")
         if isinstance(value, str) and value:
@@ -132,6 +138,12 @@ def extract_session_id(
             value = properties.get(key)
             if isinstance(value, str) and value:
                 return value
+        info = properties.get("info")
+        if isinstance(info, dict):
+            for key in ("sessionID", "sessionId", "session_id"):
+                value = info.get(key)
+                if isinstance(value, str) and value:
+                    return value
         part = properties.get("part")
         if isinstance(part, dict):
             for key in ("sessionID", "sessionId", "session_id"):
@@ -757,8 +769,9 @@ async def collect_opencode_output_from_events(
     error: Optional[str] = None
     message_roles: dict[str, str] = {}
     message_roles_seen = False
-    last_role_seen: Optional[str] = None
     pending_text: dict[str, list[str]] = {}
+    pending_no_id: list[str] = []
+    no_id_role: Optional[str] = None
     fallback_message: Optional[tuple[Optional[str], Optional[str], str]] = None
     last_usage_total: Optional[int] = None
     last_context_window: Optional[int] = None
@@ -793,7 +806,7 @@ async def collect_opencode_output_from_events(
         return None
 
     def _register_message_role(payload: Any) -> tuple[Optional[str], Optional[str]]:
-        nonlocal last_role_seen, message_roles_seen
+        nonlocal message_roles_seen
         if not isinstance(payload, dict):
             return None, None
         info = payload.get("info")
@@ -806,18 +819,27 @@ async def collect_opencode_output_from_events(
         if isinstance(role, str) and msg_id:
             message_roles[msg_id] = role
             message_roles_seen = True
-            last_role_seen = role
         return msg_id, role if isinstance(role, str) else None
 
+    def _flush_pending_no_id_as_assistant() -> None:
+        nonlocal no_id_role
+        if pending_no_id:
+            text_parts.extend(pending_no_id)
+            pending_no_id.clear()
+        no_id_role = "assistant"
+
+    def _discard_pending_no_id() -> None:
+        if pending_no_id:
+            pending_no_id.clear()
+
     def _append_text_for_message(message_id: Optional[str], text: str) -> None:
         if not text:
             return
         if message_id is None:
-            if not message_roles_seen:
-                text_parts.append(text)
-                return
-            if last_role_seen != "user":
+            if no_id_role == "assistant":
                 text_parts.append(text)
+            else:
+                pending_no_id.append(text)
             return
         role = message_roles.get(message_id)
         if role == "user":
@@ -839,12 +861,32 @@ async def collect_opencode_output_from_events(
             text_parts.extend(pending)
 
     def _flush_all_pending_text() -> None:
-        if not pending_text:
+        if pending_text:
+            for pending in list(pending_text.values()):
+                if pending:
+                    text_parts.extend(pending)
+            pending_text.clear()
+        if pending_no_id:
+            # If we have not seen a role yet, assume assistant for backwards
+            # compatibility with providers that omit roles entirely. Otherwise,
+            # only flush when we have already classified no-id text as assistant
+            # or when we have no other text (to avoid echoing user prompts).
+            if not message_roles_seen or no_id_role == "assistant" or not text_parts:
+                text_parts.extend(pending_no_id)
+            pending_no_id.clear()
+
+    def _handle_role_update(message_id: Optional[str], role: Optional[str]) -> None:
+        nonlocal no_id_role
+        if not role:
+            return
+        if role == "assistant":
+            _flush_pending_text(message_id)
+            _flush_pending_no_id_as_assistant()
             return
-        for pending in list(pending_text.values()):
-            if pending:
-                text_parts.extend(pending)
-        pending_text.clear()
+        if role == "user":
+            _flush_pending_text(message_id)
+            _discard_pending_no_id()
+            no_id_role = None
 
     async def _resolve_session_model_ids() -> tuple[Optional[str], Optional[str]]:
         nonlocal session_model_ids
@@ -1002,7 +1044,7 @@ async def collect_opencode_output_from_events(
                         status_type=status_type,
                         idle_seconds=idle_seconds,
                     )
-                    if not text_parts and pending_text:
+                    if not text_parts and (pending_text or pending_no_id):
                         _flush_all_pending_text()
                     break
                 if last_primary_completion_at is not None:
@@ -1079,7 +1121,7 @@ async def collect_opencode_output_from_events(
                             status_type=status_type,
                             idle_seconds=idle_seconds,
                         )
-                        if not text_parts and pending_text:
+                        if not text_parts and (pending_text or pending_no_id):
                             _flush_all_pending_text()
                         break
                     if last_primary_completion_at is not None:
@@ -1296,8 +1338,7 @@ async def collect_opencode_output_from_events(
             if event.event in ("message.updated", "message.completed"):
                 if is_primary_session:
                     msg_id, role = _register_message_role(payload)
-                    if role == "assistant":
-                        _flush_pending_text(msg_id)
+                    _handle_role_update(msg_id, role)
             if event.event == "message.part.updated":
                 properties = (
                     payload.get("properties") if isinstance(payload, dict) else None
@@ -1470,7 +1511,7 @@ async def collect_opencode_output_from_events(
             ):
                 if not is_primary_session:
                     continue
-                if not text_parts and pending_text:
+                if not text_parts and (pending_text or pending_no_id):
                     _flush_all_pending_text()
                 break
             if event.event == "message.completed" and is_primary_session:
@@ -1485,7 +1526,7 @@ async def collect_opencode_output_from_events(
             resolved_role = message_roles.get(msg_id)
         if resolved_role == "assistant":
             _append_text_for_message(msg_id, text)
-            if pending_text:
+            if pending_text or pending_no_id:
                 _flush_all_pending_text()
 
     return OpenCodeTurnOutput(text="".join(text_parts).strip(), error=error)

{codex_autorunner-1.0.0 → codex_autorunner-1.1.0}/src/codex_autorunner/agents/registry.py

@@ -163,14 +163,33 @@ def _load_agent_plugins() -> dict[str, AgentDescriptor]:
             )
             continue
 
-        if descriptor.plugin_api_version != CAR_PLUGIN_API_VERSION:
+        api_version_raw = getattr(descriptor, "plugin_api_version", None)
+        try:
+            api_version = int(api_version_raw)
+        except Exception:
+            api_version = None
+        if api_version is None:
+            _logger.warning(
+                "Ignoring agent plugin %s: invalid api_version %s",
+                agent_id,
+                api_version_raw,
+            )
+            continue
+        if api_version > CAR_PLUGIN_API_VERSION:
             _logger.warning(
-                "Ignoring agent plugin %s (api_version=%s): expected %s",
+                "Ignoring agent plugin %s (api_version=%s) requires newer core (%s)",
                 agent_id,
-                descriptor.plugin_api_version,
+                api_version,
                 CAR_PLUGIN_API_VERSION,
             )
             continue
+        if api_version < CAR_PLUGIN_API_VERSION:
+            _logger.info(
+                "Loaded agent plugin %s with older api_version=%s (current=%s)",
+                agent_id,
+                api_version,
+                CAR_PLUGIN_API_VERSION,
+            )
 
         if agent_id in _BUILTIN_AGENTS:
             _logger.warning(

{codex_autorunner-1.0.0 → codex_autorunner-1.1.0}/src/codex_autorunner/bootstrap.py

@@ -11,6 +11,8 @@ from .core.config import (
     resolve_hub_config_data,
 )
 from .core.state import RunnerState, save_state
+from .core.ticket_linter_cli import ensure_ticket_linter
+from .core.ticket_manager_cli import ensure_ticket_manager
 from .core.utils import atomic_write
 from .manifest import load_manifest
 
@@ -19,11 +21,11 @@ GENERATED_CONFIG_HEADER = "# GENERATED by CAR - DO NOT EDIT\n"
 
 
 def sample_todo() -> str:
-    return """# TODO\n\n- [ ] Replace this item with your first task\n- [ ] Add another task\n- [x] Example completed item\n"""
+    return ""
 
 
 def sample_spec() -> str:
-    return """# Spec\n\n## Context\n- Add project background and goals here.\n\n## Requirements\n- Requirement 1\n- Requirement 2\n\n## Non-goals\n- Out of scope items\n"""
+    return ""
 
 
 def _seed_doc(path: Path, force: bool, content: str) -> None:
@@ -102,7 +104,7 @@ def seed_repo_files(
         workspace_dir.mkdir(parents=True, exist_ok=True)
 
     _seed_doc(workspace_dir / "active_context.md", force, sample_todo())
-    _seed_doc(workspace_dir / "decisions.md", force, "# Decisions\n\n")
+    _seed_doc(workspace_dir / "decisions.md", force, "")
     _seed_doc(workspace_dir / "spec.md", force, sample_spec())
 
     # Seed an always-available briefing doc for interactive Codex sessions.
@@ -115,6 +117,8 @@ def seed_repo_files(
         },
         force=force,
     )
+    ensure_ticket_linter(repo_root, force=force)
+    ensure_ticket_manager(repo_root, force=force)
 
 
 def seed_hub_files(hub_root: Path, force: bool = False) -> None:

codex_autorunner-1.1.0/src/codex_autorunner/cli.py

@@ -0,0 +1,8 @@
+"""Backward-compatible CLI entrypoint.
+
+Re-export the Typer app from the CLI surface.
+"""
+
+from .surfaces.cli.cli import _resolve_repo_api_path, app, main  # noqa: F401
+
+__all__ = ["app", "main", "_resolve_repo_api_path"]

codex_autorunner-1.1.0/src/codex_autorunner/codex_cli.py

@@ -0,0 +1,20 @@
+"""Backward-compatible Codex CLI helpers.
+
+Delegates to core.utils to avoid duplicated logic.
+"""
+
+from .core.utils import (  # noqa: F401
+    apply_codex_options,
+    extract_flag_value,
+    inject_flag,
+    supports_flag,
+    supports_reasoning,
+)
+
+__all__ = [
+    "apply_codex_options",
+    "extract_flag_value",
+    "inject_flag",
+    "supports_flag",
+    "supports_reasoning",
+]

codex_autorunner-1.1.0/src/codex_autorunner/core/__init__.py

@@ -0,0 +1,5 @@
+"""Core runtime primitives."""
+
+from .archive import ArchiveResult, archive_worktree_snapshot
+
+__all__ = ["ArchiveResult", "archive_worktree_snapshot"]

{codex_autorunner-1.0.0 → codex_autorunner-1.1.0}/src/codex_autorunner/core/about_car.py

@@ -76,7 +76,8 @@ 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\n"
+        "- Tickets live under `.codex-autorunner/tickets/`.\n"
+        "- Lint ticket frontmatter after edits (runs against all tickets): `python3 .codex-autorunner/bin/lint_tickets.py`.\n\n"
         "## Optional workspace docs\n"
         "- **Active context**: "
         f"`{active_context_disp}`\n"
@@ -91,6 +92,10 @@ def build_about_car_markdown(
         "- **Dispatch**: An update or message from the agent.\n"
         "- **Handoff**: Passing control from agent to user (or vice versa).\n"
         "- **Inbox**: Where the agent receives files/messages.\n\n"
+        "## Ticket helpers\n"
+        "- 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"
         "## 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"