@openlines/opl-pi-sht 0.1.21 → 0.2.1

package/extensions/opl-init/index.ts

@@ -20,56 +20,68 @@ const MANIFESTS = new Set([
 const MAX_DEPTH = 3;
 const MAX_MEMBER_DEPTH = 3;
 const MAX_TREE_LINES = 300;
-const MAX_MANIFEST_BYTES = 2048;
+const MAX_MANIFEST_PARSE_BYTES = 262144;
 const MAX_DIR_ENTRIES = 40;
-const MAX_RULE_SOURCE_BYTES = 2048;
-
-// Instruction sources other coding agents use (see research/harness-init-comparison.md).
-// AGENTS.md is deliberately absent — it is this command's output.
-const RULE_SOURCES = [
-  ".cursorrules",
-  ".cursor/rules",
-  ".github/copilot-instructions.md",
-  "CLAUDE.md",
-  "CLAUDE.local.md",
-  ".claude/rules",
-  ".windsurfrules",
-  ".windsurf/rules",
-  ".clinerules",
-  ".devin/rules",
-];
+// Bumping this constant is how generator upgrades invalidate every
+// previously-written guide: it is a fingerprint input.
+const GUIDE_SCHEMA_VERSION = 1;
 
 type Crawl = {
   tree: string[];
   extCounts: Map<string, number>;
   manifests: { path: string; content: string }[];
   workspaceMembers: string[];
+  seen: Set<string>;
 };
 
 // Marker the model appends to AGENTS.md so future runs can detect staleness exactly.
 const FP_MARKER = /<!-- opl-init:fp (\S+) -->/;
 
 // Exact snapshot of git-tracked + untracked state. Respects .gitignore for free.
+// Content-based: HEAD + per-path content hashes of every dirty tracked file
+// (vs HEAD, so staged changes count) and every untracked file. Only the root
+// AGENTS.md is excluded, so writing the guide does not make it stale;
+// subdirectory AGENTS.md files are repository facts.
 // Returns null for non-git directories (caller falls back to fingerprintFallback).
 function fingerprintGit(root: string): string | null {
+  const head = gitOutput(root, ["rev-parse", "HEAD"]);
+  if (head === null) return null;
+  const hash = createHash("sha256").update(`schema:${GUIDE_SCHEMA_VERSION}\0head:${head}\0`);
+  // --relative keeps diff paths cwd-relative and cwd-scoped, matching
+  // ls-files --others and the crawl; without it a subdirectory session would
+  // resolve every dirty path to a nonexistent file and hash "DELETED".
+  for (const path of (gitOutput(root, ["diff", "HEAD", "--name-only", "-z", "--relative"]) ?? "").split("\0")) {
+    if (!path || path === "AGENTS.md") continue;
+    hash.update(`${path}\0`).update(hashFile(join(root, path))).update("\0");
+  }
+  for (const path of (gitOutput(root, ["ls-files", "--others", "--exclude-standard", "-z"]) ?? "").split("\0")) {
+    if (!path || path === "AGENTS.md") continue;
+    hash.update(`${path}\0`).update(hashFile(join(root, path))).update("\0");
+  }
+  return hash.digest("hex").slice(0, 16);
+}
+
+function gitOutput(root: string, args: string[]): string | null {
   try {
-    const head = execFileSync("git", ["rev-parse", "HEAD"], {
+    return execFileSync("git", args, {
       cwd: root,
       encoding: "utf8",
       stdio: ["ignore", "pipe", "ignore"],
+      maxBuffer: 64 * 1024 * 1024,
     });
-    const status = execFileSync(
-      "git",
-      ["status", "--porcelain=v1", "--untracked-files=all"],
-      { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] },
-    );
-    const relevantStatus = status.split("\n").filter(line => !line.endsWith("AGENTS.md")).join("\n");
-    return createHash("sha256").update(head).update(relevantStatus).digest("hex").slice(0, 16);
   } catch {
     return null;
   }
 }
 
+function hashFile(path: string): string {
+  try {
+    return createHash("sha256").update(readFileSync(path)).digest("hex");
+  } catch {
+    return "DELETED";
+  }
+}
+
 // ponytail: stat-only (path|size|mtime), not content hashing. Catches add/delete/
 // rename but shares the touch-without-change blind spot; only used for non-git dirs.
 function fingerprintFallback(root: string): string {
@@ -101,7 +113,7 @@ function fingerprintFallback(root: string): string {
 
   walk(root);
   parts.sort();
-  return createHash("sha256").update(parts.join("\n")).digest("hex").slice(0, 16);
+  return createHash("sha256").update(`schema:${GUIDE_SCHEMA_VERSION}\n`).update(parts.join("\n")).digest("hex").slice(0, 16);
 }
 
 function fingerprint(root: string): string {
@@ -114,6 +126,7 @@ function crawl(root: string): Crawl {
     extCounts: new Map(),
     manifests: [],
     workspaceMembers: [],
+    seen: new Set(),
   };
 
   function walk(dir: string, depth: number, prefix: string, maxDepth: number) {
@@ -144,17 +157,23 @@ function crawl(root: string): Crawl {
       }
 
       files.push(entry);
-      const extension = extname(entry) || entry;
-      result.extCounts.set(extension, (result.extCounts.get(extension) ?? 0) + 1);
-
-      if (MANIFESTS.has(entry)) {
-        try {
-          result.manifests.push({
-            path: relative(root, path),
-            content: readFileSync(path, "utf8").slice(0, MAX_MANIFEST_BYTES),
-          });
-        } catch {
-          // Skip unreadable manifests.
+      // Dedupe by absolute path: declared-member re-walks overlap the root
+      // walk, and the inventory must not double-count. Tree lines still
+      // accept shallow overlap for completeness.
+      if (!result.seen.has(path)) {
+        result.seen.add(path);
+        const extension = extname(entry) || entry;
+        result.extCounts.set(extension, (result.extCounts.get(extension) ?? 0) + 1);
+
+        if (MANIFESTS.has(entry)) {
+          try {
+            result.manifests.push({
+              path: relative(root, path),
+              content: readFileSync(path, "utf8").slice(0, MAX_MANIFEST_PARSE_BYTES),
+            });
+          } catch {
+            // Skip unreadable manifests.
+          }
         }
       }
     }
@@ -295,157 +314,194 @@ function result_tree_paths(root: string): string[] {
   return paths;
 }
 
-function packageScripts(content: string): string | null {
-  try {
-    const packageJson = JSON.parse(content);
-    if (!packageJson.scripts || !Object.keys(packageJson.scripts).length) return null;
-    return Object.entries(packageJson.scripts)
-      .map(([name, command]) => `  ${name}: ${command}`)
-      .join("\n");
-  } catch {
-    return null;
-  }
-}
-
-function findRuleSources(root: string): { path: string; detail: string }[] {
-  const found: { path: string; detail: string }[] = [];
-  for (const name of RULE_SOURCES) {
-    const path = join(root, name);
-    let stats;
+// Root-first, per-package-labeled script lines, bounded at 30 entries total.
+function aggregateScripts(manifests: { path: string; content: string }[]): string | null {
+  const lines: string[] = [];
+  const sorted = [...manifests].sort((a, b) =>
+    a.path === "package.json" ? -1 : b.path === "package.json" ? 1 : a.path.localeCompare(b.path));
+  for (const manifest of sorted) {
+    if (!manifest.path.endsWith("package.json") || lines.length >= 30) continue;
+    let parsed;
     try {
-      stats = statSync(path);
+      parsed = JSON.parse(manifest.content);
     } catch {
       continue;
     }
-    if (stats.isDirectory()) {
-      // ponytail: filenames only for rule dirs; model can read entries itself.
-      let entries: string[] = [];
-      try {
-        entries = readdirSync(path).slice(0, 20);
-      } catch {
-        continue;
-      }
-      found.push({ path: `${name}/ (${entries.length} file${entries.length === 1 ? "" : "s"})`, detail: entries.join(", ") });
-    } else {
-      try {
-        found.push({ path: name, detail: readFileSync(path, "utf8").slice(0, MAX_RULE_SOURCE_BYTES) });
-      } catch {
-        found.push({ path: name, detail: "(unreadable)" });
-      }
+    const scripts = parsed?.scripts;
+    if (!scripts || typeof scripts !== "object") continue;
+    const label = manifest.path === "package.json" ? "" : `${manifest.path.replace(/\/package\.json$/, "")}/ `;
+    for (const [name, command] of Object.entries(scripts)) {
+      if (lines.length >= 30) break;
+      lines.push(`  ${label}${name}: ${command}`);
     }
   }
-  return found;
+  return lines.length ? lines.join("\n") : null;
 }
 
-function buildContext(root: string, crawlResult: Crawl): string {
-  const extensions = [...crawlResult.extCounts.entries()]
-    .sort((a, b) => b[1] - a[1])
-    .map(([extension, count]) => `${extension} (${count})`)
-    .join(", ");
-  const sections = [
-    `## Repository crawl for: ${root}`,
-    `### Directory tree (depth ${MAX_DEPTH}; declared workspace members get their own depth-${MAX_MEMBER_DEPTH} walk; per-directory entries capped at ${MAX_DIR_ENTRIES})\n\`\`\`\n${crawlResult.tree.join("\n")}\n\`\`\``,
-    `### File counts by extension\n${extensions || "(none)"}`,
-  ];
-
-  if (crawlResult.workspaceMembers.length) {
-    sections.push(`### Declared workspace members (expanded above)\n${crawlResult.workspaceMembers.join(", ")}`);
-  }
+function buildGuide(root: string, crawlResult: Crawl, marker: string): string {
+  const topLevel = crawlResult.tree.filter(line => !line.startsWith("  ")).slice(0, 30).join(", ");
+  const scripts = aggregateScripts(crawlResult.manifests);
+  const commandBlock = scripts ? "Package scripts:\n```\n" + scripts + "\n```" : "No package scripts were detected by the repository crawl.";
+  return `# Repository Guide\n\n## What this is\n\nRepository at \`${root}\`. Use the repository files as the source of truth; the top-level inventory includes ${topLevel || "(not available)"}.\n\n## Commands\n\n${commandBlock}\n\n## Repository inventory\n\n- File types: ${[...crawlResult.extCounts.entries()].map(([extension, count]) => `${extension} (${count})`).join(", ") || "none detected"}.\n- Inspect specific files before changing behavior; this guide is a starting point, not a substitute for reading the code.\n\n## Agent workflow\n\nKeep changes focused on the requested behavior, preserve existing interfaces, and run the narrowest relevant test before the full suite. Keep secrets and generated output out of tracked configuration.\n${marker}\n`;
+}
 
-  if (crawlResult.manifests.length) {
-    // ponytail: send paths + package.json scripts only; the model can read a
-    // manifest itself if it needs the raw body. Keeps the prompt small and stable.
-    sections.push("### Manifests (read these files directly if you need more detail)");
-    for (const manifest of crawlResult.manifests) {
-      sections.push(`**${manifest.path}**`);
-      if (manifest.path.endsWith("package.json")) {
-        const scripts = packageScripts(manifest.content);
-        if (scripts) sections.push(`Scripts:\n\`\`\`\n${scripts}\n\`\`\``);
-      }
+const MAX_EVIDENCE_BYTES = 24576;
+const MAX_README_HEAD_BYTES = 2048;
+
+// Evidence the model cannot fetch itself: the deterministic stand-in for the
+// tools the refine call does not have, under a hard byte budget. The spec's
+// three parts: baseline guide, full per-package scripts blocks, readme heads.
+function evidencePacket(
+  root: string,
+  baseline: string,
+  crawlResult: { manifests: { path: string; content: string }[]; workspaceMembers: string[] },
+): string {
+  const parts = [baseline];
+  let used = Buffer.byteLength(baseline, "utf8");
+  const push = (block: string): boolean => {
+    const bytes = Buffer.byteLength(block, "utf8") + 1;
+    if (used + bytes > MAX_EVIDENCE_BYTES) {
+      parts.push("(evidence truncated)");
+      return false;
+    }
+    used += bytes;
+    parts.push(block);
+    return true;
+  };
+  for (const manifest of crawlResult.manifests) {
+    if (!manifest.path.endsWith("package.json")) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(manifest.content);
+    } catch {
+      continue;
     }
+    const scripts = parsed?.scripts;
+    if (!scripts || typeof scripts !== "object") continue;
+    const block = `=== scripts: ${manifest.path} ===\n${Object.entries(scripts).map(([name, command]) => `${name}: ${command}`).join("\n")}`;
+    if (!push(block)) return parts.join("\n");
   }
-
-  const ruleSources = findRuleSources(root);
-  if (ruleSources.length) {
-    sections.push("### Existing agent rule sources (from other coding agents)");
-    for (const source of ruleSources) {
-      sections.push(`**${source.path}**\n\`\`\`\n${source.detail}\n\`\`\``);
+  const candidates = ["README.md", "readme.md", "README", "CLAUDE.md"];
+  const paths = [...candidates, ...crawlResult.workspaceMembers.flatMap((m) => candidates.map((c) => `${m}/${c}`))];
+  for (const rel of paths) {
+    let head: string;
+    try {
+      head = readFileSync(join(root, rel), "utf8").slice(0, MAX_README_HEAD_BYTES);
+    } catch {
+      continue;
     }
+    if (!push(`=== ${rel} ===\n${head}`)) break;
   }
-
-  return sections.join("\n\n");
+  return parts.join("\n");
 }
 
-function fallbackGuide(root: string, crawlResult: Crawl, marker: string): string {
-  const topLevel = crawlResult.tree.filter(line => !line.startsWith("  ")).slice(0, 30).join(", ");
-  const scripts = crawlResult.manifests
-    .map(manifest => manifest.path.endsWith("package.json") ? packageScripts(manifest.content) : null)
-    .find(Boolean);
-  const commandBlock = scripts ? "Package scripts:\n```\n" + scripts + "\n```" : "No package scripts were detected by the repository crawl.";
-  return `# Repository Guide\n\n## What this is\n\nRepository at \`${root}\`. Use the repository files as the source of truth; the top-level inventory includes ${topLevel || "(not available)"}.\n\n## Commands\n\n${commandBlock}\n\n## Repository inventory\n\n- File types: ${[...crawlResult.extCounts.entries()].map(([extension, count]) => `${extension} (${count})`).join(", ") || "none detected"}.\n- The full crawl is available in the init task context. Inspect specific files before changing behavior.\n\n## Agent workflow\n\nKeep changes focused on the requested behavior, preserve existing interfaces, and run the narrowest relevant test before the full suite. Keep secrets and generated output out of tracked configuration.\n${marker}\n`;
+const REFINE_SYSTEM_PROMPT = [
+  "You are rewriting a repository guide for an AI coding agent.",
+  "Input: a draft guide generated from a deterministic repository crawl, plus bounded file excerpts.",
+  "Return ONLY the final Markdown document: no preamble, no code fence around the document, no HTML comments.",
+  "Do not invent facts unsupported by the input; keep the factual inventory (commands, file types, workspace members).",
+  'Prefer these sections when evidence supports them: "## What this is", "## Commands", "## Architecture", "## Configuration and installation", "## Testing and operational quirks", "## Key files". Omit unsupported sections.',
+  "Usually 250-700 words. Avoid generic contribution, Git, or pull-request advice.",
+].join("\n");
+
+// The model never owns the marker line: every opl-init:fp comment is stripped
+// and the extension's exact marker is appended as the final line.
+function finalizeRefinedGuide(text: string, marker: string): string {
+  let body = text.trim();
+  // Strip a wrapper fence only when it opens *and* closes; a guide ending in
+  // a legitimate code block keeps its closing fence.
+  if (/^```[a-zA-Z]*\s*\n/.test(body)) {
+    body = body.replace(/^```[a-zA-Z]*\s*\n/, "").replace(/\n```\s*$/, "");
+  }
+  body = body.replace(/<!-- opl-init:fp \S+ -->/g, "").trimEnd();
+  return `${body}\n${marker}\n`;
 }
 
-const PROMPT = `Generate or update AGENTS.md as an agent guide for this repository. This is an execution task, not a request for prose in chat. You MUST use the write tool to write the guide to the repository's AGENTS.md path; a response containing Markdown without writing the file is a failure. After writing, use the read tool to verify the file exists and ends with the exact fingerprint marker. Do not modify, refactor, or create any other file.
-If AGENTS.md already exists and the repository crawl below says it is current, do not overwrite or modify it. If it is marked stale, update it. If it does not exist, create it.
-
-The repository crawl below (directory tree, file counts, manifests, and any existing rule sources) is the primary source of truth. It was produced for you, so do not re-crawl, re-list, or re-scan the tree, and do not spawn subagents or task lists for this. Read a small number of specific files directly only when you must confirm a repository-specific fact the crawl does not already answer.
-
-Produce a concise, useful Markdown guide, usually 250-700 words:
-- Start with a project-specific title such as "# Repository Guide" or "# <project>".
-- Prefer these sections when supported by evidence: "## What this is", "## Commands", "## Architecture", "## Configuration and installation", "## Testing and operational quirks", and "## Key files".
-- State meaningful absences when known, such as no build, lint, or typecheck command.
-- Capture non-obvious constraints, state, deployment, security, or test-order invariants when they materially affect contributors.
-- Avoid generic contribution, Git, or pull-request advice unless the repository supplies specific facts for it.
-- Omit unsupported sections rather than inventing details.
-- If existing agent rule sources are listed below, incorporate their relevant project-specific content into the guide. Do not copy them verbatim and do not treat them as authoritative over evidence from this repository.
-- IMPORTANT: when you write or update AGENTS.md, make the very last line exactly the fingerprint marker given below (verbatim, no changes). This lets future runs detect staleness.
+// One out-of-band completion on the current model. No tools, no session
+// message: any failure returns null and the caller writes the baseline.
+// Bounded so a stalled provider cannot leave /init hanging with no UI signal
+// (the old injected turn was Esc-cancellable; this replaces that escape hatch).
+const REFINE_TIMEOUT_MS = 120000;
 
----
-`;
+async function refineGuide(ctx: any, evidence: string, marker: string): Promise<string | null> {
+  const model = ctx.model;
+  if (!model || typeof ctx.modelRegistry?.streamSimple !== "function") return null;
+  ctx.ui?.notify?.("opl-init: refining the guide with the current model...", "info");
+  try {
+    const stream = ctx.modelRegistry.streamSimple(
+      model,
+      { systemPrompt: REFINE_SYSTEM_PROMPT, messages: [{ role: "user", content: evidence, timestamp: Date.now() }], tools: [] },
+      { reasoning: false, signal: AbortSignal.timeout(REFINE_TIMEOUT_MS) },
+    );
+    const result = await stream.result();
+    if (!result || result.stopReason === "error" || result.stopReason === "aborted") return null;
+    const text = (result.content ?? [])
+      .filter((part: any) => part.type === "text")
+      .map((part: any) => part.text)
+      .join("\n");
+    return text.trim() ? finalizeRefinedGuide(text, marker) : null;
+  } catch {
+    return null;
+  }
+}
 
-// Named export for fixture tests (tests/opl-init-crawl.test.mjs).
-export { crawl };
+// Named exports for fixture tests (tests/opl-init-*.test.mjs).
+export { crawl, fingerprint, evidencePacket, finalizeRefinedGuide, refineGuide };
 
 export default function (pi: ExtensionAPI) {
   pi.registerCommand("init", {
-    description: "[opl-init] Crawl the repository and generate an AGENTS.md contributor guide",
+    description: "[opl-init] Crawl + refine AGENTS.md out-of-band; zero model calls when current",
     handler: async (_args, ctx) => {
       const root = ctx.cwd;
       const agentsPath = join(root, "AGENTS.md");
-      const currentFp = fingerprint(root);
-      const exists = existsSync(agentsPath);
-
-      let storedFp: string | null = null;
-      if (exists) {
+      const storedFp = () => {
         try {
-          storedFp = readFileSync(agentsPath, "utf8").match(FP_MARKER)?.[1] ?? null;
+          return readFileSync(agentsPath, "utf8").match(FP_MARKER)?.[1] ?? null;
         } catch {
-          storedFp = null;
+          return null;
         }
-      }
+      };
 
-      if (exists && storedFp === currentFp) {
+      let currentFp = fingerprint(root);
+      if (existsSync(agentsPath) && storedFp() === currentFp) {
         ctx.ui.notify("AGENTS.md is current; /init will not modify it.", "info");
         return;
       }
 
-      const status = !exists
-        ? "AGENTS.md status: missing; create it."
-        : storedFp === null
-          ? "AGENTS.md status: no fingerprint marker found; treat as stale and update it."
-          : "AGENTS.md status: stale (fingerprint mismatch); update it.";
+      if (!ctx.isIdle()) {
+        ctx.ui.notify("opl-init: waiting for the current agent run to settle before writing AGENTS.md.", "info");
+        await ctx.waitForIdle();
+        // The settling run may have moved the tree; recompute before crawling.
+        currentFp = fingerprint(root);
+        if (existsSync(agentsPath) && storedFp() === currentFp) {
+          ctx.ui.notify("AGENTS.md is current; /init will not modify it.", "info");
+          return;
+        }
+      }
+
       const marker = `<!-- opl-init:fp ${currentFp} -->`;
+      // Regenerating replaces the whole file, including hand-edited prose; the
+      // repository's version control is the recovery path.
       const crawlResult = crawl(root);
+      const baseline = buildGuide(root, crawlResult, marker);
+      const refined = await refineGuide(ctx, evidencePacket(root, baseline, crawlResult), marker);
+
       try {
-        writeFileSync(agentsPath, fallbackGuide(root, crawlResult, marker), "utf8");
-        ctx.ui.notify("AGENTS.md baseline written; the agent will refine it from the crawl.", "info");
+        writeFileSync(agentsPath, refined ?? baseline, "utf8");
       } catch (error: any) {
-        ctx.ui.notify(`Could not write AGENTS.md baseline: ${error?.message || error}`, "error");
+        ctx.ui.notify(`Could not write AGENTS.md: ${error?.message || error}`, "error");
+        return;
       }
 
-      pi.sendUserMessage(
-        `${PROMPT}\n${status}\nFingerprint marker to append as the last line: ${marker}\n\n${buildContext(root, crawlResult)}`,
+      ctx.ui.notify(
+        refined
+          ? "AGENTS.md written from the repository crawl (model-refined)."
+          : "refine failed; wrote deterministic AGENTS.md from the repository crawl.",
+        "info",
       );
+      // Terminal: pi docs say code after ctx.reload() runs in the old frame.
+      await ctx.reload();
+      return;
     },
   });
 }

package/extensions/opl-input/README.md

@@ -15,11 +15,12 @@ No commands, flags, or shortcuts. It replaces the standard editor at session sta
 - **Scroll-aware borders**: Editor scroll indicators are embedded in the top or bottom border when the input has more content than fits.
 - **Slash-menu placement**: The slash menu is rendered below the input with configurable gap and indentation.
 - **Responsive rendering**: Narrow terminals fall back to the native editor rendering; the companion is hidden below 40 columns.
+- **Shared idle heartbeat**: this component owns the bundle's only render timer. With the companion disabled it slows to one repaint per second instead of ten, which still advances the footer's elapsed/time-per-second cells while Pi is idle.
 - **Hex and theme colors**: Color settings accept Pi theme tokens or six-digit hex colors.
 
 ## Mode styling precedence
 
-Exactly one style applies at a time, in this order: Bash (`!` input) > active `opl-modes` appearance > hardcoded mode fallback. The compiled fallbacks are normal: `❯`/`accent`/`border`; chat: `»`/`chatModeBorder`; and plan/execute: `⏸`/`customMessageLabel`.
+Exactly one style applies at a time, in this order: Bash (`!` input) > active `opl-modes` appearance > hardcoded mode fallback. The compiled fallbacks are normal: `❯`/`accent`/`border`; chat: `»`/`borderAccent`; and plan/execute: `⏸`/`customMessageLabel`.
 
 ## Configuration
 
@@ -54,7 +55,7 @@ Create `~/.pi/agent/configs/opl-input.json` or copy [`configs/opl-input.json.sam
 
 | Field | Type | Default | Description |
 |---|---|---:|---|
-| `companion.enabled` | boolean | `false` | Show the animated companion above the input. |
+| `companion.enabled` | boolean | `false` | Show the animated companion above the input. The idle repaint that drives it runs every 100 ms when enabled and every 1 s when disabled (the footer's time-based cells ride the same tick). |
 | `companion.color` | color | `"accent"` | Companion color. |
 | `companion.type` | string | unset | Select a named entry from `companion.types`; built-in `dog` also has a fallback shape (`"cat"` uses the default ears). |
 | `companion.ears` | string | cat ears | Directly override the companion's top line; wins over `type`. |
@@ -74,9 +75,10 @@ Every color option accepts either:
   - Syntax: `syntaxComment`, `syntaxKeyword`, `syntaxFunction`, `syntaxVariable`, `syntaxString`, `syntaxNumber`, `syntaxType`, `syntaxOperator`, `syntaxPunctuation`
   - Thinking borders: `thinkingOff`, `thinkingMinimal`, `thinkingLow`, `thinkingMedium`, `thinkingHigh`, `thinkingXhigh`, `thinkingMax`
   - Special: `bashMode`
-- **A six-digit hex color** — e.g. `"#c07898"` (rendered as ANSI truecolor, downgraded automatically on 256-color terminals).
+- **A hex color** — `"#c07898"`, or the three-digit shorthand `"#abc"` (expanded to `#aabbcc`; rendered as ANSI truecolor, downgraded automatically on 256-color terminals).
 
 Invalid theme tokens fall back to the theme's `border` token; invalid hex renders uncolored rather than crashing.
+- A mode `prefix` is clamped to one terminal cell (continuation lines reserve a single space), so a wide or multi-character `appearance.prefix` such as `👀` is truncated to one cell rather than pushing the box border past the editor width.
 
 ## Architecture
 

package/extensions/opl-input/index.ts

@@ -1,10 +1,10 @@
 import { CustomEditor, type ExtensionAPI, type Theme } from "@earendil-works/pi-coding-agent";
 import type { TUI, EditorTheme } from "@earendil-works/pi-tui";
 import type { KeybindingsManager } from "@earendil-works/pi-coding-agent";
-import { visibleWidth } from "@earendil-works/pi-tui";
+import { visibleWidth, truncateToWidth } from "@earendil-works/pi-tui";
 import { CONFIG, COMPANION_PADDING, MIN_WIDTH_FOR_COMPANION } from "./config.js";
 import { resolveModeStyle, type ModeAppearance } from "./mode-style.js";
-import { applyColor, CompanionAnimator, startRenderTimer } from "./utils.js";
+import { applyColor, CompanionAnimator, COMPANION_TICK_MS, IDLE_REPAINT_MS, startRenderTimer } from "./utils.js";
 
 // ─── Helpers ──────────────────────────────────────────────────────────────
 const ANSI_RE = /\x1b\[[0-9;]*m|\x1b\[0?m/g;
@@ -43,10 +43,15 @@ class ChatInput extends CustomEditor {
 		this.inputTheme = theme;
 
 		// Animate companion even when idle — tick drives state machine
-		this.stopCompanionTimer = startRenderTimer(() => {
-			this.animator.tick(Date.now());
-			this.tui.requestRender();
-		});
+		// With the companion hidden this component still owns the only idle repaint in the
+		// bundle (footer time-based cells read it), so the tick slows down instead of stopping.
+		this.stopCompanionTimer = startRenderTimer(
+			() => {
+				this.animator.tick(Date.now());
+				this.tui.requestRender();
+			},
+			CONFIG.COMPANION_ENABLED ? COMPANION_TICK_MS : IDLE_REPAINT_MS,
+		);
 	}
 
 	dispose(): void {
@@ -74,7 +79,9 @@ class ChatInput extends CustomEditor {
 		const style = resolveModeStyle({ bash: isBash, mode: mode.mode, appearance: mode.appearance });
 		const border = (s: string) => applyColor(this.uiTheme, style.borderColor, s);
 		const accent = (s: string) => applyColor(this.uiTheme, style.prefixColor, s);
-		const prefix = style.prefix;
+		// The layout reserves exactly one cell for the prefix (continuation lines pad with " "),
+		// so a wider configured prefix would push the box border past `width`.
+		const prefix = truncateToWidth(style.prefix, 1);
 
 		if (CONFIG.BOXED_VIEW) {
 			return this.renderBoxed(stock, contentWidth, width, border, accent, prefix);

package/extensions/opl-input/mode-style.ts

@@ -21,7 +21,7 @@ export interface ResolvedModeStyle {
 
 const MODE_DEFAULTS: Record<string, Required<ModeAppearance>> = {
 	off: { prefix: "❯", prefixColor: "accent", borderColor: "border" },
-	chat: { prefix: "»", prefixColor: "chatModeBorder", borderColor: "chatModeBorder" },
+	chat: { prefix: "»", prefixColor: "borderAccent", borderColor: "borderAccent" },
 	plan: { prefix: "⏸", prefixColor: "customMessageLabel", borderColor: "customMessageLabel" },
 	execute: { prefix: "⏸", prefixColor: "customMessageLabel", borderColor: "customMessageLabel" },
 };

package/extensions/opl-input/utils.ts

@@ -48,7 +48,9 @@ function isHexColor(color: string): boolean {
 }
 
 function hexToAnsi(hex: string): string {
-	const h = hex.replace("#", "");
+	// Accept the #abc shorthand so a three-digit value renders the same as #aabbcc.
+	let h = hex.replace("#", "");
+	if (/^[0-9a-fA-F]{3}$/.test(h)) h = h.split("").map((c) => c + c).join("");
 	if (!/^[0-9a-fA-F]{6}$/.test(h)) return "";
 	const r = parseInt(h.slice(0, 2), 16);
 	const g = parseInt(h.slice(2, 4), 16);
@@ -56,14 +58,23 @@ function hexToAnsi(hex: string): string {
 	return `\x1b[38;2;${r};${g};${b}m`;
 }
 
-export function startRenderTimer(render: () => void): () => void {
-	const timer = setInterval(render, 100);
+/** Animation cadence while the companion is visible. */
+export const COMPANION_TICK_MS = 100;
+/** Idle repaint cadence with the companion off: keeps time-based footer cells advancing without 10 repaints/second. */
+export const IDLE_REPAINT_MS = 1000;
+
+export function startRenderTimer(render: () => void, periodMs: number = COMPANION_TICK_MS): () => void {
+	const timer = setInterval(render, periodMs);
 	return () => clearInterval(timer);
 }
 
 export function applyColor(theme: Theme, color: string, text: string): string {
 	if (isHexColor(color)) {
-		return `${hexToAnsi(color)}${text}\x1b[0m`;
+		// A malformed hex yields "": render the text with no escape rather than an empty
+		// color plus a stray reset.
+		const ansi = hexToAnsi(color);
+		if (!ansi) return text;
+		return `${ansi}${text}\x1b[0m`;
 	}
 	try {
 		return theme.fg(color as ThemeColor, text);
@@ -86,7 +97,7 @@ export interface CompanionState {
 
 type Phase = "face" | "ears" | "full" | "none";
 
-const TICK_MS = 100; // matches setInterval in ChatInput
+const TICK_MS = COMPANION_TICK_MS; // companion animation frame budget
 const R = (min: number, max: number) => min + Math.random() * (max - min);
 
 export class CompanionAnimator {