@mokuyoaxis/agent-guard 0.2.5-rc1 → 0.2.5-rc3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/CONTRIBUTING.md +24 -0
  2. package/README.md +43 -10
  3. package/README.zh-CN.md +35 -9
  4. package/SECURITY.md +14 -8
  5. package/adapters/dsh/harness/README.md +5 -0
  6. package/adapters/dsh/harness/guard_lab.py +3 -2
  7. package/adapters/kimi-code/harness/README.md +5 -0
  8. package/core/audit.py +170 -25
  9. package/core/lab.py +82 -9
  10. package/docs/README.md +20 -4
  11. package/docs/design/architecture.md +12 -5
  12. package/docs/design/compatibility.md +48 -6
  13. package/docs/guides/audit-metadata.md +77 -0
  14. package/docs/guides/getting-started.md +13 -6
  15. package/docs/guides/harness-capabilities.md +7 -1
  16. package/docs/history/friction.md +4 -3
  17. package/docs/lab/blue-team-calibration.md +45 -0
  18. package/docs/lab/examples/blue-team-calibration.py +53 -0
  19. package/docs/lab/guard-lab.md +20 -2
  20. package/docs/releases/release-notes-0.2.5-rc2.md +101 -0
  21. package/docs/releases/release-notes-0.2.5-rc3.md +74 -0
  22. package/docs/reports/blue-team-lab-2026-10.md +73 -0
  23. package/docs/research/README.md +41 -0
  24. package/docs/research/content-authorization.md +54 -0
  25. package/docs/research/dataflow-observability.md +48 -0
  26. package/docs/research/delegation-provenance.md +56 -0
  27. package/docs/research/evaluation-method.md +51 -0
  28. package/docs/research/lab-observations-2026-10.json +43 -0
  29. package/guard_lab.py +11 -0
  30. package/package.json +1 -1
  31. package/skills/delete-guard/SKILL.md +6 -3
  32. package/skills/delete-guard/references/policy.md +14 -10
  33. package/skills/delete-guard/scripts/gc.py +18 -3
  34. package/skills/delete-guard/scripts/safe_delete.py +1 -1
  35. package/skills/delete-guard/scripts/status.py +9 -7
  36. package/skills/exfil-guard/SKILL.md +1 -1
  37. package/skills/exfil-guard/references/rules.md +6 -3
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
 
@@ -767,14 +772,17 @@ def prepare_run(
767
772
  task_file: Optional[Path] = None,
768
773
  attack_sample: str = "direct-v1",
769
774
  non_guard_configuration_sha256: Optional[str] = None,
775
+ *,
776
+ _injection_samples: Optional[dict] = None,
770
777
  ) -> dict[str, Any]:
778
+ samples = INJECTION_SAMPLES if _injection_samples is None else _injection_samples
771
779
  if case_id not in CASE_DEFINITIONS:
772
780
  raise LabError("unknown lab case")
773
- if attack_sample not in INJECTION_SAMPLES:
781
+ if attack_sample not in samples:
774
782
  raise LabError("unknown injection sample")
775
783
  if case_id != "injection-probe" and attack_sample != "direct-v1":
776
784
  raise LabError("attack samples apply only to injection-probe")
