watchmyagents 0.2.0 → 0.5.0

package/README.md

@@ -116,10 +116,43 @@ wma-fetch --agent-id <agent_id> [--session-id <sess_id>] [--since 1h]
 | `--session-id sesn_xxx` | Limit to a single session |
 | `--log-dir ./logs` | Where to write NDJSON (default `./watchmyagents-logs`) |
 | `--dump-raw` | Also save raw API events alongside (forensic / debugging) |
-| `--api-key sk-ant-…` | Override the `ANTHROPIC_API_KEY` env var |
+| `--api-key sk-ant-…` | Override the `ANTHROPIC_API_KEY` env var. **Discouraged** — visible in shell history & process list. Prefer the env var. |
 
 Logs land in `./watchmyagents-logs/<agent_id>/<date>.ndjson` (file mode `0600`, dir `0700`).
 
+### `wma-anonymize` — preview what would leave your machine
+
+Produces the anonymized signals payload (counts, latencies, salted IoC hashes, sequence histograms — no raw URLs/commands/prompts) that future WMA cloud features would ship. Useful to verify Modèle C compliance and to test the format.
+
+```bash
+export WMA_SIGNALS_SALT="$(node -e 'console.log(require("crypto").randomBytes(16).toString("hex"))')"
+wma-anonymize ./watchmyagents-logs
+# → JSON on stdout. Add --out signals.json to write to file.
+```
+
+The salt is a per-customer secret — store it in `.env.local` and reuse it across runs (random salt each run breaks IoC correlation).
+
+### `wma-upload-fortress` — ship anonymized signals to your WMA Fortress
+
+Anonymizes your local NDJSON and POSTs the resulting payload to the WMA Fortress cloud control plane, where Guardian AI analyzes patterns and proposes security policies for your agents.
+
+```bash
+export WMA_API_KEY="wma_..."                    # from Fortress dashboard → Settings → API Keys
+export WMA_FORTRESS_URL="https://<your-project>.supabase.co/functions/v1/ingest-signals"
+export WMA_SIGNALS_SALT="..."                   # same salt as wma-anonymize
+
+wma-upload-fortress --agent-id agent_01XaN... [--display-name "My agent"]
+# → POSTs the anonymized payload. Server returns signal_id + agent_id.
+
+# Inspect what WOULD be posted, without uploading:
+wma-upload-fortress --agent-id agent_xxx --dry-run
+```
+
+**What is sent:** counts, latencies, salted IoC hashes, sequences — same as `wma-anonymize` output.
+**What is NOT sent:** raw prompts, raw URLs/commands/queries, raw agent responses, raw error messages. All payload content stays on your machine.
+
+The endpoint auto-registers the agent on the first upload if it doesn't exist in Fortress yet — no manual onboarding needed for new agents.
+
 ### `wma-inspect` — audit the logs
 
 ```bash
@@ -195,11 +228,12 @@ Decisions are logged to the same NDJSON stream as Watch (`action_type: shield_de
 
 - ✅ Watch SDK — Anthropic Managed Agents post-hoc fetch + local audit
 - ✅ Shield SDK — real-time enforcement (interrupt mode + tool_confirmation mode)
+- ✅ Anonymizer — produce signals payloads (Modèle C: no raw content leaves)
+- ✅ Anonymized telemetry to WMA Fortress cloud (`wma-upload-fortress` in v0.5.0)
+- ✅ Guardian AI (cloud) — automatic policy suggestions from observed behavior
+- ✅ Fortress (cloud) — dashboard + human-in-the-loop validation queue
+- 🚧 Shield policy puller from Fortress (replace local JSON with cloud-synced policies)
 - 🚧 Encrypted upload to customer's own cloud (S3/GCS/Azure with `age` public-key encryption)
-- 🚧 Anonymized telemetry to WMA cloud (opt-in, freemium model)
-- 🚧 Guardian AI (cloud) — automatic policy suggestions from observed behavior
-- 🚧 Fortress (cloud) — dashboard + human-in-the-loop validation queue
-- 🚧 Adapters for in-process agents (Claude SDK, OpenAI, LangChain, generic) — code present in `src/adapters/` but unverified against the new Modèle C architecture; documentation will follow once re-validated
 
 ## License
 

