@mokuyoaxis/agent-guard 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. package/CONTRIBUTING.md +101 -0
  2. package/LICENSE +21 -0
  3. package/README.md +558 -0
  4. package/README.zh-CN.md +488 -0
  5. package/adapters/INTEGRATION.md +94 -0
  6. package/adapters/claude/README.md +141 -0
  7. package/adapters/claude/compatibility.json +17 -0
  8. package/adapters/claude/harness/README.md +59 -0
  9. package/adapters/claude/harness/mock_anthropic_api.mjs +47 -0
  10. package/adapters/claude/harness/run_scenario.sh +79 -0
  11. package/adapters/claude/harness/run_scenario_no_python3.sh +49 -0
  12. package/adapters/claude/hook_bridge.sh +33 -0
  13. package/adapters/claude/pre_tool_use.py +264 -0
  14. package/adapters/claude/settings.example.json +16 -0
  15. package/adapters/codex/harness/README.md +53 -0
  16. package/adapters/codex/harness/acceptance.py +226 -0
  17. package/adapters/dsh/README.md +62 -0
  18. package/adapters/dsh/cordis.patch.yml +30 -0
  19. package/adapters/dsh/lib/index.js +500 -0
  20. package/adapters/kimi-code/README.md +169 -0
  21. package/adapters/kimi-code/compatibility.json +17 -0
  22. package/adapters/kimi-code/config.example.toml +26 -0
  23. package/adapters/kimi-code/hook_bridge.sh +32 -0
  24. package/adapters/kimi-code/pre_tool_use.py +72 -0
  25. package/core/__init__.py +47 -0
  26. package/core/audit.py +86 -0
  27. package/core/classifier.py +1175 -0
  28. package/core/dialects.py +898 -0
  29. package/core/policy.py +817 -0
  30. package/core/recovery.py +700 -0
  31. package/core/redaction.py +1096 -0
  32. package/core/safe_view.py +212 -0
  33. package/docs/architecture.md +223 -0
  34. package/docs/compatibility.md +142 -0
  35. package/docs/development-note-unguarded-deletion.md +187 -0
  36. package/docs/friction.md +266 -0
  37. package/docs/harness-capabilities.md +72 -0
  38. package/docs/host-drift.md +142 -0
  39. package/docs/publishing-from-ephemeral-environments.md +104 -0
  40. package/docs/release-notes-0.2.0-rc1.md +46 -0
  41. package/docs/release-notes-0.2.0.md +72 -0
  42. package/docs/release-notes-0.2.1.md +78 -0
  43. package/docs/release-notes-0.2.2.md +120 -0
  44. package/docs/secret-guard-analysis.md +416 -0
  45. package/docs/secret-guard-architecture.md +93 -0
  46. package/docs/secret-guard-design.md +649 -0
  47. package/docs/test-report-claude-code-harness.md +462 -0
  48. package/docs/test-report-codex-gpt-5.6-sol.md +335 -0
  49. package/docs/test-report-codex-gpt-6-astra-high.md +129 -0
  50. package/docs/test-report-dsh-0.1.5-rc.1.md +84 -0
  51. package/docs/test-report-dsh-v0.1.1.md +126 -0
  52. package/docs/test-report-kimi-code-block.md +198 -0
  53. package/docs/test-report-zcode-glm-flash.md +241 -0
  54. package/docs/threat-model.md +44 -0
  55. package/doctor.py +756 -0
  56. package/live_sentinel.py +339 -0
  57. package/package.json +69 -0
  58. package/skills/delete-guard/SKILL.md +109 -0
  59. package/skills/delete-guard/agents/openai.yaml +4 -0
  60. package/skills/delete-guard/references/policy.md +161 -0
  61. package/skills/delete-guard/scripts/_bootstrap.py +8 -0
  62. package/skills/delete-guard/scripts/check.py +370 -0
  63. package/skills/delete-guard/scripts/gc.py +103 -0
  64. package/skills/delete-guard/scripts/restore.py +98 -0
  65. package/skills/delete-guard/scripts/safe_delete.py +256 -0
  66. package/skills/delete-guard/scripts/status.py +130 -0
  67. package/skills/exfil-guard/SKILL.md +143 -0
  68. package/skills/exfil-guard/agents/openai.yaml +4 -0
  69. package/skills/exfil-guard/references/channels.md +58 -0
  70. package/skills/exfil-guard/references/rules.md +194 -0
  71. package/skills/exfil-guard/scripts/_bootstrap.py +8 -0
  72. package/skills/exfil-guard/scripts/check_span.py +250 -0
  73. package/skills/exfil-guard/scripts/sanitize.py +155 -0
  74. package/skills/exfil-guard/scripts/view.py +44 -0
  75. package/skills/recovery-audit/SKILL.md +283 -0
  76. package/skills/recovery-audit/agents/openai.yaml +4 -0
  77. package/skills/recovery-audit/references/evidence-records.md +85 -0
