@xfey/tutti 0.1.66 → 0.1.68

package/dist/control-plane/reference-summary-refresh.js

@@ -2,6 +2,8 @@ import { createWorkflowInvocationRef } from "@tutti/shared/ids";
 import { recordProjectTimelineEvent } from "../project-timeline/index.js";
 import { WorkspaceOpsError, readReferenceSummaryTargets, updateReferenceSummaries, } from "../workspace-ops/index.js";
 import { logProcedureExecutionError } from "./procedure-logging.js";
+const REFERENCE_SUMMARY_CONCURRENCY = 2;
+const REFERENCE_SUMMARY_MAX_ATTEMPTS = 2;
 function publishReferenceSummaryTimelineChanged(input) {
     input.events.publish({
         event_type: "query.invalidate",
@@ -62,111 +64,104 @@ function logNotStarted(input) {
     }, "Reference summary refresh not started");
 }
 async function runReferenceSummaryRefresh(options) {
-    const summaries = [];
+    let targets = options.targets;
+    const processedTargets = new Set();
+    let targetCount = 0;
+    let updatedCount = 0;
     let failedCount = 0;
     let adapterUnavailableCount = 0;
-    for (const target of options.targets) {
+    let lastCommitOid;
+    while (targets.length !== 0) {
+        const batch = targets.filter((target) => !processedTargets.has(`${target.path}\u0000${target.blob_oid}`));
+        if (batch.length === 0) {
+            break;
+        }
+        for (const target of batch) {
+            processedTargets.add(`${target.path}\u0000${target.blob_oid}`);
+        }
+        targetCount += batch.length;
+        options.reportProgress?.({
+            phase: "reference_summary_batch",
+            summary: `Summarizing ${batch.length} reference file${batch.length === 1 ? "" : "s"}.`,
+        });
+        let completedInBatch = 0;
+        const batchResults = await mapWithConcurrency(batch, REFERENCE_SUMMARY_CONCURRENCY, async (target) => {
+            const result = await summarizeReferenceTarget({
+                target,
+                runner: options.runner,
+                workflowRef: options.workflowRef,
+                activityRef: options.activityRef,
+                logger: options.logger,
+                now: options.now,
+            });
+            completedInBatch += 1;
+            options.reportProgress?.({
+                phase: "reference_summary_batch",
+                summary: `Processed ${completedInBatch} of ${batch.length} reference files.`,
+            });
+            return result;
+        });
+        const summaries = batchResults.map((entry) => entry.summary);
+        failedCount += batchResults.filter((entry) => entry.failed).length;
+        adapterUnavailableCount += batchResults.filter((entry) => entry.adapterUnavailable).length;
+        let result;
         try {
-            const output = await options.runner.runReferenceFileSummary?.({
-                workflow_ref: options.workflowRef,
-                activity_ref: options.activityRef,
-                file: {
-                    path: target.path,
-                    name: target.name,
-                    category: target.category,
-                    size_bytes: target.size_bytes,
-                    blob_oid: target.blob_oid,
-                    ...(target.media_type === undefined ? {} : { media_type: target.media_type }),
-                },
-            }, {
-                workflow_ref: options.workflowRef,
-                activity_ref: options.activityRef,
-                ...(options.reportProgress === undefined
-                    ? {}
-                    : { reportProgress: options.reportProgress }),
+            result = updateReferenceSummaries({
+                workspaceRoot: options.projectContext.workspaceRoot,
+                summaries,
+                now: options.now,
             });
-            if (output === undefined) {
-                adapterUnavailableCount += 1;
-                summaries.push({
-                    path: target.path,
-                    status: "unavailable",
-                    generated_at: options.now().toISOString(),
-                    source_blob_oid: target.blob_oid,
-                    unavailable_reason: "summary_adapter_unavailable",
-                });
-                continue;
-            }
-            summaries.push(summaryRecordFromOutput({
-                target,
-                output,
-                generatedAt: options.now().toISOString(),
-            }));
         }
         catch (error) {
-            failedCount += 1;
-            options.logger?.info({
-                workflow_ref: options.workflowRef,
+            recordProjectTimelineEvent(options.store.db, {
+                event_kind: "reference_summary",
+                status: "failed",
+                summary: "Reference summary write failed.",
                 activity_ref: options.activityRef,
-                path: target.path,
-                error_name: error instanceof Error ? error.name : "UnknownError",
-            }, "Reference summary target failed");
-            summaries.push({
-                path: target.path,
-                status: "unavailable",
-                generated_at: options.now().toISOString(),
-                source_blob_oid: target.blob_oid,
-                unavailable_reason: "summary_failed",
+                workflow_ref: options.workflowRef,
+                meta: [
+                    `target count: ${targetCount}`,
+                    `error: ${error instanceof Error ? error.name : "UnknownError"}`,
+                ],
+                now: options.now,
+            });
+            publishReferenceSummaryTimelineChanged({
+                events: options.events,
+                message: "Reference summary timeline updated.",
             });
+            throw error;
         }
-    }
-    let result;
-    try {
-        result = updateReferenceSummaries({
-            workspaceRoot: options.projectContext.workspaceRoot,
-            summaries,
-            now: options.now,
-        });
-    }
-    catch (error) {
-        recordProjectTimelineEvent(options.store.db, {
-            event_kind: "reference_summary",
-            status: "failed",
-            summary: "Reference summary write failed.",
-            activity_ref: options.activityRef,
-            workflow_ref: options.workflowRef,
-            meta: [
-                `target count: ${options.targets.length}`,
-                `error: ${error instanceof Error ? error.name : "UnknownError"}`,
-            ],
+        updatedCount += result.updated_paths.length;
+        if (result.commit_oid !== undefined) {
+            lastCommitOid = result.commit_oid;
+        }
+        targets = readTargets({
+            projectContext: options.projectContext,
             now: options.now,
-        });
-        publishReferenceSummaryTimelineChanged({
-            events: options.events,
-            message: "Reference summary timeline updated.",
-        });
-        throw error;
+        }).filter((target) => (target.summary.status === "missing" || target.summary.status === "stale") &&
+            !processedTargets.has(`${target.path}\u0000${target.blob_oid}`));
     }
     options.logger?.info({
         workflow_ref: options.workflowRef,
         activity_ref: options.activityRef,
-        target_count: options.targets.length,
-        updated_count: result.updated_paths.length,
+        target_count: targetCount,
+        updated_count: updatedCount,
         failed_count: failedCount,
         adapter_unavailable_count: adapterUnavailableCount,
-        ...(result.commit_oid === undefined ? {} : { commit_oid: result.commit_oid }),
+        ...(lastCommitOid === undefined ? {} : { commit_oid: lastCommitOid }),
     }, "Reference summaries refreshed");
     recordProjectTimelineEvent(options.store.db, {
         event_kind: "reference_summary",
         status: "completed",
-        summary: result.updated_paths.length === 0
+        summary: updatedCount === 0
             ? "Reference summaries already up to date."
-            : `Updated ${result.updated_paths.length} reference summaries.`,
+            : `Updated ${updatedCount} reference summaries.`,
         activity_ref: options.activityRef,
         workflow_ref: options.workflowRef,
-        ...(result.commit_oid === undefined ? {} : { commit_oid: result.commit_oid }),
+        ...(lastCommitOid === undefined ? {} : { commit_oid: lastCommitOid }),
         meta: [
-            `target count: ${options.targets.length}`,
-            `updated paths: ${result.updated_paths.length}`,
+            `target count: ${targetCount}`,
+            `updated paths: ${updatedCount}`,
             `failed targets: ${failedCount}`,
             `adapter unavailable: ${adapterUnavailableCount}`,
         ],
@@ -175,7 +170,7 @@ async function runReferenceSummaryRefresh(options) {
     publishReferenceSummaryTimelineChanged({
         events: options.events,
         message: "Reference summary timeline updated.",
-        ...(result.updated_paths.length !== 0
+        ...(updatedCount !== 0
             ? {
                 invalidates: [
                     { kind: "viewer", path: "docs/reference" },
@@ -188,12 +183,96 @@ async function runReferenceSummaryRefresh(options) {
     });
     return {
         kind: "completed",
-        summary: result.updated_paths.length === 0
+        summary: updatedCount === 0
             ? "Reference summaries already up to date."
-            : `Updated ${result.updated_paths.length} reference summaries.`,
+            : `Updated ${updatedCount} reference summaries.`,
         result_anchor: { kind: "workflow", workflow_ref: options.workflowRef },
     };
 }
+async function mapWithConcurrency(items, concurrency, worker) {
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    const workers = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+        while (nextIndex < items.length) {
+            const index = nextIndex;
+            nextIndex += 1;
+            const item = items[index];
+            if (item !== undefined) {
+                results[index] = await worker(item);
+            }
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}
+async function summarizeReferenceTarget(options) {
+    for (let attempt = 1; attempt <= REFERENCE_SUMMARY_MAX_ATTEMPTS; attempt += 1) {
+        try {
+            const output = await options.runner.runReferenceFileSummary?.({
+                workflow_ref: options.workflowRef,
+                activity_ref: options.activityRef,
+                file: {
+                    path: options.target.path,
+                    name: options.target.name,
+                    category: options.target.category,
+                    size_bytes: options.target.size_bytes,
+                    blob_oid: options.target.blob_oid,
+                    ...(options.target.media_type === undefined
+                        ? {}
+                        : { media_type: options.target.media_type }),
+                },
+            });
+            if (output === undefined) {
+                return {
+                    summary: {
+                        path: options.target.path,
+                        status: "unavailable",
+                        generated_at: options.now().toISOString(),
+                        source_blob_oid: options.target.blob_oid,
+                        unavailable_reason: "summary_adapter_unavailable",
+                    },
+                    failed: false,
+                    adapterUnavailable: true,
+                };
+            }
+            return {
+                summary: summaryRecordFromOutput({
+                    target: options.target,
+                    output,
+                    generatedAt: options.now().toISOString(),
+                }),
+                failed: false,
+                adapterUnavailable: false,
+            };
+        }
+        catch (error) {
+            options.logger?.info({
+                workflow_ref: options.workflowRef,
+                activity_ref: options.activityRef,
+                path: options.target.path,
+                attempt,
+                retrying: attempt < REFERENCE_SUMMARY_MAX_ATTEMPTS,
+                error_name: error instanceof Error ? error.name : "UnknownError",
+            }, attempt < REFERENCE_SUMMARY_MAX_ATTEMPTS
+                ? "Reference summary target retrying"
+                : "Reference summary target failed");
+            if (attempt === REFERENCE_SUMMARY_MAX_ATTEMPTS) {
+                return {
+                    summary: {
+                        path: options.target.path,
+                        status: "unavailable",
+                        generated_at: options.now().toISOString(),
+                        source_blob_oid: options.target.blob_oid,
+                        unavailable_reason: "summary_failed",
+                    },
+                    failed: true,
+                    adapterUnavailable: false,
+                };
+            }
+        }
+    }
+    throw new Error("Reference summary retry loop ended unexpectedly");
+}
 export function startReferenceSummaryRefreshProcedure(input) {
     const activeActivity = input.readActiveActivity();
     const requestedPathCount = input.paths?.length ?? 0;
@@ -268,23 +347,6 @@ export function startReferenceSummaryRefreshProcedure(input) {
             },
         };
     }
-    if (runnerResolution.runner.runReferenceFileSummary === undefined) {
-        logNotStarted({
-            logger: input.logger,
-            disposition: "provider_unavailable",
-            requestedPathCount,
-            targetCount: targets.length,
-            reason: "provider_model_unavailable",
-            retryable: false,
-        });
-        return {
-            disposition: {
-                kind: "provider_unavailable",
-                reason: "provider_model_unavailable",
-                retryable: false,
-            },
-        };
-    }
     const workflowRef = createWorkflowInvocationRef();
     const projectContext = input.projectContext;
     const start = input.engine.startProcedure({
@@ -302,18 +364,24 @@ export function startReferenceSummaryRefreshProcedure(input) {
             activityRef: context.activity_ref,
             error,
         }),
-        execute: async (context) => runReferenceSummaryRefresh({
-            store: input.store,
-            runner: runnerResolution.runner,
-            workflowRef,
-            activityRef: context.activity_ref,
-            targets,
-            projectContext,
-            events: input.events,
-            logger: input.logger,
-            reportProgress: context.reportProgress,
-            now: input.now,
-        }),
+        execute: async (context) => {
+            input.onExecuteStart?.({
+                activityRef: context.activity_ref,
+                workflowRef,
+            });
+            return runReferenceSummaryRefresh({
+                store: input.store,
+                runner: runnerResolution.runner,
+                workflowRef,
+                activityRef: context.activity_ref,
+                targets,
+                projectContext,
+                events: input.events,
+                logger: input.logger,
+                reportProgress: context.reportProgress,
+                now: input.now,
+            });
+        },
     });
     if (start.kind === "already_running") {
         logNotStarted({

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

@@ -1,3 +1,4 @@
+import { materializeWorkflowRecentReferences } from "./recent-references.js";
 import { recordRunPipelineFailure, recordRunPipelineResult, } from "./run-result-recording.js";
 import { projectBriefShouldRefreshForUpdatedPaths, refreshProjectBriefProjection, } from "./project-brief-refresh.js";
 function runLineageFields(lineage) {
@@ -79,6 +80,14 @@ export function startControlPlaneRunForTask(input) {
             const pipelineStartedAt = input.now();
             input.logger?.info(lifecycleFields, "Run pipeline started");
             try {
+                const recentReferences = input.projectContext === undefined
+                    ? []
+                    : materializeWorkflowRecentReferences({
+                        db: input.store.db,
+                        workspaceRoot: input.projectContext.workspaceRoot,
+                        workflowRef: input.run.task.created_from_workflow_ref,
+                        now: input.now,
+                    });
                 const pipelineResult = await input.run.runner.runTask({
                     activity_ref: context.activity_ref,
                     task: input.run.task,
@@ -88,6 +97,9 @@ export function startControlPlaneRunForTask(input) {
                     ...(input.run.continuation_context === undefined
                         ? {}
                         : { continuation_context: input.run.continuation_context }),
+                    ...(recentReferences.length === 0
+                        ? {}
+                        : { recent_references: recentReferences }),
                     on_stage: (progress) => context.reportProgress({
                         phase: progress.stage,
                         summary: runStageSummary(input.run, progress),

package/dist/control-plane/task-compile-continuation.d.ts

@@ -3,6 +3,7 @@ import type { ProcedureEngine, ProcedureEngineState } from "../procedure-engine/
 import type { WorkspaceEventBus } from "../server-shell/http/workspace-events.js";
 import type { HostProjectStore } from "../store/index.js";
 import type { ControlPlaneLogger } from "./types.js";
+import type { Phase5ControlPlaneOptions } from "./types.js";
 import type { ProcedureWorkflowRunnerResolver } from "./workflows/index.js";
 export declare function startControlPlaneTaskCompileContinuation(options: {
     engine: ProcedureEngine;
@@ -17,6 +18,7 @@ export declare function startControlPlaneTaskCompileContinuation(options: {
     };
     roundId: ClarificationRoundRef;
     resolveWorkflowRunner: ProcedureWorkflowRunnerResolver;
+    projectContext: Phase5ControlPlaneOptions["projectContext"] | undefined;
     logger?: ControlPlaneLogger | undefined;
     now: () => Date;
     publishProcedureTransition: (state: ProcedureEngineState) => void;

package/dist/control-plane/task-compile-continuation.js

@@ -4,6 +4,7 @@ import { clarificationInvalidates } from "./invalidations.js";
 import { applyTaskCompileProcedureOutput } from "./task-compile-output.js";
 import { readTaskCompileClarificationRounds } from "./task-compile-clarification-context.js";
 import { logProcedureExecutionError } from "./procedure-logging.js";
+import { materializeRecentReferences, readRecentReferenceSources, } from "./recent-references.js";
 export function startControlPlaneTaskCompileContinuation(options) {
     if (options.owner.kind !== "task_compile") {
         return false;
@@ -43,10 +44,20 @@ export function startControlPlaneTaskCompileContinuation(options) {
                     workflowRef,
                     throughRoundId: options.roundId,
                 });
+                const recentReferences = options.projectContext === undefined
+                    ? []
+                    : materializeRecentReferences({
+                        workspaceRoot: options.projectContext.workspaceRoot,
+                        sources: readRecentReferenceSources(options.store.db, taskCompileContext.sources),
+                        now: options.now,
+                    });
                 const output = await runnerResolution.runner.runTaskCompile({
                     workflow_ref: workflowRef,
                     scratchpad: taskCompileContext.scratchpad_snapshot,
                     worklist: readWorklistProjection(options.store.db),
+                    ...(recentReferences.length === 0
+                        ? {}
+                        : { recent_references: recentReferences }),
                     clarification_rounds: clarificationRounds,
                 }, {
                     workflow_ref: workflowRef,

package/dist/control-plane/task-compile-start.d.ts

@@ -15,6 +15,7 @@ export declare function startControlPlaneTaskCompile(options: {
     logger: ControlPlaneLogger | undefined;
     now: () => Date;
     publishProcedureTransition: (state: ProcedureEngineState) => void;
+    registerReferenceSummaryWaiter: (activityRef: ActivityRef, waiter: (state: ProcedureEngineState) => void) => void;
     onTasksAdded: () => void;
 }): ControlPlaneCommandResult<SubmitWorklistDisposition, SubmitWorklistResult>;
 export declare function runControlPlaneTaskCompileProcedure(options: {
@@ -23,6 +24,7 @@ export declare function runControlPlaneTaskCompileProcedure(options: {
     activityRef: ActivityRef;
     store: HostProjectStore;
     events: WorkspaceEventBus;
+    projectContext: Phase5ControlPlaneOptions["projectContext"] | undefined;
     now: () => Date;
     onTasksAdded: () => void;
     reportProgress?: (progress: ProcedureProgressUpdate) => void;

package/dist/control-plane/task-compile-start.js

@@ -1,11 +1,13 @@
 import { createWorkflowInvocationRef, } from "@tutti/shared/ids";
-import { captureTaskCompileContext, readActiveTaskCompileContext, readScratchpadProjection, readWorklistProjection, rollbackTaskCompileContext, } from "../collaboration-state/index.js";
+import { captureTaskCompileContext, readActiveTaskCompileContext, readCurrentScratchpadSourceRefs, readScratchpadProjection, readWorklistProjection, rollbackTaskCompileContext, } from "../collaboration-state/index.js";
 import { initializeProjectDocs, readProjectDocsInitializationStatus, } from "../workspace-ops/index.js";
 import { logProcedureExecutionError } from "./procedure-logging.js";
 import { projectBriefShouldRefreshForUpdatedPaths, refreshProjectBriefProjection, } from "./project-brief-refresh.js";
 import { applyProjectDocsInitializationResult, buildProjectDocsInitializationContext, tryProjectContextBootstrapDocuments, } from "./project-context-bootstrap.js";
 import { readActiveScratchpadRefreshActivityRef, readControlPlaneScratchpadSourceBatch, runControlPlaneScratchpadRefreshProcedure, } from "./scratchpad-refresh-start.js";
 import { applyTaskCompileProcedureOutput } from "./task-compile-output.js";
+import { materializeRecentReferences, readPendingRecentReferenceSummaryPaths, readRecentReferenceSources, } from "./recent-references.js";
+import { startReferenceSummaryRefreshProcedure } from "./reference-summary-refresh.js";
 export function startControlPlaneTaskCompile(options) {
     const activeContext = readActiveTaskCompileContext(options.store.db);
     if (activeContext !== null) {
@@ -26,7 +28,6 @@ export function startControlPlaneTaskCompile(options) {
             },
         };
     }
-    const shouldInitializeProjectContext = shouldInitializeControlPlaneProjectContext(options);
     const runnerResolution = options.resolveWorkflowRunner();
     if (runnerResolution.kind === "not_configured") {
         return { disposition: { kind: "provider_not_configured" } };
@@ -65,14 +66,7 @@ export function startControlPlaneTaskCompile(options) {
     if (!scratchpadHasSubmittableContent(scratchpad)) {
         return { disposition: { kind: "scratchpad_empty" } };
     }
-    if (shouldInitializeProjectContext) {
-        return startProjectContextBootstrapActivity({
-            ...options,
-            runner: runnerResolution.runner,
-            taskCompileWorkflowRef,
-        });
-    }
-    return startControlPlaneTaskCompileActivity({
+    return startReferenceSummaryGateOrNextStage({
         ...options,
         runner: runnerResolution.runner,
         taskCompileWorkflowRef,
@@ -105,6 +99,7 @@ function startControlPlaneTaskCompileActivity(options) {
             runner: options.runner,
             store: options.store,
             events: options.events,
+            projectContext: options.projectContext,
             workflowRef,
             activityRef: context.activity_ref,
             reportProgress: context.reportProgress,
@@ -146,12 +141,7 @@ function startScratchpadRefreshBeforeTaskCompileActivity(options) {
             if (!scratchpadHasSubmittableContent(scratchpad)) {
                 return;
             }
-            if (shouldInitializeControlPlaneProjectContext(options)) {
-                void startProjectContextBootstrapActivity(options);
-            }
-            else {
-                void startControlPlaneTaskCompileActivity(options);
-            }
+            void startReferenceSummaryGateOrNextStage(options);
         },
         onError: ({ context, error }) => logProcedureExecutionError({
             logger: options.logger,
@@ -186,6 +176,103 @@ function startScratchpadRefreshBeforeTaskCompileActivity(options) {
         },
     };
 }
+function startReferenceSummaryGateOrNextStage(options) {
+    const sourceRefs = readActiveTaskCompileContext(options.store.db, options.taskCompileWorkflowRef)?.sources ??
+        readCurrentScratchpadSourceRefs(options.store.db);
+    const referenceSources = readRecentReferenceSources(options.store.db, sourceRefs);
+    const pendingPaths = options.projectContext === undefined
+        ? []
+        : readPendingRecentReferenceSummaryPaths({
+            workspaceRoot: options.projectContext.workspaceRoot,
+            sources: referenceSources,
+            now: options.now,
+        });
+    if (pendingPaths.length === 0) {
+        return startNextTaskCompileStage(options);
+    }
+    const activeReferenceSummary = options.engine.getActiveProcedures().find((activity) => activity.lane === "foreground" &&
+        activity.workflow_kind === "reference_summary_refresh");
+    if (activeReferenceSummary !== undefined) {
+        readOrCaptureTaskCompileContext({
+            store: options.store,
+            workflowRef: options.taskCompileWorkflowRef,
+            activityRef: activeReferenceSummary.activity_ref,
+            now: options.now,
+        });
+        registerReferenceSummaryGateWaiter(options, activeReferenceSummary.activity_ref);
+        return {
+            disposition: {
+                kind: "already_running",
+                activity_ref: activeReferenceSummary.activity_ref,
+            },
+        };
+    }
+    const started = startReferenceSummaryRefreshProcedure({
+        engine: options.engine,
+        store: options.store,
+        events: options.events,
+        paths: pendingPaths,
+        resolveWorkflowRunner: () => ({ kind: "ready", runner: options.runner }),
+        readActiveActivity: () => {
+            const active = options.engine.getActiveProcedures().find((activity) => activity.lane === "foreground");
+            return active === undefined
+                ? null
+                : { activity_ref: active.activity_ref };
+        },
+        projectContext: options.projectContext,
+        logger: options.logger,
+        now: options.now,
+        onExecuteStart: ({ activityRef }) => {
+            readOrCaptureTaskCompileContext({
+                store: options.store,
+                workflowRef: options.taskCompileWorkflowRef,
+                activityRef,
+                now: options.now,
+            });
+        },
+        publishProcedureTransition: options.publishProcedureTransition,
+    });
+    if (started.disposition.kind === "accepted") {
+        const activityRef = started.result?.activity_ref;
+        const workflowRef = started.result?.workflow_ref;
+        if (activityRef === undefined || workflowRef === undefined) {
+            throw new Error("Accepted reference summary gate is missing activity identity");
+        }
+        registerReferenceSummaryGateWaiter(options, activityRef);
+        return {
+            disposition: { kind: "accepted" },
+            result: {
+                activity_ref: activityRef,
+                workflow_ref: workflowRef,
+            },
+        };
+    }
+    if (started.disposition.kind === "already_running") {
+        return { disposition: started.disposition };
+    }
+    if (started.disposition.kind === "no_targets") {
+        return startNextTaskCompileStage(options);
+    }
+    return { disposition: started.disposition };
+}
+function registerReferenceSummaryGateWaiter(options, activityRef) {
+    options.registerReferenceSummaryWaiter(activityRef, (state) => {
+        if (state.activity.status !== "finished") {
+            rollbackTaskCompileContext(options.store.db, {
+                workflow_ref: options.taskCompileWorkflowRef,
+                now: options.now,
+            });
+            return;
+        }
+        void startReferenceSummaryGateOrNextStage(options);
+    });
+}
+function startNextTaskCompileStage(options) {
+    if (shouldInitializeControlPlaneProjectContext(options)) {
+        return startProjectContextBootstrapActivity(options);
+    }
+    return startControlPlaneTaskCompileActivity(options);
+}
 function shouldInitializeControlPlaneProjectContext(options) {
     if (options.projectContext === undefined) {
         return false;
@@ -324,10 +411,20 @@ export async function runControlPlaneTaskCompileProcedure(options) {
         };
     }
     try {
+        const recentReferences = options.projectContext === undefined
+            ? []
+            : materializeRecentReferences({
+                workspaceRoot: options.projectContext.workspaceRoot,
+                sources: readRecentReferenceSources(options.store.db, context.sources),
+                now: options.now,
+            });
         const output = await options.runner.runTaskCompile({
             workflow_ref: options.workflowRef,
             scratchpad: context.scratchpad_snapshot,
             worklist: readWorklistProjection(options.store.db),
+            ...(recentReferences.length === 0
+                ? {}
+                : { recent_references: recentReferences }),
         }, {
             workflow_ref: options.workflowRef,
             activity_ref: options.activityRef,

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

@@ -4,6 +4,7 @@ import type { ActivityRef, ClarificationRoundRef, TaskId, TaskModuleId } from "@
 import type { ActiveApprovalProjection, ClarificationRequestPayload, ExecutionRuntimeSnapshot, MessageProjection, RecoverySummaryProjection, TaskDetailProjection, TaskProjection } from "@tutti/shared/schemas/api";
 import type { HostProjectStore } from "../store/index.js";
 import type { WorkspaceEventBus } from "../server-shell/http/workspace-events.js";
+import type { RecentReferenceContext } from "./reference-context-types.js";
 import type { ProcedureWorkflowRunnerResolver } from "./workflows/index.js";
 export type Phase5ControlPlaneOptions = {
     store: HostProjectStore;
@@ -104,6 +105,7 @@ export type RunPipelineInput = {
     dispatch_context: RunDispatchContext;
     continuation_context?: RunContinuationContext;
     correction_context?: RunCorrectionContext;
+    recent_references?: RecentReferenceContext[];
     on_stage?: (progress: RunPipelineStageProgress) => void;
 };
 export type RunPipelineStageProgress = {

package/dist/control-plane/workflows/openai.js

@@ -160,6 +160,13 @@ export function buildTaskCompilePromptInput(input) {
             })),
         },
     };
+    if (input.recent_references !== undefined && input.recent_references.length !== 0) {
+        promptInput.recent_references = input.recent_references.map((reference) => ({
+            path: reference.path,
+            name: reference.name,
+            summary: { ...reference.summary },
+        }));
+    }
     if (input.clarification_rounds !== undefined) {
         promptInput.clarification_rounds = input.clarification_rounds.map((round) => ({
             request: {