Make warlock integration harness-agnostic: per-run scanner instance + streaming results

[sarahxsanders]

Problem

warlock's core is already portable — scan(content) -> matches is a pure, stateless engine that drops into any project. But the reporting/telemetry lifecycle currently has to be wired by each integrator, and the wizard's integration (src/lib/yara-hooks.ts) reveals why that's fragile:

• It accumulates scan results into a module-level singleton (scanViolations array) and flushes once at "the end" of a run, then resets.
• This has two portability defects:
  1. It needs an "end." Accumulate-then-flush-once forces every harness to define and correctly hook "the run is over." Miss it and reporting silently never fires.
  2. It's a singleton. One shared buffer per process silently assumes one sequential run. It breaks under: parallel/fan-out harnesses (runs clobber each other), long-running daemons (never "ends"), and serverless (no shared module state).

The wizard just hit this concretely: when its runner was split into multiple harnesses (linear + experimental orchestrator), the report flush — bolted into one exit path — would silently not fire for the other harness. The current stopgap is an idempotent flushScanReport() finalizer wired at the wizard's single dispatcher seam, but that's wizard-internal glue; it doesn't port to a different harness shape.

Goal

Anyone should be able to hook warlock into any project — whatever their harness shape — with ≤1 line of integration code and no knowledge of warlock's reporting lifecycle.

Proposed shape

The root cause of both defects is batching into a singleton. Remove the batch and both evaporate. Offer two complementary triggers so no harness lifecycle has to be reasoned about:

1. Push (streaming) — removes the "end" problem entirely. A per-run scanner emits each match to a consumer-supplied sink as it happens:

   const scanner = warlock.createScanner({ rules, onMatch: m => sink.send(m) });

   No buffer, no "end" — daemon, serverless, and parallel fan-out are all identical.

2. Per-run instance + dispose — for consumers who still want one aggregated summary. The buffer moves off the module singleton and into a scanner instance, flushed on dispose (scope-bound, concurrency-safe):

   await using scanner = warlock.createScanner({ rules });   // owns its own results
   // ... summary auto-emitted at scope exit, or scanner.report() on demand

Between push (no end needed) and dispose (scope-bound end), virtually every harness is covered with ≤1 line; the exotic case falls back to explicit scanner.close().

Layering (respects warlock's engine-only philosophy)

Layer	Owns	Ports?
warlock core	scan -> matches (pure)	anywhere, already
thin optional adapter	per-run scanner instance: streaming onMatch + disposable summary	anywhere — no harness assumptions
integrator glue	maps the adapter onto this harness's hooks	tiny, per-project

The consumer still decides how to respond to matches (warlock stays engine-only); this just stops every integrator from re-implementing accumulation + lifecycle.

Acceptance

• No module-level singleton state in the reporting path.
• A new integrator can wire warlock into a fresh project's harness (any shape) with ≤1 line and no lifecycle knowledge.
• Concurrent/parallel runs don't share or clobber scan state.

Context: surfaced while integrating warlock into the PostHog wizard (PostHog/wizard, yara-improvements branch).

[sarahxsanders]

North star: design for the harness we haven't seen

The real goal is open-source warlock that anyone can hook into any agent harness in a few lines — homegrown loops, research agents, daemons, serverless functions, multi-agent swarms, whatever. We can't anticipate those shapes, so the design driver must be the unknown harness, not the ones we happen to have.

The two PostHog consumers below are proof points, not design targets. The moment warlock is tuned to fit the wizard or agent_platform specifically, it bakes in an assumption that breaks the next integrator. The test isn't "does it fit ours?" — it's "did we have to assume anything about ours?"

Assume nothing about the host

• No clear "end" (suspend/resume, daemons, infinite streams exist).
• Not single-threaded or single-tenant (concurrent, multi-customer exist).
• Not one tool-execution chokepoint (many harnesses have several).
• No fixed process model (in-process / subprocess / container).
• No known reporting destination (stdout / bus / file / callback).

So the floor is the smallest possible contract

• scan(content) -> matches — pure, stateless, no lifecycle. The integrator calls it wherever their tools execute. This alone is a complete, useful integration.
• Results are pushed the instant they're found (returned / via onMatch). Never accumulated — accumulation needs an "end" we can't assume.
• Everything else is opt-in sugar — a per-run scanner instance, an aggregated summary, dispose hooks — for harnesses that happen to want it. The default path needs none of it.

"Easy to set up" = one function, bundled rules, a five-line hello-world. Layers you grow into, not ceremony you start with.

---

Proof point A — PostHog wizard (the "easy" end)

Single-user CLI, one run, clear finish. Looks like the case where a shared buffer + flush-at-end is fine — and it mostly is. But the wizard now has an orchestrator (behind a flag) where one run fans out into parallel subagent tasks in the same process. It stays single-customer with a clean top-level end (no leak, no suspend/resume), so flush-at-end still fires correctly — but the parallel tasks all dump into one unlabeled buffer. It can't answer "which subagent tripped the scanner?" So even the easy consumer wants per-run / per-task isolation. The wizard's current stopgap (a process-global buffer + an idempotent end-of-run finalizer) is safe-but-lossy here.

Proof point B — PostHog agent_platform (the opposite end)

One Node process runs ~8 concurrent sessions for different customers, and sessions can suspend and resume (no reliable "end"). Here a shared buffer is an actual cross-customer leak, and flush-at-end has no "end" to fire at. The codebase's own rules forbid module-level run state. The minimal contract maps cleanly:

• Create the scanner per session, in the same closure as the rest of the session's state (rules compile once at worker startup, shared + immutable; results isolated per session).
• Block at the tool seam by wrapping each tool's execute — the same pattern the existing approval gate already uses (block → deny the call, warn → allow + emit, allow → pass).
• Stream matches via onMatch onto the harness's existing event bus / log sink, tagged with session + team — at scan time, so suspend/resume is a non-issue.
• One altitude choice: tools run in a no-network sandbox, so the runner seam sees tool args/results but not in-sandbox actions; scanning the actual actions means a second hook inside the sandbox dispatcher. Start at the runner seam.

---

These two bracket a wide range — single-user/clear-end vs concurrent/multi-tenant/no-end. If the same scan() + push contract fits both without warlock knowing anything about either, it will fit harnesses nobody has built yet. That's the bar.