[Vedant-200]

Summary

Adds the explicit SECFOO_SENSOR opt-in gate plus the watchlist and append-only runtime event formats to the package init.

Fixes #51

---

🤖 Generated by the DevPilot agent — please review before merging.

[vsn411]

Thanks for jumping in on the runtime reachability work. I'm going to close this one, and I'd like to explain why so the next attempt lands.

#51 is the tracking issue, not a task. Its body is a checklist of sub-issues (#52–#57, #66–#80), and Fixes #51 here would close that whole roadmap on merge. Each sub-issue is sized to be a PR on its own; pick one of those instead. #54 (import coverage files) has a good first issue label and a clear spec, and #52/#53 define the formats everything else depends on.

What would need to change in the code itself:

1. Location. This adds sensor/runtime code to src/secfoo/__init__.py, so every import secfoo loads it. Rule 0 in #51 is that installing secfoo never pulls in probe code paths. Runtime code should live in its own module (e.g. src/secfoo/runtime/), imported only by the commands that need it.
2. Event format. #53 defines the NDJSON contract: type: session | load | hit lines with session, finding_fingerprint, count, first_seen/last_seen, auth, stack_sample. The RuntimeEvent dataclass here is a different, flat schema, so anything built on it would have to be redone. Please build to #53 (and raise it in that thread if you think the format should change).
3. Watchlist format. #52 proposes version, generated_at, and entries with ecosystem and granularity, and asks for discussion before building. load_watchlist() drops all of those fields.
4. The SECFOO_SENSOR gate is in the wrong place. append_event() silently writes nothing unless SECFOO_SENSOR=1. Rule 0 is about probes not hooking into the app process; the coverage importer (#54) and secfoo runtime ingest write event files with no sensor running, so this gate would break them.
5. Tests. CONTRIBUTING asks for tests with any behavior change, and #53 specifically lists the cases: a valid file, a malformed line (skip and report, don't abort), and re-ingesting the same file without double counting.

If you'd like to take one of the sub-issues, comment on it so nobody duplicates the work, and feel free to ask questions there before writing code. Happy to review the next one.