one-code-extension 0.4.1 → 0.6.0

package/skills/security-review/SKILL.md

@@ -1,16 +1,13 @@
 ---
 name: security-review
-description: >
-  Complete a security review of the pending changes on the current branch — a
-  focused, high-confidence hunt for exploitable vulnerabilities newly introduced
-  by the diff, reported as a severity-ranked markdown briefing.
+description: Complete a security review of the pending changes on the current branch
 ---
 
 You are a senior security engineer conducting a focused security review of the changes on this branch.
 
 ## Phase 0 — Gather the changes
 
-Run these commands and treat their combined output as the review scope:
+Run these commands and treat their combined output as the review scope (the "Do not use the bash tool" line further down is for the false-positive sub-tasks, not this step):
 
 - `git status`
 - `git diff --name-only origin/HEAD...` — files modified

package/skills/simplify/SKILL.md

@@ -3,7 +3,8 @@ name: simplify
 description: >
   Review the changed code for reuse, simplification, efficiency, and altitude
   cleanups, then apply the fixes. Quality only — it does not hunt for bugs; use
-  code-review for that.
+  /code-review for that.
+argument-hint: "[<target>]"
 ---
 
 `/simplify → 4 cleanup agents in parallel → apply the fixes`
@@ -55,10 +56,11 @@ alternative.
 
 ### Altitude
 
-Check that each change is implemented at the right depth, not as a fragile
-bandaid. Special cases layered on shared infrastructure are a sign the fix
-isn't deep enough — prefer generalizing the underlying mechanism over adding
-special cases.
+Check that each change fixes the root cause at the right depth rather than
+patching a symptom with a fragile bandaid. Special cases layered on shared
+infrastructure are a sign the fix isn't deep enough — prefer the simpler, more
+general change to the underlying mechanism over adding special cases, and name
+that change.
 
 ## Phase 2 — Apply the fixes
 

