feat: inspect cloud runs from CLI

Author: rohans0509

docs/codealmanac-launch/auth-api-contract.md

@@ -359,6 +359,15 @@ GET  /v1/repositories/{repo_id}/triggers
 PUT  /v1/repositories/{repo_id}/triggers  # body carries branch, enabled, deliveryMode
 ```
 
+Slice 37 implemented the CLI-token run read routes used by
+`codealmanac runs ...`:
+
+```text
+GET /v1/repositories/{repo_id}/runs
+GET /v1/runs/{run_id}
+GET /v1/runs/{run_id}/events
+```
+
 Branch names are body fields, not path segments, so slash branches such as
 `release/1.4` are preserved.
 

docs/codealmanac-launch/cli-contract.md

@@ -111,6 +111,19 @@ codealmanac runs start --branch <branch>
 
 Cloud uses `runs` because execution happens in the cloud control plane.
 
+Implemented in Slice 37:
+
+```text
+codealmanac runs list
+codealmanac runs show <run-id>
+codealmanac runs logs <run-id>
+```
+
+`runs list` resolves the current checkout's GitHub `origin` before asking the
+cloud for that repository's runs. `runs show` and `runs logs` use the run id and
+do not need a current checkout. `runs start`, `runs cancel`, and `runs retry`
+are deferred until cloud worker queue semantics are explicit.
+
 ## Cloud Capture
 
 ```text

docs/codealmanac-launch/next-agent-brief.md

@@ -10,64 +10,58 @@ verification, launch-folder updates, commit, push, and RelayForge update.
 
 ## Last Completed Slice
 
-Slice 36 added cloud repository trigger CLI mirrors.
+Slice 37 added cloud run CLI mirrors.
 
 Implemented:
 
 - hosted worktree at
   `/Users/rohan/.config/superpowers/worktrees/usealmanac/hosted-baseline-convergence`
 - hosted branch `codex/workos-authkit-api-foundation`
-- hosted CLI-token routes:
-  `POST /v1/repositories/resolve`,
-  `GET /v1/repositories/{repo_id}/triggers`, and
-  `PUT /v1/repositories/{repo_id}/triggers`
-- direct repo-id repository trigger service methods for CLI auth
-- CodeAlmanac `cloud_repositories` service and typed HTTP adapter methods
-- current-checkout `cloud_repo` workflow that resolves GitHub `origin`
+- hosted CLI-token run read routes:
+  `GET /v1/repositories/{repo_id}/runs`,
+  `GET /v1/runs/{run_id}`, and
+  `GET /v1/runs/{run_id}/events`
+- CodeAlmanac `cloud_runs` service and typed HTTP adapter methods
+- current-checkout cloud run workflow for listing repo runs
+- run-id-only cloud run detail and log workflows
 - public CLI commands:
-  `codealmanac repo status`,
-  `codealmanac repo triggers list`,
-  `codealmanac repo triggers enable <branch> --delivery pr|commit`,
-  `codealmanac repo triggers disable <branch>`, and
-  `codealmanac repo delivery set --branch <branch> --mode pr|commit`
+  `codealmanac runs list`,
+  `codealmanac runs show <run-id>`, and
+  `codealmanac runs logs <run-id>`
 - pushed hosted commit
-  `fbf8b5a feat: add CLI repository trigger routes`
-- pushed CodeAlmanac commit
-  `8ca50e0f feat: mirror cloud repository triggers in CLI`
+  `168f9b2 feat: add CLI run read routes`
 
 Verified:
 
 ```text
 cd /Users/rohan/.config/superpowers/worktrees/usealmanac/hosted-baseline-convergence/backend
-uv run pytest tests/test_cli_repositories_api_contract.py tests/test_repositories_api_contract.py tests/test_repositories_contract.py -q
+uv run pytest tests/test_cli_runs_api_contract.py tests/test_repositories_api_contract.py tests/test_updates_contract.py -q
 uv run ruff check .
-uv run ruff format --check src/almanac/services/repositories/service.py src/almanac/server/app.py src/almanac/server/cli_repositories_router.py tests/test_cli_repositories_api_contract.py tests/test_repositories_contract.py
 uv run python -m compileall src modal_app -q
 uv run pytest -q
 
 cd /Users/rohan/Desktop/Projects/codealmanac
-uv run pytest tests/test_cloud_repositories_service.py tests/test_cloud_repo_workflow.py tests/test_cli.py -q
+uv run pytest tests/test_cloud_runs_service.py tests/test_cloud_runs_workflow.py tests/test_cli.py tests/test_architecture.py -q
 uv run ruff check .
-uv run ruff format --check src/codealmanac/app.py src/codealmanac/cli/dispatch/admin.py src/codealmanac/cli/dispatch/repo.py src/codealmanac/cli/parser/admin.py src/codealmanac/cli/parser/repo.py src/codealmanac/cli/render/repo.py src/codealmanac/integrations/cloud/http.py src/codealmanac/services/cloud_repositories tests/test_cloud_repositories_service.py tests/test_cloud_repo_workflow.py tests/test_cli.py tests/test_architecture.py
 uv run python -m compileall src -q
 uv run pytest -q
 ```
 
