docs: record slice 40 milestone update

Author: rohans0509

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

@@ -10,53 +10,39 @@ verification, launch-folder updates, commit, push, and RelayForge update.
 
 ## Last Completed Slice
 
-Slice 39 added manual cloud run start.
+Slice 40 added hosted terminal run events.
 
 Implemented:
 
 - hosted worktree at
   `/Users/rohan/.config/superpowers/worktrees/usealmanac/hosted-baseline-convergence`
 - hosted branch `codex/workos-authkit-api-foundation`
-- hosted CLI-token run start route:
-  `POST /v1/repositories/{repo_id}/runs`
-- hosted `ManualBranchRuns` service
-- hosted manual-start semantics:
-  `Action.APPROVE_UPDATE`, GitHub-resolved branch head, branch delivery policy
-  when present, default `commit` delivery otherwise, duplicate-head idempotency
-- CodeAlmanac cloud runs service/client start method
-- CodeAlmanac `CloudRunsWorkflow.start`
-- public CLI command:
-  `codealmanac runs start --branch <branch>`
+- hosted `RunFailed` domain event
+- hosted `RunStale` domain event
+- `UpdateCompletion` dispatches `RunFailed` after failed or blocked worker
+  completion
+- `UpdateCompletion` dispatches `RunStale` after delivery detects that the
+  expected branch head moved
+- failed/stale run events carry repo id, account id, repo full name, source
+  head sha, and reason; stale events also carry expected and actual head shas
 - pushed hosted commit
-  `14caf8b feat: start cloud runs from CLI`
-- pushed CodeAlmanac commit
-  `0e3879e1 feat: start cloud runs from CLI`
+  `8795849 feat: emit terminal run events`
+- CodeAlmanac product code was unchanged; local launch docs record this slice
+  in a follow-up docs commit.
 
 Verified:
 
 ```text
 cd /Users/rohan/.config/superpowers/worktrees/usealmanac/hosted-baseline-convergence/backend
-uv run pytest tests/test_updates_contract.py tests/test_cli_runs_api_contract.py -q
+uv run pytest tests/test_events_contract.py tests/test_updates_contract.py tests/test_architecture_contract.py -q
 uv run ruff check .
 uv run python -m compileall src modal_app -q
 uv run pytest -q
-
-cd /Users/rohan/.config/superpowers/worktrees/usealmanac/hosted-baseline-convergence/frontend
-npm run test:routes
-npm run lint
-
-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
-uv run pytest -q
 git diff --check
 ```
 
-Counts so far: hosted backend focused `37 passed, 1 warning`; hosted
-backend full `333 passed, 1 warning`; hosted frontend route tests `27 passed`;
-hosted frontend lint passed; CodeAlmanac focused `123 passed`; CodeAlmanac
-full `496 passed`.
+Counts so far: hosted backend focused `108 passed`; hosted backend full
+`334 passed, 1 warning`; hosted ruff, compileall, and diff-check passed.
 
 ## Next Pressure Test
 
@@ -67,7 +53,7 @@ deployment/provider rename checks.
 Pressure points:
 
 - terminal failed/stale runs still do not have a dedicated `RunFailed` or
-  `RunStale` domain-event fanout for GitHub check updates
+  `RunStale` GitHub Check subscriber
 - CLI commands list/show/log/start cloud runs, but do not cancel/retry them
 - `runs cancel` needs a real Modal/provider cancellation primitive before it
   should be public
@@ -100,7 +86,8 @@ origin at `1b00b63 feat: add repository trigger policies`; Slice 36 is pushed
 to origin at `fbf8b5a feat: add CLI repository trigger routes`; Slice 37 is
 pushed to origin at `168f9b2 feat: add CLI run read routes`; Slice 38 is
 pushed to origin at `ed7e765 feat: add cloud route handoff`; Slice 39 is
-pushed to origin at `14caf8b feat: start cloud runs from CLI`.
+pushed to origin at `14caf8b feat: start cloud runs from CLI`; Slice 40 is
+pushed to origin at `8795849 feat: emit terminal run events`.
 
 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 39 cloud run start.
