@piagent/platform 1.2.17 → 1.3.0-ie.8

package/packages/piagent-core/runtime/registration/activity-inspector-command.ts

@@ -0,0 +1,265 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import type { TaskContract } from "../../extensions/guard-types.ts";
+import {
+  buildActivityInspector,
+  formatActivityInspector,
+  inspectWorkingTreeFiles,
+  type ActivityInspectorEvent,
+  type CurrentActivity
+} from "../product/activity-inspector.ts";
+import { formatActivityFooter, formatActivityPanel } from "../product/activity-inspector-footer.ts";
+import { prefixCompletions, registerRuntimeCommand } from "./extension-registration.ts";
+
+const INSPECTOR_ACTIONS = ["summary", "files", "commands", "security", "context", "toggle", "help"] as const;
+const INSPECTOR_SURFACE_KEY = "00-piagent-inspector";
+type InspectorAction = typeof INSPECTOR_ACTIONS[number];
+
+type InspectorDependencies = {
+  activeTask: (ctx: ExtensionContext) => TaskContract | undefined;
+  readEvents: (cwd: string) => ActivityInspectorEvent[];
+  selectAction: (
+    ctx: ExtensionContext,
+    title: string,
+    entries: Array<{ value: string; label: string; description?: string; recommended?: boolean }>,
+    defaultValue?: string
+  ) => Promise<string | undefined>;
+  emit: (ctx: ExtensionContext, customType: string, content: string, details?: Record<string, unknown>) => void;
+};
+
+function sessionKey(ctx: ExtensionContext): string {
+  return `${ctx.cwd}\u0000${ctx.sessionManager.getSessionId()}`;
+}
+
+function clipped(value: unknown, maximum = 96): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const normalized = value.replace(/\s+/g, " ").trim();
+  if (!normalized) return undefined;
+  return normalized.length <= maximum ? normalized : `${normalized.slice(0, maximum - 1)}…`;
+}
+
+function currentActivity(event: ActivityInspectorEvent): CurrentActivity | undefined {
+  const toolCallId = String(event.toolCallId ?? "").trim();
+  const toolName = String(event.toolName ?? "").trim();
+  if (!toolCallId || !toolName) return undefined;
+  const target = clipped(event.targetPath ?? event.command);
+  const label = ["edit", "write", "apply_patch"].includes(toolName)
+    ? "editing"
+    : ["read", "grep", "find", "ls"].includes(toolName)
+      ? "reading"
+      : ["bash", "shell", "exec"].includes(toolName)
+        ? "running"
+        : "calling";
+  return { toolCallId, toolName, label, target, startedAt: event.recordedAt ?? new Date().toISOString(), status: "running" };
+}
+
+function mergeEvents(persisted: ActivityInspectorEvent[], memory: ActivityInspectorEvent[]): ActivityInspectorEvent[] {
+  const merged = new Map<string, ActivityInspectorEvent>();
+  for (const event of [...persisted, ...memory]) {
+    const key = event.activityId ?? [event.event, event.toolCallId, event.recordedAt, event.toolName].join(":");
+    merged.set(key, event);
+  }
+  return [...merged.values()];
+}
+
+export function registerActivityInspector(pi: ExtensionAPI, dependencies: InspectorDependencies) {
+  const memoryEvents = new Map<string, ActivityInspectorEvent[]>();
+  const running = new Map<string, Map<string, CurrentActivity>>();
+  const lastActivity = new Map<string, CurrentActivity>();
+  const enabled = new Map<string, boolean>();
+  const cached = new Map<string, { at: number; view: ReturnType<typeof buildActivityInspector> }>();
+
+  function sessionEvents(ctx: ExtensionContext): ActivityInspectorEvent[] {
+    let persisted: ActivityInspectorEvent[] = [];
+    try {
+      persisted = dependencies.readEvents(ctx.cwd);
+    } catch {
+      persisted = [];
+    }
+    return mergeEvents(persisted, memoryEvents.get(sessionKey(ctx)) ?? []);
+  }
+
+  function currentFor(ctx: ExtensionContext): CurrentActivity[] {
+    const key = sessionKey(ctx);
+    const active = [...(running.get(key)?.values() ?? [])];
+    return active.length > 0 ? active : lastActivity.has(key) ? [lastActivity.get(key) as CurrentActivity] : [];
+  }
+
+  function project(ctx: ExtensionContext, force = false, exactFiles = false) {
+    const key = sessionKey(ctx);
+    const previous = cached.get(key);
+    const current = currentFor(ctx);
+    if (!exactFiles && !force && previous && Date.now() - previous.at < 400) {
+      return { ...previous.view, state: { ...previous.view.state, running: current.filter((activity) => activity.status === "running").length, current } };
+    }
+    const view = buildActivityInspector({
+      cwd: ctx.cwd,
+      sessionId: ctx.sessionManager.getSessionId(),
+      task: dependencies.activeTask(ctx),
+      events: sessionEvents(ctx),
+      sessionEntries: ctx.sessionManager.getBranch(),
+      contextUsage: ctx.getContextUsage(),
+      current,
+      fileEvidenceMode: exactFiles ? "exact" : "observed",
+      workingTreeFiles: exactFiles ? undefined : inspectWorkingTreeFiles(ctx.cwd)
+    });
+    cached.set(key, { at: Date.now(), view });
+    return view;
+  }
+
+  function clearSurface(ctx: ExtensionContext): void {
+    if (typeof ctx.ui?.setStatus === "function") ctx.ui.setStatus(INSPECTOR_SURFACE_KEY, undefined);
+    if (typeof ctx.ui?.setWidget === "function") ctx.ui.setWidget("piagent-inspector", undefined);
+  }
+
+  function renderSurface(ctx: ExtensionContext, force = false): void {
+    const canUseStatus = typeof ctx.ui?.setStatus === "function";
+    const canUseWidget = typeof ctx.ui?.setWidget === "function";
+    if (ctx.hasUI === false || (!canUseStatus && !canUseWidget)) return;
+    const key = sessionKey(ctx);
+    if (enabled.get(key) === false) {
+      clearSurface(ctx);
+      return;
+    }
+    try {
+      const view = project(ctx, force);
+      const color = process.env.NO_COLOR === undefined && process.env.TERM !== "dumb";
+      if (canUseWidget) {
+        ctx.ui.setWidget("piagent-inspector", formatActivityPanel(view, { color }), { placement: "belowEditor" });
+        if (canUseStatus) ctx.ui.setStatus(INSPECTOR_SURFACE_KEY, undefined);
+      } else if (canUseStatus) {
+        ctx.ui.setStatus(INSPECTOR_SURFACE_KEY, formatActivityFooter(view, { color }));
+      }
+    } catch {
+      if (canUseWidget) {
+        ctx.ui.setWidget("piagent-inspector", ["! PIAGENT    state unavailable"], { placement: "belowEditor" });
+        if (canUseStatus) ctx.ui.setStatus(INSPECTOR_SURFACE_KEY, undefined);
+      } else if (canUseStatus) ctx.ui.setStatus(INSPECTOR_SURFACE_KEY, "! Piagent · state unavailable");
+    }
+  }
+
+  function observe(ctx: ExtensionContext, payload: ActivityInspectorEvent): void {
+    const key = sessionKey(ctx);
+    const task = dependencies.activeTask(ctx);
+    const event = {
+      ...payload,
+      sessionId: ctx.sessionManager.getSessionId(),
+      taskRunId: payload.taskRunId ?? task?.taskRunId
+    };
+    const stored = [...(memoryEvents.get(key) ?? []), event].slice(-1_000);
+    memoryEvents.set(key, stored);
+    let active = running.get(key);
+    if (!active) {
+      active = new Map();
+      running.set(key, active);
+    }
+    if (event.event === "tool_call") {
+      const activity = currentActivity(event);
+      if (activity) {
+        active.set(activity.toolCallId, activity);
+        lastActivity.delete(key);
+      }
+    }
+    if (event.event === "tool_decision" && event.decision === "blocked" && event.toolCallId) {
+      const previous = active.get(event.toolCallId);
+      active.delete(event.toolCallId);
+      if (previous) lastActivity.set(key, { ...previous, label: "blocked", status: "blocked" });
+    }
+    if (event.event === "tool_result" && event.toolCallId) {
+      const previous = active.get(event.toolCallId);
+      active.delete(event.toolCallId);
+      if (previous) {
+        const failed = event.isError === true || (typeof event.exitCode === "number" && event.exitCode !== 0);
+        const delta = typeof event.additions === "number" && typeof event.deletions === "number"
+          ? ` +${event.additions} -${event.deletions}`
+          : "";
+        lastActivity.set(key, {
+          ...previous,
+          label: failed ? "failed" : ["edit", "write", "apply_patch"].includes(previous.toolName) ? "edited" : "completed",
+          target: `${previous.target ?? previous.toolName}${delta}`,
+          status: failed ? "failed" : "completed"
+        });
+      }
+    }
+    cached.delete(key);
+    renderSurface(ctx, event.event === "tool_result" || event.event === "tool_decision");
+  }
+
+  function emitHelp(ctx: ExtensionContext): void {
+    dependencies.emit(ctx, "piagent-inspector-help", [
+      "namespace: /piagent-inspector",
+      "/piagent-inspector summary",
+      "/piagent-inspector files",
+      "/piagent-inspector commands",
+      "/piagent-inspector security",
+      "/piagent-inspector context",
+      "/piagent-inspector toggle",
+      "/piagent-inspector --json [summary|files|commands|security|context]",
+      "note: the vertical footer panel is automatic and session-local; per-tool model tokens are unavailable by design"
+    ].join("\n"), { actions: INSPECTOR_ACTIONS });
+  }
+
+  async function chooseAction(ctx: ExtensionContext): Promise<InspectorAction | undefined> {
+    const chosen = await dependencies.selectAction(ctx, "Piagent Inspector", [
+      { value: "summary", label: "Summary", description: "Task, files, commands, safety, and context", recommended: true },
+      { value: "files", label: "Changed files", description: "Task delta, test files, and line counts" },
+      { value: "commands", label: "Commands", description: "Executed, failed, blocked, and verifier results" },
+      { value: "security", label: "Safety", description: "Policy blocks, redactions, and integrity warnings" },
+      { value: "context", label: "Context budget", description: "Live context plus turn and session usage" },
+      { value: "toggle", label: "Toggle footer panel", description: "Show or hide the vertical panel beside Pi's native footer for this session" },
+      { value: "help", label: "Help", description: "Show the compact command map" }
+    ], "summary");
+    return INSPECTOR_ACTIONS.includes(chosen as InspectorAction) ? chosen as InspectorAction : undefined;
+  }
+
+  registerRuntimeCommand(pi, "piagent-inspector", {
+    description: "Inspect task diff, commands, safety, and context budget",
+    getArgumentCompletions: (prefix: string) => prefixCompletions([...INSPECTOR_ACTIONS, "--json"], prefix),
+    handler: async (raw: string, ctx: ExtensionContext) => {
+      const tokens = String(raw ?? "").trim().split(/\s+/).filter(Boolean);
+      const json = tokens.includes("--json");
+      const actionToken = tokens.find((token) => token !== "--json")?.toLowerCase();
+      const action = actionToken
+        ? INSPECTOR_ACTIONS.includes(actionToken as InspectorAction) ? actionToken as InspectorAction : undefined
+        : await chooseAction(ctx);
+      if (!action) {
+        if (!actionToken) return;
+        dependencies.emit(ctx, "piagent-inspector-error", `Unknown inspector option: ${actionToken ?? "none"}\nRun /piagent-inspector help`, { action: actionToken });
+        return;
+      }
+      if (action === "help") {
+        emitHelp(ctx);
+        return;
+      }
+      if (action === "toggle") {
+        const key = sessionKey(ctx);
+        const next = enabled.get(key) === false;
+        enabled.set(key, next);
+        renderSurface(ctx, true);
+        ctx.ui.notify(`Piagent Inspector footer panel: ${next ? "on" : "off"}`, "info");
+        return;
+      }
+      const view = project(ctx, true, action === "files" || action === "security");
+      const content = json ? JSON.stringify({ action, inspector: view }) : formatActivityInspector(view, action);
+      dependencies.emit(ctx, `piagent-inspector-${action}`, content, { action, inspector: view });
+      renderSurface(ctx);
+    }
+  });
+
+  function dispose(ctx: ExtensionContext): void {
+    const key = sessionKey(ctx);
+    clearSurface(ctx);
+    memoryEvents.delete(key);
+    running.delete(key);
+    lastActivity.delete(key);
+    enabled.delete(key);
+    cached.delete(key);
+  }
+
+  return {
+    observe,
+    refresh: (ctx: ExtensionContext) => renderSurface(ctx, true),
+    project: (ctx: ExtensionContext) => project(ctx, true, true),
+    dispose
+  };
+}

