little-coder 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to little-coder are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and little-coder's public interface (CLI, providers, tools, skills) follows semver starting at `v0.0.1` post-rename.
 
+## [v1.0.2] — 2026-04-28
+
+### Changed
+- README order: **Install**, **Run**, and **Local model setup** now lead the doc (right after "How it relates to pi"), with **Paper / benchmark results** and **Roadmap** moved below. New users hit the install command first instead of scrolling past benchmark tables.
+
+---
+
+## [v1.0.1] — 2026-04-28
+
+### Added
+- **Update check on startup.** When a newer `little-coder` is on npm, the launcher tells you and (in interactive mode) offers to update on the spot.
+  - **Interactive TTY:** prompt `Update now? [Y/n]` — Enter or `y` runs `npm install -g little-coder@latest` and asks you to re-run; `n` skips for this session.
+  - **Non-TTY (CI, scripts, pipes, `--print` pipelines):** prints a one-line stderr notice with the install command, never prompts.
+  - **Skipped automatically** for `--help`, `--version`, `--list-models`, `--export`, `--mode rpc`, `--mode json`, when `CI=true`, and for the new `--no-update-check` flag / `LITTLE_CODER_NO_UPDATE_CHECK=1` env opt-out.
+  - **Cached** at `${XDG_CACHE_HOME:-~/.cache}/little-coder/version-check.json` with a 12 h TTL — at most one network call per day.
+  - **Best-effort:** 2 s fetch timeout, all errors swallowed silently. Update check never blocks the agent if the registry is slow or unreachable.
+
+---
+
 ## [v1.0.0] — 2026-04-28
 
 Distribution + stability release. Hi everywhere, bye `./node_modules/.bin/pi`.

package/README.md

@@ -12,37 +12,6 @@ little-coder is **pi + 20 extensions + 30 skill markdown files + a Python benchm
 
 If you've never used pi, it's useful to skim [pi.dev](https://pi.dev) first — the rest of this doc assumes pi's model of `--agent-import-path`, `--mode rpc`, and `.pi/extensions/` auto-discovery.
 
-## Paper / benchmark results
-
-| Release | Model | Benchmark | Result |
-|---|---|---|---|
-| [**v0.0.2**](https://github.com/itayinbarr/little-coder/releases/tag/v0.0.2) (commit `1d62bde`) — the paper | Qwen3.5-9B via Ollama | Aider Polyglot (225 exercises) | **45.56 %** mean of two runs; matched-model vanilla Aider baseline 19.11 %. Paper: [*Honey, I Shrunk the Coding Agent* on Substack](https://open.substack.com/pub/itayinbarr/p/honey-i-shrunk-the-coding-agent). |
-| [**v0.0.5**](https://github.com/itayinbarr/little-coder/releases/tag/v0.0.5) — pre-pi Python | Qwen3.6-35B-A3B via llama.cpp | Aider Polyglot | **78.67 %**. [Full narrative](docs/benchmark-qwen3.6-35b-a3b.md). |
-| [**v0.1.4**](https://github.com/itayinbarr/little-coder/releases/tag/v0.1.4) — on pi | Qwen3.6-35B-A3B via llama.cpp | Terminal-Bench-Core v0.1.1 (80 tasks) | **40.0 %** in 6 h 50 min. [Write-up](docs/benchmark-terminal-bench-v0.1.1.md). |
-| [**v0.1.13**](https://github.com/itayinbarr/little-coder/releases/tag/v0.1.13) — on pi, TB 2.0 leaderboard | Qwen3.6-35B-A3B via llama.cpp | Terminal-Bench 2.0 (89 tasks × 5 trials = 445) | **23.82 %** (106 / 445). [PR #158](https://huggingface.co/datasets/harborframework/terminal-bench-2-leaderboard/discussions/158) — awaiting maintainer merge. |
-| [**v0.1.24**](https://github.com/itayinbarr/little-coder/releases/tag/v0.1.24) — on pi, TB 2.0 leaderboard, smaller model | Qwen3.5-9B (Q4_K_M) via llama.cpp (5.3 GB on GPU, 2× faster per-token than the 35B-A3B) | Terminal-Bench 2.0 (89 tasks × 5 trials = 445) | **9.21 %** (41 / 445). [PR #163](https://huggingface.co/datasets/harborframework/terminal-bench-2-leaderboard/discussions/163) — awaiting maintainer merge. |
-| [**v0.1.27**](https://github.com/itayinbarr/little-coder/releases/tag/v0.1.27) — on pi, GAIA validation | Qwen3.6-35B-A3B via llama.cpp | GAIA validation set (165 tasks) | **40.00 %** (66 / 165). L1 60.4 % / L2 37.2 % / L3 7.7 %. Test-split run pending. |
-
-All runs used a consumer laptop: i9-14900HX, 32 GB RAM, **8 GB VRAM** on RTX 5070 Laptop (Blackwell). No cloud inference at any point.
-
----
-
-## Roadmap
-
-The near-term focus is **benchmarking**, not new features. The paper established that scaffold–model fit moves a 9.7 B model from 19 % to 45 % on Aider Polyglot. The open question is: **how wide is the impact radius?** Does the same set of adaptations — Write-vs-Edit invariant, per-turn skill injection, thinking-budget cap, output-repair, quality monitor — help on tasks that *aren't* self-contained coding exercises? What breaks? What compounds?
-
-The plan is to establish a wide baseline before any further scaffolding changes:
-
-1. **Aider Polyglot** — done. 45.56 % (paper, Qwen3.5-9B) and 78.67 % (v0.0.5, Qwen3.6-35B-A3B).
-2. **Terminal-Bench-Core v0.1.1** — done. 40.0 % (v0.1.4).
-3. **Terminal-Bench 2.0** — done. Qwen3.6-35B-A3B at **23.82 %** ([PR #158](https://huggingface.co/datasets/harborframework/terminal-bench-2-leaderboard/discussions/158)) and Qwen3.5-9B at **9.21 %** ([PR #163](https://huggingface.co/datasets/harborframework/terminal-bench-2-leaderboard/discussions/163)), both awaiting maintainer merge. The v0.1.24 prompt-repetition fix (re-add tool descriptions + concision guideline, validated by a 4 / 4 pilot on the previously-regressing `prove-plus-comm` task) was the prompt for both submissions.
-4. **GAIA** — validation set done at v0.1.27: **40.00 %** (66 / 165) on Qwen3.6-35B-A3B. Per-level L1 60.4 % / L2 37.2 % / L3 7.7 %. Test-split run (301 tasks) pending → leaderboard submission to follow.
-5. **SWE-bench Verified** — after GAIA. Multi-file real-world patches; the longest-horizon test of whether the scaffolding generalizes past exercise-scale tasks.
-
-**After that baseline is in place**, the next phase starts: improvement experiments targeted at the specific failure patterns we've seen (thinking-budget / quality-monitor behavior on long-horizon tasks, deliberate.py-style parallel branches on failure, better shell-session recovery for interactive-process traps). No scaffold changes until the data says which ones are worth running.
-
----
-
 ## Install
 
 One-line install (Node.js 20.6+ required):
@@ -122,6 +91,37 @@ All small-model-specific extensions auto-disable for large/cloud models so they
 
 ---
 
+## Paper / benchmark results
+
+| Release | Model | Benchmark | Result |
+|---|---|---|---|
+| [**v0.0.2**](https://github.com/itayinbarr/little-coder/releases/tag/v0.0.2) (commit `1d62bde`) — the paper | Qwen3.5-9B via Ollama | Aider Polyglot (225 exercises) | **45.56 %** mean of two runs; matched-model vanilla Aider baseline 19.11 %. Paper: [*Honey, I Shrunk the Coding Agent* on Substack](https://open.substack.com/pub/itayinbarr/p/honey-i-shrunk-the-coding-agent). |
+| [**v0.0.5**](https://github.com/itayinbarr/little-coder/releases/tag/v0.0.5) — pre-pi Python | Qwen3.6-35B-A3B via llama.cpp | Aider Polyglot | **78.67 %**. [Full narrative](docs/benchmark-qwen3.6-35b-a3b.md). |
+| [**v0.1.4**](https://github.com/itayinbarr/little-coder/releases/tag/v0.1.4) — on pi | Qwen3.6-35B-A3B via llama.cpp | Terminal-Bench-Core v0.1.1 (80 tasks) | **40.0 %** in 6 h 50 min. [Write-up](docs/benchmark-terminal-bench-v0.1.1.md). |
+| [**v0.1.13**](https://github.com/itayinbarr/little-coder/releases/tag/v0.1.13) — on pi, TB 2.0 leaderboard | Qwen3.6-35B-A3B via llama.cpp | Terminal-Bench 2.0 (89 tasks × 5 trials = 445) | **23.82 %** (106 / 445). [PR #158](https://huggingface.co/datasets/harborframework/terminal-bench-2-leaderboard/discussions/158) — awaiting maintainer merge. |
+| [**v0.1.24**](https://github.com/itayinbarr/little-coder/releases/tag/v0.1.24) — on pi, TB 2.0 leaderboard, smaller model | Qwen3.5-9B (Q4_K_M) via llama.cpp (5.3 GB on GPU, 2× faster per-token than the 35B-A3B) | Terminal-Bench 2.0 (89 tasks × 5 trials = 445) | **9.21 %** (41 / 445). [PR #163](https://huggingface.co/datasets/harborframework/terminal-bench-2-leaderboard/discussions/163) — awaiting maintainer merge. |
+| [**v0.1.27**](https://github.com/itayinbarr/little-coder/releases/tag/v0.1.27) — on pi, GAIA validation | Qwen3.6-35B-A3B via llama.cpp | GAIA validation set (165 tasks) | **40.00 %** (66 / 165). L1 60.4 % / L2 37.2 % / L3 7.7 %. Test-split run pending. |
+
+All runs used a consumer laptop: i9-14900HX, 32 GB RAM, **8 GB VRAM** on RTX 5070 Laptop (Blackwell). No cloud inference at any point.
+
+---
+
+## Roadmap
+
+The near-term focus is **benchmarking**, not new features. The paper established that scaffold–model fit moves a 9.7 B model from 19 % to 45 % on Aider Polyglot. The open question is: **how wide is the impact radius?** Does the same set of adaptations — Write-vs-Edit invariant, per-turn skill injection, thinking-budget cap, output-repair, quality monitor — help on tasks that *aren't* self-contained coding exercises? What breaks? What compounds?
+
+The plan is to establish a wide baseline before any further scaffolding changes:
+
+1. **Aider Polyglot** — done. 45.56 % (paper, Qwen3.5-9B) and 78.67 % (v0.0.5, Qwen3.6-35B-A3B).
+2. **Terminal-Bench-Core v0.1.1** — done. 40.0 % (v0.1.4).
+3. **Terminal-Bench 2.0** — done. Qwen3.6-35B-A3B at **23.82 %** ([PR #158](https://huggingface.co/datasets/harborframework/terminal-bench-2-leaderboard/discussions/158)) and Qwen3.5-9B at **9.21 %** ([PR #163](https://huggingface.co/datasets/harborframework/terminal-bench-2-leaderboard/discussions/163)), both awaiting maintainer merge. The v0.1.24 prompt-repetition fix (re-add tool descriptions + concision guideline, validated by a 4 / 4 pilot on the previously-regressing `prove-plus-comm` task) was the prompt for both submissions.
+4. **GAIA** — validation set done at v0.1.27: **40.00 %** (66 / 165) on Qwen3.6-35B-A3B. Per-level L1 60.4 % / L2 37.2 % / L3 7.7 %. Test-split run (301 tasks) pending → leaderboard submission to follow.
+5. **SWE-bench Verified** — after GAIA. Multi-file real-world patches; the longest-horizon test of whether the scaffolding generalizes past exercise-scale tasks.
+
+**After that baseline is in place**, the next phase starts: improvement experiments targeted at the specific failure patterns we've seen (thinking-budget / quality-monitor behavior on long-horizon tasks, deliberate.py-style parallel branches on failure, better shell-session recovery for interactive-process traps). No scaffold changes until the data says which ones are worth running.
+
+---
+
 ## Troubleshooting
 
 **`little-coder: command not found`** — npm's global bin directory isn't on your PATH. Run `npm config get prefix` to see where it installed; add `<prefix>/bin` to your PATH. Or reinstall with `sudo` if your prefix needs root.

package/bin/little-coder.mjs

@@ -4,9 +4,10 @@
 // custom extension wired in — works from any working directory.
 
 import { spawn } from "node:child_process";
-import { existsSync, readdirSync, statSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { checkForUpdate } from "./update-check.mjs";
 
 // ---- 1. Node version preflight (>= 20.6.0, matching pi.dev) ----
 const MIN_NODE = [20, 6, 0];
@@ -54,20 +55,37 @@ if (existsSync(extDir)) {
   }
 }
 
-// ---- 5. Compose pi argv ----
+// ---- 5. Update check (best-effort, blocks on TTY prompt only) ----
+let currentVersion = "0.0.0";
+try {
+  const pkgJson = JSON.parse(readFileSync(join(pkgRoot, "package.json"), "utf-8"));
+  if (typeof pkgJson?.version === "string") currentVersion = pkgJson.version;
+} catch {
+  // ignore — update-check just won't fire if we can't read the version
+}
+const exitAfterCheck = await checkForUpdate(currentVersion);
+if (exitAfterCheck) {
+  // Successful update happened; user needs to re-run the new binary.
+  process.exit(0);
+}
+
+// ---- 6. Compose pi argv ----
 // --no-context-files : ignore the user's AGENTS.md / CLAUDE.md so OURS wins
 // --no-extensions    : skip pi's auto-discovery from cwd; explicit -e flags still load
 // --system-prompt    : load <pkgRoot>/AGENTS.md regardless of cwd
+//
+// Strip our own flags before forwarding to pi so it doesn't reject them.
+const userArgs = process.argv.slice(2).filter((a) => a !== "--no-update-check");
 const agentsMd = join(pkgRoot, "AGENTS.md");
 const piArgs = [
   "--no-context-files",
   "--no-extensions",
   ...(existsSync(agentsMd) ? ["--system-prompt", agentsMd] : []),
   ...extArgs,
-  ...process.argv.slice(2),
+  ...userArgs,
 ];
 
-// ---- 6. Spawn pi in the user's cwd ----
+// ---- 7. Spawn pi in the user's cwd ----
 const child = spawn(piBin, piArgs, {
   stdio: "inherit",
   cwd: process.cwd(),

package/bin/update-check.mjs

@@ -0,0 +1,167 @@
+// little-coder update check.
+// Polls the npm registry for a newer published version and (in TTY mode)
+// offers to install it before the agent starts. Cached so we don't call out
+// on every invocation. Best-effort throughout: if anything fails, we skip
+// silently — never block the agent over a version check.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { createInterface } from "node:readline";
+
+const REGISTRY = "https://registry.npmjs.org/little-coder/latest";
+const CACHE_TTL_MS = 12 * 60 * 60 * 1000;   // 12 h
+const FETCH_TIMEOUT_MS = 2000;
+
+export function cachePath() {
+  const xdg = process.env.XDG_CACHE_HOME && process.env.XDG_CACHE_HOME.trim();
+  const base = xdg ? xdg : join(homedir(), ".cache");
+  return join(base, "little-coder", "version-check.json");
+}
+
+export function readCache(now = Date.now()) {
+  try {
+    const path = cachePath();
+    if (!existsSync(path)) return null;
+    const data = JSON.parse(readFileSync(path, "utf-8"));
+    if (typeof data.checkedAt !== "number" || typeof data.latest !== "string") return null;
+    if (now - data.checkedAt > CACHE_TTL_MS) return null;
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+export function writeCache(latest, now = Date.now()) {
+  try {
+    const path = cachePath();
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify({ checkedAt: now, latest }));
+  } catch {
+    // best-effort; permission errors etc. are not fatal
+  }
+}
+
+// Compare semver strings. Only handles X.Y.Z[+pre]. Returns 1 if a > b,
+// -1 if a < b, 0 if equal. Pre-release suffixes are treated as < release.
+export function compareSemver(a, b) {
+  const parse = (v) => {
+    const [core, pre] = String(v).split("-", 2);
+    const parts = core.split(".").map((n) => parseInt(n, 10));
+    return {
+      major: parts[0] || 0,
+      minor: parts[1] || 0,
+      patch: parts[2] || 0,
+      pre: pre || "",
+    };
+  };
+  const pa = parse(a);
+  const pb = parse(b);
+  if (pa.major !== pb.major) return pa.major > pb.major ? 1 : -1;
+  if (pa.minor !== pb.minor) return pa.minor > pb.minor ? 1 : -1;
+  if (pa.patch !== pb.patch) return pa.patch > pb.patch ? 1 : -1;
+  // Equal core: a release beats a pre-release.
+  if (pa.pre === pb.pre) return 0;
+  if (pa.pre === "") return 1;
+  if (pb.pre === "") return -1;
+  return pa.pre > pb.pre ? 1 : -1;
+}
+
+async function fetchLatest() {
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const res = await fetch(REGISTRY, { signal: ctrl.signal });
+    if (!res.ok) return null;
+    const json = await res.json();
+    return typeof json?.version === "string" ? json.version : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+// Decide whether to skip the check entirely. Errs toward NOT prompting in
+// any context that smells programmatic.
+export function shouldSkip(argv = process.argv.slice(2), env = process.env, stdout = process.stdout) {
+  if (env.LITTLE_CODER_NO_UPDATE_CHECK === "1") return true;
+  if (env.CI === "true" || env.CI === "1") return true;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--no-update-check") return true;
+    if (a === "--help" || a === "-h") return true;
+    if (a === "--version" || a === "-v") return true;
+    if (a === "--list-models") return true;
+    if (a === "--export") return true;
+    if (a === "--mode") {
+      const next = argv[i + 1];
+      if (next === "rpc" || next === "json") return true;
+    }
+  }
+  // Non-TTY runs: scripts, pipes, --print pipelines. Notice only, no prompt.
+  if (!stdout.isTTY) return "notice-only";
+  return false;
+}
+
+function promptYesNo(question) {
+  return new Promise((resolve) => {
+    if (!process.stdin.isTTY) {
+      resolve(false);
+      return;
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    rl.question(question, (answer) => {
+      rl.close();
+      const a = (answer ?? "").trim().toLowerCase();
+      resolve(a === "" || a === "y" || a === "yes");
+    });
+  });
+}
+
+// Returns `true` if the launcher should NOT proceed to spawn pi (because we
+// updated and exited / the user opted out and we should re-run).  Returns
+// `false` to let the launcher continue.
+export async function checkForUpdate(currentVersion, opts = {}) {
+  const skip = opts.skip ?? shouldSkip();
+  if (skip === true) return false;
+
+  let latest = readCache()?.latest;
+  if (!latest) {
+    latest = await fetchLatest();
+    if (latest) writeCache(latest);
+  }
+  if (!latest) return false;
+  if (compareSemver(latest, currentVersion) <= 0) return false;
+
+  const headline =
+    `\n📦 little-coder v${latest} is available (you have v${currentVersion}).`;
+
+  if (skip === "notice-only") {
+    process.stderr.write(`${headline}\n   Update with: npm install -g little-coder\n\n`);
+    return false;
+  }
+
+  process.stderr.write(`${headline}\n`);
+  const wantsUpdate = await promptYesNo("   Update now? [Y/n] ");
+  if (!wantsUpdate) {
+    process.stderr.write("   Skipping update for this run.\n\n");
+    return false;
+  }
+
+  process.stderr.write(`\n   Running: npm install -g little-coder@${latest}\n\n`);
+  const result = spawnSync("npm", ["install", "-g", `little-coder@${latest}`], {
+    stdio: "inherit",
+  });
+  if (result.status === 0) {
+    process.stderr.write(
+      `\n   ✓ Updated to v${latest}. Re-run \`little-coder\` to use the new version.\n\n`,
+    );
+    return true;
+  }
+  process.stderr.write(
+    `\n   ✗ Update failed (npm exit ${result.status}). Continuing with v${currentVersion}.\n\n`,
+  );
+  return false;
+}

package/bin/update-check.test.mjs

@@ -0,0 +1,164 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, existsSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  cachePath,
+  readCache,
+  writeCache,
+  compareSemver,
+  shouldSkip,
+} from "./update-check.mjs";
+
+describe("compareSemver", () => {
+  it("orders major / minor / patch correctly", () => {
+    expect(compareSemver("1.0.0", "1.0.0")).toBe(0);
+    expect(compareSemver("1.0.1", "1.0.0")).toBe(1);
+    expect(compareSemver("1.0.0", "1.0.1")).toBe(-1);
+    expect(compareSemver("1.1.0", "1.0.99")).toBe(1);
+    expect(compareSemver("2.0.0", "1.99.99")).toBe(1);
+    expect(compareSemver("0.99.99", "1.0.0")).toBe(-1);
+  });
+
+  it("treats releases as greater than pre-releases of same core", () => {
+    expect(compareSemver("1.0.0", "1.0.0-rc.1")).toBe(1);
+    expect(compareSemver("1.0.0-rc.1", "1.0.0")).toBe(-1);
+    expect(compareSemver("1.0.0-rc.2", "1.0.0-rc.1")).toBe(1);
+  });
+
+  it("tolerates short version strings", () => {
+    expect(compareSemver("1.0", "1.0.0")).toBe(0);
+    expect(compareSemver("1", "1.0.0")).toBe(0);
+  });
+});
+
+describe("cachePath", () => {
+  it("uses XDG_CACHE_HOME when set", () => {
+    const orig = process.env.XDG_CACHE_HOME;
+    process.env.XDG_CACHE_HOME = "/tmp/xdg-test";
+    try {
+      expect(cachePath()).toBe("/tmp/xdg-test/little-coder/version-check.json");
+    } finally {
+      if (orig !== undefined) process.env.XDG_CACHE_HOME = orig;
+      else delete process.env.XDG_CACHE_HOME;
+    }
+  });
+
+  it("falls back to ~/.cache when XDG is unset", () => {
+    const orig = process.env.XDG_CACHE_HOME;
+    delete process.env.XDG_CACHE_HOME;
+    try {
+      const p = cachePath();
+      expect(p).toMatch(/\.cache\/little-coder\/version-check\.json$/);
+    } finally {
+      if (orig !== undefined) process.env.XDG_CACHE_HOME = orig;
+    }
+  });
+});
+
+describe("read/writeCache", () => {
+  let tmp;
+  let origXdg;
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), "lc-uc-test-"));
+    origXdg = process.env.XDG_CACHE_HOME;
+    process.env.XDG_CACHE_HOME = tmp;
+  });
+  afterEach(() => {
+    if (origXdg !== undefined) process.env.XDG_CACHE_HOME = origXdg;
+    else delete process.env.XDG_CACHE_HOME;
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("returns null when no cache exists", () => {
+    expect(readCache()).toBeNull();
+  });
+
+  it("round-trips a fresh entry", () => {
+    writeCache("1.0.5", 1000);
+    const cached = readCache(2000);
+    expect(cached?.latest).toBe("1.0.5");
+    expect(cached?.checkedAt).toBe(1000);
+  });
+
+  it("returns null for stale entries past 12h TTL", () => {
+    writeCache("1.0.5", 0);
+    const stale = readCache(13 * 60 * 60 * 1000);
+    expect(stale).toBeNull();
+  });
+
+  it("returns the entry if exactly at TTL boundary", () => {
+    writeCache("1.0.5", 0);
+    const at = readCache(12 * 60 * 60 * 1000);
+    expect(at?.latest).toBe("1.0.5");
+  });
+
+  it("handles malformed cache files gracefully", () => {
+    writeCache("garbage", 1000);
+    const path = cachePath();
+    // Corrupt the file
+    const fs = readFileSync(path, "utf-8");
+    expect(fs).toContain("garbage");
+    // Now write actual garbage
+    require("node:fs").writeFileSync(path, "{not-json");
+    expect(readCache()).toBeNull();
+  });
+
+  it("creates the cache directory if missing", () => {
+    rmSync(join(tmp, "little-coder"), { recursive: true, force: true });
+    writeCache("1.2.3", 5000);
+    expect(existsSync(cachePath())).toBe(true);
+    expect(readCache(5000)?.latest).toBe("1.2.3");
+  });
+});
+
+describe("shouldSkip", () => {
+  function ttyStdout() { return { isTTY: true }; }
+  function pipeStdout() { return { isTTY: false }; }
+  const noEnv = {};
+
+  it("returns false in plain TTY interactive mode", () => {
+    expect(shouldSkip([], noEnv, ttyStdout())).toBe(false);
+  });
+
+  it("skips when LITTLE_CODER_NO_UPDATE_CHECK=1", () => {
+    expect(shouldSkip([], { LITTLE_CODER_NO_UPDATE_CHECK: "1" }, ttyStdout())).toBe(true);
+  });
+
+  it("skips on --no-update-check flag", () => {
+    expect(shouldSkip(["--no-update-check"], noEnv, ttyStdout())).toBe(true);
+  });
+
+  it("skips on --help / -h", () => {
+    expect(shouldSkip(["--help"], noEnv, ttyStdout())).toBe(true);
+    expect(shouldSkip(["-h"], noEnv, ttyStdout())).toBe(true);
+  });
+
+  it("skips on --version / -v", () => {
+    expect(shouldSkip(["--version"], noEnv, ttyStdout())).toBe(true);
+    expect(shouldSkip(["-v"], noEnv, ttyStdout())).toBe(true);
+  });
+
+  it("skips on --list-models and --export", () => {
+    expect(shouldSkip(["--list-models"], noEnv, ttyStdout())).toBe(true);
+    expect(shouldSkip(["--export", "session.jsonl"], noEnv, ttyStdout())).toBe(true);
+  });
+
+  it("skips for --mode rpc / --mode json", () => {
+    expect(shouldSkip(["--mode", "rpc"], noEnv, ttyStdout())).toBe(true);
+    expect(shouldSkip(["--mode", "json"], noEnv, ttyStdout())).toBe(true);
+  });
+
+  it("does not skip for --mode text", () => {
+    expect(shouldSkip(["--mode", "text"], noEnv, ttyStdout())).toBe(false);
+  });
+
+  it("skips in CI environments", () => {
+    expect(shouldSkip([], { CI: "true" }, ttyStdout())).toBe(true);
+    expect(shouldSkip([], { CI: "1" }, ttyStdout())).toBe(true);
+  });
+
+  it("returns notice-only on non-TTY pipelines", () => {
+    expect(shouldSkip([], noEnv, pipeStdout())).toBe("notice-only");
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "little-coder",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "A pi-based coding agent optimized for small local language models. Reproduces the whitepaper's scaffold-model-fit adaptations as pi extensions.",
   "homepage": "https://github.com/itayinbarr/little-coder",
   "repository": {