kanban_db_workspace.py 34 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843
  1. """Task workspace lifecycle: scratch/dir/worktree resolution (incl. git worktree creation), post-completion cleanup with containment guards, worker tmux teardown and the first-use scratch-workspace tip.
  2. Split out of ``hermes_cli.kanban_db``; origin-resident helpers are reached
  3. late-bound via ``_kb`` (import-cycle breaking) so monkeypatching
  4. ``kanban_db.<name>`` keeps working.
  5. """
  6. from __future__ import annotations
  7. import os
  8. import shutil
  9. import sqlite3
  10. import subprocess
  11. import time
  12. import unicodedata
  13. from pathlib import Path
  14. from typing import Optional
  15. from typing import TYPE_CHECKING
  16. import contextlib
  17. from hermes_cli.worktree_ops import release_lsp_clients
  18. if TYPE_CHECKING:
  19. from hermes_cli.kanban_db import Task
  20. _REMOVABLE_KINDS = ("scratch", "worktree")
  21. def _path_key(path: Path | str | None) -> str:
  22. """Unicode-form-insensitive identity for a filesystem path.
  23. macOS hands back DECOMPOSED path strings (NFD: ``o`` + U+0308) for names the
  24. user typed in composed form (NFC: ``ö``) — a OneDrive/FileProvider path like
  25. ``OneDrive-Persönlich`` round-trips through ``git rev-parse --show-toplevel``
  26. as NFD while the DB row holds NFC. Raw ``Path`` equality then reports a real
  27. repo root as "not a repo" purely on Unicode form, so every path identity
  28. check here goes through this key.
  29. """
  30. return unicodedata.normalize("NFC", str(path)) if path is not None else ""
  31. # Statuses after which a task no longer needs a workspace: a child stops
  32. # needing its parent's handoff artifacts, and a sharer stops holding a dir.
  33. _TERMINAL_STATUSES_SQL = "('done', 'archived', 'failed', 'cancelled')"
  34. _ACTIVE_CHILDREN_SQL = (
  35. "SELECT 1 FROM task_links l "
  36. "JOIN tasks t ON t.id = l.child_id "
  37. f"WHERE l.parent_id = ? AND t.status NOT IN {_TERMINAL_STATUSES_SQL} "
  38. "LIMIT 1"
  39. )
  40. _WORKSPACE_ROW_SQL = "SELECT workspace_kind, workspace_path, branch_name FROM tasks WHERE id = ?"
  41. def _git(repo_root: Path, *args: str, timeout: int) -> subprocess.CompletedProcess:
  42. """``git -C repo_root args``; never raises on a non-zero exit.
  43. :func:`noninteractive_repo_git_env` (GHSA-7x36-8jrh-v4pw): the dispatcher runs ``worktree add``
  44. unattended, which executes the repo's hooks, ``core.fsmonitor`` and smudge filters.
  45. """
  46. from hermes_cli._subprocess_compat import FILTER_DISCOVERY_FAILED, noninteractive_repo_git_env
  47. env = noninteractive_repo_git_env(repo_root)
  48. if env is None:
  49. return subprocess.CompletedProcess(["git", "-C", str(repo_root), *args], 1, "", FILTER_DISCOVERY_FAILED)
  50. return subprocess.run(
  51. ["git", "-C", str(repo_root), *args],
  52. capture_output=True,
  53. text=True, encoding='utf-8', errors='replace',
  54. timeout=timeout,
  55. check=False,
  56. stdin=subprocess.DEVNULL,
  57. env=env,
  58. )
  59. def _has_active_children(conn: sqlite3.Connection, task_id: str) -> bool:
  60. return conn.execute(_ACTIVE_CHILDREN_SQL, (task_id,)).fetchone() is not None
  61. _TERMINAL_TASK_SQL = (
  62. f"SELECT 1 FROM tasks WHERE id = ? AND status IN {_TERMINAL_STATUSES_SQL}"
  63. )
  64. def _is_terminal_task(conn: sqlite3.Connection, task_id: str) -> bool:
  65. return conn.execute(_TERMINAL_TASK_SQL, (task_id,)).fetchone() is not None
  66. _OTHER_LIVE_PATHS_SQL = (
  67. "SELECT workspace_path FROM tasks "
  68. "WHERE id != ? AND workspace_path IS NOT NULL "
  69. f"AND status NOT IN {_TERMINAL_STATUSES_SQL}"
  70. )
  71. # Sibling boards mint their own ids, so the id being cleaned up here can
  72. # name a different live task there. Do not exclude it.
  73. _ANY_LIVE_PATHS_SQL = (
  74. "SELECT workspace_path FROM tasks "
  75. "WHERE workspace_path IS NOT NULL "
  76. f"AND status NOT IN {_TERMINAL_STATUSES_SQL}"
  77. )
  78. def _conn_uses_path(
  79. conn: sqlite3.Connection, task_id: str, key: str, *, exclude_task_id: bool = True
  80. ) -> bool:
  81. if exclude_task_id:
  82. rows = conn.execute(_OTHER_LIVE_PATHS_SQL, (task_id,)).fetchall()
  83. else:
  84. rows = conn.execute(_ANY_LIVE_PATHS_SQL).fetchall()
  85. for row in rows:
  86. other = row["workspace_path"]
  87. if not other:
  88. continue
  89. try:
  90. other_key = _path_key(Path(other).expanduser().resolve(strict=False))
  91. except OSError:
  92. continue
  93. if other_key == key:
  94. return True
  95. return False
  96. def _sibling_board_db_files(conn: sqlite3.Connection) -> list[Path]:
  97. """Every other board's ``kanban.db``. Raises ``OSError`` when the set is unknown.
  98. ``kanban_db_path`` follows ``HERMES_KANBAN_DB`` and would collapse every
  99. slug onto the pinned file, so the scan uses the on-disk layout: the
  100. default board at ``<home>/kanban.db`` and named boards at
  101. ``<home>/kanban/boards/<slug>/kanban.db``.
  102. """
  103. from hermes_cli.kanban_db_connect import _main_db_file # late: import cycle
  104. current_file = _main_db_file(conn)
  105. current = Path(current_file).resolve() if current_file else None
  106. candidates = [_kb.kanban_home() / "kanban.db"]
  107. root = _kb.boards_root()
  108. if root.is_dir():
  109. for child in root.iterdir():
  110. if child.is_dir():
  111. candidates.append(child / "kanban.db")
  112. found: list[Path] = []
  113. seen: set[Path] = set()
  114. for path in candidates:
  115. if not path.is_file():
  116. continue
  117. resolved = path.resolve()
  118. if current is not None and resolved == current:
  119. continue
  120. if resolved in seen:
  121. continue
  122. seen.add(resolved)
  123. found.append(resolved)
  124. return found
  125. def _other_board_uses_path(db_file: Path, task_id: str, key: str) -> bool:
  126. uri = db_file.as_uri() + "?mode=ro"
  127. other = sqlite3.connect(uri, uri=True, timeout=1.0)
  128. try:
  129. other.row_factory = sqlite3.Row
  130. return _conn_uses_path(other, task_id, key, exclude_task_id=False)
  131. finally:
  132. other.close()
  133. def _workspace_in_use_by_other(
  134. conn: sqlite3.Connection, task_id: str, path: Path | str
  135. ) -> Optional[str]:
  136. """Why *path* must be kept: ``"shared"``, ``"unknown"``, or None when free.
  137. ``gc``, completion and deferred parent cleanup used to ``rmtree`` a shared
  138. ``workspace_path`` as soon as one of its tasks went terminal. Compare the
  139. resolved path: a row may store ``~`` or a symlinked spelling.
  140. The connection covers one board. A ready task on a named board can point
  141. at the same directory. If that set of databases cannot be read, refuse
  142. the delete (``"unknown"``) and log the board DB that failed, so one broken
  143. sibling DB is not reported as a live sharer.
  144. """
  145. try:
  146. key = _path_key(Path(path).expanduser().resolve(strict=False))
  147. except OSError as exc:
  148. _kb._log.warning("Cannot resolve workspace %s for task %s: %s", path, task_id, exc)
  149. return "unknown"
  150. if not key:
  151. return None
  152. try:
  153. if _conn_uses_path(conn, task_id, key):
  154. return "shared"
  155. except sqlite3.Error as exc:
  156. _kb._log.warning("Cannot read live workspaces for task %s: %s", task_id, exc)
  157. return "unknown"
  158. try:
  159. siblings = _sibling_board_db_files(conn)
  160. except OSError as exc:
  161. _kb._log.warning("Cannot list kanban boards for task %s: %s", task_id, exc)
  162. return "unknown"
  163. for db_file in siblings:
  164. try:
  165. if _other_board_uses_path(db_file, task_id, key):
  166. return "shared"
  167. except (OSError, sqlite3.Error) as exc:
  168. _kb._log.warning(
  169. "Cannot read board db %s for task %s: %s", db_file, task_id, exc,
  170. )
  171. return "unknown"
  172. return None
  173. def _defer_shared_workspace_cleanup(
  174. conn: sqlite3.Connection, task_id: str, path: Path | str
  175. ) -> bool:
  176. """Skip removal and record why, when *path* may still be used by a live task."""
  177. reason = _workspace_in_use_by_other(conn, task_id, path)
  178. if reason is None:
  179. return False
  180. if reason == "shared":
  181. _kb._log.warning(
  182. "Deferring workspace cleanup for task %s: %s is still used by "
  183. "another non-terminal task",
  184. task_id, path,
  185. )
  186. else:
  187. _kb._log.warning(
  188. "Deferring workspace cleanup for task %s: cannot tell whether "
  189. "another task still uses %s",
  190. task_id, path,
  191. )
  192. try:
  193. _kb._append_event(
  194. conn, task_id, "workspace_cleanup_deferred_shared",
  195. {"path": str(path), "reason": reason},
  196. )
  197. except sqlite3.Error:
  198. pass
  199. return True
  200. def _defer_shared_worktree_cleanup(
  201. conn: sqlite3.Connection, task_id: str, path: Path | str
  202. ) -> bool:
  203. """Defer removing a linked worktree another live task may still use.
  204. Only a real linked worktree is ever removed, so the sharing scan runs just
  205. for those.
  206. """
  207. wt = Path(path).expanduser()
  208. return (
  209. wt.is_dir()
  210. and _is_linked_worktree_checkout(wt)
  211. and _defer_shared_workspace_cleanup(conn, task_id, path)
  212. )
  213. def _lexical_path(path: Path | str) -> Path:
  214. """Absolute, ``..``-collapsed, NFC form of *path* WITHOUT following symlinks."""
  215. return Path(_path_key(os.path.abspath(path)))
  216. def _managed_scratch_path_info(p: Path) -> tuple[bool, Optional[str]]:
  217. """Return whether *p* is managed scratch storage and the matching board.
  218. *p* must be strictly below a managed root both after resolving symlinks
  219. AND lexically (as spelled, without resolving). Resolved containment alone
  220. is not enough: when a root is itself a symlink to a broad directory
  221. (relocated storage, or a planted link), every path inside the link target
  222. would resolve "under" the root, so a scratch task naming such a path
  223. directly would get it rmtree'd. Tasks created through the root are spelled
  224. through it, so the lexical check keeps them managed. A root's lexical form
  225. is accepted both as configured and with its anchor (kanban home, or the
  226. override's parent) resolved, so a process spelling a symlinked home by its
  227. real path still matches; the managed ``kanban/.../workspaces`` components
  228. themselves are never resolved for the lexical check.
  229. """
  230. try:
  231. p_abs = p.resolve(strict=False)
  232. except OSError:
  233. return False, None
  234. p_lex = _lexical_path(p)
  235. # (resolved root, lexical spellings of the root, board)
  236. roots: list[tuple[Path, tuple[Path, ...], Optional[str]]] = []
  237. def _add_root(
  238. anchor: Path, anchor_real: Path, parts: tuple[str, ...], board: Optional[str]
  239. ) -> None:
  240. root = anchor.joinpath(*parts)
  241. with contextlib.suppress(OSError):
  242. roots.append((
  243. root.resolve(strict=False),
  244. (_lexical_path(root), _lexical_path(anchor_real.joinpath(*parts))),
  245. board,
  246. ))
  247. override = os.environ.get("HERMES_KANBAN_WORKSPACES_ROOT", "").strip()
  248. if override:
  249. override_root = Path(override).expanduser()
  250. with contextlib.suppress(OSError):
  251. override_parent = override_root.parent
  252. _add_root(
  253. override_parent,
  254. override_parent.resolve(strict=False),
  255. (override_root.name,),
  256. None,
  257. )
  258. try:
  259. home = _kb.kanban_home()
  260. # Resolve the shared anchor once, not once per board root.
  261. home_real = home.resolve(strict=False)
  262. except OSError:
  263. home = None
  264. if home is not None:
  265. _add_root(home, home_real, ("kanban", "workspaces"), _kb.DEFAULT_BOARD)
  266. entries: list[Path] = []
  267. with contextlib.suppress(OSError):
  268. entries = list((home / "kanban" / "boards").resolve(strict=False).iterdir())
  269. for entry in entries:
  270. with contextlib.suppress(OSError):
  271. if entry.is_dir():
  272. _add_root(
  273. home, home_real, ("kanban", "boards", entry.name, "workspaces"), entry.name
  274. )
  275. for root, lexical_roots, board in roots:
  276. if p_abs == root:
  277. continue
  278. try:
  279. if p_abs.is_relative_to(root) and any(
  280. p_lex != lex and p_lex.is_relative_to(lex) for lex in lexical_roots
  281. ):
  282. return True, board
  283. except ValueError:
  284. continue
  285. return False, None
  286. def _scratch_workspace(conn: sqlite3.Connection, task_id: str) -> Optional[Path]:
  287. """Expanded ``workspace_path`` when the task uses a scratch workspace, else ``None``."""
  288. row = conn.execute(
  289. "SELECT workspace_kind, workspace_path FROM tasks WHERE id = ?",
  290. (task_id,),
  291. ).fetchone()
  292. if not row or row["workspace_kind"] != "scratch" or not row["workspace_path"]:
  293. return None
  294. return Path(row["workspace_path"]).expanduser()
  295. def _is_managed_scratch_path(p: Path) -> bool:
  296. """True iff *p* is a STRICT descendant of a kanban-managed ``workspaces/``
  297. root (``HERMES_KANBAN_WORKSPACES_ROOT``, ``<kanban_home>/kanban/workspaces``,
  298. or ``<kanban_home>/kanban/boards/<slug>/workspaces``). A path equal to a
  299. root is not managed (deleting it would wipe every task's scratch dir);
  300. ``<kanban_home>/kanban``, ``.../logs`` and ``.../boards/<slug>`` hold
  301. Hermes' own DB and metadata. :func:`_cleanup_workspace` refuses
  302. ``rmtree`` outside managed storage — a board ``default_workdir`` on a real
  303. source tree paired with ``workspace_kind='scratch'`` would otherwise make
  304. task completion delete user data.
  305. See #28818.
  306. """
  307. return _managed_scratch_path_info(p)[0]
  308. def _cleanup_workspace(conn: sqlite3.Connection, task_id: str) -> None:
  309. """Remove a task's scratch workspace dir and kill its stale tmux session.
  310. Called from :func:`complete_task` after the transaction commits; best-effort
  311. so cleanup never blocks completion. ``scratch`` is removed; ``worktree``
  312. only when provably free of work (clean tree, every commit reachable from a
  313. remote-tracking ref); ``dir`` is intentionally preserved."""
  314. try:
  315. row = conn.execute(_WORKSPACE_ROW_SQL, (task_id,)).fetchone()
  316. if not row:
  317. return
  318. kind: Optional[str] = row["workspace_kind"]
  319. path: Optional[str] = row["workspace_path"]
  320. if kind not in _REMOVABLE_KINDS or not path:
  321. # Not removable itself, but completing may still unblock a deferred
  322. # parent scratch cleanup (e.g. a 'dir' child of a scratch parent).
  323. # See #33774.
  324. _try_cleanup_parent_workspaces(conn, task_id)
  325. return
  326. # Defer while any child is not yet terminal so it can still read
  327. # handoff artifacts from this workspace.
  328. if _has_active_children(conn, task_id):
  329. _kb._log.debug(
  330. "Deferring %s workspace cleanup for task %s: "
  331. "active children still need workspace at %s",
  332. kind, task_id, path,
  333. )
  334. return
  335. # Kill the (dead) tmux worker session BEFORE removing a worktree so a
  336. # lingering worker never has its cwd deleted from under it.
  337. if kind == "worktree":
  338. _cleanup_worker_tmux(conn, task_id)
  339. if not _defer_shared_worktree_cleanup(conn, task_id, path):
  340. _cleanup_worktree_workspace(task_id, path, row["branch_name"])
  341. _try_cleanup_parent_workspaces(conn, task_id)
  342. return
  343. wp = Path(path)
  344. if wp.is_dir():
  345. # Containment guard: a board's ``default_workdir`` can pair
  346. # ``workspace_kind='scratch'`` with a user path pointing at a real
  347. # source tree; without this, completion would rmtree the user's data.
  348. # See #28818. Containment runs first so an unmanaged dir that is
  349. # never removed does not pay for (or log) the shared-use scan.
  350. if _is_managed_scratch_path(wp):
  351. if not _defer_shared_workspace_cleanup(conn, task_id, path):
  352. release_lsp_clients(str(wp))
  353. shutil.rmtree(wp, ignore_errors=True)
  354. _kb._log.debug("Removed scratch workspace: %s", wp)
  355. else:
  356. _kb._log.warning(
  357. "Refusing to remove out-of-scratch workspace for task %s: %s "
  358. "(workspace_kind='scratch' but path is outside any "
  359. "kanban-managed workspaces root)",
  360. task_id, wp,
  361. )
  362. # Kill the owning worker's tmux session if it is now dead, then let any
  363. # parent whose children are all done run its deferred cleanup.
  364. _cleanup_worker_tmux(conn, task_id)
  365. # After cleaning up this task's workspace, check if any parent tasks now have all children done —
  366. # their deferred cleanup can proceed (#33774).
  367. _try_cleanup_parent_workspaces(conn, task_id)
  368. except Exception:
  369. pass # best-effort — never block completion
  370. def _cleanup_worktree_workspace(
  371. task_id: str, path: str, branch_name: Optional[str] = None
  372. ) -> None:
  373. """Remove a finished task's linked git worktree when it holds no work.
  374. Mirrors the CLI startup pruner (``cli._prune_stale_worktrees``): removal
  375. requires a clean tree AND every commit reachable from a remote-tracking
  376. ref; any doubt (dirty, unpushed, unresolvable repo, failing git) preserves
  377. it. The auto-generated ``wt/<task-id>`` branch is deleted with it; custom
  378. branches are kept. Best-effort."""
  379. try:
  380. from hermes_cli.worktree_ops import _worktree_has_unpushed_commits, _worktree_is_dirty
  381. except Exception:
  382. return # CLI safety predicates unavailable — preserve
  383. try:
  384. wp = Path(path).expanduser()
  385. if not wp.is_dir():
  386. return
  387. common = _git_common_dir(wp)
  388. if common is None or common.name != ".git":
  389. return # not a linked worktree of a normal repo — never guess
  390. repo_root = common.parent
  391. if _path_key(wp.resolve(strict=False)) == _path_key(repo_root.resolve(strict=False)):
  392. return # never remove the main checkout
  393. if _worktree_is_dirty(str(wp), str(repo_root)) or _worktree_has_unpushed_commits(str(wp)):
  394. _kb._log.info(
  395. "Preserving worktree for task %s: dirty or unpushed work at %s",
  396. task_id, wp,
  397. )
  398. return
  399. # Windows cannot delete a directory while this process has its current
  400. # directory inside it. Completed workers normally run from their own
  401. # linked worktree, so move this process back to the main checkout
  402. # before asking Git to remove the worktree.
  403. worktree_path = wp.resolve(strict=False)
  404. try:
  405. cwd = Path.cwd().resolve(strict=False)
  406. except OSError:
  407. # cwd was already deleted (a scratch-kind child's own workspace is
  408. # rmtree'd before this deferred parent cleanup runs, #33774). A
  409. # dead cwd cannot hold the worktree open, so leaving it is safe.
  410. cwd = None
  411. if cwd is None or cwd == worktree_path or cwd.is_relative_to(worktree_path):
  412. try:
  413. os.chdir(repo_root)
  414. except OSError as exc:
  415. _kb._log.warning(
  416. "Preserving worktree for task %s: cannot leave %s for %s: %s",
  417. task_id, cwd or "<deleted cwd>", repo_root, exc,
  418. )
  419. return
  420. # No --force: git's own dirty guard re-verifies at removal time, so if
  421. # the tree became dirty since our check (TOCTOU) removal fails safe.
  422. release_lsp_clients(str(worktree_path))
  423. result = _git(repo_root, "worktree", "remove", str(wp), timeout=60)
  424. if result.returncode != 0:
  425. # Windows can retain a directory handle briefly after cwd changes.
  426. # Retry once without --force; Git still enforces its dirty guard.
  427. time.sleep(0.1)
  428. result = _git(repo_root, "worktree", "remove", str(wp), timeout=60)
  429. if result.returncode != 0:
  430. _kb._log.warning(
  431. "git worktree remove failed for task %s at %s: %s",
  432. task_id, wp, (result.stderr or result.stdout or "").strip(),
  433. )
  434. return
  435. _kb._log.debug("Removed worktree workspace: %s", wp)
  436. branch = (branch_name or "").strip() or f"wt/{task_id}"
  437. if branch.startswith("wt/"):
  438. _git(repo_root, "branch", "-D", branch, timeout=30)
  439. except Exception:
  440. pass # best-effort — never block completion
  441. def _try_cleanup_parent_workspaces(conn: sqlite3.Connection, task_id: str) -> None:
  442. """Run the deferred cleanup of any parent scratch/worktree workspace whose
  443. children are now all done/archived/failed/cancelled (called after each
  444. child completes).
  445. See #33774.
  446. """
  447. try:
  448. parents = conn.execute(
  449. "SELECT parent_id FROM task_links WHERE child_id = ?",
  450. (task_id,),
  451. ).fetchall()
  452. for (parent_id,) in parents:
  453. row = conn.execute(_WORKSPACE_ROW_SQL, (parent_id,)).fetchone()
  454. if (
  455. not row
  456. or row["workspace_kind"] not in _REMOVABLE_KINDS
  457. or not row["workspace_path"]
  458. or not _is_terminal_task(conn, parent_id)
  459. or _has_active_children(conn, parent_id)
  460. ):
  461. continue
  462. ws_path = row["workspace_path"]
  463. if row["workspace_kind"] == "worktree":
  464. if _defer_shared_worktree_cleanup(conn, parent_id, ws_path):
  465. continue
  466. _cleanup_worktree_workspace(parent_id, ws_path, row["branch_name"])
  467. continue
  468. wp = Path(ws_path)
  469. if not wp.is_dir():
  470. continue
  471. if _is_managed_scratch_path(wp):
  472. if _defer_shared_workspace_cleanup(conn, parent_id, ws_path):
  473. continue
  474. release_lsp_clients(str(wp))
  475. shutil.rmtree(wp, ignore_errors=True)
  476. _kb._log.debug("Deferred cleanup: removed parent %s scratch workspace: %s", parent_id, wp)
  477. except Exception:
  478. pass # best-effort
  479. def _cleanup_worker_tmux(conn: sqlite3.Connection, task_id: str) -> None:
  480. """Kill the tmux session associated with a task's assignee, if dead."""
  481. try:
  482. row = conn.execute(
  483. "SELECT assignee FROM tasks WHERE id = ?", (task_id,)
  484. ).fetchone()
  485. if not row or not row["assignee"]:
  486. return
  487. # Workers named swarm1-12 use tmux sessions named swarm-swarm1 etc.
  488. session = f"swarm-{row['assignee']}"
  489. out = subprocess.run(
  490. ["tmux", "list-panes", "-t", session, "-F", "#{pane_dead}"],
  491. capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=5,
  492. check=False,
  493. )
  494. if out.stdout.strip() == "1":
  495. subprocess.run(["tmux", "kill-session", "-t", session], capture_output=True, timeout=5, check=False)
  496. _kb._log.debug("Killed stale tmux session: %s", session)
  497. except Exception:
  498. pass # best-effort — never block completion
  499. _SCRATCH_TIP_SENTINEL_NAME = ".scratch_tip_shown"
  500. _SCRATCH_TIP_MESSAGE = (
  501. "scratch workspaces are ephemeral — they're deleted when the task "
  502. "completes. Use --workspace worktree: (git worktree) or "
  503. "--workspace dir:/abs/path (existing dir) to preserve worker output."
  504. )
  505. def _scratch_tip_sentinel_path() -> Path:
  506. """Path to the per-install scratch-workspace-tip sentinel file."""
  507. return _kb.kanban_home() / _SCRATCH_TIP_SENTINEL_NAME
  508. def _scratch_tip_shown() -> bool:
  509. """True iff the scratch-workspace tip was already emitted on this install.
  510. Best-effort — any error re-emits, the safer failure mode for a help message."""
  511. try:
  512. return _scratch_tip_sentinel_path().exists()
  513. except OSError:
  514. return False
  515. def _mark_scratch_tip_shown() -> None:
  516. """Touch the sentinel so future scratch workspaces stay silent. Best-effort:
  517. a failure means the tip may appear once more, preferable to crashing dispatch."""
  518. try:
  519. path = _scratch_tip_sentinel_path()
  520. path.parent.mkdir(parents=True, exist_ok=True)
  521. path.touch(exist_ok=True)
  522. except OSError:
  523. pass
  524. def _maybe_emit_scratch_tip(
  525. conn: sqlite3.Connection,
  526. task_id: str,
  527. workspace_kind: Optional[str],
  528. ) -> None:
  529. """Emit the first-use scratch-workspace tip once per install, right after a
  530. scratch workspace is materialized. No-op for ``worktree``/``dir`` (preserved
  531. by design) and once the sentinel exists."""
  532. if (workspace_kind or "scratch") != "scratch" or _scratch_tip_shown():
  533. return
  534. try:
  535. _kb._log.warning("kanban: %s (task %s)", _SCRATCH_TIP_MESSAGE, task_id)
  536. with _kb.write_txn(conn):
  537. _kb._append_event(
  538. conn, task_id, "tip_scratch_workspace",
  539. {"message": _SCRATCH_TIP_MESSAGE},
  540. )
  541. except Exception:
  542. # Best-effort — never block the spawn loop over a help message.
  543. pass
  544. finally:
  545. _mark_scratch_tip_shown()
  546. # ---------------------------------------------------------------------------
  547. # Workspace resolution
  548. # ---------------------------------------------------------------------------
  549. def _git_toplevel(path: Path) -> Optional[Path]:
  550. """Return the git toplevel containing ``path``, or ``None`` if not in a repo."""
  551. out = _kb._git_out(path, "rev-parse", "--show-toplevel")
  552. if out is None:
  553. return None
  554. try:
  555. return Path(out).expanduser().resolve()
  556. except Exception:
  557. return Path(out).expanduser()
  558. def _git_branch_exists(repo_root: Path, branch_name: str) -> bool:
  559. try:
  560. result = _git(repo_root, "show-ref", "--verify", f"refs/heads/{branch_name}", timeout=30)
  561. except Exception:
  562. return False
  563. return result.returncode == 0
  564. def _git_abs_path(path: Path, flag: str) -> Optional[Path]:
  565. out = _kb._git_out(path, "rev-parse", "--path-format=absolute", flag)
  566. return Path(out).expanduser().resolve(strict=False) if out else None
  567. def _git_common_dir(path: Path) -> Optional[Path]:
  568. return _git_abs_path(path, "--git-common-dir")
  569. def _git_current_branch(path: Path) -> Optional[str]:
  570. return _kb._git_out(path, "branch", "--show-current")
  571. def _is_linked_worktree_checkout(path: Path) -> bool:
  572. """True when *path* is a linked worktree (git-dir differs from common-dir).
  573. One ``rev-parse`` call answers both directories.
  574. """
  575. out = _kb._git_out(
  576. path, "rev-parse", "--path-format=absolute", "--git-dir", "--git-common-dir"
  577. )
  578. lines = out.splitlines() if out else []
  579. return len(lines) == 2 and (
  580. Path(lines[0]).resolve(strict=False) != Path(lines[1]).resolve(strict=False)
  581. )
  582. def _nearest_existing_path(path: Path) -> Path:
  583. current = path
  584. while not current.exists() and current != current.parent:
  585. current = current.parent
  586. return current
  587. def _repo_root_for_worktree_target(path: Path) -> Optional[Path]:
  588. current = _nearest_existing_path(path).resolve(strict=False)
  589. while True:
  590. repo_root = _git_toplevel(current)
  591. if repo_root is not None:
  592. return repo_root
  593. if current == current.parent:
  594. return None
  595. current = current.parent
  596. def _ensure_git_worktree(repo_root: Path, target: Path, branch_name: str) -> None:
  597. """Materialize ``target`` as a linked git worktree under ``repo_root``."""
  598. target = target.expanduser()
  599. repo_common = _git_common_dir(repo_root)
  600. if target.exists() and repo_common is not None and _path_key(_git_common_dir(target)) == _path_key(repo_common):
  601. return
  602. target.parent.mkdir(parents=True, exist_ok=True)
  603. if _git_branch_exists(repo_root, branch_name):
  604. args = ["worktree", "add", str(target), branch_name]
  605. else:
  606. args = ["worktree", "add", "-b", branch_name, str(target), "HEAD"]
  607. result = _git(repo_root, *args, timeout=60)
  608. if result.returncode != 0:
  609. stderr = (result.stderr or result.stdout or "").strip()
  610. raise RuntimeError(
  611. f"git worktree add failed for {target} on branch {branch_name}: {stderr}"
  612. )
  613. def _anchored_worktree(repo_root: Path, task_id: str, branch_name: str) -> tuple[Path, str]:
  614. """Materialize the canonical ``<repo>/.worktrees/<task-id>`` worktree."""
  615. target = repo_root / ".worktrees" / task_id
  616. _ensure_git_worktree(repo_root, target, branch_name)
  617. return target, branch_name
  618. def _resolve_worktree_workspace(task: Task, *, board: Optional[str] = None) -> tuple[Path, str]:
  619. """Resolve + materialize a linked git worktree for ``task``. With no
  620. ``task.workspace_path`` the anchor is the board's ``default_workdir`` so
  621. every worktree lands under a board-owned repo (``<repo>/.worktrees/<id>``)
  622. instead of the dispatcher's incidental CWD (whatever dir the gateway was
  623. launched from); with no anchor configured we fail loudly rather than guess."""
  624. branch_name = (task.branch_name or "").strip() or f"wt/{task.id}"
  625. if not task.workspace_path:
  626. board_slug = board if board else _kb.get_current_board()
  627. board_default = (_kb.read_board_metadata(board_slug).get("default_workdir") or "").strip()
  628. if not board_default:
  629. raise ValueError(
  630. f"task {task.id} has workspace_kind=worktree but no workspace_path, "
  631. f"and board {board_slug!r} has no default_workdir set. Set a board "
  632. "default workdir (a git repo) or create the task with "
  633. "--workspace worktree:<absolute-repo-path>."
  634. )
  635. anchor = Path(board_default).expanduser()
  636. if not anchor.is_absolute():
  637. raise ValueError(
  638. f"board {board_slug!r} default_workdir {board_default!r} is not "
  639. "absolute; use an absolute path to a git repo"
  640. )
  641. repo_root = _git_toplevel(anchor)
  642. if repo_root is None:
  643. raise ValueError(
  644. f"task {task.id} has workspace_kind=worktree but board "
  645. f"{board_slug!r} default_workdir {board_default!r} is not inside a git repo"
  646. )
  647. return _anchored_worktree(repo_root, task.id, branch_name)
  648. requested = Path(task.workspace_path).expanduser()
  649. if not requested.is_absolute():
  650. raise ValueError(
  651. f"task {task.id} has non-absolute worktree path "
  652. f"{task.workspace_path!r}; use an absolute path"
  653. )
  654. requested_resolved = requested.resolve(strict=False)
  655. if requested.exists() and _is_linked_worktree_checkout(requested):
  656. actual_branch = _git_current_branch(requested)
  657. if actual_branch == branch_name:
  658. return requested_resolved, actual_branch
  659. # The requested path is an existing checkout of a DIFFERENT task's
  660. # branch (decompose children inherit the root's workspace_path
  661. # verbatim, so siblings all point here). Reusing it would run this task
  662. # on the other task's branch — silent cross-task provenance corruption,
  663. # unsafe under concurrency — so fall back to our own worktree.
  664. fallback_root = _repo_root_for_worktree_target(requested.parent)
  665. if fallback_root is not None:
  666. fallback = fallback_root / ".worktrees" / task.id
  667. if _path_key(fallback.resolve(strict=False)) != _path_key(requested_resolved):
  668. _ensure_git_worktree(fallback_root, fallback, branch_name)
  669. return fallback.resolve(strict=False), branch_name
  670. # No repo to anchor a fallback on (or the occupied path IS this task's
  671. # own canonical worktree): keep the legacy reuse rather than fail dispatch.
  672. return requested_resolved, actual_branch or branch_name
  673. repo_root = _git_toplevel(requested)
  674. if repo_root is not None and _path_key(requested_resolved) == _path_key(repo_root):
  675. return _anchored_worktree(repo_root, task.id, branch_name)
  676. repo_root = _repo_root_for_worktree_target(requested.parent)
  677. if repo_root is None:
  678. raise ValueError(
  679. f"task {task.id} worktree path {task.workspace_path!r} is not inside a git repo "
  680. "and does not point at a git repo root"
  681. )
  682. _ensure_git_worktree(repo_root, requested, branch_name)
  683. return requested, branch_name
  684. def resolve_workspace(task: Task, *, board: Optional[str] = None) -> Path:
  685. """Resolve (and create if needed) the workspace for a task.
  686. ``scratch``: ``<board-root>/workspaces/<id>/`` — path-stable across the
  687. dispatcher and every profile worker. ``dir``: ``workspace_path``, created
  688. if missing; MUST be absolute (relative paths would resolve against the
  689. dispatcher's CWD — confused-deputy traversal). ``worktree``: a linked git
  690. worktree; a repo-root ``workspace_path`` anchors ``<repo>/.worktrees/<id>``,
  691. a concrete path is created/reused, none -> the board's ``default_workdir``
  692. (raises if unset rather than guessing). Persist via ``set_workspace_path``.
  693. """
  694. kind = task.workspace_kind or "scratch"
  695. if kind == "worktree":
  696. return _resolve_worktree_workspace(task, board=board)[0]
  697. if kind == "scratch" and not task.workspace_path:
  698. p = _kb.workspaces_root(board=board) / task.id
  699. elif kind == "scratch":
  700. # Legacy explicit-path scratch tasks get the same absolute-path guard
  701. # as dir: — same threat model.
  702. p = Path(task.workspace_path).expanduser()
  703. if not p.is_absolute():
  704. raise ValueError(
  705. f"task {task.id} has non-absolute workspace_path "
  706. f"{task.workspace_path!r}; workspace paths must be absolute"
  707. )
  708. elif kind == "dir":
  709. if not task.workspace_path:
  710. raise ValueError(f"task {task.id} has workspace_kind=dir but no workspace_path")
  711. p = Path(task.workspace_path).expanduser()
  712. if not p.is_absolute():
  713. raise ValueError(
  714. f"task {task.id} has non-absolute workspace_path "
  715. f"{task.workspace_path!r}; use an absolute path "
  716. f"(relative paths are ambiguous against the dispatcher's CWD)"
  717. )
  718. else:
  719. raise ValueError(f"unknown workspace_kind: {kind}")
  720. p.mkdir(parents=True, exist_ok=True)
  721. return p
  722. def _set_task_column(conn: sqlite3.Connection, task_id: str, column: str, value: str) -> None:
  723. with _kb.write_txn(conn):
  724. conn.execute(f"UPDATE tasks SET {column} = ? WHERE id = ?", (value, task_id))
  725. def set_workspace_path(conn: sqlite3.Connection, task_id: str, path: Path | str) -> None:
  726. _set_task_column(conn, task_id, "workspace_path", str(path))
  727. def set_branch_name(conn: sqlite3.Connection, task_id: str, branch_name: str) -> None:
  728. _set_task_column(conn, task_id, "branch_name", str(branch_name))
  729. # Late-bound origin namespace (see module docstring); imported LAST so this
  730. # module is fully populated before ``kanban_db`` imports from it.
  731. from hermes_cli import kanban_db as _kb