@xzzpig/pi-openspec-x 0.1.0 → 0.2.1

package/src/dispatch-gate.ts

@@ -4,9 +4,14 @@
  *
  * `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.
+ * an `opsx-worker` dispatch and the tick — and the `tool_call` handler uses it
+ * to block an `update_goal_task` completion that has no accepted worker report
+ * behind it.
+ *
+ * The report itself is NOT the tracker's state any more. It arrives as the
+ * persisted ready receipt for the task (design D3/D7), because the report tool
+ * runs inside the child session and the parent never sees it as a tool result.
+ * The tracker keeps only what the gate needs for presence and stall detection.
  *
  * 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.
@@ -50,7 +55,6 @@ function looksFailed(result: string | undefined): boolean {
  */
 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
@@ -67,11 +71,12 @@ export class DispatchReviewTracker {
   }
 
   /**
-   * Remember the main agent's `report_work` review and attach its changed-file
-   * count to the most recent dispatch it can belong to.
+   * Attach an accepted worker report to the most recent dispatch it can belong
+   * to. Only the changed-file count is retained, for stall detection: the
+   * report itself is the gate's input, never the tracker's stored evidence
+   * (design D7).
    */
-  rememberReport(report: WorkReportLike): void {
-    this.reports.set(report.taskId, report);
+  noteReceipt(report: WorkReportLike): void {
     for (let index = this.records.length - 1; index >= 0; index -= 1) {
       const record = this.records[index]!;
       if (record.taskId !== undefined && record.taskId !== report.taskId) {
@@ -90,11 +95,6 @@ export class DispatchReviewTracker {
     }
   }
 
-  /** 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
@@ -123,7 +123,6 @@ export class DispatchReviewTracker {
 
   reset(): void {
     this.records.length = 0;
-    this.reports.clear();
   }
 }
 
@@ -161,7 +160,7 @@ function filterTaskDelta(paths: readonly string[]): string[] {
  * 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`;
+ * 2. the dispatch must have produced an accepted worker report;
  * 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
