@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.
@@ -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"])
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.8](releases/release-notes-0.2.8.md) adds MCP diagnosis and
20
- recovery validation to the [0.2.7](releases/release-notes-0.2.7.md) baseline
21
- of Cleanup plans, deletion admission and optional local MCP tools.
22
- Before installing 0.2.8,
23
- check the exact [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.8)
24
- and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.8)
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.8 维护、0.2.7 范围及 0.2.6 历史,保留原验收边界 |
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`; deletion admission applies shared limits; the current MCP adapter exposes deletion/recovery tools and its doctor checks them through read-only queries | [Delete-guard Skill](../../skills/delete-guard/SKILL.md) · [Cleanup](../guides/cleanup-plan.md) · [Limits](../guides/deletion-limits.md) · [MCP](../guides/mcp.md) |
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 checkout adds an optional local stdio MCP server with five explicit tools:
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