@xzzpig/pi-openspec-x 0.1.0 → 0.2.1

package/src/index.ts

@@ -1,4 +1,7 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
 
 import { loadOpsxConfig, type OpsxConfig } from "./config.ts";
 import {
@@ -15,6 +18,9 @@ import {
 } from "./dependencies.ts";
 import { createResourcesDiscoverHandler } from "./discover.ts";
 import { createOpsxRecoverySessionStartHandler } from "./goal-base.ts";
+import { readGoalBaseSummaries } from "./goal-base.ts";
+import { registerChildReportIngestion } from "./child-report-ingestion.ts";
+import { childReportFlowId } from "./child-report-ingestion.ts";
 import {
   registerOpsxAuditorResolver,
   buildOpsxAuditorOverride,
@@ -27,13 +33,17 @@ import {
 import {
   registerImplementFlow,
   activeImplementFlow,
+  rebindImplementFlow,
 } from "./implement-command.ts";
 import { createOpsxSessionStartHandler } from "./mode.ts";
-import { registerPlanFlow, activePlanSession } from "./plan-command.ts";
+import {
+  registerPlanFlow,
+  activePlanSession,
+  rebindPlanFlow,
+} from "./plan-command.ts";
 import { registerRollbackFlow } from "./rollback-command.ts";
 import { registerPlanGateTools } from "./plan-gate.ts";
-import { registerProgressObserver } from "./progress-observer.ts";
-import { registerReportTools } from "./report-tools.ts";
+import { recordChildReportProgress } from "./progress-observer.ts";
 import { buildSandboxProfiles } from "./sandbox-profiles.ts";
 
 // Read once at extension load (merge semantics in loadOpsxConfig).
@@ -65,8 +75,10 @@ const config: OpsxConfig = loadOpsxConfig();
  * semantics; see mode.ts).
  *
  * Registers the three child reporting tools (report_gap_analysis,
- * report_plan_review, report_work) that the opsx subagents submit their
- * structured results through.
+ * report_plan_review, report_work) through the role-specific child-only
+ * extensions declared in agents.ts (design D1): each tool is registered into
+ * its own subagent's process and never into the main session, so the parent's
+ * tool declaration and prompt rules stay free of them.
  *
  * pi-subagents is probed the same lazy way: on success the four opsx
  * subagents (opsx-gap-analysis / opsx-plan-review / opsx-worker / opsx-reviewer) are
@@ -95,10 +107,12 @@ export default async function piOpenspecX(pi: ExtensionAPI): Promise<void> {
     }
   }
 
-  registerReportTools(pi);
-  // Parent-side projection of the subagents' structured progress (task 9.2).
-  registerProgressObserver(pi);
   // Progress lines for the flow entries (task 9.1).
+  //
+  // The progress board is no longer fed by a main-session `tool_result`
+  // listener: the report tools are not registered here any more (design D1),
+  // so the only honest source is an accepted child report, delivered through
+  // the ingestion callback below (task 4.4).
   registerFlowRenderers(pi);
   // `/opsx:plan`: planner mode + append-only phase injection (task 7.1).
   registerPlanFlow(pi);
