@openlines/opl-pi-sht 0.2.11 → 0.3.0

package/extensions/opl-init/README.md

@@ -9,13 +9,19 @@ Generates or refreshes a repository-specific `AGENTS.md` guide through `/init`.
 
 ## Extension features
 
-- Produces a deterministic repository guide with package commands and a file-type inventory, then refines it with **one** `ctx.modelRegistry.streamSimple()` call on the current model (pi >= 0.86.0). The refinement never enters the conversation: no synthetic user message, no turn in the transcript, no `write` tool needed, and read-only/chat/plan modes refine identically.
+- Produces a deterministic repository guide with package commands and a file-type inventory, then refines it with **one** `ctx.modelRegistry.streamSimple()` call on the current model at `reasoning: "minimal"` (pi >= 0.86.0). The refinement never enters the conversation: no synthetic user message, no turn in the transcript, no `write` tool needed, and read-only/chat/plan modes refine identically. `"minimal"` is the lowest thinking level pi-ai accepts; an earlier `{ reasoning: false }` read as *unset*, so the call silently paid the provider's default thinking level.
 - The model only sees a bounded evidence packet (the baseline guide, every `package.json`'s full scripts block, and the first ~2 KB of each root/workspace `README`/`CLAUDE.md`, hard 24 KB budget with an explicit truncation line). The crawl is the only explorer.
 - The extension owns the fingerprint marker: model output is stripped of fences and any `opl-init:fp` comment, and the exact marker is appended as the final line. A model can never corrupt or fake a "current" guide.
 - Refine failure (no model, no auth, provider error, empty output) writes the deterministic baseline and notifies `refine failed` - `/init` only fails to write if the write itself fails.
 - Mid-session `/init` waits for the agent to settle (`ctx.waitForIdle()`), recomputes the fingerprint, and only then crawls. It never steers or interrupts the task in flight.
-- Crawls to depth 3, ignores generated/dependency directories, caps directory listings at 40 entries, caps the rendered tree at 300 lines with explicit omission markers, and re-walks declared `pnpm-workspace.yaml`/Cargo members with their own depth-3 budget.
-- Fingerprints dirty tracked + untracked file **contents** (plus HEAD and a generator schema version), excluding the root `AGENTS.md` itself, so writing the guide never makes it immediately stale and re-editing an already-modified file is never read as "current".
+- Crawls to depth 3, ignores generated/dependency directories, caps directory listings at 40 entries and the rendered tree at 300 lines with explicit omission markers, and re-walks declared `pnpm-workspace.yaml`/Cargo members with their own depth-3 budget. Workspace globs escape every metacharacter except `*` and `?`, because real member patterns carry them (`packages/app(one`, `libs/c++/*`); an unescaped one threw `SyntaxError` and aborted the entire crawl. A glob that compiles to nothing is skipped, reported in `Crawl.skippedGlobs`, and named in a tree line so the skip is visible in the guide.
+- Fingerprints dirty tracked + untracked files (plus HEAD and a generator schema version), excluding the root `AGENTS.md` itself, so writing the guide never makes it immediately stale and re-editing an already-modified file is never read as "current". Content hashing is **budgeted** (`FP_LIMITS`: 2 MB per file, 32 MB total, 5,000 paths): past the per-file or total ceiling a file contributes `name|size|mtime` instead of its bytes, and past the path ceiling a path contributes its name plus `OVER_CAP`. Budget state is folded into the digest, so the fingerprint cannot oscillate. Without the ceilings a single 200 MB build artifact cost 143 ms and +200 MB of RSS on every `/init`.
+
+## User-owned operational notes
+
+`/init` preserves an existing `## Operational notes` section verbatim, including nested `###` subsections, whitespace and line endings. The section ends at the next level-1 or level-2 Markdown heading outside a fenced code block, or at the end of the document. The final `opl-init:fp` marker belongs to the extension, not the section. The preserved section is placed after the regenerated guide and before that marker, whether model refinement succeeds or falls back to the deterministic crawl. Other hand-edited sections are replaced; if the protected heading is absent, generation is unchanged.
+
+Use one section with that exact, case-sensitive title. Duplicate sections cancel the update, as does a detected file change during refinement; resolve duplicates or rerun `/init` after editing. This protects against `/init` updates only, not ordinary agent edits or other programs.
 
 ## Requirements
 
@@ -23,4 +29,6 @@ Refinement needs pi 0.86.0 or newer (`ctx.modelRegistry.streamSimple`, `ctx.relo
 
 ## Architecture
 
-`index.ts` owns crawling, fingerprinting, the evidence packet, the model call, output validation, and writing. Git repositories fingerprint `schema version + HEAD + sha256 of every dirty tracked and untracked file` (root `AGENTS.md` excluded); non-git repositories use sorted path/size/mtime tuples. `/init` writes the file itself and reloads the session context; the main agent is never enlisted.
+Every `git` call goes through one guard. A repository is attacker-chosen data and can declare programs of its own (`[diff "x"] textconv`, `core.fsmonitor`, `core.hooksPath`, or a system/user config naming a helper) that git runs while answering what looks like a read-only query. The guard passes `--no-pager`, `-c core.fsmonitor=false`, `-c core.hooksPath=`, `-c protocol.ext.allow=never`, `-c credential.helper=`, `GIT_CONFIG_NOSYSTEM`, `GIT_ATTR_NOSYSTEM`, `GIT_TERMINAL_PROMPT=0` and `GIT_OPTIONAL_LOCKS=0`, plus `--no-ext-diff --no-textconv` on diff-family subcommands. Probes still ask for name-only or porcelain output, because that is all a fingerprint needs. The block is duplicated in `opl-footer/git-status.ts` - installs are per-directory, so the two cannot share a module - and `tests/net-guard-parity.test.mjs` fails if the copies drift.
+
+`index.ts` owns crawling, fingerprinting, the evidence packet, the model call, output validation, and writing. Git repositories fingerprint `schema version + HEAD + a budgeted digest of dirty tracked and untracked files` (root `AGENTS.md` excluded, content replaced by `size|mtime` past the byte ceilings); non-git repositories use sorted path/size/mtime tuples. `gitOutput` caps captured output at 4 MB because every probe asks for path lists or a single value. `/init` writes the file itself and reloads the session context; the main agent is never enlisted.

package/extensions/opl-init/index.ts

@@ -31,6 +31,7 @@ type Crawl = {
   extCounts: Map<string, number>;
   manifests: { path: string; content: string }[];
   workspaceMembers: string[];
+  skippedGlobs: string[];
   seen: Set<string>;
 };
 
@@ -42,41 +43,147 @@ const FP_MARKER = /<!-- opl-init:fp (\S+) -->/;
 // (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.
+// /init computes the fingerprint synchronously on the command path, and a workspace can
+// hold a dataset, model weights or a recording. Content-hashing everything cost 135 ms and
+// 245 MB RSS for a single 200 MB file, so large files are represented by their metadata and
+// the whole pass runs under a path and byte budget.
+// Known blind spot, accepted deliberately: a rewrite that keeps size and mtime identical, or
+// any change past the caps, is invisible until a change the fingerprint can see happens.
+const FP_LIMITS = {
+  maxFileBytes: 2 * 1024 * 1024,
+  maxTotalBytes: 32 * 1024 * 1024,
+  maxPaths: 5000,
+};
+
+type FpLimits = typeof FP_LIMITS;
+type FpBudget = { bytes: number; paths: number; capped: boolean };
+
 // Returns null for non-git directories (caller falls back to fingerprintFallback).
-function fingerprintGit(root: string): string | null {
+function fingerprintGit(root: string, limits: FpLimits = FP_LIMITS): 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`);
+  const budget: FpBudget = { bytes: 0, paths: 0, capped: false };
   // --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");
+    hashFingerprintPath(hash, root, path, budget, limits);
   }
   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");
