@erichll/pi-auto-review 0.23.0 → 0.25.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 0.25.0 - 2026-10-07
+
+- Pass permission-system's matched bash spelling (#910) through the review and
+  audit pipeline. The ask payload's `request.matchedSpelling` — the alternate
+  spelling the matched rule hit when it did not match the command as typed,
+  e.g. the absolute spelling of a relative path argument — is now normalized
+  into the reviewer evidence and `BoundaryRequest`, described to the model
+  reviewer, carried through hard-deny audits, and persisted in the policy
+  audit as an anonymous `spelling_fingerprint` (schema v3; v1 and v2
+  databases migrate transactionally). Because `permissions:decision` still
+  carries only `matchedPattern`, the spelling is captured from
+  authorizer entry (including automatic allow/deny) and
+  `permissions:ui_prompt` by request id and joined at record time with a
+  bounded FIFO cache; decisions that carry the field directly are used
+  as-is. The report grows a "spelling fingerprints" section (v3); the
+  spelling stays out of the boundary request hash, which is display-only
+  input. On permission-system 39.x the field is simply absent and the audit
+  behaves exactly as before. The development baseline moves to ^40.0.2,
+  including the /dev/null core-reader exemption fix and bash-chain session
+  grant isolation security fix; the peer floor stays `>=39.0.0`. Real
+  permission-system integration tests cover alternate spellings, redirect
+  exemptions, automatic spelling audits, and sibling-unit isolation.
+- Isolate authorizer tests from the real user audit database: ordinary tests
+  disable audit collection, while audit integration uses a temporary HOME.
+  Schema v3 is a forward migration; upgrade and restart all audit collectors
+  rather than leaving pre-v3 sessions writing to the upgraded database.
+
+## 0.24.0 - 2026-10-03
+
+- Raise the `@earendil-works/pi-ai` and `@earendil-works/pi-coding-agent`
+  peer floors to `^1.0.0` and the development baselines to `^1.0.0`, plus
+  `@types/node` to `^26.6.4`. Raise the
+  `@gotgenes/pi-permission-system` development baseline to `^38.0.2`; the peer
+  floor stays `>=36.0.0`. Validated against Pi 1.0.0 with
+  pi-permission-system 38.0.2 via `tsc --noEmit` and the full test suite: no
+  source changes were required, and the authorizer seam this package consumes
+  is unchanged.
+- Move the example's Pi MCP tool rules under `mcp` (`mcp__atlassian__*`,
+  `mcp__pencil__*`) and update the README's MCP guidance to match, because
+  pi-permission-system 38.0.0 gates Pi's built-in MCP tools on the `mcp`
+  surface instead of their top-level names.
+
 ## 0.23.0 - 2026-10-02
 
 - Add opt-in `model: "current"` to review approval requests with the active Pi

package/README.md

