okstra 0.236.0 → 0.238.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (25) hide show
  1. package/docs/architecture/storage-model.md +1 -0
  2. package/docs/architecture.md +1 -1
  3. package/package.json +1 -1
  4. package/runtime/BUILD.json +2 -2
  5. package/runtime/prompts/lead/okstra-lead-contract.md +1 -1
  6. package/runtime/prompts/profiles/_clarification-recommendation.md +1 -1
  7. package/runtime/python/okstra_ctl/agent/evidence_recovery.py +17 -5
  8. package/runtime/python/okstra_ctl/approval_decisions.py +22 -2
  9. package/runtime/python/okstra_ctl/attempt_evidence.py +79 -2
  10. package/runtime/python/okstra_ctl/design_review_evidence.py +16 -5
  11. package/runtime/python/okstra_ctl/dispatch_core.py +58 -38
  12. package/runtime/python/okstra_ctl/dispatch_state.py +60 -3
  13. package/runtime/python/okstra_ctl/manager_cli.py +42 -5
  14. package/runtime/python/okstra_ctl/manager_launch.py +60 -1
  15. package/runtime/python/okstra_ctl/manager_store.py +45 -0
  16. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +1 -1
  17. package/runtime/python/okstra_ctl/plan_item_evidence.py +25 -1
  18. package/runtime/python/okstra_ctl/verification_dispatch.py +31 -9
  19. package/runtime/python/okstra_ctl/wizard/cli.py +14 -2
  20. package/runtime/python/okstra_ctl/wizard/state.py +4 -1
  21. package/runtime/python/okstra_ctl/wizard/statefile.py +8 -3
  22. package/runtime/python/okstra_ctl/worker_audit_ledger.py +9 -3
  23. package/runtime/skills/okstra-manager/SKILL.md +8 -2
  24. package/runtime/skills/okstra-setup/SKILL.md +34 -5
  25. package/runtime/skills/okstra-setup/references/project-config.md +19 -0
@@ -707,6 +707,7 @@ Storage authority:
707
707
  - `manager.json`: manager identity and schema version.
708
708
  - `projects.json`: the projectId / projectRoot / role / tags registered with the manager. `projectRoot` must be an existing directory, and setup-equivalent registration is performed only when project-local `.okstra/project.json` is absent.
709
709
  - `manifest.json`, `children.json`, `directives.jsonl`: manager-owned plan, child assignment, and shared/project directives.
710
+ - `children.json`의 하위 작업 행은 `task run --base-ref`로 받은 `baseRef`와, `task register-session`이 기록한 `session`(`address`, `name`, `registeredAt`)을 가집니다. `task run`은 옵션이 없으면 그 `baseRef`를 쓰고, 없으면 같은 프로젝트 형제 행들이 모두 같은 `baseRef`를 가질 때만 그 값을 씁니다. 세션 등록이 값을 바꾸면 작업 `events.jsonl`에 `child-session-registered` 행을 남깁니다.
710
711
  - `group.json`: the task group's original name and creation time, written by `new task-group` and `new task`. The directory name is a slug and cannot give the name back.
711
712
  - `split-plan.json`: the last tracker split plan `task split` applied. The briefs it produced live in each child project's `.okstra/briefs/`, and the children it registered carry `ticketId`, `briefPath`, `scope` and `recommendedPhase` in `children.json`.
712
713
  - `snapshots.json`: a read-side snapshot that `task sync` imports from the child project's `.okstra`. It is not the source of truth for project state.
@@ -154,7 +154,7 @@ Runtime entry points are consolidated in Python packages. Bash and skills only c
154
154
  - `prompts/lead/adapters/cmux.md` is selected by environment rather than by runtime: when the run manifest's `terminalBackend` is `cmux-pane`, every lead runtime resolves to it and dispatches through `okstra team`, because okstra owns the worker panes on that path instead of the host. It overrides only the adapter and the dispatch mode; the lead's agent, role, and session accounting still come from its own runtime.
155
155
  - Runtime metadata and role assignments are persisted separately, but the lead provider is derived from the host: Claude Code maps to Claude, Codex maps to Codex, and Antigravity CLI maps to Antigravity. New runs persist `hostRuntime`, `leadAssignment`, and `workerAssignments[]`; each assignment records its provider, model, execution value, and resolved `native-session` or `cli-wrapper` runner. `lead-execution-prompt.md` is canonical: one file per run at `runs/<task-type>/prompts/lead-execution-prompt-<task-type>-<seq>.md`. No Claude-named copy is written — `resources.claudeExecutionPromptPath` in the run manifest is a key alias that resolves to that same file for historical consumers.
156
156
  - Host and provider registries remain separate: the active registered host owns the native lead session, while non-native providers run through their registered CLI wrappers.
157
- - [`skills/okstra-setup/SKILL.md`](../skills/okstra-setup/SKILL.md) — **first-run bootstrap**. Runs `okstra install` and creates `project.json`.
157
+ - [`skills/okstra-setup/SKILL.md`](../skills/okstra-setup/SKILL.md) — **first-run bootstrap**. Runs `okstra install`, creates `project.json`, and offers to save worker defaults through the `okstra-run` worker settings mode.
158
158
  - [`skills/okstra-run/SKILL.md`](../skills/okstra-run/SKILL.md) — host-aware in-session entry point that starts an okstra task in the current registered host session and calls `prepare_task_bundle` directly.
