cyborg-hunter 0.5.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

@@ -4,25 +4,29 @@ Detects AI-tool use during browser-based behavioral experiments. Captures paste,
 
 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.
 
-### Example: 100-participant Prolific pilot
+### 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 |
+The bundled three-participant synthetic dataset (`examples/synthetic-pilot/` — every number hand-authored, no real participant behind any of it) triages like this:
 
-6 hard-flagged + 12 soft-flagged out of 100. Per-participant tab-away timeline (rank 4, 42 events across 15 trials):
+| 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:
+
+![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)
+
+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/`, `studies/` — tests, package docs, full-study fixtures
+- `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
 
@@ -41,9 +45,11 @@ Browser (experiment page) — load via unpkg or copy `dist/*.js` into your proje
 <!-- 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.4.0/dist/...`.
+For production studies, pin a version: `https://unpkg.com/cyborg-hunter@0.7.0/dist/...`.
 
 ## Plug into a jsPsych experiment
 
@@ -83,7 +89,47 @@ cyborg-hunter report              # writes ./cyborg-hunter-report/
 open cyborg-hunter-report/index.html
 ```
 
-Output: `summary.csv` (per-participant columns), `triage.md` (ranked list), `event-log.csv` (chronological events), `images/` (per-participant mouse paths, tab timelines, typing profiles), `index.html` (landing page).
+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();
+```
+
+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
 
@@ -95,16 +141,18 @@ Output: `summary.csv` (per-participant columns), `triage.md` (ranked list), `eve
 | Tab-away | `visibilitychange` + `blur`/`focus` | Soft (weighted) |
 | Browser sidebar | `innerWidth` delta + layout compression | Soft (weighted) |
 | Suspicious typing speed | chars/sec exceeding preset threshold | Soft (weighted) |
-| Synthetic insertion | text appearing without keystrokes | 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 | Soft (weighted) |
-| AI-extension content scripts | DOM scan for known extension selectors | 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` / `standard` (default) / `strict`. Per-signal thresholds: [docs/signals-reference.md](docs/signals-reference.md).
 
-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) — captured as `ai_use` / `ai_report` columns.
+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.)
+
+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).
 
 ## What it doesn't detect
 
@@ -114,21 +162,30 @@ The optional **guard** extensions add: fullscreen / sidebar / focus enforcement
 
 ## Documentation
 
+- [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
-- [docs/design-decisions.md](docs/design-decisions.md) — architecture rationale
+
+## Development
+
+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
 
 ```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.4.0}
+  license = {MIT}
 }
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cyborg-hunter",
-  "version": "0.5.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(' ');
+}