pi-long-task 0.3.17 → 0.5.0

package/src/coordinator.ts

@@ -10,9 +10,34 @@ import type {
 } from "./types.ts";
 import { commitAfterSession, gitDirtyPaths, shouldCommitOutcome, type CommitAfterSessionResult } from "./git.ts";
 import { formatCoordinatorResultMessage } from "./render.ts";
-import { extractResultSummary } from "./result_writer.ts";
+import { extractResultSummary, hasCompleteTaskResult } from "./result_writer.ts";
 import { runGuardedSessionPrompt } from "./session_guard.ts";
+import {
+  generatePlanRevision,
+  PlanRevisionGenerationError,
+  type GeneratedPlanRevision,
+  type PlanRevisionRequest,
+  type PlanRevisionRelevantResult,
+} from "./plan_revision_generation.ts";
+import { taskSemanticFingerprint, type PlanTaskState } from "./plan_revision.ts";
+import {
+  PersistentTodoPlanStore,
+  planTaskReference,
+  resolvePlanTaskReference,
+  type PlanTaskReference,
+} from "./plan_store.ts";
+import type { SerializedSteeringQueue, SteeringMessage } from "./steering.ts";
 import { parseWorkerRuntimeConfig } from "./worker_config.ts";
+import {
+  classifyWorkerSessionRetry,
+  createWorkerSessionCompatibilityFingerprint,
+  decideWorkerSessionReuse,
+  DEFAULT_WORKER_SESSION_REUSE_CONTEXT_THRESHOLD_PERCENT,
+  DEFAULT_WORKER_SESSION_REUSE_ENABLED,
+  resolveWorkerSessionReuseConfig,
+  type WorkerSessionCompatibilityFingerprint,
+  type WorkerSessionHealth,
+} from "./worker_reuse_policy.ts";
 import { buildTaskProgressModel, type TaskProgressModel, type TaskProgressStatus } from "./task_progress.ts";
 import {
   applyGoalInstructionsToTodoMarkdown,
@@ -23,14 +48,23 @@ import {
   todoMarkdownFromString,
   validateTodoMarkdown,
 } from "./todo_generator.ts";
-import { markTaskDone, parseTasks, todoGlobalInstructions, type Task } from "./todo_parser.ts";
+import { parseTasks, todoGlobalInstructions, type Task } from "./todo_parser.ts";
 import {
+  buildWorkerSessionCreationFailureOutcome,
   createIsolatedWorkerSession,
+  createWorkerSessionResource,
+  DEFAULT_WORKER_TOOLS,
+  disposeWorkerSessionResource,
   runWorkerTask,
+  runWorkerTaskAssignment,
+  workerSessionContextUsagePercent,
   type RunWorkerTaskOptions,
   type SessionOutcome,
+  type WorkerSessionDiagnostic,
   type WorkerSessionFactory,
   type WorkerSessionLike,
+  type WorkerSessionResource,
+  type WorkerUsageTotals,
 } from "./worker_session.ts";
 
 export type { CoordinatorStatus } from "./types.ts";
@@ -43,6 +77,8 @@ export const DEFAULT_COORDINATOR_OPTIONS = {
   maxBashTimeoutMs: 300_000,
   taskThinking: "high",
   todoThinking: "xhigh",
+  workerSessionReuse: DEFAULT_WORKER_SESSION_REUSE_ENABLED,
+  workerSessionReuseContextThresholdPercent: DEFAULT_WORKER_SESSION_REUSE_CONTEXT_THRESHOLD_PERCENT,
 } as const;
 
 export type WorkerRunner = (options: RunWorkerTaskOptions) => Promise<SessionOutcome>;
@@ -50,10 +86,12 @@ export type CoordinatorProgressPhase =
   | "planning"
   | "planned"
   | "task_start"
+  | "worker_session"
   | "worker_tool"
   | "task_done"
   | "task_blocked"
   | "task_failed"
+  | "task_obsolete"
   | "complete";
 
 export type PlannerDiagnosticKind = "timeout" | "abort" | "invalid_output" | "repair_attempt" | "failure";
@@ -108,6 +146,10 @@ export interface CoordinatorProgressUpdate {
   plannerDiagnostics?: string[];
   plannerSessionFile?: string;
   plannerSessionId?: string;
+  workerSessionEvent?: WorkerSessionDiagnostic["event"];
+  workerSessionReason?: string;
+  workerSessionContextUsagePercent?: number;
+  workerSessionContextThresholdPercent?: number;
 }
 
 export type CoordinatorProgressHandler = (update: CoordinatorProgressUpdate) => void;
@@ -130,8 +172,16 @@ export interface RunCoordinatorOptions extends PiLongTaskInput {
   maxBashTimeoutMs?: number;
   taskThinking?: string;
   todoThinking?: string;
+  /** Set false to retain the legacy one-session-per-task lifecycle. */
+  workerSessionReuse?: boolean;
+  /** Rotate before another assignment when context usage reaches this percentage. */
+  workerSessionReuseContextThresholdPercent?: number;
   now?: () => Date;
   onProgress?: CoordinatorProgressHandler;
+  /** Run-scoped FIFO populated by the extension input handler during active execution. */
+  steeringQueue?: SerializedSteeringQueue;
+  /** Runs after rebase/validation and immediately before the revision is atomically persisted. */
+  onPlanRevisionAccepted?: (revision: GeneratedPlanRevision) => void | Promise<void>;
 }
 
 export interface TodoPlannerOptions {
@@ -146,11 +196,17 @@ export interface TodoPlannerOptions {
   sessionFactory?: WorkerSessionFactory;
   onDiagnostic?: PlannerDiagnosticHandler;
   goal?: string;
+  /** Exact prompt for revision planners; bypasses the initial TODO-creation wrapper. */
+  plannerPrompt?: string;
+  /** Structured revision context supplied alongside plannerPrompt. */
+  planRevision?: Readonly<PlanRevisionRequest>;
 }
 
 export interface TaskAttemptSummary {
   taskId: string;
   title: string;
+  taskStableId?: string;
+  taskFingerprint?: string;
   attempt: number;
   reportedStatus: string;
   done: boolean;
@@ -158,6 +214,18 @@ export interface TaskAttemptSummary {
   commitHash?: string;
   commitError?: string;
   commitSkipped?: string;
+  /** The worker finished after an accepted revision replaced or removed its task. */
+  obsolete?: boolean;
+  /** Retry continuity retained across task renumbering and accepted revisions. */
+  resultText?: string;
+}
+
+export interface WorkerSessionMetrics {
+  starts: number;
+  reuses: number;
+  rotations: number;
+  retained: number;
+  rotationReasons: Record<string, number>;
 }
 
 export interface CoordinatorResult {
@@ -180,6 +248,10 @@ export interface CoordinatorResult {
   attempts: TaskAttemptSummary[];
   taskProgress: TaskProgressModel;
   workerCostTotal: number;
+  /** Sum of task/attempt token deltas; omitted when statistics are unavailable. */
+  workerUsageTotal?: WorkerUsageTotals;
+  /** Additive lifecycle counters for adaptive worker-session reuse. */
+  workerSessionMetrics?: WorkerSessionMetrics;
   commit: boolean;
   goal?: string;
   error?: string;
@@ -206,9 +278,12 @@ interface RuntimeOptions {
   goal?: string;
   taskThinking: string;
   todoThinking: string;
+  workerSessionReuse: boolean;
+  workerSessionReuseContextThresholdPercent: number;
   todoTimeoutMs: number;
   todoGracefulShutdownMs: number;
   workerRunner: WorkerRunner;
+  useRetainedWorkerLifecycle: boolean;
   todoPlanner: TodoPlanner;
   abortSignal?: AbortSignal;
   workerSessionFactory?: WorkerSessionFactory;
@@ -220,10 +295,461 @@ interface RuntimeOptions {
   workerTextByWorker: Map<string, string>;
   workerTextPublishedLengthByWorker: Map<string, number>;
   plannerDiagnostics: PlannerDiagnostic[];
+  workerSessionMetrics: WorkerSessionMetrics;
+  steeringQueue?: SerializedSteeringQueue;
+  onPlanRevisionAccepted?: (revision: GeneratedPlanRevision) => void | Promise<void>;
+}
+
+type RetainedWorkerReuseScope = "sequential_task" | "partial_continuation";
+
+export interface WorkerAssignmentIdentity {
+  /** Unique invocation identity, even when a replacement reuses a task ID and attempt number. */
+  assignmentId: string;
+  /** Stable task identity or semantic fingerprint from the plan that launched this assignment. */
+  taskIdentity: string;
+  /** Accepted-steering generation at the assignment boundary. */
+  steeringGeneration: number;
+  /** Structural plan generation from which the assignment was selected. */
+  planAuthorityToken: string;
+}
+
+interface RetainedWorkerState {
+  resource: WorkerSessionResource;
+  compatibility: WorkerSessionCompatibilityFingerprint;
+  health: WorkerSessionHealth;
+  contextUsagePercent?: number;
+  previousTask: Pick<Task, "taskId" | "title">;
+  previousAttempt: number;
+  previousAssignmentIdentity: WorkerAssignmentIdentity;
+  reportDiagnostic: (diagnostic: WorkerSessionDiagnostic) => void;
+  reuseScope: RetainedWorkerReuseScope;
+}
+
+interface ActiveWorkerSessionAssignment {
+  identity: WorkerAssignmentIdentity;
+  controller: AbortController;
+  tainted: boolean;
+  rotationReported: boolean;
+  resource?: WorkerSessionResource;
+  reportDiagnostic?: (diagnostic: WorkerSessionDiagnostic) => void;
+  resolveCompletion: () => void;
+  completion: Promise<void>;
+}
+
+export interface CoordinatorWorkerSessionOwnerOptions {
+  runId: string;
+  cwd: string;
+  workerSessionReuse: boolean;
+  workerSessionReuseContextThresholdPercent: number;
+}
+
+/** Run-scoped owner for the single retained worker session and its assignment lock. */
+export class CoordinatorWorkerSessionOwner {
+  private retained: RetainedWorkerState | undefined;
+  private active: ActiveWorkerSessionAssignment | undefined;
+  private closed = false;
+  private disposePromise: Promise<void> | undefined;
+  private assignmentSequence = 0;
+  private readonly runtime: CoordinatorWorkerSessionOwnerOptions;
+
+  constructor(runtime: CoordinatorWorkerSessionOwnerOptions) {
+    this.runtime = runtime;
+  }
+
+  async run(options: RunWorkerTaskOptions, identity?: WorkerAssignmentIdentity): Promise<SessionOutcome> {
+    if (this.closed) {
+      throw new Error("retained worker session owner is closed");
+    }
+    const assignmentIdentity = identity ?? this.defaultIdentity(options);
+    if (this.active) {
+      throw new Error("retained worker session already has an active assignment");
+    }
+
+    let resolveCompletion: (() => void) | undefined;
+    const completion = new Promise<void>((resolve) => {
+      resolveCompletion = resolve;
+    });
+    const active: ActiveWorkerSessionAssignment = {
+      identity: assignmentIdentity,
+      controller: new AbortController(),
+      tainted: false,
+      rotationReported: false,
+      resolveCompletion: resolveCompletion as () => void,
+      completion,
+    };
+    this.active = active;
+    const assignmentOptions = {
+      ...options,
+      abortSignal: combineAbortSignals(options.abortSignal, active.controller.signal),
+    };
+    try {
+      return await this.runExclusive(assignmentOptions, assignmentIdentity, active);
+    } finally {
+      const activeResource = active.resource;
+      const retained = this.retained;
+      if (active.tainted && activeResource && retained?.resource === activeResource) {
+        retained.health = "cancelled";
+        await this.disposeRetainedResource(activeResource);
+      }
+      if (this.active === active) {
+        this.active = undefined;
+      }
+      active.resolveCompletion();
+    }
+  }
+
+  private async runExclusive(
+    options: RunWorkerTaskOptions,
+    identity: WorkerAssignmentIdentity,
+    active: ActiveWorkerSessionAssignment,
+  ): Promise<SessionOutcome> {
+    const compatibility = this.compatibilityFor(options);
+    const diagnostics: WorkerSessionDiagnostic[] = [];
+    const report = (diagnostic: WorkerSessionDiagnostic) => {
+      diagnostics.push(diagnostic);
+      options.onSessionDiagnostic?.(diagnostic);
+    };
+    active.reportDiagnostic = report;
+    const diagnosticContext = (retained: RetainedWorkerState) => ({
+      ...(retained.contextUsagePercent !== undefined ? { contextUsagePercent: retained.contextUsagePercent } : {}),
+      contextThresholdPercent: this.runtime.workerSessionReuseContextThresholdPercent,
+      previousTaskId: retained.previousTask.taskId,
+    });
+
+    let reusedFrom: Pick<Task, "taskId" | "title"> | undefined;
+    if (this.retained && !this.assignmentMatchesRetainedScope(options, this.retained)) {
+      // A partial-work session is continuity for exactly the next attempt of
+      // that task. It must never spill into unrelated work or a later retry.
+      report({
+        event: "session_rotated",
+        reasonCode: "partial_continuation_scope_mismatch",
+        ...diagnosticContext(this.retained),
+      });
+      await this.disposeRetained();
+    }
+    if (this.retained) {
+      const decision = decideWorkerSessionReuse({
+        config: {
+          enabled: this.runtime.workerSessionReuse,
+          contextThresholdPercent: this.runtime.workerSessionReuseContextThresholdPercent,
+        },
+        candidate: {
+          health: this.retained.health,
+          compatibility: this.retained.compatibility,
+          contextUsagePercent: this.retained.contextUsagePercent,
+          assignmentState: "idle",
+          disposed: this.retained.resource.disposed,
+        },
+        requestedCompatibility: compatibility,
+      });
+      if (decision.reusable) {
+        reusedFrom = this.retained.previousTask;
+        report({
+          event: "session_reused",
+          reasonCode: decision.reasonCode,
+          ...diagnosticContext(this.retained),
+        });
+      } else {
+        report({
+          event: "session_rotated",
+          reasonCode: decision.reasonCode,
+          ...diagnosticContext(this.retained),
+        });
+        await this.disposeRetained();
+      }
+    }
+
+    if (!this.retained) {
+      try {
+        this.retained = {
+          resource: await createWorkerSessionResource(options, options.sessionFactory ?? createIsolatedWorkerSession),
+          compatibility,
+          health: "healthy",
+          previousTask: options.task,
+          previousAttempt: options.attempt,
+          previousAssignmentIdentity: identity,
+          reportDiagnostic: report,
+          reuseScope: "sequential_task",
+        };
+        report({
+          event: "session_started",
+          reasonCode: diagnostics.some((item) => item.event === "session_rotated")
+            ? "rotation_completed"
+            : "fresh_session",
+          contextThresholdPercent: this.runtime.workerSessionReuseContextThresholdPercent,
+        });
+      } catch (error) {
+        const failed = buildWorkerSessionCreationFailureOutcome(options, error);
+        failed.sessionDiagnostics = diagnostics;
+        return failed;
+      }
+    }
+
+    active.resource = this.retained.resource;
+    let outcome: SessionOutcome;
+    try {
+      outcome = await runWorkerTaskAssignment(
+        options,
+        this.retained.resource,
+        reusedFrom ? { previousTask: reusedFrom } : undefined,
+      );
+    } catch (error) {
+      this.retained.health = active.tainted ? "cancelled" : "unrecoverable_error";
+      if (!active.rotationReported) {
+        active.rotationReported = true;
+        report({
+          event: "session_rotated",
+          reasonCode: "health_unrecoverable_error",
+          ...diagnosticContext(this.retained),
+        });
+      }
+      await this.disposeRetained();
+      throw error;
+    }
+
+    if (this.retained) {
+      const cancelled = Boolean(options.abortSignal?.aborted);
+      this.retained.health = workerSessionHealthForOutcome(outcome, cancelled);
+      this.retained.contextUsagePercent = await workerSessionContextUsagePercent(this.retained.resource.session);
+      this.retained.previousTask = options.task;
+      this.retained.previousAttempt = options.attempt;
+      this.retained.previousAssignmentIdentity = identity;
+      this.retained.reportDiagnostic = report;
+
+      if (active.tainted) {
+        if (!active.rotationReported) {
+          this.reportTaintedRotation(active, "assignment_cancelled");
+        }
+        await this.disposeRetainedResource(this.retained.resource);
+        outcome.sessionDiagnostics = [...(outcome.sessionDiagnostics ?? []), ...diagnostics];
+        return outcome;
+      }
+
+      const retry = classifyWorkerSessionRetry({
+        done: outcome.done,
+        reportedStatus: outcome.reportedStatus,
+        completeTaskResult: hasCompleteTaskResult(outcome.assistantText),
+        timedOut: outcome.timedOut,
+        aborted: outcome.aborted,
+        cancelled,
+        error: outcome.error,
+      });
+      this.retained.reuseScope = retry.mayContinueInSession ? "partial_continuation" : "sequential_task";
+
+      const postAssignmentDecision = decideWorkerSessionReuse({
+        config: {
+          enabled: this.runtime.workerSessionReuse,
+          contextThresholdPercent: this.runtime.workerSessionReuseContextThresholdPercent,
+        },
+        candidate: {
+          health: this.retained.health,
+          compatibility: this.retained.compatibility,
+          contextUsagePercent: this.retained.contextUsagePercent,
+          assignmentState: "idle",
+          disposed: this.retained.resource.disposed,
+        },
+        requestedCompatibility: compatibility,
+      });
+      // Completed tasks may flow into the next sequential TODO. A retry may
+      // remain only when it is an explicitly safe partial continuation and all
+      // normal health/compatibility/context checks still pass.
+      const rotateForRetry = !outcome.done && !retry.mayContinueInSession;
+      if (!postAssignmentDecision.reusable || rotateForRetry) {
+        if (!active.rotationReported) {
+          active.rotationReported = true;
+          report({
+            event: "session_rotated",
+            reasonCode: postAssignmentDecision.reusable ? retry.reasonCode : postAssignmentDecision.reasonCode,
+            ...diagnosticContext(this.retained),
+          });
+        }
+        await this.disposeRetained();
+      } else {
+        report({
+          event: "session_retained",
+          reasonCode: postAssignmentDecision.reasonCode,
+          ...diagnosticContext(this.retained),
+        });
+      }
+    }
+    outcome.sessionDiagnostics = [...(outcome.sessionDiagnostics ?? []), ...diagnostics];
+    return outcome;
+  }
+
+  /**
+   * Taint and abort only the matching obsolete assignment. Late cancellation
+   * from an older steering generation cannot affect a replacement assignment.
+   */
+  async invalidateAssignment(identity: WorkerAssignmentIdentity): Promise<boolean> {
+    const active = this.active;
+    if (active && sameWorkerAssignment(active.identity, identity)) {
+      this.taintActiveAssignment(active, "steering_revision_obsolete");
+      if (!active.controller.signal.aborted) {
+        active.controller.abort(new Error(`worker assignment ${identity.assignmentId} became obsolete`));
+      }
+      return true;
+    }
+
+    if (this.retained && sameWorkerAssignment(this.retained.previousAssignmentIdentity, identity)) {
+      const retained = this.retained;
+      retained.health = "cancelled";
+      retained.reportDiagnostic({
+        event: "session_rotated",
+        reasonCode: "steering_revision_obsolete",
+        ...this.diagnosticContext(retained),
+      });
+      await this.disposeRetained();
+      return true;
+    }
+    return false;
+  }
+
+  /** Abort active work, wait for its ownership path, then dispose retained state once. */
+  dispose(): Promise<void> {
+    if (!this.disposePromise) {
+      this.closed = true;
+      this.disposePromise = this.disposeAfterActiveAssignment();
+    }
+    return this.disposePromise;
+  }
+
+  private async disposeAfterActiveAssignment(): Promise<void> {
+    const active = this.active;
+    if (active) {
+      this.taintActiveAssignment(active, "coordinator_shutdown");
+      if (!active.controller.signal.aborted) {
+        active.controller.abort(new Error("worker session owner disposed"));
+      }
+      await active.completion;
+    }
+    await this.disposeRetained();
+  }
+
+  private assignmentMatchesRetainedScope(options: RunWorkerTaskOptions, retained: RetainedWorkerState): boolean {
+    if (retained.reuseScope === "sequential_task") {
+      return true;
+    }
+    return (
+      options.task.taskId === retained.previousTask.taskId &&
+      options.task.title === retained.previousTask.title &&
+      options.attempt === retained.previousAttempt + 1
+    );
+  }
+
+  private taintActiveAssignment(active: ActiveWorkerSessionAssignment, reasonCode: string): void {
+    active.tainted = true;
+    const retained = this.retained;
+    if (retained && retained.resource === active.resource) {
+      retained.health = "cancelled";
+    }
+    this.reportTaintedRotation(active, reasonCode);
+  }
+
+  private reportTaintedRotation(active: ActiveWorkerSessionAssignment, reasonCode: string): void {
+    if (active.rotationReported) return;
+    active.rotationReported = true;
+    const retained = this.retained;
+    active.reportDiagnostic?.({
+      event: "session_rotated",
+      reasonCode,
+      ...(retained ? this.diagnosticContext(retained) : {}),
+    });
+  }
+
+  private diagnosticContext(retained: RetainedWorkerState): {
+    contextUsagePercent?: number;
+    contextThresholdPercent: number;
+    previousTaskId: string;
+  } {
+    return {
+      ...(retained.contextUsagePercent !== undefined ? { contextUsagePercent: retained.contextUsagePercent } : {}),
+      contextThresholdPercent: this.runtime.workerSessionReuseContextThresholdPercent,
+      previousTaskId: retained.previousTask.taskId,
+    };
+  }
+
+  private defaultIdentity(options: RunWorkerTaskOptions): WorkerAssignmentIdentity {
+    const sequence = ++this.assignmentSequence;
+    return {
+      assignmentId: `${options.task.taskId}:${options.attempt}:${sequence}`,
+      taskIdentity: `${options.task.taskId}:${options.task.title}`,
+      steeringGeneration: 0,
+      planAuthorityToken: "direct-owner",
+    };
+  }
+
+  private compatibilityFor(options: RunWorkerTaskOptions): WorkerSessionCompatibilityFingerprint {
+    return createWorkerSessionCompatibilityFingerprint({
+      coordinatorRunId: this.runtime.runId,
+      repositoryRoot: this.runtime.cwd,
+      worktreeRoot: options.cwd,
+      modelName: options.modelName,
+      model: options.model,
+      tools: options.tools ?? DEFAULT_WORKER_TOOLS,
+      thinkingLevel: options.thinkingLevel,
+      agentDir: options.agentDir,
+      modelRuntime: options.modelRuntime,
+      authStorage: options.authStorage,
+      modelRegistry: options.modelRegistry,
+      settingsManager: options.settingsManager,
+      resourceLoader: options.resourceLoader,
+      sessionFactory: options.sessionFactory ?? createIsolatedWorkerSession,
+    });
+  }
+
+  private async disposeRetained(): Promise<void> {
+    const retained = this.retained;
+    if (!retained) {
+      return;
+    }
+    await this.disposeRetainedResource(retained.resource);
+  }
+
+  private async disposeRetainedResource(resource: WorkerSessionResource): Promise<void> {
+    if (this.retained?.resource === resource) {
+      this.retained = undefined;
+    }
+    try {
+      await disposeWorkerSessionResource(resource);
+    } catch {
+      // Session disposal is best effort; resource ownership is still closed exactly once.
+    }
+  }
+}
+
+function sameWorkerAssignment(left: WorkerAssignmentIdentity, right: WorkerAssignmentIdentity): boolean {
+  return (
+    left.assignmentId === right.assignmentId &&
+    left.taskIdentity === right.taskIdentity &&
+    left.steeringGeneration === right.steeringGeneration &&
+    left.planAuthorityToken === right.planAuthorityToken
+  );
+}
+
+function combineAbortSignals(...signals: Array<AbortSignal | undefined>): AbortSignal | undefined {
+  const available = signals.filter((signal): signal is AbortSignal => Boolean(signal));
+  if (available.length === 0) return undefined;
+  if (available.length === 1) return available[0];
+  return AbortSignal.any(available);
+}
+
+export function workerSessionHealthForOutcome(
+  outcome: Pick<SessionOutcome, "timedOut" | "aborted" | "error" | "assistantText">,
+  cancelled = false,
+): WorkerSessionHealth {
+  if (outcome.timedOut) return "timed_out";
+  if (cancelled) return "cancelled";
+  if (outcome.aborted) return "aborted";
+  if (outcome.error) return "unrecoverable_error";
+  if (!hasCompleteTaskResult(outcome.assistantText)) return "invalid_state";
+  return "healthy";
 }
 
 export async function runCoordinator(options: RunCoordinatorOptions): Promise<CoordinatorResult> {
   const runtime = buildRuntimeOptions(options);
+  const workerSessionOwner = runtime.useRetainedWorkerLifecycle
+    ? new CoordinatorWorkerSessionOwner(runtime)
+    : undefined;
   const inputText = coordinatorInputText(options);
   const attempts: TaskAttemptSummary[] = [];
   const outcomes: SessionOutcome[] = [];
@@ -235,7 +761,14 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
   let latestTodoMarkdown: string | undefined;
   let latestTasks: Task[] = [];
   let activeTask: Task | undefined;
+  let activeTaskReference: PlanTaskReference | undefined;
   let activeAttempt: number | undefined;
+  let activeWorkerAssignment:
+    | { identity: WorkerAssignmentIdentity; controller: AbortController; obsolete: boolean }
+    | undefined;
+  let steeringGeneration = 0;
+  let workerExecutionSequence = 0;
+  let removeSteeringProcessor: (() => void) | undefined;
   const protectedDirtyPathsByTask = new Map<string, Set<string>>();
 
   try {
@@ -244,7 +777,7 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
     validateTodoMarkdown(todoMarkdown);
     planningComplete = true;
     latestTodoMarkdown = todoMarkdown;
-    await writeFile(runtime.todoPath, todoMarkdown, "utf8");
+    const planStore = await PersistentTodoPlanStore.create(runtime.todoPath, todoMarkdown);
     const initialTasks = parseTasks(todoMarkdown);
     latestTasks = initialTasks;
     emitProgress(runtime, `Created TODO plan with ${initialTasks.length} task(s).`, {
@@ -253,10 +786,92 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
       taskProgress: buildTaskProgressModel({ tasks: initialTasks }),
     });
 
-    const previousAttempts = new Map<string, string[]>();
     let failure: string | undefined;
+    removeSteeringProcessor = runtime.steeringQueue?.setProcessor(async (message) => {
+      const baseAtRequest = planStore.snapshot();
+      const activeTaskAtRequest = activeTaskReference
+        ? resolvePlanTaskReference(
+            parseTasks(baseAtRequest.markdown),
+            activeTaskReference,
+            baseAtRequest.authorityToken,
+          )
+        : undefined;
+      try {
+        const revision = await generateSteeringPlanRevision({
+          message,
+          currentTodoMarkdown: baseAtRequest.markdown,
+          attempts,
+          outcomes,
+          commits,
+          activeTask: activeTaskAtRequest,
+          activeAttempt,
+          runtime,
+        });
+        const currentTasks = parseTasks(planStore.snapshot().markdown);
+        const appliedRevision = await planStore.applyRevision(revision, {
+          expectedAuthorityToken: baseAtRequest.authorityToken,
+          taskStates: coordinatorPlanTaskStates(currentTasks, attempts, activeTaskAtRequest),
+          runningTask: activeTaskReference,
+          // The callback remains part of acceptance: a rejection occurs before
+          // the atomic replacement and therefore leaves the prior plan active.
+          beforeCommit: runtime.onPlanRevisionAccepted,
+        });
+        // The store snapshot is the scheduler's authority at every task
+        // boundary, so this accepted revision continues the same run.
+        latestTodoMarkdown = appliedRevision.todoMarkdown;
+        latestTasks = appliedRevision.reconciliation.activeTasks.map((item) => item.task);
+        steeringGeneration += 1;
+
+        // Once replacement/removal is authoritative, make the exact old
+        // invocation obsolete before aborting it. Event callbacks consult this
+        // identity, so a late old result cannot repaint replacement progress.
+        const assignmentAtAcceptance = activeWorkerAssignment;
+        const activeStillValid = activeTaskReference
+          ? Boolean(resolvePlanTaskReference(latestTasks, activeTaskReference, planStore.snapshot().authorityToken))
+          : true;
+        if (assignmentAtAcceptance && !activeStillValid) {
+          assignmentAtAcceptance.obsolete = true;
+          if (!assignmentAtAcceptance.controller.signal.aborted) {
+            assignmentAtAcceptance.controller.abort(
+              new Error(`steering revision ${message.sequence} replaced the active assignment`),
+            );
+          }
+          await workerSessionOwner?.invalidateAssignment(assignmentAtAcceptance.identity);
+        }
+
+        emitProgress(
+          runtime,
+          `Accepted steering revision ${message.sequence} with ${appliedRevision.reconciliation.activeTasks.length} task(s).`,
+          {
+            phase: "planned",
+            status: "revised",
+            totalTasks: appliedRevision.reconciliation.activeTasks.length,
+            taskProgress: revisionTaskProgress(appliedRevision),
+          },
+        );
+      } catch (error) {
+        const currentSnapshot = planStore.snapshot();
+        const messageText =
+          error instanceof PlanRevisionGenerationError
+            ? `${error.message} The prior plan remains active and this guidance can be retried.`
+            : `Plan revision failed. The prior plan remains active: ${errorMessage(error)}`;
+        emitProgress(runtime, messageText, {
+          phase: "planning",
+          status: "revision_failed",
+          isError: true,
+          totalTasks: parseTasks(currentSnapshot.markdown).length,
+          taskProgress: buildTaskProgressModel({ tasks: parseTasks(currentSnapshot.markdown) }),
+        });
+        throw error;
+      }
+    });
 
     while (!runtime.abortSignal?.aborted) {
+      // Guidance received before this boundary must settle before selecting
+      // more work. Failed revisions leave the prior snapshot usable.
+      await runtime.steeringQueue?.waitForIdle();
+      const schedulingSnapshot = planStore.snapshot();
+      todoMarkdown = schedulingSnapshot.markdown;
       const tasksBeforeAttempt = parseTasks(todoMarkdown);
       latestTasks = tasksBeforeAttempt;
       const nextTask = tasksBeforeAttempt.find((task) => !task.done);
@@ -264,10 +879,28 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
         break;
       }
 
-      const attempt = (previousAttempts.get(nextTask.taskId)?.length ?? 0) + 1;
+      const priorTaskAttempts = attemptsForTask(tasksBeforeAttempt, attempts, nextTask);
+      const attempt = priorTaskAttempts.length + 1;
       const initialActivity =
         nextTask.statusItems.find((item) => !item.done)?.text ?? `Starting TODO ${nextTask.taskId}`;
       const worker = workerKey(nextTask.taskId, attempt);
+      // Task IDs and attempt numbers may be reused after an in-flight task is
+      // replaced by steering. Accounting needs an invocation identity so the
+      // obsolete attempt's finalized spend cannot be overwritten.
+      const accountingWorker = `${worker}#${++workerExecutionSequence}`;
+      const assignmentIdentity: WorkerAssignmentIdentity = {
+        assignmentId: accountingWorker,
+        taskIdentity: nextTask.stableId ?? taskSemanticFingerprint(nextTask),
+        steeringGeneration,
+        planAuthorityToken: schedulingSnapshot.authorityToken,
+      };
+      const assignmentController = new AbortController();
+      const assignmentState = { identity: assignmentIdentity, controller: assignmentController, obsolete: false };
+      const taskPlanReference = planTaskReference(nextTask, schedulingSnapshot.authorityToken);
+      activeWorkerAssignment = assignmentState;
+      activeTask = nextTask;
+      activeAttempt = attempt;
+      activeTaskReference = taskPlanReference;
       runtime.workerActivityByWorker.set(worker, initialActivity);
       runtime.workerTextByWorker.delete(worker);
       runtime.workerTextPublishedLengthByWorker.delete(worker);
@@ -288,22 +921,25 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
           }),
         },
       );
-      let preExistingDirtyPaths = protectedDirtyPathsByTask.get(nextTask.taskId);
+      const executionIdentity = taskExecutionIdentity(nextTask);
+      let preExistingDirtyPaths = protectedDirtyPathsByTask.get(executionIdentity);
       if (!preExistingDirtyPaths) {
         preExistingDirtyPaths = options.commit
           ? await gitDirtyPaths(runtime.cwd, runtime.taskResultPath, runtime.todoPath, runtime.runDir)
           : new Set<string>();
-        protectedDirtyPathsByTask.set(nextTask.taskId, preExistingDirtyPaths);
+        protectedDirtyPathsByTask.set(executionIdentity, preExistingDirtyPaths);
       }
-      activeTask = nextTask;
-      activeAttempt = attempt;
-      const outcome = await runtime.workerRunner({
+      const workerOptions: RunWorkerTaskOptions = {
         cwd: runtime.cwd,
         todoPath: runtime.todoPath,
         task: nextTask,
         attempt,
         commitRequested: options.commit,
-        previousAttempts: previousAttempts.get(nextTask.taskId)?.join("\n\n---\n\n"),
+        previousAttempts:
+          priorTaskAttempts
+            .map((item) => item.resultText)
+            .filter((item): item is string => Boolean(item))
+            .join("\n\n---\n\n") || undefined,
         globalInstructions: todoGlobalInstructions(todoMarkdown),
         goal: runtime.goal,
         maxBashTimeoutSeconds: runtime.maxBashTimeoutSeconds,
@@ -311,52 +947,111 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
         model: runtime.workerModel,
         modelName: runtime.workerModelName,
         thinkingLevel: runtime.taskThinking,
-        abortSignal: runtime.abortSignal,
+        abortSignal: combineAbortSignals(runtime.abortSignal, assignmentController.signal),
         sessionFactory: runtime.workerSessionFactory,
         now: runtime.now,
-        onEvent: (event) => emitWorkerEventProgress(runtime, tasksBeforeAttempt, nextTask, attempts, attempt, event),
-      });
-      outcomes.push(outcome);
-      finalizeWorkerCost(runtime.workerCostState, outcome);
+        onEvent: (event) => {
+          if (activeWorkerAssignment === assignmentState && !assignmentState.obsolete) {
+            emitWorkerEventProgress(runtime, tasksBeforeAttempt, nextTask, attempts, attempt, event, accountingWorker);
+          }
+        },
+        onSessionDiagnostic: (diagnostic) => {
+          if (activeWorkerAssignment === assignmentState && !assignmentState.obsolete) {
+            emitWorkerSessionProgress(runtime, tasksBeforeAttempt, nextTask, attempts, attempt, diagnostic);
+          } else {
+            // Lifecycle accounting remains accurate, but obsolete diagnostics
+            // must not mutate the replacement task's visible progress.
+            recordWorkerSessionMetric(runtime.workerSessionMetrics, diagnostic);
+          }
+        },
+      };
+      let outcome: SessionOutcome;
+      try {
+        outcome = workerSessionOwner
+          ? await workerSessionOwner.run(workerOptions, assignmentIdentity)
+          : await runtime.workerRunner(workerOptions);
+      } catch (error) {
+        if (!assignmentState.obsolete) {
+          throw error;
+        }
+        // A cancellation-aware custom runner may reject instead of returning
+        // an aborted outcome. Preserve historical evidence, but never let that
+        // obsolete rejection terminate or update the replacement assignment.
+        outcome = buildWorkerSessionCreationFailureOutcome(workerOptions, error);
+        outcome.aborted = true;
+      }
+      finalizeWorkerCost(runtime.workerCostState, accountingWorker, outcome);
+
+      // A revision may have been accepted while the worker was running. Let all
+      // already-received guidance settle, then resolve this exact task identity
+      // against the latest plan before applying any terminal state.
+      await runtime.steeringQueue?.waitForIdle();
+      const initialResolution = await planStore.resolveTask(taskPlanReference);
+      const initiallyObsolete = initialResolution.stale || !initialResolution.task;
+
+      // Durable attempt evidence must exist before any completion checkbox is
+      // persisted. If this write fails, normal failure handling leaves the task
+      // pending and retryable.
+      await appendTaskResult(runtime.taskResultPath, nextTask, outcome, initiallyObsolete);
+      const settlement = initiallyObsolete
+        ? initialResolution
+        : outcome.done
+          ? await planStore.completeTask(taskPlanReference)
+          : await planStore.resolveTask(taskPlanReference);
+      const obsolete = settlement.stale || !settlement.task;
+      if (obsolete && !initiallyObsolete) {
+        await appendObsoleteDisposition(runtime.taskResultPath);
+      }
+      const settledTask = settlement.task ?? initialResolution.task ?? nextTask;
+      todoMarkdown = settlement.snapshot.markdown;
+      latestTodoMarkdown = todoMarkdown;
+      latestTasks = parseTasks(todoMarkdown);
 
       const attemptDetails: TaskAttemptSummary = {
         taskId: nextTask.taskId,
         title: nextTask.title,
+        taskStableId: nextTask.stableId,
+        taskFingerprint: taskSemanticFingerprint(nextTask),
         attempt,
         reportedStatus: outcome.reportedStatus,
         done: outcome.done,
         error: outcome.error,
+        obsolete,
+        resultText: resultTextForPreviousAttempt(outcome),
       };
       attempts.push(attemptDetails);
-      await appendTaskResult(runtime.taskResultPath, nextTask, outcome);
+      outcomes.push(outcome);
 
-      if (outcome.done) {
-        todoMarkdown = markTaskDone(todoMarkdown, nextTask.taskId);
-        latestTodoMarkdown = todoMarkdown;
-        await writeFile(runtime.todoPath, todoMarkdown, "utf8");
-      }
       activeTask = undefined;
+      activeTaskReference = undefined;
       activeAttempt = undefined;
+      if (activeWorkerAssignment === assignmentState) {
+        activeWorkerAssignment = undefined;
+      }
 
       let taskCommitHash: string | undefined;
       let taskCommitError: string | undefined;
       let taskCommitSkipped: string | undefined;
       if (options.commit) {
-        const commitResult = shouldCommitOutcome(outcome)
-          ? await commitAfterSession({
-              cwd: runtime.cwd,
-              resultPath: runtime.taskResultPath,
-              todoPath: runtime.todoPath,
-              runDir: runtime.runDir,
-              outcome,
-              preExistingDirtyPaths,
-            })
-          : ({ skipped: "outcome is not eligible for commit" } satisfies CommitAfterSessionResult);
+        const commitResult = obsolete
+          ? ({
+              skipped: "task was replaced or removed by an accepted plan revision",
+            } satisfies CommitAfterSessionResult)
+          : shouldCommitOutcome(outcome)
+            ? await commitAfterSession({
+                cwd: runtime.cwd,
+                resultPath: runtime.taskResultPath,
+                todoPath: runtime.todoPath,
+                runDir: runtime.runDir,
+                outcome,
+                preExistingDirtyPaths,
+              })
+            : ({ skipped: "outcome is not eligible for commit" } satisfies CommitAfterSessionResult);
         attemptDetails.commitHash = commitResult.hash;
         attemptDetails.commitError = commitResult.error;
         attemptDetails.commitSkipped = commitResult.skipped;
         if (commitResult.hash || commitResult.error) {
-          commits.push({ taskId: nextTask.taskId, hash: commitResult.hash, error: commitResult.error });
+          commits.push({ taskId: settledTask.taskId, hash: commitResult.hash, error: commitResult.error });
         }
         taskCommitHash = commitResult.hash;
         taskCommitError = commitResult.error;
@@ -364,10 +1059,15 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
         await appendCommitNote(runtime.taskResultPath, commitResult);
       }
 
+      if (obsolete) {
+        emitObsoleteTaskOutcomeProgress(runtime, latestTasks, nextTask, attempts, outcome);
+        continue;
+      }
+
       emitTaskOutcomeProgress(
         runtime,
-        parseTasks(todoMarkdown),
-        nextTask,
+        latestTasks,
+        settledTask,
         attempts,
         outcome,
         taskCommitHash,
@@ -375,15 +1075,33 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
         taskCommitSkipped,
       );
 
-      const attemptSummary = resultTextForPreviousAttempt(outcome);
-      previousAttempts.set(nextTask.taskId, [...(previousAttempts.get(nextTask.taskId) ?? []), attemptSummary]);
-
       if (outcome.done) {
         continue;
       }
 
       if (attempt >= runtime.maxAttemptsPerTask) {
-        failure = `TODO ${nextTask.taskId} — ${nextTask.title} did not report done after ${attempt} attempt(s).`;
+        // Give guidance received at the failure boundary the same chance to
+        // replace this work before terminal retry exhaustion is declared.
+        await runtime.steeringQueue?.waitForIdle();
+        const failureResolution = await planStore.resolveTask(taskPlanReference);
+        if (failureResolution.stale || !failureResolution.task) {
+          attemptDetails.obsolete = true;
+          await appendObsoleteDisposition(runtime.taskResultPath);
+          todoMarkdown = failureResolution.snapshot.markdown;
+          latestTodoMarkdown = todoMarkdown;
+          latestTasks = parseTasks(todoMarkdown);
+          emitObsoleteTaskOutcomeProgress(runtime, latestTasks, nextTask, attempts, outcome);
+          continue;
+        }
+        const currentAttemptCount = attemptsForTask(
+          parseTasks(failureResolution.snapshot.markdown),
+          attempts,
+          failureResolution.task,
+        ).length;
+        if (currentAttemptCount < runtime.maxAttemptsPerTask) {
+          continue;
+        }
+        failure = `TODO ${failureResolution.task.taskId} — ${failureResolution.task.title} did not report done after ${currentAttemptCount} attempt(s).`;
         break;
       }
     }
@@ -432,6 +1150,8 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
       attempts,
       taskProgress,
       workerCostTotal: runtime.workerCostState.total,
+      workerUsageTotal: aggregateWorkerUsage(outcomes),
+      workerSessionMetrics: snapshotWorkerSessionMetrics(runtime.workerSessionMetrics),
       commit: options.commit,
       goal: runtime.goal,
       error: failure,
@@ -470,6 +1190,8 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
       attempts.push({
         taskId: activeTask.taskId,
         title: activeTask.title,
+        taskStableId: activeTask.stableId,
+        taskFingerprint: taskSemanticFingerprint(activeTask),
         attempt: activeAttempt,
         reportedStatus: "failed",
         done: false,
@@ -511,6 +1233,8 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
       attempts,
       taskProgress,
       workerCostTotal: runtime.workerCostState.total,
+      workerUsageTotal: aggregateWorkerUsage(outcomes),
+      workerSessionMetrics: snapshotWorkerSessionMetrics(runtime.workerSessionMetrics),
       commit: options.commit,
       goal: runtime.goal,
       error: resultError,
@@ -523,6 +1247,9 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
       taskProgress,
     });
     return result;
+  } finally {
+    removeSteeringProcessor?.();
+    await workerSessionOwner?.dispose();
   }
 }
 
@@ -607,6 +1334,152 @@ async function requestTodoPlan(inputText: string, runtime: RuntimeOptions): Prom
   });
 }
 