159
159
  - Twelve skills are user-invocable: `skills/okstra-setup/SKILL.md`, `skills/okstra-brief-gen/SKILL.md`, `skills/okstra-run/SKILL.md`, `skills/okstra-discussion/SKILL.md`, `skills/okstra-manager/SKILL.md`, `skills/okstra-memory/SKILL.md`, `skills/okstra-chat/SKILL.md`, `skills/okstra-schedule-gen/SKILL.md`, `skills/okstra-pr-gen/SKILL.md`, `skills/okstra-user-response/SKILL.md`, `skills/okstra-code-review/SKILL.md`, and `skills/okstra-explain-flow/SKILL.md`. Only these are copied into the agent skill home. They cover brief authoring, phase execution, multi-agent discussions that settle requirements before planning, cross-project manager task coordination, global Memory Book storage/search, global chat rooms, schedule support, PR description generation, clarification-response submission, and census-based code review of a stage or branch diff. `okstra-manager` uses `okstra manager` CLI JSON/launch packets as the source of truth, and stores manager-owned plans, assignments, directives, snapshots, and events under `~/.okstra/managers/<manager-id>/`.
160
160
  - Wrapper transcripts are written at `<run-dir>/prompts/<worker>-prompt-<phase>-<seq>.log`; for stage executions, the stage-qualified `run_dir` includes `stage-<N>/`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "okstra",
3
- "version": "0.236.0",
3
+ "version": "0.238.0",
4
4
  "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
5
5
  "license": "MIT",
6
6
  "author": "devonshin",
@@ -1,5 +1,5 @@
1
1
  {
2
- "package": "0.236.0",
3
- "builtAt": "2026-11-19T05:54:13.362Z",
2
+ "package": "0.238.0",
3
+ "builtAt": "2026-11-19T15:02:21.983Z",
4
4
  "repoRoot": "/home/runner/work/okstra/okstra"
5
5
  }
@@ -103,7 +103,7 @@ Every `okstra` command the lead documents cite, grouped by phase, each spelled w
103
103
  | `okstra lead-progress append --project-root <dir> --run-manifest <path> --phase <phase-id>` | Every `PROGRESS` checkpoint the command performing that step does not record itself; print the `progressLine` it returns. `--phase` accepts only the listed phase ids; use `--worker`, `--field NAME=VALUE`, and `--detail <text>` for the rest | this contract "Progress reporting" |
104
104
  | `okstra agent-activity append --project-root <dir> --run-manifest <path> --kind <kind> --agent <agent> --outcome <outcome> --summary <text>` | Before each activity boundary when the run manifest declares `activityContractVersion: 1`, except a `worker-dispatched` / `worker-completed` row the dispatching command already appended (see "Progress reporting") | launch prompt "Progress reporting" |
105
105
  | `okstra error-log append-observed --out <errors-path> --task-key <key> --phase <phase> --agent <provider-worker> --agent-role <role> --model <model> --error-type <type> --command-kind <kind> --command <command> --message <text>` | Record an observed failure. `--agent` takes the provider worker id (`codex-worker`); an execution label goes in `--execution-label` | this contract "Errors log path wiring"; `team-contract` "Worker error-log command" |
106
- | `okstra approval-decision open --ledger <path> --task-key <key> --task-type <type> --run-seq <seq> --clarification-id <C-NNN> --ticket-id <id> --statement <text> --expected-form <form> --classification <class> --origin <origin> --user-confirmation <text> --unblock-condition <text> --recommended-disposition <disposition> [--supersedes <C-NNN>] [--candidate-ref <IO-NNN>]` | Open an approval blocker after the user confirmed it; `--candidate-ref` names the implementation option a split-vote decision accepts | this contract "User confirmation before an approval blocker" |
106
+ | `okstra approval-decision open --ledger <path> --task-key <key> --task-type <type> --run-seq <seq> --clarification-id <C-NNN> --ticket-id <id> --statement <text> --expected-form <form> --classification <class> --origin <origin> --user-confirmation <text> --unblock-condition <text> --recommended-disposition <disposition> [--supersedes <C-NNN>] [--candidate-ref <IO-NNN>] [--blocks next-phase]` | Open an approval blocker after the user confirmed it; `--candidate-ref` names the implementation option a split-vote decision accepts; `--blocks next-phase` records a decision of a phase whose profile says `Blocks=next-phase` (the default is `approval`) | this contract "User confirmation before an approval blocker" |
107
107
  | `okstra approval-decision carry --ledger <path> --clarification-id <C-NNN> --from-responses <path>` | Carry a decision answered in an earlier run | `report-writer` "Role-owned inputs" |
108
108
  | `okstra approval-decision resolve --ledger <path> --clarification-id <C-NNN> --disposition <disposition> --user-text <text> --user-response-ref <ref>` | Record the user's disposition of an approval row; it touches no verdict | `plan-body-verification` "Round protocol" |
109
109
  | `okstra user-response show --report <path>` | Not a lead step: the `okstra-user-response` skill reads approval rows through it, so an `origin` outside the schema enum breaks every later read | `plan-body-verification` "Round protocol" |
