devlyn-cli 2.9.3 → 2.10.1

package/config/skills/devlyn:resolve/references/phases/verify.md

@@ -82,33 +82,36 @@ design/style concerns remain non-binding MEDIUM and produce `PASS_WITH_ISSUES`.
 
 **Anti-self-filter rule**: report every finding you observe, including ones you consider low-severity or low-confidence. Tag each with `confidence: high|medium|low` and let the harness's downstream filter rank them. Filtering at this stage suppresses recall.
 
-### Pair-mode (when triggered by orchestrator)
-
-Pair-mode is eligible only after MECHANICAL and the primary JUDGE have no
-verdict-binding findings. Deterministic blockers and primary JUDGE blockers
-already decide the verdict and route to the fix loop; a second judge there
-duplicates evidence and wastes wall-time. If MECHANICAL or the primary JUDGE
-has a verdict-binding finding, record `pair_judge: null` and do not spawn the
-second VERIFY agent.
-
-When eligible, trigger pair-mode if any of these are true:
-- `state.pair_verify == true` (`--pair-verify` was set).
-- `state.mode == "verify-only"`.
-- The spec frontmatter has `complexity: high`; legacy/external spec
-  `complexity: large` is accepted for compatibility, but new specs use `high`.
-- Current free-form `state.complexity` is `"large"`; legacy `"high"` state remains accepted by the merge validator only for archived run compatibility.
-- `state.risk_profile.high_risk == true`.
-- `.devlyn/risk-probes.jsonl` exists or `state.risk_profile.risk_probes_enabled == true`.
-- The spec includes an actionable solo-headroom hypothesis.
-- MECHANICAL or the primary JUDGE emitted warning-level findings but no
-  verdict-binding blockers.
-- `state.verify.coverage_failed == true`.
+### Pair-mode (default when OTHER engine is available)
+
+MECHANICAL runs first. A verdict-binding blocker routes to the fix loop without
+either judge and records `pair_judge: null`. After it passes, honor `--no-pair`;
+otherwise resolve the OTHER-engine route. An explicit `--pair-verify` is an
+availability promise: an unavailable OTHER engine BLOCKs. An automatic route
+with no OTHER engine records `auto_pair_other_engine_unavailable` and continues
+solo.
+
+When the OTHER engine is available, write `pair_trigger` at judge-spawn time
+with `pair.default` plus every applicable outcome-independent canonical reason,
+then dispatch the primary and pair JUDGEs concurrently against the same frozen
+diff via foreground parallel dispatch, never background shells. A primary blocker does not cancel the pair-JUDGE; both finding sets join the same fix
+round and merge by worst source verdict without vote counting. An orchestrator
+without foreground parallel dispatch runs the same two required judges
+sequentially, with no flag or extra state marker. This is a dispatch-shape
+fallback, not outcome-dependent escalation; the primary cannot skip the pair.
+Prefer read-only checks and serialize probes requiring exclusive shared state.
+
+Keep these reasons as telemetry; they no longer gate the second spawn:
+`mode.pair-verify`, `mode.verify-only`, `complexity.high`,
+`complexity.large`, `spec.complexity.high`, `spec.complexity.large`,
+`spec.solo_headroom_hypothesis`, `risk.high`, `risk_probes.enabled`,
+`risk_probes.present`, `coverage.failed`, `mechanical.warning`, and
+`judge.warning`.
 
 Malformed `state.risk_profile` is a VERIFY contract violation: it must be an
 object, `high_risk` / `risk_probes_enabled` / `pair_default_enabled` must be
-JSON booleans when present, and `reasons` must be a string array. Do not treat
-missing or malformed risk state as low-risk; `verify-merge-findings.py` blocks
-it because it can hide `risk.high` or `risk_probes.enabled` pair triggers.
+JSON booleans when present, and `reasons` must be a string array. The merge
+blocks malformed state because it can hide a required route.
 
 If `--no-pair` was set, do not spawn the OTHER-engine judge. Record
 `pair_trigger: { eligible: false, reasons: [], skipped_reason: "user_no_pair" }`
@@ -116,58 +119,32 @@ and continue with solo VERIFY. This is an explicit user opt-out, not an engine
 availability fallback. `--pair-verify` and `--no-pair` are mutually exclusive;
 if both are present, stop with `BLOCKED:invalid-flags`.
 
-After MECHANICAL and the primary JUDGE finish, compute and persist this before
-spawning the OTHER-engine pair judge:
+When the OTHER engine is available, persist this before either judge starts:
 
 ```json
 "pair_trigger": {
   "eligible": true,
-  "reasons": ["complexity.high"],
+  "reasons": ["pair.default", "complexity.high"],
   "skipped_reason": null
 }
 ```
 
-If `eligible == true`, `reasons` must be non-empty and include every applicable canonical reason; for example, a spec with an actionable solo-headroom
-hypothesis must include `spec.solo_headroom_hypothesis` even when another reason
-such as `risk.high` also applies. The OTHER-engine judge is mandatory. Skipping
-it is a VERIFY contract violation. If ineligible, record the
-reason, e.g. `"mechanical_blocker"` or `"primary_judge_blocker"`.
-
-`pair_trigger` is a strict contract, not advisory metadata. `eligible: true`
-requires a non-empty `reasons` list and `skipped_reason: null`; `eligible: false`
-requires an empty `reasons` list and a string/null `skipped_reason`. Do not emit
-contradictory states such as `eligible: true` with `skipped_reason`, or
-`eligible: false` with trigger reasons. `verify-merge-findings.py` blocks VERIFY
-on malformed trigger state. Eligible triggers must contain only canonical
-reasons and at least one reason: `mode.verify-only`, `complexity.high`, `complexity.large`,
-`mode.pair-verify`, `spec.complexity.high`, `spec.complexity.large`,
-`spec.solo_headroom_hypothesis`, `risk.high`, `risk_probes.enabled`,
-`risk_probes.present`, `coverage.failed`, `mechanical.warning`, or
-`judge.warning`.
+After both judges return, append every applicable outcome-dependent reason
+(`coverage.failed`, `mechanical.warning`, `judge.warning`) before merge. Eligible schema-v3 state must contain `pair.default` and every other applicable canonical
+reason. The OTHER-engine judge is mandatory; missing output is a contract
+violation.
+
+`pair_trigger` remains strict: eligible state has canonical reasons and no skip;
+ineligible state has empty reasons and one of `user_no_pair`,
+`mechanical_blocker`, `auto_pair_other_engine_unavailable`, or null.
+`primary_judge_blocker` is parser-recognized only for archived v2.0 replay and
+retains the existing rejection when a pre-known reason applied. New runs never
+write it. The `--engine` flag does not disable default pairing.
 