package/packages/piagent-core/runtime/registration/context-commands.ts

@@ -0,0 +1,392 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+type ExtensionContext = any;
+
+export function registerContextCommands(pi: ExtensionAPI, deps: Record<string, any>): any {
+  const {
+    activeSessionTask, buildContextEfficiencyReport, buildContextIndexStatus, buildContextIndexV2, buildContextPack, buildContextPreflight,
+    buildTaskEfficiencyMetrics,
+    buildTestImpact, buildUsageSnapshot, commandArgs, compactSessionTask, contextIndexExcludePatterns,
+    contextIndexV2Status, crypto, emitRuntimeMessage, ensureContextIndexV2, estimateContextTokens,
+    formatContextPreflight,
+    formatCount, formatPercent, fs, helpersMode, loadProfileFromContext, memoryHandbookPath,
+    policy, projectFilePath, resolveMemorySettings, resolveOrchestrationPolicy, searchContextIndex,
+    searchContextIndexV2, selectRuntimeAction, semanticCompactionInstructions, telemetry
+  } = deps;
+  function emitContextIndexSearch(ctx: ExtensionContext, query: string): void {
+    const profile = loadProfileFromContext(ctx);
+    let matches: Array<{ id: string; kind: string; label: string; match: string }> = [];
+    let error: string | undefined;
+    try {
+      matches = query ? searchContextIndex(ctx.cwd, profile, query, 8) : [];
+    } catch (caught) {
+      error = caught instanceof Error ? caught.message : String(caught);
+    }
+    emitRuntimeMessage(ctx, "piagent-context-index-search", error
+      ? `Context index search failed: ${error}`
+      : matches.length
+      ? matches.map((match) => `${match.id} [${match.kind}] ${match.label}: ${match.match}`).join("\n")
+      : "No context index matches.", { query, matches, error });
+  }
+
+  function emitContextIndexStatus(ctx: ExtensionContext): void {
+    const profile = loadProfileFromContext(ctx);
+    const status = buildContextIndexStatus(ctx.cwd, profile);
+    ctx.ui.notify(`Context index: ${status.exists ? `${status.nodes} nodes` : "missing"}`, status.warnings.length ? "warning" : "info");
+    emitRuntimeMessage(ctx, "piagent-context-index-status", [
+      `contextIndex: ${status.enabled ? "enabled" : "off"}`,
+      `path: ${status.path} (${status.exists ? "exists" : "missing"})`,
+      `nodes: ${status.nodes}`,
+      `edges: ${status.edges}`,
+      `citations: ${status.citations}`,
+      `updatedAt: ${status.updatedAt ?? "never"}`,
+      `warnings: ${status.warnings.join("; ") || "none"}`
+    ].join("\n"), status);
+  }
+
+  async function emitContextEngineStatus(ctx: ExtensionContext): Promise<void> {
+    try {
+      const status = await contextIndexV2Status(ctx.cwd, {
+        excludePatterns: contextIndexExcludePatterns(policy, loadProfileFromContext(ctx))
+      });
+      emitRuntimeMessage(ctx, "piagent-context-engine-status", [
+        `contextEngine: ${status.exists ? "ready" : "missing"}`,
+        `path: ${status.path}`,
+        `files: ${status.files ?? 0}`,
+        `symbols: ${status.symbols ?? 0}`,
+        `imports: ${status.imports ?? 0}`,
+        `builtAt: ${status.builtAt ?? "never"}`,
+        `stale: ${status.stale ? "yes" : "no"}`,
+        `warnings: ${status.warnings.join("; ") || "none"}`,
+        "rebuild: /context rebuild"
+      ].join("\n"), status);
+    } catch (error) {
+      emitRuntimeMessage(ctx, "piagent-context-engine-status", `Context Engine status failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  async function rebuildContextEngine(ctx: ExtensionContext): Promise<void> {
+    const profile = loadProfileFromContext(ctx);
+    const excludePatterns = contextIndexExcludePatterns(policy, profile);
+    try {
+      const result = await buildContextIndexV2(ctx.cwd, {
+        excludePatterns
+      });
+      telemetry(ctx, { event: "context_engine_action", action: "rebuild", ...result });
+      emitRuntimeMessage(ctx, "piagent-context-engine-rebuild", [
+        "contextEngine: rebuilt",
+        `files: ${result.files}; symbols: ${result.symbols}; imports: ${result.imports}`,
+        `changed: ${result.changed}; removed: ${result.removed}`,
+        `skipped: ${result.skippedLarge} large, ${result.skippedBinary} binary`,
+        `duration: ${result.durationMs}ms`
+      ].join("\n"), result);
+    } catch (error) {
+      emitRuntimeMessage(ctx, "piagent-context-engine-rebuild", `Context Engine rebuild failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  async function emitContextEngineSearch(ctx: ExtensionContext, query: string): Promise<boolean> {
+    const excludePatterns = contextIndexExcludePatterns(policy, loadProfileFromContext(ctx));
+    const { status } = await ensureContextIndexV2(ctx.cwd, {
+      excludePatterns,
+      rebuildMissing: false
+    });
+    if (!status.exists || !query.trim()) return false;
+    const search = await searchContextIndexV2(ctx.cwd, query, { limit: 12, excludePatterns });
+    emitRuntimeMessage(ctx, "piagent-context-engine-search", [
+      `confidence: ${search.confidence}`,
+      `stale: ${status.stale ? "yes" : "no"}`,
+      ...search.results.map((item) => `- ${item.path}: ${item.sources.join("+")}; ${item.symbols.slice(0, 4).map((symbol) => `${symbol.name}@${symbol.line}`).join(", ") || "no symbols"}`)
+    ].join("\n"), { queryHash: crypto.createHash("sha256").update(query).digest("hex"), search });
+    return true;
+  }
+
+  async function emitContextPack(ctx: ExtensionContext, query: string): Promise<void> {
+    if (!query.trim()) {
+      emitRuntimeMessage(ctx, "piagent-context-pack-help", "Usage: /context pack <task or symbol>");
+      return;
+    }
+    const excludePatterns = contextIndexExcludePatterns(policy, loadProfileFromContext(ctx));
+    const { status } = await ensureContextIndexV2(ctx.cwd, {
+      excludePatterns,
+      rebuildMissing: false
+    });
+    if (!status.exists) {
+      emitRuntimeMessage(ctx, "piagent-context-pack-help", "Context Engine index is missing. Run /context rebuild first.");
+      return;
+    }
+    const pack = await buildContextPack(ctx.cwd, query, {
+      budgetTokens: 1_500,
+      includeCode: false,
+      limit: 15,
+      excludePatterns
+    });
+    telemetry(ctx, {
+      event: "context_pack",
+      queryHash: pack.queryHash,
+      confidence: pack.confidence,
+      candidates: pack.candidates,
+      selected: pack.selected.length,
+      estimatedTokens: pack.estimatedTokens,
+      selectedPaths: pack.selected.map((item) => item.path),
+      source: "command"
+    });
+    emitRuntimeMessage(ctx, "piagent-context-pack-v2", pack.text, {
+      queryHash: pack.queryHash,
+      confidence: pack.confidence,
+      estimatedTokens: pack.estimatedTokens,
+      paths: pack.selected.map((item) => item.path),
+      finderRecommended: pack.finderRecommended
+    });
+  }
+
+  async function emitTestImpact(ctx: ExtensionContext, raw: string): Promise<void> {
+    const files = raw.split(/\s+/).map((file) => file.trim()).filter(Boolean);
+    const excludePatterns = contextIndexExcludePatterns(policy, loadProfileFromContext(ctx));
+    await ensureContextIndexV2(ctx.cwd, { excludePatterns, rebuildMissing: false });
+    const impact = await buildTestImpact(ctx.cwd, files, { excludePatterns });
+    emitRuntimeMessage(ctx, "piagent-context-impact", [
+      `changed: ${impact.changedFiles.join(", ") || "none"}`,
+      `impacted: ${impact.impactedFiles.map((item) => `${item.path} via ${item.via}`).join(", ") || "none"}`,
+      `tests: ${impact.tests.join(", ") || "none"}`
+    ].join("\n"), impact);
+  }
+
+  function emitContextEfficiency(ctx: ExtensionContext): void {
+    const report = buildContextEfficiencyReport(ctx.cwd);
+    const task = activeSessionTask(ctx);
+    const taskEfficiency = task ? buildTaskEfficiencyMetrics(ctx.cwd, task) : null;
+    emitRuntimeMessage(ctx, "piagent-context-efficiency", [
+      `contextWasteScore: ${report.metrics.contextWasteScore}/100 (lower is better)`,
+      `activeTools: ${report.metrics.averageActiveTools}`,
+      `toolSchemaShare: ${formatPercent(report.metrics.toolSchemaShare)}`,
+      `duplicateReads: ${report.metrics.duplicateReads}/${report.metrics.readCalls}`,
+      `duplicateOutput: ${formatPercent(report.metrics.duplicateOutputRate)}`,
+      `lowConfidencePacks: ${report.metrics.lowConfidencePacks}/${report.sample.contextPacks}`,
+      `taskEfficiency: ${taskEfficiency ? `${taskEfficiency.solver.route}; verify=${taskEfficiency.verification.attempts}; outcome=${taskEfficiency.outcome.task}` : "no active task"}`,
+      ...report.recommendations.map((recommendation) => `- ${recommendation}`)
+    ].join("\n"), { ...report, taskEfficiency });
+  }
+
+  function parsePreflightWorkflow(raw: string): string {
+    return raw.match(/\b(?:scout|be-to-fe|review|plan|platform-improve|task)\b/i)?.[0]?.toLowerCase() ?? "task";
+  }
+
+  function compactCurrentSession(ctx: ExtensionContext): void {
+    const sessionId = ctx.sessionManager.getSessionId();
+    const instructions = semanticCompactionInstructions(ctx.cwd, sessionId);
+    telemetry(ctx, {
+      event: "compaction_requested",
+      mode: "semantic",
+      instructionTokens: estimateContextTokens(instructions),
+      hasTaskContract: Boolean(compactSessionTask(ctx.cwd, sessionId))
+    });
+    ctx.compact({
+      customInstructions: instructions
+    });
+  }
+
+  function emitContextPreflight(ctx: ExtensionContext, raw: string, shouldCompact = false): void {
+    const workflow = parsePreflightWorkflow(raw);
+    const snapshot = buildUsageSnapshot(ctx, String(pi.getThinkingLevel()));
+    const preflight = buildContextPreflight(snapshot, workflow, raw.length);
+    const context = snapshot.contextUsage
+      ? `${formatCount(snapshot.contextUsage.tokens)} / ${formatCount(snapshot.contextUsage.contextWindow)} (${formatPercent(snapshot.contextUsage.percent)})`
+      : "context unavailable";
+    ctx.ui.notify(`Task preflight: ${preflight.recommendation}; ${context}`, preflight.recommendation === "ok" ? "info" : "warning");
+    if (shouldCompact) compactCurrentSession(ctx);
+    emitRuntimeMessage(ctx, "piagent-task-preflight", formatContextPreflight(preflight, snapshot), preflight);
+  }
+
+  async function runPiagentContextNamespace(raw: string, ctx: ExtensionContext): Promise<void> {
+    const { action, rest } = commandArgs(raw);
+    if (!action) {
+      const chosen = await selectRuntimeAction(ctx, "Piagent context", [
+        { value: "index", label: "Index status", description: "Architecture map plus local code index", recommended: true },
+        { value: "pack", label: "Context pack", description: "Rank paths and symbols for a task" },
+        { value: "impact", label: "Test impact", description: "Map changed files to dependents and tests" },
+        { value: "efficiency", label: "Efficiency", description: "Show transparent context waste metrics" },
+        { value: "rebuild", label: "Rebuild index", description: "Incrementally refresh changed files" },
+        { value: "preflight", label: "Preflight", description: "Check whether to run, compact, or fresh-session" },
+        { value: "compact", label: "Compact", description: "Compact current session with Piagent carry-over rules" },
+        { value: "search", label: "Search index", description: "Use /context search <keyword>" },
+        { value: "help", label: "Help", description: "Show typed forms" }
+      ], "index");
+      if (chosen === "index") {
+        emitContextIndexStatus(ctx);
+        await emitContextEngineStatus(ctx);
+        return;
+      }
+      if (chosen === "rebuild") {
+        await rebuildContextEngine(ctx);
+        return;
+      }
+      if (chosen === "efficiency") {
+        emitContextEfficiency(ctx);
+        return;
+      }
+      if (chosen === "pack") {
+        await emitContextPack(ctx, "");
+        return;
+      }
+      if (chosen === "impact") {
+        await emitTestImpact(ctx, "");
+        return;
+      }
+      if (chosen === "search") {
+        emitRuntimeMessage(ctx, "piagent-context-search-help", "Usage: /context search <keyword or symbol>");
+        return;
+      }
+      if (chosen === "preflight") {
+        emitContextPreflight(ctx, "task");
+        return;
+      }
+      if (chosen === "compact") {
+        emitContextPreflight(ctx, "task compact", true);
+        return;
+      }
+      emitRuntimeMessage(ctx, "piagent-context-help", [
+        "namespace: /context",
+        "index: /context index",
+        "rebuild: /context rebuild",
+        "search: /context search <keyword>",
+        "pack: /context pack <task or symbol>",
+        "impact: /context impact [changed files]",
+        "efficiency: /context efficiency",
+        "preflight: /context preflight [task|scout|be-to-fe|review|plan]",
+        "compact: /context compact [task|scout|be-to-fe]",
+        "legacy: /piagent-context | /context-index | /task-preflight"
+      ].join("\n"));
+      return;
+    }
+    if (["index", "status", "show", "current"].includes(action)) {
+      emitContextIndexStatus(ctx);
+      await emitContextEngineStatus(ctx);
+      return;
+    }
+    if (["rebuild", "build", "refresh"].includes(action)) {
+      await rebuildContextEngine(ctx);
+      return;
+    }
+    if (action === "search") {
+      try {
+        if (!await emitContextEngineSearch(ctx, rest)) emitContextIndexSearch(ctx, rest);
+      } catch {
+        emitContextIndexSearch(ctx, rest);
+      }
+      return;
+    }
+    if (action === "pack") {
+      await emitContextPack(ctx, rest);
+      return;
+    }
+    if (["impact", "tests"].includes(action)) {
+      await emitTestImpact(ctx, rest);
+      return;
+    }
+    if (["efficiency", "stats", "waste"].includes(action)) {
+      emitContextEfficiency(ctx);
+      return;
+    }
+    if (["preflight", "check"].includes(action)) {
+      emitContextPreflight(ctx, rest || "task");
+      return;
+    }
+    if (action === "compact") {
+      emitContextPreflight(ctx, `${rest || "task"} compact`, true);
+      return;
+    }
+    if (action === "help") {
+      emitRuntimeMessage(ctx, "piagent-context-help", [
+        "namespace: /context",
+        "index: /context index",
+        "rebuild: /context rebuild",
+        "search: /context search <keyword>",
+        "pack: /context pack <task or symbol>",
+        "impact: /context impact [changed files]",
+        "efficiency: /context efficiency",
+        "preflight: /context preflight [task|scout|be-to-fe|review|plan]",
+        "compact: /context compact [task|scout|be-to-fe]",
+        "legacy: /piagent-context | /context-index | /task-preflight"
+      ].join("\n"));
+      return;
+    }
+    emitContextIndexSearch(ctx, [action, rest].filter(Boolean).join(" "));
+  }
+
+  pi.registerCommand("piagent-context", {
+    description: "Legacy alias for /context",
+    getArgumentCompletions: (prefix: string) => {
+      const actions = ["index", "rebuild", "search", "pack", "impact", "efficiency", "preflight", "compact", "help"];
+      const typed = String(prefix ?? "").trim().toLowerCase();
+      return actions.filter((action) => action.startsWith(typed)).map((action) => ({ value: action, label: action }));
+    },
+    handler: async (args, ctx) => {
+      await runPiagentContextNamespace(String(args ?? ""), ctx);
+    }
+  });
+
+  pi.registerCommand("context", {
+    description: "Context index, retrieval pack, test impact, efficiency, preflight, and compact controls without a model follow-up",
+    getArgumentCompletions: (prefix: string) => {
+      const actions = ["index", "rebuild", "search", "pack", "impact", "efficiency", "preflight", "compact", "help"];
+      const typed = String(prefix ?? "").trim().toLowerCase();
+      return actions.filter((action) => action.startsWith(typed)).map((action) => ({ value: action, label: action }));
+    },
+    handler: async (args, ctx) => {
+      await runPiagentContextNamespace(String(args ?? ""), ctx);
+    }
+  });
+
+  pi.registerCommand("context-index", {
+    description: "Legacy alias for /context index/search",
+    handler: async (args, ctx) => {
+      const raw = String(args ?? "").trim();
+      await runPiagentContextNamespace(raw ? raw : "index", ctx);
+    }
+  });
+
+  pi.registerCommand("piagent-orchestration", {
+    description: "Show solo-first subagent, review lens, model-role, and Field Guide policy",
+    handler: async (_args, ctx) => {
+      const profile = loadProfileFromContext(ctx);
+      const settings = resolveMemorySettings(profile);
+      const orchestration = resolveOrchestrationPolicy(profile, policy);
+      let fieldGuidePath = orchestration.fieldGuide.path || settings.handbookFile;
+      let fieldGuideExists = false;
+      try {
+        fieldGuideExists = fs.existsSync(projectFilePath(ctx.cwd, fieldGuidePath));
+      } catch {
+        fieldGuidePath = settings.handbookFile;
+        fieldGuideExists = fs.existsSync(memoryHandbookPath(ctx.cwd, settings));
+      }
+      ctx.ui.notify(`Piagent orchestration: ${orchestration.defaultMode}`, "info");
+      pi.sendMessage(
+        {
+          customType: "piagent-orchestration-policy",
+          content: [
+            `mode: ${orchestration.defaultMode}`,
+            `helpersMode: ${helpersMode()}`,
+            `subagents: bounded read-only scout/planning/review; max ${orchestration.maxConcurrentSubagents}`,
+            `lenses: ${orchestration.defaultReviewLenses.join(", ")}`,
+            `fieldGuide: ${orchestration.fieldGuide.enabled ? `${fieldGuidePath} (${fieldGuideExists ? "exists" : "missing"})` : "off"}`,
+            "writer: single writer by default; parallel writers need explicit approval + isolation"
+          ].join("\n"),
+          display: true,
+          details: {
+            ...orchestration,
+            helpersMode: helpersMode(),
+            fieldGuide: {
+              ...orchestration.fieldGuide,
+              path: fieldGuidePath,
+              exists: fieldGuideExists
+            }
+          }
+        },
+        { triggerTurn: false }
+      );
+    }
+  });
+
+  return { emitContextEfficiency, emitContextPreflight };
+}