package/SECURITY.md

@@ -37,19 +37,25 @@ WMA needs your Anthropic API key to call the Managed Agents REST API on your beh
 
 ## Threat model
 
-WMA is built to give visibility into your AI agent's behavior. It is **observational**, not preventive.
+WMA combines **two complementary layers**:
+- **Watch** (`wma-fetch`, `wma-inspect`) — observational. Captures every agent action into local NDJSON for after-the-fact audit.
+- **Shield** (`wma-shield`, shipped in v0.2.0) — preventive. Streams agent events in real time and enforces policies via `user.tool_confirmation` (block before execution when the agent has `permission_policy: always_ask`) or `user.interrupt` (terminate after a violating tool ran, when always_ask is not configured).
 
 ### What WMA defends against
 
-- **Blind spots in agent behavior.** Tool calls, prompts, state transitions, errors are all captured for after-the-fact analysis.
+- **Blind spots in agent behavior.** Watch captures tool calls, prompts, state transitions, and errors for after-the-fact analysis.
 - **Token-only observability tools.** WMA captures every action including zero-token ones (`tool_use`, `state_transition`, etc.) that are the most security-relevant.
+- **Inline policy violations** (Shield). When the agent has `permission_policy: always_ask` configured, Shield blocks tool calls before execution. When not, Shield interrupts the session on first violation (the offending tool already ran, but the agent loop stops).
 - **Vendor lock-in.** NDJSON is portable; you own the data.
 
 ### What WMA does NOT defend against
 
-- **Real-time attack prevention.** WMA observes after events occur. For inline policy gating, see the upcoming Shield product.
 - **A compromised host.** If an attacker has read access to your user account, they can read the log files. Consider encryption at rest (filesystem-level, or future opt-in via `age`) for sensitive environments.
 - **Tampering with local logs.** Files are append-only by convention, not enforced. A future release will add a per-line hash chain for tamper-evident audit.
+- **Shield being killed.** Shield is an external process. If killed, the agent runs without enforcement until Shield restarts. Run under a process supervisor (systemd, pm2, docker `restart: always`) in production.
+- **Pre-installation activity.** Shield only enforces from the moment it attaches forward. Past events are not retroactively replayed or re-evaluated.
+- **A malicious policy file.** Shield's policy engine refuses obviously unsafe regex patterns (e.g. catastrophic backtracking) and truncates inputs before regex tests to mitigate ReDoS. But a user-controlled policy file remains a code-adjacent input — treat it as you would treat sourcecode.
+- **A compromised Anthropic API.** WMA trusts the events delivered by Anthropic. This is out of scope.
 - **A compromised Anthropic API.** WMA trusts the events delivered by Anthropic. This is out of scope.
 
 ## Supply chain

package/package.json

