protect-context 0.0.0-stage → 1.1.0

package/extension/lib/brief.ts

@@ -0,0 +1,128 @@
+/**
+ * Compact pre-agent brief (SPEC §5 before_agent_start) and digest helper.
+ * Pure logic — no pi imports.
+ */
+
+import { createHash } from "node:crypto";
+import type { Constraint } from "./defaults.ts";
+import type { LoopInfo } from "./loops.ts";
+import { normalizeOneLine, trunc } from "./text.ts";
+
+export function sha1Hex(s: string): string {
+  return createHash("sha1").update(s, "utf8").digest("hex");
+}
+
+export interface BriefInput {
+  contract: Constraint[];
+  /** Most recent trusted decisions, newest first (already sliced). */
+  decisions?: Array<{ type: string; text: string; tags: string[] }>;
+  /** Most recent corrections, newest first (already sliced). */
+  corrections: Array<{ type: string; text: string; tags: string[] }>;
+  loops: LoopInfo[];
+  lastEvidence: { id: string; exit: number; cmd: string; ms: number | null } | null;
+}
+
+export const BRIEF_MAX_CONTRACT_LINES = 12;
+export const BRIEF_MAX_DECISIONS = 3;
+export const BRIEF_MAX_CORRECTIONS = 3;
+export const BRIEF_MAX_LOOPS = 2;
+/** Command display cap (chars) — matches Python's cmd[:60] discipline. */
+export const CMD_DISPLAY_MAX = 60;
+
+/** One-line cap for brief snippets: collapse whitespace, then truncate with an
+ *  ellipsis. Model-supplied text must never bloat the re-injected brief (goal #12). */
+export function truncLine(s: unknown, max = 200): string {
+  // Normalize before applying the display ellipsis. The normalizer gets a
+  // generous pre-cap so trunc(), rather than an invisible hard slice, marks
+  // ordinary overlong text.
+  return trunc(normalizeOneLine(s, Math.max(max + 1, 10_000)), max);
+}
+
+function isTrustedOwnerConstraint(c: Constraint): boolean {
+  return c.source === "owner" || c.source === "user";
+}
+
+/**
+ * Select the constraints that can enter the frozen 12-line brief cap.
+ *
+ * Authority is more important than append order: newest explicit owner/user
+ * constraints come first, then the frozen seed contract, and only then other
+ * (including agent-authored) entries. Consequently an agent entry can never
+ * crowd a seed constraint out of the brief. Stable source indexes break ties
+ * when the day-only `added` field is identical.
+ */
+export function selectBriefConstraints(contract: Constraint[]): Constraint[] {
+  const indexed = contract.map((constraint, index) => ({ constraint, index }));
+  const owners = indexed
+    .filter(({ constraint }) => isTrustedOwnerConstraint(constraint))
+    .sort(
+      (a, b) =>
+        String(b.constraint.added ?? "").localeCompare(String(a.constraint.added ?? "")) || b.index - a.index,
+    );
+  const seeds = indexed.filter(({ constraint }) => constraint.source === "seed");
+  const others = indexed.filter(
+    ({ constraint }) => constraint.source !== "seed" && !isTrustedOwnerConstraint(constraint),
+  );
+  return [...owners, ...seeds, ...others]
+    .slice(0, BRIEF_MAX_CONTRACT_LINES)
+    .map(({ constraint }) => constraint);
+}
+
+function appendJournalSection(
+  lines: string[],
+  heading: "decisions:" | "corrections:",
+  entries: Array<{ text: string; tags: string[] }>,
+  cap: number,
+): void {
+  if (entries.length === 0) return;
+  lines.push(heading);
+  for (const entry of entries.slice(0, cap)) {
+    const safeTags = [...new Set((Array.isArray(entry.tags) ? entry.tags : []).map((tag) => truncLine(tag, 40)).filter(Boolean))]
+      .slice(0, 8);
+    const tags = safeTags.length > 0 ? ` [${safeTags.join(",")}]` : "";
+    lines.push(`- ${truncLine(entry.text)}${tags}`);
+  }
+}
+
+/** Build the compact brief: contract (≤12 lines), ≤3 trusted decisions,
+ *  ≤3 trusted corrections, ≤2 loops, and last evidence. */
+export function buildBrief(input: BriefInput): string {
+  const lines: string[] = [];
+
+  const contractLines = selectBriefConstraints(input.contract);
+  if (contractLines.length > 0) {
+    lines.push("contract:");
+    for (const c of contractLines) {
+      // Provenance: seed constraints are the frozen defaults; anything else is
+      // tagged with its source so agent-written constraints are visible as such.
+      const source = truncLine(c.source, 40);
+      const src = source && source !== "seed" ? ` [${source}]` : "";
+      lines.push(`${truncLine(c.id, 80) || "(missing-id)"}${src}: ${truncLine(c.text)}`);
+    }
+    const hidden = input.contract.length - contractLines.length;
+    if (hidden > 0) {
+      // Never silently drop owner-added constraints: announce the overflow so
+      // the model knows constraints exist beyond the injected 12 (goal #1).
+      lines.push(`+${hidden} more constraints hidden — run /guard-contract list`);
+    }
+  }
+
+  appendJournalSection(lines, "decisions:", input.decisions ?? [], BRIEF_MAX_DECISIONS);
+  appendJournalSection(lines, "corrections:", input.corrections, BRIEF_MAX_CORRECTIONS);
+
+  if (input.loops.length > 0) {
+    lines.push("loops:");
+    for (const l of input.loops.slice(0, BRIEF_MAX_LOOPS)) {
+      lines.push(`- '${truncLine(l.cmd, CMD_DISPLAY_MAX)}' failed ${l.failures}x`);
+    }
+  }
+
+  if (input.lastEvidence) {
+    const ms = input.lastEvidence.ms === null ? "" : ` ${(input.lastEvidence.ms / 1000).toFixed(1)}s`;
+    lines.push(
+      `last verify: ${truncLine(input.lastEvidence.id, 40)} exit=${input.lastEvidence.exit} '${truncLine(input.lastEvidence.cmd, CMD_DISPLAY_MAX)}'${ms}`,
+    );
+  }
+
+  return lines.join("\n");
+}