@@ -0,0 +1,700 @@
1
+ """Recoverability pillar: the Compensation Engine.
2
+
3
+ Two compensation strategies, chosen by the caller (policy decides which):
4
+
5
+ relocate - move targets into the quarantine tree, preserving their
6
+ workspace-relative structure under one transaction id
7
+ snapshot_git - capture tracked modifications as a stash commit WITHOUT
8
+ changing the working tree (git stash create + store), so a
9
+ subsequent reset --hard / restore stays reversible
10
+
11
+ Everything lands in an append-only manifest (JSONL). Restore is itself
12
+ non-destructive: it refuses to overwrite anything that now exists at the
13
+ origin path unless the human passes force explicitly.
14
+
15
+ The quarantine directory must be Git-ignored before it is created. An existing
16
+ repository `.gitignore` rule is accepted; otherwise the engine adds a local
17
+ `.git/info/exclude` rule without modifying the user's tracked files.
18
+ """
19
+ from __future__ import annotations
20
+
21
+ import json
22
+ import os
23
+ import shutil
24
+ import subprocess
25
+ import time
26
+ import errno
27
+ import re
28
+ from typing import Any, Dict, List, Optional, Tuple
29
+
30
+ from . import MANIFEST_NAME, TRASH_DIRNAME
31
+ from .audit import new_txid, utc_now_iso
32
+ from .classifier import PathSpec, _physical, _physical_keep_final
33
+
34
+ # Soft retention policy (docs/references: GC). Thresholds only MARK entries
35
+ # GC_ELIGIBLE; actual purging is an explicit maintenance action - a system
36
+ # that promises recoverability must never silently destroy its own evidence.
37
+ SOFT_RETENTION_DAYS = 30
38
+ SOFT_SIZE_LIMIT_BYTES = 5 * 1024 * 1024 * 1024 # 5 GiB
39
+
40
+ _STORAGE_ERRNOS = {
41
+ getattr(errno, "ENOSPC", None),
42
+ getattr(errno, "EDQUOT", None),
43
+ } - {None}
44
+
45
+ # A transaction directory is one direct child of the quarantine, never a
46
+ # caller-supplied path. Accept simple historical identifiers too, but no
47
+ # separators or dots that could turn an ID into a path traversal.
48
+ _GC_TXID_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9_-]*\Z")
49
+
50
+
51
+ class StorageUnavailable(OSError):
52
+ """Quarantine cannot accept new relocations (disk full / quota)."""
53
+
54
+
55
+ class RecoveryEngine:
56
+ def __init__(self, workspace: str, trash_root: Optional[str] = None):
57
+ self.workspace = os.path.normpath(os.path.abspath(workspace))
58
+ self.trash_root = os.path.normpath(os.path.abspath(
59
+ trash_root or os.path.join(self.workspace, TRASH_DIRNAME)))
60
+
61
+ # ------------------------------------------------------------- layout
62
+
63
+ @staticmethod
64
+ def _contained_dest(dest: str, tx_dir: str) -> str:
65
+ """Return dest, refusing anything that escapes trash_root/<txid>/.
66
+
67
+ Relocation must be RECOVERABLE: a destination outside the
68
+ transaction directory is evidence that the origin/trash spelling
69
+ pair diverged (the macOS /var link bug) or that a symlink moved
70
+ under us. Never silently write there - raise OSError, which the
71
+ caller turns into a controlled failure plus a manifest record.
72
+ """
73
+ root = _physical(os.path.normpath(os.path.abspath(tx_dir)))
74
+ candidate = _physical(os.path.normpath(os.path.abspath(dest)))
75
+ if candidate == root:
76
+ raise OSError(
77
+ f"refusing to relocate onto the transaction directory: {dest}")
78
+ if os.path.commonpath([candidate, root]) != root:
79
+ raise OSError(
80
+ f"destination escapes quarantine transaction directory "
81
+ f"{root}: {dest}")
82
+ return candidate
83
+
84
+ @property
85
+ def manifest_path(self) -> str:
86
+ return os.path.join(self.trash_root, MANIFEST_NAME)
87
+
88
+ def ensure_layout(self) -> None:
89
+ # Establish the ignore rule first. If protected Git metadata prevents
90
+ # this, fail without leaving a new untracked quarantine directory.
91
+ self._exclude_from_git()
92
+ os.makedirs(self.trash_root, exist_ok=True)
93
+
94
+ def _trash_is_git_ignored(self) -> bool:
95
+ """Whether Git already excludes the quarantine path.
96
+
97
+ Codex and other harness sandboxes commonly protect `.git` from writes.
98
+ A repository-level `.gitignore` is sufficient in that environment, so
99
+ do not require a redundant `.git/info/exclude` mutation.
100
+ """
101
+ try:
102
+ rel = os.path.relpath(_physical(self.trash_root),
103
+ _physical(self.workspace))
104
+ if rel == os.pardir or rel.startswith(os.pardir + os.sep):
105
+ return True # external quarantine cannot pollute this repo
106
+ git_rel = rel.replace(os.sep, "/").rstrip("/") + "/"
107
+ proc = subprocess.run(
108
+ ["git", "-C", self.workspace, "check-ignore", "-q",
109
+ "--no-index", "--", git_rel],
110
+ capture_output=True, timeout=10)
111
+ return proc.returncode == 0
112
+ except (OSError, subprocess.TimeoutExpired, ValueError):
113
+ return False
114
+
115
+ def _exclude_from_git(self) -> None:
116
+ """Hide the quarantine from git status via .git/info/exclude."""
117
+ git_marker = os.path.join(self.workspace, ".git")
118
+ if not os.path.exists(git_marker): # dir or worktree pointer file
119
+ return
120
+ if self._trash_is_git_ignored():
121
+ return
122
+ resolved = subprocess.run(
123
+ ["git", "-C", self.workspace, "rev-parse", "--git-path",
124
+ "info/exclude"], capture_output=True, text=True, timeout=10)
125
+ if resolved.returncode != 0 or not resolved.stdout.strip():
126
+ raise OSError((resolved.stderr or
127
+ "cannot resolve Git exclude path").strip())
128
+ exclude = resolved.stdout.strip()
129
+ if not os.path.isabs(exclude):
130
+ exclude = os.path.join(self.workspace, exclude)
131
+ info = os.path.dirname(exclude)
132
+ os.makedirs(info, exist_ok=True)
133
+ try:
134
+ with open(exclude, "r", encoding="utf-8") as fh:
135
+ existing = fh.read()
136
+ except OSError:
137
+ existing = ""
138
+ # Both sides physical: an external AGENT_GUARD_TRASH given in a
139
+ # non-physical spelling (symlinked ancestor) would otherwise yield
140
+ # a `..`-laden pattern that excludes the wrong path from git status.
141
+ rel = os.path.relpath(
142
+ _physical(self.trash_root),
143
+ _physical(self.workspace)).replace(os.sep, "/")
144
+ pattern = f"/{rel.strip('/')}/"
145
+ for line in existing.splitlines():
146
+ if line.strip() in (TRASH_DIRNAME, pattern):
147
+ return
148
+ with open(exclude, "a", encoding="utf-8") as fh:
149
+ if existing and not existing.endswith("\n"):
150
+ fh.write("\n")
151
+ fh.write(f"# added by agent-guard (quarantine is not project data)\n")
152
+ fh.write(f"{pattern}\n")
153
+
154
+ # ------------------------------------------------------------ manifest
155
+
156
+ def _manifest_append(self, records: List[Dict[str, Any]]) -> None:
157
+ self.ensure_layout()
158
+ with open(self.manifest_path, "a", encoding="utf-8") as fh:
159
+ for record in records:
160
+ record.setdefault("ts", utc_now_iso())
161
+ fh.write(json.dumps(record, ensure_ascii=False,
162
+ sort_keys=True) + "\n")
163
+ fh.flush()
164
+ os.fsync(fh.fileno())
165
+
166
+ def read_manifest(self) -> List[Dict[str, Any]]:
167
+ path = self.manifest_path
168
+ if not os.path.exists(path):
169
+ return []
170
+ out: List[Dict[str, Any]] = []
171
+ with open(path, "r", encoding="utf-8") as fh:
172
+ for raw in fh:
173
+ raw = raw.strip()
174
+ if not raw:
175
+ continue
176
+ try:
177
+ out.append(json.loads(raw))
178
+ except json.JSONDecodeError:
179
+ continue
180
+ return out
181
+
182
+ # -------------------------------------------------------------- move
183
+
184
+ @staticmethod
185
+ def _move(src: str, dest: str) -> None:
186
+ """Move file/symlink/dir preserving symlink semantics.
187
+
188
+ Same-filesystem moves are plain renames. Cross-device fallbacks keep
189
+ symlinks as symlinks (never materialize what they point at).
190
+ """
191
+ try:
192
+ os.rename(src, dest)
193
+ return
194
+ except OSError as exc:
195
+ if exc.errno in _STORAGE_ERRNOS:
196
+ raise StorageUnavailable(
197
+ f"quarantine storage unavailable: {exc}") from exc
198
+ if exc.errno != errno.EXDEV:
199
+ raise
200
+ try:
201
+ if os.path.islink(src):
202
+ link_target = os.readlink(src)
203
+ os.symlink(link_target, dest)
204
+ os.unlink(src)
205
+ elif os.path.isdir(src):
206
+ shutil.copytree(src, dest, symlinks=True)
207
+ shutil.rmtree(src)
208
+ else:
209
+ shutil.copy2(src, dest)
210
+ os.unlink(src)
211
+ except OSError as exc:
212
+ if exc.errno in _STORAGE_ERRNOS:
213
+ raise StorageUnavailable(
214
+ f"quarantine storage unavailable: {exc}") from exc
215
+ raise
216
+
217
+ # ----------------------------------------------------------- relocate
218
+
219
+ def relocate(self, specs: List[PathSpec], txid: Optional[str] = None,
220
+ meta: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
221
+ """Move every concrete target into trash/<txid>/<workspace-relative>.
222
+
223
+ Layout arithmetic uses PHYSICAL spellings on BOTH sides: the
224
+ workspace root is realpath-resolved (F8) while ``spec.resolved`` is
225
+ deliberately LEXICAL, so a lexically-spelled target under a
226
+ symlinked ancestor (macOS /var -> /private/var) used to produce a
227
+ multi-segment ``..`` relpath and a destination OUTSIDE the
228
+ transaction directory. ``origin_path`` stays lexical: restore and
229
+ every message must speak the caller's spelling.
230
+ """
231
+ txid = txid or new_txid()
232
+ # Write-ahead journal: no source mutation may happen until the
233
+ # transaction exists durably. Each target intent is durable before its
234
+ # move, so an interrupted completion write remains discoverable.
235
+ self._manifest_append([{
236
+ "type": "tx-start", "txid": txid, "strategy": "relocate",
237
+ "meta": meta or {},
238
+ }])
239
+ moved: List[Dict[str, Any]] = []
240
+ skipped: List[Dict[str, Any]] = []
241
+ storage_failure = False
242
+ for spec in specs:
243
+ src = spec.resolved
244
+ entry_base = {"raw": spec.raw}
245
+ if spec.wildcard or spec.indeterminable or not src:
246
+ skipped.append({**entry_base, "reason": "not concretely resolved"})
247
+ continue
248
+ if not os.path.lexists(src):
249
+ skipped.append({**entry_base, "reason": "already absent"})
250
+ continue
251
+ tx_dir = os.path.join(self.trash_root, txid)
252
+ # Parent chain physical, final component verbatim: a target
253
+ # that is itself a symlink keeps its own location (F9).
254
+ rel = os.path.relpath(_physical_keep_final(src),
255
+ _physical(self.workspace))
256
+ dest = os.path.join(tx_dir, rel)
257
+ try:
258
+ # Defence in depth (F9): a symlink race or an exotic
259
+ # spelling must never let a target land outside its own
260
+ # transaction directory. Fail closed, with evidence.
261
+ dest = self._contained_dest(dest, tx_dir)
262
+ except OSError as exc:
263
+ skipped.append({**entry_base,
264
+ "reason": f"uncontained destination: {exc}"})
265
+ self._manifest_append([{
266
+ "type": "relocate-failed", "txid": txid,
267
+ "origin_path": src, "trash_path": dest,
268
+ "reason": str(exc),
269
+ }])
270
+ continue
271
+ intent = {"type": "relocate-intent", "txid": txid,
272
+ "origin_path": src, "trash_path": dest,
273
+ "raw": spec.raw}
274
+ self._manifest_append([intent])
275
+ try:
276
+ os.makedirs(os.path.dirname(dest), exist_ok=True)
277
+ self._move(src, dest)
278
+ except StorageUnavailable:
279
+ # Hard principle: capacity limits never downgrade to
280
+ # permanent deletion. Abort; the failed target stays at its
281
+ # origin untouched; callers map this to BLOCK.
282
+ storage_failure = True
283
+ self._manifest_append([{
284
+ "type": "relocate-failed", "txid": txid,
285
+ "origin_path": src, "trash_path": dest,
286
+ "reason": "storage unavailable",
287
+ }])
288
+ break
289
+ except OSError as exc:
290
+ self._manifest_append([{
291
+ "type": "relocate-failed", "txid": txid,
292
+ "origin_path": src, "trash_path": dest,
293
+ "reason": str(exc),
294
+ }])
295
+ raise
296
+ item = {"type": "relocate", "txid": txid,
297
+ "origin_path": src, "trash_path": dest}
298
+ self._manifest_append([item])
299
+ moved.append({"origin": src, "trash": dest})
300
+ return {"txid": txid, "moved": moved, "skipped": skipped,
301
+ "storage_failure": storage_failure}
302
+
303
+ # ------------------------------------------------------ git snapshot
304
+
305
+ def snapshot_git(self, cwd: Optional[str] = None,
306
+ txid: Optional[str] = None,
307
+ meta: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
308
+ """Stash-create tracked modifications without touching the tree.
309
+
310
+ Returns sha=None when there is nothing to snapshot (clean tree) -
311
+ that is success, not failure.
312
+ """
313
+ cwd = cwd or self.workspace
314
+ txid = txid or new_txid()
315
+ create = subprocess.run(["git", "-C", cwd, "stash", "create"],
316
+ capture_output=True, text=True, timeout=30)
317
+ if create.returncode != 0:
318
+ return {"ok": False, "clean": False, "txid": txid,
319
+ "sha": None, "stored": False,
320
+ "error": (create.stderr or
321
+ "git stash create failed").strip()}
322
+ sha = create.stdout.strip()
323
+ if not sha:
324
+ self._manifest_append([{
325
+ "type": "snapshot", "txid": txid, "sha": None,
326
+ "note": "working tree clean; nothing to snapshot",
327
+ "meta": meta or {},
328
+ }])
329
+ return {"ok": True, "clean": True, "txid": txid,
330
+ "sha": None, "stored": False, "error": ""}
331
+ store = subprocess.run(
332
+ ["git", "-C", cwd, "stash", "store", "-m", f"agent-guard:{txid}", sha],
333
+ capture_output=True, text=True, timeout=30)
334
+ stored = store.returncode == 0
335
+ error = "" if stored else (
336
+ store.stderr or "git stash store failed").strip()
337
+ self._manifest_append([{
338
+ "type": "snapshot", "txid": txid, "sha": sha,
339
+ "stored": stored, "error": error, "meta": meta or {},
340
+ }])
341
+ return {"ok": stored, "clean": False, "txid": txid, "sha": sha,
342
+ "stored": stored, "error": error}
343
+
344
+ # --------------------------------------------------- git clean enum
345
+
346
+ @staticmethod
347
+ def _decode_git_quoted_path(value: str) -> str:
348
+ """Decode Git's double-quoted C-style path representation."""
349
+ if len(value) < 2 or not (value.startswith('"') and
350
+ value.endswith('"')):
351
+ return value
352
+ data = value[1:-1]
353
+ result = bytearray()
354
+ escapes = {
355
+ "a": 7, "b": 8, "t": 9, "n": 10, "v": 11,
356
+ "f": 12, "r": 13, "\\": 92, '"': 34,
357
+ }
358
+ i = 0
359
+ while i < len(data):
360
+ ch = data[i]
361
+ if ch != "\\":
362
+ result.extend(os.fsencode(ch))
363
+ i += 1
364
+ continue
365
+ i += 1
366
+ if i >= len(data):
367
+ raise ValueError("trailing backslash in Git-quoted path")
368
+ esc = data[i]
369
+ if esc in "01234567":
370
+ digits = esc
371
+ i += 1
372
+ while i < len(data) and len(digits) < 3 and data[i] in "01234567":
373
+ digits += data[i]
374
+ i += 1
375
+ result.append(int(digits, 8))
376
+ continue
377
+ if esc not in escapes:
378
+ raise ValueError(f"unknown Git path escape: \\{esc}")
379
+ result.append(escapes[esc])
380
+ i += 1
381
+ return os.fsdecode(bytes(result))
382
+
383
+ def enumerate_git_clean(self, cwd: Optional[str],
384
+ clean_flags: List[str],
385
+ targets: Optional[List[str]] = None,
386
+ ) -> Tuple[List[str], str]:
387
+ """Dry-run `git clean` mirroring the caller's scope flags.
388
+
389
+ Returns (untracked_paths, stderr). Nested repositories are reported
390
+ by git as 'Would skip' and are intentionally left alone.
391
+ """
392
+ cwd = cwd or self.workspace
393
+ mirror = ["-n"]
394
+ allowed = {"-d", "-x", "-X", "--directory", "--ignored"}
395
+ for flag in clean_flags:
396
+ if flag in allowed:
397
+ mirror.append(flag)
398
+ if targets:
399
+ mirror.extend(["--", *targets])
400
+ env = dict(os.environ)
401
+ env["LC_ALL"] = "C"
402
+ proc = subprocess.run(["git", "-C", cwd, "clean"] + mirror,
403
+ capture_output=True, text=True, timeout=60,
404
+ env=env)
405
+ if proc.returncode != 0:
406
+ detail = (proc.stderr or proc.stdout or
407
+ "git clean dry-run failed").strip()
408
+ return [], detail
409
+ paths: List[str] = []
410
+ unparsed: List[str] = []
411
+ for line in proc.stdout.splitlines():
412
+ line = line.strip()
413
+ if not line:
414
+ continue
415
+ if line.startswith("Would skip repository "):
416
+ continue
417
+ if not line.startswith("Would remove "):
418
+ unparsed.append(line)
419
+ continue
420
+ target = line[len("Would remove "):].strip()
421
+ try:
422
+ paths.append(self._decode_git_quoted_path(target))
423
+ except ValueError as exc:
424
+ return [], f"cannot decode git clean path {target!r}: {exc}"
425
+ if unparsed:
426
+ return [], "unrecognized git clean dry-run output: " + \
427
+ "; ".join(unparsed[:3])
428
+ return paths, proc.stderr.strip()
429
+
430
+ # ------------------------------------------------------------- restore
431
+
432
+ def transactions(self) -> Dict[str, Dict[str, Any]]:
433
+ """Group manifest entries by transaction id (insertion order)."""
434
+ out: Dict[str, Dict[str, Any]] = {}
435
+ for record in self.read_manifest():
436
+ txid = record.get("txid")
437
+ if not txid:
438
+ continue
439
+ slot = out.setdefault(txid, {"txid": txid, "items": []})
440
+ if record.get("type") == "tx-start":
441
+ slot["meta"] = record.get("meta", {})
442
+ slot["ts"] = record.get("ts")
443
+ elif record.get("type") in ("relocate", "snapshot"):
444
+ slot["items"].append(record)
445
+ elif record.get("type") == "relocate-intent":
446
+ slot.setdefault("_intents", []).append(record)
447
+ elif record.get("type") == "relocate-failed":
448
+ slot.setdefault("failures", []).append(record)
449
+ elif record.get("type") == "restore":
450
+ slot["last_restore"] = record
451
+ elif record.get("type") == "purged":
452
+ slot["purged"] = True
453
+
454
+ # If a move succeeded but its completion record could not be written,
455
+ # the durable intent plus filesystem state is sufficient to recover.
456
+ for slot in out.values():
457
+ completed = {
458
+ (item.get("origin_path"), item.get("trash_path"))
459
+ for item in slot["items"] if item.get("type") == "relocate"
460
+ }
461
+ for intent in slot.pop("_intents", []):
462
+ key = (intent.get("origin_path"), intent.get("trash_path"))
463
+ if key in completed:
464
+ continue
465
+ origin, trash = key
466
+ if trash and os.path.lexists(trash):
467
+ slot["items"].append({
468
+ **intent, "type": "relocate",
469
+ "recovered_from_intent": True,
470
+ })
471
+ live_items = 0
472
+ for item in slot["items"]:
473
+ if item.get("type") == "relocate" and \
474
+ os.path.lexists(item.get("trash_path", "")):
475
+ live_items += 1
476
+ elif item.get("type") == "snapshot" and item.get("sha"):
477
+ # Stored stashes are deliberately retained after apply.
478
+ live_items += 1
479
+ slot["restorable_items"] = live_items
480
+ restored = slot.get("last_restore", {})
481
+ if slot.get("purged"):
482
+ slot["state"] = "PURGED"
483
+ elif restored.get("restored") and not restored.get("errors") and \
484
+ not restored.get("conflicts"):
485
+ slot["state"] = "RESTORED"
486
+ elif live_items:
487
+ slot["state"] = "RESTORABLE"
488
+ elif slot.get("failures"):
489
+ slot["state"] = "FAILED"
490
+ else:
491
+ slot["state"] = "EMPTY"
492
+ return out
493
+
494
+ def restore(self, txid: str, force: bool = False,
495
+ cwd: Optional[str] = None) -> Dict[str, Any]:
496
+ """Undo one transaction. Refuses to overwrite unless force is set.
497
+
498
+ Relocate items move back to their origin paths; snapshot items apply
499
+ the stored stash (apply, never drop - the evidence stays until a
500
+ human prunes it).
501
+ """
502
+ tx = self.transactions().get(txid)
503
+ if not tx:
504
+ return {"ok": False, "error": f"unknown transaction: {txid}"}
505
+ restored: List[str] = []
506
+ conflicts: List[str] = []
507
+ errors: List[str] = []
508
+ for item in tx["items"]:
509
+ if item.get("type") == "relocate":
510
+ origin = item["origin_path"]
511
+ trash = item["trash_path"]
512
+ if not os.path.lexists(trash):
513
+ errors.append(f"quarantine copy vanished: {trash}")
514
+ continue
515
+ if os.path.lexists(origin):
516
+ if not force:
517
+ conflicts.append(origin)
518
+ continue
519
+ if os.path.isdir(origin) and not os.path.islink(origin):
520
+ shutil.rmtree(origin)
521
+ else:
522
+ os.unlink(origin)
523
+ parent = os.path.dirname(origin)
524
+ if parent:
525
+ os.makedirs(parent, exist_ok=True)
526
+ try:
527
+ self._move(trash, origin)
528
+ restored.append(origin)
529
+ except OSError as exc:
530
+ errors.append(f"{origin}: {exc}")
531
+ elif item.get("type") == "snapshot":
532
+ sha = item.get("sha")
533
+ if not sha:
534
+ continue
535
+ apply = subprocess.run(
536
+ ["git", "-C", cwd or self.workspace, "stash", "apply", sha],
537
+ capture_output=True, text=True, timeout=60)
538
+ if apply.returncode == 0:
539
+ restored.append(f"stash:{sha}")
540
+ else:
541
+ errors.append(
542
+ f"stash apply {sha}: {(apply.stderr or '').strip()}")
543
+
544
+ self._manifest_append([{
545
+ "type": "restore", "txid": txid, "force": force,
546
+ "restored": restored, "conflicts": conflicts, "errors": errors,
547
+ }])
548
+ # drop empty quarantine directories for tidy listings
549
+ txdir = os.path.join(self.trash_root, txid)
550
+ try:
551
+ if os.path.isdir(txdir) and not os.listdir(txdir):
552
+ os.rmdir(txdir)
553
+ except OSError:
554
+ pass
555
+ return {"ok": not errors and not conflicts,
556
+ "restored": restored, "conflicts": conflicts, "errors": errors}
557
+
558
+ # ------------------------------------------------------------- status
559
+
560
+ def usage(self) -> Dict[str, Any]:
561
+ """Size/count summary of the quarantine tree."""
562
+ files = 0
563
+ total = 0
564
+ for root, _dirs, names in os.walk(self.trash_root):
565
+ for name in names:
566
+ path = os.path.join(root, name)
567
+ if os.path.islink(path):
568
+ files += 1
569
+ continue
570
+ try:
571
+ total += os.lstat(path).st_size
572
+ files += 1
573
+ except OSError:
574
+ pass
575
+ transactions = self.transactions()
576
+ return {
577
+ "files": files,
578
+ "bytes": total,
579
+ "transactions": len(transactions),
580
+ "restorable_transactions": sum(
581
+ 1 for tx in transactions.values()
582
+ if tx.get("state") == "RESTORABLE"),
583
+ "restorable_items": sum(
584
+ tx.get("restorable_items", 0)
585
+ for tx in transactions.values()),
586
+ }
587
+
588
+ # ------------------------------------------------------ GC lifecycle
589
+
590
+ @staticmethod
591
+ def _parse_ts(value: Optional[str]) -> Optional[float]:
592
+ if not value:
593
+ return None
594
+ try:
595
+ return time.mktime(time.strptime(
596
+ value, "%Y-%m-%dT%H:%M:%SZ")) - time.timezone
597
+ except (ValueError, TypeError):
598
+ return None
599
+
600
+ def tx_inventory(self) -> List[Dict[str, Any]]:
601
+ """Per-transaction age/size facts for retention decisions."""
602
+ inventory: List[Dict[str, Any]] = []
603
+ for txid, tx in self.transactions().items():
604
+ tx_dir = os.path.join(self.trash_root, txid)
605
+ total = 0
606
+ for root, _dirs, names in os.walk(tx_dir):
607
+ for name in names:
608
+ p = os.path.join(root, name)
609
+ if not os.path.islink(p):
610
+ try:
611
+ total += os.lstat(p).st_size
612
+ except OSError:
613
+ pass
614
+ created = self._parse_ts(tx.get("ts"))
615
+ inventory.append({
616
+ "txid": txid, "ts": tx.get("ts"), "created_epoch": created,
617
+ "bytes": total, "items": len(tx["items"]),
618
+ })
619
+ inventory.sort(key=lambda e: e.get("created_epoch") or 0)
620
+ return inventory
621
+
622
+ def gc_plan(self, now: Optional[float] = None,
623
+ retention_days: int = SOFT_RETENTION_DAYS,
624
+ size_limit_bytes: int = SOFT_SIZE_LIMIT_BYTES,
625
+ ) -> Dict[str, Any]:
626
+ """Mark GC_ELIGIBLE entries. Never deletes anything by itself.
627
+
628
+ Eligibility: older than the soft retention window, or - when the
629
+ quarantine exceeds the soft size cap - oldest-first until back
630
+ under the cap. The audit log is never eligible.
631
+ """
632
+ now = now if now is not None else time.time()
633
+ cutoff = now - retention_days * 86400
634
+ inventory = self.tx_inventory()
635
+ total = sum(e["bytes"] for e in inventory)
636
+ eligible: List[Dict[str, Any]] = []
637
+ for entry in inventory:
638
+ created = entry.get("created_epoch")
639
+ if created is not None and created < cutoff:
640
+ eligible.append({**entry, "reason": "age"})
641
+ remaining = total - sum(e["bytes"] for e in eligible)
642
+ if remaining > size_limit_bytes:
643
+ for entry in inventory:
644
+ if any(e["txid"] == entry["txid"] for e in eligible):
645
+ continue
646
+ if remaining <= size_limit_bytes:
647
+ break
648
+ if entry["bytes"] <= 0 and entry["items"] == 0:
649
+ continue
650
+ eligible.append({**entry, "reason": "capacity"})
651
+ remaining -= entry["bytes"]
652
+ return {
653
+ "retention_days": retention_days,
654
+ "size_limit_bytes": size_limit_bytes,
655
+ "total_bytes": total,
656
+ "eligible": eligible,
657
+ "remaining_bytes_after_gc": max(remaining, 0),
658
+ }
659
+
660
+ def validate_gc_targets(self, txids: List[str]) -> List[Tuple[str, str]]:
661
+ """Resolve only manifest-owned direct children of the quarantine."""
662
+ # Validate the whole batch before touching anything: an unsafe ID
663
+ # after a valid one must not cause a partial purge. A directory that
664
+ # is not backed by a manifest transaction is not ours to delete.
665
+ known = self.transactions()
666
+ trash_physical = os.path.realpath(self.trash_root)
667
+ targets: List[Tuple[str, str]] = []
668
+ for txid in txids:
669
+ if not isinstance(txid, str) or not _GC_TXID_RE.fullmatch(txid):
670
+ raise ValueError(f"invalid quarantine transaction id: {txid!r}")
671
+ tx_dir = os.path.join(self.trash_root, txid)
672
+ if os.path.islink(tx_dir):
673
+ raise ValueError(f"refusing symlinked transaction: {txid}")
674
+ if os.path.isdir(tx_dir):
675
+ if txid not in known or known[txid].get("purged"):
676
+ raise ValueError(f"unmanaged quarantine directory: {txid}")
677
+ if os.path.dirname(os.path.realpath(tx_dir)) != trash_physical:
678
+ raise ValueError(f"transaction escapes quarantine: {txid}")
679
+ targets.append((txid, tx_dir))
680
+
681
+ return targets
682
+
683
+ def gc_execute(self, txids: List[str]) -> Dict[str, Any]:
684
+ """Purge validated transactions; write tombstones after removal.
685
+
686
+ Audit records are NEVER removed - the QUARANTINED -> RESTORABLE ->
687
+ GC_ELIGIBLE -> PURGED lifecycle stays fully reconstructible.
688
+ """
689
+ targets = self.validate_gc_targets(txids)
690
+ purged: List[str] = []
691
+ missing: List[str] = []
692
+ for txid, tx_dir in targets:
693
+ if not os.path.isdir(tx_dir):
694
+ missing.append(txid)
695
+ continue
696
+ # Never report PURGED after a failed or partial filesystem remove.
697
+ shutil.rmtree(tx_dir)
698
+ self._manifest_append([{"type": "purged", "txid": txid}])
699
+ purged.append(txid)
700
+ return {"purged": purged, "missing": missing}