@mokuyoaxis/agent-guard 0.2.4 → 0.2.5-rc2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. package/README.md +166 -573
  2. package/README.zh-CN.md +138 -489
  3. package/SECURITY.md +53 -0
  4. package/adapters/INTEGRATION.md +4 -2
  5. package/adapters/dsh/README.md +7 -0
  6. package/assets/linux-do-community.svg +19 -0
  7. package/core/audit.py +170 -25
  8. package/core/classifier.py +25 -1
  9. package/core/lab.py +77 -7
  10. package/core/policy.py +17 -9
  11. package/core/recovery.py +5 -1
  12. package/core/redaction.py +122 -21
  13. package/docs/README.md +18 -5
  14. package/docs/design/architecture.md +25 -6
  15. package/docs/design/compatibility.md +106 -1
  16. package/docs/design/threat-model.md +6 -4
  17. package/docs/guides/audit-metadata.md +77 -0
  18. package/docs/guides/getting-started.md +106 -0
  19. package/docs/guides/harness-capabilities.md +5 -0
  20. package/docs/history/friction.md +85 -0
  21. package/docs/lab/guard-lab.md +15 -1
  22. package/docs/releases/release-notes-0.2.5-rc1.md +91 -0
  23. package/docs/releases/release-notes-0.2.5-rc2.md +101 -0
  24. package/guard_lab.py +11 -0
  25. package/package.json +4 -2
  26. package/skills/delete-guard/SKILL.md +45 -7
  27. package/skills/delete-guard/references/policy.md +90 -4
  28. package/skills/delete-guard/scripts/check.py +3 -0
  29. package/skills/delete-guard/scripts/gc.py +18 -3
  30. package/skills/delete-guard/scripts/restore.py +22 -7
  31. package/skills/delete-guard/scripts/safe_delete.py +52 -29
  32. package/skills/delete-guard/scripts/status.py +9 -7
  33. package/skills/exfil-guard/SKILL.md +23 -11
  34. package/skills/exfil-guard/references/channels.md +8 -1
  35. package/skills/exfil-guard/references/rules.md +86 -6
  36. package/skills/exfil-guard/scripts/_payload.py +20 -0
  37. package/skills/exfil-guard/scripts/check_span.py +5 -1
  38. package/skills/exfil-guard/scripts/sanitize.py +6 -3
package/SECURITY.md ADDED
@@ -0,0 +1,53 @@
1
+ # Security policy
2
+
3
+ ## Reporting
4
+
5
+ Open a GitHub issue for non-sensitive issues, or contact the maintainer
6
+ directly for anything you believe is exploitable. Please include the
7
+ verdict JSON and audit lines involved.
8
+
9
+ ## What agent-guard claims to be
10
+
11
+ Reliability infrastructure: it makes destructive actions reversible by
12
+ default and records evidence. It is **not a security sandbox** - an agent
13
+ with the same OS privileges as the guard can bypass it. See
14
+ [docs/design/threat-model.md](docs/design/threat-model.md) before relying on it.
15
+
16
+ ## Expected scanner hits on this repository
17
+
18
+ This repository documents, tests, and demonstrates destructive commands -
19
+ that is its subject matter. Static scanners (including `dsh-plugin-gate`)
20
+ will therefore report hits such as:
21
+
22
+ - `rm_recursive` / command patterns inside `README*`, `docs/`, and
23
+ especially `tests/` fixtures, which must contain real command strings to
24
+ exercise the classifier;
25
+ - `dynamic_require` in `core/policy.py` (the `subprocess` call backing
26
+ `git check-ignore`);
27
+ - credential-adjacent wording in `docs/guides/publishing-from-ephemeral-environments.md`
28
+ (a guide about *avoiding* credential leaks).
29
+
30
+ As of v0.1.0 a full self-scan reports 61 hits (29 high / 10 medium / 22
31
+ low) with **zero in runtime decision paths** - all are documentation or
32
+ test fixtures. If you find a hit outside docs/tests/fixtures, please
33
+ report it.
34
+
35
+ ## Data handling
36
+
37
+ The command guards store recovery and audit data locally. The default bucket
38
+ is the workspace's `.agent-trash/`; `AGENT_GUARD_TRASH` can select a custom or
39
+ external bucket. Recovery may also write Git metadata, including local exclude
40
+ rules and retained stashes. Linked worktrees can share Git metadata outside
41
+ the selected worktree. Diagnostics and Lab commands use their declared output
42
+ locations. A dry-run assessment can still write metadata.
43
+
44
+ There is no automatic telemetry. Built-in Lab controls call no model and use
45
+ only bounded loopback observation. Explicit live-host/model tests can contact
46
+ the configured provider through the host and consume quota; they are separate
47
+ from local command checks and require a selected experiment scope.
48
+
49
+ Recovery manifests, CLI diagnostics and historical audit records can contain
50
+ exact paths or other private text. Audit minimization in the 0.2.5-rc1 source
51
+ candidate does not make every output or old record secret-free. The exfil text
52
+ CLIs return decisions/plans or sanitized stdout; they do not automatically
53
+ persist egress audit events. Review and redact evidence before sharing it.
@@ -42,8 +42,10 @@ call. It must never silently become allow. Treat malformed payloads and
42
42
  adapter failures conservatively **when the adapter is invoked**; this does
