@mokuyoaxis/agent-guard 0.2.7 → 0.2.9

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.
@@ -17,7 +17,8 @@ import threading
17
17
 
18
18
  ROOT = Path(__file__).resolve().parents[2]
19
19
  SCRIPTS = ROOT / "skills" / "delete-guard" / "scripts"
20
- TOOLS = frozenset(("safe_delete", "restore", "transactions", "status", "gc_plan"))
20
+ GROUP_TOOLS = frozenset(("cleanup_discover", "cleanup_measure"))
21
+ TOOLS = frozenset(("safe_delete", "restore", "transactions", "status", "gc_plan")) | GROUP_TOOLS
21
22
  MAX_PATHS = 1000
22
23
  TXID_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9_-]*\Z")
23
24
 
@@ -76,7 +77,9 @@ class Operations:
76
77
  if not isinstance(arguments, dict):
77
78
  raise InvalidArguments("tool arguments must be an object")
78
79
  allowed = {"safe_delete": {"paths", "dry_run"}, "restore": {"txid"},
79
- "status": {"tail"}, "transactions": set(), "gc_plan": set()}[name]
80
+ "status": {"tail"}, "transactions": set(), "gc_plan": set(),
81
+ "cleanup_discover": {"scopes", "max_entries", "max_depth"},
82
+ "cleanup_measure": {"scopes", "max_entries", "max_depth"}}[name]
80
83
  if set(arguments) - allowed:
81
84
  raise InvalidArguments("unsupported tool argument")
82
85
  result = dict(arguments)
@@ -102,6 +105,19 @@ class Operations:
102
105
  if type(result.get("tail", 10)) is not int or not 0 <= result.get("tail", 10) <= 100:
103
106
  raise InvalidArguments("tail must be an integer between 0 and 100")
104
107
  result["tail"] = result.get("tail", 10)
108
+ elif name in GROUP_TOOLS:
109
+ scopes = result.get("scopes", [])
110
+ if (not isinstance(scopes, list) or len(scopes) > 64
111
+ or (name == "cleanup_measure" and not scopes)
112
+ or any(not isinstance(path, str) or not path or "\0" in path for path in scopes)):
113
+ raise InvalidArguments("scopes must be at most 64 nonempty literal directory paths; measure requires scopes")
114
+ result["scopes"] = scopes
115
+ for field, maximum in (("max_entries", 10000 if name == "cleanup_discover" else 20000),
116
+ ("max_depth", 4 if name == "cleanup_discover" else 32)):
117
+ value = result.get(field, maximum)
118
+ if type(value) is not int or not 1 <= value <= maximum:
119
+ raise InvalidArguments(field + " must be an integer between 1 and " + str(maximum))
120
+ result[field] = value
105
121
  return result
106
122
 
107
123
  def _quarantine_overlap(self, paths):
@@ -136,8 +152,14 @@ class Operations:
136
152
  command = ["restore.py", "list", "--json"]
137
153
  elif name == "status":
138
154
  command = ["status.py", "--json", "--tail", str(args["tail"])]
139
- else:
155
+ elif name == "gc_plan":
140
156
  command = ["gc.py", "--json"]
157
+ else:
158
+ command = ["cleanup.py", "--json", "--discover" if name == "cleanup_discover" else "--measure",
159
+ "--max-entries", str(args["max_entries"]), "--max-depth", str(args["max_depth"])]
160
+ # Equals syntax keeps even an option-looking literal inside its
161
+ # value, without changing the server's fixed workspace binding.
162
+ command += ["--scope=" + scope for scope in args["scopes"]]
141
163
 
142
164
  # Serialize calls in this server, without changing process cwd or
143
165
  # environment. Other participating processes share Core admission.
@@ -168,6 +190,14 @@ class Operations:
168
190
  return self._failure(name, "MCP_CLI_PROTOCOL_ERROR",
169
191
  "CLI did not return a JSON object; inspect recovery state before retrying",
170
192
  exit_code=child.returncode, may_have_changed=mutating)
193
+ if name in GROUP_TOOLS and child.returncode in (0, 1):
194
+ expected = "cleanup_group_discovery/v1" if name == "cleanup_discover" else "cleanup_group_measurement/v1"
195
+ if result.get("schema") != expected:
196
+ return self._failure(name, "MCP_CLI_PROTOCOL_ERROR", "Unexpected cleanup observation schema",
197
+ exit_code=child.returncode)
198
+ partial = (not result["coverage"]["frontier_complete"] if name == "cleanup_discover"
199
+ else any(not row["size_complete"] for row in result["scopes"]))
200
+ return {"tool": name, "ok": True, "partial": partial, "exit_code": child.returncode, "result": result}
171
201
  # Preserve all existing CLI evidence, including txids/moved paths on