-Counts: hosted backend focused `23 passed, 1 warning`; hosted backend full
-`324 passed, 1 warning`; CodeAlmanac focused `57 passed`; CodeAlmanac full
-`487 passed`.
+Counts: hosted backend focused `40 passed, 1 warning`; hosted backend full
+`326 passed, 1 warning`; CodeAlmanac focused `121 passed`; CodeAlmanac full
+`490 passed`.
 
 ## Next Pressure Test
 
 Choose the next launch-hardening slice between terminal run fanout,
-setup/onboarding entrypoints, cloud run CLI mirrors, and full verification for
-the new CLI routes.
+setup/onboarding entrypoints, cloud run start/cancel/retry semantics, and
+frontend onboarding changes.
 
 Pressure points:
 
 - terminal failed/stale runs still do not have a dedicated `RunFailed` or
   `RunStale` domain-event fanout for GitHub check updates
-- CLI commands do not yet list/start/cancel/retry cloud runs
+- CLI commands list/show/log cloud runs, but do not start/cancel/retry them
 - browser setup/onboarding entrypoints still need the new cloud setup flow
 - old inline-message conversation routes should remain compatibility-only
 
@@ -89,7 +83,8 @@ origin at `12cfc08 feat: persist hosted run events`; Slice 33 is pushed to
 origin at `9098b65 feat: record stale delivery outcomes`; Slice 34 is pushed
 to origin at `4e4c94b feat: expose run event timeline`; Slice 35 is pushed to
 origin at `1b00b63 feat: add repository trigger policies`; Slice 36 is pushed
-to origin at `fbf8b5a feat: add CLI repository trigger routes`.
+to origin at `fbf8b5a feat: add CLI repository trigger routes`; Slice 37 is
+pushed to origin at `168f9b2 feat: add CLI run read routes`.
 
 The local wiki command currently fails on this checkout with:
 

docs/codealmanac-launch/progress.md

@@ -8,7 +8,7 @@ Percentages are planning estimates, not accounting metrics.
 
 ## Latest RelayForge Update
 
-Sent: 2026-07-02 after Slice 36 cloud repo trigger CLI.
+Pending: 2026-07-02 after Slice 37 cloud runs CLI.
 
 Route:
 
@@ -26,9 +26,9 @@ It was not present in `codealmanac/prd` when checked.
 
 | Area | Latest | Previous | Basis |
 | --- | ---: | ---: | --- |
-| CodeAlmanac backend/local | 93% | 92% | Slice 36 adds cloud repository service/workflow seams in the local package; local worker behavior is unchanged. |
-| CodeAlmanac CLI/public UX | 72% | 64% | CLI now mirrors dashboard trigger policy reads/writes for the current GitHub checkout. |
-| CodeAlmanac-hosted backend/auth/API | 78% | 74% | Hosted now exposes CLI-token `/v1` repository resolve and trigger policy routes. |
+| CodeAlmanac backend/local | 94% | 93% | Slice 37 adds the typed `cloud_runs` service/workflow in the local package; local worker behavior is unchanged. |
+| CodeAlmanac CLI/public UX | 78% | 72% | CLI now mirrors cloud run list/detail/log inspection from the terminal. |
+| CodeAlmanac-hosted backend/auth/API | 80% | 78% | Hosted now exposes CLI-token `/v1` run read routes. |
 | Hosted frontend/onboarding | 28% | 28% | Slice 36 does not change browser UI. |
 | Infra/deploy rename | 15% | 15% | Slice 35 changes Supabase schema but does not change provider deployment naming/configuration. |
 