777
- sample = INJECTION_SAMPLES[attack_sample]
785
+ sample = samples[attack_sample]
778
786
  sample_identity = {
779
787
  "id": attack_sample,
780
788
  "template_sha256": _sha256_bytes(_canonical_bytes(sample)),
@@ -1026,6 +1034,41 @@ def _write_observer_state(evidence: Path, state: dict[str, Any]) -> None:
1026
1034
  _atomic_write_json(evidence / "observer.json", state)
1027
1035
 
1028
1036
 
1037
+ def _observer_startup_note(stage: str, stream: Any = None) -> None:
1038
+ # Static phases and monotonic time only: never log tokens, paths or errors.
1039
+ try:
1040
+ print(
1041
+ f"observer-startup stage={stage} monotonic={time.monotonic():.6f}",
1042
+ file=sys.stderr if stream is None else stream,
1043
+ flush=True,
1044
+ )
1045
+ except (OSError, ValueError):
1046
+ pass # Diagnosis must not determine the observer's health.
1047
+
1048
+
1049
+ def _observer_arm_note(evidence: Path, stage: str) -> None:
1050
+ flags = os.O_WRONLY | os.O_APPEND | getattr(os, "O_CLOEXEC", 0)
1051
+ flags |= getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0)
1052
+ try:
1053
+ descriptor = os.open(evidence / "observer.log", flags)
1054
+ with os.fdopen(descriptor, "a", encoding="utf-8") as output:
1055
+ if stat.S_ISREG(os.fstat(output.fileno()).st_mode):
1056
+ _observer_startup_note(stage, output)
1057
+ except OSError:
1058
+ pass
1059
+
1060
+
1061
+ def _check_observer_startup_stop(evidence: Path, *, ready: bool = False) -> None:
1062
+ stop_path = evidence / "stop.request"
1063
+ if not stop_path.is_file():
1064
+ return
1065
+ if ready:
1066
+ stop = _read_json(stop_path, "observer stop request")
1067
+ if stop.get("reason") != "OBSERVER_STARTUP_TIMEOUT":
1068
+ return # An ordinary stop after READY keeps its existing meaning.
1069
+ raise _ObserverStartupCancelled("observer startup was cancelled")
1070
+
1071
+
1029
1072
  def arm_observer(evidence_dir: Path, duration: int = 60) -> dict[str, Any]:
1030
1073
  if duration < MIN_DURATION_SECONDS or duration > MAX_DURATION_SECONDS:
1031
1074
  raise LabError("observer duration is outside the supported range")
@@ -1037,7 +1080,8 @@ def arm_observer(evidence_dir: Path, duration: int = 60) -> dict[str, Any]:
1037
1080
  raise LabError("observer has already been armed for this run")
1038
1081
 
1039
1082
  log_path = evidence / "observer.log"
1040
- flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_CLOEXEC", 0)
1083
+ flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_APPEND
1084
+ flags |= getattr(os, "O_CLOEXEC", 0)
1041
1085
  flags |= getattr(os, "O_NOFOLLOW", 0)
1042
1086
  try:
1043
1087
  log_descriptor = os.open(log_path, flags, 0o600)
@@ -1058,7 +1102,8 @@ def arm_observer(evidence_dir: Path, duration: int = 60) -> dict[str, Any]:
1058
1102
  else:
1059
1103
  process_options["start_new_session"] = True
1060
1104
  try:
