@bastani/atomic 0.9.11-alpha.8 → 0.9.11

package/dist/builtin/workflows/builtin/open-claude-design-runner.ts

@@ -15,8 +15,12 @@ import { exportOpenClaudeDesign, refineOpenClaudeDesign } from "./open-claude-de
 import {
   NO_REFERENCES_BRIEF,
   buildReferenceDiscoveryPrompt,
+  designContextPath,
+  persistDesignContext,
   persistReferencesBrief,
+  referencesBriefPath,
   runDiscoveryAndInit,
+  type LiveReviewGateUi,
 } from "./open-claude-design-setup.js";
 
 const GROUNDED_REPORTING =
@@ -37,6 +41,7 @@ type OpenClaudeDesignContext = {
   exit?(options?: { readonly status?: string; readonly reason?: string; readonly outputs?: Partial<OpenClaudeDesignOutputs> }): never;
   task(name: string, options: WorkflowTaskOptions): Promise<WorkflowTaskResult>;
   parallel(steps: readonly WorkflowTaskStep[], options: WorkflowParallelOptions): Promise<WorkflowTaskResult[]>;
+  readonly ui: LiveReviewGateUi;
 };
 
 export async function runOpenClaudeDesignWorkflow(ctx: OpenClaudeDesignContext): Promise<OpenClaudeDesignOutputs> {
@@ -61,6 +66,10 @@ export async function runOpenClaudeDesignWorkflow(ctx: OpenClaudeDesignContext):
   );
   const previewFileUrl = `file://${previewPath}`;
   const specFileUrl = `file://${specPath}`;
+  const partialArtifactOutputs = {
+    playwright_cli_status: playwrightCli.summary, run_id: runId, artifact_dir: artifactDir,
+    preview_path: previewPath, preview_file_url: previewFileUrl, spec_path: specPath, spec_file_url: specFileUrl,
+  };
 
   // Browser-centric workflow: the discovery/preview review and the interactive
   // `live` QA loop need the playwright-cli browser. If it is unavailable, exit
@@ -72,13 +81,31 @@ export async function runOpenClaudeDesignWorkflow(ctx: OpenClaudeDesignContext):
   ) {
     designContext.exit({
       reason: `open-claude-design needs the playwright-cli skill's browser for interactive design review, which is unavailable (${playwrightCli.error ?? playwrightCli.summary}). No design was generated. Install it (\`npm install -g @playwright/cli@latest\` + \`npx playwright install chromium\`) and re-run.`,
-      outputs: {
-        playwright_cli_status: playwrightCli.summary, run_id: runId, artifact_dir: artifactDir,
-        preview_path: previewPath, preview_file_url: previewFileUrl, spec_path: specPath, spec_file_url: specFileUrl,
-      },
+      outputs: partialArtifactOutputs,
     });
   }
 
+  // design-context.md / references.md are required `reads` inputs for the
+  // reference-discovery, generate, and exporter stages. A failed write must
+  // not let those stages dispatch against nonexistent context: exit the run
+  // as `blocked` through ctx.exit (mirroring the browser early-exit) with the
+  // artifact paths surfaced, or propagate the error when ctx.exit is absent.
+  const persistRequiredContextOrExit = (persist: () => void): void => {
+    try {
+      persist();
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      if (typeof designContext.exit === "function") {
+        designContext.exit({
+          status: "blocked",
+          reason: `${detail} No design was generated.`,
+          outputs: partialArtifactOutputs,
+        });
+      }
+      throw error;
+    }
+  };
+
   // Anthropic-heavy chain for design taste. Opus stays at :xhigh here because
   // visual quality, rather than cost per task, is the primary objective.
   const designModelConfig = {
@@ -229,31 +256,41 @@ export async function runOpenClaudeDesignWorkflow(ctx: OpenClaudeDesignContext):
   });
   const onboardingSummary = joinResults(onboardingAnalysis);
 
