ctlrm 0.1.0__tar.gz

ctlrm-0.1.0/.agents/skills/ctlrm/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: ctlrm
+description: Coordinate independent agents or humans through a shared project directory using a first-authored prompt, author-assigned roles, participant-owned signatures, and immutable mailbox messages. Use when participants share a filesystem but not one native agent thread; do not use for ordinary in-thread subagent delegation.
+---
+
+# Ctlrm
+
+Use the single `ctlrm` command to join and communicate through a project-local `.ctlrm/` directory. Joining a room does not grant permission beyond the user's existing authorization.
+
+## Enter a room
+
+1. Use the explicit project root. Do not create a room at an inferred location when the target is ambiguous.
+2. Read `.ctlrm/room.md` if it exists. It contains the first participant's canonical prompt and complete role roster.
+3. If the room does not exist, act as its first participant only when responsible for defining the task. Initialize it with one `--assign PARTICIPANT=ROLE` option for every expected participant, including yourself.
+4. If the room exists, select the participant ID assigned to you. Do not invent or alter your role. Run `ctlrm --root <root> join ...`; the command copies the assigned role into your signature.
+5. Each participant invokes `join` only for itself, creating `.ctlrm/participants/<id>.yaml`. Never create, replace, or edit another participant's signature.
+6. Read the prompt and existing signatures before starting work or addressing messages.
+
+A signature is immutable acceptance of an assigned role. The CLI does not manage heartbeat or progress state.
+
+## Communicate
+
+Send findings, questions, requests, and handoffs with `ctlrm --root <root> send ...`. Messages are created exclusively and cannot overwrite an existing message ID. Read them with `ctlrm --root <root> inbox --participant <id>`.
+
+Use messages only when another participant needs the information. Include concrete file paths and evidence when relevant. Keep private scratch work outside the mailbox.
+
+Poll only when the task requires waiting. Use bounded intervals and stop at the user's deadline or after reporting a real blocker.
+
+Read [references/protocol.md](references/protocol.md) for the directory schema, initialization behavior, and command examples.

ctlrm-0.1.0/.agents/skills/ctlrm/references/protocol.md

@@ -0,0 +1,68 @@
+# Ctlrm directory protocol
+
+```text
+.ctlrm/
+├── room.md
+└── participants/
+    ├── coordinator.yaml
+    ├── coordinator/
+    │   └── inbox/
+    ├── reviewer.yaml
+    └── reviewer/
+        └── inbox/
+```
+
+## Room definition
+
+`room.md` is an immutable Markdown document with YAML front matter. The body is the first participant's prompt. The front matter records `protocol_version`, a room `id`, the `author`, `created_at`, and the complete list of participant-to-role `assignments`.
+
+The author must assign itself a role. Participant IDs must be unique, and every participant must have exactly one role. Only assigned participant IDs can join.
+
+```bash
+ctlrm --root /path/to/project init \
+  --id coordinator \
+  --name Coordinator \
+  --provider codex \
+  --assign coordinator=coordinate \
+  --assign reviewer=review \
+  --prompt-file /path/to/prompt.md
+```
+
+Room creation is exclusive. A repeated `init` by the same author with the same prompt and assignments repairs a missing author signature and otherwise leaves the room unchanged. A different author, prompt, or roster is a conflict.
+
+## Participant signatures
+
+Each participant accepts its preassigned role by invoking:
+
+```bash
+ctlrm --root /path/to/project join \
+  --id reviewer \
+  --name Reviewer \
+  --provider claude \
+  --capability code-review
+```
+
+`join` has no role option. It reads the role from `room.md` and creates `participants/<id>.yaml` plus that participant's inbox. A signature contains `protocol_version`, `room_id`, `id`, `name`, `role`, `kind`, optional `provider`, `joined_at`, and optional `capabilities`.
+
+## Messaging
+
+```bash
+ctlrm --root /path/to/project send \
+  --from coordinator \
+  --to reviewer \
+  --kind review_request \
+  --title "Review the implementation" \
+  --file src/ctlrm/runtime/room.py \
+  --body "Check role enforcement and recovery."
+
+ctlrm --root /path/to/project inbox --participant reviewer
+ctlrm --root /path/to/project participants
+```
+
+Both endpoints must have valid signatures bound to the current room and their assigned roles. Duplicate message IDs return conflict exit code 3. Validation returns 2, missing files return 4, and storage failures return 5.
+
+## Ownership and storage
+
+The CLI exclusively creates `room.md`, signatures, and messages. By convention, the first participant authors `room.md`, each participant authors only its own signature, and each declared sender authors its messages. These rules are cooperative rather than authenticated; any process with directory write access can unlink or forge files.
+
+Ctlrm creates files with mode `0660` and directories with mode `2770`. Participants running as different users must share the directory's Unix group. Exclusive creation requires a POSIX-style filesystem supporting hard links and directory `fsync`; ctlrm reports a storage error rather than weakening the no-overwrite guarantee.