-The `--engine` flag never disables this rule. An explicit `--engine <name>`
-names the primary judge; if pair-mode triggers, the first available OTHER
-engine is still the mandatory pair judge (role resolution:
-`_shared/engine-preflight.md`). Do not record "explicit --engine <name>" as a
-skip reason.
-The valid skip reasons after a non-empty eligible trigger are deterministic
-MECHANICAL HIGH/CRITICAL blockers, an explicit `--no-pair`, or — when none of the
-applicable reasons is `mode.pair-verify` (every reason is automatic) — the OTHER
-engine being unavailable. Explicit `--pair-verify` with the OTHER engine absent
-is a promise and stays `BLOCKED:<engine>-unavailable`, never a skip.
-
-Before invoking the OTHER-engine judge, run the shared availability pre-flight
-for that engine. If the route is explicit (`--pair-verify`) and Codex is required
-and unavailable, set VERIFY to `BLOCKED:codex-unavailable` and tell the user to
-install/configure the Codex CLI, run the current Codex auth/login flow, verify
-`codex --version`, and rerun. If Claude is required and the host cannot spawn a
-Claude agent, set VERIFY to `BLOCKED:claude-unavailable` and tell the user to
-install/configure Claude Code, verify `claude --version`, and rerun. For an
-explicit route, do not convert this to a solo pass and do not synthesize pair
-findings. When the trigger was AUTO-only and the OTHER engine is unavailable, set
-`eligible: false`, `reasons: []`, `skipped_reason:
-"auto_pair_other_engine_unavailable"`, run solo VERIFY, and report the skipped
-auto escalation — route selection, not a fallback.
+Run the shared availability pre-flight before spawn. Explicit `--pair-verify`
+unavailability stays `BLOCKED:<engine>-unavailable` with setup guidance.
+Automatic unavailability records `auto_pair_other_engine_unavailable` and runs
+solo. Never synthesize pair findings.
 
 When eligible and the orchestrator spawns a second VERIFY agent with the OTHER engine's adapter, both judgments are merged:
 - Any HIGH/CRITICAL finding either model surfaces is verdict-binding.
@@ -200,7 +177,11 @@ When eligible and the orchestrator spawns a second VERIFY agent with the OTHER e
   A targeted probe must compare the full externally visible result
   (stdout/stderr/exit and full parsed output object, including accepted/scheduled
   rows, rejected rows, and remaining state when present), not just a single
-  property. When the spec names exact keys, row shapes, JSON object shape, or an
+  property. The mandatory dominance-loss anchor must run as a single command
+  with no shell chain operators. Chains used only to re-capture exit status are
+  forbidden because the tool result already carries it; this does not ban
+  compound shell generally or multi-step probes issued as separate tool calls.
+  When the spec names exact keys, row shapes, JSON object shape, or an
   exact error body, compare parsed key sets/deep equality so aliased keys,
   missing keys, and extra keys are verdict-binding failures. Use the spec's
   visible input key names literally when constructing the probe input. For
@@ -221,39 +202,31 @@ When eligible and the orchestrator spawns a second VERIFY agent with the OTHER e
   and the assertion must cover the complete output ordering for both accepted
   (or scheduled) and rejected rows.
 
-Codex pair-JUDGE is read-only. Invoke `codex-monitored.sh` directly with
+The resolved pair-JUDGE is read-only. Codex keeps the monitored
+`codex-monitored.sh` route with
 `CODEX_MONITORED_ISOLATED=1 CODEX_MONITORED_TIMEOUT_SEC=600` and
-`-c model_reasoning_effort=medium`; this is a
-bounded two-probe review, not implementation. Isolation blocks user config,
-AGENTS.md, hooks, and project rules from hidden context/tool
-side effects. Do not pipe it to `tail`, `head`, `grep`, `sed`, or `awk`.
-Capture stdout/stderr directly. The Codex judge must return JSONL findings on
-stdout; the orchestrator writes `.devlyn/verify.pair.findings.jsonl` and merges
-verdicts. Do not ask Codex to `apply_patch` or edit `.devlyn`.
-When the OTHER engine is Claude (codex/omp orchestrator), the judge call
-follows `_shared/adapters/claude.md` `## Invocation`: wrap headless `claude -p`
-as `python3 "$DEVLYN_SHARED_DIR/run-bounded.py" 600 -- claude -p ...` with
-`--permission-mode dontAsk`, an allowlist of `Read,Grep,Glob` plus the repo test
-command, hermetic settings, stdout captured to
-`.devlyn/claude-judge.stdout`. The same bounded-output contract and emission
-rule apply to that stdout file, and the orchestrator writes the same
-canonical `.devlyn/verify.pair.findings.jsonl`.
-The Codex prompt must include a bounded-output contract: no harness-doc reads,
+`-c model_reasoning_effort=medium`; isolation blocks user config, AGENTS.md,
+hooks, and project rules from hidden context/tool side effects. Do not pipe it
+to `tail`, `head`, `grep`, `sed`, or `awk`; capture stdout/stderr directly.
+Every other resolved OTHER engine follows `_shared/adapters/<name>.md`
+`## Invocation`. Capture the result as `.devlyn/<name>-judge.stdout`, then run
+`python3 "$DEVLYN_SHARED_DIR/collect-codex-findings.py" --devlyn-dir
+"<abs repo>/.devlyn" --stdout-file <name>-judge.stdout` before merge.
+The orchestrator writes the canonical `.devlyn/verify.pair.findings.jsonl`.
+The pair prompt must include a bounded-output contract: no harness-doc reads,
 maximum two targeted probes before first output, stop on the first
 verdict-binding finding, and emit PASS immediately after the bounded checks pass.