1061
- with os.fdopen(log_descriptor, "wb") as log_output:
1105
+ with os.fdopen(log_descriptor, "w", encoding="utf-8") as log_output:
1106
+ _observer_startup_note("SPAWNING", log_output)
1062
1107
  process = subprocess.Popen(
1063
1108
  [
1064
1109
  sys.executable,
@@ -1077,18 +1122,24 @@ def arm_observer(evidence_dir: Path, duration: int = 60) -> dict[str, Any]:
1077
1122
  close_fds=True,
1078
1123
  **process_options,
1079
1124
  )
1125
+ _observer_startup_note("SPAWNED", log_output)
1080
1126
  _CHILD_PROCESSES[str(evidence)] = process
1081
1127
  except OSError as exc:
1082
1128
  raise LabError("observer process could not be started") from exc
1083
1129
 
1084
1130
  deadline = time.monotonic() + 5
1085
1131
  last_state: Optional[dict[str, Any]] = None
1132
+ noted_unreadable_state = False
1086
1133
  while time.monotonic() < deadline:
1087
1134
  try:
1088
1135
  last_state = _observer_state(evidence)
1089
1136
  except LabError:
1090
1137
  last_state = None
1138
+ if not noted_unreadable_state:
1139
+ _observer_arm_note(evidence, "ARM_STATE_UNREADABLE")
1140
+ noted_unreadable_state = True
1091
1141
  if last_state and last_state.get("status") == "READY":
1142
+ _observer_arm_note(evidence, "ARM_READY")
1092
1143
  return {
1093
1144
  "schema_version": SCHEMA_VERSION,
1094
1145
  "run_id": run["run_id"],
@@ -1098,22 +1149,26 @@ def arm_observer(evidence_dir: Path, duration: int = 60) -> dict[str, Any]:
1098
1149
  "duration_seconds": duration,
1099
1150
  }
1100
1151
  if last_state and last_state.get("status") == "FAILED":
1101
- process.wait(timeout=2)
1102
- _CHILD_PROCESSES.pop(str(evidence), None)
1152
+ _observer_arm_note(evidence, "ARM_FAILED")
1153
+ _reap_local_observer(evidence)
1103
1154
  raise LabError("observer failed its startup self-check")
1104
1155
  if process.poll() is not None:
1105
1156
  _CHILD_PROCESSES.pop(str(evidence), None)
1157
+ _observer_arm_note(evidence, "ARM_EXITED")
1106
1158
  raise LabError("observer exited before becoming ready")
1107
1159
  time.sleep(0.05)
1160
+ _observer_arm_note(evidence, "ARM_TIMEOUT")
1108
1161
  stop_path = evidence / "stop.request"
1109
1162
  if not stop_path.exists():
1110
1163
  try:
1111
1164
  _write_new_json(
1112
1165
  stop_path,
1113
- {"schema_version": SCHEMA_VERSION, "requested_at": _now()},
1166
+ {"schema_version": SCHEMA_VERSION, "requested_at": _now(),
1167
+ "reason": "OBSERVER_STARTUP_TIMEOUT"},
1114
1168
  )
1115
1169
  except LabError:
1116
1170
  pass
1171
+ _reap_local_observer(evidence)
1117
1172
  raise LabError("observer did not become ready in time")
1118
1173
 
1119
1174
 
@@ -2023,6 +2078,7 @@ class _LabRequestHandler(BaseHTTPRequestHandler):
2023
2078
 
2024
2079
 
2025
2080
  def run_observer(evidence_dir: Path, duration: int, supplied_token: str) -> int:
2081
+ _observer_startup_note("VALIDATING")
2026
2082
  evidence, run = _load_run(evidence_dir)
2027
2083
  control = _load_control(evidence, run)
2028
2084
  fixture = _validate_fixture(run, evidence)
@@ -2030,15 +2086,19 @@ def run_observer(evidence_dir: Path, duration: int, supplied_token: str) -> int:
2030
2086
  raise LabError("observer control token mismatch")
2031
2087
  if _observer_state(evidence) is not None:
2032
2088
  raise LabError("observer state already exists")
2089
+ _observer_startup_note("VALIDATED")
2033
2090
 
2034
2091
  started_at = _now()
2035
2092
  deadline = time.monotonic() + duration
2036
2093
  server: Optional[_LabHTTPServer] = None
2037
2094
  try:
2095
+ _check_observer_startup_stop(evidence)
2096
+ _observer_startup_note("BINDING")
2038
2097
  server = _LabHTTPServer(
2039
2098
  ("127.0.0.1", 0), _LabRequestHandler, evidence, run, fixture, control,
2040
2099
  str(control["route_token"]),
2041
2100
  )
2101
+ _observer_startup_note("BOUND")
2042
2102
  server.timeout = 0.25
2043
2103
  port = int(server.server_address[1])
2044
2104
  endpoint = {
@@ -2051,6 +2111,9 @@ def run_observer(evidence_dir: Path, duration: int, supplied_token: str) -> int:
2051
2111
  fixture / "bait" / "url.txt",
2052
2112
  f"http://127.0.0.1:{port}/canary/{control['route_token']}\n",
2053
2113
  )
2114
+ _observer_startup_note("ENDPOINT_WRITTEN")
2115
+ _check_observer_startup_stop(evidence)
2116
+ _observer_startup_note("PUBLISHING_READY")
2054
2117
  _append_event(
2055
2118
  evidence,
2056
2119
  {
@@ -2073,9 +2136,12 @@ def run_observer(evidence_dir: Path, duration: int, supplied_token: str) -> int:
2073
2136
  "duration_seconds": duration,
2074
2137
  }
2075
2138
  _write_observer_state(evidence, state)
2139
+ _observer_startup_note("READY")
2140
+ _check_observer_startup_stop(evidence, ready=True)
2076
2141
  next_heartbeat = time.monotonic() + 0.5
2077
2142
  while time.monotonic() < deadline:
2078
2143
  if (evidence / "stop.request").is_file():
2144
+ _check_observer_startup_stop(evidence, ready=True)
2079
2145
  _append_event(
2080
2146
  evidence,
2081
2147
  {
@@ -2113,7 +2179,9 @@ def run_observer(evidence_dir: Path, duration: int, supplied_token: str) -> int:
2113
2179
  state.update({"status": "EXPIRED", "heartbeat_at": _now(), "stopped_at": _now()})
2114
2180
  _write_observer_state(evidence, state)
2115
2181
  return 0
2116
- except Exception:
2182
+ except Exception as exc:
2183
+ cancelled = isinstance(exc, _ObserverStartupCancelled)
2184
+ _observer_startup_note("CANCELLED" if cancelled else "FAILED")
2117
2185
  try:
2118
2186
  _write_observer_state(
2119
2187
  evidence,
@@ -2124,11 +2192,14 @@ def run_observer(evidence_dir: Path, duration: int, supplied_token: str) -> int:
2124
2192
  "pid": os.getpid(),
2125
2193
  "started_at": started_at,
2126
2194
  "heartbeat_at": _now(),
2127
- "reason": "OBSERVER_RUNTIME_FAILURE",
2195
+ "reason": ("OBSERVER_STARTUP_CANCELLED" if cancelled
2196
+ else "OBSERVER_RUNTIME_FAILURE"),
2128
2197
  },
2129
2198
  )
2130
2199
  except Exception:
2131
2200
  pass
2201
+ if cancelled:
2202
+ return 1
2132
2203
  raise
2133
2204
  finally:
2134
2205
  if server is not None:
@@ -2391,6 +2462,8 @@ def observer_cli_main(argv: Optional[Sequence[str]] = None) -> int:
2391
2462
  try:
2392
2463
  return run_observer(arguments.evidence_dir, arguments.duration, supplied_token)
2393
2464
  except (LabError, OSError, ValueError):
2465
+ _observer_startup_note("FAILED")
2394
2466
  return 1
2395
2467
  except Exception:
2468
+ _observer_startup_note("FAILED")
2396
2469
  return 1
package/docs/README.md CHANGED
@@ -7,9 +7,12 @@ 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
+ Published RC baseline: [0.2.5-rc2](releases/release-notes-0.2.5-rc2.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
+ Source candidate: [0.2.5-rc3](releases/release-notes-0.2.5-rc3.md), with
13
+ [blue-team research](research/README.md) and a [four-control example](lab/blue-team-calibration.md).
14
+ Evaluate the source preview through a reviewed checkout or tarball;
15
+ GitHub/npm package publication needs separate versioned receipts.
13
16
 
14
17
  先看入门指南,再按恢复保护、外发检测、Lab 验测选择入口。测试报告按所测版本与配置保留;发布记录、
15
18
  历史设计和外部案例各自归档,不能据此扩展当前产品的承诺。
@@ -18,7 +21,8 @@ Candidate preparation and package validation do not establish publication.
18
21
  |---|---|
19
22
  | [Guides](#guides) / 使用指南 | 宿主接入证据、漂移检查、维护者发布指南 |
20
23
  | [Design](#design) / 架构与契约 | 当前架构、威胁模型与兼容契约 |
21
- | [Lab](#lab) / 实验与候选素材 | Lab 流程、任务模板、外部攻击案例 |
24
+ | [Lab](#lab) / 防守验测 | 校准流程、任务模板及历史候选参考 |
25
+ | [Research](#research) / 防守研究 | 来源、发送授权、父子代理与正常任务评分 |
22
26
  | [Reports](#reports) / 测试报告 | 按宿主、版本和观察范围记录的证据 |
23
27
  | [Releases](#releases) / 发布记录 | 正式版与预览版各自的范围 |
24
28
  | [History](#history) / 历史设计与经验 | 早期设计、实现教训和事故探索 |
@@ -31,6 +35,7 @@ Candidate preparation and package validation do not establish publication.
31
35
  | [Harness capabilities](guides/harness-capabilities.md) | 当前接入范围、证据等级与未验证路径 |
32
36
  | [Host drift](guides/host-drift.md) | 宿主版本、配置与本地基线检查 |
33
37
  | [Trash locations](guides/trash-index.md) | 0.2.4 的只读位置查询、Agent/前端共享 JSON 契约 |
38
+ | [Audit metadata](guides/audit-metadata.md) | RC2 引入的字段投影、会话关联、GC/status 契约与保留边界 |
34
39
  | [Publishing from ephemeral environments](guides/publishing-from-ephemeral-environments.md) | 临时环境中的 GitHub 发布操作参考 |
35
40
 
36
41
  Adapter setup remains in [adapters/](../adapters/INTEGRATION.md). Skill contracts
@@ -49,6 +54,7 @@ remain in [skills/](../skills/delete-guard/SKILL.md).
49
54
  | Document / 文档 | Scope / 范围 |
50
55
  |---|---|
51
56
  | [Guard Lab guide](lab/guard-lab.md) | 操作流程、信道、L0/L1/L2 语义与限制 |
57
+ | [Blue-team calibration](lab/blue-team-calibration.md) | 可从 checkout/包运行的四种零模型控制 |
52
58
  | [Clean task](lab/tasks/guard-lab-clean-task.md) | 干净对照任务模板 |
53
59
  | [Injection trial task](lab/tasks/guard-lab-trial-task.md) | 提示注入试次任务模板 |
54
60
  | [Native-read trial task](lab/tasks/guard-lab-read-trial-task.md) | 原生读取脱敏任务模板 |
@@ -58,6 +64,13 @@ Task templates and external case references are separate from completed test
58
64
  reports. A scripted provider checks host behavior; a real-model injection
59
65
  trial needs an effective unguarded baseline before a matched comparison.
60
66
 
67
+ ## Research
68
+
69
+ [研究导航](research/README.md)汇总本项目防守研究的整理稿:
70
+ 数据流观察、正文发送授权、父子来源与独立评分。私有实验方法、公开校准入口与生产
71
+ 覆盖分别说明。Lab 小规模推进,欢迎 fork、PR 与独立复现;公开资料不包含诱导载荷
72
+ 或私有运行原件。
73
+
61
74
  ## Reports
62
75
 
63
76
  Each report preserves its original version, configuration, result and limits.
@@ -66,6 +79,7 @@ coverage rather than treating every historical result as current acceptance.
66
79
 
67
80
  | Document / 文档 | Scope / 范围 |
68
81
  |---|---|
82
+ | [Blue-team Lab, October 2026](reports/blue-team-lab-2026-10.md) | 来源/发送授权/任务效用与失败的去敏阶段摘要;不升级正式证据等级 |
69
83
  | [0.2.3 contract review](reports/test-report-release-readiness-0.2.3.md) | 发布前契约复核与 DSH 原生验收 |
70
84
  | [0.2.4 official Flash / PTC](reports/test-report-dsh-0.2.4-ptc.md) | 实模主/子代理碰撞拒绝;原始主 PTC 任务失败与独立收尾分别记录 |
71
85
  | [Claude Code harness](reports/test-report-claude-code-harness.md) | 脚本模型驱动的真实宿主 hook 验证 |
@@ -89,7 +103,9 @@ coverage rather than treating every historical result as current acceptance.
89
103
 
90
104
  | Document / 文档 | Scope / 范围 |
91
105
  |---|---|
92
- | [0.2.5-rc1](releases/release-notes-0.2.5-rc1.md) | 当前维护候选、文档整理、版本例外与验收状态 |
106
+ | [0.2.5-rc3](releases/release-notes-0.2.5-rc3.md) | 蓝队研究/文档源码候选与零模型示例;包发布另行核查 |
107
+ | [0.2.5-rc2](releases/release-notes-0.2.5-rc2.md) | 已发布的维护 RC;共享审计、observer 维护与兼容边界 |
108
+ | [0.2.5-rc1](releases/release-notes-0.2.5-rc1.md) | 已发布的维护预发布基线、文档整理与版本例外 |
93
109
  | [0.2.4](releases/release-notes-0.2.4.md) | 恢复维护、trash 查询及兼容性例外 |
94
110
  | [0.2.3](releases/release-notes-0.2.3.md) | 正式版范围与证据边界 |
95
111
  | [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
+ Release 0.2.5-rc2 introduced 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,12 @@ 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 source candidate is 0.2.5-rc3; stable 0.2.4 and published RC2 remain
309
+ baselines. It retains the recovery, shared audit and observer maintenance,
310
+ and adds [defensive research](../research/README.md) plus an example using the
311
+ existing zero-model controls. Private research methods do not add a general
312
+ authorization service or new production enforcement point.
313
+ See [candidate notes](../releases/release-notes-0.2.5-rc3.md) and
307
314
  [compatibility](compatibility.md) for behaviour and validation boundaries.
308
315
 
309
316
  The milestones below describe historical delivery and future design scope,
@@ -4,6 +4,16 @@ 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 source candidate is [0.2.5-rc3](../releases/release-notes-0.2.5-rc3.md);
8
+ the published RC baseline is [0.2.5-rc2](../releases/release-notes-0.2.5-rc2.md).
9
+ Versioned sections retain the origin of changes introduced by earlier releases.
10
+
11
+ RC3 publishes defensive research and an example around the existing four
12
+ zero-model controls. Experimental disclosure labels and private delegation
13
+ methods are not additions to the Decision Protocol or native-hook contract.
14
+ No production dependency, policy verdict or storage/configuration migration
15
+ is introduced by this preparation.
16
+
7
17
  ## The adapter contract (frozen surface)
8
18
 
9
19
  Harness adapters integrate against exactly four things:
@@ -91,9 +101,40 @@ codes, phases and static outcome labels remain available. Free-form
91
101
  `--reason` stays accepted but is omitted from new audit events and
92
102
  `tx-start.meta`. Essential recovery paths/intents, CLI result fields,
93
103
  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).
104
+ Audit event shapes are not frozen. At the released RC1 baseline, generic
105
+ audit/session handling is unchanged; the RC2 projection below
106
+ extends it. See the [writer contract](../../skills/delete-guard/references/policy.md#safe_delete-audit-metadata).
107
+
108
+ ### 0.2.5-rc2 shared audit metadata maintenance (source candidate)
109
+
110
+ `append` stores a closed metadata projection and returns the stored record;
111
+ `tail` projects legacy records without rewriting them, skips non-object JSON,
112
+ and returns no records for non-positive limits. Unknown/custom fields and
113
+ free text under allowed names are omitted. Audit shapes are not frozen, but
114
+ callers relying on arbitrary payload storage must adapt explicitly.
115
+
116
+ Session/display identities become deterministic opaque correlation. Generated
117
+ transaction/check IDs remain exact; noncanonical audit IDs become correlation
118
+ tags, and `find_by_txid` accepts the original spelling. Unknown GC selections
119
+ use digest metadata; CLI results and recovery journal IDs/paths remain exact.
120
+ Ordinary status actor display is projected without changing authorization
121
+ state or session selection. No decision/exit/flag semantics, manifest schema,
122
+ audit locations or durability gates change. This work is not included in the
123
+ published RC1; see the [full audit contract](../guides/audit-metadata.md).
124
+
125
+ ### 0.2.5-rc2 observer startup maintenance (source candidate)
126
+
127
+ The readiness window stays five seconds after spawn. Startup logs add static
128
+ phases and monotonic timestamps without tokens, paths or exception text.
129
+ They remain diagnostic and do not establish evidence health. Startup timeout
130
+ requests cooperative cancellation, then permits up to two seconds of local
131
+ child reaping; a live child remains registered without a forced signal.
132
+ Reap timeouts preserve the original LabError. Cancelled startup is
133
+ `FAILED` / `OBSERVER_STARTUP_CANCELLED` and `INCONCLUSIVE`, including late READY
134
+ publication; ordinary stops after accepted readiness retain their meaning.
135
+ Public CLI arguments, exit codes, evidence levels and loopback scope stay
136
+ unchanged. The first intermittent timeout's root cause is still unknown.
137
+ See the [Lab contract](../lab/guard-lab.md) and [RC2 notes](../releases/release-notes-0.2.5-rc2.md).
97
138
 
98
139
  ### 0.2.5-rc1 exemption configuration diagnostics (source candidate)
99
140
 
@@ -109,7 +150,7 @@ CLI warnings use stderr; JSON checker stdout and sanitizer payload/plan stdout
109
150
  keep their respective formats. Normal missing/valid configurations remain
110
151
  quiet. Diagnostic codes are configuration metadata, not Decision Protocol
111
152
  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
153
+ these diagnostics originated in RC1 and are retained by RC2 and RC3. The diagnostic
113
154
  grammar and privacy contract are in [rules.md](../../skills/exfil-guard/references/rules.md#configuration-diagnostics).
114
155
 
115
156
  ### 0.2.0 check output minimization
@@ -228,7 +269,8 @@ with `restored_count`/`conflict_count`/`error_count`. Established IDs and backup
228
269
  attempt IDs stay correlated; invalid/unknown caller IDs use `txid_sha256`.
229
270
  Audit shapes beyond manifests are not frozen. CLI parameters, exit codes,
230
271
  recovery manifests and returned recovery paths/errors retain their roles.
231
- This is one writer's minimization, not general recursive audit sanitization.
272
+ That released change is one writer's minimization. The RC2 shared
273
+ projection is described above; it does not rewrite manifests or old log bytes.
232
274
 
233
275
  A changed default verdict for an existing shape is a **minor** release and
234
276
  requires an entry in [friction.md](../history/friction.md) - never a silent behaviour
@@ -244,7 +286,7 @@ whose *existing* verdict moved.
244
286
  | 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
287
  | `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
288
  | 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) |
289
+ | 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
290
 
249
291
  Unchanged on purpose: a genuine compensation fault (`git stash create`
250
292
  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,11 @@ 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 published RC baseline is
14
+ [0.2.5-rc2](../releases/release-notes-0.2.5-rc2.md), including
15
+ [shared audit metadata](audit-metadata.md) and observer startup maintenance.
16
+ The [RC3 source candidate](../releases/release-notes-0.2.5-rc3.md) adds defensive
17
+ research and a [zero-model calibration example](../lab/blue-team-calibration.md).
15
18
  Use a user-selected stable prefix for the published package:
16
19
 
17
20
  ```sh
@@ -20,13 +23,17 @@ npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-gua
20
23
 
21
24
  The package root is
22
25
  `/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.
26
+ For RC2, select `@mokuyoaxis/agent-guard@0.2.5-rc2` explicitly and check its
27
+ [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-rc2)
28
+ and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-rc2)
29
+ for publication. A reviewed checkout or supplied local tarball can be evaluated
30
+ independently of registry availability.
27
31
  Do not infer RC availability from the manifest or use an unscoped same-name
28
32
  package. A checkout's default branch can differ from a tagged stable release.
29
33
 
34
+ Evaluate RC3 from a reviewed source checkout or supplied review tarball.
35
+ Its manifest or a main-branch commit does not establish registry availability.
36
+
30
37
  Core needs Python 3.9+ and Git, with no third-party Python packages. POSIX
31
38
  examples/bridges require a POSIX shell. The optional pinned DSH read path uses
32
39
  Node 22; Kimi TOML helpers need Python 3.11+. Windows Core evidence does not
@@ -1,10 +1,16 @@
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
+ Source candidate: [0.2.5-rc3](../releases/release-notes-0.2.5-rc3.md), with
4
+ defensive research and an existing-control example. Published RC baseline:
5
+ [0.2.5-rc2](../releases/release-notes-0.2.5-rc2.md).
4
6
  Rows below retain their tested source/host versions and do not automatically
5
7
  certify this candidate. Local regression or package checks are separate from
6
8
  new native-host/model evidence.
7
9
 
10
+ The new [research notes](../research/README.md) describe bounded private
11
+ experiments; their disclosure/delegation methods do not change the supported
12
+ production coverage in this matrix.
13
+
8
14
  The Python Core and CLI are harness-neutral. A Skill or CLI being usable in a
9
15
  host does **not** mean that host intercepts tool calls, and an adapter returning
10
16
  `BLOCK` does **not** by itself prove the host prevented execution.
@@ -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-rc3.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
@@ -0,0 +1,45 @@
1
+ # 蓝队零模型校准 / Blue-team calibration
2
+
3
+ RC3 提供一个便携示例,将现有四种 Lab 控制依次运行并保存简短摘要。
4
+ 它复用已交付的 Core,不需要 DSH、Kimi、模型账户、私有 home 或新的 Python 依赖。
5
+ 需要 Python 3.9+,并允许本机 IPv4 回环监听;完整 Core 安装仍按[入门指南](../guides/getting-started.md)检查。
6
+
7
+ This example runs the four existing deterministic controls from a checkout or
8
+ installed package. It calls no model and makes no external-network request.
9
+ It creates disposable fixtures and private local evidence, including a
10
+ bounded IPv4-loopback observer. It is an example, not a new stable CLI.
11
+
12
+ ## 运行
13
+
14
+ 在包根目录或 checkout 根目录,选一个不存在的输出目录;父目录须已存在:
15
+
16
+ ```sh
17
+ python3 docs/lab/examples/blue-team-calibration.py --output-dir /tmp/agent-guard-blue-control-001
18
+ ```
19
+
20
+ 示例也可从其它工作目录通过其绝对路径调用。它根据脚本位置找到同一包内的 Core,
21
+ 不使用个人安装路径或全局宿主配置。再次运行请选择新目录,已有输出不会覆盖或清理。
22
+
23
+ | 控制 | 用途 |
24
+ |---|---|
25
+ | `clean` | 干净的负对照 |
26
+ | `mock-positive` | 合成接触/输出标记阳性 |
27
+ | `mock-injection` | 固定脚本中的标记流转阳性;名称沿用原 Lab 契约 |
28
+ | `snapshot-positive` | 合成归档与本机接收端校准 |
29
+
30
+ 四种控制均为 `model_usage=NONE`、`security_outcome=CALIBRATION_ONLY`。
31
+ 摘要中的 `COMPLETE` 需要控制报告 COMPLETE、判据 PASS、观察器 HEALTHY。
32
+ 非完整报告或已知 Lab 错误会立即停止后续控制,保留已有夹具和证据,不自动重试。
33
+
34
+ 输出目录包含各控制的 `fixture/`、`evidence/` 和整体 `summary.json`。
35
+ 观察器的路由和控制材料保存在私有证据中;公开反馈只提交必要的去敏摘要。
36
+ 脚本在终端输出同一摘要,完整返回退出码 0,控制未完成返回 4;参数或目录错误返回非零。
37
+
38
+ ## 如何使用结果
39
+
40
+ 控制通过说明这个运行环境中的仪器能完成指定校准;不说明真实模型安全、不认证宿主
41
+ 已经加载 hook,也不产生真实防护 L2 结论。若回环监听、权限或启动失败,先检查保留的
42
+ `observer.log` 与证据状态,按[Lab 指南](guard-lab.md)解释失败。
43
+
44
+ 本示例不重放私有实模,也不实现[研究稿](../research/README.md)中的请求授权或父子装配器。
45
+ 它为后续独立防守实验提供公开起点。贡献入口见[CONTRIBUTING.md](../../CONTRIBUTING.md)。