+Sent: 2026-07-02 after Slice 40 terminal run events.
 
 Route:
 
@@ -26,10 +26,10 @@ It was not present in `codealmanac/prd` when checked.
 
 | Area | Latest | Previous | Basis |
 | --- | ---: | ---: | --- |
-| CodeAlmanac backend/local | 95% | 95% | Slice 39 adds cloud-run API plumbing only; local worker behavior is unchanged. |
-| CodeAlmanac CLI/public UX | 87% | 84% | `codealmanac runs start --branch <branch>` now starts a cloud run from the current checkout. |
-| CodeAlmanac-hosted backend/auth/API | 84% | 81% | Hosted adds the CLI-token manual branch run route and service semantics. |
-| Hosted frontend/onboarding | 35% | 35% | Slice 39 does not change hosted UI; richer onboarding screens remain. |
+| CodeAlmanac backend/local | 95% | 95% | Slice 40 is hosted-only; local worker behavior is unchanged. |
+| CodeAlmanac CLI/public UX | 87% | 87% | Slice 40 adds no public CLI verbs. |
+| CodeAlmanac-hosted backend/auth/API | 85% | 84% | Hosted now emits typed `RunFailed` and `RunStale` domain events for terminal run fanout. |
+| Hosted frontend/onboarding | 35% | 35% | Slice 40 does not change hosted UI; richer onboarding screens remain. |
 | Infra/deploy rename | 15% | 15% | Slice 35 changes Supabase schema but does not change provider deployment naming/configuration. |
 
 ## Update Rule

docs/codealmanac-launch/verification-matrix.md

@@ -624,7 +624,18 @@ Current evidence:
   (`333 passed, 1 warning`), frontend route tests (`27 passed`),
   `npm run lint`, `uv run ruff check .`,
   `uv run python -m compileall src modal_app -q`, and `git diff --check`.
-- Remaining hosted worker risks: terminal failed/stale GitHub check fanout,
+- Slice 40 added typed `RunFailed` and `RunStale` domain events. `UpdateCompletion`
+  dispatches them when a worker fails/blocks or delivery detects a stale branch
+  head.
+- `backend/tests/test_events_contract.py` proves terminal run events carry
+  repo/head facts.
+- `backend/tests/test_updates_contract.py` proves failed and stale completions
+  dispatch `run_failed` and `run_stale` events after terminal run state is
+  written.
+- Slice 40 hosted verification passed with focused tests (`108 passed`), full
+  hosted backend tests (`334 passed, 1 warning`), `uv run ruff check .`,
+  `uv run python -m compileall src modal_app -q`, and `git diff --check`.
+- Remaining hosted worker risks: terminal failed/stale GitHub check subscriber,
   cloud run cancel/retry, and richer production setup/onboarding screens
   still need launch-hardening.
 

docs/codealmanac-launch/worklog.md

@@ -979,3 +979,22 @@
 - Recorded progress as: CodeAlmanac backend/local 95%, CLI/public UX 87%,
   CodeAlmanac-hosted backend/auth/API 84%, hosted frontend/onboarding 35%, and
   infra/deploy rename 15%.
+- Planned Slice 40 in
+  `docs/plans/2026-07-02-slice-40-run-terminal-events.md`.
+- Added hosted `RunFailed` and `RunStale` domain events.
+- Updated hosted `UpdateCompletion` so failed/blocked worker completions
+  dispatch `RunFailed` and stale delivery completions dispatch `RunStale`.
+- Kept GitHub Check publishing out of Slice 40 because no check publisher
+  exists yet; this slice creates the fanout seam that a later publisher can
+  subscribe to.
+- Pushed hosted commit `8795849 feat: emit terminal run events` to
+  `origin/codex/workos-authkit-api-foundation`.
+- Verified hosted focused behavior with
+  `uv run pytest tests/test_events_contract.py tests/test_updates_contract.py tests/test_architecture_contract.py -q`
+  (`108 passed`).
+- Verified hosted backend full behavior with `uv run pytest -q`
+  (`334 passed, 1 warning`), `uv run ruff check .`,
+  `uv run python -m compileall src modal_app -q`, and `git diff --check`.
+- Recorded progress as: CodeAlmanac backend/local 95%, CLI/public UX 87%,
+  CodeAlmanac-hosted backend/auth/API 85%, hosted frontend/onboarding 35%, and
+  infra/deploy rename 15%.

