jeo-code 0.4.8 → 0.5.0

package/README.ja.md

@@ -150,11 +150,11 @@ CI は `.github/workflows/npm-publish.yml` で公開します — GitHub リリ
 ## 変更履歴 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.5.0]** (2026-06-14) — Performance: workspace-scan, workflow-state, and DNA-Claw HUD caches; plus a credential-safety fix that never wipes OAuth over an invalid config.
+- **[0.4.9]** (2026-06-14) — Live-frame width-clamp (content-sized height) replaces the constant-height approach, typed text shows during a running turn, and a docs/AGENTS refresh.
 - **[0.4.8]** (2026-06-14) — Live-frame stability: constant-height live turn, renderer self-heal off-by-one fix, and frame-safe child-stdout sanitizing — no more duplicate model bar or torn escapes.
 - **[0.4.7]** (2026-06-14) — Detached subagents + `subagent` control tool, live shaded in-flight output, registry-driven providers, fuller `read` budget, styled italics in the final report, and `gjc` retired.
 - **[0.4.6]** (2026-06-14) — Width-correct forge cards for CJK/emoji, red borders on failed tool cards, aligned `ooo ralph` monitor HUD, and a per-theme user-card palette.
-- **[0.4.5]** (2026-06-14) — First-class filesystem make/remove tools.
-- **[0.4.4]** (2026-06-13) — Live subagent status mirroring, always-useful Ctrl+O activity tail, read lineRange crash guard.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.ko.md

@@ -150,11 +150,11 @@ CI는 `.github/workflows/npm-publish.yml`로 배포합니다 — GitHub 릴리
 ## 변경 이력 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.5.0]** (2026-06-14) — Performance: workspace-scan, workflow-state, and DNA-Claw HUD caches; plus a credential-safety fix that never wipes OAuth over an invalid config.
+- **[0.4.9]** (2026-06-14) — Live-frame width-clamp (content-sized height) replaces the constant-height approach, typed text shows during a running turn, and a docs/AGENTS refresh.
 - **[0.4.8]** (2026-06-14) — Live-frame stability: constant-height live turn, renderer self-heal off-by-one fix, and frame-safe child-stdout sanitizing — no more duplicate model bar or torn escapes.
 - **[0.4.7]** (2026-06-14) — Detached subagents + `subagent` control tool, live shaded in-flight output, registry-driven providers, fuller `read` budget, styled italics in the final report, and `gjc` retired.
 - **[0.4.6]** (2026-06-14) — Width-correct forge cards for CJK/emoji, red borders on failed tool cards, aligned `ooo ralph` monitor HUD, and a per-theme user-card palette.
-- **[0.4.5]** (2026-06-14) — First-class filesystem make/remove tools.
-- **[0.4.4]** (2026-06-13) — Live subagent status mirroring, always-useful Ctrl+O activity tail, read lineRange crash guard.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.md

@@ -150,11 +150,11 @@ Required npm token permissions (repository secret `NPM_TOKEN`):
 ## Changelog
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.5.0]** (2026-06-14) — Performance: workspace-scan, workflow-state, and DNA-Claw HUD caches; plus a credential-safety fix that never wipes OAuth over an invalid config.
+- **[0.4.9]** (2026-06-14) — Live-frame width-clamp (content-sized height) replaces the constant-height approach, typed text shows during a running turn, and a docs/AGENTS refresh.
 - **[0.4.8]** (2026-06-14) — Live-frame stability: constant-height live turn, renderer self-heal off-by-one fix, and frame-safe child-stdout sanitizing — no more duplicate model bar or torn escapes.
 - **[0.4.7]** (2026-06-14) — Detached subagents + `subagent` control tool, live shaded in-flight output, registry-driven providers, fuller `read` budget, styled italics in the final report, and `gjc` retired.
 - **[0.4.6]** (2026-06-14) — Width-correct forge cards for CJK/emoji, red borders on failed tool cards, aligned `ooo ralph` monitor HUD, and a per-theme user-card palette.
-- **[0.4.5]** (2026-06-14) — First-class filesystem make/remove tools.
-- **[0.4.4]** (2026-06-13) — Live subagent status mirroring, always-useful Ctrl+O activity tail, read lineRange crash guard.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.zh.md

@@ -150,11 +150,11 @@ CI 通过 `.github/workflows/npm-publish.yml` 发布 — GitHub 发布 release
 ## 更新日志 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.5.0]** (2026-06-14) — Performance: workspace-scan, workflow-state, and DNA-Claw HUD caches; plus a credential-safety fix that never wipes OAuth over an invalid config.
+- **[0.4.9]** (2026-06-14) — Live-frame width-clamp (content-sized height) replaces the constant-height approach, typed text shows during a running turn, and a docs/AGENTS refresh.
 - **[0.4.8]** (2026-06-14) — Live-frame stability: constant-height live turn, renderer self-heal off-by-one fix, and frame-safe child-stdout sanitizing — no more duplicate model bar or torn escapes.
 - **[0.4.7]** (2026-06-14) — Detached subagents + `subagent` control tool, live shaded in-flight output, registry-driven providers, fuller `read` budget, styled italics in the final report, and `gjc` retired.
 - **[0.4.6]** (2026-06-14) — Width-correct forge cards for CJK/emoji, red borders on failed tool cards, aligned `ooo ralph` monitor HUD, and a per-theme user-card palette.
-- **[0.4.5]** (2026-06-14) — First-class filesystem make/remove tools.
-- **[0.4.4]** (2026-06-13) — Live subagent status mirroring, always-useful Ctrl+O activity tail, read lineRange crash guard.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jeo-code",
-  "version": "0.4.8",
+  "version": "0.5.0",
   "description": "Clean, highly optimized AI coding agent using spec-first loop",
   "type": "module",
   "main": "src/cli.ts",

package/src/AGENTS.md

@@ -1,5 +1,5 @@
 <!-- Parent: ../AGENTS.md -->
-<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-14 -->
 
 # src
 
@@ -9,9 +9,12 @@ Core application source code for the `jeo-code` CLI and agent runtime. It orches
 ## Key Files
 | File | Description |
 |------|-------------|
+| `autopilot.ts` | Brief description of purpose |
+| `bun-imports.d.ts` | TypeScript declarations for Bun built-ins and raw module imports |
 | `cli.ts` | The main binary entrypoint |
 | `index.ts` | Library exports |
-| `bun-imports.d.ts` / `md-modules.d.ts` | TypeScript declarations for Bun built-ins and raw module imports |
+| `ledger.ts` | Brief description of purpose |
+| `md-modules.d.ts` | TypeScript declarations for Bun built-ins and raw module imports |
 
 ## Subdirectories
 | Directory | Purpose |

package/src/agent/AGENTS.md

@@ -1,5 +1,5 @@
 <!-- Parent: ../AGENTS.md -->
-<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-14 -->
 
 # agent
 
@@ -9,13 +9,33 @@ The core runtime loop, tool registry, session management, and state persistence
 ## Key Files
 | File | Description |
 |------|-------------|
+| `bash-fixups.ts` | Brief description of purpose |
+| `compaction.ts` | Brief description of purpose |
+| `config-schema.ts` | Brief description of purpose |
+| `context-files.ts` | Brief description of purpose |
+| `engine.ts` | Brief description of purpose |
+| `hooks.ts` | Brief description of purpose |
+| `json.ts` | Brief description of purpose |
 | `loop.ts` | The primary execution loop orchestrating model calls and tool execution |
-| `tools.ts` | Built-in tool definitions (bash, read, write, edit, etc.) |
-| `state.ts` | File-backed state and session persistence (`.jeo/state/`) |
-| `session.ts` | Session context building, compaction, and history management |
+| `memory.ts` | Brief description of purpose |
+| `model-recency.ts` | Brief description of purpose |
+| `output-minimizer.ts` | Brief description of purpose |
+| `output-util.ts` | Brief description of purpose |
 | `plan.ts` | Subagent planning structures and validation |
+| `seed.ts` | Brief description of purpose |
+| `session.ts` | Session context building, compaction, and history management |
+| `state.ts` | File-backed state and session persistence (`.jeo/state/`) |
 | `step-budget.ts` | gjc-style flexible step budgeting: progress-scored extensions, hard cap, fail-fast |
-| `subagents.ts` / `task-tool.ts` | Delegation mechanisms and background execution of task subagents |
+| `subagent-registry.ts` | Brief description of purpose |
+| `subagent-tool.ts` | Brief description of purpose |
+| `subagents.ts` | Brief description of purpose |
+| `task-tool.ts` | Brief description of purpose |
+| `todo-tool.ts` | Brief description of purpose |
+| `tokenizer.ts` | Brief description of purpose |
+| `tool-output.ts` | Brief description of purpose |
+| `tool-registry.ts` | Brief description of purpose |
+| `tools.ts` | Built-in tool definitions (bash, read, write, edit, etc.) |
+| `web-search.ts` | Brief description of purpose |
 
 ## Subdirectories
 | Directory | Purpose |

package/src/agent/context-files.ts

@@ -78,7 +78,10 @@ const EXPLICIT_GUIDANCE_FILES = [".agents/oma-config.yaml", ".agents/oma-config.
 
 // Module-level cache of the downward scan, keyed by resolved cwd. The scan is
 // independent of $HOME (it only walks the cwd subtree), so caching by cwd is safe.
+// Bounded LRU: a long-running session that scans many distinct cwds (subagents,
+// worktrees, /view of other trees) must not grow this Map without bound.
 const workspaceScanCache = new Map<string, WorkspaceScan>();
+const WORKSPACE_SCAN_CACHE_CAP = 32;
 
 function segsEqual(a: readonly string[], b: readonly string[]): boolean {
   if (a.length !== b.length) return false;
@@ -161,8 +164,18 @@ async function scanWorkspaceDownwards(resolvedCwd: string): Promise<WorkspaceSca
 async function getWorkspaceScan(cwd: string): Promise<WorkspaceScan> {
   const resolvedCwd = path.resolve(cwd);
   const cached = workspaceScanCache.get(resolvedCwd);
-  if (cached) return cached;
+  if (cached) {
+    // LRU refresh: re-insert so the most-recently-used entry is evicted last.
+    workspaceScanCache.delete(resolvedCwd);
+    workspaceScanCache.set(resolvedCwd, cached);
+    return cached;
+  }
   const scan = await scanWorkspaceDownwards(resolvedCwd);
+  // Evict the oldest entry (Map preserves insertion order) once at capacity.
+  if (workspaceScanCache.size >= WORKSPACE_SCAN_CACHE_CAP) {
+    const oldest = workspaceScanCache.keys().next().value;
+    if (oldest !== undefined) workspaceScanCache.delete(oldest);
+  }
   workspaceScanCache.set(resolvedCwd, scan);
   return scan;
 }

package/src/agent/dev/AGENTS.md

@@ -1,5 +1,5 @@
-<!-- Parent: ../../AGENTS.md -->
-<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-14 -->
 
 # dev
 
@@ -9,6 +9,11 @@ Developer-specific agent tooling and spec automation.
 ## Key Files
 | File | Description |
 |------|-------------|
+| `advanced-analyzer.ts` | Brief description of purpose |
+| `evolution-bridge.ts` | Brief description of purpose |
+| `evolution-logger.ts` | Brief description of purpose |
+| `self-analysis.ts` | Brief description of purpose |
+| `self-improve.ts` | Brief description of purpose |
 | `spec-automation.ts` | Tools to sync `.specify/` artifacts to ooo seeds |
 
 ## Subdirectories

package/src/agent/state.ts

@@ -233,7 +233,7 @@ type ParsedFile =
   | { kind: "ok"; config: Config }
   | { kind: "missing" }
   | { kind: "bad-json"; warned: boolean }
-  | { kind: "invalid"; message: string; warned: boolean };
+  | { kind: "invalid"; message: string; warned: boolean; rawObject?: unknown };
 const configReadCache = new Map<string, { mtimeMs: number; size: number; parsed: ParsedFile }>();
 const CONFIG_CACHE_CAP = 8;
 
@@ -259,7 +259,9 @@ async function readParsedConfigFile(): Promise<ParsedFile> {
     const result = parseConfig(raw);
     parsed = result.ok
       ? { kind: "ok", config: result.config as Config }
-      : { kind: "invalid", message: result.message, warned: false };
+      // Keep the raw JSON object on a schema-invalid (but JSON-valid) config so
+      // readRawGlobalConfig can salvage the credential blocks instead of dropping them.
+      : { kind: "invalid", message: result.message, warned: false, rawObject: raw };
   } catch {
     parsed = { kind: "bad-json", warned: false };
   }
@@ -271,6 +273,20 @@ async function readParsedConfigFile(): Promise<ParsedFile> {
   return parsed;
 }
 
+/** Overlay the `oauth` + `providers` credential blocks from a schema-invalid (but
+ *  JSON-valid) config's raw object onto `base`. A single bad scalar field (e.g. a
+ *  non-string defaultModel) must never cost the user their stored credentials — neither
+ *  when resolving them at runtime (readGlobalConfig) nor when persisting (readRawGlobalConfig). */
+function salvageCredentials(base: Config, parsed: ParsedFile): Config {
+  if (parsed.kind !== "invalid" || !parsed.rawObject || typeof parsed.rawObject !== "object") return base;
+  const ro = parsed.rawObject as Record<string, unknown>;
+  if (ro.oauth && typeof ro.oauth === "object") base.oauth = structuredClone(ro.oauth) as Config["oauth"];
+  if (ro.providers && typeof ro.providers === "object") {
+    base.providers = { ...base.providers, ...(structuredClone(ro.providers) as Config["providers"]) };
+  }
+  return base;
+}
+
 export async function readGlobalConfig(): Promise<Config> {
   const parsed = await readParsedConfigFile();
   if (parsed.kind === "bad-json" || parsed.kind === "invalid") {
@@ -280,7 +296,9 @@ export async function readGlobalConfig(): Promise<Config> {
       const detail = parsed.kind === "invalid" ? ` is invalid (${parsed.message})` : " is not valid JSON";
       process.stderr.write(`[jeo] ${globalConfigPath()}${detail}; using environment defaults.\n`);
     }
-    return withEnvOverlay(envDefaultConfig());
+    // Credential salvage: keep oauth/providers from a JSON-valid-but-schema-invalid
+    // config so the runtime stays authenticated (and a later write repairs the file).
+    return withEnvOverlay(salvageCredentials(envDefaultConfig(), parsed));
   }
   if (parsed.kind === "missing") return withEnvOverlay(envDefaultConfig());
   return withEnvOverlay(structuredClone(parsed.config));
@@ -307,9 +325,15 @@ export async function saveGlobalConfig(config: Config): Promise<void> {
  *  JEO_*_MODEL role tiers, OLLAMA_HOST/OPENAI_BASE_URL) are never baked into
  *  ~/.jeo/config.json by an unrelated `/agents`/`/roles`/`/model save`. */
 export async function readRawGlobalConfig(): Promise<Config> {
-  const clean: Config = { providers: {}, defaultModel: DEFAULT_MODEL, thinkingLevel: "medium" };
   const parsed = await readParsedConfigFile();
-  return parsed.kind === "ok" ? structuredClone(parsed.config) : clean;
+  if (parsed.kind === "ok") return structuredClone(parsed.config);
+  // CREDENTIAL SAFETY: when the on-disk config is JSON-valid but fails schema validation
+  // on some unrelated field, salvage the `oauth` + `providers` blocks. Without this, the
+  // next saveConfigPatch (e.g. an auto token refresh that patches ONE provider) bases on
+  // a clean config and silently wipes every OTHER stored credential — the "OAuth de-authed
+  // after a session" bug. The invalid scalar field is dropped (reset to default).
+  const clean: Config = { providers: {}, defaultModel: DEFAULT_MODEL, thinkingLevel: "medium" };
+  return salvageCredentials(clean, parsed);
 }
 
 /** Merge a patch onto the RAW on-disk config and persist. The `build` callback
@@ -326,17 +350,65 @@ export function getLocalJeoDir(cwd: string = process.cwd()): string {
   return path.join(cwd, ".jeo");
 }
 
+// mtime+size-validated cache for the small per-skill workflow-state JSON. readWorkflowState
+// runs repeatedly (the mutation guard reads before every mutating tool), so re-reading +
+// re-parsing each call is wasteful. CROSS-PROCESS-SAFE: a write by another process bumps
+// mtime/size → forces a fresh read, so the security-sensitive guard never serves a stale
+// lock. Same-process write/clear update or drop the entry directly. LRU-capped.
+const workflowStateCache = new Map<string, { mtimeMs: number; size: number; value: WorkflowState | null }>();
+const WORKFLOW_STATE_CACHE_CAP = 16;
+
+function cacheWorkflowState(statePath: string, mtimeMs: number, size: number, value: WorkflowState | null): void {
+  workflowStateCache.delete(statePath);
+  if (workflowStateCache.size >= WORKFLOW_STATE_CACHE_CAP) {
+    const oldest = workflowStateCache.keys().next().value;
+    if (oldest !== undefined) workflowStateCache.delete(oldest);
+  }
+  workflowStateCache.set(statePath, { mtimeMs, size, value });
+}
+
+async function loadWorkflowStateFile(statePath: string, strict: boolean): Promise<WorkflowState | null> {
+  let st: { mtimeMs: number; size: number };
+  try {
+    st = await fs.stat(statePath);
+  } catch (err) {
+    workflowStateCache.delete(statePath);
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
+    if (strict) throw err;
+    return null;
+  }
+  const hit = workflowStateCache.get(statePath);
+  if (hit && hit.mtimeMs === st.mtimeMs && hit.size === st.size) {
+    workflowStateCache.delete(statePath); // LRU refresh
+    workflowStateCache.set(statePath, hit);
+    return hit.value;
+  }
+  let data: string;
+  try {
+    data = await fs.readFile(statePath, "utf-8");
+  } catch (err) {
+    workflowStateCache.delete(statePath);
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
+    if (strict) throw err;
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(data) as WorkflowState;
+    cacheWorkflowState(statePath, st.mtimeMs, st.size, parsed);
+    return parsed;
+  } catch {
+    workflowStateCache.delete(statePath);
+    if (strict) throw new Error(`workflow state ${statePath} is corrupt (invalid JSON)`);
+    return null;
+  }
+}
+
 export async function readWorkflowState(
   skill: "deep-interview" | "ralplan" | "team" | "ultragoal",
   cwd: string = process.cwd()
 ): Promise<WorkflowState | null> {
   const statePath = path.join(getLocalJeoDir(cwd), "state", `${skill}-state.json`);
-  try {
-    const data = await fs.readFile(statePath, "utf-8");
-    return JSON.parse(data) as WorkflowState;
-  } catch {
-    return null;
-  }
+  return loadWorkflowStateFile(statePath, false);
 }
 
 /**
@@ -349,18 +421,7 @@ export async function readWorkflowStateStrict(
   cwd: string = process.cwd()
 ): Promise<WorkflowState | null> {
   const statePath = path.join(getLocalJeoDir(cwd), "state", `${skill}-state.json`);
-  let data: string;
-  try {
-    data = await fs.readFile(statePath, "utf-8");
-  } catch (err) {
-    if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
-    throw err;
-  }
-  try {
-    return JSON.parse(data) as WorkflowState;
-  } catch {
-    throw new Error(`workflow state ${statePath} is corrupt (invalid JSON)`);
-  }
+  return loadWorkflowStateFile(statePath, true);
 }
 
 export async function writeWorkflowState(
@@ -382,6 +443,14 @@ export async function writeWorkflowState(
     await fs.unlink(tmpPath).catch(() => {});
     throw err;
   }
+  // Cache the just-written state keyed on the new file fingerprint so the next read
+  // (often the mutation guard milliseconds later) is served from memory.
+  try {
+    const st = await fs.stat(statePath);
+    cacheWorkflowState(statePath, st.mtimeMs, st.size, state);
+  } catch {
+    workflowStateCache.delete(statePath);
+  }
   return statePath;
 }
 
@@ -393,6 +462,7 @@ export async function clearWorkflowState(
   try {
     await fs.unlink(statePath);
   } catch {}
+  workflowStateCache.delete(statePath);
 }
 
 /**

package/src/ai/AGENTS.md

@@ -1,5 +1,5 @@
 <!-- Parent: ../AGENTS.md -->
-<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-14 -->
 
 # ai
 
@@ -9,9 +9,20 @@ Abstractions for LLM inference, provider management, tool formatting, and token
 ## Key Files
 | File | Description |
 |------|-------------|
-| `registry.ts` | Central registry for available providers and model resolution |
+| `index.ts` | Brief description of purpose |
+| `model-catalog-compat.ts` | Brief description of purpose |
+| `model-catalog.ts` | Brief description of purpose |
+| `model-discovery.ts` | Brief description of purpose |
+| `model-enrich.ts` | Brief description of purpose |
+| `model-manager.ts` | Brief description of purpose |
+| `model-picker.ts` | Brief description of purpose |
+| `model-registry.ts` | Brief description of purpose |
+| `pricing.ts` | Brief description of purpose |
+| `provider-registry.ts` | Brief description of purpose |
+| `provider-status.ts` | Brief description of purpose |
+| `register-providers.ts` | Brief description of purpose |
+| `sse.ts` | Brief description of purpose |
 | `types.ts` | Common interfaces for AI requests, responses, and streams |
-| `format.ts` | Conversion between internal tool schemas and provider-specific formats |
 
 ## Subdirectories
 | Directory | Purpose |

package/src/ai/providers/AGENTS.md

@@ -1,5 +1,5 @@
-<!-- Parent: ../../AGENTS.md -->
-<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-14 -->
 
 # providers
 
@@ -10,10 +10,12 @@ Concrete implementations for various LLM providers, translating generic requests
 | File | Description |
 |------|-------------|
 | `anthropic.ts` | Anthropic Claude integration |
-| `openai.ts` | OpenAI (and Codex backend) integration |
-| `gemini.ts` | Google Gemini (and Cloud Code Assist) integration |
 | `antigravity.ts` | Antigravity desktop-app OAuth client integration |
+| `errors.ts` | Brief description of purpose |
+| `gemini.ts` | Google Gemini (and Cloud Code Assist) integration |
 | `ollama.ts` | Local Ollama integration |
+| `openai-responses.ts` | Brief description of purpose |
+| `openai.ts` | OpenAI (and Codex backend) integration |
 
 ## Subdirectories
 *(None)*

package/src/auth/AGENTS.md

@@ -1,5 +1,5 @@
 <!-- Parent: ../AGENTS.md -->
-<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-14 -->
 
 # auth
 
@@ -9,8 +9,13 @@ Authentication and credential management for OAuth flows and API keys. Ensures s
 ## Key Files
 | File | Description |
 |------|-------------|
-| `store.ts` | Secure credential storage mechanism |
-| `config.ts` | Resolution of keys from environment variables and config files |
+| `callback-server.ts` | Brief description of purpose |
+| `index.ts` | Brief description of purpose |
+| `oauth.ts` | Brief description of purpose |
+| `pkce.ts` | Brief description of purpose |
+| `refresh.ts` | Brief description of purpose |
+| `storage.ts` | Brief description of purpose |
+| `types.ts` | Brief description of purpose |
 
 ## Subdirectories
 | Directory | Purpose |

package/src/auth/flows/AGENTS.md

@@ -1,5 +1,5 @@
-<!-- Parent: ../../AGENTS.md -->
-<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-14 -->
 
 # flows
 
@@ -9,8 +9,12 @@ Specific OAuth flow implementations for various providers.
 ## Key Files
 | File | Description |
 |------|-------------|
-| `oauth.ts` / `pkce.ts` | Generic OAuth and PKCE utilities |
-| `*.ts` | Provider-specific login flows (e.g., anthropic, openai, gemini) |
+| `anthropic.ts` | Brief description of purpose |
+| `antigravity.ts` | Brief description of purpose |
+| `google-project.ts` | Brief description of purpose |
+| `google.ts` | Brief description of purpose |
+| `index.ts` | Brief description of purpose |
+| `openai.ts` | Brief description of purpose |
 
 ## Subdirectories
 *(None)*
@@ -27,6 +31,11 @@ Specific OAuth flow implementations for various providers.
 - Loopback HTTP servers for receiving OAuth callbacks.
 
 ## Dependencies
-*(None)*
+
+### Internal
+{References to other parts of the codebase this depends on}
+
+### External
+{Key external packages/libraries used}
 
 <!-- MANUAL: -->

package/src/cli/AGENTS.md

@@ -1,5 +1,5 @@
 <!-- Parent: ../AGENTS.md -->
-<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-14 -->
 
 # cli
 
@@ -9,8 +9,8 @@ Command-line interface routing, argument parsing, and initialization logic. Defi
 ## Key Files
 | File | Description |
 |------|-------------|
-| `parser.ts` | Argument parsing and flag validation |
-| `router.ts` | Dispatches CLI commands to their respective implementations |
+| `index.ts` | Brief description of purpose |
+| `runner.ts` | Brief description of purpose |
 
 ## Subdirectories
 *(None)*

package/src/commands/AGENTS.md

@@ -1,5 +1,5 @@
 <!-- Parent: ../AGENTS.md -->
-<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-14 -->
 
 # commands
 
@@ -9,10 +9,28 @@ Concrete implementations of `jeo` subcommands (e.g., launch, setup, team, ultrag
 ## Key Files
 | File | Description |
 |------|-------------|
+| `approve.ts` | Brief description of purpose |
+| `auth.ts` | Brief description of purpose |
+| `chat.ts` | Brief description of purpose |
+| `deep-interview.ts` | Brief description of purpose |
+| `doctor.ts` | Brief description of purpose |
+| `evolve-core.ts` | Brief description of purpose |
+| `evolve.ts` | Brief description of purpose |
+| `export.ts` | Brief description of purpose |
 | `launch.ts` | The primary interactive/one-shot execution command |
+| `mcp.ts` | Brief description of purpose |
+| `ooo-seed.ts` | Brief description of purpose |
+| `ralplan.ts` | Brief description of purpose |
+| `resume.ts` | Brief description of purpose |
+| `session.ts` | Brief description of purpose |
+| `setup-helpers.ts` | Brief description of purpose |
 | `setup.ts` | Guided configuration command |
+| `skills.ts` | Brief description of purpose |
+| `state.ts` | Brief description of purpose |
+| `status.ts` | Brief description of purpose |
 | `team.ts` | Multi-agent coordination command |
-| `status.ts` / `update.ts` | Inspection and maintenance commands |
+| `ultragoal.ts` | Brief description of purpose |
+| `update.ts` | Brief description of purpose |
 
 ## Subdirectories
 *(None)*

package/src/commands/launch.ts

@@ -1418,13 +1418,13 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
               return;
             }
           }
-          // Mid-turn additional input is committed (and shown) ONLY on Enter (above):
-          // the running turn does NOT echo half-typed text per keystroke. Captured
-          // printable input accumulates silently in the draft buffer and surfaces as a
-          // `user` card the moment Enter lifts it into the steering inbox (or folds into
-          // the next prompt if the turn ends first). JEO_LIVE_DRAFT=1 restores the
-          // legacy live per-keystroke echo in the input box.
-          if (captured && jeoEnv("LIVE_DRAFT") === "1") {
+          // Mid-turn typing is echoed LIVE into the input box so the field never looks
+          // frozen/disabled while a turn runs — the typed text IS captured, so it must be
+          // visible. This updates the in-frame input box via the differential renderer
+          // only; it never leaks into scrollback/history (native readline echo stays
+          // suppressed for the whole turn). On Enter the draft is lifted into the steering
+          // inbox and surfaces as a `user` card (above). JEO_NO_LIVE_DRAFT=1 opts out.
+          if (captured && jeoEnv("NO_LIVE_DRAFT") !== "1") {
             tui.setLivePromptInput(queueBusySnapshot?.().text ?? "");
           }
         },

package/src/mcp/AGENTS.md

@@ -1,5 +1,5 @@
 <!-- Parent: ../AGENTS.md -->
-<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-14 -->
 
 # mcp
 
@@ -9,8 +9,10 @@ Model Context Protocol (MCP) integration, allowing `jeo-code` to expose tools or
 ## Key Files
 | File | Description |
 |------|-------------|
+| `index.ts` | Brief description of purpose |
+| `protocol.ts` | Brief description of purpose |
 | `server.ts` | MCP server implementation (if exposing tools) |
-| `client.ts` | MCP client implementation (for consuming external tools) |
+| `tools.ts` | Brief description of purpose |
 
 ## Subdirectories
 *(None)*

package/src/prompts/AGENTS.md

@@ -1,5 +1,5 @@
 <!-- Parent: ../AGENTS.md -->
-<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-14 -->
 
 # prompts
 
@@ -7,9 +7,7 @@
 Bundled system prompts, role definitions, and workflow skill documentation for the agent.
 
 ## Key Files
-| File | Description |
-|------|-------------|
-| `system.md` | Core system prompt template |
+*(None)*
 
 ## Subdirectories
 | Directory | Purpose |

package/src/prompts/agents/AGENTS.md

@@ -1,5 +1,5 @@
-<!-- Parent: ../../AGENTS.md -->
-<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-14 -->
 
 # agents
 
@@ -9,10 +9,10 @@ Role-specific system prompts defining the behavior of subagents (executor, plann
 ## Key Files
 | File | Description |
 |------|-------------|
-| `executor.md` | Mutating agent for executing bounded tasks |
-| `planner.md` | Read-only agent for sequencing tasks |
 | `architect.md` | Read-only agent for structural review |
 | `critic.md` | Read-only agent for plan critique |
+| `executor.md` | Mutating agent for executing bounded tasks |
+| `planner.md` | Read-only agent for sequencing tasks |
 
 ## Subdirectories
 *(None)*
@@ -30,6 +30,11 @@ Role-specific system prompts defining the behavior of subagents (executor, plann
 *(None)*
 
 ## Dependencies
-*(None)*
+
+### Internal
+{References to other parts of the codebase this depends on}
+
+### External
+{Key external packages/libraries used}
 
 <!-- MANUAL: -->

package/src/prompts/skills/AGENTS.md

@@ -1,5 +1,5 @@
-<!-- Parent: ../../AGENTS.md -->
-<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-14 -->
 
 # skills
 
@@ -7,16 +7,16 @@
 Bundled workflow skills offering specialized, multi-step procedures for the agent.
 
 ## Key Files
-*(See subdirectories)*
+*(None)*
 
 ## Subdirectories
 | Directory | Purpose |
 |-----------|---------|
+| `deep-dive/` | What it contains (see `deep-dive/AGENTS.md`) |
 | `deep-interview/` | Socratic requirements gathering |
 | `ralplan/` | Spec-first planning and consensus building |
 | `team/` | Coordinated multi-agent execution |
 | `ultragoal/` | Durable verification and ledger tracking |
-| `gjc/` | Legacy parity configurations |
 
 ## For AI Agents
 
@@ -31,6 +31,11 @@ Bundled workflow skills offering specialized, multi-step procedures for the agen
 *(None)*
 
 ## Dependencies
-*(None)*
+
+### Internal
+{References to other parts of the codebase this depends on}
+
+### External
+{Key external packages/libraries used}
 
 <!-- MANUAL: -->

package/src/prompts/skills/deep-dive/AGENTS.md

@@ -1,5 +1,5 @@
 <!-- Parent: ../AGENTS.md -->
-<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-14 -->
 
 # deep-dive
 
@@ -26,6 +26,11 @@ Bundled SKILL.md for the `deep-dive` workflow.
 *(None)*
 
 ## Dependencies
-*(None)*
+
+### Internal
+{References to other parts of the codebase this depends on}
+
+### External
+{Key external packages/libraries used}
 
 <!-- MANUAL: -->

package/src/prompts/skills/deep-interview/AGENTS.md

@@ -1,5 +1,5 @@
 <!-- Parent: ../AGENTS.md -->
-<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-14 -->
 
 # deep-interview
 
@@ -26,6 +26,11 @@ Bundled SKILL.md for the `deep-interview` workflow.
 *(None)*
 
 ## Dependencies
-*(None)*
+
+### Internal
+{References to other parts of the codebase this depends on}
+
+### External
+{Key external packages/libraries used}
 
 <!-- MANUAL: -->

package/src/prompts/skills/ralplan/AGENTS.md

@@ -1,5 +1,5 @@
 <!-- Parent: ../AGENTS.md -->
-<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-14 -->
 
 # ralplan
 
@@ -26,6 +26,11 @@ Bundled SKILL.md for the `ralplan` workflow.
 *(None)*
 
 ## Dependencies
-*(None)*
+
+### Internal
+{References to other parts of the codebase this depends on}
+
+### External
+{Key external packages/libraries used}
 
 <!-- MANUAL: -->

package/src/prompts/skills/team/AGENTS.md

@@ -1,5 +1,5 @@
 <!-- Parent: ../AGENTS.md -->
-<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-14 -->
 
 # team
 
@@ -26,6 +26,11 @@ Bundled SKILL.md for the `team` workflow.
 *(None)*
 
 ## Dependencies
-*(None)*
+
+### Internal
+{References to other parts of the codebase this depends on}
+
+### External
+{Key external packages/libraries used}
 
 <!-- MANUAL: -->

package/src/prompts/skills/ultragoal/AGENTS.md

@@ -1,5 +1,5 @@
 <!-- Parent: ../AGENTS.md -->
-<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-14 -->
 
 # ultragoal
 
@@ -26,6 +26,11 @@ Bundled SKILL.md for the `ultragoal` workflow.
 *(None)*
 
 ## Dependencies
-*(None)*
+
+### Internal
+{References to other parts of the codebase this depends on}
+
+### External
+{Key external packages/libraries used}
 
 <!-- MANUAL: -->

package/src/skills/AGENTS.md

@@ -1,5 +1,5 @@
 <!-- Parent: ../AGENTS.md -->
-<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-14 -->
 
 # skills
 
@@ -9,8 +9,7 @@ Framework for discovering, loading, and executing workflow skills (both bundled
 ## Key Files
 | File | Description |
 |------|-------------|
-| `registry.ts` | Discovers and catalogs available skills |
-| `executor.ts` | Mechanism to inject skill prompts into the active session |
+| `catalog.ts` | Brief description of purpose |
 
 ## Subdirectories
 *(None)*

package/src/tui/AGENTS.md

@@ -1,5 +1,5 @@
 <!-- Parent: ../AGENTS.md -->
-<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-14 -->
 
 # tui
 
@@ -10,6 +10,7 @@ Terminal User Interface logic, layout systems, and the differential renderer. Re
 | File | Description |
 |------|-------------|
 | `app.ts` | High-level TUI orchestrator (`LaunchTui`) |
+| `index.ts` | Brief description of purpose |
 | `renderer.ts` | The differential, atomic terminal renderer (handles scrollback, resizing, DECSET 2026) |
 | `terminal.ts` | Low-level ANSI escape codes and terminal size utilities |
 

package/src/tui/app.ts

@@ -554,10 +554,6 @@ export class LaunchTui {
     });
   }
 
-  private renderLiveUserQueryCard(cols: number): string[] {
-    return this.renderUserCard(this.livePromptInput, cols);
-  }
-
   /** Render a `user`-labeled query card (orange "user" header over a filled box).
    *  Shared by the live next-prompt draft and the mid-turn steering flush. */
   private renderUserCard(rawText: string, cols: number): string[] {
@@ -1186,12 +1182,6 @@ export class LaunchTui {
       }));
     }
 
-    // User text typed while the model is still thinking is surfaced as a live
-    // pending-user card (same query input underneath, no hidden auto-executing queue).
-    if (this.livePromptInput.trim()) {
-      tail.push("");
-      tail.push(...this.renderLiveUserQueryCard(cols));
-    }
 
     // Agent task plan (the `todo` tool) as a Todos checklist.
     if (args.planLines.length) {
@@ -1316,18 +1306,11 @@ export class LaunchTui {
     // model bar), no outer border, no mascot art — completed work lives in scrollback.
     if (fit && this.inline) {
       const inlineFrame = this.composeInlineFrame({ cols, rows, stepNow, elapsedMs, idx, isThinking, planLines });
-      // Option C (constant live-frame height): pad the composed frame to EXACTLY `rows`
-      // — blank rows at the TOP, the tail (status/hud/input/model bar) pinned to the
-      // bottom. With a constant height the differential renderer reserves rows ONCE and
-      // thereafter only does in-place, within-frame cursor moves; the bottom-margin
-      // reserve-GROW that drifted the anchor by one row (the duplicate model bar during
-      // rapid tool churn) never runs again. Every line is still width-clamped so a long
-      // line cannot soft-wrap into a second physical row and desync the row accounting.
-      const capped = inlineFrame.length > rows ? inlineFrame.slice(inlineFrame.length - rows) : inlineFrame;
-      const fixedHeight = capped.length < rows
-        ? [...new Array(rows - capped.length).fill(""), ...capped]
-        : capped;
-      this.renderer.render(fixedHeight.map(l => truncateToWidth(l, cols)));
+      // Screen-safety: every rendered line is width-clamped to `cols` so a long line
+      // (e.g. the model bar with a deep cwd) cannot soft-wrap into a second physical row
+      // and desync the differential renderer's 1-line=1-row accounting. Frame height stays
+      // content-sized so completed cards remain visible in scrollback above the live frame.
+      this.renderer.render(inlineFrame.slice(0, rows).map(l => truncateToWidth(l, cols)));
       return;
     }
 
@@ -1391,10 +1374,6 @@ export class LaunchTui {
         bottom.push(`  ${categoryBadge("status", { color: this.theme.color })} ${msg}${guardBadge}`);
       }
     }
-    if (fit && this.livePromptInput.trim()) {
-      bottom.push("");
-      bottom.push(...this.renderLiveUserQueryCard(innerWidth));
-    }
     // TTY only: keep the same query input box visible above the footer while the
     // turn is running; typed text edits the next-prompt draft, not a side queue.
     if (fit) {

package/src/tui/components/AGENTS.md

@@ -1,5 +1,5 @@
-<!-- Parent: ../../AGENTS.md -->
-<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-14 -->
 
 # components
 
@@ -9,11 +9,44 @@ Reusable UI widgets and layout primitives for the terminal interface.
 ## Key Files
 | File | Description |
 |------|-------------|
+| `ascii-art.ts` | Cellular evolution graphics |
+| `autocomplete.ts` | Brief description of purpose |
+| `autopilot-status.ts` | Brief description of purpose |
+| `capability.ts` | Brief description of purpose |
+| `category-index.ts` | Brief description of purpose |
+| `code-view.ts` | Brief description of purpose |
+| `color.ts` | Brief description of purpose |
+| `config-panel.ts` | Brief description of purpose |
+| `duration.ts` | Brief description of purpose |
+| `evolution.ts` | Brief description of purpose |
+| `footer.ts` | Brief description of purpose |
 | `forge.ts` | Formats the boxed tool execution outputs |
-| `status.ts` | The `[STEP]` / `[STATUS]` / `[TOOL]` HUD lines |
-| `section.ts` | Shadcn-inspired card layout and spacing tokens |
+| `hints.ts` | Brief description of purpose |
+| `hud.ts` | Brief description of purpose |
+| `index.ts` | Brief description of purpose |
+| `input-box.ts` | Brief description of purpose |
 | `layout.ts` | Low-level padding, boxing, and alignment math |
-| `ascii-art.ts` | Cellular evolution graphics |
+| `live-model-picker.ts` | Brief description of purpose |
+| `markdown-table.ts` | Brief description of purpose |
+| `markdown-text.ts` | Brief description of purpose |
+| `meter.ts` | Brief description of purpose |
+| `model-picker.ts` | Brief description of purpose |
+| `provider-picker.ts` | Brief description of purpose |
+| `section.ts` | Shadcn-inspired card layout and spacing tokens |
+| `select-list.ts` | Brief description of purpose |
+| `skill-picker.ts` | Brief description of purpose |
+| `slash.ts` | Brief description of purpose |
+| `spinner.ts` | Brief description of purpose |
+| `status.ts` | The `[STEP]` / `[STATUS]` / `[TOOL]` HUD lines |
+| `step-timeline.ts` | Brief description of purpose |
+| `stream.ts` | Brief description of purpose |
+| `themes.ts` | Brief description of purpose |
+| `todo-card.ts` | Brief description of purpose |
+| `tool-list.ts` | Brief description of purpose |
+| `transcript.ts` | Brief description of purpose |
+| `update-box.ts` | Brief description of purpose |
+| `welcome.ts` | Brief description of purpose |
+| `width.ts` | Brief description of purpose |
 
 ## Subdirectories
 *(None)*

package/src/tui/components/ascii-art.ts

@@ -524,6 +524,15 @@ export const DNA_CLAW_ART_GRAND_ASCII: string[] = [
   "        [ D N A . C L A W ]         "
 ];
 
+// Bounded memo of fully-rendered DNA Claw frames keyed by every input that affects
+// output (grand/unicode/cols/color/colorLevel/phase/frame). The live HUD cycles a
+// FIXED ~60-frame set (3 twists × 20 gradient phases) at ~120ms; without this each
+// recurrence recomputed per-line animatedGradientText (ANSI gradient) from scratch.
+// The memo makes the 2nd+ cycle O(1) lookups, cutting steady-state HUD CPU. LRU-capped.
+const dnaClawMemo = new Map<string, string[]>();
+const DNA_CLAW_MEMO_CAP = 256;
+const EMPTY_DNA_FRAME: string[] = [];
+
 export function renderDnaClaw(opts: {
   cols?: number;
   phase?: number;
@@ -537,6 +546,9 @@ export function renderDnaClaw(opts: {
    *  `phase` this animates the forge identity without any frame-count growth. */
   frame?: number;
 }): string[] {
+  const memoKey = `${opts.grand ? "g" : "c"}|${opts.unicode !== false ? 1 : 0}|${opts.cols ?? -1}|${opts.color !== false ? 1 : 0}|${opts.colorLevel ?? ColorLevel.TrueColor}|${opts.phase ?? 0}|${opts.frame ?? 0}`;
+  const memoHit = dnaClawMemo.get(memoKey);
+  if (memoHit) return memoHit;
   const useUnicode = opts.unicode !== false;
   let source: string[];
   if (opts.grand) {
@@ -549,7 +561,8 @@ export function renderDnaClaw(opts: {
   const width = Math.max(0, ...source.map(l => l.length));
 
   if (opts.cols !== undefined && opts.cols < width) {
-    return [];
+    dnaClawMemo.set(memoKey, EMPTY_DNA_FRAME);
+    return EMPTY_DNA_FRAME;
   }
 
   const phase = opts.phase ?? 0;
@@ -557,13 +570,20 @@ export function renderDnaClaw(opts: {
   const colorLevel = opts.colorLevel ?? ColorLevel.TrueColor;
   const palette = DNA_FLOW_PALETTE;
 
-  return source.map((line, idx) => {
+  const result = source.map((line, idx) => {
     const padded = line.length < width ? line + " ".repeat(width - line.length) : line;
     if (!useColor || colorLevel < ColorLevel.TrueColor) {
       return padded;
     }
     return animatedGradientText(padded, palette, phase + idx * 0.07, { colorLevel });
   });
+
+  if (dnaClawMemo.size >= DNA_CLAW_MEMO_CAP) {
+    const oldest = dnaClawMemo.keys().next().value;
+    if (oldest !== undefined) dnaClawMemo.delete(oldest);
+  }
+  dnaClawMemo.set(memoKey, result);
+  return result;
 }
 
 /** The DNA Claw identity palette (emerald → cyan → violet helix flow). Shared by

package/src/tui/monitoring/AGENTS.md

@@ -1,5 +1,5 @@
-<!-- Parent: ../../AGENTS.md -->
-<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-14 -->
 
 # monitoring
 
@@ -26,6 +26,11 @@ Specialized HUD views and sovereign monitoring interfaces.
 *(None)*
 
 ## Dependencies
-*(None)*
+
+### Internal
+{References to other parts of the codebase this depends on}
+
+### External
+{Key external packages/libraries used}
 
 <!-- MANUAL: -->

package/src/tui/renderer.ts

@@ -134,20 +134,10 @@ export class Renderer {
       .map((line, i, arr) => (i === arr.length - 1 && line === "" ? "" : toColumn(1) + clearLine() + line))
       .join("\n");
     let out = BEGIN_SYNC + body;
-    // Eagerly EL-clear the old frame rows the inserted block did NOT cover, then hop
-    // back to the row right below the insert (where the next render() anchors).
-    // The geometry is provably safe HERE: when stale > 0 the body write never hit
-    // the bottom margin (the old frame fit on screen and the insert is shorter), so
-    // every stale row exists and cursor-down cannot clamp. Deferring this clear to
-    // the next render() via coverRows walked PAST the bottom margin, where the
-    // clamped cursor-down desynced the row bookkeeping — each subsequent frame then
-    // painted one row higher, devouring the flushed scrollback content above (the
-    // "truncated card" corruption).
-    // Use the same occupancy measure the reserve block uses (max of prev.length and
-    // coverRows). A reset() between frames drops prev but records coverRows; ignoring it
-    // here left the old frame's lower rows uncleared and the cursor below the true
-    // anchor, so the next render's cursorDown crossed the bottom margin and clamped —
-    // the persistent off-by-one that duplicated the model bar.
+    // EL-clear the old frame rows the inserted block did NOT cover, then hop back to the
+    // row right below the insert (where the next render() anchors). occupied = max(prev,
+    // coverRows) matches the reserve block so a reset()->insertAbove() ordering still
+    // clears the old frame's lower rows (the off-by-one that duplicated the model bar).
     const occupied = Math.max(this.prev.length, this.coverRows);
     const stale = occupied - written;
     if (stale > 0) {
@@ -158,7 +148,7 @@ export class Renderer {
     }
     this.write(out);
     this.prev = [];
-    this.coverRows = 0; // consumed: the frame below is now the single source of truth
+    this.coverRows = 0;
   }
 
   /** Clear the live frame. Inline (reserve) mode walks the known frame rows with

package/src/util/AGENTS.md

@@ -1,5 +1,5 @@
 <!-- Parent: ../AGENTS.md -->
-<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-14 -->
 
 # util
 
@@ -9,9 +9,11 @@ General utilities, helper functions, and shared types used across the applicatio
 ## Key Files
 | File | Description |
 |------|-------------|
-| `update-check.ts` | Async check for newer npm versions |
-| `retry.ts` | Rate-limit backoff and generic retry mechanisms |
+| `clipboard-image.ts` | Brief description of purpose |
+| `env.ts` | Brief description of purpose |
 | `provider-error.ts` | Error normalization helpers |
+| `retry.ts` | Rate-limit backoff and generic retry mechanisms |
+| `update-check.ts` | Async check for newer npm versions |
 
 ## Subdirectories
 *(None)*