@narumitw/pi-inspect 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@narumitw/pi-inspect",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Read-only browser inspector for Pi session context and live tool calls.",
+  "type": "module",
+  "license": "MIT",
+  "private": false,
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "session",
+    "inspector",
+    "context",
+    "observability"
+  ],
+  "files": [
+    "src",
+    "dist",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "check": "npm run build && biome check . && npm run typecheck",
+    "format": "biome check --write .",
+    "prepack": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --config vitest.config.ts",
+    "test:browser": "playwright test --config playwright.config.ts",
+    "smoke": "node scripts/smoke.mjs",
+    "smoke:git-install": "node scripts/git-install-smoke.mjs"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "dependencies": {
+    "@radix-ui/colors": "3.0.0",
+    "@radix-ui/react-collapsible": "1.1.20",
+    "@radix-ui/react-icons": "1.3.2",
+    "@radix-ui/themes": "3.3.0",
+    "esbuild": "0.28.2",
+    "react": "19.3.0",
+    "react-dom": "19.3.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "1.1.0",
+    "@earendil-works/pi-coding-agent": "1.1.0",
+    "@playwright/test": "1.63.0",
+    "@types/node": "26.6.4",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "typebox": "1.3.36",
+    "typescript": "7.0.2",
+    "vitest": "5.0.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/narumiruna/pi-extensions",
+    "directory": "packages/pi-inspect"
+  }
+}

package/src/ancestry.ts

@@ -0,0 +1,32 @@
+import type { ExtensionContext, SessionEntry } from "@earendil-works/pi-coding-agent";
+
+import { EntryIndex } from "./entry-index.js";
+import { structuralIssue } from "./identity.js";
+import { nativeProjection } from "./native-projection.js";
+
+// Pi's native projection walks parent links without cycle detection; validate before invoking it.
+export function ancestry(
+  manager: ExtensionContext["sessionManager"],
+  id: string,
+  index = new EntryIndex(manager.getEntries()),
+): { path: SessionEntry[]; issue?: string } {
+  const path: SessionEntry[] = [];
+  const seen = new Set<string>();
+  if (index.duplicates.has(id)) return { path: [], issue: "duplicate entry id" };
+  let current = index.get(id);
+  while (current) {
+    const issue = structuralIssue(current);
+    if (issue) return { path: path.reverse(), issue };
+    if (seen.has(current.id)) return { path: path.reverse(), issue: "recorded parent cycle" };
+    if (path.length >= 10000)
+      return { path: path.reverse(), issue: "ancestry exceeds the 10,000-entry inspection budget" };
+    seen.add(current.id);
+    path.push(current);
+    const parent = current.parentId;
+    if (parent && index.duplicates.has(parent)) return { path: path.reverse(), issue: "duplicate ancestor id" };
+    current = parent ? index.get(parent) : undefined;
+    if (parent && !current) return { path: path.reverse(), issue: "missing recorded parent" };
+  }
+  path.reverse();
+  return { path, issue: nativeProjection(path, id).issue };
+}

package/src/collector.ts

