cue-ai 0.9.0 → 0.9.2

package/src/commands/shell.test.ts

@@ -1,9 +1,9 @@
 import { describe, expect, test, beforeEach, afterEach } from "bun:test";
-import { mkdtemp, readFile, rm, mkdir, stat } from "node:fs/promises";
+import { mkdtemp, readFile, writeFile, rm, mkdir, stat, chmod } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import { runInstall, runUninstall } from "./shell";
+import { runInstall, runUninstall, shimInstalled, resolveCueInvocation } from "./shell";
 
 let fakeHome: string;
 beforeEach(async () => {
@@ -22,10 +22,13 @@ describe("shell install", () => {
     });
     expect(rc).toBe(0);
 
+    // Assert on `launch <agent>` (present in both the bare and absolute-path
+    // shim forms) rather than the exact invocation token, which depends on
+    // whether `cue` is resolvable on the test runner's PATH.
     const claudeShim = await readFile(join(fakeHome, ".local", "bin", "claude"), "utf8");
-    expect(claudeShim).toContain("exec cue launch claude");
+    expect(claudeShim).toContain("launch claude");
     const codexShim = await readFile(join(fakeHome, ".local", "bin", "codex"), "utf8");
-    expect(codexShim).toContain("exec cue launch codex");
+    expect(codexShim).toContain("launch codex");
 
     const st = await stat(join(fakeHome, ".local", "bin", "claude"));
     expect((st.mode & 0o111) !== 0).toBe(true); // executable
@@ -53,3 +56,61 @@ describe("shell install", () => {
     await expect(stat(join(fakeHome, ".local", "bin", "claude"))).rejects.toThrow();
   });
 });
+
+describe("shimInstalled", () => {
+  const shimPath = () => join(fakeHome, ".local", "bin", "claude");
+
+  test("false when no shim exists", () => {
+    expect(shimInstalled(fakeHome)).toBe(false);
+  });
+
+  test("true for the runInstall() bare format (exec cue launch claude)", async () => {
+    await writeFile(shimPath(), '#!/usr/bin/env bash\nexec cue launch claude "$@"\n');
+    expect(shimInstalled(fakeHome)).toBe(true);
+  });
+
+  test("true for the `cue shell install` absolute-path format", async () => {
+    // This is the exact format run(["install"]) writes — the case the original
+    // `cue launch` substring check false-negatived on.
+    await writeFile(shimPath(), '#!/usr/bin/env bash\nexec "/home/u/Documents/cue/bin/cue" launch claude "$@"\n');
+    expect(shimInstalled(fakeHome)).toBe(true);
+  });
+
+  test("false for a non-cue claude on PATH", async () => {
+    await writeFile(shimPath(), '#!/usr/bin/env bash\nexec /opt/anthropic/claude "$@"\n');
+    expect(shimInstalled(fakeHome)).toBe(false);
+  });
+});
+
+describe("resolveCueInvocation", () => {
+  test("returns bare `cue` when an executable cue is resolvable on PATH (npm-global case)", async () => {
+    const binDir = join(fakeHome, "pathbin");
+    await mkdir(binDir, { recursive: true });
+    await writeFile(join(binDir, "cue"), "#!/bin/sh\n");
+    await chmod(join(binDir, "cue"), 0o755);
+    expect(resolveCueInvocation({ pathDirs: [binDir] })).toBe("cue");
+  });
+
+  test("ignores a non-executable cue on PATH and falls back to the abspath", async () => {
+    const binDir = join(fakeHome, "pathbin2");
+    await mkdir(binDir, { recursive: true });
+    await writeFile(join(binDir, "cue"), "not executable\n"); // no chmod +x
+    const repoRoot = join(fakeHome, "repo2");
+    await mkdir(join(repoRoot, "bin"), { recursive: true });
+    await writeFile(join(repoRoot, "bin", "cue"), "#!/usr/bin/env bun\n");
+    const out = resolveCueInvocation({ pathDirs: [binDir], repoRoot });
+    expect(out).toBe(`"${join(repoRoot, "bin", "cue")}"`);
+  });
+
+  test("falls back to a quoted absolute path when cue is not on PATH (source clone)", async () => {
+    const repoRoot = join(fakeHome, "repo");
+    await mkdir(join(repoRoot, "bin"), { recursive: true });
+    await writeFile(join(repoRoot, "bin", "cue"), "#!/usr/bin/env bun\n");
+    const emptyDir = join(fakeHome, "empty");
+    await mkdir(emptyDir, { recursive: true });
+    const out = resolveCueInvocation({ pathDirs: [emptyDir], repoRoot });
+    expect(out).toBe(`"${join(repoRoot, "bin", "cue")}"`);
+    // Either form must keep the `launch claude` substring intact downstream.
+    expect(`exec ${out} launch claude "$@"`).toContain("launch claude");
+  });
+});