@@ -1,4 +1,4 @@
1
- - every `Kind=decision` clarification row is recorded by the lead in the approval decision ledger — one `okstra approval-decision open --ledger <approvalDecisionsPath>` call per row, before report assembly runs. Assembly reads `clarificationItems[]` from that ledger and from nowhere else, so a decision that exists only as narrative prose reaches no reader and no answer channel: `okstra user-response` cannot offer a row the ledger never carried, and the HTML prints "No further decision is needed" over the top of it. Each option is an object with eight fields:
1
+ - every `Kind=decision` clarification row is recorded by the lead in the approval decision ledger — one `okstra approval-decision open --ledger <approvalDecisionsPath>` call per row, before report assembly runs. The row's `Blocks` value is the call's `--blocks`: `approval` by default, so pass `--blocks next-phase` for every row the phase profile or `_common-contract.md` assigns `Blocks=next-phase`. **Enforced:** `scripts/okstra_ctl/approval_decisions.py` `_decision_row` refuses any other value. Assembly reads `clarificationItems[]` from that ledger and from nowhere else, so a decision that exists only as narrative prose reaches no reader and no answer channel: `okstra user-response` cannot offer a row the ledger never carried, and the HTML prints "No further decision is needed" over the top of it. Each option is an object with eight fields:
2
2
  - `role` — `recommended` for the single best answer, `alternative` for the rest. Exactly one option per row is `recommended`.
3
3
  - `answer` — the choice itself, phrased so the user can pick it as-is. Keep it to a short phrase (roughly 120 characters); the reasoning and the consequences have their own fields below.
4
4
  - `rationale` — why this option is on the board, as long as the reason needs.
@@ -2,6 +2,7 @@
2
2
  from __future__ import annotations
3
3
 
4
4
  from pathlib import Path
5
+ from typing import Literal
5
6
 
