@d3ara1n/pi-editor-shell 0.9.0 → 0.10.0

package/README.md

@@ -7,7 +7,7 @@ Replaces pi's default editor and status bar with a unified rounded-corner shell
 ## What shows up where
 
 - **Top border** — `  model ·  thinking-level ` (left) + pinned extension statuses (right, via `pinnedStatus` config)
-- **Bottom border** — `  ctx NN%/NNk|N.NM · ⚡ cacheRead (total)  hitRate% · NN.N t/s · $N.NNN ` (left) + `  ~/Projects (main +2 ~1 *4) ` (right, shows git branch plus staged, unstaged, and untracked file counts when in a repo). TPS is measured for the latest completed response from its first streamed content delta, excluding time-to-first-token. Session cost includes assistant, tool, compaction, and branch-summary usage; the dollar segment is hidden when the provider reports no priced usage. Session hit rate via `/editor-shell:status`.
+- **Bottom border** — `  ctx NN%/NNk|N.NM · ⚡ cacheRead (total)  hitRate% · NN.N e2e t/s · $N.NNN ` (left) + `  ~/Projects (main +2 ~1 *4) ` (right, shows git branch plus staged, unstaged, and untracked file counts when in a repo; inside a linked worktree the branch carries an `@<name>` tag, e.g. `(feature-x @feature-x +2 ~1)`, so sibling worktrees of one repo are told apart at a glance). Response throughput defaults to client-observed end-to-end visible-text throughput, including local request preparation, network and queue latency, hidden reasoning, and visible generation. It can instead show generation throughput or be hidden; see [Throughput display](#throughput-display). A new turn clears the previous measurement, so unavailable samples never leave stale data in the border. Session cost includes assistant, tool, compaction, and branch-summary usage; the dollar segment is hidden when the provider reports no priced usage. Session hit rate and detailed response timing are available via `/editor-shell:status`.
 - **Below shell** — Auto-wrapping extension status line (all `setStatus` entries not pinned to the top)
 - **Border color** follows pi's thinking-level / bash-mode indicator automatically.
 
@@ -21,6 +21,7 @@ In `~/.pi/agent/settings.json` under the `editorShell` key:
 {
   "editorShell": {
     "pinnedStatus": ["subagent", "access-denied"],
+    "tpsDisplay": "end-to-end",
     "icons": {
       "model": "robot",
       "cache": "\\uf0e7"
@@ -54,16 +55,36 @@ How the model is labeled in the top-left border (`"name"` by default):
 
 | Value | Example |
 |-------|---------|
-| `"name"` (default) | `Claude Opus 4.8 (Yanproxy)` |
-| `"provider-id"` | `yanproxy/anthropic/claude-opus-4-8` |
+| `"name"` (default) | `Claude Opus 4.8` |
+| `"provider-id"` | `anthropic/claude-opus-4-8` |
 
 `"name"` uses `model.name`; a model with no name falls back to its id, so the slot never goes blank.
 
+### Throughput display
+
+Choose the response-throughput metric shown in the bottom border (`"end-to-end"` by default):
+
+```json
+{
+  "editorShell": {
+    "tpsDisplay": "end-to-end"
+  }
+}
+```
+
+| Value | Border label | Measurement |
+|-------|--------------|-------------|
+| `"end-to-end"` (default) | `e2e t/s` | Visible output tokens divided by total turn duration, including wait time and hidden reasoning |
+| `"generation"` | `gen t/s` | Visible tokens after the first divided by the time from first visible text to response completion |
+| `"none"` | — | Hides response throughput from the border |
+
+Both throughput values, time to first visible text, total response time, visible-token count, and token source remain available via `/editor-shell:status`. Generation samples below 10 visible tokens or 250 ms are reported as unavailable. Responses containing tool calls cannot provide a portable text-token split. If reasoning is active but the provider does not supply a usable positive reasoning-token count, both throughput values are reported as unavailable rather than treating hidden tokens as visible output.
+
 ## Commands
 
 | Command | Description |
 |---------|-------------|
-| `/editor-shell:status` | Show debug info: pinned config, all extension statuses with their keys, cache totals, latest response TPS, and session cost |
+| `/editor-shell:status` | Show debug info: config, extension statuses, cache totals, response wait time, end-to-end and generation throughput, token source, and session cost |
 
 ## How it works
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d3ara1n/pi-editor-shell",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "type": "module",
   "description": "Replaces pi's default editor and status bar with a unified rounded-corner shell embedding status info in the border",
   "keywords": [

package/src/config.ts

@@ -25,6 +25,9 @@ export interface EditorShellIcons {
 /** How the model is shown in the top-left border slot. */
 export type ModelDisplay = "name" | "provider-id";
 
+/** Which response-throughput metric is shown in the shell border. */
+export type TpsDisplay = "end-to-end" | "generation" | "none";
+
 export interface EditorShellConfig {
   /**
    * Status keys to pin to the shell's top-right corner.
@@ -44,6 +47,11 @@ export interface EditorShellConfig {
    * - `"provider-id"` — `provider/id`.
    */
   modelDisplay: ModelDisplay;
+  /**
+   * Response-throughput metric shown in the bottom border.
+   * Detailed response timing remains available via /editor-shell:status.
+   */
+  tpsDisplay: TpsDisplay;
 }
 
 const ICON_KEYS: ReadonlyArray<keyof EditorShellIcons> = [
@@ -70,6 +78,7 @@ export const DEFAULT_CONFIG: EditorShellConfig = {
   pinnedStatus: [],
   icons: {},
   modelDisplay: "name",
+  tpsDisplay: "end-to-end",
 };
 
 /** Read the `editorShell` block from a settings file.
@@ -101,6 +110,13 @@ export function loadEditorShellConfig(cwd?: string): EditorShellConfig {
     modelDisplayRaw === "name" || modelDisplayRaw === "provider-id"
       ? modelDisplayRaw
       : DEFAULT_CONFIG.modelDisplay;
+  const tpsDisplayRaw = raw.tpsDisplay;
+  const tpsDisplay =
+    tpsDisplayRaw === "end-to-end" ||
+    tpsDisplayRaw === "generation" ||
+    tpsDisplayRaw === "none"
+      ? tpsDisplayRaw
+      : DEFAULT_CONFIG.tpsDisplay;
   return {
     pinnedStatus: Array.isArray(pinned)
       ? pinned.filter((k): k is string => typeof k === "string")
@@ -110,5 +126,6 @@ export function loadEditorShellConfig(cwd?: string): EditorShellConfig {
         ? filterIcons(iconsRaw as Record<string, unknown>)
         : {},
     modelDisplay,
+    tpsDisplay,
   };
 }

package/src/index.ts

@@ -1,10 +1,12 @@
 import type { ExtensionAPI, ThemeColor } from "@earendil-works/pi-coding-agent";
 import { visibleWidth } from "@earendil-works/pi-tui";
 import { spawn } from "node:child_process";
+import { readFileSync, statSync } from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { CardEditor, type FrameProvider, type SpinnerPhase } from "./card-editor.ts";
 import { DEFAULT_CONFIG, loadEditorShellConfig, type EditorShellConfig, type EditorShellIcons } from "./config.ts";
+import { calculateResponsePerformance, type ResponsePerformance } from "./tps.ts";
 
 /**
  * pi-editor-shell — Replaces pi's default editor and status bar with a
@@ -75,6 +77,7 @@ const DEFAULT_ICONS: EditorShellIcons = {
 interface UsageSnap {
   input?: number;
   output?: number;
+  reasoning?: number;
   cacheRead?: number;
   cacheWrite?: number;
   cost?: {
@@ -83,7 +86,9 @@ interface UsageSnap {
 }
 interface MsgSnap {
   role: string;
+  content?: Array<{ type: string; text?: string }>;
   usage?: UsageSnap;
+  stopReason?: string;
 }
 interface EntrySnap {
   type: string;
@@ -185,6 +190,24 @@ function formatTokens(n: number): string {
   return String(n);
 }
 
+function formatDuration(ms: number | undefined): string {
+  if (ms == null || !Number.isFinite(ms) || ms < 0) return "n/a";
+  if (ms < 1_000) return `${ms.toFixed(0)} ms`;
+  const seconds = ms / 1_000;
+  if (seconds < 60) return `${trimFixed1(seconds)}s`;
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = seconds - minutes * 60;
+  if (minutes < 60) return `${minutes}m ${trimFixed1(remainingSeconds)}s`;
+  const hours = Math.floor(minutes / 60);
+  return `${hours}h ${minutes % 60}m`;
+}
+
+function formatTps(tps: number): string {
+  if (tps < 0.1) return tps.toFixed(3);
+  if (tps < 1) return tps.toFixed(2);
+  return tps.toFixed(1);
+}
+
 // ── Git dirty state (event-driven, not TTL) ───────────────────────
 // Refreshed at session_start and after every agent turn (turn_end).
 interface GitDirty {
@@ -248,6 +271,60 @@ function refreshGitDirty(cwd: string, onDone?: () => void): void {
   child.on("close", (code) => settle(code === 0, stdout));
 }
 
+/** Filesystem boundary for {@link linkedWorktreeName}, injectable so tests
+ *  can exercise the walk-up and pointer parsing without touching the real
+ *  filesystem. `isFile` distinguishes "missing" (undefined) from "exists but
+ *  not a regular file" (false) — the walk-up continues past the former and
+ *  stops at the latter (a `.git` directory = main worktree). */
+export interface WorktreeIO {
+  isFile(p: string): boolean | undefined;
+  readText(p: string): string;
+}
+
+const NODE_IO: WorktreeIO = {
+  isFile(p) {
+    try {
+      return statSync(p).isFile();
+    } catch (e) {
+      if ((e as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+      throw e;
+    }
+  },
+  readText(p) {
+    return readFileSync(p, "utf8");
+  },
+};
+
+/** Name of the linked worktree containing `cwd`, or null when `cwd` sits in
+ *  the main worktree or outside any repo. A linked worktree marks itself with
+ *  a `.git` *file* pointing at `<main>/.git/worktrees/<name>`; the parent-dir
+ *  check keeps submodule pointers (`.git/modules/…`) from masquerading as
+ *  worktrees.
+ *  @internal — exported for testing; the session reads it once at start. */
+export function linkedWorktreeName(cwd: string, io: WorktreeIO = NODE_IO): string | null {
+  let dir = path.resolve(cwd);
+  for (;;) {
+    const dotGit = path.join(dir, ".git");
+    const kind = io.isFile(dotGit);
+    if (kind === undefined) {
+      const parent = path.dirname(dir);
+      if (parent === dir) return null;
+      dir = parent;
+      continue;
+    }
+    if (!kind) return null;
+    try {
+      const content = io.readText(dotGit).trim();
+      if (!content.startsWith("gitdir: ")) return null;
+      const gitdir = path.resolve(dir, content.slice("gitdir: ".length));
+      if (path.basename(path.dirname(gitdir)) !== "worktrees") return null;
+      return path.basename(gitdir) || null;
+    } catch {
+      return null;
+    }
+  }
+}
+
 /** Format dirty state as "+staged ~unstaged *untracked" (leading space), or ""
  *  if clean / unknown — ready to splice into a "(branch…)" segment. */
 function gitDirtyDisplay(): string {
@@ -279,17 +356,24 @@ export default function (pi: ExtensionAPI) {
   let footerSnap: FooterSnap | undefined;
   // CWD cached from session_start — used by turn_end to refresh git dirty.
   let _cwd = "";
+  // Linked-worktree name for the session cwd, resolved once at session_start
+  // (worktree names are stable for the lifetime of a session). Null = main
+  // worktree or outside any repo — no badge.
+  let _worktreeName: string | null = null;
   // cacheRead total + latest-turn usage, refreshed at session_start +
   // agent_end. The render provider reads these instead of re-scanning
   // entries every frame.
   let _cacheTotal = 0;
   let _latestUsage: UsageSnap | undefined;
-  // Latest completed response throughput. Timing begins with the first streamed
-  // content delta, excluding time-to-first-token; it is intentionally not
-  // reconstructed for resumed sessions because persisted messages have no end time.
-  let _streamStartedAt: number | undefined;
-  let _pendingResponseElapsedMs: number | undefined;
-  let _latestTps: number | undefined;
+  // Client-observed timing for the current assistant response. The completed
+  // measurement replaces the previous turn even when throughput is unavailable,
+  // so the shell never displays stale performance data.
+  let _turnStartedAt: number | undefined;
+  let _firstVisibleTextAt: number | undefined;
+  let _responseEndedAt: number | undefined;
+  let _reasoningExpected = false;
+  let _sawThinking = false;
+  let _latestPerformance: ResponsePerformance | undefined;
   // Full-session billable cost, including tool/summarization usage. Zero means the
   // provider supplied no priced usage, so the border omits the dollar segment.
   let _sessionCost = 0;
@@ -297,20 +381,30 @@ export default function (pi: ExtensionAPI) {
   // ── Phase-aware spinner + lifecycle ────────────────────────────
   // Each event asks the editor for a phase; CardEditor.setSpinner is itself
   // a same-phase no-op, so rapid event streams never reset the animation.
+  pi.on("turn_start", (_event, ctx) => {
+    _turnStartedAt = performance.now();
+    _firstVisibleTextAt = undefined;
+    _responseEndedAt = undefined;
+    _reasoningExpected = Boolean(ctx.model?.reasoning && pi.getThinkingLevel() !== "off");
+    _sawThinking = false;
+    _latestPerformance = undefined;
+    editor?.setSpinner("thinking");
+    editor?.requestRender();
+  });
   pi.on("message_start", (event) => {
     if (event.message.role !== "assistant") return;
-    _streamStartedAt = undefined;
-    _pendingResponseElapsedMs = undefined;
+    _firstVisibleTextAt = undefined;
+    _responseEndedAt = undefined;
+    _sawThinking = false;
   });
-  pi.on("turn_start", () => editor?.setSpinner("thinking"));
   pi.on("message_update", (event) => {
-    const t = event.assistantMessageEvent.type;
-    if (
-      _streamStartedAt == null &&
-      (t === "thinking_delta" || t === "text_delta" || t === "toolcall_delta")
-    ) {
-      _streamStartedAt = Date.now();
+    const update = event.assistantMessageEvent;
+    const t = update.type;
+    if (t === "text_delta" && update.delta.length > 0) {
+      _firstVisibleTextAt ??= performance.now();
     }
+    if (t.startsWith("thinking_")) _sawThinking = true;
+
     let next: SpinnerPhase;
     if (t.startsWith("thinking_")) next = "thinking";
     else if (t.startsWith("text_")) next = "outputting";
@@ -320,9 +414,13 @@ export default function (pi: ExtensionAPI) {
   });
   pi.on("message_end", (event) => {
     if (event.message.role !== "assistant") return;
-    const elapsedMs = _streamStartedAt == null ? 0 : Date.now() - _streamStartedAt;
-    _pendingResponseElapsedMs = elapsedMs > 0 ? elapsedMs : undefined;
-    _streamStartedAt = undefined;
+    _responseEndedAt = performance.now();
+    const message = event.message as MsgSnap;
+    const hasVisibleText = message.content?.some(
+      (part) => part.type === "text" && typeof part.text === "string" && part.text.length > 0,
+    ) ?? false;
+    // Non-streaming providers expose visible text only when the response completes.
+    if (hasVisibleText) _firstVisibleTextAt ??= _responseEndedAt;
   });
   pi.on("tool_execution_start", () => editor?.setSpinner("exec"));
   pi.on("agent_end", (_event, ctx) => {
@@ -334,9 +432,12 @@ export default function (pi: ExtensionAPI) {
     editor?.setSpinner(null);
   });
   pi.on("session_shutdown", () => {
-    _streamStartedAt = undefined;
-    _pendingResponseElapsedMs = undefined;
-    _latestTps = undefined;
+    _turnStartedAt = undefined;
+    _firstVisibleTextAt = undefined;
+    _responseEndedAt = undefined;
+    _reasoningExpected = false;
+    _sawThinking = false;
+    _latestPerformance = undefined;
     _sessionCost = 0;
     editor?.setSpinner(null);
     editor = undefined;
@@ -354,10 +455,26 @@ export default function (pi: ExtensionAPI) {
   // Async — never blocks the event loop; re-renders once settled.
   pi.on("turn_end", (event) => {
     if (event.message.role === "assistant") {
-      const output = (event.message as MsgSnap).usage?.output ?? 0;
-      const elapsedMs = _pendingResponseElapsedMs ?? 0;
-      _latestTps = elapsedMs > 0 && output > 0 ? output / (elapsedMs / 1000) : undefined;
-      _pendingResponseElapsedMs = undefined;
+      const message = event.message as MsgSnap;
+      const hasVisibleText = message.content?.some(
+        (part) => part.type === "text" && typeof part.text === "string" && part.text.length > 0,
+      ) ?? false;
+      _latestPerformance = calculateResponsePerformance({
+        outputTokens: message.usage?.output,
+        reasoningTokens: message.usage?.reasoning,
+        reasoningExpected: _reasoningExpected || _sawThinking,
+        turnStartedAt: _turnStartedAt,
+        firstVisibleTextAt: _firstVisibleTextAt,
+        responseEndedAt: _responseEndedAt,
+        hasVisibleText,
+        hasToolCall: message.content?.some((part) => part.type === "toolCall") ?? false,
+        stopReason: message.stopReason,
+      });
+      _turnStartedAt = undefined;
+      _firstVisibleTextAt = undefined;
+      _responseEndedAt = undefined;
+      _reasoningExpected = false;
+      _sawThinking = false;
       editor?.requestRender();
     }
     if (_cwd) refreshGitDirty(_cwd, () => editor?.requestRender());
@@ -367,13 +484,17 @@ export default function (pi: ExtensionAPI) {
     if (!ctx.hasUI) return;
 
     _cwd = ctx.cwd;
+    _worktreeName = linkedWorktreeName(ctx.cwd);
     config = loadEditorShellConfig(ctx.cwd);
     icons = { ...DEFAULT_ICONS, ...config.icons };
     _cacheTotal = sumCacheRead(ctx);
     _latestUsage = latestAssistantUsage(ctx);
-    _streamStartedAt = undefined;
-    _pendingResponseElapsedMs = undefined;
-    _latestTps = undefined;
+    _turnStartedAt = undefined;
+    _firstVisibleTextAt = undefined;
+    _responseEndedAt = undefined;
+    _reasoningExpected = false;
+    _sawThinking = false;
+    _latestPerformance = undefined;
     _sessionCost = sumSessionCost(ctx);
     refreshGitDirty(ctx.cwd, () => editor?.requestRender());
 
@@ -422,22 +543,30 @@ export default function (pi: ExtensionAPI) {
         _cacheTotal > 0
           ? `${theme.fg("dim", " · ")}${theme.fg("warning", `${icons.cache} ${formatTokens(cacheReadNow)} (${formatTokens(_cacheTotal)})${hitRate != null ? ` ${icons.hitRate} ${hitRate.toFixed(1)}%` : ""}`)}`
           : "";
-      const tpsPart =
-        _latestTps != null
-          ? `${theme.fg("dim", " · ")}${theme.fg("success", `${_latestTps.toFixed(1)} t/s`)}`
-          : "";
+      const displayedTps = config.tpsDisplay === "end-to-end"
+        ? _latestPerformance?.e2eTps
+        : config.tpsDisplay === "generation"
+          ? _latestPerformance?.generationTps
+          : undefined;
+      const tpsLabel = config.tpsDisplay === "end-to-end" ? "e2e" : "gen";
+      const tpsPart = displayedTps != null
+        ? `${theme.fg("dim", " · ")}${theme.fg("warning", `${formatTps(displayedTps)} ${tpsLabel} t/s`)}`
+        : "";
       const costPart =
         _sessionCost > 0
           ? `${theme.fg("dim", " · ")}${theme.fg("warning", `$${_sessionCost.toFixed(3)}`)}`
           : "";
 
-      // Git branch + dirty state — pi's format: ~/Projects (main).
+      // Git branch + worktree badge + dirty state — pi's format:
+      // ~/Projects (main). Inside a linked worktree the branch carries an
+      // @<name> tag, so sibling worktrees of one repo are told apart at a glance.
       const cwdText = formatCwd(ctx.cwd);
       const branch = footerSnap?.getGitBranch() ?? null;
+      const worktreeTag = _worktreeName ? ` @${_worktreeName}` : "";
       const dirty = branch ? gitDirtyDisplay() : "";
       const cwdDisplay =
         branch && branch !== "detached"
-          ? `${icons.folder} ${cwdText} (${branch}${dirty})`
+          ? `${icons.folder} ${cwdText} (${branch}${worktreeTag}${dirty})`
           : `${icons.folder} ${cwdText}`;
 
       // Model in accent; thinking label in its level token — same hue the
@@ -511,6 +640,7 @@ export default function (pi: ExtensionAPI) {
       lines.push("[editor-shell config]");
       lines.push(`  pinnedStatus: [${config.pinnedStatus.join(", ")}]`);
       lines.push(`  modelDisplay: ${config.modelDisplay}`);
+      lines.push(`  tpsDisplay: ${config.tpsDisplay}`);
 
       lines.push("");
       lines.push("[extension statuses]");
@@ -544,13 +674,33 @@ export default function (pi: ExtensionAPI) {
       const sessionCost = sumSessionCost(ctx);
       _sessionCost = sessionCost;
       lines.push(`  session cost: ${sessionCost > 0 ? `$${sessionCost.toFixed(3)}` : "n/a"}`);
-      lines.push(`  latest response TPS: ${_latestTps != null ? `${_latestTps.toFixed(1)} t/s` : "n/a"}`);
       const latest = latestAssistantUsage(ctx);
       const now = latest?.cacheRead ?? 0;
       lines.push(`  this turn cacheRead: ${formatTokens(now)}`);
       const hr = cacheHitRate(latest);
       lines.push(`  this turn hit rate: ${hr != null ? `${hr.toFixed(1)}%` : "n/a"}`);
 
+      lines.push("");
+      lines.push("[response performance]");
+      const perf = _latestPerformance;
+      const throughputReason = perf?.throughputUnavailableReason;
+      const generationReason = throughputReason ?? perf?.generationUnavailableReason;
+      lines.push(`  wait to first visible text: ${formatDuration(perf?.waitMs)}`);
+      lines.push(`  total response time: ${formatDuration(perf?.totalMs)}`);
+      lines.push(
+        `  end-to-end throughput: ${perf?.e2eTps != null ? `${formatTps(perf.e2eTps)} t/s` : `n/a${throughputReason ? ` (${throughputReason})` : ""}`}`,
+      );
+      lines.push(
+        `  generation throughput: ${perf?.generationTps != null ? `${formatTps(perf.generationTps)} t/s` : `n/a${generationReason ? ` (${generationReason})` : ""}`}`,
+      );
+      lines.push(`  visible output tokens: ${perf?.visibleTokens ?? "n/a"}`);
+      const tokenSource = perf?.tokenSource === "provider-output-minus-reasoning"
+        ? "provider output minus reasoning"
+        : perf?.tokenSource === "provider-output"
+          ? "provider output (reasoning not expected)"
+          : "n/a";
+      lines.push(`  token source: ${tokenSource}`);
+
       lines.push("");
       lines.push(`[context] cwd: ${ctx.cwd}`);
       const branch = footerSnap?.getGitBranch();
@@ -558,6 +708,7 @@ export default function (pi: ExtensionAPI) {
       if (branch) {
         const dirty = gitDirtyDisplay().trim();
         lines.push(`  git dirty: ${dirty || "clean"}`);
+        lines.push(`  worktree: ${_worktreeName ?? "main"}`);
       }
       const m = ctx.model;
       lines.push(`  model: ${m ? `${m.provider}/${m.id}:${pi.getThinkingLevel()}` : "none"}`);

package/src/tps.test.ts

@@ -0,0 +1,136 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  calculateResponsePerformance,
+  type ResponsePerformanceSample,
+} from "./tps.ts";
+
+function sample(overrides: Partial<ResponsePerformanceSample> = {}): ResponsePerformanceSample {
+  return {
+    outputTokens: 101,
+    reasoningTokens: 20,
+    reasoningExpected: true,
+    turnStartedAt: 1_000,
+    firstVisibleTextAt: 3_000,
+    responseEndedAt: 7_000,
+    hasVisibleText: true,
+    hasToolCall: false,
+    stopReason: "stop",
+    ...overrides,
+  };
+}
+
+test("calculates wait, end-to-end throughput, and generation throughput", () => {
+  assert.deepEqual(calculateResponsePerformance(sample()), {
+    waitMs: 2_000,
+    totalMs: 6_000,
+    generationMs: 4_000,
+    visibleTokens: 81,
+    e2eTps: 13.5,
+    generationTps: 20,
+    tokenSource: "provider-output-minus-reasoning",
+  });
+});
+
+test("uses provider output when reasoning is not expected", () => {
+  const result = calculateResponsePerformance(sample({
+    outputTokens: 51,
+    reasoningTokens: undefined,
+    reasoningExpected: false,
+    firstVisibleTextAt: 2_000,
+    responseEndedAt: 6_000,
+  }));
+  assert.equal(result.visibleTokens, 51);
+  assert.equal(result.e2eTps, 10.2);
+  assert.equal(result.generationTps, 12.5);
+  assert.equal(result.tokenSource, "provider-output");
+});
+
+test("rejects throughput when expected reasoning usage is missing or ambiguous", () => {
+  for (const reasoningTokens of [undefined, 0]) {
+    const result = calculateResponsePerformance(sample({ reasoningTokens }));
+    assert.equal(result.waitMs, 2_000);
+    assert.equal(result.totalMs, 6_000);
+    assert.equal(result.e2eTps, undefined);
+    assert.equal(result.generationTps, undefined);
+    assert.equal(
+      result.throughputUnavailableReason,
+      "provider omitted usable reasoning-token usage",
+    );
+  }
+});
+
+test("rejects throughput for responses containing tool calls", () => {
+  const result = calculateResponsePerformance(sample({ hasToolCall: true }));
+  assert.equal(result.waitMs, 2_000);
+  assert.equal(result.e2eTps, undefined);
+  assert.equal(result.throughputUnavailableReason, "text and tool-call tokens are not separable");
+});
+
+test("rejects throughput for failed and aborted responses", () => {
+  for (const stopReason of ["error", "aborted"]) {
+    const result = calculateResponsePerformance(sample({ stopReason }));
+    assert.equal(result.e2eTps, undefined);
+    assert.equal(result.throughputUnavailableReason, "response failed or was aborted");
+  }
+});
+
+test("rejects throughput when there is no visible text", () => {
+  const result = calculateResponsePerformance(sample({ hasVisibleText: false }));
+  assert.equal(result.e2eTps, undefined);
+  assert.equal(result.throughputUnavailableReason, "response contained no visible text");
+});
+
+test("keeps end-to-end throughput when the generation sample is too small", () => {
+  const result = calculateResponsePerformance(sample({
+    outputTokens: 9,
+    reasoningTokens: 0,
+    firstVisibleTextAt: 6_800,
+  }));
+  assert.equal(result.e2eTps, 1.5);
+  assert.equal(result.generationTps, undefined);
+  assert.equal(result.generationUnavailableReason, "fewer than 10 visible tokens");
+});
+
+test("rejects a generation sample shorter than 250 ms", () => {
+  const result = calculateResponsePerformance(sample({
+    outputTokens: 10,
+    reasoningTokens: 0,
+    firstVisibleTextAt: 6_751,
+  }));
+  assert.equal(result.e2eTps, 10 / 6);
+  assert.equal(result.generationTps, undefined);
+  assert.equal(result.generationUnavailableReason, "visible generation lasted less than 250 ms");
+});
+
+test("represents non-streaming output as full wait with unavailable generation throughput", () => {
+  const result = calculateResponsePerformance(sample({
+    outputTokens: 50,
+    reasoningTokens: 0,
+    firstVisibleTextAt: 7_000,
+  }));
+  assert.equal(result.waitMs, 6_000);
+  assert.equal(result.totalMs, 6_000);
+  assert.equal(result.e2eTps, 50 / 6);
+  assert.equal(result.generationTps, undefined);
+  assert.equal(result.generationUnavailableReason, "visible generation lasted less than 250 ms");
+});
+
+test("rejects invalid provider usage", () => {
+  assert.equal(
+    calculateResponsePerformance(sample({ outputTokens: undefined })).throughputUnavailableReason,
+    "provider output-token usage is unavailable",
+  );
+  assert.equal(
+    calculateResponsePerformance(sample({ reasoningTokens: 102 })).throughputUnavailableReason,
+    "provider reasoning-token usage is invalid",
+  );
+});
+
+test("rejects invalid timing without manufacturing rates", () => {
+  const result = calculateResponsePerformance(sample({ responseEndedAt: 500 }));
+  assert.equal(result.waitMs, undefined);
+  assert.equal(result.totalMs, undefined);
+  assert.equal(result.e2eTps, undefined);
+  assert.equal(result.throughputUnavailableReason, "end-to-end timing data is unavailable");
+});

package/src/tps.ts

@@ -0,0 +1,128 @@
+const MIN_GENERATION_TOKENS = 10;
+const MIN_GENERATION_DURATION_MS = 250;
+
+export type TpsTokenSource = "provider-output" | "provider-output-minus-reasoning";
+
+/** @internal — exported for focused throughput tests. */
+export interface ResponsePerformanceSample {
+  outputTokens?: number;
+  reasoningTokens?: number;
+  reasoningExpected: boolean;
+  turnStartedAt?: number;
+  firstVisibleTextAt?: number;
+  responseEndedAt?: number;
+  hasVisibleText: boolean;
+  hasToolCall: boolean;
+  stopReason?: string;
+}
+
+/** @internal — exported for focused throughput tests. */
+export interface ResponsePerformance {
+  waitMs?: number;
+  totalMs?: number;
+  generationMs?: number;
+  visibleTokens?: number;
+  e2eTps?: number;
+  generationTps?: number;
+  tokenSource?: TpsTokenSource;
+  throughputUnavailableReason?: string;
+  generationUnavailableReason?: string;
+}
+
+function validTimestamp(value: number | undefined): value is number {
+  return value != null && Number.isFinite(value);
+}
+
+/**
+ * Calculate client-observed response performance for one completed assistant message.
+ *
+ * End-to-end throughput includes all time after turn start: local request preparation,
+ * network and queue latency, hidden reasoning, and visible generation. Generation
+ * throughput follows the common TPOT boundary: response completion minus time to the
+ * first visible text, divided across the remaining visible tokens.
+ *
+ * @internal — exported for focused throughput tests.
+ */
+export function calculateResponsePerformance(
+  sample: ResponsePerformanceSample,
+): ResponsePerformance {
+  const result: ResponsePerformance = {};
+  const start = sample.turnStartedAt;
+  const first = sample.firstVisibleTextAt;
+  const end = sample.responseEndedAt;
+
+  if (validTimestamp(start) && validTimestamp(end) && end >= start) {
+    result.totalMs = end - start;
+  }
+  if (
+    validTimestamp(start) &&
+    validTimestamp(first) &&
+    validTimestamp(end) &&
+    first >= start &&
+    first <= end
+  ) {
+    result.waitMs = first - start;
+    result.generationMs = end - first;
+  }
+
+  if (sample.stopReason === "error" || sample.stopReason === "aborted") {
+    result.throughputUnavailableReason = "response failed or was aborted";
+    return result;
+  }
+  if (sample.hasToolCall) {
+    result.throughputUnavailableReason = "text and tool-call tokens are not separable";
+    return result;
+  }
+  if (!sample.hasVisibleText) {
+    result.throughputUnavailableReason = "response contained no visible text";
+    return result;
+  }
+
+  const output = sample.outputTokens;
+  const reasoning = sample.reasoningTokens;
+  if (output == null || !Number.isFinite(output) || output < 0) {
+    result.throughputUnavailableReason = "provider output-token usage is unavailable";
+    return result;
+  }
+  // Some adapters normalize an omitted reasoning count to zero. When reasoning
+  // was enabled or observed, zero is therefore ambiguous and cannot safely be
+  // used to derive a visible-token count.
+  if (sample.reasoningExpected && (reasoning == null || reasoning === 0)) {
+    result.throughputUnavailableReason = "provider omitted usable reasoning-token usage";
+    return result;
+  }
+  if (reasoning != null && (!Number.isFinite(reasoning) || reasoning < 0 || reasoning > output)) {
+    result.throughputUnavailableReason = "provider reasoning-token usage is invalid";
+    return result;
+  }
+
+  const visibleTokens = output - (reasoning ?? 0);
+  if (visibleTokens <= 0) {
+    result.throughputUnavailableReason = "provider reported no visible output tokens";
+    return result;
+  }
+
+  result.visibleTokens = visibleTokens;
+  result.tokenSource = reasoning == null
+    ? "provider-output"
+    : "provider-output-minus-reasoning";
+
+  if (result.totalMs == null || result.totalMs <= 0) {
+    result.throughputUnavailableReason = "end-to-end timing data is unavailable";
+    return result;
+  }
+  result.e2eTps = visibleTokens / (result.totalMs / 1000);
+
+  if (result.generationMs == null) {
+    result.generationUnavailableReason = "first visible-text timing is unavailable";
+  } else if (visibleTokens < MIN_GENERATION_TOKENS) {
+    result.generationUnavailableReason = `fewer than ${MIN_GENERATION_TOKENS} visible tokens`;
+  } else if (result.generationMs < MIN_GENERATION_DURATION_MS) {
+    result.generationUnavailableReason = `visible generation lasted less than ${MIN_GENERATION_DURATION_MS} ms`;
+  } else {
+    // N visible tokens span N - 1 post-first-token intervals.
+    result.generationTps = (visibleTokens - 1) / (result.generationMs / 1000);
+  }
+
+  return result;
+}

package/src/worktree.test.ts

@@ -0,0 +1,63 @@
+import * as assert from "node:assert/strict";
+import * as path from "node:path";
+import { describe, it } from "node:test";
+
+import { linkedWorktreeName, type WorktreeIO } from "./index.ts";
+
+/** In-memory filesystem fake: path → file content, or `"dir"` for a directory.\n *  Keys and lookups go through path.resolve, so tests use plain absolute\n *  paths and no real file is ever touched. */
+function fakeIO(entries: Record<string, string>): WorktreeIO {
+  const map = new Map(Object.entries(entries).map(([k, v]) => [path.resolve(k), v]));
+  return {
+    isFile(p) {
+      const v = map.get(path.resolve(p));
+      return v === undefined ? undefined : v !== "dir";
+    },
+    readText(p) {
+      const v = map.get(path.resolve(p));
+      if (v === undefined || v === "dir") throw new Error(`ENOENT: ${p}`);
+      return v;
+    },
+  };
+}
+
+describe("linkedWorktreeName", () => {
+  it("returns null in the main worktree (.git is a directory)", () => {
+    const io = fakeIO({ "/r/.git": "dir" });
+    assert.equal(linkedWorktreeName("/r", io), null);
+    assert.equal(linkedWorktreeName("/r/src", io), null);
+  });
+
+  it("returns the worktree name for a linked worktree", () => {
+    const io = fakeIO({
+      "/r/.git": "dir",
+      "/wt/.git": "gitdir: /r/.git/worktrees/feature-x\n",
+    });
+    assert.equal(linkedWorktreeName("/wt", io), "feature-x");
+    assert.equal(linkedWorktreeName("/wt/src/nested", io), "feature-x");
+  });
+
+  it("resolves a relative gitdir pointer", () => {
+    const io = fakeIO({
+      "/r/.git": "dir",
+      "/wt/.git": "gitdir: ../r/.git/worktrees/rel-wt",
+    });
+    assert.equal(linkedWorktreeName("/wt", io), "rel-wt");
+  });
+
+  it("returns null for a submodule-style pointer", () => {
+    const io = fakeIO({
+      "/super/.git": "dir",
+      "/super/lib/.git": "gitdir: /super/.git/modules/lib",
+    });
+    assert.equal(linkedWorktreeName("/super/lib", io), null);
+  });
+
+  it("returns null for a non-pointer .git file", () => {
+    const io = fakeIO({ "/wt/.git": "garbage" });
+    assert.equal(linkedWorktreeName("/wt", io), null);
+  });
+
+  it("returns null outside any repo", () => {
+    assert.equal(linkedWorktreeName("/nowhere", fakeIO({})), null);
+  });
+});