@guanlin4924/devflow-pi 0.1.95 → 0.1.97

package/plugins/devflow-core/extensions/devflow-core.ts

@@ -1,6 +1,7 @@
 import { createHash, createHmac, randomBytes, randomUUID } from "node:crypto";
 import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from "node:fs";
-import { appendFile, mkdir, rename, writeFile } from "node:fs/promises";
+import { appendFile, mkdir, rename, unlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
@@ -15,6 +16,7 @@ import { loadProjectContext } from "../../../src/project-context.ts";
 import { runProjectInitialization } from "../../../src/project-initializer.ts";
 import { projectControlDatabasePath } from "../../../src/paths.ts";
 import { generateProjectDocuments } from "../../../src/project-documents.ts";
+import { describeStartupIssue, renderStartupBriefing } from "../../../src/startup-briefing.ts";
 import { exportInitializationSnapshot, importLegacyInitialization, switchInitializationAuthority } from "../../../src/project-migration.ts";
 import { migrateLegacyProjectLayout } from "../../../src/project-layout.ts";
 import {
@@ -43,6 +45,67 @@ export type SessionControlState = {
   label: string;
 };
 
+/**
+ * Credentials entered in the control panel are deliberately session-local.
+ * Keeping them in a Map (instead of process.env) is important: every Agent
+ * child process inherits the extension environment, while only the Core
+ * acceptance runner is allowed to receive these values explicitly.
+ */
+export class TestCredentialStore {
+  private readonly values = new Map<string, string>();
+
+  set(name: string, value: string): void {
+    if (!name || !value) {
+      this.values.delete(name);
+      return;
+    }
+    this.values.set(name, value);
+  }
+
+  clear(name: string): void {
+    this.values.delete(name);
+  }
+
+  clearAll(): void {
+    this.values.clear();
+  }
+
+  has(name: string): boolean {
+    return this.values.has(name);
+  }
+
+  /** Return only values declared by the current project's profiles. */
+  forEnvironment(names: Iterable<string>): Record<string, string> {
+    const result: Record<string, string> = {};
+    for (const name of names) {
+      const value = this.values.get(name);
+      if (value !== undefined) result[name] = value;
+    }
+    return result;
+  }
+}
+
+export function declaredSecretEnvironmentNames(cwd: string): string[] {
+  const root = path.join(cwd, ".devflow", "planning", "test-environments");
+  if (!existsSync(root)) return [];
+  const names = new Set<string>();
+  for (const file of readdirSync(root)) {
+    if (!file.endsWith(".json")) continue;
+    try {
+      const profile = JSON.parse(readFileSync(path.join(root, file), "utf8")) as Record<string, unknown>;
+      const secretEnv = profile.secret_env;
+      if (!secretEnv || typeof secretEnv !== "object" || Array.isArray(secretEnv)) continue;
+      for (const value of Object.values(secretEnv as Record<string, unknown>)) {
+        if (typeof value === "string" && value) names.add(value);
+      }
+    } catch {
+      // Doctor owns profile validation; an invalid profile contributes no
+      // injectable names and therefore cannot widen the secret boundary.
+    }
+  }
+  return [...names].sort();
+}
+
 type ProjectInitializationMode = "plan" | "apply";
 
 type ProjectInitializationRequest = {
@@ -540,6 +603,118 @@ type ProcessResult = {
   stderr: string;
 };
 
+const EXPLORE_IDLE_MS = 10 * 60 * 1000;
+const EXPLORE_TOTAL_MS = 60 * 60 * 1000;
+
+export type ExploreHostRequest = {
+  id: number;
+  method: "start" | "observe" | "act" | "assert" | "draft" | "stop";
+  params?: Record<string, unknown>;
+};
+
+/** Small JSON-lines client. The host owns Playwright; Core owns its lifetime. */
+export class ExploreHostManager {
+  private child: any;
+  private nextId = 1;
+  private readerTask?: Promise<void>;
+  private readonly pending = new Map<number, { resolve: (value: unknown) => void; reject: (error: Error) => void }>();
+  private idleTimer?: ReturnType<typeof setTimeout>;
+  private totalTimer?: ReturnType<typeof setTimeout>;
+  private lastActivity = 0;
+
+  get running(): boolean { return Boolean(this.child); }
+
+  async start(hostPath: string, cwd: string, environmentFile: string, secrets: Record<string, string>): Promise<void> {
+    if (this.child) throw new Error("an explore session is already active");
+    const inherited = process.env;
+    const env: Record<string, string> = {};
+    for (const name of ["PATH", "HOME", "TMPDIR", "LANG", "PLAYWRIGHT_BROWSERS_PATH"]) {
+      const value = inherited[name];
+      if (value !== undefined) env[name] = value;
+    }
+    env.DEVFLOW_EXPLORE_ENVIRONMENT_FILE = environmentFile;
+    for (const [name, value] of Object.entries(secrets)) env[name] = value;
+    this.child = Bun.spawn(["node", hostPath], { cwd, env, stdin: "pipe", stdout: "pipe", stderr: "pipe", detached: true });
+    void new Response(this.child.stderr).text();
+    this.lastActivity = Date.now();
+    this.readerTask = this.readResponses(this.child.stdout);
+    this.totalTimer = setTimeout(() => void this.stop("explore session exceeded the 60 minute limit"), EXPLORE_TOTAL_MS);
+    this.armIdleTimer();
+  }
+
+  async request(method: ExploreHostRequest["method"], params: Record<string, unknown> = {}): Promise<any> {
+    if (!this.child) throw new Error("no active explore session");
+    const id = this.nextId++;
+    const request = JSON.stringify({ id, method, params }) + "\n";
+    this.lastActivity = Date.now();
+    this.armIdleTimer();
+    const result = new Promise<unknown>((resolve, reject) => this.pending.set(id, { resolve, reject }));
+    try {
+      this.child.stdin.write(request);
+    } catch (error) {
+      this.pending.delete(id);
+      throw error;
+    }
+    return result;
+  }
+
+  async stop(reason = "explore session stopped"): Promise<void> {
+    const child = this.child;
+    if (!child) return;
+    this.child = undefined;
+    if (this.idleTimer) clearTimeout(this.idleTimer);
+    if (this.totalTimer) clearTimeout(this.totalTimer);
+    for (const pending of this.pending.values()) pending.reject(new Error(reason));
+    this.pending.clear();
+    try { child.stdin?.end(); } catch { /* already closed */ }
+    const pid = typeof child.pid === "number" ? child.pid : undefined;
+    if (pid !== undefined) {
+      try { process.kill(-pid, "SIGTERM"); } catch { try { process.kill(pid, "SIGTERM"); } catch { /* exited */ } }
+      await new Promise(resolve => setTimeout(resolve, 100));
+      try { process.kill(-pid, "SIGKILL"); } catch { try { process.kill(pid, "SIGKILL"); } catch { /* exited */ } }
+    }
+  }
+
+  terminateNow(): void {
+    const pid = typeof this.child?.pid === "number" ? this.child.pid : undefined;
+    if (pid === undefined) return;
+    try { process.kill(-pid, "SIGKILL"); } catch { try { process.kill(pid, "SIGKILL"); } catch { /* exited */ } }
+  }
+
+  private armIdleTimer(): void {
+    if (this.idleTimer) clearTimeout(this.idleTimer);
+    const delay = Math.max(1, EXPLORE_IDLE_MS - (Date.now() - this.lastActivity));
+    this.idleTimer = setTimeout(() => void this.stop("explore session idle timeout"), delay);
+  }
+
+  private async readResponses(stream: ReadableStream<Uint8Array>): Promise<void> {
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+      for (;;) {
+        const chunk = await reader.read();
+        if (chunk.done) break;
+        buffer += decoder.decode(chunk.value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+        for (const line of lines) {
+          if (!line.trim()) continue;
+          let response: any;
+          try { response = JSON.parse(line); } catch { continue; }
+          const waiter = this.pending.get(response?.id);
+          if (!waiter) continue;
+          this.pending.delete(response.id);
+          if (response.ok === true) waiter.resolve(response.result);
+          else waiter.reject(new Error(String(response?.error?.message ?? "explore-host request failed")));
+        }
+      }
+    } finally {
+      if (this.child) await this.stop("explore-host exited unexpectedly");
+    }
+  }
+}
+
 type DoctorStatus = "pass" | "warn" | "fail";
 
 type DoctorCheck = {
@@ -597,6 +772,7 @@ const REQUIRED_EXTENSION_TOOLS = [
   "devflow_context_cursor",
   "devflow_design_rule",
   "devflow_mainflow",
+  "devflow_explore",
   "devflow_approval",
 ];
 
@@ -608,6 +784,7 @@ const REQUIRED_SKILLS = [
   "workflow-api-contract",
   "workflow-api-supplement",
   "workflow-acceptance-test-design",
+  "workflow-regression-test-design",
   "workflow-backend-tech-spec",
   "workflow-bug-fix",
   "workflow-change-plan",
@@ -673,8 +850,10 @@ const REQUIRED_SCRIPTS = [
   "workflow-orchestrator/scripts/acceptance_test_runner.py",
   "workflow-orchestrator/scripts/machine_evidence.rb",
   "workflow-orchestrator/scripts/review_preflight.py",
+  "workflow-orchestrator/scripts/startup_preflight.py",
   "workflow-orchestrator/scripts/cross_track_consistency_check.rb",
   "workflow-orchestrator/scripts/execution_contract.rb",
+  "workflow-orchestrator/scripts/explore_preflight.py",
   "workflow-code-index/scripts/code_index.py",
   "workflow-context-sync/scripts/context_sync_cursor.py",
 ];
@@ -947,6 +1126,13 @@ function renderResult(result: ProcessResult, details: Record<string, unknown> =
   };
 }
 
+function redactCredentialOutput(result: ProcessResult, values: Record<string, string>): ProcessResult {
+  const secrets = Object.values(values).filter(value => value.length > 0);
+  if (secrets.length === 0) return result;
+  const redact = (text: string) => secrets.reduce((current, secret) => current.split(secret).join("[REDACTED]"), text);
+  return { ...result, stdout: redact(result.stdout), stderr: redact(result.stderr) };
+}
+
 function registeredNames(value: unknown): Set<string> {
   if (Array.isArray(value)) {
     return new Set(
@@ -995,6 +1181,16 @@ function parseJsonResult(result: ProcessResult): Record<string, unknown> | null
   }
 }
 
+function parseJsonOutput(result: ProcessResult): Record<string, unknown> | null {
+  if (!result.stdout) return null;
+  try {
+    const parsed = JSON.parse(result.stdout);
+    return parsed && typeof parsed === "object" ? parsed as Record<string, unknown> : null;
+  } catch {
+    return null;
+  }
+}
+
 export function canonicalReviewJson(value: unknown): string {
   if (value === null || typeof value === "string" || typeof value === "boolean") return JSON.stringify(value);
   if (typeof value === "number" && Number.isFinite(value)) return JSON.stringify(value);
@@ -1115,7 +1311,7 @@ export function workflowResumeDisposition(snapshot: Record<string, unknown>): Wo
   return "blocked";
 }
 
-function workflowDirective(snapshot: Record<string, unknown>, source: "start" | "approval", requirementDraft?: string): string {
+function workflowDirective(snapshot: Record<string, unknown>, source: "start" | "approval", requirementDraft?: string, briefing?: string): string {
   const selectedStep = selectedWorkflowStep(snapshot);
   const reviewInstructions = selectedStep?.id === "code-review"
     ? [
@@ -1153,8 +1349,12 @@ function workflowDirective(snapshot: Record<string, unknown>, source: "start" |
     : [];
   return [
     "<devflow-runtime-directive>",
-    "Devflow 已通过启动预检。读取 skill://workflow-pipeline，并只执行当前项目的一个工作流步骤。",
-    "先调用 devflow_state(action=\"inspect\") 重新确认 revision，再调用 devflow_contract(action=\"status\")；若没有匹配当前 feature/current_step 的 fresh contract，立即调用 devflow_contract(action=\"activate\", feature=<current_feature>, step=<current_step>)，激活成功后才能执行或写入。",
+    briefing
+      ? "Devflow Runtime 已完成开工预检（环境、交接、状态、合同、输入），以下开工简报中的事实已经核实；执行合同已激活，不要再次调用 devflow_state inspect 或 devflow_contract activate。读取 skill://workflow-pipeline，并只执行当前项目的一个工作流步骤。"
+      : "Devflow Runtime 已完成环境与状态检查。读取 skill://workflow-pipeline，并只执行当前项目的一个工作流步骤。",
+    ...(briefing
+      ? ["<startup-briefing>", briefing, "</startup-briefing>"]
+      : ["先调用 devflow_state(action=\"inspect\") 重新确认 revision，再调用 devflow_contract(action=\"status\")；若没有匹配当前 feature/current_step 的 fresh contract，立即调用 devflow_contract(action=\"activate\", feature=<current_feature>, step=<current_step>)，激活成功后才能执行或写入。"]),
     "只按 inspector 返回的当前 step 加载所需 Skill：step.skill 是精确 ID，必须读取 skill://<step.skill>，不得自行添加 workflow- 前缀或改写名称；本回合严禁读取或写入 xd://devflow_transition，严禁调用 devflow_transition，严禁执行 Skill 中的 complete-step/confirm-checkpoint，不得推进下一步骤；状态写回和会话切换由 Runtime 在用户确认后独占处理。",
     ...reviewInstructions,
     ...(parallelInstructions.length > 0 ? parallelInstructions : [
@@ -1584,6 +1784,27 @@ export function approvalReviewText(proposal: ProposalRecord): string {
 
 export default function devflowCore(pi: ExtensionAPI) {
   const { z } = pi.zod;
+  const testCredentials = new TestCredentialStore();
+  const exploreHost = new ExploreHostManager();
+  process.once("exit", () => exploreHost.terminateNow());
+
+  const redactExploreValue = (value: unknown, secrets: Record<string, string>): unknown => {
+    const values = Object.values(secrets).filter(Boolean);
+    if (typeof value === "string") return values.reduce((text, secret) => text.split(secret).join("[REDACTED]"), value);
+    if (Array.isArray(value)) return value.map(item => redactExploreValue(item, secrets));
+    if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, redactExploreValue(item, secrets)]));
+    return value;
+  };
+
+  const exploreHostPath = (): string => {
+    const candidates = [
+      path.join(resolvePluginRoot(), "devflow-quality", "runtime", "playwright", "explore-host.mjs"),
+      path.join(resolvePluginRoot(), "devflow-quality", "runtime", "playwright", "dist", "explore-host.mjs"),
+    ];
+    const found = candidates.find(candidate => existsSync(candidate));
+    if (!found) throw new Error("explore-host.mjs is not installed; build the Devflow Playwright Runtime first");
+    return found;
+  };
   pi.registerTool({
     name: "devflow_project_context",
     label: "Devflow Project Context",
@@ -1690,10 +1911,13 @@ export default function devflowCore(pi: ExtensionAPI) {
   // during extension construction and never becomes model-controlled state.
   const cliSessionResumeRequested = process.env.DEVFLOW_CLI_SESSION_RESUME === "1";
   delete process.env.DEVFLOW_CLI_SESSION_RESUME;
-  let sessionId = randomUUID();
+  let sessionId: string = randomUUID();
   let controlState: SessionControlState = initialControlState();
   let activeContract: ActiveExecutionContract | undefined;
   let contractAgentCalls = 0;
+  let stepUserNotes: string[] = [];
+  let lastAgentReport = "";
+  let sessionBootstrapContext = "";
   const reviewBindingKey = randomBytes(32).toString("hex");
   const pendingReviewTasks = new Map<string, { feature: string; contractId: string }>();
   const completedReviewTasks = new Map<string, { feature: string; contractId: string; report: Record<string, unknown> }>();
@@ -1932,6 +2156,63 @@ export default function devflowCore(pi: ExtensionAPI) {
     return undefined;
   }
 
+  async function activateExecutionContract(
+    ctx: {
+      cwd: string;
+      ui: {
+        confirm(title: string, body: string): Promise<boolean>;
+        setStatus(key: string, text: string | undefined): void;
+        setWidget?(key: string, content: unknown, options?: { placement?: "aboveEditor" | "belowEditor" }): void;
+      };
+    },
+    feature: string,
+    step: string,
+  ): Promise<{ ok: true; contract: ActiveExecutionContract } | { ok: false; reason: string }> {
+    const inspected = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/execution_contract.rb", [
+      "inspect", "--feature", feature, "--step", step, "--json",
+    ]);
+    const payload = parseJsonResult(inspected);
+    const raw = payload?.contract;
+    if (!controlPlaneSucceeded(inspected) || !raw || typeof raw !== "object") {
+      return { ok: false, reason: inspected.stderr || inspected.stdout || "Core returned no execution contract." };
+    }
+    const contract = contractFromRecord(raw as Record<string, unknown>);
+    if (!contract) return { ok: false, reason: "Core returned an invalid execution contract." };
+    const confirmed = await ctx.ui.confirm(
+      "激活 Devflow 执行合同",
+      [
+        `合同：${contract.contractId}`,
+        `Feature：${contract.feature}`,
+        `步骤：${contract.step}`,
+        `STATE revision：${contract.stateRevision ?? "未初始化"}`,
+        `图谱 revision：${contract.graphRevision ?? 0}`,
+        `可写路径：${contract.allowedPaths.join(", ")}`,
+        `允许 Agent：${contract.allowedAgents.join(", ")}`,
+        `固定检查器：${contract.checkerIds.join(", ") || "无"}`,
+        `冻结哈希：${contract.frozenHash}`,
+        "确认后低成本模型只能在以上范围执行；未知项必须阻塞升级。",
+      ].join("\n"),
+    );
+    if (!confirmed) return { ok: false, reason: "User declined execution contract activation." };
+    try {
+      const createArgs = ["create", "--feature", feature, "--step", step, "--write", "--json"];
+      if (contract.stateRevision !== undefined) createArgs.push("--expected-state-revision", String(contract.stateRevision));
+      if (contract.graphRevision !== undefined) createArgs.push("--expected-graph-revision", String(contract.graphRevision));
+      const written = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/execution_contract.rb", createArgs);
+      if (!controlPlaneSucceeded(written)) {
+        return { ok: false, reason: written.stderr || written.stdout || "Execution contract activation failed." };
+      }
+      const writtenPayload = parseJsonResult(written);
+      contract.contractPath = typeof writtenPayload?.path === "string" ? writtenPayload.path : ".devflow/planning/contracts/";
+      activeContract = contract;
+      contractAgentCalls = 0;
+      setControlState(ctx, executingState(`合同执行：${contract.contractId}`));
+      return { ok: true, contract };
+    } catch (error) {
+      return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+    }
+  }
+
   async function collectProjectInitialization(ctx: {
     cwd: string;
     ui: {
@@ -2055,12 +2336,13 @@ export default function devflowCore(pi: ExtensionAPI) {
     });
   }
 
-  async function runPython(cwd: string, relativeScript: string, args: string[]) {
+  async function runPython(cwd: string, relativeScript: string, args: string[], extraEnv: Record<string, string> = {}) {
     assertRuntimeProjectBoundary(cwd);
     const kitRoot = resolveKitRoot(cwd);
     return runProcess(["python3", path.join(kitRoot, relativeScript), ...args], cwd, {
       DEVFLOW_KIT_ROOT: kitRoot,
       OMP_PROJECT_DIR: cwd,
+      ...extraEnv,
     });
   }
 
@@ -2248,6 +2530,114 @@ export default function devflowCore(pi: ExtensionAPI) {
     return { ok: checks.every(check => check.status !== "fail"), checks, models };
   }
 
+  async function runStartupPreflight(
+    ctx: DoctorContext & {
+      ui: {
+        confirm(title: string, body: string): Promise<boolean>;
+        notify(message: string, level: "info" | "error"): void;
+        setStatus(key: string, text: string | undefined): void;
+        setWidget?(key: string, content: unknown, options?: { placement?: "aboveEditor" | "belowEditor" }): void;
+      };
+    },
+    snapshot: Record<string, unknown>,
+    options: { doctorAlreadyPassed?: boolean; handoffPath?: string } = {},
+  ): Promise<{ ok: true; briefing?: string } | { ok: false }> {
+    if (options.doctorAlreadyPassed !== true) {
+      const report = await runDoctor(ctx);
+      if (!report.ok) {
+        setControlState(ctx, { intent: "workflow-execute", phase: "blocked", label: "开工预检失败" });
+        ctx.ui.notify(formatDoctorReport(report).slice(0, 10000), "error");
+        return { ok: false };
+      }
+    }
+    if (workflowResumeDisposition(snapshot) !== "execute" || snapshot.action === "run_parallel_window") {
+      return { ok: true };
+    }
+
+    try {
+    const feature = typeof snapshot.current_feature === "string" ? snapshot.current_feature : "";
+    const step = String(selectedWorkflowStep(snapshot)?.id ?? "");
+    if (!feature || !step) {
+      setControlState(ctx, { intent: "workflow-execute", phase: "blocked", label: "开工预检未通过" });
+      ctx.ui.notify("开工预检未通过：当前 Feature 或步骤不可用。", "error");
+      return { ok: false };
+    }
+    let contract = activeContract;
+    if (!contract || contract.feature !== feature || contract.step !== step || !(await contractIsFresh(ctx.cwd, contract))) {
+      const activated = await activateExecutionContract(ctx, feature, step);
+      if (!activated.ok) {
+        setControlState(ctx, { intent: "workflow-execute", phase: "blocked", label: "开工预检：执行合同未激活" });
+        ctx.ui.notify(`开工预检：执行合同未激活。${activated.reason}`, "error");
+        return { ok: false };
+      }
+      contract = activated.contract;
+    }
+    if (!contract.contractPath) {
+      setControlState(ctx, { intent: "workflow-execute", phase: "blocked", label: "开工预检：执行合同未激活" });
+      ctx.ui.notify("开工预检：执行合同未激活。合同冻结路径不可用。", "error");
+      return { ok: false };
+    }
+    const contractAbsolute = path.resolve(ctx.cwd, contract.contractPath);
+    const contractRelative = path.relative(ctx.cwd, contractAbsolute).split(path.sep).join("/");
+    if (!contractRelative || contractRelative === ".." || contractRelative.startsWith("../")) {
+      setControlState(ctx, { intent: "workflow-execute", phase: "blocked", label: "开工预检：执行合同未激活" });
+      ctx.ui.notify("开工预检：执行合同未激活。合同冻结路径越出项目。", "error");
+      return { ok: false };
+    }
+    const preflight = await runPython(ctx.cwd, "workflow-orchestrator/scripts/startup_preflight.py", [
+      "--root", ctx.cwd,
+      "--feature", feature,
+      "--step", step,
+      "--contract", contractRelative,
+      ...(options.handoffPath ? ["--handoff", options.handoffPath] : []),
+    ]);
+    const payload = parseJsonOutput(preflight);
+    if (!payload || payload.status !== "ready") {
+      setControlState(ctx, { intent: "workflow-execute", phase: "blocked", label: "开工预检未通过" });
+      const issues = Array.isArray(payload?.issues) ? payload.issues : [];
+      const details = issues.length > 0
+        ? issues.map(issue => `- ${describeStartupIssue(issue && typeof issue === "object" ? issue as Record<string, unknown> : {})}`).join("\n")
+        : "- 开工预检输出无法解析";
+      ctx.ui.notify(`开工预检未通过：\n${details}`, "error");
+      return { ok: false };
+    }
+    const facts = payload.facts && typeof payload.facts === "object" ? payload.facts as Record<string, unknown> : {};
+    const handoff = payload.handoff && typeof payload.handoff === "object" ? payload.handoff as Record<string, unknown> : {};
+    return {
+      ok: true,
+      briefing: renderStartupBriefing(facts, handoff, {
+        revision: snapshot.revision,
+        handoffProvided: Boolean(options.handoffPath),
+      }),
+    };
+    } catch (error) {
+      setControlState(ctx, { intent: "workflow-execute", phase: "blocked", label: "开工预检未通过" });
+      ctx.ui.notify(`开工预检未通过：${error instanceof Error ? error.message : String(error)}`, "error");
+      return { ok: false };
+    }
+  }
+
+  async function startWorkflowAfterPreflight(
+    ctx: DoctorContext & {
+      ui: {
+        confirm(title: string, body: string): Promise<boolean>;
+        notify(message: string, level: "info" | "error"): void;
+        setStatus(key: string, text: string | undefined): void;
+        setWidget?(key: string, content: unknown, options?: { placement?: "aboveEditor" | "belowEditor" }): void;
+      };
+    },
+    snapshot: Record<string, unknown>,
+    source: "start" | "approval",
+    options: { doctorAlreadyPassed?: boolean; handoffPath?: string; executingLabel?: string } = {},
+  ): Promise<void> {
+    const preflight = await runStartupPreflight(ctx, snapshot, options);
+    if (!preflight.ok) return;
+    setControlState(ctx, executingState(options.executingLabel));
+    if (preflight.briefing) await triggerWorkflow(snapshot, source, undefined, preflight.briefing);
+    else if (source === "start") await triggerWorkflow(snapshot, "start");
+    else await triggerWorkflow(snapshot, "approval");
+  }
+
   async function inspectWorkflow(cwd: string): Promise<{ result: ProcessResult; snapshot: Record<string, unknown> | null }> {
     const result = await runRuby(cwd, "workflow-orchestrator/scripts/inspect_state.rb", ["--json"]);
     return { result, snapshot: parseJsonResult(result) };
@@ -2294,26 +2684,33 @@ export default function devflowCore(pi: ExtensionAPI) {
   async function requestControlledRollover(ctx: { cwd: string; sessionManager: { getSessionId(): string } }, snapshot: Record<string, unknown>) {
     const revision = typeof snapshot.revision === "number" ? snapshot.revision : undefined;
     if (revision === undefined) throw new Error("Cannot prepare session rollover without a STATE revision.");
-    const prepared = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/session_rollover.rb", [
-      "prepare", "--write", "--json", "--expected-revision", String(revision),
-      "--source-session-id", ctx.sessionManager.getSessionId(), "--reason", "workflow_step_boundary",
-    ]);
-    const payload = parseJsonResult(prepared);
-    if (!prepared.ok || !payload || typeof payload.revision !== "number") {
-      throw new Error(prepared.stderr || prepared.stdout || "rollover prepare failed");
-    }
-    const rollover = payload.rollover as Record<string, unknown> | undefined;
-    const rolloverId = typeof rollover?.id === "string" ? rollover.id : undefined;
-    if (!rolloverId) throw new Error("rollover prepare returned no rollover id");
-    const synced = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/sync_artifacts.rb", [
-      "--write", "--no-preserve", "--json",
-    ]);
-    if (!controlPlaneSucceeded(synced)) {
-      throw new Error(synced.stderr || synced.stdout || "artifact registry sync after rollover prepare failed");
+    const carryPath = path.join(tmpdir(), `devflow-rollover-carry-${randomUUID()}.json`);
+    try {
+      await writeFile(carryPath, JSON.stringify({ user_notes: stepUserNotes, agent_report: lastAgentReport }), "utf8");
+      const prepared = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/session_rollover.rb", [
+        "prepare", "--write", "--json", "--expected-revision", String(revision),
+        "--source-session-id", ctx.sessionManager.getSessionId(), "--reason", "workflow_step_boundary",
+        "--carry-file", carryPath,
+      ]);
+      const payload = parseJsonResult(prepared);
+      if (!prepared.ok || !payload || typeof payload.revision !== "number") {
+        throw new Error(prepared.stderr || prepared.stdout || "rollover prepare failed");
+      }
+      const rollover = payload.rollover as Record<string, unknown> | undefined;
+      const rolloverId = typeof rollover?.id === "string" ? rollover.id : undefined;
+      if (!rolloverId) throw new Error("rollover prepare returned no rollover id");
+      const synced = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/sync_artifacts.rb", [
+        "--write", "--no-preserve", "--json",
+      ]);
+      if (!controlPlaneSucceeded(synced)) {
+        throw new Error(synced.stderr || synced.stdout || "artifact registry sync after rollover prepare failed");
+      }
+      // The runtime can observe the request immediately; arm the switch handler first.
+      pendingRollover = { snapshot, preparedRevision: payload.revision, rolloverId };
+      await enqueueControlledRolloverRequest(ctx.cwd, rolloverId, ctx.sessionManager.getSessionId());
+    } finally {
+      await unlink(carryPath).catch(() => undefined);
     }
-    // The runtime can observe the request immediately; arm the switch handler first.
-    pendingRollover = { snapshot, preparedRevision: payload.revision, rolloverId };
-    await enqueueControlledRolloverRequest(ctx.cwd, rolloverId, ctx.sessionManager.getSessionId());
   }
 
   function parallelBranches(snapshot: Record<string, unknown>): Array<{ workflow_step: string; track: string }> {
@@ -2361,7 +2758,9 @@ export default function devflowCore(pi: ExtensionAPI) {
     return { ...snapshot, parallel_run: payload.run };
   }
 
-  async function triggerWorkflow(snapshot: Record<string, unknown>, source: "start" | "approval", requirementDraft?: string) {
+  async function triggerWorkflow(snapshot: Record<string, unknown>, source: "start" | "approval", requirementDraft?: string, briefing?: string) {
+    stepUserNotes = [];
+    lastAgentReport = "";
     if (snapshot.action !== "run_parallel_window") {
       parallelRunActive = false;
       parallelContinuationQueued = false;
@@ -2372,26 +2771,35 @@ export default function devflowCore(pi: ExtensionAPI) {
     }
     const preparedSnapshot = await prepareParallelRun(projectRoot ?? process.cwd(), snapshot);
     activeWorkflowTurn = true;
-    await pi.sendUserMessage(workflowDirective(preparedSnapshot, source, requirementDraft));
+    await pi.sendUserMessage(workflowDirective(preparedSnapshot, source, requirementDraft, briefing));
   }
 
   async function resumeInspectedWorkflow(
     ctx: {
       cwd: string;
+      models: { resolve(spec: string): ModelLike | undefined };
       ui: {
+        confirm(title: string, body: string): Promise<boolean>;
         notify(message: string, level: "info" | "error"): void;
         setStatus(key: string, text: string | undefined): void;
         setWidget?(key: string, content: string[] | undefined, options?: { placement?: "aboveEditor" | "belowEditor" }): void;
       };
     },
     snapshot: Record<string, unknown>,
+    options: { doctorAlreadyPassed: boolean },
   ): Promise<WorkflowResumeDisposition> {
     const disposition = workflowResumeDisposition(snapshot);
     const stepId = String(selectedWorkflowStep(snapshot)?.id ?? "当前步骤");
     if (disposition === "execute") {
-      setControlState(ctx, executingState(`恢复并执行 ${stepId}`));
-      ctx.ui.notify(`Devflow 已恢复到 ${stepId}，当前步骤产物尚未完成，正在继续执行。`, "info");
-      await triggerWorkflow(snapshot, "start");
+      setControlState(ctx, executingState("开工预检中"));
+      ctx.ui.notify(`Devflow 已恢复到 ${stepId}，当前步骤产物尚未完成，正在完成开工预检。`, "info");
+      void startWorkflowAfterPreflight(ctx, snapshot, "start", {
+        doctorAlreadyPassed: options.doctorAlreadyPassed,
+        executingLabel: `恢复并执行 ${stepId}`,
+      }).catch(error => {
+        setControlState(ctx, { intent: "workflow-execute", phase: "blocked", label: "开工预检未通过" });
+        ctx.ui.notify(`开工预检未通过：${String(error)}`, "error");
+      });
       return disposition;
     }
     if (disposition === "review") {
@@ -2488,6 +2896,7 @@ export default function devflowCore(pi: ExtensionAPI) {
 
   type ProjectControlCommandContext = {
     cwd: string;
+    models: DoctorContext["models"];
     sessionManager: { getSessionId(): string };
     ui: ProjectControlUi & {
       select(title: string, options: string[]): Promise<string | undefined>;
@@ -2668,6 +3077,45 @@ export default function devflowCore(pi: ExtensionAPI) {
     }
   }
 
+  async function manageTestCredentials(ctx: ProjectControlCommandContext): Promise<void> {
+    const names = declaredSecretEnvironmentNames(ctx.cwd);
+    if (names.length === 0) {
+      ctx.ui.notify("当前项目没有声明测试凭据（secret_env）。", "info");
+      return;
+    }
+    for (;;) {
+      const labels = names.map(name => `${name}（${testCredentials.has(name) || process.env[name] !== undefined ? "已设置" : "未设置"}）`);
+      const selected = await ctx.ui.select("测试凭据（输入内容会显示在屏幕上，不会持久化）", [
+        ...labels,
+        "清除全部",
+        "返回",
+      ]);
+      if (!selected || selected === "返回") return;
+      if (selected === "清除全部") {
+        if (await ctx.ui.confirm("清除全部测试凭据", "只清除本次 devflow-pi 会话内存中的面板凭据；不会修改启动环境。继续吗？")) {
+          testCredentials.clearAll();
+          ctx.ui.notify("已清除本次会话的面板凭据。", "info");
+        }
+        continue;
+      }
+      const index = labels.indexOf(selected);
+      const name = names[index];
+      if (!name) continue;
+      const action = await ctx.ui.select(`测试凭据：${name}`, ["设置/覆盖", "清除面板值", "返回"]);
+      if (!action || action === "返回") continue;
+      if (action === "清除面板值") {
+        testCredentials.clear(name);
+        ctx.ui.notify(`已清除 ${name} 的面板值；启动环境值仍可能存在。`, "info");
+        continue;
+      }
+      const value = await ctx.ui.input(`输入测试凭据：${name}`, "输入值（会显示在屏幕上，不会持久化）");
+      if (value === undefined) continue;
+      if (!value) testCredentials.clear(name);
+      else testCredentials.set(name, value);
+      ctx.ui.notify(`${name} 已${value ? "设置" : "清除"}（值不会显示）。`, "info");
+    }
+  }
+
   async function openProjectControlPanel(ctx: ProjectControlCommandContext): Promise<void> {
     for (;;) {
       // The control panel is a read-only projection. Each action below reads a
@@ -2683,6 +3131,7 @@ export default function devflowCore(pi: ExtensionAPI) {
       if (snapshot.action === "await_user_confirmation") options.push("审查并批准推进…");
       if (hasSafeRecoveryPlan(snapshot)) options.push("执行安全恢复…");
       if (typeof snapshot.current_feature === "string" && !["completed", "cancelled", "failed"].includes(String(snapshot.status))) options.push("取消当前功能…");
+      options.push("测试凭据…");
       const approvalCount = await pendingApprovalCount(ctx.cwd);
       const approvalOption = approvalCount === null ? null : `待审批（${approvalCount}）…`;
       if (approvalOption) options.push(approvalOption);
@@ -2701,7 +3150,7 @@ export default function devflowCore(pi: ExtensionAPI) {
           ctx.ui.notify(`启动前状态读取失败：${fresh.result.stderr || fresh.result.stdout}`, "error");
           return;
         }
-        await resumeInspectedWorkflow(ctx, fresh.snapshot);
+        await resumeInspectedWorkflow(ctx, fresh.snapshot, { doctorAlreadyPassed: false });
         return;
       }
       if (selected === "审查并批准推进…") {
@@ -2716,6 +3165,10 @@ export default function devflowCore(pi: ExtensionAPI) {
         await cancelFeatureFromPanel(ctx);
         return;
       }
+      if (selected === "测试凭据…") {
+        await manageTestCredentials(ctx);
+        continue;
+      }
       if (approvalOption && selected === approvalOption) {
         await reviewPendingApprovalsFromPanel(ctx);
         continue;
@@ -2797,6 +3250,36 @@ export default function devflowCore(pi: ExtensionAPI) {
 
   pi.setLabel("Devflow Project Runtime");
 
+  async function refreshSessionBootstrapContext(
+    ctx: { cwd: string },
+    source: "startup" | "rollover",
+  ): Promise<{ ok: true } | { ok: false; reason: string }> {
+    sessionBootstrapContext = "";
+    try {
+      const result = await runHook(ctx.cwd, "start.py", {
+        session_id: sessionId,
+        cwd: ctx.cwd,
+        source,
+        hook_event_name: "SessionStart",
+      });
+      if (!result.ok) return { ok: false, reason: result.stderr || result.stdout || "start.py did not complete successfully" };
+      const bootstrap = parseJsonResult(result);
+      const hookOutput = bootstrap?.hookSpecificOutput;
+      const additionalContext = hookOutput && typeof hookOutput === "object"
+        ? (hookOutput as Record<string, unknown>).additionalContext
+        : undefined;
+      if (typeof additionalContext === "string" && additionalContext) {
+        sessionBootstrapContext = additionalContext.length > 8000
+          ? `${additionalContext.slice(0, 7999)}…`
+          : additionalContext;
+      }
+      return { ok: true };
+    } catch (error) {
+      sessionBootstrapContext = "";
+      return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+    }
+  }
+
   pi.on("session_start", async (_event, ctx) => {
     projectRoot = ctx.cwd;
     sessionId = randomUUID();
@@ -2806,14 +3289,9 @@ export default function devflowCore(pi: ExtensionAPI) {
       ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
       return;
     }
-    const result = await runHook(ctx.cwd, "start.py", {
-      session_id: sessionId,
-      cwd: ctx.cwd,
-      source: "startup",
-      hook_event_name: "SessionStart",
-    });
-    if (!result.ok) {
-      ctx.ui.notify(`Devflow bootstrap failed: ${result.stderr || result.stdout}`, "error");
+    const bootstrap = await refreshSessionBootstrapContext(ctx, "startup");
+    if (!bootstrap.ok) {
+      ctx.ui.notify(`Devflow bootstrap failed: ${bootstrap.reason}`, "error");
       return;
     }
     ctx.ui.setStatus("devflow", "Devflow ready");
@@ -2866,8 +3344,15 @@ export default function devflowCore(pi: ExtensionAPI) {
           ctx.ui.notify(`会话已恢复，但工作流校验失败，未启动 AI：${String(after.snapshot.reason ?? "state validation failed")}`, "error");
           return;
         }
-        setControlState(ctx, executingState("恢复已认领的干净会话"));
-        await triggerWorkflow(after.snapshot, "approval");
+        setControlState(ctx, executingState("开工预检中"));
+        void startWorkflowAfterPreflight(ctx, after.snapshot, "approval", {
+          handoffPath: typeof rollover.handoff_path === "string" ? rollover.handoff_path : undefined,
+          executingLabel: "恢复已认领的干净会话",
+        }).catch(error => {
+          setControlState(ctx, { intent: "workflow-execute", phase: "blocked", label: "开工预检未通过" });
+          ctx.ui.notify(`开工预检未通过：${String(error)}`, "error");
+        });
+        return;
       } else if (!consumed.ok || !synced || !controlPlaneSucceeded(synced)) {
         ctx.ui.notify(`已认领的会话交接无法恢复；工作流保持冻结：${consumed.stderr || consumed.stdout}`, "error");
       }
@@ -2883,7 +3368,7 @@ export default function devflowCore(pi: ExtensionAPI) {
         ctx.ui.notify(`Devflow resume failed: ${inspected.result.stderr || inspected.result.stdout || "invalid inspector JSON"}`, "error");
         return;
       }
-      await resumeInspectedWorkflow(ctx, inspected.snapshot);
+      await resumeInspectedWorkflow(ctx, inspected.snapshot, { doctorAlreadyPassed: true });
     }
   });
 
@@ -2925,6 +3410,8 @@ export default function devflowCore(pi: ExtensionAPI) {
       ctx.ui.notify(`Devflow 会话交接消费或 registry 同步失败；工作流保持冻结：${consumed.stderr || consumed.stdout || synced?.stderr || synced?.stdout}`, "error");
       return;
     }
+    sessionId = targetSessionId;
+    await refreshSessionBootstrapContext(ctx, "rollover");
     pendingRollover = undefined;
     activeContract = undefined;
     contractAgentCalls = 0;
@@ -2934,8 +3421,15 @@ export default function devflowCore(pi: ExtensionAPI) {
       ctx.ui.notify(`会话已切换，但工作流校验失败，未启动 AI：${String(next.snapshot?.reason ?? next.result.stderr ?? next.result.stdout ?? "state validation failed")}`, "error");
       return;
     }
-    setControlState(ctx, executingState("在干净会话中执行下一工作流步骤"));
-    await triggerWorkflow(next.snapshot, "approval");
+    const claimedRollover = claimedPayload.rollover as Record<string, unknown> | undefined;
+    setControlState(ctx, executingState("开工预检中"));
+    void startWorkflowAfterPreflight(ctx, next.snapshot, "approval", {
+      handoffPath: typeof claimedRollover?.handoff_path === "string" ? claimedRollover.handoff_path : undefined,
+      executingLabel: "在干净会话中执行下一工作流步骤",
+    }).catch(error => {
+      setControlState(ctx, { intent: "workflow-execute", phase: "blocked", label: "开工预检未通过" });
+      ctx.ui.notify(`开工预检未通过：${String(error)}`, "error");
+    });
   });
 
   pi.on("before_agent_start", async event => {
@@ -2943,11 +3437,25 @@ export default function devflowCore(pi: ExtensionAPI) {
       await appendEngineEvidence(projectRoot, "ai_runtime_initialized", { source: "runtime_before_agent_start" });
       await appendEngineEvidence(projectRoot, "ai_invocation", { source: "runtime_before_agent_start" });
     }
-    return { systemPrompt: [...event.systemPrompt, DEVFLOW_CHINESE_LANGUAGE_POLICY] };
+    return {
+      systemPrompt: [
+        ...event.systemPrompt,
+        ...(sessionBootstrapContext ? [sessionBootstrapContext] : []),
+        DEVFLOW_CHINESE_LANGUAGE_POLICY,
+      ],
+    };
   });
 
   pi.on("agent_end", async (event, ctx) => {
     if (!activeWorkflowTurn || event.willContinue) return;
+    const assistant = [...event.messages].reverse().find(message => (
+      message && typeof message === "object" && (message as { role?: unknown }).role === "assistant"
+    ));
+    const content = assistant && typeof assistant === "object" ? (assistant as { content?: unknown }).content : undefined;
+    lastAgentReport = Array.isArray(content)
+      ? content.flatMap(part => part && typeof part === "object" && (part as { type?: unknown }).type === "text"
+        && typeof (part as { text?: unknown }).text === "string" ? [(part as { text: string }).text] : []).join("")
+      : "";
     activeWorkflowTurn = false;
     if (parallelRunActive) {
       parallelContinuationQueued = false;
@@ -2983,6 +3491,10 @@ export default function devflowCore(pi: ExtensionAPI) {
   pi.on("input", async (event, ctx) => {
     if (event.source !== "interactive") return;
     const controlAction = classifyNaturalControlAction(event.text);
+    const stepNote = event.text.trim();
+    if (controlState.intent === "workflow-execute" && !controlAction && stepNote && !stepNote.startsWith("/")) {
+      stepUserNotes.push(stepNote);
+    }
     if (controlState.intent === "requirement-draft" && controlState.phase === "planning") {
       const requirementDraft = event.text.trim();
       if (!requirementDraft) return { handled: true };
@@ -3471,6 +3983,7 @@ export default function devflowCore(pi: ExtensionAPI) {
   });
 
   pi.on("session_stop", async (_event, ctx) => {
+    await exploreHost.stop("Devflow session stopped");
     const result = await runHook(ctx.cwd, "context_sync_gate.py", {
       session_id: sessionId,
       cwd: ctx.cwd,
@@ -3775,12 +4288,106 @@ export default function devflowCore(pi: ExtensionAPI) {
     },
   });
 
+  pi.registerTool({
+    name: "devflow_explore",
+    label: "Devflow Explore",
+    description: [
+      "在已批准的 environment_profile 内启动结构化页面探索会话；探索结果不是验收结论，draft 仍必须经过编译、校验和用户批准。",
+      "凭据只按 profile.secret_env 注入 explore-host 子进程，永不写入 process.env、日志或工具输出。页面文本可能包含个人信息，本工具不做页面级个人信息脱敏。",
+    ].join(" "),
+    parameters: z.object({
+      action: z.enum(["start", "observe", "act", "assert", "draft", "stop"]),
+      feature: z.string().min(1).optional(),
+      environment_profile: z.string().min(1).optional(),
+      url: z.string().min(1).optional(),
+      scope: z.string().optional(),
+      full: z.boolean().optional(),
+      table_text: z.boolean().optional(),
+      ref: z.string().min(1).optional(),
+      operation: z.enum(["click", "fill", "check", "uncheck", "select", "press"]).optional(),
+      action_name: z.string().optional(),
+      value: z.string().optional(),
+      value_from_secret: z.string().optional(),
+      kind: z.string().optional(),
+      match: z.string().optional(),
+      expected: z.unknown().optional(),
+      name: z.string().optional(),
+      tc_id: z.string().optional(),
+    }),
+    approval: args => args.action === "observe" || args.action === "stop" ? "read" : "write",
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const fail = (message: string, code = "invalid_request") => ({
+        content: [{ type: "text" as const, text: message }],
+        details: { code },
+        isError: true,
+      });
+      const response = (result: unknown, secrets: Record<string, string> = {}) => ({
+        content: [{ type: "text" as const, text: JSON.stringify(redactExploreValue(result, secrets), null, 2) }],
+        details: redactExploreValue(result, secrets),
+      });
+      try {
+        if (activeContract && !["regression-test-design", "regression-dsl", "generate-mainflow-cases"].includes(activeContract.step)) {
+          return fail("devflow_explore is only available while idle or during regression-test-design/DSL generation", "tool_not_allowed");
+        }
+        if (params.action === "stop") {
+          await exploreHost.stop();
+          return response({ ok: true, stopped: true });
+        }
+        if (params.action === "start") {
+          if (!params.feature || !params.environment_profile || !params.url) return fail("start requires feature, environment_profile and url");
+          assertRuntimeProjectBoundary(ctx.cwd);
+          const preflight = await runPython(ctx.cwd, "workflow-orchestrator/scripts/explore_preflight.py", [
+            "--root", ctx.cwd, "--feature", params.feature, "--environment-profile", params.environment_profile,
+          ]);
+          const checked = parseJsonResult(preflight);
+          if (!preflight.ok || checked?.ok !== true) {
+            return renderResult({ ...preflight, ok: false, exitCode: preflight.exitCode || 1 }, { code: checked?.reason ?? "environment_profile_not_approved" });
+          }
+          const secretNames = Array.isArray(checked.secret_names) ? checked.secret_names.filter((name): name is string => typeof name === "string") : [];
+          const panelSecrets = testCredentials.forEnvironment(secretNames);
+          const childSecrets: Record<string, string> = {};
+          const missing: string[] = [];
+          for (const name of secretNames) {
+            const value = panelSecrets[name] ?? process.env[name];
+            if (value === undefined || value === "") missing.push(name);
+            else childSecrets[name] = value;
+          }
+          if (missing.length) return fail(`environment secret is missing: ${missing.join(", ")}`, "environment_secret_missing");
+          await exploreHost.start(exploreHostPath(), ctx.cwd, String(checked.profile_path), childSecrets);
+          const result = await exploreHost.request("start", {
+            feature: params.feature, environment_profile: params.environment_profile, url: params.url,
+          });
+          return response(result, childSecrets);
+        }
+        if (!exploreHost.running) return fail("no active explore session", "session_missing");
+        const requestParams: Record<string, unknown> = {};
+        if (params.action === "observe") Object.assign(requestParams, { scope: params.scope, full: params.full, table_text: params.table_text });
+        else if (params.action === "act") {
+          const operation = params.operation ?? params.action_name;
+          if (!params.ref || !operation) return fail("act requires ref and operation");
+          if (!["click", "fill", "check", "uncheck", "select", "press"].includes(operation)) return fail("act operation is invalid");
+          Object.assign(requestParams, { ref: params.ref, action: operation, value: params.value, value_from_secret: params.value_from_secret });
+        } else if (params.action === "assert") {
+          if (!params.ref || !params.kind || !["text", "visible", "value", "each_text"].includes(params.kind)) return fail("assert requires ref and a supported kind");
+          Object.assign(requestParams, { ref: params.ref, kind: params.kind, match: params.match, expected: params.expected });
+        } else if (params.action === "draft") {
+          if (!params.name) return fail("draft requires name");
+          Object.assign(requestParams, { name: params.name, tc_id: params.tc_id });
+        }
+        return response(await exploreHost.request(params.action, requestParams));
+      } catch (error) {
+        return fail(error instanceof Error ? error.message : String(error), "explore_failed");
+      }
+    },
+  });
+
   pi.registerTool({
     name: "devflow_run_acceptance_tests",
     label: "Devflow Run Acceptance Tests",
     description: [
       "Validate or execute the adapters bound to the frozen TC acceptance suite: command, portable HTTP, and devflow_playwright (the Core-owned Playwright Runtime driven by a pinned DSL).",
       "Actions: validate (bindings and suite), validate_human (manual TCs), run (executes every automated TC and writes the canonical acceptance-results.json; Core is the only writer), validate_results (re-checks recorded results against current approvals and hashes), gc_runs (prunes .devflow/runs/<feature> execution directories per retention rules; dry-run by default, pass write=true to delete; optional retentionDays / unreferencedTtlDays).",
+      "Failure analysis reads only the Core-produced result.json summary; trace files and screenshots are not readable by Agent tools and are for the user to inspect locally with Playwright in a terminal.",
       "devflow_playwright bindings require CURRENT human approvals created with devflow_approval and confirmed by the user in /devflow control: an execution_plan approval per TC (pins the DSL, TC and suite) and an environment_profile approval for the target profile; manual or downgraded TCs need a human_result / mode_override approval. You cannot confirm approvals yourself.",
       "Hard gate: a missing, superseded or expired approval, or a DSL/profile/suite/evidence hash that changed after the approval or the run, makes run and validate_results return ok=false and blocks run-acceptance-tests from completing; there is no soft override and results must never be written by hand.",
     ].join(" "),
@@ -3794,10 +4401,17 @@ export default function devflowCore(pi: ExtensionAPI) {
     approval: args => args.action === "run" || (args.action === "gc_runs" && args.write === true) ? "write" : "read",
     async execute(_id, params, _signal, _onUpdate, ctx) {
       const args = acceptanceRunnerArgs(params);
-      const process = await runPython(ctx.cwd, "workflow-orchestrator/scripts/acceptance_test_runner.py", args);
+      // Only the Core-owned acceptance execution receives panel credentials.
+      // validate/validate_results and every other subprocess stay on the
+      // inherited startup environment and never receive Map values.
+      const credentialEnv = params.action === "run"
+        ? testCredentials.forEnvironment(declaredSecretEnvironmentNames(ctx.cwd))
+        : {};
+      const process = await runPython(ctx.cwd, "workflow-orchestrator/scripts/acceptance_test_runner.py", args, credentialEnv);
+      const safeProcess = redactCredentialOutput(process, credentialEnv);
       const payload = parseJsonResult(process);
       const failed = payload && typeof payload === "object" && (payload as { ok?: unknown }).ok === false;
-      return renderResult(failed ? { ...process, ok: false, exitCode: process.exitCode || 1 } : process, {
+      return renderResult(failed ? { ...safeProcess, ok: false, exitCode: safeProcess.exitCode || 1 } : safeProcess, {
         action: params.action,
         feature: params.feature,
       });
@@ -4163,51 +4777,25 @@ export default function devflowCore(pi: ExtensionAPI) {
         };
       }
       if (!input.feature || !input.step) return renderResult({ ok: false, exitCode: 2, stdout: "", stderr: "feature and step are required; Core derives all control fields." });
-      const inspected = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/execution_contract.rb", ["inspect", "--feature", input.feature, "--step", input.step, "--json"]);
-      const payload = parseJsonResult(inspected);
-      const raw = payload?.contract;
-      if (!controlPlaneSucceeded(inspected) || !raw || typeof raw !== "object") return renderResult(inspected, { action: input.action });
-      const contract = contractFromRecord(raw as Record<string, unknown>);
-      if (!contract) return renderResult({ ok: false, exitCode: 1, stdout: "", stderr: "Core returned an invalid execution contract." });
-      if (input.action === "inspect") return { content: [{ type: "text" as const, text: JSON.stringify(contract, null, 2) }], details: { contract } };
+      if (input.action === "inspect") {
+        const inspected = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/execution_contract.rb", ["inspect", "--feature", input.feature, "--step", input.step, "--json"]);
+        const payload = parseJsonResult(inspected);
+        const raw = payload?.contract;
+        if (!controlPlaneSucceeded(inspected) || !raw || typeof raw !== "object") return renderResult(inspected, { action: input.action });
+        const contract = contractFromRecord(raw as Record<string, unknown>);
+        if (!contract) return renderResult({ ok: false, exitCode: 1, stdout: "", stderr: "Core returned an invalid execution contract." });
+        return { content: [{ type: "text" as const, text: JSON.stringify(contract, null, 2) }], details: { contract } };
+      }
       if (!contractActivationPhaseAllowed(controlState.phase, activeWorkflowTurn)) {
         return renderResult({ ok: false, exitCode: 2, stdout: "", stderr: "Contracts may only be activated from planning/review, or for the exact current step during a runtime-triggered workflow turn." });
       }
-      const confirmed = await ctx.ui.confirm(
-        "激活 Devflow 执行合同",
-        [
-          `合同：${contract.contractId}`,
-          `Feature：${contract.feature}`,
-          `步骤：${contract.step}`,
-          `STATE revision：${contract.stateRevision ?? "未初始化"}`,
-          `图谱 revision：${contract.graphRevision ?? 0}`,
-          `可写路径：${contract.allowedPaths.join(", ")}`,
-          `允许 Agent：${contract.allowedAgents.join(", ")}`,
-          `固定检查器：${contract.checkerIds.join(", ") || "无"}`,
-          `冻结哈希：${contract.frozenHash}`,
-          "确认后低成本模型只能在以上范围执行；未知项必须阻塞升级。",
-        ].join("\n"),
-      );
-      if (!confirmed) return renderResult({ ok: false, exitCode: 1, stdout: "", stderr: "User declined execution contract activation." });
-      try {
-        const createArgs = ["create", "--feature", input.feature, "--step", input.step, "--write", "--json"];
-        if (contract.stateRevision !== undefined) createArgs.push("--expected-state-revision", String(contract.stateRevision));
-        if (contract.graphRevision !== undefined) createArgs.push("--expected-graph-revision", String(contract.graphRevision));
-        const written = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/execution_contract.rb", createArgs);
-        if (!controlPlaneSucceeded(written)) return renderResult(written, { action: input.action });
-        const writtenPayload = parseJsonResult(written);
-        const destination = typeof writtenPayload?.path === "string" ? writtenPayload.path : ".devflow/planning/contracts/";
-        contract.contractPath = destination;
-        activeContract = contract;
-        contractAgentCalls = 0;
-        setControlState(ctx, executingState(`合同执行：${contract.contractId}`));
-        return {
-          content: [{ type: "text" as const, text: `Execution contract activated: ${destination}` }],
-          details: { contract, destination },
-        };
-      } catch (error) {
-        return renderResult({ ok: false, exitCode: 1, stdout: "", stderr: error instanceof Error ? error.message : String(error) });
-      }
+      const activated = await activateExecutionContract(ctx, input.feature, input.step);
+      if (!activated.ok) return renderResult({ ok: false, exitCode: 1, stdout: "", stderr: activated.reason });
+      const destination = activated.contract.contractPath ?? ".devflow/planning/contracts/";
+      return {
+        content: [{ type: "text" as const, text: `Execution contract activated: ${destination}` }],
+        details: { contract: activated.contract, destination },
+      };
     },
   });
 
@@ -4255,7 +4843,7 @@ export default function devflowCore(pi: ExtensionAPI) {
     parameters: z.object({
       feature: z.string().min(1),
       phase: z.string().min(1).optional(),
-      flow: z.enum(["feature-development", "acceptance-remediation"]).default("feature-development"),
+      flow: z.enum(["feature-development", "acceptance-remediation", "regression-acceptance"]).default("feature-development"),
       force: z.boolean().default(false),
     }),
     approval: "write",
@@ -4792,7 +5380,7 @@ export default function devflowCore(pi: ExtensionAPI) {
           ctx.ui.notify("Devflow 已恢复待完成的受控会话交接；当前回合结束后将继续切换。", "info");
           return;
         }
-        await resumeInspectedWorkflow(ctx, inspected.snapshot);
+        await resumeInspectedWorkflow(ctx, inspected.snapshot, { doctorAlreadyPassed: true });
         return;
       }
       if (trimmed.startsWith("start ")) {