docs/codealmanac-launch/verification-matrix.md

@@ -98,6 +98,12 @@ Current evidence:
 - `backend/tests/test_cli_repositories_api_contract.py` proves those routes
   authenticate with the CLI token, resolve from `fullName`, preserve slash
   branches in the JSON body, and call the repository service.
+- Slice 37 added hosted CLI-token run read routes:
+  `GET /v1/repositories/{repo_id}/runs`, `GET /v1/runs/{run_id}`, and
+  `GET /v1/runs/{run_id}/events`.
+- `backend/tests/test_cli_runs_api_contract.py` proves those routes
+  authenticate with the CLI token, return page/detail/event DTOs, and preserve
+  run-event payloads by reference.
 
 ## CodeAlmanac Local Repo
 

docs/codealmanac-launch/worklog.md

@@ -2,6 +2,33 @@
 
 ## 2026-07-02
 
+- Planned Slice 37 in
+  `docs/plans/2026-07-02-slice-37-cloud-runs-cli.md`.
+- Added hosted CLI run read routes:
+  `GET /v1/repositories/{repo_id}/runs`, `GET /v1/runs/{run_id}`, and
+  `GET /v1/runs/{run_id}/events`.
+- Added CodeAlmanac `cloud_runs` service, typed cloud run/run-event models,
+  HTTP adapter methods, and cloud run workflow.
+- Added public cloud run commands:
+  `codealmanac runs list`, `codealmanac runs show <run-id>`, and
+  `codealmanac runs logs <run-id>`.
+- Verified Slice 37 focused hosted backend gate with
+  `uv run pytest tests/test_cli_runs_api_contract.py
+  tests/test_repositories_api_contract.py tests/test_updates_contract.py -q`
+  (`40 passed, 1 warning`).
+- Verified Slice 37 focused CodeAlmanac gate with
+  `uv run pytest tests/test_cloud_runs_service.py
+  tests/test_cloud_runs_workflow.py tests/test_cli.py tests/test_architecture.py -q`
+  (`121 passed`).
+- Verified Slice 37 CodeAlmanac hygiene with `uv run ruff check .` and
+  `uv run python -m compileall src -q`.
+- Verified Slice 37 hosted backend hygiene with `uv run ruff check .`,
+  `uv run python -m compileall src modal_app -q`, and `git diff --check`.
+- Verified Slice 37 full gates with CodeAlmanac `uv run pytest -q`
+  (`490 passed`) and hosted backend `uv run pytest -q`
+  (`326 passed, 1 warning`).
+- Pushed hosted commit `168f9b2 feat: add CLI run read routes` to
+  `origin/codex/workos-authkit-api-foundation`.
 - Planned Slice 36 in
   `docs/plans/2026-07-02-slice-36-cloud-repo-trigger-cli.md`.
 - Added hosted CLI repository routes:

docs/plans/2026-07-02-slice-37-cloud-runs-cli.md

