# M47 Execution Checklist: Persistent Worker Runtime (PR-Sized Plan)

**Parent Spec:** `spec-files/outstanding/agentic_orchestrator_persistent_worker_runtime_spec.md`  
**Version:** 1.0  
**Date:** 2026-03-05  
**Status:** Draft

---

## 0. Purpose

This checklist breaks M47 into mergeable, low-risk PR slices with deterministic test gates.

Each PR below is intentionally scoped to one logical concern and can be reviewed independently.

---

## 1. Global Merge Rules

- Keep all worker code mutation paths patch-mediated (`PATCH` -> `repo.apply_patch` only).
- Do not change role firewall or tool authorization behavior.
- Keep backward-compatible defaults (`worker_execution_mode: turn_spawn`).
- Keep codex/claude persistent capability disabled by default in M47 baseline.
- Each PR must pass:
  - `npm run lint`
  - `npm run typecheck`
  - `npm test`

---

## 2. PR Sequence Overview

| PR ID     | Slice | Scope                                         | Risk   | Depends On |
| --------- | ----- | --------------------------------------------- | ------ | ---------- |
| PR-M47-01 | M47.1 | Schema and config contracts                   | Low    | None       |
| PR-M47-02 | M47.1 | Error taxonomy + config plumb                 | Low    | PR-M47-01  |
| PR-M47-03 | M47.2 | Execution strategy abstraction                | Medium | PR-M47-02  |
| PR-M47-04 | M47.2 | Persistent runtime manager core               | Medium | PR-M47-03  |
| PR-M47-05 | M47.3 | Provider capability negotiation               | Medium | PR-M47-04  |
| PR-M47-06 | M47.3 | CLI provider integration + fallback           | High   | PR-M47-05  |
| PR-M47-07 | M47.4 | Session lifecycle wiring                      | Medium | PR-M47-06  |
| PR-M47-08 | M47.4 | Resume and restart policy wiring              | High   | PR-M47-07  |
| PR-M47-09 | M47.5 | Runtime observability artifacts and reporting | Medium | PR-M47-08  |
| PR-M47-10 | M47.6 | Integration and regression hardening          | High   | PR-M47-09  |

---

## 3. PR Details

## PR-M47-01 - Runtime Mode and Policy Schema Contracts

**Maps to:** M47.1

**Goal:** Add additive runtime/policy config fields and schema validation support.

**Files:**

- `agentic/orchestrator/agents.yaml`
- `agentic/orchestrator/schemas/agents.schema.json`
- `agentic/orchestrator/policy.yaml`
- `agentic/orchestrator/schemas/policy.schema.json`

**Checklist:**

- [ ] Add `worker_execution_mode` and runtime limits fields.
- [ ] Add persistent failure policy fields.
- [ ] Add provider override schema with codex/claude defaults disabled.
- [ ] Preserve backward compatibility when fields are absent.

**Tests:**

- [ ] Schema validation tests for valid/invalid runtime fields.
- [ ] Schema validation tests for invalid provider override keys and missing protocol values.

## PR-M47-02 - Error Codes and Runtime Config Plumbing

**Maps to:** M47.1

**Goal:** Introduce new persistent-runtime error codes and thread config values through runtime creation paths.

**Files:**

- `apps/control-plane/src/core/error-codes.ts`
- `apps/control-plane/src/providers/worker-provider-factory.ts`
- `apps/control-plane/src/cli/run-command-handler.ts`
- `apps/control-plane/src/cli/resume-command-handler.ts`

**Checklist:**

- [ ] Add new runtime failure codes.
- [ ] Thread runtime-mode config into provider factory input.
- [ ] Preserve existing behavior when mode is `turn_spawn`.

**Tests:**

- [ ] Unit tests for config resolution defaults and invalid combinations.
- [ ] Unit tests for deterministic error code mapping in setup failures.

## PR-M47-03 - Worker Execution Strategy Abstraction

**Maps to:** M47.2

**Goal:** Introduce strategy interface and extract current spawn-per-turn behavior into explicit strategy class.

**Files:**

- `apps/control-plane/src/providers/worker-execution-strategy.ts` (new)
- `apps/control-plane/src/providers/providers.ts`
- `apps/control-plane/src/providers/cli-worker-provider.ts`

**Checklist:**

- [ ] Define `WorkerExecutionMode` and strategy interface.
- [ ] Implement `SpawnPerTurnExecutionStrategy` as behavior-preserving extraction.
- [ ] Keep current run path functionally identical.

**Tests:**

- [ ] Regression tests proving output equivalence pre/post extraction.
- [ ] No-op behavior confirmation for mode defaulting.

## PR-M47-04 - Persistent Runtime Manager Core

**Maps to:** M47.2

**Goal:** Build runtime manager with handle lifecycle, restart counters, and bounded limits.

**Files:**

- `apps/control-plane/src/providers/persistent-worker-runtime-manager.ts` (new)
- `apps/control-plane/src/providers/providers.ts`

**Checklist:**

- [ ] Implement runtime handle state machine.
- [ ] Implement `ensureReady`, `runTurn`, `closeRuntime`.
- [ ] Implement restart budgeting and exhaustion handling.

**Tests:**

- [ ] Unit tests for boot success/failure and restart loops.
- [ ] Unit tests for idle TTL and max-turn rollover behavior.

## PR-M47-05 - Provider Capability Negotiation

