type: meta

slug: observability-control-api

base_branch: feat/cursor-codex-preset

gate0_mode: strict

preset: cursor-codex

land_mode: merge-to-main


type: goal

text: Ship lossless attempt observability and complete control API as one gated DAG while every old plan and active journal missing new fields keeps current behavior.


type: methodology

text: Contract-first TDD; one multi-wave DAG; strict deterministic gate after every task; serialize shared-file edits; centralized removable legacy boundary; fail closed on state mutation, never on missing optional observability.


type: intent

text: Upgrade live harness without interrupting or migrating current plans, then make legacy compatibility removable as one explicit retirement change.


type: direction

verbatim: need to make sure the new upgraded runplan harness can run with old plans until they are retired. so the new fields are not mandatory for a run, if these fields are missing just ignore them and work as it is now, but make it easy to remove the legacy behavior as soon as the current plans stop running.


verbatim: basically, why not just make one long DAG with runplan, and have proper gates ?


type: deferred

text: Observability compatibility retirement

reason: Requires runtime inventory proving zero nonterminal legacy plans/runs after this upgrade lands.


type: gated

category: policy

needs: Authorize declared harness source/spec/test changes

why: Harness protects src/ and spec/; user explicitly requested execution of this upgrade.

status: RESOLVED

resolved_by: user

source: author


type: task

seat: coder

tier: high

desc: Read docs/plans/2026-07-18-observability-control-api.md Task 1 (Compatibility boundary + deletion manifest) for the full contract. Centralize optional-field behavior and retirement inventory. Acceptance: node --test src/observability.test.js. Commit only: src/observability.js, src/observability.test.js, spec/OBSERVABILITY-COMPAT.md.

requires_decision: g-protected-observability


desc: Read docs/plans/2026-07-18-observability-control-api.md Task 2 (Attempt lifecycle + producer enrichment + acceptance) for the full contract. Emit durable correlated optional observability without changing old runs. Acceptance: node --test src/test/observability-producers.test.js src/test/runner-transcript.test.js src/test/engine-gates.test.js. Commit only: src/runner.js, src/engine/gates.js, spec/events.schema.json, src/test/runner-transcript.test.js, src/test/engine-gates.test.js, src/test/observability-producers.test.js.


desc: Read docs/plans/2026-07-18-observability-control-api.md Task 3 (Authoritative event feed + SSE replay) for the full contract. Provide bounded composite-cursor event reads and live replay. Acceptance: node --test src/event-feed.test.js. Commit only: src/event-feed.js, src/event-feed.test.js.


desc: Read docs/plans/2026-07-18-observability-control-api.md Task 4 (Task-scoped control state machine) for the full contract. Add identity-safe task pause/resume/kill with durable replay. Acceptance: node --test src/task-control.test.js. Commit only: src/task-control.js, src/task-control.test.js.


desc: Read docs/plans/2026-07-18-observability-control-api.md Task 5 (Idempotent run launch service) for the full contract. Submit CLI-equivalent runs exactly once within authorized roots. Acceptance: node --test src/control-launch.test.js. Commit only: src/control-launch.js, src/control-launch.test.js.


desc: Read docs/plans/2026-07-18-observability-control-api.md Task 6 (Config read + concurrency-safe mutation) for the full contract. Expose existing config provenance with atomic guarded mutations. Acceptance: node --test src/control-config.test.js src/config.test.js. Commit only: src/control-config.js, src/control-config.test.js, src/config.js, src/config.test.js.


desc: Read docs/plans/2026-07-18-observability-control-api.md Task 7 (Durable plan revision service) for the full contract. Revise only safe plan state through crash-idempotent journal protocol. Acceptance: node --test src/plan-revisions.test.js. Commit only: src/plan-revisions.js, src/plan-revisions.test.js.


desc: Read docs/plans/2026-07-18-observability-control-api.md Task 8 (Control API route integration) for the full contract. Wire authenticated additive routes while preserving every old route. Acceptance: node --test src/test/control-api.test.js. Commit only: src/control-api.js, src/test/control-api.test.js.


desc: Read docs/plans/2026-07-18-observability-control-api.md Task 9 (Legacy active-run compatibility gate) for the full contract. Prove all pre-upgrade lifecycle paths retain current behavior. Acceptance: bash test/observability-legacy.test.sh. Commit only: test/fixtures/observability-legacy/, test/observability-legacy.test.sh.


desc: Read docs/plans/2026-07-18-observability-control-api.md Task 10 (Full build + launcher runtime probe) for the full contract. Verify actual launcher, release build, and complete warning-free suite. Acceptance: bash test/observability-runtime.test.sh && make test. Commit only: test/observability-runtime.test.sh.