@@ -0,0 +1,143 @@
+import type {
+  ToolExecutionEndEvent,
+  ToolExecutionStartEvent,
+  ToolExecutionUpdateEvent,
+} from "@earendil-works/pi-coding-agent";
+import type { Call } from "./model.js";
+import { capture, displayText } from "./privacy.js";
+
+function validIdentity(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0 && value.length <= 512;
+}
+
+export class Collector {
+  readonly startedAt = Date.now();
+  private calls = new Map<string, Call>();
+  private partialAt = new Map<string, number>();
+  private sequence = 0;
+  dropped = 0;
+  invalidEvents = 0;
+  private admit(event: { toolCallId: string; toolName: string }): boolean {
+    if (validIdentity(event.toolCallId) && validIdentity(event.toolName)) return true;
+    this.invalidEvents++;
+    return false;
+  }
+  private fenceParent(call: Call, parent: unknown): boolean {
+    if (parent !== undefined && !validIdentity(parent)) {
+      const changed =
+        call.parentUnavailable !== "Invalid or over-budget parent ID; relationship unavailable" ||
+        call.parentOccurrenceId !== undefined;
+      call.parentId = undefined;
+      call.parentOccurrenceId = undefined;
+      call.parentUnavailable = "Invalid or over-budget parent ID; relationship unavailable";
+      return changed;
+    }
+    return false;
+  }
+  constructor(private readonly maxCalls = 128) {}
+  private create(
+    event: { toolCallId: string; parentToolCallId?: string; toolName: string },
+    args: unknown,
+    anchor: string | null,
+  ): Call {
+    const parentId = validIdentity(event.parentToolCallId) ? event.parentToolCallId : undefined;
+    const parent = parentId ? this.active(parentId) : undefined;
+    const ambiguousParent =
+      event.parentToolCallId !== undefined &&
+      this.list().filter((item) => item.id === event.parentToolCallId && item.status === "running").length > 1;
+    const call: Call = {
+      id: event.toolCallId,
+      occurrenceId: `call-${++this.sequence}`,
+      parentId,
+      parentUnavailable: ambiguousParent ? "Overlapping running parent IDs; relationship unavailable" : undefined,
+      parentOccurrenceId: parent?.status === "running" ? parent.occurrenceId : undefined,
+      name: displayText(event.toolName),
+      status: "running",
+      args: capture(args, 8192),
+      branchAnchor: parent?.status === "running" ? parent.branchAnchor : validIdentity(anchor) ? anchor : null,
+      correlationUnavailable: anchor !== null && !validIdentity(anchor) ? true : undefined,
+    };
+    this.fenceParent(call, event.parentToolCallId);
+    this.calls.set(call.occurrenceId, call);
+    while (this.calls.size > this.maxCalls) {
+      const first = this.calls.keys().next().value;
+      if (first === undefined) break;
+      this.calls.delete(first);
+      this.partialAt.delete(first);
+      this.dropped++;
+    }
+    return call;
+  }
+  private active(rawId: string): Call | undefined {
+    const running = this.list().filter((call) => call.id === rawId && call.status === "running");
+    if (running.length > 1) {
+      for (const call of running) call.correlationUnavailable = true;
+      return undefined;
+    }
+    return running[0];
+  }
+  start(event: ToolExecutionStartEvent, anchor: string | null): void {
+    if (!this.admit(event)) return;
+    const now = Date.now();
+    const call = this.create(event, event.args, anchor);
+    call.observedStartedAt = now;
+    if (
+      this.list().filter((parent) => parent.id === call.id && parent.branchAnchor === call.branchAnchor).length === 1
+    ) {
+      for (const child of this.calls.values())
+        if (
+          child.parentId === call.id &&
+          !child.parentOccurrenceId &&
+          !child.parentUnavailable &&
+          child.status === "running" &&
+          child.branchAnchor === call.branchAnchor
+        )
+          child.parentOccurrenceId = call.occurrenceId;
+    }
+    const occurrences = this.list().filter((item) => item.id === call.id && item.branchAnchor === call.branchAnchor);
+    if (occurrences.length > 1) {
+      for (const occurrence of occurrences) occurrence.correlationUnavailable = true;
+      for (let i = 0; i < this.calls.size; i++)
+        for (const child of this.calls.values())
+          if (child.parentOccurrenceId && this.calls.get(child.parentOccurrenceId)?.correlationUnavailable)
+            child.correlationUnavailable = true;
+    }
+    this.active(event.toolCallId); // Explicitly mark overlapping reused IDs as ambiguous, never misroute their results.
+  }
+  update(event: ToolExecutionUpdateEvent, anchor: string | null): boolean {
+    if (!this.admit(event)) return true; // Publish the new unavailable-event counter.
+    const now = Date.now();
+    let call = this.active(event.toolCallId);
+    if (!call && this.list().some((call) => call.id === event.toolCallId && call.status === "running")) return false;
+    call ??= this.create(event, event.args, anchor);
+    const parentChanged = this.fenceParent(call, event.parentToolCallId);
+    if (now - (this.partialAt.get(call.occurrenceId) ?? -Infinity) < 250) return parentChanged;
+    this.partialAt.set(call.occurrenceId, now);
+    call.result = capture(event.partialResult);
+    return true;
+  }
+  end(event: ToolExecutionEndEvent, anchor: string | null): void {
+    if (!this.admit(event)) return;
+    const now = Date.now();
+    const running = this.list().filter((call) => call.id === event.toolCallId && call.status === "running");
+    const call = this.active(event.toolCallId) ?? this.create(event, "[not captured]", anchor);
+    if (running.length > 1) {
+      call.correlationUnavailable = true;
+      call.parentOccurrenceId = undefined;
+    }
+    this.fenceParent(call, event.parentToolCallId);
+    call.status = event.isError ? "error" : "ok";
+    call.durationMs =
+      typeof event.durationMs === "number" && Number.isFinite(event.durationMs) && event.durationMs >= 0
+        ? event.durationMs
+        : undefined;
+    call.observedEndedAt = now;
+    call.result = capture(event.result);
+  }
+  settle(): void {
+    for (const call of this.calls.values()) if (call.status === "running") call.status = "unfinished";
+  }
+  list(): Call[] {
+    return [...this.calls.values()];
+  }
+}