ctlrm-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,121 @@
+name: checks
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: '3.11'
+      - name: Validate release tag
+        if: github.event_name == 'release'
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          [[ "$RELEASE_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+((a|b|rc)[0-9]+)?$ ]]
+          git fetch --no-tags origin +refs/heads/main:refs/remotes/origin/main \
+            "+refs/tags/$RELEASE_TAG:refs/tags/$RELEASE_TAG"
+          git merge-base --is-ancestor HEAD origin/main
+          test "$(git rev-parse "refs/tags/$RELEASE_TAG^{commit}")" = "$(git rev-parse HEAD)"
+      - name: Build sdist, then wheel from sdist
+        run: uv build
+      - run: uvx twine==7.0.0 check --strict dist/*
+      - name: Verify release package version
+        if: github.event_name == 'release'
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          uv run --no-project python - <<'PYTHON'
+          import email
+          import os
+          import pathlib
+          import zipfile
+
+          wheel, = pathlib.Path("dist").glob("*.whl")
+          with zipfile.ZipFile(wheel) as archive:
+              metadata_path, = (name for name in archive.namelist() if name.endswith(".dist-info/METADATA"))
+              metadata = email.message_from_bytes(archive.read(metadata_path))
+          if metadata["Name"] != "ctlrm" or "v" + metadata["Version"] != os.environ["RELEASE_TAG"]:
+              raise SystemExit("Package name/version does not match the release tag")
+          PYTHON
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-distributions
+          path: dist/*
+          if-no-files-found: error
+          retention-days: 7
+
+  test:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.11', '3.14']
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+      - name: Install tmux for terminal integration tests
+        run: sudo apt-get update && sudo apt-get install -y tmux
+      - run: uv sync --locked
+      - run: npm --prefix frontend ci
+      - run: npm --prefix frontend run check
+      - name: Verify bundled terminal assets are reproducible
+        run: |
+          npm --prefix frontend run build
+          git diff --exit-code -- src/ctlrm/web/static/vendor
+      - name: Install browser for workbench acceptance
+        run: npm --prefix frontend exec -- playwright install --with-deps chromium --only-shell
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run pytest --cov ctlrm --cov-report term-missing --cov-report xml:test-results/coverage.xml --durations=25 --junitxml=test-results/python.xml
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-distributions
+          path: dist
+      - name: Test installed wheel outside source tree
+        run: |
+          uv venv --python '${{ matrix.python }}' /tmp/ctlrm-wheel
+          uv pip install --python /tmp/ctlrm-wheel/bin/python dist/*.whl
+          cd /tmp
+          /tmp/ctlrm-wheel/bin/ctlrm --help
+      - name: Test installed workbench in Chromium
+        env:
+          CTLRM_BROWSER_PYTHON: /tmp/ctlrm-wheel/bin/python
+          CTLRM_BROWSER_REQUIRE_WHEEL: '1'
+        run: npm --prefix frontend run test:browser
+      - name: Preserve test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results-python-${{ matrix.python }}
+          path: |
+            test-results/
+            frontend/test-results/
+          if-no-files-found: ignore
+          retention-days: 7

ctlrm-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,33 @@
+name: release
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pypi-${{ github.event.release.tag_name }}
+  cancel-in-progress: false
+
+jobs:
+  checks:
+    uses: ./.github/workflows/ci.yml
+
+  publish:
+    needs: checks
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/project/ctlrm/
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-distributions
+          path: dist
+      - name: Publish tested distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

ctlrm-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+.ctlrm/
+.superpowers/
+.venv/
+.venv-*/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+# Local coordination data, including a .scratch symlink.
+.scratch
+.coverage*
+htmlcov/
+dist/
+
+frontend/node_modules/
+
+frontend/test-results/
+frontend/playwright-report/
+/test-results/

ctlrm-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,13 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff check
+        entry: uv run ruff check
+        language: system
+        types_or: [python, pyi]
+      - id: ruff-format
+        name: ruff format
+        entry: uv run ruff format --check
+        language: system
+        types_or: [python, pyi]

ctlrm-0.1.0/AGENTS.md

@@ -0,0 +1,12 @@
+# Code development guidance
+- Put tests under `tests/` mirroring package structure.
+- Group tests in classes.
+- Place fixtures as close as practical to usage (class, module, then `conftest.py`).
+- Write tests that focus on boundaries, not implementation details.
+- Keep test names short; put extra detail in the docstring when needed.
+- Add type hints for public functions/methods.
+- All functions, classes and modules must have a docstring, private code needs only something short.
+- Prefer concise explanatory docstrings. Describe parameters and return values when their behavior needs clarification.
+- Don't add newlines to markdown prose; let editors wrap.
+- coverage by `pytest --cov ctlrm --cov-report term-missing`
+- link by `uvx prek run --all-files`

ctlrm-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.5
+Name: ctlrm
+Version: 0.1.0
+Summary: Local web workbench for orchestrating CLI agents and human workflow participants
+Project-URL: Repository, https://github.com/d-chambers/ctlrm
+Project-URL: Documentation, https://github.com/d-chambers/ctlrm/tree/main/docs
+Project-URL: Issues, https://github.com/d-chambers/ctlrm/issues
+Requires-Python: >=3.11
+Requires-Dist: anyio<5,>=4
+Requires-Dist: fastapi<1,>=0.115
+Requires-Dist: libtmux<0.63,>=0.62
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.12
+Requires-Dist: uvicorn<1,>=0.34
+Requires-Dist: websockets<17,>=14
+Description-Content-Type: text/markdown
+
+# ctlrm
+
+Control room coordinates CLI agents and human participants through a shared directory. The CLI manages background Codex and Claude sessions, native recovery, reusable sequential workflows, review loops, and human response steps. Projects organize improvements to a codebase; each job uses its own Git worktree and branch to execute a workflow. Standalone managed sessions are also supported. The local web workbench provides project and participant tabs, workflow graphs, human responses, artifacts, code browsing, and direct access to managed agent sessions.
+
+## Open the workbench
+
+Run `uv run ctlrm serve` and open the complete loopback URL printed in the terminal. Installed packages use `ctlrm serve`. The browser uses the same central project records as the CLI; `--data PATH` selects an isolated store and `--port PORT` changes the default port 8766. The server binds only to `127.0.0.1`. Its generated access capability is carried in the initial URL fragment, removed from the address bar, and retained for that browser tab.
+
+Create a project, add a job using a packaged workflow or custom YAML, then explicitly start it. Opening an agent terminal attaches to its existing tmux session. Interactive providers accept direct keyboard input; native Codex sessions use a conversation message composer between turns. Closing the terminal or browser leaves the agent running. Drag the sidebar divider or terminal divider, or focus a divider and use arrow keys; Full screen and Escape preserve the same terminal view. See the [web workbench guide](https://github.com/d-chambers/ctlrm/blob/main/docs/web-workbench.md) for controls and boundaries.
+
+## Data model
+
+```text
+Codebase
+└── Project — a goal or related goals, with an optional design document
+    └── Job — a deliverable, usually a PR, defined by a workflow
+        └── Task — a fixed, generic assignment defined in the workflow
+            └── Execution — one attempt, assigned to a participant and optional agent session
+```
+
+A **workflow** is a reusable YAML template defining the task graph, task instructions, participant roles, provider/model profiles, and outcome transitions. For example, a job might run “implement the goal,” “review blast radius,” and “review performance.” The job supplies the concrete goal and acceptance criteria; its workflow tasks provide the instructions for carrying it out.
+
+An **execution** records the task's inputs, participant/session assignment, status, outputs, and outcome within a particular job. Review loops and explicit retries create new executions of the same task. Restarting an agent session continues its existing execution. A session can perform multiple executions; human participants need no agent session. A single-agent job can use a one-task workflow. Each execution records its initial commit, timestamps, and outgoing mailbox messages. Its accepted outcome retains commit messages and diffs alongside the worktree manifest. In task details, double-click a commit or sent message to view its full retained text in a read-only editor window; Enter and Open are also supported.
+
+Projects can contain dependent jobs, each with an immutable workflow snapshot and its own worktree/branch. PR identity belongs to the job: assign a repository and PR number, then search by number with an optional repository filter. Workflow completion, PR merge, project completion, and archival are distinct milestones.
+
+The OS-specific user data directory owns durable project and job records. Each job worktree exposes its records through `.scratch/ctlrm`, a symlink into the central job directory. See [project/job commands, storage, and PR lookup](https://github.com/d-chambers/ctlrm/blob/main/docs/projects.md) and the [backend implementation plan](https://github.com/d-chambers/ctlrm/blob/main/docs/superpowers/plans/2026-09-05-project-jobs.md). Workflows can request bounded specialist-review tasks from a predefined allowlist. The [ship workflow](https://github.com/d-chambers/ctlrm/blob/main/src/ctlrm/web/templates/ship.yaml) uses review lenses, fresh reviewer sessions, PR publication, and CI/review handling; the [single-agent workflow](https://github.com/d-chambers/ctlrm/blob/main/src/ctlrm/web/templates/single-agent.yaml) keeps simple jobs small. Project completion retires owned processes and retains the accepted code; `project archive` creates a verified ZIP while keeping PR metadata searchable. See [completion and archival](https://github.com/d-chambers/ctlrm/blob/main/docs/projects.md#completion-and-archival).
+
+## Development
+
+Use Linux, Python 3.11 or newer, tmux 3.2a or newer, and local POSIX storage. `libtmux` 0.62.x is installed with the package. Install and authenticate the provider CLIs separately. Run `uv sync`, then `uv run ctlrm --help`. Run checks with `uv run pytest --cov ctlrm --cov-report term-missing`, `uv run ruff check .`, `uv run ruff format --check .`, and `uvx prek run --all-files`. Browser assets are packaged locally. After editing frontend source, run `npm --prefix frontend ci`, `npm --prefix frontend run build`, and `npm --prefix frontend run check`; `npm --prefix frontend run format` formats authored assets. Node is needed for frontend development, not to run the installed workbench.
+
+## Releases
+
+CI checks pull requests and `main` on Python 3.11 and 3.14. Publishing a GitHub release runs those checks again and uploads the tested packages to PyPI through Trusted Publishing. See [release setup and versioning](https://github.com/d-chambers/ctlrm/blob/main/docs/releases.md), including the one-time PyPI account configuration.
+
+## Managed sessions and workflows
+
+```sh
+ctlrm --root /path/to/worktree session start --provider codex
+ctlrm --root /path/to/worktree session status
+ctlrm workflow validate --template src/ctlrm/web/templates/implement-review.yaml
+ctlrm --root /path/to/another-worktree workflow submit --template src/ctlrm/web/templates/implement-review.yaml --title "Implement the task" --file task.md --request-id my-task
+ctlrm --root /path/to/another-worktree workflow status
+```
+
+Use a fresh worktree for each independent job. The [example template](https://github.com/d-chambers/ctlrm/blob/main/src/ctlrm/web/templates/implement-review.yaml) binds implementer and reviewer roles to separate Codex sessions, then waits for a human owner. Profiles explicitly select provider permissions; Claude automatic input requires an unattended profile. See [session operations and recovery limits](https://github.com/d-chambers/ctlrm/blob/main/docs/managed-sessions.md) and [workflow acknowledgment, approval, retry, and cancellation](https://github.com/d-chambers/ctlrm/blob/main/docs/workflows.md).
+
+For project jobs, use `project complete` and `project archive`. To retire a standalone area, explicitly stop every managed session and verify its owned provider processes have exited, then stop the supervisor. Preserve wanted logs and artifacts outside the area before explicitly removing runtime files or the worktree with normal filesystem/Git tools. Supervisor stop alone leaves agents running. Project jobs can create dedicated worktrees automatically. Automatic worktree removal, recycling, parallel workflows in one area, cron, remote delegation, and embedded editing are deferred.
+
+## Room example
+
+```sh
+ctlrm --root /path/to/worktree init --id coordinator --name Coordinator --assign coordinator=coordinate --assign reviewer=review --prompt "Review the change."
+ctlrm --root /path/to/worktree join --id reviewer --name Reviewer
+ctlrm --root /path/to/worktree send --from coordinator --to reviewer --title Review --body "Please review."
+ctlrm --root /path/to/worktree inbox --participant reviewer
+```
+
+Restart commands in room signatures are stored only; use managed sessions for executable recovery. Room identity is cooperative rather than authenticated. All participants need appropriate shared filesystem permissions.
+
+### Conversation input
+
+Managed native Codex sessions accept conversation messages between turns with `ctlrm --root WORKTREE session interact --session-id ID --generation N --text "Explain the current change"`. This resumes the recorded native conversation and does not assign, acknowledge, or complete a workflow task. The supervisor accepts up to eight pending messages, each at most 16 KiB. A runner claims each message before invoking the provider; interrupted turns are retained as `uncertain` and are never automatically replayed. Explicitly replacing a conversation cancels its queued messages. Recent messages remain in the session snapshot and older messages remain in the event journal. Interactive providers continue to accept direct input through their owned tmux terminal.

ctlrm-0.1.0/docs/evidence/csv-brief-recovery-2026-09-06.json

@@ -0,0 +1,203 @@
+{
+  "date": "2026-09-06",
+  "application": "CSV Brief",
+  "description": "Standard-library Python streaming CSV summary CLI",
+  "project": "csv-brief",
+  "job": "build",
+  "provenance": {
+    "managed_agent_build": true,
+    "provider": "codex",
+    "terminal_manager": "libtmux",
+    "app_commit": "e0db8affd86cc79ab27253ccbcea3b22749a1c54",
+    "runtime_commit": "d0cba76"
+  },
+  "recovery_checks": [
+    {
+      "test": "initial live writer checkpoint",
+      "at": "2026-09-06T15:20:29Z",
+      "generation": 1,
+      "native_id": "01a07747-69a5-7e90-b843-0aad144b817a",
+      "execution": "execution-257d8cb8c6824a6a85fde7c75120d470",
+      "files": 5
+    },
+    {
+      "test": "automatic recovery after provider death",
+      "at": "2026-09-06T15:22:15Z",
+      "generation": 2,
+      "same_native_id": true,
+      "same_execution": true,
+      "uncommitted_files_preserved": true,
+      "killed_owned_processes": 3,
+      "exit_status": -9
+    },
+    {
+      "test": "supervisor crash and restart",
+      "at": "2026-09-06T15:22:15Z",
+      "agent_generation_unchanged": true,
+      "agent_process_identity_unchanged": true,
+      "same_execution": true,
+      "uncommitted_files_preserved": true
+    },
+    {
+      "test": "automatic recovery after terminal loss",
+      "at": "2026-09-06T15:23:55Z",
+      "generation": 3,
+      "same_native_id": true,
+      "same_execution": true,
+      "uncommitted_files_preserved": true
+    },
+    {
+      "test": "explicit stop suppresses automatic restart",
+      "at": "2026-09-06T15:23:59Z",
+      "generation": 3,
+      "repeated_request_idempotent": true
+    },
+    {
+      "test": "explicit native resume",
+      "at": "2026-09-06T15:25:46Z",
+      "generation": 4,
+      "same_native_id": true,
+      "same_execution": true,
+      "uncommitted_files_preserved": true
+    },
+    {
+      "test": "stale generation rejected",
+      "at": "2026-09-06T15:25:46Z",
+      "current_generation": 4,
+      "old_generation": 3,
+      "current_process_preserved": true
+    },
+    {
+      "test": "writer released after faults",
+      "at": "2026-09-06T15:25:46Z"
+    },
+    {
+      "test": "explicit fresh-session replacement",
+      "at": "2026-09-06T15:34:23Z",
+      "generation": 2,
+      "new_native_id": true,
+      "same_review_execution": true,
+      "same_input_artifact": true,
+      "code_unchanged": true
+    },
+    {
+      "test": "one implementation and one review handoff",
+      "at": "2026-09-06T15:36:03Z",
+      "tasks": [
+        {
+          "task": "implement",
+          "status": "completed",
+          "outcome": "completed",
+          "execution": "execution-257d8cb8c6824a6a85fde7c75120d470"
+        },
+        {
+          "task": "review",
+          "status": "completed",
+          "outcome": "approved",
+          "execution": "execution-8b20888aa86443869c3627cb4735ff9d"
+        },
+        {
+          "task": "counterpart",
+          "status": "pending",
+          "outcome": null,
+          "execution": "execution-0829201f9f564bc585eb34852c0c8a89"
+        }
+      ],
+      "commit": "e0db8affd86cc79ab27253ccbcea3b22749a1c54",
+      "worktree_clean": true
+    }
+  ],
+  "final_checks": {
+    "completed_writer_resumed_same_native_session": true,
+    "writer_final_generation": 5,
+    "completed_task_not_reopened": true,
+    "no_duplicate_task_or_commit": true,
+    "implementation_commits": 1,
+    "unchanged_commit": "e0db8affd86cc79ab27253ccbcea3b22749a1c54",
+    "all_agent_sessions_stopped": true,
+    "supervisor_stopped": true,
+    "tmux_sessions_remaining": 0,
+    "processes_in_app_worktree": [],
+    "counterpart_gate": "pending"
+  },
+  "task_artifacts": [
+    {
+      "task": "implement",
+      "items": [
+        {
+          "kind": "commit",
+          "id": "commit-bcd2e031bc052bc23b118af27aff3e7d0e0a58399947a2aef544fbec404c3405"
+        },
+        {
+          "kind": "message",
+          "id": "msg-20260906T152656-24f1ff5e"
+        },
+        {
+          "kind": "report",
+          "id": "execution-257d8cb8c6824a6a85fde7c75120d470"
+        }
+      ]
+    },
+    {
+      "task": "review",
+      "items": [
+        {
+          "kind": "commit",
+          "id": "commit-bcd2e031bc052bc23b118af27aff3e7d0e0a58399947a2aef544fbec404c3405"
+        },
+        {
+          "kind": "message",
+          "id": "msg-20260906T153546-3237d120"
+        },
+        {
+          "kind": "report",
+          "id": "execution-8b20888aa86443869c3627cb4735ff9d"
+        }
+      ]
+    }
+  ],
+  "validation": {
+    "app_tests_passed": 14,
+    "app_cli_acceptance_passed": 13,
+    "runtime_tests_passed": 41,
+    "ruff": "passed",
+    "prek": "passed",
+    "independent_review": "approved with no actionable findings"
+  },
+  "scope": {
+    "counterpart_review": "pending source-transmission approval",
+    "remote_pr_and_ci": "not exercised; no remote was configured",
+    "not_exercised": [
+      "machine reboot",
+      "provider credential or network outage",
+      "different interpreter installation path",
+      "crash before native recovery registration"
+    ]
+  },
+  "source_evidence": [
+    {
+      "file": "recovery-checks.json",
+      "sha256": "5f3a61f2d485bf9b1e3dd7695381d2cfdd147230351181318d6be41bc9b4b032"
+    },
+    {
+      "file": "final-acceptance.json",
+      "sha256": "0483a05d81cd0d76c5818a91da3fa3f6d79d0a52236f2b4e788bb228c39207c6"
+    },
+    {
+      "file": "app-acceptance.json",
+      "sha256": "2332c8f8cad6dfafec7dfcbb5519a83d71663e93906d50b41fb1fcd3671d22d8"
+    },
+    {
+      "file": "app-tests.txt",
+      "sha256": "189ba3e93109df5c0e2844a310a6be7d2a2f21d45cad6afe125bf9815602596f"
+    },
+    {
+      "file": "runtime-tests.txt",
+      "sha256": "d77b1376218e38d6643d1705fad4ef31f241e9c801355fbe10d4e315b14aae91"
+    },
+    {
+      "file": "runtime-lint.txt",
+      "sha256": "84617e5ab13858c275ee0228d2588844cac631a8dce9f3d2dadc36a8d5320d67"
+    }
+  ]
+}

ctlrm-0.1.0/docs/evidence/managed-codex-recovery-2026-09-05.json

@@ -0,0 +1 @@
+{"area_id":"area-5bac55c1489946ee91ed5af7ed47320c","at":"2026-09-05T09:04:44.328906+00:00","context_token_recalled":true,"final_session":"stopped","initial_generation":1,"native_id":"01a070cd-2b8a-7170-bf30-64ac34c353e6","provider":"codex-cli 0.153.4","resumed_generation":2,"session_id":"session-b116ebd7feca4c7cb8171aada15534d9","status":"completed","work_id":"work-60cb312d51774f0988fc283e9e69edef"}

ctlrm-0.1.0/docs/evidence/managed-interrupted-recovery-2026-09-05.json

@@ -0,0 +1 @@
+{"area_id":"area-439baa3c8c9543fcaad869f78a661653","completed_at":"2026-09-05T08:17:59.603639+00:00","exit_observation":"{\"returncode\":-9,\"token\":\"launch-acdf98f7971f4d4a9251e4476f6d32e5\"}\n","final_session_status":"stopped","final_work_status":"completed","interrupted_generation":3,"kill_at":"2026-09-05T08:17:35.270240+00:00","native_id":"540f01be-c322-4bcf-bcd1-3c2a5b75f0bd","provider_pid":194934,"recovered_generation":4,"session_id":"session-d6917cd078db429fa8bed5a9d49211e7","work_id":"work-582c13ff8d384649983051e0834075e7","work_status_at_kill":"acknowledged"}

ctlrm-0.1.0/docs/evidence/managed-native-recovery-2026-09-05.json

@@ -0,0 +1 @@
+{"area_id":"area-439baa3c8c9543fcaad869f78a661653","completed_at":"2026-09-05T07:33:56.802582+00:00","explicit_stop_at":"2026-09-05T07:34:41.853755+00:00","final_generation":2,"final_status":"stopped","initial_generation":1,"initial_recovery":{"area_id":"area-439baa3c8c9543fcaad869f78a661653","at":"2026-09-05T07:28:24.041481+00:00","context":"/home/derrick/.claude","executable":"/home/derrick/.local/bin/claude","generation":1,"native_id":"540f01be-c322-4bcf-bcd1-3c2a5b75f0bd","required_environment":[],"resume_argv":["/home/derrick/.local/bin/claude","--permission-mode","dontAsk","--tools","Read,Bash","--allowedTools","Read,Bash(/tmp/ctlrm-implementation/.venv/bin/python3 -m ctlrm --root /tmp/ctlrm-managed-native:*)","--resume","540f01be-c322-4bcf-bcd1-3c2a5b75f0bd",""],"root":"/tmp/ctlrm-managed-native","schema_version":1,"session_id":"session-d6917cd078db429fa8bed5a9d49211e7"},"initial_work":{"generation":1,"id":"work-0a7ea1c14e084de0bfda23db95b861a9","message":{"body":"Work ID: work-0a7ea1c14e084de0bfda23db95b861a9\nAcknowledge this work ID before acting.\n\nRemember the exact token IRIS-7382 in this conversation. Acknowledge this work ID before acting. Then report completed with the documented session disposition command. Do not edit files or poll.","created_at":"2026-09-05T07:29:53.806863+00:00","files":[],"from":"coordinator","id":"msg-9338beba8e8546668a51ad65e41f55b8","kind":"prompt","node_id":null,"run_id":null,"status":"pending","title":"prompt","to":"agent","workflow_id":null},"status":"completed"},"killed_at":"2026-09-05T07:31:17.481761+00:00","native_id":"540f01be-c322-4bcf-bcd1-3c2a5b75f0bd","provider_process":"157014:850395","recall_work":{"generation":2,"id":"work-515bc22c1858446ab0e409d74446d342","message":{"body":"Work ID: work-515bc22c1858446ab0e409d74446d342\nAcknowledge this work ID before acting.\n\nWithout opening old mailbox messages or any other files, recall the exact acceptance token from the previous completed prompt in this native conversation and print it in your response. Acknowledge this work ID first and report completed afterward. Only read this current assignment and use the documented ctlrm commands. Do not poll.","created_at":"2026-09-05T07:32:21.946279+00:00","files":[],"from":"coordinator","id":"msg-f282df14eb214504a9dad380bbe4f18a","kind":"prompt","node_id":null,"run_id":null,"status":"pending","title":"prompt","to":"agent","workflow_id":null},"status":"completed"},"resumed_generation":2,"resumed_native_id":"540f01be-c322-4bcf-bcd1-3c2a5b75f0bd","resumed_recovery":{"area_id":"area-439baa3c8c9543fcaad869f78a661653","at":"2026-09-05T07:31:48.001959+00:00","context":"/home/derrick/.claude","executable":"/home/derrick/.local/bin/claude","generation":2,"native_id":"540f01be-c322-4bcf-bcd1-3c2a5b75f0bd","required_environment":[],"resume_argv":["/home/derrick/.local/bin/claude","--permission-mode","dontAsk","--tools","Read,Bash","--allowedTools","Read,Bash(/tmp/ctlrm-implementation/.venv/bin/python3 -m ctlrm --root /tmp/ctlrm-managed-native:*)","--resume","540f01be-c322-4bcf-bcd1-3c2a5b75f0bd",""],"root":"/tmp/ctlrm-managed-native","schema_version":1,"session_id":"session-d6917cd078db429fa8bed5a9d49211e7"},"root":"/tmp/ctlrm-managed-native","session_id":"session-d6917cd078db429fa8bed5a9d49211e7","signal":"SIGKILL"}

ctlrm-0.1.0/docs/evidence/mixed-workflow-2026-09-05.json

@@ -0,0 +1 @@
+{"area_id":"area-dcbf097538734122960a5b612e277636","at":"2026-09-05T09:12:15.847055+00:00","final_output":"version two","handoff_supervisor_restart":true,"human_response":"exercised by acceptance controller","interrupted_execution":"execution-7edfb41a22c645149b86086b20110f8a","native_implementer":"01a070d1-f394-75d0-9fe7-13e13ddf6e22","recovered_generation":2,"run":{"active":null,"executions":[{"artifact":"artifact-3a808a7cd8b04730ae4f679d86c30919502cb1f0cfc9d42884c6a91ca3a871e9","generation":2,"id":"execution-7edfb41a22c645149b86086b20110f8a","input":{},"message":{"body":"Area: area-dcbf097538734122960a5b612e277636\nRun: run-74e3b4884e844374a6c4ef9894c065ad\nWork ID: execution-7edfb41a22c645149b86086b20110f8a\nRole instructions: This is a bounded ctlrm protocol acceptance test. Only edit acceptance.txt. No repository implementation work or code review subprocesses are requested. Always follow assignment acknowledgment/report commands. On the FIRST implement visit, acknowledge, write acceptance.txt with exactly version one, then end your turn WITHOUT reporting completion. The controller will interrupt and natively resume you. In the resumed generation, acknowledge readiness, reconcile as in_progress, acknowledge this same execution using the current generation, then report completed. Do not rewrite the existing version one file after recovery. On a later implement visit triggered by changes_requested, write exactly version two and report completed normally. Never act as the human owner.\nTask: .ctlrm/task.md\nInput: {}\nAllowed outcomes: completed\nBefore acting, run: /tmp/ctlrm-implementation/.venv/bin/python3 -m ctlrm --root /tmp/ctlrm-mixed-native workflow acknowledge --run-id run-74e3b4884e844374a6c4ef9894c065ad --execution-id execution-7edfb41a22c645149b86086b20110f8a --participant implementer --session-id session-1e23fc2d53e144a89602c4d51f80e503 --generation 1\nReport with: /tmp/ctlrm-implementation/.venv/bin/python3 -m ctlrm --root /tmp/ctlrm-mixed-native workflow report --run-id run-74e3b4884e844374a6c4ef9894c065ad --execution-id execution-7edfb41a22c645149b86086b20110f8a --participant implementer --session-id session-1e23fc2d53e144a89602c4d51f80e503 --generation 1 --outcome OUTCOME --summary SUMMARY\nAfter native resume use your CURRENT generation in these commands. Do not choose the next recipient; the workflow routes accepted outcomes. After an accepted report, finish your turn and wait; do not perform further work.","created_at":"2026-09-05T09:07:26.747440+00:00","files":[],"from":"coordinator","id":"msg-745f6060b3ef4d37835410bebd1aca1e","kind":"assignment","node_id":null,"run_id":null,"status":"pending","title":"assignment","to":"implementer","workflow_id":null},"outcome":"completed","participant":"implementer","session_id":"session-1e23fc2d53e144a89602c4d51f80e503","status":"completed","step":"implement","summary":"Reconciled as in_progress and acknowledged in generation 2. Verified acceptance.txt contains exactly version one without rewriting it."},{"artifact":"artifact-21550c592394dee7a54f4e234eeaa3deb49385749322a851d545316473fb04b7","generation":1,"id":"execution-af1ac02a58734ee58c75f535ecd72d1d","input":{"artifact":"artifact-3a808a7cd8b04730ae4f679d86c30919502cb1f0cfc9d42884c6a91ca3a871e9","execution_id":"execution-7edfb41a22c645149b86086b20110f8a","outcome":"completed","summary":"Reconciled as in_progress and acknowledged in generation 2. Verified acceptance.txt contains exactly version one without rewriting it."},"message":{"body":"Area: area-dcbf097538734122960a5b612e277636\nRun: run-74e3b4884e844374a6c4ef9894c065ad\nWork ID: execution-af1ac02a58734ee58c75f535ecd72d1d\nRole instructions: Bounded protocol acceptance test. Read acceptance.txt and acknowledge the exact input artifact. If it says version one, report changes_requested with summary Change acceptance.txt to exactly version two. If it says version two, report approved with summary Version two verified. Do not modify any files and do not run another review agent. Use the supplied workflow acknowledgment/report commands with your current generation. Never act as the human owner.\nTask: .ctlrm/task.md\nInput: {\"artifact\": \"artifact-3a808a7cd8b04730ae4f679d86c30919502cb1f0cfc9d42884c6a91ca3a871e9\", \"execution_id\": \"execution-7edfb41a22c645149b86086b20110f8a\", \"outcome\": \"completed\", \"summary\": \"Reconciled as in_progress and acknowledged in generation 2. Verified acceptance.txt contains exactly version one without rewriting it.\"}\nAllowed outcomes: approved, changes_requested\nBefore acting, run: /tmp/ctlrm-implementation/.venv/bin/python3 -m ctlrm --root /tmp/ctlrm-mixed-native workflow acknowledge --run-id run-74e3b4884e844374a6c4ef9894c065ad --execution-id execution-af1ac02a58734ee58c75f535ecd72d1d --participant reviewer --session-id session-3bd4551d3215426287a69e82a2845b81 --generation 1 --input-artifact artifact-3a808a7cd8b04730ae4f679d86c30919502cb1f0cfc9d42884c6a91ca3a871e9\nReport with: /tmp/ctlrm-implementation/.venv/bin/python3 -m ctlrm --root /tmp/ctlrm-mixed-native workflow report --run-id run-74e3b4884e844374a6c4ef9894c065ad --execution-id execution-af1ac02a58734ee58c75f535ecd72d1d --participant reviewer --session-id session-3bd4551d3215426287a69e82a2845b81 --generation 1 --input-artifact artifact-3a808a7cd8b04730ae4f679d86c30919502cb1f0cfc9d42884c6a91ca3a871e9 --outcome OUTCOME --summary SUMMARY\nAfter native resume use your CURRENT generation in these commands. Do not choose the next recipient; the workflow routes accepted outcomes. After an accepted report, finish your turn and wait; do not perform further work.","created_at":"2026-09-05T09:10:33.547900+00:00","files":[],"from":"coordinator","id":"msg-cea145f2be0c421296b1f64ed9c3bfb9","kind":"assignment","node_id":null,"run_id":null,"status":"pending","title":"assignment","to":"reviewer","workflow_id":null},"outcome":"changes_requested","participant":"reviewer","session_id":"session-3bd4551d3215426287a69e82a2845b81","status":"completed","step":"review","summary":"Change acceptance.txt to exactly version two"},{"artifact":"artifact-29f8a96dc842cb5a351514c06da7b6f05bf828c29f2c7bf84cc21f6eb29340d2","generation":2,"id":"execution-01d6eba5e01a4cb0af250761664a59f6","input":{"artifact":"artifact-21550c592394dee7a54f4e234eeaa3deb49385749322a851d545316473fb04b7","execution_id":"execution-af1ac02a58734ee58c75f535ecd72d1d","outcome":"changes_requested","summary":"Change acceptance.txt to exactly version two"},"message":{"body":"Area: area-dcbf097538734122960a5b612e277636\nRun: run-74e3b4884e844374a6c4ef9894c065ad\nWork ID: execution-01d6eba5e01a4cb0af250761664a59f6\nRole instructions: This is a bounded ctlrm protocol acceptance test. Only edit acceptance.txt. No repository implementation work or code review subprocesses are requested. Always follow assignment acknowledgment/report commands. On the FIRST implement visit, acknowledge, write acceptance.txt with exactly version one, then end your turn WITHOUT reporting completion. The controller will interrupt and natively resume you. In the resumed generation, acknowledge readiness, reconcile as in_progress, acknowledge this same execution using the current generation, then report completed. Do not rewrite the existing version one file after recovery. On a later implement visit triggered by changes_requested, write exactly version two and report completed normally. Never act as the human owner.\nTask: .ctlrm/task.md\nInput: {\"execution_id\": \"execution-af1ac02a58734ee58c75f535ecd72d1d\", \"outcome\": \"changes_requested\", \"summary\": \"Change acceptance.txt to exactly version two\", \"artifact\": \"artifact-21550c592394dee7a54f4e234eeaa3deb49385749322a851d545316473fb04b7\"}\nAllowed outcomes: completed\nBefore acting, run: /tmp/ctlrm-implementation/.venv/bin/python3 -m ctlrm --root /tmp/ctlrm-mixed-native workflow acknowledge --run-id run-74e3b4884e844374a6c4ef9894c065ad --execution-id execution-01d6eba5e01a4cb0af250761664a59f6 --participant implementer --session-id session-1e23fc2d53e144a89602c4d51f80e503 --generation 2 --input-artifact artifact-21550c592394dee7a54f4e234eeaa3deb49385749322a851d545316473fb04b7\nReport with: /tmp/ctlrm-implementation/.venv/bin/python3 -m ctlrm --root /tmp/ctlrm-mixed-native workflow report --run-id run-74e3b4884e844374a6c4ef9894c065ad --execution-id execution-01d6eba5e01a4cb0af250761664a59f6 --participant implementer --session-id session-1e23fc2d53e144a89602c4d51f80e503 --generation 2 --input-artifact artifact-21550c592394dee7a54f4e234eeaa3deb49385749322a851d545316473fb04b7 --outcome OUTCOME --summary SUMMARY\nAfter native resume use your CURRENT generation in these commands. Do not choose the next recipient; the workflow routes accepted outcomes. After an accepted report, finish your turn and wait; do not perform further work.","created_at":"2026-09-05T09:10:50.277924+00:00","files":[],"from":"coordinator","id":"msg-ee19c4fbe2384019991dbafa9390df2b","kind":"assignment","node_id":null,"run_id":null,"status":"pending","title":"assignment","to":"implementer","workflow_id":null},"outcome":"completed","participant":"implementer","session_id":"session-1e23fc2d53e144a89602c4d51f80e503","status":"completed","step":"implement","summary":"Changed acceptance.txt to exactly version two and verified its exact bytes."},{"artifact":"artifact-c321e643b05bb8c8cc288018d93a011185d8cfa13bf544657e3cc4194684aee1","generation":1,"id":"execution-e7a895f0890d450ca0a3ba48eb605cfd","input":{"artifact":"artifact-29f8a96dc842cb5a351514c06da7b6f05bf828c29f2c7bf84cc21f6eb29340d2","execution_id":"execution-01d6eba5e01a4cb0af250761664a59f6","outcome":"completed","summary":"Changed acceptance.txt to exactly version two and verified its exact bytes."},"message":{"body":"Area: area-dcbf097538734122960a5b612e277636\nRun: run-74e3b4884e844374a6c4ef9894c065ad\nWork ID: execution-e7a895f0890d450ca0a3ba48eb605cfd\nRole instructions: Bounded protocol acceptance test. Read acceptance.txt and acknowledge the exact input artifact. If it says version one, report changes_requested with summary Change acceptance.txt to exactly version two. If it says version two, report approved with summary Version two verified. Do not modify any files and do not run another review agent. Use the supplied workflow acknowledgment/report commands with your current generation. Never act as the human owner.\nTask: .ctlrm/task.md\nInput: {\"execution_id\": \"execution-01d6eba5e01a4cb0af250761664a59f6\", \"outcome\": \"completed\", \"summary\": \"Changed acceptance.txt to exactly version two and verified its exact bytes.\", \"artifact\": \"artifact-29f8a96dc842cb5a351514c06da7b6f05bf828c29f2c7bf84cc21f6eb29340d2\"}\nAllowed outcomes: approved, changes_requested\nBefore acting, run: /tmp/ctlrm-implementation/.venv/bin/python3 -m ctlrm --root /tmp/ctlrm-mixed-native workflow acknowledge --run-id run-74e3b4884e844374a6c4ef9894c065ad --execution-id execution-e7a895f0890d450ca0a3ba48eb605cfd --participant reviewer --session-id session-3bd4551d3215426287a69e82a2845b81 --generation 1 --input-artifact artifact-29f8a96dc842cb5a351514c06da7b6f05bf828c29f2c7bf84cc21f6eb29340d2\nReport with: /tmp/ctlrm-implementation/.venv/bin/python3 -m ctlrm --root /tmp/ctlrm-mixed-native workflow report --run-id run-74e3b4884e844374a6c4ef9894c065ad --execution-id execution-e7a895f0890d450ca0a3ba48eb605cfd --participant reviewer --session-id session-3bd4551d3215426287a69e82a2845b81 --generation 1 --input-artifact artifact-29f8a96dc842cb5a351514c06da7b6f05bf828c29f2c7bf84cc21f6eb29340d2 --outcome OUTCOME --summary SUMMARY\nAfter native resume use your CURRENT generation in these commands. Do not choose the next recipient; the workflow routes accepted outcomes. After an accepted report, finish your turn and wait; do not perform further work.","created_at":"2026-09-05T09:11:49.072292+00:00","files":[],"from":"coordinator","id":"msg-6316c2609e874c32bbf2b82d8003d98d","kind":"assignment","node_id":null,"run_id":null,"status":"pending","title":"assignment","to":"reviewer","workflow_id":null},"outcome":"approved","participant":"reviewer","session_id":"session-3bd4551d3215426287a69e82a2845b81","status":"completed","step":"review","summary":"Version two verified"},{"artifact":"artifact-cfa8a12a6fe891eba8425a22bcde66e427b475c60456dfb506ef12803dcb2421","generation":null,"id":"execution-9592c63076df4f4c9cae4097b08374d1","input":{"artifact":"artifact-c321e643b05bb8c8cc288018d93a011185d8cfa13bf544657e3cc4194684aee1","execution_id":"execution-e7a895f0890d450ca0a3ba48eb605cfd","outcome":"approved","summary":"Version two verified"},"message":{"body":"Area: area-dcbf097538734122960a5b612e277636\nRun: run-74e3b4884e844374a6c4ef9894c065ad\nWork ID: execution-9592c63076df4f4c9cae4097b08374d1\nRole instructions: Accept the final version after the review loop.\nTask: .ctlrm/task.md\nInput: {\"execution_id\": \"execution-e7a895f0890d450ca0a3ba48eb605cfd\", \"outcome\": \"approved\", \"summary\": \"Version two verified\", \"artifact\": \"artifact-c321e643b05bb8c8cc288018d93a011185d8cfa13bf544657e3cc4194684aee1\"}\nAllowed outcomes: approved\nBefore acting, run: /tmp/ctlrm-implementation/.venv/bin/python3 -m ctlrm --root /tmp/ctlrm-mixed-native workflow acknowledge --run-id run-74e3b4884e844374a6c4ef9894c065ad --execution-id execution-9592c63076df4f4c9cae4097b08374d1 --participant owner --input-artifact artifact-c321e643b05bb8c8cc288018d93a011185d8cfa13bf544657e3cc4194684aee1\nReport with: /tmp/ctlrm-implementation/.venv/bin/python3 -m ctlrm --root /tmp/ctlrm-mixed-native workflow report --run-id run-74e3b4884e844374a6c4ef9894c065ad --execution-id execution-9592c63076df4f4c9cae4097b08374d1 --participant owner --input-artifact artifact-c321e643b05bb8c8cc288018d93a011185d8cfa13bf544657e3cc4194684aee1 --outcome OUTCOME --summary SUMMARY\nAfter native resume use your CURRENT generation in these commands. Do not choose the next recipient; the workflow routes accepted outcomes. After an accepted report, finish your turn and wait; do not perform further work.","created_at":"2026-09-05T09:12:11.489732+00:00","files":[],"from":"coordinator","id":"msg-faef987c47e54fafa6919d466cfd281e","kind":"assignment","node_id":null,"run_id":null,"status":"pending","title":"assignment","to":"owner","workflow_id":null},"outcome":"approved","participant":"owner","session_id":null,"status":"completed","step":"approve","summary":"Acceptance controller verified version two and exercised the human response API."}],"id":"run-74e3b4884e844374a6c4ef9894c065ad","reason":null,"status":"completed","task_id":"task-6d7369d3d346443eb9747bae13ae9f95"},"second_area_canceled_before_launch":true,"second_area_id":"area-213057c5365e4a0eb75fd48969b7f981","sessions_explicitly_stopped":true,"unchanged_template_reused":true}