okstra 0.229.0 → 0.231.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 (150) hide show
  1. package/README.md +1 -5
  2. package/dist/cli-registry.mjs +0 -18
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/lifecycle/doctor.mjs +0 -15
  5. package/dist/commands/lifecycle/doctor.mjs.map +1 -1
  6. package/dist/lib/skill-catalog.mjs +4 -4
  7. package/dist/lib/skill-catalog.mjs.map +1 -1
  8. package/docs/architecture/storage-model.md +168 -18
  9. package/docs/architecture.md +15 -14
  10. package/docs/coding-rules.md +15 -0
  11. package/docs/contributor-change-matrix.md +5 -5
  12. package/docs/project-structure-overview.md +13 -19
  13. package/package.json +2 -3
  14. package/runtime/BUILD.json +2 -2
  15. package/runtime/bin/lib/okstra/interactive.sh +2 -1
  16. package/runtime/prompts/coding-preflight/clean-code.md +8 -0
  17. package/runtime/prompts/coding-preflight/overview.md +1 -0
  18. package/runtime/prompts/launch.template.md +7 -5
  19. package/runtime/prompts/lead/convergence.md +4 -4
  20. package/runtime/prompts/lead/okstra-lead-contract.md +19 -18
  21. package/runtime/prompts/lead/phase-routing.md +1 -1
  22. package/runtime/prompts/lead/report-writer.md +3 -3
  23. package/runtime/prompts/lead/team-contract.md +3 -3
  24. package/runtime/prompts/profiles/_coding-conventions-preflight.md +2 -0
  25. package/runtime/python/okstra_ctl/agent/invocation.py +190 -9
  26. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +31 -1
  27. package/runtime/python/okstra_ctl/blocking_checks.py +10 -0
  28. package/runtime/python/okstra_ctl/cmux.py +4 -2
  29. package/runtime/python/okstra_ctl/code_review_census.py +194 -0
  30. package/runtime/python/okstra_ctl/code_review_coverage.py +3 -1
  31. package/runtime/python/okstra_ctl/code_review_scope.py +9 -6
  32. package/runtime/python/okstra_ctl/code_review_target.py +38 -2
  33. package/runtime/python/okstra_ctl/conformance.py +30 -0
  34. package/runtime/python/okstra_ctl/conformance_evidence.py +316 -0
  35. package/runtime/python/okstra_ctl/correction_round.py +19 -13
  36. package/runtime/python/okstra_ctl/dispatch_core.py +1 -1
  37. package/runtime/python/okstra_ctl/dispatch_state.py +1 -0
  38. package/runtime/python/okstra_ctl/execution_mutation_audit.py +13 -1
  39. package/runtime/python/okstra_ctl/generated_input.py +21 -0
  40. package/runtime/python/okstra_ctl/ids.py +1 -41
  41. package/runtime/python/okstra_ctl/incremental_carry.py +7 -4
  42. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +30 -0
  43. package/runtime/python/okstra_ctl/interactive_cli.py +5 -0
  44. package/runtime/python/okstra_ctl/locks.py +28 -1
  45. package/runtime/python/okstra_ctl/model_io/renderers.py +7 -0
  46. package/runtime/python/okstra_ctl/paths.py +90 -33
  47. package/runtime/python/okstra_ctl/phases/catalog.py +3 -0
  48. package/runtime/python/okstra_ctl/phases/change_impact_analysis/spec.md +2 -2
  49. package/runtime/python/okstra_ctl/phases/discussion/spec.md +63 -63
  50. package/runtime/python/okstra_ctl/phases/discussion/wizard.py +2 -11
  51. package/runtime/python/okstra_ctl/phases/error_analysis/report_assets/error-analysis-input.template.md +1 -1
  52. package/runtime/python/okstra_ctl/phases/error_analysis/spec.md +2 -2
  53. package/runtime/python/okstra_ctl/phases/feature_analysis/spec.md +1 -1
  54. package/runtime/python/okstra_ctl/phases/final_verification/profile.md +5 -4
  55. package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification-input.template.md +1 -1
  56. package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification.template.html +8 -0
  57. package/runtime/python/okstra_ctl/phases/final_verification/spec.md +5 -4
  58. package/runtime/python/okstra_ctl/phases/final_verification/validation.py +53 -0
  59. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +6 -2
  60. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +4 -2
  61. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +1 -1
  62. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +23 -7
  63. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation-input.template.md +1 -1
  64. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +1 -1
  65. package/runtime/python/okstra_ctl/phases/implementation/spec.md +6 -4
  66. package/runtime/python/okstra_ctl/phases/implementation/validation.py +152 -30
  67. package/runtime/python/okstra_ctl/phases/implementation_option_selection/spec.md +2 -2
  68. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +16 -22
  69. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +12 -12
  70. package/runtime/python/okstra_ctl/phases/implementation_planning/plan_body.py +14 -0
  71. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +4 -4
  72. package/runtime/python/okstra_ctl/phases/implementation_planning/report_assets/implementation-planning-input.template.md +1 -1
  73. package/runtime/python/okstra_ctl/phases/implementation_planning/spec.md +1 -1
  74. package/runtime/python/okstra_ctl/phases/implementation_planning/wizard.py +11 -4
  75. package/runtime/python/okstra_ctl/phases/project_analysis/spec.md +2 -2
  76. package/runtime/python/okstra_ctl/phases/release_handoff/entry.py +7 -3
  77. package/runtime/python/okstra_ctl/phases/release_handoff/operations.py +4 -5
  78. package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +1 -1
  79. package/runtime/python/okstra_ctl/phases/release_handoff/report_assets/release-handoff-input.template.md +1 -1
  80. package/runtime/python/okstra_ctl/phases/release_handoff/spec.md +4 -4
  81. package/runtime/python/okstra_ctl/phases/technical_verification/spec.md +1 -1
  82. package/runtime/python/okstra_ctl/plan_items.py +28 -0
  83. package/runtime/python/okstra_ctl/process_group.py +26 -3
  84. package/runtime/python/okstra_ctl/qa_commands.py +5 -1
  85. package/runtime/python/okstra_ctl/recap.py +1 -2
  86. package/runtime/python/okstra_ctl/render.py +25 -2
  87. package/runtime/python/okstra_ctl/report_assembly.py +102 -1
  88. package/runtime/python/okstra_ctl/report_execution_evidence.py +220 -0
  89. package/runtime/python/okstra_ctl/report_finalize.py +3 -3
  90. package/runtime/python/okstra_ctl/report_inputs.py +28 -0
  91. package/runtime/python/okstra_ctl/report_narrative.py +12 -3
  92. package/runtime/python/okstra_ctl/report_synthesis_packet.py +5 -0
  93. package/runtime/python/okstra_ctl/run.py +40 -20
  94. package/runtime/python/okstra_ctl/stage_close.py +52 -6
  95. package/runtime/python/okstra_ctl/stage_command_commits.py +143 -0
  96. package/runtime/python/okstra_ctl/stage_fix_carry.py +21 -1
  97. package/runtime/python/okstra_ctl/stage_integrate.py +90 -25
  98. package/runtime/python/okstra_ctl/verification_capture.py +291 -0
  99. package/runtime/python/okstra_ctl/verification_conformance.py +28 -9
  100. package/runtime/python/okstra_ctl/verification_dispatch.py +136 -0
  101. package/runtime/python/okstra_ctl/verification_evidence.py +671 -0
  102. package/runtime/python/okstra_ctl/verification_generation.py +34 -16
  103. package/runtime/python/okstra_ctl/verification_input_ref.py +9 -0
  104. package/runtime/python/okstra_ctl/verification_input_types.py +2 -0
  105. package/runtime/python/okstra_ctl/verification_inputs.py +83 -2
  106. package/runtime/python/okstra_ctl/verification_invocation.py +140 -0
  107. package/runtime/python/okstra_ctl/verification_target.py +10 -3
  108. package/runtime/python/okstra_ctl/wizard/engine.py +23 -0
  109. package/runtime/python/okstra_ctl/wizard/registry.py +2 -1
  110. package/runtime/python/okstra_ctl/wizard/render.py +2 -1
  111. package/runtime/python/okstra_ctl/wizard/sources.py +14 -3
  112. package/runtime/python/okstra_ctl/wizard/steps_identity.py +2 -1
  113. package/runtime/python/okstra_ctl/wizard/steps_plan.py +6 -2
  114. package/runtime/python/okstra_ctl/worker_runner.py +1 -1
  115. package/runtime/python/okstra_ctl/worktree/git_ops.py +8 -1
  116. package/runtime/python/okstra_ctl/worktree/rebase.py +5 -2
  117. package/runtime/python/okstra_ctl/worktree_lock_cli.py +70 -17
  118. package/runtime/python/okstra_ctl/worktree_registry.py +4 -0
  119. package/runtime/schemas/final-report-v3.0.schema.json +184 -1
  120. package/runtime/skills/okstra-code-review/SKILL.md +7 -5
  121. package/runtime/skills/okstra-code-review/references/census-rules.md +2 -2
  122. package/runtime/skills/okstra-explain-flow/SKILL.md +1 -1
  123. package/runtime/skills/okstra-run/SKILL.md +11 -7
  124. package/runtime/skills/okstra-schedule-gen/SKILL.md +3 -3
  125. package/runtime/skills/okstra-setup/SKILL.md +2 -3
  126. package/runtime/templates/reports/html/i18n/en.json +7 -0
  127. package/runtime/templates/reports/html/i18n/ko.json +7 -0
  128. package/runtime/validators/validate-run.py +130 -20
  129. package/runtime/validators/validate-workflow.sh +1 -1
  130. package/docs/cli.md +0 -1060
  131. package/docs/container.md +0 -100
  132. package/docs/follow-ups/2026-07-10-final-report-option-3.md +0 -51
  133. package/docs/performance-improvement-plan-v2.md +0 -369
  134. package/runtime/python/okstra_ctl/container.py +0 -702
  135. package/runtime/python/okstra_ctl/rollup.py +0 -241
  136. package/runtime/python/okstra_ctl/usage_report.py +0 -362
  137. package/runtime/skills/okstra-container-build/SKILL.md +0 -139
  138. package/runtime/skills/okstra-inspect/SKILL.md +0 -100
  139. package/runtime/skills/okstra-inspect/facets/cost.md +0 -84
  140. package/runtime/skills/okstra-inspect/facets/error-zip.md +0 -41
  141. package/runtime/skills/okstra-inspect/facets/errors.md +0 -69
  142. package/runtime/skills/okstra-inspect/facets/history.md +0 -86
  143. package/runtime/skills/okstra-inspect/facets/logs.md +0 -89
  144. package/runtime/skills/okstra-inspect/facets/recap.md +0 -167
  145. package/runtime/skills/okstra-inspect/facets/report.md +0 -57
  146. package/runtime/skills/okstra-inspect/facets/run-audit.md +0 -34
  147. package/runtime/skills/okstra-inspect/facets/status.md +0 -163
  148. package/runtime/skills/okstra-inspect/facets/time.md +0 -57
  149. package/runtime/skills/okstra-rollup/SKILL.md +0 -75
  150. package/runtime/skills/okstra-usage/SKILL.md +0 -71