**Maps to:** M47.3

**Goal:** Add deterministic provider capability matrix and policy-based fallback.

**Files:**

- `apps/control-plane/src/providers/worker-provider-factory.ts`
- `apps/control-plane/src/providers/cli-worker-provider.ts`
- `apps/control-plane/src/providers/api-worker-provider.ts`

**Checklist:**

- [ ] Implement capability defaults:
  - codex: persistent disabled by default
  - claude: persistent disabled by default
  - custom: config-driven
  - gemini: unchanged API path
- [ ] Enforce required-vs-optional persistent behavior.
- [ ] Emit fallback telemetry event when degrading to `turn_spawn`.

**Tests:**

- [ ] Factory tests for unsupported capability with required persistent mode.
- [ ] Factory tests for optional mode fallback.

## PR-M47-06 - CLI Provider Persistent Path Integration

**Maps to:** M47.3

**Goal:** Wire `CliWorkerProvider` to strategy mode selection and runtime manager calls.

**Files:**

- `apps/control-plane/src/providers/cli-worker-provider.ts`
- `apps/control-plane/src/providers/output-parsers/*.ts`

**Checklist:**

- [ ] Route turns through selected strategy.
- [ ] Keep output parser contract unchanged.
- [ ] Preserve and test session-id behavior across repeated turns.

**Tests:**

- [ ] Adapter tests proving stable runtime identity across repeated turns in persistent mode.
- [ ] Adapter tests proving existing turn-spawn behavior unchanged.

## PR-M47-07 - Session Lifecycle Boot and Teardown Wiring

**Maps to:** M47.4

**Goal:** Integrate runtime boot and close into feature cluster lifecycle.

**Files:**

- `apps/control-plane/src/supervisor/session-orchestrator.ts`
- `apps/control-plane/src/supervisor/runtime.ts`

**Checklist:**

- [ ] Eager boot on cluster init when configured.
- [ ] Deterministic teardown on cluster close.
- [ ] Ensure no runtime leak on terminal feature states.

**Tests:**

- [ ] Unit tests for init/close lifecycle with persistent mode.
- [ ] Unit tests for no-op behavior under turn-spawn mode.

## PR-M47-08 - Resume Reconstruction and Restart Policy Enforcement

**Maps to:** M47.4

**Goal:** Reconstruct runtimes on resume and enforce restart policy actions deterministically.

**Files:**

- `apps/control-plane/src/supervisor/runtime.ts`
- `apps/control-plane/src/supervisor/worker-decision-loop.ts`
- `apps/control-plane/src/supervisor/build-wave-executor.ts`
- `apps/control-plane/src/supervisor/qa-wave-executor.ts`

**Checklist:**

- [ ] Rebuild runtime map from active feature/session assignments.
- [ ] Apply restart exhaustion policy (`block_feature` vs `fail_run`).
- [ ] Keep feature-scoped failures isolated from unrelated features.

**Tests:**

- [ ] Resume tests with dead runtime reconstruction.
- [ ] Wave policy tests for restart exhaustion behavior.

## PR-M47-09 - Runtime Observability Artifacts and Reporting

**Maps to:** M47.5

**Goal:** Persist runtime registry and event artifacts and expose summary fields in dashboard/report outputs.

**Files:**

- `apps/control-plane/src/core/path-layout.ts`
- `apps/control-plane/src/supervisor/worker-decision-loop.ts`
- `apps/control-plane/src/application/services/reporting-service.ts`

**Checklist:**

- [ ] Write `.aop/runtime/worker-runtime-registry/<run_id>.json`.
- [ ] Append `.aop/runtime/worker-runtime-events/<run_id>.jsonl` entries.
- [ ] Include runtime summary in reporting payloads.

**Tests:**

- [ ] Artifact creation and append-only behavior tests.
- [ ] Reporting tests for runtime summary fields.

## PR-M47-10 - End-to-End Regression and Safety Hardening

**Maps to:** M47.6

**Goal:** Land full integration coverage and non-regression guarantees before mode rollout.

**Files:**

- `apps/control-plane/test/providers.spec.ts`
- `apps/control-plane/test/worker-provider-adapters.spec.ts`
- `apps/control-plane/test/worker-execution-policy.spec.ts`
- `apps/control-plane/test/supervisor.unit.spec.ts`
- `apps/control-plane/test/supervisor.spec.ts`

**Checklist:**

- [ ] Multi-feature mixed-health integration scenario.
- [ ] Persistent failure fallback scenario.
- [ ] Patch-mediation invariants unchanged.
- [ ] Role firewall and idempotency non-regression assertions.

**Tests:**

- [ ] `npm test` includes all M47 scenarios.
- [ ] Coverage remains >=90% for all thresholds.

---

## 4. Rollout Recommendation

Rollout should be staged:

1. Land all PRs with `worker_execution_mode: turn_spawn` default unchanged.
2. Enable persistent mode only in controlled local/staging runs.
3. Track runtime restart/fallback metrics for at least one week of realistic workloads.
4. Only then consider flipping default for providers that prove protocol stability.

---

## 5. Definition of Ready for Implementation

M47 implementation can start when:

- parent spec (M47) is approved
- this checklist is approved
- provider assumptions for codex and claude are accepted as baseline constraints
- CI baseline (`lint`, `typecheck`, `test`) is green before PR-M47-01
