@mokuyoaxis/agent-guard 0.2.6 → 0.2.7

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,7 +9,7 @@ F21–F23 changes subsequently shipped in 0.2.3; F24–F25 shipped in 0.2.4.
9
9
  F26–F31 subsequently shipped in 0.2.5-rc1. RC2 adds shared audit metadata and
10
10
  observer startup maintenance; publication is checked by its versioned receipts.
11
11
  Current scope is in the
12
- [candidate notes](../releases/release-notes-0.2.5.md); historical failures and
12
+ [0.2.7 notes](../releases/release-notes-0.2.7.md); historical failures and
13
13
  test counts below are not rewritten by a later success.
14
14
 
15
15
  ## Current feedback maintenance · status, explanations and retained storage
@@ -567,3 +567,101 @@ Exact CLI/recovery paths and error diagnostics remain available, with the
567
567
  same mutation-intent durability and assessment/outcome failure behavior.
568
568
  Historical records, automatic session identity and other audit/output
569
569
  writers remain outside this change.
570
+
571
+ <a id="f32-deletion-admission"></a>
572
+
573
+ ## F32 · Repeated admitted deletions could keep growing recovery storage
574
+
575
+ The existing recovery path preserved valuable content but had no persistent
576
+ session byte/entry budget, rolling operation rate or same-target-set limit.
577
+ A caller could repeatedly delete/recreate content or launch fresh CLI
578
+ processes while adding more recovery copies. The soft 30-day/5-GiB GC plan
579
+ did not bound new admission and never purged automatically.
580
+
581
+ **0.2.7 change:** covered relocations, Git-clean compensation and
582
+ force-restore occupant preservation now check quarantine admission capacity.
583
+ Regenerable direct deletion also consumes applicable session/rate/repeat
584
+ budgets. Accounting is persisted before the guarded operation under a
585
+ cross-process lock; admitted failures and subsequent restores do not refund
586
+ it. Unnamed CLI processes share a stable bucket instead of receiving a fresh
587
+ budget on every invocation.
588
+
589
+ Defaults are 5 GiB/100000 quarantine entries, 1 GiB/10000 admitted session
590
+ entries, 60 operations per 60 seconds and five admissions of the same
591
+ normalized target set per window. `BLOCK_DELETE_LIMIT`, `BLOCK_DELETE_RATE`
592
+ and `BLOCK_DELETE_REPEAT` are upgrade-visible refusals. Inspect `status` and
593
+ the caller; rate/repeat windows can expire, while cumulative budgets require
594
+ explicit operator review and interactive `RESET` or a deliberate policy
595
+ adjustment. Do not switch session identity or remove state to bypass them.
596
+
597
+ Capacity pressure never triggers automatic GC or a fallback to permanent
598
+ deletion. Normal restore, explicit transaction GC and unprotected quarantine
599
+ payload housekeeping remain available without a new deletion debit. Existing
600
+ compound ASK and Git snapshots remain outside these counters. Logical
601
+ accounting and same-UID state are accident suppression, not an OS disk quota
602
+ or a complete anomaly detector. See [deletion limits](../guides/deletion-limits.md)
603
+ for metadata/hardlink accounting and fixed inventory bounds.
604
+
605
+ <a id="f33-batch-confirmation"></a>
606
+
607
+ ## F33 · Large automated deletion batches had no separate review gate
608
+
609
+ A supported automated command could compensate many concrete targets under
610
+ the existing deletion policy without an additional batch-size review. Looking
611
+ at each segment separately also let one shell request contain several
612
+ individually small deletions whose combined target set was large.
613
+
614
+ **0.2.7 change:** the enforced checker combines covered rm/artifact
615
+ and enumerated Git-clean targets before its first compensation. Operations
616
+ above 256 MiB or 1000 filesystem entries return
617
+ `BLOCK_DELETE_BATCH_CONFIRM`, directing the operator to the reviewed Cleanup
618
+ plan. The default plan only proposes candidates; execution requires exact
619
+ selection and terminal `EXECUTE`, followed by rescan and per-target
620
+ safe_delete calls.
621
+
622
+ Cleanup creates a ten-minute approval bound to the session, effective
623
+ configuration, exact paths and measured metadata. Each path is consumed once;
624
+ stale, changed, expired or replayed approval is refused. This lifts only the
625
+ batch gate, not protection, session/rate/repeat or quarantine capacity.
626
+ There is no new native host ASK/resume protocol; existing compound ASK and
627
+ Git SNAPSHOT behavior remains separate. The optional MCP adapter does not
628
+ expose approval creation or provide a `confirm=true` shortcut. See the
629
+ [Cleanup workflow](../guides/cleanup-plan.md).
630
+
631
+ <a id="f34-deletion-protection"></a>
632
+
633
+ ## F34 · Configured evidence and admission controls needed shared protection
634
+
635
+ Existing hard-coded workspace/Git/recovery boundaries did not express
636
+ additional project evidence roots or a shared protected-path list. Artifact
637
+ classification and housekeeping could not rely on such a declaration, and
638
+ new budget/configuration state needed protection from covered deletion.
639
+
640
+ **0.2.7 change:** the optional workspace
641
+ `.agent-guard/delete-policy.json` supplies literal protected paths and limits.
642
+ Protection covers lexical/physical locations, descendants and ancestor
643
+ deletion, before artifact or payload-housekeeping exemptions. The configuration
644
+ directory, `admission.json`, temporary state and `admission.lock` are protected.
645
+ Missing configuration uses documented defaults without creating the file;
646
+ malformed, unreadable or unsupported configuration returns
647
+ `BLOCK_DELETE_CONFIG_INVALID`. Overlap returns `BLOCK_DELETE_PROTECTED`;
648
+ unusable admission inventory, lock or state returns
649
+ `BLOCK_DELETE_STATE_INVALID` instead of silently disabling admission.
650
+
651
+ Fix the reported configuration/storage issue or preserve the protected
652
+ evidence; do not remove controls to make deletion proceed. This is cooperative
653
+ path protection, not legal hold, minimum directory retention or immutable
654
+ storage. Same-UID processes and unobserved writes/deletion channels remain
655
+ outside its authority. Existing recovery format and explicit GC semantics
656
+ are retained.
657
+
658
+ The maintainer selected version 0.2.7 for these F32–F34
659
+ changes as a bounded maintenance-version exception, recorded in
660
+ [compatibility](../design/compatibility.md#027-candidate-bounded-maintainer-selected-exception).
661
+ This does not relax the general minor-release promise for other patches.
662
+ The pre-alignment 1090/1123-case runs and sampled Kimi results keep their
663
+ original scope. At the 2026-10-29 versioned preparation checkpoint, 1129
664
+ Python cases and both Node groups passed in 1194.265 seconds, and the
665
+ 155-file offline package passed installed MCP checks. That local checkpoint
666
+ did not include remote CI or publication, and made no new real-model requests.
667
+ See the [versioned validation record](../releases/release-notes-0.2.7.md#validation-status).
@@ -0,0 +1,217 @@
1
+ # 0.2.7 — Cleanup, deletion limits and local MCP
2
+
3
+ Version 0.2.7 adds Cleanup plans, shared deletion admission and optional local
4
+ MCP tools to [0.2.6](https://github.com/mokuyoaxis/agent-guard/blob/0.2.7/docs/releases/release-notes-0.2.6.md).
5
+ Use the exact [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.7)
6
+ and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.7)
7
+ to verify availability before installing; a manifest, checkout or local
8
+ tarball alone does not establish publication. This version leaves the
9
+ existing `rc` and `hotfix` channels unchanged. The separate 0.3.0 plan remains
10
+ paused. Local preparation evidence below is dated 2026-10-29.
11
+
12
+ 本版收录 Cleanup Copilot、删除准入加固和可选本地 MCP 工具。新增预算与保护
13
+ 可能拒绝此前可执行的删除。安装前请确认精确版本的发行与包页面可用;下方
14
+ 版本化测试、打包与发布门记录单独保留,不能沿用旧 0.2.6 元数据工件的结论。
15
+
16
+ <a id="candidate-scope"></a>
17
+
18
+ ## Version scope
19
+
20
+ ### Cleanup Copilot
21
+
22
+ `agent-guard-cleanup` proposes workspace candidates with logical sizes,
23
+ reasons and projected effects in four categories: regenerable, explicitly
24
+ caller-declared discarded, uncertain and protected. Age, ignore status or
25
+ being untracked alone does not make a file disposable.
26
+
27
+ Default planning writes no workspace files, guard metadata or audit records.
28
+ Execution requires an unchanged reviewed plan, explicit selection and terminal
29
+ `EXECUTE` confirmation, then delegates to the existing safe_delete path.
30
+ Valuable files retain recovery copies and disk use; only provably regenerable
31
+ artifacts follow the existing physical-delete rules. See
32
+ [the workflow and limits](https://github.com/mokuyoaxis/agent-guard/blob/0.2.7/docs/guides/cleanup-plan.md).
33
+
34
+ ### Shared deletion admission
35
+
36
+ Optional `.agent-guard/delete-policy.json` supplies protected paths and limits.
37
+ Missing configuration uses defaults; malformed configuration or unusable
38
+ admission state refuses covered execution instead of silently disabling it.
39
+ The configuration directory and admission control files are protected.
40
+
41
+ | Default | Value |
42
+ |---|---|
43
+ | Quarantine admission ceiling | 5 GiB / 100000 entries |
44
+ | Cumulative session budget | 1 GiB / 10000 entries |
45
+ | Rolling rate | 60 admissions per 60 seconds |
46
+ | Repeated normalized target set | 5 admissions per window |
47
+ | Batch review threshold | Above 256 MiB or 1000 entries |
48
+
49
+ Measurement, durable debit and guarded mutation share a cross-process lock.
50
+ Unnamed CLI processes use a stable shared budget; failures and later restores
51
+ do not refund admitted bytes/entries. Rate windows expire, while cumulative
52
+ budgets require explicit operator action. A repeated-target-set stop is a
53
+ simple loop signal, not a general anomaly detector.
54
+
55
+ Large covered automated deletions return `BLOCK_DELETE_BATCH_CONFIRM` with
56
+ Cleanup guidance. The shell checker combines supported rm/artifact/Git-clean
57
+ targets across a request before its first compensation. Cleanup confirmation
58
+ creates a ten-minute session/configuration/path/metadata-bound approval,
59
+ consumed once per selected path; it lifts only the batch gate, not protection,
60
+ capacity, budget or rate limits.
61
+
62
+ The additive refusal codes are:
63
+
64
+ - `BLOCK_DELETE_CONFIG_INVALID`
65
+ - `BLOCK_DELETE_PROTECTED`
66
+ - `BLOCK_DELETE_LIMIT`
67
+ - `BLOCK_DELETE_RATE`
68
+ - `BLOCK_DELETE_REPEAT`
69
+ - `BLOCK_DELETE_BATCH_CONFIRM`
70
+ - `BLOCK_DELETE_STATE_INVALID`
71
+
72
+ Existing Decision classes, check.py exit roles and recovery-manifest formats
73
+ retain their contracts. No data/configuration migration or automatic GC is
74
+ introduced. See [defaults, accounting and operator recovery](https://github.com/mokuyoaxis/agent-guard/blob/0.2.7/docs/guides/deletion-limits.md)
75
+ and the [compatibility contract](https://github.com/mokuyoaxis/agent-guard/blob/0.2.7/docs/design/compatibility.md) for the bounded
76
+ maintainer decision to select 0.2.7 for these additions.
77
+
78
+ ### Optional local MCP tools
79
+
80
+ `agent-guard-mcp` exposes safe_delete, ordinary restore, transactions, status
81
+ and GC-plan preview over local stdio. Workspace, local quarantine and stable
82
+ session identity are fixed at trusted startup. Tools cannot supply a new
83
+ workspace/session/environment, force restore, GC execution, budget reset or
84
+ Cleanup approval. Quarantine targets are refused by MCP safe_delete to avoid
85
+ a permanent-GC shortcut.
86
+
87
+ The official MIT-licensed `mcp==2.3.0` SDK is installed separately in an
88
+ optional Python 3.10+ environment. Core/CLI still requires Python 3.9+ and Git
89
+ without third-party Python packages; npm does not install the SDK. No server
90
+ network listener is provided. Follow the [MCP setup guide](https://github.com/mokuyoaxis/agent-guard/blob/0.2.7/docs/guides/mcp.md).
91
+
92
+ MCP is an explicit cooperative tool interface. It does not intercept shell,
93
+ script or editor operations that bypass it. Startup session selection chooses
94
+ the existing CLI authorization mode as well as budget. It does not inherit
95
+ native host restrictions or an in-memory veto without trusted bridging.
96
+
97
+ ## Upgrade and operator notes
98
+
99
+ - Covered automated filesystem compensation, regenerable direct deletion,
100
+ Git-clean compensation and force-restore occupant preservation can newly
101
+ refuse work when limits are reached. An earlier advisory assessment is not
102
+ a capacity grant. A later refusal can follow completed earlier operations;
103
+ inspect returned transaction IDs and the filesystem.
104
+ - Normal restore remains available without a fresh deletion debit. Explicit
105
+ transaction GC and existing unprotected quarantine housekeeping retain
106
+ their exemptions; configuration/control-path protection still precedes
107
+ housekeeping. The existing GC CLI's `--execute` does not require a TTY;
108
+ MCP's preview-only scope does not change that separate interface.
109
+ - Existing compound-command ASK and Git reset/restore/checkout SNAPSHOT paths
110
+ are outside these new admission counters. Git stash storage can still grow.
111
+ Do not describe this release as a limit on every destructive operation.
112
+ - `status.py --reset-delete-budget` requires an interactive terminal and
113
+ `RESET`, after investigation. It resets only the selected bucket and its
114
+ approvals, without deleting recovery copies or altering capacity/limits.
115
+ Agents must not change identity, remove state or manufacture confirmation
116
+ to bypass a refusal.
117
+ - Accounting uses bounded logical lstat inventory, including directory and
118
+ symlink metadata and conservative per-entry hardlink counts. It is not an
119
+ OS disk quota. Audit/manifest metadata and unrelated writers can still grow
120
+ storage; scan/state bounds may refuse before a larger configured limit.
121
+ - Package/Core changes affect doctor fingerprints. An old baseline may become
122
+ `DRIFTED`; it is not silently replaced, and a new local baseline does not
123
+ prove native-hook interception or model receipt of feedback.
124
+
125
+ Existing installations require an explicit upgrade to acquire these additions.
126
+ Installing a separate copy does not upgrade another existing installation;
127
+ host configuration and hook activation remain separate steps.
128
+ Same-UID, concurrency and uncovered-tool
129
+ limitations remain in the [threat model](https://github.com/mokuyoaxis/agent-guard/blob/0.2.7/docs/design/threat-model.md).
130
+
131
+ <a id="evaluate-the-unpublished-candidate"></a>
132
+
133
+ ## Install or evaluate version 0.2.7
134
+
135
+ After confirming that the exact version is available on both publication
136
+ pages above, install it into a chosen, stable prefix:
137
+
138
+ ```sh
139
+ npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.7
140
+ ```
141
+
142
+ For source review or before publication is available, use a reviewed checkout
143
+ or a tarball produced and checked from that exact source. An already-built
144
+ local tarball can be installed into a disposable prefix:
145
+
146
+ ```sh
147
+ npm install --offline --ignore-scripts --legacy-peer-deps --no-audit --no-fund \
148
+ --prefix /absolute/path/to/agent-guard-review \
149
+ /absolute/path/to/mokuyoaxis-agent-guard-0.2.7.tgz
150
+ ```
151
+
152
+ The optional MCP SDK remains a separate installation. Compare the selected
153
+ package with the release artifact checksum; local packaging and the version
154
+ string alone do not establish registry availability.
155
+
156
+ ## Validation status
157
+
158
+ **Local 0.2.7-versioned validation passed on 2026-10-29.** The explicit
159
+ 219-file public candidate excluded private experiments. All 1129 Python cases
160
+ and both Node groups passed in 1194.265 seconds, with no failures, errors,
161
+ skips, timeouts or automatic retries. The existing diagnostic collector kept
162
+ `npm test`'s scope and original deadlines; npm itself was not invoked.
163
+
164
+ The 155-file 0.2.7 package passed offline installation, all 12 CLI entry-point
165
+ checks and actual installed stdio deletion, restoration, persistent-budget,
166
+ protection and batch-gate checks. MCP `serverInfo.version` matched package
167
+ version `0.2.7`; read-only tools left the workspace unchanged and forbidden
168
+ override/force/reset/GC-execute arguments were refused. A separate final
169
+ package consistency check verifies documentation-only updates against the
170
+ tested runtime and the final source.
171
+
172
+ Six release-gate tests executed the workflow's actual SDK preflight body:
173
+ missing/wrong/broken SDK and disabled/skipped/empty protocol suites were
174
+ refused. The same body also passed against the existing isolated SDK. The tag
175
+ workflow now installs that pinned SDK and requires enabled protocol coverage
176
+ before its unchanged `npm test` step. These are the **2026-10-29 local
177
+ preparation results**: they did not include final-commit remote CI or
178
+ publication checks and made no new real-model requests. Published artifact
179
+ and workflow results must be checked through the exact version links above.
180
+
181
+ Earlier local source evidence is retained with its original checkpoint:
182
+
183
+ | Checkpoint | Observed result |
184
+ |---|---|
185
+ | Cleanup-only | 1012 Python cases and both Node groups passed continuously in 979.997 seconds; 37 Cleanup/9 manifest checks and a 146-file offline package also passed |
186
+ | Deletion hardening | Three independent runs each passed 1090 Python cases and both Node groups in 1061.017 / 1025.315 / 1042.145 seconds; a 149-file offline package and three real Kimi root-Bash scenarios passed |
187
+ | MCP source, first full run | 1123 Python cases, one observer READY-startup error, no skips; 1156.312 seconds; Node did not start |
188
+ | Same MCP source, second full run | 1123 Python cases and both Node groups passed in 1143.435 seconds, without failures, errors, skips, timeouts or automatic retries |
189
+ | MCP source packaging | 154 files / 12 CLI checks, local offline installation and actual installed stdio deletion/recovery/budget/protection checks passed |
190
+
191
+ These source/package checks used 0.2.6 package metadata before selecting
192
+ version 0.2.7. They are not acceptance of a renamed 0.2.7 tarball. The first MCP
193
+ run's observer error remains unresolved; the unchanged case passed separate
194
+ SDK/system-Python checks in 4.409 / 2.979 seconds. The successful second run
195
+ does not establish a general timeout fix. Both full runs used the existing
196
+ diagnostic result collector with npm test's scope and original deadlines,
197
+ without invoking npm itself.
198
+
199
+ At the earlier 0.2.6-metadata MCP checkpoint, three real Kimi Code 2.3.0
200
+ root-agent native MCP trials passed: normal
201
+ deletion/model-driven restore (27.288 seconds), same-session budget refusal
202
+ and model-driven restore (26.121 seconds), and configured protection
203
+ (16.814 seconds). All 19 configured-route requests returned HTTP 200;
204
+ 16 model-generated MCP calls matched native stdio requests, without Bash,
205
+ fixed replies, automatic trial retries or route changes. Restored bytes and
206
+ user configuration/auth fingerprints matched; restored budget remained
207
+ charged. The existing loopback gateway's server-side model identity was not
208
+ independently authenticated.
209
+
210
+ Local evidence is ARM64/PRoot POSIX, Python 3.13.5 and Node 22.23.4.
211
+ Without the optional SDK, seven real-stdio protocol cases skip; the local
212
+ 0.2.7 full run included that SDK, and the release gate refuses skipped
213
+ protocol coverage. New SDK-backed CI declarations are not
214
+ remote-CI results. Protocol evidence exercised the classic 2025-06-18
215
+ handshake, not every extension/client version. Claude/Cursor/Codex examples
216
+ are documentation guidance; no new live-client, subagent, native Windows,
217
+ macOS or shared-Android-storage acceptance is claimed.
@@ -1,4 +1,136 @@
1
- # Maintenance delivered in 0.2.6 / 0.2.6 维护说明
1
+ # 0.2.7 changes and 0.2.6 maintenance history
2
+
3
+ <a id="unreleased-changes-and-026-maintenance-history"></a>
4
+ <a id="027-candidate-changes-and-026-maintenance-history"></a>
5
+
6
+ The maintainer selected **0.2.7** for Cleanup Copilot, deletion admission and
7
+ optional local MCP tools. Check its exact GitHub release and npm version
8
+ through the [version notes](release-notes-0.2.7.md) before installing; a source
9
+ version alone does not establish publication. This path is retained for
10
+ existing links. At the **2026-10-29 local preparation checkpoint**, versioned
11
+ validation passed:
12
+ 1129 Python cases and both Node groups in 1194.265 seconds, with no failures,
13
+ errors, skips, timeouts or automatic retries, plus a 155-file offline package
14
+ and installed MCP identity/operation checks. The diagnostic collector kept
15
+ `npm test` scope/deadlines without invoking npm. Release SDK-gate fault checks
16
+ also passed; that checkpoint did not include final-commit remote CI or
17
+ publication. These results are separate from the historical checkpoints below; this preparation
18
+ made no new real-model requests. See
19
+ [version scope, upgrade effects and validation](release-notes-0.2.7.md).
20
+ The separate 0.3.0 plan remains paused.
21
+
22
+ <a id="local-mcp-tools-unreleased"></a>
23
+ <a id="local-mcp-tools-027-candidate"></a>
24
+
25
+ ## Local MCP tools (0.2.7)
26
+
27
+ The checkout adds an optional local stdio server for explicit safe_delete,
28
+ ordinary restore, transaction/status queries and GC-plan preview. Workspace
29
+ and stable session identity are set at startup; tools cannot override them,
30
+ the environment or quarantine. Operations use the existing CLI without a
31
+ shell and retain deletion protection, budget, audit and recovery semantics.
32
+ Session selection chooses saved CLI authorization mode as well as budget;
33
+ without it, legacy CLI state and the shared default bucket apply. Reusing
34
+ state requires matching workspace/quarantine/session. Native host-session
35
+ restrictions or in-memory veto require trusted bridging and are not inherited
36
+ merely by registering this server.
37
+ No force restore, GC execution, budget reset or Cleanup approval is exposed;
38
+ safe-delete quarantine targets are also refused. The existing GC CLI remains
39
+ separate; preview-only MCP does not add a terminal requirement to that CLI.
40
+
41
+ The official MIT-licensed `mcp==2.3.0` SDK is an optional separate-environment
42
+ dependency, not a new Core/CLI requirement or automatic npm installation.
43
+ MCP tools do not replace native hooks or cover shell/script/editor actions
44
+ that bypass them. For the 2026-10-28 frozen candidate, the first full local
45
+ run finished 1123 Python cases with one observer READY-startup error in
46
+ 1156.312 seconds; Node did not run. The original error remains unresolved.
47
+ The same case passed separate SDK/system-Python checks, and a second complete
48
+ run passed all 1123 Python cases and both Node groups in 1143.435 seconds,
49
+ without failures, errors, skips, timeouts, runtime changes or automatic retries.
50
+ The diagnostic collector preserved `npm test` scope/deadlines; npm itself was
51
+ not invoked. Default Core testing without the optional SDK skips seven
52
+ protocol cases; the two recorded full runs included it. An independent
53
+ SDK CI job is configured; the local preparation checkpoint included no
54
+ remote execution of that job.
55
+
56
+ The 154-file offline install/12 CLI checks and three real Kimi 2.3.0 native-MCP
57
+ trials passed: ordinary delete/restore, same-session budget and configured
58
+ protection. The model made 16 MCP calls across 19 real configured-route HTTP
59
+ 200 requests, without Bash, fixed replies or route changes. Its gateway's
60
+ server-side model identity was not independently verified. Local evidence
61
+ covers ARM64/PRoot Python 3.13.5; there are no new Windows/macOS/shared-storage
62
+ or live Claude/Cursor/Codex tests. Their setup examples remain documentation
63
+ guidance. See [installation, failure history and limits](../guides/mcp.md).
64
+ Published 0.2.6 and its old evidence remain unchanged; 0.3.0 is still paused.
65
+
66
+ <a id="deletion-admission-hardening-unreleased"></a>
67
+ <a id="deletion-admission-hardening-027-candidate"></a>
68
+
69
+ ## Deletion admission hardening (0.2.7)
70
+
71
+ The current checkout adds quarantine capacity admission, persistent session
72
+ byte/entry budgets, short-window rate and repeated-target-set limits, and
73
+ shared protected paths in optional `.agent-guard/delete-policy.json`.
74
+ Cross-process locking covers measurement, durable admission debit and the
75
+ guarded mutation. Failures and restores do not refund session budget; unnamed
76
+ CLI processes share a default bucket. Configuration/state failures block new
77
+ admission instead of silently disabling limits.
78
+
79
+ Large batches require Cleanup's existing terminal review, followed by a
80
+ ten-minute approval bound to paths, metadata, configuration and session and
81
+ consumed once per selected path. Covered automated large-delete checks BLOCK with
82
+ Cleanup guidance; no new host approval/resume protocol is added. Approval
83
+ does not bypass capacity, budgets or protection. Status adds explicit
84
+ terminal-confirmed reset of the current budget only.
85
+ Existing compound-command ASK and Git snapshots remain outside the new
86
+ budget; normal restore, explicit GC and unprotected quarantine housekeeping
87
+ remain exempt. Configuration/control-path protection still applies.
88
+
89
+ Accounting uses logical `lstat` sizes including directory metadata and
90
+ conservative per-entry hardlink counts, not physical disk quotas. Audits,
91
+ metadata and unrelated writers can still grow storage. GC remains explicit;
92
+ capacity refusal never downgrades to permanent deletion. See
93
+ [defaults, reason codes and recovery](../guides/deletion-limits.md).
94
+
95
+ The 2026-10-28 frozen public runtime passed three independent full runs,
96
+ each with 1090 Python cases and both Node groups: 1061.017, 1025.315 and
97
+ 1042.145 seconds, with no failures, errors, skips, timeouts or automatic retries.
98
+ The existing diagnostic collector retained `npm test` scope/deadlines without
99
+ invoking npm itself. An offline 149-file package and three real Kimi 2.3.0
100
+ root-Bash cases passed; nine configured-route model requests returned HTTP 200.
101
+ See the guide for POSIX-only validation, gateway identity and host/tool limits.
102
+ The earlier unexplained npm timeout did not recur; its history is retained.
103
+ The Cleanup-only results below predate these changes. Those earlier checks
104
+ used 0.2.6 package metadata without claiming the additions shipped in that
105
+ release. Subsequent versioned 0.2.7 tests and package checks passed as recorded
106
+ above; the separate 0.3.0 plan remains paused.
107
+
108
+ <a id="cleanup-copilot-unreleased"></a>
109
+ <a id="cleanup-copilot-027-candidate"></a>
110
+
111
+ ## Cleanup Copilot (0.2.7)
112
+
113
+ The current checkout adds a metadata-only cleanup plan and an explicitly
114
+ confirmed CLI execution workflow. It reports regenerable, caller-declared
115
+ discarded, uncertain and protected targets with logical sizes, reasons and
116
+ projected deletion/quarantine effects. Execution still uses safe_delete;
117
+ ordinary quarantined files retain disk usage. The default plan writes no
118
+ workspace or guard metadata. See [usage and limits](../guides/cleanup-plan.md).
119
+
120
+ This initial addition is separate from published 0.2.6 and is included in
121
+ version 0.2.7. At its initial checkpoint it added no native host tool or
122
+ deletion-policy change. Subsequent admission hardening is described above. At the Cleanup-only
123
+ checkpoint, the runtime passed a continuous local ARM64/PRoot POSIX rerun:
124
+ 1012 Python cases and both Node groups in 979.997 seconds, with no failures,
125
+ errors, skips or retries. This used the existing diagnostic result collector
126
+ with the same test scope and deadlines as `npm test`. The earlier literal
127
+ npm command's timeout remains recorded and unexplained; it did not recur
128
+ in this rerun. Focused cleanup/manifest checks and an offline package also passed,
129
+ including terminal confirmation, physical deletion and quarantine/restore.
130
+ See the guide's [validation scope](../guides/cleanup-plan.md#validation-scope)
131
+ for the local platform and host limits.
132
+
133
+ ## Maintenance delivered in 0.2.6 / 0.2.6 维护说明
2
134
 
3
135
  Updated 2026-10-22. The additions previously tracked here now ship in
4
136
  [0.2.6](release-notes-0.2.6.md). This path is retained for existing links and
@@ -126,16 +258,18 @@ commands; restoration and repeat-Stop checks passed. This does not establish
126
258
  all-model, subagent, background or long-running behavior. The new DSH
127
259
  diagnostic checks made no external model requests.
128
260
 
129
- ## 中文摘要
261
+ <a id="中文摘要"></a>
262
+
263
+ ## 0.2.6 中文摘要
130
264
 
131
- 本页记录已纳入 0.2.6 的维护:Kimi 可选 Stop 恢复反馈、120 秒外层超时接入说明,以及
265
+ 以下为 0.2.6 历史维护摘要:Kimi 可选 Stop 恢复反馈、120 秒外层超时接入说明,以及
132
266
  DSH Lab 版本/配置预检的原因、退出码和计时诊断,及 Kimi Stop 的独立 doctor 检查。
133
267
  后续默认删除适配加入 DSH `0.2.1-alpha.4`,读取脱敏/Lab 不随之扩大。
134
268
  Kimi Bash profile 新增精确版本 2.3.0;CLI/ACP 各八项固定响应试次提供有限根代理证据,
135
269
  未调用外部模型,也未扩大 Kimi Lab 的 2.1.1 准入或子代理声明。
136
270
  Stop 未配置不报错;配置或本地探针失败退出 1,模型送达始终未验证。已发布 0.2.5 的范围保持原记录;
137
- 已有安装需升级至 0.2.6,Stop 另需显式配置;原页面路径为已有链接保留。
271
+ 这些功能自 0.2.6 起提供,Stop 另需显式配置;原页面路径为已有链接保留。
138
272
 
139
273
  版本/文档对齐前,最终实现检查点的 974 项 Python 与两组 Node 已在同一冻结流程通过;
140
274
  此前 962 项检查点和历史失败分别保留,原失败原因仍未确定。
141
- 删除策略、rm 通配符规则、恢复格式和手动 GC 保持原样。
275
+ 上述 0.2.6 维护未改变删除策略、rm 通配符规则、恢复格式或手动 GC。
@@ -97,7 +97,7 @@ The pinned `read` tool's presentation metadata contains the returned lines.
97
97
  Replacing only `content` therefore leaves a second copy of read text in the
98
98
  private session/UI data.
99
99
 
100
- The [native probe](../../tests/probes/dsh_result_hook.mjs) instantiates the real
100
+ The [native probe](https://github.com/mokuyoaxis/agent-guard/blob/e73101666288735880d4ff70bb0a20a025d426b0/tests/probes/dsh_result_hook.mjs) instantiates the real
101
101
  Cordis, SystemPrompt and ToolRuntime services, registers synthetic tools and
102
102
  tests their results without a model, shell, session or network request:
103
103
 
@@ -287,7 +287,7 @@ old direct-Python hook-startup failure demonstrates a concrete fail-open
287
287
  boundary; the later bridge trial shows only a bounded mitigation.
288
288
  The fixtures and traces were preserved for review. Adapter-level regressions
289
289
  for both inert command shapes live in
290
- [`tests/test_kimi_adapter.py`](../../tests/test_kimi_adapter.py).
290
+ [`tests/test_kimi_adapter.py`](https://github.com/mokuyoaxis/agent-guard/blob/75b51b888279583541792e00b14a4ceaf2a59fba/tests/test_kimi_adapter.py).
291
291
 
292
292
  After the live trials, the Kimi adapter was tightened to reject malformed
293
293
  `PreToolUse` JSON and missing required Bash fields. Unit tests verify this
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mokuyoaxis/agent-guard",
3
- "version": "0.2.6",
3
+ "version": "0.2.7",
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": {
@@ -25,6 +25,8 @@
25
25
  "agent-guard-lab": "./guard_lab.py",
26
26
  "agent-guard-check": "./skills/delete-guard/scripts/check.py",
27
27
  "agent-guard-safe-delete": "./skills/delete-guard/scripts/safe_delete.py",
28
+ "agent-guard-cleanup": "./skills/delete-guard/scripts/cleanup.py",
29
+ "agent-guard-mcp": "./adapters/mcp/server.py",
28
30
  "agent-guard-restore": "./skills/delete-guard/scripts/restore.py",
29
31
  "agent-guard-status": "./skills/delete-guard/scripts/status.py",
30
32
  "agent-guard-exfil-check": "./skills/exfil-guard/scripts/check_span.py",
@@ -10,6 +10,10 @@ description: >-
10
10
 
11
11
  # delete-guard
12
12
 
13
+ Version **0.2.7** adds the Cleanup proposals and deletion admission described
14
+ below; 0.2.6 lacks these additions. See the
15
+ [0.2.7 scope, upgrade impact and exact-version availability checks](../../docs/releases/release-notes-0.2.7.md).
16
+
13
17
  You operate inside a workspace where irreversible destruction is not a
14
18
  default capability. This skill defines the deletion discipline the guard
15
19
  enforces and how to work with it productively. The four pillars:
@@ -47,6 +51,66 @@ Globs passed to `safe_delete` are expanded explicitly before anything moves.
47
51
  That is why `safe_delete '*.log'` works while `rm *.log` is blocked: the
48
52
  guard refuses opaque target sets, not cleanup work.
49
53
 
54
+ <a id="cleanup-proposals-027-candidate"></a>
55
+
56
+ ## Cleanup proposals (0.2.7)
57
+
58
+ When asked to investigate workspace cleanup, start with a read-only plan:
59
+
60
+ ```bash
61
+ python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/cleanup.py --json
62
+ ```
63
+
64
+ The planner separates regenerable, explicitly discarded, uncertain and
65
+ protected entries, with sizes, reasons and projected effects. Declare known
66
+ discarded paths with `--discard PATH` and evidence/backup roots with
67
+ `--protect PATH`. Age, ignore status and untracked status alone do not prove
68
+ discardability. `.internal`, Git metadata and recovery boundaries are pruned.
69
+
70
+ Only propose the plan by default. Execution requires `--execute`, the
71
+ reviewed `--plan-id`, exact `--select PATH` entries and a human's terminal
72
+ acknowledgement. Do not answer that prompt on the user's behalf. The tool
73
+ rechecks the plan after confirmation and delegates to existing safe_delete;
74
+ ordinary files retain recovery copies and disk usage. This CLI adds no
75
+ native host tool or human-identity guarantee. See the
76
+ [workflow, effects and limits](../../docs/guides/cleanup-plan.md).
77
+
78
+ <a id="deletion-admission-027-candidate"></a>
79
+
80
+ ## Deletion admission (0.2.7)
81
+
82
+ Covered deletion paths now share persistent session byte/entry budgets,
83
+ short-window rate/repeated-target-set limits and quarantine capacity admission.
84
+ The optional workspace `.agent-guard/delete-policy.json` configures limits
85
+ and protected paths; its directory and admission control files are protected.
86
+ Protection wins over artifact and housekeeping exemptions. Missing configuration
87
+ uses defaults; malformed configuration or state blocks new admission.
88
+
89
+ Defaults are 5 GiB/100000 entries for quarantine admission, 1 GiB/10000
90
+ entries per persistent session, 60 operations per 60 seconds, five repeated
91
+ admissions of one target set per window, and batch review above 256 MiB or
92
+ 1000 entries. Counts include filesystem entries and logical metadata; these
93
+ limits are not an OS storage quota. Updating the package does not silently
94
+ reset existing counters or replace a drifted doctor baseline.
95
+
96
+ Unnamed CLI processes share a stable budget. Failed admitted operations and
97
+ restores do not refund it. A limit refusal is not permission to change session
98
+ identity, remove state, disguise the delete or purge recovery copies. Inspect
99
+ status and explain the reason. Large batches require the reviewed Cleanup
100
+ workflow; covered automated checks BLOCK rather than creating a new host ASK flow.
101
+ Cleanup's ten-minute, one-use-per-path approval still obeys budgets, capacity
102
+ and protection. No limit automatically triggers permanent deletion or GC.
103
+ Existing compound ASK and Git snapshot paths are outside this new budget;
104
+ normal restore, explicit GC and unprotected quarantine housekeeping retain
105
+ their exemptions. Configuration/control-path protection still applies.
106
+
107
+ After investigation, an operator can explicitly reset the current bucket with
108
+ `status.py --reset-delete-budget`, an interactive terminal and `RESET`.
109
+ Do not supply this acknowledgement on the user's behalf. Reset does not free
110
+ storage or change limits; normal restore and explicit GC remain separate.
111
+ Portable state and TTY remain advisory against same-UID processes. See
112
+ [defaults, accounting and limits](../../docs/guides/deletion-limits.md).
113
+
50
114
  ## If you run `rm` / destructive git anyway
51
115
 
52
116
  A harness adapter may intercept the command before execution. Verdicts you
@@ -62,6 +126,10 @@ can receive:
62
126
  | `BLOCK_OUT_OF_WORKSPACE` / `BLOCK_PROTECTED_PATH` / `BLOCK_PROTECTED_ANCESTOR` | outside boundary, workspace root, `.git`, or a filesystem root (`/`, `/home`, `/usr`, `$HOME`) | do not retry; this is a hard boundary. Ask the human if it is truly needed |
63
127
  | `BLOCK_RESTRICTED_MODE` | session is downgraded | only explicit single-file deletes are permitted; ask the human for anything more |
64
128
  | `BLOCK_FORCE_PUSH` | remote history destruction | do not retry; escalate to the human |
129
+ | `BLOCK_DELETE_CONFIG_INVALID` / `BLOCK_DELETE_STATE_INVALID` | invalid configuration, state or admission machinery | stop and report; do not remove state to bypass the refusal |
130
+ | `BLOCK_DELETE_PROTECTED` | configured protection or deletion configuration overlap | preserve the target and its protected descendants |
131
+ | `BLOCK_DELETE_LIMIT` / `BLOCK_DELETE_RATE` / `BLOCK_DELETE_REPEAT` | capacity, cumulative budget or short-window limit | inspect status/loop; wait only when the reported window can expire |
132
+ | `BLOCK_DELETE_BATCH_CONFIRM` | large operation or stale/consumed Cleanup approval | propose and review a fresh Cleanup plan |
65
133
 
66
134
  Shape rules on compound commands: a single line that `cd`s anywhere before a
67
135
  destructive op (F1), or that creates files (`touch/mkdir/cp/mv/tee`,
@@ -195,7 +263,7 @@ space and remain subject to its existing explicit GC policy.
195
263
  See `references/policy.md` for the complete rule table, verdict codes, and
196
264
  manifest format.
197
265
 
198
- The candidate's restore audit records counts and transaction associations rather
266
+ Restore audit records counts and transaction associations rather
199
267
  than duplicate paths/error text. CLI results and recovery manifests still
200
268
  contain the exact data needed to inspect and restore; a failed CLI result
201
269
  must still be checked against the filesystem and preservation attempts.