@pi-unipi/unipi 2.9.0 → 2.10.1

package/CHANGELOG.md

@@ -6,6 +6,34 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [2.10.1] — 2026-08-25
+
+Patch release: `/unipi:trajectory` now registers argument auto-completion so users discover its `stop`, `off`, and `toggle` options inline instead of having to read the docs.
+
+### Fixed
+
+- `trajectory`: `/unipi:trajectory` registered its command with only a `description` and `handler`, so the TUI never offered argument completions and users had no way to learn that `stop`/`off`/`toggle` (or running it bare to open the server) existed. Added `getArgumentCompletions` to the registered command, returning `stop`, `off`, `toggle`, and a `(no argument)` hint that opens/reuses the server — matching the action set the handler already accepts.
+
+### Changed
+
+- All `@pi-unipi/*` packages and the umbrella re-versioned to `2.10.1` so npm installs keep a single synchronized workspace set and avoid nested stale package copies.
+
+## [2.10.0] — 2026-08-25
+
+This release adds UniPi Trajectory, a localhost-only live inspector for the current Pi session, with durable redacted sidecar telemetry for exact request/tool timings and provider metadata.
+
+### Added
+
+- `@pi-unipi/trajectory`: new `/unipi:trajectory` command that opens or reuses a local session inspector on `127.0.0.1:8176-8186`.
+- Trajectory UI: turn-aware ledger, Input/Model/Tools overview timeline, search, turn/tool folding, drag-to-focus, detail tabs, light/dark theme toggle, and responsive inspector.
+- Trajectory projection: current `SessionManager.getBranch()` is projected into user, assistant, tool, compaction, and branch records without mutating Pi session history or provider context.
+- Trajectory telemetry: append-only `~/.unipi/trajectory/<session-id>.jsonl` sidecars capture redacted provider payload/options, tool schemas, response status/headers, TTFT, decoding/total request timing, token/cache usage, and tool execution duration when Pi hooks expose them.
+
+### Changed
+
+- Umbrella `@pi-unipi/unipi` now includes trajectory and the autocomplete registry lists `/unipi:trajectory`.
+- All `@pi-unipi/*` packages re-versioned to `2.10.0` so npm installs keep a single synchronized workspace set and avoid nested stale package copies.
+
 ## [2.9.0] — 2026-08-24
 
 This release upgrades the Pi SDK floor to `^0.84.0` (resolves to 0.84.2) across all packages and re-synchronizes every package onto a single shared version (2.9.0) after the 2.6/2.8 version drift caused npm to resolve registry copies of workspace packages — stale peers that broke clean installs (ERESOLVE) and shipped nested stale copies. It also ships the compactor auto-compaction abort fix (issue #30).

package/README.md

@@ -1,6 +1,6 @@
 # Unipi
 
-21 workspace packages that turn Pi into a full development workstation. Structured workflows, persistent memory, parallel agents, web research, notifications, context management, command autocomplete, and a live status bar — all wired together through a shared event system.
+22 workspace packages that turn Pi into a full development workstation. Structured workflows, persistent memory, parallel agents, web research, notifications, context management, command autocomplete, and a live status bar — all wired together through a shared event system.
 
 One command installs everything:
 ```bash
@@ -43,6 +43,8 @@ pi install npm:@pi-unipi/unipi
 
 **[Kanboard](./packages/kanboard/README.md)** — Web UI and TUI overlay for kanban boards. Parses all workflow documents into cards with progress indicators.
 
+**[Trajectory](./packages/trajectory/README.md)** — Live localhost session inspector. Explore turns, reasoning, tool payloads/results, timing, token/cache usage, and compactions for the current session.
+
 **[Info Screen](./packages/info-screen/README.md)** — Dashboard overlay showing module status, tools, and custom data groups.
 
 **[Utility](./packages/utility/README.md)** — Environment info, diagnostics, cleanup, name badge, and Shiki-powered diff rendering.
@@ -95,6 +97,7 @@ Coexists triggers enhance behavior when packages are installed together. Workflo
 | Utility | `/unipi:` | env, doctor, status, cleanup, badge-name |
 | Milestone | `/unipi:milestone-` | onboard, update |
 | Kanboard | `/unipi:kanboard` | toggle, doctor |
+| Trajectory | `/unipi:trajectory` | open the live current-session inspector |
 | Footer | `/unipi:footer` | toggle, settings |
 | Updater | `/unipi:` | readme, changelog, updater-settings |
 | Info | `/unipi:info` | dashboard, settings |
@@ -143,6 +146,7 @@ unipi/
 │   ├── ask-user/       # Structured input
 │   ├── milestone/      # Goal tracking
 │   ├── kanboard/       # Kanban visualization
+│   ├── trajectory/     # Live session trajectory inspector
 │   ├── info-screen/    # Dashboard overlay
 │   ├── utility/        # Diagnostics, diff rendering
 │   ├── updater/        # Auto-update, browsers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/unipi",
-  "version": "2.9.0",
+  "version": "2.10.1",
   "description": "All-in-one extension suite for Pi coding agent",
   "type": "module",
   "license": "MIT",
@@ -82,27 +82,28 @@
     "typebox": "^1.1.38"
   },
   "dependencies": {
-    "@pi-unipi/ask-user": "2.9.0",
-    "@pi-unipi/background-tasks": "2.9.0",
-    "@pi-unipi/btw": "2.9.0",
-    "@pi-unipi/command-enchantment": "2.9.0",
-    "@pi-unipi/compactor": "2.9.0",
-    "@pi-unipi/core": "2.9.0",
-    "@pi-unipi/footer": "2.9.0",
-    "@pi-unipi/image": "2.9.0",
-    "@pi-unipi/info-screen": "2.9.0",
-    "@pi-unipi/input-shortcuts": "2.9.0",
-    "@pi-unipi/kanboard": "2.9.0",
-    "@pi-unipi/mcp": "2.9.0",
-    "@pi-unipi/memory": "2.9.0",
-    "@pi-unipi/milestone": "2.9.0",
-    "@pi-unipi/notify": "2.9.0",
-    "@pi-unipi/ralph": "2.9.0",
-    "@pi-unipi/subagents": "2.9.0",
-    "@pi-unipi/updater": "2.9.0",
-    "@pi-unipi/utility": "2.9.0",
-    "@pi-unipi/web-api": "2.9.0",
-    "@pi-unipi/workflow": "2.9.0"
+    "@pi-unipi/ask-user": "2.10.0",
+    "@pi-unipi/background-tasks": "2.10.0",
+    "@pi-unipi/btw": "2.10.0",
+    "@pi-unipi/command-enchantment": "2.10.0",
+    "@pi-unipi/compactor": "2.10.0",
+    "@pi-unipi/core": "2.10.0",
+    "@pi-unipi/footer": "2.10.0",
+    "@pi-unipi/image": "2.10.0",
+    "@pi-unipi/info-screen": "2.10.0",
+    "@pi-unipi/input-shortcuts": "2.10.0",
+    "@pi-unipi/kanboard": "2.10.0",
+    "@pi-unipi/mcp": "2.10.0",
+    "@pi-unipi/memory": "2.10.0",
+    "@pi-unipi/milestone": "2.10.0",
+    "@pi-unipi/notify": "2.10.0",
+    "@pi-unipi/ralph": "2.10.0",
+    "@pi-unipi/subagents": "2.10.0",
+    "@pi-unipi/trajectory": "2.10.0",
+    "@pi-unipi/updater": "2.10.0",
+    "@pi-unipi/utility": "2.10.0",
+    "@pi-unipi/web-api": "2.10.0",
+    "@pi-unipi/workflow": "2.10.0"
   },
   "devDependencies": {
     "@earendil-works/pi-agent-core": "^0.84.0",

package/packages/ask-user/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pi-unipi/ask-user",
-  "version": "2.9.0",
-  "description": "Structured user input tool for Pi coding agent \u2014 single-select, multi-select, freeform",
+  "version": "2.10.1",
+  "description": "Structured user input tool for Pi coding agent — single-select, multi-select, freeform",
   "type": "module",
   "main": "index.ts",
   "license": "MIT",
@@ -40,7 +40,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.9.0"
+    "@pi-unipi/core": "2.10.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.0",

package/packages/autocomplete/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pi-unipi/command-enchantment",
-  "version": "2.9.0",
-  "description": "Enhanced TUI autocomplete for /unipi:* commands \u2014 colored, sorted, and grouped by package",
+  "version": "2.10.1",
+  "description": "Enhanced TUI autocomplete for /unipi:* commands — colored, sorted, and grouped by package",
   "type": "module",
   "main": "src/index.ts",
   "license": "MIT",

package/packages/autocomplete/src/constants.ts

@@ -30,6 +30,7 @@ export const PACKAGE_ORDER: string[] = [
   "compact",
   "notify",
   "kanboard",
+  "trajectory",
   "footer",
   "updater",
   "input-shortcuts",
@@ -54,6 +55,7 @@ export const PACKAGE_COLORS: Record<string, string> = {
   compact:   `${ESC}[37m`, // White
   notify:    `${ESC}[96m`, // Bright Cyan
   kanboard:  `${ESC}[92m`, // Bright Green
+  trajectory: `${ESC}[94m`, // Bright Blue
   footer:    `${ESC}[34m`, // Blue
   updater:   `${ESC}[93m`, // Bright Yellow
   "input-shortcuts": `${ESC}[95m`, // Bright Magenta
@@ -190,6 +192,9 @@ export const COMMAND_REGISTRY: Record<string, string> = {
   "unipi:kanboard":          "kanboard",
   "unipi:kanboard-doctor":   "kanboard",
 
+  // trajectory (1 command)
+  "unipi:trajectory":        "trajectory",
+
   // footer (3 commands)
   "unipi:footer":            "footer",
   "unipi:footer-settings":   "footer",
@@ -267,6 +272,7 @@ export const COMMAND_DESCRIPTIONS: Record<string, string> = {
   "unipi:util-settings": "Unified settings — badge + diff rendering config",
   "unipi:kanboard":        "Start the kanboard visualization server",
   "unipi:kanboard-doctor": "Diagnose and fix kanboard parser issues",
+  "unipi:trajectory":      "Open/reuse trajectory; add stop/off or toggle to close it",
 
   "unipi:ask-user-settings": "Configure ask-user settings",
 
@@ -340,6 +346,7 @@ export const PACKAGE_LABELS: Record<string, string> = {
   compact:   "compact",
   notify:    "notify",
   kanboard:  "kanboard",
+  trajectory: "trajectory",
   footer:    "footer",
   updater:   "updater",
   "input-shortcuts": "input-shortcuts",

package/packages/background-tasks/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pi-unipi/background-tasks",
-  "version": "2.9.0",
-  "description": "Background tasks for UniPi \u2014 durable shell jobs, delegated agents, attested Pi runs, and fixed-purpose Fusion workflows",
+  "version": "2.10.1",
+  "description": "Background tasks for UniPi — durable shell jobs, delegated agents, attested Pi runs, and fixed-purpose Fusion workflows",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -10,7 +10,7 @@
   },
   "dependencies": {
     "@earendil-works/pi-ai": "^0.84.0",
-    "@pi-unipi/core": "2.9.0",
+    "@pi-unipi/core": "2.10.0",
     "turndown": "^7.2.4"
   },
   "devDependencies": {

package/packages/btw/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pi-unipi/btw",
-  "version": "2.9.0",
-  "description": "A pi extension for parallel side conversations with /unipi:btw \u2014 part of the Unipi suite",
+  "version": "2.10.1",
+  "description": "A pi extension for parallel side conversations with /unipi:btw — part of the Unipi suite",
   "type": "module",
   "main": "extensions/btw.ts",
   "license": "MIT",
@@ -37,7 +37,7 @@
     "@earendil-works/pi-tui": "^0.84.0"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.9.0"
+    "@pi-unipi/core": "2.10.0"
   },
   "pi": {
     "extensions": [

package/packages/compactor/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pi-unipi/compactor",
-  "version": "2.9.0",
-  "description": "Context engine for Pi \u2014 zero-LLM compaction, session continuity, sandbox execution, and tool display optimization",
+  "version": "2.10.1",
+  "description": "Context engine for Pi — zero-LLM compaction, session continuity, sandbox execution, and tool display optimization",
   "type": "module",
   "main": "src/index.ts",
   "license": "MIT",
@@ -34,8 +34,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.9.0",
-    "@pi-unipi/info-screen": "2.9.0",
+    "@pi-unipi/core": "2.10.0",
+    "@pi-unipi/info-screen": "2.10.0",
     "@earendil-works/pi-agent-core": "^0.84.0"
   },
   "peerDependencies": {

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/core",
-  "version": "2.9.0",
+  "version": "2.10.1",
   "description": "Shared utilities, event types, and constants for Unipi extension suite",
   "type": "module",
   "license": "MIT",

package/packages/footer/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pi-unipi/footer",
-  "version": "2.9.0",
-  "description": "Persistent status bar for Unipi \u2014 subscribes to UNIPI_EVENTS and renders key stats from all unipi packages",
+  "version": "2.10.1",
+  "description": "Persistent status bar for Unipi — subscribes to UNIPI_EVENTS and renders key stats from all unipi packages",
   "type": "module",
   "main": "index.ts",
   "license": "MIT",
@@ -32,7 +32,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.9.0"
+    "@pi-unipi/core": "2.10.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.0",

package/packages/image/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/image",
-  "version": "2.9.0",
+  "version": "2.10.1",
   "description": "Image generation and image recognition tools for the Pi coding agent",
   "type": "module",
   "main": "src/index.ts",
@@ -34,7 +34,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.9.0"
+    "@pi-unipi/core": "2.10.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "^0.84.0",

package/packages/info-screen/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pi-unipi/info-screen",
-  "version": "2.9.0",
-  "description": "Dashboard and module registry for Unipi \u2014 configurable info overlay with tabbed groups",
+  "version": "2.10.1",
+  "description": "Dashboard and module registry for Unipi — configurable info overlay with tabbed groups",
   "type": "module",
   "main": "index.ts",
   "license": "MIT",
@@ -33,7 +33,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.9.0"
+    "@pi-unipi/core": "2.10.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.0",

package/packages/input-shortcuts/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pi-unipi/input-shortcuts",
-  "version": "2.9.0",
-  "description": "Keyboard shortcuts for stash/restore, undo/redo, clipboard, and thinking toggle \u2014 chord-based overlay system",
+  "version": "2.10.1",
+  "description": "Keyboard shortcuts for stash/restore, undo/redo, clipboard, and thinking toggle — chord-based overlay system",
   "type": "module",
   "main": "src/index.ts",
   "license": "MIT",
@@ -33,7 +33,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.9.0"
+    "@pi-unipi/core": "2.10.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.0",

package/packages/kanboard/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pi-unipi/kanboard",
-  "version": "2.9.0",
-  "description": "Visualization layer for unipi workflow \u2014 HTTP server with htmx/Alpine.js UI, modular parsers, TUI overlay, and kanban board",
+  "version": "2.10.1",
+  "description": "Visualization layer for unipi workflow — HTTP server with htmx/Alpine.js UI, modular parsers, TUI overlay, and kanban board",
   "type": "module",
   "main": "index.ts",
   "license": "MIT",
@@ -39,7 +39,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.9.0"
+    "@pi-unipi/core": "2.10.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.0",

package/packages/mcp/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pi-unipi/mcp",
-  "version": "2.9.0",
-  "description": "MCP server management extension for Pi coding agent \u2014 browse, add, configure, and use MCP servers",
+  "version": "2.10.1",
+  "description": "MCP server management extension for Pi coding agent — browse, add, configure, and use MCP servers",
   "type": "module",
   "main": "src/index.ts",
   "license": "MIT",
@@ -30,7 +30,7 @@
     "test": "npx tsx --test tests/**/*.test.ts"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.9.0"
+    "@pi-unipi/core": "2.10.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.0",

package/packages/memory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/memory",
-  "version": "2.9.0",
+  "version": "2.10.1",
   "description": "Persistent cross-session memory with MemPalace backend (auto-installed) and SQLite fallback for Pi coding agent",
   "type": "module",
   "main": "index.ts",
@@ -39,8 +39,8 @@
     "README.md"
   ],
   "dependencies": {
-    "@pi-unipi/core": "2.9.0",
-    "@pi-unipi/info-screen": "2.9.0",
+    "@pi-unipi/core": "2.10.0",
+    "@pi-unipi/info-screen": "2.10.0",
     "js-yaml": "^4.1.0"
   },
   "peerDependencies": {

package/packages/milestone/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pi-unipi/milestone",
-  "version": "2.9.0",
-  "description": "Lifecycle layer for project-level goals \u2014 MILESTONES.md tracking, session hooks, auto-sync",
+  "version": "2.10.1",
+  "description": "Lifecycle layer for project-level goals — MILESTONES.md tracking, session hooks, auto-sync",
   "type": "module",
   "main": "index.ts",
   "scripts": {
@@ -32,7 +32,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.9.0"
+    "@pi-unipi/core": "2.10.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.0",

package/packages/notify/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pi-unipi/notify",
-  "version": "2.9.0",
-  "description": "Cross-platform notification extension for Pi \u2014 native OS, Gotify, and Telegram notifications for agent lifecycle events",
+  "version": "2.10.1",
+  "description": "Cross-platform notification extension for Pi — native OS, Gotify, and Telegram notifications for agent lifecycle events",
   "type": "module",
   "main": "index.ts",
   "license": "MIT",
@@ -34,7 +34,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.9.0",
+    "@pi-unipi/core": "2.10.0",
     "node-notifier": "^10.0.1"
   },
   "peerDependencies": {

package/packages/ralph/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/ralph",
-  "version": "2.9.0",
+  "version": "2.10.1",
   "description": "Long-running iterative development loops for Pi coding agent",
   "type": "module",
   "main": "index.ts",
@@ -31,8 +31,8 @@
     "test": "npx tsx --test reminder.test.ts"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.9.0",
-    "@pi-unipi/info-screen": "2.9.0"
+    "@pi-unipi/core": "2.10.0",
+    "@pi-unipi/info-screen": "2.10.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "^0.84.0",

package/packages/subagents/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pi-unipi/subagents",
-  "version": "2.9.0",
-  "description": "Subagents for UniPi \u2014 parallel execution, file locking, workflow integration",
+  "version": "2.10.1",
+  "description": "Subagents for UniPi — parallel execution, file locking, workflow integration",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -9,7 +9,7 @@
     "test": "npx tsx --test src/__tests__/*.test.ts"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.9.0",
+    "@pi-unipi/core": "2.10.0",
     "@earendil-works/pi-agent-core": "^0.84.0",
     "acorn": "8.18.0"
   },

package/packages/trajectory/README.md

@@ -0,0 +1,47 @@
+# @pi-unipi/trajectory
+
+Live, localhost-only UniPi trajectory inspector for the current Pi session.
+
+## Usage
+
+```text
+/unipi:trajectory             # open or reuse the server
+/unipi:trajectory stop        # stop this session's server
+/unipi:trajectory off         # alias of stop
+/unipi:trajectory toggle      # open when stopped, stop when running
+```
+
+Typing `/unipi:trajectory` followed by a space auto-completes the available
+actions (`stop`, `off`, `toggle`), so the options are discoverable without
+reading the docs. Running it with no argument opens or reuses the server.
+
+The command starts or reuses an in-process server on `127.0.0.1:8176-8186` and opens it in the default browser. The page follows the active session every 500 ms. The server is owned by the current Pi process and is stopped on any Pi session shutdown/reload/resume/new/fork event.
+
+## What it shows
+
+- Turn-aware User, Assistant, Tool, Compaction, and Branch ledger
+- Assistant reasoning and final output
+- Tool payloads, results, errors, and measured call duration
+- Provider, model, stop reason, token usage, cache reads/writes, and cost
+- Provider, model, thinking level, request payload/options, tool schemas, response status/headers
+- Exact TTFT, decoding/total request timing, and tool execution timing
+- Input/Model/Tools overview timeline with drag-to-focus
+- Search, turn folding, call folding, and a local record inspector
+
+## Privacy and model behavior
+
+The server binds only to `127.0.0.1`. It reads `SessionManager.getBranch()` and never appends or changes session entries, prompts, provider requests, or model context. It therefore has no prefix-cache effect.
+
+Detailed telemetry is appended to `~/.unipi/trajectory/<session-id>.jsonl` with a private directory/file mode. Authorization, API-key, token, cookie, secret, password, and credential fields and credential-shaped values are recursively redacted before persistence.
+
+Detailed request fields appear when captured by the trajectory telemetry sidecar.
+
+## Lifecycle
+
+Each Pi process owns its own trajectory server. A second Pi process running `/unipi:trajectory` picks the next free localhost port in `8176-8186`; it never attaches to or controls another Pi process's server. When the owning Pi session exits, reloads, resumes another session, starts a new session, or forks, its server is closed.
+
+## Limitations
+
+- Live transport uses 500 ms polling rather than a push stream.
+- Very large branches are rendered in one table; browser virtualization can be added if measured sessions require it.
+- Tool duration uses exact executor telemetry when captured and session timestamps otherwise.

package/packages/trajectory/index.ts

@@ -0,0 +1,80 @@
+import type { ExtensionAPI, ExtensionContext, SessionEntry } from "@earendil-works/pi-coding-agent";
+import { registerTelemetryCapture } from "./src/capture.js";
+import { projectTrajectory } from "./src/project.js";
+import { openBrowser, TrajectoryServer } from "./src/server.js";
+
+let server: TrajectoryServer | null = null;
+let currentContext: ExtensionContext | null = null;
+
+function stopServer(): boolean {
+  if (!server?.url) return false;
+  server.stop();
+  server = null;
+  return true;
+}
+
+export default function trajectory(pi: ExtensionAPI): void {
+  const readTelemetry = registerTelemetryCapture(pi);
+
+  pi.registerCommand("unipi:trajectory", {
+    description: "Open or manage UniPi's live trajectory for the current session",
+    getArgumentCompletions: (argumentPrefix: string) => {
+      const prefix = argumentPrefix.trim().toLowerCase();
+      const actions = [
+        { value: "stop", label: "stop", description: "Stop this session's trajectory server" },
+        { value: "off", label: "off", description: "Alias of stop" },
+        { value: "toggle", label: "toggle", description: "Open when stopped, stop when running" },
+      ];
+      const matches = prefix
+        ? actions.filter((a) => a.value.startsWith(prefix) || a.label.startsWith(prefix))
+        : actions;
+      // With no prefix (or a matching one) also surface a hint that running bare
+      // opens/reuses the server, so users learn the default behavior exists.
+      const items = matches.map((a) => ({ value: a.value, label: a.label, description: a.description }));
+      if (!prefix) {
+        items.unshift({
+          value: "",
+          label: "(no argument)",
+          description: "Open or reuse the trajectory server in the browser",
+        });
+      }
+      return items;
+    },
+    handler: async (args, ctx) => {
+      const action = String(args ?? "").trim().toLowerCase();
+      const wantsStop = ["stop", "off", "--stop", "--off"].includes(action);
+      const wantsToggle = ["toggle", "--toggle"].includes(action);
+      if (wantsStop || (wantsToggle && server?.url)) {
+        ctx.ui.notify(stopServer() ? "Trajectory stopped" : "Trajectory is not running", "info");
+        return;
+      }
+
+      currentContext = ctx;
+      if (!server) {
+        server = new TrajectoryServer({
+          snapshot: () => {
+            const active = currentContext ?? ctx;
+            return projectTrajectory(active.sessionManager.getBranch() as SessionEntry[], {
+              sessionId: active.sessionManager.getSessionId(),
+              name: active.sessionManager.getSessionName(),
+              cwd: active.cwd,
+            }, readTelemetry());
+          },
+        });
+      }
+      try {
+        const url = await server.start();
+        openBrowser(url);
+        ctx.ui.notify(`Trajectory running at ${url}`, "info");
+      } catch (error) {
+        ctx.ui.notify(`Trajectory error: ${error instanceof Error ? error.message : String(error)}`, "error");
+      }
+    },
+  });
+
+  pi.on("session_start", (_event, ctx) => { currentContext = ctx; });
+  pi.on("session_shutdown", () => {
+    currentContext = null;
+    stopServer();
+  });
+}