@mokuyoaxis/agent-guard 0.2.8 → 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.
- package/CONTRIBUTING.md +13 -0
- package/README.md +18 -15
- package/README.zh-CN.md +16 -14
- package/adapters/INTEGRATION.md +9 -3
- package/adapters/mcp/doctor.py +4 -3
- package/adapters/mcp/operations.py +33 -3
- package/adapters/mcp/server.py +17 -0
- package/core/cleanup.py +33 -11
- package/core/cleanup_groups.py +329 -0
- package/core/policy.py +20 -3
- package/docs/README.md +16 -7
- package/docs/design/architecture.md +31 -1
- package/docs/design/compatibility.md +52 -1
- package/docs/guides/cleanup-plan.md +97 -0
- package/docs/guides/getting-started.md +7 -7
- package/docs/guides/harness-capabilities.md +8 -1
- package/docs/guides/mcp.md +69 -5
- package/docs/releases/release-notes-0.2.9.md +68 -0
- package/docs/releases/unreleased.md +155 -1
- package/package.json +1 -1
- package/skills/delete-guard/SKILL.md +27 -1
- package/skills/delete-guard/scripts/cleanup.py +48 -3
|
@@ -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
|
|
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 =
|
|
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
|
|
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"])
|
package/docs/README.md
CHANGED
|
@@ -16,12 +16,13 @@ Cleanup Copilot, deletion admission and the current MCP tools/doctor are
|
|
|
16
16
|
Delete-guard functions. [Recovery-audit](../skills/recovery-audit/SKILL.md)
|
|
17
17
|
is an auxiliary incident-recovery workflow.
|
|
18
18
|
|
|
19
|
-
Version [0.2.
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
19
|
+
Version [0.2.9](releases/release-notes-0.2.9.md) adds read-only Cleanup
|
|
20
|
+
inventory and selected-scope measurement through CLI and MCP, faster plan
|
|
21
|
+
scans and a repository-corpus test fix. The earlier
|
|
22
|
+
[0.2.8](releases/release-notes-0.2.8.md) adds MCP diagnosis and recovery validation.
|
|
23
|
+
Before installing 0.2.9,
|
|
24
|
+
check the exact [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.9)
|
|
25
|
+
and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.9)
|
|
25
26
|
for availability. A checkout or manifest does not establish publication or
|
|
26
27
|
the current npm `latest` channel.
|
|
27
28
|
The opt-in `rc` line remains [0.2.5-rc3](releases/release-notes-0.2.5-rc3.md), and `hotfix` is the
|
|
@@ -38,6 +39,11 @@ need an upgrade to acquire those additions; see its [version notes](releases/rel
|
|
|
38
39
|
Cleanup、删除限制与当前 MCP 工具/doctor 归入 Delete-guard。测试报告按所测版本与配置保留;发布记录、
|
|
39
40
|
历史设计和外部案例各自归档,不能据此扩展当前产品的承诺。
|
|
40
41
|
|
|
42
|
+
0.2.9 新增[目录概况与计量](guides/cleanup-plan.md#directory-overview-and-measurement-029)
|
|
43
|
+
及两个[只读 MCP 工具](guides/mcp.md#cleanup-observations-unreleased),仍归属 Cleanup Copilot;
|
|
44
|
+
0.2.8 不含这些新增能力。[变更摘要](releases/unreleased.md#current-unreleased-scope)
|
|
45
|
+
汇总当前范围与验证,历史失败和各版发行记录在其后保留。
|
|
46
|
+
|
|
41
47
|
| Category / 分类 | Contents / 内容 |
|
|
42
48
|
|---|---|
|
|
43
49
|
| [Guides](#guides) / 使用指南 | 宿主接入证据、漂移检查、维护者发布指南 |
|
|
@@ -58,8 +64,10 @@ ALLOW_NOOP 覆盖边界及准确 GC 用法;纳入 0.2.5。
|
|
|
58
64
|
| [Getting started](guides/getting-started.md) | 安装路径、Agent 接入提示词与最短验证流程 |
|
|
59
65
|
| [Status and cleanup feedback](guides/recovery-feedback.md) | Python/插件状态、ALLOW_NOOP、保留空间与手动 GC |
|
|
60
66
|
| [Cleanup Copilot](guides/cleanup-plan.md) | Delete-guard,0.2.7:零写入计划、四类候选、大小与显式确认执行 |
|
|
67
|
+
| [Directory overview and measurement](guides/cleanup-plan.md#directory-overview-and-measurement-029) | Delete-guard,0.2.9:先概况、再按范围发现/计量;没有执行许可 |
|
|
61
68
|
| [Deletion limits](guides/deletion-limits.md) | Delete-guard,0.2.7:隔离容量、会话预算、频率、保护路径与批量确认 |
|
|
62
69
|
| [Local MCP tools](guides/mcp.md) | Delete-guard,0.2.7:本地 stdio 安全删除、普通恢复、事务/状态和 GC 预览;不替代 hook |
|
|
70
|
+
| [Read-only cleanup MCP](guides/mcp.md#cleanup-observations-029) | Delete-guard,0.2.9:cleanup_discover/cleanup_measure、固定工作区与部分观察状态 |
|
|
63
71
|
| [MCP diagnosis](guides/mcp.md#diagnose-a-local-service-028) | Delete-guard,0.2.8:选定本地服务的依赖、握手、工作区绑定与只读调用检查 |
|
|
64
72
|
| [Harness capabilities](guides/harness-capabilities.md) | 当前接入范围、证据等级与未验证路径 |
|
|
65
73
|
| [Host drift](guides/host-drift.md) | 宿主版本、配置与本地基线检查 |
|
|
@@ -140,10 +148,11 @@ coverage rather than treating every historical result as current acceptance.
|
|
|
140
148
|
|
|
141
149
|
| Document / 文档 | Scope / 范围 |
|
|
142
150
|
|---|---|
|
|
151
|
+
| [0.2.9](releases/release-notes-0.2.9.md) | 目录概况/计量、两只读 MCP 工具、扫描提速与语料门修复 |
|
|
143
152
|
| [0.2.8](releases/release-notes-0.2.8.md) | MCP 接入诊断、真实协议中断验证、安装与验收边界 |
|
|
144
153
|
| [0.2.7](releases/release-notes-0.2.7.md) | Cleanup、删除准入与MCP的版本范围、升级影响和准备阶段验证 |
|
|
145
154
|
| [0.2.6](releases/release-notes-0.2.6.md) | 正式版范围、升级影响与验收;Kimi 反馈/doctor、DSH 预检与版本扩展 |
|
|
146
|
-
| [Changes and maintenance details](releases/unreleased.md) | 0.2.
|
|
155
|
+
| [Changes and maintenance details](releases/unreleased.md) | 0.2.9 范围与本地验证;其后保留0.2.8、0.2.7及更早维护历史 |
|
|
147
156
|
| [0.2.5](releases/release-notes-0.2.5.md) | 正式版范围;累计 RC 维护、明确反馈与升级影响 |
|
|
148
157
|
| [0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1) | 已发布的稳定线回收站保护回补;不含完整 RC 累计内容 |
|
|
149
158
|
| [0.2.5-rc3](releases/release-notes-0.2.5-rc3.md) | 已发布的研究/文档预发布版与零模型示例 |
|
|
@@ -18,7 +18,7 @@ see the [capability matrix](../guides/harness-capabilities.md).
|
|
|
18
18
|
| Main capability | Functions and implementation | Contract and guides |
|
|
19
19
|
|---|---|---|
|
|
20
20
|
| **Exfil-guard** | Text detection/redaction in `core/redaction.py`, disclosure decisions in `core/policy.py`, and safe config views in `core/safe_view.py` | [Exfil-guard Skill](../../skills/exfil-guard/SKILL.md) |
|
|
21
|
-
| **Delete-guard** | Classification, authorization, recovery and audit; Cleanup Copilot delegates execution to `safe_delete`;
|
|
21
|
+
| **Delete-guard** | Classification, authorization, recovery and audit; Cleanup Copilot includes read-only inventory/measurement and delegates reviewed execution to `safe_delete`; MCP exposes explicit tools while its doctor performs read-only state queries | [Delete-guard Skill](../../skills/delete-guard/SKILL.md) · [Cleanup](../guides/cleanup-plan.md) · [Limits](../guides/deletion-limits.md) · [MCP](../guides/mcp.md) |
|
|
22
22
|
| **Guard-lab** | `guard_lab.py` and `core/lab.py` provide a user-controlled diagnostic plane: calibration, declared-channel observation and matched comparisons | [Lab workflow and evidence](../lab/guard-lab.md) |
|
|
23
23
|
|
|
24
24
|
Core and adapters provide shared infrastructure. The
|
|
@@ -291,6 +291,30 @@ FORBIDDEN (BLOCK, never askable).
|
|
|
291
291
|
feed a Lab observation into Core policy or claim to ban model calls. A real
|
|
292
292
|
block would require a host hook or request gateway that owns the call.
|
|
293
293
|
|
|
294
|
+
<a id="read-only-cleanup-observations-unreleased"></a>
|
|
295
|
+
|
|
296
|
+
## Read-only cleanup observations (0.2.9)
|
|
297
|
+
|
|
298
|
+
`core/cleanup_groups.py` supplies bounded directory-group discovery and
|
|
299
|
+
explicit-scope measurement to the Cleanup CLI. The MCP adapter delegates its
|
|
300
|
+
two new read-only tools to that same CLI, keeping one implementation and a
|
|
301
|
+
fixed original workspace. This addition starts in 0.2.9 and is absent from 0.2.8.
|
|
302
|
+
|
|
303
|
+
Discovery reads a shallow frontier, recognizes environments before cache
|
|
304
|
+
markers, and groups application-managed caches without expanding them.
|
|
305
|
+
Path hints prioritize work within the existing budget; incomplete frontiers
|
|
306
|
+
and unknown sizes stay explicit. A follow-up scope is a new bounded
|
|
307
|
+
observation, not a whole-workspace completion claim. Measurement streams
|
|
308
|
+
metadata into a digest and per-scope/global inode maps, omits protected
|
|
309
|
+
subtrees, and never follows links. Observed subset completeness is separate
|
|
310
|
+
from whole-size completeness.
|
|
311
|
+
|
|
312
|
+
Independent observation schemas and IDs cannot be used as executable Cleanup
|
|
313
|
+
plans. All rows remain nonselectable. A shared Core projection for complete
|
|
314
|
+
ordinary artifacts does not check admission or grant approval. The existing
|
|
315
|
+
plan confirmation and safe_delete pipeline remains responsible for mutation.
|
|
316
|
+
See [result and limit contracts](../guides/cleanup-plan.md#directory-overview-and-measurement-unreleased).
|
|
317
|
+
|
|
294
318
|
## Read-only quarantine queries
|
|
295
319
|
|
|
296
320
|
core/trash_index.py exposes list_trash_locations for CLI, agent and future
|
|
@@ -318,6 +342,12 @@ order of value:
|
|
|
318
342
|
|
|
319
343
|
## Delivery status and design directions
|
|
320
344
|
|
|
345
|
+
Version [0.2.9](../releases/release-notes-0.2.9.md) adds read-only directory
|
|
346
|
+
observations and two MCP tools, speeds up existing planning, and corrects
|
|
347
|
+
the normal-corpus test boundary. The original five operations and mutation
|
|
348
|
+
contracts remain in place. The version decision is recorded in
|
|
349
|
+
[compatibility](compatibility.md#029-cleanup-maintenance-decision).
|
|
350
|
+
|
|
321
351
|
Version [0.2.8](../releases/release-notes-0.2.8.md) adds MCP connection
|
|
322
352
|
diagnosis and protocol-interruption validation. The existing five tools,
|
|
323
353
|
deletion policy and recovery format
|
|
@@ -4,6 +4,8 @@ agent-guard's promise is recoverability. A promise is only as good as its
|
|
|
4
4
|
stability over time - this page states exactly what may change and what
|
|
5
5
|
may not, per release class.
|
|
6
6
|
|
|
7
|
+
Version [0.2.9](../releases/release-notes-0.2.9.md) adds read-only Cleanup
|
|
8
|
+
inventory and measurement, faster planning and a repository-corpus test fix.
|
|
7
9
|
Version [0.2.8](../releases/release-notes-0.2.8.md) adds diagnosis and
|
|
8
10
|
reliability maintenance to the published
|
|
9
11
|
[0.2.7](../releases/release-notes-0.2.7.md) baseline. Use exact GitHub release
|
|
@@ -24,6 +26,8 @@ separate 0.3.0 plan remains paused.
|
|
|
24
26
|
The later **0.2.8** selection is independently scoped to MCP diagnosis and
|
|
25
27
|
reliability maintenance, as recorded below; earlier exceptions do not grant
|
|
26
28
|
permission to change unrelated policy under a patch number.
|
|
29
|
+
The **0.2.9** selection has its own bounded decision for the Cleanup
|
|
30
|
+
observation interfaces and accompanying performance/test maintenance below.
|
|
27
31
|
|
|
28
32
|
RC3 publishes defensive research and an example around the existing four
|
|
29
33
|
zero-model controls. Experimental disclosure labels and private delegation
|
|
@@ -31,6 +35,30 @@ methods are not additions to the Decision Protocol or native-hook contract.
|
|
|
31
35
|
No production dependency, policy verdict or storage/configuration migration
|
|
32
36
|
is introduced by the research documentation.
|
|
33
37
|
|
|
38
|
+
<a id="unreleased-cleanup-observation-additions"></a>
|
|
39
|
+
|
|
40
|
+
## Cleanup observation additions (0.2.9)
|
|
41
|
+
|
|
42
|
+
Version 0.2.9 adds independent read-only discovery/measurement schemas,
|
|
43
|
+
CLI modes and MCP tools. They are absent from published 0.2.8 and cannot
|
|
44
|
+
produce an executable plan or approval. Its MCP server advertises seven
|
|
45
|
+
tools; its doctor verifies that set and invokes only the original three
|
|
46
|
+
state queries. Published 0.2.8 retains its five-tool contract. Use doctor and
|
|
47
|
+
server from the same installation; identical version text in a working
|
|
48
|
+
checkout does not establish identical bytes or tools.
|
|
49
|
+
|
|
50
|
+
Existing default Cleanup plans, execution confirmation, original five MCP
|
|
51
|
+
tools, deletion policy and recovery formats retain their interfaces. No
|
|
52
|
+
dependency, configuration or storage migration is introduced.
|
|
53
|
+
See [new observation semantics](../guides/mcp.md#cleanup-observations-029).
|
|
54
|
+
The versioned checkpoints below describe their original release scope.
|
|
55
|
+
|
|
56
|
+
The new CLI modes, independent observation JSON and two MCP tools are
|
|
57
|
+
additive public interfaces, even though they grant no deletion permission.
|
|
58
|
+
The maintainer selected 0.2.9 through the new bounded decision below;
|
|
59
|
+
earlier patch-version exceptions do not authorize it. The paused 0.3.0
|
|
60
|
+
research roadmap is a separate scope decision and is not resumed.
|
|
61
|
+
|
|
34
62
|
## The adapter contract (frozen surface)
|
|
35
63
|
|
|
36
64
|
<a id="mcp-doctor-028-development"></a>
|
|
@@ -70,7 +98,7 @@ replaced. See [options, result scope and recovery after a lost response](../guid
|
|
|
70
98
|
|
|
71
99
|
### Local MCP tools (0.2.7)
|
|
72
100
|
|
|
73
|
-
The
|
|
101
|
+
The 0.2.7 release introduced an optional local stdio MCP server with five explicit tools:
|
|
74
102
|
safe_delete, ordinary restore, transactions, status and GC-plan preview.
|
|
75
103
|
It invokes existing CLI operations without a shell, preserves policy/audit/
|
|
76
104
|
recovery semantics and binds workspace/session identity at trusted startup.
|
|
@@ -273,6 +301,29 @@ While the major version is `0`:
|
|
|
273
301
|
| check.py CLI flags removed or re-semanticized | major + MIGRATION.md |
|
|
274
302
|
| Default policy verdict changes for an existing shape | minor + entry in docs/history/friction.md |
|
|
275
303
|
|
|
304
|
+
<a id="029-cleanup-maintenance-decision"></a>
|
|
305
|
+
|
|
306
|
+
### 0.2.9: bounded Cleanup maintenance decision
|
|
307
|
+
|
|
308
|
+
The maintainer selected **0.2.9** for read-only directory discovery and
|
|
309
|
+
measurement, planning performance and the normal-corpus test correction.
|
|
310
|
+
The new CLI modes, version-1 observation schemas and two MCP tools are
|
|
311
|
+
additive public interfaces carried as this release's explicit maintenance
|
|
312
|
+
exception. The general release-class promises remain in force; this decision
|
|
313
|
+
does not authorize other patch releases or resume the 0.3.0 research plan.
|
|
314
|
+
|
|
315
|
+
Upgrade both doctor and server from the same package: 0.2.9 expects seven
|
|
316
|
+
tools, while 0.2.8 expects five. Existing installations need an explicit
|
|
317
|
+
upgrade. Changed package/helper bytes may make an older doctor fingerprint
|
|
318
|
+
baseline `DRIFTED`; review it rather than silently replacing it.
|
|
319
|
+
|
|
320
|
+
The original five MCP operations, default executable plans and confirmation,
|
|
321
|
+
Decision classes/reasons, default deletion rules, budgets, recovery manifests,
|
|
322
|
+
ordinary restore and preview-only MCP GC retain their contracts. Observation
|
|
323
|
+
IDs and policy projections cannot authorize deletion. No dependency or
|
|
324
|
+
configuration/storage migration is introduced. See the
|
|
325
|
+
[release notes](../releases/release-notes-0.2.9.md).
|
|
326
|
+
|
|
276
327
|
<a id="028-diagnosis-maintenance-decision"></a>
|
|
277
328
|
|
|
278
329
|
### 0.2.8: bounded diagnosis maintenance decision
|