@ilya-lesikov/pi-pi 0.6.0 → 0.8.0

package/extensions/orchestrator/pp-menu.ts

@@ -1,7 +1,7 @@
 import { existsSync, readdirSync, writeFileSync } from "fs";
-import { join, relative } from "path";
+import { join, relative, basename } from "path";
 import { isDeepStrictEqual } from "util";
-import { askUser, isCancel } from "../../3p/pi-ask-user/index.js";
+import { askUser, isCancel, type CancelReason } from "../../3p/pi-ask-user/index.js";
 import { unregisterAgentDefinitions } from "./agents/registry.js";
 import {
   type AfterEditCommandConfig,
@@ -27,7 +27,8 @@ import {
 } from "./context.js";
 import { detectDefaultBranch, enterReviewCycle, finalizeReviewCycle } from "./event-handlers.js";
 import { Orchestrator } from "./orchestrator.js";
-import { cancelPendingPlannotatorWait } from "./plannotator.js";
+import { cancelPendingPlannotatorWait, openPlannotator, waitForPlannotatorResult } from "./plannotator.js";
+import { advanceBanner } from "./messages.js";
 import { spawnPlanners, spawnPlanReviewers } from "./phases/planning.js";
 import { spawnCodeReviewers } from "./phases/review.js";
 import { spawnBrainstormReviewers } from "./phases/brainstorm.js";
@@ -44,6 +45,8 @@ import {
   saveTask,
   taskAge,
   taskName,
+  taskNameFromState,
+  taskShortId,
   type AutonomousConfig,
   type TaskMode,
   type TaskInfo,
@@ -53,6 +56,8 @@ import {
   clearFlantGeneratedConfig,
   getFlantGeneratedConfig,
   loadFlantSettings,
+  readClaudeOAuthToken,
+  readGatewayApiKey,
   saveFlantSettings,
   unregisterFlantProviders,
   updateFlantInfra,
@@ -67,6 +72,13 @@ type MenuMode = "command" | "tool";
 
 const BACK = "back" as const;
 
+// Sentinel returned by showActiveTaskMenu when the user dismissed the top-level
+// menu with a deliberate ESC (cancelReason "user"), as opposed to selecting the
+// "Back" option or a programmatic dismissal. Callers (pp_phase_complete) use it
+// to stop the turn cleanly instead of returning reminder text that starts a new
+// LLM turn. It is intentionally distinct from the empty-string "Back" return.
+export const USER_CANCELLED = "\u0000user-cancelled" as const;
+
 type OptionInput = string | { title: string; description?: string };
 
 type TimeoutKey =
@@ -81,6 +93,18 @@ function isEnabled(value: { enabled?: boolean } | undefined): boolean {
 }
 
 async function selectOption(ctx: any, question: string, options: OptionInput[]): Promise<string | undefined> {
+  return (await selectOptionCancelable(ctx, question, options)).choice;
+}
+
+// Like selectOption but also surfaces the cancel reason so callers can tell a
+// deliberate user ESC (reason "user") apart from a normal non-selection. Used by
+// showActiveTaskMenu so pp_phase_complete can stop the turn cleanly on ESC
+// (mirroring ask_user) while keeping the "Back" navigation reminder.
+async function selectOptionCancelable(
+  ctx: any,
+  question: string,
+  options: OptionInput[],
+): Promise<{ choice?: string; cancelReason?: CancelReason }> {
   const result = await askUser(ctx, {
     question,
     options,
@@ -88,8 +112,9 @@ async function selectOption(ctx: any, question: string, options: OptionInput[]):
     allowComment: false,
     allowMultiple: false,
   });
-  if (!result || isCancel(result) || result.kind !== "selection") return undefined;
-  return result.selections[0];
+  if (result && isCancel(result)) return { cancelReason: result.reason };
+  if (!result || result.kind !== "selection") return {};
+  return { choice: result.selections[0] };
 }
 
 function opt(title: string, description: string): OptionInput {
@@ -201,6 +226,44 @@ async function pickCommitForRepo(orchestrator: Orchestrator, ctx: any, repo: Rep
   return pickedHash || null;
 }
 
+async function repoHasReviewableChanges(
+  orchestrator: Orchestrator,
+  repo: RepoInfo,
+  base: string,
+): Promise<{ changed: boolean; error?: string }> {
+  const run = async (args: string[]): Promise<{ out: string; failed: boolean }> => {
+    try {
+      const res = await orchestrator.pi.exec("git", args, { cwd: repo.path, timeout: 5000 });
+      if (res.code !== 0) return { out: "", failed: true };
+      return { out: res.stdout, failed: false };
+    } catch {
+      return { out: "", failed: true };
+    }
+  };
+
+  const committed = await run(["diff", "--name-only", `${base}...HEAD`]);
+  const unstaged = await run(["diff", "--name-only"]);
+  const staged = await run(["diff", "--cached", "--name-only"]);
+  const status = await run(["status", "--porcelain"]);
+
+  const hasCommitted = committed.out.trim().length > 0;
+  const hasUnstaged = unstaged.out.trim().length > 0;
+  const hasStaged = staged.out.trim().length > 0;
+  const hasUntracked = status.out.split("\n").some((line) => line.startsWith("??"));
+  const changed = hasCommitted || hasUnstaged || hasStaged || hasUntracked;
+
+  if (changed) return { changed: true };
+
+  // No change detected — but a failed probe (e.g. a missing/invalid base ref)
+  // could be masking real changes, so surface it rather than silently hiding
+  // the repo.
+  if (committed.failed || unstaged.failed || staged.failed || status.failed) {
+    return { changed: false, error: "git status/diff failed" };
+  }
+
+  return { changed: false };
+}
+
 interface RepoPrContext {
   repoPath: string;
   prUrl: string | null;
@@ -228,6 +291,11 @@ function showStatus(orchestrator: Orchestrator, ctx: any): void {
 }
 
 async function abortCurrentWork(orchestrator: Orchestrator, ctx: any): Promise<void> {
+  // Clear pi-pi's own delayed post-error retry (timer + ESC interrupt). Unlike
+  // pause/finish, abortCurrentWork does NOT go through cleanupActive/
+  // resetTaskScopedState, so without this a scheduled retry would survive the
+  // abort and re-nudge seconds later.
+  orchestrator.cancelPendingRetry();
   orchestrator.abortAllSubagents();
   orchestrator.transitionController.abortMainAgent(ctx.abort?.bind(ctx));
   await ctx.waitForIdle?.();
@@ -771,6 +839,9 @@ function collectRoleAssignments(config: Partial<PiPiConfig> | null): string[] {
   add("agents.subagents.simple.explore", config.agents?.subagents?.simple?.explore?.model);
   add("agents.subagents.simple.librarian", config.agents?.subagents?.simple?.librarian?.model);
   add("agents.subagents.simple.task", config.agents?.subagents?.simple?.task?.model);
+  add("agents.subagents.simple.advisor", config.agents?.subagents?.simple?.advisor?.model);
+  add("agents.subagents.simple.deep-debugger", config.agents?.subagents?.simple?.["deep-debugger"]?.model);
+  add("agents.subagents.simple.reviewer", config.agents?.subagents?.simple?.reviewer?.model);
   return out;
 }
 
@@ -783,6 +854,21 @@ function flantStatusText(settings: FlantSettings): string {
     `Last updated: ${settings.lastUpdated ?? "never"}`,
     `Providers: pp-flant-anthropic (${providers.anthropic} models), pp-flant-openai (${providers.openai} models)`,
   ];
+  if (settings.subscription) {
+    const hasOAuth = !!readClaudeOAuthToken();
+    const hasGatewayKey = !!readGatewayApiKey();
+    const subActive = hasOAuth && hasGatewayKey;
+    lines.push(
+      `Personal subscription: on (${subActive ? `active — pp-flant-anthropic-sub, ${providers.anthropic} models` : "inactive"})`,
+    );
+    lines.push(`Rate-limit switch-back check: every ${settings.switchBackIntervalMinutes} min`);
+    if (!subActive) {
+      if (!hasOAuth) lines.push("  - missing Claude OAuth token (run pi /login for Anthropic)");
+      if (!hasGatewayKey) lines.push("  - missing gateway key (set LLM_API_KEY or FLANT_API_KEY)");
+    }
+  } else {
+    lines.push("Personal subscription: off");
+  }
   if (assignments.length === 0) {
     lines.push("Role assignments: none");
   } else {
@@ -811,13 +897,22 @@ async function showFlantInfraMenu(orchestrator: Orchestrator, ctx: any): Promise
   while (true) {
     const settings = loadFlantSettings();
     const enableLabel = `Enable: ${settings.enabled ? "ON" : "OFF"}`;
-    const options: OptionInput[] = [enableLabel];
+    const options: OptionInput[] = [
+      { title: enableLabel, description: "Turn the Flant AI model providers on or off" },
+    ];
+    const subscriptionLabel = `Personal Claude subscription: ${settings.subscription ? "ON" : "OFF"}`;
     if (settings.enabled) {
       options.push(
-        `Auto-update on startup: ${settings.autoUpdate ? "ON" : "OFF"}`,
-        `Cache period: ${settings.cacheTTLDays} ${settings.cacheTTLDays === 1 ? "day" : "days"}`,
-        "Update now",
-        "Current status",
+        { title: subscriptionLabel, description: "Route Claude roles through your personal Claude subscription instead of the gateway" },
+        { title: `Auto-update on startup: ${settings.autoUpdate ? "ON" : "OFF"}`, description: "Refresh the available model list automatically each time pi starts" },
+        { title: `Cache period: ${settings.cacheTTLDays} ${settings.cacheTTLDays === 1 ? "day" : "days"}`, description: "How long the fetched model list is reused before it is refreshed" },
+      );
+      if (settings.subscription) {
+        options.push({ title: `Rate-limit switch-back check: every ${settings.switchBackIntervalMinutes} min`, description: "How often to retry your subscription after it was rate-limited and traffic fell back to the gateway" });
+      }
+      options.push(
+        { title: "Update now", description: "Fetch the latest model list from Flant right away" },
+        { title: "Current status", description: "Show the current Flant configuration, providers, and model counts" },
       );
     }
     options.push({ title: "Back", description: "Return to the previous menu" });
@@ -852,6 +947,50 @@ async function showFlantInfraMenu(orchestrator: Orchestrator, ctx: any): Promise
       continue;
     }
 
+    if (choice === subscriptionLabel) {
+      const turningOn = !settings.subscription;
+      if (turningOn) {
+        if (!readClaudeOAuthToken()) {
+          ctx.ui.notify("No Claude OAuth token found. Log in to your personal Claude subscription in pi first (/login → Anthropic), then retry.", "warning");
+          continue;
+        }
+        if (!readGatewayApiKey()) {
+          ctx.ui.notify("Set LLM_API_KEY (or FLANT_API_KEY) for the gateway first.", "warning");
+          continue;
+        }
+      }
+      const next = { ...settings, subscription: turningOn };
+      saveFlantSettings(next);
+      const result = await updateFlantInfra(orchestrator.pi);
+      if (!result.ok) {
+        ctx.ui.notify(`Personal subscription ${turningOn ? "enable" : "disable"} failed: ${result.error ?? "unknown error"}`, "error");
+      } else {
+        ctx.ui.notify(
+          turningOn
+            ? "Personal Claude subscription ON — Claude roles now route through sub/claude-* (billed to your subscription); non-Claude roles stay on llm-api.flant.ru."
+            : "Personal Claude subscription OFF — Claude roles reverted to pp-flant-anthropic.",
+          "info",
+        );
+      }
+      continue;
+    }
+
+    if (choice.startsWith("Rate-limit switch-back check:")) {
+      const selected = await selectOption(ctx, "Switch-back check interval", [
+        { title: "15 min", description: "Probe the subscription limit every 15 minutes" },
+        { title: "30 min", description: "Default — probe every 30 minutes" },
+        { title: "60 min", description: "Probe hourly" },
+        { title: "120 min", description: "Probe every two hours" },
+        { title: "Back", description: "Return to the previous menu" },
+      ]);
+      if (!selected || selected === "Back") continue;
+      const mins = Number(selected.split(" ")[0]);
+      if (!Number.isFinite(mins) || mins <= 0) continue;
+      saveFlantSettings({ ...settings, switchBackIntervalMinutes: mins });
+      ctx.ui.notify(`Switch-back check interval set to ${mins} min.`, "info");
+      continue;
+    }
+
     if (choice.startsWith("Cache period:")) {
       const selected = await selectOption(ctx, "Cache period", [
         { title: "1 day", description: "Refresh model metadata daily" },
@@ -899,17 +1038,18 @@ function formatElapsedDuration(ms: number): string {
   return remMin > 0 ? `${hr}h ${remMin}m` : `${hr}h`;
 }
 
-function showUsage(ctx: any): void {
+export function showUsage(ctx: any): void {
   const tracker = (globalThis as any)[Symbol.for("pi-pi:usage-tracker")] as
     | {
         getTotalInputTokens(): number; getTotalOutputTokens(): number;
         getTotalCacheReadTokens(): number; getTotalCacheWriteTokens(): number;
+        getTotalProcessedInputTokens(): number;
         getTotalCost(): number; getCacheHitRate(): number;
         getMainInputTokens(): number; getMainOutputTokens(): number;
         getMainCacheReadTokens(): number; getMainCacheWriteTokens(): number;
         getMainCost(): number;
-        getPerModelUsage(): Record<string, { inputTokens: number; outputTokens: number; cacheReadTokens: number; cacheWriteTokens: number; cacheSupported: boolean; turns: number }>;
-        getSubagentList(): Array<{ description: string; agentType: string; modelId: string; inputTokens: number; outputTokens: number; cacheReadTokens: number; cacheWriteTokens: number; cacheSupported: boolean; cost: number; durationMs: number; toolUses: number }>;
+        getPerModelUsage(): Record<string, { inputTokens: number; outputTokens: number; cacheReadTokens: number; cacheWriteTokens: number; cacheSupported: boolean; turns: number; subscription: boolean }>;
+        getSubagentList(): Array<{ description: string; agentType: string; modelId: string; inputTokens: number; outputTokens: number; cacheReadTokens: number; cacheWriteTokens: number; cacheSupported: boolean; cost: number; durationMs: number; toolUses: number; subscription: boolean }>;
       }
     | undefined;
 
@@ -918,30 +1058,52 @@ function showUsage(ctx: any): void {
     return;
   }
 
-  const totalInput = tracker.getTotalInputTokens();
+  // Token-weighted cache hit rate: cache reads over all processed input
+  // (uncached + cache read + cache write). Same formula everywhere so the
+  // total, per-model, and per-agent percentages are directly comparable.
+  const hitRate = (uncached: number, cacheRead: number, cacheWrite: number): number => {
+    const processed = uncached + cacheRead + cacheWrite;
+    return processed > 0 ? cacheRead / processed : 0;
+  };
+
+  // Compact one-line input part: total processed input with an inline
+  // uncached / cache read / cache write breakdown, e.g. "↑1.3k (u84 r1.0k w200)".
+  const inputPart = (uncached: number, cacheRead: number, cacheWrite: number, cacheSupported: boolean): string => {
+    const processed = uncached + cacheRead + cacheWrite;
+    const head = `↑${formatTokenCount(processed)}`;
+    if (!cacheSupported) return head;
+    return `${head} (u${formatTokenCount(uncached)} r${formatTokenCount(cacheRead)} w${formatTokenCount(cacheWrite)})`;
+  };
+
+  const totalUncachedInput = tracker.getTotalInputTokens();
   const totalOutput = tracker.getTotalOutputTokens();
   const totalCacheRead = tracker.getTotalCacheReadTokens();
+  const totalCacheWrite = tracker.getTotalCacheWriteTokens();
+  const totalProcessedInput = tracker.getTotalProcessedInputTokens();
   const totalCost = tracker.getTotalCost();
-  const totalCacheRate = (totalCacheRead + totalInput) > 0
-    ? totalCacheRead / (totalCacheRead + totalInput)
-    : 0;
+  const totalCacheRate = tracker.getCacheHitRate();
 
   const mainInput = tracker.getMainInputTokens();
   const mainOutput = tracker.getMainOutputTokens();
   const mainCacheRead = tracker.getMainCacheReadTokens();
+  const mainCacheWrite = tracker.getMainCacheWriteTokens();
   const mainCost = tracker.getMainCost();
   const models = tracker.getPerModelUsage();
   const subagents = tracker.getSubagentList();
 
-  const byModel = new Map<string, { input: number; output: number; cacheRead: number; cacheWrite: number; cacheSupported: boolean; cost: number }>();
+  const byModel = new Map<string, { input: number; output: number; cacheRead: number; cacheWrite: number; cacheSupported: boolean; cost: number; subscription: boolean }>();
   const mainModelEntries = Object.entries(models);
-  const mainTotalTokens = mainModelEntries.reduce((s, [, u]) => s + u.inputTokens + u.outputTokens, 0);
+  // Subscription (flat-rate) models contribute no dollars, so exclude their
+  // tokens from the proportional-share denominator or paid rows would be
+  // inflated and the sub/ rows would receive a spurious share.
+  const mainTotalTokens = mainModelEntries.reduce((s, [, u]) => s + (u.subscription ? 0 : u.inputTokens + u.outputTokens), 0);
   for (const [modelId, usage] of mainModelEntries) {
     const modelTokens = usage.inputTokens + usage.outputTokens;
-    const modelCostShare = mainTotalTokens > 0 ? mainCost * (modelTokens / mainTotalTokens) : 0;
+    const modelCostShare = usage.subscription || mainTotalTokens <= 0 ? 0 : mainCost * (modelTokens / mainTotalTokens);
     byModel.set(modelId, {
       input: usage.inputTokens, output: usage.outputTokens,
       cacheRead: usage.cacheReadTokens, cacheWrite: usage.cacheWriteTokens, cacheSupported: usage.cacheSupported, cost: modelCostShare,
+      subscription: usage.subscription,
     });
   }
   for (const sa of subagents) {
@@ -954,28 +1116,37 @@ function showUsage(ctx: any): void {
       existing.cacheWrite += sa.cacheWriteTokens;
       if (sa.cacheSupported) existing.cacheSupported = true;
       existing.cost += sa.cost;
+      if (sa.subscription) existing.subscription = true;
     } else {
       byModel.set(key, {
         input: sa.inputTokens, output: sa.outputTokens,
         cacheRead: sa.cacheReadTokens, cacheWrite: sa.cacheWriteTokens, cacheSupported: sa.cacheSupported, cost: sa.cost,
+        subscription: sa.subscription,
       });
     }
   }
 
+  // Total input the model processed = uncached + cache read + cache write.
+  // Shown as an explicit breakdown so the (often tiny) uncached sliver no
+  // longer masquerades as the whole "Input" figure.
   const lines: string[] = ["Session usage (total):"];
-  lines.push(`  Input: ${formatTokenCount(totalInput)} tokens`);
+  lines.push(`  Input: ${formatTokenCount(totalProcessedInput)} tokens`);
+  lines.push(`    • uncached:    ${formatTokenCount(totalUncachedInput)}`);
+  lines.push(`    • cache read:  ${formatTokenCount(totalCacheRead)}`);
+  lines.push(`    • cache write: ${formatTokenCount(totalCacheWrite)}`);
   lines.push(`  Output: ${formatTokenCount(totalOutput)} tokens`);
   if (totalCacheRead > 0) lines.push(`  Cache: ⚡${Math.round(totalCacheRate * 100)}% hit rate`);
-  if (totalCost > 0) lines.push(`  Cost: $${totalCost.toFixed(2)}`);
+  lines.push(`  Cost: $${totalCost.toFixed(2)}`);
 
   if (byModel.size > 0) {
     lines.push("");
     lines.push("By model:");
     for (const [modelId, m] of byModel) {
-      const cr = (m.cacheRead + m.input) > 0 ? Math.round(m.cacheRead / (m.cacheRead + m.input) * 100) : 0;
-      const parts = [`↑${formatTokenCount(m.input)}`, `↓${formatTokenCount(m.output)}`];
+      const cr = Math.round(hitRate(m.input, m.cacheRead, m.cacheWrite) * 100);
+      const parts = [inputPart(m.input, m.cacheRead, m.cacheWrite, m.cacheSupported), `↓${formatTokenCount(m.output)}`];
       if (m.cacheSupported) parts.push(`⚡${cr}%`);
-      if (m.cost > 0) parts.push(`$${m.cost.toFixed(2)}`);
+      if (m.subscription) parts.push("subscription");
+      else if (m.cost > 0) parts.push(`$${m.cost.toFixed(2)}`);
       lines.push(`  ${modelId}: ${parts.join("  ")}`);
     }
   }
@@ -985,13 +1156,15 @@ function showUsage(ctx: any): void {
   const agentModelNames = Object.keys(models);
   if (agentModelNames.length > 0) {
     const mainCacheSupported = mainModelEntries.some(([, u]) => u.cacheSupported);
-    const mainParts = [`↑${formatTokenCount(mainInput)}`, `↓${formatTokenCount(mainOutput)}`];
-    const mainCR = (mainCacheRead + mainInput) > 0 ? Math.round(mainCacheRead / (mainCacheRead + mainInput) * 100) : 0;
+    const mainAllSubscription = mainModelEntries.every(([, u]) => u.subscription);
+    const mainParts = [inputPart(mainInput, mainCacheRead, mainCacheWrite, mainCacheSupported), `↓${formatTokenCount(mainOutput)}`];
+    const mainCR = Math.round(hitRate(mainInput, mainCacheRead, mainCacheWrite) * 100);
     if (mainCacheSupported) mainParts.push(`⚡${mainCR}%`);
-    if (mainCost > 0) mainParts.push(`$${mainCost.toFixed(2)}`);
+    if (mainAllSubscription) mainParts.push("subscription");
+    else if (mainCost > 0) mainParts.push(`$${mainCost.toFixed(2)}`);
     lines.push(`  Main (${agentModelNames.join(", ")}): ${mainParts.join("  ")}`);
   }
-  const byAgentType = new Map<string, { input: number; output: number; cacheRead: number; cacheSupported: boolean; cost: number; durationMs: number; toolUses: number; count: number }>();
+  const byAgentType = new Map<string, { input: number; output: number; cacheRead: number; cacheWrite: number; cacheSupported: boolean; cost: number; durationMs: number; toolUses: number; count: number; subscriptionRuns: number }>();
   for (const sa of subagents) {
     const key = sa.agentType || sa.description;
     const existing = byAgentType.get(key);
@@ -999,24 +1172,29 @@ function showUsage(ctx: any): void {
       existing.input += sa.inputTokens;
       existing.output += sa.outputTokens;
       existing.cacheRead += sa.cacheReadTokens;
+      existing.cacheWrite += sa.cacheWriteTokens;
       if (sa.cacheSupported) existing.cacheSupported = true;
       existing.cost += sa.cost;
       existing.durationMs += sa.durationMs;
       existing.toolUses += sa.toolUses;
       existing.count += 1;
+      if (sa.subscription) existing.subscriptionRuns += 1;
     } else {
       byAgentType.set(key, {
-        input: sa.inputTokens, output: sa.outputTokens, cacheRead: sa.cacheReadTokens,
+        input: sa.inputTokens, output: sa.outputTokens, cacheRead: sa.cacheReadTokens, cacheWrite: sa.cacheWriteTokens,
         cacheSupported: sa.cacheSupported, cost: sa.cost, durationMs: sa.durationMs, toolUses: sa.toolUses, count: 1,
+        subscriptionRuns: sa.subscription ? 1 : 0,
       });
     }
   }
   for (const [agentType, agg] of byAgentType) {
-    const saCR = (agg.cacheRead + agg.input) > 0
-      ? Math.round(agg.cacheRead / (agg.cacheRead + agg.input) * 100) : 0;
-    const parts = [`↑${formatTokenCount(agg.input)}`, `↓${formatTokenCount(agg.output)}`];
+    const saCR = Math.round(hitRate(agg.input, agg.cacheRead, agg.cacheWrite) * 100);
+    const parts = [inputPart(agg.input, agg.cacheRead, agg.cacheWrite, agg.cacheSupported), `↓${formatTokenCount(agg.output)}`];
     if (agg.cacheSupported) parts.push(`⚡${saCR}%`);
-    if (agg.cost > 0) parts.push(`$${agg.cost.toFixed(2)}`);
+    // All runs subscription-routed → flat-rate label; otherwise show the
+    // paid-only summed cost (subscription runs already contribute $0).
+    if (agg.subscriptionRuns === agg.count) parts.push("subscription");
+    else if (agg.cost > 0) parts.push(`$${agg.cost.toFixed(2)}`);
     if (agg.durationMs > 0) parts.push(formatElapsedDuration(agg.durationMs));
     if (agg.toolUses > 0) parts.push(`${agg.toolUses} tools`);
     const countSuffix = agg.count > 1 ? ` (×${agg.count})` : "";
@@ -1085,12 +1263,16 @@ const ORCHESTRATOR_ROLES: Array<{ role: MainModelRole; label: string; descriptio
   { role: "plan", label: "Planner", description: "agents.orchestrators.plan" },
   { role: "debug", label: "Debugger", description: "agents.orchestrators.debug" },
   { role: "review", label: "Reviewer", description: "agents.orchestrators.review" },
+  { role: "quick", label: "Quick", description: "agents.orchestrators.quick" },
 ];
 
 const SUBAGENT_ROLES: Array<{ role: AgentRole; label: string; description: string }> = [
   { role: "explore", label: "Explore", description: "agents.subagents.simple.explore" },
   { role: "librarian", label: "Librarian", description: "agents.subagents.simple.librarian" },
   { role: "task", label: "Task", description: "agents.subagents.simple.task" },
+  { role: "advisor", label: "Advisor", description: "agents.subagents.simple.advisor" },
+  { role: "deep-debugger", label: "Deep debugger", description: "agents.subagents.simple.deep-debugger" },
+  { role: "reviewer", label: "Reviewer", description: "agents.subagents.simple.reviewer" },
 ];
 
 const PRESET_GROUP_ITEMS: Array<{ group: PresetGroup; label: string }> = [
@@ -1816,7 +1998,7 @@ async function showPresetVariantEditor(
       continue;
     }
     if (choice.startsWith("Enabled:")) {
-      await showBooleanSetting(orchestrator, ctx, "Enabled", [...variantPath, "enabled"]);
+      await showBooleanSetting(orchestrator, ctx, "Enabled", [...variantPath, "enabled"], "Make this agent available for use", "Disable this agent so it is not used");
       continue;
     }
     const confirm = await selectOption(ctx, "Confirm delete?", [
@@ -1957,8 +2139,8 @@ async function showPresetEnabledSetting(
   const yesTitle = withTags("Yes", formatSourceTags(true, info));
   const noTitle = withTags("No", formatSourceTags(false, info));
   const choice = await selectOption(ctx, "Enabled", [
-    yesTitle,
-    noTitle,
+    { title: yesTitle, description: "Make this preset available for selection" },
+    { title: noTitle, description: "Hide this preset so it can no longer be selected" },
     opt("Back", "Return to the previous menu"),
   ]);
   if (!choice || choice === "Back") return;
@@ -2139,7 +2321,7 @@ async function showAfterEditCommands(orchestrator: Orchestrator, ctx: any): Prom
         continue;
       }
       if (commandChoice.startsWith("Enabled:")) {
-        await showBooleanSetting(orchestrator, ctx, "Enabled", [...commandPath, "enabled"]);
+        await showBooleanSetting(orchestrator, ctx, "Enabled", [...commandPath, "enabled"], "Run this command when its triggers fire", "Keep this command configured but stop running it");
         continue;
       }
       if (commandChoice === "Triggers") {
@@ -2256,7 +2438,7 @@ async function showAfterImplementCommands(orchestrator: Orchestrator, ctx: any):
         continue;
       }
       if (commandChoice.startsWith("Enabled:")) {
-        await showBooleanSetting(orchestrator, ctx, "Enabled", [...commandPath, "enabled"]);
+        await showBooleanSetting(orchestrator, ctx, "Enabled", [...commandPath, "enabled"], "Run this command when its triggers fire", "Keep this command configured but stop running it");
         continue;
       }
       const confirm = await selectOption(ctx, "Confirm delete?", [
@@ -2379,14 +2561,16 @@ async function showBooleanSetting(
   ctx: any,
   title: string,
   keyPath: string[],
+  yesDescription = "Turn this setting on",
+  noDescription = "Turn this setting off",
 ): Promise<void> {
   while (true) {
     const info = getConfigSourceInfo(orchestrator, keyPath);
     const yesTitle = withTags("Yes", formatSourceTags(true, info));
     const noTitle = withTags("No", formatSourceTags(false, info));
     const choice = await selectOption(ctx, title, [
-      yesTitle,
-      noTitle,
+      { title: yesTitle, description: yesDescription },
+      { title: noTitle, description: noDescription },
       ...buildResetOptions(orchestrator, keyPath),
       opt("Back", "Return to the previous menu"),
     ]);
@@ -2408,14 +2592,16 @@ async function showInvertedBooleanSetting(
   ctx: any,
   title: string,
   keyPath: string[],
+  yesDescription = "Turn this setting on",
+  noDescription = "Turn this setting off",
 ): Promise<void> {
   while (true) {
     const info = getConfigSourceInfo(orchestrator, keyPath);
     const yesTitle = withTags("Yes", formatSourceTags(false, info));
     const noTitle = withTags("No", formatSourceTags(true, info));
     const choice = await selectOption(ctx, title, [
-      yesTitle,
-      noTitle,
+      { title: yesTitle, description: yesDescription },
+      { title: noTitle, description: noDescription },
       ...buildResetOptions(orchestrator, keyPath),
       opt("Back", "Return to the previous menu"),
     ]);
@@ -2433,15 +2619,15 @@ async function showInvertedBooleanSetting(
 }
 
 async function showLogLevelSetting(orchestrator: Orchestrator, ctx: any): Promise<void> {
-  const levels: Array<{ value: PiPiConfig["general"]["logLevel"]; label: string }> = [
-    { value: "debug", label: "Debug" },
-    { value: "info", label: "Info" },
-    { value: "warn", label: "Warning" },
-    { value: "error", label: "Error" },
+  const levels: Array<{ value: PiPiConfig["general"]["logLevel"]; label: string; description: string }> = [
+    { value: "debug", label: "Debug", description: "Log everything, including detailed diagnostics for troubleshooting" },
+    { value: "info", label: "Info", description: "Log normal activity plus warnings and errors" },
+    { value: "warn", label: "Warning", description: "Log only warnings and errors" },
+    { value: "error", label: "Error", description: "Log only errors" },
   ];
   while (true) {
     const info = getConfigSourceInfo(orchestrator, ["general", "logLevel"]);
-    const options: OptionInput[] = levels.map((entry) => withTags(entry.label, formatSourceTags(entry.value, info)));
+    const options: OptionInput[] = levels.map((entry) => ({ title: withTags(entry.label, formatSourceTags(entry.value, info)), description: entry.description }));
     options.push(...buildResetOptions(orchestrator, ["general", "logLevel"]));
     options.push(opt("Back", "Return to the previous menu"));
     const choice = await selectOption(ctx, "Log level", options);
@@ -2471,11 +2657,11 @@ async function showGeneralSettings(orchestrator: Orchestrator, ctx: any): Promis
     ]);
     if (!choice || choice === "Back") return BACK;
     if (choice.startsWith("Commit automatically:")) {
-      await showBooleanSetting(orchestrator, ctx, "Commit automatically", ["general", "autoCommit"]);
+      await showBooleanSetting(orchestrator, ctx, "Commit automatically", ["general", "autoCommit"], "Commit changes automatically as work progresses", "Leave committing to you");
       continue;
     }
     if (choice.startsWith("Ignore configs from other repos:")) {
-      await showInvertedBooleanSetting(orchestrator, ctx, "Ignore configs from other repos", ["general", "loadExtraRepoConfigs"]);
+      await showInvertedBooleanSetting(orchestrator, ctx, "Ignore configs from other repos", ["general", "loadExtraRepoConfigs"], "Use only the root repo config and ignore configs from other registered repos", "Also load configs from the other registered repos");
       continue;
     }
     if (choice.startsWith("Log level:")) {
@@ -2483,7 +2669,7 @@ async function showGeneralSettings(orchestrator: Orchestrator, ctx: any): Promis
       continue;
     }
     if (choice.startsWith("Tracing:")) {
-      await showBooleanSetting(orchestrator, ctx, "Tracing", ["general", "tracing"]);
+      await showBooleanSetting(orchestrator, ctx, "Tracing", ["general", "tracing"], "Capture full session traces to .pp/logs/traces/", "Do not record session traces");
       continue;
     }
     await showFlantInfraMenu(orchestrator, ctx);
@@ -2737,14 +2923,59 @@ async function pickModeForTaskStart(
   }
 }
 
+// Title: scannable human-readable intent + age. Callers must guarantee
+// uniqueness across the menu (see buildResumeOptions) so the option->task
+// mapping stays stable.
 function resumeOptionTitle(t: TaskInfo): string {
-  return taskName(t.dir);
+  return `${taskNameFromState(t.dir, t.state)} — ${taskAge(t.state)}`;
 }
 
-function resumeOptionDescription(t: TaskInfo): string {
-  const age = taskAge(t.state);
-  const phase = t.state.phase === t.type ? t.type : `${t.type}/${t.state.phase}`;
-  return `${phase}, ${age}`;
+// Description: rich per-entry detail sourced entirely from the already-loaded
+// TaskState (no extra disk reads). Empty/irrelevant fields are omitted.
+function resumeOptionDescription(t: TaskInfo, cwd: string): string {
+  const s = t.state;
+  const parts: string[] = [];
+
+  const phaseStep = s.step ? `${s.phase}/${s.step}` : s.phase;
+  parts.push(`${t.type} · ${phaseStep}`);
+
+  const mode = s.effectiveMode ?? s.mode;
+  if (mode) parts.push(mode);
+
+  if (s.reviewCycle && s.reviewCycle.pass > 0) parts.push(`review pass ${s.reviewCycle.pass}`);
+
+  const fileCount = s.modifiedFiles?.length ?? 0;
+  if (fileCount > 0) parts.push(`${fileCount} file${fileCount === 1 ? "" : "s"}`);
+
+  // Only surface the repo when it is informative: a multi-repo task, or a root
+  // repo that differs from the current project directory.
+  const rootRepo = s.repos?.find((r) => r.isRoot) ?? s.repos?.[0];
+  if (rootRepo && ((s.repos?.length ?? 0) > 1 || basename(rootRepo.path) !== basename(cwd))) {
+    parts.push(`repo: ${basename(rootRepo.path)}`);
+  }
+
+  parts.push(`id ${taskShortId(t.dir)}`);
+  return parts.join(" · ");
+}
+
+// Build menu options with a stable option->task index. Titles are made unique
+// (short id appended on collision) so selection maps back deterministically even
+// if two tasks share an intent, and the age component can't break the mapping
+// after the picker returns.
+function buildResumeOptions(tasks: TaskInfo[], cwd: string): { options: OptionInput[]; byTitle: Map<string, TaskInfo> } {
+  const seen = new Map<string, number>();
+  const byTitle = new Map<string, TaskInfo>();
+  const options: OptionInput[] = [];
+  for (const t of tasks) {
+    let title = resumeOptionTitle(t);
+    const count = seen.get(title) ?? 0;
+    seen.set(title, count + 1);
+    if (count > 0 || byTitle.has(title)) title = `${title} [${taskShortId(t.dir)}]`;
+    while (byTitle.has(title)) title = `${title} ·`;
+    byTitle.set(title, t);
+    options.push({ title, description: resumeOptionDescription(t, cwd) });
+  }
+  return { options, byTitle };
 }
 
 async function showResumeMenu(
@@ -2760,16 +2991,13 @@ async function showResumeMenu(
       return BACK;
     }
 
-    const options: OptionInput[] = tasks.map((t) => ({
-      title: resumeOptionTitle(t),
-      description: resumeOptionDescription(t),
-    }));
+    const { options, byTitle } = buildResumeOptions(tasks, orchestrator.cwd);
     options.push({ title: "Back", description: "Return to the previous menu" });
 
     const choice = await selectOption(ctx, "Resume", options);
     if (!choice || choice === "Back") return BACK;
 
-    const task = tasks.find((t) => resumeOptionTitle(t) === choice);
+    const task = byTitle.get(choice);
     if (!task) continue;
     const result = await resumeTask(orchestrator, ctx, task);
     if (result.ok) return "started";
@@ -2906,30 +3134,24 @@ async function openCodeReviewInPlannotator(
   if (payload.diffType) requestPayload.diffType = payload.diffType;
   if (payload.defaultBranch) requestPayload.defaultBranch = payload.defaultBranch;
 
-  return await new Promise((resolve) => {
-    let handled = false;
-    const timer = setTimeout(() => {
-      if (!handled) resolve({ status: "error", error: "Plannotator is not available." });
-    }, 30000);
-    orchestrator.pi.events.emit("plannotator:request", {
-      requestId: crypto.randomUUID(),
-      action: "code-review",
-      payload: requestPayload,
-      respond: (response: any) => {
-        handled = true;
-        clearTimeout(timer);
-        if (response?.status !== "handled") {
-          resolve({ status: "error", error: response?.error || "Plannotator is not available." });
-          return;
-        }
-        const approved = !!response?.result?.approved;
-        const feedback = typeof response?.result?.feedback === "string" && response.result.feedback.trim().length > 0
-          ? response.result.feedback
-          : undefined;
-        resolve({ status: approved ? "approved" : "needs_changes", feedback });
-      },
-    });
-  });
+  const { opened, reviewId } = await openPlannotator(orchestrator.pi, "code-review", requestPayload);
+  if (!opened) {
+    return { status: "error", error: "Plannotator is not available." };
+  }
+
+  let result: { approved: boolean; feedback?: string; error?: string };
+  try {
+    result = await waitForPlannotatorResult(orchestrator, reviewId, null);
+  } catch (err) {
+    return { status: "error", error: err instanceof Error ? err.message : "Plannotator review failed." };
+  }
+  if (result.error) {
+    return { status: "error", error: result.error };
+  }
+  const feedback = typeof result.feedback === "string" && result.feedback.trim().length > 0
+    ? result.feedback
+    : undefined;
+  return { status: result.approved ? "approved" : "needs_changes", feedback };
 }
 
 async function startReviewTask(
@@ -3251,13 +3473,16 @@ async function showQuickTaskMenu(
     if (summary !== "/pp") headerLines.push(`\n\n${summary}`);
     const menuTitle = headerLines.join("");
 
-    const choice = await selectOption(ctx, menuTitle, [
+    const { choice, cancelReason } = await selectOptionCancelable(ctx, menuTitle, [
       opt("Complete", "Mark task as done and clean up"),
       opt("Pause", "Suspend task to resume later"),
       opt("Info", "Subagents, usage, and task status"),
       opt("Settings", "Flant AI and other configuration"),
       opt("Back", "Return to the prompt and keep working"),
     ]);
+    // A deliberate ESC in tool mode must stop the turn cleanly (mirror the
+    // guided/autonomous branches); in command mode ESC just closes the menu.
+    if (cancelReason === "user" && mode === "tool") return USER_CANCELLED;
     if (!choice || choice === "Back") return "";
     if (choice === "Info") {
       await showInfoMenu(orchestrator, ctx);
@@ -3282,7 +3507,7 @@ export async function showActiveTaskMenu(
   summary: string,
   mode: MenuMode = "command",
 ): Promise<string> {
-  const continueMessage = "User wants to continue. Run /pp when ready to advance.";
+  const continueMessage = advanceBanner("[PI-PI] User wants to continue. Run /pp when ready to advance.");
 
   while (true) {
     if (!orchestrator.active) return "No active task.";
@@ -3306,13 +3531,17 @@ export async function showActiveTaskMenu(
     const opt = (title: string, description: string): OptionInput => ({ title, description });
 
     if (effectiveMode === "autonomous") {
-      const autoChoice = await selectOption(ctx, `/pp\n\nTask: ${task.type}\nPhase: ${phase}${summary !== "/pp" ? `\n\n${summary}` : ""}`, [
+      const { choice: autoChoice, cancelReason } = await selectOptionCancelable(ctx, `/pp\n\nTask: ${task.type}\nPhase: ${phase}${summary !== "/pp" ? `\n\n${summary}` : ""}`, [
         opt("Complete task", "Mark task as done and clean up"),
         opt("Pause task", "Suspend task to resume later"),
         opt("Info", "Subagents, usage, and task status"),
         opt("Settings", "Flant AI and other configuration"),
         opt("Back", "Return to the prompt and keep working"),
       ]);
+      // A deliberate ESC only needs distinct handling in tool mode (so
+      // pp_phase_complete can stop the turn); in command mode ESC just closes
+      // the menu like "Back".
+      if (cancelReason === "user" && mode === "tool") return USER_CANCELLED;
       if (!autoChoice || autoChoice === "Back") return "";
       if (autoChoice === "Info") {
         await showInfoMenu(orchestrator, ctx);
@@ -3342,7 +3571,8 @@ export async function showActiveTaskMenu(
     const headerLines = [`/pp\n\nTask: ${task.type}\nPhase: ${phase}`];
     if (summary !== "/pp") headerLines.push(`\n\n${summary}`);
     const menuTitle = headerLines.join("");
-    const choice = await selectOption(ctx, menuTitle, options);
+    const { choice, cancelReason } = await selectOptionCancelable(ctx, menuTitle, options);
+    if (cancelReason === "user" && mode === "tool") return USER_CANCELLED;
     if (!choice || choice === "Back") {
       return "";
     }
@@ -3417,7 +3647,9 @@ export async function showActiveTaskMenu(
       if (hasPlannotator) {
         reviewOptions.push(opt("Review in Plannotator", phase === "plan" ? "Open plan review in browser" : "Open code diff review in browser"));
       }
-      reviewOptions.push(opt("Review on my own", "Review manually, then continue"));
+      reviewOptions.push(opt("Review on my own", phase === "implement"
+        ? "Review in your editor: mark spots with AI_REVIEW: comments, then have the agent address them"
+        : "Review manually, then continue"));
       reviewOptions.push(opt("Back", "Return to the previous menu"));
 
       const reviewChoice = await selectOption(ctx, "Review", reviewOptions);
@@ -3433,8 +3665,23 @@ export async function showActiveTaskMenu(
           if (handled.continueLoop) continue;
           return handled.text ?? text;
         }
-        const repos = getRegisteredRepos(orchestrator);
+        const allRepos = getRegisteredRepos(orchestrator);
         const summaries: string[] = [];
+        const repos: RepoInfo[] = [];
+        for (const repo of allRepos) {
+          const base = await detectDefaultBranch(orchestrator, allRepos, repo.path);
+          const { changed, error } = await repoHasReviewableChanges(orchestrator, repo, base);
+          if (error) {
+            summaries.push(`${formatRepoLabel(repo)}: ERROR — ${error}`);
+            repos.push(repo);
+          } else if (changed) {
+            repos.push(repo);
+          }
+        }
+        if (repos.length === 0) {
+          ctx.ui.notify("No registered repositories have changes to review.", "info");
+          continue;
+        }
         let stopReviewing = false;
 
         for (const repo of repos) {
@@ -3503,10 +3750,35 @@ export async function showActiveTaskMenu(
       if (reviewChoice === "Review on my own") {
         if (phase === "plan") {
           setStep(orchestrator, "synthesize");
-        } else {
+          return continueMessage;
+        }
+        if (phase !== "implement") {
           setStep(orchestrator, "llm_work");
+          return continueMessage;
         }
-        return continueMessage;
+
+        const gate = await selectOption(ctx, "Editor review", [
+          opt("Done", "I've added AI_REVIEW: markers and saved my files"),
+          opt("Skip markers", "Continue without the marker workflow"),
+          opt("Back", "Return to the review menu"),
+        ]);
+        if (!gate || gate === "Back") continue;
+        setStep(orchestrator, "llm_work");
+        if (gate === "Skip markers") {
+          return continueMessage;
+        }
+        return advanceBanner(
+          "[PI-PI] The user reviewed the changes in their editor and left inline `AI_REVIEW:` markers " +
+          "(inside each file's native comment syntax, e.g. `// AI_REVIEW: ...`, `# AI_REVIEW: ...`, " +
+          "`<!-- AI_REVIEW: ... -->`).\n\n" +
+          "For each registered repo, enumerate the CHANGED files only — union of `git diff --name-only <base>...HEAD`, " +
+          "`git diff --name-only`, `git diff --cached --name-only`, and untracked-non-ignored files from `git status --porcelain` " +
+          "(base = each repo's configured base branch) — and search WITHIN those files for `AI_REVIEW:`. Do NOT grep the whole " +
+          "worktree (avoid vendored/generated/node_modules and historical markers).\n\n" +
+          "For each marker: address the request, then remove that marker in the SAME edit. After a pass, re-scan the changed " +
+          "files and repeat until no `AI_REVIEW:` markers remain. Then verify your work and report what you changed per marker. " +
+          "When complete, call pp_phase_complete.",
+        );
       }
 
       const reviewPreset = await pickPreset(ctx, orchestrator, getReviewPresetGroup(phase), "Review preset");