6
7
  from .invocation import (
7
8
  AgentInstruction, AgentInstructionSource, AgentInvocationError,
@@ -15,7 +16,7 @@ from ..worker_artifact_paths import audit_sidecar_rel
15
16
 
16
17
  def prepare_evidence_recovery(
17
18
  metadata_path: Path, *, project_root: Path, result_path: Path,
18
- source_attempt: int,
19
+ source_attempt: int, reason: RecoveryReason,
19
20
  ) -> tuple[PreparedAgentInvocation, Path]:
20
21
  """원래 모델·역할을 유지하고 새 결과 경로에 제한된 증거 보완을 발행한다."""
21
22
  metadata = load_owned_object(metadata_path, artifact="recovery source metadata")
@@ -44,7 +45,7 @@ def prepare_evidence_recovery(
44
45
  }
45
46
  anchors = tuple(next((f"{key} {value}" for key, value in replacements.items()
46
47
  if line.startswith(key)), line) for line in _extract_anchor_lines(prefix))
47
- body = _recovery_instructions(identity.invocation_ref, source_attempt, result_path, old_prompt)
48
+ body = _recovery_instructions(identity.invocation_ref, source_attempt, result_path, old_prompt, reason)
48
49
  prepared = prepare_agent_invocation(AgentInvocationRequest(
49
50
  invocation_id=invocation_id, worker_id=None, audience=metadata["audience"],
50
51
  assignment_ref=metadata["assignmentRef"], purpose=None,
@@ -61,14 +62,25 @@ def prepare_evidence_recovery(
61
62
  return prepared, result
62
63
 
63
64
 
64
- def _recovery_instructions(invocation_ref: str, source_attempt: int, result_path: Path, old_prompt: Path) -> str:
65
- """완료된 구현을 재실행하지 않는 보완 범위를 전달한다."""
65
+ RecoveryReason = Literal["declaration", "unsealed"]
66
+
67
+ _RECOVERY_CAUSES: dict[str, str] = {
68
+ "declaration": "The prior attempt failed only on a declaration discrepancy.",
69
+ "unsealed": ("The prior attempt completed, but it closed before okstra sealed attempt evidence, so "
70
+ "its result cannot be read as verification evidence."),
71
+ }
72
+
73
+
74
+ def _recovery_instructions(
75
+ invocation_ref: str, source_attempt: int, result_path: Path, old_prompt: Path, reason: RecoveryReason,
76
+ ) -> str:
77
+ """The recovery scope: keep the completed implementation and rebuild only its evidence."""
66
78
  return (
67
79
  "## Evidence recovery scope\n\n"
68
80
  f"Original invocation: {invocation_ref}; attempt: {source_attempt}.\n"
69
81
  f"Read and preserve the original result: {result_path}.\n"
70
82
  f"Read the original audit: {old_prompt}.mutation-audit.json.\n"
71
- "The prior attempt failed only on a declaration discrepancy. Preserve existing source and QA work. "
83
+ f"{_RECOVERY_CAUSES[reason]} Preserve existing source and QA work. "
72
84
  "Do not repeat completed implementation steps or edit production source. Reconcile the declaration "
73
85
  "and required evidence against current artifacts; retain historical validation as historical. "
74
86
  "Do not invent a missing before-state or claim independent verification. If a substantive defect "
@@ -11,6 +11,7 @@ from dataclasses import dataclass
11
11
  from pathlib import Path
12
12
  from typing import Any, Mapping, Sequence
13
13
 
14
+ from .clarification_items.dispositions import USER_INPUT_BLOCKS
14
15
  from .clarification_items.sidecars import (
15
16
  sidecar_answers,
16
17
  attached_response_sections,
@@ -57,6 +58,10 @@ SCOPE_EFFECTS = frozenset({"new-schema", "deferrable"})
57
58
  CLASSIFICATIONS = frozenset(
58
59
  {"user-decision", "noncritical-dissent", "correctness-critical"}
59
60
  )
61
+ # A phase without an approval gate records its decisions as next-phase blockers
62
+ # (`_common-contract.md` reporter-confirmation precondition); both are the values
63
+ # the gates read as waiting on user input.
64
+ DECISION_BLOCKS = tuple(sorted(USER_INPUT_BLOCKS))
60
65
  _FORBIDDEN_BY_CLASSIFICATION = {
61
66
  "correctness-critical": frozenset({"select"}),
62
67
  "noncritical-dissent": frozenset({"select"}),
@@ -214,7 +219,12 @@ def _decision_row(
214
219
  expected_form: str, classification: str, origin: str,
215
220
  user_confirmation: str, unblock_condition: str,
216
221
  recommended_disposition: str, options: Sequence[DecisionOption],
222
+ blocks: str = "approval",
217
223
  ) -> dict[str, Any]:
224
+ if blocks not in DECISION_BLOCKS:
225
+ raise ApprovalDecisionError(
226
+ f"invalid blocks: {blocks!r}. Allowed values: " + ", ".join(DECISION_BLOCKS)
227
+ )
218
228
  if classification not in CLASSIFICATIONS:
219
229
  raise ApprovalDecisionError(f"invalid classification: {classification}")
220
230
  _reject_off_enum(origin, "origin", "ClarificationOrigin")
@@ -232,7 +242,7 @@ def _decision_row(
232
242
  "kind": "decision",
233
243
  "statement": _required(statement, "statement"),
234
244
  "expectedForm": _required(expected_form, "expected_form"),
235
- "blocks": "approval",
245
+ "blocks": blocks,
236
246
  "origin": _required(origin, "origin"),
237
247
  "userConfirmation": _required(user_confirmation, "user_confirmation"),
238
248
  "approval": {
@@ -250,7 +260,7 @@ def open_decision(
250
260
  classification: str, origin: str, user_confirmation: str,
251
261
  unblock_condition: str, recommended_disposition: str,
252
262
  options: Sequence[DecisionOption], supersedes: Sequence[str] = (),
253
- candidate_ref: str = "",
263
+ candidate_ref: str = "", blocks: str = "approval",
254
264
  ) -> None:
255
265
  row = _decision_row(
256
266
  clarification_id=clarification_id, ticket_id=ticket_id,
@@ -258,6 +268,7 @@ def open_decision(
258
268
  classification=classification, origin=origin,
259
269
  user_confirmation=user_confirmation, unblock_condition=unblock_condition,
260
270
  recommended_disposition=recommended_disposition, options=options,
271
+ blocks=blocks,
261
272
  )
262
273
  ledger = _ledger(ledger_path, task_key, task_type, run_seq)
263
274
  active = ledger.get("activeClarifications")
@@ -487,6 +498,15 @@ def _add_open_arguments(parser: argparse.ArgumentParser) -> None:
487
498
  "candidate's splitAcceptance may cite only a decision opened for it."
488
499
  ),
489
500
  )
501
+ parser.add_argument(
502
+ "--blocks",
503
+ choices=DECISION_BLOCKS,
504
+ default="approval",
505
+ help=(
506
+ "what the open row withholds: approval (the default) or next-phase, "
507
+ "for a phase without an approval gate"
508
+ ),
509
+ )
490
510
 
491
511
 
492
512
  _CLI_EPILOG = r"""Usage:
@@ -3,6 +3,7 @@ from __future__ import annotations
3
3
 
4
4
  import hashlib
5
5
  import json
6
+ import sys
6
7
  from dataclasses import dataclass, replace
7
8
  from datetime import datetime, timezone
8
9
  from pathlib import Path
@@ -13,6 +14,7 @@ from .execution_identity import (
13
14
  Attempt,
14
15
  ExecutionManifestError,
15
16
  MutationRecoveryDecision,
17
+ build_dispatch_id,
16
18
  )
17
19
  from .execution_manifest import read_execution_manifest
18
20
  from .execution_manifest import _replace_manifest, _write_manifest_over_existing
@@ -41,8 +43,6 @@ class TerminalObservation:
41
43
  changed_paths: tuple[str, ...]
42
44
  artifact_paths: tuple[Path, ...]
43
45
  host_event_stream_path: Path
44
- project_root: Path
45
- worktree: Path | None
46
46
  interrupted_before_record: bool = False
47
47
 
48
48
 
@@ -284,6 +284,83 @@ def finalize_attempt(
284
284
  return seal
285
285
 
286
286
 
287
+ def host_event_stream_path(prompt_path: Path, attempt: int) -> Path:
288
+ """One stream per attempt: a seal pins the stream's bytes, so a retry must not append to it."""
289
+ return prompt_path.with_name(f"{prompt_path.name}.attempt-{attempt}.host-events.jsonl")
290
+
291
+
292
+ def closed_before_sealing(prompt_path: Path, attempt: int, evidence_seal_ref: str | None) -> bool:
293
+ """Whether a closed attempt predates sealing: it has neither a seal nor its own event stream.
294
+
295
+ The sealing code writes the stream before it seals, so a failed seal leaves the stream behind
296
+ and is not mistaken for an attempt that was never observed at its close.
297
+ """
298
+ return evidence_seal_ref is None and not host_event_stream_path(prompt_path, attempt).is_file()
299
+
300
+
301
+ def seal_observed_attempt(
302
+ manifest_path: Path,
303
+ *,
304
+ invocation_ref: str,
305
+ attempt: int,
306
+ status: str,
307
+ change_summary: Mapping[str, Any],
308
+ artifact_paths: Sequence[Path],
309
+ prompt_path: Path,
310
+ task_key: str,
311
+ resume: bool = False,
312
+ ) -> AttemptEvidenceSeal | None:
313
+ """Record the terminal state okstra observed for an attempt and seal it with its results.
314
+
315
+ The closing call passes `resume=False`. A later identical close passes `resume=True`: it
316
+ finishes a seal whose stream this function already wrote, and seals nothing for an attempt
317
+ closed without one, because that attempt's bytes were never observed at its close.
318
+ Calling it again for the same attempt reuses the stream, so `finalize_attempt` returns the
319
+ existing seal rather than recording a second observation.
320
+ """
321
+ if resume and closed_before_sealing(prompt_path, attempt, None):
322
+ return None
323
+ stream = host_event_stream_path(prompt_path, attempt)
324
+ if not stream.is_file():
325
+ HostEventStreamWriter(stream, invocation_ref=invocation_ref, attempt=attempt).append(
326
+ "attempt-terminal-observed",
327
+ {"status": status, "artifacts": [str(path) for path in artifact_paths]},
328
+ )
329
+ changed = change_summary.get("changedPaths")
330
+ return finalize_attempt(
331
+ manifest_path,
332
+ build_dispatch_id(invocation_ref, attempt),
333
+ TerminalObservation(
334
+ status=status,
335
+ # A source-readonly attempt has no mutation snapshot; the empty digest records that no
336
+ # source state was observed for it.
337
+ source_diff_digest=str(change_summary.get("beforeDigest") or _sha(b"")),
338
+ git_projection_digest=str(change_summary.get("afterDigest") or _sha(b"")),
339
+ changed_paths=tuple(str(path) for path in changed) if isinstance(changed, list) else (),
340
+ artifact_paths=tuple(artifact_paths),
341
+ host_event_stream_path=stream,
342
+ ),
343
+ task_key=task_key,
344
+ )
345
+
346
+
347
+ def seal_or_report(manifest_path: Path, **observation: Any) -> bool:
348
+ """Seal an attempt; report a failure on stderr instead of replacing the caller's outcome.
349
+
350
+ The attempt is already closed when this runs, so the caller's own result or error is what its
351
+ user needs. Repeating the same close retries the seal.
352
+ """
353
+ try:
354
+ seal_observed_attempt(manifest_path, **observation)
355
+ except (OSError, ValueError) as exc:
356
+ print(
357
+ f"okstra dispatch: attempt {observation['invocation_ref']} #{observation['attempt']} "
358
+ f"was not sealed: {exc}; repeat the same close to retry",
359
+ file=sys.stderr,
360
+ )
361
+ return False
362
+ return True
363
+
287
364
  def reject_unsealed_attempt(
288
365
  manifest_path: Path,
289
366
  attempt_ref: str,
@@ -4,7 +4,7 @@ import json
4
4
  import re
5
5
  from pathlib import Path
6
6
  from collections.abc import Mapping
7
- from typing import Any
7
+ from typing import Any, Callable
8
8
 
9
9
  from .agent.invocation import (
10
10
  reserved_generation_reference, reserved_invocation_metadata_path, verify_agent_invocation,
@@ -15,13 +15,19 @@ from .execution_identity import ExecutionManifest
15
15
  from .execution_manifest import read_execution_manifest
16
16
  from .json_boundary import load_owned_object
17
17
  from .qa_procedures import canonical_json_digest, content_digest, safe_qa_path
18
- from .verification_dispatch import implementation_generation_frontier, read_completed_attempt_result, verification_generation_number
18
+ from .verification_dispatch import (
19
+ implementation_generation_frontier, read_completed_attempt_result, read_history_attempt_result,
20
+ verification_generation_number,
21
+ )
19
22
  from .verification_input_ref import VerificationInputReference
20
23
  from .verification_inputs import read_verification_inputs
21
24
  from .verification_input_types import DESIGN_REVIEW_INPUT_SCHEMA_VERSION
22
25
  from .verification_invocation import VerificationGenerationReference, read_invocation_generation
23
26
  from .verification_evidence import implementation_verifier_roster, roster_verifier_role_execution_ref
24
27
 
28
+ # Reads an earlier attempt's result given its prompt path; the current verdict never uses one.
29
+ ResultReader = Callable[[Path, ExecutionManifest, str, int, Path], tuple[Path, bytes]]
30
+
25
31
 
26
32
  def design_review_required(project: Path, manifest: Mapping[str, Any]) -> bool:
27
33
  reference = VerificationInputReference.from_artifact_fields(manifest)
@@ -80,7 +86,8 @@ def _prior_reviews(
80
86
  if reference is None:
81
87
  raise ValueError("earlier design-review attempt has no bound generation")
82
88
  binding = BoundInvocation(invocation, number, index, None, reference.to_payload())
83
- record, _ = _read_review(project, manifest_path, manifest, execution, binding, attempt.attempt)
89
+ record, _ = _read_review(project, manifest_path, manifest, execution, binding, attempt.attempt,
90
+ read_result=read_history_attempt_result)
84
91
  history.append(record)
85
92
  return history
86
93
 
@@ -109,7 +116,7 @@ def prior_design_review_prompt(
109
116
 
110
117
  def _read_review(
111
118
  project: Path, manifest_path: Path, manifest: Mapping[str, Any], execution: ExecutionManifest,
112
- binding: BoundInvocation, attempt: int,
119
+ binding: BoundInvocation, attempt: int, *, read_result: ResultReader | None = None,
113
120
  ) -> tuple[dict[str, Any], str]:
114
121
  invocation = binding.invocation
115
122
  metadata_path = reserved_invocation_metadata_path(project, manifest, invocation.invocation_ref, attempt)
@@ -134,7 +141,11 @@ def _read_review(
134
141
  if (generation["generation"] != binding.generation_number
135
142
  or binding.generation_ref["path"] != expected_path.relative_to(project).as_posix()):
136
143
  raise ValueError("design review generation differs from its dispatch")
137
- result_path, raw = _read_attempt_result(project, execution, invocation.invocation_ref, attempt)
144
+ if read_result is None:
145
+ result_path, raw = _read_attempt_result(project, execution, invocation.invocation_ref, attempt)
146
+ else:
147
+ prompt = project / load_owned_object(metadata_path, artifact="invocation metadata")["prompt"]["path"]
148
+ result_path, raw = read_result(project, execution, invocation.invocation_ref, attempt, prompt)
138
149
  body = raw.decode("utf-8")
139
150
  source = Path(generation["sourceRoot"])
140
151
  review = parse_design_review(source if source.is_dir() else project, generation["designReview"], body)
@@ -450,7 +450,7 @@ def dispatch_plan(
450
450
  거부된 배치와 증거 보완으로 빠진 작업은 여기까지 오지 않으므로, 띄울 워커에
451
451
  대한 사실(체크포인트)은 이 시점에 기록해야 실제로 뜬 워커만 남는다.
452
452
  """
453
- plan = _recover_declaration_failures(plan)
453
+ plan = _route_closed_executors_to_evidence_recovery(plan)
454
454
  if not plan.jobs:
455
455
  return 0
456
456
  plan = _ensure_runtime_chain(plan)
@@ -555,7 +555,7 @@ def dispatch_cli_wrapper_plan(
555
555
  """Start one dependency-free CLI batch before collecting any worker."""
556
556
  if any(job.backend != BACKEND_CLI_WRAPPER for job in plan.jobs):
557
557
  raise DispatchError("concurrent CLI dispatch requires cli-wrapper jobs only")
558
- plan = _recover_declaration_failures(plan)
558
+ plan = _route_closed_executors_to_evidence_recovery(plan)
559
559
  if not plan.jobs:
560
560
  return 0
561
561
  plan = _ensure_runtime_chain(plan)
@@ -1364,17 +1364,21 @@ def _spawn_cli_job_nonblocking(
1364
1364
  )
1365
1365
 
1366
1366
 
1367
- def _recover_declaration_failures(plan: DispatchPlan) -> DispatchPlan:
1368
- """선언만으로 거부된 구현은 같은 호출을 재시도하지 않고 증거 보완으로 연결한다."""
1367
+ def _route_closed_executors_to_evidence_recovery(plan: DispatchPlan) -> DispatchPlan:
1368
+ """Route a closed executor to evidence recovery instead of retrying the same invocation.
1369
+
1370
+ The causes are those `_evidence_recovery_source` selects.
1371
+ """
1369
1372
  if not any(job.has_execution_identity for job in plan.jobs):
1370
1373
  return plan
1371
1374
  manifest = read_execution_manifest(plan.manifest_path)
1372
1375
  jobs: list[WorkerJob] = []
1373
1376
  for job in plan.jobs:
1374
- source_attempt = _declaration_recovery_attempt(manifest, job)
1375
- if source_attempt is None:
1377
+ recovery = _evidence_recovery_source(manifest, plan.manifest, job)
1378
+ if recovery is None:
1376
1379
  jobs.append(job)
1377
1380
  continue
1381
+ source_attempt, reason = recovery
1378
1382
  recovered_ref = f"{job.invocation_ref}-evidence-recovery-{source_attempt}"
1379
1383
  recovered = [row for row in manifest.attempts if row.invocation_ref == recovered_ref]
1380
1384
  if recovered and max(recovered, key=lambda row: row.attempt).status == "ok":
@@ -1383,6 +1387,7 @@ def _recover_declaration_failures(plan: DispatchPlan) -> DispatchPlan:
1383
1387
  prepared, result = prepare_evidence_recovery(
1384
1388
  job.prompt_metadata_path, project_root=plan.project_root,
1385
1389
  result_path=job.result_path, source_attempt=source_attempt,
1390
+ reason=reason,
1386
1391
  )
1387
1392
  except AgentInvocationError as exc:
1388
1393
  raise DispatchError(f"evidence recovery could not be prepared: {exc}") from exc
@@ -1396,24 +1401,46 @@ def _recover_declaration_failures(plan: DispatchPlan) -> DispatchPlan:
1396
1401
  if not recovered:
1397
1402
  _append_event(plan, "worker-evidence-recovery-prepared", {
1398
1403
  "sourceInvocationRef": job.invocation_ref, "sourceAttempt": source_attempt,
1404
+ "reason": reason,
1399
1405
  "invocationRef": prepared.invocation_ref, "resultPath": str(result),
1400
1406
  "modelExecutionValue": job.model_execution_value,
1401
1407
  })
1402
1408
  return replace(plan, jobs=tuple(jobs))
1403
1409
 
1404
1410
 
1405
- def _declaration_recovery_attempt(manifest: ExecutionManifest, job: WorkerJob) -> int | None:
1406
- """선언 오류만 있는 종결 시도를 고르고 이미 시작한 후속 작업은 보존한다."""
1411
+ def _evidence_recovery_source(
1412
+ manifest: ExecutionManifest, run_manifest: Mapping[str, Any], job: WorkerJob,
1413
+ ) -> tuple[int, str] | None:
1414
+ """The executor attempt to route to evidence recovery and its cause; refuse when a later
1415
+ invocation of the same role already started.
1416
+
1417
+ `declaration`: rejected only for a declaration discrepancy. `unsealed`: closed ok before
1418
+ attempts were sealed. A run under the verification-evidence contract reads the executor result
1419
+ only through its seal (`verification_dispatch.read_completed_attempt_result`), so it needs a
1420
+ recovery result that does not repeat the implementation.
1421
+ """
1422
+ from .attempt_evidence import closed_before_sealing
1423
+ from .verification_invocation import verification_generation_required
1424
+
1407
1425
  prior = [row for row in manifest.attempts if row.invocation_ref == job.invocation_ref]
1408
1426
  last = max(prior, key=lambda row: row.attempt) if prior else None
1409
- summary = last.change_summary if last else {}
1410
- if not (
1411
- job.audience == "implementation-executor" and last is not None
1412
- and last.finished_at is not None and last.status == "contract-failed-unattributed"
1427
+ if (job.audience != "implementation-executor" or last is None or last.finished_at is None
1428
+ or "-evidence-recovery-" in job.invocation_ref):
1429
+ return None
1430
+ summary = last.change_summary
1431
+ if (
1432
+ last.status == "contract-failed-unattributed"
1413
1433
  and summary.get("sourceChanged") is False and summary.get("gitChanged") is False
1414
1434
  and summary.get("violations") == ["declared out-of-plan path did not change"]
1415
- and "-evidence-recovery-" not in job.invocation_ref
1416
1435
  ):
1436
+ reason = "declaration"
1437
+ elif (
1438
+ last.status == "ok"
1439
+ and closed_before_sealing(job.prompt_path, last.attempt, last.evidence_seal_ref)
1440
+ and verification_generation_required(run_manifest, "implementation-verifier")
1441
+ ):
1442
+ reason = "unsealed"
1443
+ else:
1417
1444
  return None
1418
1445
  recovered_ref = f"{job.invocation_ref}-evidence-recovery-{last.attempt}"
1419
1446
  later_refs = {
@@ -1429,7 +1456,7 @@ def _declaration_recovery_attempt(manifest: ExecutionManifest, job: WorkerJob) -
1429
1456
  f"{', '.join(sorted({row.invocation_ref for row in later}))} instead of redispatching "
1430
1457
  f"the historical failure {job.invocation_ref}"
1431
1458
  )
1432
- return last.attempt
1459
+ return last.attempt, reason
1433
1460
 
1434
1461
 
1435
1462
  def _next_attempt(plan: DispatchPlan, job: WorkerJob) -> int:
@@ -2305,6 +2332,8 @@ def _finish_manifest_attempt(
2305
2332
  and existing.result_path == expected_result
2306
2333
  and dict(existing.change_summary) == mutation.change_summary()
2307
2334
  ):
2335
+ if existing.evidence_seal_ref is None:
2336
+ _seal_finished_attempt(plan, job, attempt, mutation, resume=True)
2308
2337
  return
2309
2338
  raise DispatchError("attempt terminal mutation result drift")
2310
2339
  finish_attempt_mutation(
@@ -2321,33 +2350,24 @@ def _finish_manifest_attempt(
2321
2350
  _seal_finished_attempt(plan, job, attempt, mutation)
2322
2351
 
2323
2352
 
2324
- def _seal_finished_attempt(plan, job, attempt, mutation) -> None:
2325
- from .attempt_evidence import TerminalObservation, finalize_attempt
2353
+ def _seal_finished_attempt(plan, job, attempt, mutation, *, resume: bool = False) -> None:
2354
+ from .attempt_evidence import seal_or_report
2326
2355
 
2327
- events = job.prompt_path.with_name(job.prompt_path.name + ".host-events.jsonl")
2328
- if not events.is_file() or not job.has_execution_identity:
2356
+ if not job.has_execution_identity:
2329
2357
  return
2330
- artifacts = tuple(
2331
- path for path in (job.result_path, job.worker_result_path) if path
2358
+ seal_or_report(
2359
+ plan.manifest_path,
2360
+ invocation_ref=job.invocation_ref,
2361
+ attempt=attempt,
2362
+ status=mutation.status,
2363
+ change_summary=mutation.change_summary(),
2364
+ artifact_paths=tuple(
2365
+ path for path in (job.result_path, job.worker_result_path) if path
2366
+ ),
2367
+ prompt_path=job.prompt_path,
2368
+ task_key=_require_string(plan.manifest, "taskKey"),
2369
+ resume=resume,
2332
2370
  )
2333
- try:
2334
- finalize_attempt(
2335
- plan.manifest_path,
2336
- _build_dispatch_id(job.invocation_ref, attempt),
2337
- TerminalObservation(
2338
- status=mutation.status,
2339
- source_diff_digest=mutation.change_summary().get("beforeDigest", ""),
2340
- git_projection_digest=mutation.change_summary().get("afterDigest", ""),
2341
- changed_paths=tuple(mutation.changed_paths),
2342
- artifact_paths=artifacts,
2343
- host_event_stream_path=events,
2344
- project_root=plan.project_root,
2345
- worktree=Path(job.worktree_path) if job.worktree_path else None,
2346
- ),
2347
- task_key=_require_string(plan.manifest, "taskKey"),
2348
- )
2349
- except (OSError, ValueError):
2350
- return
2351
2371
 
2352
2372
 
2353
2373
  def _link_result(
@@ -1171,7 +1171,7 @@ def _finish_native_agent_attempt(
1171
1171
  result_path=result_path,
1172
1172
  policy=policy,
1173
1173
  )
1174
- _close_native_attempt(
1174
+ closed = _close_native_attempt(
1175
1175
  manifest_path,
1176
1176
  manifest,
1177
1177
  identity,
@@ -1179,6 +1179,17 @@ def _finish_native_agent_attempt(
1179
1179
  result_relative,
1180
1180
  summary,
1181
1181
  )
1182
+ _seal_native_attempt(
1183
+ project_root=project_root,
1184
+ manifest_path=manifest_path,
1185
+ manifest=manifest,
1186
+ dispatch=dispatch,
1187
+ identity=identity,
1188
+ status=status,
1189
+ result_relative=result_relative,
1190
+ summary=summary,
1191
+ resume=not closed,
1192
+ )
1182
1193
  if status != "ok":
1183
1194
  violations = summary.get("violations")
1184
1195
  detail = "; ".join(violations) if isinstance(violations, list) else status
@@ -1236,7 +1247,8 @@ def _close_native_attempt(
1236
1247
  status: str,
1237
1248
  result_path: str,
1238
1249
  summary: Mapping[str, Any],
1239
- ) -> None:
1250
+ ) -> bool:
1251
+ """Close the attempt; False when an identical earlier close already did."""
1240
1252
  execution = read_execution_manifest(manifest_path)
1241
1253
  existing = next(
1242
1254
  (
@@ -1252,7 +1264,7 @@ def _close_native_attempt(
1252
1264
  and existing.result_path == result_path
1253
1265
  and dict(existing.change_summary) == dict(summary)
1254
1266
  ):
1255
- return
1267
+ return False
1256
1268
  raise DispatchError("agent attempt terminal mutation result drift")
1257
1269
  finish_attempt_mutation(
1258
1270
  manifest_path,
@@ -1265,7 +1277,52 @@ def _close_native_attempt(
1265
1277
  change_summary=summary,
1266
1278
  task_key=require_string(manifest, "taskKey"),
1267
1279
  )
1280
+ return True
1281
+
1282
+
1283
+ def _seal_native_attempt(
1284
+ *,
1285
+ project_root: Path,
1286
+ manifest_path: Path,
1287
+ manifest: Mapping[str, Any],
1288
+ dispatch: Mapping[str, Any],
1289
+ identity: Mapping[str, Any],
1290
+ status: str,
1291
+ result_relative: str,
1292
+ summary: Mapping[str, Any],
1293
+ resume: bool,
1294
+ ) -> None:
1295
+ """Seal a host-native attempt with the same policy as `dispatch_core._seal_finished_attempt`.
1268
1296
 
1297
+ A verifier result in a run under the verification-evidence contract is read only through its
1298
+ seal (`verification_dispatch.read_completed_attempt_result`); without one the report cannot
1299
+ be assembled. `resume` is set when an earlier identical close already closed the attempt.
1300
+ """
1301
+ from .attempt_evidence import seal_or_report
1302
+
1303
+ if resume:
1304
+ execution = read_execution_manifest(manifest_path)
1305
+ attempt = next(
1306
+ (
1307
+ row for row in execution.attempts
1308
+ if row.invocation_ref == identity["invocation_ref"]
1309
+ and row.attempt == identity["attempt"]
1310
+ ),
1311
+ None,
1312
+ )
1313
+ if attempt is None or attempt.evidence_seal_ref is not None:
1314
+ return
1315
+ seal_or_report(
1316
+ manifest_path,
1317
+ invocation_ref=identity["invocation_ref"],
1318
+ attempt=identity["attempt"],
1319
+ status=status,
1320
+ change_summary=summary,
1321
+ artifact_paths=(project_root.resolve() / result_relative,),
1322
+ prompt_path=resolve_project_path(project_root, require_string(dispatch, "promptPath")),
1323
+ task_key=require_string(manifest, "taskKey"),
1324
+ resume=resume,
1325
+ )
1269
1326
 
1270
1327
  def _native_out_of_plan_paths(
1271
1328
  result_path: Path, *, project_root: Path