@xfey/tutti 0.1.94 → 0.1.96

package/dist/collaboration-state/index.d.ts

@@ -10,6 +10,8 @@ export { openNextTaskBoundClarificationRound, openNextTaskCompileClarificationRo
 export { closeTaskBoundClarificationAsRetaskingRequired, materializeClarificationSuccessor, materializeTaskBoundRunSuccessor, submitClarificationRound, } from "./clarification-successors.js";
 export { readRecoverySummariesPage, readRecoverySummaryProjection, readRunResultProjectionByActivityRef, readTaskRunResultsPage, recordRecoverySummary, } from "./run-results.js";
 export { recordRunNeedsHumanResult, recordRunResult } from "./run-recording.js";
+export { materializeTaskRetryRun, readMaterializedTaskRetry } from "./task-retry.js";
+export type { MaterializeTaskRetryResult } from "./task-retry.js";
 export { readStaleRunningTaskIdentities, recoverStaleRunningTasksAsFailed, } from "./recovery.js";
 export { markReadStateScope, readReadStateSummary, recordReadNotificationEvent, } from "./read-state.js";
 export { readTaskDetailProjection } from "./task-details.js";

package/dist/collaboration-state/index.js

@@ -10,6 +10,7 @@ export { openNextTaskBoundClarificationRound, openNextTaskCompileClarificationRo
 export { closeTaskBoundClarificationAsRetaskingRequired, materializeClarificationSuccessor, materializeTaskBoundRunSuccessor, submitClarificationRound, } from "./clarification-successors.js";
 export { readRecoverySummariesPage, readRecoverySummaryProjection, readRunResultProjectionByActivityRef, readTaskRunResultsPage, recordRecoverySummary, } from "./run-results.js";
 export { recordRunNeedsHumanResult, recordRunResult } from "./run-recording.js";
+export { materializeTaskRetryRun, readMaterializedTaskRetry } from "./task-retry.js";
 export { readStaleRunningTaskIdentities, recoverStaleRunningTasksAsFailed, } from "./recovery.js";
 export { markReadStateScope, readReadStateSummary, recordReadNotificationEvent, } from "./read-state.js";
 export { readTaskDetailProjection } from "./task-details.js";

package/dist/collaboration-state/messages.js

@@ -76,6 +76,21 @@ export function mapMessageRow(row, db) {
     if (row.refs_json !== null) {
         message.refs = parseJson(row.refs_json, {});
     }
+    const taskResult = message.refs?.task_result;
+    if (db !== undefined && taskResult?.latest_run_result_id !== undefined) {
+        const runResult = db
+            .prepare("SELECT result_json FROM run_results WHERE id = ?")
+            .get(taskResult.latest_run_result_id);
+        if (runResult !== undefined) {
+            const result = parseJson(runResult.result_json, {});
+            if (result.retry_action === "retryable" || result.retry_action === "retried") {
+                taskResult.retry_action = result.retry_action;
+            }
+            else {
+                delete taskResult.retry_action;
+            }
+        }
+    }
     if (db !== undefined && row.message_kind === "clarification_card") {
         const clarificationCard = readClarificationCardForMessage(db, row.id);
         if (clarificationCard !== undefined) {

package/dist/collaboration-state/run-recording.js

@@ -19,13 +19,30 @@ export function recordRunResult(db, input) {
         const taskStatus = input.result.result_kind === "finished" && input.result.outcome === "completed"
             ? "done"
             : "failed";
-        const resultJson = { ...input.result };
+        const blocksManualRetry = input.result.result_kind === "failed" &&
+            (input.result.error_code === "codex_app_server_output_schema_invalid" ||
+                input.result.error_code === "codex_app_server_auth_failed" ||
+                input.result.error_code === "codex_app_server_session_unavailable" ||
+                input.result.error_code === "codex_app_server_turn_state_unknown" ||
+                input.result.error_code === "codex_app_server_process_lifecycle_failed" ||
+                input.result.error_code === "run_pipeline_failed" ||
+                input.result.error_code.startsWith("workspace_ops_"));
+        const externalSideEffectBlocksRetry = input.result.result_kind === "finished" &&
+            input.result.external_side_effects?.some((effect) => effect.status === "succeeded" || effect.status === "unknown") === true;
+        const retryAction = taskStatus === "failed" && !blocksManualRetry && !externalSideEffectBlocksRetry
+            ? "retryable"
+            : undefined;
+        const resultJson = {
+            ...input.result,
+            ...(retryAction === undefined ? {} : { retry_action: retryAction }),
+        };
         const detailResult = {
             latest_run_result_id: runResultId,
             result_kind: input.result.result_kind,
             run_lineage: input.run_lineage,
             summary: input.result.summary,
             updated_at: createdAt,
+            ...(retryAction === undefined ? {} : { retry_action: retryAction }),
         };
         if (input.result.result_kind === "finished") {
             detailResult.outcome = input.result.outcome;

package/dist/collaboration-state/run-results.js

@@ -31,6 +31,9 @@ export function mapRunResultRow(row) {
             summary: typeof result.summary === "string" ? result.summary : "",
             error_code: typeof result.error_code === "string" ? result.error_code : "unknown",
             retryable: typeof result.retryable === "boolean" ? result.retryable : false,
+            ...(result.retry_action === "retryable" || result.retry_action === "retried"
+                ? { retry_action: result.retry_action }
+                : {}),
         };
     }
     const projection = {
@@ -68,6 +71,9 @@ export function mapRunResultRow(row) {
         projection.external_side_effects =
             result.external_side_effects;
     }
+    if (result.retry_action === "retryable" || result.retry_action === "retried") {
+        projection.retry_action = result.retry_action;
+    }
     return projection;
 }
 export function readRunResultProjectionByActivityRef(db, activityRef) {

package/dist/collaboration-state/task-retry.d.ts

@@ -0,0 +1,16 @@
+import type { ActivityRef, RunResultId, TaskId } from "@tutti/shared/ids";
+import type { RetryTaskDisposition } from "@tutti/shared/schemas/api";
+import { type SqliteDatabase } from "../store/index.js";
+export type MaterializeTaskRetryResult = {
+    disposition: RetryTaskDisposition;
+};
+export declare function readMaterializedTaskRetry(db: SqliteDatabase, runResultId: RunResultId): Extract<RetryTaskDisposition, {
+    kind: "accepted";
+}> | null;
+export declare function materializeTaskRetryRun(db: SqliteDatabase, input: {
+    task_id: TaskId;
+    expected_latest_run_result_id: RunResultId;
+    activity_ref: ActivityRef;
+    now?: () => Date;
+}): MaterializeTaskRetryResult;
+//# sourceMappingURL=task-retry.d.ts.map

package/dist/collaboration-state/task-retry.js

@@ -0,0 +1,136 @@
+import { withHostStoreTransaction } from "../store/index.js";
+import { nowIso, parseJson, stringifyJson } from "./serialization.js";
+import { readTaskDetailProjection } from "./task-details.js";
+import { readTaskProjection } from "./worklist.js";
+import { recordReadNotificationEvent } from "./read-state.js";
+export function readMaterializedTaskRetry(db, runResultId) {
+    const row = db
+        .prepare("SELECT * FROM run_results WHERE id = ?")
+        .get(runResultId);
+    if (row === undefined) {
+        return null;
+    }
+    const result = parseJson(row.result_json, {});
+    if (typeof result.retry_activity_ref !== "string") {
+        return null;
+    }
+    return {
+        kind: "accepted",
+        task_id: row.task_id,
+        activity_ref: result.retry_activity_ref,
+        retried_run_result_id: row.id,
+    };
+}
+function failedResultCanRetry(row, result) {
+    if (result.retry_action === "retryable") {
+        return true;
+    }
+    if (row.result_kind === "failed") {
+        const errorCode = typeof result.error_code === "string" ? result.error_code : "unknown";
+        return (errorCode !== "codex_app_server_output_schema_invalid" &&
+            errorCode !== "codex_app_server_auth_failed" &&
+            errorCode !== "codex_app_server_session_unavailable" &&
+            errorCode !== "codex_app_server_turn_state_unknown" &&
+            errorCode !== "codex_app_server_process_lifecycle_failed" &&
+            errorCode !== "run_pipeline_failed" &&
+            !errorCode.startsWith("workspace_ops_"));
+    }
+    if (row.result_kind !== "finished" || result.outcome !== "failed") {
+        return false;
+    }
+    if (!Array.isArray(result.external_side_effects)) {
+        return true;
+    }
+    return !result.external_side_effects.some((effect) => typeof effect === "object" &&
+        effect !== null &&
+        "status" in effect &&
+        (effect.status === "succeeded" || effect.status === "unknown"));
+}
+export function materializeTaskRetryRun(db, input) {
+    return withHostStoreTransaction(db, (tx) => {
+        const taskRow = tx
+            .prepare("SELECT * FROM tasks WHERE id = ?")
+            .get(input.task_id);
+        if (taskRow === undefined) {
+            return { disposition: { kind: "task_not_failed" } };
+        }
+        if (taskRow.latest_run_result_id !== input.expected_latest_run_result_id) {
+            return {
+                disposition: {
+                    kind: "latest_run_result_changed",
+                    ...(taskRow.latest_run_result_id === null
+                        ? {}
+                        : { latest_run_result_id: taskRow.latest_run_result_id }),
+                },
+            };
+        }
+        if (taskRow.status === "running" && taskRow.current_activity_ref !== null) {
+            return {
+                disposition: {
+                    kind: "already_running",
+                    activity_ref: taskRow.current_activity_ref,
+                },
+            };
+        }
+        if (taskRow.status !== "failed") {
+            return { disposition: { kind: "task_not_failed" } };
+        }
+        const runResultRow = tx
+            .prepare("SELECT * FROM run_results WHERE id = ?")
+            .get(input.expected_latest_run_result_id);
+        if (runResultRow === undefined || runResultRow.task_id !== input.task_id) {
+            return { disposition: { kind: "latest_run_result_changed" } };
+        }
+        const result = parseJson(runResultRow.result_json, {});
+        if (result.retry_activity_ref !== undefined) {
+            return {
+                disposition: {
+                    kind: "retry_already_started",
+                    activity_ref: result.retry_activity_ref,
+                },
+            };
+        }
+        if (!failedResultCanRetry(runResultRow, result)) {
+            return { disposition: { kind: "retry_requires_resolution" } };
+        }
+        const updatedAt = nowIso(input.now);
+        tx.prepare("UPDATE run_results SET result_json = ? WHERE id = ?").run(stringifyJson({
+            ...result,
+            retry_action: "retried",
+            retry_activity_ref: input.activity_ref,
+            retried_at: updatedAt,
+        }), input.expected_latest_run_result_id);
+        tx.prepare(`
+        UPDATE tasks
+        SET status = 'running',
+            current_activity_ref = ?,
+            updated_at = ?
+        WHERE id = ?
+          AND status = 'failed'
+      `).run(input.activity_ref, updatedAt, input.task_id);
+        const detail = readTaskDetailProjection(tx, input.task_id);
+        if (detail === null) {
+            throw new Error("Task retry could not read task detail.");
+        }
+        tx.prepare("UPDATE task_details SET result_json = ?, updated_at = ? WHERE task_id = ?").run(stringifyJson({ ...detail.detail.result, retry_action: "retried", updated_at: updatedAt }), updatedAt, input.task_id);
+        recordReadNotificationEvent(tx, {
+            scope: "worklist",
+            source_kind: "task_run_started",
+            source_ref: input.task_id,
+            occurred_at: updatedAt,
+        });
+        const task = readTaskProjection(tx, input.task_id);
+        if (task === null) {
+            throw new Error("Task retry did not produce a readable task.");
+        }
+        return {
+            disposition: {
+                kind: "accepted",
+                task_id: input.task_id,
+                activity_ref: input.activity_ref,
+                retried_run_result_id: input.expected_latest_run_result_id,
+            },
+        };
+    });
+}
+//# sourceMappingURL=task-retry.js.map

package/dist/control-plane/command-recovery.js

@@ -1,4 +1,4 @@
-import { readClarificationRoundProjection, readRecoverableScheduledRun, readRunResultProjectionByActivityRef, } from "../collaboration-state/index.js";
+import { readClarificationRoundProjection, readRecoverableScheduledRun, readRunResultProjectionByActivityRef, readMaterializedTaskRetry, } from "../collaboration-state/index.js";
 const SUBMIT_CLARIFICATION_ROUND_COMMANDS = new Set([
     "clarification.round.submit",
     "submit_clarification_round",
@@ -10,6 +10,7 @@ const MATERIALIZE_CLARIFICATION_SUCCESSOR_COMMANDS = new Set([
 ]);
 const RECORD_RUN_RESULT_COMMANDS = new Set(["run.result.record", "record_run_result"]);
 const RUN_SCHEDULER_NOW_COMMANDS = new Set(["scheduler.run_now", "runSchedulerNow"]);
+const RETRY_TASK_COMMANDS = new Set(["task.retry"]);
 function completed(disposition) {
     return {
         status: "completed",
@@ -74,6 +75,13 @@ export const resolveControlPlaneCommandRecovery = (db, record) => {
             queued_task_ids: scheduled.queued_task_ids,
         });
     }
+    if (RETRY_TASK_COMMANDS.has(record.command_name)) {
+        if (record.target_ref === null) {
+            return null;
+        }
+        const retry = readMaterializedTaskRetry(db, record.target_ref);
+        return retry === null ? null : completed(retry);
+    }
     return null;
 };
 //# sourceMappingURL=command-recovery.js.map

package/dist/control-plane/index.d.ts

@@ -1,5 +1,5 @@
-import { type ActivityRef, type ClarificationRoundRef, type IdempotencyKey, type WorkflowInvocationRef } from "@tutti/shared/ids";
-import type { ExecutionStatusProjection, MessageProjection, ContextSyncDisposition, ContextSyncResult, RefreshScratchpadDisposition, RefreshScratchpadResult, RunSchedulerNowDisposition, RunSchedulerNowPayload, RefreshReferenceSummariesDisposition, RefreshReferenceSummariesPayload, RefreshReferenceSummariesResult, SendClarificationRoundMessageDisposition, SendClarificationRoundMessagePayload, SendClarificationRoundMessageResult, SubmitClarificationRoundDisposition, SubmitClarificationRoundPayload, SubmitClarificationRoundResult, SubmitWorklistDisposition, SubmitWorklistPayload, SubmitWorklistResult, ProcedureLane } from "@tutti/shared/schemas/api";
+import { type ActivityRef, type ClarificationRoundRef, type IdempotencyKey, type TaskId, type WorkflowInvocationRef } from "@tutti/shared/ids";
+import type { ExecutionStatusProjection, MessageProjection, ContextSyncDisposition, ContextSyncResult, RefreshScratchpadDisposition, RefreshScratchpadResult, RunSchedulerNowDisposition, RunSchedulerNowPayload, RetryTaskDisposition, RetryTaskPayload, RefreshReferenceSummariesDisposition, RefreshReferenceSummariesPayload, RefreshReferenceSummariesResult, SendClarificationRoundMessageDisposition, SendClarificationRoundMessagePayload, SendClarificationRoundMessageResult, SubmitClarificationRoundDisposition, SubmitClarificationRoundPayload, SubmitClarificationRoundResult, SubmitWorklistDisposition, SubmitWorklistPayload, SubmitWorklistResult, ProcedureLane } from "@tutti/shared/schemas/api";
 import type { ContextSyncWorkflowTrigger } from "./workflows/index.js";
 import type { ControlPlaneCommandResult, Phase5ControlPlaneOptions, StartupRecoveryOptions, StartupRecoveryResult, TrustedHumanAuthor } from "./types.js";
 import { type ProjectBriefRefreshReason, type RefreshProjectBriefProjectionResult } from "./project-brief-refresh.js";
@@ -18,6 +18,7 @@ export declare class Phase5ControlPlane {
     private readonly runLifecycle;
     private readonly now;
     private readonly scratchpadAutoRefreshScheduler;
+    private pendingWorklistCompletionContextSyncTimer;
     private readonly pendingReferenceSummaryPaths;
     private readonly referenceSummaryWaiters;
     private pendingAllReferenceSummaries;
@@ -28,6 +29,7 @@ export declare class Phase5ControlPlane {
     constructor(options: Phase5ControlPlaneOptions);
     getExecutionStatus(): ExecutionStatusProjection;
     runSchedulerNow(payload?: RunSchedulerNowPayload): ControlPlaneCommandResult<RunSchedulerNowDisposition, never>;
+    retryTask(taskId: TaskId, payload: RetryTaskPayload): ControlPlaneCommandResult<RetryTaskDisposition, never>;
     runStartupRecovery(options?: StartupRecoveryOptions): StartupRecoveryResult;
     startScratchpadRefresh(options?: {
         lane?: ProcedureLane;
@@ -66,7 +68,9 @@ export declare class Phase5ControlPlane {
     private tryRunTaskArrivalScheduler;
     private maybeScheduleAfterRunCompletion;
     private worklistCompletionContextSyncTrigger;
-    private maybeStartContextSyncAfterWorklistCompletion;
+    private scheduleContextSyncAfterWorklistCompletion;
+    private attemptContextSyncAfterWorklistCompletion;
+    private cancelPendingWorklistCompletionContextSync;
     private startTaskCompileContinuation;
     private startTaskBoundFollowUpCheck;
     private publishProcedureTransition;

package/dist/control-plane/index.js

@@ -1,7 +1,7 @@
-import { readActiveTaskCompileContext, readWorklistProjection, } from "../collaboration-state/index.js";
+import { readActiveTaskCompileContext, readScratchpadSourceState, readWorklistProjection, } from "../collaboration-state/index.js";
 import { ProcedureEngine } from "../procedure-engine/index.js";
 import { RunEngine } from "../run-engine/index.js";
-import { WorkspaceOpsError, readReferenceSummaryTargets, } from "../workspace-ops/index.js";
+import { WorkspaceOpsError, readReferenceSummaryTargets } from "../workspace-ops/index.js";
 import { publishProcedureTransition as publishProcedureTransitionEvent, publishRunResultRecorded as publishRunResultRecordedEvent, publishRunTransition as publishRunTransitionEvent, publishTaskRunStarted as publishTaskRunStartedEvent, } from "./event-publishers.js";
 import { startContextSyncAnalysisProcedure } from "./context-sync.js";
 import { refreshProjectBriefProjection, } from "./project-brief-refresh.js";
@@ -16,8 +16,10 @@ import { startControlPlaneTaskCompileContinuation } from "./task-compile-continu
 import { startControlPlaneTaskBoundFollowUpCheck } from "./follow-up-start.js";
 import { runControlPlaneSchedulerForTaskArrival, runControlPlaneSchedulerNow, } from "./run-scheduler.js";
 import { startControlPlaneRunForTask } from "./run-start.js";
+import { retryControlPlaneTask } from "./run-retry.js";
 import { runSendClarificationRoundMessage, runSubmitClarificationRound, } from "./clarification-commands.js";
 import { emitTaskCompletedResultMessage, emitTaskFailedResultMessage, } from "./worklist-terminal-feedback.js";
+const WORKLIST_COMPLETION_CONTEXT_SYNC_GRACE_MS = 30_000;
 export class Phase5ControlPlane {
     engine;
     runEngine;
@@ -32,6 +34,7 @@ export class Phase5ControlPlane {
     runLifecycle;
     now;
     scratchpadAutoRefreshScheduler;
+    pendingWorklistCompletionContextSyncTimer = null;
     pendingReferenceSummaryPaths = new Set();
     referenceSummaryWaiters = new Map();
     pendingAllReferenceSummaries = false;
@@ -82,6 +85,19 @@ export class Phase5ControlPlane {
             now: this.now,
         });
     }
+    retryTask(taskId, payload) {
+        return retryControlPlaneTask({
+            store: this.store,
+            taskId,
+            payload,
+            resolveRunPipeline: this.resolveRunPipeline,
+            readActiveActivity: () => this.readSchedulerBlocker(),
+            startRunForTask: (runInput) => {
+                void this.startRunForTask(runInput);
+            },
+            now: this.now,
+        });
+    }
     runStartupRecovery(options = {}) {
         return runControlPlaneStartupRecovery({
             store: this.store,
@@ -98,6 +114,7 @@ export class Phase5ControlPlane {
         });
     }
     startScratchpadRefresh(options = {}) {
+        this.cancelPendingWorklistCompletionContextSync();
         return startControlPlaneScratchpadRefresh({
             engine: this.engine,
             store: this.store,
@@ -114,6 +131,7 @@ export class Phase5ControlPlane {
         if (!shouldUseMessageAsScratchpadSource(message)) {
             return;
         }
+        this.cancelPendingWorklistCompletionContextSync();
         this.scratchpadAutoRefreshScheduler.notifySourceChanged();
     }
     refreshProjectBrief(options) {
@@ -134,6 +152,7 @@ export class Phase5ControlPlane {
         }
         this.closing = true;
         this.scratchpadAutoRefreshScheduler.dispose();
+        this.cancelPendingWorklistCompletionContextSync();
         this.pendingAllReferenceSummaries = false;
         this.pendingReferenceSummaryPaths.clear();
     }
@@ -157,6 +176,7 @@ export class Phase5ControlPlane {
         }
     }
     startTaskCompile(payload) {
+        this.cancelPendingWorklistCompletionContextSync();
         const activeRun = this.readActiveRun();
         if (activeRun !== null) {
             return {
@@ -197,6 +217,9 @@ export class Phase5ControlPlane {
         });
     }
     startContextSyncAnalysis(trigger = { kind: "manual" }) {
+        if (trigger.kind === "manual") {
+            this.cancelPendingWorklistCompletionContextSync();
+        }
         return startContextSyncAnalysisProcedure({
             engine: this.engine,
             store: this.store,
@@ -352,6 +375,7 @@ export class Phase5ControlPlane {
             publishRunResultRecorded: (recorded) => this.publishRunResultRecorded(recorded),
         });
         if (result.kind === "accepted") {
+            this.cancelPendingWorklistCompletionContextSync();
             this.runLifecycle?.started();
         }
         return result;
@@ -483,7 +507,7 @@ export class Phase5ControlPlane {
         if (this.tryRunTaskArrivalScheduler()) {
             return;
         }
-        this.maybeStartContextSyncAfterWorklistCompletion();
+        this.scheduleContextSyncAfterWorklistCompletion();
     }
     worklistCompletionContextSyncTrigger() {
         const worklist = readWorklistProjection(this.store.db);
@@ -497,16 +521,46 @@ export class Phase5ControlPlane {
             module_count: worklist.modules.length,
         };
     }
-    maybeStartContextSyncAfterWorklistCompletion() {
-        if (this.closing) {
+    scheduleContextSyncAfterWorklistCompletion() {
+        if (this.closing ||
+            !this.store.db.open ||
+            this.pendingWorklistCompletionContextSyncTimer !== null) {
+            return;
+        }
+        const sourceState = readScratchpadSourceState(this.store.db);
+        if (this.worklistCompletionContextSyncTrigger() === undefined ||
+            sourceState.dirty_since !== undefined ||
+            sourceState.in_flight !== undefined ||
+            this.readSchedulerBlocker() !== null) {
+            return;
+        }
+        this.pendingWorklistCompletionContextSyncTimer = setTimeout(() => {
+            this.attemptContextSyncAfterWorklistCompletion();
+        }, WORKLIST_COMPLETION_CONTEXT_SYNC_GRACE_MS);
+        this.pendingWorklistCompletionContextSyncTimer.unref?.();
+    }
+    attemptContextSyncAfterWorklistCompletion() {
+        this.pendingWorklistCompletionContextSyncTimer = null;
+        if (this.closing || !this.store.db.open) {
             return;
         }
         const trigger = this.worklistCompletionContextSyncTrigger();
-        if (trigger === undefined || this.readSchedulerBlocker() !== null) {
+        const sourceState = readScratchpadSourceState(this.store.db);
+        if (trigger === undefined ||
+            sourceState.dirty_since !== undefined ||
+            sourceState.in_flight !== undefined ||
+            this.readSchedulerBlocker() !== null) {
             return;
         }
         void this.startContextSyncAnalysis(trigger);
     }
+    cancelPendingWorklistCompletionContextSync() {
+        if (this.pendingWorklistCompletionContextSyncTimer === null) {
+            return;
+        }
+        clearTimeout(this.pendingWorklistCompletionContextSyncTimer);
+        this.pendingWorklistCompletionContextSyncTimer = null;
+    }
     startTaskCompileContinuation(owner, roundId) {
         let tasksAdded = false;
         return startControlPlaneTaskCompileContinuation({
@@ -556,6 +610,9 @@ export class Phase5ControlPlane {
         });
     }
     publishProcedureTransition(state) {
+        if (state.transition_kind === "started" && state.activity.lane === "foreground") {
+            this.cancelPendingWorklistCompletionContextSync();
+        }
         this.logProcedureTransition(state);
         publishProcedureTransitionEvent({
             events: this.events,
@@ -582,6 +639,11 @@ export class Phase5ControlPlane {
             }
             if (!this.closing) {
                 this.schedulePendingReferenceSummaryRefresh();
+                if (state.activity.status === "finished" &&
+                    (state.activity.workflow_kind === "scratchpad_refresh" ||
+                        state.activity.workflow_kind === "reference_summary_refresh")) {
+                    this.scheduleContextSyncAfterWorklistCompletion();
+                }
             }
         }
     }

package/dist/control-plane/run-retry.d.ts

@@ -0,0 +1,19 @@
+import { type ActivityRef, type TaskId } from "@tutti/shared/ids";
+import type { RetryTaskDisposition, RetryTaskPayload } from "@tutti/shared/schemas/api";
+import type { HostProjectStore } from "../store/index.js";
+import type { StartRunForTaskInput } from "./run-start.js";
+import type { ControlPlaneCommandResult, RunPipelineResolver } from "./types.js";
+type ActiveActivity = {
+    activity_ref: ActivityRef;
+};
+export declare function retryControlPlaneTask(input: {
+    store: HostProjectStore;
+    taskId: TaskId;
+    payload: RetryTaskPayload;
+    resolveRunPipeline: RunPipelineResolver | undefined;
+    readActiveActivity: () => ActiveActivity | null;
+    startRunForTask: (run: StartRunForTaskInput) => void;
+    now: () => Date;
+}): ControlPlaneCommandResult<RetryTaskDisposition, never>;
+export {};
+//# sourceMappingURL=run-retry.d.ts.map

package/dist/control-plane/run-retry.js

@@ -0,0 +1,103 @@
+import { createActivityRef, } from "@tutti/shared/ids";
+import { materializeTaskRetryRun, readNextRunnableTask, readTaskDetailProjection, readTaskRunResultsPage, } from "../collaboration-state/index.js";
+import { toDomainRunLineage } from "./run-lineage.js";
+function retryCorrectionContext(result, detail) {
+    const resultProjection = detail.detail.result;
+    const reasonCode = result.result_kind === "failed"
+        ? result.error_code
+        : resultProjection.checks === "failed"
+            ? "checks_failed"
+            : resultProjection.promotion?.reason_code ?? "previous_run_failed";
+    return {
+        previous_provider_result: result.result_kind === "finished"
+            ? {
+                decision: "completed",
+                summary: result.summary,
+                ...(result.user_note_candidate === undefined
+                    ? {}
+                    : { user_note_candidate: result.user_note_candidate }),
+            }
+            : { decision: "failed", summary: result.summary },
+        summary: result.summary,
+        reason_code: reasonCode,
+        guidance: "Continue the same task from the retained project state and correct the problem that caused the previous Run to fail.",
+        diagnostic: {
+            source: "previous_run_result",
+            text: result.summary,
+            truncated: false,
+        },
+        promotion_failure: resultProjection.promotion?.status === "not_promoted"
+            ? {
+                reason_code: resultProjection.promotion.reason_code ?? reasonCode,
+                summary: resultProjection.promotion.summary ?? result.summary,
+            }
+            : null,
+    };
+}
+export function retryControlPlaneTask(input) {
+    const active = input.readActiveActivity();
+    if (active !== null) {
+        return { disposition: { kind: "already_running", activity_ref: active.activity_ref } };
+    }
+    const pipelineResolution = input.resolveRunPipeline?.();
+    if (pipelineResolution === undefined || pipelineResolution.kind === "not_configured") {
+        return { disposition: { kind: "provider_not_configured" } };
+    }
+    if (pipelineResolution.kind === "unavailable") {
+        return {
+            disposition: {
+                kind: "provider_unavailable",
+                reason: pipelineResolution.reason,
+                retryable: pipelineResolution.retryable,
+            },
+        };
+    }
+    const latestResult = readTaskRunResultsPage(input.store.db, input.taskId, { limit: 1 })?.items[0];
+    const detail = readTaskDetailProjection(input.store.db, input.taskId);
+    if (latestResult === undefined || detail === null) {
+        return { disposition: { kind: "task_not_failed" } };
+    }
+    const activityRef = createActivityRef();
+    const materialized = materializeTaskRetryRun(input.store.db, {
+        task_id: input.taskId,
+        expected_latest_run_result_id: input.payload.expected_latest_run_result_id,
+        activity_ref: activityRef,
+        now: input.now,
+    });
+    if (materialized.disposition.kind !== "accepted") {
+        return materialized;
+    }
+    const taskDetail = readTaskDetailProjection(input.store.db, input.taskId);
+    if (taskDetail === null) {
+        return { disposition: { kind: "retry_requires_resolution" } };
+    }
+    const parentLineage = toDomainRunLineage(latestResult.run_lineage);
+    const runLineage = {
+        kind: "retry",
+        attempt: parentLineage.attempt + 1,
+        parent_activity_ref: latestResult.activity_ref,
+        root_activity_ref: parentLineage.root_activity_ref ?? latestResult.activity_ref,
+    };
+    const next = readNextRunnableTask(input.store.db);
+    const orderedTaskRefs = next.kind === "found"
+        ? [input.taskId, ...next.queued_task_ids.filter((taskId) => taskId !== input.taskId)]
+        : [input.taskId];
+    const dispatchContext = {
+        trigger: "recovery",
+        queue_scope: { kind: "worklist" },
+        current_task_id: input.taskId,
+        ordered_task_refs: orderedTaskRefs,
+        current_module_id: taskDetail.task.module_id,
+    };
+    input.startRunForTask({
+        activity_ref: activityRef,
+        task: taskDetail.task,
+        task_detail: taskDetail,
+        run_lineage: runLineage,
+        dispatch_context: dispatchContext,
+        correction_context: retryCorrectionContext(latestResult, detail),
+        runner: pipelineResolution.runner,
+    });
+    return materialized;
+}
+//# sourceMappingURL=run-retry.js.map

package/dist/control-plane/run-start.d.ts

@@ -4,7 +4,7 @@ import type { TaskDetailProjection, TaskProjection } from "@tutti/shared/schemas
 import type { RunEngine, RunEngineState, StartRunResult } from "../run-engine/index.js";
 import type { HostProjectStore } from "../store/index.js";
 import { recordRunPipelineResult } from "./run-result-recording.js";
-import type { ControlPlaneLogger, Phase5ControlPlaneOptions, RunContinuationContext, RunDispatchContext, RunPipelineRunner } from "./types.js";
+import type { ControlPlaneLogger, Phase5ControlPlaneOptions, RunCorrectionContext, RunContinuationContext, RunDispatchContext, RunPipelineRunner } from "./types.js";
 export type StartRunForTaskInput = {
     activity_ref: ActivityRef;
     task: TaskProjection;
@@ -12,6 +12,7 @@ export type StartRunForTaskInput = {
     run_lineage: RunLineage;
     dispatch_context: RunDispatchContext;
     continuation_context?: RunContinuationContext;
+    correction_context?: RunCorrectionContext;
     runner: RunPipelineRunner;
 };
 export type RunResultRecordedPublisher = (recorded: ReturnType<typeof recordRunPipelineResult>["recorded"]) => void;

package/dist/control-plane/run-start.js

@@ -107,6 +107,9 @@ export function startControlPlaneRunForTask(input) {
                     ...(input.run.continuation_context === undefined
                         ? {}
                         : { continuation_context: input.run.continuation_context }),
+                    ...(input.run.correction_context === undefined
+                        ? {}
+                        : { correction_context: input.run.correction_context }),
                     ...(sourceMessages.length === 0 ? {} : { source_messages: sourceMessages }),
                     ...(clarificationRounds.length === 0
                         ? {}