feat(pi): add Pi (pi.dev) as a sixth CLI run mode (#206)

SessionMode gains 'pi', a first-class backend alongside Claude Code, OpenCode, Codex, Gemini and Antigravity: its own PTY, tmux session, rose tab identity, welcome button, run-mode entry, cron agentType, Docker and remote-SSH command defaults, and clone-repo Brain option. Pi is a different shape of CLI from the other four, and three decisions follow from that: - It has NO permission prompts and no sandbox, so there is no --dangerously-skip-permissions analog and none was invented. The privilege-shaped knob is the tri-state approveProjectTrust, which makes pi load and EXECUTE repo-local .pi/extensions TypeScript and install missing project packages. clampExternalCliBypassForOwner() therefore puts pi in the MATERIALIZE branch: a non-granted multi-user owner gets --no-approve even when no config was sent, because pi's own default is a prompt the session user could answer themselves. That helper had zero test coverage; it now has coverage for all four CLIs. - Only the PI_ prefix joins the env allowlist. Pi's ~34 provider key vars share no prefix and ALLOWED_ENV_PREFIXES is one global list with no mode context, so admitting them would widen the allowlist for every mode at once. Auth goes through pi's /login or the server's own environment. --api-key is deliberately never wired: it would put a provider secret on the spawn command line. - pi stays OUT of isAltScreenStripMode(). Its default TUI renders into the main screen with terminal-owned scrollback, and its 0.84.0 fullscreen mode is runtime-switchable via /settings; that flip was measured to put the pane into the alt screen, which the strip would have corrupted. pi-cli-resolver.ts additionally sanity-probes `pi --version` and requires semver-shaped output, because `pi` is a short generic name a stray binary can shadow; GET /api/pi/status surfaces path and version so a misresolution is diagnosable rather than presenting as a broken mode. Docker installs pi in its own --ignore-scripts step so that flag cannot affect the other four CLIs, and seeds its credentials per-file rather than whole-dir (~/.pi/agent also holds sessions, extensions and package trees). Verified end to end against pi 0.84.1 on an isolated instance: resolver search-dir fallback, flag construction, piConfig persistence across a full server restart, the trust prompt and its --no-approve suppression, the rose Run button on the default daylight-blue skin (the nested skin block eats per-mode gradients unless the rule lives inside it), and the buffer local-echo policy, which pi tolerates where codex did not. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-10-03 22:19:42 +02:00 · 2026-08-13 13:54:47 +02:00
parent f39beb3326
commit c5b59633d8
45 changed files with 2143 additions and 101 deletions
@@ -106,6 +106,14 @@ export const DEPENDENCY_REGISTRY: ToolDependency[] = [
    usedBy: ['Antigravity sessions'],
    resolvers: [{ match: ALL, resolver: { kind: 'path', bins: ['agy'], versionArg: '--version' } }],
  },
+  {
+    id: 'pi',
+    label: 'Pi CLI',
+    category: 'core',
+    required: false,
+    usedBy: ['Pi sessions'],
+    resolvers: [{ match: ALL, resolver: { kind: 'path', bins: ['pi'], versionArg: '--version' } }],
+  },
  {
    id: 'libreoffice',
    label: 'LibreOffice',
@@ -144,6 +144,7 @@ export function defaultDockerCommandForMode(mode: SessionMode): string {
    codex: 'exec codex',
    gemini: 'exec gemini',
    antigravity: 'exec agy',
+    pi: 'exec pi',
  };
  return commands[mode as DockerCommandMode] || commands.shell;
 }
@@ -600,6 +601,19 @@ const CRED_STORES: CredStorePolicy[] = [
  // `conversations/`, `knowledge/`) under `~/.gemini/antigravity-cli/`, so it needs no
  // entry of its own. There is no `~/.antigravity` credential dir to add.
  { rel: '.gemini', seedWhole: true },
+  // Pi (pi.dev) keeps auth + config in `~/.pi/agent`, but that dir ALSO holds
+  // `sessions/`, `extensions/`, `skills/` and the installed package trees
+  // (`npm/`, `git/`) — easily gigabytes on an active host, so seedWhole would
+  // `cp -a` all of it into every container start. Seed only what pi needs to
+  // authenticate and behave consistently; `models.json` is in the list because it
+  // holds user-defined custom providers. Consequence to document: in-container pi
+  // sessions are invisible host-side, so `pi -c` inside a Docker case only sees
+  // that container's own history (unlike codex, whose `sessions/` is shared RW
+  // precisely because Codeman reads it host-side).
+  {
+    rel: '.pi/agent',
+    seedFiles: ['auth.json', 'settings.json', 'trust.json', 'models.json', 'models-store.json'],
+  },
  { rel: '.config/gcloud', seedWhole: true },
  { rel: '.config/opencode', seedWhole: true },
 ];
@@ -18,6 +18,7 @@ import type {
  EffortLevel,
  GeminiConfig,
  AntigravityConfig,
+  PiConfig,
  SessionRemote,
  SessionDocker,
 } from './types.js';
@@ -76,6 +77,7 @@ export interface CreateSessionOptions {
  codexConfig?: CodexConfig;
  geminiConfig?: GeminiConfig;
  antigravityConfig?: AntigravityConfig;
+  piConfig?: PiConfig;
  /** When restoring after reboot, resume a previous Claude conversation by its session ID */
  resumeSessionId?: string;
  /** Extra env vars exported before launching the CLI (e.g., CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS). Ephemeral — not written to disk. */
@@ -107,6 +109,7 @@ export interface RespawnPaneOptions {
  codexConfig?: CodexConfig;
  geminiConfig?: GeminiConfig;
  antigravityConfig?: AntigravityConfig;
+  piConfig?: PiConfig;
  /** Resume a previous Claude conversation when respawning */
  resumeSessionId?: string;
  /** Extra env vars exported before launching the CLI (preserved across respawns). */
@@ -113,6 +113,7 @@ export function defaultRemoteCommandForMode(mode: SessionMode): string {
    codex: remoteLoginShellCommand('codex'),
    gemini: remoteLoginShellCommand('gemini'),
    antigravity: remoteLoginShellCommand('agy'),
+    pi: remoteLoginShellCommand('pi'),
  };
  return commands[mode as RemoteCommandMode] || commands.shell;
 }
@@ -50,6 +50,7 @@ import {
  type EffortLevel,
  type GeminiConfig,
  type AntigravityConfig,
+  type PiConfig,
  type SessionRemote,
  type SessionDocker,
 } from './types.js';
@@ -162,7 +163,7 @@ const NEWLINE_SPLIT_PATTERN = /\r?\n/;

 /** True for external-CLI run modes (non-Claude) that use their own TUI and output format. */
 export function isExternalCliMode(mode: SessionMode): boolean {
-  return mode === 'opencode' || mode === 'codex' || mode === 'gemini' || mode === 'antigravity';
+  return mode === 'opencode' || mode === 'codex' || mode === 'gemini' || mode === 'antigravity' || mode === 'pi';
 }

 function getModeLabel(mode: SessionMode): string {
@@ -175,6 +176,8 @@ function getModeLabel(mode: SessionMode): string {
      return 'Gemini';
    case 'antigravity':
      return 'Antigravity';
+    case 'pi':
+      return 'Pi';
    case 'shell':
      return 'Shell';
    case 'claude':
@@ -190,9 +193,12 @@ function getModeLabel(mode: SessionMode): string {
 * Codex, Claude Code, and Gemini are known, controlled (Ink/React) TUIs that
 * repaint via cursor positioning, so dropping the alt-screen switch is safe —
 * content stays in the normal buffer. Excluded: `shell` (arbitrary programs like
- * vim/less/htop legitimately need the alt screen) and `opencode` (renders its own
- * TUI that may rely on it). Keep parity with the replay-side strip in
- * session-routes.ts.
+ * vim/less/htop legitimately need the alt screen), `opencode` (renders its own
+ * TUI that may rely on it) and `pi` (its default TUI already renders into the
+ * MAIN screen with terminal-owned scrollback, so there is nothing to strip — and
+ * since pi 0.84.0 the user can switch to a fullscreen TUI at runtime via
+ * `/settings`, where the alt screen is load-bearing). Keep parity with the
+ * replay-side strip in session-routes.ts.
 */
 export function isAltScreenStripMode(mode: SessionMode): boolean {
  return mode === 'codex' || mode === 'claude' || mode === 'gemini';
@@ -468,6 +474,8 @@ export class Session extends EventEmitter {
  private _geminiConfig: GeminiConfig | undefined;
  // Antigravity configuration (only for mode === 'antigravity')
  private _antigravityConfig: AntigravityConfig | undefined;
+  // Pi configuration (only for mode === 'pi')
+  private _piConfig: PiConfig | undefined;
  private _resumeSessionId: string | undefined;

  // Ephemeral env overrides (e.g., CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS). Exported by tmux
@@ -561,6 +569,8 @@ export class Session extends EventEmitter {
      geminiConfig?: GeminiConfig;
      /** Antigravity configuration (only for mode === 'antigravity') */
      antigravityConfig?: AntigravityConfig;
+      /** Pi configuration (only for mode === 'pi') */
+      piConfig?: PiConfig;
      /** Resume a previous Claude conversation (used after server reboot) */
      resumeSessionId?: string;
      /** Extra env vars exported to the CLI at spawn time (no disk persistence) */
@@ -654,6 +664,11 @@ export class Session extends EventEmitter {
      this._antigravityConfig = config.antigravityConfig;
    }

+    // Apply Pi configuration
+    if (config.piConfig) {
+      this._piConfig = config.piConfig;
+    }
+
    // Apply env overrides (exported at spawn, not persisted to disk).
    // Legacy migration: pre-0.7.2 carried effort as the CLAUDE_CODE_EFFORT_LEVEL env var,
    // which hard-locks /effort switching. Extract it into _effort (--settings soft default)
@@ -1228,6 +1243,7 @@ export class Session extends EventEmitter {
      codexConfig: this._codexConfig,
      geminiConfig: this._geminiConfig,
      antigravityConfig: this._antigravityConfig,
+      piConfig: this._piConfig,
      resumeSessionId: this._resumeSessionId,
      effort: this._effort,
      // COD-118: runtime-only — surfaced so the frontend can require explicit user
@@ -1397,9 +1413,11 @@ export class Session extends EventEmitter {
          cols: ptyCols,
          rows: ptyRows,
          cwd: resolveMuxAttachCwd(this.workingDir, this._remote, this._docker),
-          // COD-75: codex/gemini/antigravity get COLORTERM=truecolor — mirrors buildEnvExports()
+          // COD-75: codex/gemini/antigravity/pi get COLORTERM=truecolor — mirrors buildEnvExports()
          // in tmux-manager.ts so the attach client and the tmux session agree.
-          env: buildMuxAttachEnv(this.mode === 'codex' || this.mode === 'gemini' || this.mode === 'antigravity'),
+          env: buildMuxAttachEnv(
+            this.mode === 'codex' || this.mode === 'gemini' || this.mode === 'antigravity' || this.mode === 'pi'
+          ),
        })
      );
    } catch (spawnErr) {
@@ -1467,6 +1485,7 @@ export class Session extends EventEmitter {
      codexConfig: this._codexConfig,
      geminiConfig: this._geminiConfig,
      antigravityConfig: this._antigravityConfig,
+      piConfig: this._piConfig,
      resumeSessionId: this._resumeSessionId,
      envOverrides: this._envOverrides,
      effort: this._effort,
@@ -1681,6 +1700,7 @@ export class Session extends EventEmitter {
            codexConfig: this._codexConfig,
            geminiConfig: this._geminiConfig,
            antigravityConfig: this._antigravityConfig,
+            piConfig: this._piConfig,
            resumeSessionId: this._resumeSessionId,
            envOverrides: this._envOverrides,
            effort: this._effort,
@@ -1766,6 +1786,10 @@ export class Session extends EventEmitter {
      if (this.mode === 'antigravity') {
        throw new Error('Antigravity sessions require tmux. Direct PTY fallback is not supported.');
      }
+      // Pi sessions require tmux for env override injection via setenv
+      if (this.mode === 'pi') {
+        throw new Error('Pi sessions require tmux. Direct PTY fallback is not supported.');
+      }
      try {
        // Pass --session-id to use the SAME ID as the Codeman session
        // This ensures subagents can be directly matched to the correct tab
@@ -45,6 +45,7 @@ import {
  type EffortLevel,
  type GeminiConfig,
  type AntigravityConfig,
+  type PiConfig,
  type SessionRemote,
  type SessionDocker,
  type DockerCommandMode,
@@ -78,6 +79,7 @@ import {
  resolveCodexDir,
  resolveGeminiDir,
  resolveAntigravityDir,
+  resolvePiDir,
  resolveLocalShell,
  loginShellArgs,
 } from './utils/index.js';
@@ -735,6 +737,63 @@ function buildAntigravityCommand(config?: AntigravityConfig): string {
  return parts.join(' ');
 }

+/** Pi's `--thinking` levels. Runtime allowlist — defense in depth beyond the Zod enum. */
+const PI_THINKING_LEVELS = new Set(['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']);
+
+/**
+ * Build the Pi CLI (pi.dev) command with appropriate flags.
+ *
+ * Pi has NO permission prompts and no `--dangerously-skip-permissions` analog, so
+ * there is deliberately nothing bypass-shaped here. The privileged knob is the
+ * TRI-STATE `approveProjectTrust`: `true` -> `--approve` (trust repo-local `.pi/`
+ * config, which means loading and EXECUTING repository TypeScript and installing
+ * missing project packages), `false` -> `--no-approve` (force-deny, used by the
+ * multi-user clamp so the trust prompt never appears), absent -> pi's own
+ * `defaultProjectTrust`.
+ *
+ * `--api-key` is deliberately NEVER wired: it would put a provider secret on the
+ * spawn command line (visible in `ps` and tmux state), which is exactly what the
+ * socket-scoped `tmux setenv` discipline exists to prevent.
+ *
+ * Like the sibling builders, every user value is regex-allowlisted and silently
+ * DROPPED on failure — the result is interpolated into a `bash -c "..."` string.
+ */
+function buildPiCommand(config?: PiConfig): string {
+  const parts = ['pi'];
+
+  if (config?.approveProjectTrust === true) {
+    parts.push('--approve');
+  } else if (config?.approveProjectTrust === false) {
+    parts.push('--no-approve');
+  }
+
+  if (config?.model) {
+    // `:` for a thinking suffix (`sonnet:high`), `/` for `provider/id` (`openai/gpt-4o`).
+    const safeModel = /^[a-zA-Z0-9._\-/:]+$/.test(config.model) ? config.model : undefined;
+    if (safeModel) parts.push('--model', safeModel);
+  }
+
+  if (config?.provider) {
+    const safeProvider = /^[a-z0-9-]+$/.test(config.provider) ? config.provider : undefined;
+    if (safeProvider) parts.push('--provider', safeProvider);
+  }
+
+  if (config?.thinking && PI_THINKING_LEVELS.has(config.thinking)) {
+    parts.push('--thinking', config.thinking);
+  }
+
+  // --session and -c conflict; a valid explicit session id wins.
+  const safeSessionId =
+    config?.resumeSessionId && /^[a-zA-Z0-9._-]+$/.test(config.resumeSessionId) ? config.resumeSessionId : undefined;
+  if (safeSessionId) {
+    parts.push('--session', safeSessionId);
+  } else if (config?.continueSession) {
+    parts.push('-c');
+  }
+
+  return parts.join(' ');
+}
+
 /**
 * Build the spawn command for any session mode.
 * Shared by createSession() and respawnPane() to avoid duplication.
@@ -777,6 +836,7 @@ export function buildSpawnCommand(options: {
  codexConfig?: CodexConfig;
  geminiConfig?: GeminiConfig;
  antigravityConfig?: AntigravityConfig;
+  piConfig?: PiConfig;
  resumeSessionId?: string;
  effort?: EffortLevel;
  /** Codeman session name, passed to claude as `--name` (version-gated, sanitized; local spawns only). */
@@ -823,6 +883,9 @@ export function buildSpawnCommand(options: {
  if (options.mode === 'antigravity') {
    return buildAntigravityCommand(options.antigravityConfig);
  }
+  if (options.mode === 'pi') {
+    return buildPiCommand(options.piConfig);
+  }
  // #208: NOT the literal '$SHELL'. This string is embedded in the `bash -c "…"`
  // argument of the respawn-pane line, which execSync runs through `/bin/sh -c`,
  // so a `$SHELL` here is expanded by the SERVER process's shell against the
@@ -1036,6 +1099,8 @@ function appendResumeFlag(modeCommand: string, mode: SessionMode, resumeId: stri
      return `${modeCommand} resume ${resumeId}`;
    case 'antigravity':
      return `${modeCommand} --conversation ${resumeId}`;
+    case 'pi':
+      return `${modeCommand} --session ${resumeId}`;
    default:
      return modeCommand; // shell / opencode: no resume
  }
@@ -1604,10 +1669,10 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
    const exports = [
      'export LANG=en_US.UTF-8',
      'export LC_ALL=en_US.UTF-8',
-      mode === 'codex' || mode === 'gemini' || mode === 'antigravity'
+      mode === 'codex' || mode === 'gemini' || mode === 'antigravity' || mode === 'pi'
        ? 'export COLORTERM=truecolor'
        : 'unset COLORTERM',
-      ...(mode === 'codex' || mode === 'gemini' || mode === 'antigravity' ? ['unset NO_COLOR'] : []),
+      ...(mode === 'codex' || mode === 'gemini' || mode === 'antigravity' || mode === 'pi' ? ['unset NO_COLOR'] : []),
      // Stamp each Codex pane with a unique originator so the response-viewer
      // can locate THIS pane's rollout exactly — codex writes the value into
      // session_meta.originator of every rollout it creates. Without it,
@@ -1698,6 +1763,10 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
      const dir = resolveAntigravityDir();
      return { pathExport: dir ? `export PATH="${dir}:$PATH" && ` : '', dir };
    }
+    if (mode === 'pi') {
+      const dir = resolvePiDir();
+      return { pathExport: dir ? `export PATH="${dir}:$PATH" && ` : '', dir };
+    }
    return { pathExport: '', dir: null };
  }

@@ -1746,6 +1815,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
      codexConfig,
      geminiConfig,
      antigravityConfig,
+      piConfig,
      resumeSessionId,
      envOverrides,
      effort,
@@ -1802,6 +1872,11 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
        'Antigravity CLI not found. Install with: curl -fsSL https://antigravity.google/cli/install.sh | bash'
      );
    }
+    if (mode === 'pi' && !cliDir) {
+      throw new Error(
+        'Pi CLI not found. Install with: npm install -g --ignore-scripts @earendil-works/pi-coding-agent'
+      );
+    }

    const envExportsStr = this.buildEnvExports(sessionId, muxName, mode).join(' && ');

@@ -1815,6 +1890,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
      codexConfig,
      geminiConfig,
      antigravityConfig,
+      piConfig,
      resumeSessionId,
      effort,
      sessionName: name,
@@ -2039,6 +2115,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
      codexConfig,
      geminiConfig,
      antigravityConfig,
+      piConfig,
      resumeSessionId,
      envOverrides,
      effort,
@@ -2078,6 +2155,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
      codexConfig,
      geminiConfig,
      antigravityConfig,
+      piConfig,
      resumeSessionId,
      effort,
      sessionName: name,
@@ -8,13 +8,14 @@
 * - SessionConfig — creation-time config (id, workingDir, createdAt)
 * - SessionOutput — captured stdout/stderr/exitCode
 * - SessionStatus — 'idle' | 'busy' | 'stopped' | 'error'
- * - SessionMode — 'claude' | 'shell' | 'opencode' | 'codex' | 'gemini' | 'antigravity' (which CLI backend)
+ * - SessionMode — 'claude' | 'shell' | 'opencode' | 'codex' | 'gemini' | 'antigravity' | 'pi' (which CLI backend)
 * - ClaudeMode — CLI permission mode ('dangerously-skip-permissions' | 'auto' | 'normal' | 'allowedTools')
 * - SessionColor — visual differentiation color
 * - OpenCodeConfig — OpenCode-specific settings (model, autoAllowTools, continueSession)
 * - CodexConfig — Codex (OpenAI CLI)-specific settings (model, resumeSessionId)
 * - GeminiConfig — Gemini CLI-specific settings (model, approvalMode, resumeSession)
 * - AntigravityConfig — Antigravity CLI (agy) settings (model, dangerouslySkipPermissions, resumeConversationId)
+ * - PiConfig — Pi CLI (pi.dev) settings (model, provider, thinking, resume/continue, project trust)
 *
 * Cross-domain relationships:
 * - SessionState.respawnConfig embeds RespawnConfig (respawn domain)
@@ -43,11 +44,11 @@ export type SessionStatus = 'idle' | 'busy' | 'stopped' | 'error';
 export type ClaudeMode = 'dangerously-skip-permissions' | 'auto' | 'normal' | 'allowedTools';

 /** Session mode: which CLI backend a session runs */
-export type SessionMode = 'claude' | 'shell' | 'opencode' | 'codex' | 'gemini' | 'antigravity';
+export type SessionMode = 'claude' | 'shell' | 'opencode' | 'codex' | 'gemini' | 'antigravity' | 'pi';

 export type RemoteCommandMode = Extract<
  SessionMode,
-  'shell' | 'claude' | 'opencode' | 'codex' | 'gemini' | 'antigravity'
+  'shell' | 'claude' | 'opencode' | 'codex' | 'gemini' | 'antigravity' | 'pi'
 >;

 /**
@@ -156,7 +157,7 @@ export interface RemoteSessionInfo {
 /** Which CLI backends a Docker case can run (same set as remote). */
 export type DockerCommandMode = Extract<
  SessionMode,
-  'shell' | 'claude' | 'opencode' | 'codex' | 'gemini' | 'antigravity'
+  'shell' | 'claude' | 'opencode' | 'codex' | 'gemini' | 'antigravity' | 'pi'
 >;

 /** Container engine. Docker and Podman differ in the uid/userns + host-gateway alias. */
@@ -331,6 +332,37 @@ export interface AntigravityConfig {
  resumeConversationId?: string;
 }

+/**
+ * Pi CLI (pi.dev) session configuration.
+ *
+ * Pi has NO permission prompts and no `--dangerously-skip-permissions` analog,
+ * so there is deliberately no bypass field here. The one privilege-shaped knob is
+ * `approveProjectTrust`, which controls whether pi loads and EXECUTES repo-local
+ * `.pi/` extensions (and installs missing project packages).
+ */
+export interface PiConfig {
+  /** Model pattern or ID. Supports `provider/id` and a `:<thinking>` suffix (e.g. `sonnet:high`). Passed via --model. */
+  model?: string;
+  /** Provider name (anthropic, openai, google, ...). Passed via --provider. */
+  provider?: string;
+  /** Reasoning level. Passed via --thinking. */
+  thinking?: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+  /** Continue the most recent session (-c). Skipped when resumeSessionId is set (the two conflict). */
+  continueSession?: boolean;
+  /** Resume a specific session by ID or partial UUID (--session). Ids only, never paths. */
+  resumeSessionId?: string;
+  /**
+   * Tri-state project trust (repo-local `.pi/` settings/extensions/skills, plus
+   * installing missing project packages):
+   *   true   -> --approve    (trust for this run; loads and EXECUTES repository TypeScript)
+   *   false  -> --no-approve (force-deny; the trust prompt never appears)
+   *   absent -> pi's own defaultProjectTrust (ask).
+   * Multi-user: MATERIALIZED to false for non-granted owners, because pi's
+   * absent-config default is a prompt the session user could answer themselves.
+   */
+  approveProjectTrust?: boolean;
+}
+
 /**
 * Configuration for creating a new session
 */
@@ -484,6 +516,8 @@ export interface SessionState {
  geminiConfig?: GeminiConfig;
  /** Antigravity-specific configuration (only for mode === 'antigravity') */
  antigravityConfig?: AntigravityConfig;
+  /** Pi-specific configuration (only for mode === 'pi') */
+  piConfig?: PiConfig;
  /** Claude conversation session ID to resume after reboot (set by restore script) */
  resumeSessionId?: string;
  /** Claude CLI effort level (soft default via --settings, switchable in-session via /effort) */
@@ -34,3 +34,4 @@ export { resolveOpenCodeDir } from './opencode-cli-resolver.js';
 export { resolveCodexDir, isCodexAvailable } from './codex-cli-resolver.js';
 export { resolveGeminiDir, isGeminiAvailable } from './gemini-cli-resolver.js';
 export { resolveAntigravityDir, isAntigravityAvailable } from './antigravity-cli-resolver.js';
+export { resolvePiDir, isPiAvailable, getPiCliVersion } from './pi-cli-resolver.js';
@@ -0,0 +1,134 @@
+/**
+ * @fileoverview Resolve the Pi CLI (`pi`) binary across common install paths.
+ *
+ * Mirrors antigravity-cli-resolver.ts, with one addition the other external-CLI
+ * resolvers do not need: `pi` is a SHORT, GENERIC name (Raspberry Pi tooling,
+ * personal scripts, `$PATH` accidents), so a `which pi` hit is not by itself
+ * evidence that the coding agent is installed. Every candidate is therefore
+ * sanity-probed with `pi --version` and required to print a semver-shaped
+ * string; a binary that fails the probe is treated as absent and the rejected
+ * path is logged so a misresolution is diagnosable.
+ *
+ * Pi ships as the npm package `@earendil-works/pi-coding-agent`, so the search
+ * dirs are the usual global-bin locations (npm/bun/manual installs).
+ *
+ * @module utils/pi-cli-resolver
+ */
+
+import { execFileSync, execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { EXEC_TIMEOUT_MS } from '../config/exec-timeout.js';
+
+/** Common directories where the Pi CLI binary may be installed */
+const PI_SEARCH_DIRS = [
+  join(homedir(), '.local', 'bin'),
+  '/usr/local/bin',
+  join(homedir(), '.bun', 'bin'),
+  join(homedir(), '.npm-global', 'bin'),
+  join(homedir(), 'bin'),
+];
+
+/** A real `pi --version` prints a semver-shaped string (e.g. `0.84.1`). */
+const PI_VERSION_PATTERN = /^\d+\.\d+\.\d+/;
+
+/** Cached directory containing the pi binary (empty string = searched but not found) */
+let _piDir: string | null = null;
+/** Cached version string reported by the resolved binary (empty string = probed, unusable) */
+let _piVersion: string | null = null;
+
+/**
+ * Run `pi --version` on a candidate path and return the trimmed version when it
+ * looks like the coding agent. Returns null for anything else — a missing
+ * binary, a non-zero exit, a hang (timeout), or output that is not semver-shaped
+ * (which is how an unrelated `pi` on PATH gets rejected).
+ *
+ * Never runs under vitest: the suites must stay hermetic and must not depend on
+ * whether the dev box happens to have pi installed.
+ */
+function probePiVersion(binPath: string): string | null {
+  if (process.env.VITEST) return null;
+  try {
+    const out = execFileSync(binPath, ['--version'], {
+      encoding: 'utf-8',
+      timeout: EXEC_TIMEOUT_MS,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    // Upstream prints a bare version today; tolerate a `pi 0.84.1` style prefix too.
+    const candidate = out.split(/\s+/).find((token) => PI_VERSION_PATTERN.test(token));
+    if (candidate) return candidate;
+    console.warn(`[PiResolver] Ignoring ${binPath}: "pi --version" printed ${JSON.stringify(out.slice(0, 80))}`);
+  } catch (err) {
+    console.warn(`[PiResolver] Ignoring ${binPath}: "pi --version" failed (${(err as Error).message})`);
+  }
+  return null;
+}
+
+/**
+ * Finds the directory containing a verified `pi` binary.
+ * Checks `which pi` first, then falls back to common install locations. Every
+ * candidate must pass the `pi --version` sanity probe (§2.6 of the integration
+ * plan) before it is accepted.
+ *
+ * @returns Directory path, or null if not found
+ */
+export function resolvePiDir(): string | null {
+  if (_piDir !== null) return _piDir || null;
+
+  const accept = (binPath: string): string | null => {
+    // Under vitest the probe never runs, so existence alone decides (keeps the
+    // suites hermetic and matches how the sibling resolvers behave there).
+    if (process.env.VITEST) {
+      _piDir = dirname(binPath);
+      _piVersion = '';
+      return _piDir;
+    }
+    const version = probePiVersion(binPath);
+    if (!version) return null;
+    _piDir = dirname(binPath);
+    _piVersion = version;
+    return _piDir;
+  };
+
+  try {
+    const result = execSync('which pi', {
+      encoding: 'utf-8',
+      timeout: EXEC_TIMEOUT_MS,
+    }).trim();
+    if (result && existsSync(result)) {
+      const dir = accept(result);
+      if (dir) return dir;
+    }
+  } catch {
+    // pi not in PATH, will check common locations
+  }
+
+  for (const dir of PI_SEARCH_DIRS) {
+    const binPath = join(dir, 'pi');
+    if (!existsSync(binPath)) continue;
+    const accepted = accept(binPath);
+    if (accepted) return accepted;
+  }
+
+  _piDir = '';
+  _piVersion = '';
+  return null;
+}
+
+/**
+ * Check if the Pi CLI is available on the system.
+ */
+export function isPiAvailable(): boolean {
+  return resolvePiDir() !== null;
+}
+
+/**
+ * Version reported by the resolved `pi` binary, or null when pi is unavailable
+ * (or when the probe was skipped, i.e. under vitest). Surfaced through
+ * `GET /api/pi/status` so a misresolution is diagnosable from the UI.
+ */
+export function getPiCliVersion(): string | null {
+  resolvePiDir();
+  return _piVersion || null;
+}
@@ -2003,9 +2003,11 @@ class CodemanApp {
        ? 'Gemini'
        : mode === 'antigravity'
          ? 'Antigravity'
-          : mode === 'opencode'
-            ? 'OpenCode'
-            : 'Claude';
+          : mode === 'pi'
+            ? 'Pi'
+            : mode === 'opencode'
+              ? 'OpenCode'
+              : 'Claude';
  }

  async toggleResponseViewer() {
@@ -3881,7 +3883,7 @@ class CodemanApp {
          <span class="tab-status ${status}" aria-hidden="true"></span>
          <span class="tab-info">
            <span class="tab-name-row">
-              ${mode === 'shell' ? '<span class="tab-mode shell" aria-hidden="true">sh</span>' : mode === 'opencode' ? '<span class="tab-mode opencode" aria-hidden="true">oc</span>' : mode === 'codex' ? '<span class="tab-mode codex" aria-hidden="true">cx</span>' : mode === 'gemini' ? '<span class="tab-mode gemini" aria-hidden="true">gm</span>' : mode === 'antigravity' ? '<span class="tab-mode antigravity" aria-hidden="true">ag</span>' : ''}
+              ${mode === 'shell' ? '<span class="tab-mode shell" aria-hidden="true">sh</span>' : mode === 'opencode' ? '<span class="tab-mode opencode" aria-hidden="true">oc</span>' : mode === 'codex' ? '<span class="tab-mode codex" aria-hidden="true">cx</span>' : mode === 'gemini' ? '<span class="tab-mode gemini" aria-hidden="true">gm</span>' : mode === 'antigravity' ? '<span class="tab-mode antigravity" aria-hidden="true">ag</span>' : mode === 'pi' ? '<span class="tab-mode pi" aria-hidden="true">pi</span>' : ''}
              <span class="tab-name" data-session-id="${id}">${escapeHtml(tabLabel)}</span>
              <span class="tab-detached-badge" aria-hidden="true">detached</span>
            </span>
@@ -5053,7 +5055,9 @@ class CodemanApp {
            ? 'Kill Tmux & Gemini'
            : session.mode === 'antigravity'
              ? 'Kill Tmux & Antigravity'
-              : 'Kill Tmux & Claude Code';
+              : session.mode === 'pi'
+                ? 'Kill Tmux & Pi'
+                : 'Kill Tmux & Claude Code';
    }

    document.getElementById('closeConfirmModal').classList.add('active');
@@ -104,6 +104,7 @@
    'Run OpenCode': '运行 OpenCode',
    'Run Gemini': '运行 Gemini',
    'Run Antigravity': '运行 Antigravity',
+    'Run Pi': '运行 Pi',
    'Run Shell': '运行 Shell',
    'Select AI backend': '选择 AI 后端',
    'Create New Case': '新建案例',
@@ -352,6 +352,10 @@
              <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polygon points="5 3 19 12 5 21 5 3"/></svg>
              Run Gemini
            </button>
+            <button class="welcome-btn welcome-btn-pi" id="welcomePiBtn" style="display: none;" onclick="app.setRunMode('pi'); app.runPi()">
+              <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polygon points="5 3 19 12 5 21 5 3"/></svg>
+              Run Pi
+            </button>
          </div>
          <div class="welcome-qr" id="welcomeQr" onclick="app.toggleWelcomeQrSize()">
            <div class="welcome-qr-inner" id="welcomeQrInner"></div>
@@ -526,6 +530,9 @@
              <button class="run-mode-option" data-mode="antigravity" onclick="app.setRunMode('antigravity')">
                <span class="run-mode-dot antigravity"></span>Antigravity
              </button>
+              <button class="run-mode-option" data-mode="pi" onclick="app.setRunMode('pi')">
+                <span class="run-mode-dot pi"></span>Pi
+              </button>
              <div class="run-mode-sep"></div>
              <button class="run-mode-option" data-mode="shell" onclick="app.setRunMode('shell')">
                <span class="run-mode-dot shell"></span>Terminal / Shell
@@ -801,6 +808,7 @@
                <option value="codex">Codex</option>
                <option value="gemini">Gemini</option>
                <option value="antigravity">Antigravity</option>
+                <option value="pi">Pi</option>
              </select>
            </div>
            <div class="form-row"><label>Working Directory</label><input type="text" id="schWorkingDir" placeholder="/absolute/path"></div>
@@ -2481,6 +2489,7 @@
                <option value="gemini" data-cli="gemini">Gemini</option>
                <option value="opencode" data-cli="opencode">OpenCode</option>
                <option value="antigravity" data-cli="antigravity">Antigravity</option>
+                <option value="pi" data-cli="pi">Pi</option>
                <option value="shell">Shell (no agent)</option>
              </select>
              <span class="form-hint">Which CLI to point the Run button at once the clone finishes. Changeable any time from the Run dropdown.</span>
@@ -2621,7 +2630,7 @@
            <div class="form-row">
              <label>Image</label>
              <input type="text" id="dockerImage" placeholder="codeman/agent:base" autocomplete="off" autocapitalize="off" spellcheck="false">
-              <span class="form-hint">Build it once with <code>node scripts/build-agent-image.mjs</code>. Contains node + claude/codex/gemini/opencode/agy + tmux.</span>
+              <span class="form-hint">Build it once with <code>node scripts/build-agent-image.mjs</code>. Contains node + claude/codex/gemini/opencode/agy/pi + tmux.</span>
            </div>
            <div class="form-row">
              <label>Network</label>
@@ -58,6 +58,7 @@ const MOBILE_OVERVIEW_RUN_MODES = [
  { mode: 'codex', label: 'Codex', short: 'Codex' },
  { mode: 'gemini', label: 'Gemini', short: 'Gemini' },
  { mode: 'antigravity', label: 'Antigravity', short: 'Antigravity' },
+  { mode: 'pi', label: 'Pi', short: 'Pi' },
  { mode: 'shell', label: 'Terminal / Shell', short: 'Shell' },
 ];

@@ -911,6 +911,25 @@ html.mobile-init .file-browser-panel {
    border-color: rgba(34, 211, 238, 0.5);
  }

+  /* Pi mode colors on mobile.
+     `!important` is load-bearing here, not noise: styles.css nests its skin rules
+     inside `html:not([data-skin="og"])`, so a bare `.btn-toolbar.btn-run` in there
+     resolves to (0,2,1) and outranks this (0,2,0) `.mode-pi` pair regardless of
+     load order. The antigravity block right above omits it and is consequently
+     dead on every non-og skin (i.e. on the default) — do not copy that. */
+  .btn-toolbar.btn-run.mode-pi,
+  .btn-toolbar.btn-run-gear.mode-pi {
+    background: #33121f !important;
+    border-color: rgba(244, 114, 182, 0.3) !important;
+    color: #fce7f3 !important;
+  }
+
+  .btn-toolbar.btn-run.mode-pi:active,
+  .btn-toolbar.btn-run-gear.mode-pi:active {
+    background: #9d174d !important;
+    border-color: rgba(244, 114, 182, 0.5) !important;
+  }
+
  /* Run mode dropdown menu — positioned above toolbar on mobile */
  .run-mode-menu {
    bottom: 100%;
@@ -2988,6 +3007,12 @@ html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="cat
  color: #ffffff;
 }

+html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="catppuccin-latte"], [data-skin="rose-pine-dawn"]) :is(.btn-toolbar.btn-run.mode-pi, .btn-toolbar.btn-run-gear.mode-pi) {
+  background: linear-gradient(135deg, #be185d, #db2777);
+  border-color: #9d174d;
+  color: #ffffff;
+}
+
 html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="catppuccin-latte"], [data-skin="rose-pine-dawn"]) .btn-toolbar.btn-run-gear {
  border-left-color: var(--control-border-hover) !important;
 }
@@ -427,7 +427,7 @@ Object.assign(CodemanApp.prototype, {

  _buildCommandPaletteNewSessionItem(query = '') {
    const mode = this.runMode || this._runMode || 'claude';
-    const labels = { claude: 'Claude', opencode: 'OpenCode', codex: 'Codex', gemini: 'Gemini', antigravity: 'Antigravity' };
+    const labels = { claude: 'Claude', opencode: 'OpenCode', codex: 'Codex', gemini: 'Gemini', antigravity: 'Antigravity', pi: 'Pi' };
    const caseName = this._findCommandPaletteCaseMatch(query) || document.getElementById('quickStartCase')?.value || 'testcase';
    return {
      id: 'new-session',
@@ -1,5 +1,5 @@
 /**
- * @fileoverview Quick start (case loading, session spawning for Claude/Shell/OpenCode/Codex/Gemini/Antigravity),
+ * @fileoverview Quick start (case loading, session spawning for Claude/Shell/OpenCode/Codex/Gemini/Antigravity/Pi),
 * session options modal (per-session settings, color picker, rename),
 * session options tabs (Ralph config tab), case settings (CRUD, links),
 * create case modal, and mobile case picker.
@@ -400,6 +400,9 @@ Object.assign(CodemanApp.prototype, {
      if (mode === 'antigravity') {
        return await this.runAntigravity();
      }
+      if (mode === 'pi') {
+        return await this.runPi();
+      }
      if (mode === 'shell') {
        return await this.runShell();
      }
@@ -461,11 +464,11 @@ Object.assign(CodemanApp.prototype, {
   * `.run-mode-option` is also the class the saved-dashboard rows and the history
   * rows use, and a bare querySelector would find whichever came first in the DOM.
   *
-   * Antigravity is in this list even though #201 predates it — it is a run mode
-   * like the rest, and `agy` is the LEAST likely of the five to be installed.
+   * Antigravity and Pi are in this list even though #201 predates them — they are
+   * run modes like the rest, and neither `agy` nor `pi` is likely to be installed.
   */
  _refreshRunModeAvailability(menu) {
-    for (const mode of ['claude', 'opencode', 'codex', 'gemini', 'antigravity']) {
+    for (const mode of ['claude', 'opencode', 'codex', 'gemini', 'antigravity', 'pi']) {
      const btn = menu.querySelector(`.run-mode-option[data-mode="${mode}"]`);
      if (btn) btn.style.display = this.isCliAvailable(mode) ? 'flex' : 'none';
    }
@@ -562,7 +565,7 @@ Object.assign(CodemanApp.prototype, {
      gearBtn.className = `btn-toolbar btn-run-gear mode-${mode}`;
    }
    if (label) {
-      label.textContent = mode === 'opencode' ? 'Run OC' : mode === 'codex' ? 'Run CX' : mode === 'gemini' ? 'Run GM' : mode === 'antigravity' ? 'Run AG' : mode === 'shell' ? 'Run SH' : 'Run';
+      label.textContent = mode === 'opencode' ? 'Run OC' : mode === 'codex' ? 'Run CX' : mode === 'gemini' ? 'Run GM' : mode === 'antigravity' ? 'Run AG' : mode === 'pi' ? 'Run PI' : mode === 'shell' ? 'Run SH' : 'Run';
    }
  },

@@ -1218,6 +1221,63 @@ Object.assign(CodemanApp.prototype, {
    }
  },

+  /**
+   * Launch a Pi (pi.dev) session.
+   *
+   * Deliberately sends NO piConfig: pi has no permission prompts, so there is no
+   * bypass to opt into, and project trust is pi's own `defaultProjectTrust`
+   * decision (an interactive prompt the user answers in the terminal). Sending
+   * `approveProjectTrust: true` here would silently opt every browser-launched pi
+   * session into executing repo-supplied TypeScript.
+   */
+  async runPi() {
+    const caseName = document.getElementById('quickStartCase').value || 'testcase';
+    // Remote/docker cases run pi on the OTHER side — skip the local status probe and the
+    // local-only config/env below (quick-start rejects them for remote cases).
+    const _runLoc = (this.cases || []).find(c => c.name === caseName)?.location;
+    const isRemote = _runLoc === 'remote' || _runLoc === 'docker';
+
+    const ownsLaunchTerminal = this._beginSessionLaunchStatus(`Starting Pi session in ${caseName}...`);
+    this.terminal.focus();
+
+    try {
+      if (!isRemote) {
+        const statusRes = await fetch('/api/pi/status');
+        const status = (await statusRes.json()).data;
+        if (!status.available) {
+          this._reportSessionLaunchError(
+            ownsLaunchTerminal,
+            'Pi CLI not found. Install with: npm install -g --ignore-scripts @earendil-works/pi-coding-agent'
+          );
+          return;
+        }
+      }
+
+      const envOverrides = this.buildEnvOverrides(this.getCaseSettings(caseName), this.loadAppSettingsFromStorage());
+      const res = await fetch('/api/quick-start', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          caseName,
+          mode: 'pi',
+          sessionName: `w${this._nextCaseSessionStartNumber(caseName)}-${caseName}`,
+          ...(isRemote || Object.keys(envOverrides).length === 0 ? {} : { envOverrides }),
+        })
+      });
+      const data = await res.json();
+      if (!data.success) throw new Error(data.error || 'Failed to start Pi');
+      await this._ensureCreatedSessionVisible(data.data.sessionId, data.data.session);
+
+      if (data.data.sessionId) {
+        await this.selectSession(data.data.sessionId);
+      }
+
+      this.terminal.focus();
+    } catch (err) {
+      this._reportSessionLaunchError(ownsLaunchTerminal, err.message);
+    }
+  },
+

  // ═══════════════════════════════════════════════════════════════
  // Session Options Modal
@@ -1230,7 +1290,7 @@ Object.assign(CodemanApp.prototype, {
    this.editingSessionId = sessionId;

    // Reset to an appropriate tab — Summary for external CLIs (Respawn/Ralph are Claude-only)
-    const isAltMode = session.mode === 'opencode' || session.mode === 'codex' || session.mode === 'gemini' || session.mode === 'antigravity';
+    const isAltMode = session.mode === 'opencode' || session.mode === 'codex' || session.mode === 'gemini' || session.mode === 'antigravity' || session.mode === 'pi';
    this.switchOptionsTab(isAltMode ? 'summary' : 'respawn');

    // Update respawn status display and buttons
@@ -1260,7 +1320,7 @@ Object.assign(CodemanApp.prototype, {
    }

    // Hide Claude-specific options for external CLI sessions
-    const isExternalCli = session.mode === 'opencode' || session.mode === 'codex' || session.mode === 'gemini' || session.mode === 'antigravity';
+    const isExternalCli = session.mode === 'opencode' || session.mode === 'codex' || session.mode === 'gemini' || session.mode === 'antigravity' || session.mode === 'pi';
    const claudeOnlyEls = document.querySelectorAll('[data-claude-only]');
    claudeOnlyEls.forEach(el => { el.style.display = isExternalCli ? 'none' : ''; });

@@ -2952,7 +3012,7 @@ Object.defineProperty(CodemanApp.prototype, 'runMode', {
  },
  set(mode) {
    this._runMode =
-      mode === 'opencode' || mode === 'codex' || mode === 'gemini' || mode === 'antigravity' || mode === 'claude'
+      mode === 'opencode' || mode === 'codex' || mode === 'gemini' || mode === 'antigravity' || mode === 'pi' || mode === 'claude'
        ? mode
        : 'claude';
  },
@@ -1179,6 +1179,7 @@ Object.assign(CodemanApp.prototype, {
      ['welcomeOpencodeBtn', 'opencode'],
      ['welcomeAntigravityBtn', 'antigravity'],
      ['welcomeGeminiBtn', 'gemini'],
+      ['welcomePiBtn', 'pi'],
      // Not a run mode, same reasoning: offering a Cloudflare Tunnel on a box
      // without cloudflared can only ever produce "cloudflared not found".
      ['welcomeTunnelBtn', 'cloudflared'],
@@ -329,7 +329,8 @@ html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="cat
  .search-badge-session,
  .history-view-all-btn,
  .session-tab .tab-mode.gemini,
-  .session-tab .tab-mode.antigravity
+  .session-tab .tab-mode.antigravity,
+  .session-tab .tab-mode.pi
 ) {
  color: var(--accent-d);
 }
@@ -2159,6 +2160,11 @@ body.solo-mode .btn-lifecycle-log {
  color: #22d3ee;
 }

+.session-tab .tab-mode.pi {
+  background: rgba(244, 114, 182, 0.2);
+  color: #f472b6;
+}
+
 /* Timer Banner - Compact */
 .timer-banner {
  display: flex;
@@ -3378,6 +3384,23 @@ body.touch-device .terminal-container .xterm .xterm-helper-textarea {
  transform: translateY(-1px);
 }

+/* Pi (pi.dev): rose identity, matching .btn-toolbar.btn-run.mode-pi and
+   .run-mode-dot.pi so the welcome action reads as the same backend. */
+.welcome-btn-pi {
+  background: linear-gradient(135deg, #33121f 0%, #9d174d 55%, #be185d 100%);
+  border-color: rgba(244, 114, 182, 0.4);
+  color: #fce7f3;
+  box-shadow: 0 2px 8px rgba(244, 114, 182, 0.16), inset 0 1px 0 rgba(255, 255, 255, 0.06);
+}
+
+.welcome-btn-pi:hover {
+  background: linear-gradient(135deg, #4a1a2c 0%, #be185d 55%, #db2777 100%);
+  box-shadow: 0 4px 20px rgba(244, 114, 182, 0.3), 0 0 40px rgba(190, 24, 93, 0.12), inset 0 1px 0 rgba(255, 255, 255, 0.08);
+  border-color: rgba(249, 168, 212, 0.5);
+  color: #fff1f7;
+  transform: translateY(-1px);
+}
+
 .welcome-btn-gemini {
  background: linear-gradient(135deg, #10243f 0%, #174ea6 55%, #4f46e5 100%);
  border-color: rgba(96, 165, 250, 0.4);
@@ -4432,6 +4455,26 @@ body.touch-device .terminal-container .xterm .xterm-helper-textarea {
  color: #ecfeff;
 }

+/* Pi mode colors. NOTE: this base-sheet pair only renders on the `og` skin — the
+   nested `html:not([data-skin="og"])` block further down re-declares
+   `.btn-toolbar.btn-run` at a HIGHER specificity, which is why gemini's and
+   antigravity's gradients are dead on the default skin. Pi therefore also carries
+   a rule inside that block (search `.btn-toolbar.btn-run.mode-pi`). */
+.btn-toolbar.btn-run.mode-pi,
+.btn-toolbar.btn-run-gear.mode-pi {
+  background: linear-gradient(135deg, #33121f 0%, #9d174d 55%, #be185d 100%);
+  border-color: rgba(244, 114, 182, 0.5);
+  color: #fce7f3;
+  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.2), inset 0 1px 0 rgba(255, 255, 255, 0.06);
+}
+.btn-toolbar.btn-run.mode-pi:hover,
+.btn-toolbar.btn-run-gear.mode-pi:hover {
+  background: linear-gradient(135deg, #4a1a2c 0%, #be185d 55%, #db2777 100%);
+  box-shadow: 0 0 12px rgba(244, 114, 182, 0.35), 0 2px 8px rgba(190, 24, 93, 0.2), inset 0 1px 0 rgba(255, 255, 255, 0.08);
+  border-color: rgba(249, 168, 212, 0.6);
+  color: #fff1f7;
+}
+
 /* Dropdown menu */
 .run-mode-menu {
  display: none;
@@ -4514,6 +4557,7 @@ body.touch-device .terminal-container .xterm .xterm-helper-textarea {
 .run-mode-dot.codex { background: #a855f7; }
 .run-mode-dot.gemini { background: #8ab4f8; }
 .run-mode-dot.antigravity { background: #22d3ee; }
+.run-mode-dot.pi { background: #f472b6; }
 .run-mode-dot.shell { background: #94a3b8; }

 /* Phone-only Enter button (see index.html). Hidden by default at every width;
@@ -13790,6 +13834,17 @@ html:not([data-skin="og"]) {
  color: #061c20;
 }
 .btn-toolbar.btn-run.mode-codex:hover { box-shadow: 0 0 14px -2px rgba(43, 203, 187, 0.45); }
+/* Pi keeps its rose identity on the non-og skins. This rule has to live INSIDE
+   this nested block: the generic `.btn-toolbar.btn-run` above resolves to (0,3,1)
+   here and would otherwise beat the base sheet's (0,3,0) `.mode-pi` pair, which
+   is exactly why gemini's and antigravity's gradients render as generic claude
+   blue on the default skin. */
+.btn-toolbar.btn-run.mode-pi {
+  background: linear-gradient(135deg, #be185d, #f472b6);
+  border-color: #be185d;
+  color: #fff1f7;
+}
+.btn-toolbar.btn-run.mode-pi:hover { box-shadow: 0 0 14px -2px rgba(244, 114, 182, 0.45); }
 .btn-toolbar.btn-run-gear {
  background: var(--accent-d);
  border-color: var(--accent);
@@ -1747,7 +1747,7 @@ Object.assign(CodemanApp.prototype, {
    }
    titleSpan.appendChild(document.createTextNode(this._historyRowLabel(s, shortDir)));

-    // Badge row: mode (claude/codex/opencode/gemini/antigravity/shell) + a LIVE pill.
+    // Badge row: mode (claude/codex/opencode/gemini/antigravity/pi/shell) + a LIVE pill.
    const badgeRow = document.createElement('div');
    badgeRow.className = 'history-item-badges';
    if (s.mode) {
@@ -22,6 +22,7 @@ import {
  type CodexConfig,
  type GeminiConfig,
  type AntigravityConfig,
+  type PiConfig,
 } from '../../types.js';
 import { Session, isAltScreenStripMode, isMuxAltScreenOnlyStripMode } from '../../session.js';
 import { SseEvent } from '../sse-events.js';
@@ -312,29 +313,50 @@ export function _resetPasteRateBuckets(): void {
 * Antigravity is like Codex: an ABSENT config already defaults safe (no bypass flag), so
 * only a sent config needs the flag forced off. No-op in single-user mode / for a granted
 * owner (canUsernameRunPrivilegedCommands returns true when !isMultiUserMode()).
+ *
+ * Pi has no permission prompts at all, so there is no bypass switch to clamp; its
+ * privilege-shaped knob is `approveProjectTrust`, which makes pi LOAD AND EXECUTE
+ * repo-local `.pi/extensions` TypeScript and npm-install missing project packages.
+ * Pi joins the gemini-style MATERIALIZE branch, not the codex/antigravity
+ * only-if-sent one: pi's absent-config default is an interactive trust prompt the
+ * session user could simply answer "yes" to in the terminal, so merely omitting
+ * `--approve` is not a clamp. Forcing `approveProjectTrust: false` makes
+ * buildPiCommand emit `--no-approve`, and the prompt never appears.
 */
 async function clampExternalCliBypassForOwner(
  owner: string | undefined,
  codexConfig: CodexConfig | undefined,
  geminiConfig: GeminiConfig | undefined,
-  antigravityConfig: AntigravityConfig | undefined
+  antigravityConfig: AntigravityConfig | undefined,
+  piConfig: PiConfig | undefined
 ): Promise<{
  codexConfig: CodexConfig | undefined;
  geminiConfig: GeminiConfig | undefined;
  antigravityConfig: AntigravityConfig | undefined;
+  piConfig: PiConfig | undefined;
 }> {
  const granted = await canUsernameRunPrivilegedCommands(owner);
-  if (granted) return { codexConfig, geminiConfig, antigravityConfig };
+  if (granted) return { codexConfig, geminiConfig, antigravityConfig, piConfig };
  // Non-granted: force codex/antigravity bypass off (only meaningful when a config was
-  // sent) and materialize gemini to auto_edit (clamps an explicit 'yolo' and the yolo default).
+  // sent) and materialize gemini to auto_edit (clamps an explicit 'yolo' and the yolo default)
+  // and pi to --no-approve (clamps an explicit true AND pi's own "ask" default).
  const clampedCodex = codexConfig ? { ...codexConfig, dangerouslyBypassApprovals: false } : codexConfig;
  const clampedGemini: GeminiConfig = { ...(geminiConfig ?? {}), approvalMode: 'auto_edit' };
  const clampedAntigravity = antigravityConfig
    ? { ...antigravityConfig, dangerouslySkipPermissions: false }
    : antigravityConfig;
-  return { codexConfig: clampedCodex, geminiConfig: clampedGemini, antigravityConfig: clampedAntigravity };
+  const clampedPi: PiConfig = { ...(piConfig ?? {}), approveProjectTrust: false };
+  return {
+    codexConfig: clampedCodex,
+    geminiConfig: clampedGemini,
+    antigravityConfig: clampedAntigravity,
+    piConfig: clampedPi,
+  };
 }

+/** Test hook: the clamp is the multi-user safety gate for the external CLIs' privileged flags. */
+export const _clampExternalCliBypassForOwner = clampExternalCliBypassForOwner;
+
 // ═══════════════════════════════════════════════════════════════
 // Agent wait helpers (shared by GET /wait, GET /wait-output, POST /input)
 // ═══════════════════════════════════════════════════════════════
@@ -706,6 +728,7 @@ export function registerSessionRoutes(
      body.mode !== 'codex' &&
      body.mode !== 'gemini' &&
      body.mode !== 'antigravity' &&
+      body.mode !== 'pi' &&
      body.envOverrides &&
      Object.keys(body.envOverrides).length > 0 &&
      (workingDir.startsWith(CASES_DIR + '/') || workingDir.startsWith(managedCasesBase + '/'));
@@ -788,6 +811,15 @@ export function registerSessionRoutes(
        );
      }
    }
+    if (body.mode === 'pi') {
+      const { isPiAvailable } = await import('../../utils/pi-cli-resolver.js');
+      if (!isPiAvailable()) {
+        return createErrorResponse(
+          ApiErrorCode.OPERATION_FAILED,
+          'Pi CLI not found. Install with: npm install -g --ignore-scripts @earendil-works/pi-coding-agent'
+        );
+      }
+    }

    // Pre-validate resumeSessionId: check that the conversation file actually exists
    // in Claude's projects directory. If not, skip resume to avoid confusing
@@ -831,9 +863,11 @@ export function registerSessionRoutes(
            ? body.geminiConfig?.model
            : mode === 'antigravity'
              ? body.antigravityConfig?.model
-              : mode !== 'shell'
-                ? modelConfig?.defaultModel || undefined
-                : undefined;
+              : mode === 'pi'
+                ? body.piConfig?.model
+                : mode !== 'shell'
+                  ? modelConfig?.defaultModel || undefined
+                  : undefined;
    const claudeModeConfig = await ctx.getClaudeModeConfig();
    // Section 6.3: force non-granted users to a classifier-guarded mode.
    const effectiveClaudeMode = await resolveClaudeModeForUsername(claudeModeConfig.claudeMode, owner);
@@ -842,7 +876,14 @@ export function registerSessionRoutes(
      codexConfig: gatedCodexConfig,
      geminiConfig: gatedGeminiConfig,
      antigravityConfig: gatedAntigravityConfig,
-    } = await clampExternalCliBypassForOwner(owner, body.codexConfig, body.geminiConfig, body.antigravityConfig);
+      piConfig: gatedPiConfig,
+    } = await clampExternalCliBypassForOwner(
+      owner,
+      body.codexConfig,
+      body.geminiConfig,
+      body.antigravityConfig,
+      body.piConfig
+    );
    const terminalHistoryConfig = await ctx.getTerminalHistoryConfig();
    const session = new Session({
      workingDir,
@@ -858,6 +899,7 @@ export function registerSessionRoutes(
      codexConfig: mode === 'codex' ? gatedCodexConfig : undefined,
      geminiConfig: mode === 'gemini' ? gatedGeminiConfig : undefined,
      antigravityConfig: mode === 'antigravity' ? gatedAntigravityConfig : undefined,
+      piConfig: mode === 'pi' ? gatedPiConfig : undefined,
      resumeSessionId: validatedResumeId,
      envOverrides: body.envOverrides,
      effort: body.effort,
@@ -2570,6 +2612,7 @@ export function registerSessionRoutes(
      codexConfig,
      geminiConfig,
      antigravityConfig,
+      piConfig,
      envOverrides,
      effort,
      parentSessionId,
@@ -2617,6 +2660,7 @@ export function registerSessionRoutes(
        codexConfig ||
        geminiConfig ||
        antigravityConfig ||
+        piConfig ||
        openCodeConfig
      ) {
        return createErrorResponse(
@@ -2648,6 +2692,7 @@ export function registerSessionRoutes(
        codexConfig ||
        geminiConfig ||
        antigravityConfig ||
+        piConfig ||
        openCodeConfig
      ) {
        return createErrorResponse(
@@ -2751,6 +2796,17 @@ export function registerSessionRoutes(
        }
      }

+      // Check Pi availability if requested
+      if (mode === 'pi') {
+        const { isPiAvailable } = await import('../../utils/pi-cli-resolver.js');
+        if (!isPiAvailable()) {
+          return createErrorResponse(
+            ApiErrorCode.OPERATION_FAILED,
+            'Pi CLI not found. Install with: npm install -g --ignore-scripts @earendil-works/pi-coding-agent'
+          );
+        }
+      }
+
      // Resolve case path: check linked-cases registry first, then fall back to CASES_DIR.
      // This mirrors the behaviour of resolveCasePath() in case-routes so that linked
      // external project directories are honoured by quick-start just like regular case routes.
@@ -2798,7 +2854,7 @@ export function registerSessionRoutes(

        // Write .claude/settings.local.json with hooks for desktop notifications
        // (Claude-specific — OpenCode, Codex, Gemini, and Antigravity use their own systems)
-        if (mode !== 'opencode' && mode !== 'codex' && mode !== 'gemini' && mode !== 'antigravity') {
+        if (mode !== 'opencode' && mode !== 'codex' && mode !== 'gemini' && mode !== 'antigravity' && mode !== 'pi') {
          await writeHooksConfig(resolvedCasePath);
        }

@@ -2833,7 +2889,8 @@ export function registerSessionRoutes(
      mode !== 'opencode' &&
      mode !== 'codex' &&
      mode !== 'gemini' &&
-      mode !== 'antigravity'
+      mode !== 'antigravity' &&
+      mode !== 'pi'
    ) {
      try {
        if (!existsSync(join(resolvedCasePath, 'CLAUDE.md'))) {
@@ -2864,6 +2921,7 @@ export function registerSessionRoutes(
      mode !== 'codex' &&
      mode !== 'gemini' &&
      mode !== 'antigravity' &&
+      mode !== 'pi' &&
      !remote &&
      envOverrides &&
      Object.keys(envOverrides).length > 0
@@ -2884,9 +2942,11 @@ export function registerSessionRoutes(
            ? geminiConfig?.model
            : mode === 'antigravity'
              ? antigravityConfig?.model
-              : mode !== 'shell'
-                ? qsModelConfig?.defaultModel || undefined
-                : undefined;
+              : mode === 'pi'
+                ? piConfig?.model
+                : mode !== 'shell'
+                  ? qsModelConfig?.defaultModel || undefined
+                  : undefined;
    const qsClaudeModeConfig = await ctx.getClaudeModeConfig();
    const qsEffectiveClaudeMode = await resolveClaudeModeForUsername(qsClaudeModeConfig.claudeMode, owner);
    // Section 6.3: clamp Codex/Gemini/Antigravity bypass switches for a non-granted owner (no-op single-user/granted).
@@ -2894,7 +2954,8 @@ export function registerSessionRoutes(
      codexConfig: qsGatedCodexConfig,
      geminiConfig: qsGatedGeminiConfig,
      antigravityConfig: qsGatedAntigravityConfig,
-    } = await clampExternalCliBypassForOwner(owner, codexConfig, geminiConfig, antigravityConfig);
+      piConfig: qsGatedPiConfig,
+    } = await clampExternalCliBypassForOwner(owner, codexConfig, geminiConfig, antigravityConfig, piConfig);
    const qsTerminalHistoryConfig = await ctx.getTerminalHistoryConfig();
    const session = new Session({
      workingDir: resolvedCasePath,
@@ -2911,6 +2972,7 @@ export function registerSessionRoutes(
      codexConfig: mode === 'codex' ? qsGatedCodexConfig : undefined,
      geminiConfig: mode === 'gemini' ? qsGatedGeminiConfig : undefined,
      antigravityConfig: mode === 'antigravity' ? qsGatedAntigravityConfig : undefined,
+      piConfig: mode === 'pi' ? qsGatedPiConfig : undefined,
      envOverrides,
      effort,
      remote,
@@ -374,7 +374,7 @@ export function registerSystemRoutes(
  });

  // ═══════════════════════════════════════════════════════════════
-  // CLI Integrations (Claude, OpenCode, Codex, Gemini, Antigravity)
+  // CLI Integrations (Claude, OpenCode, Codex, Gemini, Antigravity, Pi)
  // ═══════════════════════════════════════════════════════════════

  // ========== Claude ==========
@@ -425,6 +425,21 @@ export function registerSystemRoutes(
    };
  });

+  // ========== Pi ==========
+
+  // Carries `version` on top of the sibling shape: `pi` is a short, generic binary
+  // name, so the resolver sanity-probes `pi --version` and rejects anything that
+  // is not the coding agent. Surfacing path + version makes a misresolution
+  // diagnosable from the UI instead of presenting as "the mode just doesn't work".
+  app.get('/api/pi/status', async () => {
+    const { isPiAvailable, resolvePiDir, getPiCliVersion } = await import('../../utils/pi-cli-resolver.js');
+    return {
+      available: isPiAvailable(),
+      path: resolvePiDir(),
+      version: getPiCliVersion(),
+    };
+  });
+
  // ═══════════════════════════════════════════════════════════════
  // State & Lifecycle (cleanup, lifecycle log, stats)
  // ═══════════════════════════════════════════════════════════════
@@ -122,7 +122,7 @@ export const FileWriteSchema = z
 // ========== Env Var Allowlist ==========

 /** Allowlisted env var key prefixes */
-const ALLOWED_ENV_PREFIXES = ['CLAUDE_CODE_', 'OPENCODE_', 'CODEX_', 'GEMINI_', 'GOOGLE_', 'ANTIGRAVITY_'];
+const ALLOWED_ENV_PREFIXES = ['CLAUDE_CODE_', 'OPENCODE_', 'CODEX_', 'GEMINI_', 'GOOGLE_', 'ANTIGRAVITY_', 'PI_'];

 /**
 * Allowlisted exact env var keys (checked alongside the prefixes).
@@ -161,7 +161,7 @@ const safeEnvOverridesSchema = z
    },
    {
      message:
-        'envOverrides contains blocked or disallowed env var keys. Only CLAUDE_CODE_*, OPENCODE_*, CODEX_*, GEMINI_*, GOOGLE_*, ANTIGRAVITY_* keys and CLAUDE_CONFIG_DIR are allowed.',
+        'envOverrides contains blocked or disallowed env var keys. Only CLAUDE_CODE_*, OPENCODE_*, CODEX_*, GEMINI_*, GOOGLE_*, ANTIGRAVITY_*, PI_* keys and CLAUDE_CONFIG_DIR are allowed.',
    }
  );

@@ -269,6 +269,37 @@ const AntigravityConfigSchema = z
  })
  .optional();

+/**
+ * Schema for Pi CLI (pi.dev)-specific configuration.
+ *
+ * No bypass field exists on purpose: pi has no permission prompts. The one
+ * privilege-shaped knob is the TRI-STATE `approveProjectTrust` (see PiConfig),
+ * which the multi-user clamp MATERIALIZES to `false` for non-granted owners.
+ */
+const PiConfigSchema = z
+  .object({
+    // `:` for a thinking suffix (`sonnet:high`), `/` for `provider/id`.
+    model: z
+      .string()
+      .max(100)
+      .regex(/^[a-zA-Z0-9._\-/:]+$/)
+      .optional(),
+    provider: z
+      .string()
+      .max(50)
+      .regex(/^[a-z0-9-]+$/)
+      .optional(),
+    thinking: z.enum(['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']).optional(),
+    continueSession: z.boolean().optional(),
+    resumeSessionId: z
+      .string()
+      .max(100)
+      .regex(/^[a-zA-Z0-9._-]+$/)
+      .optional(),
+    approveProjectTrust: z.boolean().optional(),
+  })
+  .optional();
+
 /**
 * The session that spawned the one being created — pure UI decoration, drawn as a
 * lineage line between the two tabs. Accepted here and, equivalently, as the
@@ -282,7 +313,7 @@ const parentSessionIdSchema = z.string().max(100).optional();

 export const CreateSessionSchema = z.object({
  workingDir: safePathSchema.optional(),
-  mode: z.enum(['claude', 'shell', 'opencode', 'codex', 'gemini', 'antigravity']).optional(),
+  mode: z.enum(['claude', 'shell', 'opencode', 'codex', 'gemini', 'antigravity', 'pi']).optional(),
  name: z.string().max(100).optional(),
  /** Session that spawned this one — see parentSessionIdSchema. */
  parentSessionId: parentSessionIdSchema,
@@ -297,6 +328,7 @@ export const CreateSessionSchema = z.object({
  codexConfig: CodexConfigSchema,
  geminiConfig: GeminiConfigSchema,
  antigravityConfig: AntigravityConfigSchema,
+  piConfig: PiConfigSchema,
  /** Resume a previous Claude conversation by its session ID (used for reboot recovery) */
  resumeSessionId: z
    .string()
@@ -431,6 +463,7 @@ const RemoteCommandOverridesSchema = z
    codex: z.string().min(1).max(300).optional(),
    gemini: z.string().min(1).max(300).optional(),
    antigravity: z.string().min(1).max(300).optional(),
+    pi: z.string().min(1).max(300).optional(),
  })
  .strict()
  .optional();
@@ -705,11 +738,12 @@ export const QuickStartSchema = z.object({
   *  a real host dir, so the settings file crosses the bind mount); rejected for
   *  remote cases (the file would be written on the WRONG machine). */
  modelOverride: z.string().max(50).optional(),
-  mode: z.enum(['claude', 'shell', 'opencode', 'codex', 'gemini', 'antigravity']).optional(),
+  mode: z.enum(['claude', 'shell', 'opencode', 'codex', 'gemini', 'antigravity', 'pi']).optional(),
  openCodeConfig: OpenCodeConfigSchema,
  codexConfig: CodexConfigSchema,
  geminiConfig: GeminiConfigSchema,
  antigravityConfig: AntigravityConfigSchema,
+  piConfig: PiConfigSchema,
  envOverrides: safeEnvOverridesSchema,
  /** Claude CLI effort level (soft default via --settings, switchable in-session via /effort) */
  effort: effortLevelSchema,
@@ -1211,7 +1245,7 @@ const noNewlines = (v: string) => !/[\r\n]/.test(v);
 /** Shared field shape for creating/updating a scheduled job. */
 const CronJobBaseSchema = z.object({
  name: z.string().min(1).max(200),
-  agentType: z.enum(['claude', 'shell', 'opencode', 'codex', 'gemini', 'antigravity']),
+  agentType: z.enum(['claude', 'shell', 'opencode', 'codex', 'gemini', 'antigravity', 'pi']),
  workingDir: safePathSchema,
  launchCommand: z.string().max(2000).refine(noNewlines, 'launchCommand must be a single line').optional(),
  promptMode: z.enum(['inline_text', 'prompt_file_path']),
@@ -1380,6 +1380,7 @@ export class WebServer extends EventEmitter {
        { isCodexAvailable },
        { isGeminiAvailable },
        { isAntigravityAvailable },
+        { isPiAvailable },
        { isCloudflaredAvailable },
        { isGitAvailable },
      ] = await Promise.all([
@@ -1388,6 +1389,7 @@ export class WebServer extends EventEmitter {
        import('../utils/codex-cli-resolver.js'),
        import('../utils/gemini-cli-resolver.js'),
        import('../utils/antigravity-cli-resolver.js'),
+        import('../utils/pi-cli-resolver.js'),
        import('../utils/cloudflared-resolver.js'),
        import('../git-clone.js'),
      ]);
@@ -1397,6 +1399,7 @@ export class WebServer extends EventEmitter {
        codex: isCodexAvailable(),
        gemini: isGeminiAvailable(),
        antigravity: isAntigravityAvailable(),
+        pi: isPiAvailable(),
        cloudflared: isCloudflaredAvailable(),
        // Not a run mode: the Add Case → Clone tab is an offer this box cannot
        // keep without git (issue #236), same reasoning as cloudflared above.
@@ -2634,6 +2637,7 @@ export class WebServer extends EventEmitter {
              codexConfig: muxSession.mode === 'codex' ? savedState?.codexConfig : undefined,
              geminiConfig: muxSession.mode === 'gemini' ? savedState?.geminiConfig : undefined,
              antigravityConfig: muxSession.mode === 'antigravity' ? savedState?.antigravityConfig : undefined,
+              piConfig: muxSession.mode === 'pi' ? savedState?.piConfig : undefined,
              envOverrides: savedEnvOverrides,
              effort: savedState?.effort,
              attachmentHistory: savedAttachmentHistory,