type: meta

slug: throughput-seams

base_branch: main

gate0_mode: strict

preset: cursor-codex

land_mode: merge-to-main


type: goal

text: Implement amended throughput-seams contracts T1/T2/T5 as one buildable DAG while plans without throughput_policy retain byte-identical legacy behavior.


type: methodology

text: Contract-first TDD; strict gate0 after every task; policy boundary first; journal reducers and process ownership before runner integration; daemon tick last; serialize shared-file edits; fail closed on unverified ownership.


type: intent

text: Stop repeated dead-adapter dispatch, kill banner-then-silence attempts at exactly three minutes, reap complete process trees, and resume queued work immediately when adapters heal.


type: direction

verbatim: legacy byte-identical when policy field absent


verbatim: Wrapper banner/preamble/liveness output MUST NOT satisfy the deadline.


type: deferred

text: T3 pipeline overlap and dependency-DAG admission

reason: Outside amended T1/T2/T5 scope.


text: T4 wave-level candidate gates and absolute gate timeout

reason: Separate gate-topology workstream.


text: T6 reviewer fallback and risk-tier review

reason: This plan applies existing fallback doctrine to all seat types but does not redesign review policy.


text: T7 resume-not-restart after non-deadline quarantine

reason: Only first-output-deadline and adapter-heal requeue semantics are in scope.


text: T8 journal payload hygiene and alert floors

reason: No alerting or payload redesign in this seam plan.


text: Delivery controller, validation receipts, CI topology, executor placement, publication credentials, and artifact deployment

reason: Owned by separate delivery plan or later phases.


text: Migration or cleanup of orphan processes predating attempt ownership

reason: Ownership cannot be proven safely.


text: Machine-wide and fleet circuit aggregation

reason: Per-run v1 counting already bounds measured 352-quarantine failure; broader aggregation is not required.


text: Legacy throughput-policy retirement

reason: Requires proof of zero nonterminal legacy runs after deployment.


type: gated

category: policy

needs: Authorize declared harness source/spec/test changes

why: Implementation touches protected src/ and spec/ paths; user explicitly requested a run-plan implementing the amended throughput spec.

status: RESOLVED

resolved_by: user

source: author


type: anchor

what: Amended throughput-seams design source of truth.


what: Non-negotiable compatibility contract: absent throughput_policy selects legacy; legacy acceptance remains byte-identical except pre-existing timestamps.


type: task

seat: coder

tier: high

desc: Implement amended spec Contract 1 and Contract 4 rule 7: centralized opt-in policy, all-seat fallback gating, explicit per-adapter safe-probe argv in presets/adapters.json, and unknown-policy rejection without changing legacy defaults. Acceptance evidence: src/test/throughput-policy.test.js and test/adapters-schema.sh via `node --test src/test/throughput-policy.test.js && bash test/adapters-schema.sh`. Commit only: src/throughput-policy.js, src/test/throughput-policy.test.js, presets/adapters.json, spec/adapters.schema.json, test/adapters-schema.sh.

requires_decision: g-protected-throughput


desc: Implement amended spec Contract 2: journal-derived per-run adapter circuit reducer, exact two-failure opening, generation idempotency, and coder/reviewer/fixer fallback only while primary circuit is open. Acceptance evidence: src/test/adapter-circuit.test.js via `node --test src/test/adapter-circuit.test.js`. Commit only: src/engine/adapter-circuit.js, src/test/adapter-circuit.test.js.


desc: Implement amended spec Contract 3 ownership foundation: transient cgroup v2 attempt owner, verified PID/PGID/cgroup generation, TERM-to-KILL teardown receipt, descendant-zero lease release, and fail-closed unverified-host behavior. Acceptance evidence: src/test/attempt-process.test.js and src/test/fail-taxonomy.test.js via `node --test src/test/attempt-process.test.js src/test/fail-taxonomy.test.js`. Commit only: src/engine/attempt-process.js, src/fail-taxonomy.js, src/test/attempt-process.test.js, src/test/fail-taxonomy.test.js.


desc: Integrate amended spec Contract 2 with quarantine and scheduler admission: enrich infrastructure failures with adapter identity, pause only open-adapter admissions, preserve manual pause, keep dependents queued, and rebind queued attempts through existing fallback dispatch. Acceptance evidence: src/test/adapter-circuit.test.js and src/test/engine-scheduler.test.js via `node --test src/test/adapter-circuit.test.js src/test/engine-scheduler.test.js`. Commit only: src/engine/repair.js, src/engine/scheduler.js, src/test/adapter-circuit.test.js, src/test/engine-scheduler.test.js.


desc: Implement amended spec Contract 3 runner/watchdog seam: count only parsed Codex/Cursor structured agent-protocol events or verified post-baseline workspace activity; exclude banner, preamble, liveness, unstructured streams, CPU, and journal writes; breach exactly at 180000ms and compose cgroup teardown with existing PGID watchdog. Acceptance evidence: src/test/runner-transcript.test.js, src/test/watchdog.test.js, and banner-then-silence fixture in src/test/attempt-process.test.js via `node --test src/test/runner-transcript.test.js src/test/watchdog.test.js src/test/attempt-process.test.js`. Commit only: src/runner.js, src/engine/watchdog.js, src/test/runner-transcript.test.js, src/test/watchdog.test.js, src/test/attempt-process.test.js, test/fixtures/agent-logs/banner-then-silence.log.


desc: Implement amended spec Contract 4 probe engine: reduce due open circuits from journals, claim one bounded probe per generation, consume catalog-owned argv without runtime derivation, close only on primary heal, and leave unsupported/down circuits open. Acceptance evidence: src/test/adapter-health.test.js via `node --test src/test/adapter-health.test.js`. Commit only: src/engine/adapter-health.js, src/test/adapter-health.test.js.


desc: Integrate amended spec Contract 3 with task lifecycle: persist attempt.started before deadline timing, dispatch implementation/fixer/reviewer inside attempt owner, requeue with new generation only after descendant-zero teardown, and preserve durable task state without quarantine/pruning. Acceptance evidence: src/test/engine-ship.test.js and src/test/attempt-process.test.js via `node --test src/test/engine-ship.test.js src/test/attempt-process.test.js`. Commit only: src/engine/ship.js, src/test/engine-ship.test.js, src/test/attempt-process.test.js.


desc: Integrate amended spec Contract 4 and cross-mechanism invariants into harnessd: add adapterHealth tick after watchdog and before promote, reconcile incomplete teardown, wake scheduler without overriding manual pause, and preserve legacy backoff paths. Acceptance evidence: src/daemon.test.js, src/test/adapter-health.test.js, and src/test/engine-scheduler.test.js via `node --test src/daemon.test.js src/test/adapter-health.test.js src/test/engine-scheduler.test.js`. Commit only: src/daemon.js, src/daemon.test.js, src/test/adapter-health.test.js, src/test/engine-scheduler.test.js.


desc: Prove amended spec Contracts 1-4 end to end: 352-quarantine circuit bound, banner-then-silence breach at exactly +3min, whole-tree teardown, heal-triggered immediate requeue, warning-free full suite, release build, and actual bin/runplan/bin/harnessd launcher resolution while absent throughput_policy stays legacy byte-identical. Acceptance evidence: test/throughput-seams-runtime.test.sh via `bash test/throughput-seams-runtime.test.sh && make test`. Commit only: test/throughput-seams-runtime.test.sh, test/fixtures/throughput-legacy/, test/fixtures/throughput-cgroups/.