feat(launch): materialize source bundles

Author: rohans0509

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

@@ -10,22 +10,22 @@ verification, launch-folder updates, commit, and push.
 
 ## Last Completed Slice
 
-Slice 10 added branch-head staling.
+Slice 11 added source bundle materialization.
 
 Implemented:
 
-- `app.control.get_run(...)`
-- staling of queued/running runs when a newer trigger arrives for the same
-  branch with a different expected head
-- normalized stale run events
-- preservation of terminal runs
-- preservation of queued/running runs already targeting the new head
-- removal of unused `EnsureControlSchemaRequest`
+- control DB verbs for sessions, turns, turn-branch links, and branch session
+  selection
+- `app.source_bundles`
+- `sources/manifest.json`
+- copied full session files under `sources/sessions/<provider>/`
+- local run preparation that materializes source bundles before writing
+  `request.json`
 
 Verified:
 
 ```text
-uv run pytest tests/test_control_service.py tests/test_architecture.py
+uv run pytest tests/test_control_service.py tests/test_source_bundles_service.py tests/test_local_run_preparation_workflow.py tests/test_architecture.py
 uv run pytest
 uv run ruff check .
 git diff --check
@@ -38,7 +38,6 @@ 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
-- source bundle selection materialization for claimed runs
 - local model worker execution from prepared `EngineRunRequest`
 - delivery commit application from `EngineRunResult`
 
@@ -48,7 +47,7 @@ progress update, commit, and push.
 
 ## Known Repo State
 
-The branch is `dev`. At the start of Slice 10 it was clean and even with
+The branch is `dev`. At the start of Slice 11 it was clean and even with
 `origin/dev`.
 
 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 10 verification.
+Sent: 2026-07-02 after Slice 11 verification.
 
 Route:
 
@@ -26,7 +26,7 @@ It was not present in `codealmanac/prd` when checked.
 
 | Area | Latest | Previous | Basis |
 | --- | ---: | ---: | --- |
-| CodeAlmanac backend/local | 50% | 47% | Slice 10 added branch-head staling so newer triggers mark older queued/running runs stale before delivery can use an old expected head. |
+| CodeAlmanac backend/local | 53% | 50% | Slice 11 added branch session selection and local source bundle materialization into worker `sources/`. |
 | 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/schema-contract.md

@@ -55,6 +55,8 @@ Local worker workspaces:
 ~/.codealmanac/workspaces/<run-id>/
   repo/
   sources/
+    manifest.json
+    sessions/
   run/
 ```
 

docs/codealmanac-launch/verification-matrix.md

@@ -111,6 +111,15 @@ Current evidence:
   runs are preserved.
 - `tests/test_control_service.py` proves stale runs receive normalized status
   run events.
+- Slice 11 added branch session selection and source bundle materialization.
+- `tests/test_control_service.py` proves branch selection returns distinct full
+  sessions through `turn_branches`.
+- `tests/test_source_bundles_service.py` proves session source files are copied
+  into `sources/sessions/<provider>/` and recorded in `manifest.json`.
+- `tests/test_local_run_preparation_workflow.py` proves local run preparation
+  materializes the source bundle before writing the engine request.
+- `tests/test_architecture.py` proves source-bundle materialization remains a
+  separate service boundary.
 
 Commands:
 

docs/codealmanac-launch/worklog.md

@@ -225,3 +225,21 @@
   `uv run pytest tests/test_control_service.py tests/test_architecture.py`.
 - Verified Slice 10 full gate with `uv run pytest` (`394 passed`),
   `uv run ruff check .`, and `git diff --check`.
+- Sent the Slice 10 RelayForge update and recorded progress as:
+  CodeAlmanac backend/local 50%, CLI/public UX 10%,
+  CodeAlmanac-hosted backend/auth/API 8%, hosted frontend/onboarding 5%, and
+  infra/deploy rename 5%.
+- Planned Slice 11 in
+  `docs/plans/2026-07-02-slice-11-source-bundle-materialization.md`.
+- Added control DB verbs for sessions, turns, turn-branch links, and distinct
+  branch session selection.
+- Added `app.source_bundles` with a manifest-backed local source bundle
+  materializer.
+- Wired local run preparation to materialize `sources/manifest.json` and copied
+  session files before writing the engine request.
+- Added architecture guards for the source-bundle service boundary.
+- Corrected the launch plan commit-subject example to `docs almanac:`.
+- Verified Slice 11 focused behavior with
+  `uv run pytest tests/test_control_service.py tests/test_source_bundles_service.py tests/test_local_run_preparation_workflow.py tests/test_architecture.py`.
+- Verified Slice 11 full gate with `uv run pytest` (`398 passed`),
+  `uv run ruff check .`, and `git diff --check`.