43
43
  not protect a call when the host never starts the hook. For a shell tool,
44
44
  `check.py --enforce` may relocate files or snapshot Git state, so use it only
45
- in an authorized execution path; use advisory mode for non-mutating policy
46
- checks.
45
+ in an authorized execution path. Advisory mode assesses without changing
46
+ command targets, but may initialize quarantine/audit metadata and a Git local
47
+ exclude rule. Its exit 0 does not authorize a BLOCK or ASK decision. See the
48
+ [assessment contract](../skills/delete-guard/references/policy.md#assessment-and-dry-run-side-effects).
47
49
 
48
50
  ## 3. Configure and verify without destructive trials
49
51
 
@@ -129,6 +129,13 @@ is forwarded verbatim rather than swapped for POSIX, so `check.py` returns
129
129
 
130
130
  ## Notes
131
131
 
132
+ The [0.2.4 official Flash/PTC report](../../docs/reports/test-report-dsh-0.2.4-ptc.md)
133
+ also observed sampled root/child SDK Bash collision refusals. Its original root
134
+ PTC task failed; a separate summary completed. This does not establish general
135
+ PTC Node API mediation or injection L2. The 0.2.5-rc1 documentation update adds
136
+ no new native-host/model result; use the
137
+ [capability matrix](../../docs/guides/harness-capabilities.md) for the full scope.
138
+
132
139
  - Deletion commands inherit the caller's sandbox policy per invocation
133
140
  (`exec.agent.session`) through the native shell executor.
134
141
  - Once the adapter has registered its pre-execute listener, Core process and
@@ -0,0 +1,19 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="1000" height="160" viewBox="0 0 1000 160" role="img" aria-labelledby="title desc">
2
+ <title id="title">LINUX DO community link</title>
3
+ <desc id="desc">A project-made banner linking to the LINUX DO community, not an official endorsement.</desc>
4
+ <defs>
5
+ <linearGradient id="background" x2="1" y2="1">
6
+ <stop offset="0" stop-color="#111827"/>
7
+ <stop offset="1" stop-color="#263b55"/>
8
+ </linearGradient>
9
+ </defs>
10
+ <rect width="1000" height="160" rx="18" fill="url(#background)"/>
11
+ <rect x="0" y="0" width="12" height="160" rx="6" fill="#f59e0b"/>
12
+ <rect x="40" y="33" width="11" height="11" fill="#f59e0b"/>
13
+ <rect x="55" y="33" width="11" height="11" fill="#f59e0b"/>
14
+ <rect x="40" y="48" width="11" height="11" fill="#f59e0b"/>
15
+ <rect x="55" y="48" width="11" height="11" fill="#f59e0b"/>
16
+ <text x="86" y="79" fill="#ffffff" font-family="Arial, Helvetica, sans-serif" font-size="49" font-weight="700" letter-spacing="2">LINUX DO</text>
17
+ <text x="87" y="115" fill="#cbd5e1" font-family="Arial, Helvetica, sans-serif" font-size="22">COMMUNITY LINK · 社区友链</text>
18
+ <path d="M790 80h145m-27-27 27 27-27 27" fill="none" stroke="#f59e0b" stroke-width="5" stroke-linecap="round" stroke-linejoin="round"/>
19
+ </svg>
package/core/audit.py CHANGED
@@ -1,22 +1,167 @@
1
1
  """Auditability pillar: append-only JSONL evidence log.
2
2
 
3
- Every decision the guard makes - allow, relocate, compensate, block - is
4
- appended as one JSON object per line. The log is intentionally dumb: no
5
- rotation, no aggregation, no mutation. Post-hoc verification reads it
6
- sequentially. A torn or corrupt line is skipped on read, never rewritten.
3
+ Records contain supported metadata, not arbitrary caller payloads. Reading
4
+ legacy records applies the same projection without rewriting the log.
5
+ Durability and append-only storage remain separate from recovery manifests,
6
+ which retain the exact paths required to restore data.
7
7
  """
8
8
  from __future__ import annotations
9
9
 
10
- import getpass
10
+ from collections import deque
11
+ from functools import lru_cache
12
+ import hashlib
11
13
  import json
14
+ import math
12
15
  import os
13
- import platform
16
+ import re
14
17
  import threading
15
18
  import time
16
19
  import uuid
17
- from typing import Any, Dict, List, Optional
20
+ from typing import Any, Dict, List
18
21
 
19
22
  _APPEND_LOCK = threading.Lock()
23
+ _LOCAL_SESSION = uuid.uuid4().hex
24
+ _CORRELATION_RE = re.compile(r"sha256:[0-9a-f]{64}\Z")
25
+ _TXID_RE = re.compile(r"[0-9]{8}-[0-9]{6}-[0-9a-f]{8}\Z")
26
+ _TIMESTAMP_RE = re.compile(r"[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z\Z")
27
+ _HASH_RE = re.compile(r"[0-9a-f]{64}\Z")
28
+ _GIT_SHA_RE = re.compile(r"[0-9a-f]{40}(?:[0-9a-f]{24})?\Z")
29
+ _COUNTS = frozenset({
30
+ "target_count", "moved_count", "skipped_count", "restored_count",
31
+ "conflict_count", "error_count", "missing_count", "moved", "skipped",
32
+ "enumerated", "start", "end", "length",
33
+ })
34
+ _IDENTIFIERS = frozenset({"txid", "check_id", "plan_id"})
35
+ _ID_LISTS = frozenset({"txids", "backup_txids", "purged", "missing"})
36
+ _COMPENSATION_FIELDS = frozenset({
37
+ "strategy", "txid", "status", "moved", "skipped", "enumerated", "sha",
38
+ })
39
+
40
+
41
+ def correlation_id(value: str) -> str:
42
+ """Opaque, deterministic correlation; not encryption or authentication.
43
+
44
+ Already-projected identifiers remain stable when read or re-appended.
45
+ Surrogate escapes in POSIX metadata are hashed without emitting them.
46
+ """
47
+ if _CORRELATION_RE.fullmatch(value):
48
+ return value
49
+ return "sha256:" + hashlib.sha256(
50
+ value.encode("utf-8", errors="surrogatepass")).hexdigest()
51
+
52
+
53
+ def _identifier(value: str) -> str:
54
+ # Generated recovery/check IDs stay directly usable. Other spellings
55
+ # retain correlation without becoming an arbitrary text channel.
56
+ return value if _TXID_RE.fullmatch(value) else correlation_id(value)
57
+
58
+
59
+ @lru_cache(maxsize=1)
60
+ def _enums():
61
+ # Import after module initialization: recovery imports the ID/time
62
+ # helpers above, and needs no policy or redaction decisions here.
63
+ from . import dialects, policy, redaction
64
+ decisions = frozenset({"ALLOW", "RELOCATE", "SNAPSHOT", "SANITIZE", "ASK", "BLOCK"})
65
+ return {
66
+ "event": frozenset({
67
+ "check", "ask", "decision", "advisory", "intent", "outcome",
68
+ "enforce-block", "enforce-intent", "enforce-error", "enforce-proceed",
69
+ "restore", "gc-intent", "gc",
70
+ }) | {"exfil-" + decision.lower() for decision in decisions},
71
+ "decision": decisions, "action": decisions | {"PURGED"},
72
+ "code": frozenset(policy.EXPLANATIONS),
73
+ "tool": frozenset({"safe_delete", "check", "restore", "gc"}),
74
+ "phase": frozenset({"advisory", "intent", "complete"}),
75
+ "outcome": frozenset({
76
+ "relocated to quarantine", "deleted directly (provably regenerable)",
77
+ "deleted directly (quarantine housekeeping)",
78
+ }),
79
+ "dialect": frozenset(dialects.DIALECT_ALIASES.values()),
80
+ "dialect_requested": frozenset(dialects.DIALECT_ALIASES) | {"<redacted>"},
81
+ "dialect_outcome": frozenset({"ok", "unusable"}),
82
+ "strategy": frozenset({"relocate", "clean-enumerate", "snapshot"}),
83
+ "status": frozenset({"started", "complete", "partial", "storage-failed",
84
+ "failed", "incomplete"}),
85
+ "rule_id": frozenset(value for key, value in vars(redaction).items()
86
+ if key.startswith("RULE_") and isinstance(value, str)),
87
+ "family": frozenset({"secret", "path"}),
88
+ "confidence": frozenset({"deterministic", "contextual"}),
89
+ "channel": frozenset(redaction.CHANNELS),
90
+ "context": frozenset({"prose", "key", "uri-userinfo", "env-var"}),
91
+ "command": frozenset({"<redacted>"}),
92
+ "error": frozenset({"compensation failed"}),
93
+ }
94
+
95
+
96
+ def project(record: Dict[str, Any]) -> Dict[str, Any]:
97
+ """Supported metadata only; unknown fields/types/free text are omitted.
98
+
99
+ This is a closed record projection, not a general text sanitizer. Nested
100
+ compensation records and GC reason maps have explicit shapes. Recovery
101
+ journals, authorization state, and caller objects are never modified.
102
+ """
103
+ if not isinstance(record, dict):
104
+ raise TypeError("audit record must be an object")
105
+ stored: Dict[str, Any] = {}
106
+ for key, allowed in _enums().items():
107
+ value = record.get(key)
108
+ if key == "context" and isinstance(value, str) and value.startswith("key="):
109
+ value = "key"
110
+ if isinstance(value, str) and value in allowed:
111
+ stored[key] = value
112
+ for key in _COUNTS:
113
+ value = record.get(key)
114
+ if type(value) is int and value >= 0:
115
+ stored[key] = value
116
+ for key in ("force", "ok", "exempted"):
117
+ if type(record.get(key)) is bool:
118
+ stored[key] = record[key]
119
+ latency = record.get("guard_latency_ms")
120
+ if (type(latency) is int and latency >= 0 or
121
+ type(latency) is float and math.isfinite(latency) and latency >= 0):
122
+ stored["guard_latency_ms"] = latency
123
+ ts = record.get("ts")
124
+ if isinstance(ts, str) and _TIMESTAMP_RE.fullmatch(ts):
125
+ stored["ts"] = ts
126
+ for key in _IDENTIFIERS:
127
+ value = record.get(key)
128
+ if isinstance(value, str) and value:
129
+ stored[key] = _identifier(value)
130
+ for key in _ID_LISTS:
131
+ values = record.get(key)
132
+ if isinstance(values, list):
133
+ stored[key] = [_identifier(v) for v in values if isinstance(v, str) and v]
134
+ session = record.get("session")
135
+ if isinstance(session, str) and session:
136
+ stored["session"] = correlation_id(session)
137
+ digest = record.get("txid_sha256")
138
+ if isinstance(digest, str) and _HASH_RE.fullmatch(digest):
139
+ stored["txid_sha256"] = digest
140
+ digests = record.get("missing_txid_sha256")
141
+ if isinstance(digests, list):
142
+ stored["missing_txid_sha256"] = [
143
+ v for v in digests if isinstance(v, str) and _HASH_RE.fullmatch(v)]
144
+ sha = record.get("sha")
145
+ if "sha" in record and (sha is None or isinstance(sha, str) and _GIT_SHA_RE.fullmatch(sha)):
146
+ stored["sha"] = sha
147
+ span = record.get("span")
148
+ if (isinstance(span, list) and len(span) == 2 and
149
+ all(type(v) is int and v >= 0 for v in span) and span[1] >= span[0]):
150
+ stored["span"] = list(span)
151
+ if record.get("reasons") == []:
152
+ stored["reasons"] = []
153
+ compensations = record.get("compensations")
154
+ if isinstance(compensations, list):
155
+ stored["compensations"] = [
156
+ project({k: v for k, v in item.items() if k in _COMPENSATION_FIELDS})
157
+ for item in compensations if isinstance(item, dict)]
158
+ reasons = record.get("plan_reasons")
159
+ if isinstance(reasons, dict):
160
+ stored["plan_reasons"] = {
161
+ _identifier(txid): reason for txid, reason in reasons.items()
162
+ if isinstance(txid, str) and txid and isinstance(reason, str)
163
+ and reason in {"age", "capacity"}}
164
+ return stored
20
165
 
21
166
 
22
167
  def utc_now_iso() -> str:
@@ -29,27 +174,20 @@ def new_txid() -> str:
29
174
 
30
175
 
31
176
  def session_id() -> str:
32
- """Best-effort identity of the acting session.
177
+ """Opaque correlation for the acting session.
33
178
 
34
179
  An agent harness may identify itself through AGENT_GUARD_SESSION.
35
180
  This is correlation metadata, not authentication.
36
181
  """
37
182
  env = os.environ.get("AGENT_GUARD_SESSION")
38
183
  if env:
39
- return env
40
- try:
41
- user = getpass.getuser()
42
- except Exception: # pragma: no cover - exotic passwd setups
43
- user = "unknown"
44
- # platform.node() is the cross-platform form of os.uname().nodename
45
- # (os.uname does not exist on Windows); empty on exotic setups.
46
- host = platform.node() or "localhost"
47
- return f"{user}@{host}:{os.getpid()}"
184
+ return correlation_id(env)
185
+ return correlation_id(f"{_LOCAL_SESSION}:{os.getpid()}")
48
186
 
49
187
 
50
188
  def append(record: Dict[str, Any], audit_path: str) -> Dict[str, Any]:
51
- """Append one record; returns the stored record (with defaults filled)."""
52
- stored = dict(record)
189
+ """Append projected metadata; return exactly what was stored."""
190
+ stored = project(record)
53
191
  stored.setdefault("ts", utc_now_iso())
54
192
  stored.setdefault("session", session_id())
55
193
  line = json.dumps(stored, ensure_ascii=False, sort_keys=True)
@@ -65,22 +203,29 @@ def append(record: Dict[str, Any], audit_path: str) -> Dict[str, Any]:
65
203
 
66
204
 
67
205
  def tail(audit_path: str, n: int = 20) -> List[Dict[str, Any]]:
68
- """Read the last n valid records. Corrupt/torn lines are skipped."""
69
- if not os.path.exists(audit_path):
206
+ """Last n projected objects; malformed/non-object lines are skipped.
207
+
208
+ A non-positive limit reads nothing. Old bytes are never rewritten.
209
+ """
210
+ if n <= 0 or not os.path.exists(audit_path):
70
211
  return []
71
- records: List[Dict[str, Any]] = []
212
+ records = deque(maxlen=n)
72
213
  with open(audit_path, "r", encoding="utf-8") as fh:
73
214
  for raw in fh:
74
215
  raw = raw.strip()
75
216
  if not raw:
76
217
  continue
77
218
  try:
78
- records.append(json.loads(raw))
219
+ record = json.loads(raw)
79
220
  except json.JSONDecodeError:
80
221
  continue
81
- return records[-max(n, 0):]
222
+ if isinstance(record, dict):
223
+ records.append(project(record))
224
+ return list(records)
82
225
 
83
226
 
84
227
  def find_by_txid(audit_path: str, txid: str) -> List[Dict[str, Any]]:
85
228
  """All audit records belonging to one compensation transaction."""
86
- return [r for r in tail(audit_path, n=100_000) if r.get("txid") == txid]
229
+ key = _identifier(txid)
230
+ return [r for r in tail(audit_path, n=100_000)
231
+ if r.get("txid") == key]
@@ -33,7 +33,7 @@ import shlex
33
33
  from dataclasses import dataclass, field
34
34
  from typing import List, Optional, Tuple
35
35
 
36
- from . import dialects
36
+ from . import AUDIT_NAME, MANIFEST_NAME, STATE_NAME, dialects
37
37
 
38
38
  # ---------------------------------------------------------------- vocabulary
39
39
 
@@ -192,6 +192,7 @@ class PathSpec:
192
192
  inside_trash: bool = False
193
193
  protected: Optional[str] = None # None | ancestor-root | workspace-root
194
194
  # | outside-workspace | git-metadata
195
+ # | quarantine-control
195
196
  error: Optional[str] = None
196
197
 
197
198
  # ------------------------------------------------------------- path analysis
@@ -250,6 +251,26 @@ def _physical_keep_final(path: str) -> str:
250
251
  return os.path.join(os.path.realpath(parent), name)
251
252
 
252
253
 
254
+ def _quarantine_control_path(absolute: str, physical: str,
255
+ trash_root: str, trash_physical: str,
256
+ workspace: str) -> bool:
257
+ """Protect storage access and root metadata, retaining leaf-link location."""
258
+ # A configured final link is also the access path to an external bucket.
259
+ # Deleting its parent would sever that access even if storage is elsewhere.
260
+ if (inside_path(physical, workspace) and
261
+ any(inside_path(storage, physical) for storage in
262
+ (trash_physical, _physical_keep_final(trash_root)))):
263
+ return True
264
+ controls = {MANIFEST_NAME, AUDIT_NAME, STATE_NAME, STATE_NAME + ".tmp",
265
+ "sessions"}
266
+ for candidate in (physical, _physical_keep_final(absolute)):
267
+ if inside_path(candidate, trash_physical):
268
+ relative = os.path.relpath(candidate, trash_physical)
269
+ if relative.split(os.sep)[0] in controls:
270
+ return True
271
+ return False
272
+
273
+
253
274
  def workspace_boundary_root(workspace: str) -> str:
254
275
  """Physical form of a workspace root, for callers that compare roots."""
255
276
  return _physical(os.path.normpath(os.path.abspath(workspace)))
@@ -365,6 +386,9 @@ def classify_paths(
365
386
  # content. `rm -rf .` stays a hard BLOCK. (When no trash_root is
366
387
  # given, trash_physical is None and cannot match a real path.)
367
388
  spec.protected = "workspace-root"
389
+ elif trash_root and _quarantine_control_path(
390
+ absolute, physical, trash_root, trash_physical, workspace):
391
+ spec.protected = "quarantine-control"
368
392
  elif not spec.inside_workspace:
369
393
  spec.protected = "outside-workspace"
370
394
  else:
package/core/lab.py CHANGED
@@ -19,6 +19,7 @@ from pathlib import Path
19
19
  import re
20
20
  import secrets
21
21
  from socketserver import TCPServer
22
+ import stat
22
23
  import subprocess
23
24
  import sys
24
25
  import tarfile
@@ -194,6 +195,10 @@ class LabError(RuntimeError):
194
195
  """Expected guard-lab error with a safe, bounded message."""
195
196
 
196
197
 
198
+ class _ObserverStartupCancelled(LabError):
199
+ """The controller stopped this observer before accepting its readiness."""
200
+
201
+
197
202
  def _now() -> str:
198
203
  return datetime.now(timezone.utc).isoformat()
199
204
 
@@ -1026,6 +1031,41 @@ def _write_observer_state(evidence: Path, state: dict[str, Any]) -> None:
1026
1031
  _atomic_write_json(evidence / "observer.json", state)
1027
1032
 
1028
1033
 
1034
+ def _observer_startup_note(stage: str, stream: Any = None) -> None:
1035
+ # Static phases and monotonic time only: never log tokens, paths or errors.
1036
+ try:
1037
+ print(
1038
+ f"observer-startup stage={stage} monotonic={time.monotonic():.6f}",
1039
+ file=sys.stderr if stream is None else stream,
1040
+ flush=True,
1041
+ )
1042
+ except (OSError, ValueError):
1043
+ pass # Diagnosis must not determine the observer's health.
1044
+
1045
+
1046
+ def _observer_arm_note(evidence: Path, stage: str) -> None:
1047
+ flags = os.O_WRONLY | os.O_APPEND | getattr(os, "O_CLOEXEC", 0)
1048
+ flags |= getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0)
1049
+ try:
1050
+ descriptor = os.open(evidence / "observer.log", flags)
1051
+ with os.fdopen(descriptor, "a", encoding="utf-8") as output:
1052
+ if stat.S_ISREG(os.fstat(output.fileno()).st_mode):
1053
+ _observer_startup_note(stage, output)
1054
+ except OSError:
1055
+ pass
1056
+
1057
+
1058
+ def _check_observer_startup_stop(evidence: Path, *, ready: bool = False) -> None:
1059
+ stop_path = evidence / "stop.request"
1060
+ if not stop_path.is_file():
1061
+ return
1062
+ if ready:
1063
+ stop = _read_json(stop_path, "observer stop request")
1064
+ if stop.get("reason") != "OBSERVER_STARTUP_TIMEOUT":
1065
+ return # An ordinary stop after READY keeps its existing meaning.
1066
+ raise _ObserverStartupCancelled("observer startup was cancelled")
1067
+
1068
+
1029
1069
  def arm_observer(evidence_dir: Path, duration: int = 60) -> dict[str, Any]:
1030
1070
  if duration < MIN_DURATION_SECONDS or duration > MAX_DURATION_SECONDS:
1031
1071
  raise LabError("observer duration is outside the supported range")
@@ -1037,7 +1077,8 @@ def arm_observer(evidence_dir: Path, duration: int = 60) -> dict[str, Any]:
1037
1077
  raise LabError("observer has already been armed for this run")
1038
1078
 
1039
1079
  log_path = evidence / "observer.log"
1040
- flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_CLOEXEC", 0)
1080
+ flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_APPEND
1081
+ flags |= getattr(os, "O_CLOEXEC", 0)
1041
1082
  flags |= getattr(os, "O_NOFOLLOW", 0)
1042
1083
  try:
1043
1084
  log_descriptor = os.open(log_path, flags, 0o600)
@@ -1058,7 +1099,8 @@ def arm_observer(evidence_dir: Path, duration: int = 60) -> dict[str, Any]:
1058
1099
  else:
1059
1100
  process_options["start_new_session"] = True
1060
1101
  try:
1061
- with os.fdopen(log_descriptor, "wb") as log_output:
1102
+ with os.fdopen(log_descriptor, "w", encoding="utf-8") as log_output:
1103
+ _observer_startup_note("SPAWNING", log_output)
1062
1104
  process = subprocess.Popen(
1063
1105
  [
1064
1106
  sys.executable,
@@ -1077,18 +1119,24 @@ def arm_observer(evidence_dir: Path, duration: int = 60) -> dict[str, Any]:
1077
1119
  close_fds=True,
1078
1120
  **process_options,
1079
1121
  )
1122
+ _observer_startup_note("SPAWNED", log_output)
1080
1123
  _CHILD_PROCESSES[str(evidence)] = process
1081
1124
  except OSError as exc:
1082
1125
  raise LabError("observer process could not be started") from exc
1083
1126
 
1084
1127
  deadline = time.monotonic() + 5
1085
1128
  last_state: Optional[dict[str, Any]] = None
1129
+ noted_unreadable_state = False
1086
1130
  while time.monotonic() < deadline:
1087
1131
  try:
1088
1132
  last_state = _observer_state(evidence)
1089
1133
  except LabError:
1090
1134
  last_state = None
1135
+ if not noted_unreadable_state:
1136
+ _observer_arm_note(evidence, "ARM_STATE_UNREADABLE")
1137
+ noted_unreadable_state = True
1091
1138
  if last_state and last_state.get("status") == "READY":
1139
+ _observer_arm_note(evidence, "ARM_READY")
1092
1140
  return {
1093
1141
  "schema_version": SCHEMA_VERSION,
1094
1142
  "run_id": run["run_id"],
@@ -1098,22 +1146,26 @@ def arm_observer(evidence_dir: Path, duration: int = 60) -> dict[str, Any]:
1098
1146
  "duration_seconds": duration,
1099
1147
  }
1100
1148
  if last_state and last_state.get("status") == "FAILED":
1101
- process.wait(timeout=2)
1102
- _CHILD_PROCESSES.pop(str(evidence), None)
1149
+ _observer_arm_note(evidence, "ARM_FAILED")
1150
+ _reap_local_observer(evidence)
1103
1151
  raise LabError("observer failed its startup self-check")
1104
1152
  if process.poll() is not None:
1105
1153
  _CHILD_PROCESSES.pop(str(evidence), None)
1154
+ _observer_arm_note(evidence, "ARM_EXITED")
1106
1155
  raise LabError("observer exited before becoming ready")
1107
1156
  time.sleep(0.05)
1157
+ _observer_arm_note(evidence, "ARM_TIMEOUT")
1108
1158
  stop_path = evidence / "stop.request"
1109
1159
  if not stop_path.exists():
1110
1160
  try:
1111
1161
  _write_new_json(
1112
1162
  stop_path,
1113
- {"schema_version": SCHEMA_VERSION, "requested_at": _now()},
1163
+ {"schema_version": SCHEMA_VERSION, "requested_at": _now(),
1164
+ "reason": "OBSERVER_STARTUP_TIMEOUT"},
1114
1165
  )
1115
1166
  except LabError:
1116
1167
  pass
1168
+ _reap_local_observer(evidence)
1117
1169
  raise LabError("observer did not become ready in time")
1118
1170
 
1119
1171
 
@@ -2023,6 +2075,7 @@ class _LabRequestHandler(BaseHTTPRequestHandler):
2023
2075
 
2024
2076
 
2025
2077
  def run_observer(evidence_dir: Path, duration: int, supplied_token: str) -> int:
2078
+ _observer_startup_note("VALIDATING")
2026
2079
  evidence, run = _load_run(evidence_dir)
2027
2080
  control = _load_control(evidence, run)
2028
2081
  fixture = _validate_fixture(run, evidence)
@@ -2030,15 +2083,19 @@ def run_observer(evidence_dir: Path, duration: int, supplied_token: str) -> int:
2030
2083
  raise LabError("observer control token mismatch")
2031
2084
  if _observer_state(evidence) is not None:
2032
2085
  raise LabError("observer state already exists")
2086
+ _observer_startup_note("VALIDATED")
2033
2087
 
2034
2088
  started_at = _now()
2035
2089
  deadline = time.monotonic() + duration
2036
2090
  server: Optional[_LabHTTPServer] = None
2037
2091
  try:
2092
+ _check_observer_startup_stop(evidence)
2093
+ _observer_startup_note("BINDING")
2038
2094
  server = _LabHTTPServer(
2039
2095
  ("127.0.0.1", 0), _LabRequestHandler, evidence, run, fixture, control,
2040
2096
  str(control["route_token"]),
2041
2097
  )
2098
+ _observer_startup_note("BOUND")
2042
2099
  server.timeout = 0.25
2043
2100
  port = int(server.server_address[1])
2044
2101
  endpoint = {
@@ -2051,6 +2108,9 @@ def run_observer(evidence_dir: Path, duration: int, supplied_token: str) -> int:
2051
2108
  fixture / "bait" / "url.txt",
2052
2109
  f"http://127.0.0.1:{port}/canary/{control['route_token']}\n",
2053
2110
  )
2111
+ _observer_startup_note("ENDPOINT_WRITTEN")
2112
+ _check_observer_startup_stop(evidence)
2113
+ _observer_startup_note("PUBLISHING_READY")
2054
2114
  _append_event(
2055
2115
  evidence,
2056
2116
  {
@@ -2073,9 +2133,12 @@ def run_observer(evidence_dir: Path, duration: int, supplied_token: str) -> int:
2073
2133
  "duration_seconds": duration,
2074
2134
  }
2075
2135
  _write_observer_state(evidence, state)
2136
+ _observer_startup_note("READY")
2137
+ _check_observer_startup_stop(evidence, ready=True)
2076
2138
  next_heartbeat = time.monotonic() + 0.5
2077
2139
  while time.monotonic() < deadline:
2078
2140
  if (evidence / "stop.request").is_file():
2141
+ _check_observer_startup_stop(evidence, ready=True)
2079
2142
  _append_event(
2080
2143
  evidence,
2081
2144
  {
@@ -2113,7 +2176,9 @@ def run_observer(evidence_dir: Path, duration: int, supplied_token: str) -> int:
2113
2176
  state.update({"status": "EXPIRED", "heartbeat_at": _now(), "stopped_at": _now()})
2114
2177
  _write_observer_state(evidence, state)
2115
2178
  return 0
2116
- except Exception:
2179
+ except Exception as exc:
2180
+ cancelled = isinstance(exc, _ObserverStartupCancelled)
2181
+ _observer_startup_note("CANCELLED" if cancelled else "FAILED")
2117
2182
  try:
2118
2183
  _write_observer_state(
2119
2184
  evidence,
@@ -2124,11 +2189,14 @@ def run_observer(evidence_dir: Path, duration: int, supplied_token: str) -> int:
2124
2189
  "pid": os.getpid(),
2125
2190
  "started_at": started_at,
2126
2191
  "heartbeat_at": _now(),
2127
- "reason": "OBSERVER_RUNTIME_FAILURE",
2192
+ "reason": ("OBSERVER_STARTUP_CANCELLED" if cancelled
2193
+ else "OBSERVER_RUNTIME_FAILURE"),
2128
2194
  },
2129
2195
  )
2130
2196
  except Exception:
2131
2197
  pass
2198
+ if cancelled:
2199
+ return 1
2132
2200
  raise
2133
2201
  finally:
2134
2202
  if server is not None:
@@ -2391,6 +2459,8 @@ def observer_cli_main(argv: Optional[Sequence[str]] = None) -> int:
2391
2459
  try:
2392
2460
  return run_observer(arguments.evidence_dir, arguments.duration, supplied_token)
2393
2461
  except (LabError, OSError, ValueError):
2462
+ _observer_startup_note("FAILED")
2394
2463
  return 1
2395
2464
  except Exception:
2465
+ _observer_startup_note("FAILED")
2396
2466
  return 1
package/core/policy.py CHANGED
@@ -166,8 +166,10 @@ EXPLANATIONS: Dict[str, str] = {
166
166
  "/usr, /etc, ...), regardless of the "
167
167
  "workspace setting. Hard boundary - not "
168
168
  "askable.",
169
- CODE_BLOCK_PROTECTED_PATH: "Target is the workspace root or git "
170
- "metadata. Hard boundary - not askable.",
169
+ CODE_BLOCK_PROTECTED_PATH: "Target is a protected workspace, Git or "
170
+ "quarantine control path. Hard boundary - "
171
+ "not askable; quarantine transaction cleanup "
172
+ "uses the explicit GC entry point.",
171
173
  CODE_BLOCK_WILDCARD: "Glob target sets are opaque; use safe_delete, "
172
174
  "which expands globs explicitly.",
173
175
  CODE_BLOCK_RESTRICTED_MODE: "This session is in RESTRICTED mode; the "
@@ -497,7 +499,20 @@ def decide_path_batch(specs: List[PathSpec], ctx: PolicyContext,
497
499
  [f"protected filesystem root: {s.raw}"
498
500
  for s in protected_ancestor[:5]])
499
501
 
502
+ # Housekeeping never overrides root, control-file or Git protection.
503
+ protected_other = [s for s in specs
504
+ if s.protected in ("workspace-root", "git-metadata",
505
+ "quarantine-control")]
506
+ if protected_other:
507
+ return Verdict(DECISION_BLOCK, CODE_BLOCK_PROTECTED_PATH,
508
+ [f"protected: {s.protected} ({s.raw})"
509
+ for s in protected_other[:5]])
510
+
500
511
  if specs and all(s.inside_trash for s in specs):
512
+ if any(s.wildcard for s in specs):
513
+ return Verdict(DECISION_BLOCK, CODE_BLOCK_WILDCARD,
514
+ ["quarantine globs may include protected evidence; "
515
+ "enumerate explicitly with safe_delete"])
501
516
  return Verdict(DECISION_ALLOW, CODE_ALLOW_TRASH_GC)
502
517
 
503
518
  protected_outside = [s for s in specs
@@ -507,13 +522,6 @@ def decide_path_batch(specs: List[PathSpec], ctx: PolicyContext,
507
522
  [f"outside workspace boundary: {s.raw}"
508
523
  for s in protected_outside[:5]])
509
524
 
510
- protected_other = [s for s in specs
511
- if s.protected in ("workspace-root", "git-metadata")]
512
- if protected_other:
513
- return Verdict(DECISION_BLOCK, CODE_BLOCK_PROTECTED_PATH,
514
- [f"protected: {s.protected} ({s.raw})"
515
- for s in protected_other[:5]])
516
-
517
525
  wild = [s for s in specs if s.wildcard]
518
526
  if wild:
519
527
  return Verdict(DECISION_BLOCK, CODE_BLOCK_WILDCARD,