pi-long-task 0.3.17 → 0.5.0

package/src/plan_revision_generation.ts

@@ -0,0 +1,376 @@
+import type { PlanRevisionResult, PlanTaskState, ReconciledPlanTask } from "./plan_revision.ts";
+import { reconcilePlanRevision } from "./plan_revision.ts";
+import { parseTasks, type Task } from "./todo_parser.ts";
+import { extractAndValidateTodoMarkdown, validateTodoMarkdown } from "./todo_generator.ts";
+
+export interface PlanRevisionRelevantResult {
+  /** Task ID in the current (pre-revision) plan. */
+  taskId: string;
+  status: string;
+  summary: string;
+  outputReferences?: readonly string[];
+}
+
+export interface PlanRevisionActiveTaskContext {
+  taskId: string;
+  title: string;
+  attempt?: number;
+  startedAt?: string;
+  activity?: string;
+}
+
+export interface PlanRevisionRequest {
+  revisionId: string;
+  guidance: string;
+  currentTodoMarkdown: string;
+  taskStates: Readonly<Record<string, PlanTaskState>>;
+  relevantResults: readonly PlanRevisionRelevantResult[];
+  activeTask?: PlanRevisionActiveTaskContext;
+  invalidatedTaskIds: readonly string[];
+}
+
+export interface PlanRevisionPlannerInput {
+  /** Ready-to-send planner prompt containing the complete revision context. */
+  prompt: string;
+  /** Structured form of the same context for planner adapters that do not consume a text prompt. */
+  request: Readonly<PlanRevisionRequest>;
+}
+
+export type PlanRevisionPlanner = (input: PlanRevisionPlannerInput) => Promise<string>;
+
+export interface PreservedPlanRevisionResult {
+  previousTaskId: string;
+  identity: string;
+  retainedAs: "active" | "history";
+  result: PlanRevisionRelevantResult;
+}
+
+export interface GeneratedPlanRevision {
+  revisionId: string;
+  guidance: string;
+  /** Valid planner proposal before coordinator-owned state is applied. */
+  proposalMarkdown: string;
+  /** Complete, valid TODO markdown with reconciled task identity and completion state. */
+  todoMarkdown: string;
+  reconciliation: PlanRevisionResult;
+  preservedResults: PreservedPlanRevisionResult[];
+}
+
+export interface GeneratePlanRevisionOptions {
+  currentTodoMarkdown: string;
+  guidance: string;
+  revisionId: string;
+  planner: PlanRevisionPlanner;
+  taskStates?: Readonly<Record<string, PlanTaskState>>;
+  relevantResults?: readonly PlanRevisionRelevantResult[];
+  activeTask?: PlanRevisionActiveTaskContext;
+  invalidatedTaskIds?: readonly string[];
+}
+
+/**
+ * A failed revision is recoverable: callers must keep priorTodoMarkdown as the
+ * authoritative plan and may retry the same queued guidance.
+ */
+export class PlanRevisionGenerationError extends Error {
+  readonly recoverable = true;
+  readonly priorTodoMarkdown: string;
+  readonly revisionId: string;
+
+  constructor(message: string, options: { priorTodoMarkdown: string; revisionId: string; cause?: unknown }) {
+    super(message, { cause: options.cause });
+    this.name = "PlanRevisionGenerationError";
+    this.priorTodoMarkdown = options.priorTodoMarkdown;
+    this.revisionId = options.revisionId;
+  }
+}
+
+/**
+ * Requests a complete revised plan, validates it, and reconciles it without
+ * mutating or persisting the current plan. A caller should replace its active
+ * snapshot only after this function resolves.
+ */
+export async function generatePlanRevision(options: GeneratePlanRevisionOptions): Promise<GeneratedPlanRevision> {
+  const priorTodoMarkdown = options.currentTodoMarkdown;
+  const revisionId = options.revisionId.trim();
+  const guidance = options.guidance.trim();
+
+  try {
+    if (!revisionId) {
+      throw new Error("A plan revision requires a non-empty revisionId.");
+    }
+    if (!guidance) {
+      throw new Error("Plan revision guidance must not be empty.");
+    }
+
+    validateTodoMarkdown(priorTodoMarkdown);
+    const previousTasks = parseTasks(priorTodoMarkdown);
+    const taskStates = effectiveTaskStates(previousTasks, options.taskStates, options.activeTask);
+    const request: PlanRevisionRequest = {
+      revisionId,
+      guidance,
+      currentTodoMarkdown: priorTodoMarkdown,
+      taskStates,
+      relevantResults: (options.relevantResults ?? []).map(copyRelevantResult),
+      activeTask: options.activeTask ? { ...options.activeTask } : undefined,
+      invalidatedTaskIds: [...(options.invalidatedTaskIds ?? [])],
+    };
+    const prompt = buildPlanRevisionPrompt(request);
+    const rawProposal = await options.planner({ prompt, request });
+    const proposalMarkdown = extractAndValidateTodoMarkdown(rawProposal);
+    // Keep this explicit even though extraction validates. It guards future
+    // extractor changes before any accepted state can be returned.
+    validateTodoMarkdown(proposalMarkdown);
+    const revisedTasks = parseTasks(proposalMarkdown);
+    const reconciliation = reconcilePlanRevision(previousTasks, revisedTasks, {
+      previousStates: taskStates,
+      runningTaskId: options.activeTask?.taskId,
+      invalidatedTaskIds: request.invalidatedTaskIds,
+      revisionId,
+    });
+    const todoMarkdown = renderReconciledTodoMarkdown(proposalMarkdown, reconciliation.activeTasks);
+    validateTodoMarkdown(todoMarkdown);
+    const renderedTasks = parseTasks(todoMarkdown);
+    const renderedReconciliation = reconciliationWithRenderedTasks(reconciliation, renderedTasks);
+
+    return {
+      revisionId,
+      guidance,
+      proposalMarkdown,
+      todoMarkdown,
+      reconciliation: renderedReconciliation,
+      preservedResults: preservedRevisionResults(previousTasks, renderedReconciliation, request.relevantResults),
+    };
+  } catch (error) {
+    if (error instanceof PlanRevisionGenerationError) {
+      throw error;
+    }
+    throw new PlanRevisionGenerationError(
+      `Plan revision ${revisionId || "<unknown>"} was not accepted: ${errorMessage(error)}`,
+      {
+        priorTodoMarkdown,
+        revisionId,
+        cause: error,
+      },
+    );
+  }
+}
+
+/** Builds the complete planner context required to place steering guidance. */
+export function buildPlanRevisionPrompt(request: Readonly<PlanRevisionRequest>): string {
+  const taskContext = parseTasks(request.currentTodoMarkdown).map((task) => ({
+    taskId: task.taskId,
+    stableId: task.stableId,
+    title: task.title,
+    state: request.taskStates[task.taskId] ?? (task.done ? "completed" : "pending"),
+  }));
+  const activeTask = request.activeTask ?? null;
+
+  return `Revise an active Pi Long Task TODO plan using new steering guidance.
+
+Return one complete, valid revised plan. Output only markdown, without commentary or a code fence.
+
+Required format and revision rules:
+- Start with exactly \`# Pi Long Task TODO\`.
+- Include a \`## Progress\` section with exactly one \`- [ ] TODO N — Title\` or \`- [x] TODO N — Title\` line per task.
+- Include a \`---\` separator, then sequential \`## TODO N — Title\` sections.
+- Every task must include \`**Goal:**\`, \`**Status:**\` with checkbox items, \`**Verify:**\`, and \`**Done when:**\`.
+- Apply the guidance where it belongs and revise only affected plan content. Preserve unrelated tasks and global constraints.
+- Preserve the relative order of unaffected tasks unless the guidance requests a reorder.
+- Preserve each \`<!-- pi-long-task-id: ... -->\` marker on equivalent existing work. New tasks may omit the marker.
+- Do not use checkbox changes to discard coordinator-owned status. The coordinator will reconcile status after validation.
+- Never silently rewrite or erase completed history. If guidance corrects completed work, retain its valid result and express the new requirement as explicit follow-up work.
+- Return the full plan, not a patch, diff, explanation, or partial task section.
+
+Revision ID: ${oneLine(request.revisionId)}
+
+Coordinator-owned task state:
+
+${markdownFence(JSON.stringify(taskContext, null, 2), "json")}
+
+Active-task context:
+
+${markdownFence(JSON.stringify(activeTask, null, 2), "json")}
+
+Relevant completed/attempt results and output references:
+
+${markdownFence(JSON.stringify(request.relevantResults, null, 2), "json")}
+
+Explicitly invalidated current task IDs:
+
+${markdownFence(JSON.stringify(request.invalidatedTaskIds), "json")}
+
+New steering guidance:
+
+${markdownFence(request.guidance, "text")}
+
+Current complete TODO plan:
+
+${markdownFence(request.currentTodoMarkdown, "markdown")}
+`;
+}
+
+/**
+ * Produces a normal Pi Long Task TODO document from reconciled active items.
+ * Persistence and atomic replacement are intentionally left to the caller.
+ */
+export function renderReconciledTodoMarkdown(
+  proposedMarkdown: string,
+  activeTasks: readonly ReconciledPlanTask[],
+): string {
+  if (activeTasks.length === 0) {
+    throw new Error("A revised TODO plan must retain at least one active or historical-completion task.");
+  }
+
+  const normalized = proposedMarkdown.replace(/\r\n?/g, "\n");
+  const lines = normalized.split("\n");
+  const progressIndex = lines.findIndex((line) => /^##\s+Progress\s*$/i.test(line.trim()));
+  if (progressIndex < 0) {
+    throw new Error("The revised TODO plan is missing its Progress section.");
+  }
+  const prefix = lines.slice(0, progressIndex).join("\n").trimEnd();
+  const progress = activeTasks
+    .map((item, index) => `- [${item.state === "completed" ? "x" : " "}] TODO ${index + 1} — ${item.task.title}`)
+    .join("\n");
+  const sections = activeTasks
+    .map((item, index) => renumberTaskSection(item.task.section, index + 1, item.task.title))
+    .join("\n\n");
+  const rendered = `${prefix}\n\n## Progress\n\n${progress}\n\n---\n\n${sections.trimEnd()}\n`;
+  validateTodoMarkdown(rendered);
+  return rendered;
+}
+
+function effectiveTaskStates(
+  tasks: readonly Task[],
+  supplied: Readonly<Record<string, PlanTaskState>> | undefined,
+  activeTask: PlanRevisionActiveTaskContext | undefined,
+): Readonly<Record<string, PlanTaskState>> {
+  const knownIds = new Set(tasks.map((task) => task.taskId));
+  for (const taskId of Object.keys(supplied ?? {})) {
+    if (!knownIds.has(taskId)) {
+      throw new Error(`Task state refers to unknown current TODO ${taskId}.`);
+    }
+  }
+  if (activeTask && !knownIds.has(activeTask.taskId)) {
+    throw new Error(`Active task TODO ${activeTask.taskId} is not present in the current plan.`);
+  }
+
+  return Object.fromEntries(
+    tasks.map((task) => {
+      const state = task.done
+        ? "completed"
+        : activeTask?.taskId === task.taskId
+          ? "running"
+          : (supplied?.[task.taskId] ?? "pending");
+      return [task.taskId, state];
+    }),
+  );
+}
+
+function reconciliationWithRenderedTasks(
+  reconciliation: PlanRevisionResult,
+  renderedTasks: readonly Task[],
+): PlanRevisionResult {
+  if (renderedTasks.length !== reconciliation.activeTasks.length) {
+    throw new Error("Rendered revised plan task count does not match reconciliation output.");
+  }
+  return {
+    ...reconciliation,
+    activeTasks: reconciliation.activeTasks.map((item, index) => ({
+      ...item,
+      task: renderedTasks[index],
+    })),
+  };
+}
+
+function preservedRevisionResults(
+  previousTasks: readonly Task[],
+  reconciliation: PlanRevisionResult,
+  results: readonly PlanRevisionRelevantResult[],
+): PreservedPlanRevisionResult[] {
+  const previousByTaskId = new Map(previousTasks.map((task) => [task.taskId, task]));
+  const activeByPreviousTaskId = new Map(
+    reconciliation.activeTasks
+      .filter((item) => item.previousTaskId && item.preserveOutputs)
+      .map((item) => [item.previousTaskId as string, item]),
+  );
+  const retiredByPreviousTaskId = new Map(
+    reconciliation.retiredTasks
+      .filter((item) => item.preserveOutputs)
+      .map((item) => {
+        const task = previousTasks.find(
+          (candidate) => candidate.stableId === item.identity || candidate.taskId === item.task.taskId,
+        );
+        return task ? [task.taskId, item] : undefined;
+      })
+      .filter((entry): entry is [string, PlanRevisionResult["retiredTasks"][number]] => Boolean(entry)),
+  );
+
+  const preserved: PreservedPlanRevisionResult[] = [];
+  for (const result of results) {
+    if (!previousByTaskId.has(result.taskId)) {
+      throw new Error(`Relevant result refers to unknown current TODO ${result.taskId}.`);
+    }
+    const active = activeByPreviousTaskId.get(result.taskId);
+    if (active) {
+      preserved.push({
+        previousTaskId: result.taskId,
+        identity: active.identity,
+        retainedAs: "active",
+        result: copyRelevantResult(result),
+      });
+      continue;
+    }
+    const retired = retiredByPreviousTaskId.get(result.taskId);
+    if (retired) {
+      preserved.push({
+        previousTaskId: result.taskId,
+        identity: retired.identity,
+        retainedAs: "history",
+        result: copyRelevantResult(result),
+      });
+    }
+  }
+  return preserved;
+}
+
+function copyRelevantResult(result: PlanRevisionRelevantResult): PlanRevisionRelevantResult {
+  return {
+    ...result,
+    outputReferences: result.outputReferences ? [...result.outputReferences] : undefined,
+  };
+}
+
+function renumberTaskSection(section: string, taskNumber: number, title: string): string {
+  const heading = `## TODO ${taskNumber} — ${title}`;
+  if (!/^##\s+TODO\s+\d+\s+[—-]\s+.+$/m.test(section)) {
+    throw new Error(`Cannot render revised task ${taskNumber}; its TODO heading is missing.`);
+  }
+  return section.replace(/^##\s+TODO\s+\d+\s+[—-]\s+.+$/m, heading).trimEnd();
+}
+
+function markdownFence(value: string, language: string): string {
+  const fence = "`".repeat(Math.max(3, longestBacktickRun(value) + 1));
+  return `${fence}${language}\n${value.trim()}\n${fence}`;
+}
+
+function longestBacktickRun(value: string): number {
+  let longest = 0;
+  let current = 0;
+  for (const character of value) {
+    if (character === "`") {
+      current += 1;
+      longest = Math.max(longest, current);
+    } else {
+      current = 0;
+    }
+  }
+  return longest;
+}
+
+function oneLine(value: string): string {
+  return value.replace(/\s+/g, " ").trim();
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/plan_store.ts

@@ -0,0 +1,281 @@
+import { createHash, randomUUID } from "node:crypto";
+import { readFile, rename, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { reconcilePlanRevision, taskSemanticFingerprint, type PlanTaskState } from "./plan_revision.ts";
+import { renderReconciledTodoMarkdown, type GeneratedPlanRevision } from "./plan_revision_generation.ts";
+import { markTaskDone, parseTasks, type Task } from "./todo_parser.ts";
+import { validateTodoMarkdown } from "./todo_generator.ts";
+
+export interface PersistedPlanSnapshot {
+  markdown: string;
+  /** Changes only when plan structure/content changes, not when checkboxes change. */
+  authorityToken: string;
+}
+
+export interface PlanTaskReference {
+  taskId: string;
+  stableId?: string;
+  semanticFingerprint: string;
+  authorityToken: string;
+}
+
+export interface ApplyPersistedPlanRevisionOptions {
+  expectedAuthorityToken: string;
+  taskStates?: Readonly<Record<string, PlanTaskState>>;
+  runningTask?: PlanTaskReference;
+  /** Runs while writes are serialized and before the authoritative file is replaced. */
+  beforeCommit?: (revision: GeneratedPlanRevision) => void | Promise<void>;
+}
+
+export interface ResolvePersistedTaskResult {
+  task?: Task;
+  stale: boolean;
+  snapshot: PersistedPlanSnapshot;
+}
+
+export interface CompletePersistedTaskResult extends ResolvePersistedTaskResult {
+  applied: boolean;
+}
+
+export class StalePlanRevisionError extends Error {
+  readonly recoverable = true;
+
+  constructor(message: string) {
+    super(message);
+    this.name = "StalePlanRevisionError";
+  }
+}
+
+/**
+ * Serialized, atomic persistence for the authoritative TODO document.
+ *
+ * Every mutation is derived from the latest in-memory snapshot and reaches disk
+ * through a same-directory temporary file + rename. Structural authority tokens
+ * let status-only writes rebase safely while rejecting planner output generated
+ * from an older accepted plan.
+ */
+export class PersistentTodoPlanStore {
+  readonly todoPath: string;
+  private markdown: string;
+  private authorityToken: string;
+  private writeTail: Promise<void> = Promise.resolve();
+
+  private constructor(todoPath: string, markdown: string) {
+    validateTodoMarkdown(markdown);
+    this.todoPath = todoPath;
+    this.markdown = markdown;
+    this.authorityToken = planAuthorityToken(markdown);
+  }
+
+  static async create(todoPath: string, markdown: string): Promise<PersistentTodoPlanStore> {
+    const store = new PersistentTodoPlanStore(todoPath, markdown);
+    await atomicWrite(todoPath, markdown);
+    return store;
+  }
+
+  /** Restores the exact rendered plan state from the authoritative TODO file. */
+  static async load(todoPath: string): Promise<PersistentTodoPlanStore> {
+    return new PersistentTodoPlanStore(todoPath, await readFile(todoPath, "utf8"));
+  }
+
+  /** Restores from content already read by a caller. */
+  static fromPersistedMarkdown(todoPath: string, markdown: string): PersistentTodoPlanStore {
+    return new PersistentTodoPlanStore(todoPath, markdown);
+  }
+
+  snapshot(): PersistedPlanSnapshot {
+    return { markdown: this.markdown, authorityToken: this.authorityToken };
+  }
+
+  async applyRevision(
+    revision: GeneratedPlanRevision,
+    options: ApplyPersistedPlanRevisionOptions,
+  ): Promise<GeneratedPlanRevision> {
+    return this.withWriteLock(async () => {
+      if (options.expectedAuthorityToken !== this.authorityToken) {
+        throw new StalePlanRevisionError(
+          `Plan revision ${revision.revisionId} was generated from a stale plan and cannot replace the latest revision.`,
+        );
+      }
+
+      const currentTasks = parseTasks(this.markdown);
+      const renderedTargetTasks = parseTasks(revision.todoMarkdown);
+      if (renderedTargetTasks.length !== revision.reconciliation.activeTasks.length) {
+        throw new Error("Persisted revision task count does not match its reconciliation state.");
+      }
+      const currentByTaskId = new Map(currentTasks.map((task) => [task.taskId, task]));
+      const targetTasks = renderedTargetTasks.map((task, index) => {
+        const item = revision.reconciliation.activeTasks[index];
+        const previous = item?.previousTaskId ? currentByTaskId.get(item.previousTaskId) : undefined;
+        const shouldMatchPrevious = previous && item.revisionKind !== "follow_up" && item.revisedTaskId !== undefined;
+        return shouldMatchPrevious ? taskWithStableId(task, previous.stableId) : task;
+      });
+      const runningTaskId = options.runningTask
+        ? resolvePlanTaskReference(currentTasks, options.runningTask, this.authorityToken)?.taskId
+        : undefined;
+      const taskStates = Object.fromEntries(
+        currentTasks.map((task) => [
+          task.taskId,
+          task.done ? "completed" : (options.taskStates?.[task.taskId] ?? "pending"),
+        ]),
+      ) as Record<string, PlanTaskState>;
+      const reconciliation = reconcilePlanRevision(currentTasks, targetTasks, {
+        previousStates: taskStates,
+        runningTaskId,
+        revisionId: revision.revisionId,
+      });
+      const todoMarkdown = renderReconciledTodoMarkdown(revision.todoMarkdown, reconciliation.activeTasks);
+      validateTodoMarkdown(todoMarkdown);
+      const renderedTasks = parseTasks(todoMarkdown);
+      const appliedRevision: GeneratedPlanRevision = {
+        ...revision,
+        todoMarkdown,
+        reconciliation: {
+          ...reconciliation,
+          activeTasks: reconciliation.activeTasks.map((item, index) => ({
+            ...item,
+            task: renderedTasks[index],
+          })),
+        },
+      };
+
+      await options.beforeCommit?.(appliedRevision);
+      await atomicWrite(this.todoPath, todoMarkdown);
+      this.markdown = todoMarkdown;
+      this.authorityToken = planAuthorityToken(todoMarkdown);
+      return appliedRevision;
+    });
+  }
+
+  /**
+   * Marks the equivalent task in the latest plan complete. If an accepted
+   * revision replaced that work, the stale worker update becomes a no-op.
+   */
+  async completeTask(reference: PlanTaskReference): Promise<CompletePersistedTaskResult> {
+    return this.withWriteLock(async () => {
+      const tasks = parseTasks(this.markdown);
+      const task = resolvePlanTaskReference(tasks, reference, this.authorityToken);
+      if (!task) {
+        return { applied: false, stale: true, snapshot: this.snapshot() };
+      }
+      if (task.done) {
+        return { applied: false, stale: false, task, snapshot: this.snapshot() };
+      }
+
+      const nextMarkdown = markTaskDone(this.markdown, task.taskId);
+      validateTodoMarkdown(nextMarkdown);
+      await atomicWrite(this.todoPath, nextMarkdown);
+      this.markdown = nextMarkdown;
+      // Completion updates only checkboxes, so the structural token normally
+      // remains unchanged. Recompute it to keep this invariant verified.
+      this.authorityToken = planAuthorityToken(nextMarkdown);
+      const snapshot = this.snapshot();
+      const completedTask = resolvePlanTaskReference(parseTasks(snapshot.markdown), reference, snapshot.authorityToken);
+      return { applied: true, stale: false, task: completedTask, snapshot };
+    });
+  }
+
+  /** Resolves an in-flight worker identity against the latest accepted plan. */
+  async resolveTask(reference: PlanTaskReference): Promise<ResolvePersistedTaskResult> {
+    return this.withWriteLock(async () => {
+      const snapshot = this.snapshot();
+      const task = resolvePlanTaskReference(parseTasks(snapshot.markdown), reference, snapshot.authorityToken);
+      return { task, stale: !task, snapshot };
+    });
+  }
+
+  private async withWriteLock<T>(operation: () => Promise<T>): Promise<T> {
+    const previous = this.writeTail;
+    let release: (() => void) | undefined;
+    this.writeTail = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    await previous;
+    try {
+      return await operation();
+    } finally {
+      release?.();
+    }
+  }
+}
+
+function taskWithStableId(task: Task, stableId: string | undefined): Task {
+  const markerPattern = /^[\t ]*<!--[\t ]*pi-long-task-id:.*-->[\t ]*(?:\r?\n)?/im;
+  const withoutMarker = task.section.replace(markerPattern, "");
+  if (!stableId) {
+    return { ...task, stableId: undefined, section: withoutMarker };
+  }
+  const headingEnd = withoutMarker.search(/\r?\n/);
+  const marker = `<!-- pi-long-task-id: ${stableId} -->`;
+  const section =
+    headingEnd < 0
+      ? `${withoutMarker}\n\n${marker}\n`
+      : `${withoutMarker.slice(0, headingEnd + 1)}\n${marker}\n${withoutMarker.slice(headingEnd + 1).replace(/^\n/, "")}`;
+  return { ...task, stableId, section };
+}
+
+export function planTaskReference(task: Task, authorityToken: string): PlanTaskReference {
+  return {
+    taskId: task.taskId,
+    stableId: task.stableId,
+    semanticFingerprint: taskSemanticFingerprint(task),
+    authorityToken,
+  };
+}
+
+/** Stable across checkbox-only task completion writes. */
+export function planAuthorityToken(markdown: string): string {
+  const normalized = markdown
+    .replace(/\r\n?/g, "\n")
+    .replace(/^(\s*-\s+\[)[ xX](\])/gm, "$1 $2")
+    .trimEnd();
+  // A deterministic content token avoids persisting a second source of truth.
+  return `plan:${createHash("sha256").update(normalized).digest("hex")}`;
+}
+
+export function resolvePlanTaskReference(
+  tasks: readonly Task[],
+  reference: PlanTaskReference,
+  currentAuthorityToken: string,
+): Task | undefined {
+  if (reference.stableId) {
+    const stableMatches = tasks.filter(
+      (task) => task.stableId === reference.stableId && taskSemanticFingerprint(task) === reference.semanticFingerprint,
+    );
+    if (stableMatches.length === 1) {
+      return stableMatches[0];
+    }
+    // Once a worker has a persisted identity, a newer revision must not let it
+    // fall through to semantically similar work under a different identity.
+    // Fingerprint fallback is reserved for legacy workers launched before IDs
+    // were first added to their plan.
+    if (reference.authorityToken !== currentAuthorityToken) {
+      return undefined;
+    }
+  }
+
+  const semanticMatches = tasks.filter((task) => taskSemanticFingerprint(task) === reference.semanticFingerprint);
+  if (semanticMatches.length === 1) {
+    return semanticMatches[0];
+  }
+
+  if (reference.authorityToken === currentAuthorityToken) {
+    return tasks.find((task) => task.taskId === reference.taskId);
+  }
+  return undefined;
+}
+
+async function atomicWrite(pathname: string, content: string): Promise<void> {
+  const temporaryPath = path.join(
+    path.dirname(pathname),
+    `.${path.basename(pathname)}.${process.pid}.${randomUUID()}.tmp`,
+  );
+  await writeFile(temporaryPath, content, "utf8");
+  try {
+    await rename(temporaryPath, pathname);
+  } catch (error) {
+    await unlink(temporaryPath).catch(() => undefined);
+    throw error;
+  }
+}

package/src/render.ts

@@ -462,6 +462,8 @@ function progressPhaseLabel(phase: string): string {
       return "Failed";
     case "task_blocked":
       return "Blocked";
+    case "task_obsolete":
+      return "Revised";
     case "complete":
       return "Complete";
     default: