protect-context 0.0.0-stage → 1.0.0

package/extension/lib/gitparse.ts

@@ -0,0 +1,229 @@
+/**
+ * git numstat / shortstat parsing and diff verdicts (SPEC §5, §1 #8).
+ * Pure logic — no pi imports.
+ */
+
+import { closeSync, lstatSync, openSync, readSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
+
+export const UNTRACKED_MAX_FILES_SCANNED = 1_000;
+export const UNTRACKED_MAX_BYTES_PER_FILE = 1_000_000;
+export const UNTRACKED_MAX_BYTES_TOTAL = 8_000_000;
+const READ_CHUNK = 64 * 1024;
+
+export interface NumstatRow {
+  path: string;
+  additions: number;
+  deletions: number;
+  binary: boolean;
+}
+
+export interface Numstat {
+  files: NumstatRow[];
+  fileCount: number;
+  lines: number;
+}
+
+/** Parse `git diff --numstat HEAD` output. Binary rows report "-\t-". */
+export function parseNumstat(out: string): Numstat {
+  const files: NumstatRow[] = [];
+  for (const line of out.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed === "") continue;
+    const parts = trimmed.split("\t");
+    if (parts.length < 3) continue;
+    const path = parts.slice(2).join("\t");
+    const additions = parts[0] === "-" ? 0 : Number(parts[0]);
+    const deletions = parts[1] === "-" ? 0 : Number(parts[1]);
+    files.push({
+      path,
+      additions: Number.isFinite(additions) ? additions : 0,
+      deletions: Number.isFinite(deletions) ? deletions : 0,
+      binary: parts[0] === "-" || parts[1] === "-",
+    });
+  }
+  return {
+    files,
+    fileCount: files.length,
+    lines: files.reduce((sum, f) => sum + f.additions + f.deletions, 0),
+  };
+}
+
+/** Parse `git status --porcelain=v1 -z --untracked-files=all --`. Porcelain
+ * v1's NUL form is stable and paths are repo-root-relative; ignored files are
+ * absent because Git, rather than a home-grown ignore matcher, selects them. */
+export function parseUntrackedPaths(out: string, activeStorePath: string | null = ".agent-guard"): string[] {
+  const store = activeStorePath
+    ?.replaceAll("\\", "/")
+    .replace(/^\.\//, "")
+    .replace(/\/+$/, "");
+  const paths = new Set<string>();
+  for (const record of out.split("\0")) {
+    if (!record.startsWith("?? ")) continue;
+    const path = record.slice(3);
+    // The audit itself creates this runtime store. It is never part of the
+    // user's diff, even when the consumer has not installed the recommended
+    // .gitignore rule. Every other exclusion remains Git's decision.
+    const normalizedPath = path.replaceAll("\\", "/");
+    if (store && (normalizedPath === store || normalizedPath.startsWith(`${store}/`))) {
+      continue;
+    }
+    paths.add(path);
+  }
+  return [...paths].sort((a, b) => a.localeCompare(b));
+}
+
+export interface UntrackedScan {
+  /** Exact number of non-ignored untracked paths reported by Git. */
+  files: number;
+  lines: number;
+  filesScanned: number;
+  bytesScanned: number;
+  binaryFiles: number;
+  skippedFiles: number;
+  truncatedFiles: number;
+  scanLimited: boolean;
+}
+
+/** Count text lines in untracked files under strict I/O caps. Symlinks and
+ * paths escaping `root` are never followed. File count remains exact even
+ * when content scanning reaches a cap. */
+export function scanUntrackedFiles(root: string, paths: string[], hardLineBudget: number): UntrackedScan {
+  const rootAbs = resolve(root);
+  const budget = Math.max(0, hardLineBudget);
+  let lines = 0;
+  let filesScanned = 0;
+  let bytesScanned = 0;
+  let binaryFiles = 0;
+  let skippedFiles = 0;
+  let truncatedFiles = 0;
+
+  for (const path of paths) {
+    if (
+      filesScanned >= UNTRACKED_MAX_FILES_SCANNED ||
+      bytesScanned >= UNTRACKED_MAX_BYTES_TOTAL ||
+      lines >= budget
+    ) {
+      skippedFiles += 1;
+      continue;
+    }
+
+    const candidate = resolve(rootAbs, path);
+    const rel = relative(rootAbs, candidate);
+    if (rel === "" || rel.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) || rel === ".." || isAbsolute(rel)) {
+      skippedFiles += 1;
+      continue;
+    }
+
+    try {
+      const stat = lstatSync(candidate);
+      if (stat.isSymbolicLink() || !stat.isFile()) {
+        skippedFiles += 1;
+        continue;
+      }
+    } catch {
+      skippedFiles += 1;
+      continue;
+    }
+
+    let fd: number | null = null;
+    let fileBytes = 0;
+    let fileLines = 0;
+    let lastByte: number | null = null;
+    let binary = false;
+    let complete = true;
+    try {
+      fd = openSync(candidate, "r");
+      for (;;) {
+        const remainingFile = UNTRACKED_MAX_BYTES_PER_FILE - fileBytes;
+        const remainingTotal = UNTRACKED_MAX_BYTES_TOTAL - bytesScanned;
+        if (remainingFile <= 0 || remainingTotal <= 0 || lines + fileLines >= budget) {
+          complete = false;
+          break;
+        }
+        const size = Math.min(READ_CHUNK, remainingFile, remainingTotal);
+        const buffer = Buffer.allocUnsafe(size);
+        const read = readSync(fd, buffer, 0, size, null);
+        if (read === 0) break;
+        const chunk = buffer.subarray(0, read);
+        fileBytes += read;
+        bytesScanned += read;
+        if (chunk.includes(0)) {
+          binary = true;
+          fileLines = 0;
+          break;
+        }
+        for (const byte of chunk) if (byte === 0x0a) fileLines += 1;
+        lastByte = chunk[read - 1] ?? null;
+      }
+    } catch {
+      skippedFiles += 1;
+      continue;
+    } finally {
+      if (fd !== null) {
+        try {
+          closeSync(fd);
+        } catch {
+          // Best-effort close after a read failure.
+        }
+      }
+    }
+
+    filesScanned += 1;
+    if (binary) {
+      binaryFiles += 1;
+      continue;
+    }
+    if (complete && fileBytes > 0 && lastByte !== 0x0a) fileLines += 1;
+    if (!complete) truncatedFiles += 1;
+    lines += fileLines;
+  }
+
+  return {
+    files: paths.length,
+    lines,
+    filesScanned,
+    bytesScanned,
+    binaryFiles,
+    skippedFiles,
+    truncatedFiles,
+    scanLimited: skippedFiles > 0 || truncatedFiles > 0,
+  };
+}
+
+export interface Shortstat {
+  files: number;
+  lines: number;
+}
+
+/** Parse `git diff --shortstat HEAD` output, e.g.
+ *  " 3 files changed, 120 insertions(+), 4 deletions(-)". */
+export function parseShortstat(out: string): Shortstat {
+  const filesM = out.match(/(\d+)\s+files? changed/);
+  const insM = out.match(/(\d+)\s+insertions?\(\+\)/);
+  const delM = out.match(/(\d+)\s+deletions?\(-\)/);
+  const files = filesM ? Number(filesM[1]) : 0;
+  const lines = (insM ? Number(insM[1]) : 0) + (delM ? Number(delM[1]) : 0);
+  return { files, lines };
+}
+
+export type DiffLevel = "ok" | "warn" | "hard";
+
+export interface DiffVerdict {
+  level: DiffLevel;
+  lines: number;
+  files: number;
+}
+
+export interface DiffThresholds {
+  diff_warn_lines: number;
+  diff_hard_lines: number;
+  diff_warn_files: number;
+}
+
+/** Verdict of a diff against configured thresholds (SPEC §1 #8). */
+export function diffVerdict(lines: number, files: number, t: DiffThresholds): DiffVerdict {
+  if (lines >= t.diff_hard_lines) return { level: "hard", lines, files };
+  if (lines >= t.diff_warn_lines || files >= t.diff_warn_files) return { level: "warn", lines, files };
+  return { level: "ok", lines, files };
+}

