okstra 0.174.0 → 0.176.0

package/runtime/python/okstra_ctl/execution_mutation_audit.py

@@ -0,0 +1,619 @@
+"""Batch-scoped source and Git mutation audit for worker invocations."""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import subprocess
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .write_policy import WritePolicy
+
+
+class MutationAuditError(ValueError):
+    """Raised before dispatch when policies cannot share one audit batch."""
+
+
+def assert_compatible_batch(policies: Sequence[WritePolicy]) -> None:
+    """Reject a dispatch batch before any attempt is recorded."""
+    _validate_batch(tuple(policies))
+
+
+@dataclass(frozen=True)
+class MutationSnapshot:
+    root: Path
+    artifact_root: Path
+    policy_digests: tuple[str, ...]
+    file_digests: Mapping[str, str]
+    artifact_digests: Mapping[str, str]
+    scratch_digests: Mapping[str, str]
+    git_projection: Mapping[str, Any]
+    digest: str
+    orchestrator_paths: tuple[str, ...] = ()
+
+    def to_payload(self) -> dict[str, Any]:
+        return {
+            "root": str(self.root),
+            "artifactRoot": str(self.artifact_root),
+            "policyDigests": list(self.policy_digests),
+            "fileDigests": dict(self.file_digests),
+            "artifactDigests": dict(self.artifact_digests),
+            "scratchDigests": dict(self.scratch_digests),
+            "gitProjection": dict(self.git_projection),
+            "digest": self.digest,
+            "orchestratorPaths": list(self.orchestrator_paths),
+        }
+
+    @classmethod
+    def from_payload(cls, payload: Mapping[str, Any]) -> "MutationSnapshot":
+        snapshot = cls(
+            root=Path(str(payload["root"])),
+            artifact_root=Path(str(payload["artifactRoot"])),
+            policy_digests=tuple(payload["policyDigests"]),
+            file_digests=dict(payload["fileDigests"]),
+            artifact_digests=dict(payload["artifactDigests"]),
+            scratch_digests=dict(payload["scratchDigests"]),
+            git_projection=dict(payload["gitProjection"]),
+            digest=str(payload["digest"]),
+            orchestrator_paths=tuple(payload.get("orchestratorPaths", ())),
+        )
+        expected = _snapshot_digest(
+            snapshot.root,
+            snapshot.artifact_root,
+            snapshot.policy_digests,
+            snapshot.file_digests,
+            snapshot.artifact_digests,
+            snapshot.scratch_digests,
+            snapshot.git_projection,
+            snapshot.orchestrator_paths,
+        )
+        if snapshot.digest != expected:
+            raise MutationAuditError("mutation snapshot digest does not match payload")
+        return snapshot
+
+
+@dataclass(frozen=True)
+class MutationAuditResult:
+    status: str
+    changed_paths: tuple[str, ...]
+    source_changed: bool
+    git_changed: bool
+    attribution: str
+    retry_allowed: bool
+    violations: tuple[str, ...]
+    before_digest: str
+    after_digest: str
+    git_projection: Mapping[str, Any]
+
+    def change_summary(self) -> dict[str, Any]:
+        return {
+            "mutationStatus": self.status,
+            "changedPaths": list(self.changed_paths),
+            "sourceChanged": self.source_changed,
+            "gitChanged": self.git_changed,
+            "attribution": self.attribution,
+            "retryAllowed": self.retry_allowed,
+            "violations": list(self.violations),
+            "beforeDigest": self.before_digest,
+            "afterDigest": self.after_digest,
+        }
+
+
+class ExecutionMutationAudit:
+    """Capture and compare one invocation batch without global state."""
+
+    def snapshot(
+        self,
+        policies: Sequence[WritePolicy],
+        *,
+        orchestrator_paths: Sequence[Path] = (),
+    ) -> MutationSnapshot:
+        rows = tuple(policies)
+        root, artifact_root = _validate_batch(rows)
+        generated = _generated_paths(rows)
+        file_digests = _content_snapshot(root, generated)
+        artifact_digests = (
+            file_digests
+            if artifact_root == root
+            else _content_snapshot(artifact_root, generated)
+        )
+        scratch_digests = _scratch_snapshot(rows)
+        git_projection = _git_projection(root)
+        orchestrator = tuple(
+            sorted(str(path.resolve()) for path in orchestrator_paths)
+        )
+        policy_digests = tuple(policy.digest for policy in rows)
+        digest = _snapshot_digest(
+            root,
+            artifact_root,
+            policy_digests,
+            file_digests,
+            artifact_digests,
+            scratch_digests,
+            git_projection,
+            orchestrator,
+        )
+        return MutationSnapshot(
+            root=root,
+            artifact_root=artifact_root,
+            policy_digests=policy_digests,
+            file_digests=file_digests,
+            artifact_digests=artifact_digests,
+            scratch_digests=scratch_digests,
+            git_projection=git_projection,
+            digest=digest,
+            orchestrator_paths=orchestrator,
+        )
+
+    def compare(
+        self,
+        before: MutationSnapshot,
+        policies: Sequence[WritePolicy],
+        *,
+        out_of_plan_edits: Sequence[str] = (),
+        attempt_succeeded: bool = True,
+        result_present: bool = True,
+    ) -> MutationAuditResult:
+        rows = tuple(policies)
+        after = self.snapshot(
+            rows,
+            orchestrator_paths=tuple(Path(path) for path in before.orchestrator_paths),
+        )
+        _validate_snapshot_authority(before, after, rows)
+        changed = _changed_keys(before.file_digests, after.file_digests)
+        artifact_changed = _changed_keys(
+            before.artifact_digests, after.artifact_digests
+        )
+        scratch_changed = _changed_keys(
+            before.scratch_digests, after.scratch_digests
+        )
+        source_changes = _source_changes(changed, rows, before)
+        git_changed = before.git_projection != after.git_projection
+        violations = _policy_violations(
+            before,
+            after,
+            rows,
+            source_changes,
+            out_of_plan_edits,
+        )
+        violations.extend(
+            _artifact_policy_failures(before, rows, artifact_changed)
+        )
+        status = _terminal_status(
+            rows,
+            source_changed=bool(source_changes),
+            git_changed=git_changed,
+            attempt_succeeded=attempt_succeeded,
+            result_present=result_present,
+            violations=violations,
+        )
+        retry_allowed = _retry_allowed(
+            status, bool(source_changes), git_changed, bool(scratch_changed)
+        )
+        return MutationAuditResult(
+            status=status,
+            changed_paths=tuple(sorted(source_changes)),
+            source_changed=bool(source_changes),
+            git_changed=git_changed,
+            attribution="batch-unattributed",
+            retry_allowed=retry_allowed,
+            violations=tuple(violations),
+            before_digest=before.digest,
+            after_digest=after.digest,
+            git_projection=after.git_projection,
+        )
+
+
+def _validate_batch(policies: tuple[WritePolicy, ...]) -> tuple[Path, Path]:
+    if not policies:
+        raise MutationAuditError("mutation audit requires at least one policy")
+    roots = {Path(str(row.source_policy["allowedRoot"])).resolve() for row in policies}
+    artifact_roots = {
+        Path(str(row.artifact_policy["allowedRoot"])).resolve()
+        for row in policies
+    }
+    if len(roots) != 1:
+        raise MutationAuditError("one mutation batch must use one assigned worktree")
+    if len(artifact_roots) != 1:
+        raise MutationAuditError("one mutation batch must use one artifact root")
+    mutation = any(row.source_mode == "project-mutation" for row in policies)
+    non_exact_readonly = any(
+        row.source_mode == "source-readonly"
+        and _maximum_precision(row) != "exact-path"
+        for row in policies
+    )
+    if mutation and non_exact_readonly:
+        raise MutationAuditError(
+            "project mutation and non-exact readonly calls must run in separate batches"
+        )
+    return next(iter(roots)), next(iter(artifact_roots))
+
+
+def _validate_snapshot_authority(
+    before: MutationSnapshot,
+    after: MutationSnapshot,
+    policies: tuple[WritePolicy, ...],
+) -> None:
+    expected = tuple(policy.digest for policy in policies)
+    if (
+        before.root != after.root
+        or before.artifact_root != after.artifact_root
+        or before.policy_digests != expected
+    ):
+        raise MutationAuditError("mutation snapshot does not match batch policies")
+
+
+def _maximum_precision(policy: WritePolicy) -> str:
+    return policy.maximum_boundary_precision
+
+
+def _content_snapshot(root: Path, generated: frozenset[str]) -> dict[str, str]:
+    rows: dict[str, str] = {}
+    for current, directories, filenames in os.walk(root, followlinks=False):
+        current_path = Path(current)
+        traversable: list[str] = []
+        for name in sorted(directories):
+            path = current_path / name
+            relative_path = path.relative_to(root)
+            if name == ".git" or _excluded(relative_path, generated):
+                continue
+            if path.is_symlink():
+                rows[relative_path.as_posix()] = _path_digest(path)
+                continue
+            traversable.append(name)
+        directories[:] = traversable
+        for name in sorted(filenames):
+            path = current_path / name
+            relative = path.relative_to(root).as_posix()
+            if relative == ".git" or _excluded(Path(relative), generated):
+                continue
+            rows[relative] = _path_digest(path)
+    return rows
+
+
+def _scratch_snapshot(policies: Sequence[WritePolicy]) -> dict[str, str]:
+    roots = {
+        Path(value)
+        for policy in policies
+        for value in policy.auxiliary_policy.get("scratchRoots", ())
+    }
+    rows: dict[str, str] = {}
+    for root in sorted(roots):
+        if not root.exists():
+            continue
+        if root.is_file() or root.is_symlink():
+            rows[str(root)] = _path_digest(root)
+            continue
+        for path in sorted(item for item in root.rglob("*") if not item.is_dir()):
+            rows[str(path)] = _path_digest(path)
+    return rows
+
+
+def _path_digest(path: Path) -> str:
+    if path.is_symlink():
+        value = b"symlink:" + os.readlink(path).encode("utf-8")
+    else:
+        value = path.read_bytes()
+    return "sha256:" + hashlib.sha256(value).hexdigest()
+
+
+def _excluded(path: Path, generated: frozenset[str]) -> bool:
+    relative = path.as_posix()
+    return any(relative == item or relative.startswith(item + "/") for item in generated)
+
+
+def _generated_paths(policies: Sequence[WritePolicy]) -> frozenset[str]:
+    return frozenset(
+        path
+        for policy in policies
+        for path in policy.auxiliary_policy.get("generatedPaths", ())
+    )
+
+
+def _git_projection(root: Path) -> dict[str, Any]:
+    probe = subprocess.run(
+        ["git", "-C", str(root), "rev-parse", "--is-inside-work-tree"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if probe.returncode != 0:
+        return {"available": False}
+    git_dir = Path(_git_output(root, "rev-parse", "--path-format=absolute", "--git-dir"))
+    common_dir = Path(
+        _git_output(root, "rev-parse", "--path-format=absolute", "--git-common-dir")
+    )
+    branch_ref = _git_output(root, "symbolic-ref", "-q", "HEAD")
+    head = _git_output(root, "rev-parse", "HEAD")
+    index_path = Path(_git_output(root, "rev-parse", "--path-format=absolute", "--git-path", "index"))
+    return {
+        "available": True,
+        "head": head,
+        "allowedBranchRef": branch_ref,
+        "branchCommit": _git_output(root, "rev-parse", branch_ref),
+        "gitDir": str(git_dir.resolve()),
+        "gitCommonDir": str(common_dir.resolve()),
+        "indexDigest": _optional_file_digest(index_path),
+        "stagedPaths": sorted(_git_changed_paths(root, "--cached")),
+        "worktreeRegistration": _worktree_registration(root),
+        "reflogDigest": _reflog_digest(root),
+    }
+
+
+def _worktree_registration(root: Path) -> str:
+    output = _git_output(root, "worktree", "list", "--porcelain")
+    blocks = output.split("\n\n")
+    prefix = f"worktree {root.resolve()}\n"
+    block = next((item for item in blocks if (item + "\n").startswith(prefix)), "")
+    stable_lines = [
+        line for line in block.splitlines()
+        if not line.startswith("HEAD ")
+    ]
+    return "\n".join(stable_lines)
+
+
+def _optional_file_digest(path: Path) -> str | None:
+    return _path_digest(path) if path.is_file() else None
+
+
+def _git_output(root: Path, *args: str) -> str:
+    result = subprocess.run(
+        ["git", "-C", str(root), *args],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        raise MutationAuditError(result.stderr.strip() or "Git projection failed")
+    return result.stdout.strip()
+
+
+def _snapshot_digest(
+    root: Path,
+    artifact_root: Path,
+    policy_digests: Sequence[str],
+    files: Mapping[str, str],
+    artifacts: Mapping[str, str],
+    scratch: Mapping[str, str],
+    git_projection: Mapping[str, Any],
+    orchestrator_paths: Sequence[str],
+) -> str:
+    encoded = json.dumps(
+        {
+            "root": str(root),
+            "artifactRoot": str(artifact_root),
+            "policyDigests": list(policy_digests),
+            "files": files,
+            "artifacts": artifacts,
+            "scratch": scratch,
+            "gitProjection": git_projection,
+            "orchestratorPaths": list(orchestrator_paths),
+        },
+        sort_keys=True,
+        separators=(",", ":"),
+    ).encode("utf-8")
+    return "sha256:" + hashlib.sha256(encoded).hexdigest()
+
+
+def _changed_keys(before: Mapping[str, str], after: Mapping[str, str]) -> set[str]:
+    return {
+        key for key in set(before) | set(after) if before.get(key) != after.get(key)
+    }
+
+
+def _source_changes(
+    changed: set[str],
+    policies: Sequence[WritePolicy],
+    snapshot: MutationSnapshot,
+) -> set[str]:
+    artifacts = _allowed_artifact_paths(policies)
+    generated = _generated_paths(policies)
+    orchestrator = {
+        Path(value).relative_to(snapshot.root).as_posix()
+        for value in snapshot.orchestrator_paths
+        if _is_relative_to(Path(value), snapshot.root)
+    }
+    return {
+        path for path in changed
+        if not (
+            snapshot.artifact_root == snapshot.root
+            and any(_is_within(path, item) for item in artifacts)
+        )
+        and path not in orchestrator
+        and not _excluded(Path(path), generated)
+    }
+
+
+def _artifact_policy_failures(
+    snapshot: MutationSnapshot,
+    policies: Sequence[WritePolicy],
+    changed: set[str],
+) -> list[str]:
+    allowed = _allowed_artifact_paths(policies)
+    orchestrator = {
+        Path(value).relative_to(snapshot.artifact_root).as_posix()
+        for value in snapshot.orchestrator_paths
+        if _is_relative_to(Path(value), snapshot.artifact_root)
+    }
+    unauthorized = {
+        path for path in changed
+        if not any(_is_within(path, item) for item in allowed)
+        and path not in orchestrator
+    }
+    if snapshot.artifact_root == snapshot.root:
+        return []
+    return ["artifact-root change exceeds batch policy union"] if unauthorized else []
+
+
+def _allowed_artifact_paths(policies: Sequence[WritePolicy]) -> set[str]:
+    return {
+        path
+        for policy in policies
+        for path in policy.artifact_policy.get("allowedPaths", ())
+    }
+
+
+def _is_relative_to(path: Path, root: Path) -> bool:
+    try:
+        path.relative_to(root)
+    except ValueError:
+        return False
+    return True
+
+
+def _policy_violations(
+    before: MutationSnapshot,
+    after: MutationSnapshot,
+    policies: tuple[WritePolicy, ...],
+    source_changes: set[str],
+    out_of_plan_edits: Sequence[str],
+) -> list[str]:
+    if all(policy.source_mode == "source-readonly" for policy in policies):
+        failures = ["readonly source changed"] if source_changes else []
+        if before.git_projection != after.git_projection:
+            failures.append("gitPolicy disabled but Git projection changed")
+        return failures
+    policy = next(row for row in policies if row.source_mode == "project-mutation")
+    failures = _source_policy_failures(policy, source_changes, out_of_plan_edits)
+    failures.extend(_git_policy_failures(before, after, policy, source_changes, out_of_plan_edits))
+    return failures
+
+
+def _source_policy_failures(
+    policy: WritePolicy,
+    changed: set[str],
+    out_of_plan_edits: Sequence[str],
+) -> list[str]:
+    planned = set(policy.source_policy.get("plannedPaths", ()))
+    declared = set(out_of_plan_edits)
+    protected = set(policy.source_policy.get("protectedPaths", ()))
+    failures: list[str] = []
+    if not changed <= planned | declared:
+        failures.append("source changes exceed planned and declared out-of-plan paths")
+    if not declared <= changed:
+        failures.append("declared out-of-plan path did not change")
+    if any(_is_within(path, item) for path in changed for item in protected):
+        failures.append("protected path changed")
+    return failures
+
+
+def _git_policy_failures(
+    before: MutationSnapshot,
+    after: MutationSnapshot,
+    policy: WritePolicy,
+    changed: set[str],
+    out_of_plan_edits: Sequence[str],
+) -> list[str]:
+    git = policy.git_policy
+    root = before.root
+    failures: list[str] = []
+    if before.git_projection.get("head") != git.get("expectedBaseCommit"):
+        failures.append("audit baseline does not match expectedBaseCommit")
+    if after.git_projection.get("allowedBranchRef") != git.get("allowedBranchRef"):
+        failures.append("assigned branch changed")
+    if after.git_projection.get("gitDir") != git.get("worktreeGitDir"):
+        failures.append("assigned worktree Git directory changed")
+    if after.git_projection.get("gitCommonDir") != git.get("gitCommonDir"):
+        failures.append("assigned Git common directory changed")
+    if before.git_projection.get("worktreeRegistration") != after.git_projection.get("worktreeRegistration"):
+        failures.append("worktree registration changed")
+    if after.git_projection.get("stagedPaths"):
+        failures.append("final Git index contains staged changes")
+    if not _is_ancestor(root, str(git.get("expectedBaseCommit")), str(after.git_projection.get("head"))):
+        failures.append("final HEAD is not a fast-forward descendant")
+    allowed = set(policy.source_policy.get("plannedPaths", ())) | set(out_of_plan_edits)
+    if any(
+        not paths <= allowed
+        for paths in _commit_paths_by_commit(
+            root,
+            str(git.get("expectedBaseCommit")),
+            str(after.git_projection.get("head")),
+        )
+    ):
+        failures.append("commit chain changed paths outside source policy")
+    if not changed <= allowed:
+        failures.append("working tree changed paths outside source policy")
+    return failures
+
+
+def _is_ancestor(root: Path, base: str, head: str) -> bool:
+    result = subprocess.run(
+        ["git", "-C", str(root), "merge-base", "--is-ancestor", base, head],
+        capture_output=True,
+        check=False,
+    )
+    return result.returncode == 0
+
+
+def _commit_paths_by_commit(root: Path, base: str, head: str) -> tuple[set[str], ...]:
+    if base == head:
+        return ()
+    commits = _git_output(root, "rev-list", "--reverse", f"{base}..{head}").splitlines()
+    return tuple(
+        {
+            line
+            for line in _git_output(
+                root, "diff-tree", "--no-commit-id", "--name-only", "-r", commit
+            ).splitlines()
+            if line
+        }
+        for commit in commits
+    )
+
+
+def _reflog_digest(root: Path) -> str:
+    payload = _git_output(root, "reflog", "show", "--no-abbrev", "--format=%H %gs", "HEAD")
+    return "sha256:" + hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def _git_changed_paths(root: Path, *args: str) -> set[str]:
+    result = subprocess.run(
+        ["git", "-C", str(root), "diff", *args, "--name-only"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        raise MutationAuditError(result.stderr.strip() or "Git diff failed")
+    return {line for line in result.stdout.splitlines() if line}
+
+
+def _is_within(path: str, parent: str) -> bool:
+    return path == parent or path.startswith(parent + "/")
+
+
+def _terminal_status(
+    policies: Sequence[WritePolicy],
+    *,
+    source_changed: bool,
+    git_changed: bool,
+    attempt_succeeded: bool,
+    result_present: bool,
+    violations: Sequence[str],
+) -> str:
+    project_mutation = any(row.source_mode == "project-mutation" for row in policies)
+    if project_mutation and (source_changed or git_changed) and (
+        not attempt_succeeded or not result_present
+    ):
+        return "mutation-present-unresolved"
+    if violations:
+        return "contract-failed-unattributed"
+    if not attempt_succeeded or not result_present:
+        return "failed-no-mutation"
+    return "ok"
+
+
+def _retry_allowed(
+    status: str,
+    source_changed: bool,
+    git_changed: bool,
+    scratch_changed: bool,
+) -> bool:
+    if status in {"mutation-present-unresolved", "contract-failed-unattributed"}:
+        return False
+    if source_changed or git_changed:
+        return False
+    return status == "failed-no-mutation" and not scratch_changed

package/runtime/python/okstra_ctl/implementation_outcome.py

@@ -11,9 +11,10 @@ from .consumers import (
     carry_head_commit,
     read_stage_consumer_state,
 )
+from . import next_phase
 from .paths import RunRef, task_manifest_file
 from .stage_map import StageMapError, load_task_stage_map
-from .workflow import DEFAULT_NEXT_PHASE, PHASE_SEQUENCE
+from .workflow import PHASE_SEQUENCE
 
 
 @dataclass(frozen=True)
@@ -22,7 +23,6 @@ class ImplementationOutcome:
     stages: list[int] = field(default_factory=list)
     head_commit: str = ""
     report_path: str = ""
-    next_recommended_phase: str = ""
     reason: str = ""
 
 
@@ -66,7 +66,6 @@ def derive_implementation_outcome(task_root: Path) -> ImplementationOutcome:
         stages=sorted(required_stages),
         head_commit=str(latest_done.get("head_commit") or "") or carry_head_commit(latest_carry),
         report_path=_latest_implementation_report(task_root),
-        next_recommended_phase=DEFAULT_NEXT_PHASE["implementation"],
         reason="all implementation stages have pass-grade carry and done rows",
     )
 
@@ -174,7 +173,22 @@ def _promote_workflow(workflow: dict[str, Any], outcome: ImplementationOutcome)
     workflow["currentPhaseState"] = "completed"
     phase_states["implementation"] = "completed"
     workflow["lastCompletedPhase"] = "implementation"
-    workflow["nextRecommendedPhase"] = outcome.next_recommended_phase
+    # 재조정기의 사실은 "모든 stage 가 끝났다"는 상태다. 대상 phase 는 마지막
+    # stage 검증이 이미 정했으므로 건드리지 않는다 (ADR-0004).
+    #
+    # 대상 phase 가 비어 있으면 status 도 올리지 않는다. `ready` 는 "지금 이
+    # phase 를 시작할 수 있다"는 뜻인데 가리킬 phase 가 없으면 시작할 대상이
+    # 없다. 마지막 stage 리포트에 라우팅 대상이 없으면 이 자리에 빈 phase 의
+    # pending 포인터가 들어오므로, 그때는 그대로 둔다.
+    pointer = next_phase.promote(workflow.get("nextRecommendedPhase"))
+    if pointer["phase"]:
+        workflow["nextRecommendedPhase"] = next_phase.make(
+            phase=pointer["phase"],
+            status=next_phase.STATUS_READY,
+            rationale=pointer["rationale"],
+        )
+    else:
+        workflow["nextRecommendedPhase"] = pointer
     after = json.dumps(workflow, sort_keys=True, ensure_ascii=False)
     return before != after
 
@@ -195,7 +209,9 @@ def _update_task_catalog(project_root: Path, manifest: dict[str, Any]) -> bool:
         entry["currentPhase"] = workflow.get("currentPhase", "")
         entry["currentPhaseState"] = workflow.get("currentPhaseState", "")
         entry["lastCompletedPhase"] = workflow.get("lastCompletedPhase", "")
-        entry["nextRecommendedPhase"] = workflow.get("nextRecommendedPhase", "")
+        entry["nextRecommendedPhase"] = next_phase.promote(
+            workflow.get("nextRecommendedPhase")
+        )
         entry["latestReportPath"] = manifest.get("latestReportPath", "")
         entry["latestRunStatus"] = manifest.get("latestRunStatus", entry.get("latestRunStatus", ""))
         entry["currentStatus"] = manifest.get("currentStatus", entry.get("currentStatus", ""))

package/runtime/python/okstra_ctl/index.py

@@ -39,7 +39,9 @@ def record_start(home: Path, *, project_id: str, project_root: str,
                  okstra_version: str = "",
                  brief_sha256: str = "",
                  initial_status: str = "running",
-                 final_status_rel: str = "") -> str:
+                 final_status_rel: str = "",
+                 execution_manifest_path: str = "",
+                 role_execution_refs: list | None = None) -> str:
     """run 시작 시점의 인덱스/invocation/meta 를 1 트랜잭션으로 기록.
     반환값: 생성된 runId.
     """
@@ -54,7 +56,9 @@ def record_start(home: Path, *, project_id: str, project_root: str,
         finished_at=when if is_terminal else None,
         workers=workers, lead_model=lead_model, validation="not-run",
         run_dir_rel=run_dir_rel, final_report_rel=final_report_rel,
-        final_status_rel=final_status_rel)
+        final_status_rel=final_status_rel,
+        execution_manifest_path=execution_manifest_path,
+        role_execution_refs=role_execution_refs)
     # okstra-ctl 가 미리 'reserving' 예약 row 를 작성했을 수 있다(P1-2). 같은
     # runId 의 예약 row 가 있으면 update; 없으면 append.
     existing_rows = read_jsonl(home / "active.jsonl")