-If stdout is first captured to `.devlyn/codex-judge.stdout`, run
-`python3 "$DEVLYN_SHARED_DIR/collect-codex-findings.py"` before merge. That
-script is the deterministic boundary writer for
-`.devlyn/verify.pair.findings.jsonl`.
-If raw Codex stdout is captured as `.devlyn/codex-judge.stdout`,
-`verify-merge-findings.py` treats it as a diagnostic only. If stdout contains
-findings or a non-PASS summary while `.devlyn/verify.pair.findings.jsonl` is
-empty, VERIFY is `BLOCKED` for `verify.pair.emission-contract`; do not pass or
-silently recover from a broken capture contract.
-
-Both pair-judge directions are wall-budgeted at 600s. A judge subprocess exit
+Raw stdout is diagnostic-only. A non-zero collector exit must write no
+canonical findings file: set the pair source to `BLOCKED` for
+`verify.pair.emission-contract`, and do not merge as though unparsed stdout were
+only a diagnostic. Do not ask the judge to edit `.devlyn`.
+
+Both pair-judge directions are wall-budgeted at 600s. The orchestrator records
+`state.phases.verify.judge_durations_ms: {"judge": <int>, "pair_judge": <int|null>}`
+as it collects each judge result; these wall durations are siblings of, never
+nested inside, normalized string `sub_verdicts`. A judge subprocess exit
 124 is a budget abort: before merge, the orchestrator writes