package/extension/lib/journal.ts

@@ -0,0 +1,100 @@
+/**
+ * Journal (.agent-guard/journal.jsonl) — decisions/corrections/risks/notes
+ * (SPEC §1 #6 #7, §2). No pi imports.
+ */
+
+import { appendJsonl, journalPath, readJsonl } from "./store.ts";
+import { normalizeOneLine } from "./text.ts";
+
+export type JournalType = "decision" | "correction" | "risk" | "note";
+
+export interface JournalEntry {
+  ts: string;
+  type: JournalType;
+  text: string;
+  tags: string[];
+}
+
+export function isJournalType(v: unknown): v is JournalType {
+  return v === "decision" || v === "correction" || v === "risk" || v === "note";
+}
+
+/** Free-text cap (chars): journal text is re-injected into briefs (goal #12). */
+export const TEXT_CAP = 500;
+export const TAG_COUNT_CAP = 8;
+export const TAG_TEXT_CAP = 40;
+
+/** Replace terminal/control formatting, collapse whitespace and bound output. */
+export function sanitizeJournalText(value: unknown, cap = TEXT_CAP): string {
+  return normalizeOneLine(value, cap);
+}
+
+/** Clean, deduplicate and bound tags before they reach storage or a brief. */
+export function sanitizeTags(tags: unknown): string[] {
+  const clean: string[] = [];
+  const seen = new Set<string>();
+  const candidates = Array.isArray(tags) ? tags : typeof tags === "string" ? [tags] : [];
+  for (const tag of candidates) {
+    const value = sanitizeJournalText(tag, TAG_TEXT_CAP);
+    if (value !== "" && !seen.has(value)) {
+      clean.push(value);
+      seen.add(value);
+    }
+    if (clean.length >= TAG_COUNT_CAP) break;
+  }
+  return clean;
+}
+
+/** Preserve a required provenance tag even when caller tags fill the cap. */
+export function tagsWithRequired(
+  tags: unknown,
+  required: string,
+): string[] {
+  const requiredClean = sanitizeJournalText(required, TAG_TEXT_CAP);
+  if (requiredClean === "") throw new Error("required journal tag must not be blank");
+  const clean = sanitizeTags(tags).filter((tag) => tag !== requiredClean);
+  return [...clean.slice(0, TAG_COUNT_CAP - 1), requiredClean];
+}
+
+export function appendJournal(
+  cwd: string,
+  entry: { type: JournalType; text: string; tags?: string[] },
+): JournalEntry {
+  const cleanText = sanitizeJournalText(entry.text);
+  if (cleanText === "") throw new Error("journal text must not be blank");
+  const full: JournalEntry = {
+    ts: new Date().toISOString(),
+    type: entry.type,
+    text: cleanText,
+    tags: sanitizeTags(entry.tags),
+  };
+  appendJsonl(journalPath(cwd), full);
+  return full;
+}
+
+export function readJournal(cwd: string): JournalEntry[] {
+  return readJsonl<JournalEntry>(journalPath(cwd));
+}
+
+/** Most recent trusted entries of one type, newest first. Model-authored
+ * entries carry the reserved `agent` provenance tag and are never re-injected. */
+export function recentTrustedEntries(
+  journal: JournalEntry[],
+  type: "decision" | "correction",
+  n: number,
+): JournalEntry[] {
+  return journal
+    .filter((e) => e.type === type && !sanitizeTags(e.tags).includes("agent"))
+    .slice(-n)
+    .reverse();
+}
+
+/** Most recent trusted corrections, newest first. */
+export function recentCorrections(journal: JournalEntry[], n: number): JournalEntry[] {
+  return recentTrustedEntries(journal, "correction", n);
+}
+
+/** Most recent trusted decisions, newest first. */
+export function recentDecisions(journal: JournalEntry[], n: number): JournalEntry[] {
+  return recentTrustedEntries(journal, "decision", n);
+}

