Coverage for src/governed_harness/application/isolation.py: 88%
138 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
1"""Worktree isolation per run (#55, item 9; ``workspace.isolation``).
3``harness run start --isolate worktree`` (or ``workspace.isolation.mode: worktree``) runs the
4phases in a Git worktree of their own, on a new branch made from the updated base branch, so
5that several runs proceed in parallel without touching the person's working tree:
71. the base is ``isolation.base`` (default: the current branch); with ``fetch`` (default) and a
8 remote, the harness fetches it first and branches from the remote's copy;
92. the branch is ``isolation.branch`` (``harness/{taskId}-{runId}`` by default, or the branch the
10 task's operational contract names) and the worktree goes under ``isolation.directory``
11 (``.harness/worktrees/<run>``);
123. the project configuration is copied into the worktree's ``.harness/`` with a marker
13 (``isolation.json``) that names the run registry of the workspace it came from, so the run is
14 recorded where the person looks for it and ``harness status``, ``review`` or ``gate decide``
15 work from either directory.
17A branch or a directory that already exists is a collision: the run is ``BLOCKED`` with the
18reason and a ``stop.condition`` (``destructive-collision``) event; the harness never resets,
19deletes or reuses what it did not create, and ``run continue`` tries again once a person
20resolved it. ``harness run cleanup`` removes a closed run's worktree (never its branch), and only
21a worktree the harness created and that has no uncommitted change."""
23from __future__ import annotations
25import json
26import shutil
27from pathlib import Path
28from typing import TYPE_CHECKING, Any
30from governed_harness.configuration.ladder import IsolationConfig
31from governed_harness.delivery.vcs import Git, VcsError
32from governed_harness.domain.enums import PhaseId, ResultStatus
33from governed_harness.domain.errors import ConfigurationError, PolicyViolationError
34from governed_harness.domain.ids import new_id
35from governed_harness.domain.models import Execution, Task, utc_now
36from governed_harness.runtime.state_location import ISOLATION_MARKER
38if TYPE_CHECKING:
39 from governed_harness.orchestration.engine import EngineServices, RunEngine
41ISOLATION_FLAG = "isolation"
42_HARNESS_DIR = ".harness"
43GENERATED_DIRECTORIES = frozenset(
44 {_HARNESS_DIR, "__pycache__", ".pytest_cache", ".mypy_cache", ".ruff_cache", ".coverage"}
45)
46"""What a run leaves untracked in its worktree (the harness's directory, tool caches)."""
49def _generated(path: str) -> bool:
50 return any(part in GENERATED_DIRECTORIES for part in Path(path.rstrip("/")).parts)
53def isolation_record(services: EngineServices, execution_id: str) -> dict[str, Any] | None:
54 raw = services.state.get_flag(f"{ISOLATION_FLAG}:{execution_id}")
55 value = json.loads(raw) if raw else None
56 return value if isinstance(value, dict) else None
59def _branch(settings: IsolationConfig, task: Task, run_id: str) -> str:
60 if task.contract is not None and task.contract.branch: 60 ↛ 61line 60 didn't jump to line 61 because the condition on line 60 was never true
61 return task.contract.branch
62 return settings.branch_template.replace("{taskId}", task.task_id).replace("{runId}", run_id)
65def plan_worktree(
66 services: EngineServices, task: Task, run_id: str, settings: IsolationConfig
67) -> dict[str, Any]:
68 """Where the worktree goes, on which branch and from which base, and any collision."""
69 workspace = services.paths.workspace
70 git = Git(workspace)
71 if not git.is_repository() or git.resolve("HEAD") is None: 71 ↛ 72line 71 didn't jump to line 72 because the condition on line 71 was never true
72 raise ConfigurationError(
73 "worktree isolation needs a Git repository with at least one commit"
74 )
75 branch = _branch(settings, task, run_id)
76 directory = workspace / settings.worktree_directory / run_id
77 current = git.run("symbolic-ref", "--quiet", "--short", "HEAD", check=False)
78 base = settings.base or current.stdout.decode("utf-8", "replace").strip() or "HEAD"
79 remote = settings.remote or "origin"
80 plan: dict[str, Any] = {
81 "branch": branch,
82 "directory": str(directory),
83 "base": base,
84 "remote": None,
85 "fetched": False,
86 "collision": None,
87 }
88 if git.resolve(f"refs/heads/{branch}") is not None:
89 plan["collision"] = f"branch {branch} already exists"
90 elif directory.exists(): 90 ↛ 91line 90 didn't jump to line 91 because the condition on line 90 was never true
91 plan["collision"] = f"directory {directory} already exists"
92 has_remote = git.run("remote", "get-url", remote, check=False).returncode == 0
93 fetch = settings.fetch is not False
94 if plan["collision"] is None and fetch and has_remote and base != "HEAD":
95 try:
96 git.run("fetch", "--quiet", remote, base)
97 except VcsError as error:
98 plan["collision"] = (
99 f"the base branch {base} could not be fetched from {remote}: {error}"
100 )
101 else:
102 plan["remote"] = remote
103 plan["fetched"] = True
104 start = f"{remote}/{base}" if plan["fetched"] else base
105 commit = git.resolve(start)
106 if plan["collision"] is None and commit is None: 106 ↛ 107line 106 didn't jump to line 107 because the condition on line 106 was never true
107 plan["collision"] = f"the base {start} does not resolve to a commit"
108 plan["start"] = start
109 plan["baseCommit"] = commit
110 return plan
113def create_worktree(services: EngineServices, run_id: str, plan: dict[str, Any]) -> Path:
114 """Create the worktree and its ``.harness/`` (configuration and marker)."""
115 workspace = services.paths.workspace
116 directory = Path(plan["directory"])
117 directory.parent.mkdir(parents=True, exist_ok=True)
118 Git(workspace).run("worktree", "add", "-b", plan["branch"], str(directory), plan["start"])
119 harness = directory / _HARNESS_DIR
120 harness.mkdir(parents=True, exist_ok=True, mode=0o700)
121 shutil.copyfile(services.paths.harness_dir / "project.yaml", harness / "project.yaml")
122 state_root = services.paths.state_root or services.paths.harness_dir
123 marker = {
124 "schemaVersion": "1.0",
125 "createdBy": "governed-harness",
126 "executionId": run_id,
127 "origin": str(workspace),
128 "stateRoot": str(state_root),
129 "branch": plan["branch"],
130 "base": plan["base"],
131 "baseCommit": plan["baseCommit"],
132 "createdAt": utc_now().isoformat(),
133 }
134 (harness / ISOLATION_MARKER).write_text(
135 json.dumps(marker, indent=2, sort_keys=True) + "\n", encoding="utf-8"
136 )
137 return directory
140def start_isolated(
141 open_services: Any,
142 services: EngineServices,
143 task: Task,
144 provider: str | None,
145 settings: IsolationConfig,
146) -> tuple[Execution, EngineServices | None]:
147 """Create the run in its own worktree. Returns the run and the services of the worktree
148 (``None`` on a collision: the run is recorded BLOCKED in the workspace's registry)."""
149 from governed_harness.orchestration.engine import RunEngine
151 run_id = new_id("run")
152 plan = plan_worktree(services, task, run_id, settings)
153 if plan["collision"] is not None:
154 engine = RunEngine(services)
155 execution = engine.create_execution(task, provider=provider, execution_id=run_id)
156 return block_collision(services, engine, execution, plan), None
157 directory = create_worktree(services, run_id, plan)
158 isolated = open_services(directory)
159 engine = RunEngine(isolated)
160 execution = engine.create_execution(task, provider=provider, execution_id=run_id)
161 record = {**plan, "status": "CREATED", "origin": str(services.paths.workspace)}
162 isolated.state.set_flag(f"{ISOLATION_FLAG}:{run_id}", json.dumps(record, sort_keys=True))
163 isolated.events.append(run_id, "isolation.created", record)
164 return execution, isolated
167def block_collision(
168 services: EngineServices, engine: RunEngine, execution: Execution, plan: dict[str, Any]
169) -> Execution:
170 record = {**plan, "status": "COLLISION", "origin": str(services.paths.workspace)}
171 services.state.set_flag(
172 f"{ISOLATION_FLAG}:{execution.execution_id}", json.dumps(record, sort_keys=True)
173 )
174 services.events.append(execution.execution_id, "isolation.collision", record)
175 services.events.append(
176 execution.execution_id,
177 "stop.condition",
178 {"condition": "destructive-collision", "detail": plan["collision"]},
179 )
180 blocked = execution.model_copy(
181 update={
182 "status": ResultStatus.BLOCKED,
183 "terminal_reason": (
184 f"Isolation collision: {plan['collision']}. The harness never resets or "
185 "deletes it; resolve it and harness run continue"
186 ),
187 "updated_at": utc_now(),
188 }
189 )
190 engine._save_execution(blocked)
191 return blocked
194def retry_isolation(
195 open_services: Any, services: EngineServices, execution: Execution
196) -> tuple[Execution, EngineServices | None]:
197 """``run continue`` on a run blocked by a collision: plan again, create the worktree when
198 the collision is gone."""
199 from governed_harness.orchestration.engine import RunEngine
201 engine = RunEngine(services)
202 task = engine.run_task(execution)
203 settings = services.resolved.project.workspace.isolation or IsolationConfig(mode="worktree")
204 plan = plan_worktree(services, task, execution.execution_id, settings)
205 if plan["collision"] is not None: 205 ↛ 206line 205 didn't jump to line 206 because the condition on line 205 was never true
206 return block_collision(services, engine, execution, plan), None
207 directory = create_worktree(services, execution.execution_id, plan)
208 isolated = open_services(directory)
209 record = {**plan, "status": "CREATED", "origin": str(services.paths.workspace)}
210 isolated.state.set_flag(
211 f"{ISOLATION_FLAG}:{execution.execution_id}", json.dumps(record, sort_keys=True)
212 )
213 isolated.events.append(execution.execution_id, "isolation.created", record)
214 moved = execution.model_copy(
215 update={
216 "workspace": str(directory.resolve()),
217 "status": ResultStatus.PENDING,
218 "terminal_reason": None,
219 "updated_at": utc_now(),
220 }
221 )
222 RunEngine(isolated)._save_execution(moved)
223 return moved, isolated
226def cleanup_worktree(services: EngineServices, execution: Execution) -> dict[str, Any]:
227 """Remove the worktree of a finished isolated run: only one the harness created, without
228 uncommitted changes, never its branch."""
229 from governed_harness.orchestration.engine import run_is_open
231 record = isolation_record(services, execution.execution_id)
232 if record is None or record.get("status") != "CREATED": 232 ↛ 233line 232 didn't jump to line 233 because the condition on line 232 was never true
233 raise PolicyViolationError(
234 f"run {execution.execution_id} has no worktree the harness created"
235 )
236 if run_is_open(execution) and execution.current_phase is not PhaseId.CLOSURE: 236 ↛ 237line 236 didn't jump to line 237 because the condition on line 236 was never true
237 raise PolicyViolationError(f"run {execution.execution_id} is still open")
238 directory = Path(record["directory"])
239 marker = directory / _HARNESS_DIR / ISOLATION_MARKER
240 if not marker.is_file(): 240 ↛ 241line 240 didn't jump to line 241 because the condition on line 240 was never true
241 raise PolicyViolationError(f"{directory} is not a worktree the harness created")
242 origin = Path(record.get("origin") or services.paths.workspace)
243 git = Git(origin)
244 status = Git(directory).run("status", "--porcelain", "--untracked-files=normal", check=False)
245 changes = [
246 line
247 for line in status.stdout.decode("utf-8", "replace").splitlines()
248 if line[3:].strip() and not _generated(line[3:].strip().strip('"'))
249 ]
250 if changes:
251 raise PolicyViolationError(
252 f"the worktree {directory} has {len(changes)} uncommitted change(s); the harness "
253 "does not delete them"
254 )
255 for line in status.stdout.decode("utf-8", "replace").splitlines():
256 # What the harness and the validators wrote there: its own directory and caches.
257 target = directory / line[3:].strip().strip('"').rstrip("/")
258 if line.startswith("??") and _generated(line[3:].strip()) and target.is_dir(): 258 ↛ 255line 258 didn't jump to line 255 because the condition on line 258 was always true
259 shutil.rmtree(target)
260 if (directory / _HARNESS_DIR).is_dir(): 260 ↛ 261line 260 didn't jump to line 261 because the condition on line 260 was never true
261 shutil.rmtree(directory / _HARNESS_DIR)
262 git.run("worktree", "remove", str(directory))
263 updated = {**record, "status": "REMOVED", "removedAt": utc_now().isoformat()}
264 services.state.set_flag(
265 f"{ISOLATION_FLAG}:{execution.execution_id}", json.dumps(updated, sort_keys=True)
266 )
267 services.events.append(execution.execution_id, "isolation.removed", updated)
268 return updated
271__all__ = [
272 "ISOLATION_FLAG",
273 "block_collision",
274 "cleanup_worktree",
275 "create_worktree",
276 "isolation_record",
277 "plan_worktree",
278 "retry_isolation",
279 "start_isolated",
280]