cyborg-hunter 0.5.0 → 0.7.0

package/src/cli/analyzers/summary.js

@@ -10,6 +10,13 @@ export function computeSummary(participants, config) {
 export function computeParticipantSummary(participant, config) {
   const trials = participant.trials;
   const n = trials.length;
+  // Set by applyPhaseScope (config.phaseScope). Session-level aggregates
+  // (tabAwaySums, the authoritative soft score, anyHardTriggered) cover the
+  // WHOLE session, so a phase-scoped summary must ignore them and aggregate
+  // from the scoped trials instead. Ambient environment signals (sidebar,
+  // keyboard shortcuts, viewport shifts, zoom) stay session-wide by design —
+  // see phase-scope.js.
+  const phaseScoped = participant.phaseScoped === true;
 
   // Three-way tab-away duration bins for display. The 3s boundary matches
   // config.thresholds.tabAwayDurationMs — the scoring engine's soft-score cutoff.
@@ -17,8 +24,16 @@ export function computeParticipantSummary(participant, config) {
   //   flicker (<3s): OS/browser noise, notification glances — no scoring penalty
   //   medium (3-10s): deliberate brief checks — count toward soft score
   //   long   (≥10s): substantive absences — count toward soft score
-  const scoringCutoff_ms = config?.thresholds?.tabAwayDurationMs ?? 3000;
+  // Prefer the thresholds the LIBRARY actually screened this participant with
+  // (persisted in session.config.thresholds by finalize) so the report bins their
+  // data the same way the runtime did — e.g. a strict participant's 5s tab-away
+  // cutoff. Fall back to an analyst-side CLI threshold, then the default.
+  const savedThresholds = participant.session?.config?.thresholds || {};
+  const scoringCutoff_ms =
+    savedThresholds.tabAwayDurationMs ?? config?.thresholds?.tabAwayDurationMs ?? 3000;
   const longCutoff_ms = 10000;
+  const typingCutoff_cps =
+    savedThresholds.typingSpeedCps ?? config.typingSpeedThreshold_cps ?? 10;
 
   return {
     participantId: participant.participantId,
@@ -29,25 +44,26 @@ export function computeParticipantSummary(participant, config) {
     totalCopyEvents: sum(trials, t => (t.copyEvents || []).length),
     totalDropEvents: sum(trials, t => (t.dropEvents || []).length),
 
-    // Tab-away — leaving the experiment page (visibility change or blur)
-    totalTabAways: sum(trials, t => (t.tabAwayEvents || []).length),
-    tabAwayFlickerCount: sum(trials, t =>
-      (t.tabAwayEvents || []).filter(e => (e.duration_ms || 0) < scoringCutoff_ms).length),
-    tabAwayMediumCount: sum(trials, t =>
-      (t.tabAwayEvents || []).filter(e => {
-        const d = e.duration_ms || 0;
-        return d >= scoringCutoff_ms && d < longCutoff_ms;
-      }).length),
-    tabAwayLongCount: sum(trials, t =>
-      (t.tabAwayEvents || []).filter(e => (e.duration_ms || 0) >= longCutoff_ms).length),
-    totalTabAwayDuration_ms: sum(trials, t =>
-      (t.tabAwayEvents || []).reduce((s, e) => s + (e.duration_ms || 0), 0)),
-    trialsWithTabAway: trials.filter(t => (t.tabAwayEvents || []).length > 0).length,
+    // Tab-away — leaving the experiment page (visibility change or blur).
+    // Prefer session-level durations (cyborgHunter.tabAwaySums) which capture
+    // events anywhere in the session, including between trials and during
+    // gallery / consent / comprehension phases. Per-trial trials[*].tabAwayEvents
+    // only covers intervals while a trial is active, so it misses anything
+    // that happens during a study/learning phase — which is exactly where many
+    // participants go off-task.
+    ...computeTabAwayCounts(phaseScoped ? null : participant.session?.tabAwaySums, trials, scoringCutoff_ms, longCutoff_ms),
 
     // Typing speed — suspiciously fast typing may indicate paste or autocomplete
     meanTypingSpeed: avg(trials, t => t.charsPerSec || 0),
     trialsWithFastTyping: trials.filter(t =>
-      (t.charsPerSec || 0) > (config.typingSpeedThreshold_cps || 10)).length,
+      (t.charsPerSec || 0) > typingCutoff_cps).length,
+
+    // The runtime preset that screened this participant (when persisted).
+    preset: participant.session?.config?.preset ?? null,
+    // The resolved per-participant tab-away cutoff (ms) used for the bins above,
+    // so the triage reason can describe the bins with this participant's actual
+    // threshold (e.g. 5s for strict) instead of a hardcoded 3s.
+    tabAwayCutoffMs: scoringCutoff_ms,
 
     // Mouse — low event count or very efficient paths can indicate bot activity
     meanMouseEvents: avg(trials, t => (t.mouseEvents || []).length),
@@ -69,31 +85,148 @@ export function computeParticipantSummary(participant, config) {
     // Scoring — accumulated soft score and whether any hard signal fired
     totalSoftScore: sum(trials, t => t.trialSoftScore || 0),
 
-    // Session-level fields (preferred over per-trial aggregation when available)
-    sidebarEventCount: participant.session?.sidebarEvents?.length ?? trials.filter(t => (t.sidebarGapPx || 0) > 0).length,
+    // Session-level fields (preferred over per-trial aggregation when available).
+    // Count sidebar OPENINGS, not raw log entries. The runtime records a separate
+    // "opened" + "closed" entry per incident, and the innerWidth_delta and
+    // layout_compression checks can BOTH fire for one physical sidebar (same poll
+    // tick → same timestamp). countSidebarOpenings() collapses opens within one
+    // poll window into a single incident, so sidebarEventCount matches the number
+    // of times a sidebar actually appeared. The triage score weights "3 × sidebar"
+    // off this, so over-counting here would over-score.
+    sidebarEventCount: participant.session?.sidebarEvents
+      ? countSidebarOpenings(participant.session.sidebarEvents)
+      : trials.filter(t => (t.sidebarGapPx || 0) > 0).length,
     aiExtensionsFound: participant.session?.aiExtensionsFound || participant.trials[0]?.extensionsDetected || [],
     keyboardShortcutCount: participant.session?.keyboardShortcuts?.length || 0,
-    layoutShiftCount: participant.session?.layoutShifts?.length || 0,
+    // Canonical key since 0.6.1 is session.viewportWidthShifts (the signal
+    // measures viewport-width changes, not Web-Vitals CLS); layoutShifts is
+    // the deprecated alias older payloads carry. The summary field and the
+    // layout_shift_count CSV column keep their names for pipeline stability.
+    layoutShiftCount: (participant.session?.viewportWidthShifts ?? participant.session?.layoutShifts)?.length || 0,
     zoomChangeCount: participant.session?.zoomChanges?.length || 0,
     extensionInjectionCount: participant.session?.extensionInjections?.length || 0,
     devToolsEventCount: participant.session?.devToolsEvents?.length || 0,
-    authoritativeSoftScore: participant.score?.softScore ?? null,
-
-    // Authoritative hard-flag: prefer session's anyHardTriggered, else fall back to per-trial trialHits
-    // v3.1.0+ per-trial data: trialSignals.hard.*.trialHits counts this-trial occurrences
-    // (no .triggered boolean at per-trial level — that lives on session integrityScore).
-    // A participant is hard-flagged if any trial had any hard-signal hit.
-    hardTriggered: participant.score?.anyHardTriggered
-      ?? trials.some(t =>
-        t.trialSignals?.hard && Object.values(t.trialSignals.hard).some(s => (s.trialHits || 0) > 0)),
+    // Whole-session score — unusable for a phase-scoped verdict, so scoping
+    // nulls it and the scoped per-trial totalSoftScore drives soft flagging.
+    authoritativeSoftScore: phaseScoped ? null : (participant.score?.softScore ?? null),
+    // The soft-score threshold the LIBRARY actually screened this participant
+    // against (their preset's value, saved in the session report). Carried so the
+    // CLI can flag using each participant's real threshold rather than a generic
+    // analyst-side default.
+    softScoreThreshold: participant.score?.softScoreThreshold ?? null,
+
+    // Guard-honeypot self-disclosure (visible bait). null/'' when the honeypot
+    // was not used or the participant left it untouched.
+    honeypotAiUse: participant.honeypot?.aiUse ?? null,
+    honeypotAiReport: participant.honeypot?.aiReport ?? '',
+
+    // Authoritative hard-flag: prefer the session's anyHardTriggered. Fallback
+    // (no session score available) must use the CUMULATIVE sessionTotal vs the
+    // signal's countThreshold — NOT per-trial trialHits. A single paste
+    // (trialHits=1) when the threshold is 2 is NOT a hard trigger; using
+    // trialHits>0 fabricated hard flags and inflated the hard cohort whenever
+    // finalize() was missed. trialSignals.hard.*.sessionTotal is the running
+    // count at that trial, so any trial crossing its threshold = hard. When that
+    // data is absent, the signal can't promote the participant to hard.
+    // Phase-scoped verdicts recount raw hard-signal events within the scoped
+    // trials (scopedHardTriggered) — both the session's anyHardTriggered and
+    // trialSignals' sessionTotal accumulate across the whole session, so
+    // either would leak out-of-scope events into the verdict.
+    hardTriggered: phaseScoped
+      ? scopedHardTriggered(trials)
+      : participant.score?.anyHardTriggered
+      ?? trials.some(t => {
+        const hard = t.trialSignals?.hard;
+        if (!hard) return false;
+        return Object.values(hard).some(s =>
+          s && typeof s.sessionTotal === 'number' && typeof s.countThreshold === 'number'
+            && s.sessionTotal >= s.countThreshold);
+      }),
 
     // Pass through metadata for downstream use
     metadata: participant.metadata || {}
   };
 }
 
+// Re-derives the hard-flag verdict from raw event counts within a phase-scoped
+// trial set. The countThreshold is taken from the trialSignals snapshots (any
+// trial's — the runtime records the same threshold on every trial); signals
+// with no recorded threshold can't promote the participant to hard.
+function scopedHardTriggered(trials) {
+  const EVENT_FIELDS = { paste: 'pasteEvents', copy: 'copyEvents', drop: 'dropEvents' };
+  const counts = { paste: 0, copy: 0, drop: 0 };
+  const thresholds = {};
+  for (const t of trials) {
+    for (const [sig, field] of Object.entries(EVENT_FIELDS)) {
+      counts[sig] += (t[field] || []).length;
+      const th = t.trialSignals?.hard?.[sig]?.countThreshold;
+      if (typeof th === 'number') thresholds[sig] = th;
+    }
+  }
+  return Object.keys(counts).some(sig =>
+    typeof thresholds[sig] === 'number' && counts[sig] >= thresholds[sig]);
+}
+
+// Counts distinct sidebar OPENINGS from the session sidebarEvents log. The
+// runtime can emit two "opened" entries for one physical sidebar (the
+// innerWidth_delta and layout_compression checks fire in the same poll tick), so
+// counting raw "opened" entries over-counts. Walk the open/close events as a
+// state machine: an "opened" starts a new incident ONLY when transitioning from
+// the closed state, so coincident double-detection opens (no intervening close)
+// collapse to one, while a genuine open→close→open reopen counts as two — even a
+// fast one. Events are ordered by timestamp when present (double-detection opens
+// share a t and sort adjacent), else by array (push) order.
+export function countSidebarOpenings(sidebarEvents) {
+  const events = (sidebarEvents || []).filter(e => e && (e.type === 'opened' || e.type === 'closed'));
+  const ordered = events.every(e => typeof e.t === 'number')
+    ? [...events].sort((a, b) => a.t - b.t)
+    : events;
+  let open = false;
+  let count = 0;
+  for (const e of ordered) {
+    if (e.type === 'opened') {
+      if (!open) { count++; open = true; }
+    } else {
+      open = false;
+    }
+  }
+  return count;
+}
+
 // Helper: sum an array by applying fn to each element
 function sum(arr, fn) { return arr.reduce((s, x) => s + fn(x), 0); }
 
 // Helper: average an array by applying fn to each element
 function avg(arr, fn) { return arr.length === 0 ? 0 : sum(arr, fn) / arr.length; }
+
+// Helper: derive all tab-away count fields from a session-level durations
+// array (preferred — covers the whole session including gaps between trials
+// and during gallery / consent / comprehension phases) or fall back to
+// per-trial trials[*].tabAwayEvents (legacy — only covers active trials).
+function computeTabAwayCounts(sessionDurs, trials, scoringCutoff_ms, longCutoff_ms) {
+  let durations;
+  if (Array.isArray(sessionDurs)) {
+    durations = sessionDurs.map(d => Number(d) || 0);
+  } else {
+    durations = [];
+    for (const t of trials) {
+      for (const e of (t.tabAwayEvents || [])) {
+        durations.push(Number(e.duration_ms) || 0);
+      }
+    }
+  }
+  // "Meaningful" tab-aways (medium + long) are those that count toward the soft
+  // score. The runtime soft-scoring rule is STRICT ( duration > cutoff — see
+  // scoring.js and constants.js "longer than this counts" ), so the bins use the
+  // same `>` boundary: a tab-away exactly at the cutoff is a flicker, not scored.
+  // This keeps the report's tab-away count identical to what the library screened.
+  return {
+    totalTabAways: durations.length,
+    tabAwayFlickerCount: durations.filter(d => d <= scoringCutoff_ms).length,
+    tabAwayMediumCount: durations.filter(d => d > scoringCutoff_ms && d < longCutoff_ms).length,
+    tabAwayLongCount: durations.filter(d => d >= longCutoff_ms).length,
+    totalTabAwayDuration_ms: durations.reduce((s, d) => s + d, 0),
+    // `trialsWithTabAway` is per-trial-defined; keep it tied to trials[*]
+    trialsWithTabAway: trials.filter(t => (t.tabAwayEvents || []).length > 0).length,
+  };
+}

package/src/cli/analyzers/triage.js

@@ -3,10 +3,14 @@
 // This is the "start here" document for manual review — the researcher
 // reads the triage list top-to-bottom, inspecting the most suspicious first.
 //
-// The triage score is a single number combining:
-//   - Accumulated soft score from the scoring engine
-//   - Hard signal flags (these dominate with +100)
-//   - Edge-exit patterns, extension detection, synthetic insertions
+// Ranking has two parts (see rankTriage + decomposeScore below):
+//   - tier:  hard-triggered → soft-flagged → clean (primary sort key)
+//   - score: 5×paste + 5×copy + 3×sidebar-open + 1×tab-away (within a tier),
+//            where a "tab-away" is one longer than the participant's tab-away
+//            threshold (3s by default, 5s for the strict preset)
+// Other signals (AI extensions, keyboard shortcuts, layout/zoom, edge-exits,
+// synthetic insertions, foreign inputs, honeypot disclosure) are surfaced in the
+// reason and detail panes but do NOT contribute to the score.
 
 export function rankTriage(summaries, edgeExits, config) {
   const triageList = summaries.map((s, i) => {
@@ -21,14 +25,31 @@ export function rankTriage(summaries, edgeExits, config) {
       score,
       reason,
       hardTriggered: s.hardTriggered,
-      softFlagged: (s.authoritativeSoftScore ?? s.totalSoftScore) >= (config.scoring?.softScoreThreshold || 6),
+      // Threshold precedence: an explicit analyst-side CLI override
+      // (config.scoring.softScoreThreshold) wins for deliberate re-screening;
+      // otherwise use the participant's OWN saved threshold (what the library
+      // screened them against — e.g. 4 for the strict preset); else default 6.
+      // Using a hardcoded 6 here would mislabel strict-preset participants clean.
+      softFlagged: (s.authoritativeSoftScore ?? s.totalSoftScore) >=
+        (config.scoring?.softScoreThreshold ?? s.softScoreThreshold ?? 6),
       summary: s,
       edgeExitCount: totalEdgeExits
     };
   });
 
-  // Sort descending — most suspicious participants appear first
-  triageList.sort((a, b) => b.score - a.score);
+  // Sort tier-first (hard, then soft, then clean), and by score descending
+  // within a tier. A hard-triggered participant (paste/drop over its count
+  // threshold) is categorically more actionable than a high soft-signal count,
+  // so they must lead the "start here" triage.md even though the four-term
+  // score (paste/copy/sidebar/tab-away) no longer includes a hard-trigger term.
+  // This matches the HTML index's "Tier" sort (hard:0, soft:1, clean:2; score
+  // desc within tier).
+  const tierRank = (t) => (t.hardTriggered ? 0 : t.softFlagged ? 1 : 2);
+  triageList.sort((a, b) => {
+    const dt = tierRank(a) - tierRank(b);
+    if (dt !== 0) return dt;
+    return b.score - a.score;
+  });
   return triageList;
 }
 
@@ -37,27 +58,30 @@ export function rankTriage(summaries, edgeExits, config) {
 // with bars). Keeping the formula here means the score breakdown in the report can
 // never silently disagree with the ranked score it explains.
 //
-// IMPORTANT: this function is **strictly behavior-preserving** vs the previous
-// inline computeTriageScore. The defensive `|| 0` fallbacks below match the
-// original exactly — no extra ones added, no original ones removed. Adding
-// new defenses changes how malformed data (e.g. a non-numeric softScore object)
-// is rendered into csv/md/png outputs, even when the well-formed-data score
-// would be the same. We promised existing users no surprises in this refactor.
+// Scoring policy (fixed 2026-06-01): only four signals contribute to the
+// score —
+//   5 × paste events
+//   5 × copy events
+//   3 × sidebar events (open cycles)
+//   1 × tab-aways longer than the participant's tab-away threshold (3s default,
+//       5s strict) — excludes at-or-below-cutoff flickers, which are mostly noise
+//       from brief URL-bar focus / window edge clicks
+// Hard-trigger, AI extensions, layout shifts, zoom changes, keyboard shortcuts,
+// edge exits, synthetic insertions, and foreign inputs no longer affect the
+// *score*. They are NOT hidden from review: every event list still renders in
+// the per-participant detail panes, and hard-triggered participants are still
+// surfaced via the hard/soft/clean tier (which is independent of this score).
+// edgeExitCount and hardTriggered remain in the signature for the renderer's
+// call site but are unused under this policy.
 export function decomposeScore(summary, edgeExitCount, hardTriggered) {
-  const aiExtensions = summary.aiExtensionsFound || summary.extensionsDetected || [];
   const sidebarCount = summary.sidebarEventCount ?? (summary.sidebarDetected ? 1 : 0);
-  const base         = summary.authoritativeSoftScore ?? summary.totalSoftScore;
+  const tabAwayMeaningful =
+    (summary.tabAwayLongCount || 0) + (summary.tabAwayMediumCount || 0);
   return [
-    ['soft',     base],
-    ['hard',     hardTriggered ? 100 : 0],
-    ['edge',     edgeExitCount * 3],
-    ['ext',      aiExtensions.length * 5],
-    ['sidebar',  Math.min(sidebarCount * 3, 15)],
-    ['kb',       (summary.keyboardShortcutCount || 0) * 2],
-    ['layout',   (summary.layoutShiftCount || 0)],
-    ['zoom',     (summary.zoomChangeCount || 0)],
-    ['synth',    summary.totalSyntheticInsertions * 4],
-    ['foreign',  summary.totalForeignInputEvents * 3],
+    ['paste',    (summary.totalPasteEvents || 0) * 5],
+    ['copy',     (summary.totalCopyEvents  || 0) * 5],
+    ['sidebar',  sidebarCount * 3],
+    ['tabaway',  tabAwayMeaningful],
   ];
 }
 
@@ -89,9 +113,14 @@ export function generateTriageReason(summary, edgeExitCount = 0) {
     const longN = summary.tabAwayLongCount || 0;
     const midN = summary.tabAwayMediumCount || 0;
     const flickN = summary.tabAwayFlickerCount || 0;
+    // Bin boundaries follow THIS participant's tab-away cutoff (3s by default, 5s
+    // for strict) so the reason matches the counts/score, which are now computed
+    // against that same per-participant cutoff. Flicker is at-or-below the cutoff
+    // (not scored); medium is above the cutoff and under 10s.
+    const cutoffS = Math.round((summary.tabAwayCutoffMs ?? 3000) / 1000);
     if (longN > 0) parts.push(`${longN} tab-away${longN === 1 ? '' : 's'} ≥10s`);
-    if (midN > 0) parts.push(`${midN} tab-away${midN === 1 ? '' : 's'} 3–10s`);
-    if (flickN > 0) parts.push(`${flickN} flicker${flickN === 1 ? '' : 's'} <3s`);
+    if (midN > 0) parts.push(`${midN} tab-away${midN === 1 ? '' : 's'} ${cutoffS}–10s`);
+    if (flickN > 0) parts.push(`${flickN} flicker${flickN === 1 ? '' : 's'} ≤${cutoffS}s`);
   } else if (summary.totalTabAways > 0) {
     parts.push(`${summary.totalTabAways} tab-aways`);
   }
@@ -111,6 +140,9 @@ export function generateTriageReason(summary, edgeExitCount = 0) {
   if (edgeExitCount > 0) parts.push(`${edgeExitCount} edge-exit patterns`);
   if (summary.totalSyntheticInsertions > 0) parts.push(`${summary.totalSyntheticInsertions} synthetic insertions`);
   if (summary.totalForeignInputEvents > 0) parts.push(`${summary.totalForeignInputEvents} foreign inputs`);
+  // Guard-honeypot self-disclosure — a strong corroborating signal, surfaced in
+  // the reason though it does not feed the four-term score.
+  if (summary.honeypotAiUse) parts.push('self-reported AI use (honeypot)');
   if (parts.length === 0) parts.push('clean');
   return parts.join('; ');
 }

package/src/cli/config.js

@@ -35,6 +35,7 @@ export function loadConfig(cliArgs) {
   if (flags.participantIdField) config.participantIdField = flags.participantIdField;
   if (flags.filePattern) config.filePattern = flags.filePattern;
   if (flags.integrityField) config.integrityField = flags.integrityField;
+  if (flags.sessionIntegrityPath) config.sessionIntegrityPath = flags.sessionIntegrityPath;
   if (flags['no-visuals']) config.noVisuals = true;
 
   // Resolve relative paths to absolute (relative to cwd)
@@ -45,20 +46,42 @@ export function loadConfig(cliArgs) {
   const warnings = validateConfig(fileConfig);
   warnings.forEach(w => console.warn(`[cyborg-hunter] ${w}`));
 
+  // Validate config VALUES that would otherwise silently mis-score (a
+  // non-numeric softScoreThreshold coerces every `score >= threshold` to
+  // false, disabling soft flagging with no error).
+  cliConfigWarnings(config).forEach(w => console.warn(`[cyborg-hunter] ${w}`));
+
   return config;
 }
 
+// Value-level CLI config checks that catch misconfigurations which would
+// otherwise silently zero out a signal or verdict. Returns warning strings.
+// Exported for testing.
+export function cliConfigWarnings(config) {
+  const warnings = [];
+  const thr = config?.scoring?.softScoreThreshold;
+  if (thr != null && typeof thr !== 'number') {
+    warnings.push(
+      `scoring.softScoreThreshold is not a number (got ${JSON.stringify(thr)}) — ` +
+      `every soft-score comparison coerces to false, so NO participant will be ` +
+      `soft-flagged. Set it to a number.`
+    );
+  }
+  return warnings;
+}
+
 // Parses CLI arguments into a flags object.
 //
 // Supported flags (kebab-case aliases match the camelCase config keys, so
 // you can use whichever form you remember):
-//   --config <path>                # alternate config file path
+//   --config, --config-file <path> # alternate config file path
 //   --data,    --data-dir <path>   # config.dataDir
 //   --output,  --output-dir <path> # config.outputDir
 //   --participant <id>             # filter to single participant
 //   --participant-id-field <name>  # config.participantIdField
 //   --file-pattern <glob>          # config.filePattern
 //   --integrity-field <name>       # config.integrityField
+//   --session-integrity-path <p>   # config.sessionIntegrityPath (dotted)
 //   --no-visuals                   # skip canvas-rendered images
 //
 // Throws on unknown flags. Earlier behavior was to print a warning and keep
@@ -70,6 +93,7 @@ export function parseFlags(args) {
   // form so loadConfig can look it up directly.
   const SINGLE_VALUE = {
     '--config': 'config',
+    '--config-file': 'config',
     '--data': 'data',
     '--data-dir': 'data',
     '--output': 'output',
@@ -78,6 +102,7 @@ export function parseFlags(args) {
     '--participant-id-field': 'participantIdField',
     '--file-pattern': 'filePattern',
     '--integrity-field': 'integrityField',
+    '--session-integrity-path': 'sessionIntegrityPath',
   };
   for (let i = 0; i < args.length; i++) {
     const a = args[i];