package/extension/lib/config.ts

@@ -0,0 +1,67 @@
+/**
+ * config.json load/merge (SPEC §2). Pure merge + fs load — no pi imports.
+ */
+
+import { existsSync } from "node:fs";
+import { DEFAULT_CONFIG, type GuardConfig } from "./defaults.ts";
+import { configPath, readJson, storeDir, withStoreLock, writeJson } from "./store.ts";
+
+function isInteger(v: unknown): v is number {
+  return typeof v === "number" && Number.isInteger(v);
+}
+
+function strArray(v: unknown): string[] | null {
+  if (!Array.isArray(v) || v.some((x) => typeof x !== "string")) return null;
+  return v as string[];
+}
+
+/**
+ * Merge a partial config over the frozen defaults. Unknown keys are ignored;
+ * wrong-typed values fall back to the default (deterministic, test-pinned).
+ */
+export function mergeConfig(partial: Record<string, unknown> | null | undefined): GuardConfig {
+  const cfg: GuardConfig = { ...DEFAULT_CONFIG, preflight_tools: [...DEFAULT_CONFIG.preflight_tools] };
+  if (!partial || typeof partial !== "object") return cfg;
+
+  const p = partial as Record<string, unknown>;
+  if (isInteger(p.loop_block_after) && p.loop_block_after >= 1) cfg.loop_block_after = p.loop_block_after;
+  if (isInteger(p.diff_warn_lines) && p.diff_warn_lines >= 0) cfg.diff_warn_lines = p.diff_warn_lines;
+  if (isInteger(p.diff_hard_lines) && p.diff_hard_lines >= 0) cfg.diff_hard_lines = p.diff_hard_lines;
+  if (isInteger(p.diff_warn_files) && p.diff_warn_files >= 0) cfg.diff_warn_files = p.diff_warn_files;
+  if (isInteger(p.ctx_warn_pct) && p.ctx_warn_pct >= 0 && p.ctx_warn_pct <= 100) cfg.ctx_warn_pct = p.ctx_warn_pct;
+  if (p.brief_mode === "changed" || p.brief_mode === "always") cfg.brief_mode = p.brief_mode;
+  if (typeof p.risk_confirm === "boolean") cfg.risk_confirm = p.risk_confirm;
+  const tools = strArray(p.preflight_tools);
+  if (tools) cfg.preflight_tools = [...tools];
+  return cfg;
+}
+
+export interface LoadedConfig {
+  config: GuardConfig;
+  path: string;
+  existed: boolean;
+}
+
+/** Load `.agent-guard/config.json` merged over defaults. Missing file →
+ * defaults; extension startup can request an on-disk seed so an extension-only
+ * install has the documented configuration surface without first running the
+ * Python CLI. Existing corrupt files are never overwritten. */
+function readLoadedConfig(cwd: string): LoadedConfig {
+  const path = configPath(cwd);
+  const existed = existsSync(path);
+  const raw = readJson<Record<string, unknown>>(path);
+  const config = mergeConfig(raw ?? undefined);
+  return { config, path, existed };
+}
+
+export function loadConfig(cwd: string, seedMissing = false): LoadedConfig {
+  if (!seedMissing) return readLoadedConfig(cwd);
+  // Serialize and re-check the whole missing→seed transition. Without the
+  // second read inside the lease, an owner-written config could be replaced
+  // by defaults between an optimistic exists() and writeJson().
+  return withStoreLock(storeDir(cwd), () => {
+    const loaded = readLoadedConfig(cwd);
+    if (!loaded.existed) writeJson(loaded.path, loaded.config);
+    return loaded;
+  });
+}