@@ -170,4 +184,94 @@ export default async function piOpenspecX(pi: ExtensionAPI): Promise<void> {
   void disposeSessionStart;
   void disposeRecoverySessionStart;
   void disposeStatusSnapshot;
+
+  // Flow recovery (design D5): the flow registries are process memory, so a
+  // cold start leaves them empty while the branch still holds the flow's own
+  // entries. Re-bind on every session boundary and, as a lazy fallback, on the
+  // first tool call of a session that missed them — otherwise a restored
+  // session would silently skip the completion gate.
+  const rebindKeys = new Set<string>();
+  const rebindFlows = async (ctx: ExtensionContext): Promise<void> => {
+    const sessionId = ctx.sessionManager.getSessionId();
+    const key = `${sessionId}:${ctx.sessionManager.getLeafId() ?? "?"}`;
+    if (rebindKeys.has(key)) return;
+    rebindKeys.add(key);
+    try {
+      rebindPlanFlow(sessionId, ctx);
+    } catch {
+      // Recovery is best-effort; an unbound flow stays unbound rather than
+      // being bound to the wrong thing.
+    }
+    try {
+      const result = await rebindImplementFlow(ctx, {
+        readGoals: (innerCtx: ExtensionContext) =>
+          readGoalBaseSummaries({
+            cwd: innerCtx.cwd,
+            sessionManager: innerCtx.sessionManager,
+          }),
+      });
+      if (!result.ok) {
+        pi.sendMessage(
+          {
+            customType: "pi-openspec-x/recovery-notice",
+            content: result.reason,
+            display: true,
+          },
+          { deliverAs: "followUp" },
+        );
+      }
+    } catch {
+      // Best-effort: never break a session boundary.
+    }
+  };
+  const disposeRebindStart = pi.on(
+    "session_start",
+    (_event, ctx: ExtensionContext) => rebindFlows(ctx),
+  );
+  const disposeRebindSwitch = pi.on(
+    "session_before_switch",
+    (_event, ctx: ExtensionContext) => rebindFlows(ctx),
+  );
+  const disposeRebindTree = pi.on(
+    "session_tree",
+    (_event, ctx: ExtensionContext) => rebindFlows(ctx),
+  );
+  const disposeRebindToolCall = pi.on(
+    "tool_call",
+    (_event, ctx: ExtensionContext) => rebindFlows(ctx),
+  );
+  void disposeRebindStart;
+  void disposeRebindSwitch;
+  void disposeRebindTree;
+  void disposeRebindToolCall;
+
+  // Automatic child-report ingestion (design D3): the report tools live only in
+  // their own child processes, so the parent reconstructs delivery from its own
+  // launch records plus the child's canonical session record.
+  registerChildReportIngestion(pi, {
+    activeFlow: (sessionId) => {
+      const flow = activeImplementFlow(sessionId);
+      if (!flow) return undefined;
+      return {
+        flowId: childReportFlowId(sessionId, flow.changeId),
+        changeId: flow.changeId,
+        goalId: flow.goalId,
+      };
+    },
+    // Display-only projection of an accepted report's structured progress.
+    // It never gates, completes, or approves anything (task 4.4).
+    onProgress: ({ sessionId, toolName, report }) => {
+      recordChildReportProgress(pi, sessionId, { toolName, report });
+    },
+    // A durable record that cannot be confirmed is a real gap — the receipt
+    // will not survive a restart. Surfacing it keeps a silent persistence
+    // failure from looking like persistence was never wired (design D5).
+    onDiagnostic: (message) => {
+      pi.sendMessage({
+        customType: "pi-openspec-x/recovery-notice",
+        content: `[OPSX CHILD REPORT] ${message}`,
+        display: true,
+      });
+    },
+  });
 }

package/src/objective.ts