docs/plans/2026-07-02-codealmanac-cloud-local-launch.md

@@ -40,7 +40,7 @@ nouns and execution shape, not a separate conceptual product.
 - Use commit subject format:
 
 ```text
-almanac: <summary>
+docs almanac: <summary>
 ```
 
 ## Target Shape
@@ -108,7 +108,7 @@ EngineRunRequest
   expected_head_sha
   operation
   almanac_root
-  commit_subject_style = "almanac: <summary>"
+  commit_subject_style = "docs almanac: <summary>"
 
 EngineRunResult
   status
@@ -141,7 +141,7 @@ Git hook fires
   -> publisher collects wiki patch
   -> publisher checks current branch still equals expected_head_sha
   -> publisher applies patch to real checkout
-  -> publisher commits "almanac: <summary>"
+  -> publisher commits "docs almanac: <summary>"
 ```
 
 Local workspace:

docs/plans/2026-07-02-slice-11-source-bundle-materialization.md

@@ -0,0 +1,82 @@
+# Slice 11: Source Bundle Materialization
+
+Date: 2026-07-02.
+Status: planned.
+
+## Goal
+
+Materialize the local worker `sources/` folder during local run preparation.
+The run request should continue to pass a `sources_path` and
+`source_bundle_ref`; it should not inline session contents or selected source
+payloads.
+
+## Shape
+
+```python
+sessions = control.list_sessions_for_branch(branch.id)
+bundle = source_bundles.materialize(
+    run_id=run.id,
+    branch_id=branch.id,
+    target_path=worker_workspace.paths.sources_path,
+    sessions=sessions,
+)
+engine = engine_runs.prepare(..., sources_path=bundle.root_path)
+```
+
+The control DB owns session/turn/branch relationships. The source-bundle service
+owns file materialization and the manifest format. The local-run workflow only
+orchestrates services.
+
+## In Scope
+
+- Add control service verbs for:
+  - upserting sessions
+  - upserting turns
+  - linking turns to branches
+  - listing distinct sessions connected to a branch
+- Add `services/source_bundles` with:
+  - typed manifest models
+  - a materialization request
+  - a store that copies referenced local session files into `sources/`
+  - `manifest.json`
+- Wire local run preparation to materialize the source bundle before writing
+  `request.json`.
+- Add tests for control session selection, source bundle materialization, and
+  local run preparation.
+- Update launch docs and progress.
+
+## Out Of Scope
+
+- Conversation capture hooks.
+- Branch detection algorithms.
+- Git commit range evidence.
+- Model execution.
+- Delivery application.
+
+## Design Decisions
+
+- The selector is intentionally simple: include every full session with at least
+  one turn linked to the branch.
+- The bundle copies source files into the worker workspace, but the run request
+  still passes the bundle by reference via `sources_path` and
+  `source_bundle_ref`.
+- Session destination filenames use the stable local session row id, not raw
+  provider paths.
+- Missing or unsupported session refs fail preparation. That is better than
+  silently running with incomplete source context.
+
+## Verification
+
+Focused:
+
+```text
+uv run pytest tests/test_control_service.py tests/test_source_bundles_service.py tests/test_local_run_preparation_workflow.py tests/test_architecture.py
+```
+
+Full:
+
+```text
+uv run pytest
+uv run ruff check .
+git diff --check
+```

src/codealmanac/app.py

@@ -47,6 +47,8 @@
 from codealmanac.services.search.service import SearchService
 from codealmanac.services.setup.ports import InstructionInstaller
 from codealmanac.services.setup.service import SetupService
+from codealmanac.services.source_bundles.service import SourceBundlesService
+from codealmanac.services.source_bundles.store import SourceBundlesStore
 from codealmanac.services.sources.ports import (
     SourceRuntimeAdapter,
     TranscriptDiscoveryAdapter,
@@ -95,6 +97,7 @@ class CodeAlmanac:
     control: ControlService
     engine_runs: EngineRunsService
     local_hooks: LocalHooksService
+    source_bundles: SourceBundlesService
     worker_workspaces: WorkerWorkspacesService
     workspaces: WorkspacesService
     wiki: WikiService
@@ -138,6 +141,7 @@ def create_app(
         local_git_state_probe or GitLocalStateProbe(),
     )
     engine_runs = EngineRunsService(EngineRunsStore(app_config.run_artifacts_path))
+    source_bundles = SourceBundlesService(SourceBundlesStore())
     local_hooks = LocalHooksService(
         local_git_hook_manager or FileLocalGitHookManager(),
     )
@@ -214,6 +218,7 @@ def create_app(
     local_runs = LocalRunPreparationWorkflow(
         control,
         worker_workspaces,
+        source_bundles,
         engine_runs,
     )
     sync = SyncWorkflow(workspaces, sources, runs, ingest, queue, SyncLedgerStore())
@@ -231,6 +236,7 @@ def create_app(
         control=control,
         engine_runs=engine_runs,
         local_hooks=local_hooks,
+        source_bundles=source_bundles,
         worker_workspaces=worker_workspaces,
         workspaces=workspaces,
         wiki=wiki,

src/codealmanac/services/control/current_git.py

@@ -0,0 +1,35 @@
+from codealmanac.services.control.models import RecordTriggerEventResult
+from codealmanac.services.control.ports import LocalGitStateProbe
+from codealmanac.services.control.requests import (
+    RecordCurrentGitTriggerRequest,
+    RecordLocalTriggerRequest,
+)
+from codealmanac.services.control.store import ControlStore
+
+
+def record_current_git_trigger(
+    store: ControlStore,
+    local_git_state: LocalGitStateProbe,
+    request: RecordCurrentGitTriggerRequest,
+) -> RecordTriggerEventResult:
+    state = local_git_state.read(request.cwd)
+    if (
+        not state.available
+        or state.repository_root is None
+        or state.branch_name is None
+        or state.head_sha is None
+    ):
+        return RecordTriggerEventResult(
+            recorded=False,
+            reason="git_state_unavailable",
+        )
+    return store.record_local_trigger(
+        RecordLocalTriggerRequest(
+            repository_root=state.repository_root,
+            branch_name=state.branch_name,
+            kind=request.kind,
+            head_sha=state.head_sha,
+            previous_head_sha=request.previous_head_sha,
+            payload_ref=request.payload_ref,
+        )
+    )

src/codealmanac/services/control/models.py

@@ -46,6 +46,11 @@ class ControlRunEventKind(StrEnum):
     ERROR = "error"
 
 
+class SessionProvider(StrEnum):
+    CODEX = "codex"
+    CLAUDE = "claude"
+
+
 class RepositoryRecord(CodeAlmanacModel):
     id: str
     provider: str
@@ -222,6 +227,70 @@ def require_message(cls, value: str) -> str:
         return required_text(value, "run event message")
 
 
+class SessionRecord(CodeAlmanacModel):
+    id: str
+    provider: SessionProvider
+    provider_session_id: str
+    source_ref: str
+    started_at: datetime | None = None
+    ended_at: datetime | None = None
+    created_at: datetime
+    updated_at: datetime
+
+    @field_validator("id")
+    @classmethod
+    def require_id(cls, value: str) -> str:
+        return required_text(value, "session id")
+
+    @field_validator("provider_session_id")
+    @classmethod
+    def require_provider_session_id(cls, value: str) -> str:
+        return required_text(value, "provider session id")
+
+    @field_validator("source_ref")
+    @classmethod
+    def require_source_ref(cls, value: str) -> str:
+        return required_text(value, "session source ref")
+
+
+class TurnRecord(CodeAlmanacModel):
+    id: str
+    session_id: str
+    provider_turn_id: str | None = None
+    sequence: int
+    created_at: datetime
+    metadata_json: str
+
+    @field_validator("id")
+    @classmethod
+    def require_id(cls, value: str) -> str:
+        return required_text(value, "turn id")
+
+    @field_validator("session_id")
+    @classmethod
+    def require_session_id(cls, value: str) -> str:
+        return required_text(value, "turn session id")
+
+    @field_validator("provider_turn_id")
+    @classmethod
+    def require_optional_provider_turn_id(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        return required_text(value, "provider turn id")
+
+    @field_validator("sequence")
+    @classmethod
+    def require_positive_sequence(cls, value: int) -> int:
+        if value < 1:
+            raise ValueError("turn sequence must be positive")
+        return value
+
+    @field_validator("metadata_json")
+    @classmethod
+    def require_metadata_json(cls, value: str) -> str:
+        return required_text(value, "turn metadata json")
+
+
 class ClaimNextTriggerResult(CodeAlmanacModel):
     claimed: bool
     reason: str | None = None