package/src/context.ts

@@ -0,0 +1,115 @@
+import { createHash } from "node:crypto";
+import { buildSessionProjection, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { ancestry } from "./ancestry.js";
+import type { EntryIndex } from "./entry-index.js";
+import { recordedLeaf } from "./identity.js";
+import type { ContextComposition, ContextSegment, Json } from "./model.js";
+import { capture } from "./privacy.js";
+
+function object(value: Json | undefined): Record<string, Json> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+export function captureContext(
+  input: readonly unknown[],
+  source: ContextComposition["source"],
+  leafId: string | null,
+): ContextComposition {
+  const result: ContextComposition = {
+    source,
+    leafId,
+    totalMessages: input.length,
+    messages: [],
+    segments: [],
+    incomplete: false,
+  };
+  const occurrences = new Map<string, number>();
+  let budget = 1048576;
+  for (const message of input) {
+    if (result.segments.length >= 4000 || budget <= 64) {
+      result.incomplete = true;
+      break;
+    }
+    const raw = capture(message, Math.min(8192, budget));
+    const encoded = JSON.stringify(raw);
+    budget -= encoded.length;
+    result.incomplete ||= raw.truncated;
+    const data = object(raw.value);
+    const role = typeof data?.role === "string" ? data.role : "unknown";
+    const index = result.messages.length;
+    result.messages.push(raw);
+    const hash = createHash("sha256").update(encoded).digest("hex").slice(0, 20);
+    const occurrence = occurrences.get(hash) ?? 0;
+    occurrences.set(hash, occurrence + 1);
+    const content = data?.content === "" && data?.sections ? data.sections : data?.content;
+    const blocks = Array.isArray(content) && content.length ? content : [content ?? data?.sections ?? raw.value];
+    for (const [blockIndex, block] of blocks.entries()) {
+      if (result.segments.length >= 4000) {
+        result.incomplete = true;
+        break;
+      }
+      const item = object(block);
+      const kind = typeof item?.type === "string" ? item.type : role;
+      const category: ContextSegment["category"] =
+        role === "system" || role === "developer"
+          ? "system"
+          : role === "user"
+            ? "user"
+            : role === "toolResult" || role === "tool"
+              ? "toolResult"
+              : role === "assistant" && kind === "toolCall"
+                ? "toolCall"
+                : role === "assistant"
+                  ? "assistant"
+                  : "other";
+      const preview = item?.name ?? item?.text ?? item?.thinking ?? block;
+      const timestamp =
+        typeof data?.timestamp === "string"
+          ? data.timestamp
+          : typeof data?.timestamp === "number" &&
+              Number.isFinite(data.timestamp) &&
+              Math.abs(data.timestamp) < 8640000000000000
+            ? new Date(data.timestamp).toISOString()
+            : undefined;
+      result.segments.push({
+        id: `${source}-${hash}-${occurrence}-${blockIndex}`,
+        position: result.segments.length + 1,
+        messageIndex: index,
+        ...(Array.isArray(content) && content.length ? { blockIndex } : {}),
+        role,
+        kind,
+        category,
+        preview: (typeof preview === "string" ? preview : JSON.stringify(preview)).slice(0, 240),
+        ...(timestamp ? { timestamp } : {}),
+      });
+    }
+  }
+  result.incomplete ||= result.messages.length < input.length;
+  return result;
+}
+export function sessionContext(manager: ExtensionContext["sessionManager"], index: EntryIndex): ContextComposition {
+  const leafId = recordedLeaf(manager, index.duplicates);
+  const validation = leafId ? ancestry(manager, leafId, index) : { path: [], issue: "No unambiguous active leaf" };
+  if (validation.issue)
+    return {
+      source: "session-derived",
+      leafId,
+      totalMessages: 0,
+      messages: [],
+      segments: [],
+      incomplete: true,
+      unavailable: validation.issue,
+    };
+  try {
+    return captureContext(buildSessionProjection(validation.path, leafId).messages, "session-derived", leafId);
+  } catch {
+    return {
+      source: "session-derived",
+      leafId,
+      totalMessages: 0,
+      messages: [],
+      segments: [],
+      incomplete: true,
+      unavailable: "Native context projection unavailable",
+    };
+  }
+}

package/src/correlation.ts

@@ -0,0 +1,27 @@
+import type { Call } from "./model.js";
+
+// Occurrence IDs form the captured execution graph. Raw IDs are only used with an owning assistant anchor.
+export function correlatedCalls(rawIds: Set<string>, anchor: string | undefined, all: Call[]): Call[] {
+  if (!anchor) return [];
+  const multiplicity = new Map<string, number>();
+  for (const call of all)
+    if (call.branchAnchor === anchor) multiplicity.set(call.id, (multiplicity.get(call.id) ?? 0) + 1);
+  const ids = new Set(
+    all
+      .filter(
+        (call) =>
+          (rawIds.has(call.id) ||
+            (call.parentId !== undefined &&
+              rawIds.has(call.parentId) &&
+              (!call.parentOccurrenceId || !all.some((parent) => parent.occurrenceId === call.parentOccurrenceId)))) &&
+          call.branchAnchor === anchor &&
+          (!call.parentOccurrenceId || !all.some((parent) => parent.occurrenceId === call.parentOccurrenceId)) &&
+          !call.correlationUnavailable &&
+          (multiplicity.get(call.id) ?? 0) < 2,
+      )
+      .map((call) => call.occurrenceId),
+  );
+  for (let i = 0; i < all.length; i++)
+    for (const call of all) if (call.parentOccurrenceId && ids.has(call.parentOccurrenceId)) ids.add(call.occurrenceId);
+  return all.filter((call) => ids.has(call.occurrenceId));
+}

package/src/entry-index.ts

@@ -0,0 +1,17 @@
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+
+// Rebuilt only at structural boundaries, never once per inline request.
+export class EntryIndex {
+  readonly byId = new Map<string, SessionEntry>();
+  readonly duplicates = new Set<string>();
+  constructor(readonly entries: SessionEntry[]) {
+    for (const entry of entries)
+      if (typeof entry?.id === "string") {
+        if (this.byId.has(entry.id)) this.duplicates.add(entry.id);
+        this.byId.set(entry.id, entry);
+      }
+  }
+  get(id: string): SessionEntry | undefined {
+    return this.duplicates.has(id) ? undefined : this.byId.get(id);
+  }
+}

package/src/extension.ts

@@ -0,0 +1,259 @@
+import { randomUUID } from "node:crypto";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { ancestry } from "./ancestry.js";
+import { Collector } from "./collector.js";
+import { SessionFeed } from "./feed.js";
+import { recordedLeaf } from "./identity.js";
+import type { SkillView } from "./model.js";
+import { branch, detail } from "./projection.js";
+import { startServer, type ViewerServer } from "./server.js";
+
+interface Owner {
+  controller: AbortController;
+  generation: string;
+  feed?: SessionFeed;
+  ctx: ExtensionContext;
+  collector?: Collector;
+  skills: SkillView[];
+  server?: ViewerServer;
+  opening?: Promise<void>;
+}
+export interface Dependencies {
+  start: typeof startServer;
+  launch(pi: ExtensionAPI, url: string, signal: AbortSignal): Promise<boolean>;
+}
+const defaults: Dependencies = {
+  start: startServer,
+  async launch(pi, url, signal) {
+    const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "explorer.exe" : "xdg-open";
+    const result = await pi.exec(command, [url], { signal, timeout: 5000 });
+    return result.code === 0 && !result.killed;
+  },
+};
+
+export function registerInspector(pi: ExtensionAPI, deps: Dependencies = defaults): void {
+  const owners = new Map<ExtensionContext["sessionManager"], Owner>();
+  const epochs = new WeakMap<ExtensionContext["sessionManager"], object>();
+  function epochFor(ctx: ExtensionContext): object {
+    let epoch = epochs.get(ctx.sessionManager);
+    if (!epoch) {
+      epoch = {};
+      epochs.set(ctx.sessionManager, epoch);
+    }
+    return epoch;
+  }
+  const alive = (owner: Owner) => !owner.controller.signal.aborted && owners.get(owner.ctx.sessionManager) === owner;
+  async function stop(ctx: ExtensionContext): Promise<void> {
+    const owner = owners.get(ctx.sessionManager);
+    if (!owner) return;
+    owners.delete(ctx.sessionManager);
+    owner.controller.abort();
+    owner.feed?.close();
+    await owner.server?.close();
+    await owner.opening;
+    owner.collector = undefined;
+  }
+  function ownerFor(ctx: ExtensionContext): Owner {
+    epochFor(ctx);
+    let owner = owners.get(ctx.sessionManager);
+    if (!owner) {
+      owner = { controller: new AbortController(), generation: randomUUID(), ctx, skills: [] };
+      owners.set(ctx.sessionManager, owner);
+    }
+    owner.ctx = ctx;
+    return owner;
+  }
+  function changed(ctx: ExtensionContext, structural = true): Owner | undefined {
+    const owner = owners.get(ctx.sessionManager);
+    if (!owner || !alive(owner)) return;
+    owner.ctx = ctx;
+    owner.feed?.changed(structural);
+    return owner;
+  }
+  pi.on("session_start", async (_event, ctx) => {
+    const epoch = {};
+    epochs.set(ctx.sessionManager, epoch);
+    await stop(ctx);
+    if (epochs.get(ctx.sessionManager) === epoch) ownerFor(ctx);
+  });
+  pi.on("session_shutdown", async (_event, ctx) => {
+    epochs.delete(ctx.sessionManager);
+    await stop(ctx);
+  });
+  // Observation only: never return or mutate messages/payload; later hooks may still transform them.
+  pi.on("context_with_system", (event, ctx) => {
+    const owner = owners.get(ctx.sessionManager);
+    if (owner?.collector && alive(owner)) {
+      owner.ctx = ctx;
+      owner.feed?.observeContext(event.messages);
+    }
+  });
+  pi.on("before_provider_request", (event, ctx) => {
+    const owner = owners.get(ctx.sessionManager);
+    if (owner?.collector && alive(owner)) owner.feed?.observePayload(event.payload);
+  });
+  pi.on("message_end", (_event, ctx) => {
+    changed(ctx);
+  });
+  pi.on("session_tree", (_event, ctx) => {
+    changed(ctx);
+  });
+  pi.on("session_compact", (_event, ctx) => {
+    changed(ctx);
+  });
+  pi.on("session_info_changed", (_event, ctx) => {
+    changed(ctx);
+  });
+  pi.on("model_select", (_event, ctx) => {
+    changed(ctx);
+  });
+  pi.on("thinking_level_select", (_event, ctx) => {
+    changed(ctx);
+  });
+  function executionAnchor(ctx: ExtensionContext, rawId: string): string | null {
+    const index = owners.get(ctx.sessionManager)?.feed?.index();
+    const leaf = recordedLeaf(ctx.sessionManager, index?.duplicates);
+    const entry = ctx.sessionManager.getLeafEntry();
+    if (leaf && entry?.type === "message" && entry.message.role === "assistant") return leaf;
+    return (
+      (leaf ? ancestry(ctx.sessionManager, leaf, index).path : [])
+        .slice()
+        .reverse()
+        .find(
+          (entry) =>
+            entry.type === "message" &&
+            entry.message.role === "assistant" &&
+            (Array.isArray(entry.message.content) ? entry.message.content : []).some(
+              (block) => block.type === "toolCall" && block.id === rawId,
+            ),
+        )?.id ?? leaf
+    );
+  }
+  pi.on("tool_execution_start", (event, ctx) => {
+    const owner = owners.get(ctx.sessionManager);
+    owner?.collector?.start(event, executionAnchor(ctx, event.toolCallId));
+    changed(ctx, false);
+  });
+  pi.on("tool_execution_update", (event, ctx) => {
+    const owner = owners.get(ctx.sessionManager);
+    if (owner?.collector?.update(event, recordedLeaf(ctx.sessionManager, owner?.feed?.index().duplicates)))
+      changed(ctx, false);
+  });
+  pi.on("tool_execution_end", (event, ctx) => {
+    const owner = owners.get(ctx.sessionManager);
+    owner?.collector?.end(event, executionAnchor(ctx, event.toolCallId));
+    changed(ctx, false);
+  });
+  pi.on("agent_settled", (_event, ctx) => {
+    owners.get(ctx.sessionManager)?.collector?.settle();
+    changed(ctx, false);
+  });
+
+  async function open(owner: Owner, ctx: ExtensionCommandContext): Promise<void> {
+    try {
+      if (!owner.server) {
+        const accepted = await ctx.ui.confirm(
+          "Open Session Inspector?",
+          "Serve this session's prompts, code and tool outputs to a local browser and record bounded context, provider payload and child results in memory? Redaction is incomplete. Nothing is uploaded or saved.",
+          { signal: owner.controller.signal },
+        );
+        if (!alive(owner) || !accepted) return;
+        const options = ctx.getSystemPromptOptions();
+        owner.skills = (options.skills ?? [])
+          .slice(0, 257) // One sentinel lets the snapshot disclose an incomplete catalog.
+          .map((s) => ({ name: s.name, path: s.filePath, description: s.description }));
+        owner.collector = new Collector();
+        owner.feed = new SessionFeed({
+          pi,
+          context: () => owner.ctx,
+          collector: owner.collector,
+          skills: owner.skills,
+          generation: owner.generation,
+          signal: owner.controller.signal,
+          invalidate: (revision) => {
+            if (alive(owner)) owner.server?.invalidate(revision);
+          },
+        });
+        const server = await deps.start({
+          generation: owner.generation,
+          signal: owner.controller.signal,
+          snapshot: () => owner.feed?.snapshot(),
+          branch: (id, offset) => branch(ctx.sessionManager, id, offset, owner.skills, owner.feed?.index()),
+          detail: (id, leaf) =>
+            detail(ctx.sessionManager, id, leaf, owner.collector ?? new Collector(), owner.feed?.index()),
+        });
+        if (!alive(owner)) {
+          await server.close();
+          return;
+        }
+        owner.server = server;
+        owner.feed.start();
+      }
+      if (!alive(owner)) return;
+      const url = owner.server.url;
+      let launched = false;
+      try {
+        launched = await deps.launch(pi, url, owner.controller.signal);
+      } catch {
+        /* URL fallback; no command stderr or token logging. */
+      }
+      if (!alive(owner)) return;
+      ctx.ui.notify(
+        `${launched ? "Session Inspector" : "Browser unavailable; open privately"}:\n${url}\n/inspect stop revokes this URL.`,
+        launched ? "info" : "warning",
+      );
+    } catch {
+      if (!alive(owner)) return;
+      owner.collector = undefined;
+      owner.feed?.close();
+      owner.feed = undefined;
+      await owner.server?.close();
+      owner.server = undefined;
+      if (alive(owner))
+        ctx.ui.notify(
+          "Could not open Session Inspector. Build its browser assets first; see the local README.",
+          "error",
+        );
+    }
+  }
+
+  const command: Parameters<ExtensionAPI["registerCommand"]>[1] = {
+    description: "Open a private, read-only live session web inspector",
+    getArgumentCompletions: (prefix) =>
+      ["stop"].filter((s) => s.startsWith(prefix)).map((value) => ({ value, label: value })),
+    handler: async (args, ctx) => {
+      const route = args.trim();
+      if (route !== "" && route !== "stop") {
+        if (ctx.hasUI) {
+          ctx.ui.notify("Usage: /inspect [stop]", "warning");
+          return;
+        }
+        throw new Error("Usage: /inspect [stop]");
+      }
+      if (route === "stop") {
+        const epoch = epochFor(ctx);
+        await stop(ctx);
+        if (ctx.hasUI && epochs.get(ctx.sessionManager) === epoch)
+          ctx.ui.notify("Session Inspector stopped; URL revoked.", "info");
+        return;
+      }
+      if (ctx.mode !== "tui") {
+        if (ctx.hasUI) {
+          ctx.ui.notify("Opening Session Inspector requires TUI mode. Stop remains available.", "warning");
+          return;
+        }
+        throw new Error("Opening Session Inspector requires TUI mode.");
+      }
+      const owner = ownerFor(ctx);
+      if (owner.opening) return;
+      owner.opening = open(owner, ctx);
+      try {
+        await owner.opening;
+      } finally {
+        owner.opening = undefined;
+      }
+    },
+  };
+  pi.registerCommand("inspect", command);
+  pi.registerCommand("session-inspector", command); // Compatibility route, same ownership and mode guards.
+}