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

1"""Worktree isolation per run (#55, item 9; ``workspace.isolation``). 

2 

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: 

6 

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. 

16 

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.""" 

22 

23from __future__ import annotations 

24 

25import json 

26import shutil 

27from pathlib import Path 

28from typing import TYPE_CHECKING, Any 

29 

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 

37 

38if TYPE_CHECKING: 

39 from governed_harness.orchestration.engine import EngineServices, RunEngine 

40 

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).""" 

47 

48 

49def _generated(path: str) -> bool: 

50 return any(part in GENERATED_DIRECTORIES for part in Path(path.rstrip("/")).parts) 

51 

52 

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 

57 

58 

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) 

63 

64 

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 

111 

112 

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 

138 

139 

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 

150 

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 

165 

166 

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 

192 

193 

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 

200 

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 

224 

225 

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 

230 

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 

269 

270 

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]