little-coder 1.9.1 → 1.9.3

package/.pi/extensions/_shared/width.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect } from "vitest";
+import { stripAnsi, visibleWidth, truncateLineToWidth } from "./width.ts";
+
+describe("stripAnsi / visibleWidth", () => {
+  it("strips SGR color codes", () => {
+    expect(stripAnsi("\x1b[31mred\x1b[39m")).toBe("red");
+    expect(visibleWidth("\x1b[31mred\x1b[39m")).toBe(3);
+  });
+  it("strips OSC hyperlinks", () => {
+    const link = "\x1b]8;;https://example.com\x07click\x1b]8;;\x07";
+    expect(stripAnsi(link)).toBe("click");
+    expect(visibleWidth(link)).toBe(5);
+  });
+  it("counts plain ASCII", () => {
+    expect(visibleWidth("hello world")).toBe(11);
+  });
+});
+
+describe("truncateLineToWidth", () => {
+  it("returns the line unchanged when it fits", () => {
+    expect(truncateLineToWidth("hi", 10)).toBe("hi");
+  });
+  it("truncates and adds an ellipsis when it overflows", () => {
+    const out = truncateLineToWidth("abcdefghij", 5);
+    expect(visibleWidth(out)).toBeLessThanOrEqual(5);
+    expect(out).toContain("…");
+  });
+  it("preserves SGR codes through the visible portion", () => {
+    // 12 visible chars under one color, truncate to 6
+    const input = "\x1b[31m" + "abcdefghijkl" + "\x1b[39m";
+    const out = truncateLineToWidth(input, 6);
+    expect(out).toContain("\x1b[31m");
+    // visible chars in out (after stripping ansi) should be <= 6
+    expect(visibleWidth(out)).toBeLessThanOrEqual(6);
+  });
+  it("appends a reset to prevent color bleed after truncation", () => {
+    const out = truncateLineToWidth("\x1b[31mlong red string here\x1b[39m", 8);
+    expect(out.endsWith("\x1b[0m")).toBe(true);
+  });
+  it("handles a width of 0 defensively", () => {
+    expect(truncateLineToWidth("anything", 0)).toBe("");
+  });
+  it("matches the issue #48 reproduction shape", () => {
+    // Construct a row roughly the shape the sub-coder tracker would build,
+    // with a real-world ~167-char errorMessage. Without truncation this is
+    // 198 visible chars — exactly the user-reported overflow.
+    const honey = (s: string) => `\x1b[38;2;225;90;31m${s}\x1b[39m`;
+    const gray = (s: string) => `\x1b[90m${s}\x1b[39m`;
+    const red = (s: string) => `\x1b[31m${s}\x1b[39m`;
+    const longError =
+      "child process exited with non-zero code 1: " +
+      "Error: provider \"llamacpp\" — failed to reach " +
+      "http://127.0.0.1:8888/v1/chat/completions: ECONNREFUSED (transport error 503, retries=3)";
+    const row = `  ${red("✗")} deep-explorer-research  ${gray("0:47 ")}  ${gray(longError)}`;
+    expect(visibleWidth(row)).toBeGreaterThan(184);
+    const fixed = truncateLineToWidth(row, 184);
+    expect(visibleWidth(fixed)).toBeLessThanOrEqual(184);
+    expect(fixed.startsWith("  \x1b[31m✗\x1b[39m deep-explorer")).toBe(true);
+    void honey; // keep import shape parity with the tracker
+  });
+});

package/.pi/extensions/_shared/width.ts

@@ -0,0 +1,76 @@
+// Width-aware truncation for custom TUI widget content.
+//
+// pi-tui (>= ~0.75) throws "Rendered line N exceeds terminal width" when any
+// rendered line is wider than the terminal — see issue #48. Custom widgets
+// (subagent tracker, plan-mode status/indicator, branding header) MUST cap
+// every line they emit to the active terminal width, or pi crashes the whole
+// session when the widget happens to produce a long line (e.g. a failed
+// sub-coder whose errorMessage runs ~200 chars).
+//
+// pi-tui itself exports visibleWidth + truncateToWidth, but pi 0.79 no longer
+// hoists pi-tui to the top-level node_modules, so extensions can't import it
+// directly. This module is the lightweight inline replacement: it strips
+// SGR / OSC escapes for the width count and walks the string char-by-char to
+// truncate while preserving any in-flight color codes.
+
+const SGR_RE = /\x1b\[[0-9;]*[a-zA-Z]/g;
+const OSC_RE = /\x1b\][^\x07]*\x07/g;
+
+export function stripAnsi(s: string): string {
+  return s.replace(SGR_RE, "").replace(OSC_RE, "");
+}
+
+// Approximation: ANSI-stripped char count (treats every visible char as width
+// 1). Exact for ASCII / Latin / single-cell glyphs the tracker and status
+// widgets emit. Wide CJK or emoji *under*count here, so callers should leave a
+// small safety margin (see terminalColumns/SAFETY_MARGIN).
+export function visibleWidth(s: string): number {
+  return [...stripAnsi(s)].length;
+}
+
+// Truncate `line` so its visible width fits `maxWidth`. ANSI escapes are
+// preserved verbatim; the visible portion is cut at maxWidth-1 to leave room
+// for an ellipsis, and a final SGR reset is appended so a half-emitted color
+// can't bleed into the next line. If maxWidth ≤ 0, returns "" (defensive).
+export function truncateLineToWidth(line: string, maxWidth: number, ellipsis = "…"): string {
+  if (maxWidth <= 0) return "";
+  if (visibleWidth(line) <= maxWidth) return line;
+  const cutAt = Math.max(0, maxWidth - visibleWidth(ellipsis));
+  let visible = 0;
+  let out = "";
+  let i = 0;
+  while (i < line.length) {
+    const ch = line[i];
+    if (ch === "\x1b" && line[i + 1] === "[") {
+      const m = line.slice(i).match(/^\x1b\[[0-9;]*[a-zA-Z]/);
+      if (m) {
+        out += m[0];
+        i += m[0].length;
+        continue;
+      }
+    }
+    if (ch === "\x1b" && line[i + 1] === "]") {
+      const end = line.indexOf("\x07", i);
+      if (end >= 0) {
+        out += line.slice(i, end + 1);
+        i = end + 1;
+        continue;
+      }
+    }
+    if (visible >= cutAt) break;
+    out += ch;
+    visible += 1;
+    i += 1;
+  }
+  return out + ellipsis + "\x1b[0m";
+}
+
+// Current terminal width, with a small safety margin to absorb wide Unicode
+// chars that visibleWidth's char-count approximation under-measures. Falls
+// back to `fallback` columns when stdout isn't a TTY (headless runs).
+const SAFETY_MARGIN = 2;
+export function terminalColumns(fallback = 80): number {
+  const c = (process.stdout && (process.stdout as any).columns) | 0;
+  const w = c > 0 ? c : fallback;
+  return Math.max(20, w - SAFETY_MARGIN);
+}

package/.pi/extensions/branding/index.ts

@@ -2,6 +2,7 @@ import type { ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
 import { readFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { truncateLineToWidth } from "../_shared/width.ts";
 
 // Replace pi's built-in startup header + terminal title with little-coder
 // branding. The interactive TUI's "pi vX.Y.Z" logo, the "Pi can explain its
@@ -46,7 +47,7 @@ function readVersion(): string {
 
 const VERSION = readVersion();
 
-function buildHeader(theme: Theme): string[] {
+function buildHeader(theme: Theme, width: number): string[] {
   // Brand-book "prompt lockup" (the variant the brand reserves for terminals
   // and dark surfaces): a honey prompt caret, the wordmark in the foreground,
   // and the honey block cursor — "lc▌"'s ready-to-type punchline, applied to
@@ -67,7 +68,11 @@ function buildHeader(theme: Theme): string[] {
     `${dim("!")} bash`,
     `${dim("ctrl-r")} more`,
   ].join(sep);
-  return ["", logo, tagline, "", hints, ""];
+  // pi-tui throws if any rendered line exceeds the terminal width (issue #48).
+  // Truncate every line we hand it so a narrow terminal can't crash the launch.
+  return ["", logo, tagline, "", hints, ""].map((l) =>
+    l ? truncateLineToWidth(l, width) : l,
+  );
 }
 
 // Derive a short, human session name from the first user prompt. Returns
@@ -111,8 +116,8 @@ export default function (pi: ExtensionAPI) {
     if (!ctx.hasUI) return;
 
     ctx.ui.setHeader((_tui, theme) => ({
-      render(_width: number): string[] {
-        return buildHeader(theme);
+      render(width: number): string[] {
+        return buildHeader(theme, width);
       },
       invalidate() {},
     }));

package/.pi/extensions/plan-mode/index.ts

@@ -9,6 +9,7 @@ import {
 import { SubCoderTracker } from "../subagent/tracker.ts";
 import { currentModelId } from "../subagent/index.ts";
 import { PlanStatus } from "./status.ts";
+import { terminalColumns, truncateLineToWidth } from "../_shared/width.ts";
 
 // Plan Mode — a Claude-Code-style "research, ask, then plan" flow.
 //
@@ -49,7 +50,11 @@ let pendingSynthesis: { digest: string; answers: string } | null = null;
 let synthesisActive = false;
 
 function indicatorLines(): string[] {
-  return [`${honey("◆")} ${honey("PLAN MODE")}  ${gray("(alt+p to exit)")}`];
+  // Cap to terminal width — pi-tui throws on overflow (issue #48). The
+  // indicator is short, but truncate for defense in depth so even a narrow
+  // terminal (≤ 30 cols) doesn't crash on widget render.
+  const raw = `${honey("◆")} ${honey("PLAN MODE")}  ${gray("(alt+p to exit)")}`;
+  return [truncateLineToWidth(raw, terminalColumns())];
 }
 
 function setIndicator(ctx: any, on: boolean): void {

package/.pi/extensions/plan-mode/status.ts

@@ -7,6 +7,8 @@
 // (needed to animate the spinner + tick the clock), colored with raw SGR so it
 // doesn't depend on the active theme.
 
+import { terminalColumns, truncateLineToWidth } from "../_shared/width.ts";
+
 const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 const honey = (s: string) => `\x1b[38;2;225;90;31m${s}\x1b[39m`;
 const gray = (s: string) => `\x1b[90m${s}\x1b[39m`;
@@ -71,7 +73,11 @@ export class PlanStatus {
     if (!this.ctx.hasUI) return;
     const now = Date.now();
     const frame = SPINNER[Math.floor(now / 100) % SPINNER.length];
-    const line = `${honey(frame)} ${this.message}  ${gray(fmtElapsed(now - this.startMs))}`;
+    const raw = `${honey(frame)} ${this.message}  ${gray(fmtElapsed(now - this.startMs))}`;
+    // Cap to terminal width — pi-tui throws on overflow (issue #48). Our own
+    // phase messages are short, but the line is still passed through for
+    // defense-in-depth (a future caller, or a long custom message, won't crash).
+    const line = truncateLineToWidth(raw, terminalColumns());
     if (line === this.lastFrame) return; // diff-guard
     this.lastFrame = line;
     this.ctx.ui.setWidget(this.key, [line], { placement: this.placement });

package/.pi/extensions/subagent/issue-48-repro.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect } from "vitest";
+import { SubCoderTracker } from "./tracker.ts";
+
+// Live regression for issue #48 — the user's reported crash shape.
+// pi-tui throws when any rendered widget line is wider than the terminal.
+// Before the fix, the sub-coder tracker fed an unbounded errorMessage straight
+// into a widget row; a ~167-char error at terminal width 184 produced a
+// 248-char visible line and crashed the session. This test simulates the
+// exact scenario and asserts every emitted line fits.
+
+describe("issue #48 — tracker doesn't overflow terminal width", () => {
+  it("caps a failed sub-coder's row to the terminal width", () => {
+    const orig = (process.stdout as any).columns;
+    (process.stdout as any).columns = 184;
+    try {
+      const captured: string[] = [];
+      const ctx = {
+        hasUI: true,
+        ui: {
+          setWidget: (_k: string, lines: string[] | undefined) => {
+            if (lines) captured.push(...lines);
+          },
+        },
+      };
+      const tracker = new SubCoderTracker(ctx, { key: "t", totalSince: Date.now() - 47000 });
+      tracker.begin([{ id: "a", label: "deep-explorer-research" }]);
+      const longErr =
+        "child process exited with non-zero code 1: " +
+        "Error: provider \"llamacpp\" — failed to reach " +
+        "http://127.0.0.1:8888/v1/chat/completions: ECONNREFUSED (transport error 503 after 3 retries)";
+      tracker.update([
+        {
+          id: "a",
+          label: "deep-explorer-research",
+          task: "",
+          exitCode: 1,
+          errorMessage: longErr,
+          report: "",
+          messages: [],
+          stderr: "",
+          usage: { input: 0, output: 0, cost: 0, turns: 0, contextTokens: 0 },
+        },
+      ]);
+      tracker.end();
+      expect(captured.length).toBeGreaterThan(0);
+      const stripAnsi = (s: string) => s.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, "");
+      const widths = captured.map((l) => stripAnsi(l).length);
+      const max = Math.max(...widths);
+      expect(max).toBeLessThanOrEqual(184);
+    } finally {
+      (process.stdout as any).columns = orig;
+    }
+  });
+
+  it("survives narrower terminals (~80 cols)", () => {
+    const orig = (process.stdout as any).columns;
+    (process.stdout as any).columns = 80;
+    try {
+      const captured: string[] = [];
+      const ctx = {
+        hasUI: true,
+        ui: { setWidget: (_k: string, lines: string[] | undefined) => { if (lines) captured.push(...lines); } },
+      };
+      const tracker = new SubCoderTracker(ctx);
+      tracker.begin([{ id: "a", label: "x" }, { id: "b", label: "y" }]);
+      tracker.update([
+        { id: "a", label: "x", task: "", exitCode: 0, report: "ok", messages: [], stderr: "", usage: { input: 0, output: 0, cost: 0, turns: 0, contextTokens: 0 } },
+        { id: "b", label: "y", task: "", exitCode: 1, errorMessage: "x".repeat(500), report: "", messages: [], stderr: "", usage: { input: 0, output: 0, cost: 0, turns: 0, contextTokens: 0 } },
+      ]);
+      tracker.end();
+      const stripAnsi = (s: string) => s.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, "");
+      const max = Math.max(...captured.map((l) => stripAnsi(l).length));
+      expect(max).toBeLessThanOrEqual(80);
+    } finally {
+      (process.stdout as any).columns = orig;
+    }
+  });
+});

package/.pi/extensions/subagent/spawn.test.ts

@@ -64,6 +64,15 @@ describe("summarizeActivity", () => {
   it("falls back to working when running with no tool call", () => {
     expect(summarizeActivity(base)).toBe("working…");
   });
+  it("caps long error messages on failure (issue #48 regression)", () => {
+    const longErr =
+      "child process exited with non-zero code 1: " +
+      "Error: provider \"llamacpp\" — failed to reach " +
+      "http://127.0.0.1:8888/v1/chat/completions: ECONNREFUSED";
+    const out = summarizeActivity({ ...base, exitCode: 1, errorMessage: longErr });
+    expect(out.length).toBeLessThanOrEqual(56);
+    expect(out.endsWith("…")).toBe(true);
+  });
 });
 
 describe("buildChildEnv", () => {

package/.pi/extensions/subagent/spawn.ts

@@ -131,11 +131,20 @@ export function truncateReport(text: string, max = MAX_REPORT_CHARS): string {
 
 /** A one-line "what is this child doing right now" string for the tracker. */
 export function summarizeActivity(r: SubCoderResult): string {
+  const cap = (s: string, n = 56): string => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
   if (r.exitCode === 0) {
     const firstLine = r.report.split(/\r?\n/).find((l) => l.trim()) ?? "(done)";
-    return firstLine.length > 56 ? `${firstLine.slice(0, 55)}…` : firstLine;
+    return cap(firstLine);
+  }
+  if (r.exitCode > 0) {
+    // The error path used to return raw errorMessage / stderr UNCAPPED, which
+    // routinely runs ~200 chars (a child process error with a URL + stack
+    // fragment). The tracker passes that straight into a widget line, and any
+    // line wider than the terminal crashes pi-tui (issue #48). Cap here so the
+    // source string is bounded; the widget also truncates the assembled row
+    // for defense in depth.
+    return cap(r.errorMessage || r.stderr.split(/\r?\n/)[0] || "(failed)");
   }
-  if (r.exitCode > 0) return r.errorMessage || r.stderr.split(/\r?\n/)[0] || "(failed)";
   // running: surface the most recent tool call, else the latest partial text.
   for (let i = r.messages.length - 1; i >= 0; i--) {
     const m = r.messages[i];
@@ -145,7 +154,7 @@ export function summarizeActivity(r: SubCoderResult): string {
         if (part?.type === "toolCall") {
           const a = part.arguments ?? {};
           const hint = a.pattern || a.query || a.url || a.path || a.file_path || a.command || "";
-          return `→ ${part.name}${hint ? ` ${String(hint).slice(0, 40)}` : ""}`;
+          return cap(`→ ${part.name}${hint ? ` ${String(hint).slice(0, 40)}` : ""}`);
         }
       }
     }

package/.pi/extensions/subagent/tracker.ts

@@ -7,6 +7,7 @@
 // active theme and the string[] form of setWidget can be used directly.
 
 import { summarizeActivity, type SubCoderResult } from "./spawn.ts";
+import { terminalColumns, truncateLineToWidth } from "../_shared/width.ts";
 
 const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 
@@ -130,7 +131,13 @@ export class SubCoderTracker {
       return `  ${icon} ${padEnd(r.label, labelWidth)}  ${gray(padEnd(elapsed, 5))}  ${gray(activity)}`;
     });
 
-    const lines = [header, ...rows];
+    // Cap every line to the active terminal width — pi-tui throws if a custom
+    // widget renders a line wider than the terminal (issue #48). The activity
+    // text in rows can be unbounded (failed sub-coders surface raw stderr /
+    // errorMessage, which routinely runs ~200 chars), so without this each
+    // failing dispatch turn would crash the whole session.
+    const width = terminalColumns();
+    const lines = [header, ...rows].map((l) => truncateLineToWidth(l, width));
     const frameKey = lines.join("\n");
     if (frameKey === this.lastFrame) return; // diff-guard: skip identical repaints
     this.lastFrame = frameKey;

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 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.9.3] — 2026-06-18
+
+### Added
+- **`LITTLE_CODER_EXTRA_EXTENSIONS` env var: layer third-party pi extensions onto the bundled set without forking the installed package** ([#46](https://github.com/itayinbarr/little-coder/issues/46)). Path-delimited list (`:` on POSIX, `;` on Windows — `node:path.delimiter`) of extension paths. Each entry can be a direct file (e.g. a `pi-ponytail`-style `extensions/ponytail.js`) or a directory containing `index.ts` / `index.js` (the launcher prefers `.ts`). A leading `~/` is expanded; missing paths log a one-line warning to stderr and are skipped (a typo in the env var doesn't kill the session). Survives upgrades — drop the env var into your shell rc once and every `little-coder` run picks up the extras. Example: `LITTLE_CODER_EXTRA_EXTENSIONS=~/.local/lib/node_modules/pi-ponytail/extensions/ponytail.js little-coder`. Parsing rules live in `bin/extras.mjs` so they're unit-testable in isolation (9 cases covering direct-file / dir-index-resolution / `index.ts`-preference / missing-path warning / `~/` expansion / multiple entries / whitespace trimming). The launcher-level integration is exercised end-to-end (warning prints for a bad path; valid paths pass through silently to pi as `--extension <entry>` flags). Closest siblings — third-party skill bundles — are not yet covered; `skill-inject` still discovers only `<pkgRoot>/skills/tools/*.md`, and a follow-up will add the same kind of override.
+
+### Notes for upgraders
+- No CLI-flag or public-API changes. The new env var is opt-in: unset = identical behavior to v1.9.2. If you were carrying a custom wrapper extension inside the installed npm package (which gets wiped on upgrade), you can drop it and use the env var instead.
+
+---
+
+## [v1.9.2] — 2026-06-18
+
+### Fixed
+- **Width-overflow crash from custom widgets** ([#48](https://github.com/itayinbarr/little-coder/issues/48)). pi-tui throws `Rendered line N exceeds terminal width` whenever a custom TUI component emits a line wider than the active terminal — the user saw a 198-char line at width 184 take down the whole session. Root cause was the **sub-coder tracker** (`subagent/tracker.ts`): a failed sub-coder's `errorMessage` flowed straight into a widget row without any cap, and real-world child-process errors routinely run 150-250 chars (transport error + URL + retry count is enough). The tracker now caps every emitted row to the active terminal width using a new `_shared/width.ts` utility (`visibleWidth` + `truncateLineToWidth`, ANSI-aware so SGR colour codes are preserved through the cut and a final reset prevents bleed). `summarizeActivity` also gained a 56-char cap on the failure path (was uncapped) and the running path (was uncapped on `part.name`) for defense in depth. The same width-cap is now applied to the **plan-mode status panel**, the **plan-mode indicator**, and the **branding startup header** (which now uses the `width` arg pi passes to `render()` instead of returning hardcoded-length lines), so a narrow terminal can no longer crash launch either. New `width.test.ts` (9 cases) covers ASCII / SGR / OSC hyperlink / colour-bleed / the exact issue-48 reproduction shape, and `issue-48-repro.test.ts` drives the tracker directly with a 167-char failure at width 184 and asserts no emitted row exceeds the terminal.
+
+### Notes for upgraders
+- No CLI-flag or public-API changes. If you ever saw `Rendered line N exceeds terminal width (… > …)` crash a session — particularly during a `dispatch` call that errored, or while Plan Mode was orchestrating sub-coders — 1.9.2 fixes it. Third-party pi extensions (e.g. `context-mode`) that emit their own widgets remain subject to pi's check; if you still see the crash with `Loaded pi extensions: <name>` listed, the offending widget is in that extension, not little-coder.
+
+---
+
 ## [v1.9.1] — 2026-06-08
 
 ### Fixed

package/README.md

@@ -67,6 +67,7 @@ The agent uses the directory you launched it from as its working directory — `
 - **Sub-coders (`dispatch`)** — little-coder can spawn isolated child sessions to research a question (read the repo + browse online, read-only) and report back concisely, without cluttering the main conversation. A live panel above the input tracks them. Tune parallelism with `LITTLE_CODER_SUBCODER_CONCURRENCY` (default 2).
 - **Sessions** — each session is auto-named from your first prompt (rename with `/name`) and shown in the terminal tab title. Use `/resume` to list and reopen past sessions for the current directory.
 - **Read-before-edit** — editing a file requires reading it first, so edits match the file's exact current text.
+- **Third-party extensions (`LITTLE_CODER_EXTRA_EXTENSIONS`)** — path-delimited list (`:` on POSIX, `;` on Windows) of extension paths to layer on top of the bundled set. Each entry can be a direct file (e.g. a `pi-ponytail`-style `extensions/ponytail.js`) or a directory containing `index.ts` / `index.js`. `~/` is expanded; missing paths log a warning and are skipped. Survives upgrades, no patching the installed package. Example: `LITTLE_CODER_EXTRA_EXTENSIONS=~/.local/lib/node_modules/pi-ponytail/extensions/ponytail.js little-coder`. (Single-file extensions can still use `little-coder -e <path>` for one-off loads.)
 
 For local providers (llama.cpp, Ollama, LM Studio) pi expects *some* value in the API-key env even though local servers ignore it:
 

package/bin/extras.mjs

@@ -0,0 +1,56 @@
+// Helpers for layering third-party pi extensions onto little-coder's bundled
+// set. Extracted from the launcher so the parsing rules — path-delimited list,
+// `~/` expansion, directory-with-index resolution, missing-path warning — are
+// directly unit-testable without spawning the whole CLI.
+
+import { existsSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, join } from "node:path";
+
+// Given the value of LITTLE_CODER_EXTRA_EXTENSIONS (path-delimited list of
+// extension paths), return the resolved entry files that should be passed to pi
+// as `--extension <entry>` flags. Skips empty segments, expands a leading `~/`,
+// resolves a directory entry to its `index.ts` (preferred) or `index.js`, and
+// records a one-line warning for each missing/unusable path so a typo in the
+// env var doesn't kill the session — it just doesn't load that extension.
+export function parseExtraExtensions(
+  envValue,
+  { home = homedir(), exists = existsSync, stat = statSync } = {},
+) {
+  const entries = [];
+  const warnings = [];
+  for (const raw of String(envValue ?? "").split(delimiter)) {
+    const trimmed = raw.trim();
+    if (!trimmed) continue;
+    const expanded = trimmed === "~"
+      ? home
+      : trimmed.startsWith("~/")
+        ? home + trimmed.slice(1)
+        : trimmed;
+    if (!exists(expanded)) {
+      warnings.push(
+        `little-coder: LITTLE_CODER_EXTRA_EXTENSIONS path not found, skipping: ${expanded}`,
+      );
+      continue;
+    }
+    let entry = expanded;
+    try {
+      if (stat(expanded).isDirectory()) {
+        const candidates = [join(expanded, "index.ts"), join(expanded, "index.js")];
+        const found = candidates.find((p) => exists(p));
+        if (!found) {
+          warnings.push(
+            `little-coder: LITTLE_CODER_EXTRA_EXTENSIONS dir has no index.ts/index.js, skipping: ${expanded}`,
+          );
+          continue;
+        }
+        entry = found;
+      }
+    } catch {
+      // unreadable / racing stat — skip silently
+      continue;
+    }
+    entries.push(entry);
+  }
+  return { entries, warnings };
+}

package/bin/extras.test.mjs

@@ -0,0 +1,119 @@
+import { describe, it, expect } from "vitest";
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { delimiter, join } from "node:path";
+import { parseExtraExtensions } from "./extras.mjs";
+
+function setupTmp() {
+  return mkdtempSync(join(tmpdir(), "lc-extras-"));
+}
+
+describe("parseExtraExtensions", () => {
+  it("returns no entries when env is unset / empty", () => {
+    expect(parseExtraExtensions(undefined).entries).toEqual([]);
+    expect(parseExtraExtensions("").entries).toEqual([]);
+    expect(parseExtraExtensions(delimiter + delimiter).entries).toEqual([]);
+  });
+
+  it("forwards a direct file path verbatim", () => {
+    const dir = setupTmp();
+    try {
+      const file = join(dir, "ponytail.js");
+      writeFileSync(file, "export default function(){}");
+      const { entries, warnings } = parseExtraExtensions(file);
+      expect(entries).toEqual([file]);
+      expect(warnings).toEqual([]);
+    } finally {
+      rmSync(dir, { recursive: true });
+    }
+  });
+
+  it("resolves a directory entry to its index.ts (preferred)", () => {
+    const dir = setupTmp();
+    try {
+      const extDir = join(dir, "ponytail");
+      mkdirSync(extDir);
+      writeFileSync(join(extDir, "index.ts"), "");
+      writeFileSync(join(extDir, "index.js"), "");
+      const { entries } = parseExtraExtensions(extDir);
+      expect(entries).toEqual([join(extDir, "index.ts")]);
+    } finally {
+      rmSync(dir, { recursive: true });
+    }
+  });
+
+  it("falls back to index.js when index.ts is absent", () => {
+    const dir = setupTmp();
+    try {
+      const extDir = join(dir, "ponytail");
+      mkdirSync(extDir);
+      writeFileSync(join(extDir, "index.js"), "");
+      const { entries } = parseExtraExtensions(extDir);
+      expect(entries).toEqual([join(extDir, "index.js")]);
+    } finally {
+      rmSync(dir, { recursive: true });
+    }
+  });
+
+  it("warns and skips a directory without index.ts/index.js", () => {
+    const dir = setupTmp();
+    try {
+      const extDir = join(dir, "empty");
+      mkdirSync(extDir);
+      const { entries, warnings } = parseExtraExtensions(extDir);
+      expect(entries).toEqual([]);
+      expect(warnings).toHaveLength(1);
+      expect(warnings[0]).toContain("no index.ts/index.js");
+    } finally {
+      rmSync(dir, { recursive: true });
+    }
+  });
+
+  it("warns and skips a missing path (typo doesn't kill the session)", () => {
+    const { entries, warnings } = parseExtraExtensions("/tmp/does-not-exist-zzz-xyz-123");
+    expect(entries).toEqual([]);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain("path not found");
+  });
+
+  it("expands a leading ~/ using the supplied home", () => {
+    const dir = setupTmp();
+    try {
+      const extDir = join(dir, "fake-home", "ext");
+      mkdirSync(extDir, { recursive: true });
+      writeFileSync(join(extDir, "index.js"), "");
+      const { entries } = parseExtraExtensions("~/ext", {
+        home: join(dir, "fake-home"),
+      });
+      expect(entries).toEqual([join(extDir, "index.js")]);
+    } finally {
+      rmSync(dir, { recursive: true });
+    }
+  });
+
+  it("layers multiple extensions from one path-delimited list", () => {
+    const dir = setupTmp();
+    try {
+      const a = join(dir, "a.js");
+      writeFileSync(a, "");
+      const b = join(dir, "b.js");
+      writeFileSync(b, "");
+      const { entries } = parseExtraExtensions([a, b].join(delimiter));
+      expect(entries).toEqual([a, b]);
+    } finally {
+      rmSync(dir, { recursive: true });
+    }
+  });
+
+  it("trims whitespace around list entries", () => {
+    const dir = setupTmp();
+    try {
+      const a = join(dir, "a.js");
+      writeFileSync(a, "");
+      const { entries } = parseExtraExtensions(`  ${a}  `);
+      expect(entries).toEqual([a]);
+    } finally {
+      rmSync(dir, { recursive: true });
+    }
+  });
+});

package/bin/little-coder.mjs

@@ -17,6 +17,7 @@ import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { checkForUpdate } from "./update-check.mjs";
+import { parseExtraExtensions } from "./extras.mjs";
 
 // ---- 1. Node version preflight (>= 22.19.0, matching pi.dev) ----
 const MIN_NODE = [22, 19, 0];
@@ -110,6 +111,21 @@ if (existsSync(extDir)) {
   }
 }
 
+// ---- 4b. Third-party extensions via LITTLE_CODER_EXTRA_EXTENSIONS ----
+// Path-delimited list (`:` on POSIX, `;` on Windows — node:path.delimiter)
+// of extra extension paths to load alongside the bundled ones. Each entry can
+// be either a direct file path (e.g. a pi-ponytail-style `extensions/ponytail.js`)
+// or a directory containing `index.ts` / `index.js`. Survives upgrades and
+// avoids the "fork the installed npm package" workaround that issue #46 hit.
+// Parsing rules — ~/ expansion, directory-with-index resolution, one-line
+// warning for missing/unusable entries — live in ./extras.mjs so they're
+// unit-testable in isolation.
+{
+  const { entries, warnings } = parseExtraExtensions(process.env.LITTLE_CODER_EXTRA_EXTENSIONS);
+  for (const w of warnings) console.error(w);
+  for (const entry of entries) extArgs.push("--extension", entry);
+}
+
 // ---- 5. Update check (best-effort, blocks on TTY prompt only) ----
 let currentVersion = "0.0.0";
 try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "little-coder",
-  "version": "1.9.1",
+  "version": "1.9.3",
   "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": {