feat(launch): execute local engine runs

Author: rohans0509

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

@@ -10,22 +10,23 @@ verification, launch-folder updates, commit, and push.
 
 ## Last Completed Slice
 
-Slice 12 added deterministic local commit delivery.
+Slice 13 added local engine execution.
 
 Implemented:
 
-- `app.deliveries`
-- `app.workflows.local_delivery.deliver(...)`
-- native Git delivery adapter for expected-head reads, wiki-only patch
-  collection, patch application, and commit creation
-- moved-head handling: skip delivery and mark the run `stale`
-- empty-diff handling: skip delivery and mark the run `succeeded`
-- worker workspace path lookup by run id
+- `app.workflows.local_engine.execute(...)`
+- update-operation prompt at `src/codealmanac/prompts/operations/update.md`
+- local engine result helpers for deterministic `docs almanac:` subjects
+- normalized run-event recording for harness events
+- success path: request artifact -> harness run in worker repo -> result
+  artifact -> `result_ref` on the control run
+- failure path: failed harness or missing prepared request -> failed control
+  run and failed engine result when possible
 
 Verified:
 
 ```text
-uv run pytest tests/test_deliveries_service.py tests/test_local_delivery_workflow.py tests/test_git_local_delivery.py tests/test_worker_workspaces_service.py tests/test_architecture.py
+uv run pytest tests/test_local_engine_workflow.py tests/test_engine_runs_service.py tests/test_architecture.py
 uv run pytest
 uv run ruff check .
 git diff --check
@@ -38,16 +39,18 @@ Choose the next substantial slice from the launch plan. Good candidates:
 - local trigger event recording through Git hooks
 - public or hidden setup command that calls `app.local_hooks`
 - local run storage bridge from repo-local job files to the control DB
-- local model worker execution from prepared `EngineRunRequest`
+- local worker orchestration that chains prepare -> engine -> delivery
+- prompt restoration / first-build `init` path from
+  `docs/codealmanac-launch/init-first-build-prompt-restoration.md`
 
 Before coding, write the next slice plan under `docs/plans/`, then implement
 the full slice, update this brief, update `progress.md`, send a RelayForge
 progress update, commit, and push.
 
 ## Known Repo State
 
-The branch is `dev`. At the start of Slice 12 it was clean and even with
-`origin/dev`.
+The branch is `dev`. At the end of Slice 13 verification it was ready to
+commit on top of `origin/dev`.
 
 The local wiki command currently fails on this checkout with:
 

docs/codealmanac-launch/ownership-map.md

@@ -16,6 +16,7 @@ Owns:
 - local capture storage
 - local Git hook dispatchers
 - local worker workspace creation
+- local engine execution
 - deterministic local delivery
 - auto-update client behavior
 
@@ -74,4 +75,3 @@ engine result
 ```
 
 Both cloud and local workers call this boundary.
-

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 12 verification.
+Sent: pending after Slice 13 verification.
 
 Route:
 
@@ -26,7 +26,7 @@ It was not present in `codealmanac/prd` when checked.
 
 | Area | Latest | Previous | Basis |
 | --- | ---: | ---: | --- |
-| CodeAlmanac backend/local | 58% | 53% | Slice 12 added deterministic local commit delivery from worker repo patches with expected-head checks. |
+| CodeAlmanac backend/local | 63% | 58% | Slice 13 added local engine execution from prepared request/source/workspace artifacts through the harness boundary. |
 | CodeAlmanac CLI/public UX | 10% | 10% | Hidden trigger command exists; launch public CLI surface is not rebuilt yet. |
 | CodeAlmanac-hosted backend/auth/API | 8% | 8% | WorkOS/Doppler setup and hosted rename groundwork exist; public API migration is not implemented yet. |
 | Hosted frontend/onboarding | 5% | 5% | Existing frontend is deployed under CodeAlmanac; new onboarding/configuration screens are not implemented yet. |

docs/codealmanac-launch/verification-matrix.md

@@ -132,6 +132,16 @@ Current evidence:
   root.
 - `tests/test_architecture.py` proves Git delivery mechanics stay in
   `integrations/workspaces/git/delivery.py`, not in the workflow.
+- Slice 13 added local engine execution.
+- `tests/test_local_engine_workflow.py` proves the workflow reads a prepared
+  engine request, runs the harness in the worker repo, writes `result.json`,
+  stores `result_ref`, and records normalized run events.
+- `tests/test_local_engine_workflow.py` proves failed harness runs mark the
+  control run `failed` and write a failed engine result.
+- `tests/test_local_engine_workflow.py` proves a missing prepared request fails
+  the control run without invoking the harness.
+- `tests/test_architecture.py` proves local engine execution stays separate
+  from Git delivery, subprocess mechanics, SQL, and CLI strings.
 
 Commands:
 

