@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
|
@@ -14,6 +14,82 @@ layout or Git exclude rules. It also suppresses project bytecode creation.
|
|
|
14
14
|
Planning does not call `safe_delete --dry-run`, whose metadata side effects
|
|
15
15
|
remain documented in the [policy reference](../../skills/delete-guard/references/policy.md#assessment-and-dry-run-side-effects).
|
|
16
16
|
|
|
17
|
+
<a id="directory-overview-and-measurement-unreleased"></a>
|
|
18
|
+
|
|
19
|
+
## Directory overview and measurement (0.2.9)
|
|
20
|
+
|
|
21
|
+
These modes are introduced in **0.2.9**, not included in the published 0.2.8
|
|
22
|
+
package. They share the stdlib-only Core with two new
|
|
23
|
+
[read-only MCP tools](mcp.md#cleanup-observations-029). The existing
|
|
24
|
+
default plan and explicit execution workflow below keep their interfaces.
|
|
25
|
+
This addition remains part of Delete-guard's Cleanup Copilot.
|
|
26
|
+
|
|
27
|
+
Start with a bounded overview, then inspect a specific unexpanded directory
|
|
28
|
+
or measure explicit scopes, always keeping the original workspace root:
|
|
29
|
+
|
|
30
|
+
```sh
|
|
31
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/cleanup.py \
|
|
32
|
+
--root /absolute/path/to/project --discover --json
|
|
33
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/cleanup.py \
|
|
34
|
+
--root /absolute/path/to/project --discover --scope .work --json
|
|
35
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/cleanup.py \
|
|
36
|
+
--root /absolute/path/to/project --measure --scope build --scope .pytest_cache --json
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Scopes are literal, non-overlapping directories below that fixed root;
|
|
40
|
+
directory-link components, protected scopes, outside paths and the workspace
|
|
41
|
+
root itself are refused. Without scopes, discovery starts at the root.
|
|
42
|
+
Measurement requires scopes. Quote spaces; use `--scope=-name` for a leading
|
|
43
|
+
dash. A scoped discovery starts a new bounded observation rather than a
|
|
44
|
+
cursor or a claim that previous results now cover the entire workspace.
|
|
45
|
+
|
|
46
|
+
| Mode | Default limits | Output |
|
|
47
|
+
|---|---|---|
|
|
48
|
+
| `--discover` | Depth 4 per selected root, 10000 entries total, 256 expanded directories, 512 entries per directory | Compact overview; JSON includes all observed groups, review branches and unexpanded paths; all sizes unknown |
|
|
49
|
+
| `--measure` | Depth 32 per scope, 20000 entries shared across scopes | Logical file/link sizes with inode deduplication, protected roots, issues and completeness per scope |
|
|
50
|
+
|
|
51
|
+
`--max-entries` and `--max-depth` override their mode's positive limits in the
|
|
52
|
+
CLI. The MCP tools only allow lowering the stated defaults. These new modes
|
|
53
|
+
have been exercised on Linux ARM64/PRoot; their no-follow cache-marker opening
|
|
54
|
+
uses POSIX facilities and has no Windows acceptance evidence.
|
|
55
|
+
|
|
56
|
+
Discovery recognizes protected boundaries before runtime markers, cache
|
|
57
|
+
markers and known artifact patterns. A regular `pyvenv.cfg` takes precedence
|
|
58
|
+
over `CACHEDIR.TAG`; it identifies an environment hint, not an unused runtime.
|
|
59
|
+
A valid cache signature and the name `uv` provide an ownership hint only.
|
|
60
|
+
Managed caches stay grouped without suggesting their internal build fragments.
|
|
61
|
+
Cache/artifact path hints affect queue order, not permission or proof of
|
|
62
|
+
obsolescence. No age or filename heuristic declares content discarded.
|
|
63
|
+
|
|
64
|
+
JSON uses independent `cleanup_group_discovery/v1` and
|
|
65
|
+
`cleanup_group_measurement/v1` schemas with an `observation_id`, **no
|
|
66
|
+
executable `plan_id`**. Every observation has `execution_supported: false`
|
|
67
|
+
and every group has `selectable: false`. Discovery's `frontier_complete`
|
|
68
|
+
only describes its bounded frontier; `workspace_scan_complete` stays false.
|
|
69
|
+
Inspect `coverage.unexpanded`, limits and issues before choosing a scope.
|
|
70
|
+
|
|
71
|
+
Measurement never follows links. Protected subtrees and external/protected
|
|
72
|
+
link boundaries are omitted; `size_bytes: null` means unknown, not zero.
|
|
73
|
+
`observed_bytes` counts the observed subset and does not predict freed disk
|
|
74
|
+
space. `observed_subset_complete` may be true while `size_complete` and
|
|
75
|
+
`interior_checked` are false because protection prevents a whole-size claim.
|
|
76
|
+
The metadata digest is not a content hash or atomic snapshot. Scans read
|
|
77
|
+
metadata and at most 43 bytes per examined cache tag, plus existing Guard
|
|
78
|
+
configuration and Git facts; they do not parse database or cache payloads.
|
|
79
|
+
|
|
80
|
+
For complete ordinary artifact scopes, `core_policy` may show a shared Core
|
|
81
|
+
projection. Approval remains `NOT_GRANTED`, budget `NOT_CHECKED`, and the
|
|
82
|
+
projection does not grant execution. Application-managed caches remain
|
|
83
|
+
subject to their own consistency and locking protocol.
|
|
84
|
+
|
|
85
|
+
Exit 0 means the requested frontier or observed measurement subset completed;
|
|
86
|
+
1 retains partial observations after limits, I/O errors or observed source
|
|
87
|
+
changes; 2 means invalid options or refusal. A protected unknown whole size
|
|
88
|
+
can therefore coexist with measurement exit 0. None authorizes deletion.
|
|
89
|
+
`--scope` requires these new modes; they reject `--discard`, `--protect`,
|
|
90
|
+
`--execute`, `--plan-id` and `--select`. To delete, produce a separate reviewed
|
|
91
|
+
plan using the existing workflow; an observation cannot be promoted into one.
|
|
92
|
+
|
|
17
93
|
## Review a plan
|
|
18
94
|
|
|
19
95
|
From the intended workspace, run:
|
|
@@ -63,6 +139,17 @@ Unknown subtrees collapse into review rows unless generated, discarded or
|
|
|
63
139
|
protected descendants need to be shown. Candidate directories and their
|
|
64
140
|
children are not offered as overlapping selections.
|
|
65
141
|
|
|
142
|
+
The planner reuses ordinary-file metadata and its batched Git facts within
|
|
143
|
+
one scan. Directory and link boundaries still receive full checks. This does
|
|
144
|
+
not make a partial scan complete or change the scan limits. Execution still
|
|
145
|
+
rescans the plan and reads current policy and Git facts.
|
|
146
|
+
|
|
147
|
+
A regenerable classification does not verify an application's cache protocol.
|
|
148
|
+
For example, [uv documents its cache consistency and locking requirements](https://docs.astral.sh/uv/concepts/cache/#cache-safety)
|
|
149
|
+
and warns against directly changing cache contents. Review such managed
|
|
150
|
+
caches separately; the planner does not coordinate their application locks
|
|
151
|
+
or automatically invoke native cache-cleaning commands.
|
|
152
|
+
|
|
66
153
|
## Confirm and execute
|
|
67
154
|
|
|
68
155
|
Copy the plan's full `plan_id`, select exact rows marked `selectable`, and
|
|
@@ -125,6 +212,10 @@ retrying. No automatic purge or rollback runs.
|
|
|
125
212
|
|
|
126
213
|
## Sizes, limits and output
|
|
127
214
|
|
|
215
|
+
This section describes plan JSON and the confirmation workflow. The
|
|
216
|
+
[read-only observation modes](#directory-overview-and-measurement-unreleased)
|
|
217
|
+
have their own schemas and limits.
|
|
218
|
+
|
|
128
219
|
Sizes are logical file bytes, with hardlinks counted once per entry and per
|
|
129
220
|
category summary. Directory metadata is omitted; links use their own size
|
|
130
221
|
and directory links are not traversed. Protected subtree sizes are unknown.
|
|
@@ -170,6 +261,12 @@ before writing a new baseline at a new path.
|
|
|
170
261
|
|
|
171
262
|
## 中文摘要
|
|
172
263
|
|
|
264
|
+
0.2.9 新增 `--discover` 目录概况、`--measure --scope PATH` 指定范围计量,
|
|
265
|
+
并提供对应的 `cleanup_discover`/`cleanup_measure` MCP 工具;已发布 0.2.8
|
|
266
|
+
不含这些能力。按范围继续发现仍保持原工作区,未展开部分和大小未知必须保留。
|
|
267
|
+
这些观察不生成可执行计划或删除许可,MCP 的 `ok: true, partial: true` 也不代表
|
|
268
|
+
完整扫描。执行仍需另外生成并审阅下面的既有计划。
|
|
269
|
+
|
|
173
270
|
本功能自 0.2.7 加入。默认扫描只输出计划,不修改工作区;“明确废弃”仅来自
|
|
174
271
|
调用者显式声明,旧文件/未跟踪文件不会自动变为垃圾。执行必须提供计划 ID、选定
|
|
175
272
|
具体条目并由操作者在终端确认,确认后复查,再逐项走现有 safe_delete。普通文件
|
|
@@ -10,11 +10,11 @@ Agent Guard 提供恢复保护、外发检测和用户控制的行为验测。
|
|
|
10
10
|
|
|
11
11
|
## Select the package root
|
|
12
12
|
|
|
13
|
-
This guide covers [0.2.
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
exact [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.
|
|
17
|
-
and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.
|
|
13
|
+
This guide covers [0.2.9](../releases/release-notes-0.2.9.md), with read-only
|
|
14
|
+
Cleanup inventory and measurement, faster plan scans, MCP connection
|
|
15
|
+
diagnosis and the existing deletion/recovery tools. Confirm the
|
|
16
|
+
exact [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.9)
|
|
17
|
+
and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.9)
|
|
18
18
|
are available before installing from the registry. A checkout or manifest
|
|
19
19
|
does not establish publication or the current npm `latest` channel.
|
|
20
20
|
|
|
@@ -27,7 +27,7 @@ backports quarantine protection onto the stable line.
|
|
|
27
27
|
Once the exact version is available, use a user-selected stable prefix:
|
|
28
28
|
|
|
29
29
|
```sh
|
|
30
|
-
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.
|
|
30
|
+
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.9
|
|
31
31
|
```
|
|
32
32
|
|
|
33
33
|
The package root is
|
|
@@ -43,7 +43,7 @@ If that version is unavailable, use a reviewed source checkout or a checked
|
|
|
43
43
|
local tarball. Install the tarball into a separate prefix:
|
|
44
44
|
|
|
45
45
|
```sh
|
|
46
|
-
npm install --offline --ignore-scripts --legacy-peer-deps --no-audit --no-fund --prefix /absolute/path/to/agent-guard-review /absolute/path/to/mokuyoaxis-agent-guard-0.2.
|
|
46
|
+
npm install --offline --ignore-scripts --legacy-peer-deps --no-audit --no-fund --prefix /absolute/path/to/agent-guard-review /absolute/path/to/mokuyoaxis-agent-guard-0.2.9.tgz
|
|
47
47
|
```
|
|
48
48
|
|
|
49
49
|
The review package root is
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Harness capability and evidence matrix
|
|
2
2
|
|
|
3
|
-
This matrix accompanies [0.2.
|
|
3
|
+
This matrix accompanies [0.2.9](../releases/release-notes-0.2.9.md).
|
|
4
4
|
Confirm availability through the exact GitHub release and npm version links
|
|
5
5
|
in those notes; a source version does not establish publication.
|
|
6
6
|
Published prerelease, checked on 2026-10-19:
|
|
@@ -111,6 +111,13 @@ checks a selected service through handshake and read-only calls. Its PASS
|
|
|
111
111
|
does not establish host connection, model use or native interception; those
|
|
112
112
|
remain separate evidence levels.
|
|
113
113
|
|
|
114
|
+
Version 0.2.9 adds the read-only `cleanup_discover` and `cleanup_measure`
|
|
115
|
+
tools. Local source checks include real-project stdio observations and one
|
|
116
|
+
bounded Kimi Code inventory task in a synthetic workspace (three MCP calls).
|
|
117
|
+
That task covers the new observation path, not a fresh cross-host acceptance
|
|
118
|
+
of the published package or native interception. See the
|
|
119
|
+
[0.2.9 validation](../releases/release-notes-0.2.9.md#validation).
|
|
120
|
+
|
|
114
121
|
## Acceptance for each native adapter
|
|
115
122
|
|
|
116
123
|
1. Pin host version, profile/configuration, tool name, shell dialect, and
|
package/docs/guides/mcp.md
CHANGED
|
@@ -15,6 +15,11 @@ and protocol-interruption validation; see the
|
|
|
15
15
|
The later [Codex 0.165.0 acceptance](#codex-01650-with-published-027) below used
|
|
16
16
|
the published 0.2.7 package and is separate from both development checkpoints.
|
|
17
17
|
|
|
18
|
+
Version **0.2.9** adds `cleanup_discover` and `cleanup_measure`.
|
|
19
|
+
Version 0.2.8 retains the original five tools. The new read-only workflow
|
|
20
|
+
and its separate partial-result contract are described
|
|
21
|
+
[below](#cleanup-observations-029).
|
|
22
|
+
|
|
18
23
|
MCP gives a supporting coding-agent client an explicit way to use the existing
|
|
19
24
|
safe deletion and recovery operations. It does **not** intercept shell `rm`,
|
|
20
25
|
scripts, editor deletion or tools that bypass this server. Keep a compatible
|
|
@@ -85,7 +90,7 @@ this server alone does not provide that bridge. Existing
|
|
|
85
90
|
|
|
86
91
|
## Diagnose a local service (0.2.8)
|
|
87
92
|
|
|
88
|
-
From a 0.2.8 installation or checkout, run:
|
|
93
|
+
From a 0.2.8 or later installation or checkout, run:
|
|
89
94
|
|
|
90
95
|
```sh
|
|
91
96
|
python3 -B /absolute/path/to/agent-guard/doctor.py mcp \
|
|
@@ -109,7 +114,10 @@ The checks cover:
|
|
|
109
114
|
1. The selected interpreter, pinned SDK metadata and actual SDK imports.
|
|
110
115
|
2. A classic `2025-06-18` stdio handshake, the `agent-guard` service identity
|
|
111
116
|
and a service version matching the doctor's package version.
|
|
112
|
-
3. The
|
|
117
|
+
3. The expected tools and query annotations for this installation: five in
|
|
118
|
+
0.2.8, seven in 0.2.9. Use doctor and server
|
|
119
|
+
from the same installation; matching package version text alone does not
|
|
120
|
+
establish an identical tool set.
|
|
113
121
|
4. Successful `status`, `transactions` and `gc_plan` calls, including the
|
|
114
122
|
requested workspace and its local quarantine binding reported by `status`.
|
|
115
123
|
|
|
@@ -175,6 +183,8 @@ or atomic rollback. Final candidate results are recorded in the
|
|
|
175
183
|
| `transactions` | none | List the selected workspace's recovery transactions |
|
|
176
184
|
| `status` | optional integer `tail` (0–100, default 10) | Inspect recovery state, limits and recent audit information |
|
|
177
185
|
| `gc_plan` | none | Preview the existing transaction GC plan; never execute it |
|
|
186
|
+
| `cleanup_discover` (0.2.9) | optional literal directory `scopes`, `max_entries` (1–10000), `max_depth` (1–4) | Bounded read-only overview; no executable plan |
|
|
187
|
+
| `cleanup_measure` (0.2.9) | required directory `scopes`, optional `max_entries` (1–20000), `max_depth` (1–32) | Read-only metadata measurement; protected whole sizes stay unknown |
|
|
178
188
|
|
|
179
189
|
Paths are literal names, relative to the fixed workspace or absolute; the
|
|
180
190
|
Core still refuses outside targets. Glob characters name actual files rather
|
|
@@ -221,6 +231,50 @@ cancellation means nothing moved. Do not automatically retry a mutating call
|
|
|
221
231
|
after a client timeout or disconnection. The existing recovery, concurrency
|
|
222
232
|
and same-UID boundaries remain; this server is not an OS sandbox.
|
|
223
233
|
|
|
234
|
+
<a id="cleanup-observations-unreleased"></a>
|
|
235
|
+
|
|
236
|
+
## Cleanup observations (0.2.9)
|
|
237
|
+
|
|
238
|
+
First call `cleanup_discover` with `{}`. Its compact `overview` accompanies
|
|
239
|
+
the complete observed `groups`, `review_branches` and `coverage.unexpanded`
|
|
240
|
+
lists. Choose exact directory scopes for a follow-up discovery or measurement:
|
|
241
|
+
|
|
242
|
+
```json
|
|
243
|
+
{"name":"cleanup_discover","arguments":{"scopes":[".work"]}}
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
```json
|
|
247
|
+
{"name":"cleanup_measure","arguments":{"scopes":["build",".pytest_cache"]}}
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
Scopes accept at most 64 strings, stay below the same workspace, and cannot
|
|
251
|
+
overlap, cross protection or contain directory links. Omitting discovery
|
|
252
|
+
scopes starts at the root; measurement requires a nonempty selection. No
|
|
253
|
+
workspace, environment, approval, plan ID or execution override is accepted.
|
|
254
|
+
The limits are shared across all scopes in one call. A follow-up scope starts
|
|
255
|
+
a fresh observation rather than completing or authorizing an old one.
|
|
256
|
+
|
|
257
|
+
Both tools are read-only and preserve source files, audit and recovery state.
|
|
258
|
+
They do not call advisory safe_delete, which can write normal guard metadata.
|
|
259
|
+
Their results use the independent observation schemas described in the
|
|
260
|
+
[Cleanup guide](cleanup-plan.md#directory-overview-and-measurement-unreleased).
|
|
261
|
+
Runtime and managed-cache labels are hints; all groups remain nonselectable.
|
|
262
|
+
Do not treat a Core policy projection or successful inspection as approval.
|
|
263
|
+
|
|
264
|
+
A valid partial observation returns `ok: true`, `partial: true` and is not an
|
|
265
|
+
MCP `isError`. The original CLI exit code remains present, including exit 1
|
|
266
|
+
for a limited frontier or incomplete observed subset. `partial` also remains
|
|
267
|
+
true when measurement exit 0 has a protected unknown whole size. Inspect the
|
|
268
|
+
underlying coverage, issues, protected roots and completeness fields; `ok`
|
|
269
|
+
means the tool returned usable observations, not that the workspace is fully
|
|
270
|
+
scanned or a target may be deleted. Invalid options, unavailable subprocesses
|
|
271
|
+
and protocol failures remain errors. These semantics do not change the
|
|
272
|
+
original five tools' error or mutation contracts.
|
|
273
|
+
|
|
274
|
+
The doctor verifies the two new tool annotations but continues to invoke
|
|
275
|
+
only `status`, `transactions` and `gc_plan`; diagnosis does not silently start
|
|
276
|
+
directory discovery or measurement.
|
|
277
|
+
|
|
224
278
|
## Configure a client
|
|
225
279
|
|
|
226
280
|
The following examples register a local server; they do not run deletion or
|
|
@@ -296,8 +350,10 @@ installed version rather than copying another client's configuration shape.
|
|
|
296
350
|
|
|
297
351
|
## Verify and report
|
|
298
352
|
|
|
299
|
-
1. Confirm the interpreter starts the server and the client discovers the
|
|
300
|
-
tools
|
|
353
|
+
1. Confirm the interpreter starts the server and the client discovers the
|
|
354
|
+
tools for that installation: five in 0.2.8, seven in 0.2.9.
|
|
355
|
+
Check stderr when a dependency or executable cannot
|
|
356
|
+
be found, and reconnect after changing the selected installation.
|
|
301
357
|
2. Call `status`, `transactions` and `gc_plan` in a disposable project; confirm
|
|
302
358
|
preview leaves recovery payloads intact.
|
|
303
359
|
3. Create a small synthetic valuable file, call `safe_delete`, verify a real
|
|
@@ -308,6 +364,14 @@ installed version rather than copying another client's configuration shape.
|
|
|
308
364
|
results and unverified paths. A raw protocol test, a real client call and a
|
|
309
365
|
real-model trial are different evidence levels.
|
|
310
366
|
|
|
367
|
+
For the 0.2.9 observation tools, separately call `cleanup_discover`
|
|
368
|
+
and `cleanup_measure` on explicit synthetic directory scopes. Check that
|
|
369
|
+
source files and recovery state stay unchanged, unknown sizes remain null,
|
|
370
|
+
and a limited result can have `ok: true, partial: true` without execution
|
|
371
|
+
permission. A successful query or the old five-tool acceptance records do
|
|
372
|
+
not establish that the new tools reached a model; see the
|
|
373
|
+
[current source validation](../releases/unreleased.md#current-validation-checkpoint).
|
|
374
|
+
|
|
311
375
|
## Recorded validation and remaining limits
|
|
312
376
|
|
|
313
377
|
### Codex 0.165.0 with published 0.2.7
|
|
@@ -335,7 +399,7 @@ tool exchanges supported the reported behavior, and the recorded process IDs
|
|
|
335
399
|
were absent at the final check; the missing lifecycle metadata was not
|
|
336
400
|
reconstructed. This limitation is separate from the three completed model
|
|
337
401
|
tasks. These results apply to that published 0.2.7 artifact, exact Codex
|
|
338
|
-
version and cooperative MCP path, not
|
|
402
|
+
version and cooperative MCP path, not later artifacts, native
|
|
339
403
|
shell/editor interception, arbitrary subagents or all Codex releases.
|
|
340
404
|
|
|
341
405
|
### Earlier preparation and Kimi checkpoints
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
# 0.2.9 — Cleanup inventory and faster scans
|
|
2
|
+
|
|
3
|
+
Cleanup Copilot can now show a bounded directory overview before a detailed
|
|
4
|
+
scan. Pick the directories that matter, measure those scopes, then decide
|
|
5
|
+
whether to prepare a cleanup plan. Both steps are available through CLI and MCP.
|
|
6
|
+
|
|
7
|
+
本版主要改善清理前的盘点:先看目录概况,再计量选定范围。既有计划扫描也做了提速,
|
|
8
|
+
删除仍按原来的计划、确认和 safe_delete 流程执行。
|
|
9
|
+
|
|
10
|
+
## Changes
|
|
11
|
+
|
|
12
|
+
- `agent-guard-cleanup --discover` groups directory hints and reports areas
|
|
13
|
+
left unexpanded. `--measure --scope PATH` measures selected directories.
|
|
14
|
+
- MCP adds the read-only `cleanup_discover` and `cleanup_measure` tools.
|
|
15
|
+
Partial observations remain usable; incomplete coverage and unknown whole
|
|
16
|
+
sizes are explicit in the result.
|
|
17
|
+
- Plan scans reuse ordinary-file metadata and batch Git queries instead of
|
|
18
|
+
repeating them for every candidate.
|
|
19
|
+
- Cleanup previews keep recovery parents protected when reached through
|
|
20
|
+
directory aliases.
|
|
21
|
+
- The normal-corpus regression test uses Git-index paths and current file
|
|
22
|
+
contents. Private untracked experiments no longer enter that metric;
|
|
23
|
+
tracked and newly staged unsafe content still fails it.
|
|
24
|
+
|
|
25
|
+
```sh
|
|
26
|
+
agent-guard-cleanup --discover --json
|
|
27
|
+
agent-guard-cleanup --measure --scope build --json
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Inventory results cannot authorize deletion. Cache labels are hints, and
|
|
31
|
+
protected or unmeasured whole sizes stay unknown. Scanning does not coordinate
|
|
32
|
+
application cache locks. See the
|
|
33
|
+
[Cleanup guide](https://github.com/mokuyoaxis/agent-guard/blob/0.2.9/docs/guides/cleanup-plan.md#directory-overview-and-measurement-029)
|
|
34
|
+
and [MCP guide](https://github.com/mokuyoaxis/agent-guard/blob/0.2.9/docs/guides/mcp.md#cleanup-observations-029).
|
|
35
|
+
|
|
36
|
+
## Upgrade
|
|
37
|
+
|
|
38
|
+
Install the exact version after checking its
|
|
39
|
+
[GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.9)
|
|
40
|
+
and [npm page](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.9):
|
|
41
|
+
|
|
42
|
+
```sh
|
|
43
|
+
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.9
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Upgrade doctor and server together: 0.2.9 expects seven MCP tools; 0.2.8
|
|
47
|
+
expects five. Older doctor fingerprint baselines may report `DRIFTED` after
|
|
48
|
+
the upgrade and need review. The optional `mcp==2.3.0` SDK remains a separate
|
|
49
|
+
installation; Core/CLI still needs Python 3.9+ and Git.
|
|
50
|
+
|
|
51
|
+
The maintainer selected 0.2.9 as a
|
|
52
|
+
[bounded maintenance exception](https://github.com/mokuyoaxis/agent-guard/blob/0.2.9/docs/design/compatibility.md#029-cleanup-maintenance-decision)
|
|
53
|
+
for these additions. The original five MCP operations, deletion rules,
|
|
54
|
+
budgets and recovery formats retain their contracts. There is no data or
|
|
55
|
+
configuration migration. The separate 0.3.0 research plan stays paused.
|
|
56
|
+
|
|
57
|
+
## Validation
|
|
58
|
+
|
|
59
|
+
Before CI corrections, a local 0.2.9 candidate passed `npm test`: 1197 Python cases and both Node
|
|
60
|
+
groups, with the optional MCP SDK enabled and no failures, errors or skips.
|
|
61
|
+
All 16 real MCP protocol, doctor and interruption cases executed. Follow-up
|
|
62
|
+
alias and test-fixture regressions are checked separately; CI and Release
|
|
63
|
+
enforce the updated 1198-case suite before publication.
|
|
64
|
+
|
|
65
|
+
Earlier local checks also covered real-project stdio inventory and one Kimi
|
|
66
|
+
Code task in a synthetic workspace. That single task used three MCP calls;
|
|
67
|
+
it does not establish general host reliability, native shell interception or
|
|
68
|
+
application-cache deletion safety.
|
|
@@ -1,4 +1,158 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Unreleased changes and maintenance history
|
|
2
|
+
|
|
3
|
+
<a id="current-unreleased-scope"></a>
|
|
4
|
+
|
|
5
|
+
## Current scope: 0.2.9
|
|
6
|
+
|
|
7
|
+
The maintainer selected **0.2.9** for the changes below. Confirm exact-version
|
|
8
|
+
availability through the [release notes](release-notes-0.2.9.md) before installation.
|
|
9
|
+
Cleanup Copilot and its observation tools remain part of **Delete-guard**.
|
|
10
|
+
The separate disclosure-authorization roadmap and commercial work stay paused.
|
|
11
|
+
|
|
12
|
+
| Area | Change | Entry |
|
|
13
|
+
|---|---|---|
|
|
14
|
+
| Directory inventory | Bounded overview, explicit-scope discovery and metadata measurement | [CLI workflow](../guides/cleanup-plan.md#directory-overview-and-measurement-unreleased) |
|
|
15
|
+
| MCP observations | `cleanup_discover` and `cleanup_measure`; partial data is distinct from a failed call | [Tool contract](../guides/mcp.md#cleanup-observations-unreleased) |
|
|
16
|
+
| Planning performance | Reuse ordinary-file metadata and batch Git facts within one plan | [Planner boundaries](../guides/cleanup-plan.md#review-a-plan) |
|
|
17
|
+
| Corpus regression | Define the normal text corpus by Git-index paths and current working-tree contents | [Contributor workflow](../../CONTRIBUTING.md) |
|
|
18
|
+
|
|
19
|
+
The default executable-plan workflow, original five MCP operations, deletion
|
|
20
|
+
policy, budgets and recovery formats retain their contracts. Overview and
|
|
21
|
+
measurement never grant execution permission. Use doctor and server from the
|
|
22
|
+
same installation; published 0.2.8 has five tools, this checkout has seven.
|
|
23
|
+
See the [latest local validation](#current-validation-checkpoint) before
|
|
24
|
+
interpreting historical counts or host evidence.
|
|
25
|
+
|
|
26
|
+
<a id="cleanup-directory-observations-and-mcp-unreleased"></a>
|
|
27
|
+
|
|
28
|
+
## Cleanup directory observations and MCP (0.2.9)
|
|
29
|
+
|
|
30
|
+
Version 0.2.9 adds shared-Core directory discovery and selected-scope
|
|
31
|
+
measurement, exposed by `agent-guard-cleanup --discover|--measure` and the
|
|
32
|
+
MCP tools `cleanup_discover` / `cleanup_measure`. These additions are absent
|
|
33
|
+
from published 0.2.8. They remain under
|
|
34
|
+
Delete-guard's Cleanup Copilot, with no new production dependency or storage
|
|
35
|
+
migration.
|
|
36
|
+
|
|
37
|
+
Discovery groups runtime/cache hints, prioritizes cache/artifact path hints
|
|
38
|
+
within fixed limits, and records unexpanded areas. Explicit scopes continue
|
|
39
|
+
discovery under the same workspace. Measurement omits protected subtrees and
|
|
40
|
+
keeps unknown whole sizes distinct from observed bytes. All observations
|
|
41
|
+
remain nonselectable and produce no executable plan ID or approval; the
|
|
42
|
+
existing default plan and confirmed safe_delete workflow remain separate.
|
|
43
|
+
|
|
44
|
+
The MCP adapter returns valid partial observations with `ok: true` and
|
|
45
|
+
`partial: true`, preserving the CLI exit code and completeness details. The
|
|
46
|
+
original five tools retain their contracts. The source doctor expects seven
|
|
47
|
+
tools but still invokes only the original three read-only state queries.
|
|
48
|
+
Use doctor and server from the same installation.
|
|
49
|
+
|
|
50
|
+
See [CLI workflow and result fields](../guides/cleanup-plan.md#directory-overview-and-measurement-unreleased)
|
|
51
|
+
and [MCP partial-result semantics](../guides/mcp.md#cleanup-observations-unreleased).
|
|
52
|
+
|
|
53
|
+
<a id="cleanup-planning-performance-unreleased"></a>
|
|
54
|
+
|
|
55
|
+
## Cleanup planning performance (0.2.9)
|
|
56
|
+
|
|
57
|
+
Version 0.2.9 reduces repeated ordinary-file path and metadata checks
|
|
58
|
+
and reuses batched Git facts when projecting candidate verdicts. Shared
|
|
59
|
+
decision rules retain their live execution entrypoint; deleting files still
|
|
60
|
+
checks current Git and protection settings. Scan limits, categories, plan
|
|
61
|
+
fingerprints, confirmation and deletion budgets keep their contracts.
|
|
62
|
+
|
|
63
|
+
This performance change is not part of the published 0.2.8 package. On its
|
|
64
|
+
own it changes no recognition rules or MCP tools; the separate observation
|
|
65
|
+
addition above supplies directory groups and read-only MCP entrypoints.
|
|
66
|
+
Neither coordinates application locks. See the [cleanup guide](../guides/cleanup-plan.md)
|
|
67
|
+
for planning and managed-cache boundaries. The earlier validation records
|
|
68
|
+
below retain their original versions and results.
|
|
69
|
+
|
|
70
|
+
<a id="repository-corpus-noise-regression-unreleased"></a>
|
|
71
|
+
|
|
72
|
+
## Repository corpus noise regression (0.2.9)
|
|
73
|
+
|
|
74
|
+
The repository's normal-corpus test now reads current regular UTF-8 files
|
|
75
|
+
named by its own Git index. Tracked modifications and newly staged files are
|
|
76
|
+
included; untracked private adversarial experiments are outside this metric.
|
|
77
|
+
Git failures, a borrowed parent index and unreadable tracked files are not
|
|
78
|
+
silently accepted. Binary files and link targets are outside the text corpus.
|
|
79
|
+
|
|
80
|
+
This corrects the test's collection boundary without changing Exfil rules,
|
|
81
|
+
exemptions or private examples. Regressions check that unsafe tracked and new
|
|
82
|
+
staged content still fails, untracked examples still BLOCK when scanned
|
|
83
|
+
directly, and staging an example brings it into the corpus gate. New files
|
|
84
|
+
must be staged intentionally before this versioned-corpus pre-commit check;
|
|
85
|
+
it is not a whole-workspace safety scan. See the
|
|
86
|
+
[current validation](#current-validation-checkpoint); earlier failed
|
|
87
|
+
checkpoints remain recorded below.
|
|
88
|
+
|
|
89
|
+
## Current validation checkpoint
|
|
90
|
+
|
|
91
|
+
Before the CI corrections below, the versioned 0.2.9 public candidate passed the literal `npm test`: 1197
|
|
92
|
+
Python cases and both Node groups, with no failures, errors or skips.
|
|
93
|
+
All 16 real MCP protocol/doctor/interruption cases executed with the existing
|
|
94
|
+
pinned SDK. The candidate's 227 public source files stayed unchanged during
|
|
95
|
+
the run. This is local candidate validation; remote CI and publication are
|
|
96
|
+
separate checks, available through the [0.2.9 notes](release-notes-0.2.9.md).
|
|
97
|
+
|
|
98
|
+
The first cross-version CI then exposed a test-fixture issue on Python 3.9
|
|
99
|
+
and 3.10: mocking `os.stat` did not inject the intended metadata error through
|
|
100
|
+
those versions' `Path.lstat` implementation. The fixture now injects at
|
|
101
|
+
`Path.lstat` and verifies that the fault was reached, retaining the original
|
|
102
|
+
error/incompleteness assertions. Further macOS logs exposed a preview fast
|
|
103
|
+
path that missed a configured recovery parent through a directory alias.
|
|
104
|
+
It now checks both recovery-path spellings before skipping classification;
|
|
105
|
+
a new alias regression reproduces the pre-fix failure. The HOME fixture uses
|
|
106
|
+
the scanner's physical path, and the read-only fixture disables detached Git
|
|
107
|
+
maintenance before its baseline commit. These corrections retain deletion
|
|
108
|
+
policy and live execution checks. The full run above keeps its original
|
|
109
|
+
checkpoint; subsequent validation uses 1198 public cases and is recorded
|
|
110
|
+
separately.
|
|
111
|
+
|
|
112
|
+
Before the version alignment, local `npm test` passed all 1504 Python cases (1197 in public
|
|
113
|
+
test modules and 307 existing private development cases) and both Node
|
|
114
|
+
groups, with the existing optional MCP SDK enabled. There were no failures,
|
|
115
|
+
errors, skips or automatic retries; the 214 frozen code/configuration inputs
|
|
116
|
+
remained unchanged. Eight new collection-boundary controls and direct scans
|
|
117
|
+
of the original eleven private samples confirm that the detector still BLOCKs
|
|
118
|
+
those samples. Exfil rules and the allowfile were not changed.
|
|
119
|
+
|
|
120
|
+
These are local working-tree results, not acceptance of the versioned
|
|
121
|
+
release or fresh remote CI. The source suite includes private development
|
|
122
|
+
cases absent from a public checkout; public-module and private counts are
|
|
123
|
+
listed separately. The subsequent Markdown consolidation changed no
|
|
124
|
+
production code or tests and did not repeat model trials. Versioned release
|
|
125
|
+
checks are recorded separately in the [0.2.9 notes](release-notes-0.2.9.md#validation).
|
|
126
|
+
|
|
127
|
+
Local checks include actual stdio discovery/measurement against a real
|
|
128
|
+
project and one bounded real Kimi Code inventory task in a synthetic
|
|
129
|
+
workspace (four model requests, three native MCP calls). The latter completed
|
|
130
|
+
scoped discovery and measurement, preserved unknown UV whole size and mixed
|
|
131
|
+
data uncertainty, and left fixture files unchanged. This is one host/task
|
|
132
|
+
sample, not general reliability, application-cache deletion safety or shell
|
|
133
|
+
interception evidence.
|
|
134
|
+
|
|
135
|
+
The overview remains bounded and may leave an incomplete frontier. Finding
|
|
136
|
+
registered roots does not establish a complete workspace scan. The model
|
|
137
|
+
trial's source/task boundaries remain separate from native shell interception
|
|
138
|
+
and application-cache deletion safety.
|
|
139
|
+
|
|
140
|
+
### Earlier source checkpoints
|
|
141
|
+
|
|
142
|
+
At the earlier pre-corpus-fix checkpoint, the full local `npm test` run
|
|
143
|
+
completed 1496 Python cases (1189 in public test modules and 307 existing
|
|
144
|
+
private development cases), with one corpus
|
|
145
|
+
gate failure caused by existing private experiment files. The saved
|
|
146
|
+
pre-change view reproduced the same eleven hits; the then-current public-only
|
|
147
|
+
view passed that single gate. The two Node commands were then run separately
|
|
148
|
+
and passed. That original npm run remains recorded as failed; the public-only
|
|
149
|
+
gate check is not a second full-suite PASS. No Exfil exemption, production rule or
|
|
150
|
+
private fixture was changed to suppress it. The final 25 directory-group
|
|
151
|
+
controls and actual MCP/host checks passed; the earlier targeted run's
|
|
152
|
+
runpy-bootstrap fixture failure was corrected with its log retained.
|
|
153
|
+
|
|
154
|
+
These earlier results retain their failures and scope. They are not the
|
|
155
|
+
latest candidate's outcome; the successful follow-up run is recorded above.
|
|
2
156
|
|
|
3
157
|
<a id="028-development-and-earlier-maintenance-history"></a>
|
|
4
158
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mokuyoaxis/agent-guard",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.9",
|
|
4
4
|
"description": "Harness-neutral reliability infrastructure for AI coding agents: recoverable destructive actions, disclosure checks, controlled synthetic behaviour experiments, and a shared Core with optional native adapters.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"engines": {
|
|
@@ -51,11 +51,37 @@ Globs passed to `safe_delete` are expanded explicitly before anything moves.
|
|
|
51
51
|
That is why `safe_delete '*.log'` works while `rm *.log` is blocked: the
|
|
52
52
|
guard refuses opaque target sets, not cleanup work.
|
|
53
53
|
|
|
54
|
+
<a id="read-only-cleanup-inventory-unreleased-checkout"></a>
|
|
55
|
+
|
|
56
|
+
## Read-only cleanup inventory (0.2.9)
|
|
57
|
+
|
|
58
|
+
From a 0.2.9 installation or checkout, start a cleanup
|
|
59
|
+
investigation with a bounded directory overview:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/cleanup.py --discover --json
|
|
63
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/cleanup.py --measure --scope build --json
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Keep the same workspace root when selecting scopes. Use
|
|
67
|
+
`--discover --scope PATH` to inspect an unexpanded directory. Environment and managed-cache
|
|
68
|
+
labels are hints; all groups remain nonselectable. Unknown whole sizes stay
|
|
69
|
+
null, and a complete observed subset is not a complete workspace scan.
|
|
70
|
+
The corresponding MCP tools are `cleanup_discover` and `cleanup_measure`;
|
|
71
|
+
`ok: true, partial: true` is usable partial data, never execution permission.
|
|
72
|
+
|
|
73
|
+
These modes are absent from published 0.2.8. For that package, use its
|
|
74
|
+
existing plan workflow below. With the new modes, produce a separate reviewed
|
|
75
|
+
plan before any execution; `observation_id` cannot replace `plan_id`. Review
|
|
76
|
+
application-managed cache consistency separately. See
|
|
77
|
+
[observation limits](../../docs/guides/cleanup-plan.md#directory-overview-and-measurement-unreleased)
|
|
78
|
+
and [MCP semantics](../../docs/guides/mcp.md#cleanup-observations-unreleased).
|
|
79
|
+
|
|
54
80
|
<a id="cleanup-proposals-027-candidate"></a>
|
|
55
81
|
|
|
56
82
|
## Cleanup proposals (0.2.7)
|
|
57
83
|
|
|
58
|
-
|
|
84
|
+
To propose concrete executable candidates, produce a separate read-only plan:
|
|
59
85
|
|
|
60
86
|
```bash
|
|
61
87
|
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/cleanup.py --json
|