@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.
- package/README.md +28 -10
- package/README.zh-CN.md +24 -10
- package/adapters/INTEGRATION.md +6 -0
- package/adapters/mcp/__init__.py +1 -0
- package/adapters/mcp/operations.py +174 -0
- package/adapters/mcp/requirements.txt +3 -0
- package/adapters/mcp/server.py +126 -0
- package/core/admission.py +388 -0
- package/core/audit.py +1 -1
- package/core/classifier.py +2 -1
- package/core/cleanup.py +297 -0
- package/core/delete_config.py +153 -0
- package/core/policy.py +35 -7
- package/core/recovery.py +10 -0
- package/docs/README.md +14 -9
- package/docs/design/architecture.md +12 -5
- package/docs/design/compatibility.md +181 -7
- package/docs/design/threat-model.md +53 -1
- package/docs/guides/cleanup-plan.md +227 -0
- package/docs/guides/deletion-limits.md +150 -0
- package/docs/guides/getting-started.md +25 -12
- package/docs/guides/harness-capabilities.md +19 -4
- package/docs/guides/mcp.md +293 -0
- package/docs/history/friction.md +99 -1
- package/docs/releases/release-notes-0.2.7.md +217 -0
- package/docs/releases/unreleased.md +139 -5
- package/docs/reports/test-report-dsh-paired-lab.md +1 -1
- package/docs/reports/test-report-kimi-code-block.md +1 -1
- package/package.json +3 -1
- package/skills/delete-guard/SKILL.md +69 -1
- package/skills/delete-guard/references/policy.md +66 -3
- package/skills/delete-guard/scripts/check.py +39 -9
- package/skills/delete-guard/scripts/cleanup.py +164 -0
- package/skills/delete-guard/scripts/safe_delete.py +22 -4
- package/skills/delete-guard/scripts/status.py +77 -1
|
@@ -4,13 +4,21 @@ agent-guard's promise is recoverability. A promise is only as good as its
|
|
|
4
4
|
stability over time - this page states exactly what may change and what
|
|
5
5
|
may not, per release class.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
0.2.
|
|
7
|
+
This contract covers [0.2.7](../releases/release-notes-0.2.7.md). Use its exact
|
|
8
|
+
GitHub release and npm version links to confirm availability; a version in
|
|
9
|
+
source or a local tarball does not establish publication.
|
|
10
|
+
Earlier release [0.2.6](../releases/release-notes-0.2.6.md) carries cumulative
|
|
11
|
+
RC maintenance and the feedback/diagnostic additions below. The opt-in
|
|
12
|
+
prerelease [0.2.5-rc3](../releases/release-notes-0.2.5-rc3.md), earlier stable
|
|
13
|
+
0.2.5 and the
|
|
11
14
|
[0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1)
|
|
12
|
-
|
|
13
|
-
origin and preparation labels of changes introduced by
|
|
15
|
+
quarantine protection backport retain their separate artifacts. Versioned
|
|
16
|
+
sections retain the origin and preparation labels of changes introduced by
|
|
17
|
+
earlier releases.
|
|
18
|
+
|
|
19
|
+
The maintainer selected **0.2.7** for Cleanup Copilot, deletion admission and
|
|
20
|
+
optional MCP tools. The bounded versioning decision is recorded below; the
|
|
21
|
+
separate 0.3.0 plan remains paused.
|
|
14
22
|
|
|
15
23
|
RC3 publishes defensive research and an example around the existing four
|
|
16
24
|
zero-model controls. Experimental disclosure labels and private delegation
|
|
@@ -20,6 +28,106 @@ is introduced by the research documentation.
|
|
|
20
28
|
|
|
21
29
|
## The adapter contract (frozen surface)
|
|
22
30
|
|
|
31
|
+
<a id="local-mcp-tools-027-candidate"></a>
|
|
32
|
+
|
|
33
|
+
### Local MCP tools (0.2.7)
|
|
34
|
+
|
|
35
|
+
The checkout adds an optional local stdio MCP server with five explicit tools:
|
|
36
|
+
safe_delete, ordinary restore, transactions, status and GC-plan preview.
|
|
37
|
+
It invokes existing CLI operations without a shell, preserves policy/audit/
|
|
38
|
+
recovery semantics and binds workspace/session identity at trusted startup.
|
|
39
|
+
Tool calls cannot select a new workspace, session, environment or quarantine.
|
|
40
|
+
`--session` selects both saved CLI authorization mode and deletion budget;
|
|
41
|
+
omission uses legacy CLI state and the shared default bucket. Reusing saved
|
|
42
|
+
state requires matching workspace, quarantine and session. Native host-session
|
|
43
|
+
restrictions/in-memory veto are not inherited without a trusted bridge.
|
|
44
|
+
Quarantine deletion, force restore, GC execution, budget reset and Cleanup
|
|
45
|
+
approval are not exposed. Existing CLI interfaces remain available separately.
|
|
46
|
+
|
|
47
|
+
The optional `mcp==2.3.0` Python SDK and its transitive dependencies install
|
|
48
|
+
into a separate environment; Core/CLI still has no third-party Python
|
|
49
|
+
requirement. This interface is included in 0.2.7 and is absent from published
|
|
50
|
+
0.2.6. It does not resume 0.3.0. It is a cooperative tool interface, not expanded
|
|
51
|
+
native interception. Existing host-version evidence and doctor scope do not
|
|
52
|
+
automatically cover MCP. On the 2026-10-28 frozen candidate, the first local
|
|
53
|
+
full run completed 1123 Python cases with one existing observer-startup error
|
|
54
|
+
and did not run Node; its cause remains undetermined. The second full run
|
|
55
|
+
passed 1123 Python cases and both Node groups in 1143.435 seconds, with no
|
|
56
|
+
failures, errors, skips or timeouts. Neither invoked npm directly or changed
|
|
57
|
+
the runtime/tests. A 154-file offline installation and three real Kimi 2.3.0
|
|
58
|
+
native-MCP trials passed; Claude/Cursor/Codex setup examples remain docs-only.
|
|
59
|
+
Without the optional SDK, seven protocol tests skip. The added SDK-backed
|
|
60
|
+
Python 3.10/3.13 CI job had no remote execution at the 2026-10-29 local
|
|
61
|
+
preparation checkpoint. See
|
|
62
|
+
[setup, full failure history and platform/tool limits](../guides/mcp.md).
|
|
63
|
+
Those measurements predate the 0.2.7 version/document alignment and are not
|
|
64
|
+
acceptance of the final versioned artifact. The subsequent 219-file 0.2.7
|
|
65
|
+
candidate passed 1129 Python cases and both Node groups in 1194.265 seconds,
|
|
66
|
+
with no failures, errors, skips, timeouts or automatic retries. Its 155-file
|
|
67
|
+
offline package passed 12 CLI entry-point and installed MCP checks, including
|
|
68
|
+
`serverInfo.version == 0.2.7`. Local release-gate checks passed; that local
|
|
69
|
+
preparation checkpoint did not include final-commit remote CI or publication.
|
|
70
|
+
No additional real-model trial was run. See
|
|
71
|
+
the [versioned validation record](../releases/release-notes-0.2.7.md#validation-status).
|
|
72
|
+
|
|
73
|
+
<a id="deletion-admission-limits-027-candidate"></a>
|
|
74
|
+
|
|
75
|
+
### Deletion admission limits (0.2.7)
|
|
76
|
+
|
|
77
|
+
The current checkout adds shared deletion configuration, persistent
|
|
78
|
+
per-session admission budgets, rate/repeat limits and quarantine capacity
|
|
79
|
+
checks. `.agent-guard/delete-policy.json` is optional; invalid configuration
|
|
80
|
+
or state fails closed. Configuration paths and the new quarantine
|
|
81
|
+
`admission.json`, temporary state and `admission.lock` are protected. Existing
|
|
82
|
+
recovery manifests and transaction strategies are retained without migration.
|
|
83
|
+
|
|
84
|
+
New reason codes are `BLOCK_DELETE_CONFIG_INVALID`, `BLOCK_DELETE_PROTECTED`,
|
|
85
|
+
`BLOCK_DELETE_LIMIT`, `BLOCK_DELETE_RATE`, `BLOCK_DELETE_REPEAT`,
|
|
86
|
+
`BLOCK_DELETE_BATCH_CONFIRM` and `BLOCK_DELETE_STATE_INVALID`. Decision classes
|
|
87
|
+
and `check.py` exit codes retain their contracts. Limits are applied at
|
|
88
|
+
execution admission; an earlier advisory assessment is not a capacity grant.
|
|
89
|
+
Covered automatic compensation/artifact paths can newly BLOCK when a
|
|
90
|
+
configured limit is reached. The general versioning promises below classify
|
|
91
|
+
these as minor safety changes. The maintainer selected 0.2.7 for these bounded
|
|
92
|
+
additions as an explicit exception recorded below, not as a change shipped
|
|
93
|
+
in 0.2.6 or a general permission to change policy in patch releases. The
|
|
94
|
+
separate 0.3.0 plan remains paused.
|
|
95
|
+
|
|
96
|
+
Cleanup retains plan schema version 1 and terminal-confirmed execution, then
|
|
97
|
+
issues metadata/session/configuration-bound, ten-minute approval for each
|
|
98
|
+
selected path once. Covered automatic large-delete checks BLOCK with Cleanup guidance;
|
|
99
|
+
there is no new host ASK/resume protocol. `status.py --reset-delete-budget`
|
|
100
|
+
adds explicit interactive reset of the current bucket, not capacity or GC.
|
|
101
|
+
Existing compound-command ASK and Git SNAPSHOT paths remain outside the new
|
|
102
|
+
budget. Normal restore, explicit GC and unprotected quarantine payload
|
|
103
|
+
housekeeping remain exempt; configuration/control-path protection still applies.
|
|
104
|
+
Same-UID state remains advisory; accounting is logical admitted work, not an
|
|
105
|
+
OS quota. New Core bytes change doctor fingerprints. The 2026-10-28 public
|
|
106
|
+
runtime passed three independent 1090-case Python plus two-Node-group runs,
|
|
107
|
+
an offline 149-file package check and three real Kimi 2.3.0 root-Bash scenarios.
|
|
108
|
+
These local POSIX results do not establish new platform or tool coverage;
|
|
109
|
+
previous Cleanup and release evidence keeps its original scope. See
|
|
110
|
+
[defaults, accounting and recovery](../guides/deletion-limits.md).
|
|
111
|
+
|
|
112
|
+
<a id="cleanup-copilot-027-candidate"></a>
|
|
113
|
+
|
|
114
|
+
### Cleanup Copilot (0.2.7)
|
|
115
|
+
|
|
116
|
+
The checkout adds `core.cleanup` and `agent-guard-cleanup` with read-only
|
|
117
|
+
planning, categorized candidates and explicit terminal-confirmed selection.
|
|
118
|
+
Execution delegates to the existing safe_delete CLI one concrete target at a
|
|
119
|
+
time. Plan JSON has its own `schema_version: 1`; it is not a new Decision
|
|
120
|
+
Protocol surface. The initial Cleanup-only checkpoint retained existing
|
|
121
|
+
deletion policy; the subsequent admission changes are described above.
|
|
122
|
+
Recovery formats, explicit GC and native adapter tools retain their contracts.
|
|
123
|
+
Cleanup itself adds no third-party Core dependency or configuration migration.
|
|
124
|
+
This feature is included in 0.2.7 and is absent from the published 0.2.6 package.
|
|
125
|
+
|
|
126
|
+
The new Core module and package metadata change doctor runtime fingerprints.
|
|
127
|
+
An old baseline can become `DRIFTED`; it is not automatically replaced.
|
|
128
|
+
See [the CLI contract](../guides/cleanup-plan.md) for confirmation, partial
|
|
129
|
+
execution, output privacy, scan limits and the existing concurrency boundary.
|
|
130
|
+
|
|
23
131
|
<a id="unreleased-feedback-and-diagnostic-maintenance"></a>
|
|
24
132
|
|
|
25
133
|
### 0.2.6 feedback and diagnostic maintenance
|
|
@@ -125,6 +233,68 @@ While the major version is `0`:
|
|
|
125
233
|
| check.py CLI flags removed or re-semanticized | major + MIGRATION.md |
|
|
126
234
|
| Default policy verdict changes for an existing shape | minor + entry in docs/history/friction.md |
|
|
127
235
|
|
|
236
|
+
<a id="027-candidate-bounded-maintainer-selected-exception"></a>
|
|
237
|
+
|
|
238
|
+
### 0.2.7: bounded maintainer-selected exception
|
|
239
|
+
|
|
240
|
+
The maintainer explicitly selected 0.2.7 for the completed Cleanup Copilot,
|
|
241
|
+
deletion-admission hardening and optional local MCP adapter. This version
|
|
242
|
+
is a bounded exception to the general minor-release rules above; the older
|
|
243
|
+
0.2.4, 0.2.5 and 0.2.6 exceptions do not automatically authorize it. It does
|
|
244
|
+
not relax those rules for other patch releases or resume the 0.3.0 plan.
|
|
245
|
+
|
|
246
|
+
The upgrade-visible changes are explicit:
|
|
247
|
+
|
|
248
|
+
- Covered automated deletion/compensation paths now enforce persistent
|
|
249
|
+
session byte/entry budgets, rate/repeated-target-set limits and quarantine
|
|
250
|
+
admission capacity. Regenerable direct deletion also consumes applicable
|
|
251
|
+
budgets. Failed admitted operations and restores do not refund them.
|
|
252
|
+
- Ordinary large batches now BLOCK with Cleanup guidance before covered
|
|
253
|
+
compensation; reviewed terminal-confirmed Cleanup provides a ten-minute,
|
|
254
|
+
per-path approval for that gate only. It cannot bypass other limits.
|
|
255
|
+
- Optional deletion configuration and configured protected paths precede
|
|
256
|
+
artifact/housekeeping exemptions. Invalid configuration or unavailable
|
|
257
|
+
admission state refuses new covered deletion instead of silently disabling
|
|
258
|
+
the checks. The configuration directory and admission controls are protected.
|
|
259
|
+
- Seven additive reason codes are introduced: `BLOCK_DELETE_CONFIG_INVALID`,
|
|
260
|
+
`BLOCK_DELETE_PROTECTED`, `BLOCK_DELETE_LIMIT`, `BLOCK_DELETE_RATE`,
|
|
261
|
+
`BLOCK_DELETE_REPEAT`, `BLOCK_DELETE_BATCH_CONFIRM` and
|
|
262
|
+
`BLOCK_DELETE_STATE_INVALID`. Existing code names, decision classes,
|
|
263
|
+
check exit codes, recovery manifests and transaction strategies retain
|
|
264
|
+
their meanings.
|
|
265
|
+
- Cleanup adds explicit plan/selection/terminal confirmation; optional MCP
|
|
266
|
+
adds a separate stdio tool interface and SDK environment, not automatic
|
|
267
|
+
interception or a new host ASK/resume protocol.
|
|
268
|
+
|
|
269
|
+
Default limits are a 5-GiB/100000-entry quarantine admission ceiling,
|
|
270
|
+
1-GiB/10000-entry cumulative session budget, 60 operations per 60 seconds,
|
|
271
|
+
five admissions of the same target set per window, and batch review above
|
|
272
|
+
256 MiB or 1000 filesystem entries. These are logical admission figures,
|
|
273
|
+
including directory metadata and conservative hardlink counting, not an OS
|
|
274
|
+
disk quota. See the [limit guide](../guides/deletion-limits.md) for fixed
|
|
275
|
+
inventory bounds and configuration semantics.
|
|
276
|
+
|
|
277
|
+
Normal restore, explicit GC and unprotected quarantine payload housekeeping
|
|
278
|
+
retain their exemptions; existing compound ASK and Git SNAPSHOT paths are
|
|
279
|
+
outside the new budget. Capacity pressure never authorizes automatic GC or
|
|
280
|
+
a permanent-delete fallback. Operators should inspect status and the stated
|
|
281
|
+
reason, review a fresh Cleanup plan for a batch refusal, or explicitly reset
|
|
282
|
+
the current budget with an interactive `RESET` only after investigating the
|
|
283
|
+
caller. Protection/configuration failures require preserving evidence and
|
|
284
|
+
correcting the actual issue, not removing state or changing identity.
|
|
285
|
+
|
|
286
|
+
The changed existing shapes are recorded in
|
|
287
|
+
[F32](../history/friction.md#f32-deletion-admission),
|
|
288
|
+
[F33](../history/friction.md#f33-batch-confirmation) and
|
|
289
|
+
[F34](../history/friction.md#f34-deletion-protection).
|
|
290
|
+
The [0.2.7 version notes](../releases/release-notes-0.2.7.md) describe scope
|
|
291
|
+
and upgrade impact, including the passing local 1129-case/two-Node-group and
|
|
292
|
+
155-file versioned-package checks. The 2026-10-29 local preparation checkpoint
|
|
293
|
+
did not include remote CI or publication; the earlier 1090/1123-case and
|
|
294
|
+
real-Kimi evidence keeps its original scope.
|
|
295
|
+
No legal hold, directory retention or deletion-certificate capability is
|
|
296
|
+
introduced by this version.
|
|
297
|
+
|
|
128
298
|
### 0.2.4 maintenance patch exception
|
|
129
299
|
|
|
130
300
|
For this release, the maintainer explicitly selected `0.2.4` for the recovery
|
|
@@ -357,7 +527,8 @@ projection is described above; it does not rewrite manifests or old log bytes.
|
|
|
357
527
|
|
|
358
528
|
A changed default verdict for an existing shape is a **minor** release and
|
|
359
529
|
requires an entry in [friction.md](../history/friction.md) - never a silent behaviour
|
|
360
|
-
shift. The bounded 0.2.4
|
|
530
|
+
shift. The bounded 0.2.4, 0.2.5-rc1 and 0.2.7 exceptions
|
|
531
|
+
are recorded above. Additive reason codes
|
|
361
532
|
are listed above; this table is for shapes
|
|
362
533
|
whose *existing* verdict moved.
|
|
363
534
|
|
|
@@ -370,6 +541,9 @@ whose *existing* verdict moved.
|
|
|
370
541
|
| `git reset --hard [ref]` with untracked/ignored or quarantine collisions | Tracked-only `SNAPSHOT` could proceed | `BLOCK` / `BLOCK_GIT_RESET_COLLISION` | Stash does not preserve the colliding content (0.2.4 maintenance exception, F24) |
|
|
371
542
|
| Hard reset with uncertain preflight or unsupported compound/wrapper context | Could proceed or ask despite incomplete coverage | `BLOCK_UNDETERMINABLE_EFFECT` before compensation | Snapshot and preflight must describe the actual Git context (F24) |
|
|
372
543
|
| Quarantine root/control paths, protected metadata inside trash, or an in-workspace storage parent | Could be allowed as housekeeping or regenerable content | `BLOCK_PROTECTED_PATH` | Recovery/state evidence protection precedes housekeeping (introduced in 0.2.5-rc1, F26) |
|
|
544
|
+
| Covered deletion/compensation after session, rate, repeated-target-set or quarantine admission limits are reached | Could continue through existing relocation or artifact policy | `BLOCK_DELETE_LIMIT`, `BLOCK_DELETE_RATE` or `BLOCK_DELETE_REPEAT` | Persistent admission suppresses repeated deletion and storage growth (0.2.7 exception, F32) |
|
|
545
|
+
| Covered automated request above the batch threshold, or changed/expired Cleanup approval | Could compensate or directly delete under existing policy | `BLOCK_DELETE_BATCH_CONFIRM` | Review a fresh plan and confirm selected paths through Cleanup; approval lifts only this gate (F33) |
|
|
546
|
+
| Configured protected paths/configuration directory, malformed deletion policy or unusable admission state | Could follow ordinary artifact/relocation policy without these checks | `BLOCK_DELETE_PROTECTED`, `BLOCK_DELETE_CONFIG_INVALID` or `BLOCK_DELETE_STATE_INVALID` | Protection and usable admission evidence precede covered execution; no silent bypass (F34) |
|
|
373
547
|
|
|
374
548
|
Unchanged on purpose: a genuine compensation fault (`git stash create`
|
|
375
549
|
failing, a relocation that does not cover every target, an audit intent
|
|
@@ -17,6 +17,12 @@ bypass. Therefore:
|
|
|
17
17
|
- You must NOT claim: sandboxing, containment of malicious agents,
|
|
18
18
|
prevention of determined bypass.
|
|
19
19
|
|
|
20
|
+
Version **0.2.7** adds the bounded deletion-admission and optional MCP surfaces
|
|
21
|
+
below. Confirm package availability through the exact GitHub release and npm
|
|
22
|
+
version links in the [version notes](../releases/release-notes-0.2.7.md).
|
|
23
|
+
This version does not add legal hold,
|
|
24
|
+
directory retention or deletion certificates, or resume the 0.3.0 plan.
|
|
25
|
+
|
|
20
26
|
## Assets
|
|
21
27
|
|
|
22
28
|
1. User data inside the workspace (tracked, untracked, ignored).
|
|
@@ -34,7 +40,53 @@ bypass. Therefore:
|
|
|
34
40
|
| 5 | Symlink confusion (delete link vs target, trailing slash dereference) | Lexical boundary analysis; link relocation preserves the link; realpath recorded | Low |
|
|
35
41
|
| 6 | TOCTOU between classification and execution | Checks and moves are not atomic. Native hooks run Core before handing control back to host execution; there is no promised maximum gap | Concurrent changes can invalidate facts or affect later execution. Atomic isolation remains unimplemented |
|
|
36
42
|
| 7 | Destructive restore | Relocation destinations and sources are checked against the workspace and their quarantine transaction. IDs and directory locations are validated; leaf symlinks retain their semantics. Human `--force` preserves an occupant through a separate relocation transaction before replacement; failed preservation stops that item | Checks and moves are not atomic against concurrent changes. Cross-filesystem failures may leave a partial destination or backup; inspect the filesystem and reported transaction IDs. Preserved versions add storage use and follow existing explicit GC |
|
|
37
|
-
| 8 | Quarantine bloat turns `.agent-trash` into a liability (exfil via packaging, disk exhaustion) | Existing `.gitignore` or `.git/info/exclude`;
|
|
43
|
+
| 8 | Quarantine bloat turns `.agent-trash` into a liability (exfil via packaging, disk exhaustion) | Existing `.gitignore` or `.git/info/exclude`; size/status and explicit GC. Version 0.2.7 adds cross-process capacity admission, persistent session budgets, rate/repeat limits and confirmed large batches | Logical admission is not an OS quota. Audit, directory metadata and unrelated writers can still grow storage; failures/restores do not refund session charges; GC stays explicit. Same-UID configuration/state/session changes remain possible |
|
|
44
|
+
| 9 | Agent deletes configured evidence or resets its own deletion budget | Shared protection in 0.2.7 covers configured paths and ancestors before artifact/housekeeping exemptions; configuration and admission control files are protected. CLI budget reset requires terminal acknowledgement | Portable protection and TTY are not independent authority against same-UID processes; no authenticated human guarantee |
|
|
45
|
+
|
|
46
|
+
The 0.2.7 admission rules are described in the
|
|
47
|
+
[deletion limits guide](../guides/deletion-limits.md), including measured
|
|
48
|
+
three-run, package and real Kimi validation and its platform/tool limits.
|
|
49
|
+
The published 0.2.6 baseline has only the existing soft retention/GC mechanism.
|
|
50
|
+
|
|
51
|
+
## Optional local MCP boundary
|
|
52
|
+
|
|
53
|
+
The 0.2.7 [MCP adapter](../guides/mcp.md) offers explicit tools under one
|
|
54
|
+
startup-bound workspace and stable budget identity. It reuses the CLI policy,
|
|
55
|
+
audit and recovery paths; tool arguments cannot change the binding or enable
|
|
56
|
+
force restore, GC execution, budget reset or Cleanup approval. Safe-delete
|
|
57
|
+
quarantine targets are refused to keep that API from becoming a permanent-GC
|
|
58
|
+
shortcut. Tool annotations and client approval settings are hints, not server
|
|
59
|
+
authorization or authenticated human identity.
|
|
60
|
+
Startup session selection controls both existing CLI authorization mode and
|
|
61
|
+
deletion budget; omission uses legacy CLI state and the shared default bucket.
|
|
62
|
+
Saved restrictions are reused only with the same workspace, quarantine and
|
|
63
|
+
session. The caller's native-session restrictions or in-memory veto are not
|
|
64
|
+
automatically transferred; those require trusted host-side bridging.
|
|
65
|
+
|
|
66
|
+
This service does not intercept shell/script/editor operations that bypass
|
|
67
|
+
its tools. Same-UID processes can still edit state or launch another service.
|
|
68
|
+
Client cancellation, disconnects and timeouts do not prove rollback or lack
|
|
69
|
+
of mutation; inspect recovery transactions before retrying. Results may
|
|
70
|
+
contain local paths and metadata and are not a general disclosure-sanitization
|
|
71
|
+
channel. The optional SDK adds its own dependency surface; a local stdio
|
|
72
|
+
server exposes no network listener.
|
|
73
|
+
|
|
74
|
+
The local 2026-10-28 candidate's first full run had one unresolved observer
|
|
75
|
+
READY-startup error; the second passed 1123 Python cases and both Node groups
|
|
76
|
+
without failures, errors, skips or timeouts. A 154-file offline installation
|
|
77
|
+
and three real Kimi 2.3.0 root-MCP trials passed. These observations do not
|
|
78
|
+
establish a timeout fix, remote-CI success, native Windows/macOS/shared-storage
|
|
79
|
+
compatibility or live Claude/Cursor/Codex support. See the guide for the full
|
|
80
|
+
failure history, optional-SDK test skips and measured scope; older hook and
|
|
81
|
+
release evidence remains separate.
|
|
82
|
+
Those are pre-version-alignment observations. The subsequent 0.2.7 candidate
|
|
83
|
+
passed 1129 Python cases and both Node groups without failures, errors, skips
|
|
84
|
+
or timeouts; its 155-file offline package passed installed MCP checks with
|
|
85
|
+
matching 0.2.7 service identity. See the
|
|
86
|
+
[versioned validation record](../releases/release-notes-0.2.7.md#validation-status).
|
|
87
|
+
This is local protocol/package evidence, with no new real-model trial or
|
|
88
|
+
expanded host/platform coverage. The 2026-10-29 local preparation checkpoint
|
|
89
|
+
did not include remote CI or publication.
|
|
38
90
|
|
|
39
91
|
## guard-lab diagnostic boundary
|
|
40
92
|
|
|
@@ -0,0 +1,227 @@
|
|
|
1
|
+
# Cleanup Copilot / 工作区清理计划
|
|
2
|
+
|
|
3
|
+
Cleanup Copilot is introduced in **0.2.7** and is absent from 0.2.6. Run the
|
|
4
|
+
Python script from the selected package or reviewed checkout; the package
|
|
5
|
+
also exposes `agent-guard-cleanup`. The shared
|
|
6
|
+
[deletion admission rules](deletion-limits.md) also apply when executing it.
|
|
7
|
+
See the [0.2.7 notes](../releases/release-notes-0.2.7.md) for upgrade effects,
|
|
8
|
+
versioned validation and exact-version availability checks. Source/package
|
|
9
|
+
metadata alone does not establish publication.
|
|
10
|
+
|
|
11
|
+
Cleanup Copilot scans workspace metadata and proposes concrete cleanup
|
|
12
|
+
targets. The default command writes no files, audit records, quarantine
|
|
13
|
+
layout or Git exclude rules. It also suppresses project bytecode creation.
|
|
14
|
+
Planning does not call `safe_delete --dry-run`, whose metadata side effects
|
|
15
|
+
remain documented in the [policy reference](../../skills/delete-guard/references/policy.md#assessment-and-dry-run-side-effects).
|
|
16
|
+
|
|
17
|
+
## Review a plan
|
|
18
|
+
|
|
19
|
+
From the intended workspace, run:
|
|
20
|
+
|
|
21
|
+
```sh
|
|
22
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/cleanup.py
|
|
23
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/cleanup.py --json
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
`--root /absolute/path/to/workspace` explicitly chooses the workspace
|
|
27
|
+
boundary. Otherwise the command uses the existing workspace discovery and
|
|
28
|
+
`AGENT_GUARD_WORKSPACE` setting. Existing trash, session mode and artifact
|
|
29
|
+
settings and shared deletion configuration are respected. Git supplies ignore/tracking facts; without usable
|
|
30
|
+
Git facts no target is proposed as regenerable.
|
|
31
|
+
|
|
32
|
+
| Category | Evidence | Default handling |
|
|
33
|
+
|---|---|---|
|
|
34
|
+
| 可再生 / `regenerable` | Git-ignored, matches an existing artifact pattern, and no tracked descendants | Selectable if existing policy permits; inspect `effect` |
|
|
35
|
+
| 明确废弃 / `discarded` | Caller explicitly declared the path/subtree with `--discard PATH` | Selectable if existing policy permits; ordinary content goes to quarantine |
|
|
36
|
+
| 不确定 / `uncertain` | No sufficient regeneration or discard evidence, or incomplete scan | Review only |
|
|
37
|
+
| 受保护 / `protected` | `.git`, `.internal`, quarantine names/boundaries, explicit protected paths or special entries | Keep; do not traverse |
|
|
38
|
+
|
|
39
|
+
Age, being untracked, or being ignored alone never means discarded.
|
|
40
|
+
Declare known disposable paths and additional evidence/backup roots explicitly:
|
|
41
|
+
|
|
42
|
+
```sh
|
|
43
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/cleanup.py \
|
|
44
|
+
--discard old-output --protect backups --protect evidence
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
These flags are invocation options, not persisted cleanup rules. Shared
|
|
48
|
+
`.agent-guard/delete-policy.json` protection is also applied, and its directory
|
|
49
|
+
is always protected. Discard
|
|
50
|
+
declarations must exist and stay within the workspace; the workspace root
|
|
51
|
+
cannot be declared discarded. Protection overrides discard declarations and
|
|
52
|
+
artifact names. Protected descendants prevent selection of their ancestor;
|
|
53
|
+
eligible siblings may remain visible as individual entries. Existing Core
|
|
54
|
+
protection can prune an entire parent containing a recovery bucket.
|
|
55
|
+
|
|
56
|
+
Declared protection covers both the supplied path and its physical location
|
|
57
|
+
inside the workspace. A newly discovered nested protected symlink whose
|
|
58
|
+
physical location was not declared makes the plan incomplete with
|
|
59
|
+
`PROTECTED_ALIAS_REQUIRES_EXPLICIT_PROTECT`. Repeat the plan with
|
|
60
|
+
`--protect` naming that link before selecting other targets.
|
|
61
|
+
|
|
62
|
+
Unknown subtrees collapse into review rows unless generated, discarded or
|
|
63
|
+
protected descendants need to be shown. Candidate directories and their
|
|
64
|
+
children are not offered as overlapping selections.
|
|
65
|
+
|
|
66
|
+
## Confirm and execute
|
|
67
|
+
|
|
68
|
+
Copy the plan's full `plan_id`, select exact rows marked `selectable`, and
|
|
69
|
+
repeat the same root, discard, protect and scan-limit options:
|
|
70
|
+
|
|
71
|
+
```sh
|
|
72
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/cleanup.py \
|
|
73
|
+
--discard old-output --protect backups --protect evidence \
|
|
74
|
+
--execute --plan-id '<plan-id>' --select build --select old-output
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
The example assumes `build` and `old-output` actually appear as selectable
|
|
78
|
+
entries in your reviewed plan. Paths passed to `--select` are literal,
|
|
79
|
+
workspace-relative paths, not patterns. Quote spaces and use `--select=-name`
|
|
80
|
+
for a leading dash.
|
|
81
|
+
|
|
82
|
+
The command checks the current plan against the supplied ID, prints the
|
|
83
|
+
selected paths, sizes and effects, then asks the operator to type
|
|
84
|
+
`EXECUTE` in an interactive terminal. Any other answer or EOF
|
|
85
|
+
cancels without creating guard metadata. Piped/noninteractive execution is
|
|
86
|
+
refused; there is no `--yes` flag. Agents may propose a plan and explain it;
|
|
87
|
+
they must leave the confirmation response to the human operator. No new
|
|
88
|
+
native host tool or host approval integration is supplied.
|
|
89
|
+
|
|
90
|
+
After confirmation, the command rescans and checks the plan again before
|
|
91
|
+
the first mutation. The ID covers workspace, options, metadata/membership,
|
|
92
|
+
policy projections, mode, artifact settings and deletion configuration.
|
|
93
|
+
Changed plans require fresh review. It is not a content hash or an atomic filesystem snapshot; concurrent
|
|
94
|
+
changes during execution retain the existing Core's TOCTOU limits. Terminal
|
|
95
|
+
acknowledgement is a workflow check, not proof of human identity against a
|
|
96
|
+
same-UID process. See the [threat model](../design/threat-model.md).
|
|
97
|
+
|
|
98
|
+
The subsequent deletion hardening creates a ten-minute approval only after
|
|
99
|
+
this confirmation and rescan. It binds exact selected paths and their measured
|
|
100
|
+
metadata to the current session and deletion configuration; each path is
|
|
101
|
+
consumed once before execution. Changed, expired or replayed approval fails.
|
|
102
|
+
Approval satisfies the batch-review gate but does not bypass capacity,
|
|
103
|
+
session budget, rate/repeat rules or protected paths. Ordinary large deletes
|
|
104
|
+
through `check --enforce` or `safe_delete` BLOCK with Cleanup guidance rather
|
|
105
|
+
than entering a new host ASK flow. This gate covers automated deletion paths;
|
|
106
|
+
existing compound ASK, Git snapshots and quarantine housekeeping retain their
|
|
107
|
+
separate rules. See [deletion limits](deletion-limits.md).
|
|
108
|
+
|
|
109
|
+
Execution invokes existing `safe_delete` once per concrete target:
|
|
110
|
+
|
|
111
|
+
- `effect: delete`: current policy will physically delete the target. This
|
|
112
|
+
commonly applies to ignored build outputs. There is no recovery copy.
|
|
113
|
+
- `effect: quarantine`: current policy will relocate content and return a
|
|
114
|
+
transaction ID. Data remains on disk. Use the existing restore or explicit
|
|
115
|
+
GC workflow in the [feedback guide](recovery-feedback.md).
|
|
116
|
+
- `effect: blocked`, `keep` or `review`: not selectable. Existing mode and
|
|
117
|
+
boundary refusals cannot be overridden by confirmation.
|
|
118
|
+
|
|
119
|
+
An explicit discard declaration does not force a particular deletion
|
|
120
|
+
method; the actual `effect` and `policy_code` come from existing policy.
|
|
121
|
+
Separate invocations preserve each row's effect when a selection mixes
|
|
122
|
+
generated and ordinary targets. On a child failure, execution stops and
|
|
123
|
+
keeps earlier and partial transaction reports. Inspect those IDs before
|
|
124
|
+
retrying. No automatic purge or rollback runs.
|
|
125
|
+
|
|
126
|
+
## Sizes, limits and output
|
|
127
|
+
|
|
128
|
+
Sizes are logical file bytes, with hardlinks counted once per entry and per
|
|
129
|
+
category summary. Directory metadata is omitted; links use their own size
|
|
130
|
+
and directory links are not traversed. Protected subtree sizes are unknown.
|
|
131
|
+
Hardlinks shared across categories may appear in both category totals.
|
|
132
|
+
These values do not predict freed blocks, sparse-file allocation or storage
|
|
133
|
+
released by quarantine. Errors retain partial observations.
|
|
134
|
+
|
|
135
|
+
Execution admission measures directory metadata too and conservatively counts
|
|
136
|
+
hardlinks per filesystem entry. Its budget/capacity figures can therefore be
|
|
137
|
+
larger than these displayed plan sizes. A selectable plan is not a reservation
|
|
138
|
+
of capacity or session budget.
|
|
139
|
+
|
|
140
|
+
The default budget is 10,000 entries and depth 32 below the workspace.
|
|
141
|
+
`--max-entries` must be positive; `--max-depth` accepts 1–128. A reached limit,
|
|
142
|
+
unreadable subtree or observed directory mutation makes `complete: false`
|
|
143
|
+
and prevents execution. Increase the scope limits only after reviewing the
|
|
144
|
+
reported partial scan. Protected exclusions are part of the declared scan,
|
|
145
|
+
not incomplete traversal errors.
|
|
146
|
+
|
|
147
|
+
JSON uses `schema_version: 1`, a stable `plan_id`, `summary`, `entries`, scan
|
|
148
|
+
`errors`/`warnings`, options and workspace/trash context. Entry fields include
|
|
149
|
+
`path`, `category`, `size_bytes`, `size_complete`, `reason`, `selectable`,
|
|
150
|
+
`effect`, `policy_code` and an opaque metadata fingerprint. Paths remain
|
|
151
|
+
exact local paths and can be private; review output before sharing it.
|
|
152
|
+
Planning itself persists none of this output. Executing retains existing
|
|
153
|
+
safe_delete audit and recovery contracts.
|
|
154
|
+
|
|
155
|
+
When saving a plan, write it outside the scanned workspace or into a
|
|
156
|
+
protected subtree. Creating or updating an ordinary output file inside the
|
|
157
|
+
scan changes the workspace metadata and can invalidate the saved plan ID.
|
|
158
|
+
|
|
159
|
+
Exit 0 means a complete plan, cancellation, or completed execution. Exit 1
|
|
160
|
+
means an incomplete default scan. Exit 2 means invalid options, refusal or
|
|
161
|
+
stopped execution; inspect `reports` for partial effects.
|
|
162
|
+
|
|
163
|
+
Names unsupported by the existing concrete path API, including glob
|
|
164
|
+
characters, substitution syntax or trailing whitespace, remain blocked as
|
|
165
|
+
individual selections. Ordinary spaces and leading dashes are supported.
|
|
166
|
+
No rm wildcard rule, recovery format, GC policy or production dependency
|
|
167
|
+
changes. Adding the Core module and package command changes doctor runtime
|
|
168
|
+
fingerprints, so older baselines can become `DRIFTED`; review and validate
|
|
169
|
+
before writing a new baseline at a new path.
|
|
170
|
+
|
|
171
|
+
## 中文摘要
|
|
172
|
+
|
|
173
|
+
本功能自 0.2.7 加入。默认扫描只输出计划,不修改工作区;“明确废弃”仅来自
|
|
174
|
+
调用者显式声明,旧文件/未跟踪文件不会自动变为垃圾。执行必须提供计划 ID、选定
|
|
175
|
+
具体条目并由操作者在终端确认,确认后复查,再逐项走现有 safe_delete。普通文件
|
|
176
|
+
隔离后仍占空间,可再生产物符合现有规则时直接物理删除。保护项、不完整或过期的
|
|
177
|
+
计划不能执行;不提供自动清理或新的宿主原生工具。
|
|
178
|
+
|
|
179
|
+
## Validation scope
|
|
180
|
+
|
|
181
|
+
The following historical checkpoints used 0.2.6 package metadata. They do not
|
|
182
|
+
certify the versioned 0.2.7 artifact; its separate validation is tracked
|
|
183
|
+
in the [0.2.7 notes](../releases/release-notes-0.2.7.md).
|
|
184
|
+
|
|
185
|
+
On 2026-10-28, the subsequent shared configuration, admission limits and
|
|
186
|
+
operation-bound approvals passed three independent full runs on one frozen
|
|
187
|
+
public runtime: 1090 Python cases and both Node groups per run, in 1061.017,
|
|
188
|
+
1025.315 and 1042.145 seconds. There were no failures, errors, skips, timeouts
|
|
189
|
+
or automatic retries, and frozen source bytes remained unchanged. The
|
|
190
|
+
existing diagnostic collector preserved `npm test` scope and deadlines;
|
|
191
|
+
the npm command itself was not invoked.
|
|
192
|
+
|
|
193
|
+
The 149-file offline package passed installed CLI, real terminal confirmation,
|
|
194
|
+
mixed physical deletion/quarantine/restore, budget/reset, loop, capacity,
|
|
195
|
+
protection and compound-batch checks. Three real Kimi Code 2.3.0 root-Bash
|
|
196
|
+
scenarios passed: recoverable deletion, same-session budget refusal and
|
|
197
|
+
configured protection. Nine configured-route requests returned HTTP 200;
|
|
198
|
+
the loopback gateway's server-side model identity was not independently
|
|
199
|
+
authenticated. See [deletion limits](deletion-limits.md) for scope and exceptions.
|
|
200
|
+
Acceptance receipts were then updated in documentation without changing runtime
|
|
201
|
+
or tests. The following results retain the earlier Cleanup-only checkpoint.
|
|
202
|
+
|
|
203
|
+
On 2026-10-28, the Cleanup-only public runtime passed one continuous full-suite
|
|
204
|
+
run: 1012 Python cases and both Node groups in 979.997 seconds, within the
|
|
205
|
+
original 1800-second budget. There were no failures, errors, skips or
|
|
206
|
+
retries. The local environment was ARM64/PRoot POSIX with Python 3.13.5
|
|
207
|
+
and Node 22.23.4.
|
|
208
|
+
|
|
209
|
+
This run used the existing diagnostic unittest result collector and then
|
|
210
|
+
both Node commands, preserving the test scope, assertions and deadlines
|
|
211
|
+
from `npm test`. It did not invoke the npm command itself. An earlier
|
|
212
|
+
literal `npm test` run timed out after 653 logged completions; follow-up
|
|
213
|
+
checks covered the remaining cases. That timeout is retained, its cause
|
|
214
|
+
remains unresolved, and it did not recur during the continuous rerun.
|
|
215
|
+
|
|
216
|
+
Focused checks passed all 37 cleanup cases and 9 package-manifest cases.
|
|
217
|
+
An offline package installation verified 146 file contents, all 11 CLI
|
|
218
|
+
entry points, actual pseudo-terminal confirmation, physical artifact
|
|
219
|
+
removal, ordinary-file quarantine/restore and noninteractive refusal.
|
|
220
|
+
Planning also passed a write audit; cancelled/stale plans and protected
|
|
221
|
+
symlink paths have regression coverage. That earlier Cleanup-only checkpoint
|
|
222
|
+
made no external model calls.
|
|
223
|
+
|
|
224
|
+
Workspace-alias checks ran locally. Native macOS, native Windows, shared
|
|
225
|
+
Android storage and new host approval integrations were not exercised.
|
|
226
|
+
The existing release matrix and historical host reports retain their own
|
|
227
|
+
version/scope boundaries.
|