docs/plans/2026-07-02-slice-40-run-terminal-events.md

@@ -0,0 +1,92 @@
+# Run Terminal Events Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Emit first-class domain events when hosted runs fail or go stale.
+
+**Architecture:** Keep terminal run state in `UpdateCompletion`. The completion service already writes `runs` and `run_events`; it should also dispatch typed `RunFailed` and `RunStale` domain events next to the existing `RunDelivered` event. Provider-specific reactions such as GitHub Checks subscribe later through `wiring/fanout`.
+
+**Tech Stack:** Hosted FastAPI backend service layer, Pydantic domain events, SQLModel transaction-bound event dispatcher, pytest.
+
+---
+
+## Scope
+
+Implement now:
+
+- `RunFailed` domain event.
+- `RunStale` domain event.
+- Dispatch `RunFailed` when a worker completes with `error` or `blocked`.
+- Dispatch `RunStale` when delivery sees the expected branch head changed.
+- Tests proving events are dispatched after the run row and run event are
+  written.
+
+Defer:
+
+- GitHub Check Run publisher.
+- GitHub check-run retry action handling.
+- `codealmanac runs retry` and `codealmanac runs cancel`.
+
+## Design Wireframe
+
+```python
+failed = store.mark_failed(...)
+events.dispatch([RunFailed(...)], session=session)
+return UpdateResult.failed(failed, bundle)
+
+stale = store.mark_stale(...)
+events.dispatch([RunStale(...)], session=session)
+return UpdateResult.stale(stale, exc.reason)
+```
+
+`RunFailed` and `RunStale` carry repo/account/run/source facts. They do not know
+about GitHub checks, billing, Slack, dashboards, or CLI rendering.
+
+## Task 1: Domain Events
+
+**Files:**
+
+- Modify: `/Users/rohan/.config/superpowers/worktrees/usealmanac/hosted-baseline-convergence/backend/src/almanac/services/events/models.py`
+- Modify: `/Users/rohan/.config/superpowers/worktrees/usealmanac/hosted-baseline-convergence/backend/src/almanac/services/events/__init__.py`
+- Test: `/Users/rohan/.config/superpowers/worktrees/usealmanac/hosted-baseline-convergence/backend/tests/test_events_contract.py`
+
+**Steps:**
+
+1. Add `RunFailed` with run id, repo id, account id, repo full name, head sha,
+   and reason.
+2. Add `RunStale` with the same run facts plus expected and actual head shas.
+3. Add both to the `DomainEvent` type alias and export surface.
+
+## Task 2: Completion Dispatch
+
+**Files:**
+
+- Modify: `/Users/rohan/.config/superpowers/worktrees/usealmanac/hosted-baseline-convergence/backend/src/almanac/services/updates/completion.py`
+- Test: `/Users/rohan/.config/superpowers/worktrees/usealmanac/hosted-baseline-convergence/backend/tests/test_updates_contract.py`
+
+**Steps:**
+
+1. Dispatch `RunFailed` after `mark_failed`.
+2. Dispatch `RunStale` after `mark_stale`.
+3. Preserve conversation-batch success/failure/stale updates.
+4. Keep `RunDelivered` unchanged.
+
+## Task 3: Verification And Docs
+
+**Files:**
+
+- 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`
+- Modify: `/Users/rohan/Desktop/Projects/codealmanac/docs/codealmanac-launch/progress.md`
+
+**Verification:**
+
+```bash
+cd /Users/rohan/.config/superpowers/worktrees/usealmanac/hosted-baseline-convergence/backend
+uv run pytest tests/test_events_contract.py tests/test_updates_contract.py tests/test_architecture_contract.py -q
+uv run pytest -q
+uv run ruff check .
+uv run python -m compileall src modal_app -q
+git diff --check
+```