@xzzpig/pi-openspec-x 0.1.0

package/src/dispatch-gate.ts

@@ -0,0 +1,257 @@
+/**
+ * The enforced "review before tick" gate for agent mode (task 8.2; spec MUST
+ * "未审查不得勾选").
+ *
+ * `worker-dispatch.ts` decides *whether* a tick is allowed; this module is what
+ * makes the decision binding. It tracks the main session's dispatch traffic —
+ * an `opsx-worker` dispatch, the `report_work` review that must follow it, and
+ * the tick — and the `tool_call` handler uses it to block an
+ * `update_goal_task` completion that has no review behind it.
+ *
+ * The gate is agent-only on purpose: direct mode has no dispatch, so there is
+ * nothing to reconcile and the completion audit remains the only gate.
+ */
+import {
+  decideTaskTick,
+  detectStalledDispatch,
+  type DispatchTrace,
+  type WorkReportLike,
+} from "./worker-dispatch.ts";
+
+/** One observed worker dispatch and what happened to it. */
+interface DispatchRecord {
+  /** The task the dispatch was for, when it could be read from the payload. */
+  taskId: string | undefined;
+  changedFiles: number;
+  ticked: boolean;
+}
+
+/**
+ * Explicit failure markers in a recorded verification result.
+ *
+ * Kept as two expressions because the uppercase markers must stay
+ * case-sensitive: a case-insensitive `FAIL` would match the "0 failures" of a
+ * clean run, and a false hold is worse than a missed one here (the completion
+ * audit is the real verification gate). The accepted cost is that a lowercase
+ * marker such as "2 errors" is not detected — only `FAIL`/`FAILED`/`ERROR` in
+ * caps, a non-zero exit code, or an explicit "<n> failures" count are.
+ */
+const UPPERCASE_FAILURE_RE = /(^|\s)(FAIL|FAILED|ERROR|✗)/;
+const NUMERIC_FAILURE_RE =
+  /\bexit(?:ed)? (?:code )?[1-9]\b|\b[1-9]\d* (?:tests? )?fail/i;
+
+function looksFailed(result: string | undefined): boolean {
+  if (result === undefined) return false;
+  return UPPERCASE_FAILURE_RE.test(result) || NUMERIC_FAILURE_RE.test(result);
+}
+
+/**
+ * Per-session dispatch bookkeeping. One tracker per active agent flow.
+ */
+export class DispatchReviewTracker {
+  private readonly records: DispatchRecord[] = [];
+  private readonly reports = new Map<string, WorkReportLike>();
+
+  /**
+   * Record an `opsx-worker` dispatch. `taskId` is undefined when the payload
+   * did not name the task (the `subagent` tool accepts several shapes), which
+   * still counts as "a dispatch happened" — the gate must never deadlock on a
+   * task-id parsing miss.
+   */
+  noteDispatch(taskId: string | undefined): void {
+    this.records.push({
+      taskId,
+      changedFiles: 0,
+      ticked: false,
+    });
+  }
+
+  /**
+   * Remember the main agent's `report_work` review and attach its changed-file
+   * count to the most recent dispatch it can belong to.
+   */
+  rememberReport(report: WorkReportLike): void {
+    this.reports.set(report.taskId, report);
+    for (let index = this.records.length - 1; index >= 0; index -= 1) {
+      const record = this.records[index]!;
+      if (record.taskId !== undefined && record.taskId !== report.taskId) {
+        continue;
+      }
+      record.taskId = report.taskId;
+      record.changedFiles = report.changedFiles.length;
+      break;
+    }
+  }
+
+  /** Record that a task was ticked. */
+  noteTick(taskId: string): void {
+    for (const record of this.records) {
+      if (record.taskId === taskId) record.ticked = true;
+    }
+  }
+
+  /** The observed `report_work` for a task, if the main agent submitted one. */
+  reportFor(taskId: string): WorkReportLike | undefined {
+    return this.reports.get(taskId);
+  }
+
+  /**
+   * Whether a worker dispatch was observed for the task. A dispatch whose
+   * payload never named a task counts for every task: the alternative is
+   * blocking a legitimate tick because of an unparsed payload shape.
+   */
+  dispatched(taskId: string): boolean {
+    return this.records.some(
+      (record) => record.taskId === taskId || record.taskId === undefined,
+    );
+  }
+
+  /** The bounded dispatch trace used for stall detection. */
+  traces(): DispatchTrace[] {
+    return this.records.map((record) => ({
+      taskId: record.taskId ?? "<unknown>",
+      changedFiles: record.changedFiles,
+      ticked: record.ticked,
+    }));
+  }
+
+  /** Tasks that keep being dispatched without producing or reporting work. */
+  stalled(threshold = 2): string[] {
+    const result = detectStalledDispatch(this.traces(), threshold);
+    return result.stalled ? result.taskIds : [];
+  }
+
+  reset(): void {
+    this.records.length = 0;
+    this.reports.clear();
+  }
+}
+
+type TickGateDecision =
+  | { allow: true; warnings: string[] }
+  | { allow: false; reason: string };
+
+/**
+ * Root paths that belong to tooling rather than to a task's output. A window
+ * delta picks these up because extensions write into the working directory
+ * (pi-lens probe logs), and they are not the dispatch's work. Build-output
+ * directories are deliberately NOT listed: `dist/`, `coverage/`,
+ * `node_modules/` and `.cache/` are exactly what the agent write allowlist
+ * permits, so a task whose output lives there must stay reconcilable.
+ */
+const RUNTIME_ROOT_PREFIXES = [".pi/", ".pi-lens-probe-home/"];
+
+function normalizePath(filePath: string): string {
+  return filePath.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+
+/** Drop tool-runtime noise from an observed window delta. */
+function filterTaskDelta(paths: readonly string[]): string[] {
+  return paths.filter((entry) => {
+    const normalized = normalizePath(entry);
+    return !RUNTIME_ROOT_PREFIXES.some((prefix) =>
+      normalized.startsWith(prefix),
+    );
+  });
+}
+
+/**
+ * Decide whether `update_goal_task status=complete` may proceed for a task.
+ *
+ * The checks run in this order, and each one is unconditional:
+ *
+ * 1. a worker dispatch must have been observed;
+ * 2. the dispatch must have been reviewed with `report_work`;
+ * 3. the recorded verification must have run and passed;
+ * 4. the report's files must reconcile with the window delta — a claimed file
+ *    nobody changed is a false claim (hold), while a delta file the report
+ *    omitted is only a warning, because the delta also carries tool-runtime
+ *    noise no report can be expected to declare.
+ *
+ * Step 3 must not be reachable only through `decideTaskTick`: that function
+ * reports file-set mismatches before it looks at verification, so delegating
+ * the whole decision to it let a failed or missing verification through
+ * whenever the delta happened to contain an extra file.
+ */
+export function evaluateTickGate(
+  tracker: DispatchReviewTracker,
+  input: { taskId: string; observedChangedFiles?: string[] },
+): TickGateDecision {
+  if (!tracker.dispatched(input.taskId)) {
+    return {
+      allow: false,
+      reason: `Task ${input.taskId} has no observed opsx-worker dispatch. Agent mode implements every task through a dispatch: dispatch opsx-worker for it, review the diff, then tick.`,
+    };
+  }
+
+  const report = tracker.reportFor(input.taskId);
+  if (!report) {
+    return {
+      allow: false,
+      reason: `The dispatch for task ${input.taskId} has not been reviewed. Call report_work with taskId "${input.taskId}", the changed files you verified, and the verification command and result, then tick.`,
+    };
+  }
+
+  const result = report.selfVerification.result;
+  // The structured verdict wins: when the report states it explicitly, the
+  // free-text scan is never consulted (spec: 门控判断 MUST 依据结构化裁决字段，
+  // MUST NOT 依赖解析子 agent 的自由文本). It remains the fallback for reports
+  // that carry only a result string.
+  const structured = report.verificationPassed;
+  const verification = {
+    ran:
+      structured !== undefined ||
+      report.selfVerification.command !== undefined ||
+      result !== undefined,
+    passed: structured !== undefined ? structured : !looksFailed(result),
+    ...(result !== undefined ? { evidence: result } : {}),
+  };
+  if (!verification.ran) {
+    return {
+      allow: false,
+      reason:
+        "The task's verification has not been run; tick only after it passes.",
+    };
+  }
+  if (!verification.passed) {
+    return {
+      allow: false,
+      reason: `The task's verification failed${result ? `: ${result}` : ""}. Fix and re-verify before ticking.`,
+    };
+  }
+
+  // Reconciliation runs on the noise-filtered delta, so a report is never
+  // accused of a phantom claim just because a probe log was filtered out, and
+  // a build-output task (dist/, coverage/) is never filtered out of its own
+  // evidence.
+  const observed = filterTaskDelta(
+    input.observedChangedFiles ?? report.changedFiles,
+  );
+  const decision = decideTaskTick(report, {
+    observedChangedFiles: observed,
+    verification,
+  });
+  if (decision.kind === "tick") {
+    return { allow: true, warnings: [] };
+  }
+
+  // After the verification pre-check the only possible hold is a file-set
+  // mismatch. Distinguish the two directions by set membership, never by the
+  // wording of the hold reason.
+  const observedSet = new Set(observed.map(normalizePath));
+  const claimedSet = new Set(report.changedFiles.map(normalizePath));
+  const phantom = [...claimedSet].filter((file) => !observedSet.has(file));
+  if (phantom.length > 0) {
+    return { allow: false, reason: decision.reason };
+  }
+  const unclaimed = [...observedSet].filter((file) => !claimedSet.has(file));
+  if (unclaimed.length > 0) {
+    return {
+      allow: true,
+      warnings: [
+        `The window delta contains file(s) the report did not declare: ${unclaimed.join(", ")}. Confirm none of them belongs to this task before ticking.`,
+      ],
+    };
+  }
+  return { allow: false, reason: decision.reason };
+}

package/src/final-gate.ts

@@ -0,0 +1,158 @@
+/**
+ * Final review gate: point one opsx goal's completion audit at the custom
+ * opsx-reviewer, and turn the audit's structured verdict into the flow's next
+ * action (design D3/D10; openspec change add-pi-openspec-x, task 8.3).
+ *
+ * goal-x's completion transaction runs an independent audit BEFORE committing
+ * completion, so the final gate needs no plugin-side verdict channel:
+ *
+ * - S1 (per-goal auditor override, goal-x fork): `setGoalAuditorOverride`
+ *   attaches the opsx-reviewer request/prompt settings to exactly one goal id.
+ * - S2 (cross-extension resolver, goal-x fork): `registerAuditorAgentResolver`
+ *   supplies the opsx-reviewer runtime definition, which file-based preflight
+ *   discovery cannot see.
+ *
+ * Both are keyed to the opsx goal, so a user's ordinary `/goal` keeps the
+ * default auditor and checklist. A disapproved audit leaves the goal active
+ * (goal-x semantics): the flow fixes and re-reviews until approved, then guides
+ * the user to archive — the plugin never archives for them.
+ */
+import type { RuntimeAgentDefinition } from "@xzzpig/pi-subagents/agents";
+
+import { OPSX_AGENT_DEFINITIONS } from "./agents.ts";
+
+export const OPSX_REVIEWER_AGENT_NAME = "opsx-reviewer";
+
+/** The four review dimensions injected into the auditor's checklist. */
+export const OPSX_REVIEW_CHECKLIST = [
+  "Plan conformance: every task and requirement in tasks.md/design is verifiably satisfied or reported as a finding.",
+  "Code quality: the change is coherent, follows project conventions, and has no obvious defects.",
+  "Verification evidence: every claim is backed by real, reproducible command output.",
+  "Scope fidelity: every changed file belongs to the plan; unrequested changes are findings.",
+];
+
+/** The extra instructions injected into the auditor's prompt. */
+export const OPSX_REVIEW_INSTRUCTIONS = [
+  "This goal was created by pi-openspec-x for an OpenSpec change. Review the execution-window delta injected in your dispatch context, not the whole repository.",
+  "Your verdict drives a fix/re-review loop: disapprove with concrete, actionable findings so the next round can address them exactly.",
+].join("\n");
+
+/** Per-goal auditor settings the S1 override carries. */
+export interface OpsxAuditorOverride {
+  agent: string;
+  checklistExtra: string[];
+  instructions: string;
+}
+
+/** Build the per-goal auditor override for an opsx goal. */
+export function buildOpsxAuditorOverride(): OpsxAuditorOverride {
+  return {
+    agent: OPSX_REVIEWER_AGENT_NAME,
+    checklistExtra: [...OPSX_REVIEW_CHECKLIST],
+    instructions: OPSX_REVIEW_INSTRUCTIONS,
+  };
+}
+
+/**
+ * The S2 resolver: answer only for the opsx-reviewer name, with the runtime
+ * definition this plugin registered. Every other name (including the default
+ * `goal-auditor`) is a miss, so ordinary goals keep their original path.
+ *
+ * The resolver is a module-level singleton so repeated installs register the
+ * same function reference.
+ */
+let opsxResolverSingleton:
+  | ((agentName: string) => RuntimeAgentDefinition | undefined)
+  | undefined;
+
+export function createOpsxAuditorResolver(): (
+  agentName: string,
+) => RuntimeAgentDefinition | undefined {
+  opsxResolverSingleton ??= (agentName: string) =>
+    agentName === OPSX_REVIEWER_AGENT_NAME
+      ? OPSX_AGENT_DEFINITIONS[OPSX_REVIEWER_AGENT_NAME]
+      : undefined;
+  return opsxResolverSingleton;
+}
+
+/** The slice of goal-x the final gate needs (structurally the S1/S2 APIs). */
+export interface OpsxAuditorInstaller {
+  setGoalAuditorOverride(
+    goalId: string,
+    override: Record<string, unknown>,
+  ): void;
+  registerAuditorAgentResolver(
+    resolver: (agentName: string) => RuntimeAgentDefinition | undefined,
+  ): () => void;
+}
+
+/**
+ * Register the S2 resolver once for the process. Idempotent: repeated calls
+ * hand goal-x the same function reference, which its registry dedupes.
+ */
+export function registerOpsxAuditorResolver(goalX: {
+  registerAuditorAgentResolver(
+    resolver: (agentName: string) => RuntimeAgentDefinition | undefined,
+  ): () => void;
+}): () => void {
+  return goalX.registerAuditorAgentResolver(createOpsxAuditorResolver());
+}
+
+/**
+ * Install the opsx final-audit configuration for one goal: the per-goal
+ * override plus the cross-extension resolver. Returns the resolver dispose
+ * function (the override lives for the session; goal-x clears it with the
+ * goal). Throws only if goal-x rejects the override (a plugin bug, not a user
+ * error).
+ */
+export function installOpsxAuditorForGoal(
+  goalX: OpsxAuditorInstaller,
+  goalId: string,
+): { disposeResolver: () => void } {
+  goalX.setGoalAuditorOverride(goalId, { ...buildOpsxAuditorOverride() });
+  const disposeResolver = registerOpsxAuditorResolver(goalX);
+  return { disposeResolver };
+}
+
+/** The structured completion-audit result the gate consumes. */
+export interface FinalAuditResult {
+  approved: boolean;
+  report: string;
+  findings: string[];
+}
+
+export type FinalGateDecision =
+  | { kind: "approved"; report: string }
+  | { kind: "fix"; findings: string[] };
+
+/**
+ * Map the completion audit's structured verdict to the flow's next action.
+ * `approved` completes the goal (goal-x already committed it); otherwise the
+ * goal stays active and the findings drive the fix round.
+ */
+export function decideFinalGate(result: FinalAuditResult): FinalGateDecision {
+  if (result.approved) {
+    return { kind: "approved", report: result.report };
+  }
+  return {
+    kind: "fix",
+    findings:
+      result.findings.length > 0
+        ? [...result.findings]
+        : [
+            "The completion audit disapproved without naming findings; re-run the audit with concrete findings.",
+          ],
+  };
+}
+
+/**
+ * The archive guidance shown after approval. The plugin never archives: the
+ * user runs the openspec archive flow themselves.
+ */
+export function renderArchiveGuidance(changeId: string): string {
+  return [
+    `[OPSX FINAL AUDIT APPROVED change=${changeId}]`,
+    `The completion audit approved change "${changeId}". The goal is complete.`,
+    `Archive when you are ready: run the openspec archive flow (e.g. \`openspec archive "${changeId}"\`). pi-openspec-x never archives for you.`,
+  ].join("\n");
+}

package/src/flow-entries.ts

@@ -0,0 +1,258 @@
+/**
+ * Flow entries, the turn status snapshot, and the progress line renderers
+ * (design D8; openspec change add-pi-openspec-x, task 9.1).
+ *
+ * Flow state is recorded as custom session entries (mode in/out, phase change,
+ * verdict, task ticked) plus a `display: false`-style status snapshot appended
+ * each turn. Custom entries never enter the LLM context, so the snapshot keeps
+ * the interface recoverable after a compaction without perturbing the prompt
+ * cache. The renderers turn entries and messages into compact progress lines.
+ *
+ * The state model and text renderers are pure; the registration wiring only
+ * wraps them in minimal components.
+ */
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  ExtensionHandler,
+  TurnEndEvent,
+  TurnEndEventResult,
+} from "@earendil-works/pi-coding-agent";
+
+export const OPSX_ENTRY_TYPES = {
+  modeEntered: "pi-openspec-x/mode-entered",
+  modeExited: "pi-openspec-x/mode-exited",
+  phaseChanged: "pi-openspec-x/phase-changed",
+  verdict: "pi-openspec-x/verdict",
+  approval: "pi-openspec-x/approval",
+  taskTicked: "pi-openspec-x/task-ticked",
+  rollback: "pi-openspec-x/rollback",
+  progress: "pi-openspec-x/progress",
+  statusSnapshot: "pi-openspec-x/status-snapshot",
+} as const;
+
+type OpsxEntryType = (typeof OPSX_ENTRY_TYPES)[keyof typeof OPSX_ENTRY_TYPES];
+
+type OpsxFlowMode = "plan" | "agent" | "direct";
+
+export interface OpsxFlowState {
+  mode?: OpsxFlowMode;
+  changeId?: string;
+  phase?: string;
+  round?: number;
+  tasksTotal?: number;
+  tasksDone?: number;
+  lastVerdict?: string;
+  updatedAt?: string;
+  /** Set on the snapshot written when the flow ends, so a restored snapshot
+   * from a previous process is not shown as if the flow were still running. */
+  ended?: boolean;
+}
+
+/** Append a flow entry. Best-effort: a failed append never breaks the flow. */
+export function appendFlowEntry(
+  pi: Pick<ExtensionAPI, "appendEntry">,
+  type: OpsxEntryType,
+  data: Record<string, unknown>,
+): void {
+  try {
+    pi.appendEntry(type, data);
+  } catch {
+    // Observability is best-effort.
+  }
+}
+
+/**
+ * Append the per-turn status snapshot (a custom entry, so it stays out of the
+ * LLM context and survives compaction for interface recovery).
+ */
+export function appendStatusSnapshot(
+  pi: Pick<ExtensionAPI, "appendEntry">,
+  state: OpsxFlowState,
+): OpsxFlowState {
+  const snapshot: OpsxFlowState = {
+    ...state,
+    updatedAt: new Date().toISOString(),
+  };
+  appendFlowEntry(pi, OPSX_ENTRY_TYPES.statusSnapshot, {
+    ...snapshot,
+  });
+  return snapshot;
+}
+
+/** Minimal session-entry view (pi's CustomEntry shape). */
+export interface SessionEntryLike {
+  type?: string;
+  customType?: string;
+  data?: unknown;
+}
+
+/**
+ * Recover the latest flow state from session entries. Used after a compaction
+ * (or a reload) to restore the status line. Returns undefined when no snapshot
+ * was ever written.
+ */
+export function restoreFlowState(
+  entries: readonly SessionEntryLike[],
+): OpsxFlowState | undefined {
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    const entry = entries[index];
+    if (
+      entry?.type === "custom" &&
+      entry.customType === OPSX_ENTRY_TYPES.statusSnapshot &&
+      entry.data &&
+      typeof entry.data === "object"
+    ) {
+      return { ...(entry.data as OpsxFlowState) };
+    }
+  }
+  return undefined;
+}
+
+function asText(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value : undefined;
+}
+
+function asNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value)
+    ? value
+    : undefined;
+}
+
+/** Render one flow entry as a compact progress line. */
+export function renderFlowEntryText(
+  customType: string,
+  data: Record<string, unknown> | undefined,
+): string | undefined {
+  const change = asText(data?.changeId) ?? "?";
+  switch (customType) {
+    case OPSX_ENTRY_TYPES.modeEntered:
+      return `◆ opsx ${asText(data?.mode) ?? "?"} mode entered (${change})`;
+    case OPSX_ENTRY_TYPES.modeExited:
+      return `◇ opsx ${asText(data?.mode) ?? "?"} mode exited (${change})`;
+    case OPSX_ENTRY_TYPES.phaseChanged:
+      return `→ phase ${asText(data?.phase) ?? "?"} (${change})`;
+    case OPSX_ENTRY_TYPES.verdict: {
+      const round = asNumber(data?.round);
+      return `⚖ ${asText(data?.verdict) ?? "?"}${round ? ` round ${round}` : ""} (${change})`;
+    }
+    case OPSX_ENTRY_TYPES.approval:
+      return `✍ plan ${asText(data?.decision) ?? "?"} (${change})`;
+    case OPSX_ENTRY_TYPES.taskTicked:
+      return `☑ ${asText(data?.taskId) ?? "?"} (${change})`;
+    case OPSX_ENTRY_TYPES.rollback: {
+      const restored = asNumber(data?.restored) ?? 0;
+      const deleted = asNumber(data?.deleted) ?? 0;
+      return `↩ rollback: ${restored} restored, ${deleted} removed (${change})`;
+    }
+    default:
+      return undefined;
+  }
+}
+
+/** Render the session status line from the current flow state. */
+export function renderStatusLine(state: OpsxFlowState): string {
+  const parts: string[] = ["opsx"];
+  if (state.mode) parts.push(state.mode);
+  if (state.changeId) parts.push(state.changeId);
+  if (state.phase) parts.push(state.phase);
+  if (typeof state.round === "number") parts.push(`round ${state.round}`);
+  if (
+    typeof state.tasksTotal === "number" &&
+    typeof state.tasksDone === "number"
+  ) {
+    parts.push(`tasks ${state.tasksDone}/${state.tasksTotal}`);
+  }
+  if (state.lastVerdict) parts.push(`last ${state.lastVerdict}`);
+  return parts.join(" · ");
+}
+
+/** A minimal TUI component (render + invalidate are required by pi's Component). */
+interface MinimalComponent {
+  render(width: number): string[];
+  invalidate(): void;
+}
+
+function lineComponent(text: string): MinimalComponent {
+  return { render: () => [text], invalidate: () => {} };
+}
+
+/**
+ * Register the entry renderers for the flow entries. Each renders a single
+ * compact line; unknown shapes fall back to the default renderer.
+ */
+export function registerFlowRenderers(pi: ExtensionAPI): void {
+  const entryTypes: OpsxEntryType[] = [
+    OPSX_ENTRY_TYPES.modeEntered,
+    OPSX_ENTRY_TYPES.modeExited,
+    OPSX_ENTRY_TYPES.phaseChanged,
+    OPSX_ENTRY_TYPES.verdict,
+    OPSX_ENTRY_TYPES.approval,
+    OPSX_ENTRY_TYPES.taskTicked,
+    OPSX_ENTRY_TYPES.rollback,
+  ];
+  for (const entryType of entryTypes) {
+    pi.registerEntryRenderer(entryType, (entry) => {
+      const data =
+        entry.data && typeof entry.data === "object"
+          ? (entry.data as Record<string, unknown>)
+          : undefined;
+      const text = renderFlowEntryText(entryType, data);
+      return text ? lineComponent(text) : undefined;
+    });
+  }
+}
+
+/** The current flow state, recovered from the session snapshot. */
+function currentFlowState(ctx: ExtensionContext): OpsxFlowState | undefined {
+  try {
+    return restoreFlowState(ctx.sessionManager.getEntries());
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Build the turn_end handler that appends the per-turn status snapshot. The
+ * snapshot is a custom entry (never sent to the LLM), so it keeps the
+ * interface recoverable after a compaction without touching the prompt cache.
+ */
+export function createStatusSnapshotTurnEndHandler(
+  pi: Pick<ExtensionAPI, "appendEntry">,
+  getState: (sessionId: string) => OpsxFlowState | undefined,
+): ExtensionHandler<TurnEndEvent, TurnEndEventResult> {
+  return (_event: TurnEndEvent, ctx: ExtensionContext): void => {
+    let sessionId: string;
+    try {
+      sessionId = ctx.sessionManager?.getSessionId() ?? "unknown";
+    } catch {
+      return;
+    }
+    const live = getState(sessionId);
+    if (live) {
+      appendStatusSnapshot(pi, live);
+    }
+    // A process restart leaves the in-memory flow registry empty; the last
+    // persisted snapshot is then the only record of where the flow stood, so
+    // restore it instead of showing nothing (spec: 流程快照 SHALL 随会话持久化，
+    // 并在会话压缩后仍能恢复显示当前状态).
+    const restored = live ? undefined : currentFlowState(ctx);
+    const state = live ?? (restored?.ended ? undefined : restored);
+    if (!state) {
+      // A finished (or never-started) flow must not leave a stale mode/phase
+      // on the footer; clearing is idempotent when nothing was set.
+      try {
+        if (ctx.hasUI) ctx.ui.setStatus("opsx", undefined);
+      } catch {
+        // Status is best-effort.
+      }
+      return;
+    }
+    // The session status line keeps the current mode/phase visible (task 9.2).
+    try {
+      if (ctx.hasUI) ctx.ui.setStatus("opsx", renderStatusLine(state));
+    } catch {
+      // Status is best-effort.
+    }
+  };
+}