Coverage for src/governed_harness/orchestration/engine.py: 93%
1547 statements
« prev ^ index » next coverage.py v7.17.2, created at 2026-11-12 16:06 +0000
« prev ^ index » next coverage.py v7.17.2, created at 2026-11-12 16:06 +0000
1from __future__ import annotations
3import contextlib
4import json
5import socket
6import subprocess # nosec B404 - only SubprocessError: the engine starts no process here
7import threading
8import time
9from collections.abc import Callable, Sequence
10from concurrent.futures import ThreadPoolExecutor
11from concurrent.futures import wait as wait_for_futures
12from datetime import datetime, timedelta
13from functools import cached_property, partial
14from pathlib import Path
15from typing import Any, Literal, cast
17from governed_harness import __version__
18from governed_harness.agents import (
19 AgentExecutionResult,
20 AgentProvider,
21 CommandAgentConfiguration,
22 CommandAgentProvider,
23 SimulatedAgentContext,
24 SimulatedAgentProvider,
25)
26from governed_harness.agents.environment import (
27 ProviderEnvironment,
28 provider_environment,
29)
30from governed_harness.agents.native import native_provider
31from governed_harness.agents.session import SESSION_PROVIDER, SessionAgentProvider
32from governed_harness.capabilities import grants_from_rules
33from governed_harness.capabilities.authorizer import contained_path
34from governed_harness.capabilities.phase import CommandRefused, PhasePolicy, phase_scope
35from governed_harness.capabilities.repository import (
36 DestructiveActionDenied,
37 DestructivePolicy,
38 destructive_scope,
39 repository_policies,
40)
41from governed_harness.configuration.loader import BUILTIN_PROFILE_IDS
42from governed_harness.configuration.models import (
43 RuntimeConfig,
44 ValidatorDefinition,
45 WorkflowPhaseDefinition,
46)
47from governed_harness.delivery.closure import ClosureCommit, create_closure_commit
48from governed_harness.delivery.vcs import VcsError
49from governed_harness.domain.actors import IdentitySource, require_human_actor
50from governed_harness.domain.enums import (
51 ActorType,
52 DecisionKind,
53 EvidenceKind,
54 FindingSeverity,
55 PhaseId,
56 ResultStatus,
57 ValidationKind,
58)
59from governed_harness.domain.errors import (
60 ConfigurationError,
61 NotFoundError,
62 PolicyViolationError,
63)
64from governed_harness.domain.ids import new_id
65from governed_harness.domain.models import (
66 FEEDBACK_RATIONALE_CHARS,
67 HARNESS_ACTOR,
68 Actor,
69 Artifact,
70 CapabilityGrant,
71 ChangedFile,
72 ChangeRequestItem,
73 ChangeSet,
74 ClarificationAnswer,
75 ClarificationQuestion,
76 ClarificationRecord,
77 ClarificationRequest,
78 ConfigurationSnapshot,
79 Evidence,
80 ExceptionRecord,
81 Execution,
82 FeedbackDecision,
83 FeedbackGate,
84 FeedbackTrigger,
85 Finding,
86 FindingLocation,
87 GateEvaluation,
88 HumanDecision,
89 PhaseExecution,
90 Plan,
91 PlanStep,
92 Provenance,
93 ProviderFeedback,
94 Task,
95 ToolInvocation,
96 ValidationResult,
97 utc_now,
98)
99from governed_harness.events import AnchorStore
100from governed_harness.evidence import sha256_json
101from governed_harness.gates import GateEngine, GatePolicy
102from governed_harness.gates.exceptions import apply_exceptions, exception_ids
103from governed_harness.intake import (
104 ClarificationInput,
105 assess_intent,
106 no_acceptance_criteria,
107 resolve_language,
108 revise_task,
109 task_digest,
110)
111from governed_harness.intake.depth import covered_topics, depth_plan
112from governed_harness.intake.language import RECOMMENDATION_TEMPLATES
113from governed_harness.memory import MemoryStore, context_manifest
114from governed_harness.orchestration.agent_results import AgentResults
115from governed_harness.orchestration.corrections import EMPTY_RULE as EMPTY_CORRECTION_RULE
116from governed_harness.orchestration.engine_types import TASK_REVISION_DIGEST_FLAG
117from governed_harness.orchestration.engine_types import EngineServices as EngineServices
118from governed_harness.orchestration.engine_types import PhaseOutcome as PhaseOutcome
119from governed_harness.orchestration.exit_gates import ExitGateCheck, ExitGateEvaluator
120from governed_harness.orchestration.feedback import (
121 TRANSIENT_SCAN_BYTES,
122 FeedbackBuilder,
123 failing_validations,
124 head,
125 transient_cause,
126 verification_reason_codes,
127)
128from governed_harness.orchestration.friction import AFFECTED_TESTS_ID, Friction
129from governed_harness.orchestration.intent_review import ReviewOutcome as IntentReviewOutcome
130from governed_harness.orchestration.ladder import VerificationLadder
131from governed_harness.orchestration.provenance import ProvenanceRecorder
132from governed_harness.orchestration.state_machine import NormativeStateMachine
133from governed_harness.orchestration.workflow import WorkflowGraph, validator_batches
134from governed_harness.profiles import detect_profiles
135from governed_harness.retrospective import RetrospectiveEngine
136from governed_harness.retrospective.causes import CauseAnalysis
137from governed_harness.retrospective.causes import analyze as analyze_causes
138from governed_harness.runtime import (
139 CancellationToken,
140 GitAdapter,
141 PatchApplier,
142 SafeProcessRunner,
143 WorkspaceDiff,
144 WorkspaceSnapshot,
145)
146from governed_harness.runtime.guard import IGNORED_PATTERNS, ExcludedPathGuard
147from governed_harness.runtime.lease import terminate_process_group
148from governed_harness.runtime.sandbox import (
149 SandboxHost,
150 SandboxPlan,
151 SandboxUnavailable,
152 build_sandbox,
153 denied_writes,
154)
155from governed_harness.runtime.snapshots import (
156 SNAPSHOT_CACHE_SEAL,
157 SnapshotSettings,
158 SnapshotStore,
159)
160from governed_harness.runtime.state_location import isolation_marker
161from governed_harness.storage import SQLiteStateStore
162from governed_harness.telemetry import MetricsProjector
163from governed_harness.validators import (
164 TRACEABILITY_VALIDATOR_ID,
165 IndependentReviewValidator,
166 RequirementTraceabilityValidator,
167 TraceabilityOutput,
168 ValidationContext,
169 ValidatorRegistry,
170)
171from governed_harness.validators.base import ValidatorOutput
172from governed_harness.validators.coverage import CoverageValidator, coverage_minimum
174CANCELLATION_REQUESTED = "Cancellation requested"
175_CORRECTION_AUTHORIZED = "correction.authorized"
176_FINDING_RECORDED = "finding.recorded"
177_FILESYSTEM_READ = "filesystem.read"
178# A limit crossed by the last agent call stops the run before these phases (#157).
179_BUDGET_CHECKED_PHASES = frozenset({PhaseId.INDEPENDENT_REVIEW, PhaseId.DECISION})
181FAILED_ATTEMPT_STATUSES = frozenset(
182 {
183 ResultStatus.FAILED,
184 ResultStatus.ERROR,
185 ResultStatus.TIMED_OUT,
186 ResultStatus.INTERRUPTED,
187 }
188)
189"""Phase results that use up one of the workflow's ``maxAttempts``."""
191PHASE_ORDER_REASON = (
192 "phases run one at a time in the order of the workflow graph: a run has one current phase "
193 "and one workspace"
194)
195SUBTASK_ORDER_REASON = (
196 "the sub-tasks of a decomposition share the run's one workspace and each one's "
197 "IMPLEMENTATION writes it; a sub-task starts after every earlier one passed its gate"
198)
199"""The limits of ``parallelizable`` recorded in ``workflow.schedule`` (#3)."""
200DEFAULT_VALIDATOR_TIMEOUT_SECONDS = 900
202WORKSPACE_GUARD_ID = "harness.workspace-guard"
203"""Validator id of the excluded-path check (``governance.protectExcludedPaths``)."""
204OUT_OF_CHANGESET_RULE = "workspace.out-of-changeset-write"
206UNSUPPORTED_CLAIM_RULE = "agent.unsupported-claim"
207"""Rule id of the finding recorded when an agent reported success and verification failed."""
208CLAIM_CHECK_ID = "harness.claim-check"
209"""Validator id of that finding: the harness compares the claim with recorded results."""
212REJECTED_REASON = "Rejected by human decision"
215def run_is_open(execution: Execution) -> bool:
216 """Whether a run may still change: not closed, not cancelled and not rejected. A run that
217 failed or is blocked can be resumed with ``run continue`` and stays open."""
218 if execution.status in {ResultStatus.PASSED, ResultStatus.CANCELLED}:
219 return False
220 return not (
221 execution.status is ResultStatus.FAILED and execution.terminal_reason == REJECTED_REASON
222 )
225def acceptance_contract_digest(task: Task) -> str:
226 """Digest of the acceptance contract SPECIFICATION freezes: requirements, acceptance
227 criteria and constraints of a task revision."""
228 return sha256_json(
229 {
230 "requirements": [item.model_dump(mode="json") for item in task.requirements],
231 "acceptance": [item.model_dump(mode="json") for item in task.acceptance_criteria],
232 "constraints": list(task.constraints),
233 }
234 )
237def _affected_tests_failed(outputs: list[Any]) -> PhaseOutcome | None:
238 """The outcome of a fast-lane attempt stopped by its affected tests (#58), if it was."""
239 last = outputs[-1].result if outputs else None
240 if last is None or last.validator_id != AFFECTED_TESTS_ID:
241 return None
242 if last.status is ResultStatus.PASSED: 242 ↛ 243line 242 didn't jump to line 243 because the condition on line 242 was never true
243 return None
244 return PhaseOutcome(
245 last.status,
246 "The affected tests did not pass; the full suite runs on the next attempt",
247 last.evidence_refs,
248 )
251class _ProcessLedger:
252 """Records the process groups a run's runner starts (flag ``process:<run>``), so that a
253 recovery after a killed harness can terminate the ones still running."""
255 _lock = threading.Lock()
256 """Validators may run side by side (governance.enforceWorkflow, #3, and
257 friction.fastLane.verification.parallel, #58): the read-modify-write of the flag is
258 serialized across threads."""
260 def __init__(self, state: SQLiteStateStore, execution_id: str) -> None:
261 self.state = state
262 self.key = f"process:{execution_id}"
264 def started(self, pid: int, argv: tuple[str, ...]) -> None:
265 with self._lock:
266 recorded = json.loads(self.state.get_flag(self.key) or "{}")
267 recorded[str(pid)] = {
268 "pgid": pid,
269 "host": socket.gethostname(),
270 "argv0": argv[0] if argv else "",
271 "startedAt": utc_now().isoformat(),
272 }
273 self.state.set_flag(self.key, json.dumps(recorded, sort_keys=True))
275 def finished(self, pid: int) -> None:
276 with self._lock:
277 recorded = json.loads(self.state.get_flag(self.key) or "{}")
278 if recorded.pop(str(pid), None) is not None: 278 ↛ exitline 278 didn't jump to the function exit
279 self.state.set_flag(self.key, json.dumps(recorded, sort_keys=True))
282class RunEngine:
283 _exit_gate_unmet: str | None = None
284 """Why the last phase attempt did not meet its exit gate (governance.enforceWorkflow)."""
285 _budget_stopped: bool = False
286 """Whether an exceeded budget stopped the last phase before it started (#157)."""
288 def __init__(self, services: EngineServices, sandbox_host: SandboxHost | None = None) -> None:
289 self.s = services
290 self.state_machine = NormativeStateMachine()
291 self.gate_engine = GateEngine()
292 self.validators = ValidatorRegistry()
293 self.retrospective_engine = RetrospectiveEngine()
294 self._sandbox_host = sandbox_host
295 self.provenance: ProvenanceRecorder = ProvenanceRecorder(self)
296 self.snapshots = SnapshotStore(
297 services.paths.workspace,
298 services.artifacts,
299 SnapshotSettings.from_config(services.resolved.project.workspace),
300 services.paths.harness_dir,
301 seal=(
302 lambda: services.state.get_flag(SNAPSHOT_CACHE_SEAL),
303 lambda digest: services.state.set_flag(SNAPSHOT_CACHE_SEAL, digest),
304 ),
305 )
306 self._phase_deadline: float | None = None
307 # The helpers type the engine as an EngineHost (orchestration.hosts); the annotations
308 # keep mypy from inferring these attributes while it checks the engine against it.
309 self.results: AgentResults = AgentResults(self)
310 self.ladder: VerificationLadder = VerificationLadder(self)
311 self.friction: Friction = Friction(self)
313 @property
314 def sandbox_host(self) -> SandboxHost:
315 """The host the agent sandbox is built for; detected on first use unless injected."""
316 if self._sandbox_host is None:
317 self._sandbox_host = SandboxHost.detect()
318 return self._sandbox_host
320 # ----- creation and lifecycle -------------------------------------------------
321 def create_execution(
322 self, task: Task, provider: str | None = None, *, execution_id: str | None = None
323 ) -> Execution:
324 if task.project_id != self.s.resolved.project.project_id: 324 ↛ 325line 324 didn't jump to line 325 because the condition on line 324 was never true
325 raise ConfigurationError(
326 f"task project {task.project_id} does not match {self.s.resolved.project.project_id}"
327 )
328 if self.results.active:
329 # governance.stopTheLine: block refuses a run on top of unapproved changes.
330 self.results.stop_line.check_new_run(task.project_id)
331 execution_id = execution_id or new_id("run")
332 resolved_dict = self.s.resolved.model_dump(mode="json", by_alias=True)
333 config_ref = self.s.artifacts.put_json(
334 resolved_dict,
335 metadata={"kind": "configuration-snapshot", "executionId": execution_id},
336 )
337 workflow_dict = self.s.resolved.workflow.model_dump(mode="json", by_alias=True)
338 workflow_ref = self.s.artifacts.put_json(
339 workflow_dict,
340 metadata={"kind": "workflow", "executionId": execution_id},
341 )
342 configuration_digest = sha256_json(resolved_dict)
343 workflow_digest = sha256_json(workflow_dict)
344 policy_digest = sha256_json(self.s.resolved.effective_policies)
345 execution = Execution(
346 execution_id=execution_id,
347 project_id=task.project_id,
348 task_id=task.task_id,
349 workspace=str(self.s.paths.workspace),
350 status=ResultStatus.PENDING,
351 current_phase=PhaseId.INTENT,
352 configuration_digest=configuration_digest,
353 workflow_digest=workflow_digest,
354 policy_digest=policy_digest,
355 configuration_snapshot_ref=config_ref.uri,
356 workflow_ref=workflow_ref.uri,
357 )
358 self.s.state.put(
359 "execution",
360 execution.execution_id,
361 execution,
362 execution_id=execution.execution_id,
363 project_id=execution.project_id,
364 )
365 snapshot = ConfigurationSnapshot(
366 snapshot_id=new_id("configsnapshot"),
367 execution_id=execution_id,
368 content_digest=configuration_digest,
369 artifact_ref=config_ref.uri,
370 )
371 self.s.state.put(
372 "configuration_snapshot",
373 snapshot.snapshot_id,
374 snapshot,
375 execution_id=execution_id,
376 project_id=execution.project_id,
377 )
378 self.s.state.set_flag(
379 f"provider:{execution_id}", provider or self.s.resolved.project.agent_provider
380 )
381 created: dict[str, Any] = {
382 "taskId": task.task_id,
383 "projectId": task.project_id,
384 "configurationDigest": configuration_digest,
385 "workflowDigest": workflow_digest,
386 "policyDigest": policy_digest,
387 "provider": provider or self.s.resolved.project.agent_provider,
388 }
389 if self._pins_task():
390 created.update(self._pin_task_revision(execution_id, task))
391 self.s.events.append(execution_id, "run.created", created)
392 self._record_artifact(
393 execution,
394 config_ref,
395 kind="CONFIGURATION",
396 provenance=self._provenance(execution),
397 )
398 self._record_artifact(
399 execution,
400 workflow_ref,
401 kind="WORKFLOW",
402 provenance=self._provenance(execution),
403 )
404 return execution
406 def continue_execution(self, execution_id: str) -> Execution:
407 try:
408 execution = self._continue_execution(execution_id)
409 if self.results.active:
410 # governance.stopTheLine and memory.learnFromFindings at the end of a step.
411 execution = self.results.after_run(execution)
412 return execution
413 finally:
414 self.anchor_chain(execution_id)
416 def anchor_chain(self, execution_id: str) -> None:
417 """Copy the head of the run's event chain to the place ``governance.chainAnchor``
418 names, so that ``harness verify`` detects a chain whose last events were deleted. A
419 chain that does not verify is never anchored, and a failed write never stops a run:
420 ``harness verify`` reports the anchor as absent."""
421 mode = self.s.resolved.project.governance_settings.chain_anchor
422 if not mode or mode == "off":
423 return
424 check = self.s.events.check_chain(execution_id)
425 if not check.valid or check.head_sequence is None or check.head_digest is None: 425 ↛ 426line 425 didn't jump to line 426 because the condition on line 425 was never true
426 return
427 store = AnchorStore(mode, self.s.paths.workspace, self.s.resolved.project.project_id)
428 with contextlib.suppress(OSError, subprocess.SubprocessError):
429 store.record(execution_id, check.head_sequence, check.head_digest)
431 def _continue_execution(self, execution_id: str) -> Execution:
432 execution = self.get_execution(execution_id)
433 if not run_is_open(execution):
434 # Closed, cancelled or rejected (#83): a rejected run is reported as it ended, not
435 # evaluated again on the baseline stop the line restored.
436 return execution
437 if self.is_cancelled(execution_id): 437 ↛ 438line 437 didn't jump to line 438 because the condition on line 437 was never true
438 return self._cancel_execution(execution)
439 if self._leases_workspace():
440 blocked = self.recover_interrupted(execution_id)
441 if blocked is not None: 441 ↛ 442line 441 didn't jump to line 442 because the condition on line 441 was never true
442 return blocked
443 if self.results.active:
444 # governance.stopTheLine: restore took the run's changes out of the workspace; a
445 # run that is evaluated again gets them back first, intact or not at all.
446 blocked = self.results.stop_line.reapply(execution)
447 if blocked is not None:
448 return blocked
449 resumed = self._resume_recorded_decision(execution_id)
450 if resumed is not None and not run_is_open(resumed):
451 # A rejection recorded before the harness died ends the run here (#179).
452 return resumed
453 if self._enforces_workflow:
454 self._record_workflow_schedule(execution_id)
455 while True:
456 stopped = self._step(execution_id)
457 if stopped is not None:
458 return stopped
460 def _step(self, execution_id: str) -> Execution | None:
461 """One step of the run loop: the current phase runs; the run where the loop stops, or
462 ``None`` when the loop goes on."""
463 execution = self.get_execution(execution_id)
464 if execution.current_phase is PhaseId.DECISION:
465 if self._decision_waits(execution):
466 return self.get_execution(execution_id)
467 execution = self.get_execution(execution_id)
468 elif execution.current_phase is PhaseId.CLOSURE:
469 self._run_phase(execution, self._phase_closure)
470 return self.get_execution(execution_id)
471 else:
472 execution, action = self._step_work_phase(execution_id, execution)
473 if action == "stop":
474 return execution
475 if action == "next":
476 return None
477 if execution.status in { 477 ↛ 482line 477 didn't jump to line 482 because the condition on line 477 was never true
478 ResultStatus.PASSED,
479 ResultStatus.CANCELLED,
480 ResultStatus.ERROR,
481 }:
482 return execution
483 return None
485 def _step_work_phase(
486 self, execution_id: str, execution: Execution
487 ) -> tuple[Execution, Literal["stop", "next", "check"]]:
488 """Run a phase between INTENT and INDEPENDENT_REVIEW: whether the loop stops on the
489 run, goes on to the next step, or checks whether the run ended."""
490 handler = {
491 PhaseId.INTENT: self._phase_intent,
492 PhaseId.DISCOVERY: self._phase_discovery,
493 PhaseId.SPECIFICATION: self._phase_specification,
494 PhaseId.PLANNING: self._phase_planning,
495 PhaseId.IMPLEMENTATION: self._phase_implementation,
496 PhaseId.VERIFICATION: self._phase_verification,
497 PhaseId.INDEPENDENT_REVIEW: self._phase_independent_review,
498 }[execution.current_phase]
499 phase_id = execution.current_phase
500 outcome = self._run_phase(execution, handler)
501 execution = self.get_execution(execution_id)
502 if outcome.status is not ResultStatus.PASSED:
503 return execution, self._after_failed_phase(execution, phase_id, outcome)
504 if (
505 phase_id is PhaseId.VERIFICATION
506 and self.results.active
507 and self.results.after_passed_verification(execution)
508 ):
509 # planning.decomposition: the next sub-task starts (#39).
510 return execution, "next"
511 return execution, "check"
513 def _after_failed_phase(
514 self, execution: Execution, phase_id: PhaseId, outcome: PhaseOutcome
515 ) -> Literal["stop", "next"]:
516 """After a phase that did not pass: a correction cycle goes on to the next step,
517 otherwise the loop stops on the run."""
518 if self._exit_gate_unmet is not None or self._budget_stopped:
519 # The phase's own work passed but its exit gate did not (#3), or an exceeded
520 # budget stopped the phase before it started (#157): no correction cycle starts.
521 return "stop"
522 if phase_id is PhaseId.VERIFICATION and self._after_failed_verification(execution, outcome):
523 return "next"
524 if (
525 phase_id is PhaseId.INDEPENDENT_REVIEW
526 and self.results.active
527 and self.results.after_failed_review(execution, outcome.summary)
528 ):
529 return "next"
530 return "stop"
532 def _decision_waits(self, execution: Execution) -> bool:
533 """Run DECISION; whether the run stops there (BLOCKED). A ChangeSet that changed
534 outside the run sends it back to VERIFICATION first under
535 ``verification.reverifyOnChange`` (#78)."""
536 if self._reverify_after_change(execution):
537 return False
538 outcome = self._run_phase(execution, self._phase_decision)
539 return outcome.status is ResultStatus.BLOCKED
541 def cancel(self, execution_id: str, actor_id: str = "human.local") -> Execution:
542 execution = self.get_execution(execution_id)
543 self.s.state.set_flag(f"cancel:{execution_id}", "1")
544 actor = Actor(actor_type=ActorType.HUMAN, actor_id=actor_id)
545 self.s.events.append(execution_id, "run.cancellation.requested", {}, actor=actor)
546 try:
547 cancelled = self._cancel_execution(execution)
548 if self.results.active:
549 self.results.stop_line.stop(cancelled, "cancelled")
550 return cancelled
551 finally:
552 self.anchor_chain(execution_id)
554 def decide(
555 self,
556 *,
557 execution_id: str,
558 decision: DecisionKind,
559 change_set_digest: str,
560 actor_id: str,
561 rationale: str,
562 actor_display_name: str | None = None,
563 identity_source: IdentitySource | None = None,
564 expires_at: datetime | None = None,
565 acknowledged_risks: tuple[str, ...] = (),
566 change_requests: tuple[ChangeRequestItem, ...] = (),
567 checked_items: tuple[str, ...] = (),
568 ) -> HumanDecision:
569 require_human_actor(actor_id, f"decide {decision.value} on a gate")
570 execution = self.get_execution(execution_id)
571 if execution.current_phase is not PhaseId.DECISION:
572 raise PolicyViolationError("human decisions are accepted only in DECISION")
573 execution, gate = self._decision_gate(
574 execution_id, execution, decision, change_set_digest, rationale
575 )
576 if acknowledged_risks or change_requests or self.results.active:
577 # Risk factors to acknowledge and structured change requests (#52).
578 self.results.check_decision(
579 execution, decision, change_set_digest, acknowledged_risks, change_requests
580 )
581 if checked_items or self.ladder.active:
582 # The manual checklist (review.manualChecklist, #55).
583 self.ladder.check_decision(execution, decision, checked_items)
584 record, actor = self._decision_record(
585 execution,
586 gate,
587 execution_id=execution_id,
588 decision=decision,
589 change_set_digest=change_set_digest,
590 actor_id=actor_id,
591 rationale=rationale,
592 actor_display_name=actor_display_name,
593 identity_source=identity_source,
594 expires_at=expires_at,
595 acknowledged_risks=acknowledged_risks,
596 change_requests=change_requests,
597 checked_items=checked_items,
598 )
599 self.s.state.put(
600 "decision",
601 record.decision_id,
602 record,
603 execution_id=execution_id,
604 project_id=execution.project_id,
605 )
606 self.s.events.append(
607 execution_id,
608 "human.decision.recorded",
609 record.model_dump(mode="json"),
610 actor=actor,
611 )
612 self._apply_decision(execution, record, gate, actor)
613 self.anchor_chain(execution_id)
614 return record
616 def _apply_decision(
617 self, execution: Execution, record: HumanDecision, gate: GateEvaluation, actor: Actor
618 ) -> Execution:
619 """Move the run on under a recorded decision: the part of ``decide`` after its
620 ``human.decision.recorded`` event, which a resume also runs for a decision whose
621 harness died before it (#179)."""
622 if self.ladder.active and record.decision in {
623 DecisionKind.APPROVE,
624 DecisionKind.APPROVE_EXCEPTION,
625 }:
626 self.ladder.after_decision(execution, record)
627 updated = execution.model_copy(
628 update={"human_decision_id": record.decision_id, "updated_at": utc_now()}
629 )
630 updated = self._decided_execution(
631 execution,
632 updated,
633 record,
634 gate,
635 actor,
636 execution.execution_id,
637 record.decision,
638 record.change_set_digest,
639 record.change_requests,
640 )
641 self._save_execution(updated)
642 if record.decision is DecisionKind.REJECT and self.results.active:
643 self.results.stop_line.stop(updated, "rejected")
644 return updated
646 def _resume_recorded_decision(self, execution_id: str) -> Execution | None:
647 """Apply a decision whose ``human.decision.recorded`` event is stored but whose
648 harness died before the run moved on (#179, H47 K10), so the person is not asked
649 again and no second decision is recorded.
651 Fail closed: only the latest recorded decision of the run is considered, only while
652 the run waits in DECISION on the very gate the decision is bound to, and only when it
653 still holds (the current ChangeSet and acceptance contract, not expired, the
654 exception of an ``APPROVE_EXCEPTION`` recorded under ``review.exceptions``). A
655 pre-authorised approval is left to ``friction.preAuthorization``. Otherwise nothing is
656 applied and DECISION asks a person as before. Returns the run when a decision was
657 applied, ``None`` otherwise."""
658 execution = self.get_execution(execution_id)
659 if (
660 execution.current_phase is not PhaseId.DECISION
661 or execution.human_decision_id
662 or not execution.gate_evaluation_id
663 ):
664 return None
665 recorded = [
666 item
667 for item in self.s.events.list(execution_id)
668 if item.event_type == "human.decision.recorded"
669 ]
670 if not recorded:
671 return None
672 payload = recorded[-1].payload
673 decision_id = payload.get("decision_id") or payload.get("decisionId")
674 if not isinstance(decision_id, str): 674 ↛ 675line 674 didn't jump to line 675 because the condition on line 674 was never true
675 return None
676 record = self.s.state.get("decision", decision_id, HumanDecision)
677 if ( 677 ↛ 683line 677 didn't jump to line 683 because the condition on line 677 was never true
678 record.execution_id != execution_id
679 or record.gate_evaluation_id != execution.gate_evaluation_id
680 or record.pre_authorization_id is not None
681 or record.actor.actor_type is not ActorType.HUMAN
682 ):
683 return None
684 gate = self.s.state.get("gate", execution.gate_evaluation_id, GateEvaluation)
685 change_set = self._refresh_changeset(execution, record_on_run=False)
686 execution = self.get_execution(execution_id)
687 if gate.change_set_digest != record.change_set_digest: 687 ↛ 688line 687 didn't jump to line 688 because the condition on line 687 was never true
688 return None
689 if self._stale_decision(execution, record, change_set) is not None:
690 return None
691 if ( 691 ↛ 701line 691 didn't jump to line 701 because the condition on line 691 was never true
692 record.decision is DecisionKind.APPROVE_EXCEPTION
693 and self.s.resolved.project.exceptions_enabled
694 and not any(
695 item.decision_id == record.decision_id
696 for item in self.s.state.list(
697 "exception", ExceptionRecord, execution_id=execution_id
698 )
699 )
700 ):
701 return None
702 self.s.events.append(
703 execution_id,
704 "decision.resumed",
705 {
706 "decisionId": record.decision_id,
707 "decision": record.decision.value,
708 "changeSetDigest": record.change_set_digest,
709 },
710 )
711 return self._apply_decision(execution, record, gate, record.actor)
713 def _decision_gate(
714 self,
715 execution_id: str,
716 execution: Execution,
717 decision: DecisionKind,
718 change_set_digest: str,
719 rationale: str,
720 ) -> tuple[Execution, GateEvaluation]:
721 """The run and its gate evaluation for a decision bound to ``change_set_digest``;
722 refuses a stale digest, a missing or different gate and an invalid approval."""
723 # #95: comparing must not move the run's digest; a refused decision would otherwise
724 # hide the change from verification.reverifyOnChange on the next run continue.
725 current_change_set = self._refresh_changeset(execution, record_on_run=False)
726 execution = self.get_execution(execution_id)
727 if current_change_set.digest != change_set_digest:
728 raise PolicyViolationError(
729 "decision digest does not match the current ChangeSet; prior approval is stale"
730 )
731 if not execution.gate_evaluation_id: 731 ↛ 733line 731 didn't jump to line 733 because the condition on line 731 was never true
732 # Materialize the gate if the run stopped immediately before evaluation.
733 self.continue_execution(execution_id)
734 execution = self.get_execution(execution_id)
735 if not execution.gate_evaluation_id: 735 ↛ 736line 735 didn't jump to line 736 because the condition on line 735 was never true
736 raise PolicyViolationError("no current gate evaluation exists")
737 gate = self.s.state.get("gate", execution.gate_evaluation_id, GateEvaluation)
738 if gate.change_set_digest != change_set_digest: 738 ↛ 739line 738 didn't jump to line 739 because the condition on line 738 was never true
739 raise PolicyViolationError("gate was evaluated for a different ChangeSet")
740 if decision is DecisionKind.APPROVE and gate.status is not ResultStatus.PASSED:
741 raise PolicyViolationError(
742 "APPROVE is only valid for a passed automatic gate; use APPROVE_EXCEPTION with rationale"
743 )
744 if decision is DecisionKind.APPROVE_EXCEPTION and not rationale.strip(): 744 ↛ 745line 744 didn't jump to line 745 because the condition on line 744 was never true
745 raise PolicyViolationError("exception approval requires a rationale")
746 return execution, gate
748 def _decision_record(
749 self,
750 execution: Execution,
751 gate: GateEvaluation,
752 *,
753 execution_id: str,
754 decision: DecisionKind,
755 change_set_digest: str,
756 actor_id: str,
757 rationale: str,
758 actor_display_name: str | None,
759 identity_source: IdentitySource | None,
760 expires_at: datetime | None,
761 acknowledged_risks: tuple[str, ...],
762 change_requests: tuple[ChangeRequestItem, ...],
763 checked_items: tuple[str, ...],
764 ) -> tuple[HumanDecision, Actor]:
765 """The human decision to record, bound to the run's digests, and its actor."""
766 contract_digest = self._current_contract_digest(execution)
767 decided_at = utc_now()
768 expiry = self.s.resolved.project.governance_settings.decision_expiry_hours
769 # One expiry, HumanDecision.expires_at: the exception's when one is recorded
770 # (review.exceptions, which the exception ledger reuses), otherwise the decision's
771 # validity (governance.decisionExpiryHours).
772 decision_expires_at = expires_at
773 if decision_expires_at is None and expiry:
774 decision_expires_at = decided_at + timedelta(hours=expiry)
775 actor = Actor(
776 actor_type=ActorType.HUMAN, actor_id=actor_id, display_name=actor_display_name
777 )
778 record = HumanDecision(
779 decision_id=new_id("decision"),
780 execution_id=execution_id,
781 gate_evaluation_id=gate.gate_evaluation_id,
782 actor=actor,
783 decision=decision,
784 rationale=rationale.strip() or decision.value,
785 change_set_digest=change_set_digest,
786 configuration_digest=execution.configuration_digest,
787 policy_digest=execution.policy_digest,
788 acceptance_contract_digest=contract_digest,
789 identity_source=identity_source,
790 decided_at=decided_at,
791 expires_at=decision_expires_at,
792 acknowledged_risks=tuple(dict.fromkeys(acknowledged_risks)),
793 change_requests=change_requests,
794 checked_items=tuple(dict.fromkeys(checked_items)),
795 )
796 return record, actor
798 def _decided_execution(
799 self,
800 execution: Execution,
801 updated: Execution,
802 record: HumanDecision,
803 gate: GateEvaluation,
804 actor: Actor,
805 execution_id: str,
806 decision: DecisionKind,
807 change_set_digest: str,
808 change_requests: tuple[ChangeRequestItem, ...],
809 ) -> Execution:
810 """The run after the decision: back to a correction, rejected, or pending delivery."""
811 if decision is DecisionKind.REQUEST_CHANGES:
812 return self._request_changes(
813 execution,
814 updated,
815 record,
816 gate,
817 actor,
818 execution_id,
819 decision,
820 change_set_digest,
821 change_requests,
822 )
823 if decision is DecisionKind.REJECT:
824 return updated.model_copy(
825 update={
826 "status": ResultStatus.FAILED,
827 "terminal_reason": REJECTED_REASON,
828 "updated_at": utc_now(),
829 }
830 )
831 return updated.model_copy(update={"status": ResultStatus.PENDING, "updated_at": utc_now()})
833 def _request_changes(
834 self,
835 execution: Execution,
836 updated: Execution,
837 record: HumanDecision,
838 gate: GateEvaluation,
839 actor: Actor,
840 execution_id: str,
841 decision: DecisionKind,
842 change_set_digest: str,
843 change_requests: tuple[ChangeRequestItem, ...],
844 ) -> Execution:
845 """A REQUEST_CHANGES decision: the change requests open, the correction is authorized
846 and, when it applies, the person's feedback is recorded for the next attempt."""
847 if change_requests:
848 self.results.open_change_requests(execution, record)
849 transition = self.state_machine.authorize_correction(PhaseId.DECISION)
850 updated = updated.model_copy(
851 update={
852 "status": ResultStatus.PENDING,
853 "current_phase": transition.target,
854 "gate_evaluation_id": None,
855 "human_decision_id": None,
856 "updated_at": utc_now(),
857 }
858 )
859 self.s.events.append(
860 execution_id,
861 _CORRECTION_AUTHORIZED,
862 {
863 "decisionId": record.decision_id,
864 "invalidatedPhases": [phase.value for phase in transition.invalidated],
865 "approvedChangeSetDigest": change_set_digest,
866 },
867 actor=actor,
868 )
869 if self._feedback_applies(execution_id):
870 validations, findings = self._gate_inputs(gate)
871 self._record_feedback(
872 updated,
873 PhaseId.DECISION,
874 trigger="CHANGES_REQUESTED",
875 change_set_digest=change_set_digest,
876 gate=FeedbackGate(
877 gate_id="delivery_candidate",
878 gate_evaluation_id=gate.gate_evaluation_id,
879 status=gate.status,
880 reason_codes=gate.reason_codes,
881 ),
882 validations=validations,
883 findings=findings,
884 decision=FeedbackDecision(
885 decision=decision,
886 rationale=head(
887 record.rationale
888 + "".join(
889 f"\n{item.item_id} (blocking, verified by {item.condition}): "
890 f"{item.description}"
891 for item in change_requests
892 ),
893 FEEDBACK_RATIONALE_CHARS,
894 ),
895 actor_id=actor.actor_id,
896 ),
897 )
898 return updated
900 def clarify(
901 self, *, task_id: str, clarification: ClarificationInput, actor: Actor
902 ) -> tuple[ClarificationRecord, Task]:
903 """Answer the open clarification request of a task and store the revised task.
905 The answers and the revision are recorded on the event chain of the run whose INTENT
906 asked the questions; ``continue_execution`` then assesses the revised task."""
907 if actor.actor_type is not ActorType.HUMAN:
908 raise PolicyViolationError("only a human actor can answer clarification questions")
909 require_human_actor(actor.actor_id, "answer clarification questions")
910 task = self.get_task(task_id)
911 executions = [
912 item
913 for item in self.s.state.list("execution", Execution, project_id=task.project_id)
914 if item.task_id == task_id
915 ]
916 advanced = [item for item in executions if item.current_phase is not PhaseId.INTENT]
917 if advanced:
918 raise PolicyViolationError(
919 f"task {task_id} has a run past INTENT ({advanced[0].execution_id}); "
920 "clarify a new task instead"
921 )
922 previous_digest = task_digest(task)
923 requests = sorted(
924 (
925 item
926 for item in self.s.state.list(
927 "clarification_request", ClarificationRequest, project_id=task.project_id
928 )
929 if item.task_id == task_id and item.task_digest == previous_digest
930 ),
931 key=lambda item: item.created_at,
932 )
933 if not requests:
934 raise NotFoundError(
935 f"no open clarification request for the current revision of task {task_id}"
936 )
937 request = requests[-1]
938 revision = revise_task(task, request.questions, clarification)
939 execution = self.get_execution(request.execution_id)
940 by_id = {question.question_id: question for question in request.questions}
941 previous_ref = self.s.artifacts.put_json(
942 task.model_dump(mode="json"), metadata={"kind": "task-intent"}
943 )
944 revised_ref = self.s.artifacts.put_json(
945 revision.task.model_dump(mode="json"), metadata={"kind": "task-intent"}
946 )
947 record = ClarificationRecord(
948 clarification_id=new_id("clarification"),
949 execution_id=execution.execution_id,
950 task_id=task_id,
951 request_id=request.request_id,
952 actor=actor,
953 answers=tuple(
954 ClarificationAnswer(
955 question_id=question_id,
956 rule_id=by_id[question_id].rule_id,
957 target=by_id[question_id].target,
958 question=by_id[question_id].text,
959 answer=answer.strip(),
960 )
961 for question_id, answer in sorted(
962 clarification.answers.items(), key=lambda item: int(item[0][2:])
963 )
964 ),
965 replaced_criteria=revision.replaced_criteria,
966 added_criteria=revision.added_criteria,
967 added_requirements=revision.added_requirements,
968 previous_task_digest=previous_digest,
969 task_digest=task_digest(revision.task),
970 previous_task_ref=previous_ref.uri,
971 task_ref=revised_ref.uri,
972 contract_answers=dict(clarification.contract or {}),
973 )
974 self.s.state.put("task", task_id, revision.task, project_id=task.project_id)
975 if self._pins_task(): 975 ↛ 978line 975 didn't jump to line 978 because the condition on line 975 was always true
976 # A revision through clarify is the one way the task of an open run may change.
977 self.s.pin_task_revision(execution.execution_id, revised_ref.uri, record.task_digest)
978 self.s.state.put(
979 "clarification",
980 record.clarification_id,
981 record,
982 execution_id=execution.execution_id,
983 project_id=execution.project_id,
984 )
985 record_ref = self.s.artifacts.put_json(
986 record.model_dump(mode="json", by_alias=True),
987 metadata={"kind": "clarification-record", "executionId": execution.execution_id},
988 )
989 self._record_evidence(
990 execution,
991 PhaseId.INTENT,
992 EvidenceKind.HUMAN_DECISION,
993 record_ref,
994 f"Clarification: {len(record.answers)} answer(s), task revised",
995 supports=(request.request_id, task_id),
996 )
997 self.s.events.append(
998 execution.execution_id,
999 "intent.clarified",
1000 record.model_dump(mode="json"),
1001 actor=actor,
1002 )
1003 if clarification.confirm_contract and self.ladder.active:
1004 # The person confirms the operational contract with the answers (#55).
1005 self.ladder.intake.confirm_revision(execution, revision.task, actor)
1006 if self.results.active:
1007 # intake.projectSetup (#56): answers to P1 questions become the project's setup.
1008 self.results.project_setup.store_answers(execution, record)
1009 self.anchor_chain(execution.execution_id)
1010 return record, revision.task
1012 # ----- phases -----------------------------------------------------------------
1013 def _run_phase(
1014 self, execution: Execution, handler: Callable[[Execution, PhaseExecution], PhaseOutcome]
1015 ) -> PhaseOutcome:
1016 phase_id = execution.current_phase
1017 previous = [
1018 phase
1019 for phase in self.s.state.list(
1020 "phase", PhaseExecution, execution_id=execution.execution_id
1021 )
1022 if phase.phase_id is phase_id
1023 ]
1024 attempt = 1 + len(previous)
1025 self._exit_gate_unmet = None
1026 if self._enforces_workflow:
1027 # dependsOn and the order of the sub-tasks decide whether the phase may start (#3).
1028 waiting = self._phase_may_start(execution, phase_id)
1029 if waiting is not None:
1030 return waiting
1031 definition = self._phase_definition(phase_id)
1032 if definition is not None:
1033 failed = sum(1 for item in previous if item.status in FAILED_ATTEMPT_STATUSES)
1034 if failed >= definition.max_attempts:
1035 return self._attempts_exhausted(execution, definition, failed)
1036 self._phase_deadline = time.monotonic() + definition.timeout_seconds
1037 else:
1038 self._phase_deadline = None
1039 phase = PhaseExecution(
1040 phase_execution_id=new_id("phase"),
1041 execution_id=execution.execution_id,
1042 phase_id=phase_id,
1043 status=ResultStatus.RUNNING,
1044 attempt=attempt,
1045 started_at=utc_now(),
1046 )
1047 self.s.state.put(
1048 "phase",
1049 phase.phase_execution_id,
1050 phase,
1051 execution_id=execution.execution_id,
1052 project_id=execution.project_id,
1053 )
1054 running = execution.model_copy(
1055 update={"status": ResultStatus.RUNNING, "updated_at": utc_now()}
1056 )
1057 self._save_execution(running)
1058 self.s.events.append(
1059 execution.execution_id,
1060 "phase.started",
1061 {"phaseId": phase_id, "attempt": attempt},
1062 phase_execution_id=phase.phase_execution_id,
1063 )
1064 stopped = (
1065 self.results.before_phase(running, phase)
1066 if self.results.active and phase_id in _BUDGET_CHECKED_PHASES
1067 else None
1068 )
1069 self._budget_stopped = stopped is not None
1070 outcome = stopped or self._execute_handler(running, phase, handler)
1071 if definition is not None:
1072 outcome = self._apply_phase_settings(definition, phase, outcome)
1073 exit_checks: list[ExitGateCheck] = []
1074 if self._enforces_workflow and outcome.status is ResultStatus.PASSED:
1075 outcome, exit_checks = self._check_exit_gates(execution, phase, outcome)
1076 completed = phase.model_copy(
1077 update={
1078 "status": outcome.status,
1079 "finished_at": utc_now(),
1080 "evidence_refs": outcome.evidence_refs,
1081 "artifact_refs": outcome.artifact_refs,
1082 "summary": outcome.summary,
1083 "output_digest": sha256_json(
1084 {
1085 "status": outcome.status,
1086 "summary": outcome.summary,
1087 "evidenceRefs": outcome.evidence_refs,
1088 }
1089 ),
1090 }
1091 )
1092 self.s.state.put(
1093 "phase",
1094 completed.phase_execution_id,
1095 completed,
1096 execution_id=execution.execution_id,
1097 project_id=execution.project_id,
1098 )
1099 completed_payload: dict[str, Any] = {
1100 "phaseId": phase_id,
1101 "attempt": attempt,
1102 "status": outcome.status,
1103 "summary": outcome.summary,
1104 "evidenceRefs": list(outcome.evidence_refs),
1105 }
1106 if definition is not None:
1107 # The exit gate the attempt met (PASSED) or did not meet; the condition itself is
1108 # evaluated by the phase.
1109 completed_payload["exitGate"] = definition.exit_gate
1110 completed_payload["exitGateMet"] = outcome.status is ResultStatus.PASSED
1111 completed_payload["timeoutSeconds"] = definition.timeout_seconds
1112 completed_payload["maxAttempts"] = definition.max_attempts
1113 if self._enforces_workflow:
1114 # Evaluated from the run's records after the phase passed (#3).
1115 completed_payload["exitGate"] = self.workflow_graph.phase(phase_id).exit_gate
1116 completed_payload["exitGateMet"] = outcome.status is ResultStatus.PASSED
1117 completed_payload["exitConditions"] = [item.as_dict() for item in exit_checks]
1118 self.s.events.append(
1119 execution.execution_id,
1120 "phase.completed",
1121 completed_payload,
1122 phase_execution_id=phase.phase_execution_id,
1123 )
1124 self._save_execution(self._after_phase(execution.execution_id, phase_id, outcome))
1125 return outcome
1127 def _execute_handler(
1128 self,
1129 running: Execution,
1130 phase: PhaseExecution,
1131 handler: Callable[[Execution, PhaseExecution], PhaseOutcome],
1132 ) -> PhaseOutcome:
1133 """Run the phase's work under the policies of the phase. A command the policies refuse
1134 before it starts (a provider command no grant allows under
1135 ``governance.phaseCapabilities``, #87; a destructive command under
1136 ``destructiveActionsDefault: deny``, #76) blocks the phase with the finding the refusal
1137 recorded; any other exception is an ``ERROR``."""
1138 execution_id = running.execution_id
1139 try:
1140 if self.is_cancelled(execution_id): 1140 ↛ 1141line 1140 didn't jump to line 1141 because the condition on line 1140 was never true
1141 return PhaseOutcome(ResultStatus.CANCELLED, CANCELLATION_REQUESTED)
1142 with (
1143 phase_scope(self._phase_policy(running, phase)),
1144 destructive_scope(self._destructive_policy(running)),
1145 ):
1146 return handler(running, phase)
1147 except (KeyboardInterrupt, SystemExit) as interruption:
1148 # The harness itself is stopping (Ctrl-C, or SIGTERM under the workspace lease):
1149 # record the phase as interrupted so that a later run continue recovers it.
1150 if self._leases_workspace():
1151 self._mark_interrupted(
1152 execution_id,
1153 phase,
1154 f"The harness was interrupted ({type(interruption).__name__})",
1155 )
1156 raise
1157 except (CommandRefused, DestructiveActionDenied) as refusal:
1158 return PhaseOutcome(ResultStatus.BLOCKED, f"{type(refusal).__name__}: {refusal}")
1159 except Exception as error:
1160 self.s.events.append(
1161 execution_id,
1162 "phase.error",
1163 {
1164 "phaseId": phase.phase_id,
1165 "errorType": type(error).__name__,
1166 "message": str(error),
1167 },
1168 phase_execution_id=phase.phase_execution_id,
1169 )
1170 return PhaseOutcome(ResultStatus.ERROR, f"{type(error).__name__}: {error}")
1172 def _after_phase(
1173 self, execution_id: str, phase_id: PhaseId, outcome: PhaseOutcome
1174 ) -> Execution:
1175 """The run after a phase attempt: the next phase when it passed, otherwise the
1176 attempt's status (with the reason of an error or a cancellation)."""
1177 latest = self.get_execution(execution_id)
1178 if outcome.status is not ResultStatus.PASSED:
1179 stopped = outcome.status in {ResultStatus.ERROR, ResultStatus.CANCELLED}
1180 return latest.model_copy(
1181 update={
1182 "status": outcome.status,
1183 "terminal_reason": outcome.summary if stopped else None,
1184 "updated_at": utc_now(),
1185 }
1186 )
1187 if phase_id is PhaseId.CLOSURE:
1188 return latest.model_copy(
1189 update={"status": ResultStatus.PASSED, "updated_at": utc_now()}
1190 )
1191 transition = self.state_machine.advance(phase_id, ResultStatus.PASSED)
1192 target = self._next_phase(phase_id, transition.target)
1193 if phase_id is PhaseId.SPECIFICATION:
1194 # acceptanceTests.disputes (#94): after a revision of the frozen tests the plan
1195 # and the implementation stand, and the run verifies the same change again.
1196 target = self.results.disputes.resume_target(execution_id) or target
1197 return latest.model_copy(
1198 update={
1199 "status": ResultStatus.PENDING,
1200 "current_phase": target,
1201 # A run that moves on has no reason to have stopped (#77): the reason of an
1202 # earlier stop it was resumed from does not stay on it.
1203 "terminal_reason": None,
1204 "updated_at": utc_now(),
1205 }
1206 )
1208 def _phase_intent(self, execution: Execution, phase: PhaseExecution) -> PhaseOutcome:
1209 task = self.run_task(execution)
1210 task_ref = self.s.artifacts.put_json(
1211 task.model_dump(mode="json"), metadata={"kind": "task-intent"}
1212 )
1213 evidence = self._record_evidence(
1214 execution,
1215 phase.phase_id,
1216 EvidenceKind.INTENT,
1217 task_ref,
1218 "Structured intent and acceptance criteria",
1219 supports=(task.task_id,),
1220 )
1221 policy = self.s.resolved.project.criteria_policy
1222 # A task without acceptance criteria (accepted under enforce, rule C0) never passes
1223 # INTENT, whatever the policy says now: there is nothing to verify the work against.
1224 if no_acceptance_criteria(task):
1225 policy = "enforce"
1226 intake_config = self.s.resolved.project.intake
1227 language = intake_config.language if intake_config else None
1228 questions = (
1229 assess_intent(task, language=language, basic_topics=self._basic_topics(task))
1230 if policy != "off"
1231 else ()
1232 )
1233 review_refs: tuple[str, ...] = ()
1234 if self.friction.active and self.friction.fast_lane is not None:
1235 # friction.fastLane (#58): the lane of the run, recorded with its reasons.
1236 self.friction.classify(execution, phase, task)
1237 if self.results.active and policy != "off":
1238 review = self._intent_review(execution, phase, task, questions)
1239 review_refs = review.evidence_refs
1240 if review.blocked is not None:
1241 return PhaseOutcome(
1242 ResultStatus.BLOCKED, review.blocked, (evidence.artifact_ref, *review_refs)
1243 )
1244 questions = questions + review.questions
1245 # #79: an exhausted review records its open points as assumptions of a revision.
1246 task = review.revised or task
1247 contract: dict[str, Any] | None = None
1248 ladder_block: str | None = None
1249 if self.ladder.active:
1250 # Localisation, the operational contract and the interruption budget (#55).
1251 intake = self.ladder.intent(execution, phase, task, questions)
1252 review_refs = (*review_refs, *intake.evidence_refs)
1253 questions = questions + intake.questions
1254 contract = intake.contract
1255 ladder_block = intake.blocked
1256 if ladder_block is not None and contract is None: 1256 ↛ 1257line 1256 didn't jump to line 1257 because the condition on line 1256 was never true
1257 return PhaseOutcome(
1258 ResultStatus.BLOCKED, ladder_block, (evidence.artifact_ref, *review_refs)
1259 )
1260 if not questions and ladder_block is None:
1261 return self._intent_identified(
1262 execution, phase, task, (evidence.artifact_ref, *review_refs)
1263 )
1264 return self._intent_clarification(
1265 execution,
1266 phase,
1267 task,
1268 questions,
1269 policy,
1270 contract=contract,
1271 ladder_block=ladder_block,
1272 evidence=evidence,
1273 )
1275 def _basic_topics(self, task: Task) -> tuple[str, ...]:
1276 """The fundamental topics the deterministic intake asks first under
1277 ``intake.ambiguityReview.depth: adaptive`` (see :mod:`governed_harness.intake.depth`):
1278 the next ones nobody answered, while the task's rounds last. Empty without the key."""
1279 intake_config = self.s.resolved.project.intake
1280 settings = intake_config.ambiguity_settings if intake_config else None
1281 if settings is None or not settings.adaptive:
1282 return ()
1283 plan = depth_plan(task, settings.rounds, settings.questions)
1284 answered = sum(
1285 1
1286 for record in self.s.state.list(
1287 "clarification", ClarificationRecord, project_id=task.project_id
1288 )
1289 if record.task_id == task.task_id
1290 )
1291 if answered >= plan.rounds: 1291 ↛ 1292line 1291 didn't jump to line 1292 because the condition on line 1291 was never true
1292 return ()
1293 return plan.next_topics(covered_topics(task))
1295 def _intent_review(
1296 self,
1297 execution: Execution,
1298 phase: PhaseExecution,
1299 task: Task,
1300 questions: tuple[ClarificationQuestion, ...],
1301 ) -> IntentReviewOutcome:
1302 """Agent review of ambiguity and completeness, and the check of earlier answers
1303 (intake.ambiguityReview, intake.validateAnswers; #37); the fast lane of #58 keeps the
1304 deterministic intake only, except, under ``depth: adaptive``, for a poor request: a
1305 one-line wish looks small but is the request that needs the review most."""
1306 skip = (
1307 self.friction.active
1308 and not self._poor_request(task)
1309 and self.friction.skips(execution, "ambiguityReview", PhaseId.INTENT)
1310 )
1311 return self.results.intent.questions(execution, phase, task, questions, agent=not skip)
1313 def _poor_request(self, task: Task) -> bool:
1314 """Whether ``depth: adaptive`` measures the task as ``very-poor`` or ``poor``."""
1315 intake_config = self.s.resolved.project.intake
1316 settings = intake_config.ambiguity_settings if intake_config else None
1317 if settings is None or not settings.adaptive:
1318 return False
1319 return depth_plan(task, settings.rounds, settings.questions).deterministic_basics
1321 def _intent_identified(
1322 self, execution: Execution, phase: PhaseExecution, task: Task, refs: tuple[str, ...]
1323 ) -> PhaseOutcome:
1324 """INTENT with nothing to clarify; under architecture.mode: agent (#56) a new project
1325 first gets architecture options a person chooses from."""
1326 if self.results.active:
1327 advised = self.results.architecture.advise(execution, phase, task)
1328 if advised is not None:
1329 return advised
1330 return PhaseOutcome(ResultStatus.PASSED, "Intent is structured and identifiable", refs)
1332 def _intent_clarification(
1333 self,
1334 execution: Execution,
1335 phase: PhaseExecution,
1336 task: Task,
1337 questions: tuple[ClarificationQuestion, ...],
1338 policy: str,
1339 *,
1340 contract: dict[str, Any] | None,
1341 ladder_block: str | None,
1342 evidence: Evidence,
1343 ) -> PhaseOutcome:
1344 """INTENT with questions or a ladder block: the clarification request, and a block
1345 under ``enforce`` (or the ladder's), otherwise the questions as warnings."""
1346 request_evidence = self._request_clarification(
1347 execution,
1348 phase,
1349 task,
1350 questions,
1351 "enforce" if policy == "enforce" or ladder_block else "warn",
1352 contract=contract,
1353 )
1354 refs = (evidence.artifact_ref, request_evidence.artifact_ref)
1355 if ladder_block is not None and not (questions and policy == "enforce"):
1356 return PhaseOutcome(ResultStatus.BLOCKED, ladder_block, refs)
1357 if policy == "enforce":
1358 # The rules that asked are the cause a person reads on status and in the inbox
1359 # (H44): the count alone sent them to `harness task questions` to learn why.
1360 rules = ", ".join(dict.fromkeys(question.rule_id for question in questions))
1361 return PhaseOutcome(
1362 ResultStatus.BLOCKED,
1363 f"Intent needs clarification: {len(questions)} question(s) (rules {rules})",
1364 refs,
1365 )
1366 intake_config = self.s.resolved.project.intake
1367 language = resolve_language(task, intake_config.language if intake_config else None)
1368 for question in questions:
1369 self._record_clarification_finding(
1370 execution, question, request_evidence, language or "en"
1371 )
1372 return PhaseOutcome(
1373 ResultStatus.PASSED,
1374 f"Intent is structured and identifiable; {len(questions)} clarification "
1375 "question(s) recorded as warnings",
1376 refs,
1377 )
1379 def _request_clarification(
1380 self,
1381 execution: Execution,
1382 phase: PhaseExecution,
1383 task: Task,
1384 questions: tuple[ClarificationQuestion, ...],
1385 policy: Literal["enforce", "warn"],
1386 *,
1387 contract: dict[str, Any] | None = None,
1388 ) -> Evidence:
1389 request = ClarificationRequest(
1390 request_id=new_id("clarifyrequest"),
1391 execution_id=execution.execution_id,
1392 task_id=task.task_id,
1393 task_digest=task_digest(task),
1394 policy=policy,
1395 questions=questions,
1396 contract=contract,
1397 )
1398 self.s.state.put(
1399 "clarification_request",
1400 request.request_id,
1401 request,
1402 execution_id=execution.execution_id,
1403 project_id=execution.project_id,
1404 )
1405 request_ref = self.s.artifacts.put_json(
1406 request.model_dump(mode="json", by_alias=True),
1407 metadata={"kind": "clarification-request", "executionId": execution.execution_id},
1408 )
1409 evidence = self._record_evidence(
1410 execution,
1411 phase.phase_id,
1412 EvidenceKind.INTENT,
1413 request_ref,
1414 f"Clarification request: {len(questions)} question(s)"
1415 + (" and the operational contract" if contract is not None else ""),
1416 supports=tuple(dict.fromkeys(question.target for question in questions))
1417 or (task.task_id,),
1418 )
1419 self.s.events.append(
1420 execution.execution_id,
1421 "intent.clarification.requested",
1422 request.model_dump(mode="json"),
1423 phase_execution_id=phase.phase_execution_id,
1424 )
1425 return evidence
1427 def _record_clarification_finding(
1428 self,
1429 execution: Execution,
1430 question: ClarificationQuestion,
1431 evidence: Evidence,
1432 language: Literal["en", "es"] = "en",
1433 ) -> None:
1434 finding = Finding(
1435 finding_id=new_id("finding"),
1436 execution_id=execution.execution_id,
1437 validator_id="intake.clarification",
1438 rule_id=question.rule_id,
1439 category="intent-clarification",
1440 severity=FindingSeverity.LOW,
1441 message=question.text,
1442 evidence_refs=(evidence.artifact_ref,),
1443 recommendation=RECOMMENDATION_TEMPLATES[language].format(
1444 question_id=question.question_id
1445 ),
1446 provenance=self._provenance(execution),
1447 )
1448 self.s.state.put(
1449 "finding",
1450 finding.finding_id,
1451 finding,
1452 execution_id=execution.execution_id,
1453 project_id=execution.project_id,
1454 )
1455 self.s.events.append(
1456 execution.execution_id,
1457 _FINDING_RECORDED,
1458 finding.model_dump(mode="json"),
1459 actor=finding.provenance.actor,
1460 )
1462 def _phase_discovery(self, execution: Execution, phase: PhaseExecution) -> PhaseOutcome:
1463 detections = detect_profiles(
1464 self.s.paths.workspace,
1465 [
1466 profile
1467 for profile in self.s.resolved.profiles
1468 if profile.profile_id not in BUILTIN_PROFILE_IDS
1469 ],
1470 )
1471 selected = {profile.profile_id for profile in self.s.resolved.profiles}
1472 if not any(item.profile_id in selected and item.confidence > 0 for item in detections): 1472 ↛ 1473line 1472 didn't jump to line 1473 because the condition on line 1472 was never true
1473 return PhaseOutcome(
1474 ResultStatus.BLOCKED, "Configured profile was not detected in workspace"
1475 )
1476 git = GitAdapter(self.s.paths.workspace).state()
1477 snapshot = self.snapshots.take(for_storage=True)
1478 snapshot_ref = self.snapshots.store(
1479 snapshot,
1480 metadata={"kind": "workspace-baseline", "executionId": execution.execution_id},
1481 )
1482 self.s.state.set_flag(f"baseline:{execution.execution_id}", snapshot_ref.uri)
1483 discovery = {
1484 "detections": [item.__dict__ for item in detections],
1485 "selectedProfiles": sorted(selected),
1486 "git": git.__dict__,
1487 "baselineDigest": snapshot.digest,
1488 "baselineRef": snapshot_ref.uri,
1489 }
1490 discovery_ref = self.s.artifacts.put_json(discovery, metadata={"kind": "discovery"})
1491 evidence = self._record_evidence(
1492 execution,
1493 phase.phase_id,
1494 EvidenceKind.CONFIGURATION,
1495 discovery_ref,
1496 "Workspace technology, Git state and baseline snapshot",
1497 )
1498 updated = execution.model_copy(
1499 update={"baseline_revision": git.head or snapshot.digest, "updated_at": utc_now()}
1500 )
1501 self._save_execution(updated)
1502 if self.ladder.active:
1503 # The environment preflight (environment, #55).
1504 blocked = self.ladder.discovery(updated, phase, snapshot.digest)
1505 if blocked is not None:
1506 return PhaseOutcome(
1507 blocked.status,
1508 blocked.summary,
1509 (evidence.artifact_ref, snapshot_ref.uri, *blocked.evidence_refs),
1510 )
1511 if self.results.active:
1512 # architecture.mode: agent (#56): one cached survey per existing project.
1513 surveyed = self.results.architecture.survey(updated, phase, self.run_task(updated))
1514 if surveyed is not None:
1515 return surveyed
1516 return PhaseOutcome(
1517 ResultStatus.PASSED,
1518 "Workspace and baseline discovered",
1519 (evidence.artifact_ref, snapshot_ref.uri),
1520 )
1522 def _phase_specification(self, execution: Execution, phase: PhaseExecution) -> PhaseOutcome:
1523 task = self.run_task(execution)
1524 digest = acceptance_contract_digest(task)
1525 contract = {
1526 "taskId": task.task_id,
1527 "requirements": [item.model_dump(mode="json") for item in task.requirements],
1528 "acceptanceCriteria": [
1529 item.model_dump(mode="json") for item in task.acceptance_criteria
1530 ],
1531 "constraints": list(task.constraints),
1532 "digest": digest,
1533 }
1534 contract_ref = self.s.artifacts.put_json(contract, metadata={"kind": "acceptance-contract"})
1535 if self._pins_task():
1536 self.s.state.set_flag(f"contract:{execution.execution_id}", digest)
1537 evidence = self._record_evidence(
1538 execution,
1539 phase.phase_id,
1540 EvidenceKind.INTENT,
1541 contract_ref,
1542 "Versioned acceptance contract",
1543 supports=tuple(item.criterion_id for item in task.acceptance_criteria),
1544 )
1545 if self.results.active and not (
1546 self.friction.active
1547 and self.friction.skips(execution, "acceptanceTests", PhaseId.SPECIFICATION)
1548 ):
1549 # verification.acceptanceTests (#52): independent tests a person approves.
1550 blocked = self.results.acceptance.propose(execution, phase, task)
1551 if blocked is not None:
1552 return blocked
1553 return PhaseOutcome(
1554 ResultStatus.PASSED, "Acceptance contract frozen", (evidence.artifact_ref,)
1555 )
1557 def _phase_planning(self, execution: Execution, phase: PhaseExecution) -> PhaseOutcome:
1558 task = self.run_task(execution)
1559 if self.results.active and not (
1560 self.friction.active
1561 and self.friction.skips(execution, "decomposition", PhaseId.PLANNING)
1562 ):
1563 # planning.decomposition (#39): a large task waits for an approved plan.
1564 blocked = self.results.decomposition.plan(execution, phase, task)
1565 if blocked is not None:
1566 return blocked
1567 if self.ladder.active:
1568 # The verification plan and the preflight on the baseline (#55).
1569 blocked = self.ladder.planning(execution, phase, task)
1570 if blocked is not None:
1571 return blocked
1572 selection = MemoryStore(self.s.state).select(
1573 project_id=execution.project_id,
1574 task_id=task.task_id,
1575 execution_id=execution.execution_id,
1576 )
1577 manifest = context_manifest(selection.records, selection.exclusions)
1578 context_ref = self.s.artifacts.put_json(manifest, metadata={"kind": "context-manifest"})
1579 self.s.state.set_flag(f"context:{execution.execution_id}", context_ref.uri)
1580 steps = (
1581 PlanStep(
1582 step_id=new_id("step"),
1583 description=f"Apply implementation instruction using mode {task.implementation.mode}",
1584 capabilities=(_FILESYSTEM_READ, "filesystem.write", "process.execute"),
1585 expected_evidence=("agent invocation", "ChangeSet"),
1586 ),
1587 PlanStep(
1588 step_id=new_id("step"),
1589 description="Execute technology-profile validators",
1590 capabilities=(_FILESYSTEM_READ, "process.execute"),
1591 expected_evidence=tuple(
1592 item.validator_id for item in self.s.resolved.effective_validators
1593 ),
1594 ),
1595 PlanStep(
1596 step_id=new_id("step"),
1597 description="Perform independent review and evaluate policy",
1598 capabilities=(_FILESYSTEM_READ, "approval.request"),
1599 expected_evidence=("findings", "gate evaluation", "human decision"),
1600 ),
1601 )
1602 plan_steps: tuple[PlanStep, ...] = steps
1603 if self.results.active:
1604 plan_steps = (*self.results.decomposition.plan_steps(execution), *steps)
1605 plan = Plan(
1606 plan_id=new_id("plan"),
1607 execution_id=execution.execution_id,
1608 task_id=task.task_id,
1609 steps=plan_steps,
1610 risks=("Repository content is untrusted", "Approval becomes stale after any change"),
1611 validator_ids=tuple(item.validator_id for item in self.s.resolved.effective_validators)
1612 + (
1613 (TRACEABILITY_VALIDATOR_ID,)
1614 if self.s.resolved.project.requirement_traceability != "off"
1615 else ()
1616 )
1617 + ("review.independent",),
1618 provenance=self._provenance(execution),
1619 )
1620 plan_ref = self.s.artifacts.put_json(
1621 plan.model_dump(mode="json"), metadata={"kind": "plan"}
1622 )
1623 self.s.state.put(
1624 "plan",
1625 plan.plan_id,
1626 plan,
1627 execution_id=execution.execution_id,
1628 project_id=execution.project_id,
1629 )
1630 self.s.state.set_flag(f"plan:{execution.execution_id}", plan.plan_id)
1631 evidence = self._record_evidence(
1632 execution,
1633 phase.phase_id,
1634 EvidenceKind.PLAN,
1635 plan_ref,
1636 "Plan, capabilities, validators and risks",
1637 supports=(task.task_id,),
1638 )
1639 if self.friction.active:
1640 # friction.planApproval (#8 through #58): L tasks and tasks with a risk flag wait
1641 # for a person to approve the plan, bound to its digest.
1642 waiting = self.friction.plan_checkpoint(execution, phase, task, plan, plan_ref.uri)
1643 if waiting is not None:
1644 return waiting
1645 return PhaseOutcome(
1646 ResultStatus.PASSED,
1647 "Plan and context manifest recorded",
1648 (evidence.artifact_ref, context_ref.uri),
1649 )
1651 def _phase_implementation(self, execution: Execution, phase: PhaseExecution) -> PhaseOutcome:
1652 if self._leases_workspace():
1653 self._record_implementation_start(execution, phase)
1654 task = self.run_task(execution)
1655 plan_id = self.s.state.get_flag(f"plan:{execution.execution_id}")
1656 if not plan_id: 1656 ↛ 1657line 1656 didn't jump to line 1657 because the condition on line 1656 was never true
1657 return PhaseOutcome(ResultStatus.BLOCKED, "No approved plan exists")
1658 plan = self.s.state.get("plan", plan_id, Plan)
1659 provider_id = self.s.state.get_flag(f"provider:{execution.execution_id}") or "simulated"
1660 built = self._build_provider(execution, phase, provider_id)
1661 if isinstance(built, PhaseOutcome):
1662 return built
1663 provider, actor, sandbox, sandbox_refs = built
1664 if self.results.active:
1665 blocked = self.results.before_agent_call(execution, phase, "implement")
1666 if blocked is not None:
1667 return blocked
1668 # runtime.reproduceFirst: the workspace as the correction attempt found it.
1669 self.results.corrections.start(execution, phase)
1670 grants = grants_from_rules(
1671 execution.execution_id, actor, self.s.resolved.effective_capabilities
1672 )
1673 cancellation = CancellationToken(lambda: self.is_cancelled(execution.execution_id))
1674 runner = self._runner(execution)
1675 context_uri = self.s.state.get_flag(f"context:{execution.execution_id}")
1676 memory_context = self._memory_context(context_uri)
1677 runtime = self.s.resolved.project.runtime
1678 task, request_extra = self._implement_request_extra(
1679 execution, phase, task, provider_id, grants
1680 )
1681 context = SimulatedAgentContext(
1682 execution_id=execution.execution_id,
1683 workspace=self.s.paths.workspace,
1684 grants=grants,
1685 artifact_store=self.s.artifacts,
1686 process_runner=runner,
1687 patch_applier=PatchApplier(self.s.paths.workspace),
1688 provenance=self._provenance(execution).model_copy(update={"actor": actor}),
1689 timeout_seconds=self._implement_timeout(runtime.command_timeout_seconds, request_extra),
1690 max_output_bytes=runtime.max_output_bytes,
1691 cancellation=cancellation,
1692 context_manifest_ref=context_uri,
1693 memory_context=memory_context,
1694 feedback=self._pending_feedback(execution, phase),
1695 request_extra=request_extra,
1696 )
1697 invoked = self._invoke_implement(
1698 execution, phase, provider, task, plan, context, sandbox, runtime
1699 )
1700 if isinstance(invoked, PhaseOutcome):
1701 return invoked
1702 return self._implementation_outcome(
1703 execution,
1704 phase,
1705 invoked,
1706 request_extra,
1707 runtime,
1708 sandbox,
1709 sandbox_refs,
1710 timeout_seconds=context.timeout_seconds,
1711 )
1713 def _implementation_outcome(
1714 self,
1715 execution: Execution,
1716 phase: PhaseExecution,
1717 result: AgentExecutionResult,
1718 request_extra: dict[str, Any] | None,
1719 runtime: RuntimeConfig,
1720 sandbox: SandboxPlan | None,
1721 sandbox_refs: tuple[str, ...],
1722 *,
1723 timeout_seconds: int,
1724 ) -> PhaseOutcome:
1725 """The outcome of IMPLEMENTATION after the implement call: the claim to check, the
1726 self-report and the candidate ChangeSet. ``timeout_seconds``: the time the call was
1727 allowed to run (#179)."""
1728 if self.results.active:
1729 limited = self._after_implement_call(
1730 execution, phase, result, request_extra, timeout_seconds
1731 )
1732 if limited is not None:
1733 return limited
1734 self._record_claim(execution, result, runtime)
1735 if result.status is not ResultStatus.PASSED:
1736 if sandbox is not None: 1736 ↛ 1737line 1736 didn't jump to line 1737 because the condition on line 1736 was never true
1737 self._record_denied_writes(execution, result.tool_invocations)
1738 self.provenance.record_self_report(execution, phase, result, None)
1739 return PhaseOutcome(
1740 result.status,
1741 result.summary,
1742 ((result.output_ref,) if result.output_ref else ()) + sandbox_refs,
1743 )
1744 change_set = self._refresh_changeset(execution)
1745 self.provenance.record_self_report(execution, phase, result, change_set)
1746 if not change_set.files and not bool(
1747 self.s.resolved.effective_policies.get("allowEmptyChangeSet", False)
1748 ):
1749 return PhaseOutcome(
1750 ResultStatus.FAILED, "Implementation produced no ChangeSet", sandbox_refs
1751 )
1752 return PhaseOutcome(
1753 ResultStatus.PASSED,
1754 f"Candidate ChangeSet contains {len(change_set.files)} file(s)",
1755 (change_set.diff_ref, *sandbox_refs),
1756 )
1758 def _record_claim(
1759 self, execution: Execution, result: AgentExecutionResult, runtime: RuntimeConfig
1760 ) -> None:
1761 """Keep the passed claim of an external provider for the claim check."""
1762 if (
1763 result.status is ResultStatus.PASSED
1764 and runtime.claim_check_enabled
1765 and self._external_provider(execution.execution_id)
1766 ):
1767 self.s.state.set_flag(
1768 f"claim:{execution.execution_id}",
1769 json.dumps(
1770 {
1771 "invocationId": result.invocation.invocation_id,
1772 "status": result.status.value,
1773 "summary": result.summary,
1774 "outputRef": result.output_ref,
1775 }
1776 ),
1777 )
1779 def _record_implementation_start(self, execution: Execution, phase: PhaseExecution) -> None:
1780 """Store the snapshot of the workspace as this IMPLEMENTATION attempt found it."""
1781 # The workspace as this attempt found it: an interrupted attempt is undone to it
1782 # before IMPLEMENTATION runs again, so a change is never implemented twice on top.
1783 snapshot = self.snapshots.take(for_storage=True)
1784 ref = self.snapshots.store(
1785 snapshot,
1786 metadata={"kind": "implementation-start", "executionId": execution.execution_id},
1787 )
1788 self.s.state.set_flag(
1789 f"implstart:{execution.execution_id}",
1790 json.dumps({"phaseExecutionId": phase.phase_execution_id, "snapshotRef": ref.uri}),
1791 )
1793 def _memory_context(self, context_uri: str | None) -> dict[str, Any] | None:
1794 """The memory records and digest of the run's context manifest, when there is one."""
1795 memory_context: dict[str, Any] | None = None
1796 if context_uri: 1796 ↛ 1799line 1796 didn't jump to line 1799 because the condition on line 1796 was always true
1797 manifest = json.loads(self.s.artifacts.get(context_uri))
1798 memory_context = {"records": manifest["records"], "digest": manifest["digest"]}
1799 return memory_context
1801 def _implement_request_extra(
1802 self,
1803 execution: Execution,
1804 phase: PhaseExecution,
1805 task: Task,
1806 provider_id: str,
1807 grants: list[CapabilityGrant],
1808 ) -> tuple[Task, dict[str, Any] | None]:
1809 """The task the implement call receives and the extra request fields of the agent
1810 results and the ladder."""
1811 request_extra: dict[str, Any] | None = None
1812 if self.results.active:
1813 task = self.results.implementation_task(execution, task)
1814 request_extra = self.results.implement_extras(
1815 execution, phase, task, provider_id, grants
1816 )
1817 if self.ladder.active:
1818 # Locations of the locate call and a person's intake attachments, only when there
1819 # are any (#55).
1820 ladder_extra = self.ladder.implement_extras(execution, task)
1821 if ladder_extra:
1822 request_extra = {**(request_extra or {}), **ladder_extra}
1823 return task, request_extra
1825 def _retry_cause(
1826 self,
1827 provider: AgentProvider,
1828 result: AgentExecutionResult,
1829 retries: int,
1830 runtime: RuntimeConfig,
1831 ) -> str | None:
1832 """The transient cause that lets a command provider's failed call be repeated."""
1833 return (
1834 self._transient_cause(result)
1835 if isinstance(provider, CommandAgentProvider) and retries < runtime.retry_limit
1836 else None
1837 )
1839 def _invoke_implement(
1840 self,
1841 execution: Execution,
1842 phase: PhaseExecution,
1843 provider: AgentProvider,
1844 task: Task,
1845 plan: Plan,
1846 context: SimulatedAgentContext,
1847 sandbox: SandboxPlan | None,
1848 runtime: RuntimeConfig,
1849 ) -> AgentExecutionResult | PhaseOutcome:
1850 """The implement call, repeated after a transient failure within the retry limit,
1851 with the excluded paths guarded; a CANCELLED outcome when a wait is cancelled."""
1852 guard = (
1853 ExcludedPathGuard(
1854 self.s.paths.workspace,
1855 include_ignored=self.snapshots.settings.git_listing,
1856 )
1857 if self._protects_excluded_paths()
1858 else None
1859 )
1860 guard_before = guard.fingerprint() if guard else None
1861 retries = 0
1862 try:
1863 while True:
1864 self.provenance.before_invocation(execution)
1865 result = provider.implement(task, plan, context)
1866 self._save_agent_result(execution, phase, result)
1867 self.provenance.after_invocation(execution, result)
1868 cause = self._retry_cause(provider, result, retries, runtime)
1869 if cause is None:
1870 break
1871 retries += 1
1872 # The repeated call runs through the same provider, so under the same sandbox
1873 # prefix; a write the sandbox denied on the failed call is still reported.
1874 if sandbox is not None:
1875 self._record_denied_writes(execution, result.tool_invocations)
1876 self._record_provider_retry(execution, phase, result, cause, retries)
1877 if not self._wait_for_retry(execution.execution_id, runtime.retry_delay_seconds):
1878 return PhaseOutcome(ResultStatus.CANCELLED, CANCELLATION_REQUESTED)
1879 finally:
1880 if guard is not None and guard_before is not None:
1881 self._check_excluded_paths(execution, phase, guard, guard_before)
1882 return result
1884 def _after_implement_call(
1885 self,
1886 execution: Execution,
1887 phase: PhaseExecution,
1888 result: AgentExecutionResult,
1889 request_extra: dict[str, Any] | None,
1890 timeout_seconds: int,
1891 ) -> PhaseOutcome | None:
1892 """Record the implement call for the agent results; an outcome when its contract
1893 limits end the phase."""
1894 self.results.after_agent_call(execution, phase, result)
1895 limited = self._implement_limit(execution, phase, result, request_extra, timeout_seconds)
1896 if limited is not None:
1897 return limited
1898 if result.status is ResultStatus.PASSED:
1899 self.results.corrections.end(execution, phase, result)
1900 return None
1902 def _implement_timeout(self, command_timeout: int, request_extra: dict[str, Any] | None) -> int:
1903 """The time an implement call may run: the command timeout, shortened to the time limit
1904 of the task's size when the request carries ``agentContract`` (#97)."""
1905 bounded = self._bounded_timeout(command_timeout)
1906 contract = (request_extra or {}).get("agentContract")
1907 if not isinstance(contract, dict):
1908 return bounded
1909 return min(bounded, int(contract["timeLimitSeconds"]))
1911 def _implement_limit(
1912 self,
1913 execution: Execution,
1914 phase: PhaseExecution,
1915 result: AgentExecutionResult,
1916 request_extra: dict[str, Any] | None,
1917 timeout_seconds: int | None = None,
1918 ) -> PhaseOutcome | None:
1919 """Record an implement call under ``agentContract`` and end the phase in a controlled
1920 way when the call reached its time limit or token budget (#97). ``timeout_seconds``:
1921 the time the call was allowed to run, which a stopped call names (#179)."""
1922 contract = (request_extra or {}).get("agentContract")
1923 if not isinstance(contract, dict):
1924 return None
1925 return self.results.agent_contract.settle_implement(
1926 execution, phase, result, contract, timeout_seconds=timeout_seconds
1927 )
1929 def _build_provider(
1930 self, execution: Execution, phase: PhaseExecution, provider_id: str
1931 ) -> tuple[AgentProvider, Actor, SandboxPlan | None, tuple[str, ...]] | PhaseOutcome:
1932 """The provider of a run (or of one call kind), with the agent sandbox when it is
1933 enforced; a phase outcome when the provider cannot be started."""
1934 sandbox: SandboxPlan | None = None
1935 sandbox_refs: tuple[str, ...] = ()
1936 if provider_id == "simulated":
1937 provider: AgentProvider = SimulatedAgentProvider()
1938 actor = Actor(actor_type=ActorType.AGENT, actor_id="agent.simulated", version="1")
1939 return provider, actor, sandbox, sandbox_refs
1940 if provider_id == SESSION_PROVIDER:
1941 # Embedded mode (#56): the agent session that drives the harness implements.
1942 def changed() -> list[str]:
1943 diff = self._compute_owned_diff(execution)
1944 # The frozen acceptance tests the harness wrote are not the session's edits
1945 # (#81): a session that changed nothing else has not implemented anything.
1946 harness_written = self.results.acceptance.untouched(execution)
1947 return [item.path for item in diff.changes if item.path not in harness_written]
1949 actor = Actor(actor_type=ActorType.AGENT, actor_id="agent.session", version="1")
1950 return SessionAgentProvider(changed), actor, sandbox, sandbox_refs
1951 provider_config = self.s.resolved.project.agent_providers.get(provider_id)
1952 if provider_config is None: 1952 ↛ 1953line 1952 didn't jump to line 1953 because the condition on line 1952 was never true
1953 return PhaseOutcome(
1954 ResultStatus.BLOCKED,
1955 f"Provider {provider_id!r} is not configured",
1956 )
1957 if self.s.resolved.project.runtime.effective_agent_sandbox == "enforce":
1958 try:
1959 sandbox = build_sandbox(
1960 self.s.paths.workspace,
1961 self.s.resolved.project.runtime.sandbox_write_paths or (),
1962 self.sandbox_host,
1963 protected=self._protected_paths(execution),
1964 allow_network=self._agent_network_allowed(),
1965 )
1966 except SandboxUnavailable as error:
1967 self._record_sandbox_finding(
1968 execution,
1969 rule_id="sandbox.unavailable",
1970 severity=FindingSeverity.HIGH,
1971 message=f"The agent sandbox is enforced but unavailable: {error}",
1972 recommendation=(
1973 "Run on macOS (sandbox-exec) or on Linux with bubblewrap (bwrap) "
1974 "installed, or set runtime.agentSandbox to off to run the agent "
1975 "with the user's permissions."
1976 ),
1977 )
1978 return PhaseOutcome(
1979 ResultStatus.BLOCKED,
1980 f"Agent sandbox unavailable: {error}; the provider was not started",
1981 )
1982 sandbox_refs = (self._record_sandbox_evidence(execution, phase, sandbox),)
1983 environment = None
1984 if provider_config.pass_env is not None or provider_config.env is not None:
1985 environment = provider_environment(provider_config)
1986 if environment.missing:
1987 return PhaseOutcome(
1988 ResultStatus.BLOCKED,
1989 f"Provider {provider_id!r} needs environment variable(s) "
1990 f"{', '.join(environment.missing)} (env fromEnv); the provider was not "
1991 "started",
1992 )
1993 sandbox_refs = (
1994 *sandbox_refs,
1995 self._record_provider_environment(execution, phase, provider_id, environment),
1996 )
1997 configuration = CommandAgentConfiguration(
1998 provider_id=provider_id,
1999 argv_prefix=provider_config.effective_command,
2000 model=provider_config.model,
2001 sandbox_prefix=sandbox.prefix if sandbox else (),
2002 environment=environment,
2003 self_report=bool(self.s.resolved.project.provenance_settings.self_report),
2004 extra_args=provider_config.args or (),
2005 )
2006 provider = (
2007 native_provider(provider_config.kind, configuration)
2008 if provider_config.native
2009 else CommandAgentProvider(configuration)
2010 )
2011 actor = Actor(actor_type=ActorType.AGENT, actor_id=f"agent.{provider_id}", version="1")
2012 return provider, actor, sandbox, sandbox_refs
2014 # ----- capabilities per phase (#4) ----------------------------------------------------
2015 def _phase_policy(self, execution: Execution, phase: PhaseExecution) -> PhasePolicy | None:
2016 """Under ``governance.phaseCapabilities``: what grants made while this phase runs may
2017 carry, recorded as evidence of the phase attempt."""
2018 resolved = self.s.resolved
2019 if not resolved.project.governance_settings.phase_capabilities:
2020 return None
2021 definition = next(
2022 (item for item in resolved.workflow.phases if item.phase_id is phase.phase_id), None
2023 )
2024 # Each configured provider's actor (agent.ID) may start its own command, and only when
2025 # the run's process.execute grants allow it (#87).
2026 launch = {
2027 f"agent.{provider_id}": tuple(config.effective_command)
2028 for provider_id, config in resolved.project.agent_providers.items()
2029 if config.effective_command
2030 }
2032 def refused(actor: Actor, argv: Sequence[str]) -> None:
2033 self.results.record_finding(
2034 execution,
2035 validator_id="harness.capabilities",
2036 rule_id="capabilities.command-denied",
2037 category="security",
2038 severity=FindingSeverity.HIGH,
2039 message=(
2040 f"{actor.actor_id} tried to start a command no process.execute grant allows "
2041 f"in {phase.phase_id.value}: {' '.join(argv)[:200]}"
2042 ),
2043 recommendation=(
2044 "Grant the command with capabilities.extend (process.execute) in "
2045 "project.yaml if it is intended (governance.phaseCapabilities)."
2046 ),
2047 )
2049 policy = PhasePolicy(
2050 phase=phase.phase_id.value,
2051 allowed=frozenset(definition.allowed_capabilities if definition else ()),
2052 launch=launch,
2053 on_refused=refused,
2054 )
2055 provider = self.s.state.get_flag(f"provider:{execution.execution_id}")
2056 description = policy.describe(
2057 resolved.effective_capabilities, f"agent.{provider}" if provider else None
2058 )
2059 ref = self.s.artifacts.put_json(
2060 description,
2061 metadata={"kind": "phase-capabilities", "executionId": execution.execution_id},
2062 )
2063 self._record_evidence(
2064 execution,
2065 phase.phase_id,
2066 EvidenceKind.OTHER,
2067 ref,
2068 f"Capabilities of {phase.phase_id.value}: {', '.join(sorted(policy.allowed)) or 'none'}",
2069 )
2070 self.s.events.append(
2071 execution.execution_id,
2072 "capabilities.resolved",
2073 {**description, "evidenceRef": ref.uri},
2074 phase_execution_id=phase.phase_execution_id,
2075 )
2076 return policy
2078 def _destructive_policy(self, execution: Execution) -> DestructivePolicy | None:
2079 """Under ``governance.applyRepositoryPolicies`` with ``destructiveActionsDefault: deny``
2080 (#5): destructive commands are refused unless granted, each attempt a finding."""
2081 if not repository_policies(self.s.resolved).deny_destructive:
2082 return None
2084 def denied(actor: Actor, argv: Sequence[str], reason: str) -> None:
2085 self.results.record_finding(
2086 execution,
2087 validator_id="harness.capabilities",
2088 rule_id="capabilities.destructive-denied",
2089 category="security",
2090 severity=FindingSeverity.HIGH,
2091 message=(
2092 f"{actor.actor_id} tried a destructive command ({reason}): "
2093 f"{' '.join(argv)[:200]}"
2094 ),
2095 recommendation=(
2096 "Grant process.destructive for this command in project.yaml if it is "
2097 "intended (policies.destructiveActionsDefault: deny)."
2098 ),
2099 )
2101 return DestructivePolicy(self.s.paths.workspace, denied)
2103 # ----- declared settings (#51) -------------------------------------------------------
2104 def _phase_definition(self, phase_id: PhaseId) -> WorkflowPhaseDefinition | None:
2105 """The workflow definition of a phase when ``governance.applyWorkflowSettings`` is on."""
2106 if not self.s.resolved.project.governance_settings.apply_workflow_settings:
2107 return None
2108 return next(
2109 (item for item in self.s.resolved.workflow.phases if item.phase_id is phase_id), None
2110 )
2112 def _attempts_exhausted(
2113 self, execution: Execution, definition: WorkflowPhaseDefinition, failed: int
2114 ) -> PhaseOutcome:
2115 reason = (
2116 f"{definition.phase_id} is not started again: {failed} failed attempt(s) reached its "
2117 f"maxAttempts ({definition.max_attempts})"
2118 )
2119 self.s.events.append(
2120 execution.execution_id,
2121 "phase.attempts.exhausted",
2122 {
2123 "phaseId": definition.phase_id,
2124 "failedAttempts": failed,
2125 "maxAttempts": definition.max_attempts,
2126 },
2127 )
2128 latest = self.get_execution(execution.execution_id)
2129 self._save_execution(
2130 latest.model_copy(
2131 update={
2132 "status": ResultStatus.BLOCKED,
2133 "terminal_reason": reason,
2134 "updated_at": utc_now(),
2135 }
2136 )
2137 )
2138 return PhaseOutcome(ResultStatus.BLOCKED, reason)
2140 def _apply_phase_settings(
2141 self, definition: WorkflowPhaseDefinition, phase: PhaseExecution, outcome: PhaseOutcome
2142 ) -> PhaseOutcome:
2143 """An attempt that outlived ``timeoutSeconds`` is ``TIMED_OUT``."""
2144 started = phase.started_at or utc_now()
2145 elapsed = (utc_now() - started).total_seconds()
2146 if outcome.status is ResultStatus.PASSED and elapsed > definition.timeout_seconds: 2146 ↛ 2147line 2146 didn't jump to line 2147 because the condition on line 2146 was never true
2147 return PhaseOutcome(
2148 ResultStatus.TIMED_OUT,
2149 f"{definition.phase_id} took {elapsed:.0f} s, more than its timeoutSeconds "
2150 f"({definition.timeout_seconds})",
2151 outcome.evidence_refs,
2152 outcome.artifact_refs,
2153 )
2154 return outcome
2156 # ----- workflow enforcement (governance.enforceWorkflow, #3) --------------------------
2157 @property
2158 def _enforces_workflow(self) -> bool:
2159 return bool(self.s.resolved.project.governance_settings.enforce_workflow)
2161 @cached_property
2162 def workflow_graph(self) -> WorkflowGraph:
2163 """The phase graph of the configured workflow."""
2164 return WorkflowGraph(self.s.resolved.workflow)
2166 @cached_property
2167 def exit_gates(self) -> ExitGateEvaluator:
2168 return ExitGateEvaluator(self)
2170 def _next_phase(self, phase_id: PhaseId, fixed: PhaseId) -> PhaseId:
2171 """The phase after a passed one: the workflow graph's under
2172 ``governance.enforceWorkflow`` (the resolver checked that it keeps the fixed order),
2173 otherwise the state machine's."""
2174 if not self._enforces_workflow:
2175 return fixed
2176 return self.workflow_graph.next_phase(phase_id) or fixed
2178 def _passed_phases(self, execution_id: str) -> set[PhaseId]:
2179 """Phases whose latest attempt passed (or, for a phase that is not required, was not
2180 applicable)."""
2181 latest: dict[PhaseId, PhaseExecution] = {}
2182 for item in self.s.state.list("phase", PhaseExecution, execution_id=execution_id):
2183 current = latest.get(item.phase_id)
2184 if current is None or item.attempt > current.attempt: 2184 ↛ 2182line 2184 didn't jump to line 2182 because the condition on line 2184 was always true
2185 latest[item.phase_id] = item
2186 graph = self.workflow_graph
2187 return {
2188 phase_id
2189 for phase_id, item in latest.items()
2190 if item.status is ResultStatus.PASSED
2191 or (
2192 item.status is ResultStatus.NOT_APPLICABLE
2193 and phase_id in graph.order()
2194 and not graph.phase(phase_id).required
2195 )
2196 }
2198 def _phase_may_start(self, execution: Execution, phase_id: PhaseId) -> PhaseOutcome | None:
2199 """``None`` when every ``dependsOn`` phase of ``phase_id`` passed (and, for
2200 IMPLEMENTATION of a decomposed run, every earlier sub-task passed its gate); otherwise
2201 the run is ``BLOCKED`` without starting an attempt."""
2202 unmet = self.workflow_graph.unmet_dependencies(
2203 phase_id, self._passed_phases(execution.execution_id)
2204 )
2205 if unmet:
2206 names = ", ".join(item.value for item in unmet)
2207 return self._not_started(
2208 execution,
2209 f"{phase_id} cannot start: dependsOn {names} has no passed attempt",
2210 "phase.dependencies.unmet",
2211 {
2212 "phaseId": phase_id,
2213 "dependsOn": [
2214 item.value for item in self.workflow_graph.dependencies(phase_id)
2215 ],
2216 "unmet": [item.value for item in unmet],
2217 },
2218 )
2219 if phase_id is PhaseId.IMPLEMENTATION and self.results.active:
2220 return self._subtask_may_start(execution)
2221 return None
2223 def _subtask_may_start(self, execution: Execution) -> PhaseOutcome | None:
2224 """The sub-tasks of a decomposition run one after another: they share the run's one
2225 workspace and each one's IMPLEMENTATION writes it. A sub-task starts only after every
2226 earlier one passed its gate (``subtask.completed``)."""
2227 decomposition = self.results.decomposition
2228 subtasks = decomposition.approved(execution)
2229 if not subtasks: 2229 ↛ 2231line 2229 didn't jump to line 2231 because the condition on line 2229 was always true
2230 return None
2231 events = self.s.events.list(execution.execution_id)
2232 if not any(event.event_type == "workflow.subtasks.scheduled" for event in events):
2233 self.s.events.append(
2234 execution.execution_id,
2235 "workflow.subtasks.scheduled",
2236 {"count": len(subtasks), "mode": "sequential", "reason": SUBTASK_ORDER_REASON},
2237 )
2238 current = min(decomposition.index(execution), len(subtasks))
2239 passed = {
2240 event.payload.get("index")
2241 for event in events
2242 if event.event_type == "subtask.completed"
2243 and event.payload.get("gateStatus") == ResultStatus.PASSED.value
2244 }
2245 missing = [number for number in range(1, current + 1) if number not in passed]
2246 if not missing:
2247 return None
2248 return self._not_started(
2249 execution,
2250 f"sub-task {current + 1} cannot start: sub-task(s) "
2251 f"{', '.join(str(item) for item in missing)} did not pass their gate",
2252 "phase.dependencies.unmet",
2253 {
2254 "phaseId": PhaseId.IMPLEMENTATION,
2255 "subtask": current + 1,
2256 "unmetSubtasks": missing,
2257 },
2258 )
2260 def _not_started(
2261 self, execution: Execution, reason: str, event_type: str, payload: dict[str, Any]
2262 ) -> PhaseOutcome:
2263 self.s.events.append(execution.execution_id, event_type, payload)
2264 latest = self.get_execution(execution.execution_id)
2265 self._save_execution(
2266 latest.model_copy(
2267 update={
2268 "status": ResultStatus.BLOCKED,
2269 "terminal_reason": reason,
2270 "updated_at": utc_now(),
2271 }
2272 )
2273 )
2274 return PhaseOutcome(ResultStatus.BLOCKED, reason)
2276 def _check_exit_gates(
2277 self, execution: Execution, phase: PhaseExecution, outcome: PhaseOutcome
2278 ) -> tuple[PhaseOutcome, list[ExitGateCheck]]:
2279 """Evaluate the exit gate of a passed attempt and the condition of the transition it
2280 takes; the first unmet one turns the attempt into ``BLOCKED``."""
2281 checks: list[ExitGateCheck] = []
2282 exit_gate = self.workflow_graph.phase(phase.phase_id).exit_gate
2283 for condition in self.workflow_graph.exit_conditions(phase.phase_id):
2284 check = self.exit_gates.evaluate(condition, execution.execution_id, phase)
2285 checks.append(check)
2286 if check.met:
2287 continue
2288 reason = (
2289 f"{phase.phase_id} did not meet its exit gate {exit_gate} "
2290 f"({check.condition}): {check.reason}"
2291 )
2292 self._exit_gate_unmet = reason
2293 self.s.events.append(
2294 execution.execution_id,
2295 "phase.exit_gate.unmet",
2296 {
2297 "phaseId": phase.phase_id,
2298 "attempt": phase.attempt,
2299 "exitGate": exit_gate,
2300 "condition": check.condition,
2301 "reason": check.reason,
2302 },
2303 phase_execution_id=phase.phase_execution_id,
2304 )
2305 return (
2306 PhaseOutcome(
2307 ResultStatus.BLOCKED, reason, outcome.evidence_refs, outcome.artifact_refs
2308 ),
2309 checks,
2310 )
2311 return outcome, checks
2313 def _parallel_validators(self) -> bool:
2314 """Whether VERIFICATION may run its parallel-safe validators at once: the workflow is
2315 enforced, VERIFICATION is parallelizable and read-only, and ``runtime.maxParallel``
2316 allows more than one."""
2317 return (
2318 self._enforces_workflow
2319 and self.workflow_graph.runs_parallel_work(PhaseId.VERIFICATION)
2320 and self.s.resolved.project.runtime.max_parallel > 1
2321 )
2323 def _record_workflow_schedule(self, execution_id: str) -> None:
2324 """Record once per run what the workflow lets run at once and what stays ordered."""
2325 if any(
2326 event.event_type == "workflow.schedule" for event in self.s.events.list(execution_id)
2327 ):
2328 return
2329 graph = self.workflow_graph
2330 parallel = self._parallel_validators()
2331 batches = validator_batches(self.s.resolved.effective_validators, parallel=parallel)
2332 self.s.events.append(
2333 execution_id,
2334 "workflow.schedule",
2335 {
2336 "order": [item.value for item in graph.order()],
2337 "dependsOn": {
2338 item.value: [dependency.value for dependency in graph.dependencies(item)]
2339 for item in graph.order()
2340 },
2341 "phases": "sequential",
2342 "independentPhaseGroups": [
2343 [item.value for item in group] for group in graph.parallel_groups()
2344 ],
2345 "validatorBatches": [[item.validator_id for item in batch] for batch in batches],
2346 "maxParallel": self.s.resolved.project.runtime.max_parallel if parallel else 1,
2347 "subtasks": "sequential",
2348 "limits": [PHASE_ORDER_REASON, SUBTASK_ORDER_REASON],
2349 },
2350 )
2352 def _validation_context(
2353 self, execution: Execution, change_set: ChangeSet, definition: ValidatorDefinition
2354 ) -> ValidationContext:
2355 actor = Actor(
2356 actor_type=ActorType.TOOL,
2357 actor_id=f"validator.{definition.validator_id}",
2358 version="1",
2359 )
2360 return ValidationContext(
2361 execution_id=execution.execution_id,
2362 workspace=self.s.paths.workspace,
2363 task=self.run_task(execution),
2364 change_set=change_set,
2365 definition=self._bounded_definition(definition),
2366 grants=grants_from_rules(
2367 execution.execution_id, actor, self.s.resolved.effective_capabilities
2368 ),
2369 artifact_store=self.s.artifacts,
2370 process_runner=self._runner(execution),
2371 provenance=self._provenance(execution).model_copy(update={"actor": actor}),
2372 cancellation=CancellationToken(lambda: self.is_cancelled(execution.execution_id)),
2373 max_output_bytes=self.s.resolved.project.runtime.max_output_bytes,
2374 missing_command_status=self._unavailable_status("missingTestCommand"),
2375 missing_script_status=self._unavailable_status("missingTestScript"),
2376 parse_output=self.s.resolved.project.output_parsers_enabled,
2377 )
2379 def _run_profile_validators(
2380 self, execution: Execution, change_set: ChangeSet
2381 ) -> list[ValidatorOutput]:
2382 """Run the effective validators of VERIFICATION and record their results in the
2383 declared order. Without ``governance.enforceWorkflow`` (or with one validator per
2384 batch) they run one at a time as in 1.0.0; under it, consecutive validators declared
2385 ``parallelSafe`` run at once, up to ``runtime.maxParallel`` (#3)."""
2386 outputs: list[ValidatorOutput] = []
2387 batches = validator_batches(
2388 self.s.resolved.effective_validators, parallel=self._parallel_validators()
2389 )
2390 for batch in batches:
2391 if len(batch) == 1:
2392 context = self._validation_context(execution, change_set, batch[0])
2393 results = [self.validators.create(batch[0].validator_id).execute(context)]
2394 else:
2395 results = self._execute_at_once(execution, change_set, batch)
2396 for output in results:
2397 self._save_validator_output(execution, output)
2398 outputs.append(output)
2399 return outputs
2401 def _execute_at_once(
2402 self,
2403 execution: Execution,
2404 change_set: ChangeSet,
2405 batch: tuple[ValidatorDefinition, ...],
2406 ) -> list[ValidatorOutput]:
2407 """Execute a batch of parallel-safe validators at once; the results come back in the
2408 declared order whatever order they finish in, and the first error (in that order) is
2409 raised only after every validator of the batch finished."""
2410 workers = min(self.s.resolved.project.runtime.max_parallel, len(batch))
2411 self.s.events.append(
2412 execution.execution_id,
2413 "verification.validators.parallel",
2414 {"validators": [item.validator_id for item in batch], "maxParallel": workers},
2415 )
2416 contexts = [self._validation_context(execution, change_set, item) for item in batch]
2417 executor = ThreadPoolExecutor(max_workers=workers, thread_name_prefix="harness-validator")
2418 try:
2419 futures = [
2420 executor.submit(self.validators.create(item.validator_id).execute, context)
2421 for item, context in zip(batch, contexts, strict=True)
2422 ]
2423 wait_for_futures(futures)
2424 except BaseException:
2425 # Ctrl-C or SIGTERM under the workspace lease: do not wait for the validators.
2426 executor.shutdown(wait=False, cancel_futures=True)
2427 raise
2428 executor.shutdown(wait=True)
2429 return [future.result() for future in futures]
2431 def _remaining_budget(self) -> float | None:
2432 deadline = self._phase_deadline
2433 if deadline is None:
2434 return None
2435 return max(1.0, deadline - time.monotonic())
2437 def _bounded_timeout(self, seconds: int) -> int:
2438 remaining = self._remaining_budget()
2439 return seconds if remaining is None else max(1, min(seconds, int(remaining)))
2441 def _bounded_definition(self, definition: ValidatorDefinition) -> ValidatorDefinition:
2442 if self._remaining_budget() is None:
2443 return definition
2444 own = definition.timeout_seconds or DEFAULT_VALIDATOR_TIMEOUT_SECONDS
2445 return definition.model_copy(update={"timeout_seconds": self._bounded_timeout(own)})
2447 def _profile_policies_apply(self) -> bool:
2448 return bool(self.s.resolved.project.governance_settings.apply_profile_policies)
2450 def _unavailable_status(self, key: str) -> ResultStatus | None:
2451 """``missingTestCommand`` or ``missingTestScript`` as the status of an unavailable
2452 mandatory validator (``governance.applyProfilePolicies``); ``None`` keeps BLOCKED."""
2453 if not self._profile_policies_apply():
2454 return None
2455 value = self.s.resolved.effective_policies.get(key)
2456 return ResultStatus(str(value)) if value is not None else None
2458 def _coverage_minimum(self) -> float | None:
2459 if not self._profile_policies_apply():
2460 return None
2461 return coverage_minimum(self.s.resolved.effective_policies)
2463 def _verify_coverage(
2464 self, execution: Execution, change_set: ChangeSet, minimum: float
2465 ) -> ValidatorOutput:
2466 validator = CoverageValidator(minimum)
2467 actor = Actor(
2468 actor_type=ActorType.TOOL, actor_id=f"validator.{validator.validator_id}", version="1"
2469 )
2470 data_dir = self.s.paths.harness_dir / "coverage"
2471 data_dir.mkdir(parents=True, exist_ok=True, mode=0o700)
2472 output = validator.execute(
2473 ValidationContext(
2474 execution_id=execution.execution_id,
2475 workspace=self.s.paths.workspace,
2476 task=self.run_task(execution),
2477 change_set=change_set,
2478 definition=self._bounded_definition(validator.definition()),
2479 grants=grants_from_rules(
2480 execution.execution_id, actor, self.s.resolved.effective_capabilities
2481 ),
2482 artifact_store=self.s.artifacts,
2483 process_runner=self._runner(execution),
2484 provenance=self._provenance(execution).model_copy(update={"actor": actor}),
2485 cancellation=CancellationToken(lambda: self.is_cancelled(execution.execution_id)),
2486 max_output_bytes=self.s.resolved.project.runtime.max_output_bytes,
2487 missing_command_status=self._unavailable_status("missingTestCommand"),
2488 missing_script_status=self._unavailable_status("missingTestScript"),
2489 ),
2490 data_file=data_dir / f"{execution.execution_id}.coverage",
2491 )
2492 self._save_validator_output(execution, output)
2493 return output
2495 def _agent_network_allowed(self) -> bool:
2496 """``runtime.allowNetwork`` reaches the agent sandbox under
2497 ``governance.applyNetworkPolicy``; otherwise network access stays allowed (1.0.0)."""
2498 if not self.s.resolved.project.governance_settings.apply_network_policy: 2498 ↛ 2499line 2498 didn't jump to line 2499 because the condition on line 2498 was never true
2499 return True
2500 return self.s.resolved.project.runtime.allow_network
2502 # ----- interruption and recovery (governance.workspaceLease) ----------------------
2503 def _leases_workspace(self) -> bool:
2504 return bool(self.s.resolved.project.governance_settings.workspace_lease)
2506 def _runner(self, execution: Execution) -> SafeProcessRunner:
2507 if not self._leases_workspace():
2508 return SafeProcessRunner(self.s.paths.workspace)
2509 return SafeProcessRunner(
2510 self.s.paths.workspace,
2511 observer=_ProcessLedger(self.s.state, execution.execution_id),
2512 terminate_on_exit=True,
2513 )
2515 def _mark_interrupted(
2516 self, execution_id: str, phase: PhaseExecution, reason: str
2517 ) -> PhaseExecution:
2518 interrupted = phase.model_copy(
2519 update={
2520 "status": ResultStatus.INTERRUPTED,
2521 "finished_at": utc_now(),
2522 "summary": reason,
2523 }
2524 )
2525 latest = self.get_execution(execution_id)
2526 self.s.state.put(
2527 "phase",
2528 interrupted.phase_execution_id,
2529 interrupted,
2530 execution_id=execution_id,
2531 project_id=latest.project_id,
2532 )
2533 self.s.events.append(
2534 execution_id,
2535 "phase.completed",
2536 {
2537 "phaseId": phase.phase_id,
2538 "attempt": phase.attempt,
2539 "status": ResultStatus.INTERRUPTED,
2540 "summary": reason,
2541 "evidenceRefs": [],
2542 },
2543 phase_execution_id=phase.phase_execution_id,
2544 )
2545 self._save_execution(
2546 latest.model_copy(
2547 update={
2548 "status": ResultStatus.INTERRUPTED,
2549 "terminal_reason": reason,
2550 "updated_at": utc_now(),
2551 }
2552 )
2553 )
2554 return interrupted
2556 def recover_interrupted(self, execution_id: str) -> Execution | None:
2557 """Recover a run a harness left behind before its phases run again (under the
2558 workspace lease, no other harness process is executing them):
2560 * a phase still ``RUNNING`` is marked ``INTERRUPTED``;
2561 * the process groups the killed harness started and that still run are terminated;
2562 * the workspace is restored to the state an interrupted IMPLEMENTATION attempt found,
2563 so the change is not implemented twice on top of itself.
2565 Returns the run when it cannot be recovered safely (it is then ``BLOCKED``), ``None``
2566 when the phases may run."""
2567 orphans = [
2568 item
2569 for item in self.s.state.list("phase", PhaseExecution, execution_id=execution_id)
2570 if item.status is ResultStatus.RUNNING
2571 ]
2572 terminated = self._terminate_orphans(execution_id)
2573 for phase in orphans:
2574 self._mark_interrupted(
2575 execution_id, phase, "The harness stopped while the phase was running"
2576 )
2577 interrupted = [
2578 item
2579 for item in self.s.state.list("phase", PhaseExecution, execution_id=execution_id)
2580 if item.status is ResultStatus.INTERRUPTED
2581 and not self.s.state.get_flag(f"recovered:{item.phase_execution_id}")
2582 ]
2583 if not interrupted and not terminated:
2584 return None
2585 restored: list[str] = []
2586 unrestorable: list[str] = []
2587 for phase in interrupted:
2588 if phase.phase_id is PhaseId.IMPLEMENTATION: 2588 ↛ 2592line 2588 didn't jump to line 2592 because the condition on line 2588 was always true
2589 done, failed = self._restore_implementation_start(execution_id, phase)
2590 restored.extend(done)
2591 unrestorable.extend(failed)
2592 self.s.state.set_flag(f"recovered:{phase.phase_execution_id}", "1")
2593 self.s.events.append(
2594 execution_id,
2595 "run.recovered",
2596 {
2597 "interruptedPhases": [
2598 {"phaseExecutionId": item.phase_execution_id, "phaseId": item.phase_id}
2599 for item in interrupted
2600 ],
2601 "terminatedProcessGroups": terminated,
2602 "restoredPaths": restored,
2603 "unrestorablePaths": unrestorable,
2604 },
2605 )
2606 latest = self.get_execution(execution_id)
2607 if unrestorable: 2607 ↛ 2608line 2607 didn't jump to line 2608 because the condition on line 2607 was never true
2608 blocked = latest.model_copy(
2609 update={
2610 "status": ResultStatus.BLOCKED,
2611 "terminal_reason": (
2612 "An interrupted IMPLEMENTATION left files the harness cannot restore: "
2613 + ", ".join(unrestorable[:10])
2614 ),
2615 "updated_at": utc_now(),
2616 }
2617 )
2618 self._save_execution(blocked)
2619 return blocked
2620 if latest.status in {ResultStatus.INTERRUPTED, ResultStatus.RUNNING}: 2620 ↛ 2630line 2620 didn't jump to line 2630 because the condition on line 2620 was always true
2621 self._save_execution(
2622 latest.model_copy(
2623 update={
2624 "status": ResultStatus.PENDING,
2625 "terminal_reason": None,
2626 "updated_at": utc_now(),
2627 }
2628 )
2629 )
2630 return None
2632 def _terminate_orphans(self, execution_id: str) -> list[int]:
2633 key = f"process:{execution_id}"
2634 recorded = json.loads(self.s.state.get_flag(key) or "{}")
2635 host = socket.gethostname()
2636 terminated = [
2637 int(entry["pgid"])
2638 for entry in recorded.values()
2639 if entry.get("host") == host and terminate_process_group(int(entry["pgid"]))
2640 ]
2641 if recorded:
2642 self.s.state.set_flag(key, "{}")
2643 return terminated
2645 def _restore_implementation_start(
2646 self, execution_id: str, phase: PhaseExecution
2647 ) -> tuple[list[str], list[str]]:
2648 raw = self.s.state.get_flag(f"implstart:{execution_id}")
2649 if not raw: 2649 ↛ 2650line 2649 didn't jump to line 2650 because the condition on line 2649 was never true
2650 return [], []
2651 start = json.loads(raw)
2652 if start.get("phaseExecutionId") != phase.phase_execution_id: 2652 ↛ 2653line 2652 didn't jump to line 2653 because the condition on line 2652 was never true
2653 return [], []
2654 stored = self.snapshots.load(start["snapshotRef"])
2655 before = stored.snapshot
2656 diff = self.snapshots.diff(stored, self.snapshots.take())
2657 restored: list[str] = []
2658 unrestorable: list[str] = []
2659 for change in diff.changes:
2660 target = contained_path(self.s.paths.workspace, Path(change.path))
2661 previous = before.files.get(change.path)
2662 content = self.snapshots.content(stored, change.path) if previous else None
2663 if previous is None: 2663 ↛ 2664line 2663 didn't jump to line 2664 because the condition on line 2663 was never true
2664 target.unlink(missing_ok=True)
2665 restored.append(change.path)
2666 elif content is not None: 2666 ↛ 2671line 2666 didn't jump to line 2671 because the condition on line 2666 was always true
2667 target.parent.mkdir(parents=True, exist_ok=True)
2668 target.write_bytes(content)
2669 restored.append(change.path)
2670 else:
2671 unrestorable.append(change.path)
2672 return restored, unrestorable
2674 # ----- excluded paths (governance.protectExcludedPaths) ---------------------------
2675 def _protects_excluded_paths(self) -> bool:
2676 return bool(self.s.resolved.project.governance_settings.protect_excluded_paths)
2678 def _protected_paths(self, execution: Execution | None = None) -> tuple[Path, ...]:
2679 """Paths the agent sandbox keeps read-only: the harness state and Git of the workspace
2680 (``governance.protectExcludedPaths``), the run registry when it lives outside the
2681 workspace (``runtime.stateDir``, #55) and, for a run with frozen acceptance tests,
2682 those files (``verification.acceptanceTests.protect``, #94)."""
2683 external = (self.s.paths.state_root,) if self.s.paths.state_root is not None else ()
2684 if execution is not None and self.results.active:
2685 external = (*external, *self.results.acceptance.protected_paths(execution))
2686 if not self._protects_excluded_paths(): 2686 ↛ 2687line 2686 didn't jump to line 2687 because the condition on line 2686 was never true
2687 return external
2688 return (self.s.paths.harness_dir, self.s.paths.workspace / ".git", *external)
2690 def _check_excluded_paths(
2691 self,
2692 execution: Execution,
2693 phase: PhaseExecution,
2694 guard: ExcludedPathGuard,
2695 before: dict[str, str],
2696 ) -> None:
2697 """Compare the fingerprints of what the ChangeSet excludes before and after the agent
2698 ran. The comparison is IMPLEMENTATION evidence; a change is a CRITICAL finding that the
2699 gate of every later ChangeSet of the run receives."""
2700 after = guard.fingerprint()
2701 changes = guard.compare(before, after)
2702 record = {
2703 "guardedDirectories": sorted(guard.guarded),
2704 "ignoredPatterns": list(IGNORED_PATTERNS),
2705 "before": {"files": len(before), "digest": sha256_json(before)},
2706 "after": {"files": len(after), "digest": sha256_json(after)},
2707 "changes": [{"path": item.path, "status": item.status} for item in changes],
2708 }
2709 ref = self.s.artifacts.put_json(
2710 record,
2711 metadata={"kind": "excluded-path-fingerprint", "executionId": execution.execution_id},
2712 )
2713 evidence = self._record_evidence(
2714 execution,
2715 phase.phase_id,
2716 EvidenceKind.CONFIGURATION,
2717 ref,
2718 f"Paths outside the ChangeSet: {len(after)} fingerprinted, {len(changes)} changed",
2719 )
2720 if not changes:
2721 return
2722 shown = ", ".join(f"{item.path} ({item.status})" for item in changes[:10])
2723 more = f" and {len(changes) - 10} more" if len(changes) > 10 else ""
2724 finding = Finding(
2725 finding_id=new_id("finding"),
2726 execution_id=execution.execution_id,
2727 validator_id=WORKSPACE_GUARD_ID,
2728 rule_id=OUT_OF_CHANGESET_RULE,
2729 category="workspace-integrity",
2730 severity=FindingSeverity.CRITICAL,
2731 message=(
2732 f"The agent changed {len(changes)} path(s) the ChangeSet does not show: "
2733 f"{shown}{more}"
2734 ),
2735 location=FindingLocation(path=changes[0].path),
2736 evidence_refs=(evidence.artifact_ref,),
2737 recommendation=(
2738 "Inspect these paths (a Git hook runs on the next commit; a changed dependency "
2739 "changes what the tests run) and restore them before deciding; only approve an "
2740 "exception for a change you made on purpose."
2741 ),
2742 provenance=self._provenance(execution),
2743 )
2744 self.s.state.put(
2745 "finding",
2746 finding.finding_id,
2747 finding,
2748 execution_id=execution.execution_id,
2749 project_id=execution.project_id,
2750 )
2751 self.s.events.append(
2752 execution.execution_id,
2753 _FINDING_RECORDED,
2754 finding.model_dump(mode="json"),
2755 actor=finding.provenance.actor,
2756 )
2757 key = f"guard:{execution.execution_id}"
2758 recorded = json.loads(self.s.state.get_flag(key) or "[]")
2759 self.s.state.set_flag(key, json.dumps([*recorded, finding.finding_id]))
2761 def _workspace_guard_validation(self, execution: Execution, digest: str) -> None:
2762 """A failed mandatory validation for the ChangeSet the gate evaluates, carrying every
2763 out-of-ChangeSet write of the run, so the gate fails until a person decides."""
2764 finding_ids = tuple(
2765 json.loads(self.s.state.get_flag(f"guard:{execution.execution_id}") or "[]")
2766 )
2767 if not finding_ids:
2768 return
2769 if any( 2769 ↛ 2773line 2769 didn't jump to line 2773 because the condition on line 2769 was never true
2770 item.validator_id == WORKSPACE_GUARD_ID and item.finding_ids == finding_ids
2771 for item in self._latest_validations(execution.execution_id, digest)
2772 ):
2773 return
2774 findings = [self.s.state.get("finding", item, Finding) for item in finding_ids]
2775 now = utc_now()
2776 result = ValidationResult(
2777 validation_result_id=new_id("validation"),
2778 execution_id=execution.execution_id,
2779 validator_id=WORKSPACE_GUARD_ID,
2780 change_set_digest=digest,
2781 status=ResultStatus.FAILED,
2782 kind=ValidationKind.POLICY_VIOLATION,
2783 mandatory=True,
2784 summary=f"{len(finding_ids)} agent invocation(s) wrote outside the ChangeSet",
2785 finding_ids=finding_ids,
2786 evidence_refs=tuple(ref for item in findings for ref in item.evidence_refs),
2787 started_at=now,
2788 finished_at=now,
2789 provenance=self._provenance(execution),
2790 )
2791 self.s.state.put(
2792 "validation",
2793 result.validation_result_id,
2794 result,
2795 execution_id=execution.execution_id,
2796 project_id=execution.project_id,
2797 )
2798 self.s.events.append(
2799 execution.execution_id,
2800 "validation.completed",
2801 result.model_dump(mode="json"),
2802 actor=result.provenance.actor,
2803 )
2805 def _record_sandbox_evidence(
2806 self, execution: Execution, phase: PhaseExecution, sandbox: SandboxPlan
2807 ) -> str:
2808 """Record the confinement the provider runs under: mechanism, profile and its digest,
2809 and the resolved write paths (IMPLEMENTATION evidence and an ``agent.sandbox.applied``
2810 event)."""
2811 record = sandbox.evidence()
2812 ref = self.s.artifacts.put_json(
2813 record, metadata={"kind": "agent-sandbox", "executionId": execution.execution_id}
2814 )
2815 evidence = self._record_evidence(
2816 execution,
2817 phase.phase_id,
2818 EvidenceKind.CONFIGURATION,
2819 ref,
2820 f"Agent sandbox: {sandbox.mechanism}, {len(sandbox.allowed_paths)} writable path(s)",
2821 )
2822 self.s.events.append(
2823 execution.execution_id,
2824 "agent.sandbox.applied",
2825 {
2826 "mechanism": sandbox.mechanism,
2827 "profileDigest": sandbox.profile_digest,
2828 "allowedPaths": [item.path for item in sandbox.allowed_paths],
2829 "evidenceRef": evidence.artifact_ref,
2830 },
2831 phase_execution_id=phase.phase_execution_id,
2832 )
2833 return evidence.artifact_ref
2835 def _record_provider_environment(
2836 self,
2837 execution: Execution,
2838 phase: PhaseExecution,
2839 provider_id: str,
2840 environment: ProviderEnvironment,
2841 ) -> str:
2842 """The names (never the values) of the variables the provider receives."""
2843 record = {"provider": provider_id, **environment.evidence()}
2844 ref = self.s.artifacts.put_json(
2845 record, metadata={"kind": "provider-environment", "executionId": execution.execution_id}
2846 )
2847 evidence = self._record_evidence(
2848 execution,
2849 phase.phase_id,
2850 EvidenceKind.CONFIGURATION,
2851 ref,
2852 f"Provider environment: {len(environment.passed)} passed, "
2853 f"{len(environment.values)} set",
2854 )
2855 self.s.events.append(
2856 execution.execution_id,
2857 "agent.environment.applied",
2858 record,
2859 phase_execution_id=phase.phase_execution_id,
2860 )
2861 return evidence.artifact_ref
2863 def _record_denied_writes(
2864 self, execution: Execution, tools: tuple[ToolInvocation, ...]
2865 ) -> None:
2866 """A provider that failed under the sandbox and reports a denied write on standard
2867 error gets a ``sandbox.write-denied`` finding naming the path when it can be read."""
2868 for tool in tools:
2869 if not tool.stderr_ref: 2869 ↛ 2870line 2869 didn't jump to line 2870 because the condition on line 2869 was never true
2870 continue
2871 found, paths = denied_writes(self.s.artifacts.get(tool.stderr_ref))
2872 if not found: 2872 ↛ 2874line 2872 didn't jump to line 2874 because the condition on line 2872 was always true
2873 continue
2874 named = ", ".join(paths) if paths else "a path not named in the output"
2875 self._record_sandbox_finding(
2876 execution,
2877 rule_id="sandbox.write-denied",
2878 severity=FindingSeverity.MEDIUM,
2879 message=f"The agent sandbox denied a write: {named}",
2880 recommendation=(
2881 "If the agent needs this path, add it to runtime.sandboxWritePaths; "
2882 "otherwise keep the agent's changes inside the workspace."
2883 ),
2884 path=paths[0] if paths else None,
2885 evidence_refs=(tool.stderr_ref,),
2886 )
2888 def _record_sandbox_finding(
2889 self,
2890 execution: Execution,
2891 *,
2892 rule_id: str,
2893 severity: FindingSeverity,
2894 message: str,
2895 recommendation: str,
2896 path: str | None = None,
2897 evidence_refs: tuple[str, ...] = (),
2898 ) -> None:
2899 finding = Finding(
2900 finding_id=new_id("finding"),
2901 execution_id=execution.execution_id,
2902 validator_id="harness.sandbox",
2903 rule_id=rule_id,
2904 category="agent-sandbox",
2905 severity=severity,
2906 message=message,
2907 location=FindingLocation(path=path) if path else None,
2908 evidence_refs=evidence_refs,
2909 recommendation=recommendation,
2910 provenance=self._provenance(execution),
2911 )
2912 self.s.state.put(
2913 "finding",
2914 finding.finding_id,
2915 finding,
2916 execution_id=execution.execution_id,
2917 project_id=execution.project_id,
2918 )
2919 self.s.events.append(
2920 execution.execution_id,
2921 _FINDING_RECORDED,
2922 finding.model_dump(mode="json"),
2923 actor=finding.provenance.actor,
2924 )
2926 def _phase_verification(self, execution: Execution, phase: PhaseExecution) -> PhaseOutcome:
2927 change_set = self._refresh_changeset(execution)
2928 if not change_set.files: 2928 ↛ 2929line 2928 didn't jump to line 2929 because the condition on line 2928 was never true
2929 return PhaseOutcome(ResultStatus.FAILED, "Current ChangeSet is empty")
2930 waiting = self.results.disputes.waiting(execution, change_set)
2931 if waiting is not None:
2932 # acceptanceTests.disputes (#94): a person has not decided the dispute yet.
2933 return waiting
2934 if self.friction.active:
2935 # friction (#58): risk factors, size and change type of the ChangeSet; a fast run
2936 # with a risk factor or a ChangeSet larger than S leaves the fast lane here.
2937 self.friction.profile(execution, change_set)
2938 outputs: list[Any]
2939 if self.friction.active and self.friction.fast_verification_applies(execution):
2940 outputs = self._fast_validators(execution, change_set)
2941 stopped = _affected_tests_failed(outputs)
2942 if stopped is not None:
2943 return stopped
2944 else:
2945 outputs = list(self._run_profile_validators(execution, change_set))
2946 coverage = self._coverage_minimum()
2947 if coverage is not None:
2948 outputs.append(self._verify_coverage(execution, change_set, coverage))
2949 traceability = self._traceability_output(execution, phase, change_set)
2950 if traceability is not None:
2951 outputs.append(traceability)
2952 if self.results.active:
2953 # Deterministic checks of the agent-results settings, then the comparison of
2954 # failing validators with the baseline (verification.differential, #7).
2955 outputs.extend(self.results.verification.run(execution, change_set))
2956 outputs = self.results.after_verification(execution, change_set, outputs)
2957 if self.ladder.active:
2958 # Probes, light mutation and the certification of the ChangeSet (#55).
2959 outputs.extend(self.ladder.verification(execution, change_set, outputs))
2960 return self._verification_outcome(execution, change_set, outputs)
2962 def _verification_outcome(
2963 self, execution: Execution, change_set: ChangeSet, outputs: list[Any]
2964 ) -> PhaseOutcome:
2965 """The result of VERIFICATION from its validators: passed, or the worst status of the
2966 mandatory ones that did not pass. When only the frozen acceptance tests failed and the
2967 agent disputed them, the run waits for a person instead
2968 (``acceptanceTests.disputes``, #94)."""
2969 mandatory_non_passed = [
2970 output.result
2971 for output in outputs
2972 if output.result.mandatory and output.result.status is not ResultStatus.PASSED
2973 ]
2974 evidence = tuple(ref for output in outputs for ref in output.result.evidence_refs)
2975 if not mandatory_non_passed:
2976 return PhaseOutcome(
2977 ResultStatus.PASSED, f"Executed {len(outputs)} validator(s)", evidence
2978 )
2979 disputed = self.results.disputes.open(execution, change_set, mandatory_non_passed)
2980 if disputed is not None:
2981 return disputed
2982 status = self._worst_status([item.status for item in mandatory_non_passed])
2983 return PhaseOutcome(
2984 status,
2985 f"{len(mandatory_non_passed)} mandatory validator(s) did not pass",
2986 evidence,
2987 )
2989 def _fast_validators(self, execution: Execution, change_set: ChangeSet) -> list[Any]:
2990 """fastLane.verification (#58): affected tests first, side by side, reused by digest.
2991 The frozen acceptance tests a dispute can cover are not among the affected tests
2992 (#161)."""
2993 return self.friction.run_validators(
2994 execution,
2995 change_set,
2996 list(self.s.resolved.effective_validators),
2997 lambda definition: partial(
2998 self.validators.create(definition.validator_id).execute,
2999 self._validation_context(execution, change_set, definition),
3000 ),
3001 lambda output: self._save_validator_output(execution, output),
3002 exclude=self.results.disputes.disputable(execution),
3003 )
3005 def _traceability_output(
3006 self, execution: Execution, phase: PhaseExecution, change_set: ChangeSet
3007 ) -> ValidatorOutput | None:
3008 """The requirement traceability of the ChangeSet, unless the policy is off; under
3009 friction.changeTypes (#58) a documentation or configuration change records it as not
3010 applicable."""
3011 policy = self.s.resolved.project.requirement_traceability
3012 if policy == "off":
3013 return None
3014 exempt = (
3015 self.friction.tests_exempt(execution, change_set, "requirement traceability")
3016 if self.friction.active
3017 else None
3018 )
3019 if exempt is None:
3020 return self._verify_requirement_traceability(execution, phase, change_set, policy)
3021 skipped = self.friction.not_applicable(
3022 execution, change_set, TRACEABILITY_VALIDATOR_ID, exempt
3023 )
3024 self._save_validator_output(execution, skipped)
3025 return skipped
3027 def _verify_requirement_traceability(
3028 self,
3029 execution: Execution,
3030 phase: PhaseExecution,
3031 change_set: ChangeSet,
3032 policy: Literal["enforce", "warn"],
3033 ) -> TraceabilityOutput:
3034 """Relate the task's identified requirements to the tests of the workspace; the mapping
3035 is recorded as VERIFICATION evidence and each untraced requirement as a finding."""
3036 task = self.run_task(execution)
3037 if self.results.active:
3038 # Under decomposition, the requirements of the sub-tasks implemented so far.
3039 task = self.results.decomposition.verification_task(execution, task)
3040 validator = RequirementTraceabilityValidator(
3041 policy, (profile.technology for profile in self.s.resolved.profiles)
3042 )
3043 actor = Actor(
3044 actor_type=ActorType.TOOL, actor_id=f"validator.{validator.validator_id}", version="1"
3045 )
3046 output = validator.execute(
3047 ValidationContext(
3048 execution_id=execution.execution_id,
3049 workspace=self.s.paths.workspace,
3050 task=task,
3051 change_set=change_set,
3052 definition=ValidatorDefinition(
3053 id=validator.validator_id, mandatory=policy == "enforce"
3054 ),
3055 grants=grants_from_rules(
3056 execution.execution_id, actor, self.s.resolved.effective_capabilities
3057 ),
3058 artifact_store=self.s.artifacts,
3059 process_runner=self._runner(execution),
3060 provenance=self._provenance(execution).model_copy(update={"actor": actor}),
3061 cancellation=CancellationToken(lambda: self.is_cancelled(execution.execution_id)),
3062 max_output_bytes=self.s.resolved.project.runtime.max_output_bytes,
3063 )
3064 )
3065 if output.report is not None and output.report_ref is not None: 3065 ↛ 3074line 3065 didn't jump to line 3074 because the condition on line 3065 was always true
3066 self._record_evidence(
3067 execution,
3068 phase.phase_id,
3069 EvidenceKind.TEST_REPORT,
3070 output.report_ref,
3071 f"Requirement traceability: {output.result.summary}",
3072 supports=tuple(item.requirement_id for item in output.report.requirements),
3073 )
3074 self._save_validator_output(execution, output)
3075 return output
3077 def _phase_independent_review(
3078 self, execution: Execution, phase: PhaseExecution
3079 ) -> PhaseOutcome:
3080 change_set = self.current_change_set(execution.execution_id)
3081 actor = Actor(
3082 actor_type=ActorType.TOOL, actor_id="validator.independent-review", version="1"
3083 )
3084 definition = ValidatorDefinition(id="review.independent", mandatory=True)
3085 grants = grants_from_rules(
3086 execution.execution_id, actor, self.s.resolved.effective_capabilities
3087 )
3088 skip = (
3089 frozenset({"review.possible-secret"})
3090 if self.results.active and self.results.secrets_in_context
3091 else frozenset()
3092 )
3093 output = IndependentReviewValidator(skip).execute(
3094 ValidationContext(
3095 execution_id=execution.execution_id,
3096 workspace=self.s.paths.workspace,
3097 task=self.run_task(execution),
3098 change_set=change_set,
3099 definition=definition,
3100 grants=grants,
3101 artifact_store=self.s.artifacts,
3102 process_runner=self._runner(execution),
3103 provenance=self._provenance(execution).model_copy(update={"actor": actor}),
3104 cancellation=CancellationToken(lambda: self.is_cancelled(execution.execution_id)),
3105 max_output_bytes=self.s.resolved.project.runtime.max_output_bytes,
3106 raw_diff=self._compute_owned_diff(execution).unified_diff.decode(
3107 "utf-8", "replace"
3108 ),
3109 )
3110 )
3111 self._save_validator_output(execution, output)
3112 if self.results.active and (
3113 not self.friction.active or self.friction.agent_review_wanted(execution, change_set)
3114 ):
3115 # review.agentReview (#38): a second reviewer after the deterministic checks; in
3116 # the fast lane of #58 only on a signal.
3117 review = self.results.agent_review.run(execution, phase, change_set)
3118 if review.blocking and self.results.review_correction_available(execution):
3119 return PhaseOutcome(
3120 ResultStatus.FAILED,
3121 f"The agent review found {len(review.blocking)} blocking finding(s)",
3122 output.result.evidence_refs,
3123 )
3124 return PhaseOutcome(
3125 ResultStatus.PASSED,
3126 output.result.summary,
3127 output.result.evidence_refs,
3128 )
3130 def _phase_decision(self, execution: Execution, phase: PhaseExecution) -> PhaseOutcome:
3131 previous_digest = execution.change_set_digest
3132 change_set = self._refresh_changeset(execution)
3133 execution = self.get_execution(execution.execution_id)
3134 # A later change to an owned path invalidates previous gate/approval.
3135 if previous_digest and previous_digest != change_set.digest:
3136 execution = self._invalidate_approval(execution, previous_digest, change_set)
3137 current_decision = (
3138 self.s.state.get("decision", execution.human_decision_id, HumanDecision)
3139 if execution.human_decision_id
3140 else None
3141 )
3142 gate = self._current_or_evaluate_gate(execution, change_set)
3143 self.provenance.attribute(execution, change_set, PhaseId.DECISION)
3144 execution = self.get_execution(execution.execution_id)
3145 if current_decision:
3146 decided = self._decided_outcome(execution, current_decision, change_set)
3147 if decided is not None: 3147 ↛ 3160line 3147 didn't jump to line 3160 because the condition on line 3147 was always true
3148 return decided
3149 elif self.friction.active:
3150 # friction.preAuthorization (#58): the approval a person gave in advance, applied
3151 # only when its condition holds; otherwise the person is asked as usual.
3152 applied = self.friction.apply_pre_authorization(execution, gate, change_set)
3153 if applied is not None:
3154 return PhaseOutcome(
3155 ResultStatus.PASSED,
3156 f"Pre-authorised approval {applied.pre_authorization_id} by "
3157 f"{applied.actor.actor_id} applied: gate passed, no risk factor, size S",
3158 (f"record://decision/{applied.decision_id}",),
3159 )
3160 return PhaseOutcome(
3161 ResultStatus.BLOCKED,
3162 f"Human decision required for gate {gate.gate_evaluation_id} and digest {change_set.digest}",
3163 (f"record://gate/{gate.gate_evaluation_id}",),
3164 )
3166 def _invalidate_approval(
3167 self, execution: Execution, previous_digest: str, change_set: ChangeSet
3168 ) -> Execution:
3169 """Drop the gate and the approval of a run whose ChangeSet changed, and record it."""
3170 execution = execution.model_copy(
3171 update={
3172 "gate_evaluation_id": None,
3173 "human_decision_id": None,
3174 "updated_at": utc_now(),
3175 }
3176 )
3177 self._save_execution(execution)
3178 self.s.events.append(
3179 execution.execution_id,
3180 "approval.invalidated",
3181 {
3182 "previousDigest": previous_digest,
3183 "currentDigest": change_set.digest,
3184 },
3185 )
3186 return execution
3188 def _decided_outcome(
3189 self, execution: Execution, current_decision: HumanDecision, change_set: ChangeSet
3190 ) -> PhaseOutcome | None:
3191 """The outcome of DECISION under the run's human decision; ``None`` when the decision
3192 neither applies nor ends the run, so a person is asked again."""
3193 stale = self._stale_decision(execution, current_decision, change_set)
3194 if stale is not None:
3195 return stale
3196 if current_decision.decision in {DecisionKind.APPROVE, DecisionKind.APPROVE_EXCEPTION}: 3196 ↛ 3202line 3196 didn't jump to line 3202 because the condition on line 3196 was always true
3197 return PhaseOutcome(
3198 ResultStatus.PASSED,
3199 f"Human decision {current_decision.decision} is bound to the current ChangeSet",
3200 (f"record://decision/{current_decision.decision_id}",),
3201 )
3202 if current_decision.decision is DecisionKind.REJECT:
3203 return PhaseOutcome(ResultStatus.FAILED, "Execution rejected by human decision")
3204 return None
3206 def _stale_decision(
3207 self, execution: Execution, current_decision: HumanDecision, change_set: ChangeSet
3208 ) -> PhaseOutcome | None:
3209 """A BLOCKED outcome when the human decision no longer holds: bound to another
3210 ChangeSet or acceptance contract, or expired."""
3211 if current_decision.change_set_digest != change_set.digest:
3212 return PhaseOutcome(
3213 ResultStatus.BLOCKED, "Human decision is stale after ChangeSet modification"
3214 )
3215 if current_decision.acceptance_contract_digest is not None:
3216 try:
3217 contract = self._current_contract_digest(execution)
3218 except PolicyViolationError as error:
3219 return PhaseOutcome(ResultStatus.BLOCKED, str(error))
3220 if contract != current_decision.acceptance_contract_digest: 3220 ↛ 3221line 3220 didn't jump to line 3221 because the condition on line 3220 was never true
3221 return PhaseOutcome(
3222 ResultStatus.BLOCKED,
3223 "Human decision is stale: it is bound to another acceptance contract",
3224 )
3225 if (
3226 current_decision.expires_at is not None
3227 and current_decision.expires_at <= utc_now()
3228 and current_decision.decision is not DecisionKind.REJECT
3229 ):
3230 # The expiry of an exception (review.exceptions) or of any decision
3231 # (governance.decisionExpiryHours): a new decision is required.
3232 kind = (
3233 "Exception"
3234 if current_decision.decision is DecisionKind.APPROVE_EXCEPTION
3235 else "Human decision"
3236 )
3237 return PhaseOutcome(
3238 ResultStatus.BLOCKED,
3239 f"{kind} {current_decision.decision_id} expired at "
3240 f"{current_decision.expires_at.isoformat()}; a new decision is required",
3241 )
3242 return None
3244 def _reverify_after_change(self, execution: Execution) -> bool:
3245 """Under ``verification.reverifyOnChange`` (#78): a run in DECISION whose ChangeSet
3246 changed outside the run (an edit after its gate was evaluated) goes back to
3247 VERIFICATION on the new ChangeSet instead of evaluating a gate that has no validation
3248 of it (INCONCLUSIVE). The change is recorded as evidence first: both digests, the
3249 paths that differ and the new diff. Without the key the run stays in DECISION as
3250 before. Returns whether the run was sent back."""
3251 verification = self.s.resolved.project.verification
3252 if verification is None or not verification.reverify_on_change:
3253 return False
3254 previous = execution.change_set_digest
3255 if not previous: 3255 ↛ 3256line 3255 didn't jump to line 3256 because the condition on line 3255 was never true
3256 return False
3257 change_set = self._refresh_changeset(execution)
3258 if change_set.digest == previous:
3259 return False
3260 latest = self.get_execution(execution.execution_id)
3261 self.provenance.attribute(latest, change_set, PhaseId.DECISION)
3262 paths = self._paths_between(execution.execution_id, previous, change_set)
3263 ref = self.results.record_json(
3264 latest,
3265 PhaseId.DECISION,
3266 {
3267 "previousDigest": previous,
3268 "currentDigest": change_set.digest,
3269 "paths": paths,
3270 "diffRef": change_set.diff_ref,
3271 },
3272 kind="out-of-band-change",
3273 evidence_kind=EvidenceKind.CHANGESET,
3274 summary=f"ChangeSet changed outside the run: {len(paths)} path(s)",
3275 supports=(change_set.change_set_id,),
3276 )
3277 transition = self.state_machine.authorize_reverification(PhaseId.DECISION)
3278 self._save_execution(
3279 latest.model_copy(
3280 update={
3281 "status": ResultStatus.PENDING,
3282 "current_phase": transition.target,
3283 "gate_evaluation_id": None,
3284 "human_decision_id": None,
3285 "terminal_reason": None,
3286 "updated_at": utc_now(),
3287 }
3288 )
3289 )
3290 self.s.events.append(
3291 execution.execution_id,
3292 "verification.reverify.authorized",
3293 {
3294 "previousDigest": previous,
3295 "currentDigest": change_set.digest,
3296 "paths": paths,
3297 "evidenceRef": ref,
3298 "invalidatedPhases": [phase.value for phase in transition.invalidated],
3299 },
3300 )
3301 return True
3303 def _paths_between(self, execution_id: str, previous: str, change_set: ChangeSet) -> list[str]:
3304 """The paths whose content differs between the run's ChangeSet ``previous`` and
3305 ``change_set``."""
3306 records = self.s.state.list("change_set", ChangeSet, execution_id=execution_id)
3307 earlier = next((item for item in records if item.digest == previous), None)
3308 before = {item.path: item.after_digest for item in (earlier.files if earlier else ())}
3309 after = {item.path: item.after_digest for item in change_set.files}
3310 return sorted(
3311 path for path in before.keys() | after.keys() if before.get(path) != after.get(path)
3312 )
3314 def _phase_closure(self, execution: Execution, phase: PhaseExecution) -> PhaseOutcome:
3315 execution = self.get_execution(execution.execution_id)
3316 if not execution.human_decision_id or not execution.change_set_digest: 3316 ↛ 3317line 3316 didn't jump to line 3317 because the condition on line 3316 was never true
3317 return PhaseOutcome(ResultStatus.BLOCKED, "Closure requires a current human decision")
3318 decision = self.s.state.get("decision", execution.human_decision_id, HumanDecision)
3319 if not self.state_machine.approval_is_current( 3319 ↛ 3322line 3319 didn't jump to line 3322 because the condition on line 3319 was never true
3320 decision.change_set_digest, execution.change_set_digest
3321 ):
3322 return PhaseOutcome(ResultStatus.BLOCKED, "Approval does not match current ChangeSet")
3323 delivered = self._deliver(execution, phase, decision)
3324 if delivered is not None:
3325 return delivered
3326 self.s.events.verify_chain(execution.execution_id)
3327 trace = self.s.events.export_jsonl(execution.execution_id)
3328 trace_ref = self.s.artifacts.put(
3329 trace,
3330 media_type="application/x-ndjson",
3331 metadata={"kind": "execution-trace", "executionId": execution.execution_id},
3332 )
3333 evidence = self._record_evidence(
3334 execution,
3335 phase.phase_id,
3336 EvidenceKind.TRACE,
3337 trace_ref,
3338 "Immutable event-chain trace",
3339 )
3340 # Emit closure before computing the retrospective so metrics include the complete primary workflow.
3341 self.s.events.append(
3342 execution.execution_id,
3343 "run.closed",
3344 {"status": "PASSED", "changeSetDigest": execution.change_set_digest},
3345 )
3346 metrics = MetricsProjector(self.s.state).project(
3347 execution.execution_id, self.s.events.list(execution.execution_id)
3348 )
3349 metrics_ref = self.s.artifacts.put_json(
3350 {key: value.as_dict() for key, value in metrics.items()},
3351 metadata={"kind": "metrics", "executionId": execution.execution_id},
3352 )
3353 retrospective = self.retrospective_engine.generate(
3354 execution_id=execution.execution_id,
3355 metrics=metrics,
3356 evidence_refs=(trace_ref.uri, metrics_ref.uri),
3357 provenance=self._provenance(execution),
3358 analysis=self.cause_analysis(execution),
3359 trigger="CLOSED" if self.s.resolved.project.causal_retrospective else None,
3360 )
3361 self.s.state.put(
3362 "retrospective",
3363 retrospective.retrospective_id,
3364 retrospective,
3365 execution_id=execution.execution_id,
3366 project_id=execution.project_id,
3367 )
3368 retrospective_ref = self.s.artifacts.put_json(
3369 retrospective.model_dump(mode="json"),
3370 metadata={"kind": "retrospective", "executionId": execution.execution_id},
3371 )
3372 self._record_evidence(
3373 execution,
3374 PhaseId.RETROSPECTIVE,
3375 EvidenceKind.RETROSPECTIVE,
3376 retrospective_ref,
3377 "Evidence-based recommendations requiring human review",
3378 )
3379 self.s.events.append(
3380 execution.execution_id,
3381 "retrospective.generated",
3382 {
3383 "retrospectiveId": retrospective.retrospective_id,
3384 "recommendationCount": len(retrospective.recommendations),
3385 "appliedAutomatically": False,
3386 },
3387 )
3388 return PhaseOutcome(
3389 ResultStatus.PASSED,
3390 "Execution closed with verified trace and non-mutating retrospective",
3391 (evidence.artifact_ref, metrics_ref.uri, retrospective_ref.uri),
3392 )
3394 def _deliver(
3395 self, execution: Execution, phase: PhaseExecution, decision: HumanDecision
3396 ) -> PhaseOutcome | None:
3397 """``delivery.closureCommit``: write the approved ChangeSet as a commit with trailers.
3398 ``None`` lets CLOSURE go on; an outcome stops it."""
3399 delivery = self.s.resolved.project.delivery_settings
3400 change_set = self.current_change_set(execution.execution_id)
3401 if delivery.mode == "off":
3402 if self.ladder.active: 3402 ↛ 3404line 3402 didn't jump to line 3404 because the condition on line 3402 was never true
3403 # Stage the run's files when nothing is committed (delivery.stage, #55).
3404 skipped = ClosureCommit(mode="off", status="SKIPPED", reason="closureCommit off")
3405 return self.ladder.delivery.deliver(execution, phase, decision, skipped, change_set)
3406 return None
3407 task = self.run_task(execution)
3408 if isolation_marker(self.s.paths.workspace) is not None:
3409 # An isolated run (#55) commits on its own worktree's branch.
3410 delivery = delivery.model_copy(update={"closure_commit": "head"})
3411 elif self.ladder.active and task.contract is not None and task.contract.branch:
3412 # The branch the operational contract names (#55).
3413 delivery = delivery.model_copy(update={"branch": task.contract.branch})
3414 try:
3415 commit = create_closure_commit(
3416 self.s.paths.workspace,
3417 delivery,
3418 execution_id=execution.execution_id,
3419 task=self.run_task(execution),
3420 change_set=change_set,
3421 decision=decision,
3422 )
3423 except VcsError as error:
3424 self.s.events.append(
3425 execution.execution_id,
3426 "delivery.commit.failed",
3427 {"mode": delivery.mode, "reason": str(error)},
3428 phase_execution_id=phase.phase_execution_id,
3429 )
3430 return PhaseOutcome(ResultStatus.BLOCKED, f"Closure commit not created: {error}")
3431 record = self._closure_record(commit, change_set)
3432 ref = self.s.artifacts.put_json(
3433 record, metadata={"kind": "closure-commit", "executionId": execution.execution_id}
3434 )
3435 if commit.commit:
3436 where = f" on branch {commit.branch}" if commit.branch else " on the current branch"
3437 summary = f"Closure commit {commit.commit[:12]} ({commit.status.lower()})" + where
3438 else:
3439 summary = f"Closure commit skipped: {commit.reason}"
3440 self._record_evidence(
3441 execution,
3442 phase.phase_id,
3443 EvidenceKind.OTHER,
3444 ref,
3445 summary,
3446 supports=(change_set.change_set_id, decision.decision_id),
3447 )
3448 self.s.events.append(
3449 execution.execution_id,
3450 "delivery.commit.skipped" if commit.status == "SKIPPED" else "delivery.commit.created",
3451 record,
3452 phase_execution_id=phase.phase_execution_id,
3453 )
3454 if self.ladder.active:
3455 # Deferred verifications are bound to the commit; push, pull request, comment or
3456 # staging follow the operational contract (#55).
3457 if commit.commit: 3457 ↛ 3459line 3457 didn't jump to line 3459 because the condition on line 3457 was always true
3458 self.ladder.bind_commit(execution, change_set.digest, commit.commit)
3459 return self.ladder.delivery.deliver(execution, phase, decision, commit, change_set)
3460 return None
3462 def _closure_record(self, commit: ClosureCommit, change_set: ChangeSet) -> dict[str, Any]:
3463 """The closure commit as recorded. The author and the subject come from the repository:
3464 they pass the same redaction of secrets as any recorded text (a name or a subject can
3465 carry a token)."""
3466 record = commit.as_dict() | {"changeSetDigest": change_set.digest}
3467 if commit.author:
3468 record, _ = self.s.artifacts.redactor.redact_json(record)
3469 return record
3471 # ----- correction loop --------------------------------------------------------
3472 def _external_provider(self, execution_id: str) -> bool:
3473 """Whether the run uses a configured command provider. The simulated provider is
3474 deterministic and reads no feedback: the correction loop does not apply to it. Nor does
3475 it to the embedded ``session`` provider (#56): the session reads the findings and edits
3476 before it continues the run."""
3477 provider = self.s.state.get_flag(f"provider:{execution_id}") or "simulated"
3478 return provider not in {"simulated", SESSION_PROVIDER}
3480 def _feedback_applies(self, execution_id: str) -> bool:
3481 return self.s.resolved.project.runtime.feedback_enabled and self._external_provider(
3482 execution_id
3483 )
3485 def _after_failed_verification(self, execution: Execution, outcome: PhaseOutcome) -> bool:
3486 """Record what a failed VERIFICATION says about the agent's claim and, while the
3487 ``runtime.verificationCorrections`` budget lasts, send the run back to IMPLEMENTATION.
3489 Only a ``FAILED`` verification with failing mandatory validators qualifies: a blocked,
3490 timed-out or erroring validator is not something the agent can correct. Returns whether
3491 a correction cycle was authorized; otherwise the run stops as it did before."""
3492 runtime = self.s.resolved.project.runtime
3493 if (
3494 outcome.status is not ResultStatus.FAILED
3495 or not execution.change_set_digest
3496 or not self._external_provider(execution.execution_id)
3497 ):
3498 return False
3499 validations = self._latest_validations(execution.execution_id, execution.change_set_digest)
3500 failing = failing_validations(validations)
3501 if not failing: 3501 ↛ 3502line 3501 didn't jump to line 3502 because the condition on line 3501 was never true
3502 return False
3503 if runtime.claim_check_enabled:
3504 self._record_unsupported_claim(execution, failing)
3505 events = self.s.events.list(execution.execution_id)
3506 if self.results.active:
3507 # planning.decomposition (#39): each sub-task has its own correction budget.
3508 events = events[self.results.decomposition.budget_start(events) :]
3509 used = sum(
3510 1
3511 for event in events
3512 if event.event_type == _CORRECTION_AUTHORIZED
3513 and event.payload.get("trigger") == "VERIFICATION_FAILED"
3514 )
3515 limit = runtime.correction_limit
3516 failed_ids = [item.validator_id for item in failing]
3517 if used >= limit:
3518 return self._corrections_exhausted(execution, used, limit, failed_ids, validations)
3519 feedback_ref: str | None = None
3520 if self._feedback_applies(execution.execution_id):
3521 findings = [
3522 item
3523 for item in self.s.state.list(
3524 "finding", Finding, execution_id=execution.execution_id
3525 )
3526 if any(item.finding_id in validation.finding_ids for validation in validations)
3527 ]
3528 feedback_ref = self._record_feedback(
3529 execution,
3530 PhaseId.VERIFICATION,
3531 trigger="VERIFICATION_FAILED",
3532 change_set_digest=execution.change_set_digest,
3533 gate=FeedbackGate(
3534 gate_id="verification",
3535 status=outcome.status,
3536 reason_codes=verification_reason_codes(failing),
3537 ),
3538 validations=validations,
3539 findings=findings + self._claim_findings(execution, failing),
3540 )
3541 transition = self.state_machine.authorize_verification_correction(PhaseId.VERIFICATION)
3542 self._save_execution(
3543 execution.model_copy(
3544 update={
3545 "status": ResultStatus.PENDING,
3546 "current_phase": transition.target,
3547 "gate_evaluation_id": None,
3548 "human_decision_id": None,
3549 "terminal_reason": None,
3550 "updated_at": utc_now(),
3551 }
3552 )
3553 )
3554 self.s.events.append(
3555 execution.execution_id,
3556 _CORRECTION_AUTHORIZED,
3557 {
3558 "trigger": "VERIFICATION_FAILED",
3559 "cycle": used + 1,
3560 "maxCycles": limit,
3561 "failedValidators": failed_ids,
3562 "changeSetDigest": execution.change_set_digest,
3563 "invalidatedPhases": [phase.value for phase in transition.invalidated],
3564 "feedbackRef": feedback_ref,
3565 },
3566 )
3567 if self.results.active:
3568 # agentRouting (#44): a quality failure climbs the escalation ladder.
3569 self.results.escalate(execution, "VERIFICATION_FAILED")
3570 return True
3572 def _corrections_exhausted(
3573 self,
3574 execution: Execution,
3575 used: int,
3576 limit: int,
3577 failed_ids: list[str],
3578 validations: list[ValidationResult],
3579 ) -> bool:
3580 """The correction budget is spent: the run returns to PLANNING when adaptive
3581 granularity splits a coarse attempt (#39, #77) and stops otherwise. Returns whether
3582 the run goes on."""
3583 if limit > 0:
3584 self.s.events.append(
3585 execution.execution_id,
3586 "correction.exhausted",
3587 {
3588 "trigger": "VERIFICATION_FAILED",
3589 "cycles": used,
3590 "maxCycles": limit,
3591 "failedValidators": failed_ids,
3592 "changeSetDigest": execution.change_set_digest,
3593 },
3594 )
3595 # planning.granularity: adaptive (#39) decomposes a coarse attempt that failed.
3596 if self.results.active and self.results.replan_after_failure(execution):
3597 return True
3598 if limit > 0:
3599 self._stop_after_corrections(execution, used, failed_ids, validations)
3600 return False
3602 def _stop_after_corrections(
3603 self,
3604 execution: Execution,
3605 used: int,
3606 failed_ids: list[str],
3607 validations: list[ValidationResult],
3608 ) -> None:
3609 """The run stops in VERIFICATION with the correction budget spent: the reason says so,
3610 and says when the agent's last correction changed nothing (``agent.empty-correction``),
3611 so a person sees why the run did not go on (#77)."""
3612 reason = (
3613 f"VERIFICATION still fails after {used} correction cycle(s) "
3614 f"(runtime.verificationCorrections): {', '.join(failed_ids)}"
3615 )
3616 finding_ids = {item for validation in validations for item in validation.finding_ids}
3617 if any(
3618 item.rule_id == EMPTY_CORRECTION_RULE and item.finding_id in finding_ids
3619 for item in self.s.state.list("finding", Finding, execution_id=execution.execution_id)
3620 ):
3621 reason += "; the agent's last correction changed nothing (agent.empty-correction)"
3622 latest = self.get_execution(execution.execution_id)
3623 self._save_execution(
3624 latest.model_copy(update={"terminal_reason": reason, "updated_at": utc_now()})
3625 )
3627 def _record_unsupported_claim(
3628 self, execution: Execution, failing: list[ValidationResult]
3629 ) -> None:
3630 """An agent that reported success on work that then failed verification made a claim
3631 the evidence does not support. The finding is evidence for the reviewer and the metrics;
3632 it is not an input of the gate, which evaluates the current ChangeSet."""
3633 key = f"claim:{execution.execution_id}"
3634 raw = self.s.state.get_flag(key)
3635 if not raw: 3635 ↛ 3636line 3635 didn't jump to line 3636 because the condition on line 3635 was never true
3636 return
3637 self.s.state.set_flag(key, "")
3638 claim = json.loads(raw)
3639 summary = head(str(claim.get("summary", "")), 500)
3640 failed = ", ".join(f"{item.validator_id} {item.status}" for item in failing)
3641 output_ref = claim.get("outputRef")
3642 finding = Finding(
3643 finding_id=new_id("finding"),
3644 execution_id=execution.execution_id,
3645 validator_id=CLAIM_CHECK_ID,
3646 rule_id=UNSUPPORTED_CLAIM_RULE,
3647 category="agent-claim",
3648 severity=self.s.resolved.project.runtime.claim_severity,
3649 message=(
3650 f"The agent reported {claim.get('status', 'PASSED')} ({summary!r}) "
3651 f"but verification failed: {failed}"
3652 ),
3653 evidence_refs=tuple(
3654 ([output_ref] if isinstance(output_ref, str) else [])
3655 + [item.evidence_refs[0] for item in failing]
3656 ),
3657 recommendation=(
3658 "Compare the agent's summary with the validator output before trusting its "
3659 "reports; the verified outcome is what the gate evaluates."
3660 ),
3661 provenance=self._provenance(execution),
3662 )
3663 self.s.state.put(
3664 "finding",
3665 finding.finding_id,
3666 finding,
3667 execution_id=execution.execution_id,
3668 project_id=execution.project_id,
3669 )
3670 self.s.events.append(
3671 execution.execution_id,
3672 _FINDING_RECORDED,
3673 finding.model_dump(mode="json"),
3674 actor=finding.provenance.actor,
3675 )
3677 def _claim_findings(
3678 self, execution: Execution, failing: list[ValidationResult]
3679 ) -> list[Finding]:
3680 """Unsupported-claim findings that cite the failing validations of this verification."""
3681 cited = {item.evidence_refs[0] for item in failing}
3682 return [
3683 item
3684 for item in self.s.state.list("finding", Finding, execution_id=execution.execution_id)
3685 if item.rule_id == UNSUPPORTED_CLAIM_RULE and cited & set(item.evidence_refs)
3686 ]
3688 def _gate_inputs(self, gate: GateEvaluation) -> tuple[list[ValidationResult], list[Finding]]:
3689 validations: list[ValidationResult] = []
3690 findings: list[Finding] = []
3691 for ref in gate.input_refs:
3692 if ref.startswith("record://validation/"):
3693 validations.append(
3694 self.s.state.get(
3695 "validation", ref.removeprefix("record://validation/"), ValidationResult
3696 )
3697 )
3698 elif ref.startswith("record://finding/"): 3698 ↛ 3691line 3698 didn't jump to line 3691 because the condition on line 3698 was always true
3699 findings.append(
3700 self.s.state.get("finding", ref.removeprefix("record://finding/"), Finding)
3701 )
3702 return validations, findings
3704 def _record_feedback(
3705 self,
3706 execution: Execution,
3707 phase_id: PhaseId,
3708 *,
3709 trigger: FeedbackTrigger,
3710 change_set_digest: str,
3711 gate: FeedbackGate,
3712 validations: list[ValidationResult],
3713 findings: list[Finding],
3714 decision: FeedbackDecision | None = None,
3715 ) -> str:
3716 """Store the feedback for the next IMPLEMENTATION attempt as evidence and remember it
3717 for the provider request."""
3718 attempt = 1 + sum(
3719 1
3720 for item in self.s.state.list(
3721 "phase", PhaseExecution, execution_id=execution.execution_id
3722 )
3723 if item.phase_id is PhaseId.IMPLEMENTATION
3724 )
3725 feedback = FeedbackBuilder(self.s.artifacts).build(
3726 trigger=trigger,
3727 attempt=max(attempt, 2),
3728 change_set_digest=change_set_digest,
3729 gate=gate,
3730 validations=validations,
3731 findings=findings,
3732 decision=decision,
3733 )
3734 ref = self.s.artifacts.put_json(
3735 feedback.model_dump(mode="json", by_alias=True),
3736 metadata={"kind": "provider-feedback", "executionId": execution.execution_id},
3737 )
3738 self._record_evidence(
3739 execution,
3740 phase_id,
3741 EvidenceKind.OTHER,
3742 ref,
3743 f"Provider feedback for IMPLEMENTATION attempt {feedback.attempt} ({trigger})",
3744 )
3745 self.s.state.set_flag(f"feedback:{execution.execution_id}", ref.uri)
3746 return ref.uri
3748 def _pending_feedback(
3749 self, execution: Execution, phase: PhaseExecution
3750 ) -> dict[str, Any] | None:
3751 """The latest recorded feedback, sent with every attempt that follows a correction."""
3752 if not self._feedback_applies(execution.execution_id):
3753 return None
3754 uri = self.s.state.get_flag(f"feedback:{execution.execution_id}")
3755 if not uri:
3756 return None
3757 feedback = ProviderFeedback.model_validate_json(self.s.artifacts.get(uri))
3758 if phase.attempt >= 2: 3758 ↛ 3760line 3758 didn't jump to line 3760 because the condition on line 3758 was always true
3759 feedback = feedback.model_copy(update={"attempt": phase.attempt})
3760 value: dict[str, Any] = feedback.model_dump(mode="json", by_alias=True)
3761 return value
3763 # ----- agent invocations ------------------------------------------------------
3764 def _save_agent_result(
3765 self, execution: Execution, phase: PhaseExecution, result: AgentExecutionResult
3766 ) -> None:
3767 self.s.state.put(
3768 "agent_invocation",
3769 result.invocation.invocation_id,
3770 result.invocation,
3771 execution_id=execution.execution_id,
3772 project_id=execution.project_id,
3773 )
3774 for tool in result.tool_invocations:
3775 self._save_tool(execution, tool)
3776 if result.usage is not None:
3777 self.s.state.put(
3778 "resource_usage",
3779 result.usage.usage_id,
3780 result.usage,
3781 execution_id=execution.execution_id,
3782 project_id=execution.project_id,
3783 )
3784 self.s.events.append(
3785 execution.execution_id,
3786 "agent.invocation.completed",
3787 result.invocation.model_dump(mode="json"),
3788 actor=result.invocation.actor,
3789 phase_execution_id=phase.phase_execution_id,
3790 )
3792 def _transient_cause(self, result: AgentExecutionResult) -> str | None:
3793 """The configured pattern that marks a failed command-provider call as transient.
3795 A process the runner killed at its timeout, a cancelled call and a call that passed are
3796 never transient; the patterns are looked for in the end of the (redacted) stderr and
3797 stdout of the call, which also holds the provider's JSON result."""
3798 if result.status in {ResultStatus.PASSED, ResultStatus.CANCELLED} or not (
3799 result.tool_invocations
3800 ):
3801 return None
3802 tool = result.tool_invocations[0]
3803 if tool.timed_out or tool.cancelled:
3804 return None
3805 texts = []
3806 for uri in (tool.stderr_ref, tool.stdout_ref):
3807 if not uri: 3807 ↛ 3808line 3807 didn't jump to line 3808 because the condition on line 3807 was never true
3808 continue
3809 data = self.s.artifacts.get(uri)[-TRANSIENT_SCAN_BYTES:]
3810 texts.append(data.decode("utf-8", "replace"))
3811 return transient_cause(texts, self.s.resolved.project.runtime.transient_patterns)
3813 def _record_provider_retry(
3814 self,
3815 execution: Execution,
3816 phase: PhaseExecution,
3817 result: AgentExecutionResult,
3818 cause: str,
3819 retry: int,
3820 ) -> None:
3821 runtime = self.s.resolved.project.runtime
3822 tool = result.tool_invocations[0]
3823 payload = {
3824 "retry": retry,
3825 "maxRetries": runtime.retry_limit,
3826 "delaySeconds": runtime.retry_delay_seconds,
3827 "matchedPattern": cause,
3828 "invocationId": result.invocation.invocation_id,
3829 "status": result.status.value,
3830 "exitCode": tool.exit_code,
3831 "stdoutRef": tool.stdout_ref,
3832 "stderrRef": tool.stderr_ref,
3833 }
3834 ref = self.s.artifacts.put_json(
3835 payload, metadata={"kind": "provider-retry", "executionId": execution.execution_id}
3836 )
3837 self._record_evidence(
3838 execution,
3839 phase.phase_id,
3840 EvidenceKind.COMMAND,
3841 ref,
3842 f"Transient provider failure ({cause!r}); retry {retry} of {runtime.retry_limit}",
3843 supports=(result.invocation.invocation_id,),
3844 )
3845 self.s.events.append(
3846 execution.execution_id,
3847 "agent.invocation.retried",
3848 payload,
3849 phase_execution_id=phase.phase_execution_id,
3850 )
3852 def _wait_for_retry(self, execution_id: str, delay: float) -> bool:
3853 """Wait ``delay`` seconds before a retry; ``False`` when the run is cancelled meanwhile."""
3854 deadline = time.monotonic() + delay
3855 while (remaining := deadline - time.monotonic()) > 0:
3856 if self.is_cancelled(execution_id):
3857 return False
3858 time.sleep(min(remaining, 1.0))
3859 return not self.is_cancelled(execution_id)
3861 # ----- helpers ----------------------------------------------------------------
3862 def _compute_owned_diff(self, execution: Execution) -> WorkspaceDiff:
3863 """Compute the task-owned diff without persisting unredacted content."""
3865 baseline_uri = self.s.state.get_flag(f"baseline:{execution.execution_id}")
3866 if not baseline_uri: 3866 ↛ 3867line 3866 didn't jump to line 3867 because the condition on line 3866 was never true
3867 raise NotFoundError("baseline snapshot is missing")
3868 stored = self.snapshots.load(baseline_uri)
3869 before = stored.snapshot
3870 after = self.snapshots.take()
3871 task = self.run_task(execution)
3872 owned_paths: set[str] | None = None
3873 if task.implementation.mode == "patch":
3874 owned_paths = {patch.path for patch in task.implementation.patches}
3875 elif task.metadata.get("ownedPaths"):
3876 owned_paths = {str(path) for path in task.metadata["ownedPaths"]}
3877 if owned_paths is not None:
3878 before_files = {
3879 path: state for path, state in before.files.items() if path in owned_paths
3880 }
3881 after_files = {
3882 path: state for path, state in after.files.items() if path in owned_paths
3883 }
3884 before = WorkspaceSnapshot(
3885 files=before_files,
3886 digest=sha256_json({path: state.digest for path, state in before_files.items()}),
3887 )
3888 after = WorkspaceSnapshot(
3889 files=after_files,
3890 digest=sha256_json({path: state.digest for path, state in after_files.items()}),
3891 )
3892 stored.snapshot = before
3893 return self.snapshots.diff(stored, after)
3895 def baseline_digests(self, execution: Execution) -> dict[str, str]:
3896 """Path -> digest of the run's baseline snapshot."""
3897 baseline_uri = self.s.state.get_flag(f"baseline:{execution.execution_id}")
3898 if not baseline_uri: 3898 ↛ 3899line 3898 didn't jump to line 3899 because the condition on line 3898 was never true
3899 raise NotFoundError("baseline snapshot is missing")
3900 value = json.loads(self.s.artifacts.get(baseline_uri))
3901 return {path: str(item["digest"]) for path, item in value["files"].items()}
3903 def _refresh_changeset(self, execution: Execution, *, record_on_run: bool = True) -> ChangeSet:
3904 """The current ChangeSet of the run, stored once per digest. ``record_on_run`` also
3905 makes its digest the run's ``change_set_digest``; a caller that only compares (a human
3906 decision, #95) leaves the run's digest as the gate saw it, so that a change found there
3907 is still found by ``verification.reverifyOnChange``."""
3908 diff = self._compute_owned_diff(execution)
3909 diff_ref = self.s.artifacts.put(
3910 diff.unified_diff,
3911 media_type="text/x-diff",
3912 metadata={"kind": "changeset-diff", "executionId": execution.execution_id},
3913 )
3914 changeset = ChangeSet(
3915 change_set_id=new_id("changeset"),
3916 execution_id=execution.execution_id,
3917 baseline_revision=execution.baseline_revision,
3918 current_revision=GitAdapter(self.s.paths.workspace).state().head,
3919 files=tuple(
3920 ChangedFile(
3921 path=item.path,
3922 status=cast(
3923 Literal["ADDED", "MODIFIED", "DELETED", "RENAMED", "UNTRACKED"], item.status
3924 ),
3925 additions=item.additions,
3926 deletions=item.deletions,
3927 before_digest=item.before_digest,
3928 after_digest=item.after_digest,
3929 )
3930 for item in diff.changes
3931 ),
3932 diff_ref=diff_ref.uri,
3933 digest=diff.digest,
3934 )
3935 existing = [
3936 item
3937 for item in self.s.state.list(
3938 "change_set", ChangeSet, execution_id=execution.execution_id
3939 )
3940 if item.digest == changeset.digest
3941 ]
3942 if existing:
3943 changeset = existing[-1]
3944 else:
3945 self.s.state.put(
3946 "change_set",
3947 changeset.change_set_id,
3948 changeset,
3949 execution_id=execution.execution_id,
3950 project_id=execution.project_id,
3951 )
3952 self.s.events.append(
3953 execution.execution_id,
3954 "changeset.created",
3955 changeset.model_dump(mode="json"),
3956 )
3957 self._record_artifact(
3958 execution,
3959 diff_ref,
3960 kind="CHANGESET_DIFF",
3961 provenance=self._provenance(execution),
3962 )
3963 self._record_evidence(
3964 execution,
3965 PhaseId.IMPLEMENTATION,
3966 EvidenceKind.CHANGESET,
3967 diff_ref,
3968 f"ChangeSet with {len(changeset.files)} changed file(s)",
3969 supports=(changeset.change_set_id,),
3970 )
3971 if record_on_run:
3972 updated = self.get_execution(execution.execution_id).model_copy(
3973 update={"change_set_digest": changeset.digest, "updated_at": utc_now()}
3974 )
3975 self._save_execution(updated)
3976 return changeset
3978 def _current_or_evaluate_gate(
3979 self, execution: Execution, change_set: ChangeSet
3980 ) -> GateEvaluation:
3981 now = utc_now()
3982 exceptions = self._project_exceptions(execution)
3983 if execution.gate_evaluation_id:
3984 gate = self.s.state.get("gate", execution.gate_evaluation_id, GateEvaluation)
3985 relied_on = set(exception_ids(gate.reason_codes))
3986 in_force = {item.exception_id for item in exceptions if item.active_at(now)}
3987 if gate.change_set_digest == change_set.digest and relied_on <= in_force:
3988 return gate
3989 self._workspace_guard_validation(execution, change_set.digest)
3990 validations = self._latest_validations(execution.execution_id, change_set.digest)
3991 findings = [
3992 item
3993 for item in self.s.state.list("finding", Finding, execution_id=execution.execution_id)
3994 if any(item.finding_id in validation.finding_ids for validation in validations)
3995 ]
3996 applied = apply_exceptions(findings, exceptions, now)
3997 findings = applied.kept
3998 severity_names = self.s.resolved.effective_policies.get(
3999 "findingBlockSeverities", ["HIGH", "CRITICAL"]
4000 )
4001 severities = tuple(FindingSeverity(str(name)) for name in severity_names)
4002 # Structured evaluation (keyword arguments) always returns a GateEvaluation; the
4003 # LegacyGateDecision branch only serves the positional `inputs` form.
4004 gate = cast(
4005 GateEvaluation,
4006 self.gate_engine.evaluate(
4007 execution_id=execution.execution_id,
4008 gate_id="delivery_candidate",
4009 change_set_digest=change_set.digest,
4010 policy_digest=execution.policy_digest,
4011 validations=validations,
4012 findings=findings,
4013 policy=GatePolicy(
4014 require_human_decision=bool(
4015 self.s.resolved.effective_policies.get("requireHumanDecision", True)
4016 ),
4017 blocking_severities=severities,
4018 ),
4019 provenance=self._provenance(execution),
4020 ),
4021 )
4022 if applied.used:
4023 gate = gate.model_copy(
4024 update={
4025 "reason_codes": (*gate.reason_codes, *applied.reason_codes),
4026 "input_refs": (
4027 *gate.input_refs,
4028 *(f"record://finding/{item.finding_id}" for item in applied.excepted),
4029 *(f"record://exception/{item.exception_id}" for item in applied.used),
4030 ),
4031 }
4032 )
4033 if self.ladder.active:
4034 # The certification of the ChangeSet (verification.ladder, #55).
4035 certification = self.ladder.gate_reasons(execution, change_set.digest)
4036 if certification:
4037 gate = gate.model_copy(
4038 update={"reason_codes": (*gate.reason_codes, *certification)}
4039 )
4040 self.s.state.put(
4041 "gate",
4042 gate.gate_evaluation_id,
4043 gate,
4044 execution_id=execution.execution_id,
4045 project_id=execution.project_id,
4046 )
4047 updated = self.get_execution(execution.execution_id).model_copy(
4048 update={"gate_evaluation_id": gate.gate_evaluation_id, "updated_at": utc_now()}
4049 )
4050 self._save_execution(updated)
4051 self.s.events.append(
4052 execution.execution_id,
4053 "gate.evaluated",
4054 gate.model_dump(mode="json"),
4055 )
4056 return gate
4058 def cause_analysis(self, execution: Execution) -> CauseAnalysis | None:
4059 """The causes of a run's stops and corrections under ``retrospective.causal``; ``None``
4060 (the 1.0.0 retrospective) without the key."""
4061 if not self.s.resolved.project.causal_retrospective:
4062 return None
4063 names = self.s.resolved.effective_policies.get(
4064 "findingBlockSeverities", ["HIGH", "CRITICAL"]
4065 )
4066 return analyze_causes(
4067 self.s.state,
4068 self.s.events.list(execution.execution_id),
4069 execution,
4070 {FindingSeverity(str(name)) for name in names},
4071 )
4073 def _project_exceptions(self, execution: Execution) -> list[ExceptionRecord]:
4074 """Exceptions recorded in the project, considered only under ``review.exceptions``:
4075 without the key the gate evaluates every finding, as in 1.0.0."""
4076 if not self.s.resolved.project.exceptions_enabled:
4077 return []
4078 return self.s.state.list("exception", ExceptionRecord, project_id=execution.project_id)
4080 def _latest_validations(self, execution_id: str, digest: str) -> list[ValidationResult]:
4081 # Only the latest attempt of each validator for the current digest counts: a failure
4082 # caused by the environment and fixed before a retry must not keep the gate closed.
4083 # Earlier attempts stay in the record and in the trace as history.
4084 latest: dict[str, ValidationResult] = {}
4085 for item in self.s.state.list("validation", ValidationResult, execution_id=execution_id):
4086 if item.change_set_digest != digest:
4087 continue
4088 previous = latest.get(item.validator_id)
4089 if previous is None or item.finished_at >= previous.finished_at: 4089 ↛ 4085line 4089 didn't jump to line 4085 because the condition on line 4089 was always true
4090 latest[item.validator_id] = item
4091 return list(latest.values())
4093 def _save_validator_output(self, execution: Execution, output: Any) -> None:
4094 result: ValidationResult = output.result
4095 self.s.state.put(
4096 "validation",
4097 result.validation_result_id,
4098 result,
4099 execution_id=execution.execution_id,
4100 project_id=execution.project_id,
4101 )
4102 # 2.0.1: the findings of one validation in one transaction of each store; the events
4103 # are those one append per finding writes (same order, envelope and digest chain).
4104 self.s.state.put_many(
4105 [("finding", finding.finding_id, finding) for finding in output.findings],
4106 execution_id=execution.execution_id,
4107 project_id=execution.project_id,
4108 )
4109 self.s.events.append_many(
4110 execution.execution_id,
4111 [
4112 (_FINDING_RECORDED, finding.model_dump(mode="json"), finding.provenance.actor)
4113 for finding in output.findings
4114 ],
4115 )
4116 for tool in output.tool_invocations:
4117 self._save_tool(execution, tool)
4118 self.s.events.append(
4119 execution.execution_id,
4120 "validation.completed",
4121 result.model_dump(mode="json"),
4122 actor=result.provenance.actor,
4123 )
4125 def _save_tool(self, execution: Execution, tool: ToolInvocation) -> None:
4126 self.s.state.put(
4127 "tool_invocation",
4128 tool.invocation_id,
4129 tool,
4130 execution_id=execution.execution_id,
4131 project_id=execution.project_id,
4132 )
4133 self.s.events.append(
4134 execution.execution_id,
4135 "tool.invocation.completed",
4136 tool.model_dump(mode="json"),
4137 actor=tool.actor,
4138 )
4140 def _record_artifact(
4141 self, execution: Execution, ref: Any, *, kind: str, provenance: Provenance
4142 ) -> Artifact:
4143 artifact = Artifact(
4144 artifact_id=new_id("artifact"),
4145 execution_id=execution.execution_id,
4146 kind=kind,
4147 media_type=ref.media_type,
4148 uri=ref.uri,
4149 digest=ref.digest,
4150 size_bytes=ref.size_bytes,
4151 redacted=ref.redacted,
4152 provenance=provenance,
4153 metadata=ref.metadata or {},
4154 )
4155 self.s.state.put(
4156 "artifact",
4157 artifact.artifact_id,
4158 artifact,
4159 execution_id=execution.execution_id,
4160 project_id=execution.project_id,
4161 )
4162 return artifact
4164 def _record_evidence(
4165 self,
4166 execution: Execution,
4167 phase_id: PhaseId,
4168 kind: EvidenceKind,
4169 artifact_ref: Any,
4170 summary: str,
4171 *,
4172 supports: tuple[str, ...] = (),
4173 ) -> Evidence:
4174 self._record_artifact(
4175 execution,
4176 artifact_ref,
4177 kind=kind.value,
4178 provenance=self._provenance(execution),
4179 )
4180 evidence = Evidence(
4181 evidence_id=new_id("evidence"),
4182 execution_id=execution.execution_id,
4183 phase_id=phase_id,
4184 kind=kind,
4185 artifact_ref=artifact_ref.uri,
4186 digest=artifact_ref.digest,
4187 summary=summary,
4188 provenance=self._provenance(execution),
4189 supports=supports,
4190 )
4191 self.s.state.put(
4192 "evidence",
4193 evidence.evidence_id,
4194 evidence,
4195 execution_id=execution.execution_id,
4196 project_id=execution.project_id,
4197 )
4198 self.s.events.append(
4199 execution.execution_id,
4200 "evidence.recorded",
4201 evidence.model_dump(mode="json"),
4202 )
4203 return evidence
4205 def get_execution(self, execution_id: str) -> Execution:
4206 return self.s.state.get("execution", execution_id, Execution)
4208 def get_task(self, task_id: str) -> Task:
4209 return self.s.state.get("task", task_id, Task)
4211 def run_task(self, execution: Execution) -> Task:
4212 """The task revision a run works on: the revision pinned when the run was created (or
4213 revised through ``task clarify``) under ``governance.pinTaskRevision``, otherwise the
4214 stored task, re-read by every phase as in 1.0.0.
4216 A pinned revision stored redacted (a secret in a patch's content, #178) is evidence,
4217 not the task: the run works on the stored task while it has the digest pinned with the
4218 revision, and stops with a policy error otherwise. A redacted value is never applied."""
4219 uri = self.s.state.get_flag(f"taskrev:{execution.execution_id}")
4220 if not uri:
4221 return self.get_task(execution.task_id)
4222 if not self.s.artifacts.describe(uri).redacted:
4223 return Task.model_validate_json(self.s.artifacts.get(uri))
4224 pinned = self.s.state.get_flag(f"{TASK_REVISION_DIGEST_FLAG}{execution.execution_id}")
4225 task = self.get_task(execution.task_id)
4226 if pinned and task_digest(task) == pinned:
4227 return task
4228 raise PolicyViolationError(
4229 f"the task revision pinned to run {execution.execution_id} ({uri}) is stored "
4230 "redacted and the stored task no longer has its digest "
4231 f"({pinned or 'not recorded'}); the run cannot work on a redacted task"
4232 )
4234 def _pins_task(self) -> bool:
4235 return bool(self.s.resolved.project.governance_settings.pin_task_revision)
4237 def _pin_task_revision(self, execution_id: str, task: Task) -> dict[str, Any]:
4238 ref = self.s.artifacts.put_json(
4239 task.model_dump(mode="json"), metadata={"kind": "task-revision"}
4240 )
4241 digest = task_digest(task)
4242 self.s.pin_task_revision(execution_id, ref.uri, digest)
4243 return {"taskDigest": digest, "taskRevisionRef": ref.uri}
4245 def _current_contract_digest(self, execution: Execution) -> str | None:
4246 """Under ``governance.pinTaskRevision``, the digest of the acceptance contract frozen in
4247 SPECIFICATION after checking that the run's task still produces it; ``None`` without the
4248 setting (or for a run created without it)."""
4249 frozen = self.s.state.get_flag(f"contract:{execution.execution_id}")
4250 if not self._pins_task() or not frozen:
4251 return None
4252 current = acceptance_contract_digest(self.run_task(execution))
4253 if current != frozen:
4254 raise PolicyViolationError(
4255 "the acceptance contract of the run changed after SPECIFICATION "
4256 f"(frozen {frozen}, now {current}); a decision cannot be bound to it"
4257 )
4258 return frozen
4260 def current_change_set(self, execution_id: str) -> ChangeSet:
4261 execution = self.get_execution(execution_id)
4262 items = self.s.state.list("change_set", ChangeSet, execution_id=execution_id)
4263 if not items: 4263 ↛ 4264line 4263 didn't jump to line 4264 because the condition on line 4263 was never true
4264 raise NotFoundError(f"no ChangeSet for {execution_id}")
4265 if execution.change_set_digest: 4265 ↛ 4269line 4265 didn't jump to line 4269 because the condition on line 4265 was always true
4266 matching = [item for item in items if item.digest == execution.change_set_digest]
4267 if matching: 4267 ↛ 4269line 4267 didn't jump to line 4269 because the condition on line 4267 was always true
4268 return matching[-1]
4269 return items[-1]
4271 def is_cancelled(self, execution_id: str) -> bool:
4272 return self.s.state.get_flag(f"cancel:{execution_id}") == "1"
4274 def _cancel_execution(self, execution: Execution) -> Execution:
4275 updated = execution.model_copy(
4276 update={
4277 "status": ResultStatus.CANCELLED,
4278 "terminal_reason": CANCELLATION_REQUESTED,
4279 "updated_at": utc_now(),
4280 }
4281 )
4282 self._save_execution(updated)
4283 self.s.events.append(execution.execution_id, "run.cancelled", {})
4284 return updated
4286 def _save_execution(self, execution: Execution) -> None:
4287 self.s.state.put(
4288 "execution",
4289 execution.execution_id,
4290 execution,
4291 execution_id=execution.execution_id,
4292 project_id=execution.project_id,
4293 )
4295 def _provenance(self, execution: Execution) -> Provenance:
4296 return Provenance(
4297 actor=HARNESS_ACTOR,
4298 core_version=__version__,
4299 configuration_digest=execution.configuration_digest,
4300 workflow_digest=execution.workflow_digest,
4301 policy_digest=execution.policy_digest,
4302 )
4304 @staticmethod
4305 def _worst_status(statuses: list[ResultStatus]) -> ResultStatus:
4306 order = [
4307 ResultStatus.ERROR,
4308 ResultStatus.TIMED_OUT,
4309 ResultStatus.BLOCKED,
4310 ResultStatus.CANCELLED,
4311 ResultStatus.INCONCLUSIVE,
4312 ResultStatus.FAILED,
4313 ResultStatus.SKIPPED,
4314 ResultStatus.NOT_APPLICABLE,
4315 ResultStatus.PASSED,
4316 ]
4317 return next(status for status in order if status in statuses)
4319 @staticmethod
4320 def _snapshot_to_dict(snapshot: WorkspaceSnapshot) -> dict[str, Any]:
4321 return {
4322 "digest": snapshot.digest,
4323 "files": {
4324 path: {
4325 "path": state.path,
4326 "digest": state.digest,
4327 "sizeBytes": state.size_bytes,
4328 "text": state.text,
4329 }
4330 for path, state in snapshot.files.items()
4331 },
4332 }
4334 @staticmethod
4335 def _snapshot_from_dict(value: dict[str, Any]) -> WorkspaceSnapshot:
4336 from governed_harness.runtime.workspace import FileState
4338 return WorkspaceSnapshot(
4339 files={
4340 path: FileState(
4341 path=item["path"],
4342 digest=item["digest"],
4343 size_bytes=item["sizeBytes"],
4344 text=item.get("text"),
4345 )
4346 for path, item in value["files"].items()
4347 },
4348 digest=value["digest"],
4349 )