@piagent/platform 1.6.1 → 1.8.0

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

@@ -1,94 +1,52 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  WORKFLOW_OPTIONS,
+  type WorkflowId,
+  resolveWorkflowId,
+  workflowCommandNames,
+  workflowHelpLines,
+  workflowOption
+} from "../workflows/webui-workflow.ts";
+import { buildOnboardingWorkflowPrompt, buildWorkflowFollowUp } from "../workflows/workflow-follow-up.ts";
+
+import type { TaskContract } from "../../extensions/guard-types.js";
+import { activeSessionTask } from "../../extensions/task-state.js";
+import { isUncertainSendContinuation, terminalUncertainSendReceipt } from "../session/uncertain-send-continuation.ts";
 
 type ExtensionContext = any;
 
 export function registerWorkflowCommands(pi: ExtensionAPI, deps: Record<string, any>): any {
   const {
-    FRESH_COMMAND_ACTIONS, FRESH_COMMAND_HELP, ONBOARDING_COMMAND_ACTIONS, WORKFLOW_COMMAND_EXCLUSIONS, buildContextIndexStatus,
+    ONBOARDING_COMMAND_ACTIONS, WORKFLOW_COMMAND_EXCLUSIONS, buildContextIndexStatus,
     buildUsageSnapshot, commandArgs, emitProfileStatus, emitProfileTechStatus, emitRuntimeMessage,
     fs, loadProfileFromContext, prefixCompletions, projectContextFilePath, projectProfilePath,
     registerRuntimeCommand, resolveMemorySettings, runProfileTechWizard, selectRuntimeAction, sendWorkflowFollowUp,
     freshRequestParts, shortTaskLabel, techStackPath
   } = deps;
-  type WorkflowCommandName = "task" | "scout" | "be-to-fe" | "discuss" | "plan" | "review" | "platform-improve" | "commit" | "pr" | "onboard";
-
-  const WORKFLOW_ALIASES: Record<string, WorkflowCommandName> = {
-    task: "task",
-    implement: "task",
-    scout: "scout",
-    audit: "scout",
-    "be-to-fe": "be-to-fe",
-    befe: "be-to-fe",
-    discuss: "discuss",
-    clarify: "discuss",
-    plan: "plan",
-    review: "review",
-    "platform-improve": "platform-improve",
-    platform: "platform-improve",
-    commit: "commit",
-    pr: "pr",
-    onboard: "onboard",
-    "onboard-project": "onboard"
-  };
-
   function workflowChoices(): Array<{ value: string; label: string; description: string; recommended?: boolean }> {
     return [
-      { value: "task", label: "Task", description: "Implement a bounded task", recommended: true },
-      { value: "scout", label: "Scout", description: "Read-only audit/research" },
-      { value: "be-to-fe", label: "BE to FE", description: "Backend read-only, frontend implementation" },
-      { value: "discuss", label: "Discuss", description: "Clarify before planning/editing" },
-      { value: "plan", label: "Plan", description: "Create an implementation plan" },
-      { value: "review", label: "Review", description: "Review diff/source read-only" },
-      { value: "commit", label: "Commit", description: "Guarded local commit workflow" },
-      { value: "pr", label: "PR", description: "Guarded pull request preparation" },
-      { value: "onboard", label: "Onboard", description: "First-read project onboarding scout" },
-      { value: "platform-improve", label: "Platform", description: "Improve Pi Agent Platform itself" },
+      ...WORKFLOW_OPTIONS.map((option) => ({
+        value: option.id,
+        label: option.label,
+        description: option.description,
+        ...(option.id === "task" ? { recommended: true } : {})
+      })),
       { value: "help", label: "Help", description: "Show typed workflow forms" }
     ];
   }
 
-  function buildOnboardingWorkflowPrompt(focus: string): string {
-    return [
-      "Run the Pi Agent Platform first-read onboarding workflow for this repository.",
-      "",
-      `Optional focus: ${focus.trim() || "whole repository"}`,
-      "",
-      "Preconditions:",
-      "- The operator has logged in and selected the intended model/thinking level.",
-      "- Stay read-only except writing Piagent onboarding state through piagent tools.",
-      "",
-      "Mandatory flow:",
-      "1. Call piagent_context with detail=full.",
-      "2. If the project is unprofiled, call piagent_profile_options, do a lightweight root scout, recommend a profile, and use piagent_profile_apply only after the operator choice is clear.",
-      "3. Prefer /profile setup or piagent_profile_tech_options + piagent_profile_tech_apply for tech stack selection.",
-      "4. Re-call piagent_context after profile/tech changes.",
-      "5. Call piagent_memory_status and treat memory as advisory.",
-      "6. Read AGENTS.md, README/package/build config, required context, docs/architecture files, source map, and verify command definitions. Do not ingest the whole repo.",
-      "7. Identify project purpose, stack/runtime, ownership boundaries, high-risk areas, protected paths, verify commands, MCP/tool capabilities, selected tech stack, memory policy, and conventions.",
-      "8. Write a concise .pi/project-context.md snapshot and record it with piagent_project_onboarding_record so .pi/context-index.json is generated.",
-      "9. Call piagent_context_index_status and report pending/stale warnings.",
-      "",
-      "Final output: profile, tech stack, context files read, verification matrix, high-risk areas, context-index status, memory status, and any missing operator decisions."
-    ].join("\n");
-  }
-
   function emitWorkflowHelp(ctx: ExtensionContext): void {
-    emitRuntimeMessage(ctx, "piagent-workflow-help", [
-      "namespace: /workflow",
-      "daily: /workflow task <request>",
-      "readOnly: /workflow scout <area/spec/risk>",
-      "beToFe: /workflow be-to-fe <BE spec/change + FE outcome>",
-      "clarify: /workflow discuss <rough idea>",
-      "plan: /workflow plan <goal>",
-      "review: /workflow review <target or diff>",
-      "git: /workflow commit [message] | /workflow pr [title]",
-      "onboard: /workflow onboard [focus]",
-      "aliases still work: /task, /scout, /be-to-fe, /commit, /pr"
-    ].join("\n"), { workflows: workflowChoices().map((choice) => choice.value) });
+    emitRuntimeMessage(ctx, "piagent-workflow-help", workflowHelpLines().join("\n"), {
+      workflows: WORKFLOW_OPTIONS.map((option) => option.id)
+    });
   }
 
   async function runWorkflowNamespace(raw: string, ctx: ExtensionContext): Promise<void> {
     const { action, rest } = commandArgs(raw);
+    if (action === "help") {
+      emitWorkflowHelp(ctx);
+      return;
+    }
     if (!action) {
       const chosen = await selectRuntimeAction(ctx, "Piagent workflow", workflowChoices(), "task");
       if (!chosen || chosen === "help") {
@@ -107,8 +65,8 @@ export function registerWorkflowCommands(pi: ExtensionAPI, deps: Record<string,
       ].join("\n"), { workflow: chosen });
       return;
     }
-    const workflow = WORKFLOW_ALIASES[action];
-    if (!workflow || workflow === undefined) {
+    const workflow = resolveWorkflowId(action);
+    if (!workflow) {
       emitRuntimeMessage(ctx, "piagent-workflow-error", `unknown workflow: ${action}\nRun /workflow help`, { action }, { message: `Unknown workflow: ${action}`, level: "warning" });
       return;
     }
@@ -117,7 +75,7 @@ export function registerWorkflowCommands(pi: ExtensionAPI, deps: Record<string,
       ctx.ui.notify("Workflow launched: onboard", "info");
       return;
     }
-    if (!rest.trim()) {
+    if (!rest.trim() && workflowOption(workflow)?.requestRequired !== false) {
       emitRuntimeMessage(ctx, "piagent-workflow-needs-request", [
         `workflow: ${workflow}`,
         `run: /workflow ${workflow} <request>`,
@@ -125,7 +83,13 @@ export function registerWorkflowCommands(pi: ExtensionAPI, deps: Record<string,
       ].join("\n"), { workflow });
       return;
     }
-    sendWorkflowFollowUp(`/${workflow} ${rest}`);
+    // Namespace commands run before the input hook. Recover a current durable
+    // receipt here so their deferred extension prompt cannot open a model turn.
+    if (isUncertainSendContinuation(rest) && ctx.isIdle()) {
+      const receipt = terminalUncertainSendReceipt(ctx.cwd, activeSessionTask(ctx.cwd, ctx.sessionManager.getSessionId()) as TaskContract | undefined);
+      if (receipt) { emitRuntimeMessage(ctx, receipt.customType, receipt.content, receipt.details); return; }
+    }
+    sendWorkflowFollowUp(buildWorkflowFollowUp(workflow, rest));
     ctx.ui.notify(`Workflow launched: ${workflow}`, "info");
   }
 
@@ -150,20 +114,16 @@ export function registerWorkflowCommands(pi: ExtensionAPI, deps: Record<string,
     const sections: Record<string, string[]> = {
       overview: [
         "Piagent command surface:",
-        "runtime: /workflow | /piagent-inspector | /usage | /context | /permission | /commands | /profile | /memory | /onboard | /fresh",
+        "runtime: /workflow | /piagent-inspector | /usage | /context | /permission | /fast | /commands | /profile | /memory | /onboard | /fresh",
         "native: /model | /name | /session | /resume | /compact | /mcp",
-        "workflow: /workflow task|scout|be-to-fe|review|commit|pr <request>",
+        `workflow: /workflow ${WORKFLOW_OPTIONS.map((option) => option.id).join("|")} <request>`,
         "mcp: /mcp is Pi native; governed MCP checks stay at /piagent-mcp to avoid collision",
         "legacy: /piagent-* commands still work where they existed",
         "principle: runtime commands run immediately; workflows intentionally launch an agent turn"
       ],
       workflow: [
         "Workflow entrypoint:",
-        "/workflow",
-        "/workflow task <request>",
-        "/workflow scout <read-only request>",
-        "/workflow be-to-fe <BE spec/change + FE outcome>",
-        "/workflow onboard [focus]"
+        ...workflowHelpLines()
       ],
       usage: [
         "Usage/session:",
@@ -171,7 +131,7 @@ export function registerWorkflowCommands(pi: ExtensionAPI, deps: Record<string,
         "/piagent-inspector",
         "/usage history",
         "Pi native: /name <task name>",
-        "/fresh task|scout|be-to-fe <request>",
+        `/fresh ${WORKFLOW_OPTIONS.map((option) => option.id).join("|")} <request>`,
         "native: /session | /resume"
       ],
       context: [
@@ -193,8 +153,16 @@ export function registerWorkflowCommands(pi: ExtensionAPI, deps: Record<string,
         "Model:",
         "/model or Ctrl+L opens Pi native selector",
         "/model-options shows local Piagent model guidance",
+        "/fast status|on|off controls the OpenAI Codex Fast service tier without changing model/thinking",
         "Ctrl+P cycles model scope; Shift+Tab cycles thinking"
       ],
+      fast: [
+        "Fast service tier:",
+        "/fast status",
+        "/fast on",
+        "/fast off",
+        "Fast is a zero-model-turn session setting; model/thinking stay unchanged and provider quota or pricing may differ"
+      ],
       memory: [
         "Memory:",
         "/memory",
@@ -240,6 +208,7 @@ export function registerWorkflowCommands(pi: ExtensionAPI, deps: Record<string,
       { value: "context", label: "Context", description: "Index/search/preflight/compact" },
       { value: "permission", label: "Permission", description: "Read/write/full access controls" },
       { value: "model", label: "Model", description: "Native model selector and thinking" },
+      { value: "fast", label: "Fast mode", description: "Status and OpenAI Codex Fast service tier control" },
       { value: "mcp", label: "MCP", description: "Governed MCP commands" },
       { value: "subagents", label: "Subagents", description: "Health, fleet, cost" },
       { value: "terminal", label: "Terminal", description: "piagent-* helpers" }
@@ -339,7 +308,7 @@ export function registerWorkflowCommands(pi: ExtensionAPI, deps: Record<string,
   registerRuntimeCommand(pi, "workflow", {
     description: "One menu for Piagent task, scout, review, git, and onboarding workflows",
     getArgumentCompletions: (prefix: string) => prefixCompletions(
-      Object.keys(WORKFLOW_ALIASES).filter((name) => !WORKFLOW_COMMAND_EXCLUSIONS.includes(name)),
+      workflowCommandNames().filter((name) => !WORKFLOW_COMMAND_EXCLUSIONS.includes(name)),
       prefix
     ),
     handler: async (args, ctx) => {
@@ -376,16 +345,16 @@ export function registerWorkflowCommands(pi: ExtensionAPI, deps: Record<string,
     handler: async (args, ctx) => runOnboardingCommand(String(args ?? ""), ctx)
   });
 
-  async function startFreshWorkflow(workflow: "task" | "scout" | "be-to-fe", args: string, ctx: any) {
+  async function startFreshWorkflow(workflow: WorkflowId, args: string, ctx: any) {
     const parsed = freshRequestParts(String(args ?? ""));
     const request = parsed.request;
-    if (!request) {
+    if (!request && workflowOption(workflow)?.requestRequired !== false) {
       ctx.ui.notify(`Usage: /fresh ${workflow} <request>`, "warning");
       return;
     }
 
-    const label = parsed.sessionTitle ?? shortTaskLabel(request);
-    const command = `/${workflow} ${request}`;
+    const label = parsed.sessionTitle ?? shortTaskLabel(request || workflow);
+    const command = [`/${workflow}`, request].filter(Boolean).join(" ");
     const result = await ctx.newSession({
       withSession: async (nextCtx) => {
         pi.setSessionName(`pi:${label}`);
@@ -398,18 +367,20 @@ export function registerWorkflowCommands(pi: ExtensionAPI, deps: Record<string,
   }
 
   registerRuntimeCommand(pi, "fresh", {
-    description: "Open a fresh governed session for task, scout, or BE-to-FE work",
-    getArgumentCompletions: (prefix: string) => prefixCompletions(FRESH_COMMAND_ACTIONS, prefix),
+    description: "Open a fresh governed session for any Piagent workflow",
+    getArgumentCompletions: (prefix: string) => prefixCompletions([...workflowCommandNames({ aliases: false }), "help"], prefix),
     handler: async (args, ctx) => {
       const { action, rest } = commandArgs(String(args ?? ""));
       if (!action || action === "help") {
-        emitRuntimeMessage(ctx, "piagent-fresh-help", FRESH_COMMAND_HELP.join("\n"));
+        emitRuntimeMessage(ctx, "piagent-fresh-help", [
+          "namespace: /fresh",
+          ...WORKFLOW_OPTIONS.map((option) => `/fresh ${option.id} ${option.argumentHint}`)
+        ].join("\n"));
         return;
       }
-      const workflow = action === "be-to-fe" ? "be-to-fe" : action === "scout" ? "scout" : "task";
-      const request = action === "task" || action === "scout" || action === "be-to-fe"
-        ? rest
-        : [action, rest].filter(Boolean).join(" ");
+      const resolved = resolveWorkflowId(action);
+      const workflow = resolved ?? "task";
+      const request = resolved ? rest : [action, rest].filter(Boolean).join(" ");
       await startFreshWorkflow(workflow, request, ctx);
     }
   });

package/packages/piagent-core/runtime/session/completion-signals.ts

@@ -0,0 +1,23 @@
+function normalizeLanguageSignal(text: string): string {
+  // Preserve the Vietnamese progressive phrase before removing tone marks.
+  // Without this, both "đang làm" (still working) and "đáng làm" (worth doing)
+  // collapse to `dang lam`, so a perfectly final heading such as
+  // "Các ứng dụng đáng làm" is misclassified as an incomplete handoff.
+  const progressive = text.normalize("NFC").toLowerCase().replace(/đang\s+làm/gu, " piagent_in_progress ");
+  return progressive
+    .normalize("NFKD")
+    .replace(/\p{M}/gu, "")
+    .replaceAll("đ", "d");
+}
+
+export function looksLikeIncompleteHandoff(text: string): boolean {
+  const normalized = normalizeLanguageSignal(text);
+  return /\b(?:not done|not complete|not finished|still working|blocked|cannot complete|unable to complete|need clarification|tests? (?:fail|failed|failing)|verification (?:fail|failed|failing)|chua xong|chua hoan tat|chua hoan thanh|piagent_in_progress|(?:van|piagent|agent|em|toi|minh|chung toi) dang (?:lam|xu ly)|bi chan|can lam them|test (?:loi|fail))\b/.test(normalized);
+}
+
+export function looksLikeCompletionClaim(text: string): boolean {
+  const normalized = normalizeLanguageSignal(text);
+  if (!normalized.trim() || normalized.includes("[piagent completion gate:")) return false;
+  if (looksLikeIncompleteHandoff(text)) return false;
+  return /\b(?:done|completed|complete|finished|fixed|implemented|resolved|shipped|all tests pass(?:ed)?|tests? pass(?:ed)?|da xong|da sua|da fix|da hoan tat|da hoan thanh|da trien khai|test da pass|kiem tra da pass|ready\b[\s\S]{0,48}\b(?:test|review|use|ship)|san sang\b[\s\S]{0,48}\b(?:test|kiem tra|su dung))\b/.test(normalized);
+}

package/packages/piagent-core/runtime/session/message-signals.ts

@@ -1,5 +1,7 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
+export { looksLikeCompletionClaim, looksLikeIncompleteHandoff } from "./completion-signals.ts";
+
 export function assistantMessageText(message: unknown): string {
   if (!message || typeof message !== "object" || (message as { role?: unknown }).role !== "assistant") return "";
   const content = (message as { content?: unknown }).content;
@@ -15,28 +17,10 @@ export function assistantMessageHasToolCall(message: unknown): boolean {
   return Array.isArray(content) && content.some((item) => item && typeof item === "object" && (item as { type?: unknown }).type === "toolCall");
 }
 
-function normalizeLanguageSignal(text: string): string {
-  // Preserve the Vietnamese progressive phrase before removing tone marks.
-  // Without this, both "đang làm" (still working) and "đáng làm" (worth doing)
-  // collapse to `dang lam`, so a perfectly final heading such as
-  // "Các ứng dụng đáng làm" is misclassified as an incomplete handoff.
-  const progressive = text.normalize("NFC").toLowerCase().replace(/đang\s+làm/gu, " piagent_in_progress ");
-  return progressive
-    .normalize("NFKD")
-    .replace(/\p{M}/gu, "")
-    .replaceAll("đ", "d");
-}
-
-export function looksLikeIncompleteHandoff(text: string): boolean {
-  const normalized = normalizeLanguageSignal(text);
-  return /\b(?:not done|not complete|not finished|still working|blocked|cannot complete|unable to complete|need clarification|tests? (?:fail|failed|failing)|verification (?:fail|failed|failing)|chua xong|chua hoan tat|chua hoan thanh|piagent_in_progress|(?:van|piagent|agent|em|toi|minh|chung toi) dang (?:lam|xu ly)|bi chan|can lam them|test (?:loi|fail))\b/.test(normalized);
-}
-
-export function looksLikeCompletionClaim(text: string): boolean {
-  const normalized = normalizeLanguageSignal(text);
-  if (!normalized.trim() || normalized.includes("[piagent completion gate:")) return false;
-  if (looksLikeIncompleteHandoff(text)) return false;
-  return /\b(?:done|completed|complete|finished|fixed|implemented|resolved|shipped|all tests pass(?:ed)?|tests? pass(?:ed)?|da xong|da sua|da fix|da hoan tat|da hoan thanh|da trien khai|test da pass|kiem tra da pass)\b/.test(normalized);
+export function prependAssistantNotice<T extends { content?: unknown }>(message: T, notice: string) {
+  const content = Array.isArray(message.content) ? [{ type: "text" as const, text: notice }, ...message.content]
+    : [{ type: "text" as const, text: `${notice}${typeof message.content === "string" ? message.content : assistantMessageText(message)}` }];
+  return { ...message, content };
 }
 
 export function modelLabel(ctx: ExtensionContext): string {

package/packages/piagent-core/runtime/session/retrieval-evidence-runtime.ts

@@ -0,0 +1,188 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export const RETRIEVAL_EVIDENCE_VERSION = "retrieval-evidence-v1" as const;
+export const RETRIEVAL_EVIDENCE_TOOLS = new Set(["read", "grep", "find", "ls"]);
+
+export type RetrievalEvidenceObservation = {
+  toolName: string;
+  callFingerprint: string;
+  outputHash: string;
+  target?: string;
+  deterministicMiss?: boolean;
+  nonEvidenceFailure?: boolean;
+};
+
+export type RetrievalEvidenceCheckpoint = {
+  version: typeof RETRIEVAL_EVIDENCE_VERSION;
+  reason: "evidence-checkpoint" | "evidence-saturated";
+  calls: number;
+  uniqueCalls: number;
+  repeatedCalls: number;
+  uniqueTargets: number;
+  deterministicMisses: number;
+  noNovelEvidenceStreak: number;
+  generation: number;
+  generationCalls: number;
+  text: string;
+};
+
+type RetrievalTurnState = {
+  turnId?: string;
+  calls: number;
+  repeatedCalls: number;
+  deterministicMisses: number;
+  noNovelEvidenceStreak: number;
+  generation: number;
+  generationCalls: number;
+  adviceCount: number;
+  lastAdviceAt: number;
+  // Operation-wide sets keep the accounting truthful across a mutation. The
+  // generation-local sets below decide whether a result is fresh for the
+  // current tree revision.
+  callFingerprints: Set<string>;
+  generationCallFingerprints: Set<string>;
+  outputHashes: Set<string>;
+  targets: Set<string>;
+  generationTargets: Set<string>;
+};
+
+function newState(generation = 0, turnId?: string): RetrievalTurnState {
+  return {
+    turnId,
+    calls: 0,
+    repeatedCalls: 0,
+    deterministicMisses: 0,
+    noNovelEvidenceStreak: 0,
+    generation,
+    generationCalls: 0,
+    adviceCount: 0,
+    lastAdviceAt: 0,
+    callFingerprints: new Set(),
+    generationCallFingerprints: new Set(),
+    outputHashes: new Set(),
+    targets: new Set(),
+    generationTargets: new Set()
+  };
+}
+
+function sessionKey(ctx: ExtensionContext): string {
+  return `${ctx.cwd}\u0000${ctx.sessionManager.getSessionId()}`;
+}
+
+function boundedTarget(value: string | undefined): string | undefined {
+  const normalized = String(value ?? "").replace(/\s+/g, " ").trim();
+  if (!normalized) return undefined;
+  return normalized.length <= 512
+    ? normalized
+    : `${normalized.slice(0, 255)}…${normalized.slice(-256)}`;
+}
+
+function checkpointText(checkpoint: Omit<RetrievalEvidenceCheckpoint, "text">): string {
+  const prefix = checkpoint.reason === "evidence-saturated"
+    ? "Piagent retrieval saturation"
+    : "Piagent retrieval checkpoint";
+  return `[${prefix}: ${checkpoint.calls} calls; ${checkpoint.uniqueCalls} unique; ${checkpoint.repeatedCalls} repeated; ${checkpoint.deterministicMisses} deterministic misses; ${checkpoint.uniqueTargets} targets. `
+    + "If the acceptance criteria are covered, stop broad scouting and synthesize now. Continue only for a named unresolved criterion, a concrete contradiction, or a required focused test. Do not repeat an exact call, revisit a known-missing target, or batch patterns against an unconfirmed target.]";
+}
+
+/**
+ * Tracks evidence novelty for one operator operation. It never blocks a new
+ * source path: the model keeps its full reasoning/retrieval capability. The
+ * runtime only emits bounded checkpoints when search becomes long or stops
+ * producing new evidence.
+ */
+export class RetrievalEvidenceRuntime {
+  readonly #states = new Map<string, RetrievalTurnState>();
+
+  beginTurn(ctx: ExtensionContext, turnId?: string): void {
+    const key = sessionKey(ctx);
+    this.#states.set(key, newState(0, turnId));
+    while (this.#states.size > 100) this.#states.delete(this.#states.keys().next().value as string);
+  }
+
+  invalidateAfterMutation(ctx: ExtensionContext, turnId?: string): void {
+    const key = sessionKey(ctx);
+    const current = this.#states.get(key);
+    const prior = current && (!turnId || !current.turnId || current.turnId === turnId)
+      ? current
+      : newState(0, turnId);
+    if (turnId && !prior.turnId) prior.turnId = turnId;
+    // Keep the operation totals so a mutation cannot erase token accounting,
+    // but clear novelty/negative evidence because the working tree changed.
+    prior.generation += 1;
+    prior.generationCalls = 0;
+    prior.noNovelEvidenceStreak = 0;
+    prior.adviceCount = 0;
+    prior.lastAdviceAt = 0;
+    prior.generationCallFingerprints.clear();
+    prior.outputHashes.clear();
+    prior.generationTargets.clear();
+    this.#states.set(key, prior);
+  }
+
+  clearSession(ctx: ExtensionContext): void {
+    this.#states.delete(sessionKey(ctx));
+  }
+
+  observe(
+    ctx: ExtensionContext,
+    observation: RetrievalEvidenceObservation,
+    turnId?: string
+  ): RetrievalEvidenceCheckpoint | undefined {
+    const toolName = String(observation.toolName ?? "").toLowerCase();
+    if (!RETRIEVAL_EVIDENCE_TOOLS.has(toolName)) return undefined;
+    const key = sessionKey(ctx);
+    const current = this.#states.get(key);
+    const state = current && (!turnId || !current.turnId || current.turnId === turnId)
+      ? current
+      : newState(0, turnId);
+    if (turnId && !state.turnId) state.turnId = turnId;
+    this.#states.set(key, state);
+
+    state.calls += 1;
+    state.generationCalls += 1;
+    const target = boundedTarget(observation.target);
+    const repeatedAcrossOperation = state.callFingerprints.has(observation.callFingerprint);
+    const repeatedCall = state.generationCallFingerprints.has(observation.callFingerprint);
+    const repeatedOutput = Boolean(observation.outputHash) && state.outputHashes.has(observation.outputHash);
+    const knownTarget = target ? state.generationTargets.has(target) : false;
+    if (repeatedAcrossOperation) state.repeatedCalls += 1;
+    if (observation.deterministicMiss) state.deterministicMisses += 1;
+
+    const novel = !observation.nonEvidenceFailure
+      && !repeatedCall
+      && !observation.deterministicMiss
+      && (!repeatedOutput || !knownTarget);
+    state.noNovelEvidenceStreak = novel ? 0 : state.noNovelEvidenceStreak + 1;
+    state.callFingerprints.add(observation.callFingerprint);
+    state.generationCallFingerprints.add(observation.callFingerprint);
+    if (observation.outputHash) state.outputHashes.add(observation.outputHash);
+    if (target) {
+      state.targets.add(target);
+      state.generationTargets.add(target);
+    }
+
+    const saturated = state.noNovelEvidenceStreak >= 4;
+    const periodic = state.generationCalls >= 32 && state.generationCalls % 32 === 0;
+    const enoughDistance = state.adviceCount === 0
+      ? state.generationCalls >= 4
+      : state.generationCalls - state.lastAdviceAt >= 8;
+    if (state.adviceCount >= 4 || !enoughDistance || (!saturated && !periodic)) return undefined;
+
+    state.adviceCount += 1;
+    state.lastAdviceAt = state.generationCalls;
+    const checkpoint = {
+      version: RETRIEVAL_EVIDENCE_VERSION,
+      reason: saturated ? "evidence-saturated" as const : "evidence-checkpoint" as const,
+      calls: state.calls,
+      uniqueCalls: state.callFingerprints.size,
+      repeatedCalls: state.repeatedCalls,
+      uniqueTargets: state.targets.size,
+      deterministicMisses: state.deterministicMisses,
+      noNovelEvidenceStreak: state.noNovelEvidenceStreak,
+      generation: state.generation,
+      generationCalls: state.generationCalls
+    };
+    return { ...checkpoint, text: checkpointText(checkpoint) };
+  }
+}

package/packages/piagent-core/runtime/session/runtime-state.ts

@@ -1,8 +1,11 @@
 import crypto from "node:crypto";
+export { createHostWireSession, observeHostWireInput, HOST_WIRE_PHASE_EDGES } from "../trajectory/trajectory-runtime.ts";
+export type { HostWireSession, HostWireSessionOptions, HostWireOperation } from "../trajectory/trajectory-runtime.ts";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { isRuntimeOwnedContextEvidenceEntry } from "../../extensions/context-evidence.js";
 import { toolResultFingerprint } from "../../extensions/context-engine.js";
-import { workingTreeSnapshot } from "../../extensions/task-state.js";
+import { ShellVerificationSnapshots } from "../verification/shell-verification-snapshots.ts";
+import { HostProjectVerification } from "../verification/host-project-verification.ts";
 import type { TaskContract } from "../../extensions/guard-types.ts";
 import type { RecoveryHistoryEntry } from "../recovery/recovery-policy.ts";
 import type { ResumeState } from "../recovery/resume-state.ts";
@@ -65,7 +68,7 @@ export type PendingContextDelivery = {
   pack?: InjectedContextPack & { retrievalKey: string };
   injection?: ContextInjectionTelemetry;
 };
-export type RuntimeTurn = { turnId: string; promptHash: string };
+export type RuntimeTurn = { turnId: string; promptHash: string; lightweightNonAuthorizingChange: boolean };
 
 function evictOldest<K, V>(map: Map<K, V>, maximum: number): void {
   while (map.size > maximum) map.delete(map.keys().next().value as K);
@@ -88,16 +91,13 @@ export class RuntimeSessionState {
   readonly #observedContextBySession = new Map<string, Map<string, ObservedTaskContext>>();
   readonly #preTaskContextBySession = new Map<string, { turnId: string; entries: Map<string, ObservedTaskContext> }>();
   readonly #qualifiedContextEvidenceByTask = new Map<string, Map<string, ObservedTaskContext>>();
-  readonly #shellMutationSnapshots = new Map<string, Record<string, string>>();
+  readonly #shellMutationSnapshots = new ShellVerificationSnapshots();
+  readonly projectVerification = new HostProjectVerification(this.#shellMutationSnapshots);
   readonly #sourceCheckoutReadGrants = new SourceCheckoutReadGrants();
 
-  constructor(options: { maxObservedContext: number }) {
-    this.#maxObservedContext = options.maxObservedContext;
-  }
+  constructor(options: { maxObservedContext: number }) { this.#maxObservedContext = options.maxObservedContext; }
 
-  sessionKey(ctx: ExtensionContext): string {
-    return `${ctx.cwd}\u0000${ctx.sessionManager.getSessionId()}`;
-  }
+  sessionKey(ctx: ExtensionContext): string { return `${ctx.cwd}\u0000${ctx.sessionManager.getSessionId()}`; }
 
   cacheTaskIdentity(ctx: ExtensionContext, task: TaskContract | undefined): void {
     const key = this.sessionKey(ctx);
@@ -107,11 +107,10 @@ export class RuntimeSessionState {
   }
 
   taskIdentity(ctx: ExtensionContext): { taskId: string; taskRunId: string } | undefined {
-    return this.#taskIdentityBySession.get(this.sessionKey(ctx));
-  }
+    return this.#taskIdentityBySession.get(this.sessionKey(ctx)); }
 
-  beginTurn(ctx: ExtensionContext, promptHash: string): RuntimeTurn {
-    const turn = { turnId: crypto.randomUUID(), promptHash };
+  beginTurn(ctx: ExtensionContext, promptHash: string, classification: { lightweightNonAuthorizingChange?: boolean } = {}): RuntimeTurn {
+    const turn = { turnId: crypto.randomUUID(), promptHash, lightweightNonAuthorizingChange: classification.lightweightNonAuthorizingChange === true };
     const sessionKey = this.sessionKey(ctx);
     this.#turnBySession.set(sessionKey, turn);
     this.#preTaskContextBySession.set(sessionKey, { turnId: turn.turnId, entries: new Map() });
@@ -125,10 +124,16 @@ export class RuntimeSessionState {
     return turn && (!promptHash || turn.promptHash === promptHash) ? { ...turn } : undefined;
   }
 
-  hasAdvisedTool(ctx: ExtensionContext, toolName: string): boolean {
-    return this.#advisedTools.has(`${this.sessionKey(ctx)}\u0000${toolName}`);
+  classifyTurn(ctx: ExtensionContext, promptHash: string, classification: { lightweightNonAuthorizingChange: boolean }): RuntimeTurn {
+    const turn = this.currentTurn(ctx, promptHash);
+    if (!turn) return this.beginTurn(ctx, promptHash, classification);
+    turn.lightweightNonAuthorizingChange = classification.lightweightNonAuthorizingChange;
+    this.#turnBySession.set(this.sessionKey(ctx), turn); return { ...turn };
   }
 
+  hasAdvisedTool(ctx: ExtensionContext, toolName: string): boolean {
+    return this.#advisedTools.has(`${this.sessionKey(ctx)}\u0000${toolName}`); }
+
   rememberAdvisedTool(ctx: ExtensionContext, toolName: string): void {
     this.#advisedTools.add(`${this.sessionKey(ctx)}\u0000${toolName}`);
     while (this.#advisedTools.size > 500) {
@@ -156,9 +161,7 @@ export class RuntimeSessionState {
     return this.#sourceCheckoutReadGrants.grant(this.sessionKey(ctx), checkoutPath);
   }
 
-  sourceCheckoutReadRoots(ctx: ExtensionContext): string[] {
-    return this.#sourceCheckoutReadGrants.roots(this.sessionKey(ctx));
-  }
+  sourceCheckoutReadRoots(ctx: ExtensionContext): string[] { return this.#sourceCheckoutReadGrants.roots(this.sessionKey(ctx)); }
 
   rememberPreTaskContext(ctx: ExtensionContext, entry: ObservedTaskContext): void {
     const turn = this.currentTurn(ctx);
@@ -222,30 +225,21 @@ export class RuntimeSessionState {
     return [...(this.#qualifiedContextEvidenceByTask.get(key)?.values() ?? [])].map((entry) => structuredClone(entry));
   }
 
-  #shellMutationSnapshotKey(ctx: ExtensionContext, toolName: string, input: unknown): string {
-    return `${this.sessionKey(ctx)}\u0000${toolResultFingerprint(toolName, input, []).key}`;
+  rememberShellMutationSnapshot(ctx: ExtensionContext, toolName: string, input: unknown, toolCallId?: string): void {
+    this.#shellMutationSnapshots.remember(ctx, toolName, input, toolCallId, this.taskIdentity(ctx)?.taskRunId);
   }
 
-  rememberShellMutationSnapshot(ctx: ExtensionContext, toolName: string, input: unknown): void {
-    this.#shellMutationSnapshots.set(
-      this.#shellMutationSnapshotKey(ctx, toolName, input),
-      workingTreeSnapshot(ctx.cwd) as Record<string, string>
-    );
-    evictOldest(this.#shellMutationSnapshots, 100);
+  consumeShellMutationSnapshot(ctx: ExtensionContext, toolName: string, input: unknown): Record<string, string> | undefined {
+    return this.consumeShellVerificationSnapshot(ctx, toolName, input)?.snapshot as Record<string, string> | undefined;
   }
 
-  consumeShellMutationSnapshot(ctx: ExtensionContext, toolName: string, input: unknown): Record<string, string> | undefined {
-    const key = this.#shellMutationSnapshotKey(ctx, toolName, input);
-    const snapshot = this.#shellMutationSnapshots.get(key);
-    this.#shellMutationSnapshots.delete(key);
-    return snapshot;
+  consumeShellVerificationSnapshot(ctx: ExtensionContext, toolName: string, input: unknown, toolCallId?: string) {
+    return this.#shellMutationSnapshots.consume(ctx, toolName, input, toolCallId, this.taskIdentity(ctx)?.taskRunId);
   }
 
   clearShellMutationSnapshots(ctx: ExtensionContext): void {
-    const prefix = `${this.sessionKey(ctx)}\u0000`;
-    for (const key of this.#shellMutationSnapshots.keys()) {
-      if (key.startsWith(prefix)) this.#shellMutationSnapshots.delete(key);
-    }
+    this.#shellMutationSnapshots.clear(ctx);
+    this.projectVerification.clear(ctx);
   }
 
   hasAutoPackedPrompt(key: string): boolean {