+    hashFingerprintPath(hash, root, path, budget, limits);
   }
+  // Fold the budget state in so crossing a cap changes the digest once and then stays
+  // stable: an oscillating digest would make every /init run regenerate the guide.
+  hash.update(`budget:${budget.paths}:${budget.bytes}:${budget.capped ? 1 : 0}\0`);
   return hash.digest("hex").slice(0, 16);
 }
 
+function hashFingerprintPath(
+  hash: ReturnType<typeof createHash>,
+  root: string,
+  path: string,
+  budget: FpBudget,
+  limits: FpLimits,
+): void {
+  if (!path || path === "AGENTS.md") return;
+  // The name is always hashed even past a cap, so adding or removing a file is still
+  // visible; only content stops being read.
+  hash.update(`${path}\0`).update(budget.paths >= limits.maxPaths ? "OVER_CAP\0" : hashFile(join(root, path), budget, limits)).update("\0");
+  budget.paths++;
+  if (budget.paths >= limits.maxPaths) budget.capped = true;
+}
+
+// BEGIN SHARED GIT GUARD
+// A repository is attacker-chosen data: its local config, `.gitattributes` and system
+// config can name programs that git runs while answering what looks like a read-only query.
+// Measured on git 2.54: `git diff HEAD` executes a declared `[diff "x"] textconv` driver,
+// while `--name-only`, `status --porcelain`, `ls-files` and `rev-parse` do not. Every call
+// still goes through this guard so a future content-diff call cannot reintroduce the
+// execution path. Duplicated per extension because install.sh installs one directory at a
+// time; tests/net-guard-parity.test.mjs fails if the copies drift.
+const SAFE_GIT_GLOBAL_ARGS = [
+  "--no-pager",
+  "-c",
+  "core.fsmonitor=false",
+  "-c",
+  "core.hooksPath=",
+  "-c",
+  "protocol.ext.allow=never",
+  "-c",
+  "credential.helper=",
+];
+
+/** Refuse external content handlers. Diff-family subcommands only: plumbing rejects them. */
+const SAFE_GIT_DIFF_FLAGS = ["--no-ext-diff", "--no-textconv"];
+const GIT_DIFF_COMMANDS = new Set(["diff", "log", "show", "stash", "range-diff", "format-patch"]);
+
+const SAFE_GIT_ENV: Record<string, string> = {
+  // /etc/gitconfig and the user's own config can name helpers; a repo probe must not read them.
+  GIT_CONFIG_NOSYSTEM: "1",
+  GIT_ATTR_NOSYSTEM: "1",
+  GIT_PAGER: "cat",
+  // A credential prompt would hang the caller instead of failing fast.
+  GIT_TERMINAL_PROMPT: "0",
+  GIT_ASKPASS: "",
+  SSH_ASKPASS: "",
+  // Read-only plumbing must not create or wait on index.lock.
+  GIT_OPTIONAL_LOCKS: "0",
+};
+
+export function safeGitInvocation(args: string[]): string[] {
+  const [subcommand, ...rest] = args;
+  const diffFlags = subcommand && GIT_DIFF_COMMANDS.has(subcommand) ? SAFE_GIT_DIFF_FLAGS : [];
+  // A missing subcommand must not reach execFileSync/spawn as an undefined argv slot.
+  return subcommand
+    ? [...SAFE_GIT_GLOBAL_ARGS, subcommand, ...diffFlags, ...rest]
+    : [...SAFE_GIT_GLOBAL_ARGS, ...rest];
+}
+
+export function gitGuardEnv(base: Record<string, string | undefined> = process.env): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const [key, value] of Object.entries(base)) {
+    if (typeof value === "string") env[key] = value;
+  }
+  return { ...env, ...SAFE_GIT_ENV };
+}
+// END SHARED GIT GUARD
+
 function gitOutput(root: string, args: string[]): string | null {
+  // Name-only/porcelain plumbing only; the guard above refuses patch content.
   try {
-    return execFileSync("git", args, {
+    return execFileSync("git", safeGitInvocation(args), {
       cwd: root,
+      env: gitGuardEnv(),
       encoding: "utf8",
       stdio: ["ignore", "pipe", "ignore"],
-      maxBuffer: 64 * 1024 * 1024,
+      // Name-only and porcelain output is path lists: 4 MB is on the order of 100k paths.
+      // A repo that needs more makes execFileSync throw, which reads as "not a git
+      // directory" and falls through to the stat-only fingerprintFallback.
+      maxBuffer: 4 * 1024 * 1024,
     });
   } catch {
     return null;
   }
 }
 
-function hashFile(path: string): string {
+function hashFile(path: string, budget: FpBudget, limits: FpLimits): string {
+  let stats;
+  try {
+    stats = statSync(path);
+  } catch {
+    return "DELETED";
+  }
+  // Above either threshold the entry is represented by metadata instead of bytes: a
+  // change to size or mtime is still detected, and the pass stays bounded.
+  if (!stats.isFile() || stats.size > limits.maxFileBytes || budget.bytes + stats.size > limits.maxTotalBytes) {
+    budget.capped = true;
+    return `meta:${stats.size}:${Math.round(stats.mtimeMs)}`;
+  }
   try {
-    return createHash("sha256").update(readFileSync(path)).digest("hex");
+    const body = readFileSync(path);
+    budget.bytes += body.length;
+    return createHash("sha256").update(body).digest("hex");
   } catch {
     return "DELETED";
   }
@@ -126,6 +233,7 @@ function crawl(root: string): Crawl {
     extCounts: new Map(),
     manifests: [],
     workspaceMembers: [],
+    skippedGlobs: [],
     seen: new Set(),
   };
 
@@ -190,6 +298,7 @@ function crawl(root: string): Crawl {
         break;
       }
       const entry = all[i];
+      if (entry === undefined) continue;
       result.tree.push(`${prefix}${entry}`);
       if (entry.endsWith("/") && depth < maxDepth) {
         walk(join(dir, entry.slice(0, -1)), depth + 1, `${prefix}  `, maxDepth);
@@ -202,7 +311,7 @@ function crawl(root: string): Crawl {
   // Manifest-first monorepo expansion: enumerate declared workspace members
   // with a fresh depth budget so packages/foo/src is not penalized by its
   // grouping prefix.
-  for (const member of workspaceMembers(root)) {
+  for (const member of workspaceMembers(root, result.skippedGlobs)) {
     if (result.tree.length >= MAX_TREE_LINES) break;
     const abs = join(root, member);
     let stats;
@@ -225,23 +334,42 @@ function crawl(root: string): Crawl {
   if (result.tree.length >= MAX_TREE_LINES) {
     result.tree.push(`(tree truncated at ${MAX_TREE_LINES} entries)`);
   }
+  if (result.skippedGlobs.length > 0) {
+    result.tree.push(
+      `(skipped workspace glob(s) that could not be compiled: ${result.skippedGlobs.join(", ")})`,
+    );
+  }
   return result;
 }
 
 // ponytail: naive glob matcher supporting only what workspace files use in
-// practice: `**` across segments, `*` within a segment, optional trailing "/".
-function globToRegExp(pattern: string): RegExp {
+// practice: `**` across segments, `*` within a segment, `?` for one character,
+// optional trailing "/". Everything else is escaped, so a directory name that is
+// itself regex syntax (`libs/c++/*`) matches literally instead of throwing.
+// Returns null for a pattern that cannot be compiled: workspace files are
+// user-authored, and one bad line must not abort /init.
+function globToRegExp(pattern: string): RegExp | null {
   const cleaned = pattern.replace(/\/$/, "");
-  const source = cleaned
-    .split("/**/")
-    .map((seg) => seg.replace(/[*]/g, "[^/]*"))
-    .join("(?:/.*)?");
-  return new RegExp(`^${source}$`);
+  if (cleaned === "") return null;
+  try {
+    const source = cleaned
+      .split("/**/")
+      .map((segment) =>
+        segment
+          .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+          .replace(/\*/g, "[^/]*")
+          .replace(/\?/g, "[^/]"),
+      )
+      .join("(?:/.*)?");
+    return new RegExp(`^${source}$`);
+  } catch {
+    return null;
+  }
 }
 
 // ponytail: line-based subset parsing of pnpm-workspace.yaml and Cargo.toml
 // [workspace] members. Full YAML/TOML parsing not warranted for glob lists.
-function workspaceMembers(root: string): string[] {
+function workspaceMembers(root: string, skipped: string[]): string[] {
   const globs: string[] = [];
 
   try {
@@ -254,7 +382,8 @@ function workspaceMembers(root: string): string[] {
         inPackages = false;
       } else if (inPackages) {
         const match = line.match(/^\s*-\s*["']?([^"'#]+)/);
-        if (match) globs.push(match[1].trim());
+        const pkg = match?.[1];
+        if (pkg) globs.push(pkg.trim());
       }
     }
   } catch {
@@ -264,10 +393,14 @@ function workspaceMembers(root: string): string[] {
   try {
     const toml = readFileSync(join(root, "Cargo.toml"), "utf8");
     const section = toml.match(/\[workspace\]([\s\S]*?)(?:\n\[|\s*$)/);
-    const membersBlock = section?.[1].match(/members\s*=\s*\[([^\]]*)\]/s);
+    const membersBlock = section?.[1]?.match(/members\s*=\s*\[([^\]]*)\]/s);
     if (membersBlock) {
-      for (const m of membersBlock[1].matchAll(/["']([^"']+)["']/g)) {
-        globs.push(m[1]);
+      const memberList = membersBlock[1];
+      if (memberList) {
+        for (const m of memberList.matchAll(/["']([^"']+)["']/g)) {
+          const name = m[1];
+          if (name) globs.push(name);
+        }
       }
     }
   } catch {
@@ -277,6 +410,10 @@ function workspaceMembers(root: string): string[] {
   const members = new Set<string>();
   for (const glob of globs) {
     const re = globToRegExp(glob);
+    if (!re) {
+      if (!skipped.includes(glob)) skipped.push(glob);
+      continue;
+    }
     // Match against shallow candidate paths from the tree we already walked,
     // plus one extra readdir of likely parent dirs. Simple approach: test every
     // tree dir line's relative path.
@@ -431,7 +568,9 @@ async function refineGuide(ctx: any, evidence: string, marker: string): Promise<
     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) },
+      // ThinkingLevel has no "off": "minimal" is the cheapest level the adapters accept.
+      // `false` was silently dropped as "unset", so the refinement paid the provider default.
+      { reasoning: "minimal", signal: AbortSignal.timeout(REFINE_TIMEOUT_MS) },
     );
     const result = await stream.result();
     if (!result || result.stopReason === "error" || result.stopReason === "aborted") return null;
@@ -445,8 +584,50 @@ async function refineGuide(ctx: any, evidence: string, marker: string): Promise<
   }
 }
 
+// Offsets retain the user's original line endings and whitespace. Only ATX
+// headings outside fenced code blocks delimit the owned section.
+function operationalSections(text: string): { start: number; end: number }[] {
+  const sections: { start: number; end: number }[] = [];
+  let active: { start: number; end: number } | undefined;
+  let fence: { char: string; length: number } | undefined;
+  for (const match of text.matchAll(/[^\n]*(?:\n|$)/g)) {
+    const line = match[0].replace(/\r?\n$/, "");
+    const offset = match.index;
+    const fenced = line.match(/^ {0,3}(`{3,}|~{3,})(.*)$/);
+    if (fence) {
+      if (fenced?.[1]?.[0] === fence.char && fenced[1].length >= fence.length && !fenced[2]?.trim()) fence = undefined;
+      continue;
+    }
+    if (fenced?.[1] && (fenced[1][0] !== "`" || !fenced[2]?.includes("`"))) {
+      fence = { char: fenced[1][0]!, length: fenced[1].length };
+      continue;
+    }
+    const heading = line.match(/^ {0,3}(#{1,2})(?:[ \t]+(.*)|[ \t]*)$/);
+    if (!heading) continue;
+    if (active) { active.end = offset; active = undefined; }
+    if (heading[1] === "##" && heading[2]?.replace(/[ \t]+#+[ \t]*$/, "").trim() === "Operational notes") {
+      active = { start: offset, end: text.length };
+      sections.push(active);
+    }
+  }
+  return sections;
+}
+
+function guideWithoutFinalMarker(text: string): string {
+  return text.replace(/(^|\n)<!-- opl-init:fp \S+ -->[ \t]*(?:\r?\n)?$/, "$1");
+}
+
+function mergeOperationalNotes(generated: string, owned: string, marker: string): string {
+  let body = guideWithoutFinalMarker(generated);
+  // Discard generated versions: the existing user section is authoritative.
+  for (const section of operationalSections(body).reverse()) {
+    body = body.slice(0, section.start) + body.slice(section.end);
+  }
+  return `${body.trimEnd()}\n\n${owned}${owned.endsWith("\n") ? "" : "\n"}${marker}\n`;
+}
+
 // Named exports for fixture tests (tests/opl-init-*.test.mjs).
-export { crawl, fingerprint, evidencePacket, finalizeRefinedGuide, refineGuide };
+export { crawl, fingerprint, fingerprintGit, FP_LIMITS, evidencePacket, finalizeRefinedGuide, refineGuide };
 
 export default function (pi: ExtensionAPI) {
   pi.registerCommand("init", {
@@ -480,14 +661,34 @@ export default function (pi: ExtensionAPI) {
       }
 
       const marker = `<!-- opl-init:fp ${currentFp} -->`;
-      // Regenerating replaces the whole file, including hand-edited prose; the
-      // repository's version control is the recovery path.
+      let original: string | null;
+      let owned: string | undefined;
+      try {
+        original = existsSync(agentsPath) ? readFileSync(agentsPath, "utf8") : null;
+        const body = guideWithoutFinalMarker(original ?? "");
+        const sections = operationalSections(body);
+        if (sections.length > 1) {
+          ctx.ui.notify("AGENTS.md has duplicate Operational notes sections; /init will not modify it.", "error");
+          return;
+        }
+        const section = sections[0];
+        if (section) owned = body.slice(section.start, section.end);
+      } catch (error: any) {
+        ctx.ui.notify(`Could not read AGENTS.md: ${error?.message || error}`, "error");
+        return;
+      }
       const crawlResult = crawl(root);
       const baseline = buildGuide(root, crawlResult, marker);
       const refined = await refineGuide(ctx, evidencePacket(root, baseline, crawlResult), marker);
 
       try {
-        writeFileSync(agentsPath, refined ?? baseline, "utf8");
+        const latest = existsSync(agentsPath) ? readFileSync(agentsPath, "utf8") : null;
+        if (latest !== original) {
+          ctx.ui.notify("AGENTS.md changed during /init; update cancelled. Run /init again.", "error");
+          return;
+        }
+        const generated = refined ?? baseline;
+        writeFileSync(agentsPath, owned === undefined ? generated : mergeOperationalNotes(generated, owned, marker), "utf8");
       } catch (error: any) {
         ctx.ui.notify(`Could not write AGENTS.md: ${error?.message || error}`, "error");
         return;

package/extensions/opl-input/README.md

@@ -4,7 +4,7 @@ Replaces Pi's default chat editor with a mode-aware custom editor. Native editor
 
 ## Commands, flags, and shortcuts
 
-No commands, flags, or shortcuts. It replaces the standard editor at session start.
+No commands, flags, or shortcuts of its own. It replaces the standard editor at session start. Its settings are editable through the `/configurator` shell (Input tab, hotkey `i`); a save writes `opl-input.json` and reports that the change takes effect after `/reload`.
 
 ## Extension features
 
@@ -67,7 +67,7 @@ The companion requires at least 40 terminal columns and reserves three top-paddi
 
 Every color option accepts either:
 
-- **A Pi theme token** — one of the 45 tokens defined by Pi's `Theme`:
+- **A Pi theme token** — a color name from Pi's theme schema (56 names at pi 0.87.0 and 1.1.0, 7 of them `*Bg` fills). The ones that matter here:
   - Core: `accent`, `border`, `borderAccent`, `borderMuted`, `success`, `error`, `warning`, `muted`, `dim`, `text`
   - Messages/content: `thinkingText`, `searchMatchText`, `userMessageText`, `customMessageText`, `customMessageLabel`
   - Tools: `toolTitle`, `toolOutput`, `toolDiffAdded`, `toolDiffRemoved`, `toolDiffContext`
@@ -75,7 +75,7 @@ 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 hex color** — `"#c07898"`, or the three-digit shorthand `"#abc"` (expanded to `#aabbcc`; rendered as ANSI truecolor, downgraded automatically on 256-color terminals).
+- **A hex color** — `"#c07898"`, or the three-digit shorthand `"#abc"` (expanded to `#aabbcc`). Hex values are emitted as ANSI truecolor (`38;2;r;g;b`); there is no 256-color downgrade in this extension, so on a 256-only terminal a hex color may render approximately or not at all, while a theme token renders correctly.
 
 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.
@@ -83,3 +83,17 @@ Invalid theme tokens fall back to the theme's `border` token; invalid hex render
 ## Architecture
 
 `index.ts` installs the editor integration and disposes companion render timers on editor replacement or session shutdown; `mode-style.ts` resolves Bash > published mode appearance > compiled fallback; `config.ts` loads editor and companion settings; and `utils.ts` handles color and rendering helpers. `opl-modes` is the sole publisher of active mode appearance through `globalThis.__agentMode`.
+
+Two couplings are worth knowing before editing this extension:
+
+- **pi-tui's text output.** Re-framing the editor means recognising its horizontal borders and
+  its scroll indicator, and pi-tui exposes neither as an API: they are the literal strings `─`
+  and `─── ↑ 3 more `. Those markers are collected in one place (`isSolidBorder`,
+  `scrollIndicatorText`, `isBorderLike` in `index.ts`) and
+  `tests/opl-input-pi-tui-markers.test.mjs` asserts the installed pi-tui still emits them. They
+  were byte-identical in pi-tui 0.87.0, 0.99.1 and 1.1.0; a failure there means the format
+  changed and the re-framing needs updating, not that the test is wrong.
+- **The bundle's idle heartbeat.** This component owns the only render timer, so the footer's
+  time-based cells advance because of it. Disabling `opl-input` freezes that clock; with
+  `companion.enabled: false` the tick slows to one repaint per `IDLE_REPAINT_MS` rather than
+  stopping.

package/extensions/opl-input/config.ts

@@ -1,6 +1,6 @@
-import { readFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
 export const DEFAULT_CONFIG = {
 	BOX_PAD_X: 1,
@@ -29,11 +29,65 @@ interface ChatInputUserConfig {
 	};
 }
 
-const CONFIG_PATH = join(homedir(), ".pi", "agent", "configs", "opl-input.json");
+/** Resolved per call so a custom `PI_AGENT_DIR` (pi's own agent dir) is honoured. */
+export function configPath(): string {
+	return join(getAgentDir(), "configs", "opl-input.json");
+}
+
+/** Subset of fields the configurator tab is allowed to edit. */
+export interface EditableInputConfig {
+	boxedView?: boolean;
+	companion?: {
+		enabled?: boolean;
+		type?: string;
+	};
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Read the live config as a loose record ({} on absence or malformed), preserving unknown keys. */
+export function readInputConfig(): Record<string, unknown> {
+	try {
+		const parsed = JSON.parse(readFileSync(configPath(), "utf8"));
+		return isPlainObject(parsed) ? parsed : {};
+	} catch {
+		return {};
+	}
+}
+
+/** Merge only the editable fields into the live file. Returns false when nothing changed. */
+export function saveInputConfig(patch: EditableInputConfig): boolean {
+	const current = readInputConfig();
+	const next: Record<string, unknown> = { ...current };
+
+	if (typeof patch.boxedView === "boolean") next.boxedView = patch.boxedView;
+
+	if (patch.companion) {
+		const enabled = patch.companion.enabled;
+		const type = patch.companion.type;
+		const hasEnabled = typeof enabled === "boolean";
+		const hasType = typeof type === "string" && type.length > 0;
+		if (hasEnabled || hasType) {
+			const companion = isPlainObject(next.companion) ? { ...next.companion } : {};
+			if (hasEnabled) companion.enabled = enabled;
+			if (hasType) companion.type = type;
+			next.companion = companion;
+		}
+	}
+
+	if (JSON.stringify(next) === JSON.stringify(current)) return false;
+
+	const file = configPath();
+	mkdirSync(dirname(file), { recursive: true });
+	writeFileSync(file, JSON.stringify(next, null, 2) + "\n", "utf8");
+	return true;
+}
 
 function loadUserConfig(): ChatInputUserConfig {
 	try {
-		const raw = readFileSync(CONFIG_PATH, "utf8");
+		const raw = readFileSync(configPath(), "utf8");
 		return JSON.parse(raw) as ChatInputUserConfig;
 	} catch {
 		return {};