package/extension/lib/contract.ts

@@ -0,0 +1,160 @@
+/**
+ * Contract store CRUD (SPEC §1 #1, §2, §5). No pi imports.
+ */
+
+import { existsSync } from "node:fs";
+import { DEFAULT_CONTRACT, type Constraint, type Contract } from "./defaults.ts";
+import { contractPath, readJson, storeDir, withStoreLock, writeJson } from "./store.ts";
+import { normalizeOneLine } from "./text.ts";
+
+/** Free-text cap (chars): constraint text flows into re-injected briefs (goal #12). */
+export const TEXT_CAP = 500;
+export const CONTRACT_RENDER_MAX = 24;
+
+export class ContractIntegrityError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ContractIntegrityError";
+  }
+}
+
+/**
+ * Load the contract, seeding `.agent-guard/contract.json` from DEFAULT_CONTRACT
+ * only when the file does not exist. A corrupt/unreadable file falls back to
+ * in-memory defaults WITHOUT writing, so a transient read error or corruption
+ * can never silently destroy the user's constraints (mirrors contract.load()
+ * on the Python side).
+ */
+function cloneDefaultContract(): Contract {
+  return JSON.parse(JSON.stringify(DEFAULT_CONTRACT)) as Contract;
+}
+
+function isConstraint(value: unknown): value is Constraint {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const row = value as Record<string, unknown>;
+  return (
+    typeof row.id === "string" &&
+    typeof row.text === "string" &&
+    typeof row.added === "string" &&
+    typeof row.source === "string"
+  );
+}
+
+/** Caller must hold the shared store lease. */
+function loadContractUnlocked(cwd: string, forMutation = false): Contract {
+  const file = contractPath(cwd);
+  if (!existsSync(file)) {
+    const seeded = cloneDefaultContract();
+    saveContractUnlocked(cwd, seeded);
+    return seeded;
+  }
+  const existing = readJson<unknown>(file);
+  if (existing && typeof existing === "object" && Array.isArray((existing as { constraints?: unknown }).constraints)) {
+    const rows = (existing as { constraints: unknown[] }).constraints;
+    const constraints = rows.filter(isConstraint);
+    if (forMutation && constraints.length !== rows.length) {
+      throw new ContractIntegrityError(
+        "contract contains malformed rows; repair .agent-guard/contract.json before mutating it",
+      );
+    }
+    // A non-empty list with no valid records is effectively corrupt. Serve
+    // frozen seeds in memory, but never overwrite the owner's damaged file.
+    if (rows.length > 0 && constraints.length === 0) return cloneDefaultContract();
+    return { version: 1, constraints };
+  }
+  if (forMutation) {
+    throw new ContractIntegrityError(
+      "contract file is malformed; repair .agent-guard/contract.json before mutating it",
+    );
+  }
+  return cloneDefaultContract();
+}
+
+/** Caller must hold the shared store lease. */
+function saveContractUnlocked(cwd: string, contract: Contract): void {
+  writeJson(contractPath(cwd), contract);
+}
+
+export function loadContract(cwd: string): Contract {
+  return withStoreLock(storeDir(cwd), () => loadContractUnlocked(cwd));
+}
+
+export function saveContract(cwd: string, contract: Contract): void {
+  withStoreLock(storeDir(cwd), () => saveContractUnlocked(cwd, contract));
+}
+
+/** Next sequential id, e.g. "13" after the 12 seeded constraints. */
+export function nextConstraintId(constraints: Constraint[]): string {
+  let max = 0;
+  for (const c of constraints) {
+    const m = c.id.match(/^(\d+)(?:-|$)/);
+    if (m) max = Math.max(max, Number(m[1]));
+  }
+  return String(max + 1).padStart(2, "0");
+}
+
+export interface AddConstraintResult {
+  constraint: Constraint;
+  added: boolean;
+  total: number;
+}
+
+export function addConstraintWithStatus(cwd: string, text: string, source = "agent"): AddConstraintResult {
+  const cleanText = normalizeOneLine(text, TEXT_CAP);
+  if (cleanText === "") throw new Error("constraint text must not be blank");
+  return withStoreLock(storeDir(cwd), () => {
+    const contract = loadContractUnlocked(cwd, true);
+    const existing = contract.constraints.find((constraint) => normalizeOneLine(constraint.text, TEXT_CAP) === cleanText);
+    if (existing) return { constraint: existing, added: false, total: contract.constraints.length };
+    const constraint: Constraint = {
+      id: nextConstraintId(contract.constraints),
+      text: cleanText,
+      added: new Date().toISOString().slice(0, 10),
+      source: normalizeOneLine(source, 40) || "agent",
+    };
+    contract.constraints.push(constraint);
+    saveContractUnlocked(cwd, contract);
+    return { constraint, added: true, total: contract.constraints.length };
+  });
+}
+
+export function addConstraint(cwd: string, text: string, source = "agent"): Constraint {
+  return addConstraintWithStatus(cwd, text, source).constraint;
+}
+
+export function removeConstraint(cwd: string, id: string): boolean {
+  return withStoreLock(storeDir(cwd), () => {
+    const contract = loadContractUnlocked(cwd, true);
+    const before = contract.constraints.length;
+    contract.constraints = contract.constraints.filter((c) => c.id !== id);
+    if (contract.constraints.length === before) return false;
+    saveContractUnlocked(cwd, contract);
+    return true;
+  });
+}
+
+/** Bounded compact lines: frozen seeds plus the newest remaining entries. */
+export function contractLines(contract: Contract): string[] {
+  const constraints = contract.constraints;
+  let visible = constraints;
+  if (constraints.length > CONTRACT_RENDER_MAX) {
+    const seedIndexes = constraints
+      .map((constraint, index) => ({ constraint, index }))
+      .filter(({ constraint }) => constraint.source === "seed")
+      .map(({ index }) => index)
+      .slice(0, CONTRACT_RENDER_MAX);
+    const selected = new Set(seedIndexes);
+    for (let index = constraints.length - 1; index >= 0 && selected.size < CONTRACT_RENDER_MAX; index -= 1) {
+      selected.add(index);
+    }
+    visible = constraints.filter((_constraint, index) => selected.has(index));
+  }
+  const lines = visible.map((c) => {
+    const id = normalizeOneLine(c.id, 80) || "(missing-id)";
+    return `${id}: ${normalizeOneLine(c.text, TEXT_CAP)}`;
+  });
+  if (visible.length < constraints.length) {
+    lines.unshift(`… ${constraints.length - visible.length} older non-seed constraints omitted`);
+  }
+  return lines;
+}

