cyborg-hunter 0.4.0 → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,110 @@
+# Changelog
+
+All notable changes to **cyborg-hunter** are documented here. This project follows
+[Semantic Versioning](https://semver.org).
+
+## [0.7.0] — 2026-07-14
+
+### Added
+- Session replay recorder (`dist/cyborg-hunter-replay.js`, opt-in): captures pointer,
+  keys, clipboard, scroll, touch, viewport, and (at the `dom` tier) DOM snapshots +
+  mutations. Wire format is jsPsych's `SessionRecording v1` with a `ch_extensions`
+  namespace.
+- CLI report gains a per-participant replay viewer (scrub bar, cursor trail, event
+  markers); `dom`-tier recordings reconstruct the page in a sandboxed iframe.
+- Autosave and CLI ingest of replay artifacts, with ownership verification and
+  reload-collision handling.
+- Guard-honeypot and guard-friction events are captured in the replay stream.
+
+### Changed
+- Replay viewer uses a per-trial camera model for cursor/DOM alignment; legacy
+  recordings fall back to a clearly-labeled reduced-alignment mode.
+- Password inputs are redacted unconditionally in replay capture; clipboard events
+  record lengths only, not content.
+
+### Fixed
+- `drop` listener was incorrectly gated on the `paste` signal flag.
+- Idle-gap and element-trace timers leaked per session instead of being trial-scoped.
+- Edge-exit analysis silently found nothing on modern payloads due to a mismatched
+  time base.
+- Shape-3 (top-level array) ingest dropped outer trial fields and skipped tab-away
+  normalization.
+- Malformed replay artifacts no longer abort the report; `autoSave()` no longer
+  throws on circular/BigInt data.
+
+## [0.6.2] — 2026-07-12
+
+### Fixed
+- Cut events now count toward the hard-copy screenout (previously recorded but
+  never incremented the session copy count).
+- Misconfigured scoring overrides (e.g. a nested typo) now warn instead of
+  silently disabling a rule.
+- Fullscreen detection is prefix-aware, fixing false violations on Safari <16.4
+  and some iOS WebViews.
+- Honeypot re-initialization no longer inherits a prior run's violations/state.
+- `decoyAnswer: false` per-trial opt-out is now honored (was coerced to `null`).
+- A payload with both `trials` and `responses` no longer loses its integrity trials.
+- A non-array signal field no longer crashes the report; ingest now coerces and warns.
+- A numeric `trialId`/`ruleId` no longer crashes the trajectory renderer.
+- `findGuardViolations()` now scans all trials instead of locking onto the first.
+
+### Added
+- Warnings for an unresolved `participantIdField`, duplicate participant IDs, an
+  unmatched `phaseScope` phase name, and a non-numeric `scoring.softScoreThreshold`.
+
+## [0.6.1] — 2026-07-06
+
+### Added
+- `endTrial()` stamps a wall-clock ISO `timestamp` on the trial report.
+- Session-level `tabAwayEvents[]` alongside `tabAwaySums`, preserving full timing
+  for tab-aways outside `startTrial`/`endTrial`.
+- `participantIdField` accepts dot-paths (e.g. `"metadata.sessionId"`).
+- `sessionIntegrityPath`, `phaseScope`, and `trajectoryDisplayOrder` config options.
+- `showPlatformId` flag (default off) to render a platform ID as a secondary line
+  in the HTML report.
+- `--config-file` accepted as an alias of `--config`.
+
+### Changed
+- `layoutShifts` renamed to `viewportWidthShifts` (old key kept as a deprecated
+  alias); the signal measures viewport-width changes, not Web Vitals CLS.
+- Viewport-shift logging is debounced (250ms default) instead of firing per
+  animation frame.
+- Trajectory panels are tinted by phase; `triage.md` carries an explicit Tier column.
+
+### Fixed
+- `sessionIntegrityPath` no longer accepts a wrong-shaped object at the resolved
+  path, which had silently zeroed downstream signals.
+
+## [0.6.0] — 2026-06-25
+
+No public API was removed. Re-running the report on existing data may shift
+triage scores/ordering (sidebar, tab-away, and hard-flag corrections); newly
+collected data no longer saves raw per-keystroke timings by default.
+
+### Changed
+- Sidebar events are counted as distinct openings, not raw log entries.
+- Hard-flag fallback now uses the cumulative session total against the count
+  threshold, not per-trial hits.
+- Tab-away binning matches the runtime's strict cutoff.
+- Triage ranks tier-first (hard → soft → clean), then by score.
+- The CLI honors each participant's own saved thresholds instead of generic defaults.
+
+### Added
+- Guard-honeypot self-disclosure surfaced in the report (`honeypot_ai_use`,
+  `honeypot_ai_report` columns).
+- `finalize()` persists the runtime config so the CLI can reconstruct each
+  participant's screening settings.
+
+### Privacy
+- Raw per-keystroke timings are no longer persisted by default
+  (`keystrokeDynamics` toggle); only derived typing speed is kept unless opted in.
+
+### Fixed
+- Restored the authoritative session score for two saved formats that had been
+  dropped, causing over-flagging.
+- Session-timeline offset estimation no longer drifts for legacy participants.
+
+## [0.5.1] and earlier
+
+See the git tags `v0.4.0`, `v0.5.0`, `v0.5.1` for prior releases (no changelog
+was kept before 0.6.0).

package/CITATION.cff

@@ -0,0 +1,29 @@
+cff-version: 1.2.0
+title: cyborg-hunter
+message: >-
+  If you use this software in academic work, please cite it as below.
+type: software
+authors:
+  - family-names: Konuk
+    given-names: Can
+  - family-names: Btesh
+    given-names: Victor
+  - family-names: Nunez
+    given-names: Jose Luis
+repository-code: https://github.com/konukcan/cyborg-hunter
+abstract: >-
+  A JavaScript library and CLI for detecting AI-tool use during browser-based
+  behavioral experiments. Captures paste, copy, drag, tab-away, mouse
+  trajectories, browser sidebar openings, and other signals that compromise
+  data quality on Prolific, MTurk, and classroom studies. Produces a triage
+  report ranking participants by suspiciousness.
+keywords:
+  - integrity-monitoring
+  - cheating-detection
+  - online-experiments
+  - jspsych
+  - prolific
+  - behavioral-research
+license: MIT
+version: 0.7.0
+date-released: '2026-07-14'

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Can Konuk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,96 +2,134 @@
 
 Detects AI-tool use during browser-based behavioral experiments. Captures paste, copy, drag, tab-away, mouse trajectories, browser sidebar openings, and other signals that compromise data quality on Prolific / MTurk / classroom studies. Produces a triage report ranking participants by suspiciousness.
 
-### Example: 100-participant Prolific pilot
+Optional companion deterrence modules (`extension-guard-friction.js`, `extension-guard-honeypot.js`) ship in the same package: friction enforces fullscreen + blocks sidebars + scrambles content during violations + asks cooperative LLMs to refuse; honeypot exposes both hidden and visible bait fields that AI agents fill while human participants don't see them.
 
-Top of the triage list (excerpt — full ranked CSV in the report):
+### Example: what a report looks like
 
-| Rank | Participant | Score | Hard | Reason |
-|------|-------------|-------|------|--------|
-| 1 | 67c1d6d98c8787be36609212 | 4078 | no | 1 tab-away 3–10s; 2 flickers <3s; fast typing on 9 trials; **1015 synthetic insertions** |
-| 2 | 69bc21dd22f17b2337957511 | 179 | **YES** | 21 paste events; 3 copy events; 9 tab-aways ≥10s; 3 sidebar events; 21 layout shifts |
-| 3 | 69b9f3184e0896ef41b99aa8 | 152 | no | 38 synthetic insertions |
-| 4 | 5d350282cec7150015d16494 | 131 | **YES** | 5 paste events; 10 copy events; 22 tab-aways ≥10s; 5 tab-aways 3–10s; 15 flickers <3s |
-| 5 | 696a9773a84c5f9d4a930874 | 128 | **YES** | 15 paste events; 23 tab-aways ≥10s; 11 tab-aways 3–10s; 9 flickers <3s |
-| 6 | 69b594dccc64df571f092147 | 123 | **YES** | 12 paste events; 16 tab-aways ≥10s; 4 tab-aways 3–10s |
-| 7 | 69cd5149cf6fc07126897938 | 120 | **YES** | 15 paste events; 1 copy events; 19 tab-aways ≥10s; 16 flickers <3s |
-| 8 | 6314bc49055e150c92f4736e | 112 | **YES** | 12 paste events; 14 tab-aways ≥10s; 46 tab-aways 3–10s; 3 flickers <3s |
+The bundled three-participant synthetic dataset (`examples/synthetic-pilot/` — every number hand-authored, no real participant behind any of it) triages like this:
 
-Of 100 participants, 6 hard-flagged (count thresholds crossed) and 12 soft-flagged (weighted score over threshold). Per-participant tab-away timeline below — this is rank 4, with 42 tab-away events across 15 trials. Reviewers can scan the timeline visually instead of staring at a 30-column CSV:
+| Rank | Participant | Tier | Score | Reason |
+|------|-------------|------|-------|--------|
+| 1 | SYN-HARD-03 | **HARD** | 18 | 2 paste events; 1 copy events; 3 tab-aways ≥10s; 2 flickers ≤3s; fast typing on 1 trials |
+| 2 | SYN-SOFT-02 | soft | 21 | 3 copy events; 1 tab-away ≥10s; 2 tab-aways 3–10s; 1 sidebar event |
+| 3 | SYN-CLEAN-01 | clean | 0 | 1 flicker ≤3s; 1 layout shifts |
 
-![Tab-away timeline showing 42 tab-away events across 15 trials. Most trials have multiple long red bars (≥10s tab-aways), with some shorter orange (3-10s) and grey flicker (<3s) events.](docs/images/example-tab-timeline.png)
+Ranking is **tier-first** (hard-triggered lead, then soft, then clean), score-descending within a tier — rank 1 outranks rank 2 despite the lower score, because hard evidence beats any accumulation of soft evidence. The score is `5×paste + 5×copy + 3×sidebar + 1×tab-away` (counting tab-aways longer than the participant's tab-away threshold — 3s by default, 5s for the strict preset); synthetic insertions and fast typing are surfaced in the reason but do not drive the score. See [docs/cli-reference.md → Triage scoring](docs/cli-reference.md#triage-scoring). The HTML report for the same dataset:
 
-Two pieces:
+![HTML report: tier-sorted participant list on the left; per-signal counts, score breakdown, paste evidence, and typing profile for the hard-flagged participant.](docs/assets/report-example.png)
 
-- A small JS library you load in your experiment that records signals as participants work.
-- A CLI that reads the resulting data files and renders an HTML report.
+Reproduce the table and page yourself: run `cyborg-hunter report` in `examples/synthetic-pilot/` ([docs/worked-example.md](docs/worked-example.md) interprets every number).
+
+## Repo layout
+
+- `src/core/` — signal-collection library (the monitor)
+- `src/jspsych/` — jsPsych extension adapters (one per concern)
+- `src/cli/` + `bin/` — CLI that turns saved data into the triage report
+- `tests/`, `docs/` — tests, package docs
+- `examples/synthetic-pilot/` — synthetic three-participant dataset for trying the CLI (see [docs/worked-example.md](docs/worked-example.md))
 
 ## Install
 
-For analysis (CLI):
+CLI (analysis):
 
 ```bash
 npm install -g cyborg-hunter
 ```
 
-For the experiment page (library), three options:
+Browser (experiment page) — load via unpkg or copy `dist/*.js` into your project:
 
 ```html
-<!-- Option 1: load via unpkg (always serves latest published version) -->
+<!-- Signal collection -->
 <script src="https://unpkg.com/cyborg-hunter/dist/cyborg-hunter.min.js"></script>
-<script src="https://unpkg.com/cyborg-hunter/dist/jspsych-cyborg-hunter.js"></script>
-
-<!-- Option 2: pin a specific version (recommended for production studies) -->
-<script src="https://unpkg.com/cyborg-hunter@0.3.0/dist/cyborg-hunter.min.js"></script>
-<script src="https://unpkg.com/cyborg-hunter@0.3.0/dist/jspsych-cyborg-hunter.js"></script>
-
-<!-- Option 3: copy dist/cyborg-hunter.min.js + dist/jspsych-cyborg-hunter.js
-     into your project for fully offline / no-CDN-dependency setups. -->
+<script src="https://unpkg.com/cyborg-hunter/dist/extension-cyborg-hunter.js"></script>
+<!-- Optional: deterrence + bait detection -->
+<script src="https://unpkg.com/cyborg-hunter/dist/extension-guard-friction.js"></script>
+<script src="https://unpkg.com/cyborg-hunter/dist/extension-guard-honeypot.js"></script>
+<!-- Optional: session replay recorder -->
+<script src="https://unpkg.com/cyborg-hunter/dist/cyborg-hunter-replay.js"></script>
 ```
 
+For production studies, pin a version: `https://unpkg.com/cyborg-hunter@0.7.0/dist/...`.
+
 ## Plug into a jsPsych experiment
 
 ```javascript
 const jsPsych = initJsPsych({
   extensions: [
-    { type: jsPsychCyborgHunter, params: { participantId: subject.id, preset: 'standard' } }
+    { type: jsPsychCyborgHunter, params: { participantId: participant_id, preset: 'standard' } },
+    { type: jsPsychGuardFriction },     // optional
+    { type: jsPsychGuardHoneypot }      // optional
   ],
   on_finish: function () {
-    // REQUIRED: jsPsych 7 has no on_finish_experiment extension hook, so the
-    // session-level signals must be flushed manually before saving data.
-    jsPsych.extensions['cyborg-hunter'].finalize();
+    jsPsych.extensions['guard-friction'].finalize();   // stop friction first
+    jsPsych.extensions['guard-honeypot'].finalize();   // then attach data
+    jsPsych.extensions['cyborg-hunter'].finalize();    // then save
     jsPsych.data.get().localSave('csv', 'data.csv');
   }
 });
 
-// Opt every trial in to monitoring (single forEach beats editing N trials):
-timeline.forEach(t => {
-  t.extensions = (t.extensions || []).concat([{ type: jsPsychCyborgHunter }]);
-});
-
+timeline.push(jsPsychGuardFriction.entryTrial());     // user-gesture fullscreen entry
+timeline.forEach(t => t.extensions = (t.extensions || []).concat([
+  { type: jsPsychCyborgHunter },
+  { type: jsPsychGuardFriction },
+  { type: jsPsychGuardHoneypot }
+]));
 jsPsych.run(timeline);
 ```
 
-Full setup walk-through, including standalone (non-jsPsych) usage and per-trial parameters: [`docs/using-cyborg-hunter.md`](docs/using-cyborg-hunter.md).
+`participantId` must exist before `initJsPsych`. Full walk-through (per-trial params, standalone non-jsPsych use, opt-in/exclude modes): [docs/using-cyborg-hunter.md](docs/using-cyborg-hunter.md).
 
 ## Generate a report
 
-After data collection, in the directory holding your data files:
-
 ```bash
-cyborg-hunter init      # writes cyborg-hunter.config.json
+cd <your-data-dir>
+cyborg-hunter init                # writes cyborg-hunter.config.json
 # edit config: dataDir, filePattern, participantIdField
-cyborg-hunter report    # writes ./cyborg-hunter-report/
+cyborg-hunter report              # writes ./cyborg-hunter-report/
 open cyborg-hunter-report/index.html
 ```
 
-The report contains:
+Output: `summary.csv` (per-participant columns), `triage.md` (ranked list), `event-log.csv` (chronological events), `images/` (per-participant mouse paths, session timelines, typing profiles), `index.html` (landing page).
+
+## Session replay
+
+The optional replay recorder captures what the participant did and (at the
+`dom` tier) what the page looked like, so a flagged session can be reviewed
+visually instead of adjudicated from counts alone. Recordings use jsPsych
+PR #3661's `SessionRecording v1` wire format with a `ch_extensions` block.
+
+```javascript
+// jsPsych: one more extension (declare anywhere; finalize LAST)
+{ type: jsPsychCyborgHunterReplay, params: {
+    participantId: participant_id,
+    tier: 'dom',                                          // 'trace' (default) | 'dom'
+    autoSave: { mode: 'datapipe', experimentId: 'ABC123' } } }
+// on_finish: await jsPsych.extensions['cyborg-hunter-replay'].finalize();
+```
+
+```javascript
+// Standalone (any experiment, no jsPsych)
+const rec = CyborgHunterReplay.attach({ participantId, tier: 'dom',
+  autoSave: { mode: 'datapipe', experimentId: 'ABC123' } });
+rec.startSession();
+rec.startTrial({ trialId: 'r1' });   // optional bracketing
+rec.endTrial();
+rec.stopSession('finished');
+await rec.autoSaveNow();
+```
 
-- `summary.csv` — one row per participant, every signal as a column
-- `triage.md` — ranked list with one-line "why flagged" per participant
-- `event-log.csv` — chronological copy/paste/drop/tab-away events
-- `images/` — per-participant mouse trajectories, tab timelines, typing-speed profiles
-- `index.html` — landing page that ties it together
+The artifact saves as `<pid>-replay-<epoch>.json` next to your data; the CLI
+picks it up automatically and the report gains a **Session replay** section
+per participant (lazy-loaded scrub viewer — cursor trail, clicks, away
+bands, and a sandboxed reconstruction of the page for `dom`-tier
+recordings). On `dom`-tier recordings the cursor is verified per
+interaction by a five-way alignment self-check — any click it can't
+confirm draws an explicit uncertain marker instead of a wrong one, and
+recordings made before this guarantee existed replay under a reduced-
+guarantees banner. Password fields are always redacted; see
+[docs/using-cyborg-hunter.md](docs/using-cyborg-hunter.md) for the privacy
+model, data-volume guidance, delivery semantics, and the alignment
+guarantee in full.
 
 ## What it detects
 
@@ -102,56 +140,56 @@ The report contains:
 | Copy | Clipboard `copy` events | Soft (weighted) |
 | Tab-away | `visibilitychange` + `blur`/`focus` | Soft (weighted) |
 | Browser sidebar | `innerWidth` delta + layout compression | Soft (weighted) |
-| Suspicious typing speed | chars/sec exceeding the preset's threshold | Soft (weighted) |
-| Synthetic insertion | text appearing without keystrokes | Soft (weighted) |
-| Foreign input | typing landing outside the experiment container | Soft (weighted) |
-| Idle gaps | input inactivity (potential context-switch out) | Soft (weighted) |
-| AI-extension content scripts | DOM scan for known extension selectors | Soft (weighted) |
-| Mouse trajectories | 20Hz polling + path-efficiency / direction-change metrics | Diagnostic |
+| Suspicious typing speed | chars/sec exceeding preset threshold | Soft (weighted) |
+| Synthetic insertion | text appearing without keystrokes | Diagnostic (collected, not scored) |
+| Foreign input | typing landing outside experiment container | Soft (weighted) |
+| Idle gaps | input inactivity | Diagnostic (collected, not scored) |
+| AI-extension content scripts | DOM scan for known extension selectors | Diagnostic (collected, not scored) |
+| Mouse trajectories | 20Hz polling + path-efficiency metrics | Diagnostic |
 | Window/screen geometry | polled + resize-event capture, with zoom inference | Diagnostic |
 
-Three presets — `permissive` (pilot), `standard` (default), `strict` (high-stakes). Per-signal thresholds documented in [`docs/signals-reference.md`](docs/signals-reference.md).
+Three presets: `permissive` / `standard` (default) / `strict`. Per-signal thresholds: [docs/signals-reference.md](docs/signals-reference.md).
 
-## What it doesn't detect
+Tab-aways are captured session-wide, not just during trials: since 0.6.1 the session report keeps a timestamped `tabAwayEvents[]` for every tab-away — including those during consent, tutorial, or study phases — so session timelines can place them. Data saved with older versions keeps only durations (`tabAwaySums`) for off-trial events; the timeline footer counts those as unplaceable. (0.6.1 also renames the `layoutShifts` signal to `viewportWidthShifts` — it measures viewport-width changes, not Web-Vitals CLS — keeping the old key as a deprecated alias.)
 
-- **Native browser AI sidebars.** Chrome's built-in Gemini panel and similar are not browser extensions and leave no extension content scripts. The `innerWidth_delta` heuristic still catches them as a generic sidebar event, but the named-extension column will be empty.
-- **Screen-share / second device.** A participant reading questions on screen 1 and querying ChatGPT on a phone produces no detectable trace from the browser.
-- **AI text edited and retyped.** A determined participant who copies AI output, retypes it character-by-character, and never tab-switches will look clean. The mouse-trajectory and typing-rhythm signals make this much harder than it sounds, but the tool isn't a polygraph.
+The optional **guard** extensions add: fullscreen / sidebar / focus enforcement (with content-scrambling overlay on violation), AI refusal notices in the DOM, and honeypot fields (hidden + visible bait) that catch sidebar-LLMs and agentic browsers (Browser Use, Operator, Computer Use). The visible bait writes `ai_use` / `ai_report` columns into your saved data, and the report surfaces them in `summary.csv` as `honeypot_ai_use` / `honeypot_ai_report` (plus a "self-reported AI use" note in the triage reason).
 
-These are stated up front so reviewers know what flagging really represents.
+## What it doesn't detect
 
-## How it works
+- **Native browser AI sidebars** (Chrome Gemini, Edge Copilot) — they leave no extension content scripts. The `innerWidth_delta` heuristic still catches them as generic sidebar events, but the named-extension column stays empty.
+- **Screen-share / second device** — an LLM on a phone reading the screen leaves no in-browser trace.
+- **AI text edited and retyped** — a determined participant who retypes character-by-character without tab-switching looks clean. Mouse-trajectory and typing-rhythm signals raise the bar but it isn't a polygraph.
 
-The library hooks browser events that are universally available (Clipboard API, Visibility API, MouseEvent, Performance API, MutationObserver) and tracks two scopes in parallel:
+## Documentation
 
-- **Session-scoped monitors** start at experiment load and run continuously: tab-away, sidebar/extension detection, layout shifts, window position polling.
-- **Trial-scoped trackers** bracket each trial: mouse path, typing speed, paste/copy/drop within the trial's response window, idle gaps.
+- [docs/quickstart.md](docs/quickstart.md) — zero to triage report
+- [docs/worked-example.md](docs/worked-example.md) — full pipeline run on the bundled synthetic dataset, outputs interpreted
+- [docs/interpreting-signals.md](docs/interpreting-signals.md) — scores vs tiers, viewport shifts, phase scoping: the common misreadings
+- [docs/release-notes-0.7.0.md](docs/release-notes-0.7.0.md) — what 0.7.0 (and 0.6.2) change in data, config, and reports
+- [docs/release-notes-0.6.1.md](docs/release-notes-0.6.1.md) — the 0.6.1 release notes
+- [docs/using-cyborg-hunter.md](docs/using-cyborg-hunter.md) — full integration guide
+- [docs/signals-reference.md](docs/signals-reference.md) — every signal with thresholds per preset
+- [docs/configuration.md](docs/configuration.md) — config file fields and CLI flags
+- [docs/cli-reference.md](docs/cli-reference.md) — commands and output structure
 
-At the end of each trial, an "integrity" object is attached to that trial's data. At the end of the experiment, session-level rollups are attached to the last trial. The CLI ingests both standard jsPsych CSV output and project-specific JSON formats (`docs/configuration.md` describes the config-file fields).
+## Development
 
-## Documentation
-
-- [`docs/using-cyborg-hunter.md`](docs/using-cyborg-hunter.md) — full integration guide (jsPsych and standalone)
-- [`docs/signals-reference.md`](docs/signals-reference.md) — every signal with thresholds per preset
-- [`docs/configuration.md`](docs/configuration.md) — config file fields and CLI flags
-- [`docs/cli-reference.md`](docs/cli-reference.md) — commands and output structure
-- [`docs/design-decisions.md`](docs/design-decisions.md) — why the architecture looks the way it does (two-tier scoring, dual lifecycle, `finalize()`, zoom robustness, etc.)
+Run the test suite with `npm test`. Before publishing, run `scripts/check-public-hygiene.sh` — it fails if any tracked file contains personal or internal-process leakage.
 
 ## Citation
 
-If you use cyborg-hunter in academic work, please cite:
-
 ```bibtex
-@software{konuk2026cyborghunter,
-  author  = {Konuk, Can},
-  title   = {cyborg-hunter: integrity monitoring for online behavioral experiments},
+@software{konuk_cyborg_hunter,
+  author  = {Konuk, Can and Btesh, Victor and Nunez, Jose Luis},
+  title   = {cyborg-hunter: detecting AI-tool use in browser-based behavioral experiments},
   year    = {2026},
+  version = {0.7.0},
   url     = {https://github.com/konukcan/cyborg-hunter},
-  version = {0.3.0}
+  license = {MIT}
 }
 ```
 
-GitHub also renders a "Cite this repository" button (sidebar of the repo page) from the CITATION.cff file in the root.
+A "Cite this repository" button is rendered from `CITATION.cff`.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cyborg-hunter",
-  "version": "0.4.0",
+  "version": "0.7.0",
   "description": "Detect LLM-assisted 'cyborg' behavior in online behavioral experiments",
   "main": "dist/cyborg-hunter.min.js",
   "module": "dist/cyborg-hunter.esm.js",
@@ -11,14 +11,20 @@
     "build": "node build.js",
     "test:browser": "echo 'Open tests/browser/integrity-monitor.test.html in a browser'",
     "test:cli": "node --test tests/cli/*.test.js",
+    "test:core": "node --test tests/core/*.test.js",
     "test:jspsych": "node --test tests/jspsych/*.test.js",
-    "test": "npm run test:cli && npm run test:jspsych"
+    "test": "npm run test:core && npm run test:replay && npm run test:cli && npm run test:jspsych",
+    "test:replay": "node --test tests/replay/*.test.js",
+    "test:browser:replay": "node tests/browser/replay/run-replay-tests.mjs",
+    "test:browser:alignment": "node tests/browser/replay/cursor-alignment.battery.mjs"
   },
   "files": [
     "dist/",
     "bin/",
     "src/",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md",
+    "CITATION.cff"
   ],
   "keywords": [
     "integrity",
@@ -47,6 +53,7 @@
     "canvas": "^3.2.3"
   },
   "devDependencies": {
+    "ajv": "^8.20.0",
     "esbuild": "^0.21.0",
     "happy-dom": "^20.9.0"
   },

package/src/cli/analyzers/edge-exit.js

@@ -28,7 +28,10 @@ export function detectEdgeExitForTrial(trial, config) {
   const events = [];
 
   for (const ta of tabAways) {
-    const taStart = ta.start;
+    // Modern ingest normalizes tab-away starts to trial-relative startRel_ms;
+    // mouse t is already trial-relative, so both must use the same base.
+    // Legacy payloads (no startRel_ms) carried trial-relative start directly.
+    const taStart = ta.startRel_ms ?? ta.start;
     // Find mouse move events in the TIME_WINDOW before this tab-away
     const beforeTA = mouse.filter(m =>
       m.type === 'move' && m.t < taStart && m.t > taStart - TIME_WINDOW);

package/src/cli/analyzers/phase-scope.js

@@ -0,0 +1,83 @@
+// src/cli/analyzers/phase-scope.js
+// Pre-registration phase scoping.
+//
+// Studies that pre-register integrity scoring over a subset of phases (e.g.
+// counting only classification-phase signals, excluding a warm-up or
+// debrief phase) previously had to enforce that in their own analysis
+// pipeline — the CH triage scored the whole session and was misleading read
+// in isolation. config.phaseScope filters which trials feed the ANALYZERS
+// (summary, edge-exit, triage):
+//
+//   "phaseScope": { "include": ["classification"] }
+//   "phaseScope": { "exclude": ["warmup", "post_task_query", "debrief"] }
+//
+// `include` (when non-empty) keeps only listed phases; `exclude` then removes
+// its phases. A trial without a `phase` field counts as "default" — data whose
+// trials carry no phase labels should scope with `exclude`, not `include`.
+//
+// What scoping does NOT touch:
+//   * Renderers still receive the full participant — the evidence (timelines,
+//     trajectories, paste texts) stays visible; only the scores are scoped.
+//   * Ambient session-level environment signals with no phase attribution
+//     (sidebar events, keyboard shortcuts, viewport-width shifts, zoom
+//     changes) remain session-wide — they aren't tied to any one phase, so
+//     scoping them wouldn't be meaningful. Response-level signals
+//     (paste/copy/drop/tab-away/typing) are the ones that scope.
+//
+// Downstream, computeParticipantSummary sees `phaseScoped: true` and switches
+// to per-trial aggregation: session-level tabAwaySums and the authoritative
+// session soft score cover the WHOLE session, so they cannot be used for a
+// scoped verdict.
+
+export function applyPhaseScope(participants, phaseScope) {
+  const inc = Array.isArray(phaseScope?.include) && phaseScope.include.length > 0
+    ? new Set(phaseScope.include) : null;
+  const exc = Array.isArray(phaseScope?.exclude) && phaseScope.exclude.length > 0
+    ? new Set(phaseScope.exclude) : null;
+  // No scope configured → hand back the SAME array (byte-identical pipeline).
+  if (!inc && !exc) return participants;
+
+  return participants.map(p => ({
+    ...p,
+    trials: (p.trials || []).filter(t => {
+      const phase = (t && t.phase) ?? 'default';
+      if (inc && !inc.has(phase)) return false;
+      if (exc && exc.has(phase)) return false;
+      return true;
+    }),
+    phaseScoped: true,
+  }));
+}
+
+// Returns the configured phaseScope phase names (from include and exclude)
+// that match NO trial anywhere in the cohort. A non-empty result almost always
+// means a typo (e.g. include:["clasification"]) — which, for an `include`,
+// silently filters EVERY trial from EVERY participant and reports the whole
+// cohort clean. report.js warns on this so the misconfiguration is visible.
+// Exported for testing.
+export function findUnmatchedPhaseScopePhases(participants, phaseScope) {
+  const configured = [
+    ...(Array.isArray(phaseScope?.include) ? phaseScope.include : []),
+    ...(Array.isArray(phaseScope?.exclude) ? phaseScope.exclude : []),
+  ];
+  if (configured.length === 0) return [];
+  const present = new Set();
+  for (const p of (participants || [])) {
+    for (const t of (p.trials || [])) {
+      present.add((t && t.phase) ?? 'default');
+    }
+  }
+  return configured.filter(name => !present.has(name));
+}
+
+// Human-readable one-liner for the console summary.
+export function describePhaseScope(phaseScope) {
+  const parts = [];
+  if (Array.isArray(phaseScope?.include) && phaseScope.include.length > 0) {
+    parts.push(`include=[${phaseScope.include.join(', ')}]`);
+  }
+  if (Array.isArray(phaseScope?.exclude) && phaseScope.exclude.length > 0) {
+    parts.push(`exclude=[${phaseScope.exclude.join(', ')}]`);
+  }
+  return parts.join(' ');
+}