@bastani/atomic 0.8.13 → 0.8.14-0

package/dist/builtin/web-access/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/web-access",
-  "version": "0.8.13",
+  "version": "0.8.14-0",
   "private": true,
   "description": "Atomic extension for web search, URL fetching, GitHub repo cloning, PDF/video extraction. Fork of: https://github.com/nicobailon/pi-web-access",
   "contributors": [

package/dist/builtin/workflows/CHANGELOG.md

@@ -4,6 +4,30 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- Added workflow tool stage introspection and control actions (`stages`, `stage`, `transcript`, `send`, `pause`, and `reload`) for inspecting stage state, reading transcripts, answering prompts, controlling live stages, pausing runs, and reloading workflow resources ([#1023](https://github.com/flora131/atomic/issues/1023)).
+
+### Changed
+
+- Added a final Ralph PR-preparation phase that reviews changes against the configured base branch, tries available GitHub credentials using local git identity as a hint, posts implementation notes as a PR comment, and creates a pull request when possible.
+- Updated Ralph to persist planner RFCs under `specs/`, keep OS-temp implementation notes during orchestration, and pass file paths rather than the full plan text to later stages ([#1037](https://github.com/flora131/atomic/issues/1037)).
+- Updated `deep-research-codebase` output layout to write public reports under `research/` and hidden per-run handoff artifacts under `research/.deep-research-<run-id>/`.
+
+### Fixed
+
+- Removed biasing stage-output and iteration-count context from Ralph reviewer prompts while making the comparison base branch explicit ([#1037](https://github.com/flora131/atomic/issues/1037)).
+- Ordered snapshot transcript fallback entries chronologically before applying `tail`/`limit`, preserving terminal result/error entries after tools for missing or tied timestamps ([#1023](https://github.com/flora131/atomic/issues/1023)).
+- Reloaded workflow resources directly for `workflow({ action: "reload" })` instead of queuing a literal `/workflow reload` follow-up ([#1023](https://github.com/flora131/atomic/issues/1023)).
+- Kept pending prompts unresolved when `workflow({ action: "send" })` omits `text`, `response`, and `message`, while preserving explicit empty-string answers ([#1023](https://github.com/flora131/atomic/issues/1023)).
+- Included `deep-research-codebase` discovery-stage handoff files in the persisted run manifest.
+- Persisted `deep-research-codebase` final reports as dated Markdown research docs while retaining file-only handoffs for bounded aggregation.
+- Prevented `deep-research-codebase` aggregation from inlining large specialist transcripts by using file-only handoff artifacts ([#1016](https://github.com/flora131/atomic/issues/1016)).
+- Removed model metadata from workflow node cards while retaining fallback dependency metadata ([#1011](https://github.com/flora131/atomic/issues/1011)).
+- Preserve the selected workflow switcher row highlight through truncation ellipses on long stage names.
+
 ## [0.0.1] — 2026-05-15
 
 ### Added

package/dist/builtin/workflows/README.md

@@ -192,6 +192,7 @@ registry.get("alpha"); // compiled workflow definition | undefined
 | `/workflow interrupt [run-id\|--all]` | Pause active/named/all active runs so they can resume    |
 | `/workflow kill [run-id\|--all]`      | Kill and remove active/named/all active runs from status |
 | `/workflow resume <run-id>`           | Resume paused work or re-open a run snapshot             |
+| `/workflow reload`                    | Reload discovered workflow resources in-process          |
 | `/workflow inputs <name>`             | Print the input schema for a workflow                    |
 
 Input overrides are bare `key=value` tokens (no leading `--`). Values are JSON-parsed when possible, so numbers, booleans, and quoted strings work as expected (e.g. `count=3`, `flag=true`, `prompt="multi word value"`). A whole-object override can be passed as a single JSON token (e.g. `{"prompt":"...","count":3}`).
@@ -207,11 +208,21 @@ Workflows always run as **background tasks** — the chat editor stays free whil
   "parameters": {
     "workflow": "string (optional) — workflow ID or normalized name",
     "inputs": "object (optional) — key/value map of workflow inputs",
-    "action": "'run' | 'list' | 'get' | 'inputs' | 'status' | 'interrupt' | 'kill' | 'resume'",
-    "runId": "optional run id or unique prefix; interrupt/kill default to the active run; use '--all' or all:true for interrupt/kill all",
-    "stageId": "optional stage id, prefix, or name for resume",
-    "message": "optional resume message",
-    "all": "optional boolean for interrupt/kill all",
+    "action": "'run' | 'list' | 'get' | 'inputs' | 'status' | 'stages' | 'stage' | 'transcript' | 'send' | 'pause' | 'interrupt' | 'kill' | 'resume' | 'reload'",
+    "runId": "optional run id or unique prefix; control actions default to the active run where safe; use '--all' or all:true for pause/interrupt/kill all",
+    "stageId": "optional stage id, prefix, or name for stage-scoped actions; cannot be combined with all:true",
+    "statusFilter": "optional stages filter: pending/running/awaiting_input/paused/blocked/completed/failed/skipped/all",
+    "format": "optional agent-facing output format: text or json",
+    "limit": "transcript-only maximum number of most recent entries; default 50",
+    "tail": "transcript-only last-N entry count; overrides limit",
+    "includeToolOutput": "transcript-only flag for snapshot tool-event output; live transcripts may not expose tool output",
+    "text": "optional string payload for send/resume; explicit empty text answers pending prompts",
+    "response": "optional structured payload for answering pending prompts; explicit empty response is valid",
+    "message": "optional string payload for send/resume when text is not provided",
+    "delivery": "optional send delivery mode: auto, answer, prompt, steer, followUp, or resume; auto prioritizes answer, then resume, steer, followUp",
+    "promptId": "optional pending prompt identifier for send/answer",
+    "reason": "optional human-readable reload reason",
+    "all": "optional boolean for pause/interrupt/kill all; cannot be combined with stageId",
     "task/tasks/chain": "optional direct workflow-native orchestration modes"
   }
 }
@@ -219,6 +230,9 @@ Workflows always run as **background tasks** — the chat editor stays free whil
 
 - **`renderCall`** — renders a compact workflow call summary in the chat scroll.
 - **`renderResult`** — renders the result or dispatch banner; live progress continues through the widget and graph viewer. Named workflow runs are background-oriented.
+- **`transcript`** — uses a registered live stage handle when one exists, even before live messages arrive; otherwise it falls back to stored stage snapshots. Snapshot entries are ordered chronologically before `tail`/`limit` is applied, with terminal result/error entries kept after tool entries when timestamps are missing or tied. `includeToolOutput` applies to snapshot tool events; live session transcripts may not expose tool output.
+- **`send`** — answers pending stage prompts only when `text`, `response`, or `message` is present; an explicit empty string is a valid answer, while an omitted payload is a no-op. `delivery: "auto"` answers pending prompts first, then resumes paused stages, steers streaming stages, or queues a follow-up.
+- **`reload`** — refreshes workflow resources directly in-process instead of queuing a literal `/workflow reload` chat follow-up.
 
 ### F2 keyboard shortcut
 
@@ -288,18 +302,21 @@ Scout + research-history chain → two parallel specialist waves → aggregator.
 | `max_partitions`  | `number` | —        | `100`   | Maximum number of codebase partitions to explore.         |
 | `max_concurrency` | `number` | —        | `4`     | Maximum number of workflow stages to run concurrently.    |
 
+Final Markdown research documents are written to dated `research/` paths relative to the current working directory, with a numeric suffix if needed to avoid overwriting an existing document. Hidden run artifacts are written under `research/.deep-research-<run-id>/`.
+
 ### `ralph`
 
-Plan → orchestrate → simplify → infrastructure discovery → parallel review loop. Named after the [Ralph Wiggum Method](https://ghuntley.com/ralph/).
+Plan → write a spec under `specs/` → orchestrate from that spec path while maintaining OS-temp implementation notes → simplify → infrastructure discovery → parallel review loop → PR preparation. The workflow result includes the generated spec as `plan_path`, the notes file as `implementation_notes_path`, and the final PR phase report as `pr_report`. The PR phase uses local git identity as a hint when multiple GitHub accounts are logged in, tries available credentials until one works, and posts the implementation notes as a PR comment when a PR is created. Named after the [Ralph Wiggum Method](https://ghuntley.com/ralph/).
 
 ```text
-/workflow ralph prompt="Migrate the database layer to Drizzle ORM"
+/workflow ralph prompt="Migrate the database layer to Drizzle ORM" base_branch=develop
 ```
 
-| Input       | Type     | Required | Default | Description                                |
-| ----------- | -------- | -------- | ------- | ------------------------------------------ |
-| `prompt`    | `text`   | ✓        | —       | High-level task or goal to accomplish.     |
-| `max_loops` | `number` | —        | `10`    | Maximum plan → orchestrate → review loops. |
+| Input         | Type     | Required | Default | Description                                      |
+| ------------- | -------- | -------- | ------- | ------------------------------------------------ |
+| `prompt`      | `text`   | ✓        | —       | High-level task or goal to accomplish.           |
+| `max_loops`   | `number` | —        | `10`    | Maximum plan → orchestrate → review loops.       |
+| `base_branch` | `string` | —        | `origin/main` | Branch reviewers compare the current delta with. |
 
 ### `open-claude-design`
 

package/dist/builtin/workflows/builtin/deep-research-codebase.ts

@@ -8,8 +8,11 @@
  * ctx.parallel(), and ctx.chain().
  */
 
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, extname, join } from "node:path";
 import { defineWorkflow } from "../src/index.js";
 import type {
+  WorkflowOutputMode,
   WorkflowTaskResult,
   WorkflowTaskStep,
 } from "../src/shared/types.js";
@@ -17,9 +20,26 @@ import type {
 const DEFAULT_MAX_PARTITIONS = 100;
 const DEFAULT_MAX_CONCURRENCY = 4;
 const LOC_PER_PARTITION = 10_000;
+const DEFAULT_RESEARCH_DOC_DIR = "research";
+const DEEP_RESEARCH_RUN_DIR_PREFIX = ".deep-research-";
+const MAX_RESEARCH_DOC_SLUG_LENGTH = 80;
 
 type PromptSection = readonly [tag: string, content: string];
 
+interface DeepResearchCodebaseResult extends Record<string, unknown> {
+  readonly findings: string;
+  readonly research_doc_path: string;
+  readonly artifact_dir: string;
+  readonly manifest_path: string;
+  readonly partitions: readonly string[];
+  readonly explorer_count: number;
+  readonly specialist_count: number;
+  readonly max_concurrency: number;
+  readonly history: string;
+}
+
+const FILE_ONLY_OUTPUT = "file-only" satisfies WorkflowOutputMode;
+
 const CODEBASE_SKILLS = {
   locator:
     "codebase-locator — use this skill's search-first discipline when mapping where files, symbols, docs, tests, and configuration live.",
@@ -118,6 +138,147 @@ function parsePartitions(text: string, cap: number): string[] {
   return partitions.length > 0 ? partitions : ["core codebase architecture"];
 }
 
+function slugifyResearchTopic(prompt: string): string {
+  const slug = prompt
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, MAX_RESEARCH_DOC_SLUG_LENGTH)
+    .replace(/-+$/g, "");
+  return slug.length > 0 ? slug : "deep-research-codebase";
+}
+
+function defaultResearchDocPath(prompt: string, now = new Date()): string {
+  const date = now.toISOString().slice(0, 10);
+  return join(DEFAULT_RESEARCH_DOC_DIR, `${date}-${slugifyResearchTopic(prompt)}.md`);
+}
+
+function sanitizeRunId(value: string): string {
+  const sanitized = value
+    .trim()
+    .replace(/[^A-Za-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return sanitized.length > 0 ? sanitized : "run";
+}
+
+function timestampRunId(now: Date): string {
+  return sanitizeRunId(now.toISOString().replace(/[:.]/g, "-"));
+}
+
+function suffixedPath(path: string, suffix: number): string {
+  const extension = extname(path);
+  const stem = extension.length === 0 ? path : path.slice(0, -extension.length);
+  return `${stem}-${suffix}${extension}`;
+}
+
+function isFileExistsError(error: unknown): boolean {
+  return error instanceof Error && (error as { readonly code?: string }).code === "EEXIST";
+}
+
+interface DeepResearchArtifactRoot {
+  readonly runId: string;
+  readonly artifactRoot: string;
+}
+
+async function createArtifactRoot(startedAt: Date): Promise<DeepResearchArtifactRoot> {
+  await mkdir(DEFAULT_RESEARCH_DOC_DIR, { recursive: true });
+  const baseRunId = timestampRunId(startedAt);
+  for (let suffix = 0; ; suffix += 1) {
+    const runId = suffix === 0 ? baseRunId : `${baseRunId}-${suffix + 1}`;
+    const artifactRoot = join(
+      DEFAULT_RESEARCH_DOC_DIR,
+      `${DEEP_RESEARCH_RUN_DIR_PREFIX}${runId}`,
+    );
+    try {
+      await mkdir(artifactRoot, { recursive: false });
+      return { runId, artifactRoot };
+    } catch (error) {
+      if (isFileExistsError(error)) continue;
+      throw error;
+    }
+  }
+}
+
+interface DeepResearchManifest {
+  readonly runId: string;
+  readonly startedAt: string;
+  readonly completedAt?: string;
+  readonly researchQuestion: string;
+  readonly finalAsset: string;
+  readonly artifacts: Record<string, string>;
+}
+
+async function writeManifest(path: string, manifest: DeepResearchManifest): Promise<void> {
+  await writeFile(path, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+}
+
+async function writeResearchDoc(path: string, content: string): Promise<string> {
+  await mkdir(dirname(path), { recursive: true });
+
+  for (let suffix = 0; ; suffix += 1) {
+    const candidate = suffix === 0 ? path : suffixedPath(path, suffix + 1);
+    try {
+      await writeFile(candidate, content, { encoding: "utf8", flag: "wx" });
+      return candidate;
+    } catch (error) {
+      if (isFileExistsError(error)) continue;
+      throw error;
+    }
+  }
+}
+
+async function readArtifactText(path: string | undefined, fallback: string): Promise<string> {
+  if (path === undefined) return fallback;
+  try {
+    return await readFile(path, "utf8");
+  } catch {
+    return fallback;
+  }
+}
+
+async function specialistHandoffFromArtifacts(
+  partition: string,
+  index: number,
+  artifactPathsByStage: ReadonlyMap<string, string>,
+): Promise<string> {
+  const i = index + 1;
+  const locator = await readArtifactText(
+    artifactPathsByStage.get(`locator-${i}`),
+    "(no locator output)",
+  );
+  const patterns = await readArtifactText(
+    artifactPathsByStage.get(`pattern-finder-${i}`),
+    "(no pattern output)",
+  );
+  const analyzer = await readArtifactText(
+    artifactPathsByStage.get(`analyzer-${i}`),
+    "(no analyzer output)",
+  );
+  const online = await readArtifactText(
+    artifactPathsByStage.get(`online-${i}`),
+    "(no online research output)",
+  );
+  return [
+    `## Partition ${i}: ${partition}`,
+    `### Locator\n${locator}`,
+    `### Pattern Finder\n${patterns}`,
+    `### Analyzer\n${analyzer}`,
+    `### Online Researcher\n${online}`,
+  ].join("\n\n");
+}
+
+function manifestArtifactPaths(
+  artifactPathsByStage: ReadonlyMap<string, string>,
+  manifestPath: string,
+): Record<string, string> {
+  const artifacts: Record<string, string> = {};
+  for (const [stage, path] of artifactPathsByStage) {
+    artifacts[stage] = displayPath(path);
+  }
+  artifacts.manifest = displayPath(manifestPath);
+  return artifacts;
+}
+
 function findResult(
   results: readonly WorkflowTaskResult[],
   name: string,
@@ -127,32 +288,12 @@ function findResult(
   );
 }
 
-function specialistSummary(
-  partitions: readonly string[],
-  wave1: readonly WorkflowTaskResult[],
-  wave2: readonly WorkflowTaskResult[],
-): string {
-  return partitions
-    .map((partition, index) => {
-      const i = index + 1;
-      const locator =
-        findResult(wave1, `locator-${i}`)?.text ?? "(no locator output)";
-      const patterns =
-        findResult(wave1, `pattern-finder-${i}`)?.text ?? "(no pattern output)";
-      const analyzer =
-        findResult(wave2, `analyzer-${i}`)?.text ?? "(no analyzer output)";
-      const online =
-        findResult(wave2, `online-researcher-${i}`)?.text ??
-        "(no online research output)";
-      return [
-        `## Partition ${i}: ${partition}`,
-        `### Locator\n${locator}`,
-        `### Pattern Finder\n${patterns}`,
-        `### Analyzer\n${analyzer}`,
-        `### Online Researcher\n${online}`,
-      ].join("\n\n");
-    })
-    .join("\n\n---\n\n");
+function displayPath(path: string): string {
+  return path.replace(/\\/g, "/");
+}
+
+function displayPaths(paths: readonly string[]): string {
+  return paths.map(displayPath).join(", ");
 }
 
 export default defineWorkflow("deep-research-codebase")
@@ -191,13 +332,45 @@ export default defineWorkflow("deep-research-codebase")
       inputs.max_concurrency,
       DEFAULT_MAX_CONCURRENCY,
     );
+    const startedAt = new Date();
+    const finalResearchDocPath = defaultResearchDocPath(prompt);
     const codebaseLines = countCodebaseLines();
     const partitionCap = calculatePartitionCap(
       requestedMaxPartitions,
       codebaseLines,
     );
+    const { runId, artifactRoot } = await createArtifactRoot(startedAt);
+    const artifactPathsByStage = new Map<string, string>();
+    const addArtifact = (stage: string, path: string) => {
+      artifactPathsByStage.set(stage, path);
+      return path;
+    };
+    const fileOnlyOutput = (output: string): {
+      output: string;
+      outputMode: WorkflowOutputMode;
+    } => ({
+      output,
+      outputMode: FILE_ONLY_OUTPUT,
+    });
 
-    let noAskQuestionToolSet = [
+    const scoutPath = addArtifact(
+      "codebase-scout",
+      join(artifactRoot, "00-codebase-scout.md"),
+    );
+    const partitionPlanPath = addArtifact(
+      "partition",
+      join(artifactRoot, "01-partition-plan.md"),
+    );
+    const historyLocatorPath = addArtifact(
+      "history-locator",
+      join(artifactRoot, "01-history-locator.md"),
+    );
+    const historyAnalyzerPath = addArtifact(
+      "history-analyzer",
+      join(artifactRoot, "02-history-analyzer.md"),
+    );
+
+    const noAskQuestionToolSet = [
       "read",
       "bash",
       "edit",
@@ -211,7 +384,7 @@ export default defineWorkflow("deep-research-codebase")
       "intercom",
     ];
 
-    let plannerModelConfig = {
+    const plannerModelConfig = {
       model: "openai/gpt-5.5",
       fallbackModels: [
         "openai-codex/gpt-5.5",
@@ -223,7 +396,7 @@ export default defineWorkflow("deep-research-codebase")
       tools: noAskQuestionToolSet,
     };
 
-    let explorerModelConfig = {
+    const explorerModelConfig = {
       model: "openai/gpt-5.4-mini",
       fallbackModels: [
         "openai-codex/gpt-5.4-mini",
@@ -269,6 +442,7 @@ export default defineWorkflow("deep-research-codebase")
               ].join("\n"),
             ],
           ]),
+          ...fileOnlyOutput(scoutPath),
           ...plannerModelConfig,
         },
         {
@@ -295,6 +469,7 @@ export default defineWorkflow("deep-research-codebase")
               "A markdown table with columns: Path, Evidence, Relevance, Confidence.",
             ],
           ]),
+          ...fileOnlyOutput(historyLocatorPath),
           ...explorerModelConfig,
         },
       ],
@@ -305,7 +480,7 @@ export default defineWorkflow("deep-research-codebase")
       findResult(initialDiscovery, "codebase-scout") ?? initialDiscovery[0]!;
     const historyLocator =
       findResult(initialDiscovery, "history-locator") ?? initialDiscovery[1]!;
-    const history = await ctx.chain(
+    await ctx.chain(
       [
         {
           name: "history-analyzer",
@@ -341,6 +516,8 @@ export default defineWorkflow("deep-research-codebase")
             ],
           ]),
           previous: historyLocator,
+          reads: [historyLocatorPath],
+          ...fileOnlyOutput(historyAnalyzerPath),
           ...plannerModelConfig,
         },
       ],
@@ -370,14 +547,26 @@ export default defineWorkflow("deep-research-codebase")
         ["output_format", "Plain text only: one partition per line."],
       ]),
       previous: scout,
+      output: partitionPlanPath,
+      reads: [scoutPath],
       ...plannerModelConfig,
     });
 
     const partitions = parsePartitions(partitionPlan.text, partitionCap);
+    const locatorArtifactPaths = new Map<number, string>();
 
     const wave1Steps: WorkflowTaskStep[] = partitions.flatMap(
       (partition, index) => {
         const i = index + 1;
+        const locatorPath = addArtifact(
+          `locator-${i}`,
+          join(artifactRoot, `locator-${i}.md`),
+        );
+        const patternFinderPath = addArtifact(
+          `pattern-finder-${i}`,
+          join(artifactRoot, `pattern-finder-${i}.md`),
+        );
+        locatorArtifactPaths.set(i, locatorPath);
         return [
           {
             name: `locator-${i}`,
@@ -388,7 +577,10 @@ export default defineWorkflow("deep-research-codebase")
                 `Partition ${i}/${partitions.length}: ${partition}`,
               ],
               ["research_question", prompt],
-              ["scout_context", "{previous}"],
+              [
+                "scout_context",
+                `Read the scout artifact before making evidence claims: ${displayPath(scoutPath)}\nCompact saved-output reference: {previous}`,
+              ],
               ["codebase_skills", codebaseSkillGuidance("locator")],
               [
                 "instructions",
@@ -411,6 +603,8 @@ export default defineWorkflow("deep-research-codebase")
               ],
             ]),
             previous: scout,
+            reads: [scoutPath],
+            ...fileOnlyOutput(locatorPath),
             ...explorerModelConfig,
           },
           {
@@ -422,7 +616,10 @@ export default defineWorkflow("deep-research-codebase")
                 `Partition ${i}/${partitions.length}: ${partition}`,
               ],
               ["research_question", prompt],
-              ["scout_context", "{previous}"],
+              [
+                "scout_context",
+                `Read the scout artifact before making evidence claims: ${displayPath(scoutPath)}\nCompact saved-output reference: {previous}`,
+              ],
               ["codebase_skills", codebaseSkillGuidance("patternFinder")],
               [
                 "instructions",
@@ -445,6 +642,8 @@ export default defineWorkflow("deep-research-codebase")
               ],
             ]),
             previous: scout,
+            reads: [scoutPath],
+            ...fileOnlyOutput(patternFinderPath),
             ...explorerModelConfig,
           },
         ];
@@ -460,6 +659,24 @@ export default defineWorkflow("deep-research-codebase")
       (partition, index) => {
         const i = index + 1;
         const locator = findResult(wave1, `locator-${i}`);
+        const locatorPath =
+          locator === undefined ? undefined : locatorArtifactPaths.get(i);
+        const analyzerReads =
+          locatorPath === undefined ? [scoutPath] : [scoutPath, locatorPath];
+        const onlineResearcherReads =
+          locatorPath === undefined ? [scoutPath] : [locatorPath];
+        const onlineResearcherLocalContext =
+          locatorPath === undefined
+            ? `Read scout context before researching: ${displayPath(scoutPath)}\nCompact saved-output reference: {previous}`
+            : `Read local artifact context before researching: ${displayPath(locatorPath)}\nCompact saved-output reference: {previous}`;
+        const analyzerPath = addArtifact(
+          `analyzer-${i}`,
+          join(artifactRoot, `analyzer-${i}.md`),
+        );
+        const onlineResearcherPath = addArtifact(
+          `online-${i}`,
+          join(artifactRoot, `online-${i}.md`),
+        );
         return [
           {
             name: `analyzer-${i}`,
@@ -473,7 +690,10 @@ export default defineWorkflow("deep-research-codebase")
                 `Partition ${i}/${partitions.length}: ${partition}`,
               ],
               ["research_question", prompt],
-              ["context", "{previous}"],
+              [
+                "context",
+                `Read these artifacts before analyzing: ${displayPaths(analyzerReads)}\nCompact saved-output reference: {previous}`,
+              ],
               ["codebase_skills", codebaseSkillGuidance("analyzer")],
               [
                 "instructions",
@@ -496,6 +716,8 @@ export default defineWorkflow("deep-research-codebase")
               ],
             ]),
             previous: locator === undefined ? scout : [scout, locator],
+            reads: analyzerReads,
+            ...fileOnlyOutput(analyzerPath),
             ...explorerModelConfig,
           },
           {
@@ -510,7 +732,10 @@ export default defineWorkflow("deep-research-codebase")
                 `Partition ${i}/${partitions.length}: ${partition}`,
               ],
               ["research_question", prompt],
-              ["local_context", "{previous}"],
+              [
+                "local_context",
+                onlineResearcherLocalContext,
+              ],
               ["codebase_skills", codebaseSkillGuidance("onlineResearcher")],
               [
                 "instructions",
@@ -533,6 +758,8 @@ export default defineWorkflow("deep-research-codebase")
               ],
             ]),
             previous: locator === undefined ? scout : locator,
+            reads: onlineResearcherReads,
+            ...fileOnlyOutput(onlineResearcherPath),
             ...explorerModelConfig,
           },
         ];
@@ -543,8 +770,29 @@ export default defineWorkflow("deep-research-codebase")
       task: prompt,
       concurrency: maxConcurrency,
     });
-    const historyOverview = history.at(-1)?.text ?? "";
-    const specialistReports = specialistSummary(partitions, wave1, wave2);
+    const historyOverview = await readArtifactText(historyAnalyzerPath, "");
+    const explorerPaths = await Promise.all(
+      partitions.map(async (partition, index) => {
+        const i = index + 1;
+        const explorerPath = addArtifact(
+          `explorer-${i}`,
+          join(artifactRoot, `explorer-${i}.md`),
+        );
+        const explorer = await specialistHandoffFromArtifacts(
+          partition,
+          index,
+          artifactPathsByStage,
+        );
+        await writeFile(explorerPath, explorer, "utf8");
+        return explorerPath;
+      }),
+    );
+    const aggregatorReadPaths = [
+      scoutPath,
+      partitionPlanPath,
+      ...(historyOverview === "" ? [] : [historyAnalyzerPath]),
+      ...explorerPaths,
+    ];
 
     const aggregate = await ctx.task("aggregator", {
       prompt: taggedPrompt([
@@ -553,11 +801,26 @@ export default defineWorkflow("deep-research-codebase")
           "objective",
           `Answer the research question comprehensively: ${prompt}`,
         ],
+        [
+          "context_artifacts",
+          [
+            `Read the scout artifact at ${displayPath(scoutPath)}.`,
+            `Read the partition plan artifact at ${displayPath(partitionPlanPath)}.`,
+            historyOverview === ""
+              ? "No prior research overview artifact is available."
+              : `Read the prior research overview artifact at ${displayPath(historyAnalyzerPath)}.`,
+          ].join("\n"),
+        ],
         [
           "prior_research_overview",
-          historyOverview || "(no prior research found)",
+          historyOverview === ""
+            ? "(no prior research found)"
+            : `Read the prior research overview artifact at ${displayPath(historyAnalyzerPath)}.`,
+        ],
+        [
+          "specialist_reports",
+          `Read the complete explorer handoff artifact(s) at ${displayPaths(explorerPaths)}. They preserve every partition's Locator, Pattern Finder, Analyzer, and Online Researcher output from the original inline specialist handoff while keeping this prompt bounded.`,
         ],
-        ["specialist_reports", specialistReports],
         [
           "codebase_skills",
           codebaseSkillGuidance(
@@ -570,6 +833,7 @@ export default defineWorkflow("deep-research-codebase")
           "instructions",
           [
             "Synthesize; do not merely concatenate specialist reports.",
+            "Use the supplied input files as the source of detailed scout, partition, history, and specialist evidence instead of relying on inline transcripts.",
             "Prioritize claims supported by concrete paths, symbols, tests, docs, or cited external references.",
             "Resolve contradictions explicitly and preserve important uncertainty.",
             "Avoid inventing facts not supported by the supplied reports; state unknowns instead.",
@@ -588,17 +852,36 @@ export default defineWorkflow("deep-research-codebase")
           ].join("\n"),
         ],
       ]),
-      previous: [scout, partitionPlan, ...wave1, ...wave2],
+      reads: aggregatorReadPaths,
       ...explorerModelConfig,
     });
 
-    return {
+    const writtenResearchDocPath = await writeResearchDoc(
+      finalResearchDocPath,
+      aggregate.text,
+    );
+    const manifestPath = join(artifactRoot, "manifest.json");
+    const completedAt = new Date();
+    await writeManifest(manifestPath, {
+      runId,
+      startedAt: startedAt.toISOString(),
+      completedAt: completedAt.toISOString(),
+      researchQuestion: prompt,
+      finalAsset: displayPath(writtenResearchDocPath),
+      artifacts: manifestArtifactPaths(artifactPathsByStage, manifestPath),
+    });
+
+    const result: DeepResearchCodebaseResult = {
       findings: aggregate.text,
+      research_doc_path: displayPath(writtenResearchDocPath),
+      artifact_dir: displayPath(artifactRoot),
+      manifest_path: displayPath(manifestPath),
       partitions,
       explorer_count: partitions.length,
       specialist_count: wave1.length + wave2.length,
       max_concurrency: maxConcurrency,
       history: historyOverview,
     };
+    return result;
   })
   .compile();