@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 +18 -9
- package/README.zh-CN.md +14 -8
- package/core/audit.py +170 -25
- package/core/lab.py +77 -7
- package/docs/README.md +7 -3
- package/docs/design/architecture.md +10 -5
- package/docs/design/compatibility.md +41 -6
- package/docs/guides/audit-metadata.md +77 -0
- package/docs/guides/getting-started.md +8 -6
- package/docs/guides/harness-capabilities.md +1 -1
- package/docs/history/friction.md +4 -3
- package/docs/lab/guard-lab.md +14 -2
- package/docs/releases/release-notes-0.2.5-rc2.md +101 -0
- package/guard_lab.py +11 -0
- package/package.json +1 -1
- package/skills/delete-guard/SKILL.md +6 -3
- package/skills/delete-guard/references/policy.md +12 -9
- package/skills/delete-guard/scripts/gc.py +18 -3
- package/skills/delete-guard/scripts/safe_delete.py +1 -1
- package/skills/delete-guard/scripts/status.py +9 -7
- package/skills/exfil-guard/SKILL.md +1 -1
- package/skills/exfil-guard/references/rules.md +6 -3
package/README.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
[](https://www.npmjs.com/package/@mokuyoaxis/agent-guard)
|
|
5
5
|
[](LICENSE)
|
|
6
6
|
[](https://www.python.org/)
|
|
7
|
-
[](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) |
|
|
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
|
|
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-
|
|
98
|
-
|
|
99
|
-
for publication. A reviewed checkout or
|
|
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
|
-
|
|
126
|
-
from active GC planning, and
|
|
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-
|
|
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
|
[](https://www.npmjs.com/package/@mokuyoaxis/agent-guard)
|
|
5
5
|
[](LICENSE)
|
|
6
6
|
[](https://www.python.org/)
|
|
7
|
-
[](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) |
|
|
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
|
-
|
|
85
|
-
发布状态以 [GitHub Release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-
|
|
86
|
-
和 [npm 版本页](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-
|
|
87
|
-
也可使用已核查的 checkout
|
|
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
|
-
|
|
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-
|
|
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
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
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
|
|
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
|
|
16
|
+
import re
|
|
14
17
|
import threading
|
|
15
18
|
import time
|
|
16
19
|
import uuid
|
|
17
|
-
from typing import Any, Dict, List
|
|
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
|
-
"""
|
|
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
|
-
|
|
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
|
|
52
|
-
stored =
|
|
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
|
-
"""
|
|
69
|
-
|
|
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
|
|
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
|
-
|
|
219
|
+
record = json.loads(raw)
|
|
79
220
|
except json.JSONDecodeError:
|
|
80
221
|
continue
|
|
81
|
-
|
|
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
|
-
|
|
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 |
|
|
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, "
|
|
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
|
-
|
|
1102
|
-
|
|
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": "
|
|
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
|
-
|
|
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
|
-
|
|
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-
|
|
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
|
-
|
|
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
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
See [candidate notes](../releases/release-notes-0.2.5-
|
|
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.
|
|
95
|
-
|
|
96
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
14
|
-
0.2.5-rc1
|
|
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
|
|
24
|
-
[GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-
|
|
25
|
-
|
|
26
|
-
for publication.
|
|
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-
|
|
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.
|
package/docs/history/friction.md
CHANGED
|
@@ -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
|
|
10
|
-
|
|
11
|
-
|
|
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
|
package/docs/lab/guard-lab.md
CHANGED
|
@@ -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
|
|
9
|
-
|
|
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-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
10
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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.
|
|
216
|
-
and generic
|
|
217
|
-
|
|
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
|
-
|
|
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":
|
|
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.
|
|
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":
|
|
100
|
-
"mode_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 {
|
|
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
|
-
#
|
|
144
|
-
#
|
|
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
|
-
"""
|
|
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
|
-
|
|
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
|
|
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.
|
|
310
|
-
|
|
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",
|