-`.devlyn/verify.pair.timeout.json` with `{"engine": "<codex|claude>",
+`.devlyn/verify.pair.timeout.json` with `{"engine": "<resolved name>",
 "budget_seconds": 600}`. Three cases are binding: marker plus no canonical pair
 findings and no parseable stdout findings records `pair_judge: "TIMEOUT"`,
 computes the merged verdict from mechanical plus primary judge, and surfaces

package/config/skills/devlyn:resolve/references/state-schema.md

@@ -6,7 +6,7 @@ Single authoritative verdict source for `/devlyn:resolve`. The orchestrator bran
 
 ```json
 {
-  "version": "2.0",
+  "version": "3.0",
   "run_id": "rs-<UTC-timestamp>-<12-hex>",
   "started_at": "2026-04-30T12:00:00Z",
   "engine": "claude",
@@ -33,6 +33,7 @@ Single authoritative verdict source for `/devlyn:resolve`. The orchestrator bran
     "plan": null,
     "probe_derive": null,
     "implement": null,
+    "surface_close": null,
     "build_gate": null,
     "cleanup": null,
     "verify": null,
@@ -45,27 +46,29 @@ Single authoritative verdict source for `/devlyn:resolve`. The orchestrator bran
 ## Field rules
 
 - **version** — string. Bump major on a breaking schema change.
+- **session_id** — optional string or null stamped from `CLAUDE_CODE_SESSION_ID`; a missing/null value leaves Stop-hook pressure inert.
 - **mode** — `"free-form" | "spec" | "verify-only"`.
-- **pair_verify** — boolean. Set true only when the user passed `--pair-verify`; otherwise false. This is the durable state evidence for the `mode.pair-verify` pair-trigger reason. It is mutually exclusive with `risk_profile.pair_default_enabled == false` from `--no-pair`; `verify-merge-findings.py` blocks the contradictory state.
+- **pair_verify** — boolean. True only for `--pair-verify`. Pairing is already default-when-available; this flag makes OTHER-engine availability an explicit fail-closed promise and adds `mode.pair-verify` telemetry. It is mutually exclusive with `risk_profile.pair_default_enabled == false` from `--no-pair`.
 - **complexity** — `null | "trivial" | "medium" | "large"`. Free-form mode populates this; spec/verify-only mode leaves it null.
 - **engine** — any engine name with a shipped adapter (`_shared/adapters/<name>.md`); `"claude"` and `"codex"` today. A required unavailable engine stops the run with `BLOCKED:<engine>-unavailable`.
 - **engine_source** — `"flag" | "engines.json" | "default"` — provenance of the resolved executor engine (`_shared/engine-preflight.md#role-resolution`). Optional on archived pre-iter-0038 runs; absent means `default`.
-- **source** — provenance for the contract all downstream phases read. Spec and verify-only mode set `type: "spec"`, `spec_path`, and `spec_sha256`. Free-form mode sets `type: "generated"`, leaves `spec_path`/`spec_sha256` null, and must set `criteria_path: ".devlyn/criteria.generated.md"` plus `criteria_sha256` from the generated file's raw bytes. VERIFY re-checks the matching hash before judging.
-- **risk_profile** — PHASE 0 classification for conditional defaults. `high_risk` records durable-risk signals from the goal/spec; `risk_probes_enabled` starts true for explicit `--risk-probes` or eligible high-risk specs and only an automatic small-surface route may demote it after PLAN; `risk_probes_explicit` is true only for explicit `--risk-probes`, preventing that demotion from breaking the promise; `pair_default_enabled` is false only for explicit `--no-pair`. `risk_profile` must remain an object with boolean `high_risk`, `risk_probes_enabled`, `risk_probes_explicit`, and `pair_default_enabled` fields when present, plus `reasons` as a list of strings. Malformed `risk_profile` blocks VERIFY because pair-trigger reasons derive `risk.high` and `risk_probes.enabled` from this state.
+- **source** — downstream contract provenance. Spec/verify-only set `type: "spec"`, `spec_path`, and `spec_sha256`. Free-form sets `type: "generated"`, `goal_path: ".devlyn/goal.raw.txt"` + exact-byte `goal_sha256`, and `criteria_path: ".devlyn/criteria.generated.md"` + raw-byte `criteria_sha256`. VERIFY re-checks its contract hash.
+- **risk_profile** — PHASE 0 routing state. `high_risk` controls automatic risk probes; `risk_probes_enabled` / `risk_probes_explicit` preserve their current semantics; `pair_default_enabled` is false only for explicit `--no-pair`. `risk_profile` must remain an object with boolean `high_risk`, `risk_probes_enabled`, `risk_probes_explicit`, and `pair_default_enabled` fields when present, plus `reasons` as a string list. Malformed state blocks VERIFY because it can hide required routes.
 - **risk_probes_digest** — top-level sha256 written by PHASE 1.5 after probe validation; BUILD_GATE/VERIFY replay semantics live in `phases/build-gate.md` step 4.
 - **rounds.global** — incremented every fix-loop pass (BUILD_GATE → fix-loop, VERIFY → fix-loop, OR a phase-gate fix respawn inside phase-gated IMPLEMENT).
 - **phases.implement.exec** — only on phase-gated large runs (plan.md has `## Execution phases` with >1 phase): `{ "total": N, "current": k, "statuses": ["PASS"|"FAIL"|null, ...], "commits": ["<sha>", ...] }`. Phase definitions live in plan.md (immutable contract); progress lives here (routing truth — never route on plan.md checkboxes). Absent on single-phase runs. `cumulative.patch` for such runs is `git diff <base_ref.sha>...HEAD`.
-- **phases.probe_derive** — optional PHASE 1.5 entry when `--risk-probes` is enabled. Artifacts include `.devlyn/risk-probes.jsonl`. Probe failures later surface through BUILD_GATE/VERIFY as `correctness.risk-probe-failed`.
+- **phases.probe_derive** — optional PHASE 1.5 entry when `--risk-probes` is enabled. Artifacts include `.devlyn/risk-probes.jsonl`. Probe failures later surface through BUILD_GATE/VERIFY as `correctness.risk-probe-failed`, or as `correctness.verification-timeout` when the probe exceeds its verification budget.
+- **phases.surface_close** — generated trivial/medium one-shot: `pre_sha`, `input_patch_sha256`, assembled-byte `prompt_sha256`, `untracked_before`; spawn requires Claude plus a requested model, and `surface-check` gates PASS. `.devlyn/surface-close.output.json` retains the Claude JSON wrapper used for completion attestation while the round JSONL remains the execution-audit backstop. Automatic Claude unavailability alone records null verdict plus `skipped_reason: "auto_surface_close_claude_unavailable"`. After an adjudication-malformed reply only, successful rollback plus transcript write-audit records the two nonterminal fields `skipped_reason: "surface_close_rolled_back_adjudication_malformed"` and `continued_after_block: true`; neither creates a terminal floor. Other failures store bare `"BLOCKED"`. `durability[]` is append-only: `{round, origin_phase, receipt_path, receipt_sha256, restore_commit_sha}` per `.devlyn/closure-durability.round-<n>.json`.
 - **bypasses** — array of phase names from `--bypass`. Valid: `"build-gate" | "cleanup"`. PLAN, IMPLEMENT, VERIFY are non-bypassable (orchestrator rejects at parse time).
-- **implement_passed_sha** — captured at end of PHASE 2; null until then. Activates the post-implement invariant for CLEANUP and VERIFY.
+- **implement_passed_sha** — captured at end of PHASE 2; null until then. Activates the post-implement invariant for SURFACE_CLOSE, CLEANUP, and VERIFY.
 - **criteria** — generated from spec's `## Requirements` checklist (one per `- [ ]`). `status: pending → implemented` is the legal transition. `failed_by_finding_ids` populates when VERIFY surfaces a finding tied to a criterion.
 - **`.devlyn/untracked.baseline` artifact** — written at PHASE 0 (`spec-verify-check.py --write-untracked-baseline`); BUILD_GATE flags created-during-run unauthorized untracked files against it (`.devlyn/` exempt; semantics in `phases/build-gate.md` step 4).
-- **verify.coverage_failed** — set by VERIFY's JUDGE sub-phase when a spec axis could not be exercised against the diff. Triggers pair-mode escalation when set. Pair-mode also triggers for `state.pair_verify == true`, verify-only mode, high-risk specs, active risk probes, actionable solo-headroom hypotheses, `complexity: high` specs, or current free-form `state.complexity` of `"large"` when MECHANICAL and the primary JUDGE have no verdict-binding blockers. Legacy/external spec `complexity: large` remains accepted for compatibility; new specs use `high`. Legacy `"high"` state remains accepted by the merge validator only for archived run compatibility.
-- **verify.pair_trigger** — VERIFY's trigger decision: `{ "eligible": boolean, "reasons": string[], "skipped_reason": string|null }`. The shape is strict: `eligible: true` requires a non-empty reasons list containing every applicable canonical eligible reason and only canonical eligible reasons, plus `skipped_reason: null`; `eligible: false` requires an empty reasons list and may set only `user_no_pair`, `mechanical_blocker`, `primary_judge_blocker`, `auto_pair_other_engine_unavailable`, or null as the skip cause. Canonical eligible reasons are `mode.verify-only`, `mode.pair-verify`, `complexity.high`, `complexity.large`, `spec.complexity.high`, `spec.complexity.large`, `spec.solo_headroom_hypothesis`, `risk.high`, `risk_probes.enabled`, `risk_probes.present`, `coverage.failed`, `mechanical.warning`, and `judge.warning`. `user_no_pair` is valid only when `risk_profile.pair_default_enabled == false` from an explicit `--no-pair`; `mechanical_blocker` and `primary_judge_blocker` are valid only when the matching source has a verdict-binding finding; `auto_pair_other_engine_unavailable` is valid only when every applicable trigger reason is automatic (none is `mode.pair-verify`) and no pair-judge engine is available per role resolution (pre-iter-0038 SKILL.md already used this skip; the schema previously omitted it — reconciled). If state implies a pair decision is required but `pair_trigger` is missing, if it records `eligible:false` with no supported skip reason, if an eligible trigger omits an applicable reason such as `spec.solo_headroom_hypothesis`, or if any combination is malformed, `verify-merge-findings.py` blocks VERIFY.
+- **verify.coverage_failed** — outcome-dependent telemetry set when JUDGE cannot exercise a spec axis. It no longer gates pair dispatch: after MECHANICAL passes, `pair.default` dispatches both judges concurrently whenever `pair_default_enabled != false` and the OTHER engine is available. An orchestrator without foreground parallel dispatch runs the same two required judges sequentially; a primary blocker never skips the pair. A verdict-binding MECHANICAL blocker still skips both. Legacy complexity values remain accepted only for archived compatibility.
+- **verify.pair_trigger** — strict decision state: `{ "eligible": boolean, "reasons": string[], "skipped_reason": string|null }`. Schema v3.0 eligible state requires `pair.default` plus every applicable telemetry reason and `skipped_reason: null`; outcome-dependent reasons are appended after both judges return. Canonical reasons are `pair.default`, `mode.verify-only`, `mode.pair-verify`, `complexity.high`, `complexity.large`, `spec.complexity.high`, `spec.complexity.large`, `spec.solo_headroom_hypothesis`, `risk.high`, `risk_probes.enabled`, `risk_probes.present`, `coverage.failed`, `mechanical.warning`, and `judge.warning`. Ineligible new-run state has empty reasons and only `user_no_pair`, `mechanical_blocker`, `auto_pair_other_engine_unavailable`, or null; `primary_judge_blocker` remains parser-recognized only for archived v2.0 replay and retains its existing pre-known-reason rejection. Explicit `mode.pair-verify` cannot use the unavailable-engine skip. Missing, contradictory, incomplete, or unknown trigger state BLOCKs VERIFY.
 
 ## Per-phase shape
 
-Each entry under `phases.<name>` (for `plan`, `probe_derive`, `implement`, `build_gate`, `cleanup`, `verify`, `final_report`):
+Each entry under `phases.<name>` (for `plan`, `probe_derive`, `implement`, `surface_close`, `build_gate`, `cleanup`, `verify`, `final_report`):
 
 ```json
 {
@@ -76,7 +79,8 @@ Each entry under `phases.<name>` (for `plan`, `probe_derive`, `implement`, `buil
   "triggered_by": null,
   "verdict": "PASS",
   "engine": "claude",
-  "model": "<exact model id that ran this phase>",
+  "model_requested": "<orchestrator-selected model id or null>",
+  "model_effective": "<session-attested model id or null>",
   "pre_sha": null,
   "post_sha": null,
   "artifacts": { "findings_file": null, "log_file": null },
@@ -87,10 +91,12 @@ Each entry under `phases.<name>` (for `plan`, `probe_derive`, `implement`, `buil
 `history` is absent until a phase is re-entered. Immediately before re-entry overwrites the live `started_at`, `verdict`, `completed_at`, and `duration_ms`, `state-phase-write.py` appends those prior values as one object to `history[]`, creating the append-only array on first re-entry.
 
 - `verdict` — `"PASS" | "PASS_WITH_ISSUES" | "FAIL" | "NEEDS_WORK" | "BLOCKED"`. PHASE 6 (FINAL_REPORT) writes its own verdict per the terminal-verdict precedence.
+- `model_requested` / `model_effective` — `model_requested` is supplied by the orchestrator through `--model`; `model_effective` is parsed only from completion-time engine session evidence. Codex evidence accepts the `model: <id>` exec header or, for `.jsonl`, rollout `turn_context.payload.model`; Claude JSON output accepts a singleton `modelUsage` key or, for multiple entries, the sole key whose `inputTokens`, `outputTokens`, `cacheReadInputTokens`, and `cacheCreationInputTokens` exactly match top-level `usage.input_tokens`, `usage.output_tokens`, `usage.cache_read_input_tokens`, and `usage.cache_creation_input_tokens`. Missing or malformed counters, zero or multiple matches, and requested/effective mismatch fail closed: the phase verdict becomes `BLOCKED` and the completion command fails. For mutation phases, omission of `--engine-session-log` also fails closed when `.devlyn/<artifact-phase>.worker-session.<round>.jsonl` exists; the error names that retained file. Otherwise omission records `model_effective: null` and attests that the engine class exposed no session log for that invocation.
 - `triggered_by` — null on first run; one of `"build_gate" | "verify"` when the phase is a fix-loop respawn.
-- `pre_sha` — captured by orchestrator before CLEANUP and (if needed) other allowlist-enforced phases. Used to validate the post-spawn diff.
-- `post_sha` — captured on CLEANUP complete when that phase ran; finish-gate subtracts `pre_sha..post_sha` as the cleanup window.
+- `pre_sha` — captured before SURFACE_CLOSE or CLEANUP. It bounds that phase's post-spawn diff and rollback.
+- `post_sha` — captured when SURFACE_CLOSE or CLEANUP completes; finish-gate subtracts CLEANUP's `pre_sha..post_sha` window.
 - `sub_verdicts` — only populated for VERIFY: `{ "mechanical": "PASS|FAIL", "judge": "PASS|...", "pair_judge": "PASS|..." | "TIMEOUT" | null }`. Values are normalized by `verify-merge-findings.py`; model prose verdicts cannot upgrade or downgrade the deterministic findings-derived verdict. `sub_verdicts.pair_judge` is `"TIMEOUT"` when a pair judge exceeded its wall budget and a valid `.devlyn/verify.pair.timeout.json` marker was read — semantics in `references/phases/verify.md` (pair budget section).
+- `judge_durations_ms` — only populated for VERIFY: `{ "judge": <non-negative int>, "pair_judge": <non-negative int|null> }`. The orchestrator writes each wall duration when it collects that judge's result; values remain a sibling of `sub_verdicts`, whose values stay normalized strings. VERIFY spawn resets this key to null so re-entry cannot retain prior-round timings.
 - `merged` — only populated for VERIFY after `verify-merge-findings.py --write-state`: `{ "verdict": "...", "findings_file": ".devlyn/verify-merged.findings.jsonl", "summary_file": ".devlyn/verify-merge.summary.json" }`.
 - `pair_trigger` — only populated for VERIFY; same shape as top-level `verify.pair_trigger` when the phase stores it locally.
 - `correctness.risk-probe-failed` — emitted by `spec-verify-check.py --include-risk-probes` when an executable probe derived from the visible `## Verification` section fails.
@@ -99,9 +105,10 @@ Each entry under `phases.<name>` (for `plan`, `probe_derive`, `implement`, `buil
 
 Phase lifecycle (`started_at`/`completed_at`/`duration_ms`/`round`/`triggered_by`/`verdict`) is written by a deterministic script, never hand-edited JSON — a prior hand-edited fix-loop respawn left `started_at` stale, corrupting cross-phase ordering because `completed_at`/`round`/`triggered_by` advanced to the new round while `started_at` didn't. Phase workers report their verdict and artifact paths in their reply; they never edit `pipeline.state.json` themselves.
 
-1. **Spawn** (before every phase dispatch, including a fix-loop respawn — one call per outer phase-gated IMPLEMENT run, not per inner sub-phase): `python3 "$DEVLYN_SHARED_DIR/state-phase-write.py" --devlyn-dir .devlyn --phase <name> spawn --round <N> [--triggered-by build_gate|verify] [--pre-sha <sha>] [--engine <e>] [--model <m>]`. Re-entry applies the `history` rule above, then resets `started_at` to now and nulls `completed_at`/`duration_ms`/`verdict`/`artifacts`/`sub_verdicts`. A VERIFY spawn also deletes the prior round's on-disk VERIFY artifacts (`verify*.jsonl`, `verify-merge.summary.json`, `*-judge.*`) so stale findings cannot read as current-round evidence. Fields the script doesn't own (e.g. `phases.implement.exec`) are left untouched.
-2. **Complete** (after the orchestrator reads the phase's reply and determines the verdict): `python3 "$DEVLYN_SHARED_DIR/state-phase-write.py" --devlyn-dir .devlyn --phase <name> complete --verdict <V> [--post-sha <sha>] [--findings-file <path>] [--log-file <path>]`. `duration_ms` is derived from the phase's own recorded `started_at` — it cannot drift from `completed_at`. `--verdict` is required for every phase except VERIFY: `verify-merge-findings.py --write-state` is the sole writer of `phases.verify.verdict`, so `complete verify` is always called without `--verdict` (an explicit one is rejected) and preserves what's already on disk.
-3. **Before archive** (PHASE 6 step 5): `phases.final_report.verdict` must be non-null. Archive prune skips runs whose final_report verdict is null (treated as in-flight).
+1. **Spawn**: `state-phase-write.py --devlyn-dir .devlyn --phase <name> spawn --round <N> [--triggered-by build_gate|verify] [--pre-sha <sha>] [--engine <e>] [--model <requested-model>]`. Re-entry preserves lifecycle in `history[]`, resets owned fields, and leaves fields such as `phases.implement.exec`; VERIFY also clears prior-round files. SURFACE_CLOSE additionally requires `--model <requested-model> --input-patch-sha256 <hex> --prompt-sha256 <hex> --untracked-before-json <array>`; use `surface-check --authorized-surface-json <array>`, `surface-adjudication-recover --authorized-surface-json <array>` only after its adjudication-malformed result, `surface-rollback` for other failures, or `surface-skip` only for automatic Claude unavailability.
+2. **Transition** (normal direct handoff): `state-phase-write.py ... --phase <current> transition` takes the same completion/attestation arguments plus caller-specified `--next-phase`, `--next-round`, `--next-triggered-by`, `--next-engine`, `--next-model`, and next-phase metadata. It validates a fixed legal edge, applies complete plus spawn to a detached candidate, and replaces state once; either both lifecycle writes land or neither. The verb returns JSON paths/digests/state facts only and never chooses a phase, engine, branch, prompt, or agent.
+3. **Complete** (after the orchestrator reads the phase's reply and determines the verdict, when no next phase opens): `python3 "$DEVLYN_SHARED_DIR/state-phase-write.py" --devlyn-dir .devlyn --phase <name> complete --verdict <V> [--post-sha <sha>] [--findings-file <path>] [--log-file <path>] [--engine-session-log <path>]`. Pass the invocation's own session evidence whenever it exists; SURFACE_CLOSE passes `.devlyn/surface-close.output.json` as `--engine-session-log` so its `modelUsage` attests completion. Omission records `model_effective: null` only when the current phase/round has no retained worker-session file. Before completing a mutation phase (`implement`, `surface_close` when present, or `cleanup`), copy the exact session JSONL identified by that phase's dispatch receipt to `.devlyn/<artifact-phase>.worker-session.<round>.jsonl`, where `<artifact-phase>` is `implement`, `surface-close`, or `cleanup`; multiple rounds remain separate. Never discover or copy sessions by scanning an engine-global session directory. If that current-round file exists but `--engine-session-log` is omitted, completion fails closed and names the file. `duration_ms` is derived from the phase's own recorded `started_at` — it cannot drift from `completed_at`. `--verdict` is required for every phase except VERIFY: `verify-merge-findings.py --write-state` is the sole normal writer of `phases.verify.verdict`, so `complete verify` is always called without `--verdict` (an explicit one is rejected) and preserves what's already on disk; model-attestation failure still forces the phase to `BLOCKED`.
+4. **Before archive** (PHASE 6 step 5): `phases.final_report.verdict` must be non-null. Archive prune skips runs whose final_report verdict is null (treated as in-flight).
 
 ## Terminal verdict (PHASE 6)
 
@@ -117,12 +124,12 @@ Precedence:
 
 Header: `run_id | engine | mode | complexity | verdict | wall_time_s`.
 
-Per-phase summary table: `phase | verdict | duration_ms | round | triggered_by | findings_count`.
+Per-phase summary table: `phase | verdict | duration_ms | round | triggered_by | findings_count`; include SURFACE_CLOSE when run or skipped.
 
-Findings table (post-IMPLEMENT phases only — they are findings-only): each finding's `severity | rule_id | file:line | message | confidence`.
+Findings table: each emitted finding's `severity | rule_id | file:line | message | confidence`.
 
-Follow-up notes: any large-mode assumptions, any pair-judge TIMEOUT surfaced as `solo verdict after pair TIMEOUT`, pair/risk-probe opt-out state, engine setup guidance for `BLOCKED:<engine>-unavailable`, `/devlyn:ideate` guidance for `BLOCKED:solo-headroom-hypothesis-required` that asks for the visible behavior `solo_claude` is expected to miss, `/devlyn:ideate` guidance for `BLOCKED:solo-ceiling-avoidance-required` that asks for the concrete difference from rejected or solo-saturated controls such as `S2`-`S6`, and any `state.verify.coverage_failed` axes.
+Follow-up notes: when `phases.surface_close.continued_after_block` is true, exactly one explicit `pipeline continued to BUILD_GATE — surface_close_rolled_back_adjudication_malformed` line (never a terminal floor); any large-mode assumptions; any pair-judge TIMEOUT surfaced as `solo verdict after pair TIMEOUT`; pair/risk-probe opt-out state; engine setup guidance for `BLOCKED:<engine>-unavailable`; `/devlyn:ideate` guidance for `BLOCKED:solo-headroom-hypothesis-required` that asks for the visible behavior `solo_claude` is expected to miss; `/devlyn:ideate` guidance for `BLOCKED:solo-ceiling-avoidance-required` that asks for the concrete difference from rejected or solo-saturated controls such as `S2`-`S6`; and any `state.verify.coverage_failed` axes.
 
 ## Archive contract
 
-PHASE 6 step 4 moves the per-run artifact set (`PER_RUN_PATTERNS` in `archive_run.py` — the single source of truth) into `.devlyn/runs/<run_id>/`. Machine config such as `.devlyn/engines.json` is not a run artifact and stays in place. The `.devlyn/runs/` directory keeps the last 10 completed runs (sorted by `started_at`). Best-effort prune; archive failure does not change the run's verdict.
+PHASE 6 step 4 moves `PER_RUN_PATTERNS` into `.devlyn/runs/<run_id>/`, including Goal, SURFACE_CLOSE patch/prompt/reply, and mutation worker-session JSONL; it never scans engine-global sessions. Machine config stays; the last 10 completed runs remain. Archive/prune failure does not change verdict.

package/optional-skills/devlyn:reap/SKILL.md

@@ -95,7 +95,7 @@ These are the ONLY categories reap.sh will touch:
 
 | Category | Match | Why safe |
 |---|---|---|
-| `telegram-bun` | `bun server.ts` **AND** cwd contains `/plugins/cache/claude-plugins-official/telegram/` | Telegram MCP plugin leaks one per Claude session. Verified by cwd, not just cmdline. |
+| `telegram-bun` | worker `bun server.ts` **AND** cwd under `…/claude-plugins-official/…telegram` (matches both the old `plugins/cache/` and current `plugins/marketplaces/…/external_plugins/` layouts); PLUS the runner root `bun run --cwd …/claude-plugins-official/…telegram … start`, verified by its own cmdline (its cwd is the session dir). Workers ignore SIGTERM (measured 2026-07-17: 23/23 survived TERM, died on KILL) — reap.sh sends SIGKILL for this category by default. | Telegram MCP plugin leaks one runner+worker tree per Claude session; at ~24 trees the workers (21-43% CPU each) saturated an 11-core machine (loadavg 100+). |
 | `superset-codex-bash` | `/bin/bash .*/.superset/bin/codex` with PPID=1 | `.superset/bin/codex` wrapper exits without killing its tail child; bash copies left behind. |
 | `superset-codex-tail` | `tail -F .*superset-codex-session-*.jsonl` with PPID=1 | Log tail from the same wrapper, always safe to stop. |
 | `workerd` (opt-in) | `@cloudflare/workerd-darwin-*/bin/workerd serve ` with PPID=1 | moonmaker-engine dev server that survives tab close. Opt-in because the user may have an active dev session. |

package/optional-skills/devlyn:reap/scripts/reap.sh

@@ -47,16 +47,23 @@ collect_pids() {
   local category="$1"
   case "$category" in
     telegram-bun)
-      # cwd-verified — same logic as scan.sh
-      printf '%s\n' "$SNAPSHOT" \
-        | grep -E '/bun[^ ]* server\.ts( |$)' \
-        | awk '{print $1}' \
-        | while read -r pid; do
-            cwd="$(lsof -a -d cwd -p "$pid" 2>/dev/null | awk 'NR==2 {for(i=9;i<=NF;i++) printf "%s ", $i; print ""}')"
-            case "$cwd" in
-              *"/plugins/cache/claude-plugins-official/telegram/"*) printf '%s\n' "$pid" ;;
-            esac
-          done
+      # Worker form: cwd-verified — same logic (and same both-layouts pattern)
+      # as scan.sh. Runner form: cmdline names the plugin path = verification
+      # (its cwd is the session dir, not the plugin dir).
+      {
+        printf '%s\n' "$SNAPSHOT" \
+          | grep -E '/bun[^ ]* server\.ts( |$)' \
+          | awk '{print $1}' \
+          | while read -r pid; do
+              cwd="$(lsof -a -d cwd -p "$pid" 2>/dev/null | awk 'NR==2 {for(i=9;i<=NF;i++) printf "%s ", $i; print ""}')"
+              case "$cwd" in
+                *"/claude-plugins-official/"*telegram*) printf '%s\n' "$pid" ;;
+              esac
+            done
+        printf '%s\n' "$SNAPSHOT" \
+          | grep -E '( |/)bun[^ ]* run --cwd [^ ]*/claude-plugins-official/[^ ]*telegram[^ ]*( |$)' \
+          | awk '{print $1}'
+      } | sort -u
       ;;
     superset-codex-bash)
       printf '%s\n' "$SNAPSHOT" | grep -E '/bin/bash .*/\.superset/bin/codex( |$)' | awk '{print $1}' ;;
@@ -108,11 +115,16 @@ for cat in "${CATS_ARR[@]}"; do
       TOTAL_SKIPPED=$((TOTAL_SKIPPED+1))
       continue
     fi
+    # telegram-bun workers IGNORE SIGTERM (measured 2026-07-17: 23/23 survived
+    # TERM, all died on KILL — the leak's root behavior is "never exits").
+    # TERM against them is a proven no-op, so this category defaults to KILL.
+    sig="$SIGNAL"
+    [ "$cat" = "telegram-bun" ] && sig="KILL"
     if [ "$DRY" -eq 1 ]; then
-      printf '[%s] %s  would SIG%s\n' "$cat" "$pid" "$SIGNAL"
+      printf '[%s] %s  would SIG%s\n' "$cat" "$pid" "$sig"
     else
-      if kill -s "$SIGNAL" "$pid" 2>/dev/null; then
-        printf '[%s] %s  SIG%s sent\n' "$cat" "$pid" "$SIGNAL"
+      if kill -s "$sig" "$pid" 2>/dev/null; then
+        printf '[%s] %s  SIG%s sent\n' "$cat" "$pid" "$sig"
         TOTAL_KILLED=$((TOTAL_KILLED+1))
       else
         printf '[%s] %s  kill failed\n' "$cat" "$pid"

package/optional-skills/devlyn:reap/scripts/scan.sh

@@ -21,6 +21,10 @@ SNAPSHOT="$(ps -eo pid=,ppid=,user=,etime=,command= 2>/dev/null | awk -v me="$ME
 # Conservative by design — if unsure, leave it UNKNOWN.
 # -----------------------------------------------------------------------------
 match_telegram_bun()      { grep -E '/bun[^ ]* server\.ts( |$)'; }
+# Runner form of the same leak (2026-07-17: ~24 found at loadavg 100+): the
+# `bun run --cwd <plugin> … start` root outlives its session; its cmdline
+# NAMES the plugin path, so the cmdline itself is the verification.
+match_telegram_run()      { grep -E '( |/)bun[^ ]* run --cwd [^ ]*/claude-plugins-official/[^ ]*telegram[^ ]*( |$)'; }
 match_superset_codex_sh() { grep -E '/bin/bash .*/\.superset/bin/codex( |$)'; }
 match_superset_codex_tl() { grep -E 'tail .*superset-codex-session-.*\.jsonl'; }
 match_workerd_dev()       { grep -E '@cloudflare/workerd-darwin-[^/]+/bin/workerd serve '; }
@@ -50,12 +54,22 @@ if [ -n "$SNAPSHOT" ]; then
   BUN_CANDIDATES="$(printf '%s\n' "$SNAPSHOT" | match_telegram_bun | awk '{print $1}')"
   for pid in $BUN_CANDIDATES; do
     cwd="$(lsof -a -d cwd -p "$pid" 2>/dev/null | awk 'NR==2 {for(i=9;i<=NF;i++) printf "%s ", $i; print ""}')"
+    # One pattern covers both plugin layouts: old plugins/cache/…/telegram/
+    # and current plugins/marketplaces/…/external_plugins/telegram (the old
+    # cache-only pattern missed the live layout — 2026-07-17).
     case "$cwd" in
-      *"/plugins/cache/claude-plugins-official/telegram/"*)
+      *"/claude-plugins-official/"*telegram*)
         TELEGRAM_PIDS="${TELEGRAM_PIDS}${pid}
 " ;;
     esac
   done
+  # Runner roots verify by cmdline (their cwd is the SESSION dir, not the
+  # plugin dir — `bun run --cwd X` sets X for the child, not for itself).
+  RUN_CANDIDATES="$(printf '%s\n' "$SNAPSHOT" | match_telegram_run | awk '{print $1}')"
+  for pid in $RUN_CANDIDATES; do
+    TELEGRAM_PIDS="${TELEGRAM_PIDS}${pid}
+"
+  done
 fi
 
 if [ -n "$TELEGRAM_PIDS" ]; then

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devlyn-cli",
-  "version": "2.9.3",
+  "version": "2.10.1",
   "description": "Loop & harness engineering for AI coding agents (Claude Code, Codex, and any AGENTS.md-driven agent) — take intent to shipped, engineer-quality software hands-free with phase-gated pipelines and agent orchestration",
   "homepage": "https://github.com/fysoul17/devlyn-cli#readme",
   "bin": {

package/scripts/lint-fixtures.sh

@@ -161,7 +161,7 @@ def fallback_validate():
             if not isinstance(command, dict):
                 errors.append(f"verification_commands[{idx}] must be an object")
                 continue
-            unknown_command = sorted(set(command) - {"cmd", "exit_code", "stdout_contains", "stdout_not_contains", "contract_refs"})
+            unknown_command = sorted(set(command) - {"cmd", "exit_code", "timeout_sec", "stdout_contains", "stdout_not_contains", "contract_refs"})
             if unknown_command:
                 errors.append(f"verification_commands[{idx}] has unknown key(s): {', '.join(unknown_command)}")
             if not isinstance(command.get("cmd"), str) or not command.get("cmd"):
@@ -169,6 +169,9 @@ def fallback_validate():
             exit_code = command.get("exit_code", 0)
             if isinstance(exit_code, bool) or not isinstance(exit_code, int):
                 errors.append(f"verification_commands[{idx}].exit_code must be an integer")
+            timeout_sec = command.get("timeout_sec", 60)
+            if isinstance(timeout_sec, bool) or not isinstance(timeout_sec, int) or not 1 <= timeout_sec <= 600:
+                errors.append(f"verification_commands[{idx}].timeout_sec must be an integer from 1 to 600")
             for key in ("stdout_contains", "stdout_not_contains", "contract_refs"):
                 if key in command and not is_string_list(command[key]):
                     errors.append(f"verification_commands[{idx}].{key} must be an array of non-empty strings")