@mokuyoaxis/agent-guard 0.2.5-rc1 → 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.
package/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
  [![npm stable](https://img.shields.io/npm/v/%40mokuyoaxis%2Fagent-guard.svg)](https://www.npmjs.com/package/@mokuyoaxis/agent-guard)
5
5
  [![License](https://img.shields.io/github/license/mokuyoaxis/agent-guard)](LICENSE)
6
6
  [![Python 3.9+](https://img.shields.io/badge/Python-3.9%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
7
- [![0.2.5-rc1](https://img.shields.io/badge/RC-0.2.5--rc1-5B6B7A)](docs/releases/release-notes-0.2.5-rc1.md)
7
+ [![0.2.5-rc2 candidate](https://img.shields.io/badge/RC-0.2.5--rc2-5B6B7A)](docs/releases/release-notes-0.2.5-rc2.md)
8
8
 
9
9
  **Make destructive agent actions reversible by default.** · [简体中文](README.zh-CN.md)
10
10
 
@@ -75,7 +75,8 @@ native bridges and optional capture helpers have their own requirements.
75
75
  | Version | Status |
76
76
  |---|---|
77
77
  | [0.2.4](docs/releases/release-notes-0.2.4.md) | Published stable baseline |
78
- | [0.2.5-rc1](docs/releases/release-notes-0.2.5-rc1.md) | Maintenance release candidate; select the exact RC version |
78
+ | [0.2.5-rc1](docs/releases/release-notes-0.2.5-rc1.md) | Previous published prerelease baseline |
79
+ | [0.2.5-rc2](docs/releases/release-notes-0.2.5-rc2.md) | Maintenance prerelease; check the exact publication receipts |
79
80
 
80
81
  For the published stable package, use a chosen, stable user-owned prefix:
81
82
 
@@ -92,11 +93,12 @@ git clone https://github.com/mokuyoaxis/agent-guard.git
92
93
  cd agent-guard
93
94
  ```
94
95
 
95
- For the RC, select `@mokuyoaxis/agent-guard@0.2.5-rc1` explicitly; the RC
96
+ For RC2, select `@mokuyoaxis/agent-guard@0.2.5-rc2` explicitly; the RC
96
97
  channel does not replace stable `latest`. Check the
97
- [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-rc1)
98
- or [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-rc1)
99
- for publication. A reviewed checkout or locally supplied tarball is also usable. See
98
+ [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-rc2)
99
+ and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-rc2)
100
+ for publication. A reviewed checkout or supplied tarball is also usable;
101
+ the manifest alone does not establish registry availability. See
100
102
  [setup and the agent setup prompt](docs/guides/getting-started.md).
101
103
 
102
104
  ## Recover a supported deletion
@@ -122,11 +124,18 @@ may write quarantine/audit metadata and a Git local exclude entry. Advisory
122
124
  exit 0 is not permission to execute a BLOCK or ASK.
123
125
  See the [policy and assessment contract](skills/delete-guard/references/policy.md).
124
126
 
125
- The RC adds quarantine control-path protection, excludes PURGED transactions
126
- from active GC planning, and minimizes restore/safe_delete audit fields.
127
+ RC1 added quarantine control-path protection, excluded PURGED transactions
128
+ from active GC planning, and minimized restore/safe_delete audit fields.
127
129
  Exact CLI/manifest recovery paths remain available. These changes are not in
128
130
  the published 0.2.4 package; see the [RC notes](docs/releases/release-notes-0.2.5-rc1.md).
129
131
 
132
+ The RC2 source candidate also projects shared audit metadata,
133
+ uses opaque session correlation, and limits legacy status/GC metadata.
134
+ See the [audit contract and remaining boundaries](docs/guides/audit-metadata.md).
135
+ It adds observer startup diagnostics and correct cancellation accounting;
136
+ the original intermittent timeout's cause remains unknown. See the
137
+ [RC2 scope and evidence](docs/releases/release-notes-0.2.5-rc2.md).
138
+
130
139
  ## Check text before emission
131
140
 
132
141
  The payload owner invokes the scanner and applies its decision.
@@ -202,7 +211,7 @@ reconstruction and known gaps. It cannot recreate bytes that no source kept.
202
211
  | [Architecture](docs/design/architecture.md) | Shared Core, compensation and adapter flow |
203
212
  | [Threat model](docs/design/threat-model.md) | Trust assumptions and unresolved boundaries |
204
213
  | [Compatibility](docs/design/compatibility.md) | Interface and release contracts |
205
- | [0.2.5-rc1 notes](docs/releases/release-notes-0.2.5-rc1.md) | This candidate's changes and validation status |
214
+ | [0.2.5-rc2 notes](docs/releases/release-notes-0.2.5-rc2.md) | Current source candidate's changes and validation status |
206
215
 
207
216
  ## Contributing
208
217
 
package/README.zh-CN.md CHANGED
@@ -4,7 +4,7 @@
4
4
  [![npm 稳定版](https://img.shields.io/npm/v/%40mokuyoaxis%2Fagent-guard.svg)](https://www.npmjs.com/package/@mokuyoaxis/agent-guard)
5
5
  [![License](https://img.shields.io/github/license/mokuyoaxis/agent-guard)](LICENSE)
6
6
  [![Python 3.9+](https://img.shields.io/badge/Python-3.9%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
7
- [![0.2.5-rc1](https://img.shields.io/badge/RC-0.2.5--rc1-5B6B7A)](docs/releases/release-notes-0.2.5-rc1.md)
7
+ [![0.2.5-rc2 候选](https://img.shields.io/badge/RC-0.2.5--rc2-5B6B7A)](docs/releases/release-notes-0.2.5-rc2.md)
8
8
 
9
9
  **让 AI Agent 的破坏性操作默认可逆。** · [English](README.md)
10
10
 
@@ -64,7 +64,8 @@ Core 需要 Python 3.9+ 和 Git。示例采用 POSIX Shell;原生桥接和可
64
64
  | 版本 | 状态 |
65
65
  |---|---|
66
66
  | [0.2.4](docs/releases/release-notes-0.2.4.md) | 已发布的稳定基线 |
67
- | [0.2.5-rc1](docs/releases/release-notes-0.2.5-rc1.md) | 维护预发布;显式选择准确 RC 版本 |
67
+ | [0.2.5-rc1](docs/releases/release-notes-0.2.5-rc1.md) | 已发布的历史预发布基线 |
68
+ | [0.2.5-rc2](docs/releases/release-notes-0.2.5-rc2.md) | 维护预发布;以准确版本的发布回执为准 |
68
69
 
69
70
  稳定包可安装到用户选定的长期目录:
70
71
 
@@ -81,10 +82,10 @@ git clone https://github.com/mokuyoaxis/agent-guard.git
81
82
  cd agent-guard
82
83
  ```
83
84
 
84
- RC 显式选择 `@mokuyoaxis/agent-guard@0.2.5-rc1`;RC 通道不替换稳定版 `latest`。
85
- 发布状态以 [GitHub Release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-rc1)
86
- 和 [npm 版本页](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-rc1)为准,
87
- 也可使用已核查的 checkout 或本地提供的 tarball。
85
+ RC2 显式选择 `@mokuyoaxis/agent-guard@0.2.5-rc2`;RC 通道不替换稳定版 `latest`。
86
+ 发布状态以 [GitHub Release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-rc2)
87
+ 和 [npm 版本页](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-rc2)为准,
88
+ 也可使用已核查的 checkout 或提供的 tarball;manifest 版本不代表 registry 已可安装。
88
89
  接入步骤与 Agent 提示词见[入门指南](docs/guides/getting-started.md)。
89
90
 
90
91
  ## 恢复一次受支持的删除
@@ -108,10 +109,15 @@ advisory `check.py` 和 `safe_delete.py --dry-run` 保持命令目标不变,
108
109
  隔离区/审计元数据及 Git 本地 exclude。advisory 退出码 0 不代表 BLOCK/ASK
109
110
  操作获准执行。详见[策略与评估契约](skills/delete-guard/references/policy.md)。
110
111
 
111
- 本 RC 增加隔离区控制路径保护、从活跃 GC 计划排除 PURGED 事务,并最小化
112
+ RC1 已增加隔离区控制路径保护、从活跃 GC 计划排除 PURGED 事务,并最小化
112
113
  restore/safe_delete 审计字段;CLI/manifest 仍保留准确恢复路径。
113
114
  这些维护不属于已发布的 0.2.4 包,见 [RC 说明](docs/releases/release-notes-0.2.5-rc1.md)。
114
115
 
116
+ RC2 源码候选进一步限定通用审计字段、使用不透明 session 关联,
117
+ 并收口旧日志 status 展示与 GC 元信息,见[审计契约及保留边界](docs/guides/audit-metadata.md)。
118
+ 同时补充 observer 启动诊断与取消健康记账;最初偶发超时的具体原因仍未知,
119
+ 见 [RC2 范围与证据](docs/releases/release-notes-0.2.5-rc2.md)。
120
+
115
121
  ## 外发前检查文本
116
122
 
117
123
  持有载荷的调用方主动运行扫描器,并按判决处理文本:
@@ -178,7 +184,7 @@ Git/会话/缓存证据恢复项目,区分原文、重建与确认缺失
178
184
  | [架构](docs/design/architecture.md) | 共享 Core、补偿与适配器数据流 |
179
185
  | [威胁模型](docs/design/threat-model.md) | 信任假设与尚未解决的边界 |
180
186
  | [兼容契约](docs/design/compatibility.md) | 接口与发布约定 |
181
- | [0.2.5-rc1 说明](docs/releases/release-notes-0.2.5-rc1.md) | 本候选变更与验收状态 |
187
+ | [0.2.5-rc2 说明](docs/releases/release-notes-0.2.5-rc2.md) | 当前源码候选变更与验收状态 |
182
188
 
183
189
  ## 参与贡献
184
190
 
package/core/audit.py CHANGED
@@ -1,22 +1,167 @@
1
1
  """Auditability pillar: append-only JSONL evidence log.
2
2
 
3
- Every decision the guard makes - allow, relocate, compensate, block - is
4
- appended as one JSON object per line. The log is intentionally dumb: no
5
- rotation, no aggregation, no mutation. Post-hoc verification reads it
6
- sequentially. A torn or corrupt line is skipped on read, never rewritten.
3
+ Records contain supported metadata, not arbitrary caller payloads. Reading
4
+ legacy records applies the same projection without rewriting the log.
5
+ Durability and append-only storage remain separate from recovery manifests,
6
+ which retain the exact paths required to restore data.
7
7
  """
8
8
  from __future__ import annotations
9
9
 
10
- import getpass
10
+ from collections import deque
11
+ from functools import lru_cache
12
+ import hashlib
11
13
  import json
14
+ import math
12
15
  import os
13
- import platform
16
+ import re
14
17
  import threading
15
18
  import time
16
19
  import uuid
17
- from typing import Any, Dict, List, Optional
20
+ from typing import Any, Dict, List
18
21
 
19
22
  _APPEND_LOCK = threading.Lock()
23
+ _LOCAL_SESSION = uuid.uuid4().hex
24
+ _CORRELATION_RE = re.compile(r"sha256:[0-9a-f]{64}\Z")
25
+ _TXID_RE = re.compile(r"[0-9]{8}-[0-9]{6}-[0-9a-f]{8}\Z")
26
+ _TIMESTAMP_RE = re.compile(r"[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z\Z")
27
+ _HASH_RE = re.compile(r"[0-9a-f]{64}\Z")
28
+ _GIT_SHA_RE = re.compile(r"[0-9a-f]{40}(?:[0-9a-f]{24})?\Z")
29
+ _COUNTS = frozenset({
30
+ "target_count", "moved_count", "skipped_count", "restored_count",
31
+ "conflict_count", "error_count", "missing_count", "moved", "skipped",
32
+ "enumerated", "start", "end", "length",
33
+ })
34
+ _IDENTIFIERS = frozenset({"txid", "check_id", "plan_id"})
35
+ _ID_LISTS = frozenset({"txids", "backup_txids", "purged", "missing"})
36
+ _COMPENSATION_FIELDS = frozenset({
37
+ "strategy", "txid", "status", "moved", "skipped", "enumerated", "sha",
38
+ })
39
+
40
+
41
+ def correlation_id(value: str) -> str:
42
+ """Opaque, deterministic correlation; not encryption or authentication.
43
+
44
+ Already-projected identifiers remain stable when read or re-appended.
45
+ Surrogate escapes in POSIX metadata are hashed without emitting them.
46
+ """
47
+ if _CORRELATION_RE.fullmatch(value):
48
+ return value
49
+ return "sha256:" + hashlib.sha256(
50
+ value.encode("utf-8", errors="surrogatepass")).hexdigest()
51
+
52
+
53
+ def _identifier(value: str) -> str:
54
+ # Generated recovery/check IDs stay directly usable. Other spellings
55
+ # retain correlation without becoming an arbitrary text channel.
56
+ return value if _TXID_RE.fullmatch(value) else correlation_id(value)
57
+
58
+
59
+ @lru_cache(maxsize=1)
60
+ def _enums():
61
+ # Import after module initialization: recovery imports the ID/time
62
+ # helpers above, and needs no policy or redaction decisions here.
63
+ from . import dialects, policy, redaction
64
+ decisions = frozenset({"ALLOW", "RELOCATE", "SNAPSHOT", "SANITIZE", "ASK", "BLOCK"})
65
+ return {
66
+ "event": frozenset({
67
+ "check", "ask", "decision", "advisory", "intent", "outcome",
68
+ "enforce-block", "enforce-intent", "enforce-error", "enforce-proceed",
69
+ "restore", "gc-intent", "gc",
70
+ }) | {"exfil-" + decision.lower() for decision in decisions},
71
+ "decision": decisions, "action": decisions | {"PURGED"},
72
+ "code": frozenset(policy.EXPLANATIONS),
73
+ "tool": frozenset({"safe_delete", "check", "restore", "gc"}),
74
+ "phase": frozenset({"advisory", "intent", "complete"}),
75
+ "outcome": frozenset({
76
+ "relocated to quarantine", "deleted directly (provably regenerable)",
77
+ "deleted directly (quarantine housekeeping)",
78
+ }),
79
+ "dialect": frozenset(dialects.DIALECT_ALIASES.values()),
80
+ "dialect_requested": frozenset(dialects.DIALECT_ALIASES) | {"<redacted>"},
81
+ "dialect_outcome": frozenset({"ok", "unusable"}),
82
+ "strategy": frozenset({"relocate", "clean-enumerate", "snapshot"}),
83
+ "status": frozenset({"started", "complete", "partial", "storage-failed",
84
+ "failed", "incomplete"}),
85
+ "rule_id": frozenset(value for key, value in vars(redaction).items()
86
+ if key.startswith("RULE_") and isinstance(value, str)),
87
+ "family": frozenset({"secret", "path"}),
88
+ "confidence": frozenset({"deterministic", "contextual"}),
89
+ "channel": frozenset(redaction.CHANNELS),
90
+ "context": frozenset({"prose", "key", "uri-userinfo", "env-var"}),
91
+ "command": frozenset({"<redacted>"}),
92
+ "error": frozenset({"compensation failed"}),
93
+ }
94
+
95
+
96
+ def project(record: Dict[str, Any]) -> Dict[str, Any]:
97
+ """Supported metadata only; unknown fields/types/free text are omitted.
98
+
99
+ This is a closed record projection, not a general text sanitizer. Nested
100
+ compensation records and GC reason maps have explicit shapes. Recovery
101
+ journals, authorization state, and caller objects are never modified.
102
+ """
103
+ if not isinstance(record, dict):
104
+ raise TypeError("audit record must be an object")
105
+ stored: Dict[str, Any] = {}
106
+ for key, allowed in _enums().items():
107
+ value = record.get(key)
108
+ if key == "context" and isinstance(value, str) and value.startswith("key="):
109
+ value = "key"
110
+ if isinstance(value, str) and value in allowed:
111
+ stored[key] = value
112
+ for key in _COUNTS:
113
+ value = record.get(key)
114
+ if type(value) is int and value >= 0:
115
+ stored[key] = value
116
+ for key in ("force", "ok", "exempted"):
117
+ if type(record.get(key)) is bool:
118
+ stored[key] = record[key]
119
+ latency = record.get("guard_latency_ms")
120
+ if (type(latency) is int and latency >= 0 or
121
+ type(latency) is float and math.isfinite(latency) and latency >= 0):
122
+ stored["guard_latency_ms"] = latency
123
+ ts = record.get("ts")
124
+ if isinstance(ts, str) and _TIMESTAMP_RE.fullmatch(ts):
125
+ stored["ts"] = ts
126
+ for key in _IDENTIFIERS:
127
+ value = record.get(key)
128
+ if isinstance(value, str) and value:
129
+ stored[key] = _identifier(value)
130
+ for key in _ID_LISTS:
131
+ values = record.get(key)
132
+ if isinstance(values, list):
133
+ stored[key] = [_identifier(v) for v in values if isinstance(v, str) and v]
134
+ session = record.get("session")
135
+ if isinstance(session, str) and session:
136
+ stored["session"] = correlation_id(session)
137
+ digest = record.get("txid_sha256")
138
+ if isinstance(digest, str) and _HASH_RE.fullmatch(digest):
139
+ stored["txid_sha256"] = digest
140
+ digests = record.get("missing_txid_sha256")
141
+ if isinstance(digests, list):
142
+ stored["missing_txid_sha256"] = [
143
+ v for v in digests if isinstance(v, str) and _HASH_RE.fullmatch(v)]
144
+ sha = record.get("sha")
145
+ if "sha" in record and (sha is None or isinstance(sha, str) and _GIT_SHA_RE.fullmatch(sha)):
146
+ stored["sha"] = sha
147
+ span = record.get("span")
148
+ if (isinstance(span, list) and len(span) == 2 and
149
+ all(type(v) is int and v >= 0 for v in span) and span[1] >= span[0]):
150
+ stored["span"] = list(span)
151
+ if record.get("reasons") == []:
152
+ stored["reasons"] = []
153
+ compensations = record.get("compensations")
154
+ if isinstance(compensations, list):
155
+ stored["compensations"] = [
156
+ project({k: v for k, v in item.items() if k in _COMPENSATION_FIELDS})
157
+ for item in compensations if isinstance(item, dict)]
158
+ reasons = record.get("plan_reasons")
159
+ if isinstance(reasons, dict):
160
+ stored["plan_reasons"] = {
161
+ _identifier(txid): reason for txid, reason in reasons.items()
162
+ if isinstance(txid, str) and txid and isinstance(reason, str)
163
+ and reason in {"age", "capacity"}}
164
+ return stored
20
165
 
21
166
 
22
167
  def utc_now_iso() -> str:
@@ -29,27 +174,20 @@ def new_txid() -> str:
29
174
 
30
175
 
31
176
  def session_id() -> str:
32
- """Best-effort identity of the acting session.
177
+ """Opaque correlation for the acting session.
33
178
 
34
179
  An agent harness may identify itself through AGENT_GUARD_SESSION.
35
180
  This is correlation metadata, not authentication.
36
181
  """
37
182
  env = os.environ.get("AGENT_GUARD_SESSION")
38
183
  if env:
39
- return env
40
- try:
41
- user = getpass.getuser()
42
- except Exception: # pragma: no cover - exotic passwd setups
43
- user = "unknown"
44
- # platform.node() is the cross-platform form of os.uname().nodename
45
- # (os.uname does not exist on Windows); empty on exotic setups.
46
- host = platform.node() or "localhost"
47
- return f"{user}@{host}:{os.getpid()}"
184
+ return correlation_id(env)
185
+ return correlation_id(f"{_LOCAL_SESSION}:{os.getpid()}")
48
186
 
49
187
 
50
188
  def append(record: Dict[str, Any], audit_path: str) -> Dict[str, Any]:
51
- """Append one record; returns the stored record (with defaults filled)."""
52
- stored = dict(record)
189
+ """Append projected metadata; return exactly what was stored."""
190
+ stored = project(record)
53
191
  stored.setdefault("ts", utc_now_iso())
54
192
  stored.setdefault("session", session_id())
55
193
  line = json.dumps(stored, ensure_ascii=False, sort_keys=True)
@@ -65,22 +203,29 @@ def append(record: Dict[str, Any], audit_path: str) -> Dict[str, Any]:
65
203
 
66
204
 
67
205
  def tail(audit_path: str, n: int = 20) -> List[Dict[str, Any]]:
68
- """Read the last n valid records. Corrupt/torn lines are skipped."""
69
- if not os.path.exists(audit_path):
206
+ """Last n projected objects; malformed/non-object lines are skipped.
207
+
208
+ A non-positive limit reads nothing. Old bytes are never rewritten.
209
+ """
210
+ if n <= 0 or not os.path.exists(audit_path):
70
211
  return []
71
- records: List[Dict[str, Any]] = []
212
+ records = deque(maxlen=n)
72
213
  with open(audit_path, "r", encoding="utf-8") as fh:
73
214
  for raw in fh:
74
215
  raw = raw.strip()
75
216
  if not raw:
76
217
  continue
77
218
  try:
78
- records.append(json.loads(raw))
219
+ record = json.loads(raw)
79
220
  except json.JSONDecodeError:
80
221
  continue
81
- return records[-max(n, 0):]
222
+ if isinstance(record, dict):
223
+ records.append(project(record))
224
+ return list(records)
82
225
 
83
226
 
84
227
  def find_by_txid(audit_path: str, txid: str) -> List[Dict[str, Any]]:
85
228
  """All audit records belonging to one compensation transaction."""
86
- return [r for r in tail(audit_path, n=100_000) if r.get("txid") == txid]
229
+ key = _identifier(txid)
230
+ return [r for r in tail(audit_path, n=100_000)
231
+ if r.get("txid") == key]
package/core/lab.py CHANGED
@@ -19,6 +19,7 @@ from pathlib import Path
19
19
  import re
20
20
  import secrets
21
21
  from socketserver import TCPServer
22
+ import stat
22
23
  import subprocess
23
24
  import sys
24
25
  import tarfile
@@ -194,6 +195,10 @@ class LabError(RuntimeError):
194
195
  """Expected guard-lab error with a safe, bounded message."""
195
196
 
196
197
 
198
+ class _ObserverStartupCancelled(LabError):
199
+ """The controller stopped this observer before accepting its readiness."""
200
+
201
+
197
202
  def _now() -> str:
198
203
  return datetime.now(timezone.utc).isoformat()
199
204
 
@@ -1026,6 +1031,41 @@ def _write_observer_state(evidence: Path, state: dict[str, Any]) -> None:
1026
1031
  _atomic_write_json(evidence / "observer.json", state)
1027
1032
 
1028
1033
 
1034
+ def _observer_startup_note(stage: str, stream: Any = None) -> None:
1035
+ # Static phases and monotonic time only: never log tokens, paths or errors.
1036
+ try:
1037
+ print(
1038
+ f"observer-startup stage={stage} monotonic={time.monotonic():.6f}",
1039
+ file=sys.stderr if stream is None else stream,
1040
+ flush=True,
1041
+ )
1042
+ except (OSError, ValueError):
1043
+ pass # Diagnosis must not determine the observer's health.
1044
+
1045
+
1046
+ def _observer_arm_note(evidence: Path, stage: str) -> None:
1047
+ flags = os.O_WRONLY | os.O_APPEND | getattr(os, "O_CLOEXEC", 0)
1048
+ flags |= getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0)
1049
+ try:
1050
+ descriptor = os.open(evidence / "observer.log", flags)
1051
+ with os.fdopen(descriptor, "a", encoding="utf-8") as output:
1052
+ if stat.S_ISREG(os.fstat(output.fileno()).st_mode):
1053
+ _observer_startup_note(stage, output)
1054
+ except OSError:
1055
+ pass
1056
+
1057
+
1058
+ def _check_observer_startup_stop(evidence: Path, *, ready: bool = False) -> None:
1059
+ stop_path = evidence / "stop.request"
1060
+ if not stop_path.is_file():
1061
+ return
1062
+ if ready:
1063
+ stop = _read_json(stop_path, "observer stop request")
1064
+ if stop.get("reason") != "OBSERVER_STARTUP_TIMEOUT":
1065
+ return # An ordinary stop after READY keeps its existing meaning.
1066
+ raise _ObserverStartupCancelled("observer startup was cancelled")
1067
+
1068
+
1029
1069
  def arm_observer(evidence_dir: Path, duration: int = 60) -> dict[str, Any]:
1030
1070
  if duration < MIN_DURATION_SECONDS or duration > MAX_DURATION_SECONDS:
1031
1071
  raise LabError("observer duration is outside the supported range")
@@ -1037,7 +1077,8 @@ def arm_observer(evidence_dir: Path, duration: int = 60) -> dict[str, Any]:
1037
1077
  raise LabError("observer has already been armed for this run")
1038
1078
 
1039
1079
  log_path = evidence / "observer.log"
1040
- flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_CLOEXEC", 0)
1080
+ flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_APPEND
1081
+ flags |= getattr(os, "O_CLOEXEC", 0)
1041
1082
  flags |= getattr(os, "O_NOFOLLOW", 0)
1042
1083
  try:
1043
1084
  log_descriptor = os.open(log_path, flags, 0o600)
@@ -1058,7 +1099,8 @@ def arm_observer(evidence_dir: Path, duration: int = 60) -> dict[str, Any]:
1058
1099
  else:
1059
1100
  process_options["start_new_session"] = True
1060
1101
  try:
1061
- with os.fdopen(log_descriptor, "wb") as log_output:
1102
+ with os.fdopen(log_descriptor, "w", encoding="utf-8") as log_output:
1103
+ _observer_startup_note("SPAWNING", log_output)
1062
1104
  process = subprocess.Popen(
1063
1105
  [
1064
1106
  sys.executable,
@@ -1077,18 +1119,24 @@ def arm_observer(evidence_dir: Path, duration: int = 60) -> dict[str, Any]:
1077
1119
  close_fds=True,
1078
1120
  **process_options,
1079
1121
  )
1122
+ _observer_startup_note("SPAWNED", log_output)
1080
1123
  _CHILD_PROCESSES[str(evidence)] = process
1081
1124
  except OSError as exc:
1082
1125
  raise LabError("observer process could not be started") from exc
1083
1126
 
1084
1127
  deadline = time.monotonic() + 5
1085
1128
  last_state: Optional[dict[str, Any]] = None
1129
+ noted_unreadable_state = False
1086
1130
  while time.monotonic() < deadline:
1087
1131
  try:
1088
1132
  last_state = _observer_state(evidence)
1089
1133
  except LabError:
1090
1134
  last_state = None
1135
+ if not noted_unreadable_state:
1136
+ _observer_arm_note(evidence, "ARM_STATE_UNREADABLE")
1137
+ noted_unreadable_state = True
1091
1138
  if last_state and last_state.get("status") == "READY":
1139
+ _observer_arm_note(evidence, "ARM_READY")
1092
1140
  return {
1093
1141
  "schema_version": SCHEMA_VERSION,
1094
1142
  "run_id": run["run_id"],
@@ -1098,22 +1146,26 @@ def arm_observer(evidence_dir: Path, duration: int = 60) -> dict[str, Any]:
1098
1146
  "duration_seconds": duration,
1099
1147
  }
1100
1148
  if last_state and last_state.get("status") == "FAILED":
1101
- process.wait(timeout=2)
1102
- _CHILD_PROCESSES.pop(str(evidence), None)
1149
+ _observer_arm_note(evidence, "ARM_FAILED")
1150
+ _reap_local_observer(evidence)
1103
1151
  raise LabError("observer failed its startup self-check")
1104
1152
  if process.poll() is not None:
1105
1153
  _CHILD_PROCESSES.pop(str(evidence), None)
1154
+ _observer_arm_note(evidence, "ARM_EXITED")
1106
1155
  raise LabError("observer exited before becoming ready")
1107
1156
  time.sleep(0.05)
1157
+ _observer_arm_note(evidence, "ARM_TIMEOUT")
1108
1158
  stop_path = evidence / "stop.request"
1109
1159
  if not stop_path.exists():
1110
1160
  try:
1111
1161
  _write_new_json(
1112
1162
  stop_path,
1113
- {"schema_version": SCHEMA_VERSION, "requested_at": _now()},
1163
+ {"schema_version": SCHEMA_VERSION, "requested_at": _now(),
1164
+ "reason": "OBSERVER_STARTUP_TIMEOUT"},
1114
1165
  )
1115
1166
  except LabError:
1116
1167
  pass
1168
+ _reap_local_observer(evidence)
1117
1169
  raise LabError("observer did not become ready in time")
1118
1170
 
1119
1171
 
@@ -2023,6 +2075,7 @@ class _LabRequestHandler(BaseHTTPRequestHandler):
2023
2075
 
2024
2076
 
2025
2077
  def run_observer(evidence_dir: Path, duration: int, supplied_token: str) -> int:
2078
+ _observer_startup_note("VALIDATING")
2026
2079
  evidence, run = _load_run(evidence_dir)
2027
2080
  control = _load_control(evidence, run)
2028
2081
  fixture = _validate_fixture(run, evidence)
@@ -2030,15 +2083,19 @@ def run_observer(evidence_dir: Path, duration: int, supplied_token: str) -> int:
2030
2083
  raise LabError("observer control token mismatch")
2031
2084
  if _observer_state(evidence) is not None:
2032
2085
  raise LabError("observer state already exists")
2086
+ _observer_startup_note("VALIDATED")
2033
2087
 
2034
2088
  started_at = _now()
2035
2089
  deadline = time.monotonic() + duration
2036
2090
  server: Optional[_LabHTTPServer] = None
2037
2091
  try:
2092
+ _check_observer_startup_stop(evidence)
2093
+ _observer_startup_note("BINDING")
2038
2094
  server = _LabHTTPServer(
2039
2095
  ("127.0.0.1", 0), _LabRequestHandler, evidence, run, fixture, control,
2040
2096
  str(control["route_token"]),
2041
2097
  )
2098
+ _observer_startup_note("BOUND")
2042
2099
  server.timeout = 0.25
2043
2100
  port = int(server.server_address[1])
2044
2101
  endpoint = {
@@ -2051,6 +2108,9 @@ def run_observer(evidence_dir: Path, duration: int, supplied_token: str) -> int:
2051
2108
  fixture / "bait" / "url.txt",
2052
2109
  f"http://127.0.0.1:{port}/canary/{control['route_token']}\n",
2053
2110
  )
2111
+ _observer_startup_note("ENDPOINT_WRITTEN")
2112
+ _check_observer_startup_stop(evidence)
2113
+ _observer_startup_note("PUBLISHING_READY")
2054
2114
  _append_event(
2055
2115
  evidence,
2056
2116
  {
@@ -2073,9 +2133,12 @@ def run_observer(evidence_dir: Path, duration: int, supplied_token: str) -> int:
2073
2133
  "duration_seconds": duration,
2074
2134
  }
2075
2135
  _write_observer_state(evidence, state)
2136
+ _observer_startup_note("READY")
2137
+ _check_observer_startup_stop(evidence, ready=True)
2076
2138
  next_heartbeat = time.monotonic() + 0.5
2077
2139
  while time.monotonic() < deadline:
2078
2140
  if (evidence / "stop.request").is_file():
2141
+ _check_observer_startup_stop(evidence, ready=True)
2079
2142
  _append_event(
2080
2143
  evidence,
2081
2144
  {
@@ -2113,7 +2176,9 @@ def run_observer(evidence_dir: Path, duration: int, supplied_token: str) -> int:
2113
2176
  state.update({"status": "EXPIRED", "heartbeat_at": _now(), "stopped_at": _now()})
2114
2177
  _write_observer_state(evidence, state)
2115
2178
  return 0
2116
- except Exception:
2179
+ except Exception as exc:
2180
+ cancelled = isinstance(exc, _ObserverStartupCancelled)
2181
+ _observer_startup_note("CANCELLED" if cancelled else "FAILED")
2117
2182
  try:
2118
2183
  _write_observer_state(
2119
2184
  evidence,
@@ -2124,11 +2189,14 @@ def run_observer(evidence_dir: Path, duration: int, supplied_token: str) -> int:
2124
2189
  "pid": os.getpid(),
2125
2190
  "started_at": started_at,
2126
2191
  "heartbeat_at": _now(),
2127
- "reason": "OBSERVER_RUNTIME_FAILURE",
2192
+ "reason": ("OBSERVER_STARTUP_CANCELLED" if cancelled
2193
+ else "OBSERVER_RUNTIME_FAILURE"),
2128
2194
  },
2129
2195
  )
2130
2196
  except Exception:
2131
2197
  pass
2198
+ if cancelled:
2199
+ return 1
2132
2200
  raise
2133
2201
  finally:
2134
2202
  if server is not None:
@@ -2391,6 +2459,8 @@ def observer_cli_main(argv: Optional[Sequence[str]] = None) -> int:
2391
2459
  try:
2392
2460
  return run_observer(arguments.evidence_dir, arguments.duration, supplied_token)
2393
2461
  except (LabError, OSError, ValueError):
2462
+ _observer_startup_note("FAILED")
2394
2463
  return 1
2395
2464
  except Exception:
2465
+ _observer_startup_note("FAILED")
2396
2466
  return 1
package/docs/README.md CHANGED
@@ -7,9 +7,11 @@ setup. The three main paths are [recovery protection](../skills/delete-guard/SKI
7
7
  [harness capability matrix](guides/harness-capabilities.md) for observed coverage
8
8
  and the [architecture](design/architecture.md) for the shared Core.
9
9
 
10
- Current source: [0.2.5-rc1 candidate](releases/release-notes-0.2.5-rc1.md).
10
+ Previous published RC baseline: [0.2.5-rc1](releases/release-notes-0.2.5-rc1.md).
11
11
  Published stable baseline: [0.2.4](releases/release-notes-0.2.4.md).
12
- Candidate preparation and package validation do not establish publication.
12
+ Current RC: [0.2.5-rc2](releases/release-notes-0.2.5-rc2.md),
13
+ including [shared audit metadata](guides/audit-metadata.md) and observer startup maintenance;
14
+ publication is established by its GitHub/npm receipts.
13
15
 
14
16
  先看入门指南,再按恢复保护、外发检测、Lab 验测选择入口。测试报告按所测版本与配置保留;发布记录、
15
17
  历史设计和外部案例各自归档,不能据此扩展当前产品的承诺。
@@ -31,6 +33,7 @@ Candidate preparation and package validation do not establish publication.
31
33
  | [Harness capabilities](guides/harness-capabilities.md) | 当前接入范围、证据等级与未验证路径 |
32
34
  | [Host drift](guides/host-drift.md) | 宿主版本、配置与本地基线检查 |
33
35
  | [Trash locations](guides/trash-index.md) | 0.2.4 的只读位置查询、Agent/前端共享 JSON 契约 |
36
+ | [Audit metadata](guides/audit-metadata.md) | RC2 候选的字段投影、会话关联、GC/status 契约与保留边界 |
34
37
  | [Publishing from ephemeral environments](guides/publishing-from-ephemeral-environments.md) | 临时环境中的 GitHub 发布操作参考 |
35
38
 
36
39
  Adapter setup remains in [adapters/](../adapters/INTEGRATION.md). Skill contracts
@@ -89,7 +92,8 @@ coverage rather than treating every historical result as current acceptance.
89
92
 
90
93
  | Document / 文档 | Scope / 范围 |
91
94
  |---|---|
92
- | [0.2.5-rc1](releases/release-notes-0.2.5-rc1.md) | 当前维护候选、文档整理、版本例外与验收状态 |
95
+ | [0.2.5-rc2](releases/release-notes-0.2.5-rc2.md) | 当前维护 RC;共享审计、observer 维护与兼容边界 |
96
+ | [0.2.5-rc1](releases/release-notes-0.2.5-rc1.md) | 已发布的维护预发布基线、文档整理与版本例外 |
93
97
  | [0.2.4](releases/release-notes-0.2.4.md) | 恢复维护、trash 查询及兼容性例外 |
94
98
  | [0.2.3](releases/release-notes-0.2.3.md) | 正式版范围与证据边界 |
95
99
  | [0.2.3-rc2](releases/release-notes-0.2.3-rc2.md) | 离线 Lab 与已复核 DSH 契约 |
@@ -23,6 +23,11 @@ the identity of the project.
23
23
  | Authorization | Who decides what? | `core/policy.py` (mode state machine) |
24
24
  | Auditability | What actually happened? | `core/audit.py` + `.agent-trash/*.jsonl` |
25
25
 
26
+ The 0.2.5-rc2 source candidate adds a shared
27
+ [audit metadata projection](../guides/audit-metadata.md) on append and legacy
28
+ read, with opaque session correlation. Recovery manifests retain exact paths;
29
+ authorization state and required audit durability remain separate contracts.
30
+
26
31
  A fifth, cross-cutting rule governs all four:
27
32
 
28
33
  > **Uncertainty increases restriction** (fail closed).
@@ -265,7 +270,7 @@ FORBIDDEN (BLOCK, never askable).
265
270
  targets outside the workspace neither leak nor block.
266
271
  6. **Self-exclusion with protected controls.** Ordinary unprotected payloads
267
272
  inside the selected quarantine use housekeeping rather than relocation.
268
- The 0.2.5-rc1 candidate checks root/control paths and storage parents first;
273
+ Protection introduced in 0.2.5-rc1 checks root/control paths and storage parents first;
269
274
  housekeeping cannot override protection. Opaque globs must be enumerated
270
275
  explicitly, and validated transaction purge uses the GC CLI.
271
276
  7. **Diagnostics do not silently become enforcement.** `guard-lab` records
@@ -300,10 +305,10 @@ order of value:
300
305
 
301
306
  ## Delivery status and design directions
302
307
 
303
- The current source candidate is 0.2.5-rc1; 0.2.4 remains the published stable
304
- baseline. The candidate contains the documented lifecycle/audit maintenance
305
- and exemption diagnostics, alongside a README/documentation reorganization.
306
- See [candidate notes](../releases/release-notes-0.2.5-rc1.md) and
308
+ The current RC source is 0.2.5-rc2, with publication checked by its receipts;
309
+ stable 0.2.4 and the previous prerelease 0.2.5-rc1 remain baselines. It retains RC1 maintenance and adds
310
+ shared audit metadata projection plus observer startup diagnosis/cancellation.
311
+ See [candidate notes](../releases/release-notes-0.2.5-rc2.md) and
307
312
  [compatibility](compatibility.md) for behaviour and validation boundaries.
308
313
 
309
314
  The milestones below describe historical delivery and future design scope,
@@ -4,6 +4,9 @@ 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
+ Current RC source is [0.2.5-rc2](../releases/release-notes-0.2.5-rc2.md); publication is checked by its receipts.
8
+ Versioned sections retain the origin of changes introduced by earlier releases.
9
+
7
10
  ## The adapter contract (frozen surface)
8
11
 
9
12
  Harness adapters integrate against exactly four things:
@@ -91,9 +94,40 @@ codes, phases and static outcome labels remain available. Free-form
91
94
  `--reason` stays accepted but is omitted from new audit events and
92
95
  `tx-start.meta`. Essential recovery paths/intents, CLI result fields,
93
96
  verdicts, exit codes and durability gates retain their behavior.
94
- Audit event shapes are not frozen. Historical records are not rewritten,
95
- and generic audit writers, automatic session identity and other output
96
- surfaces are unchanged. See the [writer contract](../../skills/delete-guard/references/policy.md#safe_delete-audit-metadata).
97
+ Audit event shapes are not frozen. At the released RC1 baseline, generic
98
+ audit/session handling is unchanged; the RC2 projection below
99
+ extends it. See the [writer contract](../../skills/delete-guard/references/policy.md#safe_delete-audit-metadata).
100
+
101
+ ### 0.2.5-rc2 shared audit metadata maintenance (source candidate)
102
+
103
+ `append` stores a closed metadata projection and returns the stored record;
104
+ `tail` projects legacy records without rewriting them, skips non-object JSON,
105
+ and returns no records for non-positive limits. Unknown/custom fields and
106
+ free text under allowed names are omitted. Audit shapes are not frozen, but
107
+ callers relying on arbitrary payload storage must adapt explicitly.
108
+
109
+ Session/display identities become deterministic opaque correlation. Generated
110
+ transaction/check IDs remain exact; noncanonical audit IDs become correlation
111
+ tags, and `find_by_txid` accepts the original spelling. Unknown GC selections
112
+ use digest metadata; CLI results and recovery journal IDs/paths remain exact.
113
+ Ordinary status actor display is projected without changing authorization
114
+ state or session selection. No decision/exit/flag semantics, manifest schema,
115
+ audit locations or durability gates change. This work is not included in the
116
+ published RC1; see the [full audit contract](../guides/audit-metadata.md).
117
+
118
+ ### 0.2.5-rc2 observer startup maintenance (source candidate)
119
+
120
+ The readiness window stays five seconds after spawn. Startup logs add static
121
+ phases and monotonic timestamps without tokens, paths or exception text.
122
+ They remain diagnostic and do not establish evidence health. Startup timeout
123
+ requests cooperative cancellation, then permits up to two seconds of local
124
+ child reaping; a live child remains registered without a forced signal.
125
+ Reap timeouts preserve the original LabError. Cancelled startup is
126
+ `FAILED` / `OBSERVER_STARTUP_CANCELLED` and `INCONCLUSIVE`, including late READY
127
+ publication; ordinary stops after accepted readiness retain their meaning.
128
+ Public CLI arguments, exit codes, evidence levels and loopback scope stay
129
+ unchanged. The first intermittent timeout's root cause is still unknown.
130
+ See the [Lab contract](../lab/guard-lab.md) and [RC2 notes](../releases/release-notes-0.2.5-rc2.md).
97
131
 
98
132
  ### 0.2.5-rc1 exemption configuration diagnostics (source candidate)
99
133
 
@@ -109,7 +143,7 @@ CLI warnings use stderr; JSON checker stdout and sanitizer payload/plan stdout
109
143
  keep their respective formats. Normal missing/valid configurations remain
110
144
  quiet. Diagnostic codes are configuration metadata, not Decision Protocol
111
145
  reason codes. Consumers should tolerate the additive fields and warnings;
112
- the manifest is 0.2.5-rc1, selected as a prerelease candidate. The diagnostic
146
+ these diagnostics originated in RC1 and remain in the RC2 source candidate. The diagnostic
113
147
  grammar and privacy contract are in [rules.md](../../skills/exfil-guard/references/rules.md#configuration-diagnostics).
114
148
 
115
149
  ### 0.2.0 check output minimization
@@ -228,7 +262,8 @@ with `restored_count`/`conflict_count`/`error_count`. Established IDs and backup
228
262
  attempt IDs stay correlated; invalid/unknown caller IDs use `txid_sha256`.
229
263
  Audit shapes beyond manifests are not frozen. CLI parameters, exit codes,
230
264
  recovery manifests and returned recovery paths/errors retain their roles.
231
- This is one writer's minimization, not general recursive audit sanitization.
265
+ That released change is one writer's minimization. The RC2 shared
266
+ projection is described above; it does not rewrite manifests or old log bytes.
232
267
 
233
268
  A changed default verdict for an existing shape is a **minor** release and
234
269
  requires an entry in [friction.md](../history/friction.md) - never a silent behaviour
@@ -244,7 +279,7 @@ whose *existing* verdict moved.
244
279
  | Attached or newline-separated destructive commands (`echo ok;rm ...`, `echo ok` followed by newline and `rm ...`) | Could miss the destructive segment | Classifies and applies its normal policy | POSIX command boundaries must be preserved by the lexer |
245
280
  | `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) |
246
281
  | 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) |
247
- | 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 (0.2.5-rc1 candidate, F26) |
282
+ | 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) |
248
283
 
249
284
  Unchanged on purpose: a genuine compensation fault (`git stash create`
250
285
  failing, a relocation that does not cover every target, an audit intent
@@ -0,0 +1,77 @@
1
+ # Audit metadata / 审计元信息
2
+
3
+ **Status: included in 0.2.5-rc2.** The published RC1
4
+ does not include this shared projection. Its restore/safe_delete writer
5
+ minimization remains documented in the [RC notes](../releases/release-notes-0.2.5-rc1.md).
6
+ See the [RC2 scope and evidence](../releases/release-notes-0.2.5-rc2.md).
7
+
8
+ `core.audit.append()` now persists supported metadata only and returns the
9
+ exact stored object. `tail()` applies the same projection to legacy objects
10
+ in memory. Neither function rewrites earlier log bytes or recovery manifests.
11
+ Callers must not use this log as storage for arbitrary payloads or custom
12
+ fields: unsupported names, free text and malformed values are omitted.
13
+
14
+ ## Supported evidence
15
+
16
+ | Metadata | Stored/read representation |
17
+ |---|---|
18
+ | Events, tools, decisions, reason codes, phases, outcomes | Reviewed labels from the current implementation; arbitrary strings and nested values are omitted |
19
+ | Timestamp | UTC `YYYY-MM-DDTHH:MM:SSZ` shape; a missing/invalid append timestamp gets the current time |
20
+ | Counts and flags | Nonnegative integers and actual booleans; latency also permits finite nonnegative floats |
21
+ | `txid`, `check_id`, `plan_id`, ID lists | Generated `YYYYMMDD-HHMMSS-xxxxxxxx` IDs remain exact; other nonempty spellings use `sha256:<digest>` correlation |
22
+ | `session` | Deterministic `sha256:<digest>` of a supplied identity; no raw username/hostname fallback |
23
+ | `compensations` | Strategy/status labels, transaction correlation, counts and a validated Git SHA (or `null`); nested payloads are omitted |
24
+ | `plan_reasons` | Transaction correlation mapped to `age`/`capacity` |
25
+ | Optional exfil records | Built-in rule/channel/family/confidence labels, numeric offsets/length, `span` and `exempted`; `key=<source name>` context becomes `key` |
26
+ | Command/error/reasons | Only the existing `<redacted>` command marker, static `compensation failed` diagnostic and empty reasons list can remain |
27
+
28
+ The full field/label set is in [core/audit.py](../../core/audit.py). Supporting
29
+ a new writer requires an explicit schema review; its fields are not retained
30
+ merely because they look safe. The projection does not scan or hash arbitrary
31
+ payload bodies. It is not a general recursive text sanitizer.
32
+
33
+ `tail(path, n)` skips corrupt/torn JSON and non-object JSON lines and keeps
34
+ the last `n` object records in bounded memory. Non-positive `n` returns an
35
+ empty list without reading the file. It still scans the file for positive
36
+ limits; unreadable files and invalid UTF-8 are not silently certified clean.
37
+
38
+ ## Correlation and visible status
39
+
40
+ A raw `AGENT_GUARD_SESSION` still selects the existing authorization state.
41
+ Only audit/display metadata changes. The same supplied session correlates
42
+ across CLI processes; without one, correlation is stable within a process
43
+ and differs between processes. Explicit record sessions take precedence.
44
+ Already-projected tags remain stable when read or re-appended.
45
+
46
+ `find_by_txid(path, original_id)` projects the lookup ID too, so legacy
47
+ noncanonical IDs remain findable in old and new records. A `sha256:` tag is
48
+ not a restore argument: obtain the original ID from the recovery manifest
49
+ or exact CLI result. Generated transaction IDs remain directly usable.
50
+
51
+ Normal `status` still provides a small recent-event summary. Its decision
52
+ statistics use projected reason codes; legacy free text under an allowed
53
+ field name is no longer copied into counts or text output. `mode_set_by`
54
+ uses opaque correlation and invalid display timestamps become `null`.
55
+ The state file, mode decisions and session selection are unchanged.
56
+
57
+ GC intent records keep known transaction correlation and `target_count`.
58
+ Unknown selected IDs are recorded in `missing_txid_sha256`; receipts add
59
+ `missing_count`, keep known missing IDs in `missing`, and retain `purged`.
60
+ GC reason maps cover selected transactions only. CLI missing-ID diagnostics
61
+ and results remain exact. Preflight and durable intent still precede purge.
62
+
63
+ ## Limits / 边界
64
+
65
+ 这批维护只收口共享审计存取、GC writer 和普通 status 的非恢复元信息。
66
+ 旧日志文件中的原始内容仍在;直接打开或转发文件不会经过投影。
67
+ manifest、准确恢复路径、CLI 目标/错误、隔离区位置查询和授权状态不是
68
+ 本投影的脱敏对象,仍可能含敏感文字。普通工具输出/流没有因此获得统一保护。
69
+
70
+ 摘要用于关联,不是加密、鉴权或秘密存储:低熵标识可被猜测,也可能跨记录关联。
71
+ 可信调用方仍须保证 ID、计数等事实正确;字段白名单不抵抗篡改或刻意编码。
72
+ 本次没有控制面签名、配置迁移、新依赖或新的拒绝策略。
73
+
74
+ Audit locking, flush/fsync and existing required-versus-best-effort writer
75
+ boundaries remain in place. An I/O failure can leave a partial or complete
76
+ line even when append raises; it never authorizes a required operation by
77
+ itself. Supported recovery is verified separately from audit projection.
@@ -10,8 +10,9 @@ Agent Guard 提供恢复保护、外发检测和用户控制的行为验测。
10
10
 
11
11
  ## Select the package root
12
12
 
13
- The published stable baseline is 0.2.4. The current source candidate is
14
- 0.2.5-rc1; see its [scope and status](../releases/release-notes-0.2.5-rc1.md).
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.
15
16
  Use a user-selected stable prefix for the published package:
16
17
 
17
18
  ```sh
@@ -20,10 +21,11 @@ npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-gua
20
21
 
21
22
  The package root is
22
23
  `/absolute/path/to/agent-guard-install/node_modules/@mokuyoaxis/agent-guard`.
23
- For the RC, select `@mokuyoaxis/agent-guard@0.2.5-rc1` explicitly and check its
24
- [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-rc1)
25
- or [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-rc1)
26
- for publication. Its reviewed checkout or local tarball is also usable.
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.
27
29
  Do not infer RC availability from the manifest or use an unscoped same-name
28
30
  package. A checkout's default branch can differ from a tagged stable release.
29
31
 
@@ -1,6 +1,6 @@
1
1
  # Harness capability and evidence matrix
2
2
 
3
- Current source: [0.2.5-rc1 candidate](../releases/release-notes-0.2.5-rc1.md).
3
+ Current RC source: [0.2.5-rc2](../releases/release-notes-0.2.5-rc2.md); publication is checked by its receipts.
4
4
  Rows below retain their tested source/host versions and do not automatically
5
5
  certify this candidate. Local regression or package checks are separate from
6
6
  new native-host/model evidence.
@@ -6,9 +6,10 @@ model tools and a prompt section; later entries cover Core and other adapters.
6
6
 
7
7
  Entries preserve their recording date and original candidate/release state.
8
8
  F21–F23 changes subsequently shipped in 0.2.3; F24–F25 shipped in 0.2.4.
9
- F26–F31 are now included in the 0.2.5-rc1 source candidate, with publication
10
- still separate. Current version scope is in the
11
- [candidate notes](../releases/release-notes-0.2.5-rc1.md); historical failures and
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
12
13
  test counts below are not rewritten by a later success.
13
14
 
14
15
  ## F1 · Compound `cd X && rm y` resolves targets against the wrong base
@@ -5,8 +5,9 @@ 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
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 the `0.2.5-rc1` source candidate;
9
- this candidate's documentation update does not add new model-trial evidence.
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).
10
11
 
11
12
  It is not a Skill for the tested agent, a security boundary, or a certificate
12
13
  that a model or vendor is safe or malicious.
@@ -215,6 +216,17 @@ matched bait IDs, and stage; it does not retain the input or matched value.
215
216
  Evidence is capped at 1024 events and a two MiB event log. Reaching a cap makes
216
217
  the observer/report inconclusive instead of silently dropping later events.
217
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
+
218
230
  The input file and `--stage` are user-selected evidence. `scan` does not parse
219
231
  or authenticate vendor-specific transcript schemas. If a captured stream mixes
220
232
  assistant messages, tool results, and system events, split those records first
@@ -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,6 +1,6 @@
1
1
  {
2
2
  "name": "@mokuyoaxis/agent-guard",
3
- "version": "0.2.5-rc1",
3
+ "version": "0.2.5-rc2",
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
  "main": "./adapters/dsh/lib/index.js",
@@ -105,11 +105,14 @@ undone. Use only a disposable fixture when verifying this behavior; the
105
105
  [policy reference](references/policy.md#assessment-and-dry-run-side-effects)
106
106
  defines the no-match, existing-ignore and external-bucket branches.
107
107
 
108
- In the 0.2.5-rc1 source candidate, new `safe_delete` audit events record decisions, target counts and established
108
+ Since 0.2.5-rc1, new `safe_delete` audit events record decisions, target counts and established
109
109
  recovery IDs/counts rather than target paths or free-form reasons. `--reason`
110
110
  is still accepted, but its text is not persisted in audit or transaction
111
111
  metadata. Exact recovery paths remain in the CLI result and manifest.
112
- Historical records and automatic session metadata are unchanged; see the
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
113
116
  [policy reference](references/policy.md#safe_delete-audit-metadata).
114
117
 
115
118
  ## Quarantine location queries
@@ -134,7 +137,7 @@ read just to answer a location/count question.
134
137
 
135
138
  ## RESTRICTED mode
136
139
 
137
- The 0.2.5-rc1 source candidate protects the quarantine root, root manifest,
140
+ The RC2 source retains RC1 protection for the quarantine root, root manifest,
138
141
  audit/state files, state temp file, sessions tree and storage access parents.
139
142
  Housekeeping does not override those checks. Use the existing explicit
140
143
  `gc.py --execute --txid <id>` entry for a validated, audited transaction purge.
@@ -6,8 +6,9 @@ native Windows harness execution remains unverified. POSIX hook bridges have
6
6
  their own platform requirements. See the
7
7
  [compatibility contract](../../../docs/design/compatibility.md).
8
8
 
9
- This reference describes the 0.2.5-rc1 source candidate. The published 0.2.4
10
- baseline does not include its control-path, GC and audit-writer maintenance.
9
+ This reference covers the 0.2.5-rc2 source candidate, including RC1 maintenance
10
+ and shared audit metadata projection. The published 0.2.4 baseline lacks the RC's
11
+ control-path, GC and audit-writer maintenance.
11
12
 
12
13
  ## Decision Protocol
13
14
 
@@ -88,7 +89,7 @@ different effects (`-wi`, `-c`, `-p`) stays unknown and BLOCKs.
88
89
 
89
90
  ## Rule table (first match wins)
90
91
 
91
- The quarantine control-path changes below belong to the 0.2.5-rc1 source candidate;
92
+ The quarantine control-path changes below were introduced in 0.2.5-rc1;
92
93
  the published 0.2.4 artifact retains its original housekeeping order.
93
94
 
94
95
  | # | Condition | Verdict code | Effect |
@@ -145,7 +146,7 @@ a portable fallback.
145
146
  |---|---|
146
147
  | `AGENT_GUARD_WORKSPACE` | override workspace boundary discovery |
147
148
  | `AGENT_GUARD_TRASH` | override quarantine location |
148
- | `AGENT_GUARD_SESSION` | session identity recorded in audit/manifest |
149
+ | `AGENT_GUARD_SESSION` | selects session authorization state; RC2 audit metadata uses opaque correlation |
149
150
  | `AGENT_GUARD_ARTIFACTS` | `os.pathsep`-joined extra artifact patterns |
150
151
  | `AGENT_GUARD_ALLOW_REGENERABLE` | `0` disables direct deletion of artifacts |
151
152
 
@@ -187,8 +188,9 @@ Restore audit metadata now records `restored_count`, `conflict_count` and
187
188
  `error_count` instead of raw path arrays/error bodies. Known `txid`, `force`,
188
189
  `ok` and preservation `backup_txids` retain correlation; invalid/unknown input
189
190
  IDs use `txid_sha256`. Exact restoration paths and errors remain in the
190
- recovery journal and CLI result. Historical audit lines are not rewritten;
191
- automatic session metadata and other generic audit writers are unchanged.
191
+ recovery journal and CLI result. Historical audit lines are not rewritten.
192
+ At released RC1, automatic session/generic handling is unchanged; the RC2
193
+ [shared projection](../../../docs/guides/audit-metadata.md) extends it.
192
194
 
193
195
  ### safe_delete audit metadata
194
196
 
@@ -212,9 +214,10 @@ accurate. Those surfaces can still contain sensitive text.
212
214
 
213
215
  Mutation intents remain durable before deletion; assessment and outcome
214
216
  audits retain their existing best-effort behavior. Historical audit lines
215
- and manifest metadata are not rewritten. Automatic `ts`/`session` fields
216
- and generic `core.audit.append`/`tail` behavior are unchanged; this writer's
217
- minimization is not a guarantee that every audit field is sanitized.
217
+ and manifest metadata are not rewritten. At released RC1, automatic session
218
+ and generic append/tail handling is unchanged. The later unreleased
219
+ [shared projection](../../../docs/guides/audit-metadata.md) limits these fields
220
+ and legacy reads, while raw historical files and recovery surfaces remain.
218
221
 
219
222
  Authority model: `gc.py --execute` is intentionally permitted
220
223
  non-interactively (scheduled maintenance is legitimate; purging
@@ -22,6 +22,7 @@ CODE_RELOCATE_FAILED_STORAGE.
22
22
  from __future__ import annotations
23
23
 
24
24
  import argparse
25
+ import hashlib
25
26
  import json
26
27
  import os
27
28
  import sys
@@ -76,13 +77,27 @@ def main() -> int:
76
77
  # Preflight both identity and audit durability before irreversible purge.
77
78
  # A failed final receipt still leaves this intent plus manifest tombstones.
78
79
  engine.validate_gc_targets(txids)
79
- audit.append({"event": "gc-intent", "txids": txids},
80
+ known = engine.transactions()
81
+
82
+ def selection_metadata(selected):
83
+ return {
84
+ "txids": [txid for txid in selected if txid in known],
85
+ "missing_txid_sha256": [hashlib.sha256(
86
+ txid.encode("utf-8", errors="surrogatepass")).hexdigest()
87
+ for txid in selected if txid not in known],
88
+ }
89
+
90
+ audit.append({"event": "gc-intent", "target_count": len(txids),
91
+ **selection_metadata(txids)},
80
92
  os.path.join(trash_root, AUDIT_NAME))
81
93
  report = engine.gc_execute(txids)
94
+ missing = selection_metadata(report["missing"])
82
95
  audit.append({"event": "gc", "action": "PURGED",
83
- "purged": report["purged"], "missing": report["missing"],
96
+ "purged": report["purged"], "missing": missing["txids"],
97
+ "missing_count": len(report["missing"]),
98
+ "missing_txid_sha256": missing["missing_txid_sha256"],
84
99
  "plan_reasons": {e["txid"]: e["reason"]
85
- for e in plan["eligible"]}},
100
+ for e in plan["eligible"] if e["txid"] in txids}},
86
101
  os.path.join(trash_root, AUDIT_NAME))
87
102
  if args.as_json:
88
103
  print(json.dumps({"mode": "execute", **report}, ensure_ascii=False,
@@ -64,7 +64,7 @@ def safe_delete_audit_event(event, decision, code, target_count, *,
64
64
 
65
65
  Codes and outcome labels come from this CLI. Transaction IDs come from
66
66
  the recovery engine; exact moved/skipped payloads stay in its journal
67
- and the CLI result. Automatic audit session metadata is unchanged.
67
+ and the CLI result. core.audit projects automatic session metadata.
68
68
  """
69
69
  entry = {"event": event, "tool": "safe_delete", "decision": decision,
70
70
  "code": code, "target_count": target_count}
@@ -81,6 +81,8 @@ def main() -> int:
81
81
  "AGENT_GUARD_TRASH", os.path.join(workspace, TRASH_DIRNAME))
82
82
  engine = recovery.RecoveryEngine(workspace, trash_root)
83
83
  state = policy.load_mode(trash_root)
84
+ # Project display-only identity/time metadata, never authorization state.
85
+ mode_metadata = audit.project({"ts": state["since"], "session": state["set_by"]})
84
86
  usage = engine.usage()
85
87
 
86
88
  stash_count = 0
@@ -96,8 +98,8 @@ def main() -> int:
96
98
  info = {
97
99
  "workspace": workspace,
98
100
  "mode": state["mode"],
99
- "mode_since": state["since"],
100
- "mode_set_by": state["set_by"],
101
+ "mode_since": mode_metadata.get("ts"),
102
+ "mode_set_by": mode_metadata.get("session"),
101
103
  "trash_root": trash_root,
102
104
  "usage": usage,
103
105
  "retention": {
@@ -118,7 +120,8 @@ def main() -> int:
118
120
 
119
121
  print(f"workspace : {info['workspace']}")
120
122
  print(f"mode : {info['mode']}"
121
- + (f" (since {state['since']} by {state['set_by']})" if state["since"] else ""))
123
+ + (f" (since {info['mode_since']} by {info['mode_set_by']})"
124
+ if info["mode_since"] else ""))
122
125
  print(f"quarantine: {trash_root}")
123
126
  print(f"usage : {usage['files']} files, {usage['bytes']} bytes, "
124
127
  f"{usage['transactions']} transactions "
@@ -140,8 +143,8 @@ def main() -> int:
140
143
 
141
144
 
142
145
  def audit_tail(trash_root, n):
143
- # Historical append-only records can contain raw commands. Never copy
144
- # their free-form fields into an agent-visible status result.
146
+ # core.audit projects both historical field names and values. Status
147
+ # exposes a smaller summary, with no session or compensation details.
145
148
  fields = ("ts", "event", "action", "decision", "code", "txid",
146
149
  "check_id", "guard_latency_ms")
147
150
  return [{key: record[key] for key in fields if key in record}
@@ -153,8 +156,7 @@ DECISION_EVENTS = {"check", "enforce-block", "enforce-proceed", "ask",
153
156
 
154
157
 
155
158
  def decision_stats(trash_root):
156
- """Local-only aggregation of recorded decisions (nothing leaves the
157
- machine). Counts reason codes across all decision-bearing events; ask
159
+ """Aggregate projected reason codes for the status result; ask
158
160
  OUTCOMES are not visible to the guard and are therefore not claimed
159
161
  here."""
160
162
  import collections
@@ -172,7 +172,7 @@ host-side file: read from the workspace root, not settable per call. If a
172
172
  scan hits something you believe is benign, report it - do not weaken the
173
173
  rule, and do not route around the guard.
174
174
 
175
- In the 0.2.5-rc1 source candidate, both configuration filenames use the same limited section/key grammar;
175
+ Since 0.2.5-rc1, both configuration filenames use the same limited section/key grammar;
176
176
  `.agent-guardignore` is not a gitignore file. The first readable UTF-8 file
177
177
  wins, including an empty or malformed preferred file. Inspect the checker's
178
178
  `exemption.source`, counts and diagnostics before assuming a configuration
@@ -186,7 +186,7 @@ facts still apply to variable templates.
186
186
 
187
187
  ## Configuration (environment)
188
188
 
189
- The 0.2.5-rc1 candidate adds provenance/count diagnostics to the existing
189
+ The RC2 source retains the provenance/count diagnostics introduced in RC1 for the existing
190
190
  exemption parser. Matching and file priority remain unchanged; the published
191
191
  0.2.4 package does not include these diagnostic fields and warnings.
192
192
 
@@ -306,8 +306,11 @@ corpus.
306
306
  This is a safe record shape for a trusted integration that chooses to persist
307
307
  egress evidence. `check_span.py` and `sanitize.py` do not automatically append
308
308
  these events, and cannot observe a caller declining a plan. It is not a claim
309
- that every egress decision has a durable record. Generic `core.audit` also adds
310
- session metadata; that metadata and existing logs require their own review.
309
+ that every egress decision has a durable record. The RC2 source candidate
310
+ projects supported metadata on append/read, including opaque session
311
+ correlation and value-free source-key context. See the
312
+ [shared audit contract](../../../docs/guides/audit-metadata.md); direct reads of
313
+ old log bytes and other output channels remain outside that projection.
311
314
 
312
315
  ```json
313
316
  {"event":"exfil-sanitize","rule_id":"secret/openai-key",