@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.
@@ -1,8 +1,205 @@
1
- # 0.2.7 changes and 0.2.6 maintenance history
1
+ # Unreleased changes and maintenance history
2
+
3
+ <a id="current-unreleased-scope"></a>
4
+
5
+ ## Current scope: 0.2.9
6
+
7
+ The maintainer selected **0.2.9** for the changes below. Confirm exact-version
8
+ availability through the [release notes](release-notes-0.2.9.md) before installation.
9
+ Cleanup Copilot and its observation tools remain part of **Delete-guard**.
10
+ The separate disclosure-authorization roadmap and commercial work stay paused.
11
+
12
+ | Area | Change | Entry |
13
+ |---|---|---|
14
+ | Directory inventory | Bounded overview, explicit-scope discovery and metadata measurement | [CLI workflow](../guides/cleanup-plan.md#directory-overview-and-measurement-unreleased) |
15
+ | MCP observations | `cleanup_discover` and `cleanup_measure`; partial data is distinct from a failed call | [Tool contract](../guides/mcp.md#cleanup-observations-unreleased) |
16
+ | Planning performance | Reuse ordinary-file metadata and batch Git facts within one plan | [Planner boundaries](../guides/cleanup-plan.md#review-a-plan) |
17
+ | Corpus regression | Define the normal text corpus by Git-index paths and current working-tree contents | [Contributor workflow](../../CONTRIBUTING.md) |
18
+
19
+ The default executable-plan workflow, original five MCP operations, deletion
20
+ policy, budgets and recovery formats retain their contracts. Overview and
21
+ measurement never grant execution permission. Use doctor and server from the
22
+ same installation; published 0.2.8 has five tools, this checkout has seven.
23
+ See the [latest local validation](#current-validation-checkpoint) before
24
+ interpreting historical counts or host evidence.
25
+
26
+ <a id="cleanup-directory-observations-and-mcp-unreleased"></a>
27
+
28
+ ## Cleanup directory observations and MCP (0.2.9)
29
+
30
+ Version 0.2.9 adds shared-Core directory discovery and selected-scope
31
+ measurement, exposed by `agent-guard-cleanup --discover|--measure` and the
32
+ MCP tools `cleanup_discover` / `cleanup_measure`. These additions are absent
33
+ from published 0.2.8. They remain under
34
+ Delete-guard's Cleanup Copilot, with no new production dependency or storage
35
+ migration.
36
+
37
+ Discovery groups runtime/cache hints, prioritizes cache/artifact path hints
38
+ within fixed limits, and records unexpanded areas. Explicit scopes continue
39
+ discovery under the same workspace. Measurement omits protected subtrees and
40
+ keeps unknown whole sizes distinct from observed bytes. All observations
41
+ remain nonselectable and produce no executable plan ID or approval; the
42
+ existing default plan and confirmed safe_delete workflow remain separate.
43
+
44
+ The MCP adapter returns valid partial observations with `ok: true` and
45
+ `partial: true`, preserving the CLI exit code and completeness details. The
46
+ original five tools retain their contracts. The source doctor expects seven
47
+ tools but still invokes only the original three read-only state queries.
48
+ Use doctor and server from the same installation.
49
+
50
+ See [CLI workflow and result fields](../guides/cleanup-plan.md#directory-overview-and-measurement-unreleased)
51
+ and [MCP partial-result semantics](../guides/mcp.md#cleanup-observations-unreleased).
52
+
53
+ <a id="cleanup-planning-performance-unreleased"></a>
54
+
55
+ ## Cleanup planning performance (0.2.9)
56
+
57
+ Version 0.2.9 reduces repeated ordinary-file path and metadata checks
58
+ and reuses batched Git facts when projecting candidate verdicts. Shared
59
+ decision rules retain their live execution entrypoint; deleting files still
60
+ checks current Git and protection settings. Scan limits, categories, plan
61
+ fingerprints, confirmation and deletion budgets keep their contracts.
62
+
63
+ This performance change is not part of the published 0.2.8 package. On its
64
+ own it changes no recognition rules or MCP tools; the separate observation
65
+ addition above supplies directory groups and read-only MCP entrypoints.
66
+ Neither coordinates application locks. See the [cleanup guide](../guides/cleanup-plan.md)
67
+ for planning and managed-cache boundaries. The earlier validation records
68
+ below retain their original versions and results.
69
+
70
+ <a id="repository-corpus-noise-regression-unreleased"></a>
71
+
72
+ ## Repository corpus noise regression (0.2.9)
73
+
74
+ The repository's normal-corpus test now reads current regular UTF-8 files
75
+ named by its own Git index. Tracked modifications and newly staged files are
76
+ included; untracked private adversarial experiments are outside this metric.
77
+ Git failures, a borrowed parent index and unreadable tracked files are not
78
+ silently accepted. Binary files and link targets are outside the text corpus.
79
+
80
+ This corrects the test's collection boundary without changing Exfil rules,
81
+ exemptions or private examples. Regressions check that unsafe tracked and new
82
+ staged content still fails, untracked examples still BLOCK when scanned
83
+ directly, and staging an example brings it into the corpus gate. New files
84
+ must be staged intentionally before this versioned-corpus pre-commit check;
85
+ it is not a whole-workspace safety scan. See the
86
+ [current validation](#current-validation-checkpoint); earlier failed
87
+ checkpoints remain recorded below.
88
+
89
+ ## Current validation checkpoint
90
+
91
+ Before the CI corrections below, the versioned 0.2.9 public candidate passed the literal `npm test`: 1197
92
+ Python cases and both Node groups, with no failures, errors or skips.
93
+ All 16 real MCP protocol/doctor/interruption cases executed with the existing
94
+ pinned SDK. The candidate's 227 public source files stayed unchanged during
95
+ the run. This is local candidate validation; remote CI and publication are
96
+ separate checks, available through the [0.2.9 notes](release-notes-0.2.9.md).
97
+
98
+ The first cross-version CI then exposed a test-fixture issue on Python 3.9
99
+ and 3.10: mocking `os.stat` did not inject the intended metadata error through
100
+ those versions' `Path.lstat` implementation. The fixture now injects at
101
+ `Path.lstat` and verifies that the fault was reached, retaining the original
102
+ error/incompleteness assertions. Further macOS logs exposed a preview fast
103
+ path that missed a configured recovery parent through a directory alias.
104
+ It now checks both recovery-path spellings before skipping classification;
105
+ a new alias regression reproduces the pre-fix failure. The HOME fixture uses
106
+ the scanner's physical path, and the read-only fixture disables detached Git
107
+ maintenance before its baseline commit. These corrections retain deletion
108
+ policy and live execution checks. The full run above keeps its original
109
+ checkpoint; subsequent validation uses 1198 public cases and is recorded
110
+ separately.
111
+
112
+ Before the version alignment, local `npm test` passed all 1504 Python cases (1197 in public
113
+ test modules and 307 existing private development cases) and both Node
114
+ groups, with the existing optional MCP SDK enabled. There were no failures,
115
+ errors, skips or automatic retries; the 214 frozen code/configuration inputs
116
+ remained unchanged. Eight new collection-boundary controls and direct scans
117
+ of the original eleven private samples confirm that the detector still BLOCKs
118
+ those samples. Exfil rules and the allowfile were not changed.
119
+
120
+ These are local working-tree results, not acceptance of the versioned
121
+ release or fresh remote CI. The source suite includes private development
122
+ cases absent from a public checkout; public-module and private counts are
123
+ listed separately. The subsequent Markdown consolidation changed no
124
+ production code or tests and did not repeat model trials. Versioned release
125
+ checks are recorded separately in the [0.2.9 notes](release-notes-0.2.9.md#validation).
126
+
127
+ Local checks include actual stdio discovery/measurement against a real
128
+ project and one bounded real Kimi Code inventory task in a synthetic
129
+ workspace (four model requests, three native MCP calls). The latter completed
130
+ scoped discovery and measurement, preserved unknown UV whole size and mixed
131
+ data uncertainty, and left fixture files unchanged. This is one host/task
132
+ sample, not general reliability, application-cache deletion safety or shell
133
+ interception evidence.
134
+
135
+ The overview remains bounded and may leave an incomplete frontier. Finding
136
+ registered roots does not establish a complete workspace scan. The model
137
+ trial's source/task boundaries remain separate from native shell interception
138
+ and application-cache deletion safety.
139
+
140
+ ### Earlier source checkpoints
141
+
142
+ At the earlier pre-corpus-fix checkpoint, the full local `npm test` run
143
+ completed 1496 Python cases (1189 in public test modules and 307 existing
144
+ private development cases), with one corpus
145
+ gate failure caused by existing private experiment files. The saved
146
+ pre-change view reproduced the same eleven hits; the then-current public-only
147
+ view passed that single gate. The two Node commands were then run separately
148
+ and passed. That original npm run remains recorded as failed; the public-only
149
+ gate check is not a second full-suite PASS. No Exfil exemption, production rule or
150
+ private fixture was changed to suppress it. The final 25 directory-group
151
+ controls and actual MCP/host checks passed; the earlier targeted run's
152
+ runpy-bootstrap fixture failure was corrected with its log retained.
153
+
154
+ These earlier results retain their failures and scope. They are not the
155
+ latest candidate's outcome; the successful follow-up run is recorded above.
156
+
157
+ <a id="028-development-and-earlier-maintenance-history"></a>
2
158
 
3
159
  <a id="unreleased-changes-and-026-maintenance-history"></a>
4
160
  <a id="027-candidate-changes-and-026-maintenance-history"></a>
5
161
 
162
+ <a id="mcp-diagnosis-and-reliability-maintenance-028-development"></a>
163
+
164
+ ## MCP diagnosis and reliability maintenance (0.2.8)
165
+
166
+ The maintainer selected **0.2.8** for an explicit `doctor.py mcp` path,
167
+ real-protocol response-loss checks and documentation. Stable installation
168
+ examples select this exact version; confirm its GitHub release and npm
169
+ availability through the [version notes](release-notes-0.2.8.md). The local
170
+ validation and remote CI checkpoints are recorded separately.
171
+
172
+ The doctor checks a selected Python/optional SDK, service handshake and
173
+ version, the five-tool set, workspace binding and read-only queries. It does
174
+ not call a model, change host configuration or delete/restore files. Its
175
+ version-1 diagnosis and exit codes are separate from the existing
176
+ Kimi/Claude doctor and Decision Protocol surfaces. A direct-service PASS keeps
177
+ host connection, model delivery and interception `UNVERIFIED`.
178
+
179
+ The interruption work covers client deadline, cancellation, stdin EOF and
180
+ service termination after a real deletion has committed but before a reply.
181
+ Checks examine transaction recoverability and persistent budget, without
182
+ assuming that losing a response rolled back the operation. This does not
183
+ prove arbitrary multi-file interruption atomicity. A separate full rerun passed
184
+ 1152 Python cases and both Node groups with no failures/errors/skips; local
185
+ 157-file package checks passed. The earlier full-run initialization timeout
186
+ and its unresolved cause remain recorded in the
187
+ [0.2.8 notes](release-notes-0.2.8.md#validation-status).
188
+
189
+ The five tools, default deletion policy, recovery format and budget semantics
190
+ retain their contracts. The SDK stays separately optional; the separate
191
+ 0.3.0 and commercial plans remain paused. See the
192
+ [MCP diagnosis and interruption guide](../guides/mcp.md#diagnose-a-local-service-028)
193
+ and this release's [bounded compatibility decision](../design/compatibility.md#028-diagnosis-maintenance-decision).
194
+
195
+ The guide also records later Codex 0.165.0 acceptance of the published 0.2.7
196
+ package: three native-client groups and three real-model tasks with 16 MCP
197
+ calls. That exact-version cooperative-MCP evidence is not 0.2.8 acceptance or
198
+ native-shell interception evidence. Earlier checkpoints below keep their
199
+ original versions, results and failure history.
200
+
201
+ ## 0.2.7 changes and 0.2.6 maintenance history
202
+
6
203
  The maintainer selected **0.2.7** for Cleanup Copilot, deletion admission and
7
204
  optional local MCP tools. Check its exact GitHub release and npm version
8
205
  through the [version notes](release-notes-0.2.7.md) before installing; a source
package/doctor.py CHANGED
@@ -17,6 +17,8 @@ import sys
17
17
  import tempfile
18
18
  from typing import Any, Optional
19
19
 
20
+ sys.dont_write_bytecode = True
21
+
20
22
  from core.dialects import resolve_dialect
21
23
 
22
24
 
@@ -747,7 +749,7 @@ def check_claude(config_path: Path, run_probe: bool = False) -> list[str]:
747
749
  return _diagnose("claude", config_path, run_probe).problems
748
750
 
749
751
 
750
- def main(argv: Optional[list[str]] = None) -> int:
752
+ def main(argv: Optional[list[str]] = None, *, _include_mcp=True) -> int:
751
753
  parser = argparse.ArgumentParser(description=__doc__)
752
754
  subcommands = parser.add_subparsers(dest="harness", required=True)
753
755
  kimi = subcommands.add_parser("kimi", help="check the local Kimi hook")
@@ -756,6 +758,15 @@ def main(argv: Optional[list[str]] = None) -> int:
756
758
  claude = subcommands.add_parser("claude", help="check a selected Claude settings file")
757
759
  claude.add_argument(
758
760
  "--config", help="Claude settings.json (defaults to .claude/settings.json in cwd)")
761
+ if _include_mcp:
762
+ mcp = subcommands.add_parser("mcp", help="diagnose an explicit local MCP server (no model call)")
763
+ mcp.add_argument("--python", default=sys.executable,
764
+ help="Python in the optional MCP SDK environment (default: current interpreter)")
765
+ mcp.add_argument("--workspace", required=True, help="existing workspace bound to the server")
766
+ mcp.add_argument("--server", help="trusted server.py path (default: this package's MCP server)")
767
+ mcp.add_argument("--timeout", type=int, default=30, metavar="SECONDS",
768
+ help="total diagnosis deadline, 5..120 seconds (default: 30)")
769
+ mcp.add_argument("--json", action="store_true", help="print the independent MCP diagnosis report")
759
770
  for command in (kimi, claude):
760
771
  command.add_argument(
761
772
  "--probe", action="store_true",
@@ -791,6 +802,19 @@ def main(argv: Optional[list[str]] = None) -> int:
791
802
  help="live sentinel timeout, 15..600 seconds (default: 180)",
792
803
  )
793
804
  args = parser.parse_args(argv)
805
+ if args.harness == "mcp":
806
+ if not args.python or "\0" in args.python:
807
+ parser.error("--python must name a nonempty interpreter")
808
+ if not 5 <= args.timeout <= 120:
809
+ parser.error("--timeout must be from 5 to 120 seconds")
810
+ from adapters.mcp.doctor import diagnose, render
811
+
812
+ report = diagnose(args.python, args.workspace, server=args.server, timeout=args.timeout)
813
+ if args.json:
814
+ print(json.dumps(report, ensure_ascii=False))
815
+ else:
816
+ print(render(report), end="")
817
+ return 0 if report["status"] == "PASS" else 1
794
818
  if args.write_baseline is not None and not args.probe:
795
819
  parser.error("--write-baseline requires --probe")
796
820
  if args.live_sentinel and args.write_baseline is not None:
package/live_sentinel.py CHANGED
@@ -332,7 +332,7 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
332
332
  arguments = list(sys.argv[1:] if argv is None else argv)
333
333
  if "--live-sentinel" not in arguments:
334
334
  arguments.append("--live-sentinel")
335
- return doctor_main(arguments)
335
+ return doctor_main(arguments, _include_mcp=False)
336
336
 
337
337
 
338
338
  if __name__ == "__main__":
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mokuyoaxis/agent-guard",
3
- "version": "0.2.7",
3
+ "version": "0.2.9",
4
4
  "description": "Harness-neutral reliability infrastructure for AI coding agents: recoverable destructive actions, disclosure checks, controlled synthetic behaviour experiments, and a shared Core with optional native adapters.",
5
5
  "type": "module",
6
6
  "engines": {
@@ -51,11 +51,37 @@ Globs passed to `safe_delete` are expanded explicitly before anything moves.
51
51
  That is why `safe_delete '*.log'` works while `rm *.log` is blocked: the
52
52
  guard refuses opaque target sets, not cleanup work.
53
53
 
54
+ <a id="read-only-cleanup-inventory-unreleased-checkout"></a>
55
+
56
+ ## Read-only cleanup inventory (0.2.9)
57
+
58
+ From a 0.2.9 installation or checkout, start a cleanup
59
+ investigation with a bounded directory overview:
60
+
61
+ ```bash
62
+ python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/cleanup.py --discover --json
63
+ python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/cleanup.py --measure --scope build --json
64
+ ```
65
+
66
+ Keep the same workspace root when selecting scopes. Use
67
+ `--discover --scope PATH` to inspect an unexpanded directory. Environment and managed-cache
68
+ labels are hints; all groups remain nonselectable. Unknown whole sizes stay
69
+ null, and a complete observed subset is not a complete workspace scan.
70
+ The corresponding MCP tools are `cleanup_discover` and `cleanup_measure`;
71
+ `ok: true, partial: true` is usable partial data, never execution permission.
72
+
73
+ These modes are absent from published 0.2.8. For that package, use its
74
+ existing plan workflow below. With the new modes, produce a separate reviewed
75
+ plan before any execution; `observation_id` cannot replace `plan_id`. Review
76
+ application-managed cache consistency separately. See
77
+ [observation limits](../../docs/guides/cleanup-plan.md#directory-overview-and-measurement-unreleased)
78
+ and [MCP semantics](../../docs/guides/mcp.md#cleanup-observations-unreleased).
79
+
54
80
  <a id="cleanup-proposals-027-candidate"></a>
55
81
 
56
82
  ## Cleanup proposals (0.2.7)
57
83
 
58
- When asked to investigate workspace cleanup, start with a read-only plan:
84
+ To propose concrete executable candidates, produce a separate read-only plan:
59
85
 
60
86
  ```bash
61
87
  python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/cleanup.py --json
@@ -22,6 +22,7 @@ import _bootstrap # noqa: F401
22
22
 
23
23
  from core import classifier, recovery
24
24
  from core.cleanup import DEFAULT_MAX_DEPTH, DEFAULT_MAX_ENTRIES, plan_cleanup, select_entries
25
+ from core.cleanup_groups import discover_groups, measure_groups
25
26
  from core.messages import print_gc_guidance
26
27
 
27
28
 
@@ -29,6 +30,26 @@ LABELS = {"regenerable": "可再生 / regenerable", "discarded": "明确废弃 /
29
30
  "uncertain": "不确定 / uncertain", "protected": "受保护 / protected"}
30
31
 
31
32
 
33
+ def print_groups(result):
34
+ print("Read-only observation; no execution permission. Workspace: "
35
+ + json.dumps(result["workspace"], ensure_ascii=True))
36
+ if "overview" in result:
37
+ for row in result["overview"]:
38
+ print(row["kind"] + ": " + str(row.get("groups", row.get("branches")))
39
+ + " groups; size unknown")
40
+ coverage = result["coverage"]
41
+ print("Frontier complete: " + str(coverage["frontier_complete"])
42
+ + "; workspace scan complete: False; unexpanded: " + str(len(coverage["unexpanded"])))
43
+ print("Use --json for groups, scopes, issues and unexpanded paths; "
44
+ "continue discovery with explicit --scope PATH.")
45
+ else:
46
+ for row in result["scopes"]:
47
+ size = str(row["size_bytes"]) + " B" if row["size_complete"] else (
48
+ "whole size unknown; observed " + str(row["observed_bytes"]) + " B")
49
+ print(json.dumps(row["path"], ensure_ascii=True) + ": " + size)
50
+ print(result["notice"])
51
+
52
+
32
53
  def print_plan(plan, *, stream=None, selected=None):
33
54
  stream = stream or sys.stdout
34
55
  print("Plan: " + plan["plan_id"], file=stream)
@@ -106,8 +127,13 @@ def main(argv=None):
106
127
  help="explicitly declare a path/subtree discarded; repeatable")
107
128
  parser.add_argument("--protect", action="append", default=[], metavar="PATH",
108
129
  help="protect an additional path/subtree; repeatable")
109
- parser.add_argument("--max-entries", type=int, default=DEFAULT_MAX_ENTRIES)
110
- parser.add_argument("--max-depth", type=int, default=DEFAULT_MAX_DEPTH)
130
+ modes = parser.add_mutually_exclusive_group()
131
+ modes.add_argument("--discover", action="store_true", help="read-only directory overview; no executable plan")
132
+ modes.add_argument("--measure", action="store_true", help="read-only metadata sizes for explicit directory scopes")
133
+ parser.add_argument("--scope", action="append", default=[], metavar="PATH",
134
+ help="directory below the fixed root; repeatable, for --discover or --measure")
135
+ parser.add_argument("--max-entries", type=int, help="entry budget; defaults: plan/discover 10000, measure 20000")
136
+ parser.add_argument("--max-depth", type=int, help="depth budget; defaults: plan 32, discover 4, measure 32")
111
137
  parser.add_argument("--json", action="store_true")
112
138
  parser.add_argument("--execute", action="store_true")
113
139
  parser.add_argument("--plan-id", help="exact ID from the plan being reviewed")
@@ -115,13 +141,32 @@ def main(argv=None):
115
141
  help="select an exact selectable plan entry; repeatable")
116
142
  args = parser.parse_args(argv)
117
143
  try:
144
+ observing = args.discover or args.measure
145
+ if observing and (args.execute or args.plan_id or args.select or args.discard or args.protect):
146
+ raise ValueError("read-only discovery/measurement cannot accept plan declarations or execution arguments")
147
+ if args.scope and not observing:
148
+ raise ValueError("--scope requires --discover or --measure; it does not narrow an executable plan")
149
+ if observing:
150
+ root = args.root or classifier.discover_workspace(os.getcwd())
151
+ limits = {name: value for name, value in (("max_entries", args.max_entries), ("max_depth", args.max_depth))
152
+ if value is not None}
153
+ result = (discover_groups(root, args.scope, **limits) if args.discover
154
+ else measure_groups(root, args.scope, **limits))
155
+ if args.json:
156
+ print(json.dumps(result, ensure_ascii=True, indent=2))
157
+ else:
158
+ print_groups(result)
159
+ complete = (result["coverage"]["frontier_complete"] if args.discover
160
+ else all(row["observed_subset_complete"] for row in result["scopes"]))
161
+ return 0 if complete else 1
118
162
  if not args.execute and (args.select or args.plan_id):
119
163
  raise ValueError("--select and --plan-id require --execute")
120
164
  if args.execute and not args.plan_id:
121
165
  raise ValueError("--execute requires the reviewed --plan-id")
122
166
  root = args.root or classifier.discover_workspace(os.getcwd())
123
167
  options = dict(discard=args.discard, protect=args.protect,
124
- max_entries=args.max_entries, max_depth=args.max_depth)
168
+ max_entries=DEFAULT_MAX_ENTRIES if args.max_entries is None else args.max_entries,
169
+ max_depth=DEFAULT_MAX_DEPTH if args.max_depth is None else args.max_depth)
125
170
  plan = plan_cleanup(root, **options)
126
171
  if not args.execute:
127
172
  if args.json: