@tt-a1i/openpi 0.3.1 → 0.4.0

package/extensions/git-read/src/args.ts

@@ -0,0 +1,171 @@
+/**
+ * Read-only git commands: pure argv construction.
+ *
+ * Everything here is synchronous and side-effect free so the exact argv
+ * passed to the child process can be asserted in tests. Revision and path
+ * inputs are validated against strict shapes before they are ever placed
+ * in an argument list, and every user-controlled value goes after a `--`
+ * separator so it can never be parsed as a flag. Only argv subcommands that
+ * cannot write are reachable at all.
+ */
+
+export const GIT_TIMEOUT_MS = 10_000;
+export const GIT_LOG_DEFAULT_LIMIT = 100;
+export const GIT_LOG_MAX_LIMIT = 1000;
+
+/** Revisions may be a sha-ish hex string, HEAD~n, HEAD^n, or a plain name; a
+ * leading `-` is rejected so a revision can never smuggle a git flag. */
+const REVISION_PATTERN =
+  /^(?:[0-9a-fA-F]{4,40}|HEAD(?:[~^]\d*)*|[A-Za-z_][\w./@-]{0,199})$/;
+/** Diffs compare two revisions; worktree comparison uses one revision. */
+const MAX_REVISION_LENGTH = 200;
+
+export function isSafeRevision(revision: string): boolean {
+  const trimmed = revision.trim();
+  if (trimmed.length === 0 || trimmed.length > MAX_REVISION_LENGTH)
+    return false;
+  return REVISION_PATTERN.test(trimmed);
+}
+
+/** A relative repo path; `..` escapes and absolute paths are rejected. */
+const REPO_PATH_PATTERN = /^[^:/\\?#*[\]'"\s][^:/\\?#*[\]'"\s]*$/;
+
+export function isSafeRepoPath(value: string): boolean {
+  if (value.length === 0 || value.length > 512) return false;
+  const segments = value.split("/");
+  for (const segment of segments) {
+    if (segment === "" || segment === "." || segment === "..") return false;
+    if (!REPO_PATH_PATTERN.test(segment)) return false;
+  }
+  return true;
+}
+
+function revision(value: string): string | undefined {
+  return isSafeRevision(value) ? value.trim() : undefined;
+}
+
+export class InvalidRevisionError extends Error {
+  constructor(value: string) {
+    super(
+      `Invalid git revision: ${JSON.stringify(value.slice(0, 80))}. Allowed: a commit sha, branch or tag name, or HEAD with ~ / ^ modifiers.`,
+    );
+    this.name = "InvalidRevisionError";
+  }
+}
+
+export class InvalidPathError extends Error {
+  constructor(value: string) {
+    super(
+      `Invalid repository path: ${JSON.stringify(value.slice(0, 80))}. Use a relative path inside the repository.`,
+    );
+    this.name = "InvalidPathError";
+  }
+}
+
+export class InvalidDiffCombinationError extends Error {
+  constructor(message: string) {
+    super(`Invalid git diff options: ${message}`);
+    this.name = "InvalidDiffCombinationError";
+  }
+}
+
+export interface GitShowParams {
+  revision: string;
+  path?: string;
+}
+
+export function buildShowArgs(params: GitShowParams): string[] {
+  if (!isSafeRevision(params.revision))
+    throw new InvalidRevisionError(params.revision);
+  const args = [
+    "show",
+    "--no-color",
+    "--no-ext-diff",
+    "--no-textconv",
+    "--format=fuller",
+    params.revision.trim(),
+  ];
+  if (params.path !== undefined) {
+    if (!isSafeRepoPath(params.path)) throw new InvalidPathError(params.path);
+    args.push("--", params.path);
+  }
+  return args;
+}
+
+export interface GitDiffParams {
+  /** Base revision, e.g. HEAD, HEAD~1, a branch name, or a sha. */
+  from?: string;
+  /** Compared revision; omit to compare `from` against the worktree. */
+  to?: string;
+  /** Compare against the index (staged changes) instead of the worktree. */
+  staged?: boolean;
+  stat?: boolean;
+  path?: string;
+}
+
+export function buildDiffArgs(params: GitDiffParams): string[] {
+  const from = params.from !== undefined ? revision(params.from) : undefined;
+  if (params.from !== undefined && from === undefined) {
+    throw new InvalidRevisionError(params.from);
+  }
+  const to = params.to !== undefined ? revision(params.to) : undefined;
+  if (params.to !== undefined && to === undefined) {
+    throw new InvalidRevisionError(params.to);
+  }
+  if (params.to !== undefined && params.from === undefined) {
+    throw new InvalidDiffCombinationError("to requires from");
+  }
+  if (params.staged && (params.from !== undefined || params.to !== undefined)) {
+    throw new InvalidDiffCombinationError(
+      "staged cannot be combined with from or to",
+    );
+  }
+
+  const args = ["diff", "--no-color", "--no-ext-diff", "--no-textconv"];
+  if (params.staged) args.push("--cached");
+  if (params.stat) args.push("--stat");
+
+  if (from !== undefined && to !== undefined) {
+    // An explicit `--` separator is unnecessary for the range form; a
+    // validated revision can never start with `-` anyway.
+    args.push(`${from}...${to}`);
+  } else if (from !== undefined) {
+    args.push(from);
+  }
+  // No revisions: worktree vs index (or HEAD with --cached).
+
+  if (params.path !== undefined) {
+    if (!isSafeRepoPath(params.path)) throw new InvalidPathError(params.path);
+    args.push("--", params.path);
+  }
+  return args;
+}
+
+export interface GitLogParams {
+  revision?: string;
+  file?: string;
+  limit?: number;
+  oneline?: boolean;
+}
+
+export function buildLogArgs(params: GitLogParams): string[] {
+  const args = ["log", "--no-color", "--no-ext-diff"];
+  if (params.oneline !== false) args.push("--oneline");
+  const limit = Math.min(
+    GIT_LOG_MAX_LIMIT,
+    Math.max(1, Math.floor(params.limit ?? GIT_LOG_DEFAULT_LIMIT)),
+  );
+  args.push(`-n`, String(limit));
+
+  if (params.revision !== undefined) {
+    if (!isSafeRevision(params.revision)) {
+      throw new InvalidRevisionError(params.revision);
+    }
+    args.push(params.revision.trim());
+  }
+  if (params.file !== undefined) {
+    if (!isSafeRepoPath(params.file)) throw new InvalidPathError(params.file);
+    args.push("--", params.file);
+  }
+  return args;
+}

package/extensions/git-read/src/process.ts

@@ -0,0 +1,81 @@
+/**
+ * Bounded git process execution for the read-only git tools.
+ *
+ * Reuses the file-search capture discipline: a preview is retained in memory
+ * under pi's standard truncation limits while the complete output (up to the
+ * 10 MiB capture cap) streams to a temporary file, and the process group is
+ * terminated when the cap is exceeded.
+ */
+
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { Data, Effect } from "effect";
+import type { CapturedOutput } from "../../file-search/src/output.ts";
+import {
+  discardCapturedOutput,
+  executeSearchProcess,
+} from "../../file-search/src/process.ts";
+import { GIT_TIMEOUT_MS } from "./args.ts";
+
+export const GIT_CAPTURE_MAX_BYTES = 10 * 1024 * 1024;
+
+export class GitCommandError extends Data.TaggedError("GitCommandError")<{
+  readonly message: string;
+}> {}
+
+export interface GitOutcome {
+  readonly output: CapturedOutput;
+  readonly exitCode: number;
+}
+
+/**
+ * Run one git subcommand. Exit code 128 (not a repository / bad revision) and
+ * 129 (usage) surface as a GitCommandError carrying stderr; other non-zero
+ * exits also fail with the captured stderr detail.
+ */
+export function runGit(
+  args: readonly string[],
+  cwd: string,
+  timeoutMs = GIT_TIMEOUT_MS,
+): Effect.Effect<GitOutcome, GitCommandError> {
+  return Effect.gen(function* () {
+    const result = yield* Effect.catchTags(
+      executeSearchProcess({
+        command: "git",
+        args,
+        cwd,
+        tempPrefix: "pi-git-",
+        maxCaptureBytes: GIT_CAPTURE_MAX_BYTES,
+      }),
+      {
+        SearchProcessError: (error) =>
+          new GitCommandError({
+            message: `failed to run git: ${error.message}`,
+          }),
+        PlatformError: (error) =>
+          new GitCommandError({
+            message: `git output capture failed: ${String(error.reason ?? "")}`,
+          }),
+      },
+    );
+    if (result.code !== 0) {
+      const detail =
+        result.stderr.trim() || `git exited with code ${result.code}`;
+      // A failure means nothing useful was captured; drop the artifact.
+      yield* Effect.ignore(discardCapturedOutput(result.output));
+      return yield* new GitCommandError({ message: detail });
+    }
+    return {
+      output: result.output,
+      exitCode: result.code,
+    } satisfies GitOutcome;
+  }).pipe(
+    Effect.timeout(timeoutMs),
+    Effect.mapError((error) => {
+      if (error._tag === "GitCommandError") return error;
+      return new GitCommandError({
+        message: `git command timed out after ${timeoutMs}ms`,
+      });
+    }),
+    Effect.provide(NodeServices.layer),
+  );
+}

package/extensions/git-read/src/prompt.ts

@@ -0,0 +1,56 @@
+/** Model-facing text for the read-only git tools. */
+
+export const GIT_SHOW_TOOL_DESCRIPTION =
+  "Show a git commit (message, author, and patch), optionally limited to one repository path. Read-only.";
+
+export const GIT_SHOW_PROMPT_SNIPPET =
+  "Inspect a specific git commit with git_show.";
+
+export const GIT_SHOW_PROMPT_GUIDELINES = [
+  "Use git_show to review what a single commit changed instead of reading the whole file tree and guessing.",
+  "Use git_diff to compare revisions or the worktree, and git_log to find commits first.",
+];
+
+export const GIT_SHOW_PARAMETER_DESCRIPTIONS = {
+  revision:
+    "Commit to show: a sha (>=4 hex chars), branch or tag name, or HEAD with ~ / ^ modifiers, e.g. HEAD, HEAD~2, main.",
+  path: "Optional relative path inside the repository. Limits the commit patch to this path; it does not read the file blob.",
+};
+
+export const GIT_DIFF_TOOL_DESCRIPTION =
+  "Show a git diff: between two revisions, a revision and the worktree, or staged changes. Read-only.";
+
+export const GIT_DIFF_PROMPT_SNIPPET =
+  "Compare git revisions or working-tree changes with git_diff.";
+
+export const GIT_DIFF_PROMPT_GUIDELINES = [
+  "Use git_diff (not git_show) when reviewing changes between refs or uncommitted work.",
+  "Set stat to true first for a broad overview, then drill into specific paths.",
+  "To review a pull request, diff its branch against the base, e.g. from: 'main', to: 'feature-branch'.",
+];
+
+export const GIT_DIFF_PARAMETER_DESCRIPTIONS = {
+  from: "Base revision. With to, compares from...to from their merge base (PR-style). Omit both revisions to diff the worktree against the index.",
+  to: "Compared revision. Requires from and uses the merge-base range from...to. Give from alone to diff that revision against the worktree.",
+  staged:
+    "Compare the index (staged changes) against HEAD instead of the worktree.",
+  stat: "Show a diffstat (files and line counts) instead of the full patch.",
+  path: "Only diff this relative path inside the repository.",
+};
+
+export const GIT_LOG_TOOL_DESCRIPTION =
+  "List commit history with sha, author, date, and first line. Filter by revision or file. Read-only.";
+
+export const GIT_LOG_PROMPT_SNIPPET = "Browse git history with git_log.";
+
+export const GIT_LOG_PROMPT_GUIDELINES = [
+  "Use git_log with a file to find who last touched a piece of code before changing it.",
+  "Keep oneline true unless the full commit message of every entry is needed.",
+];
+
+export const GIT_LOG_PARAMETER_DESCRIPTIONS = {
+  revision: "History starting from this revision. Defaults to HEAD.",
+  file: "Only commits touching this relative path.",
+  limit: "Maximum commits to list (1-1000). Defaults to 100.",
+  oneline: "One line per commit (default true); false adds full messages.",
+};

package/extensions/sessions/index.ts

@@ -5,22 +5,24 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import {
   DynamicBorder,
-  SessionManager,
   keyHint,
+  SessionManager,
 } from "@earendil-works/pi-coding-agent";
 import {
   CancellableLoader,
   Container,
   Key,
-  SelectList,
+  matchesKey,
   type SelectItem,
+  SelectList,
   Spacer,
   Text,
-  matchesKey,
   truncateToWidth,
   visibleWidth,
   wrapTextWithAnsi,
 } from "@earendil-works/pi-tui";
+import { hintLine } from "../shared/screen-chrome.ts";
+import { createSessionStatsLoader, type SessionStats } from "./git-stats.js";
 import {
   buildPreviewError,
   buildSessionDescription,
@@ -28,14 +30,13 @@ import {
   buildSessionPreview,
   buildSessionSearchEntries,
   filterSessionEntries,
+  formatRelativeTime,
   getSessionPaneLayout,
-  parseLimit,
   type PreviewBlock,
+  parseLimit,
   type SessionInfoLike,
   type SessionPreview,
-  formatRelativeTime,
 } from "./sessions.js";
-import { createSessionStatsLoader, type SessionStats } from "./git-stats.js";
 
 const DEFAULT_VISIBLE = 12;
 const SNIPPET_MAX = 60;
@@ -82,7 +83,7 @@ const themeText = (
 ): string => {
   if (kind === "title") return theme.fg("accent", theme.bold(text));
   if (kind === "subtitle") return theme.fg("dim", text);
-  if (kind === "rule") return theme.fg("border", text);
+  if (kind === "rule") return theme.fg("borderMuted", text);
   if (kind === "user") return theme.fg("accent", theme.bold(text));
   if (kind === "assistant") return theme.fg("warning", theme.bold(text));
   if (kind === "tool") return theme.fg("muted", theme.bold(text));
@@ -357,31 +358,20 @@ const renderPreview = (
 ): { lines: string[]; totalLines: number; maxScroll: number } => {
   const raw: string[] = [];
 
+  // Left-aligned, like every other OpenPI heading: centred titles read as a
+  // different application than the panel they sit inside, and they wander as
+  // the pane resizes.
   if (!preview) {
-    raw.push(
-      " ".repeat(Math.max(0, Math.floor((width - 7) / 2))) +
-        themeText(theme, "title", "Preview"),
-    );
-    raw.push(
-      " ".repeat(Math.max(0, Math.floor((width - 25) / 2))) +
-        themeText(theme, "subtitle", "Loading selected session…"),
-    );
+    raw.push(themeText(theme, "title", "Preview"));
+    raw.push(themeText(theme, "subtitle", "Loading selected session…"));
   } else {
-    const titleStr = "Thread Preview";
-    const titleColor =
+    const titleStr = "Thread preview";
+    raw.push(
       focus === "preview"
         ? themeText(theme, "title", titleStr)
-        : themeText(theme, "subtitle", titleStr);
-    const titlePadding = " ".repeat(
-      Math.max(0, Math.floor((width - titleStr.length) / 2)),
-    );
-    raw.push(`${titlePadding}${titleColor}`);
-
-    const subStr = preview.subtitle;
-    const subPadding = " ".repeat(
-      Math.max(0, Math.floor((width - visibleWidth(subStr)) / 2)),
+        : themeText(theme, "subtitle", titleStr),
     );
-    raw.push(`${subPadding}${themeText(theme, "subtitle", subStr)}`);
+    raw.push(themeText(theme, "subtitle", preview.subtitle));
 
     raw.push(themeText(theme, "rule", "─".repeat(Math.max(0, width))));
 
@@ -438,10 +428,10 @@ const renderPreview = (
       if (i >= thumbStart && i < thumbStart + thumbSize) {
         scrollChar = theme.fg("text", "█");
       } else {
-        scrollChar = theme.fg("border", "│");
+        scrollChar = theme.fg("borderMuted", "│");
       }
     } else {
-      scrollChar = theme.fg("border", "│");
+      scrollChar = theme.fg("borderMuted", "│");
     }
 
     visible.push(padAnsiRight(line, width - 1) + scrollChar);
@@ -474,7 +464,9 @@ async function listSessions(
   const sessions = await ctx.ui.custom<SessionInfoLike[] | null>(
     (tui, theme, _kb, done) => {
       const container = new Container();
-      const borderColor = (text: string) => theme.fg("border", text);
+      // Same tone as the split-pane frame and every other OpenPI panel; this
+      // was the last `border` call left in the package.
+      const borderColor = (text: string) => theme.fg("borderMuted", text);
 
       const loader = new CancellableLoader(
         tui,
@@ -732,7 +724,7 @@ async function showSessionPicker(
         if (isLoading) {
           container.addChild(new Spacer(1));
           container.addChild(
-            new Text(theme.fg("muted", "  Loading sessions..."), 1, 0),
+            new Text(theme.fg("muted", "  Loading sessions…"), 1, 0),
           );
           container.addChild(new Spacer(1));
         } else {
@@ -762,7 +754,15 @@ async function showSessionPicker(
         }
         container.addChild(
           new Text(
-            theme.fg("dim", "↑↓ navigate • enter open • esc cancel"),
+            hintLine(
+              theme,
+              [
+                ["↑↓", "navigate"],
+                ["enter", "open"],
+                ["esc", "cancel"],
+              ],
+              Math.max(1, width - 2),
+            ),
             1,
             0,
           ),
@@ -777,29 +777,29 @@ async function showSessionPicker(
         listWidth: number,
         previewWidth: number,
       ): string => {
-        const leftTitle = " Switch Thread ";
+        const leftTitle = " sessions ";
+        const rightTitle = " preview ";
         const left = `┌─${leftTitle}${"─".repeat(Math.max(0, listWidth - leftTitle.length - 2))}`;
-        const right = "─".repeat(Math.max(0, previewWidth - 1)) + "┐";
-        return `${theme.fg("border", left)}${theme.fg("border", "─┬─")}${theme.fg("border", right)}`;
+        const right =
+          `─${rightTitle}${"─".repeat(Math.max(0, previewWidth - rightTitle.length - 2))}` +
+          "┐";
+        return `${theme.fg("borderMuted", left)}${theme.fg("borderMuted", "─┬─")}${theme.fg("borderMuted", right)}`;
       };
 
       const buildBottomBorder = (
         listWidth: number,
         previewWidth: number,
-        previewStats: string,
       ): string => {
-        const help = showAllWorkspaces
-          ? " Opt+W/Ctrl+T current workspace  ·  Esc close "
-          : " Opt+W/Ctrl+T all workspaces  ·  Esc close ";
         const left = `└${"─".repeat(Math.max(0, listWidth - 1))}`;
-        const right = `${"─".repeat(Math.max(0, previewWidth - help.length - 1))}${help}┘`;
-        return `${theme.fg("border", left)}${theme.fg("border", "─┴─")}${theme.fg("border", right)}`;
+        const right = `${"─".repeat(Math.max(0, previewWidth - 1))}┘`;
+        return `${theme.fg("borderMuted", left)}${theme.fg("borderMuted", "─┴─")}${theme.fg("borderMuted", right)}`;
       };
 
       const renderSplitPane = (width: number): string[] => {
         const layout = getSessionPaneLayout(width);
         const termRows = Math.max(12, tui.terminal?.rows ?? 24);
-        const contentHeight = Math.max(8, termRows - 2);
+        // Frame (2) + hint line (1).
+        const contentHeight = Math.max(8, termRows - 3);
         const filterLine = filter.length
           ? `${theme.fg("muted", "Filter: ")}${theme.fg("text", filter)}`
           : `${theme.fg("muted", "Filter: ")}${theme.fg("dim", "type to filter")}`;
@@ -861,26 +861,41 @@ async function showSessionPicker(
           previewScrollOffset,
           renderedPreview.maxScroll,
         );
-        const modeHints = `t ${toolsExpanded ? "compact" : "tools"} • h ${thinkingVisible ? "hide thinking" : "thinking"}`;
-        const previewStats =
-          renderedPreview.maxScroll > 0
-            ? ` ${previewScrollOffset + 1}-${Math.min(previewScrollOffset + contentHeight, renderedPreview.totalLines)}/${renderedPreview.totalLines} • pgup/pgdn • ${modeHints} `
-            : ` esc/enter • ${modeHints} `;
+        // Hints live on their own line under the frame instead of being packed
+        // into the bottom border, where they had to compete with the border for
+        // the same row and lost the keys in a wall of dim text.
+        const hints = hintLine(
+          theme,
+          [
+            renderedPreview.maxScroll > 0
+              ? ([
+                  "",
+                  `${previewScrollOffset + 1}-${Math.min(previewScrollOffset + contentHeight, renderedPreview.totalLines)}/${renderedPreview.totalLines}`,
+                ] as const)
+              : undefined,
+            renderedPreview.maxScroll > 0
+              ? (["pgup/pgdn", "scroll"] as const)
+              : undefined,
+            ["t", toolsExpanded ? "compact" : "tools"],
+            ["h", thinkingVisible ? "hide thinking" : "thinking"],
+            [
+              "opt+w/ctrl+t",
+              showAllWorkspaces ? "current workspace" : "all workspaces",
+            ],
+            ["esc", "close"],
+          ],
+          width,
+        );
 
         const lines = [buildTopBorder(layout.listWidth, layout.previewWidth)];
         for (let i = 0; i < contentHeight; i++) {
           const left = padAnsiRight(leftLines[i] ?? "", layout.listWidth);
           const right =
             renderedPreview.lines[i] ?? " ".repeat(layout.previewWidth);
-          lines.push(`${left}${theme.fg("border", " │ ")}${right}`);
+          lines.push(`${left}${theme.fg("borderMuted", " │ ")}${right}`);
         }
-        lines.push(
-          buildBottomBorder(
-            layout.listWidth,
-            layout.previewWidth,
-            previewStats,
-          ),
-        );
+        lines.push(buildBottomBorder(layout.listWidth, layout.previewWidth));
+        lines.push(hints);
         return lines.map((line) => truncateToWidth(line, width, "", true));
       };
 

package/extensions/setup/index.ts

@@ -132,10 +132,10 @@ export function buildInteractiveSetupPrompt(options: {
     "- Capability discovery: explicit is the safe default and keeps OpenPI model tools absent until the user asks for a capability. adaptive is opt-in and keeps only the small openpi_load_tools gateway visible, allowing the model to load Subagents, Workflows, background terminals, structured search, or Session tracking when it judges them useful. Loaded groups remain session-stable, and normal permission, concurrency, and workflow limits still apply.",
     "- Next-action suggestions: disabled, or model-generated after a fully settled main-agent run. A suggestion appears as dim inline text on the first row of an empty editor; reserved cells at the row end keep CJK IME preedit from overwriting it. Right accepts it without submitting, and any other editor input dismisses it. Enabling requires an available provider/model and reasoning level and adds one small model call per settled run.",
     "- Workflow fan-out: concurrency controls simultaneous agents and resource pressure; max agent calls controls the total capacity of one workflow. Valid ranges are 1-64 and 1-1024.",
-    "- UI: the large header costs vertical space; the custom footer is a declarative dashboard. Presets: powerline (one-line ANSI256 blocks), powerline-mono (one-line high-contrast gray powerline), and compact (one-line plain text); the default is plain with cwd/git/pr on the left and model/context/cost on the right. Style can also be set independently: plain, powerline, powerline-mono. Custom lines are a 2D layout of cwd/model/thinking/context/cache/cost/throughput/git/pr plus at most one flex per line for left/right alignment. Nerd Font only affects powerline separator glyphs; text stays readable without it. Changes apply immediately in the active TUI session.",
+    "- UI: the large header costs vertical space; the custom footer is a declarative dashboard. Presets: powerline (one-line ANSI256 blocks), powerline-mono (one-line high-contrast gray powerline), and compact (one-line plain text); the default is plain with model/context on the left and git/pr/cwd on the right. Style can also be set independently: plain, powerline, powerline-mono. Custom lines are a 2D layout of cwd/model/thinking/context/cache/cost/throughput/git/pr plus at most one flex per line for left/right alignment. Footer metrics use Codicon outline glyphs for model, context, and directory; a Nerd Font renders them as designed while the text stays readable without it. Changes apply immediately in the active TUI session.",
     "- Operational activity for Subagents, Workflows, and background terminals is core status and always remains visible whenever the custom footer is enabled.",
     "- Post-edit command: one optional shell command (maximum 500 characters) run in the background after a turn with successful Write/Edit operations (e.g. `npm run format`). Off by default, interactive TUI sessions only, failures surface as a notification. This is a single command, not an event-hook system.",
-    "- Result detail display: Subagent results, Bash operations, and Write/Edit operations can each default to full or compact. Compact Subagent results show only bounded status rows and keep raw child reports behind app.tools.expand; compact Bash and Write/Edit operations use folded previews. Ctrl+O expands compact output by default. Bash and Write/Edit default to compact. Recommend compact for users who do not usually inspect implementation details.",
+    "- Result detail display: Subagent results, Bash operations, and Write/Edit operations can each default to full or compact. Compact Subagent results show only bounded status rows and keep raw child reports behind app.tools.expand; compact Bash and Write/Edit operations use one-line semantic activity summaries. Read, grep, find, and ls use the same compact activity-row projection. Ctrl+O restores Pi's native full arguments, output, errors, diffs, and timing. Bash and Write/Edit default to compact. Recommend compact for users who scan activity first and inspect evidence on demand.",
     "- Agent role models: built-in explorer, implementer, reviewer, and advisor roles are shared by subagent_spawn and workflow agent_type, and inherit the parent model by default. Assign only an available registry model to an individual role when needed; clearing that role returns it to inheritance. Custom agent-type files still override a built-in role's complete definition.",
     "- Intercom: optional cross-session messaging is installed only after a native setup confirmation. It stays parent-only; Direct/Workflow children and Replay cannot use it. The status above is informational for this model-guided step—do not install packages or edit its config yourself.",
     "",
@@ -371,7 +371,7 @@ export default function openPiSetup(pi: ExtensionAPI) {
       ui_footer_style: Type.Optional(
         StringEnum(FOOTER_STYLES, {
           description:
-            "Footer visual style: plain (Pi theme separators), powerline (ANSI256 colored blocks with  seams), powerline-mono (high-contrast gray powerline). Nerd Font improves separator glyphs only. Omit to preserve the current style (or the preset's style when a preset is applied).",
+            "Footer visual style: plain (Pi theme separators), powerline (ANSI256 colored blocks with  seams), powerline-mono (high-contrast gray powerline). A Nerd Font renders Codicon metric glyphs and powerline seams as designed; text stays readable without it. Omit to preserve the current style (or the preset's style when a preset is applied).",
         }),
       ),
       ui_footer_lines: Type.Optional(
@@ -401,13 +401,13 @@ export default function openPiSetup(pi: ExtensionAPI) {
       bash_tool_display: Type.Optional(
         StringEnum(DETAIL_DISPLAYS, {
           description:
-            "How Bash commands and output render by default: compact keeps a one-line command plus a bounded output preview with a hidden-line count and expands with app.tools.expand; full keeps every command expanded. Omit to preserve the current value.",
+            "How Bash commands and output render by default: compact shows one semantic activity row with running/success/failure state; app.tools.expand restores Pi's native command, output, error, timing, and full-output metadata. Full keeps Pi's native rendering expanded by default. Omit to preserve the current value.",
         }),
       ),
       file_mutation_display: Type.Optional(
         StringEnum(DETAIL_DISPLAYS, {
           description:
-            "How Write/Edit content and diffs render by default: compact shows a Claude Code-style folded preview with a hidden-line count and expands with app.tools.expand; full keeps every operation expanded. Omit to preserve the current value.",
+            "How Write/Edit content and diffs render by default: compact shows one semantic activity row with path, status, and line/diff counts; app.tools.expand restores Pi's native preview, output, error, and diff. Full keeps Pi's native rendering expanded by default. Omit to preserve the current value.",
         }),
       ),
       subagent_role_models: Type.Optional(SUBAGENT_ROLE_MODELS_SCHEMA),
@@ -573,7 +573,7 @@ export default function openPiSetup(pi: ExtensionAPI) {
           "Current configuration:",
           currentConfiguration,
           "",
-          "Capability discovery is explicit by default; adaptive is an opt-in that keeps only openpi_load_tools visible so the model may load useful groups. Footer tips: presets are powerline, powerline-mono, compact; style is plain/powerline/powerline-mono; custom layouts use ui_footer_lines (2D enum arrays with optional flex). Do not use ui_footer_items together with ui_footer_lines. Built-in Agent role models (explorer, implementer, reviewer, advisor) are shared by subagent_spawn and workflow agent_type; they inherit the parent unless assigned an available registry model, and clearing an assignment restores inheritance. Custom agent-type files still override built-in role definitions. Nerd Font only affects powerline separator glyphs. Changes apply immediately in the active TUI session. Intercom installation is handled only by the native setup confirmation; do not install packages or edit its config yourself.",
+          "Capability discovery is explicit by default; adaptive is an opt-in that keeps only openpi_load_tools visible so the model may load useful groups. Footer tips: presets are powerline, powerline-mono, compact; style is plain/powerline/powerline-mono; custom layouts use ui_footer_lines (2D enum arrays with optional flex). Do not use ui_footer_items together with ui_footer_lines. Built-in Agent role models (explorer, implementer, reviewer, advisor) are shared by subagent_spawn and workflow agent_type; they inherit the parent unless assigned an available registry model, and clearing an assignment restores inheritance. Custom agent-type files still override built-in role definitions. A Nerd Font renders Footer Codicons and powerline seams as designed; text stays readable without it. Changes apply immediately in the active TUI session. Intercom installation is handled only by the native setup confirmation; do not install packages or edit its config yourself.",
           "",
           "Use configure_my_pi_setup to apply only the requested OpenPI-owned changes and preserve everything else. Interpret model names from the available Pi registry. Do not edit configuration files directly.",
         ]

package/extensions/shared/activity-status.ts

@@ -8,8 +8,6 @@ export interface ActivityCounts {
   failed: number;
 }
 
-const SQUARE = "■";
-
 /**
  * Settled work is an unread notice, not a session tally: `done`/`failed` stay
  * visible until the user's next explicit request acknowledges them, while
@@ -49,15 +47,18 @@ export function formatActivityStatus(
   label: "subagents" | "workflows",
   counts: ActivityCounts,
 ) {
+  // No status glyphs here: the footer line is a static string refreshed on
+  // events, so a spinner would freeze between updates — the colored words
+  // carry the state on their own.
   const parts: string[] = [];
   if (counts.running > 0) {
-    parts.push(theme.fg("warning", `${SQUARE} ${counts.running} running`));
+    parts.push(theme.fg("warning", `${counts.running} running`));
   }
   if (counts.done > 0) {
-    parts.push(theme.fg("success", `${SQUARE} ${counts.done} done`));
+    parts.push(theme.fg("success", `${counts.done} done`));
   }
   if (counts.failed > 0) {
-    parts.push(theme.fg("error", `${SQUARE} ${counts.failed} failed`));
+    parts.push(theme.fg("error", `${counts.failed} failed`));
   }
   parts.push(theme.fg("accent", `/${label}`) + theme.fg("dim", " to view"));