package/extension/lib/loops.ts

@@ -0,0 +1,151 @@
+/**
+ * Loop detection from events.jsonl (SPEC §1 #9, §5).
+ * Pure logic — no pi imports.
+ */
+
+import type { EventRecord } from "./events.ts";
+import { normalizeOneLine } from "./text.ts";
+import { normalizeCommand } from "./fingerprint.ts";
+import type { VerifyRun } from "./verify.ts";
+
+export interface LoopInfo {
+  cmd: string;
+  failures: number;
+  lastExit: number | null;
+}
+
+interface LoopOutcome {
+  ts: string;
+  cmd: string;
+  ok: boolean | null;
+  exit: number | null;
+  order: number;
+}
+
+function timestampMillis(value: string): number | null {
+  const raw = value.trim();
+  if (raw === "") return null;
+  // Python's legacy writer could omit a zone; both runtimes treat such store
+  // rows as UTC so reconstruction does not depend on the host timezone.
+  const zoned = /(?:z|[+-]\d{2}:\d{2})$/i.test(raw) ? raw : `${raw}Z`;
+  const parsed = Date.parse(zoned);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function compareOutcomes(a: LoopOutcome, b: LoopOutcome): number {
+  const aMs = timestampMillis(a.ts);
+  const bMs = timestampMillis(b.ts);
+  if (aMs !== null && bMs !== null) return aMs - bMs || a.order - b.order;
+  if (aMs !== null) return -1;
+  if (bMs !== null) return 1;
+  return a.ts.localeCompare(b.ts) || a.order - b.order;
+}
+
+function applyOutcome(map: Map<string, LoopInfo>, outcome: LoopOutcome): void {
+  const cmd = normalizeCommand(outcome.cmd);
+  if (cmd === "") return;
+  if (outcome.ok === true) {
+    map.delete(cmd);
+    return;
+  }
+  if (outcome.ok !== false) return;
+  const cur = map.get(cmd) ?? { cmd, failures: 0, lastExit: null };
+  cur.failures += 1;
+  if (outcome.exit !== null) cur.lastExit = outcome.exit;
+  map.set(cmd, cur);
+}
+
+/**
+ * Failing-command streaks per fingerprint-normalized command for a session.
+ * SPEC §1 #9 calls these "streaks": the count of failures since the LAST
+ * SUCCESSFUL run of that same fingerprint — a success (ok=true) resets the
+ * streak, a failure of a different command does not. This mirrors
+ * loops.streaks() on the Python side exactly (same store, same arithmetic).
+ */
+export function failedAttempts(events: EventRecord[], session: string): Map<string, LoopInfo> {
+  const map = new Map<string, LoopInfo>();
+  for (const e of events) {
+    if (e.kind !== "tool_result" || e.session !== session) continue;
+    if (typeof e.cmd !== "string" || e.cmd === "") continue;
+    applyOutcome(map, {
+      ts: typeof e.ts === "string" ? e.ts : "",
+      cmd: e.cmd,
+      ok: typeof e.ok === "boolean" ? e.ok : null,
+      exit: typeof e.exit === "number" && Number.isFinite(e.exit) ? e.exit : null,
+      order: 0,
+    });
+  }
+  return map;
+}
+
+/** Reconstruct streaks from both persisted sources in timestamp order.
+ * guard_verify writes the evidence ledger rather than events.jsonl, so using
+ * events alone forgets its failures after a restart. Session scoping is
+ * applied before merging; older sessions can never affect the new one. */
+export function failedAttemptsFromLedgers(
+  events: EventRecord[],
+  runs: VerifyRun[],
+  session: string,
+): Map<string, LoopInfo> {
+  const outcomes: LoopOutcome[] = [];
+  let order = 0;
+  for (const event of events) {
+    if (event.kind !== "tool_result" || event.session !== session || typeof event.cmd !== "string" || event.cmd === "") continue;
+    outcomes.push({
+      ts: typeof event.ts === "string" ? event.ts : "",
+      cmd: event.cmd,
+      ok: typeof event.ok === "boolean" ? event.ok : null,
+      exit: typeof event.exit === "number" && Number.isFinite(event.exit) ? event.exit : null,
+      order: order++,
+    });
+  }
+  for (const run of runs) {
+    if (run.session !== session || typeof run.cmd !== "string" || run.cmd === "") continue;
+    outcomes.push({
+      ts: typeof run.ts === "string" ? run.ts : "",
+      cmd: run.cmd,
+      ok: typeof run.ok === "boolean" ? run.ok : null,
+      exit: typeof run.exit === "number" && Number.isFinite(run.exit) ? run.exit : null,
+      order: order++,
+    });
+  }
+  outcomes.sort(compareOutcomes);
+
+  const map = new Map<string, LoopInfo>();
+  for (const outcome of outcomes) applyOutcome(map, outcome);
+  return map;
+}
+
+/**
+ * Block when prior failures >= loop_block_after - 1 (3rd default attempt).
+ * The max(1, …) clamp mirrors loops.block_threshold() on the Python side:
+ * loop_block_after=1 must never block a command with zero prior failures.
+ */
+export function shouldBlockLoop(priorFailures: number, loopBlockAfter: number): boolean {
+  return priorFailures >= Math.max(1, loopBlockAfter - 1);
+}
+
+/** FROZEN block reason format (SPEC §5). */
+export function loopBlockReason(cmd: string, priorFailures: number): string {
+  const safeCommand = normalizeOneLine(cmd, 60);
+  return (
+    `guard: '${safeCommand}' already failed ${priorFailures} times this session — do not re-run unchanged; ` +
+    `change approach or read the error. ` +
+    `(Raise loop_block_after in .agent-guard/config.json to override.)`
+  );
+}
+
+/** Commands currently in a failing loop (would be blocked on next attempt). */
+export function openLoopsFromMap(map: Map<string, LoopInfo>, loopBlockAfter: number): LoopInfo[] {
+  const out: LoopInfo[] = [];
+  for (const info of map.values()) {
+    if (shouldBlockLoop(info.failures, loopBlockAfter)) out.push(info);
+  }
+  out.sort((a, b) => b.failures - a.failures || a.cmd.localeCompare(b.cmd));
+  return out;
+}
+
+/** Same, computed from raw events (disk path). */
+export function openLoops(events: EventRecord[], session: string, loopBlockAfter: number): LoopInfo[] {
+  return openLoopsFromMap(failedAttempts(events, session), loopBlockAfter);
+}

package/extension/lib/orientation.ts

@@ -0,0 +1,209 @@
+/**
+ * Orientation digest (SPEC §1 #4): repo tree ≤2 levels, language counts by
+ * file extension, conventions-file detection (CLAUDE.md/AGENTS.md/README...).
+ * Pure local filesystem scanning — no network, no LLM, no pi imports.
+ *
+ * Mirrors src/protect_context/orientation.py: the session-start surface
+ * injects this digest (digest-gated like the brief) so goal #4 ("misread the
+ * repo before acting") has a reachable delivery path in the extension.
+ */
+
+import { lstatSync, readdirSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+import { normalizeOneLine } from "./text.ts";
+
+const SKIP_DIRS = new Set([
+  "venv",
+  "env",
+  "node_modules",
+  "__pycache__",
+  "dist",
+  "build",
+  "coverage",
+]);
+
+export const CONVENTIONS_FILES = ["CLAUDE.md", "AGENTS.md", "CONVENTIONS.md", "README.md", "README"] as const;
+
+const EXT_LANG: Record<string, string> = {
+  ".py": "Python",
+  ".pyw": "Python",
+  ".ts": "TypeScript",
+  ".tsx": "TypeScript",
+  ".js": "JavaScript",
+  ".jsx": "JavaScript",
+  ".mjs": "JavaScript",
+  ".cjs": "JavaScript",
+  ".rs": "Rust",
+  ".go": "Go",
+  ".java": "Java",
+  ".kt": "Kotlin",
+  ".swift": "Swift",
+  ".rb": "Ruby",
+  ".php": "PHP",
+  ".cs": "C#",
+  ".c": "C",
+  ".h": "C",
+  ".cpp": "C++",
+  ".cc": "C++",
+  ".hpp": "C++",
+  ".sh": "Shell",
+  ".bash": "Shell",
+  ".zsh": "Shell",
+};
+
+export const MAX_TREE_ENTRIES = 12;
+export const MAX_CHILDREN = 8;
+const MAX_WALK_DEPTH = 3;
+const MAX_FILES_SCANNED = 4000;
+
+function isSkippedDir(name: string): boolean {
+  return name.startsWith(".") || SKIP_DIRS.has(name) || name.endsWith(".egg-info");
+}
+
+function displayName(name: string): string {
+  return normalizeOneLine(name, 120) || "(control-only name)";
+}
+
+export interface OrientationScan {
+  root: string;
+  /** Top-level dirs (with a child sample) then top-level files. */
+  tree: string[];
+  languages: Array<{ lang: string; count: number }>;
+  conventions: string[];
+}
+
+/** Resolve nested launch directories to their containing worktree root.
+ * Failures are intentionally quiet: outside Git (or without Git installed),
+ * orientation remains a bounded scan of the caller-supplied directory. */
+export function orientationRoot(start: string): string {
+  try {
+    const value = execFileSync("git", ["-C", start, "rev-parse", "--show-toplevel"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 3000,
+      maxBuffer: 64 * 1024,
+    }).trim();
+    return value || start;
+  } catch {
+    return start;
+  }
+}
+
+function childrenSample(dir: string): string {
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return "";
+  }
+  const names: string[] = [];
+  const visible = entries.filter((e) => !isSkippedDir(e)).sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase()));
+  for (const name of visible) {
+    let isDir = false;
+    try {
+      // lstat prevents a repository symlink from turning this bounded local
+      // orientation scan into a traversal of an arbitrary external tree.
+      isDir = lstatSync(join(dir, name)).isDirectory();
+    } catch {
+      // unreadable entry: still list it
+    }
+    const shown = displayName(name);
+    names.push(isDir ? `${shown}/` : shown);
+    if (names.length >= MAX_CHILDREN) break;
+  }
+  const remaining = visible.length - names.length;
+  let s = names.join(", ");
+  if (remaining > 0) s += `, +${remaining} more`;
+  return s;
+}
+
+function languageCounts(root: string): Array<{ lang: string; count: number }> {
+  const counts = new Map<string, number>();
+  let seen = 0;
+
+  const walk = (dir: string, depth: number): void => {
+    if (seen >= MAX_FILES_SCANNED || depth > MAX_WALK_DEPTH) return;
+    let entries: string[];
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return;
+    }
+    for (const name of entries.sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase()))) {
+      if (seen >= MAX_FILES_SCANNED) return;
+      const full = join(dir, name);
+      let st;
+      try {
+        st = lstatSync(full);
+      } catch {
+        continue;
+      }
+      if (st.isDirectory()) {
+        if (!isSkippedDir(name)) walk(full, depth + 1);
+        continue;
+      }
+      seen += 1;
+      const dot = name.lastIndexOf(".");
+      if (dot <= 0) continue; // no extension / dotfiles
+      const lang = EXT_LANG[name.slice(dot).toLowerCase()];
+      if (lang) counts.set(lang, (counts.get(lang) ?? 0) + 1);
+    }
+  };
+
+  walk(root, 0);
+  return [...counts.entries()]
+    .map(([lang, count]) => ({ lang, count }))
+    .sort((a, b) => b.count - a.count || a.lang.localeCompare(b.lang));
+}
+
+export function scanOrientation(start: string): OrientationScan {
+  const root = orientationRoot(start);
+  const dirs: string[] = [];
+  const files: string[] = [];
+  let entries: string[] = [];
+  try {
+    entries = readdirSync(root);
+  } catch {
+    entries = [];
+  }
+  for (const name of entries.sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase()))) {
+    if (isSkippedDir(name)) continue;
+    let isDir = false;
+    try {
+      isDir = lstatSync(join(root, name)).isDirectory();
+    } catch {
+      // unreadable entry: list as file
+    }
+    if (isDir) {
+      const kids = childrenSample(join(root, name));
+      dirs.push(`${displayName(name)}/` + (kids ? ` (${kids})` : ""));
+    } else {
+      files.push(displayName(name));
+    }
+  }
+  const conventions = CONVENTIONS_FILES.filter((c) => {
+    try {
+      return lstatSync(join(root, c)).isFile();
+    } catch {
+      return false;
+    }
+  });
+  return { root, tree: dirs.concat(files).slice(0, MAX_TREE_ENTRIES), languages: languageCounts(root), conventions };
+}
+
+/** Compact orientation digest (ends with Nudge) — mirrors orientation.digest(). */
+export function renderOrientation(scan: OrientationScan): string {
+  const name = displayName(scan.root.split(/[\\/]/).filter(Boolean).pop() || scan.root);
+  const lines = [`PC orientation · ${name}`];
+  lines.push(...scan.tree);
+  const langs =
+    scan.languages
+      .slice(0, 6)
+      .map((l) => `${l.lang}=${l.count}`)
+      .join(", ") || "none detected";
+  lines.push(`languages: ${langs}`);
+  lines.push("conventions: " + (scan.conventions.join(", ") || "none found"));
+  lines.push("Nudge: read the conventions files and relevant code before the first edit — never code from guesses.");
+  return lines.join("\n");
+}