okstra 0.179.2 → 0.180.0

package/runtime/python/okstra_ctl/approval_decisions.py

@@ -0,0 +1,327 @@
+"""선임 에이전트가 소유하는 승인 결정 입력 원장."""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from copy import deepcopy
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+from .convergence_store import write_json_atomic
+
+
+DISPOSITIONS = frozenset({"select", "accept-risk", "request-revision", "reject"})
+REACHES = frozenset({"in-repo", "cross-repo"})
+SCOPE_EFFECTS = frozenset({"new-schema", "deferrable"})
+CLASSIFICATIONS = frozenset(
+    {"user-decision", "noncritical-dissent", "correctness-critical"}
+)
+_FORBIDDEN_BY_CLASSIFICATION = {
+    "correctness-critical": frozenset({"select", "accept-risk"}),
+    "noncritical-dissent": frozenset({"select"}),
+    "user-decision": frozenset(),
+}
+
+
+class ApprovalDecisionError(ValueError):
+    """승인 결정 입력이 역할 계약이나 선택지 불변식을 위반했다."""
+
+
+def _required(value: str, field: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ApprovalDecisionError(f"{field} must be a non-empty string")
+    return value.strip()
+
+
+@dataclass(frozen=True)
+class DecisionOption:
+    role: str
+    answer: str
+    rationale: str
+    disposition: str
+    reach: str
+    scope_effects: tuple[str, ...]
+    added_work: str
+    direction_change: str
+
+    def __post_init__(self) -> None:
+        if self.role not in {"recommended", "alternative"}:
+            raise ApprovalDecisionError(f"invalid option role: {self.role}")
+        for field in ("answer", "rationale", "added_work", "direction_change"):
+            _required(getattr(self, field), field)
+        if self.disposition not in DISPOSITIONS:
+            raise ApprovalDecisionError(f"invalid disposition: {self.disposition}")
+        if self.reach not in REACHES:
+            raise ApprovalDecisionError(f"invalid reach: {self.reach}")
+        unknown = sorted(set(self.scope_effects) - SCOPE_EFFECTS)
+        if unknown or len(set(self.scope_effects)) != len(self.scope_effects):
+            raise ApprovalDecisionError(f"invalid scope_effects: {unknown}")
+
+    def to_payload(self) -> dict[str, Any]:
+        return {
+            "role": self.role,
+            "answer": self.answer,
+            "rationale": self.rationale,
+            "disposition": self.disposition,
+            "reach": self.reach,
+            "scopeEffects": list(self.scope_effects),
+            "addedWork": self.added_work,
+            "directionChange": self.direction_change,
+        }
+
+
+def _new_ledger(task_key: str, task_type: str, run_seq: str) -> dict[str, Any]:
+    return {
+        "schemaVersion": "1.0",
+        "owner": "lead",
+        "taskKey": _required(task_key, "task_key"),
+        "taskType": _required(task_type, "task_type"),
+        "runSeq": _required(run_seq, "run_seq"),
+        "activeClarifications": [],
+        "carriedDecisions": [],
+    }
+
+
+def _read_ledger(path: Path) -> dict[str, Any]:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        raise ApprovalDecisionError(f"cannot read approval ledger {path}: {exc}") from exc
+    if not isinstance(value, dict) or value.get("owner") != "lead":
+        raise ApprovalDecisionError(f"approval ledger owner must be lead: {path}")
+    return value
+
+
+def _ledger(path: Path, task_key: str, task_type: str, run_seq: str) -> dict[str, Any]:
+    if not path.is_file():
+        return _new_ledger(task_key, task_type, run_seq)
+    ledger = _read_ledger(path)
+    expected = (task_key, task_type, run_seq)
+    actual = (ledger.get("taskKey"), ledger.get("taskType"), ledger.get("runSeq"))
+    if actual != expected:
+        raise ApprovalDecisionError("approval ledger identity does not match this run")
+    return ledger
+
+
+def _validate_option_set(
+    options: Sequence[DecisionOption], classification: str,
+    recommended_disposition: str,
+) -> None:
+    if len(options) < 2:
+        raise ApprovalDecisionError("a decision requires at least two options")
+    if sum(option.role == "recommended" for option in options) != 1:
+        raise ApprovalDecisionError("a decision requires exactly one recommended option")
+    forbidden = _FORBIDDEN_BY_CLASSIFICATION[classification]
+    used = {recommended_disposition, *(option.disposition for option in options)}
+    invalid = sorted(used & forbidden)
+    if invalid:
+        raise ApprovalDecisionError(f"{classification} forbids dispositions: {invalid}")
+    recommended = next(option for option in options if option.role == "recommended")
+    if recommended.disposition != recommended_disposition:
+        raise ApprovalDecisionError(
+            "recommended_disposition must match the recommended option"
+        )
+
+
+def _decision_row(
+    *, clarification_id: str, ticket_id: str, statement: str,
+    expected_form: str, classification: str, origin: str,
+    user_confirmation: str, unblock_condition: str,
+    recommended_disposition: str, options: Sequence[DecisionOption],
+) -> dict[str, Any]:
+    if classification not in CLASSIFICATIONS:
+        raise ApprovalDecisionError(f"invalid classification: {classification}")
+    if recommended_disposition not in DISPOSITIONS:
+        raise ApprovalDecisionError(
+            f"invalid recommended_disposition: {recommended_disposition}"
+        )
+    _validate_option_set(options, classification, recommended_disposition)
+    return {
+        "id": _required(clarification_id, "clarification_id"),
+        "ticketId": _required(ticket_id, "ticket_id"),
+        "kind": "decision",
+        "statement": _required(statement, "statement"),
+        "expectedForm": _required(expected_form, "expected_form"),
+        "blocks": "approval",
+        "origin": _required(origin, "origin"),
+        "userConfirmation": _required(user_confirmation, "user_confirmation"),
+        "approval": {
+            "classification": classification,
+            "unblockCondition": _required(unblock_condition, "unblock_condition"),
+            "recommendedDisposition": recommended_disposition,
+        },
+        "options": [option.to_payload() for option in options],
+    }
+
+
+def open_decision(
+    *, ledger_path: Path, task_key: str, task_type: str, run_seq: str,
+    clarification_id: str, ticket_id: str, statement: str, expected_form: str,
+    classification: str, origin: str, user_confirmation: str,
+    unblock_condition: str, recommended_disposition: str,
+    options: Sequence[DecisionOption],
+) -> None:
+    row = _decision_row(
+        clarification_id=clarification_id, ticket_id=ticket_id,
+        statement=statement, expected_form=expected_form,
+        classification=classification, origin=origin,
+        user_confirmation=user_confirmation, unblock_condition=unblock_condition,
+        recommended_disposition=recommended_disposition, options=options,
+    )
+    ledger = _ledger(ledger_path, task_key, task_type, run_seq)
+    active = ledger.get("activeClarifications")
+    if not isinstance(active, list):
+        raise ApprovalDecisionError("activeClarifications must be an array")
+    if any(item.get("id") == clarification_id for item in active if isinstance(item, Mapping)):
+        raise ApprovalDecisionError(f"duplicate active clarification: {clarification_id}")
+    active.append(row)
+    write_json_atomic(ledger_path, ledger)
+
+
+def resolve_decision(
+    ledger_path: Path, clarification_id: str, *, disposition: str,
+    user_text: str, user_response_ref: str, check_refs: Sequence[str],
+) -> None:
+    if disposition not in DISPOSITIONS:
+        raise ApprovalDecisionError(f"invalid disposition: {disposition}")
+    resolution = {
+        "disposition": disposition,
+        "userText": _required(user_text, "user_text"),
+        "userResponseRef": _required(user_response_ref, "user_response_ref"),
+        "checkRefs": [_required(ref, "check_refs") for ref in check_refs],
+    }
+    if not resolution["checkRefs"]:
+        raise ApprovalDecisionError("check_refs requires at least one value")
+    invalid_refs = [
+        ref for ref in resolution["checkRefs"]
+        if re.fullmatch(r"A-\d{3,}", ref) is None
+    ]
+    if invalid_refs:
+        raise ApprovalDecisionError(f"check_refs must be activity IDs: {invalid_refs}")
+    ledger = _read_ledger(ledger_path)
+    active = ledger.get("activeClarifications")
+    rows = active if isinstance(active, list) else []
+    matches = [row for row in rows if isinstance(row, dict) and row.get("id") == clarification_id]
+    if len(matches) != 1:
+        raise ApprovalDecisionError(f"active clarification not found: {clarification_id}")
+    matches[0]["resolutionInput"] = resolution
+    write_json_atomic(ledger_path, ledger)
+
+
+def carry_decision(
+    ledger_path: Path, *, source_run_ref: str, decision: Mapping[str, Any],
+) -> None:
+    ledger = _read_ledger(ledger_path)
+    carried = ledger.get("carriedDecisions")
+    if not isinstance(carried, list):
+        raise ApprovalDecisionError("carriedDecisions must be an array")
+    row = {
+        "sourceRunRef": _required(source_run_ref, "source_run_ref"),
+        "decision": deepcopy(dict(decision)),
+    }
+    if row not in carried:
+        carried.append(row)
+    write_json_atomic(ledger_path, ledger)
+
+
+def _options_from_args(args: argparse.Namespace) -> tuple[DecisionOption, ...]:
+    fields = (
+        args.option_role, args.option_answer, args.option_rationale,
+        args.option_disposition, args.option_reach, args.option_scope_effect,
+        args.option_added_work, args.option_direction_change,
+    )
+    if len({len(values) for values in fields}) != 1:
+        raise ApprovalDecisionError("every repeated option field needs the same count")
+    return tuple(
+        DecisionOption(role, answer, rationale, disposition, reach,
+                       tuple(effect.split(",")) if effect else (), added, direction)
+        for role, answer, rationale, disposition, reach, effect, added, direction
+        in zip(*fields, strict=True)
+    )
+
+
+def _add_open_arguments(parser: argparse.ArgumentParser) -> None:
+    required = (
+        "task-key", "task-type", "run-seq", "clarification-id", "ticket-id",
+        "statement", "expected-form", "classification", "origin",
+        "user-confirmation", "unblock-condition", "recommended-disposition",
+    )
+    for flag in required:
+        parser.add_argument(f"--{flag}", required=True)
+    repeated = (
+        "role", "answer", "rationale", "disposition", "reach",
+        "scope-effect", "added-work", "direction-change",
+    )
+    for flag in repeated:
+        parser.add_argument(f"--option-{flag}", action="append", default=[])
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="okstra approval-decision")
+    commands = parser.add_subparsers(dest="command", required=True)
+    opened = commands.add_parser("open")
+    opened.add_argument("--ledger", type=Path, required=True)
+    _add_open_arguments(opened)
+    resolved = commands.add_parser("resolve")
+    resolved.add_argument("--ledger", type=Path, required=True)
+    resolved.add_argument("--clarification-id", required=True)
+    resolved.add_argument("--disposition", required=True)
+    resolved.add_argument("--user-text", required=True)
+    resolved.add_argument("--user-response-ref", required=True)
+    resolved.add_argument("--check-ref", action="append", default=[])
+    carried = commands.add_parser("carry")
+    carried.add_argument("--ledger", type=Path, required=True)
+    carried.add_argument("--source-ledger", type=Path, required=True)
+    carried.add_argument("--source-run-ref", required=True)
+    carried.add_argument("--clarification-id", required=True)
+    return parser
+
+
+def _open_from_args(args: argparse.Namespace) -> None:
+    values = vars(args).copy()
+    values.pop("command")
+    values["ledger_path"] = values.pop("ledger")
+    for key in tuple(values):
+        if key.startswith("option_"):
+            values.pop(key)
+    open_decision(**values, options=_options_from_args(args))
+
+
+def _carry_from_args(args: argparse.Namespace) -> None:
+    source = _read_ledger(args.source_ledger)
+    rows = source.get("activeClarifications") or []
+    matches = [row for row in rows if isinstance(row, dict) and row.get("id") == args.clarification_id]
+    if len(matches) != 1:
+        raise ApprovalDecisionError(f"source clarification not found: {args.clarification_id}")
+    carry_decision(args.ledger, source_run_ref=args.source_run_ref, decision=matches[0])
+
+
+def _run(args: argparse.Namespace) -> None:
+    if args.command == "open":
+        _open_from_args(args)
+    elif args.command == "resolve":
+        resolve_decision(
+            args.ledger, args.clarification_id, disposition=args.disposition,
+            user_text=args.user_text, user_response_ref=args.user_response_ref,
+            check_refs=args.check_ref,
+        )
+    else:
+        _carry_from_args(args)
+
+
+def main(argv: list[str] | None = None) -> int:
+    try:
+        args = _parser().parse_args(argv)
+        _run(args)
+        print(json.dumps({"ok": True, "ledger": str(args.ledger)}, ensure_ascii=False))
+        return 0
+    except (ApprovalDecisionError, OSError) as exc:
+        print(f"approval-decision: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/python/okstra_ctl/design_snapshot.py

@@ -0,0 +1,134 @@
+"""보고서 서사에서 설계 표면 탐지기 소유 스냅샷을 생성한다."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any, Mapping
+
+from .convergence_store import write_json_atomic
+from .design_surfaces import DesignSurfaceError, detect_design_surfaces
+from .final_report_schema import load_schema_version
+from .report_narrative import NarrativeContractError, parse_narrative
+
+
+def _evidence(trigger: Any) -> list[dict[str, Any]]:
+    return [
+        {"step": row.step, "field": row.field, "match": row.match}
+        for row in trigger.evidence
+    ]
+
+
+def build_design_snapshot(planning: Mapping[str, Any]) -> dict[str, Any]:
+    """계획 본문에서 재현 가능한 설계 표면과 보수적 준비 항목을 만든다."""
+    triggers = detect_design_surfaces(planning)
+    by_stage: dict[int, list[dict[str, Any]]] = {}
+    items = []
+    for index, trigger in enumerate(triggers, start=1):
+        evidence = _evidence(trigger)
+        prep_id = f"PREP-{index:03d}"
+        evidence_refs = [
+            f"Stage {trigger.stage} step {row['step'] or 'n/a'} "
+            f"{row['field']}={row['match']}"
+            for row in evidence
+        ]
+        by_stage.setdefault(trigger.stage, []).append({
+            "kind": trigger.kind,
+            "triggerEvidence": evidence,
+            "disposition": "prep-item",
+            "prepItemId": prep_id,
+        })
+        items.append({
+            "id": prep_id,
+            "kind": trigger.kind,
+            "title": f"Stage {trigger.stage} {trigger.kind} contract",
+            "stageRefs": [trigger.stage],
+            "status": "provisional",
+            "need": (
+                f"Stage {trigger.stage} touches a {trigger.kind} surface, but the "
+                "detector evidence does not define its implementation contract."
+            ),
+            "knownFacts": [
+                {"statement": "The plan triggered this design surface.", "evidence": ref}
+                for ref in evidence_refs
+            ],
+            "openQuestions": [
+                f"What exact {trigger.kind} contract must Stage {trigger.stage} implement?"
+            ],
+            "aiProposal": {
+                "summary": "Preserve existing behaviour until the contract is confirmed.",
+                "details": [
+                    "Record the concrete contract before an irreversible implementation step."
+                ],
+                "assumptions": [
+                    "Detector evidence proves surface presence, not the missing contract details."
+                ],
+                "evidence": evidence_refs,
+                "confidence": "low",
+            },
+            "humanConfirmation": {
+                "required": True,
+                "reason": "The plan does not contain enough evidence to infer the contract.",
+                "suggestedAction": "confirm-or-edit",
+            },
+            "workingAssumption": "Preserve existing behaviour and avoid irreversible changes.",
+            "guardrails": [
+                "Do not present a synthetic or inferred contract as externally verified."
+            ],
+            "reviewAt": {"phase": "implementation", "stage": trigger.stage},
+            "ifStillOpen": "block",
+            "requestPath": (
+                f"design-prep-requests/design-prep-request-{trigger.stage}-{prep_id}.md"
+            ),
+            "replanTriggerFields": ["aiProposal", "workingAssumption"],
+        })
+    preparation = {
+        "mode": "assessed" if triggers else "no-design-inputs",
+        "reason": (
+            f"Detector found {len(triggers)} design surface(s)."
+            if triggers else "Detector found no design surfaces in the plan."
+        ),
+        "items": items,
+    }
+    return {
+        "schemaVersion": "1.0",
+        "owner": "design-surface-detector",
+        "designPreparation": preparation,
+        "stageCoverage": [
+            {"stage": stage, "rows": rows}
+            for stage, rows in sorted(by_stage.items())
+        ],
+    }
+
+
+def write_snapshot(narrative_path: Path, output_path: Path) -> dict[str, Any]:
+    narrative = parse_narrative(
+        narrative_path.read_text(encoding="utf-8"), load_schema_version("3.0")
+    )
+    planning = narrative.get("implementationPlanning")
+    if not isinstance(planning, Mapping):
+        raise DesignSurfaceError("implementationPlanning is missing from narrative")
+    snapshot = build_design_snapshot(planning)
+    write_json_atomic(output_path, snapshot)
+    return snapshot
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="okstra design-snapshot")
+    parser.add_argument("--narrative", type=Path, required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    args = parser.parse_args(argv)
+    try:
+        snapshot = write_snapshot(args.narrative, args.output)
+    except (OSError, UnicodeError, DesignSurfaceError, NarrativeContractError) as exc:
+        print(f"design-snapshot: {exc}", file=sys.stderr)
+        return 2
+    print(json.dumps({"ok": True, "surfaces": sum(
+        len(row["rows"]) for row in snapshot["stageCoverage"]
+    )}, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -310,7 +310,7 @@ class DispatchPlan:
 @dataclass(frozen=True)
 class _BuildOptions:
     okstra_bin: Path | None
-    idle_timeout_seconds: int
+    idle_timeout_seconds: int | None
     default_backend: str
     supported_worker_wrappers: Mapping[str, str]
     unsupported_worker_label: str
@@ -335,7 +335,7 @@ def build_dispatch_plan(
     workspace_root: Path,
     okstra_bin: Path | None = None,
     requested_workers: Sequence[str] = (),
-    idle_timeout_seconds: int = 600,
+    idle_timeout_seconds: int | None = None,
     required_lead_runtime: str | None = None,
     default_backend: str = BACKEND_CLI_WRAPPER,
     supported_worker_wrappers: Mapping[str, str],
@@ -432,6 +432,37 @@ def dispatch_plan(plan: DispatchPlan, *, wait: bool = True) -> int:
     return 0
 
 
+def _orchestrator_artifact_roots(plan: DispatchPlan) -> tuple[Path, ...]:
+    """okstra 자신이 이 run 동안 쓰는 산출물 경로.
+
+    `_round_artifact_paths` 는 이번 배치의 job 만 알기 때문에 원리상 완결될 수
+    없다. 감사 창에 들어오는 것은 형제 job 의 산출물만이 아니라 같은 run 의 다른
+    라운드가 남기는 것들이다 — 재시도 프롬프트와 그 `.meta.json` / `.publish.lock`,
+    이전 라운드 워커의 `.log` / `.status.json` / `.mutation-audit.json`, critic 의
+    결과, design-prep 요청. 실측 한 건에서 그렇게 빠져나간 경로가 16개였고 그
+    배치의 디스패치 5건이 전부 `readonly source changed` 로 떨어졌다.
+
+    그래서 파일을 더 세는 대신 트리를 싣는다. 이 디렉터리 아래는 정의상 okstra 의
+    산출물이고 프로젝트 소스가 아니다 — 소스가 바뀌었는지를 묻는 질문의 답이 될 수
+    없다.
+    """
+    # 실행 매니페스트는 `<run_dir>/manifests/` 아래 놓인다.
+    roots = [plan.manifest_path.resolve().parents[1]]
+    # task 매니페스트와 discovery 카탈로그는 run 디렉터리 위에 있고, prep 과
+    # 완료 기록이 실행 중에 갱신한다. 경로는 매니페스트가 이미 들고 있으므로
+    # 디렉터리 깊이를 세지 않는다 — implementation 은 stage 층이 하나 더 있어
+    # 고정 인덱스로는 task root 에 닿지 못한다.
+    for key in ("taskManifestPath", "taskCatalogPath"):
+        value = plan.manifest.get(key)
+        if isinstance(value, str) and value:
+            candidate = Path(value)
+            roots.append(
+                candidate if candidate.is_absolute()
+                else (plan.project_root / candidate)
+            )
+    return tuple(roots)
+
+
 def _round_artifact_paths(plan: DispatchPlan) -> tuple[Path, ...]:
     """Every artifact this round's workers are entitled to write.
 
@@ -1488,6 +1519,7 @@ def _mutation_snapshot(
         orchestrator_paths=(
             *round_artifact_paths,
             *_run_errors_log_path(plan),
+            *_orchestrator_artifact_roots(plan),
             plan.manifest_path,
             plan.team_state_path,
             Path(f"{plan.team_state_path}.lock"),
@@ -1840,6 +1872,31 @@ def _retry_from_record(
     _spawn_job(plan, _job_for_next_attempt(job), attempt + 1)
 
 
+# 사유 한 줄에 실을 경로 개수. 전부 실으면 team-state 행이 부풀고, 하나도 안
+# 실으면 읽는 쪽이 다른 파일을 뒤져야 한다.
+_MUTATION_REASON_PATH_LIMIT = 5
+
+
+def _mutation_failure_reason(mutation) -> str:
+    """왜 실패했는지와 무엇이 바뀌었는지를 한 줄에 담는다.
+
+    종전에는 디스패치 행에 `readonly source changed` 만 남고 바뀐 경로는
+    lead-events 에만 있었다. 읽는 쪽이 그 파일의 존재를 알아야 원인에 닿을 수
+    있었고, 실제로 두 번의 진단이 같은 자리에서 빗나갔다 — 한 번은 감사를 손으로
+    재구현해서, 한 번은 사용자 편집을 의심해서. 감사는 답을 이미 계산해 두었으니
+    사유 옆에 놓는다.
+    """
+    reason = "; ".join(mutation.violations) or mutation.status
+    paths = list(mutation.changed_paths)
+    if not paths:
+        return reason
+    shown = ", ".join(paths[:_MUTATION_REASON_PATH_LIMIT])
+    remaining = len(paths) - _MUTATION_REASON_PATH_LIMIT
+    if remaining > 0:
+        shown += f", +{remaining} more"
+    return f"{reason} [changed: {shown}]"
+
+
 def _finish_attempt(
     plan: DispatchPlan,
     job: WorkerJob,
@@ -1854,7 +1911,7 @@ def _finish_attempt(
         "contract-failed-unattributed",
         "mutation-present-unresolved",
     }:
-        reason = "; ".join(mutation.violations) or mutation.status
+        reason = _mutation_failure_reason(mutation)
         _transition_job_status(plan, job, "error", reason)
         _update_dispatch_status(
             plan.team_state_path, job, attempt, "error", reason
@@ -2866,7 +2923,8 @@ def _job_from_record(project_root: Path, record: Mapping[str, Any]) -> WorkerJob
         completion_paths=tuple(_record_completion_paths(record)),
         worktree_path=_string_value(record.get("worktreePath")),
         role=_require_string(record, "role"),
-        idle_timeout_seconds=600,
+        # 복원된 job 은 다시 실행되지 않으므로 예산을 정하지 않는다.
+        idle_timeout_seconds=None,
         dispatch_kind=_require_string(record, "kind"),
         # Restored, never re-issued: both callers rebuild a job from its record
         # to settle a dispatch that already ran, and a fresh id would settle it

package/runtime/python/okstra_ctl/dispatch_state.py

@@ -47,6 +47,7 @@ from .execution_manifest import (
 )
 from .execution_mutation_audit import ExecutionMutationAudit, MutationSnapshot
 from .final_report_paths import final_report_data_path
+from .report_inputs import report_narrative_path, uses_report_contract_v3
 from .worker_prompt_body import REPORT_WRITER_WORKER_ID
 from .worker_prompt_contract import (
     PromptRecord,
@@ -152,7 +153,11 @@ class WorkerJob:
     completion_paths: tuple[Path, ...]
     worktree_path: str
     role: str
-    idle_timeout_seconds: int
+    # None 은 "이 디스패치가 예산을 정하지 않는다" 는 뜻이고, 그때 예산은
+    # 역할이 정한다(`domain/worker_role.role_spec`). 여기에 숫자 기본값을 두면
+    # 역할별 예산이 영영 도달 불가능해진다 — 엔트리포인트는 이 자리가 비었을
+    # 때만 역할을 보기 때문이다.
+    idle_timeout_seconds: int | None
     dispatch_kind: str
     invocation_id: str = ""
     audience: str = ""
@@ -188,7 +193,7 @@ class WorkerJob:
             str(self.prompt_path),
             self.worktree_path,
             self.wrapper_role,
-            str(self.idle_timeout_seconds),
+            self._idle_timeout_argument,
             "--presentation",
             self._presentation(),
         ]
@@ -201,6 +206,18 @@ class WorkerJob:
             argv += ["--session-id", self.session_id]
         return argv
 
+    @property
+    def _idle_timeout_argument(self) -> str:
+        """엔트리포인트가 읽는 유휴 예산 자리.
+
+        비워 두면 엔트리포인트가 역할의 예산을 쓴다. 이 자리를 항상 채우던
+        동안에는 `worker_request.idle_timeout` 의 역할 분기가 한 번도 실행되지
+        않았고, executor/verifier 의 1500s 도 함께 죽어 있었다.
+        """
+        if self.idle_timeout_seconds is None:
+            return ""
+        return str(self.idle_timeout_seconds)
+
     @property
     def wrapper_role(self) -> str:
         """The canonical role the entrypoint's role positional is read as.
@@ -707,6 +724,10 @@ def record_verified_agent_dispatch(
             snapshot = ExecutionMutationAudit().snapshot(
                 (write_policy,),
                 orchestrator_paths=(
+                    # run 산출물 트리 전체. 같은 run 의 다른 라운드가 감사 창
+                    # 안에 남기는 프롬프트·로그·사이드카를 파일 단위로 미리 셀
+                    # 수 없고, 그 아래는 정의상 소스가 아니다.
+                    Path(run_manifest_path).resolve().parents[1],
                     run_manifest_path,
                     team_state_path,
                     Path(f"{team_state_path}.lock"),
@@ -1468,6 +1489,8 @@ def dispatch_result_path(
     """
     if worker_id != REPORT_WRITER_WORKER_ID:
         return worker_result_path
+    if uses_report_contract_v3(manifest):
+        return report_narrative_path(project_root, manifest)
     return final_report_data_path(
         resolve_required_path(project_root, manifest, "expectedReportRecordPath")
     )
@@ -1487,6 +1510,8 @@ def dispatch_completion_paths(
     """
     if worker_id != REPORT_WRITER_WORKER_ID:
         return (worker_result_path,)
+    if uses_report_contract_v3(manifest):
+        return (report_narrative_path(project_root, manifest), worker_result_path)
     data_json = final_report_data_path(
         resolve_required_path(project_root, manifest, "expectedReportRecordPath")
     )
@@ -1765,7 +1790,7 @@ def worker_jobs_from_file(
     manifest: Mapping[str, Any],
     active_context: Mapping[str, Any] | None = None,
     backend: str,
-    idle_timeout_seconds: int,
+    idle_timeout_seconds: int | None,
     default_dispatch_kind: str,
     resolve_wrapper: Callable[[str], Path],
     default_provider: Callable[[str], str],
@@ -1804,7 +1829,7 @@ def _worker_job_from_file(
     manifest: Mapping[str, Any],
     active_context: Mapping[str, Any] | None = None,
     backend: str,
-    idle_timeout_seconds: int,
+    idle_timeout_seconds: int | None,
     dispatch_kind: str,
     resolve_wrapper: Callable[[str], Path],
     default_provider: Callable[[str], str],