watchmyagents 1.1.5 → 1.2.0

package/SECURITY.md

@@ -11,13 +11,30 @@ WMA needs your Anthropic API key to call the Managed Agents REST API on your beh
 | Property | Behavior |
 |---|---|
 | **Source** | Environment variable `ANTHROPIC_API_KEY` or `--api-key` CLI flag |
-| **Storage** | Held in process memory for the duration of a `wma-fetch` run. Never persisted to disk by WMA. |
+| **Storage (CLI mode)** | Held in process memory for the duration of a `wma-fetch` run. Not persisted to disk. |
+| **Storage (service mode)** | Persisted to `~/.watchmyagents/env` with mode `0600` (user-only read/write) so the launchd / systemd unit can restart the daemon without prompting. See [Service-mode credentials](#service-mode-credentials) below for the exact layout. |
 | **Network** | Sent only to `api.anthropic.com` over HTTPS with strict certificate verification (`rejectUnauthorized: true`) |
 | **Logging** | The key is never written to NDJSON logs, never printed in error messages, never included in any export |
 | **Telemetry** | WMA performs zero telemetry today. No phone-home, no usage reporting. |
 
 **Recommendation:** generate a workspace-scoped API key with read-only permissions on the agents you want to monitor. See [Anthropic Console → API Keys](https://console.anthropic.com/settings/keys).
 
+#### Service-mode credentials
+
+When you run `wma-service install`, WMA registers a launchd (macOS) or systemd (Linux) unit that needs to restart the watch daemon across reboots without human intervention. The daemon's environment is therefore loaded from a small file owned by your user account:
+
+| Path | Mode | Owner | Contents |
+|---|---|---|---|
+| `~/.watchmyagents/` | `0700` | your user | Holds the env file and the launcher shell script |
+| `~/.watchmyagents/env` | `0600` | your user | `KEY=value` lines for `ANTHROPIC_API_KEY`, `WMA_API_KEY`, `WMA_SIGNALS_SALT`, `WMA_FORTRESS_BASE_URL` |
+| `~/.watchmyagents/<label>.launcher.sh` | `0600` | your user | Reads the env file with a literal `read -r` loop (no shell interpolation), then `exec`s `wma-fetch`. |
+
+Hardening notes:
+- The launcher loads secrets with `while IFS='=' read -r k v` instead of `. file` / `source file`. Sourcing would shell-evaluate every value, so a value containing `$(cmd)` would execute at every restart. The literal read assigns the bytes verbatim.
+- Values are validated before write: a newline anywhere in a credential aborts the install (would corrupt the env file or inject extra lines).
+- To wipe the credential without uninstalling the service: `chmod 600 ~/.watchmyagents/env && : > ~/.watchmyagents/env` (the daemon will exit on the next missing-env check).
+- Full removal: `wma-service uninstall` deletes the unit, the launcher, the env file, and the `~/.watchmyagents` directory.
+
 ### Local log files
 
 `wma-fetch` writes NDJSON files to `./watchmyagents-logs/<agent_id>/<date>.ndjson` with the following protections:
@@ -73,8 +90,7 @@ WMA combines **two complementary layers**:
 ## Supply chain
 
 - All code is open source on [GitHub](https://github.com/minedorfbm/watchmyagents)
-- Zero runtime dependencies (uses Node.js 18+ built-ins only)
-- One dev dependency (`@anthropic-ai/sdk`) for the optional adapter examples
+- Zero runtime AND dev dependencies (uses Node.js 18+ built-ins only). Run `npm ls --omit=dev` or check `package.json#dependencies` / `devDependencies` — both are empty.
 - Future releases will use `npm publish --provenance` for SLSA build attestation
 
 ## Reporting a vulnerability

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "watchmyagents",
-  "version": "1.1.5",
+  "version": "1.2.0",
   "description": "Security observability + real-time policy enforcement for AI agents. Local-first NDJSON capture with a continuous Watch daemon that auto-uploads anonymized signals, Shield CLI that blocks policy violations live (with policies pulled from Fortress cloud), anonymizer producing signals-only payloads, bidirectional sync with WatchMyAgents Fortress, and one-command install as an always-on launchd/systemd service — closing the recursive Watch→Guardian→Shield security loop.",
   "type": "module",
   "files": [

package/scripts/fetch-anthropic.js

@@ -91,6 +91,11 @@ function resolveModel(agent) {
 // is misconfigured or compromised; abort.
 const MAX_FORTRESS_RESPONSE_BYTES = 1 * 1024 * 1024;
 
+// v1.1.6 F-22 (P2 Codex audit): hard ceiling on a Fortress POST round
+// trip. Same rationale as in scripts/upload-fortress.js — without this,
+// a slow/unresponsive endpoint hangs the daemon's session loop.
+const FORTRESS_REQUEST_TIMEOUT_MS = 30_000;
+
 function postJson(url, headers, body) {
   return new Promise((resolveReq, rejectReq) => {
     const u = new URL(url);
@@ -125,6 +130,11 @@ function postJson(url, headers, body) {
       });
     });
     req.on('error', rejectReq);
+    // v1.1.6 F-22: bound the round trip so a non-responding endpoint
+    // can't hang the watch daemon's upload loop.
+    req.setTimeout(FORTRESS_REQUEST_TIMEOUT_MS, () => {
+      req.destroy(new Error(`Fortress request timed out after ${FORTRESS_REQUEST_TIMEOUT_MS}ms`));
+    });
     req.write(data); req.end();
   });
 }

package/scripts/shield.js

@@ -27,6 +27,7 @@
 import { resolve } from 'node:path';
 import { streamWithReconnect } from '../src/shield/stream.js';
 import { loadPolicies, evaluate } from '../src/shield/policy.js';
+import { createContextTracker } from '../src/shield/context.js';
 import {
   confirmAllow, confirmDeny, interruptSession,
   getAgentConfig, detectAlwaysAsk,
@@ -155,6 +156,15 @@ async function runSessionWorker({ sessionId, ctx }) {
   };
 
   let processed = 0, enforced = 0, sessionInterrupted = false;
+
+  // v1.2.0 — per-session context tracker. Feeds runtime attributes
+  // (hour_of_day_utc, agent_age_minutes, recent_error_rate, …) into the
+  // policy engine so rules can express context-aware authorization (see
+  // src/shield/context.js + test/policy-context.test.js). Lives entirely
+  // in process memory; nothing is forwarded to Fortress — Containment
+  // doctrine preserved.
+  const policyTracker = createContextTracker({ recentWindowSize: 20 });
+
   // Cache is only needed for tool_confirmation mode (lookup by event_id when
   // requires_action fires). Interrupt mode evaluates synchronously and never
   // reads the cache, so caching there would just leak memory on long sessions.
@@ -197,9 +207,14 @@ async function runSessionWorker({ sessionId, ctx }) {
       if (mode === 'interrupt' && CACHEABLE_TOOL_TYPES.has(rawEvent.type)) {
         // No caching in interrupt mode — react synchronously, free memory.
         const normalized = normalizeForPolicy(rawEvent);
+        // v1.2.0 — compute policy context BEFORE evaluate so rules see
+        // PRIOR history (recent_error_rate, agent_age_minutes, …), then
+        // record AFTER so the next event sees this one in its window.
+        const policyCtx = policyTracker.compute(rawEvent);
         const t0 = Date.now();
-        const result = evaluate(normalized, ctx.ruleset);
+        const result = evaluate(normalized, ctx.ruleset, policyCtx);
         const decidedInMs = Date.now() - t0;
+        policyTracker.record(rawEvent);
 
         // v1.1.3 Phase 1.D — mode badge in the log line for operator visibility.
         const modeTag = result.mode === 'shadow' ? ' [SHADOW]' : '';
@@ -266,9 +281,13 @@ async function runSessionWorker({ sessionId, ctx }) {
           }
 
           const normalized = normalizeForPolicy(sourceEvent);
+          // v1.2.0 — see interrupt-mode block above for the compute /
+          // record ordering rationale.
+          const policyCtx = policyTracker.compute(sourceEvent);
           const t0 = Date.now();
-          const result = evaluate(normalized, ctx.ruleset);
+          const result = evaluate(normalized, ctx.ruleset, policyCtx);
           const decidedInMs = Date.now() - t0;
+          policyTracker.record(sourceEvent);
 
           // v1.1.3 Phase 1.D — mode badge in the log line for operator visibility.
           const modeTag = result.mode === 'shadow' ? ' [SHADOW]' : '';

package/scripts/upload-fortress.js

@@ -68,6 +68,16 @@ async function collectFiles(p) {
 // against a compromised or misconfigured response.
 const MAX_FORTRESS_RESPONSE_BYTES = 1 * 1024 * 1024;
 
+// v1.1.6 F-22 (P2 Codex audit): hard ceiling on a Fortress POST round
+// trip. Mirrors the timeout already enforced in src/shield/sources/
+// fortress.js. Without this, a Fortress endpoint that accepts the TCP
+// connection but stops responding mid-stream would hang the upload
+// daemon indefinitely — same SLOWLORIS class of bug F-21 fixes for
+// SSE reads. 30 s is plenty for a small JSON POST (signals payloads
+// are kilobytes); legitimate Fortress nodes reply in <1 s in steady
+// state.
+const FORTRESS_REQUEST_TIMEOUT_MS = 30_000;
+
 function postJson(url, headers, body) {
   return new Promise((resolveReq, rejectReq) => {
     const u = new URL(url);
@@ -114,6 +124,10 @@ function postJson(url, headers, body) {
       }
     );
     req.on('error', rejectReq);
+    // v1.1.6 F-22: ensure a non-responding endpoint can't hang the upload.
+    req.setTimeout(FORTRESS_REQUEST_TIMEOUT_MS, () => {
+      req.destroy(new Error(`Fortress request timed out after ${FORTRESS_REQUEST_TIMEOUT_MS}ms`));
+    });
     req.write(data);
     req.end();
   });

package/src/logger.js

@@ -1,8 +1,21 @@
-import { mkdir, appendFile } from 'node:fs/promises';
+import { mkdir, appendFile, chmod } from 'node:fs/promises';
 import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { assertSafePathSegment } from './validate.js';
 
+// v1.1.6 F-24 (P3 Codex audit): the `mode` option on mkdir() and
+// appendFile() is only honored when the directory or file is CREATED.
+// If a previous wma-fetch run, a different user, or a hand-rolled mkdir
+// already left those paths around with the system umask (typically
+// 0755 / 0644), the original constructor would silently keep the loose
+// perms even though SECURITY.md promises 0700 / 0600. tightenMode runs
+// after every mkdir / append to bring the existing inode in line with
+// the docs. Errors are swallowed (best-effort): the chmod is a hardening
+// pass, not a precondition — failing it shouldn't break logging.
+async function tightenMode(path, mode) {
+  try { await chmod(path, mode); } catch { /* not fatal */ }
+}
+
 // PR-B: `framework` → `provider` (canonical name per src/sources/contract.js).
 // PR-C: adds `parent_agent_id` + `composition_pattern` so any future
 // adapter that knows the hierarchy (OpenAI Agents handoffs, CrewAI
@@ -28,7 +41,15 @@ export class Logger {
   //                Audit-grade default: refuse to silently lose events. Disk
   //                full / EACCES / EINVAL must propagate so callers know.
   //                Opt into bestEffort=true only for non-critical paths.
-  constructor({ logDir, agentId, sessionId, silent, bestEffort } = {}) {
+  // `chain`      : v1.2.0 — optional decision-chain instance (see
+  //                src/shield/decision-chain.js). When set, every record
+  //                written through this logger gets prev_hash + chain_hash
+  //                appended, building a tamper-evident audit chain. Today
+  //                this is only enabled by DecisionLogger (shield_decision
+  //                rows). Watch's Loggers leave it null so Watch rows have
+  //                no chain fields — verifyDecisionChain() filters by
+  //                action_type, so both kinds of rows coexist cleanly.
+  constructor({ logDir, agentId, sessionId, silent, bestEffort, chain } = {}) {
     // agentId becomes a filesystem path segment (logDir/<agentId>/…). Reject
     // anything that could traverse out of logDir before we ever build a path.
     assertSafePathSegment(agentId, 'agentId');
@@ -37,6 +58,7 @@ export class Logger {
     this.sessionId = sessionId || randomUUID();
     this.silent = silent !== false;
     this.bestEffort = bestEffort === true;
+    this.chain = chain || null;
     this.sequence = 0;
     this.currentDay = null;
     this.currentPath = null;
@@ -88,9 +110,18 @@ export class Logger {
       input: e.input ?? null,
       output: e.output ?? null,
     };
+    // v1.2.0 — if a decision chain is attached, wrap the composed record
+    // so it carries prev_hash + chain_hash. The wrap is computed over the
+    // canonical body that ends up on disk; the verifier reproduces the
+    // same hash by reading the file. See src/shield/decision-chain.js.
+    const toWrite = this.chain ? this.chain.wrap(full) : full;
     try {
-      await mkdir(join(this.logDir, this.agentId), { recursive: true, mode: 0o700 });
-      await appendFile(path, JSON.stringify(full) + '\n', { encoding: 'utf8', mode: 0o600 });
+      const dir = join(this.logDir, this.agentId);
+      await mkdir(dir, { recursive: true, mode: 0o700 });
+      // v1.1.6 F-24: tighten existing perms — `mode` is creation-only.
+      await tightenMode(dir, 0o700);
+      await appendFile(path, JSON.stringify(toWrite) + '\n', { encoding: 'utf8', mode: 0o600 });
+      await tightenMode(path, 0o600);
       this.count++;
     } catch (err) {
       if (!this.silent) process.stderr.write(`[wma] log write error: ${err.message}\n`);
@@ -98,7 +129,7 @@ export class Logger {
       // Disk full, EACCES, EINVAL etc. should NOT be silently swallowed.
       if (!this.bestEffort) throw err;
     }
-    return full;
+    return toWrite;
   }
 
   toExportRecord(entry) {

package/src/shield/context.js

@@ -0,0 +1,136 @@
+// Shield context tracker — v1.2.0.
+//
+// Computes runtime attributes that policy rules can evaluate alongside
+// the event payload itself. This closes the "context-aware authorization"
+// gap called out in Anthropic's May 2026 agentic security framework
+// (Part IV §Phase 4): a policy isn't just "what is the agent doing right
+// now" but also "what hour is it, how long has this agent been running,
+// has it been throwing a lot of errors lately".
+//
+// The tracker is stateful per session and lives in the Shield process. It
+// holds only short summaries — no payloads. Containment is preserved:
+// nothing here leaves the customer machine. See [[project_containment_architecture]].
+//
+// Computed attributes exposed via compute(event) → ctx:
+//   - hour_of_day_utc      number 0..23
+//   - day_of_week_utc      number 0..6 (Sunday=0)
+//   - agent_age_minutes    minutes since the first event observed in this tracker
+//   - session_duration_ms  milliseconds since the first event in this tracker
+//   - recent_error_rate    fraction 0..1 over the trailing window (PRIOR events
+//                          only — the current event isn't counted, so a rule
+//                          like "deny if recent_error_rate > 0.5" reflects
+//                          the agent's RECENT track record, not itself)
+//   - event_count_recent   number of events in the trailing window
+//   - event_count_total    total events seen by the tracker
+//
+// Usage:
+//   const tracker = createContextTracker({ recentWindowSize: 20 });
+//   for each event {
+//     const ctx = tracker.compute(event);
+//     const result = evaluate(event, ruleset, ctx);
+//     tracker.record(event, { isError: result.decision === 'deny' });
+//   }
+//
+// Order matters: compute() BEFORE evaluate(), record() AFTER. That way
+// recent_error_rate describes the past, not the present, and the rule
+// is self-consistent.
+
+const DEFAULT_RECENT_WINDOW = 20;
+
+function defaultIsError(event) {
+  // Heuristic: treat as error if the event carries an explicit error
+  // marker. We deliberately don't synthesize errors from missing fields
+  // — false negatives here just mean recent_error_rate underestimates,
+  // which is the safe direction. Callers can pass an explicit isError
+  // to record() to override.
+  if (!event || typeof event !== 'object') return false;
+  if (event.is_error === true) return true;
+  if (event.error != null) return true;
+  if (typeof event.type === 'string' && event.type.includes('error')) return true;
+  // tool_result with error content
+  if (Array.isArray(event.content)) {
+    for (const part of event.content) {
+      if (part && part.type === 'tool_result' && part.is_error === true) return true;
+    }
+  }
+  return false;
+}
+
+export function createContextTracker(options = {}) {
+  const recentWindowSize = options.recentWindowSize ?? DEFAULT_RECENT_WINDOW;
+  // Clock injection — Date.now is forbidden in some sandboxes (e.g.
+  // workflow scripts) and pinning is essential for testability. Callers
+  // can pass options.now = () => fixedEpoch to control the perceived time.
+  const now = options.now ?? (() => Date.now());
+
+  // v1.2.0: cap the window to avoid runaway memory if a caller passes
+  // something like 1_000_000. The realistic ceiling for "recent" is in
+  // the low thousands — anything bigger is no longer "recent" anyway.
+  if (!Number.isInteger(recentWindowSize) || recentWindowSize < 1 || recentWindowSize > 10_000) {
+    throw new Error(`createContextTracker: recentWindowSize must be an integer in [1, 10000], got ${recentWindowSize}`);
+  }
+
+  let firstSeenMs = null;          // ms epoch of the first observation
+  let totalCount = 0;              // total events seen
+  const recent = [];               // ring buffer of booleans (true = error)
+  let errorsInWindow = 0;          // O(1) sum so compute() stays fast
+
+  return {
+    // Build a ctx object for the given event. Pure read — no state change.
+    // Pass an optional `at` (ms epoch) to override the clock for this
+    // call (rare; used by replay scenarios).
+    compute(event, at) {
+      const nowMs = Number.isFinite(at) ? at : now();
+      const wallClock = Number.isFinite(at) ? new Date(at) : new Date(nowMs);
+      const ageMs = firstSeenMs == null ? 0 : Math.max(0, nowMs - firstSeenMs);
+      const denom = recent.length;
+      return {
+        hour_of_day_utc: wallClock.getUTCHours(),
+        day_of_week_utc: wallClock.getUTCDay(),
+        agent_age_minutes: Math.floor(ageMs / 60_000),
+        session_duration_ms: ageMs,
+        recent_error_rate: denom === 0 ? 0 : errorsInWindow / denom,
+        event_count_recent: denom,
+        event_count_total: totalCount,
+      };
+    },
+
+    // Update tracker with the outcome of `event`. Call AFTER compute() +
+    // evaluate() for the current event so its outcome enters the window
+    // for the NEXT compute() call.
+    //
+    // Options:
+    //   isError  explicit error flag (boolean). When omitted, falls back
+    //            to the default heuristic on the event itself.
+    record(event, options = {}) {
+      if (firstSeenMs == null) firstSeenMs = now();
+      totalCount += 1;
+
+      const isError = typeof options.isError === 'boolean'
+        ? options.isError
+        : defaultIsError(event);
+
+      recent.push(isError);
+      if (isError) errorsInWindow += 1;
+
+      // Evict from the head until we're back at window size.
+      while (recent.length > recentWindowSize) {
+        const dropped = recent.shift();
+        if (dropped) errorsInWindow -= 1;
+      }
+    },
+
+    // Reset all state. Useful at the start of a fresh session, or for
+    // tests that want a clean tracker between cases.
+    reset() {
+      firstSeenMs = null;
+      totalCount = 0;
+      recent.length = 0;
+      errorsInWindow = 0;
+    },
+  };
+}
+
+// Exported for tests + callers who want the same heuristic without going
+// through a tracker (e.g. one-off classification).
+export { defaultIsError };

package/src/shield/decision-chain.js

@@ -0,0 +1,186 @@
+// Shield decision audit chain — v1.2.0.
+//
+// Tamper-evidence on the shield_decision NDJSON log. Each record gets two
+// new fields:
+//
+//   prev_hash   — chain_hash of the previous record (or the genesis
+//                 marker for the first record in this chain segment)
+//   chain_hash  — sha256(prev_hash || canonical(record without these
+//                 two fields))
+//
+// Why this matters (mapping to Anthropic's May 2026 framework, Part IV
+// §Phase 6 "audit + forensics"):
+//
+//   - Operational: after an incident the forensic question is "what did
+//     Shield decide, and was the log doctored". With the chain in place,
+//     any insertion / deletion / modification breaks the next record's
+//     prev_hash. A single broken link locates the tampering window.
+//   - Investigator workflow: replay the file through verifyChain() →
+//     either OK (every record's chain_hash matches the next record's
+//     prev_hash) or BROKEN at index N (everything after is suspect).
+//
+// Scope + limitations (v1.2.0):
+//
+//   - Per-process chain. Each Shield restart begins a new chain segment
+//     with a fresh genesis. An NDJSON file may therefore contain MORE
+//     than one chain — that's deliberate and self-describing (the
+//     genesis marker carries process_id + start time). The verifier
+//     walks segments sequentially.
+//   - Soft tamper-evidence only: an attacker who can re-execute Shield
+//     can re-derive the chain from scratch. Strong tamper-evidence
+//     requires offloading to an append-only sink (Fortress + signed
+//     ingest) — tracked separately. This module is the LOCAL piece.
+//   - Hash: SHA-256 hex (32 bytes → 64 chars). Node built-in. We
+//     deliberately do NOT introduce a non-stdlib hash to preserve the
+//     zero-runtime-deps guarantee.
+//   - Canonicalization: reuses canonicalize() from signature.js — same
+//     rules as the Ed25519 chain-of-trust, so verifiers only need one
+//     serializer.
+
+import { createHash, randomUUID } from 'node:crypto';
+import { canonicalize } from './signature.js';
+
+// The two link fields are EXCLUDED from the hashed body of a record —
+// the hash of (R) cannot contain its own value, and prev_hash is
+// already mixed into the digest input separately.
+export const CHAIN_FIELDS = ['prev_hash', 'chain_hash'];
+
+function sha256Hex(input) {
+  return createHash('sha256').update(input).digest('hex');
+}
+
+// Strip the chain fields from a record before hashing. We do NOT mutate
+// the caller's object — we return a shallow copy.
+function bodyForHash(record) {
+  const out = {};
+  for (const k of Object.keys(record)) {
+    if (k === 'prev_hash' || k === 'chain_hash') continue;
+    out[k] = record[k];
+  }
+  return out;
+}
+
+// Build the digest input for a record: prev_hash followed by a single
+// separator byte (chosen as `|` since it never appears in hex output and
+// keeps the input human-inspectable), then the canonical body. The
+// separator prevents an attacker from shifting bytes between the two
+// inputs and re-deriving a collision.
+function digestInput(prevHash, body) {
+  return prevHash + '|' + canonicalize(body);
+}
+
+// Build a structured genesis marker. The verifier treats it as opaque
+// (the marker only matters as the prev_hash of the first record), but
+// the structure aids manual forensics: an investigator opening the
+// NDJSON can tell which Shield process minted that chain.
+//
+// All three components are LOCAL identifiers — none of them is sensitive
+// or correlatable to a customer account.
+export function buildGenesisMarker({ agentId, sessionId, startedAtIso, chainId } = {}) {
+  const parts = [
+    'genesis',
+    agentId || 'unknown-agent',
+    sessionId || 'unknown-session',
+    startedAtIso || new Date(0).toISOString(),  // caller injects a real timestamp
+    chainId || 'unknown-chain',
+  ];
+  return parts.join(':');
+}
+
+// Per-process chain state. wrap(body) returns a NEW object with the two
+// link fields inserted at the END of the record (NDJSON readers tolerate
+// either position, but appending keeps human diffs cleaner).
+export function createDecisionChain({ genesis } = {}) {
+  if (typeof genesis !== 'string' || genesis.length === 0) {
+    throw new Error('createDecisionChain: genesis must be a non-empty string (use buildGenesisMarker)');
+  }
+  let prevHash = genesis;
+  let count = 0;
+
+  return {
+    // Returns the chain-augmented record. Caller writes the returned
+    // object verbatim to NDJSON.
+    wrap(body) {
+      if (body == null || typeof body !== 'object' || Array.isArray(body)) {
+        throw new Error('decisionChain.wrap: body must be a plain object');
+      }
+      const chainHash = sha256Hex(digestInput(prevHash, bodyForHash(body)));
+      const out = { ...body, prev_hash: prevHash, chain_hash: chainHash };
+      prevHash = chainHash;
+      count += 1;
+      return out;
+    },
+
+    // Read-only inspection. Useful for tests + for shield.js to write a
+    // periodic "chain snapshot" line if we want one in v1.3.
+    state() {
+      return { prev_hash: prevHash, count };
+    },
+  };
+}
+
+// Walk an array of records (deserialized from NDJSON) and check that
+// every record's chain_hash is reproducible from prev_hash + body, AND
+// that record[i+1].prev_hash === record[i].chain_hash. Returns:
+//
+//   { ok: true,  count, segments }                          if intact
+//   { ok: false, broken_at: i, reason, count, segments }   if tampered
+//
+// A "segment" is a contiguous run of records that share a chain. The
+// first segment starts at the genesis marker derived from
+// records[0].prev_hash; subsequent segments start at any record whose
+// prev_hash does NOT match the previous record's chain_hash AND that
+// looks like a genesis marker (starts with "genesis:"). That tolerance
+// is what lets one NDJSON file hold the chains of multiple Shield runs.
+//
+// Anything OTHER than "valid step within the current chain" or "new
+// segment starting at a genesis marker" is a tamper signal.
+export function verifyDecisionChain(records) {
+  if (!Array.isArray(records)) {
+    return { ok: false, broken_at: -1, reason: 'records must be an array', count: 0, segments: 0 };
+  }
+  if (records.length === 0) {
+    return { ok: true, count: 0, segments: 0 };
+  }
+
+  let segmentCount = 0;
+  let runningPrev = null;  // chain_hash of the most recently verified record
+
+  for (let i = 0; i < records.length; i++) {
+    const r = records[i];
+    if (r == null || typeof r !== 'object') {
+      return { ok: false, broken_at: i, reason: 'record is not an object', count: i, segments: segmentCount };
+    }
+    if (typeof r.prev_hash !== 'string' || typeof r.chain_hash !== 'string') {
+      return { ok: false, broken_at: i, reason: 'missing prev_hash or chain_hash', count: i, segments: segmentCount };
+    }
+
+    // Is this the start of a new segment?
+    const isFirstInFile = i === 0;
+    const linksToPrev = !isFirstInFile && r.prev_hash === runningPrev;
+    const looksLikeGenesis = r.prev_hash.startsWith('genesis:');
+
+    if (!linksToPrev) {
+      if (!isFirstInFile && !looksLikeGenesis) {
+        return { ok: false, broken_at: i, reason: 'prev_hash mismatch (not a genesis marker either)', count: i, segments: segmentCount };
+      }
+      segmentCount += 1;
+    }
+
+    // Recompute the chain_hash and compare.
+    const expected = sha256Hex(digestInput(r.prev_hash, bodyForHash(r)));
+    if (expected !== r.chain_hash) {
+      return { ok: false, broken_at: i, reason: 'chain_hash recomputation mismatch', count: i, segments: segmentCount };
+    }
+
+    runningPrev = r.chain_hash;
+  }
+
+  return { ok: true, count: records.length, segments: segmentCount };
+}
+
+// Tiny convenience for shield.js / tests that want a fresh chain id
+// without pulling crypto/randomUUID at the call site.
+export function newChainId() {
+  return randomUUID();
+}

package/src/shield/decisions.js

@@ -4,12 +4,31 @@
 // file as Watch, with action_type: "shield_decision". This closes the
 // recursive loop trivially — the next wma-fetch / wma-inspect run will
 // surface Shield's actions alongside the agent's actions.
+//
+// v1.2.0 — every shield_decision row carries a SHA-256 audit chain
+// (prev_hash + chain_hash). Watch rows in the same file carry no chain
+// fields, so verifyDecisionChain() must be given the filtered subset
+// `records.filter(r => r.action_type === 'shield_decision')`. See
+// src/shield/decision-chain.js for the chain format + verifier.
 
 import { Logger } from '../logger.js';
+import { createDecisionChain, buildGenesisMarker, newChainId } from './decision-chain.js';
 
 export class DecisionLogger {
   constructor({ logDir, agentId, sessionId }) {
-    this._logger = new Logger({ logDir, agentId, sessionId, silent: true });
+    // Each DecisionLogger instance owns a single chain segment. A Shield
+    // restart creates a fresh DecisionLogger → fresh genesis. The
+    // genesis marker is self-describing (agent + session + start time +
+    // chain id) so forensics can attribute segments to processes.
+    const chain = createDecisionChain({
+      genesis: buildGenesisMarker({
+        agentId,
+        sessionId,
+        startedAtIso: new Date().toISOString(),
+        chainId: newChainId(),
+      }),
+    });
+    this._logger = new Logger({ logDir, agentId, sessionId, silent: true, chain });
   }
 
   // Record a decision Shield made about an upstream event. Shield's own

package/src/shield/policy.js

@@ -184,6 +184,44 @@ function matchValue(value, condition) {
   if (condition._regex_any !== undefined) {
     return condition._regex_any.some(r => safeRegexTest(r, value));
   }
+  // v1.2.0 — DSL extensions for ABAC / parameter validation.
+  // Numeric comparators are strict: a non-finite VALUE or a non-finite
+  // CONDITION operand fails-closed. Same as the regex branch: we never
+  // coerce or guess intent for a malformed policy.
+  if (Number.isFinite(condition.gt)) {
+    return Number.isFinite(value) && value > condition.gt;
+  }
+  if (Number.isFinite(condition.gte)) {
+    return Number.isFinite(value) && value >= condition.gte;
+  }
+  if (Number.isFinite(condition.lt)) {
+    return Number.isFinite(value) && value < condition.lt;
+  }
+  if (Number.isFinite(condition.lte)) {
+    return Number.isFinite(value) && value <= condition.lte;
+  }
+  // in_range: tuple [min, max] inclusive both sides. An inverted tuple
+  // (min > max) fails-closed — most likely an operator typo, never a
+  // legitimate "match nothing" intent.
+  if (Array.isArray(condition.in_range) && condition.in_range.length === 2) {
+    const [min, max] = condition.in_range;
+    if (!Number.isFinite(min) || !Number.isFinite(max) || min > max) return false;
+    return Number.isFinite(value) && value >= min && value <= max;
+  }
+  // length_* operators apply to strings or arrays. Anything else (object,
+  // number, null) fails-closed — length is meaningless there.
+  if (Number.isFinite(condition.length_gt)) {
+    return (typeof value === 'string' || Array.isArray(value)) && value.length > condition.length_gt;
+  }
+  if (Number.isFinite(condition.length_gte)) {
+    return (typeof value === 'string' || Array.isArray(value)) && value.length >= condition.length_gte;
+  }
+  if (Number.isFinite(condition.length_lt)) {
+    return (typeof value === 'string' || Array.isArray(value)) && value.length < condition.length_lt;
+  }
+  if (Number.isFinite(condition.length_lte)) {
+    return (typeof value === 'string' || Array.isArray(value)) && value.length <= condition.length_lte;
+  }
   // Unknown condition shape — defensive: fail-closed (no match) so unknown
   // conditions never silently allow events.
   return false;
@@ -192,18 +230,34 @@ function matchValue(value, condition) {
 // Evaluate a single policy against an event. Returns true iff every match
 // clause is satisfied. A match clause with an undefined target field still
 // counts as "no match" rather than "any match".
-export function matchesPolicy(event, policy) {
+//
+// v1.2.0 — `ctx` is an optional second namespace for runtime-computed
+// attributes (hour_of_day_utc, agent_age_minutes, recent_error_rate,
+// session_duration_ms — see src/shield/context.js). Field paths in the
+// `match` clause that start with the reserved prefix `ctx.` resolve from
+// ctx rather than event. Everything else still resolves from event, so
+// existing policies keep working unchanged.
+//
+// The `ctx.` prefix is a reserved namespace: WMA-normalized events never
+// have a top-level `ctx` field (normalizeForPolicy never sets one), so
+// there's no risk of shadowing. If a future Anthropic event shape ever
+// has one, callers can rename their context attributes.
+export function matchesPolicy(event, policy, ctx = {}) {
   for (const [field, condition] of Object.entries(policy.match || {})) {
-    const value = getNested(event, field);
+    const value = field.startsWith('ctx.')
+      ? getNested(ctx, field.slice(4))
+      : getNested(event, field);
     if (!matchValue(value, condition)) return false;
   }
   return true;
 }
 
 // First-match-wins evaluation. Returns the policy decision and metadata.
-export function evaluate(event, ruleset) {
+// v1.2.0 — accepts an optional `ctx` for runtime-computed attributes;
+// see matchesPolicy() above. Omitting ctx preserves v1.1.x behavior.
+export function evaluate(event, ruleset, ctx = {}) {
   for (const policy of ruleset.policies) {
-    if (matchesPolicy(event, policy)) {
+    if (matchesPolicy(event, policy, ctx)) {
       return {
         decision: policy.action,
         rule_id: policy.id || null,

package/src/shield/stream.js

@@ -21,6 +21,20 @@ const VERSION = '2023-06-01';
 // reconnect logic — same outcome as a network error.
 const MAX_SSE_FRAME_BYTES = 1 * 1024 * 1024;
 
+// v1.1.6 F-21 (P1 Codex audit): inactivity watchdog on the SSE reader.
+// `reader.read()` blocks until the upstream sends bytes — there is no
+// built-in heartbeat check. A misbehaving proxy or compromised upstream
+// can keep the TCP connection open without ever emitting another event,
+// which freezes Shield indefinitely without triggering the reconnect
+// path in streamWithReconnect. 45 s is well above Anthropic's normal
+// inter-event latency (typically sub-second when an agent is active,
+// and the API sends SSE comment heartbeats `: ping` every ~15-30 s
+// when it's idle), so 45 s without any byte at all is a strong signal
+// the stream is dead but TCP-alive. On timeout we throw, the existing
+// try/finally releases the reader, and the caller reconnects with
+// exponential backoff.
+const SSE_INACTIVITY_TIMEOUT_MS = 45_000;
+
 function authHeaders(apiKey) {
   return {
     'x-api-key': apiKey,
@@ -50,7 +64,16 @@ export async function* openEventStream({ apiKey, sessionId, signal }) {
 
   try {
     while (true) {
-      const { done, value } = await reader.read();
+      // v1.1.6 F-21: race the reader against the inactivity watchdog so
+      // a stalled-but-open stream cannot freeze us indefinitely. We
+      // cancel the reader on timeout to release the underlying TCP
+      // resources before throwing — otherwise the pending read() would
+      // leak. The thrown error propagates to streamWithReconnect which
+      // initiates a fresh open with backoff.
+      const { done, value } = await readWithInactivityTimeout(
+        reader,
+        SSE_INACTIVITY_TIMEOUT_MS,
+      );
       if (done) break;
       buffer += decoder.decode(value, { stream: true });
       // v1.1.4 F-18 (P1 Codex audit): normalize all SSE line terminators
@@ -89,6 +112,59 @@ export async function* openEventStream({ apiKey, sessionId, signal }) {
   }
 }
 
+/**
+ * Race a ReadableStreamDefaultReader's `.read()` against an inactivity
+ * timeout. v1.1.6 F-21 (P1 Codex audit).
+ *
+ * Why this exists: a TCP-alive but byte-silent upstream (proxy with
+ * keepalive but no SSE heartbeat, compromised endpoint, slowloris-style
+ * stall) can leave `reader.read()` pending forever, freezing Shield's
+ * event loop. Bounding the wait surfaces the stall as an error so
+ * `streamWithReconnect` initiates a fresh connection.
+ *
+ * Exported so the unit tests can hit it directly with a mock reader
+ * that never resolves.
+ *
+ * @param {ReadableStreamDefaultReader} reader
+ * @param {number} timeoutMs
+ * @returns {Promise<{ done: boolean, value?: Uint8Array }>}
+ */
+export async function readWithInactivityTimeout(reader, timeoutMs) {
+  // We deliberately avoid Promise.race here: racing two pending promises
+  // leaves the loser in a perpetual pending state, which Node's test
+  // runner (rightly) flags as a resource leak. Instead we use the
+  // Web Streams contract — `reader.cancel()` settles a pending read()
+  // to `{ done: true }` — and a simple flag to distinguish the cancel
+  // we issued from a legitimate end-of-stream.
+  let timedOut = false;
+  const timeoutId = setTimeout(() => {
+    timedOut = true;
+    // Cancel resolves the pending read() promise. We swallow any
+    // rejection from cancel (some readers throw on already-cancelled
+    // state) because the relevant error is the timeout itself.
+    Promise.resolve(reader.cancel(new Error('SSE inactivity timeout')))
+      .catch(() => undefined);
+  }, timeoutMs);
+  // NOTE: we deliberately do NOT call timeoutId.unref() here. The
+  // unref() would make the timer non-blocking for the event loop, but
+  // for a Web Stream backed by no actual I/O (e.g. unit tests, in-memory
+  // sources) Node may then consider the loop empty and never fire the
+  // timer at all — the call hangs forever. Since the timer is short-
+  // lived (single-shot, cleared on the success path), keeping it ref'd
+  // is harmless even in long-running daemons.
+  try {
+    const result = await reader.read();
+    if (timedOut) {
+      throw new Error(
+        `SSE stream stalled — no data received for ${timeoutMs}ms (caller should reconnect)`,
+      );
+    }
+    return result;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
 function parseFrame(frame) {
   // Concatenate all `data:` lines per the SSE spec (multi-line payload).
   const parts = [];