@juicesharp/rpiv-warp 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+All notable changes to `@juicesharp/rpiv-warp` are documented here.
+
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versioning: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.3.0] - 2026-05-08
+
+### Changed
+- Package is now published to npm (previously `private: true`). The title-spinner module is included in the tarball.
+
+## [1.2.1] - 2026-05-07
+
+## [1.2.0] - 2026-05-07
+
+## [1.1.5] - 2026-05-05
+
+## [1.1.4] - 2026-05-03
+
+## [1.1.3] - 2026-05-03
+
+## [1.1.2] - 2026-05-03
+
+## [1.1.1] - 2026-05-03
+
+## [1.1.0] - 2026-05-03
+
+## [1.0.19] - 2026-05-03
+
+### Added
+- README `Features` section listing customer-facing functionality: native OS toasts on Pi lifecycle events, live Warp tab badge, tab-title spinner, configurable blocking-tool allowlist, startup-only session notifications, silent-outside-Warp behavior, best-effort Windows support, and zero-tool footprint.
+
+### Changed
+- **Now publicly published on npm.** `package.json` no longer carries `"private": true`, so workspace publishes pick `@juicesharp/rpiv-warp` up alongside the rest of the family. Install with `pi install npm:@juicesharp/rpiv-warp`. The package is still opt-in: it is intentionally absent from `siblings.ts` and is NOT auto-installed by `/rpiv-setup`.
+
+## [1.0.18] - 2026-05-02
+
+## [1.0.17] - 2026-05-02
+
+## [1.0.16] - 2026-05-02
+
+## [1.0.15] - 2026-05-02
+
+## [1.0.14] - 2026-05-01
+
+### Changed
+- Cover redesigned as a macOS-style terminal-window screenshot demonstrating the extension's hero feature.
+
+## [1.0.13] - 2026-05-01
+
+### Added
+- `docs/vertical-cover.{svg,png}` — portrait-orientation hero artwork (1280×800 canvas; PNG downscaled to 320×711).
+- Best-effort Windows transport: `writeOSC777` writes the OSC 777 byte sequence to `process.stdout` (gated on `isTTY`) when `/dev/tty` is unavailable, relying on ConPTY to forward unrecognized OSCs to Warp.
+- Warp tab-title spinner: animates the first character of the terminal window title with a 4-frame braille rotation at 160ms cadence during agent loops, wrapped in xterm `CSI 22;0t` / `CSI 23;0t` push/pop so Pi's `π - <repo>` title is restored verbatim on stop.
+- `title-spinner.ts` module plus `writeOSC0`, `pushTitleStack`, `popTitleStack` emitters that share `writeOSC777`’s transport path (so they also flow through `process.stdout` on Windows).
+- Test coverage for the title-spinner emitters on Windows transport.
+
+### Changed
+- Cover canvas extended from 1280×640 to 1280×800 with refreshed crop marks/footer.
+- README hero swapped from `docs/cover.png` to `docs/vertical-cover.png`, rendered at `width="160"`. The `<a>` wrapper around the `<picture>` was removed so the image is no longer a clickable link to the package directory.
+- README edge-case table updated to flag the Windows transport as untested in the wild.
+- Internal: renamed "OSC byte sequence" section to "Escape-sequence constants" to cover the new CSI additions; split formatters into their own section to mirror `payload.ts`’s Constants → Builders separation; restated the 160ms frame cadence in module headers.
+
+## [1.0.12] - 2026-05-01
+
+### Added
+- `docs/cover.png` — package hero (rasterized from `docs/cover.svg` via `rsvg-convert`, 1280×640).
+- `session_start` payload emission on `agent_start` so Warp learns the project context at agent boot, before any tool call.
+- Client-side protocol-version negotiation: parse `WARP_CLI_AGENT_PROTOCOL_VERSION` and gate emission on the negotiated version, replacing the prior hard-coded broken-build check.
+- Config-driven blocking-tool flow: subscribes to `question_asked` / `tool_complete`, drives the OSC 777 envelope from a per-tool config table instead of the inline `NOTIFY_TOOL_NAMES` allowlist. Adds `ask_user_question` as the initial blocking-tool entry.
+
+### Changed
+- README now opens with a `<picture>`-wrapped `cover.png` hero so GitHub renders friendly artwork at the top of the package page.
+- `package.json` now carries `"private": true` to gate npm publish — the package joins lockstep + shared CI infrastructure but does not publish until explicitly opted in.
+- Agent-start emission switched from `session_start` to `prompt_submit` so Warp's UI cues fire on user-prompt cadence rather than session boot.
+
+## [1.0.11] - 2026-04-30
+
+### Added
+- Initial release. New standalone Pi extension that subscribes to four Pi lifecycle events (`session_start`, `agent_end`, `tool_call`, `turn_end`) and emits Warp's structured `OSC 777` escape sequence to `/dev/tty` so Warp renders native OS-level toast notifications. Filters `session_start` to `reason === "startup"` only, and `tool_call` to a configurable `NOTIFY_TOOL_NAMES` set (initial entry: `ask_user_question`). Detects Warp via `TERM_PROGRAM === "WarpTerminal"` plus `WARP_CLI_AGENT_PROTOCOL_VERSION`; falls back to silent no-op outside Warp, on broken Warp builds (per-channel hard-coded thresholds), or when `/dev/tty` is unreachable. Standalone — not registered as a sibling, not auto-installed by `/rpiv-setup`. Install via `pi install npm:@juicesharp/rpiv-warp`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 juicesharp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,87 @@
+# rpiv-warp
+
+<div align="center">
+  <a href="https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-warp">
+    <picture>
+      <img src="https://raw.githubusercontent.com/juicesharp/rpiv-mono/main/packages/rpiv-warp/docs/cover.png" alt="rpiv-warp cover" width="50%">
+    </picture>
+  </a>
+</div>
+
+[![npm version](https://img.shields.io/npm/v/@juicesharp/rpiv-warp.svg)](https://www.npmjs.com/package/@juicesharp/rpiv-warp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Native [Warp terminal](https://www.warp.dev/) toasts for [Pi Agent](https://github.com/badlogic/pi-mono) lifecycle events. When Pi finishes a long task, asks for your input, or completes a turn, `rpiv-warp` emits Warp's `OSC 777` escape sequence and Warp surfaces a native OS notification. Outside Warp it does nothing - install it everywhere, it only fires where it's useful.
+
+## Features
+
+- **Native OS toasts on Pi lifecycle events** - agent start, agent end, blocking-tool calls, and turn boundaries surface as native Warp / macOS / Windows notifications.
+- **Live Warp tab badge** - the tab indicator transitions through **In progress → Success / Blocked** as Pi works.
+- **Tab-title spinner** - animates the tab title while the agent loop is active and restores Pi's `π - <repo>` title on stop.
+- **Configurable blocking-tool allowlist** - choose which tool calls flip the badge to **Blocked** via `~/.config/rpiv-warp/config.json`. Defaults to `ask_user_question`.
+- **Startup-only session notifications** - `/new`, `/resume`, `/fork`, and `/reload` stay quiet; only fresh startups notify.
+- **Silent outside Warp** - no-op when not running in Warp, on known-broken Warp builds, or when `/dev/tty` is unreachable.
+- **Windows support** - best-effort delivery via `process.stdout` / ConPTY, gated on `isTTY`.
+- **Zero-tool, zero-UI footprint** - no tools registered with the model, no commands, no widgets, no token cost.
+
+## Install
+
+```bash
+pi install npm:@juicesharp/rpiv-warp
+```
+
+`rpiv-warp` is **opt-in** - it is NOT auto-installed by `/rpiv-setup`. Install it explicitly only if you use Warp.
+
+## What you get
+
+| Pi event | Warp wire event | Effect on the tab badge |
+|---|---|---|
+| `session_start` (startup only) | `session_start` | records plugin version |
+| `agent_start` | `prompt_submit` | → **In progress** |
+| `agent_end` | `stop` | → **Success** (checkmark) |
+| `tool_call` (configured blocking tool) | `question_asked` | → **Blocked** ("Waiting for your answer") |
+| `tool_execution_end` (configured blocking tool) | `tool_complete` | Blocked → **In progress** |
+
+`session_start` is filtered to `reason === "startup"` only - `/new`, `/resume`, `/fork`, `/reload` do NOT emit (you're already looking at the terminal in those cases).
+
+## Config
+
+Optional file at `~/.config/rpiv-warp/config.json`:
+
+```json
+{
+  "blockingTools": ["ask_user_question", "my_custom_blocking_tool"]
+}
+```
+
+| Key | Default | Meaning |
+|---|---|---|
+| `blockingTools` | `["ask_user_question"]` | Tool names that put the Warp tab badge into the **Blocked** state when called and clear it when the tool finishes. Use for tools that genuinely block the agent loop on user input. |
+
+Missing or malformed file falls back to defaults - no config required.
+
+## Detection
+
+`rpiv-warp` reads three environment variables Warp sets automatically:
+
+- `TERM_PROGRAM === "WarpTerminal"` - required. Outside Warp the extension is a no-op.
+- `WARP_CLI_AGENT_PROTOCOL_VERSION` - required for structured emission. If unset, `rpiv-warp` does nothing rather than falling back to a less-rich legacy format.
+- `WARP_CLIENT_VERSION` - used for broken-version gating. A short list of known-broken Warp builds (per release channel) suppresses emission until Warp ships a fix.
+
+## Edge cases
+
+| Case | Behavior |
+|---|---|
+| Not in Warp (`TERM_PROGRAM !== "WarpTerminal"`) | Silent no-op - extension loads, every handler short-circuits |
+| Pi in print mode (`pi -p "..."`) | **Toasts still fire** - print mode emits all four events at the agent layer |
+| `/dev/tty` unreachable (cron, no-tty SSH) | Silent no-op - `try/catch` around `openSync` |
+| Windows | Best-effort - writes OSC 777 to `process.stdout` so ConPTY forwards it to Warp ([Warp eng blog: "ConPTY will send even unrecognized OSCs to the shell"](https://www.warp.dev/blog/building-warp-on-windows)). Skipped when stdout is not a TTY (piped/redirected output). Untested in the wild - no Warp plugin currently ships a Windows transport |
+| Known-broken Warp build | Silent no-op - broken-version table gates emission per channel |
+
+## Why standalone (not a sibling)
+
+`rpiv-warp` is intentionally NOT registered in `rpiv-pi`'s sibling list. Not every Pi user uses Warp - auto-installing it everywhere would impose Warp-specific code on every install. If you don't use Warp, don't install it. If you do, install it explicitly. The package still joins the rpiv-mono lockstep version + shared release pipeline.
+
+## License
+
+MIT - see [LICENSE](./LICENSE).

package/config.ts

@@ -0,0 +1,30 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const CONFIG_DIR = join(homedir(), ".config", "rpiv-warp");
+export const CONFIG_PATH = join(CONFIG_DIR, "config.json");
+
+export interface RpivWarpConfig {
+	readonly blockingTools?: readonly string[];
+}
+
+export const DEFAULT_BLOCKING_TOOLS: readonly string[] = ["ask_user_question"];
+
+export function loadConfig(): RpivWarpConfig {
+	if (!existsSync(CONFIG_PATH)) return {};
+	try {
+		const parsed = JSON.parse(readFileSync(CONFIG_PATH, "utf-8")) as unknown;
+		if (parsed === null || typeof parsed !== "object") return {};
+		return parsed as RpivWarpConfig;
+	} catch {
+		return {};
+	}
+}
+
+export function getBlockingTools(): ReadonlySet<string> {
+	const config = loadConfig();
+	const list = Array.isArray(config.blockingTools) ? config.blockingTools : DEFAULT_BLOCKING_TOOLS;
+	const filtered = list.filter((s): s is string => typeof s === "string" && s.length > 0);
+	return new Set(filtered);
+}

package/index.ts

@@ -0,0 +1,66 @@
+import { basename } from "node:path";
+import type { ExtensionAPI, ExtensionContext, SessionEntry } from "@earendil-works/pi-coding-agent";
+import { getBlockingTools } from "./config.js";
+import {
+	buildPromptSubmitPayload,
+	buildQuestionAskedPayload,
+	buildSessionStartPayload,
+	buildStopPayload,
+	buildToolCompletePayload,
+	serializePayload,
+	type WarpPayload,
+} from "./payload.js";
+import { detectWarpEnvironment } from "./protocol.js";
+import { startSpinner, stopSpinner } from "./title-spinner.js";
+import { writeOSC777 } from "./warp-notify.js";
+
+const TITLE = "warp://cli-agent";
+
+function emit(payload: WarpPayload): void {
+	writeOSC777(TITLE, serializePayload(payload));
+}
+
+function readBranch(ctx: ExtensionContext): SessionEntry[] {
+	return ctx.sessionManager.getBranch() as SessionEntry[];
+}
+
+// Mirror Pi's startup tab title `<mascot> - <repo>`. We only own the first
+// character (the spinner glyph during animation); push/pop restores Pi's
+// mascot verbatim on stop.
+function titleSuffix(ctx: ExtensionContext): string {
+	return ` - ${basename(ctx.cwd)}`;
+}
+
+export default function (pi: ExtensionAPI): void {
+	const warp = detectWarpEnvironment();
+	if (!warp.isWarp || !warp.supportsStructured) return;
+
+	const blockingTools = getBlockingTools();
+
+	pi.on("session_start", async (event, ctx) => {
+		if (event.reason !== "startup") return;
+		emit(buildSessionStartPayload(ctx));
+	});
+
+	pi.on("agent_start", async (_event, ctx) => {
+		emit(buildPromptSubmitPayload(ctx));
+		startSpinner(titleSuffix(ctx));
+	});
+
+	pi.on("agent_end", async (_event, ctx) => {
+		emit(buildStopPayload(ctx, readBranch(ctx)));
+		stopSpinner();
+	});
+
+	pi.on("tool_call", async (event, ctx) => {
+		if (!blockingTools.has(event.toolName)) return;
+		emit(buildQuestionAskedPayload(ctx));
+		stopSpinner();
+	});
+
+	pi.on("tool_execution_end", async (event, ctx) => {
+		if (!blockingTools.has(event.toolName)) return;
+		emit(buildToolCompletePayload(ctx, event.toolName));
+		startSpinner(titleSuffix(ctx));
+	});
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+	"name": "@juicesharp/rpiv-warp",
+	"version": "1.3.0",
+	"private": false,
+	"description": "Pi extension. Native Warp terminal notifications, dispatched via OSC 777 on Pi lifecycle events.",
+	"keywords": [
+		"pi-package",
+		"pi-extension",
+		"rpiv",
+		"warp",
+		"terminal",
+		"notifications",
+		"osc-777"
+	],
+	"type": "module",
+	"license": "MIT",
+	"author": "juicesharp",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/juicesharp/rpiv-mono.git",
+		"directory": "packages/rpiv-warp"
+	},
+	"homepage": "https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-warp#readme",
+	"bugs": {
+		"url": "https://github.com/juicesharp/rpiv-mono/issues"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"test": "vitest run"
+	},
+	"files": [
+		"index.ts",
+		"protocol.ts",
+		"warp-notify.ts",
+		"title-spinner.ts",
+		"payload.ts",
+		"config.ts",
+		"README.md",
+		"CHANGELOG.md",
+		"LICENSE"
+	],
+	"pi": {
+		"extensions": [
+			"./index.ts"
+		]
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*"
+	}
+}

package/payload.ts

@@ -0,0 +1,180 @@
+/**
+ * rpiv-warp — Warp structured-payload composition.
+ *
+ * Pure data transforms: branch -> text extraction -> envelope -> JSON.
+ * No I/O. One small named function per concern; build* composers assemble
+ * them at the call sites consumed by `index.ts`.
+ */
+
+import { basename } from "node:path";
+import type { AssistantMessage, UserMessage } from "@earendil-works/pi-ai";
+import type { ExtensionContext, SessionEntry } from "@earendil-works/pi-coding-agent";
+import { negotiateProtocolVersion, type WarpEvent } from "./protocol.js";
+
+// ---------------------------------------------------------------------------
+// Constants — single definition site for tunables
+// ---------------------------------------------------------------------------
+
+/**
+ * Warp's `CLIAgent` enum recognizes 12 IDs (warpdotdev/warp:
+ * `app/src/terminal/cli_agent.rs`), and `"pi"` is one of them — semantically
+ * correct identity for this extension. However, the session listener at
+ * `app/src/terminal/cli_agent_sessions/listener/mod.rs:48-57` currently routes
+ * only `Claude | OpenCode | Gemini | Auggie | Codex` to a notification handler
+ * and drops every other variant (including `Pi` and `Unknown`). So `"pi"`
+ * parses correctly but produces no toast in current Warp builds.
+ *
+ * Workaround options, all bad:
+ *   - `agent: "claude"` → toasts render, but tab gets the Claude Code icon &
+ *     "Claude" label via `SessionType::CliAgent(CLIAgent::Claude)`. Identity-
+ *     misrepresenting; user-visibly wrong.
+ *   - any non-allowlisted ID → no toast.
+ *
+ * Real fix is upstream: PR `warpdotdev/warp` moving `CLIAgent::Pi` into the
+ * `DefaultSessionListener` arm + adding `icon()` / `brand_color()` cases
+ * (template: `specs/APP-4067/TECH.md` did this for Gemini). Until that ships,
+ * we keep the correct identity and accept that Warp won't render the toast.
+ */
+export const AGENT_ID = "pi";
+export const TRUNCATE_LIMIT = 200;
+
+// ---------------------------------------------------------------------------
+// Types — base envelope + per-event extras
+// ---------------------------------------------------------------------------
+
+export interface WarpPayloadBase {
+	readonly v: number;
+	readonly agent: string;
+	readonly event: WarpEvent;
+	readonly session_id: string;
+	readonly cwd: string;
+	readonly project: string;
+}
+
+export interface StopExtras {
+	readonly query: string;
+	readonly response: string;
+}
+export interface IdlePromptExtras {
+	readonly summary: string;
+}
+export interface ToolCompleteExtras {
+	readonly tool_name: string;
+}
+
+export type WarpPayload = WarpPayloadBase & Partial<StopExtras & IdlePromptExtras & ToolCompleteExtras>;
+
+// ---------------------------------------------------------------------------
+// Text helpers — small, single-purpose, composable
+// ---------------------------------------------------------------------------
+
+export function truncate(s: string, max: number = TRUNCATE_LIMIT): string {
+	if (s.length <= max) return s;
+	return `${s.slice(0, max - 3)}...`;
+}
+
+export function projectName(cwd: string): string {
+	return basename(cwd);
+}
+
+/**
+ * Extract plain text from a UserMessage.content (string | array) OR an
+ * AssistantMessage.content (always array). Filters to TextContent entries.
+ */
+export function extractMessageText(content: UserMessage["content"] | AssistantMessage["content"]): string {
+	if (typeof content === "string") return content;
+	return content
+		.filter((c): c is { type: "text"; text: string } => c.type === "text")
+		.map((c) => c.text)
+		.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Branch traversal — reverse-scan filtered branch for last user/assistant text
+// ---------------------------------------------------------------------------
+
+function isMessageEntry(entry: SessionEntry): entry is SessionEntry & { type: "message" } {
+	return entry.type === "message";
+}
+
+function findLastMessageText(branch: SessionEntry[], role: "user" | "assistant"): string {
+	for (let i = branch.length - 1; i >= 0; i--) {
+		const entry = branch[i];
+		if (!isMessageEntry(entry)) continue;
+		const message = entry.message;
+		if (message.role !== role) continue;
+		const text = extractMessageText((message as UserMessage | AssistantMessage).content);
+		if (text.length > 0) return truncate(text);
+	}
+	return "";
+}
+
+export function lastUserText(branch: SessionEntry[]): string {
+	return findLastMessageText(branch, "user");
+}
+
+export function lastAssistantText(branch: SessionEntry[]): string {
+	return findLastMessageText(branch, "assistant");
+}
+
+// ---------------------------------------------------------------------------
+// Envelope — common fields for every Warp event
+// ---------------------------------------------------------------------------
+
+export function baseEnvelope(event: WarpEvent, ctx: ExtensionContext): WarpPayloadBase {
+	const cwd = ctx.cwd;
+	return {
+		v: negotiateProtocolVersion(),
+		agent: AGENT_ID,
+		event,
+		session_id: ctx.sessionManager.getSessionId(),
+		cwd,
+		project: projectName(cwd),
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Builders — one per Warp event; composition is linear and named
+// ---------------------------------------------------------------------------
+
+export function buildSessionStartPayload(ctx: ExtensionContext): WarpPayload {
+	return baseEnvelope("session_start", ctx);
+}
+
+export function buildPromptSubmitPayload(ctx: ExtensionContext): WarpPayload {
+	return baseEnvelope("prompt_submit", ctx);
+}
+
+export function buildQuestionAskedPayload(ctx: ExtensionContext): WarpPayload {
+	return baseEnvelope("question_asked", ctx);
+}
+
+export function buildStopPayload(ctx: ExtensionContext, branch: SessionEntry[]): WarpPayload {
+	return {
+		...baseEnvelope("stop", ctx),
+		query: lastUserText(branch),
+		response: lastAssistantText(branch),
+	};
+}
+
+export function buildIdlePromptPayload(ctx: ExtensionContext, summary: string): WarpPayload {
+	return {
+		...baseEnvelope("idle_prompt", ctx),
+		summary,
+	};
+}
+
+export function buildToolCompletePayload(ctx: ExtensionContext, toolName: string): WarpPayload {
+	return {
+		...baseEnvelope("tool_complete", ctx),
+		tool_name: toolName,
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Serializer — single source of truth so tests can assert on JSON shape
+// ---------------------------------------------------------------------------
+
+export function serializePayload(payload: WarpPayload): string {
+	return JSON.stringify(payload);
+}

package/protocol.ts

@@ -0,0 +1,151 @@
+/**
+ * rpiv-warp — Warp terminal detection + protocol negotiation.
+ *
+ * Pure functions only. No module-level mutable state. Each function does
+ * one thing; `detectWarpEnvironment` is the composition site.
+ *
+ * Env vars consulted (read fresh on every call — no cache):
+ *   TERM_PROGRAM                       — must be "WarpTerminal"
+ *   WARP_CLI_AGENT_PROTOCOL_VERSION    — required for structured emission
+ *   WARP_CLIENT_VERSION                — used for per-channel broken-version gating
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Structured event names emitted in the OSC 777 payload's `event` field. */
+export type WarpEvent = "session_start" | "prompt_submit" | "stop" | "question_asked" | "tool_complete" | "idle_prompt";
+
+/** Warp release channel — present in every `WARP_CLIENT_VERSION` literal. */
+export type Channel = "stable" | "preview" | "dev";
+
+/** Parsed version components: [year, month, day, hour, minute, rev, seq]. */
+export type VersionTuple = readonly [number, number, number, number, number, number, number];
+
+export interface ParsedWarpVersion {
+	readonly tuple: VersionTuple;
+	readonly channel: Channel;
+}
+
+export interface WarpEnvironment {
+	readonly isWarp: boolean;
+	readonly supportsStructured: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Highest protocol version this plugin can speak. The plugin clamps
+ * client-side via `negotiateProtocolVersion()` and emits the agreed `v`
+ * in every payload, so an older Warp that only speaks v:1 keeps seeing v:1
+ * even after we bump this constant.
+ */
+export const PLUGIN_MAX_PROTOCOL_VERSION = 1;
+
+/**
+ * Last broken Warp build per channel. Builds at-or-below the threshold
+ * advertise structured-protocol support but render notifications behind a
+ * feature flag — gate them off until users upgrade.
+ */
+export const BROKEN_VERSIONS: Record<Channel, VersionTuple | null> = {
+	stable: [2026, 3, 25, 8, 24, 5, 5],
+	preview: [2026, 3, 25, 8, 24, 5, 5],
+	dev: null,
+};
+
+const VERSION_RE = /^v0\.(\d{4})\.(\d{1,2})\.(\d{1,2})\.(\d{1,2})\.(\d{1,2})\.(stable|preview|dev)_(\d+)$/;
+
+// ---------------------------------------------------------------------------
+// Env-var primitives — each reads exactly one variable
+// ---------------------------------------------------------------------------
+
+export function isWarpTerminal(): boolean {
+	return process.env.TERM_PROGRAM === "WarpTerminal";
+}
+
+export function hasStructuredProtocol(): boolean {
+	const v = process.env.WARP_CLI_AGENT_PROTOCOL_VERSION;
+	return typeof v === "string" && v.length > 0;
+}
+
+export function readClientVersion(): string | undefined {
+	const v = process.env.WARP_CLIENT_VERSION;
+	return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+
+/**
+ * Client-side protocol-version clamp.
+ *
+ * Returns min(WARP_CLI_AGENT_PROTOCOL_VERSION, PLUGIN_MAX_PROTOCOL_VERSION).
+ * Falls back to PLUGIN_MAX_PROTOCOL_VERSION when the env var is missing,
+ * empty, or unparseable — matches reference (warpdotdev/opencode-warp
+ * src/payload.ts).
+ *
+ * Pure: env-var reads on every call, no caching, safe under env mutation
+ * in tests (research §Q5 contract).
+ */
+export function negotiateProtocolVersion(): number {
+	const raw = process.env.WARP_CLI_AGENT_PROTOCOL_VERSION;
+	const warpVersion = raw ? Number.parseInt(raw, 10) : Number.NaN;
+	if (Number.isNaN(warpVersion)) return PLUGIN_MAX_PROTOCOL_VERSION;
+	return Math.min(warpVersion, PLUGIN_MAX_PROTOCOL_VERSION);
+}
+
+// ---------------------------------------------------------------------------
+// Version parsing — pure, regex-driven
+// ---------------------------------------------------------------------------
+
+export function parseWarpVersion(raw: string | undefined): ParsedWarpVersion | null {
+	if (!raw) return null;
+	const m = VERSION_RE.exec(raw);
+	if (!m) return null;
+	const tuple: VersionTuple = [
+		Number(m[1]),
+		Number(m[2]),
+		Number(m[3]),
+		Number(m[4]),
+		Number(m[5]),
+		Number(m[7]),
+		Number(m[7]),
+	];
+	return { tuple, channel: m[6] as Channel };
+}
+
+/** Element-wise `≤` over fixed-length tuples. Returns true on equal. */
+export function tupleLeq(a: VersionTuple, b: VersionTuple): boolean {
+	for (let i = 0; i < a.length; i++) {
+		if (a[i] < b[i]) return true;
+		if (a[i] > b[i]) return false;
+	}
+	return true;
+}
+
+// ---------------------------------------------------------------------------
+// Broken-version gate
+// ---------------------------------------------------------------------------
+
+export function isBrokenVersion(parsed: ParsedWarpVersion | null): boolean {
+	if (!parsed) return false;
+	const threshold = BROKEN_VERSIONS[parsed.channel];
+	if (threshold === null) return false;
+	return tupleLeq(parsed.tuple, threshold);
+}
+
+// ---------------------------------------------------------------------------
+// Composition — one assembly site for the structured-mode predicate
+// ---------------------------------------------------------------------------
+
+export function supportsStructured(): boolean {
+	if (!hasStructuredProtocol()) return false;
+	const parsed = parseWarpVersion(readClientVersion());
+	return !isBrokenVersion(parsed);
+}
+
+export function detectWarpEnvironment(): WarpEnvironment {
+	const isWarp = isWarpTerminal();
+	if (!isWarp) return { isWarp: false, supportsStructured: false };
+	return { isWarp: true, supportsStructured: supportsStructured() };
+}

package/title-spinner.ts

@@ -0,0 +1,116 @@
+/**
+ * rpiv-warp — Tab-title activity spinner.
+ *
+ * Warp's per-tab "moving dots" animation is NOT part of the OSC 777
+ * cli-agent protocol (research: agent: "claude" payloads with the full
+ * OSC 777 lifecycle still produce no animation). It's a side effect of
+ * the foreground process continuously rewriting its terminal title via
+ * OSC 0 (`\x1b]0;<title>\x07`). Claude Code drives this by ticking
+ * braille glyphs through the title every ~80ms while a request is in
+ * flight (anthropics/claude-code#17887). Same mechanism animates
+ * activity indicators in iTerm2, Ghostty, tmux, Windows Terminal —
+ * terminal-side, not Warp-specific. Both reference plugins
+ * (warpdotdev/claude-code-warp, warpdotdev/opencode-warp) emit ONLY OSC 777
+ * — no spinner — confirming the dots originate in the agent process.
+ *
+ * Title-preservation strategy: the original Warp tab title (e.g.
+ * `π - rpiv-mono`, set by Pi at startup) MUST survive the animation
+ * round trip — and during the animation, only the FIRST character (the
+ * Pi mascot) is swapped for the rotating glyph; the suffix (` - <repo>`)
+ * stays put.
+ *
+ *   on agent_start(suffix)        → CSI 22;0t     (push current title)
+ *   while running, every 160ms    → OSC 0         (write `<glyph><suffix>`)
+ *   on agent_end                  → CSI 23;0t     (pop — original restored)
+ *
+ * The suffix is supplied by callers in `index.ts` from `ctx.cwd`
+ * (` - ${basename(cwd)}`); on a stop, push/pop restores whatever the
+ * terminal had before — typically Pi's `π${suffix}`. Push/pop is
+ * supported by Warp, iTerm2, Ghostty, tmux, Linux console; terminals
+ * that don't implement it ignore the CSI silently.
+ *
+ * Module state: a single in-flight ticker. `startSpinner`/`stopSpinner`
+ * are idempotent — overlapping calls within one agent loop are safe.
+ * Timer is `unref()`d so a stray interval cannot block process exit.
+ * `__resetState` is the test-cleanup contract (timer-only; no I/O so
+ * the per-test fs mock isn't polluted with a stray pop sequence);
+ * `test/setup.ts` invokes it in `beforeEach`.
+ */
+
+import { popTitleStack, pushTitleStack, writeOSC0 } from "./warp-notify.js";
+
+// ---------------------------------------------------------------------------
+// Constants — tunable at one site
+// ---------------------------------------------------------------------------
+
+/**
+ * 2×2-dot rotation, inverted: three of four dots in the cell's middle
+ * sub-grid (dots 2,5,3,6) stay lit, one rotates as a moving "gap"
+ * clockwise from top-left → top-right → bottom-right → bottom-left.
+ *
+ *   ⠴   ⠦   ⠖   ⠲      (gap at TL, TR, BR, BL)
+ *
+ * Reads as a 3-dot cluster with a hole spinning around it. All four
+ * frames share the same monospace width, so the title suffix doesn't
+ * shimmer (vs Claude Code's variable-width `⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏`,
+ * anthropics/claude-code#17887).
+ *
+ * At FRAME_INTERVAL_MS = 160, the 4-frame cycle completes every ~640ms
+ * (~1.5 Hz) — relaxed pulse, deliberately slower than typical CLI
+ * spinners (80–100ms) so the tab indicator reads as ambient activity
+ * rather than urgency.
+ */
+export const SPINNER_FRAMES: readonly string[] = ["⠴", "⠦", "⠖", "⠲"];
+
+/** Tick rate — slower than typical CLI spinners (~80ms); reads as ambient. */
+export const FRAME_INTERVAL_MS = 160;
+
+// ---------------------------------------------------------------------------
+// Pure formatter — no I/O
+// ---------------------------------------------------------------------------
+
+export function activeTitle(frameIndex: number, suffix: string = ""): string {
+	return `${SPINNER_FRAMES[frameIndex % SPINNER_FRAMES.length]}${suffix}`;
+}
+
+// ---------------------------------------------------------------------------
+// Module state — one ticker at a time; idempotent start/stop
+// ---------------------------------------------------------------------------
+
+interface Ticker {
+	timer: ReturnType<typeof setInterval>;
+	frame: number;
+	suffix: string;
+}
+
+let active: Ticker | undefined;
+
+function tick(): void {
+	if (!active) return;
+	writeOSC0(activeTitle(active.frame, active.suffix));
+	active.frame = (active.frame + 1) % SPINNER_FRAMES.length;
+}
+
+// ---------------------------------------------------------------------------
+// Public API — wired from index.ts agent-loop boundaries
+// ---------------------------------------------------------------------------
+
+export function startSpinner(suffix: string = ""): void {
+	if (active) return;
+	pushTitleStack();
+	const timer = setInterval(tick, FRAME_INTERVAL_MS);
+	if (typeof timer.unref === "function") timer.unref();
+	active = { timer, frame: 0, suffix };
+}
+
+export function stopSpinner(): void {
+	if (!active) return;
+	clearInterval(active.timer);
+	active = undefined;
+	popTitleStack();
+}
+
+export function __resetState(): void {
+	if (active) clearInterval(active.timer);
+	active = undefined;
+}

package/warp-notify.ts

@@ -0,0 +1,146 @@
+/**
+ * rpiv-warp — OSC transport.
+ *
+ * Writes Warp's OSC escape sequences to the controlling terminal. On Unix
+ * this is `/dev/tty`; on Windows there is no `/dev/tty`, so we write the
+ * same OSC bytes to `process.stdout` and rely on ConPTY to forward them
+ * to Warp (per Warp's "Bringing Warp to Windows" eng blog: "ConPTY will
+ * send even unrecognized OSCs to the shell").
+ *
+ * Two OSC sequences and two CSI sequences are emitted from this module:
+ *   - OSC 777 — Warp's structured cli-agent notification (badge state +
+ *     toast). Single emission per lifecycle event; see `index.ts`.
+ *   - OSC 0  — terminal title set. Driven from `title-spinner.ts` every
+ *     160ms to animate Warp's per-tab activity dots; same mechanism
+ *     Claude Code uses (anthropics/claude-code#17887).
+ *   - CSI 22;0t / CSI 23;0t — xterm window-title stack push/pop. Used
+ *     by `title-spinner.ts` to snapshot Warp's existing tab title before
+ *     the animation starts and restore it verbatim on stop, so the
+ *     `π - <repo>` label Pi sets at startup survives the spinner round
+ *     trip.
+ *
+ * Each call on Unix opens, writes, and closes the fd — no fd cache
+ * (matches bash precedent: warp-notify.sh:21). Windows writes go straight
+ * through `process.stdout.write` — best-effort, untested in the wild as
+ * no Warp plugin currently ships a Windows transport.
+ *
+ * Tests intercept fs calls via `vi.mock("node:fs", ...)` — the same
+ * pattern used in `packages/rpiv-pi/extensions/rpiv-core/pi-installer.test.ts:4`
+ * for `node:child_process`. Production uses `import * as fs from "node:fs"`
+ * for clarity (every fs call is namespace-prefixed).
+ */
+
+import * as fs from "node:fs";
+
+// ---------------------------------------------------------------------------
+// Escape-sequence constants — exported so tests assert against the same bytes
+// ---------------------------------------------------------------------------
+
+export const OSC_INTRODUCER = "\x1b]";
+export const OSC_TERMINATOR = "\x07";
+export const OSC_777_PREFIX = "777;notify";
+export const OSC_0_PREFIX = "0";
+
+export const CSI_INTRODUCER = "\x1b[";
+/** Push window+icon titles onto xterm's title stack (Ps=0 → both). */
+export const CSI_PUSH_TITLE = "22;0t";
+/** Pop and restore window+icon titles from xterm's title stack (Ps=0 → both). */
+export const CSI_POP_TITLE = "23;0t";
+
+const TTY_PATH = "/dev/tty";
+
+// ---------------------------------------------------------------------------
+// Pure formatters — one per shape; no I/O
+// ---------------------------------------------------------------------------
+
+export function formatOSC777(title: string, body: string): string {
+	return `${OSC_INTRODUCER}${OSC_777_PREFIX};${title};${body}${OSC_TERMINATOR}`;
+}
+
+export function formatOSC0(title: string): string {
+	return `${OSC_INTRODUCER}${OSC_0_PREFIX};${title}${OSC_TERMINATOR}`;
+}
+
+export function formatPushTitleStack(): string {
+	return `${CSI_INTRODUCER}${CSI_PUSH_TITLE}`;
+}
+
+export function formatPopTitleStack(): string {
+	return `${CSI_INTRODUCER}${CSI_POP_TITLE}`;
+}
+
+// ---------------------------------------------------------------------------
+// Platform / fs primitives — small wrappers so writeRaw reads as a sentence
+// ---------------------------------------------------------------------------
+
+function isWindows(): boolean {
+	return process.platform === "win32";
+}
+
+function openTty(): number {
+	return fs.openSync(TTY_PATH, "w");
+}
+
+function writeBytes(fd: number, bytes: string): void {
+	fs.writeSync(fd, bytes);
+}
+
+function closeQuietly(fd: number): void {
+	try {
+		fs.closeSync(fd);
+	} catch {
+		/* fd already closed or invalid — ignore */
+	}
+}
+
+// Windows transport — write OSC bytes to stdout so ConPTY forwards them to
+// Warp. Skipped when stdout isn't a TTY (piped/redirected output would either
+// pollute downstream consumers or never reach the terminal).
+function writeStdout(bytes: string): void {
+	if (!process.stdout.isTTY) return;
+	process.stdout.write(bytes);
+}
+
+// ---------------------------------------------------------------------------
+// Raw transport — single platform-fork; shape-agnostic, swallows errors
+// ---------------------------------------------------------------------------
+
+function writeRaw(bytes: string): void {
+	if (isWindows()) {
+		try {
+			writeStdout(bytes);
+		} catch {
+			/* silent skip — best-effort on Windows */
+		}
+		return;
+	}
+	let fd: number | undefined;
+	try {
+		fd = openTty();
+		writeBytes(fd, bytes);
+	} catch {
+		/* silent skip — matches bash `warp-notify.sh:21` */
+	} finally {
+		if (fd !== undefined) closeQuietly(fd);
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Public emitters — one per shape; all silent-skip on any failure
+// ---------------------------------------------------------------------------
+
+export function writeOSC777(title: string, body: string): void {
+	writeRaw(formatOSC777(title, body));
+}
+
+export function writeOSC0(title: string): void {
+	writeRaw(formatOSC0(title));
+}
+
+export function pushTitleStack(): void {
+	writeRaw(formatPushTitleStack());
+}
+
+export function popTitleStack(): void {
+	writeRaw(formatPopTitleStack());
+}