cyborg-hunter 0.5.0 → 0.7.2

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];