package/src/commands/shell.ts

@@ -6,10 +6,22 @@
  * Adds a cd wrapper that checks .cue-profile on directory change.
  */
 
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync, statSync, accessSync, constants } from "node:fs";
 import { join, resolve } from "node:path";
 import { homedir } from "node:os";
 
+/** True when `p` is an executable regular file (mirrors how the shell resolves
+ * a command on PATH — skips directories and non-executable files). */
+function isExecutableFile(p: string): boolean {
+  try {
+    if (!statSync(p).isFile()) return false;
+    accessSync(p, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function hookBash(): string {
   return `# cue shell hook — auto-switch profile on cd
 __cue_cd() {
@@ -92,6 +104,52 @@ export interface ShimOptions {
   realCodex?: string;
 }
 
+/**
+ * True when the `claude` shim is already installed in ~/.local/bin and is a
+ * cue launch shim. Matches both shim formats cue writes: the user-facing
+ * `cue shell install` form (`exec "<abs-path>/cue" launch claude "$@"`) and the
+ * runInstall() helper form (`exec cue launch claude "$@"`) — both contain the
+ * literal `launch claude`. Used by `cue init` to detect that profile loading
+ * hasn't been activated yet. Conservative: any read error → false.
+ */
+export function shimInstalled(homeDir?: string): boolean {
+  const shimPath = join(homeDir ?? homedir(), ".local", "bin", "claude");
+  try {
+    return existsSync(shimPath) && readFileSync(shimPath, "utf8").includes("launch claude");
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve the token to place after `exec ` in a shim so it works for BOTH
+ * npm-global installs (cue is on PATH, there is no source clone) and
+ * source-clone users.
+ *
+ * - Prefers the portable bare `cue` when it's resolvable on PATH (the
+ *   npm-global-correct form, and the form the docs advertise).
+ * - Otherwise falls back to an absolute path to the cue entrypoint
+ *   (CUE_REPO_ROOT is exported by both `bin/cue` and `bin/cue.mjs` when cue
+ *   runs itself), double-quoted for the shell.
+ *
+ * Either form keeps the literal `launch <agent>` substring the caller
+ * appends, so shimInstalled() detects both. Previously `cue shell install`
+ * hard-coded `~/Documents/cue/bin/cue`, which doesn't exist for npm-global
+ * users — the shim pointed at a missing file and `claude` broke.
+ */
+export function resolveCueInvocation(opts: { repoRoot?: string; pathDirs?: string[] } = {}): string {
+  const pathDirs = opts.pathDirs ?? (process.env.PATH ?? "").split(":").filter(Boolean);
+  for (const dir of pathDirs) {
+    if (dir && isExecutableFile(join(dir, "cue"))) return "cue";
+  }
+  // Prefer the node entrypoint (npm layout) then the bash one, then ~/Documents.
+  const root = opts.repoRoot ?? process.env.CUE_REPO_ROOT ?? join(homedir(), "Documents", "cue");
+  for (const candidate of [join(root, "bin", "cue.mjs"), join(root, "bin", "cue")]) {
+    if (existsSync(candidate)) return `"${candidate}"`;
+  }
+  return `"${process.argv[1] ?? "cue"}"`;
+}
+
 export async function runInstall(opts: ShimOptions = {}): Promise<number> {
   const home = opts.homeDir ?? homedir();
   const shimDir = join(home, ".local", "bin");
@@ -111,14 +169,14 @@ export async function runInstall(opts: ShimOptions = {}): Promise<number> {
   }
 
   mkdirSync(shimDir, { recursive: true });
-  const cueBin = resolve(process.env.CUE_REPO_ROOT ?? join(home, "Documents", "cue"), "bin", "cue");
+  const cueInvoke = resolveCueInvocation();
 
-  const claudeShim = `#!/usr/bin/env bash\nexec cue launch claude "$@"\n`;
+  const claudeShim = `#!/usr/bin/env bash\nexec ${cueInvoke} launch claude "$@"\n`;
   writeFileSync(join(shimDir, "claude"), claudeShim);
   chmodSync(join(shimDir, "claude"), 0o755);
 
   if (opts.realCodex) {
-    const codexShim = `#!/usr/bin/env bash\nexec cue launch codex "$@"\n`;
+    const codexShim = `#!/usr/bin/env bash\nexec ${cueInvoke} launch codex "$@"\n`;
     writeFileSync(join(shimDir, "codex"), codexShim);
     chmodSync(join(shimDir, "codex"), 0o755);
   }
@@ -161,11 +219,13 @@ export async function run(args: string[]): Promise<number> {
     const { mkdirSync, writeFileSync, chmodSync } = await import("node:fs");
     mkdirSync(shimDir, { recursive: true });
 
-    const cueBin = resolve(process.env.CUE_REPO_ROOT ?? join(homedir(), "Documents", "cue"), "bin", "cue");
+    // Portable invocation token: bare `cue` when on PATH (npm-global), else
+    // an absolute path to the cue entrypoint. See resolveCueInvocation.
+    const cueInvoke = resolveCueInvocation();
 
     // Claude shim
     const claudeShim = `#!/usr/bin/env bash
-exec "${cueBin}" launch claude "$@"
+exec ${cueInvoke} launch claude "$@"
 `;
     writeFileSync(join(shimDir, "claude"), claudeShim);
     chmodSync(join(shimDir, "claude"), 0o755);
@@ -174,7 +234,7 @@ exec "${cueBin}" launch claude "$@"
     // Codex shim (optional)
     if (args.includes("--codex")) {
       const codexShim = `#!/usr/bin/env bash
-exec "${cueBin}" launch codex "$@"
+exec ${cueInvoke} launch codex "$@"
 `;
       writeFileSync(join(shimDir, "codex"), codexShim);
       chmodSync(join(shimDir, "codex"), 0o755);

package/src/commands/skills-test.ts

@@ -65,7 +65,6 @@ function loadTestCases(skillId: string): TestCase[] {
 function runTest(skillId: string, testCase: TestCase): TestResult {
   const skillPath = join(SKILLS_ROOT, skillId, "SKILL.md");
   const skillContent = existsSync(skillPath) ? readFileSync(skillPath, "utf8").toLowerCase() : "";
-  const input = testCase.input.toLowerCase();
   const failures: string[] = [];
 
   // Check: does the skill description match the input context?

package/src/commands/skills.ts

@@ -23,6 +23,7 @@ import { listProfiles, loadProfile } from "../lib/profile-loader";
 import { resolveActiveProfile } from "../lib/cwd-resolver";
 import { listAllSkillIds } from "../lib/resolver-local";
 import { fetchCompanionFiles, readSourceFile, findIncompleteSkills } from "../lib/companion-fetch";
+import { gateFreshSkill } from "./security";
 
 const REPO_ROOT = process.env.CUE_REPO_ROOT ?? process.env.SOUL_REPO_ROOT ?? resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
 const PROFILES_DIR = process.env.CUE_PROFILES_DIR ?? join(REPO_ROOT, "profiles");
@@ -442,7 +443,9 @@ async function cmdNpxAdd(args: string[]): Promise<number> {
   const repo = addArgs.find((a) => !a.startsWith("-") && !["claude-code", "codex", "*"].includes(a));
 
   // #6: If -y/--yes without --skill, inject --skill "*" to skip npx's interactive picker
-  const passedArgs = [...args];
+  // (strip our own --allow-unsafe so it isn't forwarded to `npx skills add`).
+  const allowUnsafe = args.includes("--allow-unsafe");
+  const passedArgs = args.filter((a) => a !== "--allow-unsafe");
   const hasYes = passedArgs.includes("-y") || passedArgs.includes("--yes");
   const hasSkill = passedArgs.includes("-s") || passedArgs.includes("--skill");
   if (hasYes && !hasSkill) {
@@ -491,6 +494,30 @@ async function cmdNpxAdd(args: string[]): Promise<number> {
   // If still nothing, the install was likely cancelled — don't trigger hook
   if (newSkills.length === 0) return 0;
 
+  // Security gate: scan freshly-fetched skills before the profile hook below
+  // registers any into profile.yaml. Block criticals (SEC1-3) unless
+  // --allow-unsafe; flagged skills stay on disk but are dropped from the set.
+  {
+    const blocked: string[] = [];
+    for (const slug of newSkills) {
+      const gate = gateFreshSkill(slug, { allowUnsafe });
+      if (!gate.ok) {
+        blocked.push(slug);
+        process.stderr.write(`🔴 BLOCKED ${slug}: ${gate.critical.length} critical security finding(s)\n`);
+        for (const c of gate.critical) {
+          process.stderr.write(`   [${c.code}] ${c.message}${c.line ? ` (line ${c.line})` : ""}\n`);
+        }
+      } else if (!gate.scanned) {
+        process.stderr.write(`⚠️  ${slug}: no SKILL.md found to scan — review manually.\n`);
+      }
+    }
+    if (blocked.length > 0) {
+      newSkills = newSkills.filter((s) => !blocked.includes(s));
+      process.stderr.write(`   ${blocked.length} skill(s) left on disk but NOT registered. Re-run with --allow-unsafe to register anyway.\n`);
+      if (newSkills.length === 0) return 1;
+    }
+  }
+
   // #7: Fetch GitHub repo description
   let repoDescription = "";
   if (repo) {
@@ -1525,7 +1552,6 @@ function cmdChangelog(id: string): number {
     return 1;
   }
 
-  const meta = parseSkillMeta(id);
   const skillPath = join(SKILLS_ROOT, id, "SKILL.md");
   try {
     const content = readFileSync(skillPath, "utf8");

package/src/commands/sources.ts

@@ -17,7 +17,6 @@ import { loadProfile, listProfiles } from "../lib/profile-loader";
 
 const REPO_ROOT = process.env.CUE_REPO_ROOT ?? process.env.SOUL_REPO_ROOT ?? resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
 const SKILLS_LOCK = join(homedir(), "skills-lock.json");
-const CLAUDE_SKILLS_DIR = join(homedir(), ".claude", "skills");
 
 interface LockEntry {
   source: string;
@@ -97,7 +96,7 @@ function cmdList(json: boolean): number {
 async function cmdProfile(profileName: string, json: boolean): Promise<number> {
   const lock = loadSkillsLock();
   let profile;
-  try { profile = await loadProfile(profileName); } catch (e) {
+  try { profile = await loadProfile(profileName); } catch {
     process.stderr.write(`Profile "${profileName}" not found.\n`);
     return 1;
   }

package/src/commands/status.ts

@@ -6,9 +6,10 @@
 
 import { homedir } from "node:os";
 import { join, resolve, dirname } from "node:path";
-import { existsSync, readFileSync, readdirSync, lstatSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, } from "node:fs";
 import { fileURLToPath } from "node:url";
 
+import { configDir } from "../lib/config-paths";
 import { resolveProfileForCwd } from "../lib/cwd-resolver";
 import { loadProfile, listProfiles } from "../lib/profile-loader";
 import { computeStats } from "../lib/analytics";
@@ -19,11 +20,6 @@ const SKILLS_ROOT = join(REPO_ROOT, "resources", "skills", "skills");
 const MCP_CONFIGS_DIR = join(REPO_ROOT, "resources", "mcps", "configs");
 const RUNTIME_ROOT = join(process.env.HOME ?? "~", ".config", "cue", "runtime");
 
-function configDir(): string {
-  return process.env.XDG_CONFIG_HOME
-    ? join(process.env.XDG_CONFIG_HOME, "cue")
-    : join(homedir(), ".config", "cue");
-}
 
 export interface Warning {
   code: string;

package/src/commands/submit-profile.ts

@@ -13,7 +13,7 @@
 
 import { existsSync, mkdtempSync, mkdirSync, copyFileSync, readFileSync } from "node:fs";
 import { tmpdir, homedir } from "node:os";
-import { join, basename, resolve } from "node:path";
+import { join, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
 
 import { parse as parseYaml } from "yaml";

package/src/commands/suggest.ts

@@ -11,7 +11,7 @@ import { join, resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 
-import { loadProfile, listProfiles } from "../lib/profile-loader";
+import { loadProfile, } from "../lib/profile-loader";
 import { listAllSkillIds } from "../lib/resolver-local";
 import { resolveProfileForCwd } from "../lib/cwd-resolver";
 
@@ -131,33 +131,58 @@ function tokenizeText(text: string): string[] {
   return text.toLowerCase().replace(/[^a-z0-9\s-]/g, " ").split(/\s+/).filter(t => t.length > 2);
 }
 
+// Bound the session scan so `cue suggest` stays fast regardless of how large
+// the user's history is: read the most-recent transcripts first, up to a file
+// and total-byte budget. Without this, a heavy user's ~/.claude/projects (many
+// large .jsonl files) makes both this scan and scoreSkills run for minutes.
+// `CUE_SUGGEST_SESSIONS_DIR` overrides the source dir (tests use it to stay
+// hermetic). Transcripts beyond the budget are skipped — recent sessions are
+// the relevant signal anyway.
+const MAX_SESSION_FILES = 100;
+const MAX_SESSION_BYTES = 2_000_000;
+const PER_FILE_BYTES = 100_000;
+
 function scanSessions(cutoffMs: number): string[] {
-  const projectsDir = join(homedir(), ".claude", "projects");
+  const projectsDir = process.env.CUE_SUGGEST_SESSIONS_DIR ?? join(homedir(), ".claude", "projects");
   if (!existsSync(projectsDir)) return [];
 
-  const chunks: string[] = [];
+  // Collect candidate transcripts newer than the cutoff, with mtime for ranking.
+  const candidates: Array<{ path: string; mtimeMs: number }> = [];
   try {
     const dirs = readdirSync(projectsDir).filter(d => {
       try { return statSync(join(projectsDir, d)).isDirectory(); } catch { return false; }
     });
     for (const dir of dirs) {
       const dirPath = join(projectsDir, dir);
-      const files = readdirSync(dirPath).filter(f => f.endsWith(".jsonl"));
+      let files: string[];
+      try { files = readdirSync(dirPath).filter(f => f.endsWith(".jsonl")); } catch { continue; }
       for (const f of files) {
         const fPath = join(dirPath, f);
         try {
           const st = statSync(fPath);
           if (st.mtimeMs < cutoffMs) continue;
-          // Read first 100KB of each file
-          const fd = require("node:fs").openSync(fPath, "r");
-          const buf = Buffer.alloc(100_000);
-          const n = require("node:fs").readSync(fd, buf, 0, 100_000, 0);
-          require("node:fs").closeSync(fd);
-          chunks.push(buf.toString("utf8", 0, n));
+          candidates.push({ path: fPath, mtimeMs: st.mtimeMs });
         } catch {}
       }
     }
   } catch {}
+
+  // Most-recent first, then read up to the file/byte budget.
+  candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  const fs = require("node:fs");
+  const chunks: string[] = [];
+  let total = 0;
+  for (const { path: fPath } of candidates) {
+    if (chunks.length >= MAX_SESSION_FILES || total >= MAX_SESSION_BYTES) break;
+    try {
+      const fd = fs.openSync(fPath, "r");
+      const buf = Buffer.alloc(PER_FILE_BYTES);
+      const n = fs.readSync(fd, buf, 0, PER_FILE_BYTES, 0);
+      fs.closeSync(fd);
+      chunks.push(buf.toString("utf8", 0, n));
+      total += n;
+    } catch {}
+  }
   return chunks;
 }
 

package/src/commands/trigger-gaps.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { collectUserPrompts } from "./trigger-gaps";
+
+describe("collectUserPrompts budget (guards the dashboard-hang fix)", () => {
+  function fixture(promptCount = 50): string {
+    const root = mkdtempSync(join(tmpdir(), "cue-tg-"));
+    const proj = join(root, "proj-a");
+    mkdirSync(proj);
+    const lines = Array.from({ length: promptCount }, (_, i) =>
+      JSON.stringify({ type: "user", message: { role: "user", content: `prompt ${i}` } }));
+    writeFileSync(join(proj, "session.jsonl"), lines.join("\n"));
+    return root;
+  }
+
+  test("maxPrompts caps how many prompts are collected", () => {
+    const root = fixture(50);
+    try {
+      expect(collectUserPrompts(9999, root, { maxPrompts: 5 }).length).toBe(5);
+    } finally { rmSync(root, { recursive: true, force: true }); }
+  });
+
+  test("maxBytes stops reading once the budget is exhausted", () => {
+    const root = fixture(50);
+    try {
+      // 1-byte budget reads at most the first (newest) file's prompts, never more
+      // than one file's worth — here there's a single file, so all 50, but a
+      // 0-byte-ish cap still returns the first file then stops (no unbounded walk).
+      const out = collectUserPrompts(9999, root, { maxBytes: 1 });
+      expect(out.length).toBeLessThanOrEqual(50);
+      expect(out.length).toBeGreaterThan(0);
+    } finally { rmSync(root, { recursive: true, force: true }); }
+  });
+
+  test("unbounded default still collects every in-window prompt", () => {
+    const root = fixture(50);
+    try {
+      const out = collectUserPrompts(9999, root);
+      expect(out.length).toBe(50);
+      expect(out).toContain("prompt 0");
+    } finally { rmSync(root, { recursive: true, force: true }); }
+  });
+
+  test("missing root returns empty, never throws", () => {
+    expect(collectUserPrompts(30, join(tmpdir(), "cue-does-not-exist-xyz"))).toEqual([]);
+  });
+});

package/src/commands/trigger-gaps.ts

@@ -89,10 +89,33 @@ function resolveActiveProfile(explicit: string | null): string | null {
  * each line is a message-shape object; we read defensively because the
  * shape can vary by Claude Code version.
  */
-export function collectUserPrompts(sinceDays: number, root = PROJECTS_ROOT): string[] {
+/**
+ * Bound the transcript scan so a large `~/.claude/projects/` (GBs of JSONL on
+ * an active machine) can't peg CPU / balloon memory / block the dashboard's
+ * single event loop. The detector is a recency heuristic, so reading the NEWEST
+ * transcripts under a byte + prompt budget keeps the signal while capping cost.
+ */
+export interface CollectOpts {
+  /** Max transcript bytes to read (newest-first). Default 32 MB. */
+  maxBytes?: number;
+  /** Max prompts to collect. Default 20,000. */
+  maxPrompts?: number;
+}
+
+export function collectUserPrompts(
+  sinceDays: number,
+  root = PROJECTS_ROOT,
+  opts: CollectOpts = {},
+): string[] {
+  const maxBytes = opts.maxBytes ?? 32 * 1024 * 1024;
+  const maxPrompts = opts.maxPrompts ?? 20_000;
   if (!existsSync(root)) return [];
   const cutoff = Date.now() - sinceDays * 24 * 60 * 60 * 1000;
-  const prompts: string[] = [];
+
+  // Gather in-window candidate files first, then read NEWEST-first under the
+  // budget — so when there's more history than the cap allows, we keep the most
+  // recent prompts (the ones that matter for "what should be firing lately").
+  const candidates: { fp: string; mt: number; size: number }[] = [];
   let dirs: string[] = [];
   try { dirs = readdirSync(root); } catch { return []; }
   for (const dir of dirs) {
@@ -104,35 +127,46 @@ export function collectUserPrompts(sinceDays: number, root = PROJECTS_ROOT): str
     try { files = readdirSync(dirPath).filter((f) => f.endsWith(".jsonl")); } catch { continue; }
     for (const f of files) {
       const fp = join(dirPath, f);
-      let mt = 0;
-      try { mt = statSync(fp).mtimeMs; } catch { continue; }
-      if (mt < cutoff) continue;
-      let raw = "";
-      try { raw = readFileSync(fp, "utf8"); } catch { continue; }
-      for (const line of raw.split("\n")) {
-        if (!line.trim()) continue;
-        try {
-          const msg = JSON.parse(line) as {
-            type?: string;
-            role?: string;
-            message?: { role?: string; content?: unknown };
-            content?: unknown;
-          };
-          // Claude Code shape: { type: "user", message: { role: "user", content: "..." } }
-          const role = msg.role ?? msg.message?.role ?? msg.type;
-          if (role !== "user") continue;
-          const content = msg.message?.content ?? msg.content;
-          if (typeof content === "string") {
-            prompts.push(content);
-          } else if (Array.isArray(content)) {
-            for (const part of content) {
-              if (part && typeof part === "object" && "text" in part && typeof part.text === "string") {
-                prompts.push(part.text);
-              }
+      try {
+        const st = statSync(fp);
+        if (st.mtimeMs < cutoff) continue;
+        candidates.push({ fp, mt: st.mtimeMs, size: st.size });
+      } catch { /* unreadable — skip */ }
+    }
+  }
+  candidates.sort((a, b) => b.mt - a.mt);
+
+  const prompts: string[] = [];
+  let bytesRead = 0;
+  for (const c of candidates) {
+    if (bytesRead >= maxBytes || prompts.length >= maxPrompts) break;
+    bytesRead += c.size;
+    let raw = "";
+    try { raw = readFileSync(c.fp, "utf8"); } catch { continue; }
+    for (const line of raw.split("\n")) {
+      if (prompts.length >= maxPrompts) break;
+      if (!line.trim()) continue;
+      try {
+        const msg = JSON.parse(line) as {
+          type?: string;
+          role?: string;
+          message?: { role?: string; content?: unknown };
+          content?: unknown;
+        };
+        // Claude Code shape: { type: "user", message: { role: "user", content: "..." } }
+        const role = msg.role ?? msg.message?.role ?? msg.type;
+        if (role !== "user") continue;
+        const content = msg.message?.content ?? msg.content;
+        if (typeof content === "string") {
+          prompts.push(content);
+        } else if (Array.isArray(content)) {
+          for (const part of content) {
+            if (part && typeof part === "object" && "text" in part && typeof part.text === "string") {
+              prompts.push(part.text);
             }
           }
-        } catch { /* skip malformed */ }
-      }
+        }
+      } catch { /* skip malformed */ }
     }
   }
   return prompts;

package/src/commands/update.ts

@@ -3,7 +3,7 @@
  */
 
 import { spawnSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, } from "node:fs";
 import { resolve, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 

package/src/commands/validate.ts

@@ -19,6 +19,7 @@ const RESET = "\x1b[0m";
 interface ParsedArgs {
   all: boolean;
   profile?: string;
+  online: boolean;
 }
 
 export async function run(args: string[]): Promise<number> {
@@ -33,9 +34,14 @@ export async function run(args: string[]): Promise<number> {
     return 1;
   }
 
+  // Offline by default: the npx fetchability check otherwise does one network
+  // `npx skills add` spawn per skill (thousands across --all, no cache), which
+  // hangs for minutes. `--online` opts back into the real fetch. An explicit
+  // CUE_OFFLINE=1 always wins (enforced inside the linter).
+  const lintOpts = { npxOffline: !parsed.online };
   const results = parsed.all
-    ? await lintAllProfiles()
-    : [await lintProfile(parsed.profile!)];
+    ? await lintAllProfiles(lintOpts)
+    : [await lintProfile(parsed.profile!, lintOpts)];
 
   if (parsed.all && results.length === 0) {
     process.stdout.write("No profiles found in profiles/.\n");
@@ -55,16 +61,17 @@ function parseArgs(args: string[]): ParsedArgs | "help" | string {
   if (args.includes("-h") || args.includes("--help")) return "help";
 
   const all = args.includes("--all");
+  const online = args.includes("--online") || args.includes("--no-offline");
   const positional = args.filter((arg) => !arg.startsWith("-"));
 
   if (all && positional.length > 0) {
     return "cue validate: use either --all or <profile>, not both";
   }
-  if (all) return { all: true };
+  if (all) return { all: true, online };
   if (positional.length !== 1) {
     return "cue validate: expected exactly one <profile>";
   }
-  return { all: false, profile: positional[0] };
+  return { all: false, profile: positional[0], online };
 }
 
 function printHelp(stream: Pick<NodeJS.WriteStream, "write"> = process.stdout): void {
@@ -78,6 +85,11 @@ function printHelp(stream: Pick<NodeJS.WriteStream, "write"> = process.stdout):
       "  schema validity, inheritance, local/npx/plugin skill resolution, MCP registry resolution",
       "  W1-W5 warnings and E1-E3 lint errors",
       "",
+      "Options:",
+      "  --online   Fetch uncached npx skills over the network (one `npx skills add`",
+      "             per skill). Default is offline: uncached npx skills are reported",
+      "             as 'not cached', not errors — keeps `--all` fast and hang-free.",
+      "",
     ].join("\n"),
   );
 }

package/src/commands/watch-live.ts

@@ -5,7 +5,7 @@
  * On change: re-runs materialization with 500ms debounce.
  */
 
-import { watch, existsSync, readFileSync } from "node:fs";
+import { watch, existsSync, } from "node:fs";
 import { resolve, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 

package/src/commands/workspace.ts

@@ -15,7 +15,7 @@
  */
 
 import * as p from "@clack/prompts";
-import { existsSync, readFileSync, writeFileSync, appendFileSync, mkdirSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, appendFileSync, } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { resolveProfileForCwd } from "../lib/cwd-resolver";