package/extension/lib/contract_check.ts

@@ -0,0 +1,62 @@
+/**
+ * guard_contract_check — deterministic checklist over a change summary
+ * (SPEC §5). Heuristic keyword coverage per constraint; no LLM. No pi imports.
+ */
+
+import type { Contract } from "./defaults.ts";
+
+/**
+ * Keyword coverage per constraint id (lowercased substring matching against
+ * the supplied summary).
+ */
+export const CONSTRAINT_KEYWORDS: Record<string, string[]> = {
+  "01-obey-instructions": ["instruct", "constraint", "owner", "ask instead", "conflict"],
+  "02-evidence-before-success": ["evidence", "verif", "ev-", "proof", "test run"],
+  "03-stay-in-scope": ["scope", "unrelated", "refactor", "only file", "in scope"],
+  "04-orient-first": ["read", "orient", "convention", "familiar", "reviewed"],
+  "05-simplest-correct": ["simple", "test", "behavior", "minimal"],
+  "06-journal-decisions": ["journal", "decision", "noted", "recorded"],
+  "07-log-corrections": ["correction", "tag", "corrected", "feedback"],
+  "08-keep-diffs-reviewable": ["diff", "lines", "split", "small", "reviewable"],
+  "09-no-identical-retries": ["retry", "failing", "approach", "loop", "changed strategy"],
+  "10-preflight-env": ["preflight", "tool", "version", "env", "sandbox"],
+  "11-batch-operations": ["batch", "permission", "prompt", "grouped"],
+  "12-budget-context": ["budget", "context", "digest", "head", "tail", "targeted"],
+};
+
+export interface ChecklistItem {
+  id: string;
+  addressed: boolean;
+}
+
+const CHECKLIST_IDS_MAX = 24;
+
+function compactIds(items: ChecklistItem[]): string {
+  const ids = items.slice(0, CHECKLIST_IDS_MAX).map((item) => String(item.id).slice(0, 2));
+  const omitted = items.length - ids.length;
+  return `${ids.length > 0 ? ids.join(" ") : "(none)"}${omitted > 0 ? ` +${omitted} more` : ""}`;
+}
+
+/** Mark each constraint addressed/unclear from the summary text. */
+export function checkContractSummary(summary: string, contract: Contract): ChecklistItem[] {
+  const hay = summary.toLowerCase();
+  return contract.constraints.map((c) => {
+    const keywords = CONSTRAINT_KEYWORDS[c.id] ?? [];
+    return { id: c.id, addressed: keywords.some((k) => hay.includes(k)) };
+  });
+}
+
+/** Compact rendering: addressed ids grouped, unclear ids grouped, then a Nudge. */
+export function renderChecklist(items: ChecklistItem[]): string {
+  const addressed = items.filter((i) => i.addressed);
+  const unclear = items.filter((i) => !i.addressed);
+  const lines: string[] = [];
+  lines.push(`addressed: ${compactIds(addressed)}`);
+  lines.push(`unclear: ${compactIds(unclear)}`);
+  lines.push(
+    unclear.length > 0
+      ? `Nudge: resolve unclear constraints (guard_contract list) or state why they don't apply.`
+      : `Nudge: all constraints addressed — verify before claiming success.`,
+  );
+  return lines.join("\n");
+}