@@ -0,0 +1,671 @@
1
+ """Evidence mode: run one frozen check for one open verifier attempt."""
2
+ from __future__ import annotations
3
+
4
+ import contextlib
5
+ import itertools
6
+ import os
7
+ import signal
8
+ import subprocess
9
+ from dataclasses import dataclass
10
+ from datetime import datetime, timezone
11
+ from pathlib import Path
12
+ from typing import Any, Callable, Literal, Mapping, TypedDict, cast
13
+
14
+ from .agent.invocation import (
15
+ AgentInvocationError, InvocationMetadataIdentity, agent_model_assignment_from_payload,
16
+ invocation_execution_identity_from_manifest, invocation_metadata_identity,
17
+ metadata_generation_reference, verify_agent_invocation,
18
+ )
19
+ from .conformance import validate_conformance_manifest
20
+ from .execution_manifest import read_execution_manifest
21
+ from .execution_mutation_audit import (
22
+ VerificationSourceSnapshot, capture_verification_source,
23
+ compare_verification_sources,
24
+ )
25
+ from .json_boundary import (
26
+ JsonBoundaryError, load_owned_object, load_owned_object_snapshot,
27
+ write_owned_object_atomic,
28
+ )
29
+ from .locks import resource_exec_lock, worktree_exec_lock
30
+ from .paths import RunRef
31
+ from .ports.verification_inputs import VerificationInputStore
32
+ from .qa_commands import (
33
+ QA_VERIFIER_AUDIENCE_BY_TASK_TYPE, split_verification_command,
34
+ verification_command_defects,
35
+ )
36
+ from .qa_procedures import content_digest, existing_qa_file, safe_qa_path
37
+ from .verification_conformance import conformance_manifest_path, conformance_stage
38
+ from .verification_capture import (
39
+ CLEANUP_GRACE_SECONDS, DRAIN_AFTER_EXIT_SECONDS, CommandCapture, StreamCapture,
40
+ run_captured,
41
+ )
42
+ from .verification_generation import (
43
+ VerificationGenerationRecord, sealed_source_snapshot,
44
+ )
45
+ from .verification_invocation import (
46
+ VerificationGenerationReference, read_invocation_generation,
47
+ )
48
+ from .verification_target import read_verification_head
49
+ from .worker_prompt_policy import stage_qa_owner
50
+
51
+ EVIDENCE_INCOMPLETE_EXIT = 70
52
+ # A failed observation, unlike a ValueError mismatch, says nothing about the target.
53
+ _OBSERVATION_ERRORS = (OSError, subprocess.SubprocessError)
54
+ _STRINGS = {"type": "array", "items": {"type": "string"}}
55
+ _TEXT, _OPTIONAL_TEXT = {"type": "string"}, {"type": ["string", "null"]}
56
+ _COUNT = {"type": "integer", "minimum": 1}
57
+
58
+
59
+ def _object(nullable: bool, **properties: Mapping[str, Any]) -> dict[str, Any]:
60
+ return {"type": ["object", "null"] if nullable else "object",
61
+ "additionalProperties": False, "required": list(properties),
62
+ "properties": properties}
63
+
64
+
65
+ _STREAM = _object(True, path=_TEXT, bytes={"type": "integer", "minimum": 0},
66
+ digest=_TEXT, saved={"type": "boolean"},
67
+ forwardError=_OPTIONAL_TEXT)
68
+ _TARGET = _object(True, protectedChanges=_STRINGS, generatedChanges=_STRINGS,
69
+ unclassifiedPaths=_STRINGS, trackedPathsChanged={"type": "boolean"},
70
+ artifactInputChanges=_STRINGS)
71
+ _RECORD_SCHEMA = _object(
72
+ False, schemaVersion={"const": "1.0"}, kind={"const": "verification-execution"},
73
+ status={"enum": ["started", "completed", "output-save-failed",
74
+ "drain-incomplete", "cleanup-unconfirmed", "target-changed",
75
+ "lock-unavailable", "cancelled", "interrupted",
76
+ "evidence-error"]},
77
+ runManifestPath=_TEXT, verificationGeneration=_object(False, path=_TEXT,
78
+ digest=_TEXT),
79
+ generation=_COUNT, participantRef=_TEXT, roleExecutionRef=_TEXT,
80
+ invocationRef=_TEXT, attempt=_COUNT, audience=_TEXT, checkRef=_TEXT,
81
+ checkRun=_COUNT, verificationInputsPath=_TEXT, verificationInputsDigest=_TEXT,
82
+ resourceKeys=_STRINGS, worktree=_TEXT, expectedHead=_TEXT,
83
+ declaredCommand=_TEXT, command=_TEXT, argv=_STRINGS,
84
+ locks={"enum": ["not-acquired", "held"]},
85
+ policy=_object(False, drainAfterExitSeconds={"type": "number"},
86
+ cleanupGraceSeconds={"type": "number"}),
87
+ startedAt=_OPTIONAL_TEXT, finishedAt=_OPTIONAL_TEXT,
88
+ exitCode={"type": ["integer", "null"]}, signal=_OPTIONAL_TEXT,
89
+ drain={"enum": ["not-run", "complete", "incomplete"]},
90
+ cleanup={"enum": ["not-run", "confirmed", "unconfirmed"]},
91
+ stdout=_STREAM, stderr=_STREAM, targetBefore=_TARGET, targetAfter=_TARGET,
92
+ error=_OPTIONAL_TEXT,
93
+ )
94
+
95
+
96
+ class _StreamRecord(TypedDict):
97
+ path: str
98
+ bytes: int
99
+ digest: str
100
+ saved: bool
101
+ forwardError: str | None
102
+
103
+
104
+ class _TargetRecord(TypedDict):
105
+ protectedChanges: list[str]
106
+ generatedChanges: list[str]
107
+ unclassifiedPaths: list[str]
108
+ trackedPathsChanged: bool
109
+ artifactInputChanges: list[str]
110
+
111
+
112
+ class _PolicyRecord(TypedDict):
113
+ drainAfterExitSeconds: float
114
+ cleanupGraceSeconds: float
115
+
116
+
117
+ class VerificationExecutionRecord(TypedDict):
118
+ schemaVersion: Literal["1.0"]
119
+ kind: Literal["verification-execution"]
120
+ status: str
121
+ runManifestPath: str
122
+ verificationGeneration: dict[str, str]
123
+ generation: int
124
+ participantRef: str
125
+ roleExecutionRef: str
126
+ invocationRef: str
127
+ attempt: int
128
+ audience: str
129
+ checkRef: str
130
+ checkRun: int
131
+ verificationInputsPath: str
132
+ verificationInputsDigest: str
133
+ resourceKeys: list[str]
134
+ worktree: str
135
+ expectedHead: str
136
+ declaredCommand: str
137
+ command: str
138
+ argv: list[str]
139
+ locks: Literal["not-acquired", "held"]
140
+ policy: _PolicyRecord
141
+ startedAt: str | None
142
+ finishedAt: str | None
143
+ exitCode: int | None
144
+ signal: str | None
145
+ drain: Literal["not-run", "complete", "incomplete"]
146
+ cleanup: str
147
+ stdout: _StreamRecord | None
148
+ stderr: _StreamRecord | None
149
+ targetBefore: _TargetRecord | None
150
+ targetAfter: _TargetRecord | None
151
+ error: str | None
152
+
153
+
154
+ def shell_argv(command: str) -> list[str]:
155
+ return [os.environ.get("SHELL", "") or "/bin/sh", "-c", command]
156
+
157
+
158
+ def shell_exit_code(returncode: int) -> int:
159
+ # A child killed by signal N reports -N; a shell reports that death as 128+N.
160
+ return 128 - returncode if returncode < 0 else returncode
161
+
162
+
163
+ class EvidenceRefused(ValueError):
164
+ """The invocation or check cannot produce evidence; nothing was run."""
165
+
166
+
167
+ @dataclass(frozen=True)
168
+ class EvidenceCheck:
169
+ project: Path
170
+ run_ref: RunRef
171
+ identity: InvocationMetadataIdentity
172
+ audience: str
173
+ generation_ref: VerificationGenerationReference
174
+ generation: VerificationGenerationRecord
175
+ check_ref: str
176
+ declared_command: str
177
+ command: str
178
+ resource_keys: tuple[str, ...]
179
+
180
+ @property
181
+ def worktree(self) -> Path:
182
+ return Path(self.generation["sourceRoot"])
183
+
184
+
185
+ def resolve_evidence_check(
186
+ project: Path, metadata_path: Path, check_ref: str, *,
187
+ store: VerificationInputStore,
188
+ ) -> EvidenceCheck:
189
+ try:
190
+ return _resolve(project.resolve(), metadata_path.resolve(), check_ref, store)
191
+ except EvidenceRefused:
192
+ raise
193
+ except (AgentInvocationError, OSError, ValueError, KeyError) as exc:
194
+ raise EvidenceRefused(str(exc)) from exc
195
+
196
+
197
+ def _resolve(
198
+ project: Path, metadata_path: Path, check_ref: str, store: VerificationInputStore,
199
+ ) -> EvidenceCheck:
200
+ metadata = load_owned_object(metadata_path, artifact="agent invocation metadata")
201
+ identity = invocation_metadata_identity(metadata)
202
+ if identity is None or metadata["invocationId"] != identity.invocation_ref:
203
+ raise EvidenceRefused("evidence mode requires a v2 invocation identity")
204
+ manifest_path = safe_qa_path(project, metadata["contractSource"]["runManifestPath"])
205
+ errors = verify_agent_invocation(
206
+ metadata_path, project_root=project, expected_run_manifest_path=manifest_path,
207
+ expected_invocation_ref=identity.invocation_ref,
208
+ )
209
+ if errors:
210
+ raise EvidenceRefused("invocation verification failed: " + "; ".join(errors))
211
+ manifest = load_owned_object(manifest_path, artifact="run manifest")
212
+ reference = metadata_generation_reference(metadata)
213
+ generation = read_invocation_generation(
214
+ project, manifest_path, manifest, reference, metadata["audience"],
215
+ )
216
+ if generation is None or reference is None:
217
+ raise EvidenceRefused(
218
+ "evidence mode requires a verifier bound to a verification generation"
219
+ )
220
+ if identity.duty_id != metadata["audience"]:
221
+ raise EvidenceRefused("invocation duty does not own verifier checks")
222
+ _require_open_attempt(manifest_path, identity)
223
+ run_ref = RunRef.from_manifest(manifest_path, manifest)
224
+ # The check's directory segment must be a safe path segment before anything runs.
225
+ run_ref.verification_check_dir(identity.invocation_ref, identity.attempt, check_ref)
226
+ declared, resource_keys = _declared_check(
227
+ project, run_ref, manifest, generation, identity, check_ref, store,
228
+ )
229
+ command, _ = split_verification_command(declared)
230
+ defects = verification_command_defects(command)
231
+ if defects:
232
+ raise EvidenceRefused("; ".join(defects))
233
+ return EvidenceCheck(
234
+ project, run_ref, identity, metadata["audience"], reference, generation,
235
+ check_ref, declared, command, resource_keys,
236
+ )
237
+
238
+
239
+ def _declared_check(
240
+ project: Path, run_ref: RunRef, manifest: Mapping[str, Any],
241
+ generation: VerificationGenerationRecord, identity: InvocationMetadataIdentity,
242
+ check_ref: str, store: VerificationInputStore,
243
+ ) -> tuple[str, tuple[str, ...]]:
244
+ """The declared command and resource keys of a qa or conformance check."""
245
+ kind, _, identifier = check_ref.partition(":")
246
+ if kind == "conformance" and identifier:
247
+ if conformance_check_owner_ref(manifest) not in (
248
+ None, identity.role_execution_ref,
249
+ ):
250
+ raise EvidenceRefused(
251
+ "only the stage QA owner runs an implementation conformance check"
252
+ )
253
+ entry = _sealed_conformance_entry(
254
+ project, run_ref, generation, check_ref, identifier,
255
+ )
256
+ return entry["runCommand"], ()
257
+ entry = _frozen_check(project, generation, check_ref, store)
258
+ return entry["cmd"], tuple(sorted(entry.get("resourceKeys", ())))
259
+
260
+
261
+ def conformance_check_owner_ref(manifest: Mapping[str, Any]) -> str | None:
262
+ """The one role execution whose conformance runs count in an implementation
263
+ run, the stage QA owner's; None in final verification, where every
264
+ verifier's do."""
265
+ if manifest.get("taskType") != "implementation":
266
+ return None
267
+ return _stage_qa_owner_role_execution_ref(manifest)
268
+
269
+
270
+ def _stage_qa_owner_role_execution_ref(manifest: Mapping[str, Any]) -> str:
271
+ owner = stage_qa_owner(manifest)
272
+ if not owner:
273
+ raise EvidenceRefused("the run roster has no stage QA owner")
274
+ role_execution_ref = worker_role_execution_ref(manifest, owner)
275
+ if role_execution_ref is None:
276
+ raise EvidenceRefused("the stage QA owner has no v2 role execution")
277
+ return role_execution_ref
278
+
279
+
280
+ def worker_role_execution_ref(manifest: Mapping[str, Any], worker_id: str) -> str | None:
281
+ """The role execution of a roster verifier, resolved the way initial
282
+ materialization binds a roster worker to its role execution; None for a
283
+ v1 run."""
284
+ assignment_ref = f"initial/{worker_id}"
285
+ assignments = manifest.get("invocationAssignments")
286
+ identity = invocation_execution_identity_from_manifest(
287
+ manifest,
288
+ assignment=agent_model_assignment_from_payload(
289
+ assignments.get(assignment_ref) if isinstance(assignments, Mapping)
290
+ else None
291
+ ),
292
+ assignment_ref=assignment_ref,
293
+ duty_id=QA_VERIFIER_AUDIENCE_BY_TASK_TYPE[str(manifest.get("taskType"))],
294
+ )
295
+ return None if identity is None else identity.role_execution_ref
296
+
297
+
298
+ def roster_verifier_role_execution_ref(
299
+ manifest: Mapping[str, Any], name: object,
300
+ ) -> str | None:
301
+ """The role execution a report's `verifier` name binds; None for a name the
302
+ roster does not bind to one. Report assembly attaches records by this
303
+ reading and the validator checks them by it, so both must share it."""
304
+ try:
305
+ return worker_role_execution_ref(manifest, str(name))
306
+ except (AgentInvocationError, ValueError):
307
+ # expected-miss: the caller reports the unbound name.
308
+ return None
309
+
310
+
311
+ def _sealed_conformance_entry(
312
+ project: Path, ref: RunRef, generation: VerificationGenerationRecord,
313
+ check_ref: str, stage_key: str,
314
+ ) -> Mapping[str, Any]:
315
+ relative = conformance_manifest_path(project, ref.task_root)
316
+ sealed = generation["artifactInputs"].get(relative)
317
+ if sealed is None:
318
+ raise EvidenceRefused("the verification generation seals no conformance manifest")
319
+ stored = load_owned_object_snapshot(
320
+ existing_qa_file(project, relative), artifact="conformance manifest",
321
+ )
322
+ if content_digest(stored.raw_bytes) != sealed:
323
+ raise EvidenceRefused(
324
+ "the conformance manifest changed after the generation was sealed"
325
+ )
326
+ conformance_manifest = stored.value
327
+ errors = validate_conformance_manifest(conformance_manifest)
328
+ if errors:
329
+ raise EvidenceRefused("; ".join(errors))
330
+ entry = next((entry for entry in conformance_manifest["entries"]
331
+ if entry["stageKey"] == stage_key), None)
332
+ if entry is None:
333
+ raise EvidenceRefused(f"{check_ref} is not a sealed conformance entry")
334
+ if conformance_stage(stage_key) not in generation.get("conformanceStages", ()):
335
+ raise EvidenceRefused(f"{check_ref} is not a conformance stage of this generation")
336
+ return entry
337
+
338
+
339
+ def _require_open_attempt(
340
+ manifest_path: Path, identity: InvocationMetadataIdentity,
341
+ ) -> None:
342
+ execution = read_execution_manifest(manifest_path)
343
+ expected = (identity.invocation_ref, identity.participant_ref,
344
+ identity.role_execution_ref, identity.duty_id)
345
+ if not any((row.invocation_ref, row.participant_ref, row.role_execution_ref,
346
+ row.duty_id) == expected for row in execution.invocations):
347
+ raise EvidenceRefused("invocation is not in the run execution identity")
348
+ latest = max((row for row in execution.attempts
349
+ if row.invocation_ref == identity.invocation_ref),
350
+ key=lambda row: row.attempt, default=None)
351
+ if (latest is None or latest.attempt != identity.attempt
352
+ or latest.finished_at is not None):
353
+ raise EvidenceRefused("invocation attempt is not open: finished or replaced")
354
+
355
+
356
+ def _frozen_check(
357
+ project: Path, generation: VerificationGenerationRecord, check_ref: str,
358
+ store: VerificationInputStore,
359
+ ) -> Mapping[str, Any]:
360
+ kind, _, identifier = check_ref.partition(":")
361
+ if kind != "qa" or not identifier:
362
+ raise EvidenceRefused(
363
+ "check reference must be qa:<qaCommands id> or conformance:<stageKey>"
364
+ )
365
+ inputs = store.read(
366
+ safe_qa_path(project, generation["verificationInputsPath"]),
367
+ generation["verificationInputsDigest"],
368
+ )
369
+ matches = [entry for entries in inputs["qaCommands"].values()
370
+ for entry in entries if entry.get("id") == identifier]
371
+ if len(matches) != 1:
372
+ raise EvidenceRefused(f"{check_ref} is not a frozen check of this generation")
373
+ return matches[0]
374
+
375
+
376
+ class _Interrupted(Exception):
377
+ def __init__(self, signum: int) -> None:
378
+ super().__init__(signal.Signals(signum).name)
379
+ self.signum = signum
380
+
381
+
382
+ class _Abandoned(Exception):
383
+ def __init__(self, status: str, error: str | None) -> None:
384
+ super().__init__(error)
385
+ self.status = status
386
+ self.error = error
387
+
388
+
389
+ class _InterruptGuard:
390
+ """Raise while waiting for locks; only flag once the command runs, so the
391
+ capture loop can stop the group, drain and publish before exiting."""
392
+
393
+ def __init__(self) -> None:
394
+ self.signum: int | None = None
395
+ self.capturing = False
396
+
397
+ def __enter__(self) -> _InterruptGuard:
398
+ self._previous = {
399
+ sig: signal.signal(sig, self._handle)
400
+ for sig in (signal.SIGTERM, signal.SIGINT, signal.SIGHUP)
401
+ }
402
+ return self
403
+
404
+ def __exit__(self, *_: object) -> None:
405
+ for sig, handler in self._previous.items():
406
+ signal.signal(sig, handler)
407
+
408
+ def _handle(self, signum: int, _frame: object) -> None:
409
+ if self.signum is None:
410
+ self.signum = signum
411
+ if not self.capturing:
412
+ raise _Interrupted(signum)
413
+
414
+
415
+ def run_evidence_check(
416
+ check: EvidenceCheck, metadata_path: Path, *, store: VerificationInputStore,
417
+ home: Path, on_wait: Callable[[Path], None], notify: Callable[[str], None],
418
+ ) -> int:
419
+ try:
420
+ check_run_dir, check_run = _allocate_check_run(check)
421
+ except OSError as exc:
422
+ notify(f"evidence record was not created ({exc})")
423
+ return EVIDENCE_INCOMPLETE_EXIT
424
+ record = _initial_record(check, check_run)
425
+ with _InterruptGuard() as guard, contextlib.ExitStack() as locks:
426
+
427
+ def finish(status: str, error: str | None, exit_code: int | None) -> int:
428
+ # A signal while the record is published must not abandon it.
429
+ guard.capturing = True
430
+ code = _finish(record, check_run_dir, notify, status, error, exit_code)
431
+ return code if guard.signum is None else 128 + guard.signum
432
+
433
+ try:
434
+ before = _lock_and_recheck(
435
+ check, metadata_path, store, home, on_wait, locks, record,
436
+ )
437
+ capture = _start_capture(check, check_run_dir, record, guard)
438
+ except _Abandoned as exc:
439
+ return finish(exc.status, exc.error, None)
440
+ except _Interrupted as exc:
441
+ return finish("interrupted", str(exc), None)
442
+ except (OSError, JsonBoundaryError, subprocess.SubprocessError) as exc:
443
+ return finish("evidence-error", str(exc), None)
444
+ return _conclude(record, check, capture, before, finish)
445
+
446
+
447
+ def _lock_and_recheck(
448
+ check: EvidenceCheck, metadata_path: Path, store: VerificationInputStore,
449
+ home: Path, on_wait: Callable[[Path], None], locks: contextlib.ExitStack,
450
+ record: VerificationExecutionRecord,
451
+ ) -> VerificationSourceSnapshot:
452
+ try:
453
+ locks.enter_context(worktree_exec_lock(home, check.worktree, on_wait=on_wait))
454
+ for key in check.resource_keys:
455
+ locks.enter_context(resource_exec_lock(home, key, on_wait=on_wait))
456
+ except OSError as exc:
457
+ raise _Abandoned("lock-unavailable", str(exc)) from exc
458
+ record["locks"] = "held"
459
+ try:
460
+ current = resolve_evidence_check(
461
+ check.project, metadata_path, check.check_ref, store=store,
462
+ )
463
+ except EvidenceRefused as exc:
464
+ raise _Abandoned("cancelled", str(exc)) from exc
465
+ if current != check:
466
+ raise _Abandoned("cancelled", "invocation changed while waiting")
467
+ try:
468
+ before, record["targetBefore"] = _observe_target(check, None)
469
+ except ValueError as exc:
470
+ raise _Abandoned("target-changed", str(exc)) from exc
471
+ if not _target_clean(record["targetBefore"]):
472
+ raise _Abandoned("target-changed", None)
473
+ return before
474
+
475
+
476
+ def _start_capture(
477
+ check: EvidenceCheck, check_run_dir: Path, record: VerificationExecutionRecord,
478
+ guard: _InterruptGuard,
479
+ ) -> CommandCapture:
480
+ record.update(status="started", startedAt=_now())
481
+ _publish(check_run_dir, record)
482
+ guard.capturing = True
483
+ return run_captured(
484
+ record["argv"], check.worktree, stdout_path=check_run_dir / "stdout.log",
485
+ stderr_path=check_run_dir / "stderr.log",
486
+ stop_requested=lambda: guard.signum is not None,
487
+ )
488
+
489
+
490
+ def _conclude(
491
+ record: VerificationExecutionRecord, check: EvidenceCheck,
492
+ capture: CommandCapture, before: VerificationSourceSnapshot,
493
+ finish: Callable[[str, str | None, int | None], int],
494
+ ) -> int:
495
+ error = _record_capture(record, check, capture)
496
+ observed = True
497
+ try:
498
+ _, record["targetAfter"] = _observe_target(check, before)
499
+ except ValueError as exc:
500
+ error = error or str(exc)
501
+ except _OBSERVATION_ERRORS as exc:
502
+ error, observed = error or str(exc), False
503
+ status = _capture_status(capture, record["targetAfter"], observed=observed)
504
+ return finish(status, error, (shell_exit_code(capture.returncode)
505
+ if status == "completed" else None))
506
+
507
+
508
+ def _allocate_check_run(check: EvidenceCheck) -> tuple[Path, int]:
509
+ for check_run in itertools.count(1):
510
+ path = check.run_ref.verification_execution_dir(
511
+ check.identity.invocation_ref, check.identity.attempt, check.check_ref,
512
+ check_run,
513
+ )
514
+ try:
515
+ path.mkdir(parents=True)
516
+ except FileExistsError:
517
+ # expected-miss: an earlier run of this check owns that number;
518
+ # reruns never overwrite it.
519
+ continue
520
+ return path, check_run
521
+ raise AssertionError("unreachable")
522
+
523
+
524
+ def _initial_record(
525
+ check: EvidenceCheck, check_run: int,
526
+ ) -> VerificationExecutionRecord:
527
+ generation, identity = check.generation, check.identity
528
+ return {
529
+ "schemaVersion": "1.0", "kind": "verification-execution",
530
+ "status": "lock-unavailable", "runManifestPath": generation["runManifestPath"],
531
+ "verificationGeneration": check.generation_ref.to_payload(),
532
+ "generation": generation["generation"],
533
+ "participantRef": identity.participant_ref,
534
+ "roleExecutionRef": identity.role_execution_ref,
535
+ "invocationRef": identity.invocation_ref, "attempt": identity.attempt,
536
+ "audience": check.audience, "checkRef": check.check_ref, "checkRun": check_run,
537
+ "verificationInputsPath": generation["verificationInputsPath"],
538
+ "verificationInputsDigest": generation["verificationInputsDigest"],
539
+ "resourceKeys": list(check.resource_keys),
540
+ "worktree": generation["sourceRoot"], "expectedHead": generation["head"],
541
+ "declaredCommand": check.declared_command, "command": check.command,
542
+ "argv": shell_argv(check.command),
543
+ "locks": "not-acquired",
544
+ "policy": {"drainAfterExitSeconds": DRAIN_AFTER_EXIT_SECONDS,
545
+ "cleanupGraceSeconds": CLEANUP_GRACE_SECONDS},
546
+ "startedAt": None, "finishedAt": None, "exitCode": None, "signal": None,
547
+ "drain": "not-run", "cleanup": "not-run", "stdout": None, "stderr": None,
548
+ "targetBefore": None, "targetAfter": None, "error": None,
549
+ }
550
+
551
+
552
+ def _observe_target(
553
+ check: EvidenceCheck, previous: VerificationSourceSnapshot | None,
554
+ ) -> tuple[VerificationSourceSnapshot, _TargetRecord]:
555
+ """Protected inputs compare with the seal; generated outputs with the
556
+ previous observation, so an earlier check's report is not this one's."""
557
+ sealed = sealed_source_snapshot(check.generation)
558
+ if previous is None:
559
+ previous = sealed
560
+ read_verification_head(check.worktree, check.generation["head"])
561
+ current = capture_verification_source(
562
+ check.worktree, generated_roots=sealed.generated_roots,
563
+ input_paths=sealed.input_paths,
564
+ )
565
+ changes = compare_verification_sources(sealed, current)
566
+ artifacts = sorted(
567
+ relative for relative, digest in check.generation["artifactInputs"].items()
568
+ if content_digest(existing_qa_file(check.project, relative).read_bytes())
569
+ != digest
570
+ )
571
+ return current, {
572
+ "protectedChanges": list(changes.protected_changes),
573
+ "generatedChanges": list(
574
+ compare_verification_sources(previous, current).generated_changes
575
+ ),
576
+ "unclassifiedPaths": list(changes.unclassified_paths),
577
+ "trackedPathsChanged": changes.tracked_paths_changed,
578
+ "artifactInputChanges": artifacts,
579
+ }
580
+
581
+
582
+ def _target_clean(target: _TargetRecord | None) -> bool:
583
+ return target is not None and not (
584
+ target["protectedChanges"] or target["unclassifiedPaths"]
585
+ or target["trackedPathsChanged"] or target["artifactInputChanges"]
586
+ )
587
+
588
+
589
+ def _record_capture(
590
+ record: VerificationExecutionRecord, check: EvidenceCheck, capture: CommandCapture,
591
+ ) -> str | None:
592
+ code = capture.returncode
593
+ record.update(
594
+ exitCode=code if code >= 0 else None,
595
+ signal=signal.Signals(-code).name if code < 0 else None,
596
+ drain="complete" if capture.drain_complete else "incomplete",
597
+ cleanup=capture.cleanup,
598
+ stdout=_stream_record(check.project, capture.stdout),
599
+ stderr=_stream_record(check.project, capture.stderr),
600
+ )
601
+ return capture.stdout.save_error or capture.stderr.save_error
602
+
603
+
604
+ def _stream_record(project: Path, stream: StreamCapture) -> _StreamRecord:
605
+ return {"path": stream.path.relative_to(project).as_posix(),
606
+ "bytes": stream.bytes, "digest": stream.digest,
607
+ "saved": stream.save_error is None, "forwardError": stream.forward_error}
608
+
609
+
610
+ def _capture_status(
611
+ capture: CommandCapture, target: _TargetRecord | None, *, observed: bool,
612
+ ) -> str:
613
+ if capture.interrupted:
614
+ return "interrupted"
615
+ if capture.stdout.save_error or capture.stderr.save_error:
616
+ return "output-save-failed"
617
+ if not capture.drain_complete:
618
+ return "drain-incomplete"
619
+ if capture.cleanup == "unconfirmed":
620
+ return "cleanup-unconfirmed"
621
+ if not observed:
622
+ return "evidence-error"
623
+ return "completed" if _target_clean(target) else "target-changed"
624
+
625
+
626
+ def _finish(
627
+ record: VerificationExecutionRecord, check_run_dir: Path,
628
+ notify: Callable[[str], None], status: str, error: str | None,
629
+ exit_code: int | None,
630
+ ) -> int:
631
+ record.update(status=status, finishedAt=_now(), error=error)
632
+ path = check_run_dir / "record.json"
633
+ try:
634
+ _publish(check_run_dir, record)
635
+ except (OSError, JsonBoundaryError) as exc:
636
+ notify(f"evidence record was not published ({exc}): {path}")
637
+ return EVIDENCE_INCOMPLETE_EXIT
638
+ notify(f"evidence {status}: {path}" + (f" ({error})" if error else ""))
639
+ return EVIDENCE_INCOMPLETE_EXIT if exit_code is None else exit_code
640
+
641
+
642
+ def _publish(check_run_dir: Path, record: VerificationExecutionRecord) -> None:
643
+ write_owned_object_atomic(
644
+ check_run_dir / "record.json", record, artifact="verification execution record",
645
+ schema=_RECORD_SCHEMA, validate_cross_fields=_record_errors,
646
+ )
647
+
648
+
649
+ def read_verification_execution_record(path: Path) -> VerificationExecutionRecord:
650
+ return cast(VerificationExecutionRecord, load_owned_object(
651
+ path, artifact="verification execution record", schema=_RECORD_SCHEMA,
652
+ validate_cross_fields=_record_errors,
653
+ ))
654
+
655
+
656
+ def _record_errors(record: dict[str, Any]) -> list[str]:
657
+ if record["status"] != "completed":
658
+ return []
659
+ streams_saved = all(stream and stream["saved"]
660
+ for stream in (record["stdout"], record["stderr"]))
661
+ one_outcome = (record["exitCode"] is None) != (record["signal"] is None)
662
+ process_settled = (record["drain"] == "complete"
663
+ and record["cleanup"] == "confirmed")
664
+ if (streams_saved and one_outcome and process_settled
665
+ and record["locks"] == "held" and _target_clean(record["targetAfter"])):
666
+ return []
667
+ return ["a completed verification execution requires complete evidence"]
668
+
669
+
670
+ def _now() -> str:
671
+ return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")