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>

src/web/public/app.js

@@ -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');

src/web/public/i18n.js

@@ -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': '新建案例',

src/web/public/index.html

@@ -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>

src/web/public/mobile-overview.js

@@ -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' },
 ];
 

src/web/public/mobile.css

@@ -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;
 }

src/web/public/panels-ui.js

@@ -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',

src/web/public/session-ui.js

@@ -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';
   },

src/web/public/settings-ui.js

@@ -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'],

src/web/public/styles.css

@@ -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);

src/web/public/terminal-ui.js

@@ -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) {