@@ -31,8 +31,10 @@ that dependency is a hard prerequisite (see [Install and enable](#install-and-en
 > **Prerequisite:** pi-auto-review is an authorizer inside
 > `@gotgenes/pi-permission-system`. Pi does not auto-install peer packages, so
 > install the permission system separately (once per machine) before this
-> extension. This release line requires Pi 0.99.1 or later and supports
-> permission-system 36.0.0 and later:
+> extension. This release line requires Pi 1.0.0 or later and supports
+> permission-system 39.0.0 and later (development baseline validated against
+> permission-system 40.0.2). Use 40.0.2 or later for the bash-chain session-grant
+> security fix; the older peer floor is retained for API compatibility:
 
 Node-based Pi requires Node.js 22.13.0 or newer. Permission auditing uses the
 host runtime's built-in SQLite: `node:sqlite` on Node and `bun:sqlite` on Bun,
@@ -108,6 +110,13 @@ credential rules also keep scanning raw text. When a command fact exceeds the
 reviewer bound (10 KiB), the ask defers to a human instead of being reviewed from
 a truncated program.
 
+Permission-system 40.x also reports the alternate command spelling a rule
+matched, for example `cat /repo/file` when the command was `cat ./file`.
+The reviewer sees this as explanatory evidence; it does not replace the actual
+command or enter the grant/retry hash. Absolute-path Bash rules now also reach
+relative spellings of that path, so review existing allow/ask/deny rules when
+upgrading from 39.x.
+
 Nested interpreter expansion is limited to 32 payloads and 32 KiB of cumulative
 payload text per command fact, across all recursion levels. Exceeding either
 budget keeps the raw-command hard-deny checks and otherwise defers to a human
@@ -156,19 +165,20 @@ to select a model whose ID is literally `current`.
 
 For a complete `@gotgenes/pi-permission-system` config that wires
 `pi-auto-review` into the authorizer chain — a copyable baseline covering
-read/write/edit, a read-only bash allowlist, an MCP discovery policy, and a
+read/write/edit, a read-only bash allowlist, MCP tool access, and a
 `path` deny block for secret and credential files — see
 [`examples/pi-permission-system.config.example.json`](examples/pi-permission-system.config.example.json).
 
-MCP rules are evaluated last-match-wins across the candidates derived for one
-call: the tool name, its bare server, and `mcp_call`. Keep `"*"` first in the
-`mcp` block and narrower server or tool entries after it, as the example does,
-so a specific rule cannot be shadowed by the catch-all. A bare server entry
-such as `"atlassian": "allow"` also matches the `mcp connect <server>`
-candidate list, so it auto-allows starting that server — prefer the `server_*`
-and `server:*` forms for tool calls. Any entry meant to narrow a broad allow
-(such as a destructive-tool pattern) must be written after it, or
-last-match-wins shadows it.
+Permission-system 38.0.0 gates Pi's built-in MCP tools on the `mcp` surface, so
+the example writes its `mcp__<server>__*` rules inside a `mcp` block instead of
+as top-level tool names. MCP rules are evaluated last-match-wins across the
+candidates derived for one call: the tool name, its bare server, and `mcp_call`.
+A call the `mcp` block does not match falls through to the universal
+`"*": "ask"`, and any broad catch-all must be written before a narrower
+override or last-match-wins shadows it. A bare server entry such as
+`"atlassian": "allow"` also matches the `mcp connect <server>` candidate list,
+so it auto-allows starting that server — prefer the `server_*` and `server:*`
+forms for tool calls.
 
 Package defaults:
 
@@ -407,7 +417,10 @@ assignments, quoted values, and option values are replaced with `*`; safe bare
 command words remain in plaintext so the report can emit a matching rule.
 Paths used for path-surface statistics become only
 `workspace`, `temp`, `home`, `external`, `sensitive`, or `unknown`. Request IDs,
-project locations, and matched-rule patterns are HMACed. Syntactically valid
+project locations, matched-rule patterns, and alternate command spellings are
+HMACed. Spelling facts are captured at authorizer entry as well as human prompts,
+so automatic allow/deny decisions are included; 39.x requests simply lack the
+field. Reports expose only anonymous spelling fingerprints. Syntactically valid
 custom tool names are also retained in plaintext; invalid names stay anonymous
 as `<custom-tool>`. The database never stores raw commands, raw paths,
 URLs, credentials, or non-Bash tool arguments and inputs. Because safe bare Bash
@@ -416,7 +429,11 @@ project-specific labels; inspect suggestions before copying them.
 
 Data lives at
 `~/.pi/agent/extensions/pi-auto-review/policy-audit.sqlite`, beside an
-owner-only HMAC key. Node and Bun use the same database schema and key, so
+owner-only HMAC key. Version 0.25.0 migrates the database to schema v3; older
+auto-review collectors cannot use that schema. After upgrading, restart or
+reload all sessions using the old extension. Do not delete the database to
+resolve a mixed-version collector warning. Node and Bun use the same database
+schema and key, so
 switching runtimes preserves statistics and request deduplication.
 The directory is mode `0700`; the key, database, WAL, and
 SHM are mode `0600`. Initialization, lock, write, or corruption failures disable

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@erichll/pi-auto-review",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Fail-closed, model-backed approval broker for Pi: deterministically hard-denies dangerous operations, reviews dangerous boundaries with a reviewer model, and issues one-shot expiring grants that OS sandbox adapters must consume before retrying.",
   "type": "module",
   "license": "MIT",
@@ -47,16 +47,16 @@
     "test": "node --disable-warning=ExperimentalWarning --experimental-transform-types --import ./test/register-external-ts.mjs --test test/*.test.ts"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "^0.99.1",
-    "@earendil-works/pi-coding-agent": "^0.99.1",
-    "@gotgenes/pi-permission-system": ">=36.0.0"
+    "@earendil-works/pi-ai": "^1.0.0",
+    "@earendil-works/pi-coding-agent": "^1.0.0",
+    "@gotgenes/pi-permission-system": ">=39.0.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.99.1",
-    "@earendil-works/pi-coding-agent": "^0.99.1",
-    "@earendil-works/pi-server": "^0.99.1",
-    "@gotgenes/pi-permission-system": "^36.0.0",
-    "@types/node": "^26.6.2",
+    "@earendil-works/pi-ai": "^1.0.0",
+    "@earendil-works/pi-coding-agent": "^1.0.0",
+    "@earendil-works/pi-server": "^1.0.0",
+    "@gotgenes/pi-permission-system": "^40.0.2",
+    "@types/node": "^26.6.4",
     "typescript": "^7.0.2"
   }
 }

