loadout-ai 0.7.0 → 0.8.0

package/dist/src/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { Command, CommanderError } from "commander";
 import { HIDDEN_FROM_FIRST_SCREEN } from "./core/reporting/cli-guide.js";
+import { registerCompletionCommands } from "./core/reporting/completion.js";
 import { recoverPendingTransactions } from "./core/install/transaction.js";
 import { LOADOUT_VERSION, printBeginnerGuide, runWizard, } from "./commands/support.js";
 import { registerSetup } from "./commands/setup.js";
@@ -34,6 +35,10 @@ registerInventory(program);
 registerCatalog(program);
 registerMcp(program);
 registerLifecycle(program);
+registerCompletionCommands(program.commands.map((command) => ({
+    name: command.name(),
+    subcommands: command.commands.map((sub) => sub.name()),
+})));
 for (const command of program.commands)
     // Commander supports `hidden` when a command is created. These commands are
     // registered by separate feature blocks, so use the same runtime flag here

package/dist/src/commands/catalog.js

@@ -2,9 +2,11 @@ import { explainCatalogScore, loadEffectiveCatalog, loadCatalog, promoteCatalogC
 import { detectAgents, parseAgentSelection } from "../core/agents/paths.js";
 import { resolve } from "node:path";
 import { readFile } from "node:fs/promises";
-import { allPhaseRoutes, formatCostTable, formatModelCatalog, formatRouteRecommendation, formatRoutingTable, routePhase, routeTask, } from "../core/routing/route.js";
+import { formatModelCatalog, MODEL_CATALOG } from "../core/routing/route.js";
+import { BUCKETS, formatAnswer, formatPolicy, guessBucket, policyPath, readPolicy, resolveRoute, setRule, writePolicy, } from "../core/routing/policy.js";
+import { rm } from "node:fs/promises";
 import { applyFirstPartySkill, FIRST_PARTY_SKILLS, formatFirstPartySkillList, formatFirstPartySkillPlan, installedFirstPartySkills, planFirstPartySkill, removeFirstPartySkill, } from "../core/routing/first-party-skills.js";
-import { applyPickup, formatHandoffStatus, formatInbox, formatPickupPlan, getHandoffState, initHandoff, isHandoffInitialized, markDone, planPickup, readInbox, sendHandoff, } from "../core/routing/handoff.js";
+import { applyPickup, formatHandoffStatus, formatInbox, getHandoffState, initHandoff, isHandoffInitialized, isPickupTarget, markDone, planPickup, readInbox, sendHandoff, } from "../core/routing/handoff.js";
 import { catalogTrustStage, formatCatalogTrustStage, } from "../core/catalog/profiles.js";
 import { discoverHackerNewsRepositories } from "../core/discovery/community.js";
 import { discoverPrivateRepositories } from "../core/discovery/private-discovery.js";
@@ -656,144 +658,129 @@ export function registerCatalog(program) {
     });
     const handoff = program
         .command("handoff")
-        .description("Cross-agent file-based task handoff — send work between Claude Code, Codex, and other agents");
+        .description("Hand a task to your other agent, or see what has been handed to you");
     handoff
