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.
- package/docs/architecture/storage-model.md +1 -0
- package/docs/architecture.md +1 -1
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/prompts/lead/okstra-lead-contract.md +1 -1
- package/runtime/prompts/profiles/_clarification-recommendation.md +1 -1
- package/runtime/python/okstra_ctl/agent/evidence_recovery.py +17 -5
- package/runtime/python/okstra_ctl/approval_decisions.py +22 -2
- package/runtime/python/okstra_ctl/attempt_evidence.py +79 -2
- package/runtime/python/okstra_ctl/design_review_evidence.py +16 -5
- package/runtime/python/okstra_ctl/dispatch_core.py +58 -38
- package/runtime/python/okstra_ctl/dispatch_state.py +60 -3
- package/runtime/python/okstra_ctl/manager_cli.py +42 -5
- package/runtime/python/okstra_ctl/manager_launch.py +60 -1
- package/runtime/python/okstra_ctl/manager_store.py +45 -0
- package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +1 -1
- package/runtime/python/okstra_ctl/plan_item_evidence.py +25 -1
- package/runtime/python/okstra_ctl/verification_dispatch.py +31 -9
- package/runtime/python/okstra_ctl/wizard/cli.py +14 -2
- package/runtime/python/okstra_ctl/wizard/state.py +4 -1
- package/runtime/python/okstra_ctl/wizard/statefile.py +8 -3
- package/runtime/python/okstra_ctl/worker_audit_ledger.py +9 -3
- package/runtime/skills/okstra-manager/SKILL.md +8 -2
- package/runtime/skills/okstra-setup/SKILL.md +34 -5
- 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.
|
package/docs/architecture.md
CHANGED
|
@@ -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
|
|
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
package/runtime/BUILD.json
CHANGED
|
@@ -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
|
-
|
|
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
|
-
"
|
|
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":
|
|
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
|
|
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
|
-
|
|
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 =
|
|
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 =
|
|
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
|
|
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
|
-
|
|
1375
|
-
if
|
|
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
|
|
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
|
-
|
|
1410
|
-
|
|
1411
|
-
|
|
1412
|
-
|
|
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
|
|
2353
|
+
def _seal_finished_attempt(plan, job, attempt, mutation, *, resume: bool = False) -> None:
|
|
2354
|
+
from .attempt_evidence import seal_or_report
|
|
2326
2355
|
|
|
2327
|
-
|
|
2328
|
-
if not events.is_file() or not job.has_execution_identity:
|
|
2356
|
+
if not job.has_execution_identity:
|
|
2329
2357
|
return
|
|
2330
|
-
|
|
2331
|
-
|
|
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
|
-
) ->
|
|
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
|