docs/codealmanac-launch/worklog.md

@@ -261,3 +261,23 @@
   `uv run pytest tests/test_deliveries_service.py tests/test_local_delivery_workflow.py tests/test_git_local_delivery.py tests/test_worker_workspaces_service.py tests/test_architecture.py`.
 - Verified Slice 12 full gate with `uv run pytest` (`407 passed`),
   `uv run ruff check .`, and `git diff --check`.
+- Sent the Slice 12 RelayForge update and recorded progress as:
+  CodeAlmanac backend/local 58%, CLI/public UX 10%,
+  CodeAlmanac-hosted backend/auth/API 8%, hosted frontend/onboarding 5%, and
+  infra/deploy rename 5%.
+- Planned Slice 13 in
+  `docs/plans/2026-07-02-slice-13-local-engine-execution.md`.
+- Added `app.workflows.local_engine.execute(...)`.
+- Added `src/codealmanac/workflows/local_engine/` with request/result models,
+  update prompt rendering, deterministic result helpers, and run-event
+  recording helpers.
+- Added `src/codealmanac/prompts/operations/update.md`.
+- Wired local engine execution through the existing harness seam:
+  `RunHarnessRequest(kind, cwd, prompt, title)`.
+- The local engine now reads prepared `request.json`, runs the model in the
+  worker repo, writes `result.json`, stores `result_ref`, and leaves delivery
+  to `app.workflows.local_delivery`.
+- Verified Slice 13 focused behavior with
+  `uv run pytest tests/test_local_engine_workflow.py tests/test_engine_runs_service.py tests/test_architecture.py`.
+- Verified Slice 13 full gate with `uv run pytest` (`411 passed`),
+  `uv run ruff check .`, and `git diff --check`.

docs/plans/2026-07-02-slice-13-local-engine-execution.md

@@ -0,0 +1,114 @@
+# Slice 13 Plan: Local Engine Execution
+
+Status: planned.
+Date: 2026-07-02.
+
+## Intent
+
+Complete the middle of the local launch pipeline:
+
+```python
+prepared = app.workflows.local_runs.prepare_next()
+engine = app.workflows.local_engine.execute(run_id, harness)
+delivery = app.workflows.local_delivery.deliver(run_id)
+```
+
+Slice 13 does not expose a public CLI command. It adds the backend workflow that
+cloud and local orchestration can call without going through human CLI strings.
+
+## Product Contract
+
+- The worker receives sources by reference through `sources_path`.
+- The model runs inside the prepared worker repo, not the user's active checkout.
+- The model may edit only the configured Almanac root.
+- The engine writes `~/.codealmanac/runs/<run-id>/result.json`.
+- The engine records normalized `run_events` in `~/.codealmanac/control.sqlite`.
+- The engine does not commit, merge, open PRs, or deliver changes.
+- Delivery remains deterministic and separate.
+
+## Code Shape
+
+```python
+result = app.workflows.local_engine.execute(
+    ExecuteLocalEngineRunRequest(run_id=run.id, harness=HarnessKind.CODEX)
+)
+```
+
+Ownership:
+
+- `workflows/local_engine/` owns orchestration for executing a prepared engine
+  request.
+- `services/engine_runs/` continues to own request/result artifacts.
+- `services/harnesses/` continues to own provider-neutral model execution.
+- `workflows/local_delivery/` remains the only local writer to the real
+  checkout.
+
+## Implementation Scope
+
+Add:
+
+- `src/codealmanac/workflows/local_engine/`
+  - `requests.py`
+  - `models.py`
+  - `prompt.py`
+  - `service.py`
+  - `__init__.py`
+- `src/codealmanac/prompts/operations/update.md`
+- `PromptName.OPERATION_UPDATE`
+- `app.workflows.local_engine`
+- tests for success, failure, and event/result recording
+
+The workflow should:
+
+1. Read the control run and prepared `EngineRunRequest`.
+2. Mark the control run `running`.
+3. Render an update prompt with the request JSON as runtime context.
+4. Run the requested harness with `cwd=request.repo_path`.
+5. Append normalized harness events to `run_events`.
+6. Write an `EngineRunResult`.
+7. Store `result_ref` on the control run.
+8. On harness failure, write a failed engine result, mark the run `failed`, and
+   append an error event.
+
+## Out Of Scope
+
+- Public CLI command surface.
+- Cloud worker execution.
+- WorkOS/API/auth changes.
+- Delivery changes.
+- Parsing a commit subject out of model prose.
+
+## Verification
+
+Focused:
+
+```bash
+uv run pytest tests/test_local_engine_workflow.py tests/test_engine_runs_service.py tests/test_architecture.py
+```
+
+Full gate:
+
+```bash
+uv run pytest
+uv run ruff check .
+git diff --check
+```
+
+## Architecture Notes
+
+The workflow can deterministically derive a commit subject from the harness
+summary:
+
+```text
+docs almanac: <summary>
+```
+
+If no usable summary exists, use:
+
+```text
+docs almanac: update wiki
+```
+
+The prompt should still instruct the model to produce a concise summary, but
+the Python code should not scrape durable fields out of unstructured final
+assistant text.