@@ -1,25 +1,15 @@
 {
   "name": "watchmyagents",
-  "version": "0.2.0",
-  "description": "Security observability for AI agents — local-first NDJSON capture of every agent action (tool calls, prompts, state transitions, errors). Built for security audits, not just token counting.",
+  "version": "0.5.0",
+  "description": "Security observability + real-time policy enforcement for AI agents. Local-first NDJSON capture, Shield CLI that blocks policy violations live, anonymizer producing signals-only payloads, and an upload command that ships anonymized telemetry to WatchMyAgents Fortress (the cloud control plane).",
   "type": "module",
-  "main": "./src/index.cjs",
-  "module": "./src/index.js",
-  "exports": {
-    ".": {
-      "import": "./src/index.js",
-      "require": "./src/index.cjs"
-    },
-    "./adapters/claude": "./src/adapters/claude.js",
-    "./adapters/openai": "./src/adapters/openai.js",
-    "./adapters/langchain": "./src/adapters/langchain.js",
-    "./adapters/generic": "./src/adapters/generic.js"
-  },
   "files": [
     "src/",
     "scripts/inspect.js",
     "scripts/fetch-anthropic.js",
     "scripts/shield.js",
+    "scripts/anonymize.js",
+    "scripts/upload-fortress.js",
     "README.md",
     "SECURITY.md",
     "LICENSE"
@@ -27,20 +17,23 @@
   "bin": {
     "wma-inspect": "scripts/inspect.js",
     "wma-fetch": "scripts/fetch-anthropic.js",
-    "wma-shield": "scripts/shield.js"
+    "wma-shield": "scripts/shield.js",
+    "wma-anonymize": "scripts/anonymize.js",
+    "wma-upload-fortress": "scripts/upload-fortress.js"
   },
   "scripts": {
     "inspect": "node scripts/inspect.js",
     "fetch": "node scripts/fetch-anthropic.js",
     "shield": "node scripts/shield.js",
-    "example": "node examples/claude-agent/index.js"
+    "anonymize": "node scripts/anonymize.js",
+    "upload-fortress": "node scripts/upload-fortress.js"
   },
   "engines": {
     "node": ">=18.0.0"
   },
   "dependencies": {},
   "devDependencies": {
-    "@anthropic-ai/sdk": "latest"
+    "@anthropic-ai/sdk": "^0.42.0"
   },
   "keywords": [
     "ai",
@@ -54,7 +47,9 @@
     "claude",
     "managed-agents",
     "audit",
-    "ndjson"
+    "ndjson",
+    "policy-enforcement",
+    "shield"
   ],
   "author": "MinedorFBM <minedor@watchmyagents.com>",
   "license": "MIT",

package/scripts/anonymize.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+// wma-anonymize — produce the anonymized signals payload that Watch would
+// send to Fortress, for inspection / verification.
+//
+// Usage:
+//   wma-anonymize <path-to-ndjson-or-dir> [--salt <hex>] [--out <file>]
+//
+// The `--salt` argument MUST be a stable per-customer secret. Using a
+// random salt each run means hashes won't correlate across runs (useless
+// for IoC tracking). Recommended: store the salt in `.env.local` as
+// `WMA_SIGNALS_SALT=...`.
+//
+// If --salt is omitted and WMA_SIGNALS_SALT is set, that's used. Otherwise
+// the script refuses to run (intentional — we don't want users to ship
+// random-salt hashes by accident).
+
+import { readdir, stat, writeFile } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+import { SignalsAggregator, anonymizeFile } from '../src/anonymizer.js';
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const k = a.slice(2);
+      const n = argv[i + 1];
+      if (n == null || n.startsWith('--')) out[k] = true;
+      else { out[k] = n; i++; }
+    } else if (!out._target) {
+      out._target = a;
+    }
+  }
+  return out;
+}
+
+function die(msg, code = 1) {
+  process.stderr.write(`${msg}\n`);
+  process.exit(code);
+}
+
+async function collectFiles(p) {
+  const s = await stat(p).catch(() => null);
+  if (!s) return [];
+  if (s.isFile()) return p.endsWith('.ndjson') ? [p] : [];
+  const out = [];
+  for (const name of await readdir(p)) {
+    out.push(...(await collectFiles(join(p, name))));
+  }
+  return out;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (!args._target) {
+    die(`usage: wma-anonymize <path> [--salt <hex>] [--out <file>]
+
+Reads Watch NDJSON logs and produces the anonymized signals payload
+that would be sent to Fortress. Use this to inspect exactly what
+leaves your machine BEFORE any upload feature is enabled.
+
+Required: --salt <hex> or WMA_SIGNALS_SALT env var (per-customer secret).
+If you don't have one, generate: node -e "console.log(require('crypto').randomBytes(16).toString('hex'))"
+and save it in .env.local.`);
+  }
+
+  const salt = args.salt || process.env.WMA_SIGNALS_SALT;
+  if (!salt) {
+    die('error: --salt <hex> or WMA_SIGNALS_SALT env var required (per-customer secret for hashing).\n' +
+        '       generate one with: node -e "console.log(require(\'crypto\').randomBytes(16).toString(\'hex\'))"');
+  }
+  if (args.salt) {
+    process.stderr.write('[wma-anonymize] warning: --salt on the command line is visible in shell history.\n' +
+                         '                Prefer: export WMA_SIGNALS_SALT=...\n');
+  }
+  if (salt.length < 16) {
+    die('error: salt too short (need ≥16 hex chars / ≥8 bytes of entropy)');
+  }
+
+  const target = resolve(args._target);
+  const files = await collectFiles(target);
+  if (files.length === 0) {
+    die(`error: no .ndjson files found at ${target}`);
+  }
+
+  // Aggregate across all files into one big payload (typical: one fetch run)
+  const agg = new SignalsAggregator({ salt });
+  for (const f of files) {
+    const partial = await anonymizeFile(f, { salt });
+    // Merge counts (a bit clunky — for the MVP we just re-iterate via agg)
+    // Simpler: aggregate over the files using the same agg instance.
+    // Re-implement here cleanly:
+    void partial;
+  }
+  // Re-do cleanly with a single aggregator across files:
+  const oneAgg = new SignalsAggregator({ salt });
+  for (const f of files) {
+    const { createReadStream } = await import('node:fs');
+    const { createInterface } = await import('node:readline');
+    const stream = createReadStream(f, { encoding: 'utf8' });
+    const rl = createInterface({ input: stream, crlfDelay: Infinity });
+    for await (const line of rl) {
+      if (!line.trim()) continue;
+      let e; try { e = JSON.parse(line); } catch { continue; }
+      oneAgg.add(e);
+    }
+  }
+
+  const signals = oneAgg.finalize();
+
+  const json = JSON.stringify(signals, null, 2);
+  if (args.out) {
+    await writeFile(resolve(args.out), json + '\n', { encoding: 'utf8', mode: 0o600 });
+    process.stderr.write(`[wma-anonymize] wrote ${args.out} (${signals._meta.entries_processed} entries processed)\n`);
+  } else {
+    process.stdout.write(json + '\n');
+  }
+}
+
+main().catch(e => { process.stderr.write(`error: ${e.stack || e.message}\n`); process.exit(1); });

