@jaggerxtrm/pi-extensions 0.9.0 → 0.9.2

package/extensions/serena-pool/index.ts

@@ -371,6 +371,8 @@ export const __internals = {
   getProcessStartTime,
   findProcessesByPgid,
   getRepoRoot,
+  isInsideGitRepo,
+  resolveSessionCwd,
   readState,
   writeState,
   removeState,
@@ -379,9 +381,51 @@ export const __internals = {
 };
 export type { PoolState };
 
+/** True when `cwd` is inside a git work tree (cheap synchronous probe). */
+function isInsideGitRepo(cwd: string): boolean {
+  try {
+    return (
+      execFileSync("git", ["rev-parse", "--is-inside-work-tree"], {
+        cwd,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      }).trim() === "true"
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve the cwd to bind the Serena daemon to.
+ *
+ * Why: pi's ctx.cwd is captured at session_start emission and can be a stale
+ * snapshot — most notably the parent repo when session_start fires before
+ * pi's own cwd has settled into the linked worktree the session actually runs
+ * in. The launcher (cli worktree-session) spawns pi with `cwd: worktreePath`,
+ * so `process.cwd()` is the live ground truth. The old `ctx?.cwd ??
+ * process.cwd()` form silently trusted a stale ctx.cwd because `??` only
+ * falls through on nullish — never when ctx.cwd is present-but-wrong. That
+ * produced a wrong hashToPort → daemon bound to the parent repo's --project →
+ * the next correct-cwd session found no listener on its expected port and
+ * spawned a SECOND daemon, leaving the first as an orphan (KAN-110-A).
+ *
+ * Resolution: when ctx.cwd and the live cwd disagree, trust the live cwd only
+ * if it is itself inside a git work tree — so we never bind the daemon to an
+ * unrelated process.cwd() (e.g. a test runner in /tmp). getRepoRoot then maps
+ * the worktree cwd to its true toplevel via `git rev-parse --show-toplevel`,
+ * which already returns the linked-worktree root, not the common dir.
+ */
+function resolveSessionCwd(ctxCwd: string | undefined): string {
+  const procCwd = process.cwd();
+  if (!ctxCwd) return procCwd;
+  if (ctxCwd === procCwd) return ctxCwd;
+  return isInsideGitRepo(procCwd) ? procCwd : ctxCwd;
+}
+
 export default function registerSerenaPool(pi: ExtensionAPI) {
   pi.on("session_start", async (_event: unknown, ctx: any) => {
-    const cwd: string = ctx?.cwd ?? process.cwd();
+    const cwd: string = resolveSessionCwd(ctx?.cwd);
     let projectRoot: string;
     try {
       projectRoot = getRepoRoot(cwd);

package/extensions/serena-pool/test/e2e.ts

@@ -8,21 +8,25 @@
  *
  * Requires: `uvx` on PATH (the real Serena spawn path is exercised).
  *
- * Five scenarios:
+ * Six scenarios:
  *   1. cold start         — clean slate → spawn, port listens, state written
  *   2. warm reuse         — second call → same pid, same state
  *   3. dead recovery      — kill Serena → next call spawns fresh
  *   4. synthetic orphans  — fake state pointing at a detached `sleep` group
  *                           with dead leader → cleanup kills group members
  *   5. concurrent spawn   — 5 parallel calls → exactly one Serena alive
+ *   6. cwd-race           — stale ctx.cwd (parent repo) vs live process.cwd()
+ *                           (linked worktree) → daemon binds to the worktree,
+ *                           no orphan against the parent. Uses real
+ *                           `git worktree add`.
  */
 import { spawn, spawnSync } from "node:child_process";
-import { mkdtempSync, rmSync, existsSync, readdirSync } from "node:fs";
+import { mkdtempSync, mkdirSync, rmSync, existsSync, readdirSync, realpathSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
 
-import {
+import registerSerenaPool, {
   ensureSerenaForRoot,
   STATE_DIR,
   __internals as I,
@@ -83,6 +87,29 @@ async function withTestRoot(fn: (root: string, port: number) => Promise<void>):
   }
 }
 
+function git(cwd: string, args: string[]): void {
+  const r = spawnSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+  if (r.status !== 0) {
+    throw new Error(`git ${args.join(" ")} failed in ${cwd}: ${(r.stderr || "").trim()}`);
+  }
+}
+
+type SessionStartCtx = { cwd?: string };
+type SessionStartHandler = (event: unknown, ctx: SessionStartCtx) => Promise<void>;
+
+/** Register the extension against a fake pi and capture its session_start handler. */
+function captureSessionStartHandler(): SessionStartHandler {
+  let captured: SessionStartHandler | null = null;
+  const fakePi = {
+    on(event: string, handler: SessionStartHandler) {
+      if (event === "session_start") captured = handler;
+    },
+  };
+  registerSerenaPool(fakePi as never);
+  if (!captured) throw new Error("registerSerenaPool did not register a session_start handler");
+  return captured;
+}
+
 async function test1_coldStart(): Promise<void> {
   header("1. cold start");
   await withTestRoot(async (root, expectedPort) => {
@@ -197,6 +224,77 @@ async function test5_concurrentSpawn(): Promise<void> {
   });
 }
 
+async function test6_cwdRace(): Promise<void> {
+  header("6. cwd-race (stale ctx.cwd resolves to live worktree)");
+  // Reproduce KAN-110-A: registerSerenaPool fires session_start with a ctx.cwd
+  // captured stale as the parent repo, while pi's LIVE process.cwd() is the
+  // linked worktree the session is actually running in. Uses a REAL
+  // `git worktree add` (not a bare mkdtemp) so git's worktree semantics are
+  // exercised end-to-end.
+  const tmpBase = mkdtempSync(join(tmpdir(), "serena-pool-race-"));
+  const parent = join(tmpBase, "parent");
+  const worktreeAbs = join(tmpBase, "wt");
+  mkdirSync(parent, { recursive: true });
+
+  const spawnedPorts: number[] = [];
+  const prevCwd = process.cwd();
+  const prevEnvPort = process.env.SERENA_MCP_PORT;
+  try {
+    cleanState();
+    git(parent, ["init", "-q"]);
+    git(parent, ["config", "user.email", "serena-pool-e2e@xtrm.local"]);
+    git(parent, ["config", "user.name", "serena-pool e2e"]);
+    git(parent, ["commit", "--allow-empty", "-q", "-m", "init"]);
+    // REAL linked worktree — git creates worktreeAbs.
+    git(parent, ["worktree", "add", "-q", worktreeAbs]);
+
+    const parentReal = realpathSync(parent);
+    const worktreeReal = realpathSync(worktreeAbs);
+    const expectedPort = I.hashToPort(worktreeReal);
+    const parentPort = I.hashToPort(parentReal);
+    spawnedPorts.push(expectedPort, parentPort);
+    assert(
+      expectedPort !== parentPort,
+      `worktree port (${expectedPort}) differs from parent port (${parentPort})`,
+    );
+
+    // Simulate the race: pi's LIVE cwd is the worktree (launcher guarantee),
+    // but ctx.cwd was captured stale as the parent repo.
+    process.chdir(worktreeReal);
+    const handler = captureSessionStartHandler();
+    await handler({}, { cwd: parentReal });
+
+    const state = I.readState(expectedPort);
+    assert(state != null, "state written at the worktree's port (not the parent's)");
+    assert(
+      state != null && state.projectRoot === worktreeReal,
+      `daemon --project === worktree root (got ${state?.projectRoot})`,
+    );
+    assert(
+      state != null && state.projectRoot !== parentReal,
+      "daemon --project is NOT the stale parent repo",
+    );
+    assert(state != null && I.isPidAlive(state.pid), "spawned Serena pid alive");
+
+    // No orphan daemon bound to the stale parent's port.
+    const orphan = I.readState(parentPort);
+    assert(orphan == null, "no daemon state written against the stale parent port");
+
+    // Env wiring reflects the worktree port.
+    assert(
+      process.env.SERENA_MCP_PORT === String(expectedPort),
+      `SERENA_MCP_PORT wired to worktree port ${expectedPort}`,
+    );
+  } finally {
+    for (const p of spawnedPorts) killSerenaForPort(p);
+    try { process.chdir(prevCwd); } catch { /* ignore */ }
+    try { git(parent, ["worktree", "remove", "--force", worktreeAbs]); } catch { /* parent may be gone */ }
+    rmSync(tmpBase, { recursive: true, force: true });
+    if (prevEnvPort === undefined) delete process.env.SERENA_MCP_PORT;
+    else process.env.SERENA_MCP_PORT = prevEnvPort;
+  }
+}
+
 async function main(): Promise<void> {
   console.log("serena-pool e2e driver\n");
   if (!preflight()) process.exit(2);
@@ -207,6 +305,7 @@ async function main(): Promise<void> {
     test3_deadDaemonRecovery,
     test4_syntheticOrphanCleanup,
     test5_concurrentSpawn,
+    test6_cwdRace,
   ];
 
   for (const t of tests) {

package/extensions/xtprompt/index.ts

@@ -0,0 +1,422 @@
+/**
+ * xtprompt - context aware prompt improver.
+ *
+ * Global Pi extension. Shortcut: alt+m  (alt+p intentionally avoided to not
+ * collide with pi-promptsmith if both are installed). Command: /msmith
+ *
+ * Rewrites the current editor draft via a standalone model call (the active
+ * model), using anthropic + xtrm/planning-aware intent templates + hard style rules, then writes
+ * the improved prompt back into the editor. The main agent turn never runs
+ * during the rewrite.
+ */
+import { complete } from "@earendil-works/pi-ai";
+import type {
+  Api,
+  AssistantMessage,
+  Context,
+  Model,
+  UserMessage,
+} from "@earendil-works/pi-ai";
+import {
+  BorderedLoader,
+  type ExtensionAPI,
+  type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+
+const EXTENSION = "mercury-smith";
+const COMMAND = "msmith";
+const DEFAULT_SHORTCUT = "alt+m";
+
+const SENTINEL_OPEN = "<mercury-smith>";
+const SENTINEL_CLOSE = "</mercury-smith>";
+
+const ENHANCER_MAX_OUTPUT_TOKENS = 1600;
+const DEFAULT_TIMEOUT_MS = 45_000;
+
+type Intent =
+  | "pane-dispatch"
+  | "specialist"
+  | "bead"
+  | "scope-plan"
+  | "debug"
+  | "generic";
+
+interface SmithState {
+  enabled: boolean;
+}
+
+function createState(): SmithState {
+  return { enabled: true };
+}
+
+export default function mercurySmith(pi: ExtensionAPI): void {
+  const state = createState();
+
+  const enhance = async (ctx: ExtensionContext): Promise<void> => {
+    if (!state.enabled) {
+      ctx.ui.notify(`${EXTENSION} is disabled. Run /${COMMAND} on`, "info");
+      return;
+    }
+    if (!ctx.hasUI) {
+      ctx.ui.notify(`${EXTENSION} needs the interactive TUI.`, "error");
+      return;
+    }
+    const draft = ctx.ui.getEditorText();
+    if (!draft.trim()) {
+      ctx.ui.notify(`${EXTENSION}: editor is empty — nothing to rewrite.`, "info");
+      return;
+    }
+    const model = ctx.model;
+    if (!model) {
+      ctx.ui.notify(`${EXTENSION}: no active model selected.`, "error");
+      return;
+    }
+
+    const intent = detectIntent(draft);
+    const envContext = await gatherContext(pi).catch(() => "") ?? "";
+    const systemPrompt = buildSystemPrompt(intent, envContext);
+
+    const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+    if (!auth.ok) {
+      ctx.ui.notify(`${EXTENSION}: cannot resolve API key — ${auth.error}`, "error");
+      return;
+    }
+
+    const userMessage: UserMessage = {
+      role: "user",
+      content: draft,
+      timestamp: Date.now(),
+    };
+    const request: Context = {
+      systemPrompt,
+      messages: [userMessage],
+    };
+
+    const outcome = await runWithLoader(
+      ctx,
+      `${EXTENSION} rewriting (${intent})…`,
+      async (signal) => {
+        const primary = await callModel(model, request, auth, signal);
+        if (primary === null) return null;
+        const text = extractText(primary);
+        const parsed = parseSentinel(text);
+        if (parsed !== undefined) return parsed;
+        // retry once with a harder format reminder
+        const retried = await callModel(model, retryRequest(request), auth, signal);
+        if (retried === null) return null;
+        const parsed2 = parseSentinel(extractText(retried));
+        if (parsed2 !== undefined) return parsed2;
+        throw new Error(
+          `${EXTENSION}: model did not return the ${SENTINEL_OPEN} block after a retry. Leaving editor unchanged.`,
+        );
+      },
+    ).catch((err: unknown) => {
+      ctx.ui.notify(err instanceof Error ? err.message : String(err), "error");
+      return null;
+    });
+
+    if (outcome === null) return;
+    ctx.ui.setEditorText(outcome);
+    ctx.ui.notify(`${EXTENSION}: enhanced (${intent}).`, "info");
+  };
+
+  pi.registerShortcut(DEFAULT_SHORTCUT, {
+    description: `Rewrite the current editor draft (${EXTENSION})`,
+    handler: enhance,
+  });
+
+  pi.registerCommand(COMMAND, {
+    description: `${EXTENSION}: rewrite the current editor prompt`,
+    handler: async (args, ctx) => {
+      const arg = (args ?? "").trim().toLowerCase();
+      if (arg === "on") {
+        state.enabled = true;
+        ctx.ui.notify(`${EXTENSION} enabled.`, "info");
+        return;
+      }
+      if (arg === "off") {
+        state.enabled = false;
+        ctx.ui.notify(`${EXTENSION} disabled.`, "info");
+        return;
+      }
+      if (arg === "status") {
+        ctx.ui.notify(
+          `${EXTENSION}: ${state.enabled ? "enabled" : "disabled"} · shortcut ${DEFAULT_SHORTCUT} · /${COMMAND}`,
+          "info",
+        );
+        return;
+      }
+      await enhance(ctx);
+    },
+  });
+}
+
+/* ------------------------------------------------------------------ intent */
+
+interface IntentRule {
+  intent: Intent;
+  patterns: RegExp[];
+}
+
+const INTENT_RULES: IntentRule[] = [
+  {
+    intent: "pane-dispatch",
+    patterns: [
+      /\bmultiplex(?:ing)?\b/,
+      /\bpane\b/,
+      /\bdispatch(?:ed)?\b/,
+      /\borchestrat(?:e|or|ion)\b/,
+      /\bsubordinate\b/,
+      /\bjudge\b/,
+      /\bdeploy monitor(?:ing)?\b/,
+      /\btmux\b/,
+      /\bsend .*to (?:pane|session|agent)\b/i,
+    ],
+  },
+  {
+    intent: "specialist",
+    patterns: [
+      /\bspecialist\b/,
+      /\bexecutor\b/,
+      /\breviewer\b/,
+      /\bexplorer\b/,
+      /\bdebugger\b/,
+      /\bsp (?:run|script|serve|node)\b/,
+      /\busing-specialists\b/,
+      /\bquant-methodologist\b/,
+      /\bquant-researcher\b/,
+      /\bspecialist chain\b/i,
+    ],
+  },
+  {
+    intent: "bead",
+    patterns: [
+      /\bbead\b/i,
+      /\bbd (?:create|update|close|show|dep)\b/,
+      /\b--parent\b/,
+      /\b--claim\b/,
+      /\bepic\b/i,
+      /\bacceptance criteria\b/i,
+      /\b7-section\b/i,
+      /\bPROBLEM\b/,
+      /\bSUCCESS\b/,
+      /\bNON_GOALS\b/,
+      /\bVALIDATION\b/,
+    ],
+  },
+  {
+    intent: "scope-plan",
+    patterns: [
+      /\bplanning\b/,
+      /\bscope(?: out| this)?\b/i,
+      /\barchitect(?:ure)?\b/,
+      /\bbreak (?:this )?down\b/i,
+      /\bdecompos(?:e|ition)\b/,
+      /\broadmap\b/,
+      /\bphase structure\b/i,
+    ],
+  },
+  {
+    intent: "debug",
+    patterns: [
+      /\bdebug\b/,
+      /\bfix\b/,
+      /\bbug\b/i,
+      /\bbroken\b/,
+      /\bfail(?:s|ed|ing)?\b/,
+      /\bcrash(?:es|ing)?\b/,
+      /\broot cause\b/i,
+      /\btraceback\b/,
+      /\bstack trace\b/i,
+      /\bregression\b/i,
+    ],
+  },
+];
+
+function detectIntent(draft: string): Intent {
+  const text = draft.toLowerCase();
+  for (const rule of INTENT_RULES) {
+    if (rule.patterns.some((p) => p.test(text))) return rule.intent;
+  }
+  return "generic";
+}
+
+/* ----------------------------------------------------------- system prompt */
+
+const MERCURY_RULES = [
+  "Target environment: Mercury market-data (futures analytics service stack).",
+  "1. mmd-api and mmd-mcp-server NEVER compute — they read pre-computed snapshots only; all analytics are produced by the feed services (mmd-snapshot-feed).",
+  "2. Always parameterize SQL (params={'symbol': symbol}); never f-string user input into queries.",
+  "3. Modern type hints (dict[str, Any], list[Foo]); imports use the new layout (from analytics... import, from api... import).",
+  "4. Every analytic family must be wrapped in compute(analytic_family=...); adding one without the wrap is contract drift.",
+  "5. Default to no comments; add one only when the WHY is non-obvious.",
+  "6. analytics/ is pure calc — no I/O, no datetime.now() at module scope, no DB access.",
+  "7. Use bd (beads) for ALL task tracking; create follow-ups with `bd create --parent <id>` so they never get lost.",
+  "8. Keep work tightly scoped to what is asked; flag unknowns explicitly rather than inventing requirements.",
+].join("\n");
+
+const INTENT_TEMPLATES: Record<Intent, string> = {
+  "pane-dispatch":
+    "Rewrite this as a crisp, self-contained instruction for a subordinate agent running in one tmux pane of a multiplexed session. The instruction MUST include: (a) the pane's role and explicitly what it is NOT (helper vs orchestrator), (b) the exact first action, (c) observable success criteria, (d) the escalation/notify rule — when to surface back to the orchestrator and how, (e) the communication protocol in priority order: temp files / structured notes > beads updates > direct notify. Make it dependency-aware: state what this pane must wait for and what it produces for other panes.",
+  specialist:
+    "Rewrite this as a specialist dispatch contract suitable for `sp run` / using-specialists-v3. MUST include: the specialist role needed (executor / reviewer / explorer / debugger / quant-methodologist / quant-researcher), a precise task scope (files and symbols), explicit success criteria, the verification the specialist must run, and the OUTPUT the specialist hands back. Scope it to a single chain step.",
+  bead:
+    "Rewrite this as a well-formed beads issue description using the 7-section contract, with these exact section headers: ## PROBLEM, ## SUCCESS, ## SCOPE, ## NON_GOALS, ## CONSTRAINTS, ## VALIDATION, ## OUTPUT. Make every section concrete and observable. Include a logging/telemetry note in CONSTRAINTS or VALIDATION where relevant, and at least one smoke/integration check in VALIDATION. No placeholder text. Preserve every concrete detail (bead ids, file paths, symbol names) from the original.",
+  "scope-plan":
+    "Rewrite this as a structured plan: distinct phases (P0 scaffold → P1 core → P2 integration), the dependencies between them, what can run in parallel, the top risks, and a short blast-radius summary. Keep it scoped; flag unknowns explicitly.",
+  debug:
+    "Rewrite this as a focused debugging prompt: state the symptom precisely, the reproduction/observation steps already taken, the most likely suspect code paths, and what evidence to gather before changing code. Bias toward read-only investigation first (logs, Tempo traces, profiling) before any fix.",
+  generic:
+    "Rewrite this prompt to be clearer, more direct, and better structured for a coding agent: explicit goal, constraints, and success criteria up front. Preserve every concrete detail (paths, ids, numbers). Remove vagueness and filler. Do not add requirements not implied by the original.",
+};
+
+const OUTPUT_CONTRACT = [
+  `Return ONLY the rewritten prompt wrapped in exactly one sentinel block: ${SENTINEL_OPEN} ... ${SENTINEL_CLOSE}.`,
+  "No markdown code fences, no commentary, no text before or after the sentinel block.",
+  "Preserve EVERY concrete detail from the original: file paths, symbol names, bead ids, commands, numbers, constraints.",
+  "Do not invent new requirements or details that are not implied by the original draft.",
+].join("\n");
+
+function buildSystemPrompt(intent: Intent, envContext: string): string {
+  return [
+    `You are ${EXTENSION}, an intent-aware prompt rewriter for the Mercury/xtrm coding environment.`,
+    "",
+    "Detected intent: " + intent,
+    INTENT_TEMPLATES[intent],
+    "",
+    "Hard style rules the rewritten prompt must respect where applicable:",
+    MERCURY_RULES,
+    envContext ? "\nActive context (advisory — use only if relevant):\n" + envContext : "",
+    "OUTPUT CONTRACT:",
+    OUTPUT_CONTRACT,
+  ].join("\n");
+}
+
+/* -------------------------------------------------------------- context */
+
+async function gatherContext(pi: ExtensionAPI): Promise<string> {
+  const lines: string[] = [];
+  const branch = await readExec(pi, "git", ["rev-parse", "--abbrev-ref", "HEAD"]);
+  if (branch) lines.push("- git branch: " + branch);
+  const bead = await readExec(pi, "bd", ["list", "--status=in_progress"]);
+  if (bead) {
+    const first = bead.split("\n").find((l) => l.trim());
+    if (first) lines.push("- active bead: " + first.trim().slice(0, 120));
+  }
+  return lines.join("\n");
+}
+
+async function readExec(
+  pi: ExtensionAPI,
+  cmd: string,
+  args: string[],
+): Promise<string | undefined> {
+  try {
+    const r = await Promise.race([
+      pi.exec(cmd, args, { timeout: 4000 }),
+      new Promise<never>((_, rej) =>
+        setTimeout(() => rej(new Error("timeout")), 4500),
+      ),
+    ]);
+    const out = ((r.stdout ?? "") + (r.stderr ?? "")).trim();
+    return out || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/* ----------------------------------------------------------- model calls */
+
+interface AuthOk {
+  apiKey?: string;
+  headers?: Record<string, string>;
+}
+
+async function callModel(
+  model: Model<Api>,
+  request: Context,
+  auth: AuthOk,
+  signal: AbortSignal,
+): Promise<AssistantMessage | null> {
+  const timeoutCtl = new AbortController();
+  const t = setTimeout(() => timeoutCtl.abort(), DEFAULT_TIMEOUT_MS);
+  const sig = AbortSignal.any([signal, timeoutCtl.signal]);
+  try {
+    const res = await Promise.race<AssistantMessage | null>([
+      complete(model, request, {
+        ...(auth.apiKey ? { apiKey: auth.apiKey } : {}),
+        ...(auth.headers ? { headers: auth.headers } : {}),
+        signal: sig,
+        maxTokens: Math.min(model.maxTokens, ENHANCER_MAX_OUTPUT_TOKENS),
+      }),
+      abortGuard(signal, null),
+    ]);
+    return res;
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+function retryRequest(request: Context): Context {
+  const last = request.messages.at(-1);
+  const baseText = last && typeof last.content === "string" ? last.content : "";
+  const reminder = `\n\nIMPORTANT: reply with exactly one ${SENTINEL_OPEN} block and nothing else (no fences, no commentary).`;
+  const reminded: UserMessage = {
+    role: "user",
+    content: baseText + reminder,
+    timestamp: Date.now(),
+  };
+  return { ...request, messages: [...request.messages.slice(0, -1), reminded] };
+}
+
+function abortGuard<T>(signal: AbortSignal, value: T): Promise<T> {
+  if (signal.aborted) return Promise.resolve(value);
+  return new Promise<T>((resolve) =>
+    signal.addEventListener("abort", () => resolve(value), { once: true }),
+  );
+}
+
+function extractText(msg: AssistantMessage): string {
+  return msg.content
+    .filter((p): p is { type: "text"; text: string } => p.type === "text")
+    .map((p) => p.text)
+    .join("\n")
+    .trim();
+}
+
+function parseSentinel(text: string): string | undefined {
+  const start = text.indexOf(SENTINEL_OPEN);
+  const end = text.lastIndexOf(SENTINEL_CLOSE);
+  if (start === -1 || end === -1 || end <= start) return undefined;
+  const inner = text.slice(start + SENTINEL_OPEN.length, end).trim();
+  return inner || undefined;
+}
+
+/* --------------------------------------------------------------- loader */
+
+async function runWithLoader(
+  ctx: ExtensionContext,
+  message: string,
+  task: (signal: AbortSignal) => Promise<string | null>,
+): Promise<string | null> {
+  let taskError: Error | undefined;
+  const result = await ctx.ui.custom<string | null>((tui, theme, _kb, done) => {
+    const loader = new BorderedLoader(tui, theme, message, { cancellable: true });
+    loader.onAbort = () => done(null);
+    void task(loader.signal)
+      .then((r) => {
+        if (!loader.signal.aborted) done(r);
+      })
+      .catch((err: unknown) => {
+        if (loader.signal.aborted) {
+          done(null);
+          return;
+        }
+        taskError = err instanceof Error ? err : new Error(`${EXTENSION} failed.`);
+        done(null);
+      });
+    return loader;
+  });
+  if (taskError) throw taskError;
+  return result;
+}

package/extensions/xtprompt/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@xtrm/pi-xtprompt",
+  "version": "0.1.0",
+  "description": "xtrm Pi extension: context-aware prompt improver (mercury-smith)",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "keywords": [
+    "pi",
+    "extension",
+    "xtrm",
+    "prompt"
+  ],
+  "author": "xtrm",
+  "license": "MIT",
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

package/extensions/xtrm-ui/index.ts

@@ -1363,6 +1363,37 @@ function withXtrmToolDetails(details: unknown, sourceText: string, toolName: str
 
 const XTRM_BUILTIN_TOOLS = new Set(["bash", "read", "edit", "write", "find", "grep", "ls"]);
 
+// Tools whose RESULT PAYLOAD the model needs verbatim in context. In pi, a tool_result
+// hook's return value REPLACES the model-facing content (not just the TUI render), so
+// compacting these would replace the model-facing payload with "· N lines" / "· N results"
+// for every pi surface that loads xtrm-ui — interactive sessions (where the human can
+// expand the TUI row but the model cannot) and any headless pi run that doesn't pass
+// --no-extensions. Specialists are unaffected: they run with --no-extensions and never
+// load xtrm-ui (selectively re-attach only quality-gates / service-skills / pi-gitnexus /
+// pi-serena-tools). Mutation/no-payload tools are still summarized below, preserving
+// most of the token savings.
+const PAYLOAD_TOOLS = new Set<string>([
+  // Serena reads / inspection
+  "read_file",
+  "find_symbol",
+  "find_referencing_symbols",
+  "get_symbols_overview",
+  "search_for_pattern",
+  "find_file",
+  "list_dir",
+  "read_memory",
+  // JetBrains backend equivalents
+  "jet_brains_find_symbol",
+  "jet_brains_find_referencing_symbols",
+  "jet_brains_get_symbols_overview",
+  "jet_brains_type_hierarchy",
+  // GitNexus reads (same blindness risk)
+  "gitnexus_query",
+  "gitnexus_context",
+  "gitnexus_impact",
+  "gitnexus_detect_changes",
+]);
+
 function registerXtrmUiTools(pi: ExtensionAPI, getPrefs: () => XtrmUiPrefs): void {
   const activeToolCalls = new Map<string, string>();
 
@@ -1413,6 +1444,9 @@ function registerXtrmUiTools(pi: ExtensionAPI, getPrefs: () => XtrmUiPrefs): voi
       trackToolCallEnd(event.toolCallId);
       return undefined;
     }
+    // Never compact read/inspect tools: the hook return replaces model-facing content,
+    // so summarizing these would blind headless agents/specialists (no row to expand).
+    if (PAYLOAD_TOOLS.has(event.toolName)) return undefined;
     if (!getPrefs().compactExternalToolResults) return undefined;
 
     const text = getTextContent({ content: event.content as Array<{ type: string; text?: string }> });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaggerxtrm/pi-extensions",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Unified Pi extension entrypoint for xtrm-managed extensions",
   "type": "module",
   "publishConfig": {

package/src/extensions/xtprompt.ts

@@ -0,0 +1,3 @@
+import registerExtension from "../../extensions/xtprompt/index.ts";
+
+export default registerExtension;

package/src/registry.ts

@@ -14,6 +14,7 @@ import qualityGatesExtension from "./extensions/quality-gates.ts";
 import serviceSkillsExtension from "./extensions/service-skills.ts";
 import sessionFlowExtension from "./extensions/session-flow.ts";
 import spTerminalOverlayExtension from "./extensions/sp-terminal-overlay.ts";
+import xtprompt from "./extensions/xtprompt.ts";
 import xtrmLoaderExtension from "./extensions/xtrm-loader.ts";
 import xtrmUiExtension from "./extensions/xtrm-ui.ts";
 
@@ -37,6 +38,7 @@ export const managedPiExtensions: readonly ManagedPiExtension[] = [
   { id: "service-skills", register: serviceSkillsExtension },
   { id: "session-flow", register: sessionFlowExtension },
   { id: "sp-terminal-overlay", register: spTerminalOverlayExtension },
+  { id: "xtprompt", register: xtprompt },
   { id: "xtrm-loader", register: xtrmLoaderExtension },
   { id: "xtrm-ui", register: xtrmUiExtension },
 ];