@mokuyoaxis/agent-guard 0.2.4 → 0.2.5-rc2

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.
Files changed (38) hide show
  1. package/README.md +166 -573
  2. package/README.zh-CN.md +138 -489
  3. package/SECURITY.md +53 -0
  4. package/adapters/INTEGRATION.md +4 -2
  5. package/adapters/dsh/README.md +7 -0
  6. package/assets/linux-do-community.svg +19 -0
  7. package/core/audit.py +170 -25
  8. package/core/classifier.py +25 -1
  9. package/core/lab.py +77 -7
  10. package/core/policy.py +17 -9
  11. package/core/recovery.py +5 -1
  12. package/core/redaction.py +122 -21
  13. package/docs/README.md +18 -5
  14. package/docs/design/architecture.md +25 -6
  15. package/docs/design/compatibility.md +106 -1
  16. package/docs/design/threat-model.md +6 -4
  17. package/docs/guides/audit-metadata.md +77 -0
  18. package/docs/guides/getting-started.md +106 -0
  19. package/docs/guides/harness-capabilities.md +5 -0
  20. package/docs/history/friction.md +85 -0
  21. package/docs/lab/guard-lab.md +15 -1
  22. package/docs/releases/release-notes-0.2.5-rc1.md +91 -0
  23. package/docs/releases/release-notes-0.2.5-rc2.md +101 -0
  24. package/guard_lab.py +11 -0
  25. package/package.json +4 -2
  26. package/skills/delete-guard/SKILL.md +45 -7
  27. package/skills/delete-guard/references/policy.md +90 -4
  28. package/skills/delete-guard/scripts/check.py +3 -0
  29. package/skills/delete-guard/scripts/gc.py +18 -3
  30. package/skills/delete-guard/scripts/restore.py +22 -7
  31. package/skills/delete-guard/scripts/safe_delete.py +52 -29
  32. package/skills/delete-guard/scripts/status.py +9 -7
  33. package/skills/exfil-guard/SKILL.md +23 -11
  34. package/skills/exfil-guard/references/channels.md +8 -1
  35. package/skills/exfil-guard/references/rules.md +86 -6
  36. package/skills/exfil-guard/scripts/_payload.py +20 -0
  37. package/skills/exfil-guard/scripts/check_span.py +5 -1
  38. package/skills/exfil-guard/scripts/sanitize.py +6 -3