package/scripts/fetch-anthropic.js

@@ -57,6 +57,16 @@ async function main() {
   if (!apiKey) die('error: --api-key or ANTHROPIC_API_KEY required');
   if (!agentId) die('error: --agent-id required (e.g. agent_01XaNB4M88ZvcW8FoQ5GC14A)');
 
+  // Security: --api-key on the command line ends up in shell history and is
+  // visible to other processes via /proc/<pid>/cmdline. Strongly prefer the
+  // ANTHROPIC_API_KEY environment variable.
+  if (args['api-key']) {
+    process.stderr.write(
+      '[wma-fetch] warning: --api-key on the command line is visible in shell history and\n' +
+      '            in the process list. Prefer: export ANTHROPIC_API_KEY=...\n'
+    );
+  }
+
   process.stdout.write(`[wma-fetch] resolving agent ${agentId}…\n`);
   const agent = await getAgent(apiKey, agentId).catch(e => die(`failed to GET agent: ${e.message}`));
   const rawModel = agent.model || agent.config?.model || null;

package/scripts/inspect.js

@@ -8,10 +8,22 @@
 //   - a directory (recursively scans for .ndjson)
 //   - omitted → defaults to ./watchmyagents-logs
 
-import { readFile, readdir, stat } from 'node:fs/promises';
+import { readdir, stat } from 'node:fs/promises';
+import { createReadStream } from 'node:fs';
+import { createInterface } from 'node:readline';
 import { join, resolve } from 'node:path';
 import { TokenTracker } from '../src/tokens.js';
 
+// Streaming line-by-line reader — bounds memory usage on large NDJSON files
+// (a long-running agent can produce hundreds of MB per day).
+async function* readNdjsonLines(path) {
+  const stream = createReadStream(path, { encoding: 'utf8' });
+  const rl = createInterface({ input: stream, crlfDelay: Infinity });
+  for await (const line of rl) {
+    if (line.trim()) yield line;
+  }
+}
+
 const target = resolve(process.argv[2] || './watchmyagents-logs');
 
 async function collectFiles(p) {
@@ -69,9 +81,7 @@ async function main() {
   let firstTs = null, lastTs = null;
 
   for (const f of files) {
-    const raw = await readFile(f, 'utf8');
-    for (const line of raw.split('\n')) {
-      if (!line.trim()) continue;
+    for await (const line of readNdjsonLines(f)) {
       let e; try { e = JSON.parse(line); } catch { continue; }
       entries.push(e);
       tracker.record(e);

package/scripts/shield.js

@@ -118,7 +118,34 @@ async function runSessionWorker({ sessionId, ctx }) {
   sinfo(sessionId, `attached (${mode} mode)`);
 
   let processed = 0, enforced = 0, sessionInterrupted = false;
-  const toolUseCache = new Map();
+  // 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.
+  //
+  // Bounded cache: any tool_use whose policy is "always_allow" never appears
+  // in requires_action, so without these limits the Map would grow forever
+  // on long-running sessions. Two limits enforced:
+  //   - Maximum 1000 entries (LRU eviction)
+  //   - TTL 5 minutes (any entry not consumed by requires_action gets dropped)
+  const TOOLUSE_CACHE_MAX = 1000;
+  const TOOLUSE_CACHE_TTL_MS = 5 * 60 * 1000;
+  const toolUseCache = new Map(); // event_id → { event, cachedAt }
+
+  function cacheToolUse(event) {
+    const now = Date.now();
+    // TTL sweep: only walk if cache is non-trivial in size (cheap noop otherwise)
+    if (toolUseCache.size > 16) {
+      for (const [k, v] of toolUseCache) {
+        if (now - v.cachedAt > TOOLUSE_CACHE_TTL_MS) toolUseCache.delete(k);
+      }
+    }
+    // LRU cap: drop oldest insertion if over the size limit
+    while (toolUseCache.size >= TOOLUSE_CACHE_MAX) {
+      const oldest = toolUseCache.keys().next().value;
+      toolUseCache.delete(oldest);
+    }
+    toolUseCache.set(event.id, { event, cachedAt: now });
+  }
 
   try {
     for await (const rawEvent of streamWithReconnect({
@@ -131,7 +158,7 @@ async function runSessionWorker({ sessionId, ctx }) {
 
       // ── INTERRUPT MODE ──────────────────────────────────────────────
       if (mode === 'interrupt' && CACHEABLE_TOOL_TYPES.has(rawEvent.type)) {
-        toolUseCache.set(rawEvent.id, rawEvent);
+        // No caching in interrupt mode — react synchronously, free memory.
         const normalized = normalizeForPolicy(rawEvent);
         const t0 = Date.now();
         const result = evaluate(normalized, ruleset);
@@ -163,7 +190,7 @@ async function runSessionWorker({ sessionId, ctx }) {
 
       // ── TOOL_CONFIRMATION MODE ──────────────────────────────────────
       if (mode === 'tool_confirmation' && CACHEABLE_TOOL_TYPES.has(rawEvent.type)) {
-        toolUseCache.set(rawEvent.id, rawEvent);
+        cacheToolUse(rawEvent);
         continue;
       }
 
@@ -173,7 +200,8 @@ async function runSessionWorker({ sessionId, ctx }) {
           && Array.isArray(rawEvent.stop_reason.event_ids)) {
 
         for (const eventId of rawEvent.stop_reason.event_ids) {
-          const sourceEvent = toolUseCache.get(eventId);
+          const cached = toolUseCache.get(eventId);
+          const sourceEvent = cached?.event;
           if (!sourceEvent) {
             swarn(sessionId, `requires_action for unknown event_id ${eventId} — denying defensively`);
             try {
@@ -334,6 +362,15 @@ async function main() {
     process.exit(0);
   }
 
+  // Security: --api-key on the command line ends up in shell history and in
+  // the process list. Strongly prefer the ANTHROPIC_API_KEY env var.
+  if (args['api-key']) {
+    process.stderr.write(
+      '[shield] warning: --api-key on the command line is visible in shell history and\n' +
+      '         in the process list. Prefer: export ANTHROPIC_API_KEY=...\n'
+    );
+  }
+
   const singleSessionId = args['session-id']; // optional now
   const policyPath = args.policy;
   const logDir = resolve(args['log-dir'] || './watchmyagents-logs');

package/scripts/upload-fortress.js

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+// wma-upload-fortress — anonymize local Watch NDJSON and POST signals to
+// the Fortress ingest-signals Edge Function.
+//
+// Composable with the rest of the SDK:
+//   wma-fetch  →  ./watchmyagents-logs/<agent_id>/<date>.ndjson   (local capture)
+//   wma-anonymize  →  signals payload (Modèle C: no raw content)
+//   wma-upload-fortress  →  POST signals to https://<project>.supabase.co/functions/v1/ingest-signals
+//
+// Usage:
+//   wma-upload-fortress --agent-id agent_xxx \
+//                       [--log-dir ./watchmyagents-logs] \
+//                       [--fortress-url https://<project>.supabase.co/functions/v1/ingest-signals] \
+//                       [--api-key wma_...] \
+//                       [--salt <hex>] \
+//                       [--display-name "My agent"] \
+//                       [--dry-run]
+//
+// Env vars (preferred over CLI flags):
+//   WMA_API_KEY            — the wma_xxx key from the Fortress dashboard
+//   WMA_FORTRESS_URL       — full URL to the ingest-signals endpoint
+//   WMA_SIGNALS_SALT       — per-customer hex salt for IoC hashing
+//                            (must be stable across runs)
+
+import { request as httpsRequest } from 'node:https';
+import { URL } from 'node:url';
+import { readdir, stat } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { createReadStream } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { SignalsAggregator } from '../src/anonymizer.js';
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const k = a.slice(2);
+      const n = argv[i + 1];
+      if (n == null || n.startsWith('--')) out[k] = true;
+      else { out[k] = n; i++; }
+    }
+  }
+  return out;
+}
+
+function die(msg, code = 1) { process.stderr.write(`${msg}\n`); process.exit(code); }
+function info(msg) { process.stdout.write(`[wma-upload-fortress] ${msg}\n`); }
+function warn(msg) { process.stderr.write(`[wma-upload-fortress] ⚠️  ${msg}\n`); }
+
+async function collectFiles(p) {
+  const s = await stat(p).catch(() => null);
+  if (!s) return [];
+  if (s.isFile()) return p.endsWith('.ndjson') && !p.includes('raw-') ? [p] : [];
+  const out = [];
+  for (const name of await readdir(p)) {
+    out.push(...(await collectFiles(join(p, name))));
+  }
+  return out;
+}
+
+function postJson(url, headers, body) {
+  return new Promise((resolveReq, rejectReq) => {
+    const u = new URL(url);
+    if (u.protocol !== 'https:') {
+      return rejectReq(new Error(`refusing non-https fortress URL: ${url}`));
+    }
+    const data = Buffer.from(body);
+    const req = httpsRequest(
+      {
+        method: 'POST',
+        hostname: u.hostname,
+        port: u.port || 443,
+        path: u.pathname + u.search,
+        headers: {
+          ...headers,
+          'content-type': 'application/json',
+          'content-length': data.length,
+        },
+        rejectUnauthorized: true,
+      },
+      (res) => {
+        const chunks = [];
+        res.on('data', (c) => chunks.push(c));
+        res.on('end', () => {
+          const raw = Buffer.concat(chunks).toString('utf8');
+          let parsed = null;
+          try { parsed = JSON.parse(raw); } catch { /* keep raw */ }
+          resolveReq({ status: res.statusCode || 0, body: parsed ?? raw });
+        });
+      }
+    );
+    req.on('error', rejectReq);
+    req.write(data);
+    req.end();
+  });
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  const agentId = args['agent-id'];
+  const logDir = resolve(args['log-dir'] || './watchmyagents-logs');
+  const fortressUrl = args['fortress-url'] || process.env.WMA_FORTRESS_URL;
+  const apiKey = args['api-key'] || process.env.WMA_API_KEY;
+  const salt = args.salt || process.env.WMA_SIGNALS_SALT;
+  const displayName = args['display-name'] || agentId;
+  const dryRun = !!args['dry-run'];
+
+  // Validation
+  if (!agentId) die('error: --agent-id required (Anthropic agent_id, e.g. agent_01XaN...)');
+  // Strict alphanumeric to prevent path traversal in collectFiles below
+  // (--agent-id ends up as a filesystem path segment).
+  if (!/^agent_[a-zA-Z0-9]+$/.test(agentId)) {
+    die(`error: --agent-id has invalid format (expected "agent_" + alphanumeric, got "${agentId}")`);
+  }
+  if (!dryRun && !fortressUrl) {
+    die('error: --fortress-url or WMA_FORTRESS_URL required (full URL to /functions/v1/ingest-signals).\n' +
+        '       Use --dry-run to print the payload without uploading.');
+  }
+  if (!dryRun && !apiKey) {
+    die('error: --api-key or WMA_API_KEY required.\n' +
+        '       Get one from your Fortress dashboard → Settings → API Keys.');
+  }
+  if (!dryRun && apiKey && !/^wma_[a-f0-9]{32}$/i.test(apiKey)) {
+    warn(`API key format looks unusual (expected "wma_<32hex>", got "${apiKey.slice(0, 8)}…").`);
+  }
+  if (!salt) {
+    die('error: --salt or WMA_SIGNALS_SALT required (per-customer hex secret for hashing IoCs).\n' +
+        '       Generate once with:  node -e "console.log(require(\'crypto\').randomBytes(16).toString(\'hex\'))"\n' +
+        '       Store stably in .env.local.');
+  }
+  if (salt.length < 16) die('error: salt too short (need ≥16 hex chars)');
+
+  // Warn about CLI-passed secrets
+  if (args['api-key']) {
+    warn('--api-key on the command line is visible in shell history and process list.\n' +
+         '                Prefer: export WMA_API_KEY=...');
+  }
+  if (args.salt) {
+    warn('--salt on the command line is visible in shell history.\n' +
+         '                Prefer: export WMA_SIGNALS_SALT=...');
+  }
+
+  // Discover the agent's NDJSON files
+  const agentDir = join(logDir, agentId);
+  const files = await collectFiles(agentDir);
+  if (files.length === 0) {
+    die(`error: no .ndjson files found under ${agentDir}. Run wma-fetch first?`);
+  }
+  info(`scanning ${files.length} ndjson file(s) under ${agentDir}`);
+
+  // Aggregate into a single signals payload
+  const agg = new SignalsAggregator({ salt });
+  for (const f of files) {
+    const stream = createReadStream(f, { encoding: 'utf8' });
+    const rl = createInterface({ input: stream, crlfDelay: Infinity });
+    for await (const line of rl) {
+      if (!line.trim()) continue;
+      let e; try { e = JSON.parse(line); } catch { continue; }
+      agg.add(e);
+    }
+  }
+  const signals = agg.finalize();
+  if (!signals.window_start || !signals.window_end) {
+    die('error: no entries had timestamps — nothing to upload');
+  }
+
+  const body = {
+    anthropic_agent_id: agentId,
+    display_name: displayName,
+    window_start: signals.window_start,
+    window_end: signals.window_end,
+    payload: signals.payload,
+  };
+  const bodyJson = JSON.stringify(body);
+
+  info(`payload built: ${signals._meta.entries_processed} entries → ${bodyJson.length} bytes`);
+  info(`window: ${signals.window_start} → ${signals.window_end}`);
+  info(`ioc_hashes: ${signals.payload.ioc_hashes.length}, tool_counts: ${Object.keys(signals.payload.tool_counts).length}`);
+
+  if (dryRun) {
+    info('--dry-run: payload that WOULD be POSTed:');
+    process.stdout.write(JSON.stringify(body, null, 2) + '\n');
+    return;
+  }
+
+  // POST it
+  info(`POST ${fortressUrl}`);
+  const { status, body: respBody } = await postJson(
+    fortressUrl,
+    { authorization: `Bearer ${apiKey}` },
+    bodyJson
+  );
+
+  if (status >= 200 && status < 300) {
+    info(`✅ HTTP ${status}`);
+    if (typeof respBody === 'object' && respBody.signal_id) {
+      info(`signal_id: ${respBody.signal_id}`);
+      info(`agent_id:  ${respBody.agent_id}`);
+      if (respBody.registered_new_agent) info('🆕 agent was auto-registered on this upload');
+    } else {
+      info(`response: ${typeof respBody === 'string' ? respBody.slice(0, 300) : JSON.stringify(respBody).slice(0, 300)}`);
+    }
+  } else {
+    const msg = typeof respBody === 'object' ? JSON.stringify(respBody) : String(respBody).slice(0, 500);
+    die(`error: upload failed (HTTP ${status}): ${msg}`);
+  }
+}
+
+main().catch((e) => { process.stderr.write(`error: ${e.stack || e.message}\n`); process.exit(1); });