package/src/broker/grants.ts

@@ -25,6 +25,9 @@ export function boundaryRequestHash(request: BoundaryRequest): string {
     executedUnit: request.executedUnit,
     fullCommand: request.fullCommand,
     matchedPattern: request.matchedPattern,
+    // matchedSpelling stays out: it is display-only (#910) and derives from the
+    // same request, so binding it would change grant hashes when a permission-
+    // system upgrade starts (or stops) projecting it.
     path: request.path,
     resolvedPath: request.resolvedPath,
     destination: request.destination,

package/src/broker/types.ts

@@ -25,6 +25,12 @@ export type BoundaryRequest = {
   fullCommand?: string;
   /** Rule (or synthetic sentinel) that produced this ask. */
   matchedPattern?: string;
+  /**
+   * The spelling of the rule-matched bash unit when it differs from `command`
+   * as typed — the absolute spelling of a relative path argument, say
+   * (permission-system #910). Display-only: never bound into request hashes.
+   */
+  matchedSpelling?: string;
   /**
    * Set only on the bounded reviewer view when a command fact was truncated;
    * never set on the stored request used for hashing or hard denies.

package/src/index.ts

@@ -356,6 +356,7 @@ export function createPiAutoReviewExtension(
           executedUnit: request.executedUnit,
           fullCommand: request.fullCommand,
           matchedPattern: request.matchedPattern,
+          matchedSpelling: request.matchedSpelling,
           path: request.path,
           target: request.destination,
           toolName: request.toolName,
@@ -670,6 +671,7 @@ export function createPiAutoReviewExtension(
 
   pi.events.on("permissions:ui_prompt", (event) => {
     if (context) uiAutoConfirmer.handlePrompt(event, context);
+    policyAudit.notePrompt(event);
   });
 
   pi.events.on("permissions:decision", (event) => {
@@ -716,6 +718,7 @@ export function createPiAutoReviewExtension(
         EXTENSION_NAME,
         async (details, query, log: AuthorizerLog) => {
           const evidence = normalizePermissionEvidence(details);
+          policyAudit.noteRequest(details.requestId, evidence);
           const surface = evidence.surface;
           if (!context || !broker) {
             const reason = "review context is unavailable";

package/src/policy-audit/index.ts

@@ -18,6 +18,7 @@ export type PermissionDecisionLike = {
   resolution?: unknown;
   origin?: unknown;
   matchedPattern?: unknown;
+  matchedSpelling?: unknown;
   forwarding?: unknown;
 };
 
@@ -38,6 +39,9 @@ const PERMISSION_RESOLUTIONS = new Set([
   "gate_error",
 ]);
 
+/** Upper bound on remembered ask spellings awaiting their decision event. */
+const PROMPT_SPELLING_CACHE_LIMIT = 256;
+
 export function parsePolicyAuditArguments(raw: string, retentionDays: number): PolicyAuditArguments {
   const result: PolicyAuditArguments = { days: Math.min(30, retentionDays), top: 20, minCount: 5, scope: "current" };
   const tokens = raw.trim() ? raw.trim().split(/\s+/u) : [];
@@ -76,9 +80,43 @@ export class PolicyAuditController {
   private disabled = false;
   private warned = false;
   private queue = Promise.resolve();
+  /**
+   * Ask spelling captured at authorizer entry or from `permissions:ui_prompt`,
+   * keyed by request id. Automatic allow/deny decisions never open a UI prompt.
+   * The `permissions:decision` event still carries only `matchedPattern`, so
+   * the #910 spelling has to be joined by request id at record time. The map
+   * is bounded FIFO: spellings for asks whose decision never arrives are
+   * dropped oldest-first, and the spelling is display-only anyway.
+   */
+  private readonly promptSpellings = new Map<string, string>();
 
   constructor(private readonly options: PolicyAuditControllerOptions) {}
 
+  /** Capture spelling before an authorizer or human can decide the ask. */
+  noteRequest(requestId: unknown, rawRequest: unknown): void {
+    if (!this.options.config().enabled || this.disabled) return;
+    const request = rawRequest && typeof rawRequest === "object" && !Array.isArray(rawRequest)
+      ? rawRequest as Record<string, unknown>
+      : undefined;
+    const spelling = request?.matchedSpelling;
+    if (typeof requestId !== "string" || !requestId || typeof spelling !== "string" || spelling.length === 0) return;
+    // A deferred authorizer and its eventual UI prompt describe the same ask.
+    // Updating that entry must not evict an unrelated outstanding request.
+    if (!this.promptSpellings.has(requestId) && this.promptSpellings.size >= PROMPT_SPELLING_CACHE_LIMIT) {
+      const oldest = this.promptSpellings.keys().next().value;
+      if (oldest !== undefined) this.promptSpellings.delete(oldest);
+    }
+    this.promptSpellings.set(requestId, spelling);
+  }
+
+  /** Capture human prompts, including asks that bypass our authorizer. */
+  notePrompt(raw: unknown): void {
+    const event = raw && typeof raw === "object" && !Array.isArray(raw)
+      ? raw as Record<string, unknown>
+      : undefined;
+    this.noteRequest(event?.requestId, event?.request);
+  }
+
   warmup(): void {
     if (this.options.config().enabled) void this.getStore().catch(() => undefined);
   }
@@ -137,7 +175,13 @@ export class PolicyAuditController {
       matchedPattern: typeof event.matchedPattern === "string"
         ? digest("rule", event.matchedPattern)
         : undefined,
+      matchedSpelling: typeof event.matchedSpelling === "string" && event.matchedSpelling.length > 0
+        ? digest("spelling", event.matchedSpelling)
+        : this.promptSpellings.has(event.requestId)
+          ? digest("spelling", this.promptSpellings.get(event.requestId)!)
+        : undefined,
     };
+    this.promptSpellings.delete(event.requestId);
     this.queue = this.queue
       .then(async () => (await this.getStore()).record(cwd, sanitized))
       .then(() => undefined)
@@ -165,6 +209,7 @@ export class PolicyAuditController {
   }
 
   async close(): Promise<void> {
+    this.promptSpellings.clear();
     await this.queue;
     // Detach before awaiting so concurrent shutdowns cannot double-close.
     const storePromise = this.storePromise;

package/src/policy-audit/report.ts

@@ -1,6 +1,6 @@
 import type { PolicyAuditAggregateRow, PolicyAuditQueryResult } from "./store.ts";
 
-export const POLICY_AUDIT_REPORT_VERSION = 2 as const;
+export const POLICY_AUDIT_REPORT_VERSION = 3 as const;
 
 export type PolicyAuditReportItem = { name: string; count: number; denied: number; denialRate: number };
 export type SuggestedAllowRule = {
@@ -35,6 +35,7 @@ export type PolicyAuditReport = {
   lowRiskReviewCandidates: PolicyAuditReportItem[];
   keepAskRecommendations: PolicyAuditReportItem[];
   ruleFingerprints: Array<{ fingerprint: string; count: number }>;
+  spellingFingerprints: Array<{ fingerprint: string; count: number }>;
   warnings: string[];
 };
 
@@ -213,6 +214,14 @@ export function buildPolicyAuditReport(
     if (row.ruleFingerprint === "none") continue;
     fingerprintCounts.set(row.ruleFingerprint, (fingerprintCounts.get(row.ruleFingerprint) ?? 0) + row.count);
   }
+  // Anonymous spelling fingerprints (#910): how often the matched rule hit a
+  // bash spelling other than the command as typed, e.g. its absolute path.
+  // Rows without an alternate spelling carry the 'none' sentinel and are skipped.
+  const spellingCounts = new Map<string, number>();
+  for (const row of result.rows) {
+    if (row.spellingFingerprint === "none") continue;
+    spellingCounts.set(row.spellingFingerprint, (spellingCounts.get(row.spellingFingerprint) ?? 0) + row.count);
+  }
   const warnings = [
     "Counts begin at first successful enablement; no historical logs are imported.",
     "Suggestions are evidence-based decision aids and never modify permission configuration.",
@@ -251,6 +260,11 @@ export function buildPolicyAuditReport(
       .filter((item) => item.count >= options.minCount)
       .sort((a, b) => b.count - a.count || a.fingerprint.localeCompare(b.fingerprint))
       .slice(0, options.top),
+    spellingFingerprints: [...spellingCounts]
+      .map(([fingerprint, count]) => ({ fingerprint, count }))
+      .filter((item) => item.count >= options.minCount)
+      .sort((a, b) => b.count - a.count || a.fingerprint.localeCompare(b.fingerprint))
+      .slice(0, options.top),
     warnings,
   };
 }
@@ -299,6 +313,10 @@ function renderHotspotSections(report: PolicyAuditReport): string[] {
     groups.push({ title: "Anonymous rule-hit fingerprints",
       items: report.ruleFingerprints.map((f) => ({ name: f.fingerprint, count: f.count, denied: 0, denialRate: 0 })) });
   }
+  if (report.spellingFingerprints.length > 0) {
+    groups.push({ title: "Anonymous alternate-spelling fingerprints",
+      items: report.spellingFingerprints.map((f) => ({ name: f.fingerprint, count: f.count, denied: 0, denialRate: 0 })) });
+  }
   return groups.flatMap((group) => ["", `## ${group.title}`, "", ...group.items.map(hotspotRow)]);
 }
 

package/src/policy-audit/store.ts

@@ -13,7 +13,7 @@ import { dirname, join, resolve } from "node:path";
 import type { ClassifiedPermission } from "./classifier.ts";
 import { loadSqlite, type SqliteDatabase, type SqliteModule } from "./sqlite.ts";
 
-export const POLICY_AUDIT_SCHEMA_VERSION = 2;
+export const POLICY_AUDIT_SCHEMA_VERSION = 3;
 export const POLICY_AUDIT_DATABASE_NAME = "policy-audit.sqlite";
 export const POLICY_AUDIT_KEY_NAME = "policy-audit.key";
 
@@ -24,6 +24,11 @@ export type SanitizedPermissionDecision = ClassifiedPermission & {
   origin: string;
   forwarded: boolean;
   matchedPattern?: string;
+  /**
+   * Already-digested spelling of the rule-matched bash unit when it differed
+   * from the command as typed (#910); absent when the typed text decided.
+   */
+  matchedSpelling?: string;
 };
 
 export type PolicyAuditStoreOptions = {
@@ -53,6 +58,7 @@ export type PolicyAuditAggregateRow = {
   forwarded: boolean;
   features: string;
   ruleFingerprint: string;
+  spellingFingerprint: string;
   candidateSurface: string;
   candidatePattern: string;
   candidateSafetyClass: string;
@@ -146,18 +152,19 @@ export class PolicyAuditStore {
     `);
     const version = this.db.prepare("SELECT value FROM meta WHERE key='schema_version'").get()?.value;
     const now = this.now().toISOString();
-    if (version !== undefined && version !== "1" && version !== String(POLICY_AUDIT_SCHEMA_VERSION)) {
+    if (version !== undefined && version !== "1" && version !== "2" && version !== String(POLICY_AUDIT_SCHEMA_VERSION)) {
       throw new Error("unsupported policy audit schema version");
     }
     if (version === "1") this.migrateV1(now);
-    else this.createV2Table();
+    else if (version === "2") this.migrateV2(now);
+    else this.createV3Table();
     this.db.prepare("INSERT OR IGNORE INTO meta(key,value) VALUES('schema_version',?)").run(String(POLICY_AUDIT_SCHEMA_VERSION));
     this.db.prepare("INSERT OR IGNORE INTO meta(key,value) VALUES('collecting_since',?)").run(now);
     this.db.prepare("INSERT OR IGNORE INTO meta(key,value) VALUES('recommendations_since',?)").run(now);
     this.secureSidecars();
   }
 
-  private createV2Table(): void {
+  private createV3Table(): void {
     this.db.exec(`
       CREATE TABLE IF NOT EXISTS daily_permission_stats (
         day TEXT NOT NULL,
@@ -173,13 +180,14 @@ export class PolicyAuditStore {
         forwarded INTEGER NOT NULL,
         features TEXT NOT NULL,
         rule_fingerprint TEXT NOT NULL,
+        spelling_fingerprint TEXT NOT NULL,
         candidate_surface TEXT NOT NULL,
         candidate_pattern TEXT NOT NULL,
         candidate_safety_class TEXT NOT NULL,
         candidate_eligible INTEGER NOT NULL,
         candidate_blocker TEXT NOT NULL,
         count INTEGER NOT NULL,
-        PRIMARY KEY (day, project_hash, surface, signature, bash_category, risk, path_class, result, resolution, origin, forwarded, features, rule_fingerprint, candidate_surface, candidate_pattern, candidate_safety_class, candidate_eligible, candidate_blocker)
+        PRIMARY KEY (day, project_hash, surface, signature, bash_category, risk, path_class, result, resolution, origin, forwarded, features, rule_fingerprint, spelling_fingerprint, candidate_surface, candidate_pattern, candidate_safety_class, candidate_eligible, candidate_blocker)
       ) STRICT;
       CREATE INDEX IF NOT EXISTS daily_permission_stats_project_day ON daily_permission_stats(project_hash, day);
     `);
@@ -189,20 +197,20 @@ export class PolicyAuditStore {
     this.db.exec("BEGIN IMMEDIATE");
     try {
       this.db.exec(`
-        CREATE TABLE daily_permission_stats_v2 (
+        CREATE TABLE daily_permission_stats_v3 (
           day TEXT NOT NULL, project_hash TEXT NOT NULL, surface TEXT NOT NULL, signature TEXT NOT NULL,
           bash_category TEXT NOT NULL, risk TEXT NOT NULL, path_class TEXT NOT NULL, result TEXT NOT NULL,
           resolution TEXT NOT NULL, origin TEXT NOT NULL, forwarded INTEGER NOT NULL, features TEXT NOT NULL,
-          rule_fingerprint TEXT NOT NULL, candidate_surface TEXT NOT NULL, candidate_pattern TEXT NOT NULL,
-          candidate_safety_class TEXT NOT NULL, candidate_eligible INTEGER NOT NULL, candidate_blocker TEXT NOT NULL,
-          count INTEGER NOT NULL,
-          PRIMARY KEY (day, project_hash, surface, signature, bash_category, risk, path_class, result, resolution, origin, forwarded, features, rule_fingerprint, candidate_surface, candidate_pattern, candidate_safety_class, candidate_eligible, candidate_blocker)
+          rule_fingerprint TEXT NOT NULL, spelling_fingerprint TEXT NOT NULL, candidate_surface TEXT NOT NULL,
+          candidate_pattern TEXT NOT NULL, candidate_safety_class TEXT NOT NULL, candidate_eligible INTEGER NOT NULL,
+          candidate_blocker TEXT NOT NULL, count INTEGER NOT NULL,
+          PRIMARY KEY (day, project_hash, surface, signature, bash_category, risk, path_class, result, resolution, origin, forwarded, features, rule_fingerprint, spelling_fingerprint, candidate_surface, candidate_pattern, candidate_safety_class, candidate_eligible, candidate_blocker)
         ) STRICT;
-        INSERT INTO daily_permission_stats_v2
-          SELECT day,project_hash,surface,signature,bash_category,risk,path_class,result,resolution,origin,forwarded,features,rule_fingerprint,'','','',0,'',count
+        INSERT INTO daily_permission_stats_v3
+          SELECT day,project_hash,surface,signature,bash_category,risk,path_class,result,resolution,origin,forwarded,features,rule_fingerprint,'none','','','',0,'',count
           FROM daily_permission_stats;
         DROP TABLE daily_permission_stats;
-        ALTER TABLE daily_permission_stats_v2 RENAME TO daily_permission_stats;
+        ALTER TABLE daily_permission_stats_v3 RENAME TO daily_permission_stats;
         CREATE INDEX daily_permission_stats_project_day ON daily_permission_stats(project_hash, day);
       `);
       this.db.prepare("UPDATE meta SET value=? WHERE key='schema_version'").run(String(POLICY_AUDIT_SCHEMA_VERSION));
@@ -214,6 +222,39 @@ export class PolicyAuditStore {
     }
   }
 
+  /**
+   * v2 → v3: adds `spelling_fingerprint` (#910). Pre-v3 rows never carried a
+   * spelling, so they copy over with the same 'none' sentinel fresh no-spelling
+   * rows use, and keep contributing to every recommendation unchanged.
+   */
+  private migrateV2(now: string): void {
+    this.db.exec("BEGIN IMMEDIATE");
+    try {
+      this.db.exec(`
+        CREATE TABLE daily_permission_stats_v3 (
+          day TEXT NOT NULL, project_hash TEXT NOT NULL, surface TEXT NOT NULL, signature TEXT NOT NULL,
+          bash_category TEXT NOT NULL, risk TEXT NOT NULL, path_class TEXT NOT NULL, result TEXT NOT NULL,
+          resolution TEXT NOT NULL, origin TEXT NOT NULL, forwarded INTEGER NOT NULL, features TEXT NOT NULL,
+          rule_fingerprint TEXT NOT NULL, spelling_fingerprint TEXT NOT NULL, candidate_surface TEXT NOT NULL,
+          candidate_pattern TEXT NOT NULL, candidate_safety_class TEXT NOT NULL, candidate_eligible INTEGER NOT NULL,
+          candidate_blocker TEXT NOT NULL, count INTEGER NOT NULL,
+          PRIMARY KEY (day, project_hash, surface, signature, bash_category, risk, path_class, result, resolution, origin, forwarded, features, rule_fingerprint, spelling_fingerprint, candidate_surface, candidate_pattern, candidate_safety_class, candidate_eligible, candidate_blocker)
+        ) STRICT;
+        INSERT INTO daily_permission_stats_v3
+          SELECT day,project_hash,surface,signature,bash_category,risk,path_class,result,resolution,origin,forwarded,features,rule_fingerprint,'none',candidate_surface,candidate_pattern,candidate_safety_class,candidate_eligible,candidate_blocker,count
+          FROM daily_permission_stats;
+        DROP TABLE daily_permission_stats;
+        ALTER TABLE daily_permission_stats_v3 RENAME TO daily_permission_stats;
+        CREATE INDEX daily_permission_stats_project_day ON daily_permission_stats(project_hash, day);
+      `);
+      this.db.prepare("UPDATE meta SET value=? WHERE key='schema_version'").run(String(POLICY_AUDIT_SCHEMA_VERSION));
+      this.db.exec("COMMIT");
+    } catch (error) {
+      try { this.db.exec("ROLLBACK"); } catch { /* preserve migration error */ }
+      throw error;
+    }
+  }
+
   private hash(kind: string, value: string): string {
     return createHmac("sha256", this.key).update(`${kind}\0${value}`).digest("hex");
   }
@@ -226,6 +267,10 @@ export class PolicyAuditStore {
     return pattern ? this.hash("rule", pattern).slice(0, 16) : "none";
   }
 
+  spellingFingerprint(spelling: string | undefined): string {
+    return spelling ? this.hash("spelling", spelling).slice(0, 16) : "none";
+  }
+
   private retry<T>(operation: () => T): T {
     let last: unknown;
     for (let attempt = 0; attempt < 3; attempt++) {
@@ -255,9 +300,9 @@ export class PolicyAuditStore {
         }
         this.db.prepare(`
           INSERT INTO daily_permission_stats(
-            day,project_hash,surface,signature,bash_category,risk,path_class,result,resolution,origin,forwarded,features,rule_fingerprint,
+            day,project_hash,surface,signature,bash_category,risk,path_class,result,resolution,origin,forwarded,features,rule_fingerprint,spelling_fingerprint,
             candidate_surface,candidate_pattern,candidate_safety_class,candidate_eligible,candidate_blocker,count
-          ) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,1)
+          ) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,1)
           ON CONFLICT DO UPDATE SET count=count+1
         `).run(
           day,
@@ -273,6 +318,7 @@ export class PolicyAuditStore {
           event.forwarded ? 1 : 0,
           event.features.join(","),
           this.ruleFingerprint(event.matchedPattern),
+          this.spellingFingerprint(event.matchedSpelling),
           event.candidate?.surface ?? "",
           event.candidate?.pattern ?? "",
           event.candidate?.safetyClass ?? "",
@@ -306,17 +352,18 @@ export class PolicyAuditStore {
       const params: unknown[] = [fromDay];
       if (input.scope === "current") params.push(this.projectHash(input.projectPath));
       const rows = this.db.prepare(`
-        SELECT surface,signature,bash_category,risk,path_class,result,resolution,origin,forwarded,features,rule_fingerprint,
+        SELECT surface,signature,bash_category,risk,path_class,result,resolution,origin,forwarded,features,rule_fingerprint,spelling_fingerprint,
           candidate_surface,candidate_pattern,candidate_safety_class,candidate_eligible,candidate_blocker,SUM(count) AS count
         FROM daily_permission_stats
         WHERE day >= ? ${projectClause}
-        GROUP BY surface,signature,bash_category,risk,path_class,result,resolution,origin,forwarded,features,rule_fingerprint,
+        GROUP BY surface,signature,bash_category,risk,path_class,result,resolution,origin,forwarded,features,rule_fingerprint,spelling_fingerprint,
           candidate_surface,candidate_pattern,candidate_safety_class,candidate_eligible,candidate_blocker
       `).all(...params).map((row) => ({
         surface: String(row.surface), signature: String(row.signature), bashCategory: String(row.bash_category),
         risk: String(row.risk), pathClass: String(row.path_class), result: String(row.result),
         resolution: String(row.resolution), origin: String(row.origin), forwarded: Number(row.forwarded) === 1,
-        features: String(row.features), ruleFingerprint: String(row.rule_fingerprint), count: Number(row.count),
+        features: String(row.features), ruleFingerprint: String(row.rule_fingerprint),
+        spellingFingerprint: String(row.spelling_fingerprint), count: Number(row.count),
         candidateSurface: String(row.candidate_surface), candidatePattern: String(row.candidate_pattern),
         candidateSafetyClass: String(row.candidate_safety_class), candidateEligible: Number(row.candidate_eligible) === 1,
         candidateBlocker: String(row.candidate_blocker),

package/src/policy.ts

@@ -31,6 +31,7 @@ export type PermissionDetailsLike = {
   executedUnit?: unknown;
   fullCommand?: unknown;
   matchedPattern?: unknown;
+  matchedSpelling?: unknown;
 };
 
 export type NormalizedPermissionEvidence = {
@@ -40,6 +41,13 @@ export type NormalizedPermissionEvidence = {
   executedUnit?: string;
   fullCommand?: string;
   matchedPattern?: string;
+  /**
+   * The spelling of the bash unit the matched rule hit when it did not match
+   * the command as typed — the absolute spelling of a relative path argument,
+   * say (permission-system #910). Display-only: absent whenever the typed text
+   * decided.
+   */
+  matchedSpelling?: string;
   path?: string;
   resolvedPath?: string;
   destination?: string;
@@ -171,6 +179,7 @@ export type RelevantBoundaryRequest = {
   executedUnit?: string;
   fullCommand?: string;
   matchedPattern?: string;
+  matchedSpelling?: string;
   path?: string;
   resolvedPath?: string;
   destination?: string;
@@ -390,6 +399,9 @@ export function normalizePermissionEvidence(
   const matchedPattern =
     nonEmptyString(payloadRequest?.matchedPattern) ??
     nonEmptyString(details.matchedPattern);
+  const matchedSpelling =
+    nonEmptyString(payloadRequest?.matchedSpelling) ??
+    nonEmptyString(details.matchedSpelling);
   const executedUnitCandidate =
     nonEmptyString(payloadRequest?.executedUnit) ??
     nonEmptyString(details.executedUnit);
@@ -412,6 +424,7 @@ export function normalizePermissionEvidence(
     ...(executedUnit ? { executedUnit } : {}),
     ...(fullCommand ? { fullCommand } : {}),
     ...(matchedPattern ? { matchedPattern } : {}),
+    ...(matchedSpelling ? { matchedSpelling } : {}),
     path,
     resolvedPath: accessIntent?.boundaryValue,
     destination,

package/src/review/input.ts

@@ -119,6 +119,9 @@ export function boundaryRequest(
     ...(evidence.matchedPattern
       ? { matchedPattern: evidence.matchedPattern }
       : {}),
+    ...(evidence.matchedSpelling
+      ? { matchedSpelling: evidence.matchedSpelling }
+      : {}),
     path: evidence.path,
     resolvedPath: evidence.resolvedPath,
     destination: evidence.destination,

package/src/review/prompts.ts

@@ -22,7 +22,8 @@ Policy:
 - Request facts: command is the rule-matched unit; executedUnit is what that
   unit runs after unwrapping sudo/env/xargs/inline shells; fullCommand is the
   whole program; matchedPattern names the rule or a sentinel such as
-  <opaque-bash-wrapper>, <indirection-bash-wrapper>, or <unparsed-bash-subtree>.
+  <opaque-bash-wrapper>, <indirection-bash-wrapper>, or <unparsed-bash-subtree>;
+  matchedSpelling, when present, is the alternate spelling the rule hit.
   When fullCommandTruncated is true or a wrapper payload is unresolved, defer;
   never assume unseen text is safe.