+async function generateSteeringPlanRevision(options: {
+  message: Readonly<SteeringMessage>;
+  currentTodoMarkdown: string;
+  attempts: readonly TaskAttemptSummary[];
+  outcomes: readonly SessionOutcome[];
+  commits: readonly CoordinatorCommitSummary[];
+  activeTask: Task | undefined;
+  activeAttempt: number | undefined;
+  runtime: RuntimeOptions;
+}): Promise<GeneratedPlanRevision> {
+  const currentTasks = parseTasks(options.currentTodoMarkdown);
+  const taskStates = coordinatorPlanTaskStates(currentTasks, options.attempts, options.activeTask);
+
+  return generatePlanRevision({
+    currentTodoMarkdown: options.currentTodoMarkdown,
+    guidance: options.message.text,
+    revisionId: options.message.id,
+    taskStates,
+    relevantResults: relevantPlanRevisionResults(currentTasks, options.attempts, options.outcomes, options.commits),
+    activeTask: options.activeTask
+      ? {
+          taskId: options.activeTask.taskId,
+          title: options.activeTask.title,
+          attempt: options.activeAttempt,
+          activity: options.runtime.workerActivityByWorker.get(
+            workerKey(options.activeTask.taskId, options.activeAttempt ?? 1),
+          ),
+        }
+      : undefined,
+    planner: ({ prompt, request }) =>
+      options.runtime.todoPlanner({
+        inputText: prompt,
+        plannerPrompt: prompt,
+        planRevision: request,
+        cwd: options.runtime.cwd,
+        runDir: options.runtime.runDir,
+        thinkingLevel: options.runtime.todoThinking,
+        model: options.runtime.workerModel,
+        abortSignal: options.runtime.abortSignal,
+        timeoutMs: options.runtime.todoTimeoutMs,
+        gracefulShutdownMs: options.runtime.todoGracefulShutdownMs,
+        sessionFactory: options.runtime.todoSessionFactory,
+        onDiagnostic: (diagnostic) => recordPlannerDiagnostic(options.runtime, diagnostic),
+        goal: options.runtime.goal,
+      }),
+  });
+}
+
+function coordinatorPlanTaskStates(
+  tasks: readonly Task[],
+  attempts: readonly TaskAttemptSummary[],
+  activeTask: Task | undefined,
+): Record<string, PlanTaskState> {
+  const lastAttemptByTask = new Map<string, TaskAttemptSummary>();
+  for (const attempt of taskProgressAttempts(tasks, attempts)) {
+    lastAttemptByTask.set(attempt.taskId, attempt);
+  }
+
+  return Object.fromEntries(
+    tasks.map((task) => {
+      const attempt = lastAttemptByTask.get(task.taskId);
+      const state: PlanTaskState = task.done
+        ? "completed"
+        : activeTask?.stableId && task.stableId === activeTask.stableId
+          ? "running"
+          : activeTask?.taskId === task.taskId && task.title === activeTask.title
+            ? "running"
+            : attempt?.reportedStatus === "blocked"
+              ? "blocked"
+              : attempt
+                ? "failed"
+                : "pending";
+      return [task.taskId, state];
+    }),
+  );
+}
+
+function revisionTaskProgress(revision: GeneratedPlanRevision): TaskProgressModel {
+  const tasks = revision.reconciliation.activeTasks.map((item) => item.task);
+  const running = revision.reconciliation.activeTasks.find((item) => item.state === "running");
+  const stateAttempts = revision.reconciliation.activeTasks.flatMap((item) => {
+    if (item.state !== "failed" && item.state !== "blocked") {
+      return [];
+    }
+    return [
+      {
+        taskId: item.task.taskId,
+        reportedStatus: item.state,
+        done: false,
+      },
+    ];
+  });
+  return buildTaskProgressModel({
+    tasks,
+    attempts: stateAttempts,
+    currentTaskId: running?.task.taskId,
+  });
+}
+
+function relevantPlanRevisionResults(
+  currentTasks: readonly Task[],
+  attempts: readonly TaskAttemptSummary[],
+  outcomes: readonly SessionOutcome[],
+  commits: readonly CoordinatorCommitSummary[],
+): PlanRevisionRelevantResult[] {
+  const commitByTask = new Map(
+    commits.filter((commit) => commit.hash).map((commit) => [commit.taskId, commit.hash as string]),
+  );
+
+  return currentTasks.flatMap((task) => {
+    if (!task.done) {
+      return [];
+    }
+    const completedAttempt = attemptsForTask(currentTasks, attempts, task)
+      .filter((attempt) => attempt.done)
+      .at(-1);
+    if (!completedAttempt) {
+      return [];
+    }
+    const outcome = [...outcomes]
+      .reverse()
+      .find(
+        (item) =>
+          item.attempt === completedAttempt.attempt &&
+          item.task.title === completedAttempt.title &&
+          (!completedAttempt.taskFingerprint ||
+            taskSemanticFingerprint(item.task as Task) === completedAttempt.taskFingerprint),
+      );
+    const commitHash = completedAttempt.commitHash ?? commitByTask.get(completedAttempt.taskId);
+    const outputReferences = [
+      outcome?.sessionFile ? `session:${outcome.sessionFile}` : undefined,
+      outcome?.sessionId ? `session-id:${outcome.sessionId}` : undefined,
+      commitHash ? `commit:${commitHash}` : undefined,
+    ].filter((item): item is string => Boolean(item));
+    return [
+      {
+        taskId: task.taskId,
+        status: completedAttempt.reportedStatus,
+        summary:
+          (outcome ? extractResultSummary(outcome.assistantText).trim() : "") || `Completed TODO ${task.taskId}.`,
+        outputReferences,
+      },
+    ];
+  });
+}
+
 // Planner/worker lifecycle differences are audited in docs/planner-worker-lifecycle-audit.md;
 // keep this function's public contract stable while moving shared prompt guarding into a helper.
 export async function runTodoPlanner(options: TodoPlannerOptions): Promise<string> {
@@ -627,7 +1500,7 @@ export async function runTodoPlanner(options: TodoPlannerOptions): Promise<strin
   try {
     const plannerText = await runTodoPlannerPrompt({
       session,
-      prompt: buildTodoCreationPrompt(options.inputText, options.goal),
+      prompt: options.plannerPrompt ?? buildTodoCreationPrompt(options.inputText, options.goal),
       abortSignal: options.abortSignal,
       timeoutMs,
       gracefulShutdownMs,
@@ -774,6 +1647,11 @@ function buildRuntimeOptions(options: RunCoordinatorOptions): RuntimeOptions {
   const workerModelName = options.workerModelName ?? parsedWorkerConfig.modelName;
   const workerModel = workerModelName ? undefined : options.workerModel;
   const goal = normalizeOptionalText(options.goal);
+  const workerSessionReuseConfig = resolveWorkerSessionReuseConfig({
+    enabled: options.workerSessionReuse ?? parsedWorkerConfig.workerSessionReuseEnabled,
+    contextThresholdPercent:
+      options.workerSessionReuseContextThresholdPercent ?? parsedWorkerConfig.workerSessionReuseContextThresholdPercent,
+  });
 
   return {
     cwd,
@@ -795,7 +1673,10 @@ function buildRuntimeOptions(options: RunCoordinatorOptions): RuntimeOptions {
     goal,
     taskThinking: options.taskThinking ?? DEFAULT_COORDINATOR_OPTIONS.taskThinking,
     todoThinking: options.todoThinking ?? DEFAULT_COORDINATOR_OPTIONS.todoThinking,
+    workerSessionReuse: workerSessionReuseConfig.enabled,
+    workerSessionReuseContextThresholdPercent: workerSessionReuseConfig.contextThresholdPercent,
     workerRunner: options.workerRunner ?? runWorkerTask,
+    useRetainedWorkerLifecycle: options.workerRunner === undefined,
     todoPlanner: options.todoPlanner ?? runTodoPlanner,
     abortSignal: options.abortSignal,
     workerSessionFactory: options.workerSessionFactory,
@@ -807,6 +1688,9 @@ function buildRuntimeOptions(options: RunCoordinatorOptions): RuntimeOptions {
     workerTextByWorker: new Map(),
     workerTextPublishedLengthByWorker: new Map(),
     plannerDiagnostics: [],
+    workerSessionMetrics: createWorkerSessionMetrics(),
+    steeringQueue: options.steeringQueue,
+    onPlanRevisionAccepted: options.onPlanRevisionAccepted,
   };
 }
 
@@ -851,6 +1735,41 @@ function recordPlannerDiagnostic(runtime: RuntimeOptions, diagnostic: PlannerDia
   });
 }
 
+function aggregateWorkerUsage(outcomes: readonly SessionOutcome[]): WorkerUsageTotals | undefined {
+  const usage = outcomes.flatMap((outcome) => (outcome.workerUsage ? [outcome.workerUsage] : []));
+  if (usage.length === 0) {
+    return undefined;
+  }
+  return usage.reduce<WorkerUsageTotals>(
+    (total, item) => ({
+      input: total.input + item.input,
+      output: total.output + item.output,
+      cacheRead: total.cacheRead + item.cacheRead,
+      cacheWrite: total.cacheWrite + item.cacheWrite,
+      total: total.total + item.total,
+    }),
+    { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+  );
+}
+
+function createWorkerSessionMetrics(): WorkerSessionMetrics {
+  return { starts: 0, reuses: 0, rotations: 0, retained: 0, rotationReasons: {} };
+}
+
+function snapshotWorkerSessionMetrics(metrics: WorkerSessionMetrics): WorkerSessionMetrics {
+  return { ...metrics, rotationReasons: { ...metrics.rotationReasons } };
+}
+
+function recordWorkerSessionMetric(metrics: WorkerSessionMetrics, diagnostic: WorkerSessionDiagnostic): void {
+  if (diagnostic.event === "session_started") metrics.starts += 1;
+  if (diagnostic.event === "session_reused") metrics.reuses += 1;
+  if (diagnostic.event === "session_retained") metrics.retained += 1;
+  if (diagnostic.event === "session_rotated") {
+    metrics.rotations += 1;
+    metrics.rotationReasons[diagnostic.reasonCode] = (metrics.rotationReasons[diagnostic.reasonCode] ?? 0) + 1;
+  }
+}
+
 function createWorkerCostState(): WorkerCostState {
   return {
     total: 0,
@@ -887,9 +1806,9 @@ function recordLiveWorkerCost(
 
 function finalizeWorkerCost(
   state: WorkerCostState,
-  outcome: Pick<SessionOutcome, "task" | "attempt" | "workerCostTotal">,
+  worker: string,
+  outcome: Pick<SessionOutcome, "workerCostTotal">,
 ): void {
-  const worker = workerKey(outcome.task.taskId, outcome.attempt);
   state.finalizedByWorker.set(worker, finiteNonNegativeNumber(outcome.workerCostTotal) ?? 0);
   state.liveByWorker.delete(worker);
   for (const messageKey of state.liveByMessage.keys()) {
@@ -958,6 +1877,43 @@ function subtaskProgress(
   });
 }
 
+function emitWorkerSessionProgress(
+  runtime: RuntimeOptions,
+  tasks: readonly Task[],
+  task: Pick<Task, "taskId" | "title" | "statusItems">,
+  attempts: readonly TaskAttemptSummary[],
+  attempt: number,
+  diagnostic: WorkerSessionDiagnostic,
+): void {
+  recordWorkerSessionMetric(runtime.workerSessionMetrics, diagnostic);
+  const contextText =
+    diagnostic.contextUsagePercent === undefined
+      ? ""
+      : ` at ${diagnostic.contextUsagePercent.toFixed(1)}% context usage`;
+  const action =
+    diagnostic.event === "session_started"
+      ? "started"
+      : diagnostic.event === "session_reused"
+        ? "reused"
+        : diagnostic.event === "session_rotated"
+          ? "rotated"
+          : "retained";
+  emitProgress(runtime, `Worker session ${action}${contextText} (${diagnostic.reasonCode}).`, {
+    phase: "worker_session",
+    taskId: task.taskId,
+    title: task.title,
+    attempt,
+    status: "in_progress",
+    activeStatus: `Worker session ${action}`,
+    workerSessionEvent: diagnostic.event,
+    workerSessionReason: diagnostic.reasonCode,
+    workerSessionContextUsagePercent: diagnostic.contextUsagePercent,
+    workerSessionContextThresholdPercent: diagnostic.contextThresholdPercent,
+    ...currentTaskProgress(task, "in_progress"),
+    taskProgress: buildTaskProgressModel({ tasks, attempts, currentTaskId: task.taskId }),
+  });
+}
+
 function emitWorkerEventProgress(
   runtime: RuntimeOptions,
   tasks: readonly Task[],
@@ -973,6 +1929,7 @@ function emitWorkerEventProgress(
     usageCostTotal?: number;
     usageCostKey?: string;
   },
+  accountingWorker = workerKey(task.taskId, attempt),
 ): void {
   const worker = workerKey(task.taskId, attempt);
   let activeStatus = runtime.workerActivityByWorker.get(worker);
@@ -1013,7 +1970,7 @@ function emitWorkerEventProgress(
   }
 
   const costChanged =
-    event.usageCostTotal !== undefined && recordLiveWorkerCost(runtime.workerCostState, worker, event);
+    event.usageCostTotal !== undefined && recordLiveWorkerCost(runtime.workerCostState, accountingWorker, event);
 
   if (event.type === "message_end" && event.activity) {
     emitProgress(runtime, event.activity, {
@@ -1085,7 +2042,7 @@ function emitWorkerEventProgress(
 }
 
 function stripToolOutcomePrefix(activity: string): string {
-  return activity.replace(/^(?:(?:Finished|Failed):\s*)+/i, "");
+  return activity.trim().replace(/^(?:(?:Finished|Failed):\s*)+/i, "");
 }
 
 function activeStatusFromWorkerText(text: string): string {
@@ -1093,6 +2050,27 @@ function activeStatusFromWorkerText(text: string): string {
   return (taskResultIndex >= 0 ? text.slice(0, taskResultIndex) : text).replace(/\s+/g, " ").trim();
 }
 
+function emitObsoleteTaskOutcomeProgress(
+  runtime: RuntimeOptions,
+  tasks: readonly Task[],
+  task: Pick<Task, "taskId" | "title" | "statusItems">,
+  attempts: readonly TaskAttemptSummary[],
+  outcome: SessionOutcome,
+): void {
+  emitProgress(
+    runtime,
+    `TODO ${task.taskId} result was retained as obsolete because an accepted revision replaced or removed the in-flight task.`,
+    {
+      phase: "task_obsolete",
+      taskId: task.taskId,
+      title: task.title,
+      attempt: outcome.attempt,
+      status: "obsolete",
+      taskProgress: buildTaskProgressModel({ tasks, attempts }),
+    },
+  );
+}
+
 function emitTaskOutcomeProgress(
   runtime: RuntimeOptions,
   tasks: readonly Task[],
@@ -1142,23 +2120,62 @@ function emitTaskOutcomeProgress(
   emitProgress(runtime, `TODO ${task.taskId} ${statusText}${commitText}.`, update);
 }
 
+function taskProgressAttempts(tasks: readonly Task[], attempts: readonly TaskAttemptSummary[]): TaskAttemptSummary[] {
+  return attempts.flatMap((attempt) => {
+    if (attempt.obsolete) {
+      return [];
+    }
+    const fingerprintMatches = attempt.taskFingerprint
+      ? tasks.filter((task) => taskSemanticFingerprint(task) === attempt.taskFingerprint)
+      : [];
+    const stableMatches =
+      !attempt.taskFingerprint && attempt.taskStableId
+        ? tasks.filter((task) => task.stableId === attempt.taskStableId)
+        : [];
+    const matched =
+      fingerprintMatches.length === 1
+        ? fingerprintMatches[0]
+        : stableMatches.length === 1
+          ? stableMatches[0]
+          : !attempt.taskFingerprint
+            ? tasks.find((task) => task.taskId === attempt.taskId && task.title === attempt.title)
+            : undefined;
+    return matched ? [{ ...attempt, taskId: matched.taskId, title: matched.title }] : [];
+  });
+}
+
+function attemptsForTask(
+  tasks: readonly Task[],
+  attempts: readonly TaskAttemptSummary[],
+  task: Pick<Task, "taskId">,
+): TaskAttemptSummary[] {
+  return taskProgressAttempts(tasks, attempts).filter((attempt) => attempt.taskId === task.taskId);
+}
+
+function taskExecutionIdentity(task: Task): string {
+  return task.stableId
+    ? `stable:${task.stableId}:${taskSemanticFingerprint(task)}`
+    : `semantic:${taskSemanticFingerprint(task)}`;
+}
+
 function buildCompletionTaskProgressModel(
   tasks: readonly Task[],
   attempts: readonly TaskAttemptSummary[],
   status: CoordinatorStatus,
 ): TaskProgressModel {
+  const currentAttempts = taskProgressAttempts(tasks, attempts);
   if (status === "done") {
-    return buildTaskProgressModel({ tasks, attempts });
+    return buildTaskProgressModel({ tasks, attempts: currentAttempts });
   }
 
-  const lastIncompleteAttempt = [...attempts].reverse().find((attempt) => !attempt.done);
+  const lastIncompleteAttempt = [...currentAttempts].reverse().find((attempt) => !attempt.done);
   if (!lastIncompleteAttempt) {
-    return buildTaskProgressModel({ tasks, attempts });
+    return buildTaskProgressModel({ tasks, attempts: currentAttempts });
   }
 
   return buildTaskProgressModel({
     tasks,
-    attempts,
+    attempts: currentAttempts,
     currentTaskId: lastIncompleteAttempt.taskId,
     currentTaskStatus: outcomeTaskProgressStatus(lastIncompleteAttempt),
   });
@@ -1226,7 +2243,12 @@ async function appendCommitNote(pathname: string, result: CommitAfterSessionResu
   await appendFile(pathname, `${lines.join("\n")}\n`, "utf8");
 }
 
-async function appendTaskResult(pathname: string, task: Task, outcome: SessionOutcome): Promise<void> {
+async function appendTaskResult(
+  pathname: string,
+  task: Task,
+  outcome: SessionOutcome,
+  obsolete = false,
+): Promise<void> {
   const summary = extractResultSummary(outcome.assistantText || "").trim() || "TASK_RESULT:\nstatus: unknown";
   const lines = [
     "",
@@ -1237,6 +2259,9 @@ async function appendTaskResult(pathname: string, task: Task, outcome: SessionOu
     `Reported status: ${outcome.reportedStatus}`,
     `Done: ${outcome.done ? "yes" : "no"}`,
   ];
+  if (obsolete) {
+    lines.push(obsoleteDispositionText());
+  }
 
   if (outcome.sessionId) {
     lines.push(`Session ID: ${outcome.sessionId}`);
@@ -1256,6 +2281,25 @@ async function appendTaskResult(pathname: string, task: Task, outcome: SessionOu
   if (outcome.contextObservations.length > 0) {
     lines.push("", "Context observations:", ...outcome.contextObservations.map((item) => `- ${item}`));
   }
+  if (outcome.workerCostSource || outcome.workerCostTotal > 0) {
+    lines.push(`Worker cost: ${outcome.workerCostTotal} (${outcome.workerCostSource ?? "unavailable"})`);
+  }
+  if (outcome.workerUsage) {
+    lines.push(
+      `Worker token usage: input=${outcome.workerUsage.input}, output=${outcome.workerUsage.output}, cacheRead=${outcome.workerUsage.cacheRead}, cacheWrite=${outcome.workerUsage.cacheWrite}, total=${outcome.workerUsage.total}`,
+    );
+  }
+  if (outcome.sessionDiagnostics?.length) {
+    lines.push(
+      "",
+      "Worker session diagnostics:",
+      ...outcome.sessionDiagnostics.map((item) => {
+        const context =
+          item.contextUsagePercent === undefined ? "" : ` context=${item.contextUsagePercent.toFixed(1)}%`;
+        return `- event=${item.event} reason=${item.reasonCode}${context}`;
+      }),
+    );
+  }
   if (outcome.compactionEvents.length > 0) {
     lines.push("", "Compaction events:", ...outcome.compactionEvents.map((item) => `- ${item}`));
   }
@@ -1264,9 +2308,17 @@ async function appendTaskResult(pathname: string, task: Task, outcome: SessionOu
   await appendFile(pathname, `${lines.join("\n")}\n`, "utf8");
 }
 
+async function appendObsoleteDisposition(pathname: string): Promise<void> {
+  await appendFile(pathname, `\n${obsoleteDispositionText()}\n`, "utf8");
+}
+
+function obsoleteDispositionText(): string {
+  return "Plan disposition: obsolete — an accepted revision replaced or removed this in-flight task; its result did not update plan status.";
+}
+
 function remainingTaskSummaries(tasks: Task[], attempts: TaskAttemptSummary[]): CoordinatorRemainingTask[] {
   const lastAttemptByTask = new Map<string, TaskAttemptSummary>();
-  for (const attempt of attempts) {
+  for (const attempt of taskProgressAttempts(tasks, attempts)) {
     lastAttemptByTask.set(attempt.taskId, attempt);
   }