src/codealmanac/app.py

@@ -78,6 +78,7 @@
 from codealmanac.workflows.lifecycle import LifecycleMutationPolicy
 from codealmanac.workflows.local_delivery import LocalDeliveryWorkflow
 from codealmanac.workflows.local_delivery.ports import LocalGitDeliveryManager
+from codealmanac.workflows.local_engine import LocalEngineWorkflow
 from codealmanac.workflows.local_runs import LocalRunPreparationWorkflow
 from codealmanac.workflows.page_run import PageRunWorkflow
 from codealmanac.workflows.run_queue import RunQueueWorkflow
@@ -92,6 +93,7 @@ class CodeAlmanacWorkflows:
     garden: GardenWorkflow
     queue: RunQueueWorkflow
     local_runs: LocalRunPreparationWorkflow
+    local_engine: LocalEngineWorkflow
     local_delivery: LocalDeliveryWorkflow
     sync: SyncWorkflow
 
@@ -230,6 +232,12 @@ def create_app(
         source_bundles,
         engine_runs,
     )
+    local_engine = LocalEngineWorkflow(
+        control,
+        engine_runs,
+        harnesses,
+        prompts,
+    )
     local_delivery = LocalDeliveryWorkflow(
         control,
         deliveries,
@@ -244,6 +252,7 @@ def create_app(
         garden=garden,
         queue=queue,
         local_runs=local_runs,
+        local_engine=local_engine,
         local_delivery=local_delivery,
         sync=sync,
     )

src/codealmanac/prompts/models.py

@@ -7,3 +7,4 @@ class PromptName(StrEnum):
     BASE_SYNTAX = "base/syntax.md"
     OPERATION_INGEST = "operations/ingest.md"
     OPERATION_GARDEN = "operations/garden.md"
+    OPERATION_UPDATE = "operations/update.md"

src/codealmanac/prompts/operations/update.md

@@ -0,0 +1,27 @@
+# Update Operation
+
+Update refreshes the configured Almanac wiki after a finalization event on a
+configured branch.
+
+Before editing, read `manual/README.md`, `manual/pages.md`,
+`manual/evidence.md`, `manual/style.md`, and `manual/sources.md` under the
+configured Almanac root when those files exist.
+
+Use the runtime context as the execution contract. The repository checkout is
+already positioned at the expected head SHA. The `sources_path` directory
+contains source material by reference. Read `sources_path/manifest.json`, then
+read the full session files or other referenced files that are relevant to the
+update.
+
+Do not copy source material into the wiki. Distill durable project knowledge:
+decisions, flows, invariants, incidents, gotchas, and source-backed changes
+that help future agents. Update existing pages when they are the right home.
+Create new pages only when the material names a stable concept that deserves
+one.
+
+Only edit files under the configured Almanac root. Do not commit, open a pull
+request, modify delivery state, or edit files outside the configured Almanac
+root. Delivery is handled after this engine run.
+
+End with a concise one-line summary of the wiki change. The commit subject will
+be derived from that summary using the configured `docs almanac:` style.

src/codealmanac/services/engine_runs/service.py

@@ -1,5 +1,6 @@
 from codealmanac.core.errors import NotFoundError
 from codealmanac.services.engine_runs.models import (
+    EngineRunArtifactPaths,
     EngineRunRequest,
     EngineRunResult,
     PreparedEngineRun,
@@ -16,6 +17,9 @@ class EngineRunsService:
     def __init__(self, store: EngineRunsStore):
         self.store = store
 
+    def paths(self, run_id: str) -> EngineRunArtifactPaths:
+        return self.store.paths(run_id)
+
     def prepare(self, request: PrepareEngineRunRequest) -> PreparedEngineRun:
         paths = self.store.paths(request.run_id)
         engine_request = EngineRunRequest(