+  // Large research context is handed to later stages as an artifact file plus
+  // `reads`, never as an inline prompt embed or `previous` payload, so one
+  // oversized research result cannot become one oversized prompt message
+  // (issue #2121; same failure class as the #1499 413).
+  const designSystem = [
+    "Project design context from `/skill:impeccable init` and PRODUCT.md/DESIGN.md:",
+    projectContext.summary,
+    "",
+    "Design-system and user-reference evidence:",
+    onboardingSummary,
+  ].join("\n\n");
+  persistRequiredContextOrExit(() => persistDesignContext(artifactDir, designSystem));
+  const designContextFile = designContextPath(artifactDir);
+
   const referenceResult = discoverReferences
     ? await designContext.task("reference-discovery", {
         prompt: buildReferenceDiscoveryPrompt({
           prompt: designBrief,
           outputType,
-          designContextHint: [
-            projectContext.summary,
-            "Design-system/reference discovery evidence from codebase design discovery stages:",
-            onboardingSummary,
-          ].join("\n\n"),
+          designContextFile,
           artifactDir,
           browserBootstrapRules,
         }),
-        previous: onboardingAnalysis,
+        reads: [designContextFile],
         ...designModelConfig,
       })
     : undefined;
-  const contextResults = referenceResult === undefined
-    ? onboardingAnalysis
-    : [...onboardingAnalysis, referenceResult];
 
   const referencesBriefRaw = (referenceResult?.text ?? "").trim();
   const referencesBrief =
     referencesBriefRaw.length > 0 ? referencesBriefRaw : NO_REFERENCES_BRIEF;
-  if (referencesBriefRaw.length > 0) persistReferencesBrief(artifactDir, referencesBrief);
+  // Always persist so the generate stages' `reads` target exists even when
+  // discovery is skipped or returned nothing.
+  persistRequiredContextOrExit(() => persistReferencesBrief(artifactDir, referencesBrief));
+  const referencesFile = referencesBriefPath(artifactDir);
 
   const importContext = references.length > 0
     ? [
@@ -261,16 +298,9 @@ export async function runOpenClaudeDesignWorkflow(ctx: OpenClaudeDesignContext):
         "Reference sources:",
         userReferenceContext,
         "",
-        onboardingSummary,
+        "Full design-system and reference evidence: read the design-context file.",
       ].join("\n")
     : "No user reference was provided; infer the design direction from the brief, project design context, research, and curated reference inspiration.";
-  const designSystem = [
-    "Project design context from `/skill:impeccable init` and PRODUCT.md/DESIGN.md:",
-    projectContext.summary,
-    "",
-    "Design-system and user-reference evidence:",
-    onboardingSummary,
-  ].join("\n\n");
 
   let latestDesign = "";
   let approvedForExport = false;
@@ -285,12 +315,12 @@ export async function runOpenClaudeDesignWorkflow(ctx: OpenClaudeDesignContext):
     previewFileUrl,
     artifactDir,
     browserBootstrapRules,
-    designSystem,
-    generationContext: contextResults,
+    designContextFile,
+    referencesFile,
     designModelConfig,
     workflowCwd,
-    referencesBrief,
     importContext,
+    ui: designContext.ui,
   });
   latestDesign = refinement.latestDesign;
   approvedForExport = refinement.approvedForExport;
@@ -305,7 +335,8 @@ export async function runOpenClaudeDesignWorkflow(ctx: OpenClaudeDesignContext):
     specPath,
     specFileUrl,
     browserBootstrapRules,
-    designSystem,
+    designContextFile,
+    referencesFile,
     latestDesign,
     designModelConfig,
   });

package/dist/builtin/workflows/builtin/open-claude-design-setup.ts

@@ -3,7 +3,7 @@
  *
  * Capabilities that delegate to the accessible `impeccable` skill
  * (`/skill:impeccable …`), factored into this module so the runner and phases
- * files stay under the 500-line file-length gate:
+ * files stay focused:
  *
  *   1. Discovery + init front door: one `discovery` stage runs
  *      `/skill:impeccable shape` and `/skill:impeccable init`, interviews the