package/extension/lib/defaults.ts

@@ -0,0 +1,124 @@
+/**
+ * Frozen defaults for protect-context (SPEC.md v1.0 §2 and §6).
+ *
+ * These must stay byte-identical to `src/protect_context/defaults.py`
+ * (both sides are pinned by tests: same 12 constraint ids and exact texts).
+ * Do not reword, reorder, or renumber.
+ */
+
+export interface Constraint {
+  id: string;
+  text: string;
+  added: string;
+  source: string;
+}
+
+export interface Contract {
+  version: 1;
+  constraints: Constraint[];
+}
+
+export interface GuardConfig {
+  loop_block_after: number;
+  diff_warn_lines: number;
+  diff_hard_lines: number;
+  diff_warn_files: number;
+  ctx_warn_pct: number;
+  brief_mode: "changed" | "always";
+  risk_confirm: boolean;
+  preflight_tools: string[];
+}
+
+/** Seed date = SPEC freeze date. */
+export const SEED_ADDED = "2026-08-28";
+
+/** Seed contract — SPEC §6, FROZEN ids and texts. */
+export const DEFAULT_CONTRACT: Contract = {
+  version: 1,
+  constraints: [
+    {
+      id: "01-obey-instructions",
+      text: "Obey the owner's explicit instructions and stated constraints exactly; when instructions conflict, ask instead of guessing.",
+      added: SEED_ADDED,
+      source: "seed",
+    },
+    {
+      id: "02-evidence-before-success",
+      text: "Never claim success without citing a fresh verification run (evidence id or pasted output) for the exact claim.",
+      added: SEED_ADDED,
+      source: "seed",
+    },
+    {
+      id: "03-stay-in-scope",
+      text: "Change only files the stated task requires; no unrelated refactors, reformatting, or \"improvements\".",
+      added: SEED_ADDED,
+      source: "seed",
+    },
+    {
+      id: "04-orient-first",
+      text: "Before the first edit in an unfamiliar area, read the relevant files and conventions; never code from guesses.",
+      added: SEED_ADDED,
+      source: "seed",
+    },
+    {
+      id: "05-simplest-correct",
+      text: "Prefer the simplest implementation satisfying stated behavior; add or update a test for every behavior change.",
+      added: SEED_ADDED,
+      source: "seed",
+    },
+    {
+      id: "06-journal-decisions",
+      text: "Record durable decisions and constraints in the journal when made; re-read them before resuming work.",
+      added: SEED_ADDED,
+      source: "seed",
+    },
+    {
+      id: "07-log-corrections",
+      text: "When the owner corrects behavior, log a tagged correction; check corrections before similar work.",
+      added: SEED_ADDED,
+      source: "seed",
+    },
+    {
+      id: "08-keep-diffs-reviewable",
+      text: "Keep diffs small: split work into logical steps; treat 400+ changed lines per task as a stop-and-split signal.",
+      added: SEED_ADDED,
+      source: "seed",
+    },
+    {
+      id: "09-no-identical-retries",
+      text: "After 2 failures of the same command, change approach or gather new information; never re-run identical failing commands.",
+      added: SEED_ADDED,
+      source: "seed",
+    },
+    {
+      id: "10-preflight-env",
+      text: "When tools behave unexpectedly, run preflight (tool presence/versions) before blaming code.",
+      added: SEED_ADDED,
+      source: "seed",
+    },
+    {
+      id: "11-batch-operations",
+      text: "Batch related shell operations; prefer commands that avoid per-command permission prompts.",
+      added: SEED_ADDED,
+      source: "seed",
+    },
+    {
+      id: "12-budget-context",
+      text: "Keep tool outputs bounded (head/tail/digest); use targeted reads; avoid re-reading large files.",
+      added: SEED_ADDED,
+      source: "seed",
+    },
+  ],
+};
+
+/** Default thresholds — SPEC §2, FROZEN. */
+export const DEFAULT_CONFIG: GuardConfig = {
+  loop_block_after: 3,
+  diff_warn_lines: 400,
+  diff_hard_lines: 800,
+  diff_warn_files: 10,
+  ctx_warn_pct: 70,
+  brief_mode: "changed",
+  risk_confirm: true,
+  preflight_tools: ["git", "python3", "pip", "node", "npm", "rg", "pytest"],
+};