172
202
  # partial failures. A nonzero exit never means 'nothing changed'.
173
203
  return {"tool": name, "ok": child.returncode == 0,
@@ -22,6 +22,9 @@ INSTRUCTIONS = (
22
22
  "or retry an uncertain mutation automatically. Large batches and operator-only actions "
23
23
  "remain in the existing CLI workflow. GC here is preview only. These tools do not "
24
24
  "intercept other shell or editor operations."
25
+ " Use cleanup_discover for a bounded directory overview and cleanup_measure for explicit scopes. "
26
+ "Their observations never grant execution permission. A successful call with partial=true "
27
+ "still has incomplete coverage or unknown whole sizes; inspect those fields and use exact scopes."
25
28
  )
26
29
 
27
30
  TOOL_DEFINITIONS = {
@@ -49,6 +52,20 @@ TOOL_DEFINITIONS = {
49
52
  "description": "Preview existing quarantine transaction GC eligibility and retained space. This tool never executes GC or deletes recovery copies. Execution remains an explicit operator CLI action.",
50
53
  "properties": {}, "required": [], "read_only": True, "destructive": False,
51
54
  },
55
+ "cleanup_discover": {
56
+ "description": "Read-only bounded directory overview in the fixed workspace. Optional scopes continue discovery below exact directories. Runtime/cache ownership labels are hints, not proof of obsolescence. Sizes remain unknown; inspect coverage/unexpanded and partial even when ok=true. No executable plan or deletion permission.",
57
+ "properties": {"scopes": {"type": "array", "items": {"type": "string", "minLength": 1}, "maxItems": 64},
58
+ "max_entries": {"type": "integer", "minimum": 1, "maximum": 10000, "default": 10000},
59
+ "max_depth": {"type": "integer", "minimum": 1, "maximum": 4, "default": 4}},
60
+ "required": [], "read_only": True, "destructive": False,
61
+ },
62
+ "cleanup_measure": {
63
+ "description": "Read-only metadata measurement of explicit non-overlapping directory scopes below the same workspace. Does not follow links or traverse protected subtrees. size_bytes=null means unknown, not zero; observed_bytes excludes protected data. Core projection is not approval. No plan_id, deletion, restore or GC execution.",
64
+ "properties": {"scopes": {"type": "array", "items": {"type": "string", "minLength": 1}, "minItems": 1, "maxItems": 64},
65
+ "max_entries": {"type": "integer", "minimum": 1, "maximum": 20000, "default": 20000},
66
+ "max_depth": {"type": "integer", "minimum": 1, "maximum": 32, "default": 32}},
67
+ "required": ["scopes"], "read_only": True, "destructive": False,
68
+ },
52
69
  }
53
70
 
54
71
 
package/core/cleanup.py CHANGED
@@ -113,6 +113,7 @@ def plan_cleanup(
113
113
  physical_protection.append(os.path.relpath(physical, root).replace(os.sep, "/"))
114
114
  protect = sorted(set(protect + physical_protection))
115
115
  trash = os.path.abspath(os.environ.get("AGENT_GUARD_TRASH", os.path.join(root, TRASH_DIRNAME)))
116
+ trash_physical = os.path.realpath(trash)
116
117
  if classifier.inside_path(trash, root):
117
118
  protect = sorted(set(protect + [os.path.relpath(trash, root).replace(os.sep, "/")]))
118
119
  ctx = policy.PolicyContext(workspace=root, trash_root=trash, base_dir=root,
@@ -127,7 +128,7 @@ def plan_cleanup(
127
128
  if record not in errors:
128
129
  errors.append(record)
129
130
 
130
- def visit(relative: str, depth: int) -> _Node:
131
+ def visit(relative: str, depth: int, entry=None) -> _Node:
131
132
  nonlocal examined
132
133
  node = _Node(relative)
133
134
  nodes.append(node)
@@ -144,12 +145,23 @@ def plan_cleanup(
144
145
  problem(node, "PROTECTED_ALIAS_REQUIRES_EXPLICIT_PROTECT")
145
146
  else:
146
147
  try:
147
- info = os.lstat(absolute)
148
+ info = entry.stat(follow_symlinks=False) if entry is not None else os.lstat(absolute)
148
149
  node.signature = [info.st_dev, info.st_ino, info.st_mode,
149
150
  info.st_size, info.st_mtime_ns, info.st_ctime_ns]
151
+ # Parents were checked before traversal and directory links
152
+ # are never followed. Ordinary files can reuse that location
153
+ # without repeating full boundary/type checks for every leaf.
154
+ # Keep the original classifier for directories, links and
155
+ # special roots (including an invalid trash path below a file).
156
+ ordinary_file = (stat.S_ISREG(info.st_mode)
157
+ and not classifier.protected_ancestor_root(absolute)
158
+ and not (_under(trash, absolute)
159
+ or _under(trash_physical, absolute)))
150
160
  spec = (classifier.classify_paths(["./" + relative], root, root, trash)[0]
151
- if relative != "." else None)
152
- physical = os.path.relpath(os.path.realpath(absolute), root).replace(os.sep, "/")
161
+ if relative != "." and not ordinary_file else None)
162
+ physical = os.path.relpath(
163
+ absolute if ordinary_file else os.path.realpath(absolute), root
164
+ ).replace(os.sep, "/")
153
165
  if ((spec and spec.protected) or set(physical.split("/")) & PROTECTED_NAMES
154
166
  or any(_under(physical, p) for p in protect)
155
167
  or (stat.S_ISLNK(info.st_mode)
@@ -160,20 +172,21 @@ def plan_cleanup(
160
172
  if depth >= max_depth:
161
173
  problem(node, "DEPTH_LIMIT_REACHED")
162
174
  else:
163
- names = []
175
+ children = []
164
176
  with os.scandir(absolute) as entries:
165
- for entry in entries:
166
- if examined + len(names) >= max_entries:
177
+ for child_entry in entries:
178
+ if examined + len(children) >= max_entries:
167
179
  problem(node, "ENTRY_LIMIT_REACHED")
168
180
  break
169
- names.append(entry.name)
170
- for name in sorted(names):
181
+ children.append(child_entry)
182
+ for child_entry in sorted(children, key=lambda item: item.name):
171
183
  if examined >= max_entries:
172
184
  problem(node, "ENTRY_LIMIT_REACHED")
173
185
  break
186
+ name = child_entry.name
174
187
  examined += 1
175
188
  child = visit(name if relative == "." else relative + "/" + name,
176
- depth + 1)
189
+ depth + 1, child_entry)
177
190
  node.children.append(child)
178
191
  node.files.update(child.files)
179
192
  node.complete &= child.complete
@@ -206,6 +219,12 @@ def plan_cleanup(
206
219
  parts = path.split("/")
207
220
  tracked_ancestors.update("/".join(parts[:i]) for i in range(1, len(parts)))
208
221
 
222
+ def git_ignored(workspace, absolute):
223
+ return os.path.relpath(absolute, root).replace(os.sep, "/") in ignored
224
+
225
+ def regenerable(specs, context):
226
+ return policy._regenerable(specs, context, git_ignored)
227
+
209
228
  def row(node: _Node, category: str, reason: str) -> Dict[str, Any]:
210
229
  result = {
211
230
  "path": node.path, "kind": node.kind, "category": category,
@@ -220,7 +239,10 @@ def plan_cleanup(
220
239
  # Concrete, relative spelling also used by the execution CLI.
221
240
  spelling = "./" + node.path
222
241
  specs = classifier.classify_paths([spelling], root, root, trash)
223
- verdict = policy.decide_path_batch(specs, ctx, recursive=True)
242
+ verdict = policy._decide_path_batch(
243
+ specs, ctx, recursive=True,
244
+ config_loader=lambda workspace: delete_config,
245
+ regenerable_check=regenerable)
224
246
  result["policy_code"] = verdict.code
225
247
  literal = (not specs[0].wildcard and not specs[0].indeterminable
226
248
  and specs[0].resolved == os.path.join(root, node.path))
@@ -0,0 +1,329 @@
1
+ """Read-only cleanup groups; observation never grants deletion permission.
2
+
3
+ Discovery is a bounded directory frontier. Measurement keeps the original
4
+ workspace and omits protected subtrees. Neither produces an executable plan.
5
+ """
6
+ from collections import Counter
7
+ import errno
8
+ import hashlib
9
+ import heapq
10
+ import json
11
+ import os
12
+ from pathlib import Path
13
+ import stat
14
+
15
+ from core import classifier, policy
16
+ from core.cleanup import PROTECTED_NAMES, _git_facts
17
+ from core.delete_config import load_config
18
+
19
+ TAG = b'Signature: 8a477f597d28d172789f06886806bc55'
20
+ LABELS = {'protected': '受保护', 'runtime': '运行环境', 'managed_cache': '应用管理缓存',
21
+ 'cache_hint': '缓存提示', 'artifact': '构建工件', 'link': '未跟随链接'}
22
+
23
+
24
+ def under(path, parent):
25
+ return parent == '.' or path == parent or path.startswith(parent + '/')
26
+
27
+
28
+ def signature(info):
29
+ return [info.st_dev, info.st_ino, info.st_mode, info.st_size, info.st_mtime_ns, info.st_ctime_ns]
30
+
31
+
32
+ def positive(value):
33
+ if type(value) is not int or value < 1:
34
+ raise ValueError('scan limits must be positive integers')
35
+ return value
36
+
37
+
38
+ class GroupScanner:
39
+ def __init__(self, workspace):
40
+ self.root = Path(workspace).resolve(strict=True)
41
+ if not self.root.is_dir() or classifier.protected_ancestor_root(str(self.root)):
42
+ raise ValueError('workspace must be an existing non-root project directory')
43
+ self.config = load_config(str(self.root))
44
+ self.guard_config = policy.GuardConfig.from_env()
45
+ self.protect = set(PROTECTED_NAMES) | {name.replace(os.sep, '/') for name in self.config.protected_paths}
46
+ self.trash = os.path.abspath(os.environ.get('AGENT_GUARD_TRASH', self.root / '.agent-trash'))
47
+ if classifier.inside_path(self.trash, str(self.root)):
48
+ relative = os.path.relpath(self.trash, self.root).replace(os.sep, '/')
49
+ self.protect.add(relative.split('/')[0])
50
+ for name in list(self.protect):
51
+ physical = os.path.realpath(self.root / name)
52
+ if classifier.inside_path(physical, str(self.root)):
53
+ self.protect.add(os.path.relpath(physical, self.root).replace(os.sep, '/'))
54
+ self.marker_bytes = 0
55
+
56
+ def protected(self, relative):
57
+ return bool(set(relative.split('/')) & PROTECTED_NAMES) or any(under(relative, path) for path in self.protect)
58
+
59
+ def marker(self, relative, name, *, header=False):
60
+ path = self.root / relative / name
61
+ try:
62
+ info = path.lstat()
63
+ except FileNotFoundError:
64
+ return False
65
+ if not stat.S_ISREG(info.st_mode):
66
+ return False
67
+ if not header:
68
+ return True
69
+ descriptor = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
70
+ try:
71
+ if not stat.S_ISREG(os.fstat(descriptor).st_mode):
72
+ raise OSError(errno.EAGAIN, 'cache marker changed to a non-regular file')
73
+ data = os.read(descriptor, len(TAG))
74
+ self.marker_bytes += len(data)
75
+ return data == TAG
76
+ finally:
77
+ os.close(descriptor)
78
+
79
+ def describe(self, relative):
80
+ if self.protected(relative):
81
+ kind, evidence = 'protected', ['Protected project, configuration or recovery boundary']
82
+ elif self.marker(relative, 'pyvenv.cfg'):
83
+ kind, evidence = 'runtime', ['Regular pyvenv.cfg; environment, not proof of obsolescence or activity']
84
+ elif self.marker(relative, 'CACHEDIR.TAG', header=True):
85
+ if Path(relative).name == 'uv':
86
+ kind, evidence = 'managed_cache', ['Valid CACHEDIR.TAG and name uv; ownership hint, not authentication']
87
+ elif policy._matches_artifact(relative, self.guard_config.artifact_patterns):
88
+ kind, evidence = 'artifact', ['Valid CACHEDIR.TAG and known artifact pattern']
89
+ else:
90
+ kind, evidence = 'cache_hint', ['Valid CACHEDIR.TAG; owner and cleanup protocol unverified']
91
+ elif policy._matches_artifact(relative, self.guard_config.artifact_patterns):
92
+ kind, evidence = 'artifact', ['Known artifact pattern; Git proof and interior inspection pending']
93
+ else:
94
+ return None
95
+ return {'path': relative, 'kind': kind, 'category': 'protected' if kind == 'protected' else 'uncertain',
96
+ 'managed_by': 'uv (hint)' if kind == 'managed_cache' else None,
97
+ 'evidence': evidence, 'size_bytes': None, 'size_complete': False,
98
+ 'interior_checked': False, 'selectable': False}
99
+
100
+ def classify(self, groups):
101
+ candidates = [row['path'] for row in groups if row['kind'] != 'protected']
102
+ tracked, ignored, warning = _git_facts(str(self.root), candidates) if candidates else (set(), set(), None)
103
+ for row in groups:
104
+ path = row['path']
105
+ declared_inside = any(other != path and under(other, path) for other in self.protect)
106
+ tracked_inside = any(under(other, path) for other in tracked)
107
+ row['git_ignored'] = path in ignored
108
+ row['tracked_descendant'] = tracked_inside
109
+ row['declared_protected_descendant'] = declared_inside
110
+ if row['kind'] == 'artifact' and path in ignored and not tracked_inside and not declared_inside and not row.get('protected_roots'):
111
+ row['category'] = 'regenerable'
112
+ row['evidence'].append('Git-ignored with no tracked descendants; read-only hint only')
113
+ return warning, ignored
114
+
115
+ def discover(self, values=(), *, max_depth=4, max_entries=10000, max_directories=256, per_directory=512):
116
+ for value in [max_depth, max_entries, max_directories, per_directory]:
117
+ positive(value)
118
+ scopes = self.scopes(values) if values else ['.']
119
+ queue = [(1, 0, scope) for scope in scopes]
120
+ heapq.heapify(queue)
121
+ groups, deferred, issues, limits = [], [], [], []
122
+ branches = Counter()
123
+ examined = expanded = 0
124
+ while queue:
125
+ _, depth, relative = heapq.heappop(queue)
126
+ try:
127
+ if relative != '.':
128
+ info = (self.root / relative).lstat()
129
+ if stat.S_ISLNK(info.st_mode):
130
+ deferred.append({'path': relative, 'reason': 'LINK_NOT_FOLLOWED'})
131
+ continue
132
+ if not stat.S_ISDIR(info.st_mode):
133
+ issues.append({'path': relative, 'code': 'SOURCE_TYPE_CHANGED'})
134
+ continue
135
+ group = self.describe(relative)
136
+ if group:
137
+ groups.append(group)
138
+ deferred.append({'path': relative, 'reason': group['kind'].upper() + '_NOT_EXPANDED'})
139
+ continue
140
+ else:
141
+ info = self.root.lstat()
142
+ if self.protected('.'):
143
+ groups.append(self.describe('.'))
144
+ deferred.append({'path': '.', 'reason': 'PROTECTED_NOT_EXPANDED'})
145
+ continue
146
+ if depth >= max_depth:
147
+ deferred.append({'path': relative, 'reason': 'DEPTH_FRONTIER'})
148
+ continue
149
+ if expanded >= max_directories or examined >= max_entries:
150
+ limits.append({'path': relative, 'code': 'GLOBAL_DISCOVERY_LIMIT'})
151
+ deferred.extend({'path': name, 'reason': 'GLOBAL_DISCOVERY_LIMIT'} for name in [relative, *(item[2] for item in queue)])
152
+ break
153
+ expanded += 1
154
+ children = []
155
+ with os.scandir(self.root / relative) as entries:
156
+ for index, entry in enumerate(entries):
157
+ if index >= per_directory or examined >= max_entries:
158
+ limits.append({'path': relative, 'code': 'DIRECTORY_ENTRY_LIMIT' if index >= per_directory else 'GLOBAL_ENTRY_LIMIT'})
159
+ deferred.append({'path': relative, 'reason': 'DIRECTORY_REMAINDER_UNOBSERVED'})
160
+ break
161
+ examined += 1
162
+ path = entry.name if relative == '.' else relative + '/' + entry.name
163
+ if self.protected(path):
164
+ groups.append(self.describe(path))
165
+ deferred.append({'path': path, 'reason': 'PROTECTED_NOT_EXPANDED'})
166
+ elif entry.is_symlink():
167
+ deferred.append({'path': path, 'reason': 'LINK_NOT_FOLLOWED'})
168
+ elif entry.is_dir(follow_symlinks=False):
169
+ children.append(path)
170
+ else:
171
+ branches[path.split('/')[0] if '/' in path else '.'] += 1
172
+ if signature((self.root / relative).lstat()) != signature(info):
173
+ issues.append({'path': relative, 'code': 'SOURCE_CHANGED_DURING_SCAN'})
174
+ for path in children:
175
+ # Hints affect scheduling only. Markers, Git facts and
176
+ # protection still determine the read-only group label.
177
+ hinted = (bool(set(path.split('/')) & {'cache', '.cache', 'uv'})
178
+ or policy._matches_artifact(path, self.guard_config.artifact_patterns))
179
+ heapq.heappush(queue, (0 if hinted else 1, depth + 1, path))
180
+ except OSError as error:
181
+ issues.append({'path': relative, 'code': 'OS_ERROR', 'errno': error.errno})
182
+ groups.sort(key=lambda row: row['path'])
183
+ warning, _ = self.classify(groups)
184
+ overview = []
185
+ for kind, label in LABELS.items():
186
+ paths = [row['path'] for row in groups if row['kind'] == kind]
187
+ if paths:
188
+ overview.append({'label': label, 'kind': kind, 'groups': len(paths), 'examples': paths[:3], 'size_bytes': None})
189
+ overview.append({'label': '待复核目录/根文件', 'kind': 'review', 'branches': len(branches), 'observed_files': sum(branches.values()), 'size_bytes': None})
190
+ result = {'schema': 'cleanup_group_discovery/v1', 'workspace': str(self.root), 'operation': 'read_only_discovery',
191
+ 'execution_supported': False, 'groups': groups, 'overview': overview,
192
+ 'coverage': {'scopes': scopes, 'frontier_depth': max_depth,
193
+ 'budgets': {'max_entries': max_entries, 'max_directories': max_directories, 'per_directory': per_directory}, 'frontier_complete': not issues and not limits,
194
+ 'workspace_scan_complete': False, 'entries_examined': examined,
195
+ 'directories_expanded': expanded, 'unexpanded': deferred, 'limits': limits, 'issues': issues},
196
+ 'review_branches': dict(sorted(branches.items())), 'warnings': [warning] if warning else [],
197
+ 'marker_bytes_read': self.marker_bytes,
198
+ 'notice': 'Read-only directory overview. Unknown sizes are not zero; unexpanded interiors and execution remain unverified.'}
199
+ result['observation_id'] = hashlib.sha256(json.dumps(result, sort_keys=True).encode()).hexdigest()
200
+ return result
201
+
202
+ def scopes(self, values):
203
+ if not values:
204
+ raise ValueError('measure requires at least one explicit scope')
205
+ selected = []
206
+ for value in values:
207
+ absolute = os.path.abspath(self.root / value)
208
+ if absolute == str(self.root) or not classifier.inside_path(absolute, str(self.root)):
209
+ raise ValueError('scope must be below the fixed workspace')
210
+ relative = os.path.relpath(absolute, self.root).replace(os.sep, '/')
211
+ path = self.root
212
+ for component in Path(relative).parts:
213
+ path /= component
214
+ info = path.lstat()
215
+ if stat.S_ISLNK(info.st_mode) or not stat.S_ISDIR(info.st_mode):
216
+ raise ValueError('scope components must be real directories, without aliases')
217
+ if self.protected(relative):
218
+ raise ValueError('protected scope cannot be measured')
219
+ if any(under(relative, other) or under(other, relative) for other in selected):
220
+ raise ValueError('scopes must not overlap')
221
+ selected.append(relative)
222
+ return sorted(selected)
223
+
224
+ def measure(self, values, *, max_entries=20000, max_depth=32):
225
+ positive(max_entries)
226
+ positive(max_depth)
227
+ scopes = self.scopes(values)
228
+ rows, all_inodes = [], {}
229
+ total_examined = 0
230
+ for scope in scopes:
231
+ description = self.describe(scope) or {'path': scope, 'kind': 'review', 'category': 'uncertain', 'managed_by': None, 'evidence': ['No cache or regeneration evidence'], 'selectable': False}
232
+ seen, protected, issues, special = {}, {}, [], []
233
+ digest = hashlib.sha256()
234
+ count = regular = links = directories = 0
235
+ for path in sorted(self.protect):
236
+ if path != scope and under(path, scope):
237
+ protected[path] = 'Declared protected descendant; size unmeasured'
238
+
239
+ def visit(relative, depth):
240
+ nonlocal count, regular, links, directories, total_examined
241
+ if self.protected(relative):
242
+ protected[relative] = 'Protected subtree; not traversed or sized'
243
+ return
244
+ if total_examined >= max_entries:
245
+ issues.append({'path': relative, 'code': 'ENTRY_LIMIT_REACHED'})
246
+ return
247
+ count += 1
248
+ total_examined += 1
249
+ try:
250
+ info = (self.root / relative).lstat()
251
+ if stat.S_ISLNK(info.st_mode):
252
+ spec = classifier.classify_paths(['./' + relative], str(self.root), str(self.root), self.trash)[0]
253
+ if spec.error or spec.indeterminable or spec.wildcard:
254
+ issues.append({'path': relative, 'code': 'LINK_API_UNDETERMINABLE'})
255
+ return
256
+ if not spec.is_symlink:
257
+ issues.append({'path': relative, 'code': 'SOURCE_TYPE_CHANGED'})
258
+ return
259
+ destination = os.path.relpath(spec.link_target, self.root).replace(os.sep, '/')
260
+ if spec.protected or self.protected(destination):
261
+ protected[relative] = 'Protected link boundary; destination not traversed'
262
+ return
263
+ digest.update(json.dumps([relative, signature(info)], separators=(',', ':')).encode() + b'\n')
264
+ if stat.S_ISDIR(info.st_mode):
265
+ directories += 1
266
+ if depth >= max_depth:
267
+ issues.append({'path': relative, 'code': 'DEPTH_LIMIT_REACHED'})
268
+ return
269
+ names = []
270
+ with os.scandir(self.root / relative) as entries:
271
+ for entry in entries:
272
+ if total_examined + len(names) >= max_entries:
273
+ issues.append({'path': relative, 'code': 'ENTRY_LIMIT_REACHED'})
274
+ break
275
+ names.append(entry.name)
276
+ for name in sorted(names):
277
+ if total_examined >= max_entries:
278
+ issues.append({'path': relative + '/' + name, 'code': 'ENTRY_LIMIT_REACHED'})
279
+ break
280
+ visit(relative + '/' + name, depth + 1)
281
+ if signature((self.root / relative).lstat()) != signature(info):
282
+ issues.append({'path': relative, 'code': 'SOURCE_CHANGED_DURING_SCAN'})
283
+ elif stat.S_ISREG(info.st_mode) or stat.S_ISLNK(info.st_mode):
284
+ regular += stat.S_ISREG(info.st_mode)
285
+ links += stat.S_ISLNK(info.st_mode)
286
+ seen[info.st_dev, info.st_ino] = info.st_size
287
+ all_inodes[info.st_dev, info.st_ino] = info.st_size
288
+ else:
289
+ special.append(relative)
290
+ except OSError as error:
291
+ issues.append({'path': relative, 'code': 'OS_ERROR', 'errno': error.errno})
292
+
293
+ visit(scope, 0)
294
+ observed_complete = not issues and not special
295
+ whole_complete = observed_complete and not protected
296
+ description.update(entries_examined=count, regular_files=regular, symlinks=links, directories=directories,
297
+ observed_bytes=sum(seen.values()), size_bytes=sum(seen.values()) if whole_complete else None,
298
+ size_complete=whole_complete, observed_subset_complete=observed_complete,
299
+ protected_roots=protected, issues=issues, special_entries=special,
300
+ metadata_digest=digest.hexdigest(), interior_checked=whole_complete,
301
+ approval='NOT_GRANTED', budget='NOT_CHECKED', core_policy=None)
302
+ rows.append(description)
303
+ warning, ignored = self.classify(rows)
304
+ for row in rows:
305
+ if row['category'] == 'regenerable' and row['size_complete']:
306
+ specs = classifier.classify_paths(['./' + row['path']], str(self.root), str(self.root), self.trash)
307
+ ctx = policy.PolicyContext(workspace=str(self.root), trash_root=self.trash, base_dir=str(self.root), mode=policy.load_mode(self.trash)['mode'], config=self.guard_config)
308
+ def regenerable(batch, context):
309
+ return policy._regenerable(batch, context, lambda workspace, absolute: os.path.relpath(absolute, self.root).replace(os.sep, '/') in ignored)
310
+ verdict = policy._decide_path_batch(specs, ctx, recursive=True, config_loader=lambda workspace: self.config, regenerable_check=regenerable)
311
+ row['core_policy'] = {'decision': verdict.decision, 'code': verdict.code}
312
+ result = {'schema': 'cleanup_group_measurement/v1', 'workspace': str(self.root), 'operation': 'read_only_measurement',
313
+ 'execution_supported': False, 'scopes': rows, 'unique_observed_bytes_across_scopes': sum(all_inodes.values()),
314
+ 'warnings': [warning] if warning else [], 'marker_bytes_read': self.marker_bytes,
315
+ 'entries_examined': total_examined, 'limits': {'max_entries': max_entries, 'max_depth': max_depth},
316
+ 'notice': 'Metadata observation only; protected bytes omitted, links not followed, no deletion permission or atomic content snapshot.'}
317
+ result['observation_id'] = hashlib.sha256(json.dumps(result, sort_keys=True).encode()).hexdigest()
318
+ return result
319
+
320
+
321
+
322
+ def discover_groups(workspace, scopes=(), **limits):
323
+ """Observe a bounded frontier below the original workspace or exact scopes."""
324
+ return GroupScanner(workspace).discover(scopes, **limits)
325
+
326
+
327
+ def measure_groups(workspace, scopes, **limits):
328
+ """Measure explicit non-overlapping directories, never following links."""
329
+ return GroupScanner(workspace).measure(scopes, **limits)
package/core/policy.py CHANGED
@@ -473,6 +473,11 @@ def regenerable(specs: List[PathSpec], ctx: PolicyContext) -> bool:
473
473
  and the decision table are untouched. ``spec.resolved`` is still handed
474
474
  to git unchanged.
475
475
  """
476
+ return _regenerable(specs, ctx, is_git_ignored)
477
+
478
+
479
+ def _regenerable(specs, ctx, git_ignored):
480
+ """Shared rule; the planner supplies only its scan-local Git facts."""
476
481
  if not ctx.config.allow_regenerable:
477
482
  return False
478
483
  for spec in specs:
@@ -482,7 +487,7 @@ def regenerable(specs: List[PathSpec], ctx: PolicyContext) -> bool:
482
487
  _physical(ctx.workspace))
483
488
  if not _matches_artifact(rel, ctx.config.artifact_patterns):
484
489
  return False
485
- if not is_git_ignored(ctx.workspace, spec.resolved):
490
+ if not git_ignored(ctx.workspace, spec.resolved):
486
491
  return False
487
492
  return True
488
493
 
@@ -500,6 +505,18 @@ def _block_undeterminable_effect(spec: OpSpec) -> Verdict:
500
505
  def decide_path_batch(specs: List[PathSpec], ctx: PolicyContext,
501
506
  recursive: bool) -> Verdict:
502
507
  """One batch of concrete deletion targets through the rule table."""
508
+ return _decide_path_batch(specs, ctx, recursive,
509
+ config_loader=delete_config.load_config,
510
+ regenerable_check=regenerable)
511
+
512
+
513
+ def _decide_path_batch(specs, ctx, recursive, *, config_loader,
514
+ regenerable_check):
515
+ """Same decision table for live execution and scan-local projection.
516
+
517
+ Actual deletion always enters decide_path_batch and reads fresh facts.
518
+ Planning may reuse facts within its single reviewed metadata snapshot.
519
+ """
503
520
  reasons: List[str] = []
504
521
 
505
522
  errored = [s for s in specs if s.error or s.indeterminable]
@@ -533,7 +550,7 @@ def decide_path_batch(specs: List[PathSpec], ctx: PolicyContext,
533
550
  for s in protected_outside[:5]])
534
551
 
535
552
  try:
536
- deletion_config = delete_config.load_config(ctx.workspace)
553
+ deletion_config = config_loader(ctx.workspace)
537
554
  protection = delete_config.protected_reason(
538
555
  [s.resolved for s in specs if s.resolved], ctx.workspace,
539
556
  deletion_config)
@@ -569,7 +586,7 @@ def decide_path_batch(specs: List[PathSpec], ctx: PolicyContext,
569
586
  ["restricted mode permits only explicit single-file "
570
587
  "deletes inside the workspace"])
571
588
 
572
- if recursive and regenerable(specs, ctx):
589
+ if recursive and regenerable_check(specs, ctx):
573
590
  return Verdict(DECISION_ALLOW, CODE_ALLOW_REGENERABLE,
574
591
  ["all targets are git-ignored and match known "
575
592
  "artifact patterns"])