@mokuyoaxis/agent-guard 0.2.7 → 0.2.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CONTRIBUTING.md +13 -0
- package/README.md +37 -27
- package/README.zh-CN.md +32 -24
- package/adapters/INTEGRATION.md +9 -3
- package/adapters/mcp/doctor.py +326 -0
- 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 +38 -13
- package/docs/design/architecture.md +63 -14
- package/docs/design/compatibility.md +121 -5
- package/docs/guides/cleanup-plan.md +97 -0
- package/docs/guides/getting-started.md +7 -6
- package/docs/guides/harness-capabilities.md +21 -4
- package/docs/guides/mcp.md +202 -11
- package/docs/releases/release-notes-0.2.8.md +172 -0
- package/docs/releases/release-notes-0.2.9.md +68 -0
- package/docs/releases/unreleased.md +198 -1
- package/doctor.py +25 -1
- package/live_sentinel.py +1 -1
- package/package.json +1 -1
- package/skills/delete-guard/SKILL.md +27 -1
- package/skills/delete-guard/scripts/cleanup.py +48 -3
package/docs/guides/mcp.md
CHANGED
|
@@ -9,6 +9,17 @@ first full run. They do not certify the new versioned artifact. See the
|
|
|
9
9
|
exact-version availability checks.
|
|
10
10
|
Configuration examples are not host acceptance.
|
|
11
11
|
|
|
12
|
+
Version **0.2.8** adds [local MCP diagnosis](#diagnose-a-local-service-028)
|
|
13
|
+
and protocol-interruption validation; see the
|
|
14
|
+
[0.2.8 scope and validation status](../releases/release-notes-0.2.8.md).
|
|
15
|
+
The later [Codex 0.165.0 acceptance](#codex-01650-with-published-027) below used
|
|
16
|
+
the published 0.2.7 package and is separate from both development checkpoints.
|
|
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
|
+
|
|
12
23
|
MCP gives a supporting coding-agent client an explicit way to use the existing
|
|
13
24
|
safe deletion and recovery operations. It does **not** intercept shell `rm`,
|
|
14
25
|
scripts, editor deletion or tools that bypass this server. Keep a compatible
|
|
@@ -75,6 +86,94 @@ in memory needs a trusted bridge to enforce them for MCP calls; registering
|
|
|
75
86
|
this server alone does not provide that bridge. Existing
|
|
76
87
|
[limits](deletion-limits.md) and the CLI's mode semantics still apply.
|
|
77
88
|
|
|
89
|
+
<a id="diagnose-a-local-service-028-development"></a>
|
|
90
|
+
|
|
91
|
+
## Diagnose a local service (0.2.8)
|
|
92
|
+
|
|
93
|
+
From a 0.2.8 or later installation or checkout, run:
|
|
94
|
+
|
|
95
|
+
```sh
|
|
96
|
+
python3 -B /absolute/path/to/agent-guard/doctor.py mcp \
|
|
97
|
+
--python /absolute/path/to/agent-guard-mcp-venv/bin/python \
|
|
98
|
+
--workspace /absolute/path/to/your-project --json
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
The installed CLI entry is `agent-guard-doctor mcp` with the same options.
|
|
102
|
+
`--python` defaults to the interpreter running the doctor; select the separate
|
|
103
|
+
SDK environment explicitly when the Core interpreter has no MCP SDK.
|
|
104
|
+
`--workspace` is required and must already exist. `--server` optionally selects
|
|
105
|
+
another reviewed `server.py`; otherwise the doctor uses its own package's
|
|
106
|
+
adapter. The doctor starts this script with the selected Python, so both are
|
|
107
|
+
trusted executable inputs. It uses no shell and does not discover or rewrite
|
|
108
|
+
client configuration. `--timeout` bounds the diagnostic checks in seconds
|
|
109
|
+
(default 30; accepted range 5–120). Closing the service process can add up to
|
|
110
|
+
three seconds of process waits and one second of reader-thread waiting beyond that deadline.
|
|
111
|
+
|
|
112
|
+
The checks cover:
|
|
113
|
+
|
|
114
|
+
1. The selected interpreter, pinned SDK metadata and actual SDK imports.
|
|
115
|
+
2. A classic `2025-06-18` stdio handshake, the `agent-guard` service identity
|
|
116
|
+
and a service version matching the doctor's package version.
|
|
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.
|
|
121
|
+
4. Successful `status`, `transactions` and `gc_plan` calls, including the
|
|
122
|
+
requested workspace and its local quarantine binding reported by `status`.
|
|
123
|
+
|
|
124
|
+
No model, deletion, restore, GC execution or dependency installation is part
|
|
125
|
+
of this diagnosis. It does not create host configuration or approve a budget
|
|
126
|
+
reset. A normal service leaves workspace file names and content unchanged
|
|
127
|
+
under these read-only calls; this is not a system-call-level zero-write proof
|
|
128
|
+
for an arbitrary selected script.
|
|
129
|
+
|
|
130
|
+
The independent JSON report has `schema_version: 1`, `harness: "mcp"`,
|
|
131
|
+
`status`, `stage`, `code`, `message`, `guidance` and `checks`. It contains
|
|
132
|
+
fixed diagnostic findings rather than raw service stderr, transaction data,
|
|
133
|
+
audit text, authentication or configuration contents. Exit code `0` means
|
|
134
|
+
the checks passed, `1` means a diagnosis failed, and `2` is a CLI usage error.
|
|
135
|
+
These diagnostic codes are separate from the Decision Protocol reason codes.
|
|
136
|
+
`diagnostic_stderr_bytes` reports only the captured stderr byte count; raw
|
|
137
|
+
stderr is not returned. After a successful status query, `deletion_admission`
|
|
138
|
+
is `BLOCKED` or `READABLE`. `READABLE` records that admission information was
|
|
139
|
+
inspected; it is not permission for a future deletion.
|
|
140
|
+
|
|
141
|
+
Use the returned stage and guidance to fix a missing interpreter/SDK, a
|
|
142
|
+
startup or protocol failure, a version mismatch, an incorrect workspace
|
|
143
|
+
binding or a query failure. A successful `status` can still report blocked
|
|
144
|
+
deletion admission; the text renderer highlights `BLOCKED`, and diagnosis does
|
|
145
|
+
not authorize deleting through that block.
|
|
146
|
+
|
|
147
|
+
`host_connection`, `model_delivery` and `host_interception` stay `UNVERIFIED`.
|
|
148
|
+
A PASS proves the selected service command answered these direct checks.
|
|
149
|
+
Inspect the actual client's connection and use a bounded host acceptance
|
|
150
|
+
trial to establish that a particular host and model used it. The doctor does
|
|
151
|
+
not extend Kimi/Claude hook diagnosis or automatically prove shell protection.
|
|
152
|
+
|
|
153
|
+
## After a lost response or interrupted connection
|
|
154
|
+
|
|
155
|
+
A client deadline, cancellation or process exit can occur after a mutation
|
|
156
|
+
has committed but before its response arrives. It does not roll the files or
|
|
157
|
+
budget back. Stop automatic mutation retries, reconnect to the same reviewed
|
|
158
|
+
workspace/quarantine/session identity, then inspect `status` and `transactions`.
|
|
159
|
+
Check the source and recovery payload before restoring the actual returned or
|
|
160
|
+
listed transaction. Ordinary restoration still refuses an existing occupant
|
|
161
|
+
and does not refund the deletion budget.
|
|
162
|
+
|
|
163
|
+
If evidence is incomplete or an operation may still be running, preserve it
|
|
164
|
+
and resolve the process/transaction state before another mutation. An absent
|
|
165
|
+
response or one empty query is not proof that nothing changed. Changing
|
|
166
|
+
session identity, removing admission state or manufacturing confirmation is
|
|
167
|
+
not recovery.
|
|
168
|
+
|
|
169
|
+
The 0.2.8 interruption checks target four response-loss windows: a client
|
|
170
|
+
deadline, a cancellation notification, stdin EOF and service termination.
|
|
171
|
+
Their controlled barrier is after real safe_delete has committed and before
|
|
172
|
+
the response is sent. They validate recoverability and persistent accounting
|
|
173
|
+
at that boundary, not arbitrary interruption within every multi-file operation
|
|
174
|
+
or atomic rollback. Final candidate results are recorded in the
|
|
175
|
+
[0.2.8 validation status](../releases/release-notes-0.2.8.md#validation-status).
|
|
176
|
+
|
|
78
177
|
## Tools and limits
|
|
79
178
|
|
|
80
179
|
| Tool | Inputs | Effect |
|
|
@@ -84,6 +183,8 @@ this server alone does not provide that bridge. Existing
|
|
|
84
183
|
| `transactions` | none | List the selected workspace's recovery transactions |
|
|
85
184
|
| `status` | optional integer `tail` (0–100, default 10) | Inspect recovery state, limits and recent audit information |
|
|
86
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 |
|
|
87
188
|
|
|
88
189
|
Paths are literal names, relative to the fixed workspace or absolute; the
|
|
89
190
|
Core still refuses outside targets. Glob characters name actual files rather
|
|
@@ -130,6 +231,50 @@ cancellation means nothing moved. Do not automatically retry a mutating call
|
|
|
130
231
|
after a client timeout or disconnection. The existing recovery, concurrency
|
|
131
232
|
and same-UID boundaries remain; this server is not an OS sandbox.
|
|
132
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
|
+
|
|
133
278
|
## Configure a client
|
|
134
279
|
|
|
135
280
|
The following examples register a local server; they do not run deletion or
|
|
@@ -198,14 +343,17 @@ called the tool or that all filesystem actions are covered. See the
|
|
|
198
343
|
[official OpenAI MCP documentation](https://learn.chatgpt.com/docs/extend/mcp?site_variant=chatgpt).
|
|
199
344
|
|
|
200
345
|
These source-based examples were checked against official documentation on
|
|
201
|
-
2026-10-28.
|
|
346
|
+
2026-10-28. Claude Code and Cursor remain configuration examples; the later
|
|
347
|
+
Codex acceptance below covers one exact version and selected MCP scenarios.
|
|
202
348
|
Client schemas, approvals and connection behavior can change; verify the
|
|
203
349
|
installed version rather than copying another client's configuration shape.
|
|
204
350
|
|
|
205
351
|
## Verify and report
|
|
206
352
|
|
|
207
|
-
1. Confirm the interpreter starts the server and the client discovers the
|
|
208
|
-
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.
|
|
209
357
|
2. Call `status`, `transactions` and `gc_plan` in a disposable project; confirm
|
|
210
358
|
preview leaves recovery payloads intact.
|
|
211
359
|
3. Create a small synthetic valuable file, call `safe_delete`, verify a real
|
|
@@ -216,8 +364,46 @@ installed version rather than copying another client's configuration shape.
|
|
|
216
364
|
results and unverified paths. A raw protocol test, a real client call and a
|
|
217
365
|
real-model trial are different evidence levels.
|
|
218
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
|
+
|
|
219
375
|
## Recorded validation and remaining limits
|
|
220
376
|
|
|
377
|
+
### Codex 0.165.0 with published 0.2.7
|
|
378
|
+
|
|
379
|
+
On 2026-10-29, **Codex CLI 0.165.0** on local ARM64/PRoot exercised the
|
|
380
|
+
published **agent-guard 0.2.7** package through Codex's actual MCP client.
|
|
381
|
+
Three controlled native-client groups, without model turns, covered five-tool
|
|
382
|
+
discovery, queries, deletion/restoration, quarantine/outside-target refusal,
|
|
383
|
+
protection and batch gates, and budget persistence across a fresh Codex
|
|
384
|
+
process. Read-only queries preserved the workspace file inventory and content
|
|
385
|
+
hashes.
|
|
386
|
+
|
|
387
|
+
Three separate real-model tasks using the configured `gpt-6.1-sol / max`
|
|
388
|
+
completed 16 MCP calls: ordinary delete/restore, same-session budget refusal
|
|
389
|
+
and protected-path refusal. Model call arguments and structured results
|
|
390
|
+
matched the recorded stdio requests and responses. Restored files matched
|
|
391
|
+
their original bytes; rejected files remained intact; restoration did not
|
|
392
|
+
refund the admitted budget. The model used only the MCP tools, and GC was
|
|
393
|
+
preview-only. There were no trial timeouts or harness-level automatic retries.
|
|
394
|
+
The client model label was observed; backend model identity was not
|
|
395
|
+
independently authenticated, and no upstream HTTP-request count is claimed.
|
|
396
|
+
|
|
397
|
+
Four native-client recorder exit-metadata files were incomplete. The captured
|
|
398
|
+
tool exchanges supported the reported behavior, and the recorded process IDs
|
|
399
|
+
were absent at the final check; the missing lifecycle metadata was not
|
|
400
|
+
reconstructed. This limitation is separate from the three completed model
|
|
401
|
+
tasks. These results apply to that published 0.2.7 artifact, exact Codex
|
|
402
|
+
version and cooperative MCP path, not later artifacts, native
|
|
403
|
+
shell/editor interception, arbitrary subagents or all Codex releases.
|
|
404
|
+
|
|
405
|
+
### Earlier preparation and Kimi checkpoints
|
|
406
|
+
|
|
221
407
|
The 219-file, versioned **0.2.7 preparation checkpoint** passed local validation on
|
|
222
408
|
2026-10-29: 1129 Python cases and both Node groups in 1194.265 seconds, with
|
|
223
409
|
no failures, errors, skips, timeouts or automatic retries. It used the existing
|
|
@@ -252,10 +438,15 @@ diagnostic unittest result collector with the same scope as `npm test`, then
|
|
|
252
438
|
the Node commands when Python passed; the npm command itself was not invoked.
|
|
253
439
|
|
|
254
440
|
Without the optional SDK or an explicitly configured MCP test interpreter,
|
|
255
|
-
the
|
|
256
|
-
runs above included that SDK and skipped none.
|
|
257
|
-
SDK-backed
|
|
258
|
-
|
|
441
|
+
the original Core checkpoint skipped seven real-stdio protocol cases. The two
|
|
442
|
+
full runs above included that SDK and skipped none. At that local checkpoint,
|
|
443
|
+
the separate SDK-backed Python 3.10/3.13 CI job had not been run remotely.
|
|
444
|
+
Subsequent 0.2.7 release validation for `7431da1` passed its
|
|
445
|
+
[15-job CI](https://github.com/mokuyoaxis/agent-guard/actions/runs/40835352396)
|
|
446
|
+
and [release workflow](https://github.com/mokuyoaxis/agent-guard/actions/runs/40842400686),
|
|
447
|
+
including 1130 Python cases and both Node groups with no release-test skips.
|
|
448
|
+
Those workflows predate the 0.2.8 doctor/interruption additions and do not
|
|
449
|
+
certify the new checks.
|
|
259
450
|
|
|
260
451
|
The 154-file offline package matched the frozen source and installed locally.
|
|
261
452
|
All 12 CLI help checks, adapter import, installed stdio handshake and five-tool
|
|
@@ -281,10 +472,10 @@ configuration/auth fingerprints and frozen candidate bytes remained equal.
|
|
|
281
472
|
The existing loopback gateway's actual server-side model identity was not
|
|
282
473
|
independently authenticated.
|
|
283
474
|
|
|
284
|
-
These results do not add native-hook, subagent, Claude/Cursor/Codex
|
|
285
|
-
tool coverage
|
|
286
|
-
|
|
287
|
-
|
|
475
|
+
These earlier Kimi results do not add native-hook, subagent, Claude/Cursor/Codex
|
|
476
|
+
or other tool coverage; the Codex result is recorded separately above. Claude
|
|
477
|
+
Code and Cursor remain documented examples. Native Windows, macOS and Android
|
|
478
|
+
shared storage have no new local host validation. The first full-run error and
|
|
288
479
|
the earlier unexplained project test timeouts remain recorded as unresolved;
|
|
289
480
|
the current successful full run is not evidence of a general timeout fix.
|
|
290
481
|
|
|
@@ -0,0 +1,172 @@
|
|
|
1
|
+
# 0.2.8 — MCP diagnosis and recovery validation
|
|
2
|
+
|
|
3
|
+
Version 0.2.8 adds MCP connection diagnosis, real protocol-interruption
|
|
4
|
+
checks and documentation to the
|
|
5
|
+
[0.2.7](https://github.com/mokuyoaxis/agent-guard/blob/0.2.8/docs/releases/release-notes-0.2.7.md)
|
|
6
|
+
baseline. Use the exact
|
|
7
|
+
[GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.8)
|
|
8
|
+
and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.8)
|
|
9
|
+
to verify availability before installing; a source version or local tarball
|
|
10
|
+
alone does not establish publication. The separate `rc` and `hotfix` channels
|
|
11
|
+
retain their versions.
|
|
12
|
+
|
|
13
|
+
本版提供 MCP 接入诊断与恢复验证。安装前核实精确版本的发行与包页面。已有 0.2.7 的测试、宿主实测
|
|
14
|
+
和发布记录保留各自版本边界,不能直接作为 0.2.8 候选的通过证据。
|
|
15
|
+
|
|
16
|
+
## Version scope
|
|
17
|
+
|
|
18
|
+
### Explicit MCP doctor
|
|
19
|
+
|
|
20
|
+
`agent-guard-doctor mcp` checks a selected local service through the existing
|
|
21
|
+
stdio interface. It checks the interpreter and optional pinned MCP SDK,
|
|
22
|
+
SDK imports, service handshake and package-matching version, the expected
|
|
23
|
+
five tools and query annotations, workspace/quarantine binding, and successful
|
|
24
|
+
`status`, `transactions` and `gc_plan` calls.
|
|
25
|
+
|
|
26
|
+
From this checkout or a package built from it:
|
|
27
|
+
|
|
28
|
+
```sh
|
|
29
|
+
python3 -B /absolute/path/to/agent-guard/doctor.py mcp \
|
|
30
|
+
--python /absolute/path/to/agent-guard-mcp-venv/bin/python \
|
|
31
|
+
--workspace /absolute/path/to/your-project --json
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
`--python` defaults to the doctor interpreter. `--server` optionally selects
|
|
35
|
+
another reviewed script, otherwise the package's own adapter is used.
|
|
36
|
+
`--timeout` defaults to 30 seconds and accepts 5–120 for diagnostic checks;
|
|
37
|
+
service-process shutdown can add up to three seconds of process waits and one second
|
|
38
|
+
of reader-thread waiting. The doctor starts these
|
|
39
|
+
trusted executable inputs without a shell; it neither installs dependencies
|
|
40
|
+
nor discovers or rewrites client configuration.
|
|
41
|
+
|
|
42
|
+
The independent `schema_version: 1` report contains fixed diagnostic status,
|
|
43
|
+
stage/code, message, guidance and checks. It does not expose raw child stderr,
|
|
44
|
+
configuration/authentication contents or recovery/audit records. Exit `0`
|
|
45
|
+
means PASS, `1` means diagnostic failure and `2` means invalid CLI usage.
|
|
46
|
+
These codes do not extend the Decision Protocol reason-code namespace.
|
|
47
|
+
The existing Kimi/Claude doctor paths retain their interfaces.
|
|
48
|
+
`diagnostic_stderr_bytes` exposes a byte count only. The report can show
|
|
49
|
+
`deletion_admission: BLOCKED` while connection checks pass; `READABLE` means
|
|
50
|
+
admission information was inspected, not that future deletion is approved.
|
|
51
|
+
|
|
52
|
+
A PASS covers direct checks of the selected service. `host_connection`,
|
|
53
|
+
`model_delivery` and `host_interception` stay `UNVERIFIED`; actual host loading
|
|
54
|
+
and model use require separate acceptance. No model, deletion, restore, GC
|
|
55
|
+
execution, policy modification or budget reset is performed by the doctor.
|
|
56
|
+
See the [MCP guide](https://github.com/mokuyoaxis/agent-guard/blob/0.2.8/docs/guides/mcp.md#diagnose-a-local-service-028).
|
|
57
|
+
|
|
58
|
+
### Recovery after response loss
|
|
59
|
+
|
|
60
|
+
The protocol checks target a client deadline, cancellation notification,
|
|
61
|
+
stdin EOF and service termination at a controlled barrier after safe_delete
|
|
62
|
+
has committed but before a response is sent. They inspect files, recovery
|
|
63
|
+
transactions, persistent accounting and ordinary restoration on reconnect.
|
|
64
|
+
This checks a specific response-loss boundary, not arbitrary partial
|
|
65
|
+
multi-file interruption or atomic rollback.
|
|
66
|
+
|
|
67
|
+
After an uncertain mutation, inspect status, transactions and the source/
|
|
68
|
+
recovery copy before another mutation. Reconnect with the same trusted
|
|
69
|
+
workspace/quarantine/session identity. Restoration does not refund the
|
|
70
|
+
deletion budget. See [interrupted-connection recovery](https://github.com/mokuyoaxis/agent-guard/blob/0.2.8/docs/guides/mcp.md#after-a-lost-response-or-interrupted-connection).
|
|
71
|
+
|
|
72
|
+
### Documentation and existing Codex evidence
|
|
73
|
+
|
|
74
|
+
The MCP guide now distinguishes direct-service diagnosis, live-client
|
|
75
|
+
acceptance and actual model calls. It includes the separate 2026-10-29
|
|
76
|
+
Codex CLI 0.165.0 acceptance of the published **0.2.7** package: three
|
|
77
|
+
native-client groups and three real-model tasks, totaling 16 model MCP calls.
|
|
78
|
+
That exact-version result covers the cooperative MCP path, not native Shell/
|
|
79
|
+
editor interception or the 0.2.8 candidate. Original failures and evidence
|
|
80
|
+
limitations remain in the [recorded validation](https://github.com/mokuyoaxis/agent-guard/blob/0.2.8/docs/guides/mcp.md#recorded-validation-and-remaining-limits).
|
|
81
|
+
|
|
82
|
+
## Compatibility and upgrade notes
|
|
83
|
+
|
|
84
|
+
The maintainer selected 0.2.8 for these bounded diagnosis/reliability additions.
|
|
85
|
+
Earlier doctor drift/live-sentinel additions were classified as minor. This
|
|
86
|
+
release's independent diagnostic surface is explicitly recorded as a
|
|
87
|
+
maintenance-version decision; the 0.2.7 exception is not inherited and does
|
|
88
|
+
not permit unrelated policy changes. See the
|
|
89
|
+
[compatibility decision](https://github.com/mokuyoaxis/agent-guard/blob/0.2.8/docs/design/compatibility.md#028-diagnosis-maintenance-decision).
|
|
90
|
+
|
|
91
|
+
The five MCP tools and their arguments, Decision classes/reasons, default
|
|
92
|
+
deletion rules, recovery manifests, persistent budget and preview-only MCP
|
|
93
|
+
GC retain their contracts. There is no storage/configuration migration or
|
|
94
|
+
automatic client setup. The pinned `mcp==2.3.0` SDK remains an optional
|
|
95
|
+
separate-environment dependency; Core/CLI still needs Python 3.9+ and Git
|
|
96
|
+
without third-party Python packages. MCP requires a compatible Python 3.10+
|
|
97
|
+
SDK environment.
|
|
98
|
+
|
|
99
|
+
Package/helper changes can make an older doctor fingerprint baseline
|
|
100
|
+
`DRIFTED`; it is not silently replaced. Existing installations require an
|
|
101
|
+
explicit upgrade to gain the new doctor path. Same-UID, concurrency and
|
|
102
|
+
uncovered-tool boundaries retain their existing scope. Configuration
|
|
103
|
+
diagnosis prototypes, new deletion permissions, automatic GC, 0.3.0 work
|
|
104
|
+
and commercial capabilities are outside this release.
|
|
105
|
+
|
|
106
|
+
## Install or evaluate version 0.2.8
|
|
107
|
+
|
|
108
|
+
After confirming availability on both publication pages above, install into
|
|
109
|
+
a chosen stable prefix:
|
|
110
|
+
|
|
111
|
+
```sh
|
|
112
|
+
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.8
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
For source review or before registry availability, use reviewed source or a
|
|
116
|
+
verified local tarball in a separate prefix. The optional MCP SDK is still
|
|
117
|
+
installed separately; npm does not install it or configure host clients.
|
|
118
|
+
Existing installations require an explicit upgrade.
|
|
119
|
+
|
|
120
|
+
## Validation status
|
|
121
|
+
|
|
122
|
+
Local 0.2.8 candidate validation **passed** on 2026-11-06. Local checks used ARM64/PRoot,
|
|
123
|
+
Python 3.13.5, Node 22.23.4 and the separate pinned MCP SDK 2.3.0 environment.
|
|
124
|
+
|
|
125
|
+
| Check | Observed result |
|
|
126
|
+
|---|---|
|
|
127
|
+
| Focused MCP doctor | 16 cases passed in 40.956 seconds, including four real-SDK cases |
|
|
128
|
+
| Focused protocol interruption | Four cases passed in 44.090 seconds |
|
|
129
|
+
| First completed full regression | 1152 Python cases in 1620.567 seconds: no assertion failures, one error, no skips; Node groups were not started after Python failed |
|
|
130
|
+
| Independent check of the failed case | Passed in 10.802 seconds (11.301 seconds for the outer process); this does not replace the failed full run |
|
|
131
|
+
| Complete rerun of the same candidate | PASS: 1152 Python cases and both Node groups, no failures/errors/skips, 1719.330 seconds overall; all 224 frozen public files were unchanged |
|
|
132
|
+
| Local package | 157 files; offline installation, 12 CLI help checks, installed doctor and actual MCP deletion/restoration passed; restored bytes matched and budget remained charged |
|
|
133
|
+
|
|
134
|
+
The full-run error was a fresh server's initialization exceeding its existing
|
|
135
|
+
20-second wait in an interruption test. The same run's monitoring also had a
|
|
136
|
+
415.159-second heartbeat gap. The cause remains unknown; that observation is
|
|
137
|
+
not a proven explanation for the timeout. Runtime, assertions and deadlines
|
|
138
|
+
were not changed to make the independent check or complete rerun pass.
|
|
139
|
+
The passing rerun also recorded a separate 470.896-second monitoring gap,
|
|
140
|
+
without test errors. Neither the passing checks nor these timing observations
|
|
141
|
+
establish the cause of the earlier timeout.
|
|
142
|
+
|
|
143
|
+
The full rerun used the existing immediate-diagnostic unittest collector,
|
|
144
|
+
followed by the two Node groups, with the public `npm test` pipeline's scope
|
|
145
|
+
and unchanged per-test limits. It did not invoke npm directly. All 1152 test
|
|
146
|
+
start/finish records paired uniquely; the 1800-second overall deadline was
|
|
147
|
+
retained. The SDK-backed doctor and interruption tests actually executed.
|
|
148
|
+
|
|
149
|
+
An earlier full attempt was intentionally stopped to add explicit handling
|
|
150
|
+
and a regression for an empty `--python` argument; it is not a completed full
|
|
151
|
+
run. That additional regression later passed among the 17 doctor cases in
|
|
152
|
+
the completed Python suite above. It is not combined with the earlier
|
|
153
|
+
16-case focused run and reported as a single 17-case focused result.
|
|
154
|
+
|
|
155
|
+
Package checks compare runtime and test bytes with the frozen full-test
|
|
156
|
+
candidate and account for documentation-only updates separately. They include
|
|
157
|
+
offline packing/installation, member hashes, the installed doctor and actual
|
|
158
|
+
MCP recovery. Optional-SDK skips are not protocol acceptance; SDK-backed release
|
|
159
|
+
checks must exercise the real protocol cases.
|
|
160
|
+
|
|
161
|
+
The implementation commit `1323ca5` subsequently passed
|
|
162
|
+
[CI 42353094903](https://github.com/mokuyoaxis/agent-guard/actions/runs/42353094903)
|
|
163
|
+
on 2026-11-07: all 15 jobs succeeded, including the Linux/macOS Python
|
|
164
|
+
3.9–3.13 matrices, Windows Core, DSH checks and both SDK-backed MCP jobs.
|
|
165
|
+
This checkpoint precedes the documentation-only publication alignment;
|
|
166
|
+
the release commit requires its own CI and the tag's Release workflow.
|
|
167
|
+
Actual CI/release runs and package availability remain separately verifiable;
|
|
168
|
+
these local and implementation-CI records do not certify a later artifact.
|
|
169
|
+
No new real-model trial was performed for 0.2.8.
|
|
170
|
+
|
|
171
|
+
The preceding 0.2.7 artifact and Codex/Kimi records retain their original
|
|
172
|
+
versions and scope. They are not substituted for this candidate's results.
|
|
@@ -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.
|