@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.
@@ -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. They are not claims that all three clients were exercised locally.
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 five
208
- tools. Check stderr when a dependency or executable cannot be found.
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 default Core suite skips seven real-stdio protocol cases. The two full
256
- runs above included that SDK and skipped none. A separate CI job now declares
257
- SDK-backed MCP checks for Python 3.10/3.13; it has not been run remotely in
258
- this work, and no remote-CI success is claimed.
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 or other
285
- tool coverage. Those three clients' examples were checked against official
286
- documentation, not exercised as live clients here. Native Windows, macOS and
287
- Android shared storage have no new validation. The first full-run error and
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.