package/extension/lib/events.ts

@@ -0,0 +1,69 @@
+/**
+ * Event records for `.agent-guard/events.jsonl` (SPEC §2, §5).
+ * Pure logic + record shapes — no pi imports.
+ */
+
+export type EventKind = "tool_call" | "tool_result";
+
+export interface EventRecord {
+  ts: string;
+  session: string;
+  kind: EventKind;
+  tool: string;
+  ok: boolean | null;
+  ms: number | null;
+  out_chars: number | null;
+  /** Only set for bash tool_result events; fingerprint-normalized. */
+  cmd: string | null;
+  exit: number | null;
+}
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+export function toolCallEvent(session: string, tool: string): EventRecord {
+  return {
+    ts: nowIso(),
+    session,
+    kind: "tool_call",
+    tool,
+    ok: null,
+    ms: null,
+    out_chars: null,
+    cmd: null,
+    exit: null,
+  };
+}
+
+export function toolResultEvent(
+  session: string,
+  tool: string,
+  opts: { ok: boolean | null; ms: number | null; outChars: number | null; cmd?: string | null; exit?: number | null },
+): EventRecord {
+  return {
+    ts: nowIso(),
+    session,
+    kind: "tool_result",
+    tool,
+    ok: opts.ok,
+    ms: opts.ms,
+    out_chars: opts.outChars,
+    cmd: opts.cmd ?? null,
+    exit: opts.exit ?? null,
+  };
+}
+
+/**
+ * The pi bash tool does not expose the exit code in its details; on nonzero
+ * exit it throws with "Command exited with code N" appended to the output.
+ * Parse it back out; returns null when unavailable (e.g. cancelled).
+ */
+export function bashExitFromResult(text: string): number | null {
+  const matches = text.matchAll(/Command exited with code (\d+)/g);
+  let last: number | null = null;
+  for (const m of matches) {
+    last = Number(m[1]);
+  }
+  return last;
+}