@@ -0,0 +1,182 @@
+# Cloud Runs CLI Mirrors Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add read-only cloud run inspection from the terminal: `codealmanac runs list`, `codealmanac runs show <run-id>`, and `codealmanac runs logs <run-id>`.
+
+**Architecture:** Keep local execution under `jobs`; add a separate cloud `runs` path that uses the stored CLI token and current GitHub checkout to resolve the cloud repository. Hosted adds CLI-token `/v1` run read routes that mirror existing browser `/api` run routes without account-scoped URL parameters.
+
+**Tech Stack:** FastAPI, Pydantic DTOs, SQL-backed hosted `Updates` service, CodeAlmanac Python services/workflows, argparse CLI, pytest.
+
+---
+
+## Scope
+
+Implement now:
+
+- Hosted `/v1/repositories/{repo_id}/runs`
+- Hosted `/v1/runs/{run_id}`
+- Hosted `/v1/runs/{run_id}/events`
+- CodeAlmanac `cloud_runs` service and HTTP adapter methods
+- CodeAlmanac `cloud_runs` workflow that resolves the current checkout through the same local Git probe as `repo status`
+- CLI:
+  - `codealmanac runs list [--limit N] [--json]`
+  - `codealmanac runs show <run-id> [--json]`
+  - `codealmanac runs logs <run-id> [--json]`
+
+Defer:
+
+- `codealmanac runs start`
+- `codealmanac runs cancel`
+- `codealmanac runs retry`
+- Browser UI changes
+- Worker lifecycle changes
+
+Reason for deferral: read-only inspection uses existing service semantics. Start/cancel/retry need explicit queue, billing, GitHub check, and worker-state semantics.
+
+## Design Wireframe
+
+```python
+# Hosted route edge
+user = current_cli_user(token)
+page = almanac.updates.runs_for_repo(user, repo_id, PageRequest(...))
+run = almanac.updates.run_for_user(user, run_id)
+events = almanac.updates.run_events_for_user(user, run_id)
+
+# CodeAlmanac package API
+repo_status = app.workflows.cloud_repo.status(...)
+runs = app.cloud_runs.list_for_repo(repo_status.repository.repo_id)
+run = app.cloud_runs.show(run_id)
+events = app.cloud_runs.events(run_id)
+
+# CLI edge
+codealmanac runs list
+codealmanac runs show <run-id>
+codealmanac runs logs <run-id>
+```
+
+## Task 1: Hosted CLI Run Routes
+
+**Files:**
+
+- Create: `/Users/rohan/.config/superpowers/worktrees/usealmanac/hosted-baseline-convergence/backend/src/almanac/server/cli_runs_router.py`
+- Modify: `/Users/rohan/.config/superpowers/worktrees/usealmanac/hosted-baseline-convergence/backend/src/almanac/server/app.py`
+- Test: `/Users/rohan/.config/superpowers/worktrees/usealmanac/hosted-baseline-convergence/backend/tests/test_cli_runs_api_contract.py`
+
+**Steps:**
+
+1. Add tests proving `/v1/repositories/{repo_id}/runs`, `/v1/runs/{run_id}`, and `/v1/runs/{run_id}/events` authenticate through `cli_tokens.authenticate`.
+2. Implement `cli_runs_router.py` with `current_cli_user` and existing `RunDTO`, `RunEventDTO`, and `PageDTO`.
+3. Include the router in `server/app.py`.
+4. Run:
+   ```bash
+   cd /Users/rohan/.config/superpowers/worktrees/usealmanac/hosted-baseline-convergence/backend
+   uv run pytest tests/test_cli_runs_api_contract.py tests/test_repositories_api_contract.py tests/test_updates_contract.py -q
+   ```
+
+Expected: all pass.
+
+## Task 2: CodeAlmanac Cloud Runs Service
+
+**Files:**
+
+- Create: `/Users/rohan/Desktop/Projects/codealmanac/src/codealmanac/services/cloud_runs/models.py`
+- Create: `/Users/rohan/Desktop/Projects/codealmanac/src/codealmanac/services/cloud_runs/ports.py`
+- Create: `/Users/rohan/Desktop/Projects/codealmanac/src/codealmanac/services/cloud_runs/requests.py`
+- Create: `/Users/rohan/Desktop/Projects/codealmanac/src/codealmanac/services/cloud_runs/service.py`
+- Create: `/Users/rohan/Desktop/Projects/codealmanac/src/codealmanac/services/cloud_runs/__init__.py`
+- Modify: `/Users/rohan/Desktop/Projects/codealmanac/src/codealmanac/integrations/cloud/http.py`
+- Modify: `/Users/rohan/Desktop/Projects/codealmanac/src/codealmanac/app.py`
+- Test: `/Users/rohan/Desktop/Projects/codealmanac/tests/test_cloud_runs_service.py`
+
+**Steps:**
+
+1. Add Pydantic models for cloud run source, run, event, and paged list.
+2. Add a service-owned `CloudRunsClient` protocol.
+3. Add request objects for list/show/events.
+4. Add HTTP adapter parsing for hosted run DTOs.
+5. Wire `CloudRunsService` in `create_app`.
+6. Run:
+   ```bash
+   cd /Users/rohan/Desktop/Projects/codealmanac
+   uv run pytest tests/test_cloud_runs_service.py -q
+   ```
+
+Expected: pass.
+
+## Task 3: CodeAlmanac Cloud Runs Workflow And CLI
+
+**Files:**
+
+- Create: `/Users/rohan/Desktop/Projects/codealmanac/src/codealmanac/workflows/cloud_runs/models.py`
+- Create: `/Users/rohan/Desktop/Projects/codealmanac/src/codealmanac/workflows/cloud_runs/requests.py`
+- Create: `/Users/rohan/Desktop/Projects/codealmanac/src/codealmanac/workflows/cloud_runs/service.py`
+- Create: `/Users/rohan/Desktop/Projects/codealmanac/src/codealmanac/workflows/cloud_runs/__init__.py`
+- Create: `/Users/rohan/Desktop/Projects/codealmanac/src/codealmanac/cli/parser/runs.py`
+- Create: `/Users/rohan/Desktop/Projects/codealmanac/src/codealmanac/cli/dispatch/runs.py`
+- Create: `/Users/rohan/Desktop/Projects/codealmanac/src/codealmanac/cli/render/cloud_runs.py`
+- Modify: `/Users/rohan/Desktop/Projects/codealmanac/src/codealmanac/cli/parser/admin.py`
+- Modify: `/Users/rohan/Desktop/Projects/codealmanac/src/codealmanac/cli/dispatch/admin.py`
+- Modify: `/Users/rohan/Desktop/Projects/codealmanac/src/codealmanac/cli/render/admin.py`
+- Modify: `/Users/rohan/Desktop/Projects/codealmanac/tests/test_cli.py`
+- Modify: `/Users/rohan/Desktop/Projects/codealmanac/tests/test_architecture.py`
+- Test: `/Users/rohan/Desktop/Projects/codealmanac/tests/test_cloud_runs_workflow.py`
+
+**Steps:**
+
+1. Add a workflow that resolves current checkout through `CloudRepoWorkflow.status`.
+2. Add `runs list/show/logs` parsing with `--api-url` and `--json`.
+3. Render tabular rows for human output and typed JSON for `--json`.
+4. Add CLI tests using a fake cloud runs client.
+5. Add architecture tests so parser/dispatch/render packages remain split.
+6. Run:
+   ```bash
+   cd /Users/rohan/Desktop/Projects/codealmanac
+   uv run pytest tests/test_cloud_runs_service.py tests/test_cloud_runs_workflow.py tests/test_cli.py tests/test_architecture.py -q
+   ```
+
+Expected: pass.
+
+## Task 4: Docs, Verification, Commit, Push
+
+**Files:**
+
+- Modify: `/Users/rohan/Desktop/Projects/codealmanac/docs/codealmanac-launch/auth-api-contract.md`
+- Modify: `/Users/rohan/Desktop/Projects/codealmanac/docs/codealmanac-launch/cli-contract.md`
+- Modify: `/Users/rohan/Desktop/Projects/codealmanac/docs/codealmanac-launch/progress.md`
+- Modify: `/Users/rohan/Desktop/Projects/codealmanac/docs/codealmanac-launch/verification-matrix.md`
+- Modify: `/Users/rohan/Desktop/Projects/codealmanac/docs/codealmanac-launch/worklog.md`
+- Modify: `/Users/rohan/Desktop/Projects/codealmanac/docs/codealmanac-launch/next-agent-brief.md`
+
+**Verification:**
+
+Hosted:
+
+```bash
+cd /Users/rohan/.config/superpowers/worktrees/usealmanac/hosted-baseline-convergence/backend
+uv run pytest tests/test_cli_runs_api_contract.py tests/test_repositories_api_contract.py tests/test_updates_contract.py -q
+uv run ruff check .
+uv run python -m compileall src modal_app -q
+```
+
+CodeAlmanac:
+
+```bash
+cd /Users/rohan/Desktop/Projects/codealmanac
+uv run pytest tests/test_cloud_runs_service.py tests/test_cloud_runs_workflow.py tests/test_cli.py tests/test_architecture.py -q
+uv run ruff check .
+uv run python -m compileall src -q
+git diff --check
+```
+
+Commit/push:
+
+```bash
+cd /Users/rohan/.config/superpowers/worktrees/usealmanac/hosted-baseline-convergence
+git commit -m "feat: add CLI run read routes"
+git push origin codex/workos-authkit-api-foundation
+
+cd /Users/rohan/Desktop/Projects/codealmanac
+git commit -m "feat: inspect cloud runs from CLI"
+git push origin dev
+```