@guanlin4924/devflow-pi 0.1.39 → 0.1.47

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

@@ -4,6 +4,10 @@ import { appendFile, mkdir, rename, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
+import {
+  TASK_SUBAGENT_LIFECYCLE_CHANNEL,
+  type SubagentLifecyclePayload,
+} from "@oh-my-pi/pi-coding-agent/task";
 
 
 export type DevflowIntent = "idle" | "explain-state" | "project-init" | "requirement-draft" | "workflow-execute";
@@ -274,14 +278,37 @@ export function isRequirementDraftToolAllowed(toolName: string, input: unknown,
   return normalized === "task" && taskAgents.length > 0 && taskAgents.every(agent => PLANNING_AGENTS.has(agent));
 }
 
-/** `xd://devflow_contract` is an in-memory OMP control resource, not a
- * project file. The planner must be able to read and activate it while the
- * filesystem remains read-only; otherwise initialization deadlocks before it
- * can create a bounded execution contract. */
-export function isInternalDevflowContractResource(toolName: string, input: unknown): boolean {
-  if (!["read", "write"].includes(toolName.toLowerCase()) || !input || typeof input !== "object") return false;
+type InternalDevflowControlResource = "contract" | "state" | "mainflow";
+
+/** Resolve an xdev target only when all supplied target aliases agree.
+ * A direct/eval caller can otherwise provide `path` for a real file plus an
+ * unrelated `uri` alias and trick a permissive `some(...)` check. */
+function unambiguousVirtualResourceTarget(input: unknown): string | undefined {
+  if (!input || typeof input !== "object") return undefined;
   const record = input as Record<string, unknown>;
-  return [record.path, record.uri, record.resource].some(value => value === "xd://devflow_contract");
+  const targets = [record.path, record.uri, record.resource]
+    .filter((value): value is string => typeof value === "string" && value.length > 0);
+  if (targets.length === 0 || targets.some(value => value !== targets[0])) return undefined;
+  return targets[0];
+}
+
+/** `xd://devflow_contract` and `xd://devflow_state` are OMP transports for
+ * the existing named Core tools, not project-file writes. Once the outer
+ * transport is admitted, OMP resolves the canonical tool, validates its
+ * schema, applies its approval tier, and emits the native tool_call before
+ * executing the single-sourced handler. */
+export function internalDevflowControlResource(toolName: string, input: unknown): InternalDevflowControlResource | undefined {
+  if (!["read", "write"].includes(toolName.toLowerCase()) || !input || typeof input !== "object") return undefined;
+  const target = unambiguousVirtualResourceTarget(input);
+  if (target === "xd://devflow_contract") return "contract";
+  if (target === "xd://devflow_state") return "state";
+  if (target === "xd://devflow_mainflow") return "mainflow";
+  return undefined;
+}
+
+/** Backward-compatible predicate for callers that only care about contracts. */
+export function isInternalDevflowContractResource(toolName: string, input: unknown): boolean {
+  return internalDevflowControlResource(toolName, input) === "contract";
 }
 
 export type NaturalControlAction = "approve" | "reject";
@@ -297,6 +324,13 @@ export function isStateMutationTool(toolName: string): boolean {
   return STATE_MUTATION_TOOLS.has(toolName.toLowerCase());
 }
 
+/** Generic xdev writes must not bypass the named Devflow transition guard. */
+export function isVirtualStateTransitionResource(toolName: string, input: unknown): boolean {
+  if (toolName.toLowerCase() !== "write" || !input || typeof input !== "object") return false;
+  const record = input as Record<string, unknown>;
+  return [record.path, record.uri, record.resource].some(value => value === "xd://devflow_transition");
+}
+
 export function planningToolBlockReason(toolName: string): string {
   return `Devflow ${toolName} blocked: current intent is planning. Planning is read-only; present an Evidence Pack or plan and wait for explicit approval before writing or executing.`;
 }
@@ -448,6 +482,7 @@ const REQUIRED_SCRIPTS = [
   "workflow-orchestrator/scripts/tdd_evidence.py",
   "workflow-orchestrator/scripts/acceptance_test_runner.py",
   "workflow-orchestrator/scripts/machine_evidence.rb",
+  "workflow-orchestrator/scripts/cross_track_consistency_check.rb",
   "workflow-orchestrator/scripts/execution_contract.rb",
   "workflow-code-index/scripts/code_index.py",
   "workflow-context-sync/scripts/context_sync_cursor.py",
@@ -575,6 +610,11 @@ function isCoreOwnedGovernancePath(filePath: string): boolean {
     || /^\.planning\/contracts\/[^/\\\x00-\x1F\x7F]+\/(?:EC-[A-Fa-f0-9]+\.json|control-events\.jsonl)$/u.test(filePath);
 }
 
+function planningFeatureFromPath(filePath: string): string | null {
+  const match = filePath.match(/^\.planning\/(?:requirements|features)\/([^/\\\x00-\x1F\x7F]+)(?:\/|$)/u);
+  return match?.[1] ?? null;
+}
+
 function resolveIntelSkillRoot(cwd: string): string | undefined {
   if (isEmbeddedRuntime()) {
     const packaged = path.join(resolvePluginRoot(), "devflow-intel", "skills");
@@ -744,6 +784,67 @@ function compactStep(value: unknown): Record<string, unknown> | null {
   };
 }
 
+/**
+ * The approval prompt is session-local, while the completed step outputs are
+ * durable. After a rollover, compaction, or runtime restart the in-memory
+ * control state can be idle even though the user is still looking at a
+ * completed step. This predicate lets the runtime re-arm approval handling
+ * from the Core-owned snapshot without granting approval by itself.
+ */
+function isReviewableWorkflowSnapshot(snapshot: Record<string, unknown>): boolean {
+  const status = snapshot.status;
+  if (status !== "waiting_checkpoint" && status !== "not_started" && status !== "in_progress") return false;
+  const step = snapshot.current_step;
+  if (!step || typeof step !== "object") return false;
+  const stepRecord = step as Record<string, unknown>;
+  if (typeof stepRecord.id !== "string" || !stepRecord.id) return false;
+  const outputs = Array.isArray(stepRecord.outputs) ? stepRecord.outputs : [];
+  const requiredOutputs = outputs.filter(output => {
+    if (!output || typeof output !== "object") return false;
+    return (output as Record<string, unknown>).required !== false;
+  });
+  return requiredOutputs.length > 0 && requiredOutputs.every(output => {
+    if (!output || typeof output !== "object") return false;
+    const record = output as Record<string, unknown>;
+    return record.exists === true && !["failed", "blocked"].includes(String(record.artifact_status ?? ""));
+  });
+}
+
+export type WorkflowResumeDisposition = "execute" | "review" | "blocked" | "complete" | "idle";
+
+/** Decide how an explicit workflow resume should re-enter the Runtime.
+ *
+ * Core STATE is authoritative, but output presence determines whether the
+ * current step is ready for review or still needs an agent turn. In
+ * particular, `run_next_step` does not mean that an existing current step is
+ * complete: after a process restart its required output may still be absent.
+ */
+export function workflowResumeDisposition(snapshot: Record<string, unknown>): WorkflowResumeDisposition {
+  const action = typeof snapshot.action === "string" ? snapshot.action : "";
+  const status = typeof snapshot.status === "string" ? snapshot.status : "";
+  if (["workflow_complete", "workflow_cancelled", "workflow_failed"].includes(action) || ["completed", "cancelled", "failed"].includes(status)) {
+    return "complete";
+  }
+  if (action === "blocked") return "blocked";
+
+  const feature = typeof snapshot.current_feature === "string" ? snapshot.current_feature : "";
+  const revision = snapshot.revision;
+  const selectedStep = compactStep(snapshot.next_step) ?? compactStep(snapshot.current_step);
+  const stepId = typeof selectedStep?.id === "string" ? selectedStep.id : "";
+  if (!feature || !stepId || typeof revision !== "number" || !Number.isInteger(revision)) return "idle";
+
+  if (action === "await_user_confirmation") {
+    return isReviewableWorkflowSnapshot(snapshot) ? "review" : "blocked";
+  }
+  // Parallel windows must be reconstructed by the Runtime even if a stale
+  // join artifact happens to exist; branch lifecycle is the join authority.
+  if (action === "run_parallel_window" || action === "route_failure_branch") return "execute";
+  if (action === "run_next_step") {
+    return isReviewableWorkflowSnapshot(snapshot) ? "review" : "execute";
+  }
+  return "blocked";
+}
+
 function workflowDirective(snapshot: Record<string, unknown>, source: "start" | "approval", requirementDraft?: string): string {
   const selectedStep = compactStep(snapshot.next_step) ?? compactStep(snapshot.current_step);
   const envelope = {
@@ -760,12 +861,24 @@ function workflowDirective(snapshot: Record<string, unknown>, source: "start" |
     recovery: snapshot.recovery,
     requirement_draft: requirementDraft,
   };
+  const parallelInstructions = snapshot.action === "run_parallel_window"
+    ? [
+      "这是并行窗口：先按 parallel_run 中的 branch 记录逐个调用 task；一个 task 只能负责一个 workflow_step，不得把多个 step 合并到一个子 Agent。",
+      "本窗口的 branch step（backend-tech-spec、api-call-guide、ui-spec、feature-breakdown、frontend-tech-spec、api-supplement）统一使用白名单 agent implementation-worker；不要把 workflow step 名称当作 agent 名称。",
+      "只有执行验证类步骤才使用 verification-runner；project-scout、requirements-auditor、contract-auditor、devflow-code-reviewer 不属于本并行窗口的默认执行 agent。",
+      "每个 task 的提示必须原样包含 DEVFLOW_BRANCH_ID、DEVFLOW_WORKFLOW_STEP、DEVFLOW_TRACK、DEVFLOW_ATTEMPT 和 DEVFLOW_BRANCH_REVISION，并只写该分支的白名单产物。",
+      "子 Agent 完成后只返回产物和验证证据；不得调用 devflow_transition，不得自行声明 checkpoint 或 join。主 Agent 负责根据生命周期结果继续调度，Core 负责最终门禁。",
+      "如果生命周期 status=aborted，按 failed 处理：先调用 Core 的 branch fail，再根据恢复信息调用 retry；不得把 aborted 当作成功或忽略，否则 join 会永久等待。",
+    ]
+    : [];
   return [
     "<devflow-runtime-directive>",
     "Devflow 已通过启动预检。读取 skill://workflow-pipeline，并只执行当前项目的一个工作流步骤。",
-    "先调用 devflow_state(action=\"inspect\") 重新确认 revision，再由 workflow-orchestrator 路由当前步骤。",
-    "只按 inspector 返回的当前 step 加载所需 Skill；不得调用 devflow_transition、不得推进下一步骤、不得替用户通过人工 checkpoint。",
-    "完成本步骤的真实产物后，报告证据、未决项和验证结果并停止。请用户审查后明确回复“批准执行”才可推进；回复修改意见或“拒绝执行”则不得推进。",
+    "先调用 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 在用户确认后独占处理。",
+    ...(parallelInstructions.length > 0 ? parallelInstructions : [
+      "完成本步骤的真实产物后，报告证据、未决项和验证结果并停止。请用户审查后明确回复“批准执行”才可推进；回复修改意见或“拒绝执行”则不得推进。",
+    ]),
     "当前步骤信封：",
     JSON.stringify(envelope, null, 2),
     "</devflow-runtime-directive>",
@@ -820,6 +933,27 @@ function inputPaths(input: unknown, cwd: string): string[] {
     .filter((value): value is string => value !== null);
 }
 
+function parallelBranchContext(input: unknown): { branch_id: string; attempt: number; branch_revision: number } | null {
+  const text = typeof input === "string" ? input : JSON.stringify(input ?? {});
+  const branch = text.match(/DEVFLOW_BRANCH_ID\s*[:=]\s*([^\s,}"']+)/)?.[1];
+  const attempt = text.match(/DEVFLOW_ATTEMPT\s*[:=]\s*(\d+)/)?.[1];
+  const revision = text.match(/DEVFLOW_BRANCH_REVISION\s*[:=]\s*(\d+)/)?.[1];
+  if (!branch || attempt === undefined || revision === undefined) return null;
+  return { branch_id: branch, attempt: Number(attempt), branch_revision: Number(revision) };
+}
+
+export function taskResultHasSuccessfulDispatch(details: unknown): boolean {
+  if (!details || typeof details !== "object") return false;
+  const record = details as Record<string, unknown>;
+  if (Array.isArray(record.results) && record.results.length > 0) return true;
+  if (!Array.isArray(record.progress)) return false;
+  return record.progress.some(item => {
+    if (!item || typeof item !== "object") return false;
+    const status = String((item as Record<string, unknown>).status ?? "");
+    return status !== "failed" && status !== "aborted";
+  });
+}
+
 function isControlPath(filePath: string): boolean {
   return CONTROL_PATHS.includes(filePath) || CONTROL_PREFIXES.some(prefix => filePath.startsWith(prefix));
 }
@@ -829,7 +963,7 @@ function isDirectControlMutation(toolName: string, input: unknown, cwd: string):
   return inputPaths(input, cwd).some(isControlPath);
 }
 
-function isShellControlMutation(toolName: string, input: unknown): boolean {
+export function isShellControlMutation(toolName: string, input: unknown): boolean {
   if (!["bash", "shell", "exec_command"].includes(toolName) || !input || typeof input !== "object") {
     return false;
   }
@@ -840,7 +974,7 @@ function isShellControlMutation(toolName: string, input: unknown): boolean {
       command,
     );
   const namesControlPath = [...CONTROL_PATHS, ...CONTROL_PREFIXES].some(item => command.includes(item)) || /\.planning\/requirements\//.test(command);
-  const looksLikeWrite = /(?:^|[;&|]\s*)(?:rm|mv|cp|install|truncate)\b|(?:^|\s)(?:tee|sed\s+-i|perl\s+-i)\b|>{1,2}/.test(
+  const looksLikeWrite = /(?:^|[;&|]\s*)(?:rm|mv|cp|install|truncate)\b|(?:^|\s)(?:tee|sed\s+-i|perl\s+-i)\b|(?:^|[\s;&|])(?:\d*)>{1,2}(?![>=])\s*\S/.test(
     command,
   );
   return invokesWriter || (namesControlPath && looksLikeWrite);
@@ -858,8 +992,108 @@ function shellMutationPaths(command: string, cwd: string): { mutating: boolean;
   return { mutating: true, paths };
 }
 
+type StepContractAuthority = Pick<ActiveExecutionContract, "feature" | "step">;
+
+const CONTRACT_CONTROL_TOOLS = new Set([
+  "devflow_artifact",
+  "devflow_bootstrap",
+  "devflow_contract",
+  "devflow_recovery",
+  "devflow_transition",
+]);
+
+const CONTRACT_READ_TOOLS = new Set([
+  "devflow_acceptance_tests",
+  "devflow_doctor",
+  "devflow_state",
+  "devflow_usage_stats",
+  "usage_stats",
+]);
+
+function inputAction(input: unknown): string {
+  return input && typeof input === "object" ? String((input as Record<string, unknown>).action ?? "") : "";
+}
+
+function stepScopedMutationOwner(toolName: string, input: unknown): string | null | undefined {
+  const normalized = toolName.toLowerCase();
+  // `write xd://devflow_*` is only the OMP transport. The nested canonical
+  // tool_call is authorized below under its real `devflow_*` name.
+  if (internalDevflowControlResource(normalized, input)) return undefined;
+  if (["write", "edit", "apply_patch", "notebook_edit", "task", "bash", "shell", "exec_command"].includes(normalized)) return null;
+  if (!normalized.startsWith("devflow_") || CONTRACT_CONTROL_TOOLS.has(normalized) || CONTRACT_READ_TOOLS.has(normalized)) return undefined;
+  const action = inputAction(input);
+  if (normalized === "devflow_code_index") return action === "scan" ? "code-index-refresh" : undefined;
+  if (normalized === "devflow_requirement_graph") {
+    const writeContext = input && typeof input === "object" && (input as Record<string, unknown>).write === true;
+    return ["propose", "confirm"].includes(action) || (action === "context" && writeContext) ? null : undefined;
+  }
+  if (normalized === "devflow_api_test_matrix") return action === "validate" ? undefined : "acceptance-test-design";
+  if (normalized === "devflow_tdd_evidence") return action === "inspect" ? undefined : "execute";
+  if (normalized === "devflow_run_acceptance_tests") return action === "run" ? "run-acceptance-tests" : undefined;
+  if (normalized === "devflow_mainflow") return "generate-mainflow-cases";
+  if (normalized === "devflow_wireframe" || normalized === "devflow_design_rule") return "ui-spec";
+  if (normalized.startsWith("devflow_architecture_") || normalized === "devflow_workload_constraint") {
+    return action === "inspect" ? undefined : "architecture-feasibility";
+  }
+  if (normalized === "devflow_runtime_context" || normalized === "devflow_static_runtime_context") {
+    return action === "inspect" ? undefined : null;
+  }
+  if (normalized === "devflow_evidence") return ["read", "validate"].includes(action) ? undefined : null;
+  if (normalized === "devflow_machine_evidence") {
+    const step = input && typeof input === "object" ? (input as Record<string, unknown>).step : undefined;
+    return typeof step === "string" && step ? step : null;
+  }
+  // New mutating Devflow tools must declare a step above or be explicitly
+  // classified read/control-only; they never inherit a broad devflow_* bypass.
+  return null;
+}
+
+function snapshotStepId(snapshot: Record<string, unknown>): string | undefined {
+  const step = snapshot.current_step;
+  if (typeof step === "string" && step) return step;
+  if (step && typeof step === "object" && typeof (step as Record<string, unknown>).id === "string") {
+    return String((step as Record<string, unknown>).id);
+  }
+  return undefined;
+}
+
+export function contractActivationPhaseAllowed(phase: ControlPhase, activeWorkflowTurn: boolean): boolean {
+  return ["planning", "waiting-user", "awaiting-approval"].includes(phase) || (phase === "executing" && activeWorkflowTurn);
+}
+
+export function stepScopedMutationBlockReason(
+  toolName: string,
+  input: unknown,
+  _cwd: string,
+  snapshot: Record<string, unknown>,
+  contract: StepContractAuthority | undefined,
+  contractFresh: boolean,
+): string | undefined {
+  const owner = stepScopedMutationOwner(toolName, input);
+  if (owner === undefined) return undefined;
+  const feature = typeof snapshot.current_feature === "string" ? snapshot.current_feature : undefined;
+  const step = snapshotStepId(snapshot);
+  if (!feature || !step) return "Active Devflow workflow mutation blocked: authoritative feature/current_step is unavailable.";
+  if (snapshot.status === "waiting_checkpoint") {
+    return `Active Devflow workflow is waiting at a checkpoint after ${step}; approve or reject it before any further mutation.`;
+  }
+  if (!contract) return `Workflow step ${feature}/${step} requires an active execution contract before ${toolName}.`;
+  if (contract.feature !== feature || contract.step !== step) {
+    return `Active contract ${contract.feature}/${contract.step} does not match authoritative workflow step ${feature}/${step}.`;
+  }
+  if (!contractFresh) return `Active contract for ${feature}/${step} is stale against authoritative STATE or requirement graph.`;
+  if (owner && owner !== step) return `${toolName} belongs to workflow step ${owner}, but authoritative current_step is ${step}.`;
+  return undefined;
+}
+
 export default function devflowCore(pi: ExtensionAPI) {
   const { z } = pi.zod;
+  // CLI --resume means "continue this chat session" at the OMP layer. The
+  // launcher also supplies this one-shot, process-owned signal so Devflow can
+  // safely resume an authoritative incomplete workflow step. It is consumed
+  // 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 controlState: SessionControlState = initialControlState();
   let activeContract: ActiveExecutionContract | undefined;
@@ -872,7 +1106,10 @@ export default function devflowCore(pi: ExtensionAPI) {
     const step = activeContract.step;
     if (!/^[\p{L}\p{N}._-]{1,160}$/u.test(feature) || !/^[\p{L}\p{N}._-]{1,160}$/u.test(step)) return;
     const directory = path.join(cwd, ".planning", "evidence", feature);
-    const destination = path.join(directory, `${step}.engine-events.jsonl`);
+    const attempt = typeof extra.attempt === "number" && Number.isInteger(extra.attempt) && extra.attempt >= 0
+      ? extra.attempt
+      : undefined;
+    const destination = path.join(directory, `${step}${attempt === undefined ? "" : `.attempt-${attempt}`}.engine-events.jsonl`);
     await mkdir(directory, { recursive: true });
     await appendFile(destination, `${JSON.stringify({
       schema_version: 1,
@@ -881,6 +1118,7 @@ export default function devflowCore(pi: ExtensionAPI) {
       feature,
       step,
       event,
+      ...(attempt === undefined ? {} : { attempt, branch_id: extra.branch_id }),
       collector: "devflow-runtime/harness",
       ...extra,
     })}\n`, "utf8");
@@ -1323,8 +1561,19 @@ export default function devflowCore(pi: ExtensionAPI) {
   }
 
   let activeWorkflowTurn = false;
+  let parallelRunActive = false;
+  let parallelContinuationQueued = false;
+  let parallelDispatchSucceededThisTurn = false;
+  let parallelDispatchFailureThisTurn = "";
+  const pendingParallelLifecycle = new Map<string, string>();
+  const pendingParallelLifecycleContexts = new Map<string, { branch_id: string; attempt: number; branch_revision: number }>();
+  const parallelTaskContexts = new Map<string, { branch_id: string; attempt: number; branch_revision: number }>();
   let pendingProjectInitialization: ProjectInitializationRequest | undefined;
   let pendingRollover: { snapshot: Record<string, unknown>; preparedRevision: number; rolloverId: string } | undefined;
+  // A planner may request bootstrap, but only the runtime may authorize the
+  // state mutation. Keep the authorization in memory and bind it to exactly
+  // one tool call; never persist or expose it as a model-controlled flag.
+  const runtimeBootstrapAuthorizations = new Set<string>();
 
   async function enqueueControlledRolloverRequest(cwd: string, rolloverId: string, sourceSessionId: string) {
     const requestPath = path.join(cwd, ".planning", "rollover-request.json");
@@ -1347,15 +1596,258 @@ export default function devflowCore(pi: ExtensionAPI) {
     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");
+    }
     await enqueueControlledRolloverRequest(ctx.cwd, rolloverId, ctx.sessionManager.getSessionId());
     pendingRollover = { snapshot, preparedRevision: payload.revision, rolloverId };
   }
 
+  function parallelBranches(snapshot: Record<string, unknown>): Array<{ workflow_step: string; track: string }> {
+    const window = snapshot.parallel_window;
+    if (!window || typeof window !== "object") return [];
+    const branches = (window as Record<string, unknown>).branches;
+    if (!branches || typeof branches !== "object") return [];
+    return Object.entries(branches as Record<string, unknown>).flatMap(([track, steps]) => {
+      if (!Array.isArray(steps)) return [];
+      return steps.flatMap(step => {
+        const workflowStep = typeof step === "string"
+          ? step
+          : step && typeof step === "object" ? String((step as Record<string, unknown>).id ?? "") : "";
+        return workflowStep ? [{ workflow_step: workflowStep, track }] : [];
+      });
+    });
+  }
+
+  async function prepareParallelRun(cwd: string, snapshot: Record<string, unknown>): Promise<Record<string, unknown>> {
+    if (snapshot.action !== "run_parallel_window") return snapshot;
+    const feature = String(snapshot.current_feature ?? "");
+    const window = snapshot.parallel_window as Record<string, unknown> | undefined;
+    const workflowWindow = String(window?.id ?? "");
+    const existing = parseJsonResult(await runRuby(cwd, "workflow-orchestrator/scripts/parallel_run.rb", [
+      "--action", "inspect", "--feature", feature, "--json",
+    ]));
+    if (existing?.ok === true && existing.run) {
+      parallelRunActive = true;
+      return { ...snapshot, parallel_run: existing.run };
+    }
+    const revision = typeof snapshot.revision === "number" ? snapshot.revision : undefined;
+    if (!feature || !workflowWindow || revision === undefined) throw new Error("parallel window snapshot is incomplete");
+    const branches = parallelBranches(snapshot);
+    if (branches.length === 0) throw new Error("parallel window contains no branch steps");
+    const prepared = await runRuby(cwd, "workflow-orchestrator/scripts/parallel_run.rb", [
+      "--action", "prepare", "--feature", feature, "--workflow-window", workflowWindow,
+      "--state-revision", String(revision), "--json",
+      ...branches.flatMap(branch => ["--branch", `${branch.workflow_step}:${branch.track}`]),
+    ]);
+    const payload = parseJsonResult(prepared);
+    if (!controlPlaneSucceeded(prepared) || !payload?.run) {
+      throw new Error(prepared.stderr || prepared.stdout || "parallel run prepare failed");
+    }
+    parallelRunActive = true;
+    return { ...snapshot, parallel_run: payload.run };
+  }
+
   async function triggerWorkflow(snapshot: Record<string, unknown>, source: "start" | "approval", requirementDraft?: string) {
+    if (snapshot.action !== "run_parallel_window") {
+      parallelRunActive = false;
+      parallelContinuationQueued = false;
+    }
+    if (snapshot.action === "run_parallel_window") {
+      parallelDispatchSucceededThisTurn = false;
+      parallelDispatchFailureThisTurn = "";
+    }
+    const preparedSnapshot = await prepareParallelRun(projectRoot ?? process.cwd(), snapshot);
     activeWorkflowTurn = true;
-    await pi.sendUserMessage(workflowDirective(snapshot, source, requirementDraft));
+    await pi.sendUserMessage(workflowDirective(preparedSnapshot, source, requirementDraft));
+  }
+
+  async function resumeInspectedWorkflow(
+    ctx: {
+      cwd: string;
+      ui: {
+        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>,
+  ): Promise<WorkflowResumeDisposition> {
+    const disposition = workflowResumeDisposition(snapshot);
+    const stepId = String((compactStep(snapshot.next_step) ?? compactStep(snapshot.current_step))?.id ?? "当前步骤");
+    if (disposition === "execute") {
+      setControlState(ctx, executingState(`恢复并执行 ${stepId}`));
+      ctx.ui.notify(`Devflow 已恢复到 ${stepId}，当前步骤产物尚未完成，正在继续执行。`, "info");
+      await triggerWorkflow(snapshot, "start");
+      return disposition;
+    }
+    if (disposition === "review") {
+      setControlState(ctx, waitingUserState("等待用户审查步骤产物"));
+      ctx.ui.notify(`Devflow 已恢复到 ${stepId}；请审查当前产物后明确回复“批准执行”，或直接提出修改意见。`, "info");
+      return disposition;
+    }
+    if (disposition === "blocked") {
+      setControlState(ctx, { intent: "workflow-execute", phase: "blocked", label: "恢复校验阻塞" });
+      ctx.ui.notify(`Devflow 无法安全恢复 ${stepId}：${String(snapshot.reason ?? "当前状态既不可执行也不可审查")}。`, "error");
+      return disposition;
+    }
+    setControlState(ctx, initialControlState());
+    ctx.ui.notify(
+      disposition === "complete" ? "Devflow workflow is already complete." : "当前没有可恢复的 Devflow 工作流步骤。",
+      "info",
+    );
+    return disposition;
   }
 
+  async function confirmAndAdvanceWorkflowStep(ctx: {
+    cwd: string;
+    sessionManager: { getSessionId(): string };
+    ui: { confirm(title: string, body: string): Promise<boolean>; notify(message: string, level: "info" | "error"): void; setStatus(key: string, text: string | undefined): void };
+  }): Promise<boolean> {
+    const inspected = await inspectWorkflowWithRegistryRecovery(ctx.cwd);
+    if (!inspected.result.ok || !inspected.snapshot || !isReviewableWorkflowSnapshot(inspected.snapshot)) return false;
+    const step = compactStep(inspected.snapshot.current_step);
+    const stepId = typeof step?.id === "string" ? step.id : undefined;
+    const revision = typeof inspected.snapshot.revision === "number" ? inspected.snapshot.revision : undefined;
+    if (!stepId || revision === undefined) return false;
+    const checkpoint = inspected.snapshot.status === "waiting_checkpoint";
+    let cp3Prerequisites: Array<{ id?: unknown; kind?: unknown; summary?: unknown }> = [];
+    if (checkpoint && inspected.snapshot.checkpoint === "CP-3") {
+      const feature = typeof inspected.snapshot.current_feature === "string" ? inspected.snapshot.current_feature : undefined;
+      if (!feature) return false;
+      const suite = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/acceptance_test_suite.rb", [
+        "inspect", "--feature", feature, "--json",
+      ]);
+      const suitePayload = parseJsonResult(suite);
+      if (!suite.ok || !suitePayload || suitePayload.ok !== true) {
+        setControlState(ctx, { intent: "workflow-execute", phase: "blocked", label: "CP-3 前置检查失败" });
+        ctx.ui.notify(`无法读取 CP-3 测试前置事实：${suite.stderr || suite.stdout}`, "error");
+        return true;
+      }
+      cp3Prerequisites = Array.isArray(suitePayload.unconfirmed_prerequisites)
+        ? suitePayload.unconfirmed_prerequisites as Array<{ id?: unknown; kind?: unknown; summary?: unknown }>
+        : [];
+    }
+    const prerequisiteReview = cp3Prerequisites.length > 0
+      ? [
+          "",
+          `CP-3 检测到 ${cp3Prerequisites.length} 个尚未确认、但被候选验收测试引用的前置事实。批准后 Core 会在同一原子事务中确认它们并冻结测试集：`,
+          ...cp3Prerequisites.map(item => `- ${String(item.id ?? "?")} [${String(item.kind ?? "?")}]${item.summary ? `：${String(item.summary)}` : ""}`),
+        ].join("\n")
+      : "";
+    const approved = await ctx.ui.confirm(
+      "确认推进 Devflow 工作流",
+      `当前步骤：${stepId}\n\n步骤产物已生成并通过基础校验。确认${checkpoint ? "当前 checkpoint 并" : ""}推进到下一步骤吗？${prerequisiteReview}`,
+    );
+    if (!approved) {
+      setControlState(ctx, waitingUserState("等待用户审查步骤产物并明确决定"));
+      ctx.ui.notify("已保留当前步骤，未推进工作流。", "info");
+      return true;
+    }
+    const result = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/advance_state.rb", [
+      "--write", "--json", "--expected-revision", String(revision),
+      ...(checkpoint ? ["--confirm-checkpoint", "--runtime-confirmed"] : ["--complete-step", stepId]),
+      ...(cp3Prerequisites.length > 0 ? ["--confirm-test-prerequisites"] : []),
+    ]);
+    if (!result.ok || !controlPlaneSucceeded(result)) {
+      setControlState(ctx, { intent: "workflow-execute", phase: "blocked", label: "推进校验失败" });
+      ctx.ui.notify(`未推进：${result.stderr || result.stdout}`, "error");
+      return true;
+    }
+    const after = await inspectWorkflowWithRegistryRecovery(ctx.cwd);
+    activeContract = undefined;
+    contractAgentCalls = 0;
+    if (!after.result.ok || !after.snapshot || after.snapshot.action === "workflow_complete") {
+      setControlState(ctx, initialControlState());
+      ctx.ui.notify(after.snapshot?.action === "workflow_complete" ? "工作流已完成。" : "已推进，但读取下一步骤失败。", "info");
+      return true;
+    }
+    setControlState(ctx, waitingUserState("正在准备干净会话以执行下一工作流步骤"));
+    try {
+      await requestControlledRollover(ctx, after.snapshot);
+      ctx.ui.notify("当前节点的证据已固定；当前回合结束后将自动切换到下一节点。", "info");
+    } catch (error) {
+      setControlState(ctx, { intent: "workflow-execute", phase: "blocked", label: "会话轮换准备失败" });
+      ctx.ui.notify(`未开始下一节点：会话轮换准备失败：${String(error)}`, "error");
+    }
+    return true;
+  }
+
+  async function reconcileParallelLifecycle(event: Partial<SubagentLifecyclePayload>, context: { branch_id: string; attempt: number; branch_revision: number } | undefined): Promise<void> {
+    if (!context || !projectRoot || !event.status || event.status === "started") return;
+    const workflowInspection = await inspectWorkflow(projectRoot);
+    const snapshot = workflowInspection.snapshot;
+    const feature = String(snapshot?.current_feature ?? "");
+    if (!feature) return;
+    const inspected = parseJsonResult(await runRuby(projectRoot, "workflow-orchestrator/scripts/parallel_run.rb", ["--action", "inspect", "--feature", feature, "--json"]));
+    const run = inspected?.run as Record<string, unknown> | undefined;
+    if (!run) return;
+    const stateRevision = Number(snapshot?.revision);
+    if (!Number.isInteger(stateRevision)) return;
+    const action = event.status === "completed" ? "complete" : "fail";
+    const args = ["--write", "--json", "--parallel-action", action, "--parallel-branch-id", context.branch_id, "--expected-revision", String(stateRevision)];
+    if (action === "complete") args.push("--parallel-attempt", String(context.attempt), "--parallel-branch-revision", String(context.branch_revision));
+    const result = await runRuby(projectRoot, "workflow-orchestrator/scripts/advance_state.rb", args);
+    if (!result.ok || !controlPlaneSucceeded(result)) {
+      parallelDispatchFailureThisTurn = result.stderr || result.stdout || `parallel ${action} failed`;
+      return;
+    }
+    if (action !== "complete") return;
+    const refreshed = parseJsonResult(await runRuby(projectRoot, "workflow-orchestrator/scripts/parallel_run.rb", ["--action", "inspect", "--feature", feature, "--json"]));
+    const current = refreshed?.run as Record<string, unknown> | undefined;
+    const branches = Array.isArray(current?.branches) ? current.branches as Array<Record<string, unknown>> : [];
+    if (branches.length > 0 && branches.every(branch => branch.status === "succeeded")) {
+      const after = await inspectWorkflow(projectRoot);
+      const joinRevision = Number(after.snapshot?.revision);
+      if (Number.isInteger(joinRevision)) {
+        await runRuby(projectRoot, "workflow-orchestrator/scripts/advance_state.rb", [
+          "--write", "--json", "--parallel-action", "join", "--expected-revision", String(joinRevision),
+        ]);
+      }
+    }
+  }
+
+  function scheduleParallelContinuation() {
+    if (parallelContinuationQueued || pendingParallelLifecycle.size === 0) return;
+    parallelContinuationQueued = true;
+    const events = [...pendingParallelLifecycle.entries()].map(([id, status]) => {
+      const context = pendingParallelLifecycleContexts.get(id);
+      return context ? `${id}:${status}:${JSON.stringify(context)}` : `${id}:${status}`;
+    });
+    pendingParallelLifecycle.clear();
+    pendingParallelLifecycleContexts.clear();
+    pi.sendMessage({
+      customType: "devflow-parallel-lifecycle",
+      content: `并行子 Agent 生命周期事件已到达（${events.join(", ")}）。请重新 inspect 整个 parallel run，逐一处理所有已完成/失败分支，必要时调用 Core 的 branch complete/fail/retry 动作，然后继续派发仍满足前置依赖的分支；不得直接 join。`,
+      display: false,
+      details: { events },
+    }, { triggerTurn: true, deliverAs: "nextTurn" });
+  }
+
+  pi.events.on(TASK_SUBAGENT_LIFECYCLE_CHANNEL, async data => {
+    if (!parallelRunActive || !data || typeof data !== "object") return;
+    const event = data as Partial<SubagentLifecyclePayload>;
+    if (typeof event.id !== "string" || !["started", "completed", "failed", "aborted"].includes(String(event.status))) return;
+    if (event.status === "started") {
+      parallelDispatchSucceededThisTurn = true;
+      if (typeof event.parentToolCallId === "string") {
+        const context = parallelTaskContexts.get(event.parentToolCallId);
+        if (context) pendingParallelLifecycleContexts.set(event.id, context);
+      }
+      return;
+    }
+    pendingParallelLifecycle.set(event.id, String(event.status));
+    if (typeof event.parentToolCallId === "string") {
+      const context = parallelTaskContexts.get(event.parentToolCallId);
+      if (context) pendingParallelLifecycleContexts.set(event.id, context);
+    }
+    await reconcileParallelLifecycle(event, pendingParallelLifecycleContexts.get(event.id));
+    scheduleParallelContinuation();
+  });
+
   pi.setLabel("Devflow Project Runtime");
 
   pi.on("session_start", async (_event, ctx) => {
@@ -1411,8 +1903,11 @@ export default function devflowCore(pi: ExtensionAPI) {
       const consumed = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/session_rollover.rb", [
         "consume", "--write", "--json", "--expected-revision", String(rolloverState.revision), "--target-session-id", currentSessionId,
       ]);
+      const synced = consumed.ok
+        ? await runRuby(ctx.cwd, "workflow-orchestrator/scripts/sync_artifacts.rb", ["--write", "--no-preserve", "--json"])
+        : undefined;
       const after = await inspectWorkflowWithRegistryRecovery(ctx.cwd);
-      if (consumed.ok && after.result.ok && after.snapshot) {
+      if (consumed.ok && synced && controlPlaneSucceeded(synced) && after.result.ok && after.snapshot) {
         if (after.snapshot.action === "blocked") {
           setControlState(ctx, { intent: "workflow-execute", phase: "blocked", label: "启动恢复校验失败" });
           ctx.ui.notify(`会话已恢复，但工作流校验失败，未启动 AI：${String(after.snapshot.reason ?? "state validation failed")}`, "error");
@@ -1420,10 +1915,23 @@ export default function devflowCore(pi: ExtensionAPI) {
         }
         setControlState(ctx, executingState("恢复已认领的干净会话"));
         await triggerWorkflow(after.snapshot, "approval");
-      } else if (!consumed.ok) {
+      } else if (!consumed.ok || !synced || !controlPlaneSucceeded(synced)) {
         ctx.ui.notify(`已认领的会话交接无法恢复；工作流保持冻结：${consumed.stderr || consumed.stdout}`, "error");
       }
     }
+    if (cliSessionResumeRequested && controlState.phase === "idle" && !pendingRollover) {
+      const report = await runDoctor(ctx);
+      if (!report.ok) {
+        ctx.ui.notify(formatDoctorReport(report).slice(0, 10000), "error");
+        return;
+      }
+      const inspected = await inspectWorkflowWithRegistryRecovery(ctx.cwd);
+      if (!inspected.result.ok || !inspected.snapshot) {
+        ctx.ui.notify(`Devflow resume failed: ${inspected.result.stderr || inspected.result.stdout || "invalid inspector JSON"}`, "error");
+        return;
+      }
+      await resumeInspectedWorkflow(ctx, inspected.snapshot);
+    }
   });
 
   pi.on("session_before_switch", async (event) => {
@@ -1452,13 +1960,16 @@ export default function devflowCore(pi: ExtensionAPI) {
     const consumed = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/session_rollover.rb", [
       "consume", "--write", "--json", "--expected-revision", String(claimedPayload.revision), "--target-session-id", targetSessionId,
     ]);
-    if (!consumed.ok) {
+    const synced = consumed.ok
+      ? await runRuby(ctx.cwd, "workflow-orchestrator/scripts/sync_artifacts.rb", ["--write", "--no-preserve", "--json"])
+      : undefined;
+    if (!consumed.ok || !synced || !controlPlaneSucceeded(synced)) {
       if (parseJsonResult(consumed)?.reason === "rollover_transition_failed") {
         await enqueueControlledRolloverRequest(ctx.cwd, pending.rolloverId, targetSessionId);
       } else {
         pendingRollover = undefined;
       }
-      ctx.ui.notify(`Devflow 会话交接消费失败；工作流保持冻结：${consumed.stderr || consumed.stdout}`, "error");
+      ctx.ui.notify(`Devflow 会话交接消费或 registry 同步失败；工作流保持冻结：${consumed.stderr || consumed.stdout || synced?.stderr || synced?.stdout}`, "error");
       return;
     }
     pendingRollover = undefined;
@@ -1485,9 +1996,34 @@ export default function devflowCore(pi: ExtensionAPI) {
   pi.on("agent_end", async (event, ctx) => {
     if (!activeWorkflowTurn || event.willContinue) return;
     activeWorkflowTurn = false;
+    if (parallelRunActive) {
+      parallelContinuationQueued = false;
+      if (!parallelDispatchSucceededThisTurn && pendingParallelLifecycle.size === 0) {
+        parallelRunActive = false;
+        parallelTaskContexts.clear();
+        setControlState(ctx, { intent: "workflow-execute", phase: "blocked", label: "并行子 Agent 未启动" });
+        ctx.ui.notify(
+          `并行窗口未启动任何子 Agent，已停止等待不存在的生命周期事件；STATE 未推进。${parallelDispatchFailureThisTurn ? `\n原因：${parallelDispatchFailureThisTurn}` : ""}\n请检查打包 Agent 注册；若当前环境不支持并行，调度器必须按 serial_fallback_order 串行执行。`,
+          "error",
+        );
+        return;
+      }
+      setControlState(ctx, executingState("并行窗口运行中，等待子 Agent 生命周期事件"));
+      // A second detached task may finish while the continuation is running.
+      // Its event is retained and gets a follow-up continuation instead of
+      // being dropped behind the current queue marker.
+      scheduleParallelContinuation();
+      return;
+    }
     if (controlState.phase === "executing") {
       setControlState(ctx, waitingUserState("等待用户审查步骤产物并明确决定"));
-      ctx.ui.notify("当前步骤已结束。请审查输出：明确回复“批准执行”推进，或回复修改意见/“拒绝执行”保持当前步骤。", "info");
+      // UI confirmation may legitimately wait for the user longer than the
+      // host's event-handler deadline. Do not await it from agent_end or the
+      // host reports a timeout and the approval result is lost.
+      void confirmAndAdvanceWorkflowStep(ctx).catch(error => {
+        setControlState(ctx, { intent: "workflow-execute", phase: "blocked", label: "推进确认处理失败" });
+        ctx.ui.notify(`推进确认处理失败：${String(error)}`, "error");
+      });
     }
   });
 
@@ -1545,7 +2081,22 @@ export default function devflowCore(pi: ExtensionAPI) {
       }
       return { handled: true };
     }
-    if (controlState.phase === "awaiting-approval" || controlState.phase === "waiting-user") {
+    // The in-memory prompt state is intentionally not authoritative. A fresh
+    // session starts idle, so recover the approval arm from the durable Core
+    // snapshot before handing an explicit approval phrase to the model. This
+    // still requires the user's phrase and never auto-advances the workflow.
+    let recoveredApprovalState = false;
+    if (
+      controlAction &&
+      controlState.phase === "idle"
+    ) {
+      const inspected = await inspectWorkflowWithRegistryRecovery(ctx.cwd);
+      if (inspected.result.ok && inspected.snapshot && isReviewableWorkflowSnapshot(inspected.snapshot)) {
+        setControlState(ctx, waitingUserState("恢复当前步骤审批状态"));
+        recoveredApprovalState = true;
+      }
+    }
+    if (recoveredApprovalState || controlState.phase === "awaiting-approval" || controlState.phase === "waiting-user") {
       if (controlAction === "reject") {
         ctx.ui.notify("已保留当前步骤和产物。请直接说明需要修改的内容；未执行任何推进。", "info");
         return { handled: true };
@@ -1564,6 +2115,17 @@ export default function devflowCore(pi: ExtensionAPI) {
           ctx.ui.notify("当前状态缺少可确认的 revision 或步骤，拒绝推进。", "error");
           return { handled: true };
         }
+        if (checkpoint && stepId === "wireframe-review" && typeof inspected.snapshot.current_feature === "string") {
+          const approval = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/wireframe_commit.rb", [
+            "--action", "approve", "--feature", inspected.snapshot.current_feature,
+            "--expected-revision", String(revision), "--all-screens", "--runtime-confirmed", "--write", "--json",
+          ]);
+          if (!controlPlaneSucceeded(approval)) {
+            setControlState(ctx, { intent: "workflow-execute", phase: "blocked", label: "原型确认写入失败" });
+            ctx.ui.notify(`原型确认未写入：${approval.stderr || approval.stdout}`, "error");
+            return { handled: true };
+          }
+        }
         const result = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/advance_state.rb", [
           "--write",
           "--json",
@@ -1645,7 +2207,34 @@ export default function devflowCore(pi: ExtensionAPI) {
 
   pi.on("tool_call", async (event, ctx) => {
     const toolName = String(event.toolName).toLowerCase();
-    if (activeContract && controlState.phase === "executing" && !toolName.startsWith("devflow_")) {
+    const toolInput = event.input && typeof event.input === "object" ? event.input as Record<string, unknown> : undefined;
+    const toolCallId = String(event.toolCallId ?? "");
+    const internalControlResource = internalDevflowControlResource(toolName, event.input);
+    if (isVirtualStateTransitionResource(toolName, event.input)) {
+      return {
+        block: true,
+        reason: "禁止通过 write xd://devflow_transition 推进工作流；步骤产物完成后由 Runtime 弹出用户确认并执行状态迁移。",
+      };
+    }
+    let bootstrapAuthorized = toolName === "devflow_bootstrap" && runtimeBootstrapAuthorizations.has(toolCallId);
+    if (toolName === "devflow_bootstrap" && !bootstrapAuthorized) {
+      const feature = typeof toolInput?.feature === "string" ? toolInput.feature.trim() : "";
+      const phase = typeof toolInput?.phase === "string" && toolInput.phase.trim() ? toolInput.phase.trim() : "默认需求阶段";
+      if (!feature) return { block: true, reason: "bootstrap requires a feature name" };
+      const confirmed = await ctx.ui.confirm(
+        "确认启动新的 Devflow Feature",
+        `Feature：${feature}\n阶段：${phase}\n\n确认后由 Core 原子初始化并切换当前 Feature；不会由 AI 直接修改 STATE.md。若当前仍有未完成 Feature，Core 会拒绝切换并保持原状态。继续吗？`,
+      );
+      if (!confirmed) return { block: true, reason: "User declined runtime bootstrap authorization." };
+      if (!toolCallId) return { block: true, reason: "bootstrap runtime authorization is missing a tool-call binding" };
+      runtimeBootstrapAuthorizations.add(toolCallId);
+      bootstrapAuthorized = true;
+    }
+    if (parallelRunActive && toolName === "task") {
+      const branchContext = parallelBranchContext(event.input);
+      if (branchContext) parallelTaskContexts.set(event.toolCallId, branchContext);
+    }
+    if (activeContract && controlState.phase === "executing" && !toolName.startsWith("devflow_") && !internalControlResource) {
       if (!activeContract.allowedTools.includes(toolName)) {
         return { block: true, reason: `Active contract ${activeContract.contractId} does not allow tool: ${toolName}` };
       }
@@ -1692,15 +2281,15 @@ export default function devflowCore(pi: ExtensionAPI) {
     } else if (
       controlState.phase === "planning" &&
       toolName !== "devflow_contract" &&
-      !isInternalDevflowContractResource(toolName, event.input) &&
+      !internalControlResource &&
       !(toolName === "devflow_evidence" && String((event.input as Record<string, unknown> | undefined)?.action) !== "create") &&
+      !bootstrapAuthorized &&
       !(controlState.intent === "requirement-draft"
         ? isRequirementDraftToolAllowed(toolName, event.input)
         : isPlanningToolAllowed(toolName))
     ) {
       return { block: true, reason: planningToolBlockReason(toolName) };
     }
-    const toolInput = event.input && typeof event.input === "object" ? event.input as Record<string, unknown> : undefined;
     // Registry reconciliation is intentionally the one write operation an
     // agent may request while a step is blocked: it changes only derived
     // artifact metadata and never advances STATE, checkpoints, or ownership.
@@ -1710,7 +2299,7 @@ export default function devflowCore(pi: ExtensionAPI) {
       toolName === "devflow_transition" &&
       toolInput?.action === "complete-step" &&
       toolInput?.confirm === true;
-    if (isStateMutationTool(toolName) && !isRegistryReconciliation && !isUserConfirmedStepTransition) {
+    if (isStateMutationTool(toolName) && !isRegistryReconciliation && !isUserConfirmedStepTransition && !bootstrapAuthorized) {
       return {
         block: true,
         reason:
@@ -1729,6 +2318,18 @@ export default function devflowCore(pi: ExtensionAPI) {
         };
       }
     }
+    if (activeWorkflowTurn && !parallelRunActive && stepScopedMutationOwner(toolName, event.input) !== undefined) {
+      const inspected = await inspectWorkflow(ctx.cwd);
+      if (!inspected.result.ok || !inspected.snapshot) {
+        return {
+          block: true,
+          reason: `Active Devflow workflow mutation blocked because authoritative state could not be inspected: ${inspected.result.stderr || inspected.result.stdout}`,
+        };
+      }
+      const fresh = activeContract ? await contractIsFresh(ctx.cwd, activeContract) : false;
+      const reason = stepScopedMutationBlockReason(toolName, event.input, ctx.cwd, inspected.snapshot, activeContract, fresh);
+      if (reason) return { block: true, reason };
+    }
     if (
       !toolName.startsWith("devflow_") &&
       ["write", "edit", "apply_patch", "notebook_edit", "bash", "shell", "exec_command"].includes(toolName) &&
@@ -1739,10 +2340,30 @@ export default function devflowCore(pi: ExtensionAPI) {
         reason: "规范需求图谱、派生视图、机器 Evidence 与合同审计只能由 Core writer 写入；Skill 只能提交候选 delta 或 agent_claim。",
       };
     }
+    if (
+      !toolName.startsWith("devflow_") &&
+      ["write", "edit", "apply_patch", "notebook_edit"].includes(toolName)
+    ) {
+      const scopedFeatures = inputPaths(event.input, ctx.cwd)
+        .map(planningFeatureFromPath)
+        .filter((value): value is string => value !== null);
+      if (scopedFeatures.length > 0) {
+        const state = parseJsonResult(await runRuby(ctx.cwd, "workflow-orchestrator/scripts/inspect_state.rb", ["--json"]));
+        const activeFeature = typeof state?.current_feature === "string" ? state.current_feature : undefined;
+        const mismatched = scopedFeatures.find(feature => activeFeature && feature !== activeFeature);
+        if (mismatched) {
+          return {
+            block: true,
+            reason: `feature is not active: requested=${mismatched}, current=${activeFeature}; bootstrap the feature before writing feature-scoped artifacts`,
+          };
+        }
+      }
+    }
     if (toolName.startsWith("devflow_")) return;
     if (
       activeContract &&
       controlState.phase === "executing" &&
+      !internalControlResource &&
       ["write", "edit", "apply_patch", "notebook_edit"].includes(toolName)
     ) {
       const paths = inputPaths(event.input, ctx.cwd);
@@ -1804,12 +2425,31 @@ export default function devflowCore(pi: ExtensionAPI) {
   });
 
   pi.on("tool_result", async (event, ctx) => {
+    const taskContext = parallelTaskContexts.get(event.toolCallId);
+    if (parallelRunActive && event.toolName === "task") {
+      if (taskResultHasSuccessfulDispatch(event.details)) {
+        parallelDispatchSucceededThisTurn = true;
+      } else {
+        parallelDispatchFailureThisTurn = event.content
+          .filter(part => part.type === "text")
+          .map(part => part.text)
+          .join("\n")
+          .slice(0, 1000);
+      }
+      // Detached task lifecycle events arrive after tool_result and carry the
+      // parent tool-call id. Keep the correlation until that terminal event.
+      if (taskContext && !parallelRunActive) parallelTaskContexts.delete(event.toolCallId);
+    }
     if (event.isError) return;
     if (activeWorkflowTurn && activeContract) {
-      await appendEngineEvidence(ctx.cwd, "engine_dispatched", {
-        engine: event.toolName,
-        ai_capable: event.toolName === "task" || event.toolName.toLowerCase().includes("ai") || event.toolName.toLowerCase().includes("midscene"),
-      });
+      const taskWasDispatched = event.toolName !== "task" || taskResultHasSuccessfulDispatch(event.details);
+      if (taskWasDispatched) {
+        await appendEngineEvidence(ctx.cwd, "engine_dispatched", {
+          engine: event.toolName,
+          ai_capable: event.toolName === "task" || event.toolName.toLowerCase().includes("ai") || event.toolName.toLowerCase().includes("midscene"),
+          ...(taskContext ?? {}),
+        });
+      }
     }
     await runHook(ctx.cwd, "post_tool.py", {
       session_id: sessionId,
@@ -1864,6 +2504,26 @@ export default function devflowCore(pi: ExtensionAPI) {
     },
   });
 
+  pi.registerTool({
+    name: "devflow_wireframe",
+    label: "Devflow Wireframe",
+    description: "Build Core-owned wireframe metadata from the current canonical proposal. Approval is only available through the user-confirmed checkpoint runtime path.",
+    parameters: z.object({
+      action: z.literal("meta"),
+      feature: z.string().min(1),
+      expectedRevision: z.number().int().min(0),
+    }),
+    approval: "write",
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      return renderResult(
+        await runRuby(ctx.cwd, "workflow-orchestrator/scripts/wireframe_commit.rb", [
+          "--action", "meta", "--feature", params.feature, "--expected-revision", String(params.expectedRevision), "--write", "--json",
+        ]),
+        { action: params.action, feature: params.feature },
+      );
+    },
+  });
+
   pi.registerTool({
 
     name: "devflow_requirement_graph",
@@ -1892,6 +2552,19 @@ export default function devflowCore(pi: ExtensionAPI) {
     }),
     approval: (args) => args.action === "propose" || args.action === "confirm" ? "write" : "read",
     async execute(_id, params, _signal, _onUpdate, ctx) {
+      const graphWrite = params.action === "propose" || params.action === "confirm" || (params.action === "context" && params.write === true);
+      if (graphWrite) {
+        const state = parseJsonResult(await runRuby(ctx.cwd, "workflow-orchestrator/scripts/inspect_state.rb", ["--json"]));
+        const currentFeature = typeof state?.current_feature === "string" ? state.current_feature : undefined;
+        if (currentFeature && currentFeature !== params.feature) {
+          return renderResult({
+            ok: false,
+            exitCode: 1,
+            stdout: "",
+            stderr: `feature is not active: requested=${params.feature}, current=${currentFeature}; bootstrap the feature before writing its requirement graph`,
+          });
+        }
+      }
       const args = [params.action, "--feature", params.feature, "--json"];
       if (params.action === "context") {
         if (!params.sliceId) return renderResult({ ok: false, exitCode: 2, stdout: "", stderr: "context requires sliceId" });
@@ -2391,8 +3064,8 @@ export default function devflowCore(pi: ExtensionAPI) {
       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 (!["planning", "waiting-user", "awaiting-approval"].includes(controlState.phase)) {
-        return renderResult({ ok: false, exitCode: 2, stdout: "", stderr: "Contracts may only be activated from the planning phase or while the step waits for user review." });
+      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 执行合同",
@@ -2481,6 +3154,9 @@ export default function devflowCore(pi: ExtensionAPI) {
     }),
     approval: "write",
     async execute(_id, params, _signal, _onUpdate, ctx) {
+      // Consume the one-shot runtime authorization before running Core's
+      // atomic bootstrap sequence. A retry must obtain a fresh user approval.
+      runtimeBootstrapAuthorizations.delete(String(_id));
       const phase = params.phase?.trim() || defaultPhaseId(params.feature);
       if (!validPhaseId(phase)) {
         return {
@@ -2523,10 +3199,28 @@ export default function devflowCore(pi: ExtensionAPI) {
         "--json",
       ]);
       if (!controlPlaneSucceeded(artifacts)) return renderResult(artifacts, { stage: "artifacts" });
+      const inspected = await inspectWorkflow(ctx.cwd);
+      if (!inspected.result.ok || !inspected.snapshot) {
+        return renderResult(
+          { ok: false, exitCode: 1, stdout: "", stderr: "bootstrap completed but the resulting workflow state could not be inspected" },
+          { stage: "inspect-after-bootstrap" },
+        );
+      }
+      try {
+        setControlState(ctx, waitingUserState("准备进入需求入口分诊"));
+        await requestControlledRollover(ctx, inspected.snapshot);
+      } catch (error) {
+        setControlState(ctx, { intent: "workflow-execute", phase: "blocked", label: "会话轮换准备失败" });
+        return renderResult(
+          { ok: false, exitCode: 1, stdout: "", stderr: `bootstrap succeeded but session handoff could not be prepared: ${String(error)}` },
+          { stage: "rollover" },
+        );
+      }
       return renderResult(artifacts, {
         stage: "complete",
         workflow: workflow.stdout,
         state: state.stdout,
+        rollover: "prepared",
       });
     },
   });
@@ -2841,10 +3535,6 @@ export default function devflowCore(pi: ExtensionAPI) {
           );
           return;
         }
-        if (inspected.snapshot.action === "workflow_complete") {
-          ctx.ui.notify("Devflow workflow is already complete.", "info");
-          return;
-        }
         // Re-arm a durable rollover left by an interrupted runtime. An
         // explicit resume is the user's authorization for a fresh session to
         // adopt the same project's integrity-checked prepared handoff.
@@ -2864,12 +3554,11 @@ export default function devflowCore(pi: ExtensionAPI) {
             rolloverId: rollover.id,
           };
           await enqueueControlledRolloverRequest(ctx.cwd, rollover.id, currentSessionId);
+          setControlState(ctx, waitingUserState("正在恢复受控会话交接"));
+          ctx.ui.notify("Devflow 已恢复待完成的受控会话交接；当前回合结束后将继续切换。", "info");
+          return;
         }
-        setControlState(ctx, waitingUserState("等待用户审查步骤产物"));
-        ctx.ui.notify(
-          `Devflow 已恢复到 ${String((compactStep(inspected.snapshot.next_step) ?? compactStep(inspected.snapshot.current_step))?.id ?? "当前步骤")}；请审查当前产物后明确回复“批准执行”，或直接提出修改意见。`,
-          "info",
-        );
+        await resumeInspectedWorkflow(ctx, inspected.snapshot);
         return;
       }
       if (trimmed.startsWith("start ")) {