@@ -0,0 +1,106 @@
1
+ # Getting started / 入门指南
2
+
3
+ Agent Guard has three paths: recover supported destructive actions,
4
+ check disclosure before emission, and use guard-lab for controlled behaviour
5
+ experiments. Begin with the path you need; native interception is optional
6
+ and depends on the actual host.
7
+
8
+ Agent Guard 提供恢复保护、外发检测和用户控制的行为验测。先选择需要的能力;
9
+ 自动拦截另需实际宿主提供并加载兼容 hook。
10
+
11
+ ## Select the package root
12
+
13
+ The published stable baseline is 0.2.4; the previous published RC baseline is
14
+ 0.2.5-rc1. Current RC source is [0.2.5-rc2](../releases/release-notes-0.2.5-rc2.md),
15
+ including [shared audit metadata](audit-metadata.md) and observer startup maintenance.
16
+ Use a user-selected stable prefix for the published package:
17
+
18
+ ```sh
19
+ npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.4
20
+ ```
21
+
22
+ The package root is
23
+ `/absolute/path/to/agent-guard-install/node_modules/@mokuyoaxis/agent-guard`.
24
+ For RC2, select `@mokuyoaxis/agent-guard@0.2.5-rc2` explicitly and check its
25
+ [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-rc2)
26
+ and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-rc2)
27
+ for publication. A reviewed checkout or supplied local tarball can be evaluated
28
+ independently of registry availability.
29
+ Do not infer RC availability from the manifest or use an unscoped same-name
30
+ package. A checkout's default branch can differ from a tagged stable release.
31
+
32
+ Core needs Python 3.9+ and Git, with no third-party Python packages. POSIX
33
+ examples/bridges require a POSIX shell. The optional pinned DSH read path uses
34
+ Node 22; Kimi TOML helpers need Python 3.11+. Windows Core evidence does not
35
+ establish Windows-native hook bridge or full-suite portability.
36
+
37
+ ## Set up a coding agent
38
+
39
+ Replace the root path in this prompt, and give it to your agent:
40
+
41
+ ```text
42
+ Set up Agent Guard for this workspace using /absolute/path/to/agent-guard.
43
+ Identify the actual host version, tool names and hook/skill capabilities.
44
+ Read the README, Skill contracts and matching adapter guide; check Python/Git.
45
+ Use the selected checkout/package version and preserve existing settings.
46
+ Respect already-approved paths and configuration scope. Ask only for missing
47
+ information or changes beyond that scope, including new dependencies.
48
+ Install/reference the relevant Skills. Configure a native hook only where a
49
+ blocking event is supported; otherwise report Skill/CLI-only operation.
50
+ Claude: adapters/claude/README.md. Kimi: adapters/kimi-code/README.md.
51
+ DSH: adapters/dsh/README.md. Other hosts: adapters/INTEGRATION.md.
52
+ Verify a harmless call. Submit BLOCK-shaped commands only as data to check.py;
53
+ never execute deletion of real data as a test. For Claude/Kimi, run the local
54
+ doctor, but do not treat PASS as proof of actual host interception.
55
+ Report the host/version, installed paths, configuration scope, covered tools,
56
+ observed interception and unverified paths separately.
57
+ guard-lab is the user's controller, not a Skill to install into the tested
58
+ agent. Run real-host/model experiments only in an explicitly selected scope.
59
+ ```
60
+
61
+ 不要把“Skill 已安装”“配置检查通过”和“真实调用被拦截”合并为一个成功状态。
62
+ 用户范围外的配置或依赖改动需另行确认;已经授权的常规接入不重复询问。
63
+
64
+ ## Verify without executing a destructive command
65
+
66
+ From an isolated fixture, pass command text as data:
67
+
68
+ ```sh
69
+ python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/check.py --json -- rm /
70
+ ```
71
+
72
+ Read the BLOCK decision. Advisory exit 0 means assessment completed, not that
73
+ the command may run. Assessment can create quarantine/audit metadata and a
74
+ Git local exclude entry. Use a disposable fixture, and see the
75
+ [assessment contract](../../skills/delete-guard/references/policy.md#assessment-and-dry-run-side-effects).
76
+
77
+ For Claude/Kimi, local doctor probes do not start a model:
78
+
79
+ ```sh
80
+ python3 /absolute/path/to/agent-guard/doctor.py claude --probe --json
81
+ python3 /absolute/path/to/agent-guard/doctor.py kimi --probe --json
82
+ ```
83
+
84
+ Select the actual host, not both by default. These probes check one selected
85
+ configuration and a local bridge/adapter. Real host evidence needs a separate
86
+ controlled sentinel. An explicit live sentinel may consume provider quota;
87
+ its result covers one sampled root-agent Bash call. See
88
+ [host drift](host-drift.md) and the
89
+ [capability matrix](harness-capabilities.md).
90
+
91
+ ## Try the three paths
92
+
93
+ - **Recovery:** use the [delete Skill](../../skills/delete-guard/SKILL.md).
94
+ Valuable content relocates; provably regenerable artifacts may delete
95
+ directly. Inspect txids/state after errors, including force-restore backups.
96
+ - **Disclosure:** use the [exfil Skill](../../skills/exfil-guard/SKILL.md).
97
+ A checker plan is not completed redaction. The payload owner applies the
98
+ plan, controls emission and owns any egress audit.
99
+ - **Experiments:** use the [Lab guide](../lab/guard-lab.md).
100
+ Calibrate all four built-in controls before real trials. Only an effective
101
+ unguarded baseline enables a matched mitigation comparison.
102
+
103
+ For incident recovery from surviving evidence, use
104
+ [recovery-audit](../../skills/recovery-audit/SKILL.md).
105
+ Full rules, historical reports and releases are in the
106
+ [documentation index](../README.md).
@@ -1,5 +1,10 @@
1
1
  # Harness capability and evidence matrix
2
2
 
3
+ Current RC source: [0.2.5-rc2](../releases/release-notes-0.2.5-rc2.md); publication is checked by its receipts.
4
+ Rows below retain their tested source/host versions and do not automatically
5
+ certify this candidate. Local regression or package checks are separate from
6
+ new native-host/model evidence.
7
+
3
8
  The Python Core and CLI are harness-neutral. A Skill or CLI being usable in a
4
9
  host does **not** mean that host intercepts tool calls, and an adapter returning
5
10
  `BLOCK` does **not** by itself prove the host prevented execution.
@@ -4,6 +4,14 @@ This log records findings from host trials, CLI checks and regression tests.
4
4
  The initial entries came from a DSH session using `tools/pre-execute`, three
5
5
  model tools and a prompt section; later entries cover Core and other adapters.
6
6
 
7
+ Entries preserve their recording date and original candidate/release state.
8
+ F21–F23 changes subsequently shipped in 0.2.3; F24–F25 shipped in 0.2.4.
9
+ F26–F31 subsequently shipped in 0.2.5-rc1. RC2 adds shared audit metadata and
10
+ observer startup maintenance; publication is checked by its versioned receipts.
11
+ Current scope is in the
12
+ [candidate notes](../releases/release-notes-0.2.5-rc2.md); historical failures and
13
+ test counts below are not rewritten by a later success.
14
+
7
15
  ## F1 · Compound `cd X && rm y` resolves targets against the wrong base
8
16
 
9
17
  The interceptor classifies against the tool call's declared workdir. A
@@ -462,3 +470,80 @@ Regression: `tests/test_restore_boundary.py` (14),
462
470
  `tests/test_restore_source.py` (14), and `tests/test_restore_force.py` (22).
463
471
  These are sequential checks, not atomic same-UID isolation; cross-device
464
472
  copy failures can leave partial data requiring inspection.
473
+
474
+ ## F26 · Housekeeping overrode quarantine control protection
475
+
476
+ The classifier already marked the quarantine root protected, but the policy's
477
+ inside-trash allowance ran first. Root manifest/audit/state paths were also
478
+ treated as ordinary content, and a regenerable parent could contain storage.
479
+
480
+ **Fixed in local unreleased maintenance (2026-10-08):** protected-path decisions
481
+ precede trash housekeeping. Root controls, session state and in-workspace
482
+ storage access parents are classified explicitly, including parent aliases
483
+ and a control leaf link. Ordinary payload rules and explicit transaction GC
484
+ remain available. Opaque quarantine globs return `BLOCK_WILDCARD` before
485
+ housekeeping, because their expansion could include root control files.
486
+ This addresses supported deletion mistakes; arbitrary
487
+ scripts/writes and malicious same-UID tampering remain outside the guarantee.
488
+
489
+ ## F27 · Purged history remained GC eligible
490
+
491
+ Age planning reselected tombstoned transactions even after their directories
492
+ were removed. Active inventory now excludes `PURGED` entries before walking
493
+ or accounting their directories. History remains intact; recreated directories
494
+ are not claimed again. Failed purges remain active. This local maintenance
495
+ does not implement pruning retained Git stashes or rewrite old manifests.
496
+
497
+ ## F28 · Restore audit duplicated paths and failure bodies
498
+
499
+ The CLI copied restoration/conflict paths and arbitrary move errors into
500
+ non-recovery audit metadata. Local maintenance stores outcome counts and
501
+ transaction associations instead. Unknown/invalid input IDs are hashed;
502
+ recovery journal paths and CLI results remain exact. Generic audit append,
503
+ automatic session metadata and other output paths are separate work.
504
+
505
+ ## F29 · Exemption format and loading failures were silent
506
+
507
+ Both configuration filenames use a limited section/key parser, but the
508
+ `.agent-guardignore` name suggested gitignore syntax. Bare lines were silently
509
+ ignored, load failures silently tried the next file, and a readable empty or
510
+ malformed preferred file hid the fallback. Nonstandard legacy section keys
511
+ could also remain effective without an explanation.
512
+
513
+ Local unreleased maintenance (2026-10-08) reports the selected fixed relative
514
+ source, configured entry counts and bounded static diagnostics. Checker JSON
515
+ and sanitizer library results carry the metadata; human checker/sanitizer
516
+ warnings use stderr. Raw keys, patterns, hashes, lines and exception text
517
+ are withheld. Legacy matching, precedence, verdicts, exit codes and payload/
518
+ plan stdout formats are retained. This does not add gitignore parsing,
519
+ change configuration authority or sanitize other audit/output writers.
520
+
521
+ ## F30 · Assessment audit writes were mistaken for zero-write checks
522
+
523
+ Advisory check and safe_delete dry-run preserve command targets but use the
524
+ existing audit path, which can initialize quarantine metadata and Git local
525
+ exclude. A test named "touches nothing" checked target presence and Git status,
526
+ which cannot detect an ignored audit directory. Blocked-request documentation
527
+ also described the entire filesystem as untouched.
528
+
529
+ Local contract clarification (2026-10-08) adds explicit target/metadata and
530
+ failure regressions, corrects help/guidance, and documents early no-match and
531
+ existing-ignore/external-bucket exceptions. Best-effort assessment audits and
532
+ durable enforced intents retain their existing behavior. No zero-write CLI
533
+ flag, audit relocation or unrelated writer minimization is introduced.
534
+
535
+ ## F31 · safe_delete duplicated paths and free-form reasons into audit
536
+
537
+ safe_delete copied concrete targets, policy reason bodies and caller
538
+ `--reason` text into decision/outcome audit events. Its transaction metadata
539
+ also copied `--reason`, although restoration only needs the journal's exact
540
+ origin/trash paths. A secret-bearing filename or an arbitrary private note
541
+ therefore gained additional durable copies beyond the recovery journal.
542
+
543
+ Local minimization (2026-10-08) builds this writer's events from decisions,
544
+ codes, counts and established recovery IDs; partial/storage-failure reports
545
+ retain transaction correlation. Free-form reason metadata is omitted.
546
+ Exact CLI/recovery paths and error diagnostics remain available, with the
547
+ same mutation-intent durability and assessment/outcome failure behavior.
548
+ Historical records, automatic session identity and other audit/output
549
+ writers remain outside this change.
@@ -4,7 +4,10 @@
4
4
  observable agent and harness behaviours. It creates disposable bait, watches
5
5
  only declared channels, and produces a bounded report. Its built-in controls
6
6
  call no model; its separate manual probe is designed for a user-run real
7
- harness trial. The first implementation is the `0.2.3-rc2` source candidate.
7
+ harness trial. It was introduced in `0.2.3-rc2` and shipped with `0.2.3`.
8
+ It remains available in stable `0.2.4` and published `0.2.5-rc1`;
9
+ the `0.2.5-rc2` source candidate adds startup diagnosis and cancellation maintenance
10
+ without adding new model-trial evidence. See the [RC2 notes](../releases/release-notes-0.2.5-rc2.md).
8
11
 
9
12
  It is not a Skill for the tested agent, a security boundary, or a certificate
10
13
  that a model or vendor is safe or malicious.
@@ -213,6 +216,17 @@ matched bait IDs, and stage; it does not retain the input or matched value.
213
216
  Evidence is capped at 1024 events and a two MiB event log. Reaching a cap makes
214
217
  the observer/report inconclusive instead of silently dropping later events.
215
218
 
219
+ Observer startup has a five-second readiness window. Private `observer.log`
220
+ records static startup phases and monotonic timestamps for the controller,
221
+ Python bootstrap, validation, loopback bind and readiness publication. These
222
+ best-effort notes contain no tokens, paths or exception text and do not establish
223
+ observer health. A startup timeout requests cooperative cancellation and waits
224
+ up to two additional seconds to reap the local child; a still-live child stays
225
+ registered without a forced signal. A child that sees startup cancellation
226
+ records `FAILED` / `OBSERVER_STARTUP_CANCELLED`, keeping the report
227
+ `INCONCLUSIVE` even if readiness was published late. Ordinary stops after
228
+ successful readiness retain their existing meaning.
229
+
216
230
  The input file and `--stage` are user-selected evidence. `scan` does not parse
217
231
  or authenticate vendor-specific transcript schemas. If a captured stream mixes
218
232
  assistant messages, tool results, and system events, split those records first
@@ -0,0 +1,91 @@
1
+ # Agent Guard 0.2.5-rc1
2
+
3
+ Maintenance prerelease candidate, prepared 2026-10-08. The stable baseline
4
+ remains [0.2.4](release-notes-0.2.4.md). The release workflow maps this exact
5
+ RC to a GitHub prerelease and npm `rc`, preserving stable `latest` and the
6
+ original 0.2.4 tag/artifact. Publication receipts are the
7
+ [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-rc1)
8
+ and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-rc1).
9
+
10
+ 本候选合并 10-08 已完成的维护与本轮文档整理,不是仅修改 README。
11
+ 版本由维护者明确选择为 0.2.5-rc1,并授权 GitHub/npm 双推;稳定版范围仍另行决定。
12
+
13
+ ## Changes
14
+
15
+ - **Quarantine controls before housekeeping.** Existing
16
+ `BLOCK_PROTECTED_PATH` wins for root/control files, session state and
17
+ in-workspace storage parents, including reviewed aliases. Opaque quarantine
18
+ globs are refused; safe_delete can enumerate an explicit batch. Ordinary
19
+ unprotected payload housekeeping and validated explicit transaction GC
20
+ remain available.
21
+ - **PURGED history stays out of active GC inventory.** Tombstoned transactions
22
+ are excluded before payload accounting/planning. Historical manifests
23
+ remain intact, failed purges remain active, and this does not prune retained
24
+ Git stashes or claim ownership of recreated directories.
25
+ - **Restore and safe_delete audit minimization.** New writer events retain
26
+ decisions, counts and recovery associations instead of duplicating paths
27
+ and arbitrary error/reason bodies. safe_delete still accepts `--reason`
28
+ but does not persist its text in new audit/transaction metadata.
29
+ CLI results and essential recovery paths/intents stay exact. Old records,
30
+ generic audit writers and automatic session metadata are unchanged.
31
+ - **Exemption configuration diagnostics.** The existing limited parser,
32
+ first-readable-file priority and matching are retained. Checker JSON and
33
+ sanitizer library results gain provenance/count/diagnostic metadata;
34
+ human CLI warnings use stderr. Normal absent/valid configurations stay
35
+ quiet. No full TOML/gitignore parser or configuration migration is added.
36
+ - **Assessment contract.** Advisory checks and deletion dry-runs preserve
37
+ targets while potentially writing metadata/exclude entries. Advisory exit 0
38
+ does not authorize BLOCK/ASK. This is clarification and regression coverage,
39
+ not a new zero-write assessment flag.
40
+ - **Documentation.** Both READMEs introduce recovery protection, disclosure
41
+ checks and guard-lab near the top, with setup moved to a dedicated guide.
42
+ Current contracts distinguish planned emitter/audit integrations from
43
+ implemented CLIs, local metadata from optional provider calls, and observed
44
+ host evidence from candidate validation. Historical results retain their
45
+ original dates, failures and scope.
46
+ - **Documentation resources in the npm package.** Include SECURITY.md and
47
+ the existing community banner assets, which the previous allowlist omitted.
48
+ Runtime entry points and dependency requirements are unchanged.
49
+
50
+ ## Compatibility and version choice
51
+
52
+ Control-path/glob changes make some previously allowed shapes refuse by
53
+ default. The usual 0.x contract classifies that as minor. The maintainer
54
+ explicitly chose 0.2.5-rc1 instead of 0.3.0 as a bounded maintenance exception.
55
+ The prior 0.2.4 exception is not reused as blanket permission.
56
+ See the [compatibility contract](../design/compatibility.md#025-rc1-lifecycle-and-restore-audit-maintenance-source-candidate).
57
+
58
+ Existing decision/reason strings, CLI arguments and exit-code roles remain.
59
+ Consumers should tolerate additive optional fields and stderr diagnostics.
60
+ Audit shapes outside essential recovery manifests are not frozen.
61
+ No production dependency, storage migration, new transaction strategy or
62
+ general output enforcement is introduced. Later stable 0.2.5 scope and
63
+ publication remain separate decisions.
64
+
65
+ ## Evidence and limits
66
+
67
+ Before this version/documentation pass, the combined maintenance worktree
68
+ passed 874 Python tests and both Node adapter smoke groups, plus package,
69
+ offline install and a synthetic deletion/restore round trip. The first full
70
+ run retained one DSH Lab observer-startup timeout; the single-case recheck and
71
+ full rerun passed without changing its timeout. Its root cause remains unknown.
72
+ These are prior-source checkpoints, not this versioned candidate's release gate.
73
+
74
+ The versioned regression checkpoint passed 874 Python tests (821.138 seconds)
75
+ and both Node adapter smoke groups. It preserved 173 public source files
76
+ throughout the run. Afterwards only documentation and the packaging allowlist
77
+ for the two existing resources above changed; runtime code and test cases
78
+ retain those tested bytes. The final metadata/corpus checks, package contents,
79
+ offline installation, documented example and installed Lab calibration are
80
+ verified separately: 13 metadata/corpus checks, a 122-file tarball and offline
81
+ install, all 10 CLI help commands, adapter import, the documented example,
82
+ read-only trash query, a synthetic deletion/restore round trip and all four
83
+ zero-model Lab controls passed. These local checks do not establish publication.
84
+ No new model or native-host trial is started. Existing bounded DSH/PTC and
85
+ Kimi reports do not certify this new candidate. Historical unfinished pairs
86
+ remain pending; quiet or unhealthy baselines do not establish Lab mitigation.
87
+ Concurrency isolation, same-UID control-plane protection, universal egress
88
+ coverage and full Windows-native harness E2E remain outside the guarantee.
89
+
90
+ 发布流程要求精确提交的远端 CI、npm 凭据门禁与两个渠道的工件核查;
91
+ 本地打包通过不能替代这些步骤,具体执行结果以对应 Actions 和发布工件为准。
@@ -0,0 +1,101 @@
1
+ # Agent Guard 0.2.5-rc2
2
+
3
+ Maintenance prerelease, prepared 2026-10-09; double-channel publication
4
+ authorized 2026-10-10. The stable baseline is [0.2.4](release-notes-0.2.4.md),
5
+ and the previous prerelease is [0.2.5-rc1](release-notes-0.2.5-rc1.md).
6
+ The exact RC tag routes to GitHub prerelease and npm `rc`, preserving stable
7
+ `latest` and existing version artifacts. Publication receipts are the
8
+ [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-rc2)
9
+ and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-rc2).
10
+
11
+ 维护者已选择 RC2 候选准备范围:共享审计元信息最小化、Lab observer 启动与取消收尾、
12
+ 配套文档及回归,并已授权 main 提交/推送及本次 GitHub prerelease/npm rc 双推。
13
+ 发布仍需精确提交远端门禁和两个渠道的同工件核查;状态以版本化发布回执为准。
14
+
15
+ ## Changes since RC1
16
+
17
+ - **Shared audit projection.** `append` stores supported fields and validated
18
+ values only and returns the stored record. `tail` applies the same projection
19
+ to old objects in memory, skips malformed/non-object JSON, and returns no
20
+ records for non-positive limits. Unsupported/custom fields and free text are
21
+ omitted. Earlier log bytes and recovery manifests are preserved.
22
+ - **Opaque audit identities and bounded status metadata.** Supplied sessions
23
+ and displayed actors use stable SHA-256 correlation; the automatic identity
24
+ no longer includes a raw username or hostname. Generated transaction IDs
25
+ remain exact. Noncanonical IDs are summarized in audit views, while
26
+ `find_by_txid` still accepts their original spelling. Authorization session
27
+ selection and mode state are unchanged.
28
+ - **GC audit metadata.** Unknown selected IDs use digests and missing counts;
29
+ reason maps cover selected transactions only. Exact CLI diagnostics and
30
+ recovery associations remain available. Preflight and durable intent still
31
+ precede purge.
32
+ - **Observer startup diagnosis.** Private `observer.log` gains static phases
33
+ and monotonic timestamps for spawn, Python bootstrap, validation, loopback
34
+ binding, endpoint writing and readiness. These notes contain no tokens,
35
+ paths or exception text, are best-effort, and do not establish health.
36
+ - **Cancelled startup remains inconclusive.** The five-second readiness
37
+ window stays unchanged. Startup timeout requests cooperative cancellation
38
+ and permits up to two additional seconds of local child reaping. A live
39
+ child remains registered without a forced signal. Cancelled startup records
40
+ `FAILED` / `OBSERVER_STARTUP_CANCELLED`, including late READY publication.
41
+ Reap timeouts preserve the original LabError; ordinary stops after accepted
42
+ readiness retain their existing meaning.
43
+ - **Documentation and regression coverage.** Current entry points identify
44
+ the RC2 candidate separately from published baselines, describe audit
45
+ compatibility and observer behavior, and preserve historical test/host
46
+ evidence. The two maintenance groups add 40 regression tests over RC1.
47
+
48
+ RC2 retains the lifecycle, quarantine control-path, PURGED inventory,
49
+ restore/safe_delete writer, exemption-diagnostic and assessment maintenance
50
+ described in the [RC1 notes](release-notes-0.2.5-rc1.md).
51
+
52
+ ## Compatibility
53
+
54
+ Audit logs are supported metadata records, not arbitrary payload storage.
55
+ Consumers relying on custom fields, raw sessions/actors or noncanonical audit
56
+ IDs must review the [audit contract](../guides/audit-metadata.md).
57
+ A digest is not a restore argument: recovery uses the original ID and exact
58
+ manifest/CLI paths. Digests provide correlation, not encryption or identity
59
+ authentication.
60
+
61
+ Public CLI parameters, exit-code roles, supported recovery strategies,
62
+ authorization selection, audit locking/flush/fsync and existing
63
+ required-versus-best-effort writer gates retain their behavior.
64
+ No production dependency or storage/configuration migration is introduced.
65
+ RC2 introduces no new destructive-command policy verdict or refusal shape;
66
+ the bounded version exceptions inherited from RC1 remain documented in the
67
+ [compatibility contract](../design/compatibility.md).
68
+
69
+ ## Evidence and limits
70
+
71
+ Before this version/documentation preparation, the combined maintenance
72
+ source passed 914 Python tests (1279.463 seconds, no skips) and both Node
73
+ adapter smoke groups, with 176 public files frozen during that run.
74
+ The local 123-file package matched source and offline installation, and all
75
+ four installed zero-model controls passed. These are prior-source checkpoints,
76
+ not publication receipts for a package named 0.2.5-rc2.
77
+
78
+ The versioned RC2 candidate independently passed 914 Python tests
79
+ (1072.129 seconds, no skips) and both Node smoke groups; 177 public files
80
+ remained unchanged throughout that run. This evidence paragraph was completed
81
+ afterwards; runtime code and test cases retain their tested bytes.
82
+
83
+ The final RC2 candidate gate separately verifies
84
+ version/channel routing, final package contents, offline installation,
85
+ CLI/adapter entry points, synthetic recovery round trips and zero-model
86
+ calibration. Publishing additionally requires exact-commit remote CI,
87
+ npm preflight and matching GitHub/npm artifacts; a manifest or local tarball
88
+ does not establish registry availability.
89
+
90
+ **The first intermittent observer startup timeout's unique cause remains
91
+ unknown.** Controlled delay injections establish the cancellation/health
92
+ defect and its correction; normal rechecks do not identify that historical
93
+ cause or prove every future startup will finish within five seconds.
94
+ The [Lab contract](../lab/guard-lab.md) explains the diagnostic and health gates.
95
+
96
+ Old raw logs, exact recovery data, ordinary tool output and streams are
97
+ outside the shared audit projection. No new real-model or native-host trial
98
+ is credited to this candidate. Historical unfinished pairs remain pending.
99
+ Same-UID control-plane isolation, recovery concurrency isolation, universal
100
+ egress coverage and complete Windows-native harness E2E remain outside the
101
+ guarantee. Later stable 0.2.5 scope and publication remain separate decisions.
package/guard_lab.py CHANGED
@@ -5,6 +5,17 @@ from __future__ import annotations
5
5
 