@@ -175,7 +174,15 @@ function filterTaskDelta(paths: readonly string[]): string[] {
  */
 export function evaluateTickGate(
   tracker: DispatchReviewTracker,
-  input: { taskId: string; observedChangedFiles?: string[] },
+  input: {
+    taskId: string;
+    /**
+     * The persisted ready receipt for this task, when one exists. It comes from
+     * the worker's own run, so the parent model never has to transcribe it.
+     */
+    receipt?: WorkReportLike | undefined;
+    observedChangedFiles?: string[];
+  },
 ): TickGateDecision {
   if (!tracker.dispatched(input.taskId)) {
     return {
@@ -184,11 +191,11 @@ export function evaluateTickGate(
     };
   }
 
-  const report = tracker.reportFor(input.taskId);
+  const report = input.receipt;
   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.`,
+      reason: `The dispatch for task ${input.taskId} has no accepted worker report yet. The report is recorded automatically from the worker's own run once that run finishes successfully; if the worker failed or reported nothing, re-dispatch it for this task.`,
     };
   }
 

package/src/goal-base.ts

@@ -33,6 +33,11 @@ import type { GoalTaskLike } from "./task-sync.ts";
 /** The goal-x context shape `goalStorageRoot` accepts. */
 export interface GoalStorageContextLike {
   cwd: string;
+  /**
+   * Pre-resolved storage root. goal-x returns it verbatim (no settings I/O, no
+   * directory creation), which is what the read-only focus facet passes.
+   */
+  goalStorageRoot?: string;
   sessionManager?: { getSessionId(): string | undefined };
 }
 
@@ -244,6 +249,395 @@ export async function readGoalTaskTree(
   return undefined;
 }
 
+/**
+ * goal-x custom entry types the focus facet reads (design D6).
+ *
+ * A goal's *focus* is a session-level fact carried by a `pi-goal-focus` entry
+ * on the current branch — the active-goal summaries cannot answer it, which is
+ * why this facet exists instead of reusing `readGoalBaseSummaries`.
+ */
+export const GOAL_FOCUS_ENTRY_TYPE = "pi-goal-focus";
+export const GOAL_STATE_ENTRY_TYPE = "pi-goal-state";
+
+/** The goal record fields this facet consumes (goal-x owns the real shape). */
+export interface GoalRecordLike {
+  id: string;
+  status: string;
+  objective: string;
+  updatedAt?: string;
+  activePath?: string;
+  taskList?: { tasks?: GoalTaskLike[] } | undefined;
+  [key: string]: unknown;
+}
+
+/** One persisted focus entry (goal-x's `GoalFocusEntry`). */
+export interface GoalFocusEntryLike {
+  version: 1;
+  storageRoot?: string;
+  focusedGoalId: string | null;
+  reason: string;
+}
+
+/**
+ * The slice of goal-x's published helpers this facet needs. Everything is
+ * resolved through goal-x's own modules so the plugin can never drift from the
+ * on-disk format; the live `GoalCore` is deliberately never obtained.
+ *
+ * "Read-only" here means the goal/focus/task domain state is unchanged. The
+ * helpers do maintain their own caches and derived pool snapshots, which is
+ * allowed (design D6); this package must not create such maintenance itself or
+ * write goal files, the goal ledger, focus entries or tasks.
+ */
+export interface GoalXFocusFacet {
+  goalStorageRoot(ctx: GoalStorageContextLike): string;
+  parseGoalFile(filePath: string): GoalRecordLike | null;
+  readActiveGoalPoolAsync(
+    ctx: GoalStorageContextLike,
+  ): Promise<Map<string, GoalRecordLike>>;
+  normalizeGoalFocusEntry(value: unknown): GoalFocusEntryLike | null;
+  normalizeGoalRecord(value: unknown): GoalRecordLike | null;
+  resolveSessionFocus(args: {
+    pool: Map<string, GoalRecordLike>;
+    focusEntry?: GoalFocusEntryLike | null;
+    legacyGoal?: GoalRecordLike | null;
+    autoSelectSingleGoal?: boolean;
+  }): string | null;
+  loadGoalSettings(cwd: string): { autoSelectSingleGoal?: boolean };
+}
+
+/** Injectable dynamic-import seam; tests supply a fake focus facet. */
+export type GoalXFocusLoader = () => Promise<GoalXFocusFacet>;
+
+const GOAL_RECORD_MODULE: string =
+  "@xzzpig/pi-goal-x/extensions/goal-record.ts";
+const GOAL_POOL_MODULE: string = "@xzzpig/pi-goal-x/extensions/goal-pool.ts";
+const GOAL_SETTINGS_MODULE: string =
+  "@xzzpig/pi-goal-x/extensions/goal-settings.ts";
+
+async function defaultGoalXFocusLoader(): Promise<GoalXFocusFacet> {
+  const rootModule = (await import(GOAL_ROOT_MODULE)) as {
+    goalStorageRoot: GoalXFocusFacet["goalStorageRoot"];
+  };
+  const filesModule = (await import(GOAL_FILES_MODULE)) as {
+    parseGoalFile: GoalXFocusFacet["parseGoalFile"];
+    readActiveGoalPoolAsync: GoalXFocusFacet["readActiveGoalPoolAsync"];
+  };
+  const recordModule = (await import(GOAL_RECORD_MODULE)) as {
+    normalizeGoalFocusEntry: GoalXFocusFacet["normalizeGoalFocusEntry"];
+    normalizeGoalRecord: GoalXFocusFacet["normalizeGoalRecord"];
+  };
+  const poolModule = (await import(GOAL_POOL_MODULE)) as {
+    resolveSessionFocus: GoalXFocusFacet["resolveSessionFocus"];
+  };
+  const settingsModule = (await import(GOAL_SETTINGS_MODULE)) as {
+    loadGoalSettings: GoalXFocusFacet["loadGoalSettings"];
+  };
+  return {
+    goalStorageRoot: rootModule.goalStorageRoot,
+    parseGoalFile: filesModule.parseGoalFile,
+    readActiveGoalPoolAsync: filesModule.readActiveGoalPoolAsync,
+    normalizeGoalFocusEntry: recordModule.normalizeGoalFocusEntry,
+    normalizeGoalRecord: recordModule.normalizeGoalRecord,
+    resolveSessionFocus: poolModule.resolveSessionFocus,
+    loadGoalSettings: settingsModule.loadGoalSettings,
+  };
+}
+
+/** Generation token: re-reading after any of these change invalidates a decision. */
+export interface GoalFocusToken {
+  sessionId: string | null;
+  branchGeneration: string | null;
+  storageRoot: string | null;
+  focusEntryId: string | null;
+  goalId: string | null;
+}
+
+/** One real goal tool result observed on this branch (v3 details). */
+export interface RecentGoalToolRecord {
+  goalId: string;
+  record: GoalRecordLike;
+  observedAt: string;
+  toolCallId: string;
+}
+
+/** The authoritative answer to "which goal is focused, and what is its state". */
+export interface FocusedGoalSnapshot {
+  state: "known-focused" | "known-unfocused" | "unknown";
+  goalId?: string;
+  record?: GoalRecordLike;
+  activePath?: string;
+  token: GoalFocusToken;
+  reason?: string;
+}
+
+/** Session shape this facet reads (a read-only subset of the host manager). */
+export interface FocusSessionLike {
+  getSessionId(): string | undefined;
+  getBranch(): readonly unknown[];
+  getLeafId(): string | null;
+}
+
+export interface FocusReadContext extends GoalStorageContextLike {
+  sessionManager?: FocusSessionLike;
+}
+
+function tokenOf(
+  ctx: FocusReadContext,
+  storageRoot: string | null,
+  focusEntryId: string | null,
+  goalId: string | null,
+): GoalFocusToken {
+  return {
+    sessionId: ctx.sessionManager?.getSessionId() ?? null,
+    branchGeneration: ctx.sessionManager?.getLeafId() ?? null,
+    storageRoot,
+    focusEntryId,
+    goalId,
+  };
+}
+
+function unknownSnapshot(
+  ctx: FocusReadContext,
+  reason: string,
+  storageRoot: string | null = null,
+): FocusedGoalSnapshot {
+  return {
+    state: "unknown",
+    token: tokenOf(ctx, storageRoot, null, null),
+    reason,
+  };
+}
+
+/**
+ * Resolve a goal's recorded `activePath` to a real file path under the
+ * configured storage root. goal-x records the logical `.pi/goals/<file>` form,
+ * so a bare absolute parse would miss the file. Paths that escape the root are
+ * refused rather than followed.
+ */
+function resolveActivePath(
+  storageRoot: string,
+  activePath: string,
+): string | undefined {
+  if (path.isAbsolute(activePath)) {
+    return isPathWithinRootSync(activePath, storageRoot)
+      ? activePath
+      : undefined;
+  }
+  const logical = activePath.replace(/\\/g, "/");
+  const suffix = logical.startsWith(".pi/goals/")
+    ? logical.slice(".pi/goals/".length)
+    : logical;
+  const resolved = path.resolve(storageRoot, suffix);
+  return isPathWithinRootSync(resolved, storageRoot) ? resolved : undefined;
+}
+
+function isPathWithinRootSync(child: string, root: string): boolean {
+  const relative = path.relative(root, child);
+  return (
+    relative === "" ||
+    (!relative.startsWith("..") && !path.isAbsolute(relative))
+  );
+}
+
+/**
+ * The record with the newest `updatedAt`; on a tie the branch's newer real tool
+ * result wins, because it covers task changes the file has not flushed yet.
+ */
+function mergeGoalRecords(
+  fileRecord: GoalRecordLike | null,
+  toolRecord: RecentGoalToolRecord | undefined,
+): GoalRecordLike | null {
+  if (!toolRecord) return fileRecord;
+  if (!fileRecord) return toolRecord.record;
+  if (toolRecord.goalId !== fileRecord.id) return fileRecord;
+  const fileAt = fileRecord.updatedAt ?? "";
+  const toolAt = toolRecord.record.updatedAt ?? "";
+  return toolAt >= fileAt ? toolRecord.record : fileRecord;
+}
+
+/**
+ * Read the authoritative focus snapshot (design D6).
+ *
+ * Mirrors `goal-state.ts::loadState`: the latest valid focus entry and legacy
+ * state entry on the current branch, a storage-root check against the
+ * configured root, and single-goal auto-selection only when the setting is
+ * explicitly true. An explicit `null` focus never falls back to another goal.
+ *
+ * Returns `unknown` — never a guess — when the capability is missing, the
+ * format is unrecognized, or the record cannot be read.
+ */
+export async function readFocusedGoalSnapshot(
+  ctx: FocusReadContext,
+  options: {
+    loader?: GoalXFocusLoader;
+    recentToolRecord?: RecentGoalToolRecord | undefined;
+  } = {},
+): Promise<FocusedGoalSnapshot> {
+  const loader = options.loader ?? defaultGoalXFocusLoader;
+  let facet: GoalXFocusFacet;
+  try {
+    facet = await loader();
+  } catch (error) {
+    return unknownSnapshot(
+      ctx,
+      `goal-x focus support is unavailable: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+
+  let storageRoot: string;
+  try {
+    storageRoot = facet.goalStorageRoot(ctx);
+  } catch (error) {
+    return unknownSnapshot(
+      ctx,
+      `the goal storage root could not be resolved: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+
+  // Latest valid focus entry and legacy state entry on the current branch.
+  let focusEntryId: string | null = null;
+  let focusEntry: GoalFocusEntryLike | null = null;
+  let legacyGoal: GoalRecordLike | null = null;
+  let legacySeen = false;
+  const branch = ctx.sessionManager?.getBranch() ?? [];
+  for (let index = branch.length - 1; index >= 0; index -= 1) {
+    const entry = branch[index] as {
+      type?: string;
+      id?: string;
+      customType?: string;
+      data?: unknown;
+    };
+    if (!entry || entry.type !== "custom") continue;
+    if (!focusEntry && entry.customType === GOAL_FOCUS_ENTRY_TYPE) {
+      const normalized = facet.normalizeGoalFocusEntry(entry.data);
+      if (normalized) {
+        focusEntry = normalized;
+        focusEntryId = typeof entry.id === "string" ? entry.id : null;
+      }
+    }
+    if (!legacySeen && entry.customType === GOAL_STATE_ENTRY_TYPE) {
+      const data = entry.data as { goal?: unknown } | undefined;
+      legacyGoal = facet.normalizeGoalRecord(data?.goal);
+      legacySeen = true;
+    }
+    if (focusEntry && legacySeen) break;
+  }
+
+  const defaultRoot = path.resolve(ctx.cwd, ".pi/goals");
+  if (focusEntry && (focusEntry.storageRoot ?? defaultRoot) !== storageRoot) {
+    // A focus entry recorded against a different storage root never applies
+    // here; it does not silently re-target another goal either.
+    focusEntry = { ...focusEntry, focusedGoalId: null };
+    legacyGoal = null;
+  }
+  if (storageRoot !== defaultRoot) legacyGoal = null;
+
+  let pool: Map<string, GoalRecordLike>;
+  try {
+    pool = await facet.readActiveGoalPoolAsync(ctx);
+  } catch (error) {
+    return unknownSnapshot(
+      ctx,
+      `the active goal pool could not be read: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+      storageRoot,
+    );
+  }
+
+  let autoSelectSingleGoal = false;
+  try {
+    autoSelectSingleGoal =
+      facet.loadGoalSettings(ctx.cwd).autoSelectSingleGoal === true;
+  } catch {
+    // A settings failure must not widen the search; keep the strict default.
+    autoSelectSingleGoal = false;
+  }
+
+  let goalId: string | null;
+  try {
+    goalId = facet.resolveSessionFocus({
+      pool,
+      focusEntry,
+      legacyGoal,
+      autoSelectSingleGoal,
+    });
+  } catch (error) {
+    return unknownSnapshot(
+      ctx,
+      `the focused goal could not be resolved: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+      storageRoot,
+    );
+  }
+
+  if (!goalId) {
+    return {
+      state: "known-unfocused",
+      token: tokenOf(ctx, storageRoot, focusEntryId, null),
+    };
+  }
+
+  // The record itself comes from the canonical goal file, located by the known
+  // path — not from a summary and not by scanning the directory.
+  const poolRecord = pool.get(goalId) ?? null;
+  let fileRecord: GoalRecordLike | null = poolRecord;
+  let canonicalPath: string | undefined;
+  if (poolRecord?.activePath) {
+    canonicalPath = resolveActivePath(storageRoot, poolRecord.activePath);
+  }
+  if (canonicalPath) {
+    try {
+      fileRecord = facet.parseGoalFile(canonicalPath) ?? poolRecord;
+    } catch {
+      fileRecord = poolRecord;
+    }
+  }
+  const record = mergeGoalRecords(fileRecord, options.recentToolRecord);
+  if (!record) {
+    return unknownSnapshot(
+      ctx,
+      `the focused goal ${goalId} has no readable record`,
+      storageRoot,
+    );
+  }
+
+  const activePath = canonicalPath ?? record.activePath;
+  return {
+    state: "known-focused",
+    goalId,
+    record,
+    ...(activePath ? { activePath } : {}),
+    token: tokenOf(ctx, storageRoot, focusEntryId, goalId),
+  };
+}
+
+/**
+ * Refresh one focused goal's record by its known path, without scanning the
+ * storage root. `undefined` means the record is no longer readable, which the
+ * caller must treat as "cannot prove the state" rather than "unchanged".
+ */
+export function refreshGoalRecordByPath(
+  activePath: string,
+  loader: GoalXFocusLoader = defaultGoalXFocusLoader,
+): Promise<GoalRecordLike | undefined> {
+  return loader().then(
+    (facet) => {
+      try {
+        return facet.parseGoalFile(activePath) ?? undefined;
+      } catch {
+        return undefined;
+      }
+    },
+    () => undefined,
+  );
+}
+
 export interface RecoveryHandlerDeps {
   /** Injectable storage loader (tests); defaults to the real goal-x storage. */
   loadGoalXStorage?: GoalXStorageLoader;