@@ -130,10 +130,22 @@ export const REFERENCE_DESIGN_SITES: readonly { readonly name: string; readonly
 export const NO_REFERENCES_BRIEF =
   "Reference discovery was skipped. Generate from the project design system and the prompt; do not fabricate external references.";
 
+/** Artifact filenames for large stage-to-stage context handoffs (issue #2121). */
+export const DESIGN_CONTEXT_FILENAME = "design-context.md";
+export const REFERENCES_BRIEF_FILENAME = "references.md";
+
+export function designContextPath(artifactDir: string): string {
+  return join(artifactDir, DESIGN_CONTEXT_FILENAME);
+}
+
+export function referencesBriefPath(artifactDir: string): string {
+  return join(artifactDir, REFERENCES_BRIEF_FILENAME);
+}
+
 export function buildReferenceDiscoveryPrompt(args: {
   readonly prompt: string;
   readonly outputType: string;
-  readonly designContextHint: string;
+  readonly designContextFile: string;
   readonly artifactDir: string;
   readonly browserBootstrapRules: string;
 }): string {
@@ -142,7 +154,10 @@ export function buildReferenceDiscoveryPrompt(args: {
   ).join("\n");
   return taggedPrompt([
     ["reference_galleries", siteList],
-    ["design_context", args.designContextHint],
+    [
+      "design_context_file",
+      `Read the file at ${args.designContextFile} for the project design context (PRODUCT.md/DESIGN.md summary) and the ds-* discovery evidence before curating. Do not proceed from assumptions when the file is readable; if it is missing, say so and curate from the brief alone.`,
+    ],
     ["browser_use_guidelines", args.browserBootstrapRules],
     ["screenshot_dir", args.artifactDir],
     [
@@ -161,7 +176,7 @@ export function buildReferenceDiscoveryPrompt(args: {
         `Capture motion across the entire page: start \`playwright-cli video-start ${join(args.artifactDir, "ref-<site>-<n>.webm")}\`, scroll smoothly in small increments with waits (using \`playwright-cli run-code\` or repeated \`playwright-cli mousewheel 0 600\`) so animations fire and lazy content loads, then run \`playwright-cli video-stop\`.`,
         `Also run \`playwright-cli screenshot --full-page --filename=${join(args.artifactDir, "ref-<site>-<n>.png")}\`; this still is the minimum when video is unavailable.`,
         "Record the actual destination URL, title, and author. For each reference, cite observed layout, typography, color, spacing, and motion traits rather than inferred traits.",
-        "Assess fit against DESIGN.md, PRODUCT.md, and the ds-* discovery evidence in <design_context>; prefer on-brand references and flag departures.",
+        "Assess fit against DESIGN.md, PRODUCT.md, and the ds-* discovery evidence in the design-context file; prefer on-brand references and flag departures.",
         "Use ask_user_question to ask which reference direction they prefer, offering 2-4 strongest options plus `None of these fit`. If none fit, ask them to provide a reference image, screenshot, URL, or local file path and record the answer.",
         "If `playwright-cli` is unavailable or automation is blocked, use web search / page fetch to reach actual pages and mark missing recordings or screenshots. Never fabricate references or visual claims; report galleries with no usable result.",
       ].join("\n"),
@@ -181,16 +196,53 @@ export function buildReferenceDiscoveryPrompt(args: {
   ]);
 }
 
-/** Persist the curated references brief to `<artifactDir>/references.md`. Best-effort. */
-export function persistReferencesBrief(artifactDir: string, brief: string): void {
+/**
+ * Write a context artifact that downstream stages consume via `reads`.
+ * These files are required stage inputs, not best-effort durability copies:
+ * a swallowed write failure would let reference-discovery, generate, and
+ * exporter stages dispatch against nonexistent design/reference context, so
+ * a failure propagates and stops the workflow (issue #2121, Greptile P1).
+ */
+function writeRequiredContextArtifact(
+  artifactDir: string,
+  filePath: string,
+  content: string,
+  label: string,
+): void {
   try {
     mkdirSync(artifactDir, { recursive: true });
-    writeFileSync(join(artifactDir, "references.md"), `${brief}\n`);
-  } catch {
-    /* best-effort durability; never block the workflow */
+    writeFileSync(filePath, `${content}\n`);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `open-claude-design: failed to write the required ${label} artifact at ${filePath}. Downstream stages read this file via \`reads\` and must not run without it (${detail})`,
+      { cause: error },
+    );
   }
 }
 
+/**
+ * Persist the curated references brief to `<artifactDir>/references.md`.
+ * Downstream generate stages consume this file via `reads` instead of an
+ * inline prompt embed; a write failure propagates (issue #2121).
+ */
+export function persistReferencesBrief(artifactDir: string, brief: string): void {
+  writeRequiredContextArtifact(artifactDir, referencesBriefPath(artifactDir), brief, "references-brief");
+}
+
+/**
+ * Persist the composed project design context (impeccable init summary plus
+ * ds-* discovery evidence) to `<artifactDir>/design-context.md`.
+ * Reference-discovery, generate, and exporter stages consume this file via
+ * `reads` instead of an inline prompt embed, so one oversized research result
+ * cannot become an oversized single prompt message. A write failure
+ * propagates rather than letting those stages run without their design
+ * context (issue #2121).
+ */
+export function persistDesignContext(artifactDir: string, content: string): void {
+  writeRequiredContextArtifact(artifactDir, designContextPath(artifactDir), content, "design-context");
+}
+
 // ---------------------------------------------------------------------------
 // 2. Live interactive QA prompt (user-feedback display/review stages)
 // ---------------------------------------------------------------------------
@@ -226,9 +278,10 @@ export function buildLivePreviewDisplayPrompt(args: {
       ].join("\n")
     : [
         `1. Run \`/skill:impeccable live\` targeted at the preview file so the user can pick elements in the browser, annotate them, and compare on-brand variants. The preview is a single static HTML file at ${args.previewPath}; point live at it (configure \`.impeccable/live/config.json\` for that file or pass \`--target ${args.previewPath}\` per the live reference) and open ${args.previewFileUrl} in the browser.`,
-        "2. For each element the user picks, follow the live contract: read any annotation screenshot, extract the page identity FIRST, then generate three DISTINCT on-brand variants and let the user accept one. Accepted variants are written into the preview HTML in place; do NOT branch the artifact.",
-        "3. Also handle the live `steer` path for page-level direction the user types/speaks, and treat any freeform prompt as the ceiling on direction.",
-        "4. Keep iterating until the user signals they are done with this round.",
+        `2. The moment the live review is reachable — and BEFORE starting any long-poll wait — print the exact review URL in plain text: the live \`http://\` URL when the live server is up, plus ${args.previewFileUrl} as the manual fallback. Anyone attaching to this stage mid-run must see where the review is happening from your first lines of output.`,
+        "3. For each element the user picks, follow the live contract: read any annotation screenshot, extract the page identity FIRST, then generate three DISTINCT on-brand variants and let the user accept one. Accepted variants are written into the preview HTML in place; do NOT branch the artifact.",
+        "4. Also handle the live `steer` path for page-level direction the user types/speaks, and treat any freeform prompt as the ceiling on direction.",
+        "5. Keep iterating until the user signals they are done with this round.",
       ].join("\n");
   const outputFormat = isFinal
     ? [
@@ -265,3 +318,63 @@ export function buildLivePreviewDisplayPrompt(args: {
     ["output_format", `${outputFormat}\nKeep the report under 250 words. ${GROUNDED_REPORTING}`],
   ]);
 }
+
+// ---------------------------------------------------------------------------
+// 3. Deterministic live-review gate (run-level HIL prompt, issue #2060)
+// ---------------------------------------------------------------------------
+
+/**
+ * Minimal structural slice of `ctx.ui` the live-review gate needs. Kept
+ * structural so the runner/phases modules stay decoupled from the full
+ * WorkflowRunContext type.
+ */
+export type LiveReviewGateUi = {
+  select<T extends string>(message: string, options: readonly T[]): Promise<T>;
+};
+
+/**
+ * Choices for the deterministic gate raised before every `user-feedback-*`
+ * stage. The first entry starts the browser review round; the second accepts
+ * the current design and skips straight to export.
+ */
+export const LIVE_REVIEW_GATE_OPTIONS = [
+  "Start live review",
+  "Skip remaining review rounds and export as-is",
+] as const;
+
+/**
+ * Message for the deterministic run-level prompt raised before each
+ * `user-feedback-*` stage. The stage's browser long-poll never sets
+ * `awaiting_input`, so without this gate the run is indistinguishable from
+ * active compute while it waits on a human (issue #2060). Raising a `ctx.ui`
+ * prompt sets the run-level pending prompt, which fires the needs-attention
+ * badge and carries the preview URL to the root session deterministically.
+ */
+export function buildLiveReviewGateMessage(args: {
+  readonly iteration: number;
+  readonly maxRefinements: number;
+  readonly previewPath: string;
+  readonly previewFileUrl: string;
+}): string {
+  return [
+    `Design review round ${args.iteration} of ${args.maxRefinements} is ready for your browser review.`,
+    "",
+    `Preview file: ${args.previewPath}`,
+    `Preview URL: ${args.previewFileUrl}`,
+    "",
+    `"${LIVE_REVIEW_GATE_OPTIONS[0]}" opens an interactive browser session; the user-feedback stage prints the live http:// review URL as soon as its server is up (attach with /workflow connect to see it, or open the preview URL above directly).`,
+    `"${LIVE_REVIEW_GATE_OPTIONS[1]}" accepts the current design and proceeds to export.`,
+  ].join("\n");
+}
+
+/**
+ * True only for the executor's unavailable-UI rejections (no UI adapter, or
+ * headless/non-interactive mode; see `executor-hil.ts` `makeRejectingUIContext`
+ * and the prompt-node unavailable errors). The live-review gate degrades to
+ * running the review for exactly these; every other rejection — interruption,
+ * durable checkpoint persistence failure, exit — must propagate so the
+ * workflow stops instead of opening a review against an invalid run state.
+ */
+export function isUiUnavailableRejection(error: unknown): boolean {
+  return error instanceof Error && /ctx\.ui\.\w+ (?:prompt node )?is unavailable/.test(error.message);
+}

package/dist/builtin/workflows/builtin/ralph-core.ts

@@ -1,8 +1,8 @@
-import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
+import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { Type } from "typebox";
 import type { WorkflowTaskResult } from "../src/shared/types.js";
+import { createWorkflowArtifactDirectory } from "../src/shared/workflow-artifacts.js";
 import {
   E2E_VERIFICATION_GUIDANCE,
   LITERAL_OBJECTIVE_CONTRACT,
@@ -170,8 +170,8 @@ export function defaultResearchPath(prompt: string, now = new Date()): string {
   return join(DEFAULT_RESEARCH_DIR, `${date}-${slugifyResearchTopic(prompt)}.md`);
 }
 
-export async function createImplementationNotesFile(prompt: string): Promise<string> {
-  const notesDir = await mkdtemp(join(tmpdir(), "atomic-ralph-notes-"));
+export async function createImplementationNotesFile(prompt: string, runId?: string): Promise<string> {
+  const notesDir = await createWorkflowArtifactDirectory(runId);
   const notesPath = join(notesDir, IMPLEMENTATION_NOTES_FILENAME);
   const initialNotes = [
     "# Implementation Notes",
@@ -195,8 +195,8 @@ export async function createImplementationNotesFile(prompt: string): Promise<str
 // write to it; the video file itself is produced by the orchestrator's QA pass
 // (and overwritten each iteration so it always reflects the latest state). The
 // final pull-request stage attaches it when it exists.
-export async function createQaEvidenceVideoPath(): Promise<string> {
-  const qaDir = await mkdtemp(join(tmpdir(), "atomic-ralph-qa-"));
+export async function createQaEvidenceVideoPath(runId?: string): Promise<string> {
+  const qaDir = await createWorkflowArtifactDirectory(runId);
   return join(qaDir, QA_E2E_VIDEO_FILENAME);
 }
 
@@ -367,7 +367,6 @@ export function renderResearchPrompt(args: {
   readonly acceptanceCriteria: string;
   readonly workflowCwdContext: PromptSection;
   readonly latestReviewReportPath: string | undefined;
-  readonly researchPath: string;
 }): string {
   return taggedPrompt([
     ["acceptance_criteria", args.acceptanceCriteria],
@@ -386,8 +385,7 @@ export function renderResearchPrompt(args: {
     [
       "research_artifact",
       [
-        "Return the complete research report as your final message. This workflow saves that final message verbatim as the run's research artifact; downstream implementation and review stages read it from that file.",
-        `Do not write ${args.researchPath} yourself. Anything written there during this stage is replaced by your final message, so a file you author is lost and a final message that only points at the path leaves later stages with no findings. Skill-owned notes under research/docs/ and research/web/ are unaffected.`,
+        "Return the complete research report as your final message. Downstream implementation and review stages read it from there.",
         "Produce a complete Markdown report with codebase and useful online/contextual findings, implementation guidance, relevant files/tests/docs, unresolved-finding analysis, and validation recommendations. Lead with conclusions; keep facts, caveats, and implementation-relevant next steps; drop background and repetition.",
         "Before reporting progress, audit each claim against a tool result from this session. Report only work you can point to evidence for; say so explicitly when something is unverified.",
         "Do not author an RFC/spec or implement code changes.",
@@ -417,6 +415,7 @@ export type RalphWorkflowOptions = {
   readonly comparisonBaseBranch: string;
   readonly workflowStartCwd: string;
   readonly createPr: boolean;
+  readonly runId?: string;
 };
 
 export type RalphWorkflowResult = {

package/dist/builtin/workflows/builtin/ralph-forked-prompts.ts

@@ -28,7 +28,6 @@ export function renderForkedResearchPromptRefinementPrompt(args: {
 export function renderForkedResearchPrompt(args: {
   readonly transformedResearchQuestion: string;
   readonly latestReviewReportPath: string | undefined;
-  readonly researchPath: string;
 }): string {
   return taggedPrompt([
     [
@@ -43,9 +42,8 @@ export function renderForkedResearchPrompt(args: {
     [
       "research_artifact",
       [
-        "Return the rewritten research report for this iteration as your final message. This workflow saves that final message verbatim as the run's research artifact; downstream implementation and review stages read it from that file.",
-        `Do not write ${args.researchPath} yourself. Anything written there during this stage is replaced by your final message, so a file you author is lost and a final message that only points at the path leaves later stages with no findings. Skill-owned notes under research/docs/ and research/web/ are unaffected.`,
-        "Restate the still-applicable findings in full rather than referring back to the previous iteration's artifact; it is overwritten by this message.",
+        "Return the rewritten research report for this iteration as your final message.",
+        "Restate the still-applicable findings in full rather than referring back to the previous iteration's artifact; the current artifact and transcript are the authoritative records for this iteration.",
         "Do not author an RFC/spec or implement code changes.",
       ].join("\n"),
     ],

package/dist/builtin/workflows/builtin/ralph-models.ts

@@ -48,10 +48,10 @@ export const promptEngineerModelConfig = {
 };
 
 export const researchModelConfig = {
-    model: "openai-codex/gpt-5.6-sol:medium",
+    model: "openai-codex/gpt-5.6-luna:max",
     fallbackModels: [
-      "github-copilot/gpt-5.6-sol:medium",
-      "openai/gpt-5.6-sol:medium",
+      "github-copilot/gpt-5.6-luna:max",
+      "openai/gpt-5.6-luna:max",
       "anthropic/claude-opus-5:low",
       "github-copilot/claude-opus-5:low",
       "anthropic/claude-fable-5:low",
@@ -64,7 +64,7 @@ export const researchModelConfig = {
       "xai/grok-4.5:high",
       "zai/glm-5.2:high",
       "zai-coding-cn/glm-5.2:high",
-      "openrouter/openai/gpt-5.6-sol:medium",
+      "openrouter/openai/gpt-5.6-luna:max",
       "openrouter/anthropic/claude-opus-5:low",
       "openrouter/openai/gpt-5.5:medium",
       "openrouter/anthropic/claude-fable-5:low",

package/dist/builtin/workflows/builtin/ralph-runner.ts

@@ -1,8 +1,7 @@
 import { existsSync } from "node:fs";
-import { mkdtemp } from "node:fs/promises";
-import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import type { WorkflowRunContext, WorkflowTaskResult } from "../src/shared/types.js";
+import { createWorkflowArtifactDirectory } from "../src/shared/workflow-artifacts.js";
 import {
   ACCEPTANCE_MATRIX_CONTRACT,
   CONTRACT_FIDELITY_AUDIT,
@@ -52,7 +51,7 @@ export async function runRalphWorkflow(
   ctx: WorkflowRunContext<RalphInputs>,
   options: RalphWorkflowOptions,
 ): Promise<RalphWorkflowResult> {
-  const { prompt, acceptanceCriteria, maxLoops, comparisonBaseBranch, workflowStartCwd, createPr } = options;
+  const { prompt, acceptanceCriteria, maxLoops, comparisonBaseBranch, workflowStartCwd, createPr, runId } = options;
   let latestReviewReportPath: string | undefined;
   let finalPlan = "";
   let finalPlanPath = "";
@@ -63,9 +62,9 @@ export async function runRalphWorkflow(
   const workflowCwdContext = workflowCwdContextSection(workflowStartCwd);
   const workflowPrompt = prompt;
   const workflowResearchPath = resolve(workflowStartCwd, defaultResearchPath(workflowPrompt));
-  const implementationNotesPath = await createImplementationNotesFile(workflowPrompt);
-  const qaVideoPath = await createQaEvidenceVideoPath();
-  const artifactDir = await mkdtemp(join(tmpdir(), "atomic-ralph-run-"));
+  const implementationNotesPath = await createImplementationNotesFile(workflowPrompt, runId);
+  const qaVideoPath = await createQaEvidenceVideoPath(runId);
+  const artifactDir = await createWorkflowArtifactDirectory(runId);
   let approved = false;
   let iterationsCompleted = 0;
   let previousResearchPromptRefinementSessionFile: string | undefined;
@@ -98,12 +97,10 @@ export async function runRalphWorkflow(
             acceptanceCriteria,
             workflowCwdContext,
             latestReviewReportPath,
-            researchPath: workflowResearchPath,
           })
         : renderForkedResearchPrompt({
             transformedResearchQuestion: researchPromptRefinement.text,
             latestReviewReportPath,
-            researchPath: workflowResearchPath,
           }),
       reads: latestReviewReportPath === undefined ? [] : [latestReviewReportPath],
       output: workflowResearchPath,

package/dist/builtin/workflows/builtin/ralph.ts

@@ -41,7 +41,7 @@ export default workflow({
     plan_path: Type.Optional(Type.String({ description: "Backward-compatible alias for research_path." })),
     research: Type.Optional(Type.String({ description: "Latest research report text or artifact reference." })),
     research_path: Type.Optional(Type.String({ description: "Path to the latest generated research artifact under research/." })),
-    implementation_notes_path: Type.Optional(Type.String({ description: "OS-temp notes file containing decisions, deviations, blockers, and validation notes." })),
+    implementation_notes_path: Type.Optional(Type.String({ description: "Durable run-scoped notes file containing decisions, deviations, blockers, and validation notes." })),
     qa_video_path: Type.Optional(Type.String({ description: "Absolute path to the reviewable QA end-to-end proof video recorded with playwright-cli for UI-applicable changes, when one was produced." })),
     pr_report: Type.Optional(Type.String({ description: "Pull-request report emitted only when create_pr=true and the final pull-request stage runs." })),
     approved: Type.Optional(Type.Boolean({ description: "Whether the reviewer loop approved before completion or optional final handoff." })),
@@ -72,6 +72,7 @@ export default workflow({
       comparisonBaseBranch,
       workflowStartCwd,
       createPr,
+      runId: workflowCtx.runId,
     });
   },
 });

package/dist/builtin/workflows/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/workflows",
-  "version": "0.9.11-alpha.8",
+  "version": "0.9.11",
   "private": true,
   "description": "Atomic extension for multi-stage workflow authoring and execution.",
   "contributors": [
@@ -79,11 +79,11 @@
   },
   "dependencies": {
     "jiti": "^2.7.0",
-    "typebox": "^1.3.6"
+    "typebox": "^1.3.7"
   },
   "peerDependencies": {
     "@bastani/atomic": "*",
-    "@earendil-works/pi-tui": "^0.82.1"
+    "@earendil-works/pi-tui": "^0.83.0"
   },
   "peerDependenciesMeta": {
     "@bastani/atomic": {

package/dist/builtin/workflows/skills/impeccable/scripts/live-accept.mjs

@@ -772,7 +772,10 @@ function extractOriginal(lines, block) {
  */
 function extractVariant(lines, block, variantNum) {
   const text = stripStyleAndJoin(lines, block);
-  const inner = extractInnerByAttr(text, 'data-impeccable-variant="' + variantNum + '"');
+  // `variantNum` is digit-validated at the CLI boundary, but escape it anyway:
+  // it originates from a command-line argument, and an inert fragment is what
+  // CodeQL's js/regex-injection remediation asks for.
+  const inner = extractInnerByAttr(text, 'data-impeccable-variant="' + escapeRegExp(String(variantNum)) + '"');
   if (inner === null) return null;
   const result = inner.split('\n');
   // Collapse a lone empty leading/trailing line (common after string splice).

package/dist/builtin/workflows/skills/impeccable/scripts/live-browser-dom.js

@@ -66,7 +66,11 @@
 
     function id8() {
       if (crypto?.randomUUID) return crypto.randomUUID().replace(/-/g, '').slice(0, 8);
-      return (Math.random().toString(16).slice(2) + Date.now().toString(16)).slice(0, 8);
+      // Insecure-context fallback (plain-http LAN preview): still draw from the
+      // CSPRNG. Math.random here was flagged by CodeQL (js/insecure-randomness)
+      // because these ids name live-edit sessions.
+      const bytes = crypto.getRandomValues(new Uint8Array(4));
+      return Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
     }
 
     function cssId(id) {

package/dist/builtin/workflows/skills/impeccable/scripts/live-browser-session.js

@@ -11,7 +11,13 @@
   function createLiveBrowserSessionState({ prefix, storage, idFactory }) {
     if (!prefix) throw new Error('prefix required');
     const store = storage || root.localStorage;
-    const makeId = idFactory || function () { return Math.random().toString(16).slice(2, 10); };
+    const makeId = idFactory || function () {
+      // CSPRNG default: session owner ids gate recovery handoff, and the
+      // Math.random default was the same insecure-randomness class CodeQL
+      // flagged in the id8 helper.
+      const bytes = (root.crypto || crypto).getRandomValues(new Uint8Array(4));
+      return Array.from(bytes, function (byte) { return byte.toString(16).padStart(2, '0'); }).join('');
+    };
     const sessionKey = prefix + '-session';
     const handledKey = sessionKey + '-handled';
     const scrollKey = sessionKey + '-scroll';

package/dist/builtin/workflows/skills/impeccable/scripts/live-manual-edit-evidence.mjs

@@ -354,13 +354,16 @@ function normalizeText(value) {
 }
 
 function decodeBasicHtml(value) {
+  // `&` must decode last: decoding it first can manufacture entities such
+  // as `<` out of `<` that the later replacements then decode again
+  // (CodeQL js/double-escaping).
   return value
     .replace(/"/g, '"')
     .replace(/'/g, "'")
     .replace(/'/g, "'")
-    .replace(/&/g, '&')
     .replace(/&lt;/g, '<')
-    .replace(/&gt;/g, '>');
+    .replace(/&gt;/g, '>')
+    .replace(/&amp;/g, '&');
 }
 
 function escapeRegExp(value) {

package/dist/builtin/workflows/skills/impeccable/scripts/live-server.mjs

@@ -1048,7 +1048,13 @@ function handlePollGet(req, res, url) {
     return;
   }
   state.lastPollAt = Date.now();
-  const timeout = parseInt(url.searchParams.get('timeout') || DEFAULT_POLL_TIMEOUT, 10);
+  // The poll timeout is client-supplied; clamp it so a request cannot park a
+  // timer (and this connection) for an arbitrary duration (CodeQL
+  // js/resource-exhaustion). NaN falls back to the default.
+  const requestedTimeout = parseInt(url.searchParams.get('timeout') || DEFAULT_POLL_TIMEOUT, 10);
+  const timeout = Number.isFinite(requestedTimeout)
+    ? Math.min(Math.max(requestedTimeout, 0), DEFAULT_POLL_TIMEOUT)
+    : DEFAULT_POLL_TIMEOUT;
   const leaseMs = parseInt(url.searchParams.get('leaseMs') || '30000', 10);
   const types = parsePollTypes(url.searchParams.get('types'));
   const available = findAvailablePendingEvent(Date.now(), types);