6
6
  import sys
7
7
 
8
+ if __name__ == "__main__" and len(sys.argv) > 1 and sys.argv[1] == "_observe":
9
+ import time
10
+
11
+ try:
12
+ print(
13
+ f"observer-startup stage=BOOTSTRAP monotonic={time.monotonic():.6f}",
14
+ file=sys.stderr, flush=True,
15
+ )
16
+ except (OSError, ValueError):
17
+ pass
18
+
8
19
  from core.lab import cli_main, observer_cli_main
9
20
 
10
21
 
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@mokuyoaxis/agent-guard",
3
- "version": "0.2.4",
4
- "description": "Harness-neutral reliability infrastructure for AI coding agents: reversible destructive actions, pre-emission redaction, recovery evidence, and a shared Decision Protocol with optional native adapters.",
3
+ "version": "0.2.5-rc2",
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
  "main": "./adapters/dsh/lib/index.js",
7
7
  "exports": {
@@ -32,11 +32,13 @@
32
32
  "core",
33
33
  "skills",
34
34
  "docs",
35
+ "assets",
35
36
  "doctor.py",
36
37
  "live_sentinel.py",
37
38
  "guard_lab.py",
38
39
  "LICENSE",
39
40
  "CONTRIBUTING.md",
41
+ "SECURITY.md",
40
42
  "README.md",
41
43
  "README.zh-CN.md",
42
44
  "!**/__pycache__/**",
@@ -16,19 +16,22 @@ enforces and how to work with it productively. The four pillars:
16
16
 
17
17
  - **Scope** - you act inside the workspace; the workspace root, `.git`, and
18
18
  everything outside are never yours to delete.
19
- - **Recoverability** - deletions are compensated (relocated to `.agent-trash/`
20
- with a manifest, or snapshotted as a git stash) before they take effect.
19
+ - **Recoverability** - supported valuable deletions relocate to the selected
20
+ quarantine with a manifest; supported Git overwrites snapshot tracked state.
21
+ Provably regenerable, ignored artifacts may be deleted directly.
21
22
  - **Authorization** - a human decides permission boundaries. You can be
22
23
  *downgraded* to RESTRICTED mode; you can never promote yourself back.
23
- - **Auditability** - every verdict, relocation, and restore is recorded in
24
- JSONL. Nothing is invisible.
24
+ - **Auditability** - supported writers record decision/recovery metadata in
25
+ JSONL according to their CLI contract. Mutation intents must be durable;
26
+ assessment/blocked audit may be best effort, and early no-op paths may not
27
+ write an audit. Calls outside the covered path are not automatically visible.
25
28
 
26
29
  ## The one rule
27
30
 
28
31
  **Prefer `safe_delete` over `rm`.** It applies the guard's recovery policy.
29
32
 
30
33
  ```bash
31
- # delete files/dirs/globs - they are quarantined, not destroyed:
34
+ # delete explicit targets; valuable content is quarantined:
32
35
  python3 <repo>/skills/delete-guard/scripts/safe_delete.py src/old_module.py
33
36
  python3 <repo>/skills/delete-guard/scripts/safe_delete.py 'build/**/*.tmp' --reason "stale build output"
34
37
 
@@ -64,8 +67,9 @@ redirections) before destroying them (F2), is refused as undeterminable.
64
67
  Run deletions as standalone commands with an explicit workdir.
65
68
 
66
69
  A block is not an error to route around. Retrying the same operation in a
67
- disguised form (`/bin/rm`, `python -c`, a script) is a violation of the
68
- authorization pillar and is recorded in the audit log.
70
+ disguised form (`/bin/rm`, `python -c`, a script) violates this discipline and
71
+ can bypass both protection and audit. Do not treat a missing audit as proof
72
+ that no operation occurred.
69
73
 
70
74
  `git reset --hard [commit]` first checks whether its target tree would
71
75
  overwrite untracked or ignored content. A tracked-only stash cannot recover
@@ -89,6 +93,28 @@ stop immediately. Inspect both the origin and `.agent-trash/`; never infer
89
93
  that an error means no filesystem change occurred. A durable
90
94
  `relocate-intent` can keep an interrupted relocation discoverable.
91
95
 
96
+ ## Assessment and preflight
97
+
98
+ Advisory `check.py` and `safe_delete.py --dry-run` preserve command targets,
99
+ but may create quarantine/audit metadata and a Git local exclude rule.
100
+ They are not zero-write filesystem checks. Advisory exit 0 means the
101
+ assessment completed; inspect the decision and never execute a BLOCK/ASK
102
+ command merely because the exit was zero. Blocked safe_delete still exits 2
103
+ under dry-run. Audit warnings do not imply that all metadata writes were
104
+ undone. Use only a disposable fixture when verifying this behavior; the
105
+ [policy reference](references/policy.md#assessment-and-dry-run-side-effects)
106
+ defines the no-match, existing-ignore and external-bucket branches.
107
+
108
+ Since 0.2.5-rc1, new `safe_delete` audit events record decisions, target counts and established
109
+ recovery IDs/counts rather than target paths or free-form reasons. `--reason`
110
+ is still accepted, but its text is not persisted in audit or transaction
111
+ metadata. Exact recovery paths remain in the CLI result and manifest.
112
+ At released RC1, historical records and automatic session handling are unchanged.
113
+ The 0.2.5-rc2 source candidate projects shared metadata on append/read,
114
+ uses opaque session correlation and limits status/GC metadata; see the
115
+ [shared audit contract](../../docs/guides/audit-metadata.md) and the
116
+ [policy reference](references/policy.md#safe_delete-audit-metadata).
117
+
92
118
  ## Quarantine location queries
93
119
 
94
120
  When the user asks where quarantines are or how many exist, use the shared
@@ -111,6 +137,13 @@ read just to answer a location/count question.
111
137
 
112
138
  ## RESTRICTED mode
113
139
 
140
+ The RC2 source retains RC1 protection for the quarantine root, root manifest,
141
+ audit/state files, state temp file, sessions tree and storage access parents.
142
+ Housekeeping does not override those checks. Use the existing explicit
143
+ `gc.py --execute --txid <id>` entry for a validated, audited transaction purge.
144
+ Ordinary unprotected payload housekeeping retains its existing policy.
145
+ GC plans omit `PURGED` history; they do not delete stored Git stashes.
146
+
114
147
  After a human veto, the session runs with narrowed powers: explicit
115
148
  single-file deletes inside the workspace still work (quarantined as usual);
116
149
  recursive deletes, globs, and destructive git operations are refused. Only a
@@ -144,3 +177,8 @@ space and remain subject to its existing explicit GC policy.
144
177
 
145
178
  See `references/policy.md` for the complete rule table, verdict codes, and
146
179
  manifest format.
180
+
181
+ The candidate's restore audit records counts and transaction associations rather
182
+ than duplicate paths/error text. CLI results and recovery manifests still
183
+ contain the exact data needed to inspect and restore; a failed CLI result
184
+ must still be checked against the filesystem and preservation attempts.