pi-warden 0.28.4 → 0.35.0

package/dist/holds.js

@@ -26,10 +26,11 @@ export class HoldLedger {
     /** One inspected call. `outcome` is set at once when the confirm dialog decided; a steer-mode hold starts pending. */
     record(verdict, options) {
         const at = options.at ?? Date.now();
+        const { summary } = verdict;
         const record = {
             id: this.nextId++,
             at,
-            tool: verdict.summary.tool,
+            tool: summary.tool,
             level: verdict.level,
             source: verdict.source,
             mode: options.mode,
@@ -39,6 +40,11 @@ export class HoldLedger {
             planChars: verdict.plan?.length ?? 0,
             outcome: options.outcome ?? "pending",
         };
+        // Call excerpt for auditing: tool + path only (commands never reach the log).
+        if (summary.path)
+            record.callExcerpt = `${summary.tool} ${summary.path}`;
+        else if (summary.tool)
+            record.callExcerpt = summary.tool;
         const scores = scoresOf(verdict);
         if (scores)
             record.scores = scores;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export { evaluateAction, describeAction, describePlan, matchPatterns, isReadOnlyCommand, stripDataText, buildRequest, formatVerdict, formatVerdictTokens, steerReason, intentSteer, offTaskSteer, steerFingerprint, SteerRepeatWindow, questions, intentQuestion, visibleQuestion, slopQuestions, approvalQuestion, securityQuestion, regretQuestions } from "./guard.js";
-export type { ActionInput, ActionSummary, EvaluateOptions, Judge, Judgment, SlopJudgment, SlopSymptom, Level, PatternHit, PreviousAction, ScannedCommand, ScopeLabel, Severity, Verdict } from "./guard.js";
+export { evaluateAction, describeAction, describePlan, matchPatterns, isReadOnlyCommand, stripDataText, buildRequest, formatVerdict, formatVerdictTokens, steerReason, intentSteer, offTaskSteer, shouldProceedMessage, steerFingerprint, SteerRepeatWindow, questions, intentQuestion, visibleQuestion, slopQuestions, approvalQuestion, securityQuestion, regretQuestions, authorize, isNegated, scopeMatches, isAuthEligible, patternHitsToViolations, escalateBlastRadius, escalateRulesViolation, aggregateLevel, removeAuthorized, scopeFromInput, matchPathRules, parseViolationJudgments } from "./guard.js";
+export type { ActionInput, ActionSummary, EvaluateOptions, Judge, Judgment, SlopJudgment, SlopSymptom, Level, PatternHit, PreviousAction, ScannedCommand, ScopeLabel, Severity, Verdict, Violation, ViolationSource, ViolationScope, Authorization, EscalatedViolation, ViolationJudgmentAnswer } from "./guard.js";
 export { SLOP_SYMPTOMS, SLOP_LABELS } from "./guard.js";
 export { ActionGuard } from "./action-guard.js";
 export type { Conversation, InspectOptions, ToolCallRef } from "./action-guard.js";
@@ -36,7 +36,13 @@ export { renderTemplate, actionTokens, stuckTokens, doneTokens, proseTokens, run
 export type { WidgetConfig, WidgetPlacement, WidgetBarMode, Tokens } from "./widget.js";
 export { Trace, actionDetails, stuckDetails, doneDetails, proseDetails, runawayDetails, rulesDetails } from "./trace.js";
 export type { TraceEntry, GuardName } from "./trace.js";
-export { parseRules, condense, globToRegExp, matchGlob, projectPath, RuleStore, rulesFor, describeRuleSet, describeTarget, buildRulesRequest, ruleQuestion, evaluateRules, skipReason, rulesSteer, formatRules, pathNotes, pathNoteSteer, RulesGuard, RULES_FILE, FALLBACK_FILES, MAX_RULES, AGGREGATE_QUESTION, LOCATOR_QUESTION } from "./rules.js";
+export { parseRules, condense, isRuleShaped, globToRegExp, matchGlob, projectPath, RuleStore, rulesFor, describeRuleSet, describeTarget, buildRulesRequest, ruleQuestion, evaluateRules, skipReason, rulesSteer, formatRules, pathNotes, pathNoteSteer, RulesGuard, RULES_FILE, FALLBACK_FILES, MAX_RULES, AGGREGATE_QUESTION, LOCATOR_QUESTION } from "./rules.js";
 export type { Rule, RuleSet, RuleOutcome, RuleScore, RuleFinding, RulesVerdict, RulesOptions, RulesTarget, EditView, PathNote, RulesCallRef } from "./rules.js";
+export { resolveRulesFile, extractRules, checkPiWardenMissing } from "./rules-file.js";
+export type { ResolvedRulesFile } from "./rules-file.js";
+export { writeStarterRules, generateStarterRules, detectProjectType, buildProjectContext, buildInitPrompt } from "./init.js";
+export type { InitResult } from "./init.js";
 export { initSchema, recordHold, recordOutcome as recordHoldOutcome, querySmartHistory, calculateSmartConfidence, shouldSkipHold, analyzeThresholds, analyzePatterns, generateRecommendations, analyzeSteerEffectivenessReport } from "./learning.js";
 export type { HoldRecord, HoldScores, HoldLevel, HoldOutcome, HoldContext, SmartHistory, ConfidenceResult, SkipResult, ThresholdAdjustment, PatternInsight, ContextRecommendation, SteerEffectivenessReport } from "./learning.js";
+export { buildAuditPrompt, snapshotReport, reportOutcome } from "./audit.js";
+export type { ReportSnapshot } from "./audit.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-export { evaluateAction, describeAction, describePlan, matchPatterns, isReadOnlyCommand, stripDataText, buildRequest, formatVerdict, formatVerdictTokens, steerReason, intentSteer, offTaskSteer, steerFingerprint, SteerRepeatWindow, questions, intentQuestion, visibleQuestion, slopQuestions, approvalQuestion, securityQuestion, regretQuestions } from "./guard.js";
+export { evaluateAction, describeAction, describePlan, matchPatterns, isReadOnlyCommand, stripDataText, buildRequest, formatVerdict, formatVerdictTokens, steerReason, intentSteer, offTaskSteer, shouldProceedMessage, steerFingerprint, SteerRepeatWindow, questions, intentQuestion, visibleQuestion, slopQuestions, approvalQuestion, securityQuestion, regretQuestions, authorize, isNegated, scopeMatches, isAuthEligible, patternHitsToViolations, escalateBlastRadius, escalateRulesViolation, aggregateLevel, removeAuthorized, scopeFromInput, matchPathRules, parseViolationJudgments } from "./guard.js";
 export { SLOP_SYMPTOMS, SLOP_LABELS } from "./guard.js";
 export { ActionGuard } from "./action-guard.js";
 export { evaluateProse, buildProseRequest, proseQuestions, proseNudge, describeAudience, ProseTrend, PROSE_SYMPTOMS, PROSE_LABELS } from "./prose.js";
@@ -18,5 +18,8 @@ export { CONFIG_SCHEMA, defaultConfig, loadConfig, applyUserOverrides, applyProj
 export { commandOf, outputReportsFailure, COMMAND_TOOLS } from "./tools.js";
 export { renderTemplate, actionTokens, stuckTokens, doneTokens, proseTokens, runawayTokens, rulesTokens, defaultWidgetConfig, DEFAULT_TEMPLATES, SENTENCE_TEMPLATES, pickSentenceTemplate, TOKEN_NAMES } from "./widget.js";
 export { Trace, actionDetails, stuckDetails, doneDetails, proseDetails, runawayDetails, rulesDetails } from "./trace.js";
-export { parseRules, condense, globToRegExp, matchGlob, projectPath, RuleStore, rulesFor, describeRuleSet, describeTarget, buildRulesRequest, ruleQuestion, evaluateRules, skipReason, rulesSteer, formatRules, pathNotes, pathNoteSteer, RulesGuard, RULES_FILE, FALLBACK_FILES, MAX_RULES, AGGREGATE_QUESTION, LOCATOR_QUESTION } from "./rules.js";
+export { parseRules, condense, isRuleShaped, globToRegExp, matchGlob, projectPath, RuleStore, rulesFor, describeRuleSet, describeTarget, buildRulesRequest, ruleQuestion, evaluateRules, skipReason, rulesSteer, formatRules, pathNotes, pathNoteSteer, RulesGuard, RULES_FILE, FALLBACK_FILES, MAX_RULES, AGGREGATE_QUESTION, LOCATOR_QUESTION } from "./rules.js";
+export { resolveRulesFile, extractRules, checkPiWardenMissing } from "./rules-file.js";
+export { writeStarterRules, generateStarterRules, detectProjectType, buildProjectContext, buildInitPrompt } from "./init.js";
 export { initSchema, recordHold, recordOutcome as recordHoldOutcome, querySmartHistory, calculateSmartConfidence, shouldSkipHold, analyzeThresholds, analyzePatterns, generateRecommendations, analyzeSteerEffectivenessReport } from "./learning.js";
+export { buildAuditPrompt, snapshotReport, reportOutcome } from "./audit.js";

package/dist/init.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Detect a rough project type from common manifest files.
+ * Returns a label like "typescript", "rust", "python", "go", or "generic".
+ */
+export declare function detectProjectType(cwd: string): string;
+/**
+ * Build project context for the starter rules file.
+ * Caps total context at 8000 characters.
+ */
+export declare function buildProjectContext(cwd: string): string;
+/**
+ * Generate a starter pi-warden.md file.
+ * Returns the content; does not write it.
+ */
+export declare function generateStarterRules(cwd: string): string;
+/**
+ * Build a ready-to-paste prompt for the model to generate pi-warden.md.
+ * Includes extracted project context and standard safety rules as a foundation.
+ */
+export declare function buildInitPrompt(cwd: string): string;
+/**
+ * Result of an /warden init attempt.
+ */
+export interface InitResult {
+    /** Whether a pi-warden.md already existed. */
+    alreadyExists: boolean;
+    /** The path that was written (or would be overwritten). */
+    path: string;
+    /** The content written. */
+    content: string;
+}
+/**
+ * Write a starter pi-warden.md to the project root.
+ * If it already exists, returns alreadyExists: true without writing.
+ */
+export declare function writeStarterRules(cwd: string, overwrite?: boolean): InitResult;

package/dist/init.js

@@ -0,0 +1,199 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { FALLBACK_FILES } from "./rules.js";
+/** Paths to scan for project context when generating a starter rules file. */
+const CONTEXT_CANDIDATES = [
+    "package.json",
+    "tsconfig.json",
+    "Cargo.toml",
+    "pyproject.toml",
+    "go.mod",
+];
+/**
+ * Detect a rough project type from common manifest files.
+ * Returns a label like "typescript", "rust", "python", "go", or "generic".
+ */
+export function detectProjectType(cwd) {
+    if (existsSync(join(cwd, "tsconfig.json")))
+        return "typescript";
+    if (existsSync(join(cwd, "Cargo.toml")))
+        return "rust";
+    if (existsSync(join(cwd, "pyproject.toml")))
+        return "python";
+    if (existsSync(join(cwd, "go.mod")))
+        return "go";
+    if (existsSync(join(cwd, "package.json")))
+        return "javascript";
+    return "generic";
+}
+/**
+ * Read a manifest file and extract a brief summary (name, scripts, dependencies).
+ * Returns a short string, or null if the file doesn't parse.
+ */
+function manifestSummary(cwd, filename) {
+    const path = join(cwd, filename);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        const parts = [];
+        if (raw.name)
+            parts.push(`name: ${raw.name}`);
+        if (raw.scripts) {
+            const scripts = Object.keys(raw.scripts).slice(0, 8);
+            if (scripts.length)
+                parts.push(`scripts: ${scripts.join(", ")}`);
+        }
+        if (raw.dependencies) {
+            const deps = Object.keys(raw.dependencies).slice(0, 10);
+            if (deps.length)
+                parts.push(`deps: ${deps.join(", ")}`);
+        }
+        return parts.join("; ") || null;
+    }
+    catch (err) {
+        // Best-effort: unparseable manifest is not a failure, just skip this candidate.
+        console.warn("pi-warden: could not parse manifest:", err);
+        return null;
+    }
+}
+/**
+ * Build project context for the starter rules file.
+ * Caps total context at 8000 characters.
+ */
+export function buildProjectContext(cwd) {
+    const parts = [];
+    const projectType = detectProjectType(cwd);
+    parts.push(`Project type: ${projectType}`);
+    for (const candidate of CONTEXT_CANDIDATES) {
+        const summary = manifestSummary(cwd, candidate);
+        if (summary)
+            parts.push(`${candidate}: ${summary}`);
+    }
+    const context = parts.join("\n");
+    return context.length > 8000 ? context.slice(0, 8000) + "\n...(truncated)" : context;
+}
+/** Read the first existing fallback rules file's content, or null if none exists. */
+function readExistingRules(cwd) {
+    for (const file of FALLBACK_FILES) {
+        const fullPath = join(cwd, file);
+        if (existsSync(fullPath)) {
+            try {
+                return readFileSync(fullPath, "utf8");
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    return null;
+}
+/** Read the existing pi-warden.md content, or null if it doesn't exist. */
+function readExistingPiWarden(cwd) {
+    const fullPath = join(cwd, "pi-warden.md");
+    if (!existsSync(fullPath))
+        return null;
+    try {
+        return readFileSync(fullPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/** Standard safety rules that ship in every starter pi-warden.md. */
+const SAFETY_RULES = `# No hardcoded secrets
+Source code must not contain passwords, API keys, tokens, or connection URLs with credentials.
+Read them from the environment, a function parameter, or the config module.
+
+# Comments explain why, not what
+A comment states a reason, a constraint, a workaround, or a non-obvious invariant. A comment
+that restates what the next line plainly does is a violation.
+
+# Errors are not swallowed
+A \`catch\` block must handle the error, report it, or re-raise it. An empty catch block, or
+one whose body is only a comment, is a violation.
+
+# No partial implementations
+Implement features fully. A comment that says "for now", "simplified", or "later", or a
+stub body, is a violation. If a part genuinely cannot be done, say so in your reply instead
+of stubbing it.
+
+# Do not run destructive commands that erase uncommitted work
+\`git reset --hard\`, \`git checkout -- .\`, \`git clean -fd\`, and similar commands that discard
+untracked or uncommitted changes are forbidden. These destroy work that has no backup. If a
+clean tree is needed, create a worktree instead or ask the user.
+`;
+/**
+ * Generate a starter pi-warden.md file.
+ * Returns the content; does not write it.
+ */
+export function generateStarterRules(cwd) {
+    const projectType = detectProjectType(cwd);
+    const context = buildProjectContext(cwd);
+    const existingRules = readExistingRules(cwd);
+    const lines = [
+        "Copy this file to the root of your project as `pi-warden.md` and edit it.",
+        "Every `#` heading below is one rule. The text under a heading is what Jev reads when it judges a write or an edit.",
+        "",
+        `<!-- Project context: ${context} -->`,
+        "",
+        SAFETY_RULES,
+    ];
+    const existingPiWarden = readExistingPiWarden(cwd);
+    if (existingPiWarden) {
+        lines.push("", "## Existing pi-warden.md rules (preserved)", existingPiWarden, "");
+    }
+    else if (existingRules) {
+        lines.push("", "## Existing project rules (preserved from fallback file)", existingRules, "");
+    }
+    // Add type-specific rules.
+    if (projectType === "typescript" || projectType === "javascript") {
+        lines.push("# No explicit any", "paths: **/*.ts, **/*.tsx", "Do not use the `any` type. Use a precise type, `unknown` with a runtime check, or a generic parameter.", "", "# Exported functions declare their return type", "paths: src/**/*.ts", "Every exported function or method declares its return type instead of relying on inference.", "");
+    }
+    lines.push("# New exported functions get a test", "paths: src/**", "A newly added exported function or class comes with at least one test that exercises its main behaviour.", "");
+    return lines.join("\n");
+}
+/**
+ * Build a ready-to-paste prompt for the model to generate pi-warden.md.
+ * Includes extracted project context and standard safety rules as a foundation.
+ */
+export function buildInitPrompt(cwd) {
+    const context = buildProjectContext(cwd);
+    const projectType = detectProjectType(cwd);
+    const existingRules = readExistingRules(cwd);
+    const lines = [
+        "Create a `pi-warden.md` file for this project. Every `#` heading is one rule; the text under it is what Jev judges against.",
+        "",
+        "## Project context",
+        context,
+        "",
+        "## Rules to always include",
+        SAFETY_RULES,
+    ];
+    const existingPiWarden = readExistingPiWarden(cwd);
+    if (existingPiWarden) {
+        lines.push("", "## Existing pi-warden.md rules (preserve these)", existingPiWarden, "");
+    }
+    else if (existingRules) {
+        lines.push("", "## Existing project rules (preserve these)", existingRules, "");
+    }
+    if (projectType === "typescript" || projectType === "javascript") {
+        lines.push("## Type-specific rules", "- No explicit `any` in **/*.ts, **/*.tsx", "- Exported functions declare their return type in src/**/*.ts", "");
+    }
+    lines.push("## Requirements", "- Under 50 rules", "- Each rule is a `#` heading with a description under it", "- Optional `paths:` line under a heading limits the rule to matching files", "- No stubs, no TODOs, no placeholders", "- Write the file to pi-warden.md at the project root");
+    return lines.join("\n");
+}
+/**
+ * Write a starter pi-warden.md to the project root.
+ * If it already exists, returns alreadyExists: true without writing.
+ */
+export function writeStarterRules(cwd, overwrite = false) {
+    const targetPath = join(cwd, "pi-warden.md");
+    const alreadyExists = existsSync(targetPath);
+    if (alreadyExists && !overwrite) {
+        return { alreadyExists: true, path: targetPath, content: readFileSync(targetPath, "utf8") };
+    }
+    const content = generateStarterRules(cwd);
+    writeFileSync(targetPath, content, "utf8");
+    return { alreadyExists, path: targetPath, content };
+}

package/dist/laya-download.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Download laya-mlx model weights from HuggingFace with a progress bar.
+ *
+ * Downloads to ~/.pi/agent/pi-warden/laya/ using an atomic staging strategy:
+ * files are written to a .staging subdirectory first, then promoted to the final
+ * location only after all files are present and the required files are validated.
+ * A .done marker signals a complete, validated checkpoint.
+ */
+/** The directory where model weights are stored. */
+export declare function layaModelDir(): string;
+/**
+ * True when the model directory exists, the .done marker is present,
+ * and all required files are on disk with non-zero size.
+ */
+export declare function layaModelReady(): boolean;
+/**
+ * Download the laya-mlx model. Shows a progress bar in the terminal.
+ * Returns the model directory path.
+ *
+ * Uses atomic staging: files are written to a .staging subdirectory,
+ * then promoted to the final location only after all files download
+ * successfully.  An interrupted download leaves .staging behind, which
+ * is cleaned up on the next startup.
+ *
+ * @param onStatus - callback for status messages
+ */
+export declare function downloadLayaModel(onStatus?: (msg: string) => void): Promise<string>;
+/**
+ * The directory where the pi-warden-managed Laya virtual environment lives.
+ * Uses the same agent dir as the model, keeping all Laya state together.
+ */
+export declare function layaVenvDir(): string;
+/** True when the venv exists and has laya importable. */
+export declare function layaVenvReady(): boolean;
+/** The Python executable inside the venv. */
+export declare function layaVenvPython(): string;
+/** Mark the venv as ready after successful installation. */
+export declare function markVenvReady(): Promise<void>;
+/** Remove the venv done marker so the next startup rebuilds it. */
+export declare function invalidateVenv(): void;

package/dist/laya-download.js

@@ -0,0 +1,288 @@
+/**
+ * Download laya-mlx model weights from HuggingFace with a progress bar.
+ *
+ * Downloads to ~/.pi/agent/pi-warden/laya/ using an atomic staging strategy:
+ * files are written to a .staging subdirectory first, then promoted to the final
+ * location only after all files are present and the required files are validated.
+ * A .done marker signals a complete, validated checkpoint.
+ */
+import { createWriteStream, existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { chmod, rename, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+const HF_API = "https://huggingface.co";
+const MODEL_REPO = "aac6fef/laya-mlx";
+const LAYA_DIR_NAME = "laya";
+/**
+ * Files that must exist for a valid checkpoint.
+ * Checked after download; missing files trigger a re-download.
+ */
+const REQUIRED_FILES = [
+    "model.safetensors",
+    "encoder/config.json",
+    "mlx_config.json",
+    "tokenizer/tokenizer.json",
+    "tokenizer/tokenizer_config.json",
+    "manifest.json",
+];
+/** The directory where model weights are stored. */
+export function layaModelDir() {
+    const configured = process.env.PI_CODING_AGENT_DIR?.trim();
+    const agentDir = configured
+        ? (configured === "~" || configured.startsWith("~/") ? join(homedir(), configured.slice(1)) : configured)
+        : join(homedir(), ".pi", "agent");
+    return join(agentDir, LAYA_DIR_NAME);
+}
+/** Marker file that signals a complete, validated download. */
+function doneMarker(dir) {
+    return join(dir, ".done");
+}
+/**
+ * True when the model directory exists, the .done marker is present,
+ * and all required files are on disk with non-zero size.
+ */
+export function layaModelReady() {
+    const dir = layaModelDir();
+    if (!existsSync(doneMarker(dir)))
+        return false;
+    return validateCheckpoint(dir);
+}
+/** Validate that all required checkpoint files exist with non-zero size. */
+function validateCheckpoint(dir) {
+    for (const file of REQUIRED_FILES) {
+        const path = join(dir, file);
+        try {
+            const st = statSync(path);
+            if (st.size === 0)
+                return false;
+        }
+        catch {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Fetch all files in the repo with their sizes.
+ *
+ * Uses two HuggingFace endpoints because neither alone gives us everything:
+ * - `/api/models/{repo}` siblings: full file list (including nested paths like
+ *   `encoder/config.json`) but no sizes.
+ * - `/api/models/{repo}/tree/{ref}/{path}`: sizes for files in one directory,
+ *   but only returns direct children (not recursive).
+ *
+ * Strategy: get the full list from siblings, then walk each directory subtree
+ * via /tree to fill in sizes.
+ */
+async function listRepoFiles(repo) {
+    // 1. Get the complete file list from siblings (includes nested paths).
+    const metaUrl = `${HF_API}/api/models/${repo}`;
+    const metaResp = await fetchWithTimeout(metaUrl, 15_000);
+    if (!metaResp.ok)
+        throw new Error(`HuggingFace API ${metaResp.status}: ${metaResp.statusText}`);
+    const meta = (await metaResp.json());
+    if (!meta.siblings)
+        throw new Error("no siblings in model info");
+    const allPaths = meta.siblings
+        .map(s => s.rfilename)
+        .filter(p => typeof p === "string" && p.length > 0);
+    if (allPaths.length === 0)
+        throw new Error("model repo has no files");
+    // 2. Collect directory paths that need size lookups.
+    const dirs = new Set();
+    for (const p of allPaths) {
+        const slash = p.indexOf("/");
+        if (slash !== -1)
+            dirs.add(p.slice(0, slash));
+    }
+    // 3. Fetch sizes from /tree for each directory (root + subdirs).
+    const sizes = new Map();
+    const fetchTree = async (dirPath) => {
+        const treeUrl = `${HF_API}/api/models/${repo}/tree/main${dirPath ? "/" + dirPath : ""}`;
+        const resp = await fetchWithTimeout(treeUrl, 15_000);
+        if (!resp.ok)
+            return; // non-fatal: we'll download without size info
+        const entries = (await resp.json());
+        if (!Array.isArray(entries))
+            return;
+        for (const e of entries) {
+            if (typeof e.path === "string" && typeof e.size === "number" && e.size > 0 && e.type !== "directory") {
+                // /tree returns repo-relative paths (e.g. "encoder/config.json"),
+                // not paths relative to the queried directory.
+                sizes.set(e.path, e.size);
+            }
+        }
+    };
+    // Fetch root + all known subdirectories in parallel.
+    await Promise.all([fetchTree(""), ...[...dirs].map(d => fetchTree(d))]);
+    // 4. Build the final file list.  Files without a size from /tree get size 0
+    //    (the download will still work; the progress bar just won't know the total
+    //    for that file).
+    return allPaths
+        .filter(p => !p.endsWith("/")) // skip pure directories
+        .map(p => ({ path: p, size: sizes.get(p) ?? 0 }));
+}
+/** Download a single file with progress tracking. */
+async function downloadFile(url, dest, totalBytes, progress, onProgress) {
+    const response = await fetchWithTimeout(url, 60_000);
+    if (!response.ok)
+        throw new Error(`download ${url}: ${response.status}`);
+    if (!response.body)
+        throw new Error(`no body for ${url}`);
+    const fileStream = createWriteStream(dest);
+    try {
+        const reader = response.body.getReader();
+        let done = false;
+        while (!done) {
+            const result = await reader.read();
+            done = result.done;
+            if (result.value) {
+                fileStream.write(result.value);
+                progress.downloaded += result.value.length;
+                onProgress(progress.downloaded, progress.total);
+            }
+        }
+        fileStream.end();
+        await new Promise((resolve, reject) => {
+            fileStream.on("finish", resolve);
+            fileStream.on("error", reject);
+        });
+    }
+    catch (err) {
+        fileStream.destroy();
+        throw err;
+    }
+}
+/** fetch with a timeout (using AbortController). */
+async function fetchWithTimeout(url, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(url, { signal: controller.signal, redirect: "follow" });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Download the laya-mlx model. Shows a progress bar in the terminal.
+ * Returns the model directory path.
+ *
+ * Uses atomic staging: files are written to a .staging subdirectory,
+ * then promoted to the final location only after all files download
+ * successfully.  An interrupted download leaves .staging behind, which
+ * is cleaned up on the next startup.
+ *
+ * @param onStatus - callback for status messages
+ */
+export async function downloadLayaModel(onStatus) {
+    const dir = layaModelDir();
+    if (layaModelReady())
+        return dir;
+    // Clean up any leftover staging directory from a previous interrupted download.
+    const stagingDir = `${dir}.staging`;
+    await rm(stagingDir, { recursive: true, force: true }).catch((err) => {
+        console.warn(`pi-warden: could not clean staging dir: ${err instanceof Error ? err.message : err}`);
+    });
+    // If the final dir exists but is incomplete, remove it so we start fresh.
+    if (existsSync(dir) && !validateCheckpoint(dir)) {
+        onStatus?.("incomplete model cache detected; re-downloading...");
+        await rm(dir, { recursive: true, force: true }).catch((err) => {
+            console.warn(`pi-warden: could not remove incomplete model dir: ${err instanceof Error ? err.message : err}`);
+        });
+    }
+    mkdirSync(stagingDir, { recursive: true });
+    onStatus?.("please wait, downloading laya-mlx model...");
+    // 1. List files from the repo.
+    const files = await listRepoFiles(MODEL_REPO);
+    if (files.length === 0)
+        throw new Error("HuggingFace returned no files for the model repo");
+    const totalBytes = files.reduce((sum, f) => sum + f.size, 0);
+    // 2. Download each file into the staging directory.
+    const progress = { downloaded: 0, total: totalBytes, filesDone: 0, filesTotal: files.length };
+    const lastReport = { bytes: 0, time: Date.now() };
+    const onProgress = (downloaded, total) => {
+        const now = Date.now();
+        if (now - lastReport.time < 200 && downloaded < total)
+            return;
+        lastReport.bytes = downloaded;
+        lastReport.time = now;
+        const pct = total > 0 ? (downloaded / total) * 100 : 0;
+        const mb = (downloaded / (1024 * 1024)).toFixed(1);
+        const totalMb = (total / (1024 * 1024)).toFixed(1);
+        const barLen = 30;
+        const filled = Math.round((pct / 100) * barLen);
+        const bar = "█".repeat(filled) + "░".repeat(barLen - filled);
+        process.stderr.write(`\r  ${bar} ${pct.toFixed(0)}% (${mb}/${totalMb} MB)`);
+    };
+    for (const file of files) {
+        const fileUrl = `${HF_API}/${MODEL_REPO}/resolve/main/${file.path}`;
+        const dest = join(stagingDir, file.path);
+        mkdirSync(dirname(dest), { recursive: true });
+        await downloadFile(fileUrl, dest, file.size, progress, onProgress);
+        progress.filesDone++;
+    }
+    process.stderr.write("\n");
+    // 3. Validate required files in the staging directory.
+    if (!validateCheckpoint(stagingDir)) {
+        await rm(stagingDir, { recursive: true, force: true }).catch((err) => {
+            console.warn(`pi-warden: could not clean staging dir after validation failure: ${err instanceof Error ? err.message : err}`);
+        });
+        throw new Error("laya-mlx: download completed but required checkpoint files are missing");
+    }
+    // 4. Promote staging to final location (atomic on the same filesystem).
+    if (existsSync(dir)) {
+        await rm(dir, { recursive: true, force: true }).catch((err) => {
+            console.warn(`pi-warden: could not remove old model dir before promote: ${err instanceof Error ? err.message : err}`);
+        });
+    }
+    await rename(stagingDir, dir);
+    // 5. Write done marker.
+    writeFileSync(doneMarker(dir), JSON.stringify({ files: files.map(f => f.path), totalBytes, downloadedAt: new Date().toISOString() }));
+    await chmod(doneMarker(dir), 0o600);
+    onStatus?.("laya-mlx model ready.");
+    return dir;
+}
+// ---------------------------------------------------------------------------
+// Managed virtual environment for Laya.
+// ---------------------------------------------------------------------------
+/**
+ * The directory where the pi-warden-managed Laya virtual environment lives.
+ * Uses the same agent dir as the model, keeping all Laya state together.
+ */
+export function layaVenvDir() {
+    const configured = process.env.PI_CODING_AGENT_DIR?.trim();
+    const agentDir = configured
+        ? (configured === "~" || configured.startsWith("~/") ? join(homedir(), configured.slice(1)) : configured)
+        : join(homedir(), ".pi", "agent");
+    return join(agentDir, "laya-venv");
+}
+/** Marker file that signals a working venv with laya importable. */
+function venvDoneMarker(dir) {
+    return join(dir, ".done");
+}
+/** True when the venv exists and has laya importable. */
+export function layaVenvReady() {
+    return existsSync(venvDoneMarker(layaVenvDir()));
+}
+/** The Python executable inside the venv. */
+export function layaVenvPython() {
+    return join(layaVenvDir(), "bin", "python3");
+}
+/** Mark the venv as ready after successful installation. */
+export async function markVenvReady() {
+    const marker = venvDoneMarker(layaVenvDir());
+    writeFileSync(marker, JSON.stringify({ createdAt: new Date().toISOString() }));
+    await chmod(marker, 0o600);
+}
+/** Remove the venv done marker so the next startup rebuilds it. */
+export function invalidateVenv() {
+    const marker = venvDoneMarker(layaVenvDir());
+    try {
+        statSync(marker);
+        unlinkSync(marker);
+    }
+    catch (err) {
+        console.warn(`pi-warden: could not invalidate venv marker: ${err instanceof Error ? err.message : err}`);
+    }
+}