@pify/yolo 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pifydev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# @pify/yolo
+
+One toggle to auto-approve everything in [pi](https://github.com/earendil-works/pi) — with an undo trail so YOLO never means unrecoverable.
+
+Part of the [Pify suite](https://github.com/pifydev). Install with [`pify install yolo`](https://github.com/pifydev/cli) or `pi install npm:@pify/yolo`.
+
+## Two modes, one toggle
+
+**🛡 guard** (default) — every bash call runs through a three-tier gate:
+
+| Tier | Examples | Behavior |
+|---|---|---|
+| **BLOCK** | `rm -rf /`, `rm -rf ~`, `rm -rf .git`, `mkfs`, `dd of=/dev/…`, fork bomb, `> /dev/sda` | Refused outright. Never overridable — not even by user rules. |
+| **ASK** | `rm -rf <path>`, `git push --force`, `git reset --hard`, `git clean -f`, `curl \| sh`, `find -delete`, `chmod 777`, history rewrites | Confirmation dialog with the command shown. Denials can carry your reason back to the agent. |
+| ALLOW | everything else | Runs untouched. |
+
+**⚡ yolo** (`/yolo`) — the gate stands down and everything auto-approves. The trail keeps recording.
+
+Fail-closed everywhere: rule-evaluation errors block; ASK without a UI (headless/CI) denies.
+
+## The undo trail
+
+Always on, in both modes:
+
+- Every `edit`/`write` saves the file's **pre-image** first (per-project trail under the agent dir — survives restarts).
+- Risky bash commands are logged with cwd, timestamp, and git HEAD.
+- `/yolo trail` shows history; `/yolo undo [n]` restores the newest n file changes (with a confirmation listing exactly what will be touched). Files that didn't exist before are deleted; bash effects are logged but not undoable.
+
+## Custom rules
+
+`.pi/yolo.json` — wildcard patterns, last-match-wins, may retune ASK/ALLOW but never the BLOCK floor:
+
+```json
+{
+  "rules": [
+    { "pattern": "git push origin dev*", "action": "allow" },
+    { "pattern": "npm run deploy*", "action": "ask" }
+  ]
+}
+```
+
+## Commands
+
+```
+/yolo            # toggle guard ↔ yolo
+/yolo status     # mode, rule count, trail size
+/yolo trail      # recent trail entries
+/yolo undo 3     # restore the newest 3 file pre-images
+```
+
+## License
+
+MIT © [Pify maintainers](https://github.com/pifydev)

package/extensions/yolo.ts

@@ -0,0 +1,239 @@
+/**
+ * @pify/yolo — one toggle to auto-approve everything, with an undo trail.
+ *
+ * Two modes. guard (default): bash runs through a three-tier safety gate —
+ * catastrophic patterns BLOCK outright (never overridable), destructive
+ * ones ASK with the command shown (denial reasons flow back to the agent),
+ * everything else runs. yolo: the gate stands down and everything
+ * auto-approves — but the trail keeps recording. In BOTH modes every
+ * edit/write saves a pre-image first and risky bash commands are logged,
+ * so /yolo undo can walk file changes back even after a restart.
+ *
+ * Fail-closed everywhere (zhushanwen's rule): evaluation errors block,
+ * headless ASK becomes deny. User rules in .pi/yolo.json (wildcard,
+ * last-match-wins) can retune ASK/ALLOW but never the catastrophic floor.
+ *
+ * Design synthesis: three-tier rules (pi-yolo-seatbelt), fail-closed +
+ * reject-with-reason + wildcard rules (@zhushanwen/pi-permission),
+ * /yolo session toggle (valdo766hi).
+ */
+import {
+  getAgentDir,
+  type ExtensionAPI,
+  type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { evaluateCommand, parseUserRules } from "../src/rules.ts";
+import { formatTrail, readManifest, recordBash, recordPreImage, trailDir, undo } from "../src/trail.ts";
+import { isRecord, type Mode, type UserRule } from "../src/types.ts";
+
+const MODE_ENTRY = "yolo-mode";
+
+type UiContext = ExtensionContext;
+
+export default function yolo(pi: ExtensionAPI) {
+  let mode: Mode = "guard";
+  let userRules: UserRule[] = [];
+  let dir = "";
+
+  function updateFooter(ctx: UiContext): void {
+    if (!ctx.hasUI) return;
+    ctx.ui.setStatus("yolo", mode === "yolo" ? "⚡ YOLO" : undefined);
+  }
+
+  function setMode(ctx: UiContext, next: Mode): void {
+    mode = next;
+    pi.appendEntry(MODE_ENTRY, { mode: next });
+    updateFooter(ctx);
+    if (ctx.hasUI) {
+      ctx.ui.notify(
+        next === "yolo"
+          ? "⚡ YOLO on — everything auto-approves. The undo trail keeps recording; /yolo to turn the guard back on."
+          : "🛡 Guard on — catastrophic commands block, destructive ones ask.",
+        next === "yolo" ? "warning" : "info",
+      );
+    }
+  }
+
+  function gitHead(cwd: string): string | null {
+    try {
+      return execFileSync("git", ["rev-parse", "HEAD"], {
+        cwd,
+        encoding: "utf8",
+        timeout: 2000,
+        windowsHide: true,
+      }).trim();
+    } catch {
+      return null;
+    }
+  }
+
+  function loadUserRules(cwd: string): void {
+    try {
+      userRules = parseUserRules(JSON.parse(readFileSync(join(cwd, ".pi", "yolo.json"), "utf8")));
+    } catch {
+      userRules = [];
+    }
+  }
+
+  // ── The gate + the trail ─────────────────────────────────────────────
+
+  pi.on("tool_call", async (event, ctx) => {
+    // Trail: pre-image every file mutation, in both modes.
+    if (event.toolName === "edit" || event.toolName === "write") {
+      const path = (event as { input?: { path?: unknown } }).input?.path;
+      if (typeof path === "string" && dir) {
+        recordPreImage(dir, path, Date.now());
+      }
+      return undefined;
+    }
+
+    if (event.toolName !== "bash") return undefined;
+    const command = (event as { input?: { command?: unknown } }).input?.command;
+    if (typeof command !== "string") {
+      return { block: true, reason: "yolo guard: bash call without a command (fail-closed)." };
+    }
+
+    const verdict = evaluateCommand(command, userRules);
+
+    // Log risky commands (and everything in yolo mode) to the trail.
+    if (dir && (mode === "yolo" ? verdict.action !== "allow" : verdict.action !== "allow")) {
+      recordBash(dir, command, ctx.cwd, gitHead(ctx.cwd), Date.now());
+    }
+
+    if (mode === "yolo") return undefined; // gate stands down; trail recorded
+
+    if (verdict.action === "allow") return undefined;
+
+    if (verdict.action === "block") {
+      return {
+        block: true,
+        reason: `yolo guard blocked this command (${verdict.rule}) — catastrophic patterns are never auto-approved. Do not retry it; choose a safer approach.`,
+      };
+    }
+
+    // ASK tier.
+    if (!ctx.hasUI) {
+      return {
+        block: true,
+        reason: `yolo guard: '${verdict.rule}' needs confirmation but no UI is available (fail-closed deny).`,
+      };
+    }
+    const approved = await ctx.ui.confirm(
+      "Destructive command",
+      `${command}\n\nRule: ${verdict.rule}. Run it?`,
+    );
+    if (approved) return undefined;
+
+    // Reject-with-reason: the user's why helps the agent adjust course.
+    const reason = await ctx.ui.input("Why not? (optional — sent to the agent)");
+    return {
+      block: true,
+      reason: reason?.trim()
+        ? `The user declined (${verdict.rule}): ${reason.trim()}`
+        : `The user declined this command (${verdict.rule}). Choose a different approach.`,
+    };
+  });
+
+  // ── Lifecycle ────────────────────────────────────────────────────────
+
+  pi.on("session_start", async (_event, ctx) => {
+    dir = trailDir(getAgentDir(), ctx.cwd);
+    loadUserRules(ctx.cwd);
+    mode = "guard";
+    for (const entry of ctx.sessionManager.getBranch()) {
+      const e = entry as { type?: string; customType?: string; data?: unknown };
+      if (e.type === "custom" && e.customType === MODE_ENTRY && isRecord(e.data)) {
+        if (e.data.mode === "yolo" || e.data.mode === "guard") mode = e.data.mode;
+      }
+    }
+    updateFooter(ctx);
+  });
+
+  pi.on("session_tree", async (_event, ctx) => {
+    mode = "guard";
+    for (const entry of ctx.sessionManager.getBranch()) {
+      const e = entry as { type?: string; customType?: string; data?: unknown };
+      if (e.type === "custom" && e.customType === MODE_ENTRY && isRecord(e.data)) {
+        if (e.data.mode === "yolo" || e.data.mode === "guard") mode = e.data.mode;
+      }
+    }
+    updateFooter(ctx);
+  });
+
+  pi.on("session_shutdown", async (_event, ctx) => {
+    if (ctx.hasUI) ctx.ui.setStatus("yolo", undefined);
+  });
+
+  // ── Command ──────────────────────────────────────────────────────────
+
+  pi.registerCommand("yolo", {
+    description: "Toggle auto-approve: /yolo [on|off|status|trail|undo [n]]",
+    handler: async (args, ctx) => {
+      const [route, countRaw] = (args ?? "").trim().toLowerCase().split(/\s+/);
+      switch (route || "toggle") {
+        case "toggle":
+          setMode(ctx, mode === "yolo" ? "guard" : "yolo");
+          return;
+        case "on":
+          setMode(ctx, "yolo");
+          return;
+        case "off":
+          setMode(ctx, "guard");
+          return;
+        case "status": {
+          if (!ctx.hasUI) return;
+          const entries = readManifest(dir);
+          ctx.ui.notify(
+            [
+              `Mode: ${mode === "yolo" ? "⚡ YOLO (gate off)" : "🛡 guard"}`,
+              `User rules: ${userRules.length} (.pi/yolo.json)`,
+              `Trail: ${entries.length} entries — /yolo trail to view, /yolo undo [n] to restore`,
+            ].join("\n"),
+            "info",
+          );
+          return;
+        }
+        case "trail": {
+          if (!ctx.hasUI) return;
+          ctx.ui.notify(formatTrail(readManifest(dir), 20), "info");
+          return;
+        }
+        case "undo": {
+          if (!ctx.hasUI) return;
+          const count = Math.max(1, Math.min(50, Number.parseInt(countRaw ?? "1", 10) || 1));
+          const preview = readManifest(dir)
+            .filter((e) => e.type === "file")
+            .sort((a, b) => b.seq - a.seq)
+            .slice(0, count);
+          if (preview.length === 0) {
+            ctx.ui.notify("Nothing to undo — the trail has no file entries.", "warning");
+            return;
+          }
+          const ok = await ctx.ui.confirm(
+            "Undo file changes",
+            `Restore ${preview.length} file(s) to their pre-images?\n${preview.map((e) => e.target).join("\n")}`,
+          );
+          if (!ok) return;
+          const result = undo(dir, count);
+          ctx.ui.notify(
+            [
+              result.restored.length > 0 ? `Restored: ${result.restored.join(", ")}` : "",
+              result.deleted.length > 0 ? `Deleted (were new): ${result.deleted.join(", ")}` : "",
+              result.skipped.length > 0 ? `Skipped: ${result.skipped.join(", ")}` : "",
+            ]
+              .filter(Boolean)
+              .join("\n") || "Nothing changed.",
+            "info",
+          );
+          return;
+        }
+        default:
+          if (ctx.hasUI) ctx.ui.notify("Usage: /yolo [on|off|status|trail|undo [n]]", "warning");
+      }
+    },
+  });
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@pify/yolo",
+  "version": "0.1.0",
+  "description": "One toggle to auto-approve everything, with an undo trail: three-tier bash guard, file pre-images, fail-closed everywhere",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "pify",
+    "yolo",
+    "permissions",
+    "safety"
+  ],
+  "homepage": "https://github.com/pifydev/yolo#readme",
+  "bugs": {
+    "url": "https://github.com/pifydev/yolo/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pifydev/yolo.git"
+  },
+  "license": "MIT",
+  "author": "Pify maintainers",
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "files": [
+    "extensions",
+    "src",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/yolo.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "npm run typecheck && npm test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.4",
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/yolo/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: yolo
+description: Use when a bash command gets blocked or needs confirmation by the yolo guard, or when the user asks about undoing recent changes - explains the guard tiers, how to respond to denials, and the undo trail
+---
+
+# YOLO guard & undo trail
+
+This project has the `@pify/yolo` extension installed: a three-tier bash
+safety gate plus an always-on undo trail of file pre-images.
+
+## When your command is blocked or denied
+
+- A BLOCK (catastrophic tier: `rm -rf /`, mkfs, device writes…) is final —
+  never retry or rephrase to evade it; choose a fundamentally safer
+  approach and tell the user why.
+- An ASK denial may include the user's reason — treat it as a course
+  correction, not an obstacle. Adjust the plan accordingly.
+- Do not suggest the user enable yolo mode to bypass a block.
+
+## The undo trail
+
+- Every edit/write saves the file's pre-image first, in both modes. If the
+  user asks to revert recent changes, point them to `/yolo undo [n]`
+  (or restore specific files yourself from the visible trail).
+- Bash effects are logged but NOT undoable — before a risky-but-approved
+  command, mention what it will destroy if that's not obvious.
+
+## Modes
+
+- guard (default): catastrophic → block, destructive → confirm, rest runs.
+- yolo (`/yolo`): everything auto-approves; the trail keeps recording.
+  The user toggles this — never you.

package/src/rules.ts

@@ -0,0 +1,109 @@
+import type { RuleAction, RuleHit, UserRule } from "./types.ts";
+
+/**
+ * Three-tier bash safety rules (pi-yolo-seatbelt's model):
+ * BLOCK for catastrophic patterns, ASK for destructive ones, ALLOW the rest.
+ * User rules (wildcard, last-match-wins — zhushanwen semantics) can retune
+ * ASK/ALLOW, but catastrophic BLOCKs are a hard floor no rule can override.
+ * Fail-closed: anything that throws during evaluation blocks.
+ */
+
+interface BuiltinRule {
+  name: string;
+  action: Exclude<RuleAction, "allow">;
+  re: RegExp;
+}
+
+/** Catastrophic — never overridable. */
+const CATASTROPHIC: BuiltinRule[] = [
+  { name: "rm-rf-root", action: "block", re: /\brm\s+(-\w*[rR]\w*\s+)*(-\w*[rR]\w*)\s+(["']?)(\/|\/\*)\3(\s|$)/ },
+  { name: "rm-rf-home", action: "block", re: /\brm\s+-\w*[rR]\w*\s+(["']?)(~|\$HOME)\1(\/?)(\s|$)/ },
+  { name: "rm-rf-git", action: "block", re: /\brm\s+-\w*[rR]\w*[fF]?\w*\s+\S*\.git(\s|$|\/)/ },
+  { name: "mkfs", action: "block", re: /\bmkfs(\.\w+)?\b/ },
+  { name: "dd-device", action: "block", re: /\bdd\b[^|;&]*\bof=\/dev\// },
+  { name: "fork-bomb", action: "block", re: /:\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:/ },
+  { name: "chmod-777-root", action: "block", re: /\bchmod\s+(-\w+\s+)*777\s+\/(\s|$)/ },
+  { name: "write-device", action: "block", re: />\s*\/dev\/(sd[a-z]|nvme\d|disk\d)/ },
+];
+
+/** Destructive — confirmation required in guard mode; user rules may retune. */
+const DESTRUCTIVE: BuiltinRule[] = [
+  { name: "rm-rf", action: "ask", re: /\brm\s+-\w*([rR]\w*[fF]|[fF]\w*[rR])\w*\s/ },
+  { name: "rm-r", action: "ask", re: /\brm\s+-\w*[rR]\w*\s/ },
+  { name: "git-push-force", action: "ask", re: /\bgit\s+push\b[^|;&]*(\s--force(-with-lease)?\b|\s-f\b)/ },
+  { name: "git-reset-hard", action: "ask", re: /\bgit\s+reset\s+--hard\b/ },
+  { name: "git-clean-force", action: "ask", re: /\bgit\s+clean\b[^|;&]*\s-\w*[fdx]/ },
+  { name: "git-branch-delete", action: "ask", re: /\bgit\s+branch\s+(-D|--delete\s+--force)\b/ },
+  { name: "git-discard", action: "ask", re: /\bgit\s+(checkout|restore)\s+(--\s+)?\.(\s|$)/ },
+  { name: "pipe-to-shell", action: "ask", re: /\b(curl|wget)\b[^|;&]*\|\s*(sudo\s+)?(ba|z|fi)?sh\b/ },
+  { name: "find-delete", action: "ask", re: /\bfind\b[^|;&]*\s-delete\b/ },
+  { name: "chmod-777", action: "ask", re: /\bchmod\s+(-\w+\s+)*777\b/ },
+  { name: "truncate", action: "ask", re: /\btruncate\s+-s\s*0\b/ },
+  { name: "history-rewrite", action: "ask", re: /\bgit\s+(rebase|filter-branch|filter-repo)\b/ },
+];
+
+/** Convert a user wildcard pattern (`git push*`) to a regex. */
+export function wildcardToRegex(pattern: string): RegExp {
+  const escaped = pattern
+    .trim()
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    .replace(/\*/g, ".*")
+    .replace(/\?/g, ".");
+  return new RegExp(`^${escaped}$`, "i");
+}
+
+function normalize(command: string): string {
+  return command.replace(/\s+/g, " ").trim();
+}
+
+export function evaluateCommand(command: string, userRules: UserRule[] = []): RuleHit {
+  try {
+    const normalized = normalize(command);
+    if (!normalized) return { action: "allow", rule: "empty" };
+
+    // Hard floor: catastrophic patterns are non-negotiable.
+    for (const rule of CATASTROPHIC) {
+      if (rule.re.test(normalized)) return { action: "block", rule: rule.name };
+    }
+
+    // Builtin destructive verdict, then user rules last-match-wins on top.
+    let verdict: RuleHit = { action: "allow", rule: "default" };
+    for (const rule of DESTRUCTIVE) {
+      if (rule.re.test(normalized)) {
+        verdict = { action: rule.action, rule: rule.name };
+        break;
+      }
+    }
+    for (const rule of userRules) {
+      try {
+        if (wildcardToRegex(rule.pattern).test(normalized)) {
+          verdict = { action: rule.action, rule: `user:${rule.pattern}` };
+        }
+      } catch {
+        // invalid user pattern — ignore that rule
+      }
+    }
+    return verdict;
+  } catch {
+    // Fail-closed (zhushanwen's rule): evaluation errors never allow.
+    return { action: "block", rule: "fail-closed" };
+  }
+}
+
+export function parseUserRules(raw: unknown): UserRule[] {
+  if (typeof raw !== "object" || raw === null) return [];
+  const rules = (raw as { rules?: unknown }).rules;
+  if (!Array.isArray(rules)) return [];
+  const valid: UserRule[] = [];
+  for (const rule of rules) {
+    if (
+      typeof rule === "object" &&
+      rule !== null &&
+      typeof (rule as UserRule).pattern === "string" &&
+      ["allow", "ask", "block"].includes((rule as UserRule).action)
+    ) {
+      valid.push({ pattern: (rule as UserRule).pattern, action: (rule as UserRule).action });
+    }
+  }
+  return valid;
+}

package/src/trail.ts

@@ -0,0 +1,148 @@
+import { createHash } from "node:crypto";
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, join } from "node:path";
+import type { TrailEntry } from "./types.ts";
+
+/**
+ * The undo trail: before every edit/write the file's pre-image is saved, and
+ * risky bash commands are logged with their context. One rolling trail per
+ * project (keyed by cwd hash) under the agent dir — surviving sessions, so
+ * "undo what just happened" works even after a restart.
+ */
+
+export function trailDir(agentDir: string, cwd: string): string {
+  const key = createHash("sha256").update(cwd.toLowerCase()).digest("hex").slice(0, 12);
+  return join(agentDir, "yolo-trail", key);
+}
+
+function manifestPath(dir: string): string {
+  return join(dir, "manifest.jsonl");
+}
+
+export function readManifest(dir: string): TrailEntry[] {
+  try {
+    return readFileSync(manifestPath(dir), "utf8")
+      .split("\n")
+      .filter((l) => l.trim())
+      .map((l) => {
+        try {
+          return JSON.parse(l) as TrailEntry;
+        } catch {
+          return null;
+        }
+      })
+      .filter((e): e is TrailEntry => e !== null && typeof e.seq === "number");
+  } catch {
+    return [];
+  }
+}
+
+function nextSeq(dir: string): number {
+  const entries = readManifest(dir);
+  return entries.length === 0 ? 1 : Math.max(...entries.map((e) => e.seq)) + 1;
+}
+
+function append(dir: string, entry: TrailEntry): void {
+  mkdirSync(dir, { recursive: true });
+  appendFileSync(manifestPath(dir), `${JSON.stringify(entry)}\n`);
+}
+
+/** Save a file's pre-image before it is modified. Never throws. */
+export function recordPreImage(dir: string, filePath: string, now: number): TrailEntry | null {
+  try {
+    const seq = nextSeq(dir);
+    const existed = existsSync(filePath);
+    let saved: string | null = null;
+    if (existed) {
+      saved = `${seq}-${basename(filePath).slice(0, 80)}`;
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(join(dir, saved), readFileSync(filePath));
+    }
+    const entry: TrailEntry = { seq, timestamp: now, type: "file", target: filePath, saved, existed };
+    append(dir, entry);
+    return entry;
+  } catch {
+    return null;
+  }
+}
+
+/** Log a risky/mutating bash command. Never throws. */
+export function recordBash(
+  dir: string,
+  command: string,
+  cwd: string,
+  gitHead: string | null,
+  now: number,
+): void {
+  try {
+    append(dir, {
+      seq: nextSeq(dir),
+      timestamp: now,
+      type: "bash",
+      target: command.slice(0, 500),
+      saved: null,
+      existed: false,
+      cwd,
+      ...(gitHead ? { gitHead } : {}),
+    });
+  } catch {
+    // trail must never break the tool call
+  }
+}
+
+export interface UndoResult {
+  restored: string[];
+  deleted: string[];
+  skipped: string[];
+}
+
+/**
+ * Restore the newest `count` file pre-images (newest first). Files that did
+ * not exist before their change are deleted. Bash entries cannot be undone
+ * and are skipped. Returns what happened for reporting.
+ */
+export function undo(dir: string, count: number): UndoResult {
+  const result: UndoResult = { restored: [], deleted: [], skipped: [] };
+  const entries = readManifest(dir)
+    .filter((e) => e.type === "file")
+    .sort((a, b) => b.seq - a.seq)
+    .slice(0, count);
+
+  for (const entry of entries) {
+    try {
+      if (entry.existed && entry.saved) {
+        writeFileSync(entry.target, readFileSync(join(dir, entry.saved)));
+        result.restored.push(entry.target);
+      } else if (!entry.existed && existsSync(entry.target)) {
+        unlinkSync(entry.target);
+        result.deleted.push(entry.target);
+      } else {
+        result.skipped.push(entry.target);
+      }
+    } catch {
+      result.skipped.push(entry.target);
+    }
+  }
+  return result;
+}
+
+export function formatTrail(entries: TrailEntry[], limit: number): string {
+  if (entries.length === 0) return "Trail is empty.";
+  const recent = entries.slice(-limit).reverse();
+  return recent
+    .map((e) => {
+      const when = new Date(e.timestamp).toISOString().replace("T", " ").slice(0, 19);
+      if (e.type === "file") {
+        return `#${e.seq} ${when} file  ${e.target}${e.existed ? "" : " (new file)"}`;
+      }
+      return `#${e.seq} ${when} bash  ${e.target}${e.gitHead ? ` @${e.gitHead.slice(0, 8)}` : ""}`;
+    })
+    .join("\n");
+}

package/src/types.ts

@@ -0,0 +1,44 @@
+/**
+ * Local structural types for @pify/yolo.
+ * No imports from pi packages: src/ typechecks and runs standalone.
+ */
+
+export type Mode = "guard" | "yolo";
+
+export type RuleAction = "allow" | "ask" | "block";
+
+export interface RuleHit {
+  action: RuleAction;
+  /** Human label of the matching rule, e.g. "rm-rf-root". */
+  rule: string;
+}
+
+export interface UserRule {
+  pattern: string;
+  action: RuleAction;
+}
+
+export interface TrailEntry {
+  seq: number;
+  timestamp: number;
+  type: "file" | "bash";
+  /** file: absolute path edited/written. bash: the command. */
+  target: string;
+  /** file: saved pre-image filename (null when the file did not exist). */
+  saved: string | null;
+  /** file: whether the file existed before the change. */
+  existed: boolean;
+  cwd?: string;
+  gitHead?: string;
+}
+
+export interface BranchEntryLike {
+  type?: string;
+  customType?: string;
+  data?: unknown;
+  [key: string]: unknown;
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}