@@ -125,14 +125,14 @@ function agentBoundaries(writable: readonly string[]): string[] {
     "- openspec/ plan files (tasks.md, proposal.md, specs/, design.md) are read-only for opsx-worker; only the main agent ticks tasks.md, after review.",
     "",
     "Worker dispatch contract (task 8.2): every opsx-worker dispatch carries these six sections, in this order:",
-    "1. Task — the task id and title.",
+    "1. Task — the task id and title, and on its own line the exact marker `[OPSX WORKER DISPATCH task=<taskId>]` with the task id percent-encoded. Every dispatch, and every resume of it, must carry the marker: it is what attributes the worker's report to the task.",
     "2. Expected output — the concrete files/behavior the dispatch must produce.",
     "3. Tools — the tools the worker needs for this task.",
     "4. Must do — the task-specific obligations.",
     "5. Must not do — the task-specific prohibitions, plus:",
     ...STANDARD_WORKER_MUST_NOT_DO.map((rule) => `   - ${rule}`),
     "6. Context — the files/behavior/constraints the worker needs to know.",
-    "After the dispatch: review its full diff and its verification output, then call report_work with taskId, changedFiles and the verification command/result. Ticking a task before that report exists is blocked by the tick gate, and a report that claims files the dispatch did not change (or omits files it did) is held for reconciliation.",
+    "After the dispatch: the worker's own report is recorded automatically from its run, so never transcribe or re-submit it yourself and do not look for a tool to file it with. Review the full diff and the verification output against that report, then tick the task. Ticking a task whose dispatch produced no accepted report is blocked by the gate, and a report that claims files the dispatch did not change (or omits files it did) is held for reconciliation.",
     "",
     "Don'ts:",
     "- Do not edit source files directly, not even for a one-line fix; dispatch opsx-worker.",

package/src/plan-command.ts

@@ -100,6 +100,52 @@ export function endPlanFlow(sessionId: string): string | undefined {
   return session.changeId;
 }
 
+/**
+ * Restore a plan binding from the current branch (design D5).
+ *
+ * Read-only: it re-establishes which plan flow this session is in so the
+ * phase injection and status snapshots keep working after a restart. It never
+ * re-runs the command, re-approves a plan, or changes a mode.
+ */
+export function rebindPlanFlow(
+  sessionId: string,
+  ctx: { sessionManager?: { getBranch(): readonly unknown[] } },
+): { changeId: string } | undefined {
+  const existing = planSessions.get(sessionId);
+  if (existing) return { changeId: existing.changeId };
+
+  let branch: Array<{ customType?: string; data?: unknown }> = [];
+  try {
+    branch = (ctx.sessionManager?.getBranch() ?? []) as typeof branch;
+  } catch {
+    return undefined;
+  }
+  let changeId: string | undefined;
+  for (let index = branch.length - 1; index >= 0; index -= 1) {
+    const entry = branch[index];
+    if (entry?.customType === OPSX_ENTRY_TYPES.modeExited) break;
+    if (entry?.customType !== OPSX_ENTRY_TYPES.modeEntered) continue;
+    const data = entry.data as
+      | { changeId?: unknown; mode?: unknown }
+      | undefined;
+    if (data?.mode === "plan" && typeof data.changeId === "string") {
+      changeId = data.changeId;
+    }
+    break;
+  }
+  if (!changeId) return undefined;
+
+  planSessions.set(sessionId, {
+    changeId,
+    injected: new Set<string>(),
+    // Suppress the one-shot notices for a recovered flow: the user already saw
+    // them before the restart, and re-sending them would be noise.
+    degradedNotified: true,
+    reviewNotified: true,
+  });
+  return { changeId };
+}
+
 function defaultFetchStatus(
   changeId: string,
   options: OpenspecCliOptions,

package/src/progress-observer.ts

@@ -3,76 +3,70 @@
  * MUST 经结构化上报（阶段标签 + 百分比，或等效字段），由主会话投影为看板展示).
  *
  * The reporting tools carry an optional structured `progress` field. A child's
- * tool call runs in the child's own session, so the parent does not see it
- * directly; what the parent does see is every report that reaches ITS session —
- * the main agent's own `report_work` (the tick gate requires it in agent mode)
- * and any report relayed up. This observer folds whatever it observes into one
- * row per agent+phase and appends a `progress` flow entry whose renderer draws
- * the board.
+ * tool call runs in the child's own session, so the parent never sees the call
+ * itself — and since the report tools are no longer registered in the main
+ * session at all (design D1), the parent cannot observe them as tool results
+ * either. Progress therefore arrives from the ingestion layer, which is the one
+ * component that holds an accepted child report (design D3).
  *
- * Progress is display-only: it never gates anything, and a session with no
- * reports appends nothing.
+ * This module only folds those accepted updates into one row per agent+phase
+ * and appends a `progress` flow entry whose renderer draws the board.
+ *
+ * Progress is display-only: it never gates anything, it never completes a task,
+ * and a session with no reports appends nothing.
  */
-import type {
-  ExtensionAPI,
-  ExtensionContext,
-  ExtensionHandler,
-  ToolResultEvent,
-  ToolResultEventResult,
-} from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 import { appendFlowEntry, OPSX_ENTRY_TYPES } from "./flow-entries.ts";
 import {
   progressUpdateFrom,
   projectProgress,
-  type ProgressUpdate,
+  type ProjectedProgress,
 } from "./progress-projection.ts";
 
-/** The report tools that can carry a structured progress field. */
-const REPORT_TOOL_NAMES = [
-  "report_gap_analysis",
-  "report_plan_review",
-  "report_work",
-] as const;
+/**
+ * The projected board per session.
+ *
+ * Only the folded rows are retained — one per agent+phase — so a chatty
+ * subagent cannot grow the parent's memory without bound (design D4).
+ */
+const boardsBySession = new Map<string, ProjectedProgress[]>();
 
-const updatesBySession = new Map<string, ProgressUpdate[]>();
+/** Reset the per-session progress board. Test-only. */
+export function resetProgressObserverForTests(): void {
+  boardsBySession.clear();
+}
 
-function sessionKey(ctx: ExtensionContext): string {
-  try {
-    return ctx.sessionManager?.getSessionId() ?? "unknown";
-  } catch {
-    return "unknown";
-  }
+/** The current board for a session. Test-observable. */
+export function progressBoardFor(sessionId: string): ProjectedProgress[] {
+  return boardsBySession.get(sessionId) ?? [];
 }
 
 /**
- * Build the `tool_result` handler that folds report-tool progress into the
- * session's board. Returns a value only when a board entry was appended.
+ * Record the structured progress carried by an accepted child report.
+ *
+ * Returns whether a board entry was appended. A report without progress leaves
+ * the board untouched, and a repeated update folds into the existing row rather
+ * than appending a second entry, so duplicates never reach the interface.
+ *
+ * The caller is the ingestion layer, which only ever passes a report that
+ * already reached a successful terminal state with a matching attempt nonce —
+ * so a failed run or a stale nonce is never projected.
  */
-export function createProgressObserverHandler(
+export function recordChildReportProgress(
   pi: Pick<ExtensionAPI, "appendEntry">,
-): ExtensionHandler<ToolResultEvent, ToolResultEventResult> {
-  return (event, ctx) => {
-    if (
-      !(REPORT_TOOL_NAMES as readonly string[]).includes(event.toolName) ||
-      event.isError
-    ) {
-      return;
-    }
-    const update = progressUpdateFrom(event.toolName, event.input);
-    if (!update) return;
+  sessionId: string,
+  input: { toolName: string; report: Record<string, unknown> },
+): boolean {
+  const update = progressUpdateFrom(input.toolName, input.report);
+  if (!update) return false;
 
-    const sessionId = sessionKey(ctx);
-    const updates = updatesBySession.get(sessionId) ?? [];
-    updates.push(update);
-    updatesBySession.set(sessionId, updates);
-
-    appendFlowEntry(pi, OPSX_ENTRY_TYPES.progress, {
-      rows: projectProgress(updates),
-    });
-  };
-}
+  const current = boardsBySession.get(sessionId) ?? [];
+  const next = projectProgress([...current, update]);
+  const changed = JSON.stringify(next) !== JSON.stringify(current);
+  boardsBySession.set(sessionId, next);
+  if (!changed) return false;
 
-export function registerProgressObserver(pi: ExtensionAPI): void {
-  pi.on("tool_result", createProgressObserverHandler(pi));
+  appendFlowEntry(pi, OPSX_ENTRY_TYPES.progress, { rows: next });
+  return true;
 }

package/src/report-tools.ts

@@ -23,7 +23,7 @@
  * number of times; projection of the calls is a later concern.
  */
 import { Type } from "@earendil-works/pi-ai";
-import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { defineTool } from "@earendil-works/pi-coding-agent";
 
 export const REPORT_GAP_ANALYSIS_TOOL_NAME = "report_gap_analysis";
 export const REPORT_PLAN_REVIEW_TOOL_NAME = "report_plan_review";
@@ -304,14 +304,15 @@ export const reportWorkTool = defineTool({
   },
 });
 
-/** The three reporting tools, in registration order. */
+/**
+ * The three reporting tools, in registration order.
+ *
+ * These are pure definitions: nothing here registers them into a session.
+ * Each role's child-only extension (design D1,
+ * `src/child-report-extensions/<role>.ts`) wraps exactly one of them with the
+ * attempt metadata envelope and registers that. The main session registers
+ * none of them (design D1, spec "结构化裁决上报").
+ */
 export function createReportTools() {
   return [reportGapAnalysisTool, reportPlanReviewTool, reportWorkTool];
 }
-
-/** Register the three reporting tools into the running pi process. */
-export function registerReportTools(pi: ExtensionAPI): void {
-  for (const tool of createReportTools()) {
-    pi.registerTool(tool);
-  }
-}

package/src/worker-dispatch.ts

@@ -62,7 +62,7 @@ function normalize(filePath: string): string {
 
 /**
  * Decide whether a task may be ticked. Holds (never ticks) when:
- * - no report was submitted;
+ * - no accepted worker report was recorded;
  * - the report claims files the diff does not contain (phantom work);
  * - the diff contains files the report omitted (unclaimed work);
  * - the verification did not run or did not pass.
@@ -77,7 +77,7 @@ export function decideTaskTick(
       kind: "hold",
       taskId,
       reason:
-        "No report_work was submitted; review the dispatch output before ticking.",
+        "No accepted worker report was recorded for this dispatch; let the worker run to completion, then tick.",
     };
   }