package/extension/lib/fingerprint.ts

@@ -0,0 +1,56 @@
+/**
+ * Command fingerprinting and risk-pattern matching (SPEC §2, §5).
+ * Pure logic — no pi imports, testable via `node --test --experimental-strip-types`.
+ */
+
+/**
+ * Fingerprint normalization (FROZEN): trim, collapse all whitespace runs to
+ * single spaces. Nothing else (case is preserved).
+ */
+export function normalizeCommand(cmd: string): string {
+  return cmd.trim().replace(/\s+/g, " ");
+}
+
+export interface RiskPattern {
+  name: string;
+  test: (cmd: string) => boolean;
+}
+
+/**
+ * Deny-confirm list (SPEC §5, FROZEN names). Matching is anchored to the
+ * CATASTROPHIC literal targets — over-matching benign commands (every
+ * absolute-path `rm -rf`, man pages, greps) generates confirm fatigue that
+ * defeats the grouped confirm's purpose (goal #11). `git push --force` must
+ * not match `--force-with-lease`.
+ */
+export const RISK_PATTERNS: RiskPattern[] = [
+  // Bare "/" or "~/" targets only — not every absolute path.
+  { name: "rm -rf /", test: (c) => /rm -rf \/(?:\s|$)/.test(c) },
+  { name: "rm -rf ~", test: (c) => /rm -rf ~(?:\/(?:\s|$)|\s|$)/.test(c) },
+  {
+    name: "git push --force",
+    test: (c) => /git push\b[^|;&]*--force(?!-with-lease)/.test(c),
+  },
+  { name: "git reset --hard", test: (c) => c.includes("git reset --hard") },
+  // mkfs needs a device target: reading man pages / grepping docs is safe.
+  { name: "mkfs", test: (c) => /\bmkfs[^|;&]*\/dev\//.test(c) },
+  {
+    name: "dd of=/dev/",
+    test: (c) => /\bdd\b[^|;&]*\bof=\/dev\//.test(c),
+  },
+  { name: "chmod -R 777 /", test: (c) => /chmod -R 777 \/(?:\s|$)/.test(c) },
+  {
+    name: "curl | sh",
+    test: (c) => /curl\b[^|;&]*\|\s*(sudo\s+)?(ba|z|da)?sh\b/.test(c),
+  },
+  // `sudo rm` but not `sudo rmmod` (or other rm-prefixed tools).
+  { name: "sudo rm", test: (c) => /\bsudo\s+rm(?:\s|$)/.test(c) },
+];
+
+/** Returns the matched risk pattern name, or null if the command is safe. */
+export function matchRisk(normalizedCmd: string): string | null {
+  for (const p of RISK_PATTERNS) {
+    if (p.test(normalizedCmd)) return p.name;
+  }
+  return null;
+}