-        .command("init")
-        .description("Create the .handoff/ protocol directory in the current project")
-        .action(async () => {
-        const projectRoot = process.cwd();
-        if (await isHandoffInitialized(projectRoot)) {
-            console.log("Handoff already initialized at .handoff/");
+        .argument("[agent]", "who should do it, for example codex")
+        .argument("[task...]", "what they should do")
+        .option("--context <text>", "anything they need that is not in the task")
+        .option("--from <agent>", "who is sending", "user")
+        .option("--done <id>", "mark a task finished")
+        .option("--json", "emit machine-readable JSON")
+        .action(async (agent, taskWords, options) => {
+        const cwd = process.cwd();
+        if (options.done) {
+            const message = await markDone(cwd, options.done);
+            console.log(options.json
+                ? JSON.stringify(message, null, 2)
+                : `Marked ${options.done} done.`);
             return;
         }
-        const dir = await initHandoff(projectRoot);
-        console.log(`Initialized handoff protocol at ${dir}`);
-        console.log("Add .handoff/ to version control so both agents share the message log.");
-    });
-    handoff
-        .command("send")
-        .description("Send a task or message to another agent")
-        .argument("<agent>", "target agent (e.g. codex, claude-code)")
-        .argument("<description...>", "task description")
-        .option("--from <agent>", "sending agent", "user")
-        .option("--type <type>", "message type: task, handoff, question, status, error, cancel", "task")
-        .option("--context <text>", "additional context for the receiving agent")
-        .option("--json", "emit machine-readable JSON")
-        .action(async (agent, descriptionWords, options) => {
-        const message = await sendHandoff(process.cwd(), agent, descriptionWords.join(" "), {
+        // No agent named: show what is waiting, for everyone.
+        if (!agent) {
+            const state = await getHandoffState(cwd);
+            console.log(options.json
+                ? JSON.stringify(state, null, 2)
+                : formatHandoffStatus(state));
+            return;
+        }
+        // An agent with no task means "show me my inbox".
+        const task = taskWords.join(" ").trim();
+        if (!task) {
+            const messages = await readInbox(cwd, agent);
+            console.log(options.json
+                ? JSON.stringify(messages, null, 2)
+                : formatInbox(agent, messages));
+            return;
+        }
+        // Sending is the common case, so it sets itself up rather than failing
+        // with instructions to run two other commands first.
+        const setup = [];
+        if (!(await isHandoffInitialized(cwd))) {
+            await initHandoff(cwd);
+            setup.push("created .handoff/");
+        }
+        for (const target of [options.from, agent]) {
+            if (!isPickupTarget(target))
+                continue;
+            const plan = await planPickup(cwd, target);
+            if (!plan.replacing) {
+                await applyPickup(plan);
+                setup.push(`told ${target} to check its inbox`);
+            }
+        }
+        const message = await sendHandoff(cwd, agent, task, {
             from: options.from,
-            type: options.type,
-            context: options.context,
+            ...(options.context ? { context: options.context } : {}),
         });
-        console.log(options.json
-            ? JSON.stringify(message, null, 2)
-            : `Sent ${message.type} ${message.id} → ${message.to}: ${message.description}`);
-    });
-    handoff
-        .command("done")
-        .description("Mark a handoff task as completed")
-        .argument("<id>", "message id to mark done")
-        .option("--json", "emit machine-readable JSON")
-        .action(async (id, options) => {
-        const message = await markDone(process.cwd(), id);
-        console.log(options.json
-            ? JSON.stringify(message, null, 2)
-            : `Marked ${id} as done`);
-    });
-    handoff
-        .command("inbox")
-        .description("Show pending tasks addressed to one agent, as instructions it can act on")
-        .argument("<agent>", "agent reading its inbox (e.g. claude-code, codex)")
-        .option("--json", "emit machine-readable JSON")
-        .action(async (agent, options) => {
-        const messages = await readInbox(process.cwd(), agent);
-        console.log(options.json
-            ? JSON.stringify(messages, null, 2)
-            : formatInbox(agent, messages));
-    });
-    handoff
-        .command("pickup")
-        .description("Teach agents to check their handoff inbox by adding a managed block to CLAUDE.md / AGENTS.md")
-        .option("--agents <ids>", "comma-separated agents to instruct", "claude-code,codex")
-        .option("--yes", "write the files after previewing")
-        .action(async (options) => {
-        const agents = options.agents
-            .split(",")
-            .map((value) => value.trim())
-            .filter(Boolean);
-        const plans = [];
-        for (const agent of agents)
-            plans.push(await planPickup(process.cwd(), agent));
-        console.log(formatPickupPlan(plans));
-        if (!options.yes) {
-            console.log("\nPreview only. Re-run with --yes to write these files.");
+        if (options.json) {
+            console.log(JSON.stringify({ message, setup }, null, 2));
             return;
         }
-        for (const plan of plans)
-            await applyPickup(plan);
-        console.log(`\nWrote pickup instructions for ${plans.length} agent(s). They will check their inbox on the next session.`);
-    });
-    handoff
-        .command("status")
-        .description("Show pending and completed handoff tasks")
-        .option("--json", "emit machine-readable JSON")
-        .action(async (options) => {
-        const state = await getHandoffState(process.cwd());
-        console.log(options.json
-            ? JSON.stringify(state, null, 2)
-            : formatHandoffStatus(state));
+        for (const line of setup)
+            console.log(`  ${line}`);
+        console.log(`Sent to ${agent}: ${task}`);
+        console.log(`It will pick this up next session, or now with: loadout handoff ${agent}`);
     });
     const route = program
         .command("route")
-        .description("Recommend the right model tier and agent for a task — plan, implement, review, test, debug, or document");
+        .description("Which model to use for a task, according to a routing policy you own");
     route
-        .argument("[description...]", "natural-language task description")
-        .option("--phase <phase>", "explicit phase instead of auto-classify")
-        .option("--conserve", "recommend cheaper tiers to stretch remaining session quota")
-        .option("--cost", "show cost comparison table across all phases")
-        .option("--models", "list the full model catalog Loadout knows about")
-        .option("--provider <name>", "filter models by provider (anthropic, openai, google, deepseek, meta)")
-        .option("--tier <tier>", "filter models by tier (frontier, standard, fast)")
+        .argument("[description...]", "what you are about to do")
+        .option("--bucket <bucket>", "state the bucket yourself: hard, normal, or cheap")
+        .option("--set <bucket=model>", "change the model for one bucket and save")
+        .option("--save", "write the current defaults to disk so you can edit them")
+        .option("--reset", "delete your policy and go back to the defaults")
+        .option("--models", "list the model ids you can name in a policy")
         .option("--json", "emit machine-readable JSON")
         .action(async (descriptionWords, options) => {
         if (options.models) {
             console.log(options.json
-                ? JSON.stringify((await import("../core/routing/route.js")).MODEL_CATALOG, null, 2)
-                : formatModelCatalog({
-                    provider: options.provider,
-                    tier: options.tier,
-                }));
+                ? JSON.stringify(MODEL_CATALOG, null, 2)
+                : formatModelCatalog());
             return;
         }
-        if (options.cost) {
-            console.log(options.json
-                ? JSON.stringify((await import("../core/routing/route.js")).estimateCostSavings(), null, 2)
-                : formatCostTable());
+        const detected = await detectAgents();
+        const installed = detected
+            .filter((agent) => agent.installed)
+            .map((agent) => agent.id);
+        if (options.reset) {
+            await rm(policyPath(), { force: true });
+            console.log("Removed your routing policy; defaults apply again.");
+            return;
+        }
+        if (options.set) {
+            const separator = options.set.indexOf("=");
+            if (separator <= 0)
+                throw new Error("--set expects <bucket>=<model>, for example normal=gpt-5.6-terra");
+            const bucket = options.set.slice(0, separator).trim();
+            if (!BUCKETS.includes(bucket))
+                throw new Error(`Unknown bucket '${bucket}'. Valid: ${BUCKETS.join(", ")}`);
+            const updated = await setRule(bucket, options.set.slice(separator + 1).trim(), installed);
+            console.log(formatPolicy(updated, "file"));
+            return;
+        }
+        const { policy, source } = await readPolicy(installed);
+        if (options.save) {
+            const path = await writePolicy(policy);
+            console.log(`Saved your routing policy to ${path}\n`);
+            console.log(formatPolicy(policy, "file"));
             return;
         }
         const description = descriptionWords.join(" ").trim();
-        if (!description && !options.phase) {
+        if (!description && !options.bucket) {
             console.log(options.json
-                ? JSON.stringify(allPhaseRoutes(options.conserve), null, 2)
-                : formatRoutingTable(options.conserve));
+                ? JSON.stringify({ policy, source }, null, 2)
+                : formatPolicy(policy, source));
             return;
         }
-        const rec = options.phase
-            ? routePhase(options.phase, options.conserve)
-            : routeTask(description, options.conserve);
-        // Recommendations are only useful when they name agents this machine
-        // actually has, so detection drives both the advice and the handoff line.
-        const detected = await detectAgents();
-        const installedAgents = detected
-            .filter((agent) => agent.installed)
-            .map((agent) => agent.id);
+        const stated = options.bucket;
+        if (stated && !BUCKETS.includes(stated))
+            throw new Error(`Unknown bucket '${stated}'. Valid: ${BUCKETS.join(", ")}`);
+        const bucket = stated ?? guessBucket(description);
+        const answer = resolveRoute(policy, bucket, installed, !stated);
         console.log(options.json
-            ? JSON.stringify({ ...rec, installedAgents }, null, 2)
-            : formatRouteRecommendation(rec, {
-                installedAgents,
-                ...(description ? { description } : {}),
-                handoffReady: await isHandoffInitialized(process.cwd()),
-            }));
+            ? JSON.stringify(answer, null, 2)
+            : formatAnswer(answer, description || undefined));
     });
     program
         .command("completion")

package/dist/src/core/agents/agent-inspection.js

@@ -136,6 +136,30 @@ export async function inspectAgent(agent) {
 export async function inspectAgents(agents) {
     return Promise.all(agents.map(inspectAgent));
 }
+/**
+ * Count installable units rather than raw filesystem entries. A skill is one
+ * directory containing SKILL.md, so counting every nested file reports a number
+ * many times larger than the number of skills the user actually has.
+ */
+export function countComponentUnits(component) {
+    if (!component.scanned || !component.directoryExists)
+        return 0;
+    const skillRoots = new Set();
+    let looseFiles = 0;
+    for (const entry of component.entries) {
+        if (entry.kind !== "file")
+            continue;
+        const segments = entry.path.split("/");
+        const name = segments[segments.length - 1];
+        if (name === "SKILL.md") {
+            // Depth 1 means SKILL.md sits at the component root, which is one unit.
+            skillRoots.add(segments.slice(0, -1).join("/") || ".");
+        }
+        else if (segments.length === 1)
+            looseFiles += 1;
+    }
+    return skillRoots.size || looseFiles;
+}
 /**
  * One agent's inventory. The default is a two-line summary: what is installed
  * and which component kinds the adapter supports. Adapter internals — the
@@ -155,16 +179,14 @@ export function formatAgentInventory(inventory, options = {}) {
         }
     }
     else {
-        const items = inventory.components
-            .filter((component) => component.scanned && component.directoryExists)
-            .reduce((total, component) => total + component.entries.length, 0);
+        const items = inventory.components.reduce((total, component) => total + countComponentUnits(component), 0);
         const supported = inventory.components
             .filter((component) => component.compatibility !== "unsupported")
             .map((component) => component.type);
         const skills = inventory.components.find((component) => component.type === "skill");
         if (skills?.directory)
             lines.push(`  ${skills.directory}`);
-        lines.push(`  ${items} items | supports: ${supported.join(", ")}`);
+        lines.push(`  ${items} skills | supports: ${supported.join(", ")}`);
     }
     for (const warning of inventory.warnings)
         lines.push(`  ! ${warning}`);

package/dist/src/core/catalog/registry.js

@@ -1,9 +1,11 @@
-import { createHash } from "node:crypto";
-import { cp, lstat, mkdir, readFile, readdir, rm, writeFile, } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import { cp, lstat, mkdir, readFile, readdir, rename, rm, writeFile, } from "node:fs/promises";
 import { join, relative, resolve, sep } from "node:path";
 import { loadoutHome } from "../agents/paths.js";
 import { analyzeUpdateSafety } from "./safety.js";
 const NAME = /^[a-z0-9][a-z0-9._-]*$/;
+/** A SHA-256 digest, and nothing that could traverse a path. */
+const DIGEST = /^[a-f0-9]{64}$/;
 const VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/;
 export function parsePackageDescriptor(value) {
     if (!value || typeof value !== "object")
@@ -266,18 +268,54 @@ function registryEndpoint(base, path) {
     endpoint.hash = "";
     return endpoint;
 }
+/** Registry responses are untrusted input: bound the wait and the body. */
+const REGISTRY_TIMEOUT_MS = 30_000;
+const REGISTRY_MAX_BYTES = 32 * 1024 * 1024;
+async function registryJson(input, init = {}) {
+    const response = await fetch(input, {
+        ...init,
+        signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS),
+    });
+    // Trust the declared length when present, but still cap what is read: a
+    // server may understate or omit it.
+    const declared = Number(response.headers.get("content-length"));
+    if (Number.isFinite(declared) && declared > REGISTRY_MAX_BYTES)
+        throw new Error("Remote registry response exceeds the size limit");
+    const body = await response.arrayBuffer();
+    if (body.byteLength > REGISTRY_MAX_BYTES)
+        throw new Error("Remote registry response exceeds the size limit");
+    const text = new TextDecoder().decode(body);
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw new Error("Remote registry returned a malformed JSON response");
+    }
+    return { ok: response.ok, status: response.status, value };
+}
 export async function fetchRemoteRegistryPackage(registry, name, version) {
     if (!NAME.test(name) || !VERSION.test(version))
         throw new Error("Invalid remote registry package name or version");
     const base = registryUrl(registry);
-    const response = await fetch(registryEndpoint(base, `/v1/packages/${encodeURIComponent(name)}/${encodeURIComponent(version)}`));
+    const response = await registryJson(registryEndpoint(base, `/v1/packages/${encodeURIComponent(name)}/${encodeURIComponent(version)}`));
     if (!response.ok)
         throw new Error(`Remote registry returned ${response.status}`);
-    const bundle = (await response.json());
+    const bundle = response.value;
+    // `digest` arrives from a remote server and is used to build a path that is
+    // later deleted recursively. Validate its shape before it can become one:
+    // a value such as "../../.." would otherwise escape the cache root.
+    if (typeof bundle?.digest !== "string" || !DIGEST.test(bundle.digest))
+        throw new Error("Remote registry returned a bundle whose digest is not a SHA-256 hex string");
     const key = createHash("sha256")
         .update(base.origin + base.pathname)
         .digest("hex");
-    const target = join(loadoutHome(), "cache", "registry", key, name, version, bundle.digest);
+    const root = join(loadoutHome(), "cache", "registry", key, name, version);
+    const target = resolve(root, bundle.digest);
+    // Belt and braces: even with a validated digest, never operate on a path
+    // that resolved outside the directory it was meant to live in.
+    if (target !== root && !target.startsWith(root + sep))
+        throw new Error("Remote registry bundle resolved outside the cache root");
     try {
         const packed = await packPackage(target);
         if (packed.digest === bundle.digest)
@@ -286,9 +324,19 @@ export async function fetchRemoteRegistryPackage(registry, name, version) {
     catch {
         /* import below */
     }
-    await mkdir(resolve(target, ".."), { recursive: true });
-    await rm(target, { recursive: true, force: true });
-    await importRegistryBundle(bundle, target);
+    // Import into a scratch directory and swap it in, so a failed or malicious
+    // import cannot leave the cache holding a half-written package.
+    await mkdir(root, { recursive: true });
+    const staging = `${target}.incoming-${randomUUID().slice(0, 8)}`;
+    try {
+        await importRegistryBundle(bundle, staging);
+        await rm(target, { recursive: true, force: true });
+        await rename(staging, target);
+    }
+    catch (error) {
+        await rm(staging, { recursive: true, force: true });
+        throw error;
+    }
     return { path: target, digest: bundle.digest };
 }
 export async function publishRemotePackage(root, registry, token, options = {}) {
@@ -296,7 +344,7 @@ export async function publishRemotePackage(root, registry, token, options = {})
         throw new Error("Remote registry token is required");
     const bundle = await createRegistryBundle(root);
     const base = registryUrl(registry);
-    const response = await fetch(registryEndpoint(base, "/v1/packages"), {
+    const response = await registryJson(registryEndpoint(base, "/v1/packages"), {
         method: "POST",
         headers: {
             authorization: `Bearer ${token}`,
@@ -305,7 +353,7 @@ export async function publishRemotePackage(root, registry, token, options = {})
         },
         body: JSON.stringify(bundle),
     });
-    const result = (await response.json());
+    const result = response.value;
     if (!response.ok)
         throw new Error(result.error ?? `Remote registry returned ${response.status}`);
     return {

package/dist/src/core/catalog/safety.js

@@ -38,27 +38,37 @@ const SUSPICIOUS_INSTRUCTIONS = [
 export function detectSecretKinds(content) {
     return SECRET_PATTERNS.filter((check) => check.pattern.test(content)).map((check) => check.name);
 }
-async function files(root) {
+const MAX_INSPECTABLE_BYTES = 2_000_000;
+const MAX_DEPTH = 10;
+async function files(root, gaps = []) {
     const result = new Map();
     const base = resolve(root);
     try {
         const rootInfo = await stat(base);
-        if (rootInfo.isFile() && rootInfo.size <= 2_000_000) {
+        if (rootInfo.isFile()) {
+            if (rootInfo.size > MAX_INSPECTABLE_BYTES) {
+                gaps.push({ path: basename(base), reason: "too-large" });
+                return result;
+            }
             result.set(basename(base), await readFile(base));
             return result;
         }
     }
     catch {
+        gaps.push({ path: basename(base), reason: "unreadable" });
         return result;
     }
     async function visit(directory, depth) {
-        if (depth > 10)
+        if (depth > MAX_DEPTH) {
+            gaps.push({ path: relative(base, directory), reason: "too-deep" });
             return;
+        }
         let entries;
         try {
             entries = await readdir(directory, { withFileTypes: true });
         }
         catch {
+            gaps.push({ path: relative(base, directory), reason: "unreadable" });
             return;
         }
         for (const entry of entries) {
@@ -73,14 +83,19 @@ async function files(root) {
             }
             if (!entry.isFile())
                 continue;
+            const shown = relative(base, absolute).split("\\").join("/");
             try {
                 const info = await stat(absolute);
-                if (info.size > 2_000_000)
+                if (info.size > MAX_INSPECTABLE_BYTES) {
+                    gaps.push({ path: shown, reason: "too-large" });
                     continue;
-                result.set(relative(base, absolute).split("\\").join("/"), await readFile(absolute));
+                }
+                result.set(shown, await readFile(absolute));
             }
             catch {
-                /* repository may change while being inspected */
+                // The repository may change while being inspected; either way this
+                // file was not reviewed, so record it rather than passing it silently.
+                gaps.push({ path: shown, reason: "unreadable" });
             }
         }
     }
@@ -131,8 +146,9 @@ function collectEnvironmentNames(content) {
 }
 /** Analyze changed repository files without running package code or revealing secret values. */
 export async function analyzeUpdateSafety(oldPath, newPath) {
+    const gaps = [];
     const oldFiles = oldPath ? await files(oldPath) : new Map();
-    const newFiles = await files(newPath);
+    const newFiles = await files(newPath, gaps);
     const changed = changedPaths(oldFiles, newFiles);
     const findings = [];
     const domains = new Set();
@@ -227,6 +243,19 @@ export async function analyzeUpdateSafety(oldPath, newPath) {
             paths: [...new Set(instructionPaths)].sort(),
             names: [...instructionKinds].sort(),
         });
+    // Fail closed. Anything the scan could not open is exactly what a reviewer
+    // needs told about, so an uninspectable file requires approval rather than
+    // producing a clean report.
+    if (gaps.length) {
+        const reasons = [...new Set(gaps.map((gap) => gap.reason))].sort();
+        findings.push({
+            severity: "blocking",
+            category: "uninspectable",
+            message: `Safety scan could not inspect ${gaps.length} path(s) (${reasons.join(", ")}); they were not reviewed.`,
+            paths: [...new Set(gaps.map((gap) => gap.path))].sort(),
+            names: reasons,
+        });
+    }
     return {
         approvalRequired: findings.some((finding) => finding.severity === "blocking"),
         findings,

package/dist/src/core/install/source.js

@@ -6,9 +6,26 @@ import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { loadoutHome, ensureDirectory } from "../agents/paths.js";
 const execFileAsync = promisify(execFile);
+/**
+ * Bounds apply to every fetch, not only to callers who remember to ask. An
+ * unbounded clone of an untrusted repository can hang a Git process forever or
+ * fill the disk, so callers may raise a limit but none may omit one.
+ */
+export const REPOSITORY_FETCH_DEFAULTS = {
+    /** A reviewed skill repository clones well inside this. */
+    timeoutMs: 120_000,
+    maxBytes: 256 * 1024 * 1024,
+    maxFiles: 20_000,
+};
+function withFetchDefaults(options) {
+    return {
+        ...options,
+        timeoutMs: options.timeoutMs ?? REPOSITORY_FETCH_DEFAULTS.timeoutMs,
+        maxBytes: options.maxBytes ?? REPOSITORY_FETCH_DEFAULTS.maxBytes,
+        maxFiles: options.maxFiles ?? REPOSITORY_FETCH_DEFAULTS.maxFiles,
+    };
+}
 async function enforceRepositoryBounds(root, options) {
-    if (options.maxBytes === undefined && options.maxFiles === undefined)
-        return;
     let bytes = 0;
     let files = 0;
     const pending = [root];
@@ -35,8 +52,6 @@ async function enforceRepositoryBounds(root, options) {
     }
 }
 export function validateGitHubTreeBounds(value, options) {
-    if (options.maxBytes === undefined && options.maxFiles === undefined)
-        return;
     if (!value || typeof value !== "object" || Array.isArray(value))
         throw new Error("GitHub tree preflight returned an invalid response");
     const response = value;
@@ -63,8 +78,6 @@ export function validateGitHubTreeBounds(value, options) {
     }
 }
 async function enforceGitHubTreeBounds(repository, commit, options) {
-    if (options.maxBytes === undefined && options.maxFiles === undefined)
-        return;
     const signal = AbortSignal.timeout(options.timeoutMs ?? 120_000);
     const token = process.env.GITHUB_TOKEN?.trim();
     const response = await (options.fetcher ?? fetch)(`https://api.github.com/repos/${repository}/git/trees/${commit}?recursive=1`, {
@@ -181,7 +194,8 @@ function normalizeRef(ref) {
         throw new Error(`Invalid Git ref: ${ref}`);
     return ref;
 }
-export async function fetchRepositorySnapshot(input, options = {}) {
+export async function fetchRepositorySnapshot(input, requested = {}) {
+    const options = withFetchDefaults(requested);
     const repository = normalizeRepository(input);
     const gitEnvironment = await isolatedGitEnvironment(loadoutHome());
     const ref = options.ref ? normalizeRef(options.ref) : undefined;

package/dist/src/core/reporting/cli-guide.js

@@ -16,9 +16,9 @@ IN A PROJECT
 
 WHILE YOU WORK
 
-  loadout route <describe a task>   which model tier fits, and what it costs
-  loadout route --conserve <task>   cheaper tiers when you are low on quota
-  loadout handoff send codex "..."  give a task to your other agent
+  loadout route                     your model policy: hard / normal / cheap
+  loadout route <describe a task>   which of those it looks like, and what to use
+  loadout handoff codex "..."       give a task to your other agent
 
 USE IT INSIDE YOUR AGENT