package/skills/workflow-authoring/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: workflow-authoring
+description: >
+  Reference for writing a workflow tool script (script API and gotchas,
+  resume, quality patterns, worked examples). Load before authoring a script
+  for a workflow the user already opted into; it does not itself authorize
+  running one.
+---
+
+# Workflow authoring reference
+
+A workflow structures work across many agents — to be comprehensive (decompose and cover in parallel), to be confident (independent perspectives and adversarial checks before committing), or to take on scale one context can't hold (migrations, audits, broad sweeps). The script is where you encode that structure: what fans out, what verifies, what synthesizes.
+
+When you do call it, the right move is often **hybrid**: scout inline first (list the files, find the channels, scope the diff) to discover the work-list, then call workflow to pipeline over it. You don't need to know the shape before the *task* — only before the *orchestration step*.
+
+Common single-phase workflows you can chain across turns:
+- **Understand** — parallel readers over relevant subsystems → structured map
+- **Design** — judge panel of N independent approaches → scored synthesis
+- **Review** — dimensions → find → adversarially verify (the review-changes example)
+- **Research** — multi-modal sweep → deep-read → synthesize
+- **Migrate** — discover sites → transform each (worktree isolation) → verify
+
+For larger work, run several in sequence — read each result before deciding the next phase. You stay in the loop; each workflow is one well-scoped fan-out.
+
+**Ultracode.** When a system-reminder confirms ultracode is on, that opt-in is standing: author and run a workflow for every substantive task by default. The goal is the most exhaustive, correct answer you can produce — token cost is not a constraint. For multi-phase work (understand → design → implement → review), that often means several workflows in sequence — one per phase — so you stay in the loop between them. The quality patterns below (adversarial verify, multi-modal sweep, completeness critic, loop-until-dry) are the tools; pick what fits the task. Lean toward orchestrating with workflows and adversarially verifying your findings — unless the work is trivial or already verified. Solo only on conversational turns or trivial mechanical edits. When a reminder says ultracode is off, revert to the opt-in rule in the workflow tool description.
+
+Pass the script inline via `script` — do not write it to a file first. Every invocation automatically persists its script to a file under the session directory and returns the path in the tool result. To iterate on a workflow, edit that file with write/edit and re-invoke workflow with `{scriptPath: "<path>"}` instead of resending the full script.
+
+Every script must begin with `export const meta = {...}`:
+  export const meta = {
+    name: 'find-flaky-tests',
+    description: 'Find flaky tests and propose fixes',   // one-line summary
+    phases: [                                            // one entry per phase() call
+      { title: 'Scan', detail: 'grep test logs for retries' },
+      { title: 'Fix', detail: 'one agent per flaky test' },
+    ],
+  }
+  // script body starts here — use agent()/parallel()/pipeline()/phase()/log()
+  phase('Scan')
+  const flaky = await agent('grep CI logs for retry markers', {schema: FLAKY_SCHEMA})
+  ...
+
+The `meta` object must be a PURE LITERAL — no variables, function calls, spreads, or template interpolation. Required fields: `name`, `description`. Optional: `whenToUse` (shown in the workflow list), `phases`. Use the SAME phase titles in meta.phases as in phase() calls — titles are matched exactly; a phase() call with no matching meta entry just gets its own progress group.
+
+Script body hooks:
+- agent(prompt: string, opts?: {label?: string, phase?: string, schema?: object, model?: string, allowExpensive?: boolean, effort?: string, isolation?: 'worktree', agentType?: string}): Promise<any> — spawn a subagent. Without schema, returns its final text as a string. With schema (a JSON Schema), the subagent is forced to call a structured_output tool and agent() returns the validated object — no parsing needed. Returns null if the subagent fails (filter with .filter(Boolean)); a mistake in the script itself throws. opts.label overrides the display label. opts.phase explicitly assigns this agent to a progress group (use this inside pipeline()/parallel() stages to avoid races on the global phase() state — same phase string → same group box). opts.model overrides the model for this agent call. Default to omitting it — the agent uses the effective /subagent default (the configured model, then an automatic smaller profile, then the session model). A model that costs more per token than the session model is rejected unless opts.allowExpensive is true; set it only when the user explicitly asked for that model. opts.effort overrides the reasoning effort for this agent call ('off' | 'minimal' | 'low' | 'medium' | 'high') — omit to inherit the session effort; use 'low' for cheap mechanical stages and higher tiers only for the hardest verify/judge stages. opts.isolation: 'worktree' runs the agent in a fresh git worktree — EXPENSIVE (~200-500ms setup + disk per agent), use ONLY when agents mutate files in parallel and would otherwise conflict; the worktree is auto-removed if unchanged. opts.agentType uses a custom subagent type (e.g. 'general-purpose', 'code-reviewer') instead of the default workflow subagent — resolved from the same registry as the Agent tool; composes with schema (the custom agent's system prompt gets a structured_output instruction appended).
+- pipeline(items, stage1, stage2, ...): Promise<any[]> — run each item through all stages independently, NO barrier between stages. Item A can be in stage 3 while item B is still in stage 1. This is the DEFAULT for multi-stage work. Wall-clock = slowest single-item chain, not sum-of-slowest-per-stage. Every stage callback receives (prevResult, originalItem, index) — use originalItem/index in later stages to label work without threading context through stage 1's return value. A stage that throws drops that item to `null` and skips its remaining stages.
+- parallel(thunks: Array<() => Promise<any>>): Promise<any[]> — run tasks concurrently. This is a BARRIER: awaits all thunks before returning. A thunk that throws (or whose agent errors) resolves to `null` in the result array — the call itself never rejects, so `.filter(Boolean)` before using the results. Use ONLY when you genuinely need all results together.
+- log(message: string): void — emit a progress message to the user (shown as a narrator line above the progress tree)
+- phase(title: string): void — start a new phase; subsequent agent() calls are grouped under this title in the progress display
+- args: any — the value passed as the workflow tool's `args` input, verbatim (undefined if not provided). Pass arrays/objects as actual JSON values in the tool call, NOT as a JSON-encoded string — `args: ["a.ts", "b.ts"]`, not `args: "[\"a.ts\", ...]"` (a stringified list reaches the script as one string, so `args.filter`/`args.map` throw). Use this to parameterize named workflows — e.g. pass a research question, target path, or config object directly instead of via a side-channel file.
+- budget: {total: number|null, spent(): number, remaining(): number} — the run's output-token target from the workflow tool's `tokenBudget` input. `budget.total` is null if no target was set. `budget.spent()` returns output tokens spent by this run's agents and its nested workflows — the pool is shared with them, not with the main conversation. `budget.remaining()` returns `max(0, total - spent())`, or `Infinity` if no target. Once `spent()` reaches `total`, new and queued `agent()` calls throw before starting; agents already running may finish above the target. Use for dynamic loops: `while (budget.total && budget.remaining() > 50_000) { ... }`, or static scaling: `const FLEET = budget.total ? Math.floor(budget.total / 100_000) : 5`.
+- workflow(nameOrRef: string | {scriptPath: string}, args?: any): Promise<any> — run another workflow inline as a sub-step and return whatever it returns. Pass a name to invoke a saved workflow (same registry as {name: "..."}), or {scriptPath} to run a script file you wrote earlier. The child shares this run's concurrency cap, agent counter, abort signal, and token budget — its agents appear under a "▸ name" group in /workflows and its tokens count toward budget.spent(). The args param becomes the child's `args` global. Nesting is one level only: workflow() inside a child throws. Throws on unknown name / unreadable scriptPath / child syntax error; catch to handle gracefully.
+
+Subagents are told their final text IS the return value (not a human-facing message), so they return raw data. For structured output, use the schema option — validation happens at the tool-call layer so the model retries on mismatch.
+Schemas need {type: 'object', properties: {...}} at root; any other schema throws at agent().
+
+Workflow agents get the session's connected MCP tools directly. Caveat: interactively-authenticated MCP servers may be absent in headless/cron runs.
+
+Subagents get the same CLAUDE.md files injected at start that you did (except built-in agent types that omit them, such as Explore and Plan) — don't tell them to re-read those or paste their rules into the prompt; name the specific rule a stage needs, if any.
+
+Scripts are plain JavaScript, NOT TypeScript — type annotations (`: string[]`), interfaces, and generics fail to parse. The script body runs in an async context — use await directly. Standard JS built-ins (JSON, Math, Array, etc.) are available — EXCEPT `Date.now()`/`Math.random()`/argless `new Date()`, which throw (they would break resume); pass timestamps in via `args`, stamp results after the workflow returns, and for randomness vary the agent prompt/label by index. No filesystem or Node.js API access.
+
+DEFAULT TO pipeline(). Only reach for a barrier (parallel between stages) when you genuinely need ALL prior-stage results together.
+
+A barrier is correct ONLY when stage N needs cross-item context from all of stage N-1:
+- Dedup/merge across the full result set before expensive downstream work
+- Early-exit if the total count is zero ("0 bugs found → skip verification entirely")
+- Stage N's prompt references "the other findings" for comparison
+
+A barrier is NOT justified by:
+- "I need to flatten/map/filter first" — do it inside a pipeline stage: pipeline(items, stageA, r => transform([r]).flat(), stageB)
+- "The stages are conceptually separate" — that's what pipeline() models. Separate stages ≠ synchronized stages.
+- "It's cleaner code" — barrier latency is real. If 5 finders run and the slowest takes 3× the fastest, a barrier wastes 2/3 of the fast finders' idle time.
+
+Smell test: if you wrote
+  const a = await parallel(...)
+  const b = transform(a)        // flatten, map, filter — no cross-item dependency
+  const c = await parallel(b.map(...))
+that middle transform doesn't need the barrier. Rewrite as a pipeline with the transform inside a stage. When in doubt: pipeline.
+
+Concurrent agent() calls are capped at min(16, available CPUs - 2) per workflow — excess calls queue and run as slots free up. You can still pass 100 items to parallel()/pipeline() and they all complete; only ~10 run at any moment. Total agent count across a workflow's lifetime is capped at 1000 — a runaway-loop backstop set far above any real workflow. A single parallel()/pipeline() call accepts at most 4096 items; passing more is an explicit error, not a silent truncation.
+
+When a barrier IS correct — dedup across all findings before expensive verification:
+  const all = await parallel(DIMENSIONS.map(d => () => agent(d.prompt, {schema: FINDINGS_SCHEMA})))
+  const deduped = dedupeByFileAndLine(all.filter(Boolean).flatMap(r => r.findings))  // <-- genuinely needs ALL at once
+  const verified = await parallel(deduped.map(f => () => agent(verifyPrompt(f), {schema: VERDICT_SCHEMA})))
+
+Loop-until-count pattern — accumulate to a target:
+  const bugs = []
+  while (bugs.length < 10) {
+    const result = await agent("Find bugs in this codebase.", {schema: BUGS_SCHEMA})
+    bugs.push(...result.bugs)
+    log(`${bugs.length}/10 found`)
+  }
+
+Loop-until-budget pattern — scale depth to the run's `tokenBudget`. Guard on budget.total: with no target set, remaining() is Infinity and the loop would run straight to the 1000-agent cap.
+  const bugs = []
+  while (budget.total && budget.remaining() > 50_000) {
+    const result = await agent("Find bugs in this codebase.", {schema: BUGS_SCHEMA})
+    bugs.push(...result.bugs)
+    log(`${bugs.length} found, ${Math.round(budget.remaining()/1000)}k remaining`)
+  }
+
+Composing patterns — exhaustive review (find → dedup vs seen → diverse-lens panel → loop-until-dry):
+  const seen = new Set(), confirmed = []
+  let dry = 0
+  while (dry < 2) {                                              // loop-until-dry
+    const found = (await parallel(FINDERS.map(f => () =>          // barrier: collect all finders this round
+      agent(f.prompt, {phase: 'Find', schema: BUGS})))).filter(Boolean).flatMap(r => r.bugs)
+    const fresh = found.filter(b => !seen.has(key(b)))           // dedup vs ALL seen — plain code, not an agent
+    if (!fresh.length) { dry++; continue }
+    dry = 0; fresh.forEach(b => seen.add(key(b)))
+    const judged = await parallel(fresh.map(b => () =>           // every fresh bug judged concurrently...
+      parallel(['correctness','security','repro'].map(lens => () =>   // ...each by 3 distinct lenses
+        agent(`Judge "${b.desc}" via the ${lens} lens — real?`, {phase: 'Verify', schema: VERDICT})))
+        .then(vs => ({ b, real: vs.filter(Boolean).filter(v => v.real).length >= 2 }))))
+    confirmed.push(...judged.filter(v => v.real).map(v => v.b))
+  }
+  return confirmed
+  // dedup vs `seen`, NOT `confirmed` — else judge-rejected findings reappear every round and it never converges.
+
+Quality patterns — common shapes; pick by task and compose freely:
+- Adversarial verify: spawn N independent skeptics per finding, each prompted to REFUTE. Kill if ≥majority refute. Prevents plausible-but-wrong findings from surviving.
+    const votes = await parallel(Array.from({length: 3}, () => () =>
+      agent(`Try to refute: ${claim}. Default to refuted=true if uncertain.`, {schema: VERDICT})))
+    const survives = votes.filter(Boolean).filter(v => !v.refuted).length >= 2
+- Perspective-diverse verify: when a finding can fail in more than one way, give each verifier a distinct lens (correctness, security, perf, does-it-reproduce) instead of N identical refuters — diversity catches failure modes redundancy can't.
+- Judge panel: generate N independent attempts from different angles (e.g. MVP-first, risk-first, user-first), score with parallel judges, synthesize from the winner while grafting the best ideas from runners-up. Beats one-attempt-iterated when the solution space is wide.
+- Loop-until-dry: for unknown-size discovery (bugs, issues, edge cases), keep spawning finders until K consecutive rounds return nothing new. Simple counters (while count < N) miss the tail.
+- Multi-modal sweep: parallel agents each searching a different way (by-container, by-content, by-entity, by-time). Each is blind to what the others surface; useful when one search angle won't find everything.
+- Completeness critic: a final agent that asks "what's missing — modality not run, claim unverified, source unread?" What it finds becomes the next round of work.
+- No silent caps: if a workflow bounds coverage (top-N, no-retry, sampling), `log()` what was dropped — silent truncation reads as "covered everything" when it didn't.
+
+Scale to what the user asked for. "find any bugs" → a few finders, single-vote verify. "thoroughly audit this" or "be comprehensive" → larger finder pool, 3–5 vote adversarial pass, synthesis stage. When unsure, lean toward thoroughness for research/review/audit requests and toward brevity for quick checks.
+
+These patterns aren't exhaustive — compose novel harnesses when the task calls for it (tournament brackets, self-repair loops, staged escalation, whatever fits).
+
+Use this tool for multi-step orchestration where control flow should be deterministic (loops, conditionals, fan-out) rather than model-driven.
+
+## Resume
+
+The tool result includes a runId. To resume after a pause, kill, or script edit, relaunch with workflow({scriptPath, resumeFromRunId}) — the longest unchanged prefix of agent() calls returns cached results instantly; the first edited/new call and everything after it runs live. Same script + same args → 100% cache hit. A live run must be stopped first (/workflows stop <runId>), and a background run does not survive a session switch or /reload — resume it instead. Before diagnosing why a completed workflow returned an empty or unexpected result, read <session dir>/workflows/<runId>/journal.jsonl (next to the run's script.js) — it records each agent's actual return value; do not assume cached results are non-empty. Date.now()/Math.random()/new Date() are unavailable in scripts (they would break this) — stamp results after the workflow returns, or pass timestamps via args.

package/themes/onecode-light.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
+  "$schema": "https://pi.dev/schemas/theme.schema.json",
   "name": "onecode-light",
   "vars": {
     "clay": "#c05f38",

package/themes/onecode.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
+  "$schema": "https://pi.dev/schemas/theme.schema.json",
   "name": "onecode",
   "vars": {
     "clay": "#d97757",

package/types/app.d.ts

@@ -8,6 +8,7 @@ declare module "*/lib/update-check.mjs" {
 	export const EXTENSION_PACKAGE: string;
 	export const HOMEBREW_FORMULA: string;
 	export const UPGRADE_COMMANDS: { npm: string; brew: string; "pi-package": string };
+	export function upgradeCommandFor(install: "app" | "pi-package", env?: Record<string, string | undefined>): string;
 	export function registryPackumentUrl(name: string): string;
 	export const CHECK_INTERVAL_MS: number;
 	export const HOMEBREW_MIN_RELEASE_AGE_MS: number;
@@ -26,3 +27,60 @@ declare module "*/lib/update-check.mjs" {
 		minReleaseAgeMs?: number;
 	}): (pi: unknown) => void;
 }
+
+/** Types for the plain-JS launcher-environment module (extensions/lib/app-launch.mjs). */
+declare module "*/app-launch.mjs" {
+	export const APP_AGENT_DIR_VAR: string;
+	export const LAUNCHER_ENV_VAR: string;
+	export const LAUNCHER_VARS: readonly string[];
+	export function appAgentDir(env?: Record<string, string | undefined>, home?: string): string;
+	export function installMethodFor(binRealPath: string | undefined): "brew" | "npm";
+	export function applyLauncherEnv(
+		env: Record<string, string | undefined>,
+		options: { home?: string; appVersion: string; installMethod: "brew" | "npm" },
+	): string;
+	export function childProcessEnv(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): NodeJS.ProcessEnv;
+}
+
+/** Types for the plain-JS replaced-built-ins module (extensions/lib/replaced-builtins.mjs). */
+declare module "*/replaced-builtins.mjs" {
+	export interface ReplacedBuiltin {
+		name: string;
+		ours: string;
+	}
+	export interface BuiltinLeftOn extends ReplacedBuiltin {
+		/** Which setting keeps it on: the project's `+builtin:<name>`, else the user's (no `-` entry). */
+		scope: "user" | "project";
+	}
+	export const REPLACED_BUILTINS: readonly ReplacedBuiltin[];
+	export const BUILTIN_EXTENSIONS_PI: string;
+	/** How a `!` override entry's glob is matched: pi's minimatch, or the module's port. */
+	export type GlobMatcher = (pattern: string, path: string) => boolean;
+	export const globMatches: GlobMatcher;
+	export function builtinEnabled(name: string, userExtensions: unknown, projectExtensions: unknown, matches?: GlobMatcher): boolean;
+	export function builtinsLeftOn(userExtensions: unknown, projectExtensions: unknown, matches?: GlobMatcher): BuiltinLeftOn[];
+	export function withReplacedBuiltinsOff(userExtensions: unknown): { extensions: unknown[]; changed: boolean };
+	export function replacedBuiltinsNotice(left: readonly BuiltinLeftOn[], configCommand?: string): string | undefined;
+	export function replacedBuiltinsFix(left: readonly BuiltinLeftOn[], paths: { user: string; project: string }, configCommand?: string): string;
+	export function withBuiltinsTurnedOff(userExtensions: unknown, names: readonly string[]): unknown[];
+	export const TURN_OFF_YES: string;
+	export const TURN_OFF_NO: string;
+	export function turnOffPrompt(left: readonly BuiltinLeftOn[], settingsPath: string, configCommand?: string): string;
+}
+
+/** Types for the plain-JS compaction keep-window module (extensions/lib/compaction-keep.mjs). */
+declare module "*/compaction-keep.mjs" {
+	export interface CompactionKeepView {
+		value: number;
+		source: "project" | "user" | "default";
+		/** The `provider/id` whose `compaction.modelOverrides` entry supplied the value. */
+		model?: string;
+	}
+	export const ONE_CODE_KEEP_RECENT_TOKENS: number;
+	export function withCompactionKeepBackfilled<S extends Record<string, unknown>>(settings: S): { settings: S; changed: boolean };
+	export function compactionKeepView(userSettings: unknown, projectSettings: unknown, modelKey?: string): CompactionKeepView;
+	export const KEEP_YES: string;
+	export const KEEP_NO: string;
+	export function keepWindowPrompt(settingsPath: string): string;
+	export function keepWindowFix(settingsPath: string, model?: string): string;
+}

package/types/community-packages.d.ts

@@ -5,7 +5,7 @@
  * `pi-web-search/src/*` subpath here, while jiti resolves the real module at
  * runtime.
  *
- * Only the exports `extensions/web/index.ts` uses are declared. Loosely typed
+ * Only the exports the web extension uses are declared. Loosely typed
  * on purpose (`any` for pi-web-search's own result/context shapes): the goal is
  * to keep the package out of our typecheck, not to re-type it.
  */
@@ -18,6 +18,31 @@ declare module "pi-web-search/src/index.ts" {
 }
 
 declare module "pi-web-search/src/api.ts" {
+	import type { AgentToolUpdateCallback, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+	export interface StreamResult {
+		text: string;
+		sources?: Array<{ title: string; url: string }>;
+		providerKind?: string;
+		nativeSearchUsed?: boolean;
+		nativeSearchEvents?: string[];
+		nativeSearchCalls?: unknown[];
+		searchQueries?: string[];
+		searchResults?: Array<{ title?: string; url?: string; [key: string]: unknown }>;
+		citations?: unknown[];
+		groundingMetadata?: any;
+	}
+
+	export function getConfig(model: { provider: string; api?: string }): { kind: ReturnType<typeof getProviderKind>; searchTool?: string };
+	export function callApiStream(
+		ctx: ExtensionContext,
+		model: { provider: string; id: string },
+		body: unknown,
+		onUpdate?: AgentToolUpdateCallback,
+		signal?: AbortSignal,
+	): Promise<StreamResult>;
+	export function applyCitations(text: string, groundingMetadata: unknown): { text: string; sources: Array<{ title: string; url: string }> };
+
 	// The real api.ts (loaded by jiti at runtime) maps a Google provider — by
 	// `provider` or `api` field — to "google", the only kind that supports
 	// url_context. Declared loosely so the extension can call it with a model

package/extensions/auto-mode/recoverability.ts

@@ -1,229 +0,0 @@
-/**
- * Git-recoverability check for the containment pre-gate (pure core + thin git
- * runner).
- *
- * ## Why this exists
- *
- * Claude Code's auto mode trusts the whole project directory as the agent's
- * sandbox: an in-project `rm` or `git reset --hard` is auto-approved with no
- * classifier call, even when it destroys uncommitted or untracked work git can
- * never restore (confirmed live — see docs/decisions/auto-mode.md). One Code
- * keeps the cheap in-project fast path but refuses that specific risk: an
- * in-project destructive action is auto-approved **only when git can put the
- * bytes back** — the target is tracked and clean (whole-tree ops: the entire
- * tree is clean). Anything else — untracked, dirty, not a git repo, or a git
- * query we could not run — is `unknown`/`unrecoverable`, and the pre-gate
- * escalates it to the classifier rather than destroying it silently.
- *
- * ## Contract
- *
- * Like the shell pre-gate, this may only ever *widen* what is provably safe.
- * `recoverable` is returned only on positive proof (git says tracked+clean);
- * every ambiguity — an error, a path git does not know, a non-repo — resolves to
- * `unknown`, which the caller treats exactly like `unrecoverable`: classify.
- * Being wrong toward `unknown` costs a classifier call; being wrong toward
- * `recoverable` destroys the user's work, so uncertainty never lands there.
- */
-
-import { execFileSync } from "node:child_process";
-import { existsSync, lstatSync, readdirSync } from "node:fs";
-import { basename, join, sep } from "node:path";
-
-export type Recoverability = "recoverable" | "unrecoverable" | "unknown";
-
-export interface RecoverabilityResult {
-	verdict: Recoverability;
-	/** One line naming why, for the decision log — never echoes file contents. */
-	reason: string;
-}
-
-/** What git reports about one destruction target. */
-export interface TargetState {
-	/** Original token, for the reason string (never an expanded value). */
-	token: string;
-	/** `git ls-files` matched it — git has a committed/indexed copy to restore from. */
-	tracked: boolean;
-	/** `git status --porcelain --ignored` reported anything for it — uncommitted, untracked, or ignored content that a restore would not bring back. */
-	dirty: boolean;
-	/** True when the target is a directory (its reason names the content git would not restore). */
-	directory?: boolean;
-}
-
-/**
- * Judge a set of explicit destruction targets (`rm a b`, `truncate f`). Every
- * target must be independently recoverable; the first that is not decides the
- * whole action, since one command destroys them all.
- */
-export function judgeTargets(targets: TargetState[]): RecoverabilityResult {
-	if (targets.length === 0) return { verdict: "unknown", reason: "no destruction target could be identified" };
-	for (const target of targets) {
-		if (!target.tracked) {
-			return { verdict: "unrecoverable", reason: `${target.token} is not tracked by git, so deleting it is not reversible` };
-		}
-		if (target.dirty) {
-			return {
-				verdict: "unrecoverable",
-				reason: target.directory
-					? `${target.token} is a directory holding uncommitted, untracked, or ignored files that a git restore would not bring back`
-					: `${target.token} has uncommitted changes that a git restore would not bring back`,
-			};
-		}
-	}
-	return { verdict: "recoverable", reason: "every target is tracked by git and clean, so git can restore it" };
-}
-
-/**
- * Judge a whole-tree destructive op. Recoverable only when the entire working
- * tree is clean: a clean tree's state is committed (reachable again via
- * reflog/checkout), while any modified, staged, or untracked entry is content the
- * op would erase for good. This judge is generic over any tree-wide reset, but at
- * present only `git reset --hard` is routed here — `git clean -fd` / `git checkout
- * .` are escalated directly by shell-analysis (isWholeTreeGitReset), so they reach
- * the classifier rather than this fast path.
- */
-export function judgeWholeTree(isRepo: boolean, statusPorcelain: string): RecoverabilityResult {
-	if (!isRepo) return { verdict: "unrecoverable", reason: "not a git repository, so a tree-wide reset cannot be undone" };
-	return statusPorcelain.trim().length === 0
-		? { verdict: "recoverable", reason: "the working tree is clean, so git can restore it" }
-		: { verdict: "unrecoverable", reason: "the working tree has uncommitted or untracked changes a reset would destroy" };
-}
-
-/** Combine several sub-verdicts: the whole action is only as recoverable as its least-recoverable part. */
-export function combine(results: RecoverabilityResult[]): RecoverabilityResult {
-	if (results.length === 0) return { verdict: "unknown", reason: "nothing to check" };
-	const worst = results.find((r) => r.verdict === "unrecoverable") ?? results.find((r) => r.verdict === "unknown");
-	return worst ?? results[0];
-}
-
-/** The path is `.git`, sits inside a `.git`, or is a directory with a `.git` entry (repo root, nested repo, worktree). */
-function isOrHoldsGitDir(path: string): boolean {
-	if (basename(path) === ".git") return true;
-	if (path.split(sep).includes(".git")) return true;
-	try {
-		return lstatSync(path).isDirectory() && existsSync(join(path, ".git"));
-	} catch {
-		return false;
-	}
-}
-
-/**
- * Whether any entry named `.git` exists anywhere under `dir`. Bounded by
- * `budget` directory entries; returns undefined when the budget runs out (the
- * caller escalates). Symlinks are not followed.
- */
-function holdsNestedGitDir(dir: string, budget: number): boolean | undefined {
-	const stack = [dir];
-	let seen = 0;
-	while (stack.length > 0) {
-		const current = stack.pop() as string;
-		let entries;
-		try {
-			entries = readdirSync(current, { withFileTypes: true });
-		} catch {
-			continue;
-		}
-		for (const entry of entries) {
-			if (++seen > budget) return undefined;
-			if (entry.name === ".git") return true;
-			if (entry.isDirectory()) stack.push(join(current, entry.name));
-		}
-	}
-	return false;
-}
-
-/** A thin, defensive git call: any failure (not a repo, git missing, timeout) becomes `undefined`. */
-function git(cwd: string, args: string[]): { ok: boolean; stdout: string } | undefined {
-	try {
-		const stdout = execFileSync("git", args, { cwd, encoding: "utf8", timeout: 5_000, stdio: ["ignore", "pipe", "ignore"] });
-		return { ok: true, stdout };
-	} catch (error) {
-		// A non-zero exit still carries stdout (e.g. ls-files --error-unmatch), which
-		// the caller may want; distinguish "ran and said no" from "could not run".
-		const status = (error as { status?: number }).status;
-		if (typeof status === "number") return { ok: false, stdout: String((error as { stdout?: unknown }).stdout ?? "") };
-		return undefined; // git not found / timed out / killed — genuinely unknown
-	}
-}
-
-export interface Destruction {
-	/** Resolved absolute paths the command destroys (already proven in-project by the pre-gate). */
-	targets: string[];
-	/** True for reset --hard / clean / checkout . — the target is the whole working tree, not named paths. */
-	wholeTree: boolean;
-}
-
-/**
- * Run the git queries and judge. `cwd` is the command's effective directory.
- * Returns `unknown` on any git failure so the caller escalates rather than
- * trusting an answer we could not compute.
- */
-export function checkRecoverability(cwd: string, destruction: Destruction): RecoverabilityResult {
-	const repoProbe = git(cwd, ["rev-parse", "--is-inside-work-tree"]);
-	const isRepo = repoProbe?.ok === true && repoProbe.stdout.trim() === "true";
-
-	if (destruction.wholeTree) {
-		if (!isRepo) return judgeWholeTree(false, "");
-		const status = git(cwd, ["status", "--porcelain"]);
-		if (!status) return { verdict: "unknown", reason: "could not read git status to judge a tree-wide reset" };
-		return judgeWholeTree(true, status.stdout);
-	}
-
-	if (destruction.targets.length === 0) return { verdict: "unknown", reason: "no destruction target could be identified" };
-	if (!isRepo) return { verdict: "unrecoverable", reason: "not a git repository, so deletion is not reversible" };
-
-	const states: TargetState[] = [];
-	for (const path of destruction.targets) {
-		// A target that does not exist has nothing to lose: deleting it is a no-op,
-		// truncating it creates a fresh empty file. Either way there is no
-		// pre-existing content a restore would need to bring back. Use lstat, not
-		// existsSync: existsSync follows a symlink to its target, so a tracked-but-
-		// dirty *broken* symlink (its target missing) would read as "nothing to
-		// lose" and be wrongly cleared as recoverable — the link entry itself is
-		// real, uncommitted content, so it must be queried against git.
-		let entryExists = true;
-		try {
-			lstatSync(path);
-		} catch {
-			entryExists = false;
-		}
-		if (!entryExists) continue;
-		// The repository itself is never recoverable from itself: `rm -rf .` at the
-		// root passes every tracked/clean test (git ls-files matches any dir with
-		// tracked files) yet deletes `.git`. Same for a path inside `.git` and for a
-		// directory holding a nested repository or worktree link.
-		if (isOrHoldsGitDir(path)) {
-			return { verdict: "unrecoverable", reason: `${path} is or contains a .git directory, so deleting it destroys the history that would restore it` };
-		}
-		const isDirectory = (() => {
-			try {
-				return lstatSync(path).isDirectory();
-			} catch {
-				return false;
-			}
-		})();
-		// `--ignored`: porcelain omits ignored files by default, so a directory of
-		// build output or a `.env` read as "clean" while `rm -rf` erased it for good.
-		const tracked = git(cwd, ["ls-files", "--error-unmatch", "--", path]);
-		const status = git(cwd, ["status", "--porcelain", "--ignored", "--", path]);
-		if (tracked === undefined || status === undefined) {
-			return { verdict: "unknown", reason: "could not query git for a deletion target" };
-		}
-		const dirty = status.stdout.trim().length > 0;
-		// A clean, tracked directory can still hold a nested repository deeper down
-		// (git status never lists a `.git`, so it reads as clean). Only scanned once
-		// the cheap checks passed; a huge tree exhausts the budget and stays unknown.
-		if (isDirectory && tracked.ok && !dirty) {
-			const nested = holdsNestedGitDir(path, 5_000);
-			if (nested === undefined) {
-				return { verdict: "unknown", reason: `${path} is too large to scan for nested repositories` };
-			}
-			if (nested) {
-				return { verdict: "unrecoverable", reason: `${path} contains a nested .git directory whose history git cannot restore` };
-			}
-		}
-		states.push({ token: path, tracked: tracked.ok, dirty, directory: isDirectory });
-	}
-	// Every target was a non-existent path (pure creation / no-op) — nothing to lose.
-	if (states.length === 0) return { verdict: "recoverable", reason: "no existing content would be destroyed" };
-	return judgeTargets(states);
-}