@bastani/atomic 0.9.11-alpha.9 → 0.9.12-alpha.1

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

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/web-access",
-  "version": "0.9.11-alpha.9",
+  "version": "0.9.12-alpha.1",
   "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": [
@@ -46,6 +46,6 @@
     "linkedom": "^0.18.13",
     "p-limit": "^7.3.0",
     "turndown": "^7.2.0",
-    "unpdf": "^1.6.2"
+    "unpdf": "1.7.0"
   }
 }

package/dist/builtin/workflows/CHANGELOG.md

@@ -6,6 +6,74 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.9.12-alpha.1] - 2026-08-04
+
+### Added
+
+- Added `keepContext` to the public authoring surface: `import { keepContext } from "@bastani/workflows"`. It wraps prompt text so compaction protects it verbatim regardless of the compression ratio, and is a pure, idempotent string helper rather than a `ctx.*` primitive — no graph node, no side effect, callable anywhere a prompt is assembled. `KEEP_CONTEXT_OPEN_TAG` and `KEEP_CONTEXT_CLOSE_TAG` are exported alongside it. Reserve it for text whose loss silently changes behavior — role constraints, acceptance criteria, explicit prohibitions, and identifiers a stage must not lose — and not for bulk context, since protected lines count against the keep target rather than raising it ([#2172](https://github.com/bastani-inc/atomic/issues/2172)).
+- `<keepContext>` tags also work in the run inputs and steering messages sent through the `workflow` tool, not only in authored stage prompts. Workflows inject inputs into their stage prompts, so a tagged clause in `prompt` or `acceptance_criteria` is inherited and protected by every stage that receives it, and a tagged `send` amendment survives until the stage acts on it instead of competing with the whole transcript for retention. Because `keepContext` is idempotent, an already-tagged input is not double-wrapped by a workflow that protects the same field. The workflow tool description and agent guidance now say so, so an agent can decide per launch or per steering message which clauses to protect ([#2172](https://github.com/bastani-inc/atomic/issues/2172)).
+
+### Fixed
+
+- Builtin workflows protect their own invariants with `keepContext`, so a long-running stage can no longer lose the rules that bound it: the steering propagation contract carried by every builtin stage prompt, the literal objective contract, scope discipline, worktree discipline, ralph's per-run acceptance criteria, ralph's research-only role constraint, and goal's reviewer "inspect and report; do not implement" constraint. Previously a research stage could be compacted past its own prohibition and start implementing, and a stage could lose the checkout it was bound to ([#2172](https://github.com/bastani-inc/atomic/issues/2172)).
+
+## [0.9.11] - 2026-08-03
+
+### Added
+
+- Added per-node cancellation and abort targeting to `ctx.tool`. Every callback receives a `WorkflowToolContext` (`{ signal }`) combining a per-invocation controller with the run signal, and `workflow({ action: "quit"|"interrupt", runId, stageId })` resolves a tool node by expanded id, local `tool:<argsHash>` id, or tool name. Aborting one node leaves siblings running; existing zero-argument callbacks are unchanged ([#2078](https://github.com/bastani-inc/atomic/issues/2078)).
+- Added opt-in `ctx.tool(..., { failureMode: "return" })` for checks that may fail during repair flows, preserving bounded redacted `exitCode`, `stdout`, and `stderr` as typed durable data that replays without rerunning the callback ([#1993](https://github.com/bastani-inc/atomic/issues/1993)).
+- Re-added the built-in Goal and Ralph workflows with their typed composition exports, command metadata, tests, and docs.
+- Added a run-contract discipline to every builtin workflow: only the user may change a run's contract, mid-run steering and resume text are authoritative amendments, and each stage restates the amendments it received. Every bundled workflow wraps its context once through `withSteeringPropagationContext` (exported from `@bastani/workflows/builtin/steering-context`), so `ctx.task`, `ctx.chain`, and `ctx.parallel` prompts carry it automatically. Implementation stages also freeze acceptance criteria before writing code and keep a deferred list instead of a growing diff.
+- Added a draft handoff for `ralph` runs that exhaust their review budget: with `create_pr` enabled, the run opens a draft pull request reproducing every unresolved blocking finding with priority and cited `file:line` instead of leaving the branch unpushed.
+- Added the opt-in `autoAttach` workflow-definition field, which opens the graph overlay for interactive top-level named launches, and `ctx.models`, which optionally exposes the host session's model catalog to custom definitions.
+- Embedded DBOS Postgres now works when Atomic runs as root on Linux (containers, CI sandboxes, eval harnesses) by resolving an unprivileged system account and keeping the cluster under `/var/lib/atomic-postgres`.
+
+### Changed
+
+- Workflow invocations now assign a stable, non-`default` Intercom group from the top-level run identity and apply it to every Intercom-capable stage. Nested workflows, model fallback, pause/resume, durable replay, and subagent inheritance retain the group; separate runs stay isolated and explicit overrides still win, so authors no longer thread group names manually ([#1999](https://github.com/bastani-inc/atomic/issues/1999)).
+- Adopted Claude Opus 5 as the primary model for the Ralph prompt-engineer, orchestrator, and reviewer-A stages, the Goal orchestrator and reviewer stages, and the Open Claude Design chain, with Copilot and OpenRouter mirrors added throughout. Ralph's research and reviewer-B chains keep GPT-5.6 primaries and gain Opus 5 fallbacks.
+- Reworked the Goal, Ralph, Open Claude Design, and six pattern-workflow stage prompts, plus the bundled `prompt-engineer` skill (864 → 396 lines), for GPT-5.6, Claude Opus 5, and Claude Fable 5: artifacts before the final query, explicit output and stop contracts, evidence-grounded status claims, damped delegation, and no response prefilling or internal-reasoning requests. Schemas, convergence semantics, and exports are preserved.
+- Changed the builtin Goal execution stage from a direct worker into a Ralph-style sub-agent orchestrator that delegates implementation, validation, and documentation through the `subagent` tool and writes `orchestrator-receipt.md`, while retaining Goal's ledger, reviewer, reducer, and optional PR flow.
+- Strengthened reviewer prompts with a contract-probe playbook and a code-delta integrity contract: reviewers prove the delta exists in the review checkout before trusting receipts, treat claimed-but-absent work as blocking, and flag modified or deleted pre-existing tests ([#1973](https://github.com/bastani-inc/atomic/issues/1973)).
+- Strengthened workflow-authoring and routing guidance to require DAG-only dynamic topologies with pre-launch cycle rejection, bounded loop unrolling, and topology sketches, and to triage multi-item queues into bounded concurrent top-level runs with separate worktrees ([#2010](https://github.com/bastani-inc/atomic/issues/2010), [#2012](https://github.com/bastani-inc/atomic/issues/2012)).
+- Added a worktree-discipline contract to Goal and Ralph prompts (work stays in the invoking checkout), and made PR creation an explicitly authorized `create_pr=true` action rather than embedded task text.
+- Documented deterministic delivery timing for stage messages: `steer` is consumed after the current response finishes its whole tool batch and before the next model request, `followUp` only when the agent would otherwise stop ([#2074](https://github.com/bastani-inc/atomic/issues/2074)).
+- Workflow stage chat now renders Atomic's one-cell `∀` on the shared 88 ms luminance ramp, honours caller-supplied palettes through the detected terminal color mode, and drops redundant overlay status chrome.
+
+### Removed
+
+- Removed the parenthesized context-window authoring token (`(1m)`, `(1.1m)`, `(936k)`, `(long)`) from workflow model strings along with the `contextWindow` / `contextWindowStrict` stage options. Every stage session uses its model's catalog context window.
+- Removed Cursor model fallbacks and Cursor-branded Impeccable harness compatibility ([#1994](https://github.com/bastani-inc/atomic/issues/1994)), and removed the built-in `deep-research-codebase` workflow.
+
+### Fixed
+
+- Fixed workflow graph rendering and memory on large fan-outs. Cards, edges, and composed rows clip to the viewport; store observation offers a synchronous invalidation channel plus one memoized immutable graph projection per store version, so a status update no longer `JSON.stringify`/`JSON.parse`-clones the full run payload; and truncated fields plus durable tool-result summaries copy into fresh flat strings, since a V8 SlicedString kept multi-megabyte results alive behind a 240-character summary ([#2100](https://github.com/bastani-inc/atomic/issues/2100)).
+- Fixed graceful quit ignoring in-flight `ctx.tool` calls, which previously reported `No controllable stages on run <id>` and left callbacks running. Quit now counts running tool nodes as controllable work, closes the tool-admission boundary, aborts the whole root/nested set, and only then records the durable paused transition. Resume re-executes the cancelled call at the same node instead of replaying a cancellation as data, a caught cancellation cannot publish a completed run over quit's paused record, and a failed durable write still leaves the run controllable so a retried quit can upgrade the pause ([#2078](https://github.com/bastani-inc/atomic/issues/2078)).
+- Fixed durable nested `ctx.workflow(...)` resume and completed hydration across fresh processes: boundary identity persists before child dispatch, ids stay stable under reversed parallel ordering, and stale, aliased, cyclic, or nonreciprocal records fail closed instead of flattening an unrelated run. Completed child work and `ctx.tool(...)` effects stay exactly-once, and ambiguous child-local stage ids no longer route to the first match.
+- Fixed `ctx.tool()` calls durably completing side effects before a late empty-stage rejection. Tools now create ordered, inspectable, non-attachable graph nodes with live, failed, completed, cancelled, and cached states; tool-only workflows complete normally; and terminal publication closes admission so post-terminal calls reject before any callback runs ([#1991](https://github.com/bastani-inc/atomic/issues/1991)).
+- Fixed host-session replacement (`/new`, `/resume`, `/fork`, `/reload`) leaving the process-global DBOS executor stopped, so every later run in the same process failed at its first durable checkpoint with `` `DBOS.launch()` must be called before running workflows ``. The executor lifetime is now process-scoped, and the backend factory never hands out a stopped backend ([#1957](https://github.com/bastani-inc/atomic/issues/1957)).
+- Fixed stage message queues across detach and reattach: a typed Enter in an attached stage chat names steering explicitly instead of being demoted to a follow-up, the stage handle keeps its own projection of `queue_update` snapshots so pending rows survive detaching, the graph shows a `✉ N queued` badge, a session that arrives already holding queued messages replays the snapshot its listeners missed, and Escape restores queued steering and follow-ups into the editor ([#2074](https://github.com/bastani-inc/atomic/issues/2074)).
+- Fixed controlled workflow pauses allowing queued or late-arriving work to run after a stage was visibly paused. A synchronous raw queue hold is established before one serialized abort boundary, and resume releases preserved steering, follow-up, custom, async, and user entries exactly once ([#1983](https://github.com/bastani-inc/atomic/issues/1983)).
+- Fixed programmatic `workflow send` reopening retained stage conversations after the root workflow had terminated; terminal roots now return a structured `WORKFLOW_TERMINAL` failure before any session probing or delivery, while `/workflow attach` and Intercom keep their explicit post-mortem paths ([#2009](https://github.com/bastani-inc/atomic/issues/2009)).
+- Fixed three `open-claude-design` faults: a failed `user-feedback-*` stage no longer converts into design approval and exports an unreviewed design ([#2123](https://github.com/bastani-inc/atomic/issues/2123)); research context now persists to `<artifact_dir>/design-context.md` and `references.md` and is read through `reads` instead of embedded inline, removing the `413 request_too_large` class ([#2121](https://github.com/bastani-inc/atomic/issues/2121)); and each refinement round raises a run-level prompt naming the preview path and `file://` URL instead of blocking on live review while reporting `running` ([#2060](https://github.com/bastani-inc/atomic/issues/2060)).
+- Fixed the Ralph research stage destroying its own artifact by declaring the authored report path as its runner-owned `output`; research stages now return the full report as their final message. Fixed the Classify-and-act, Fan-out-and-synthesize, Generate-and-filter, Loop-until-done, and Tournament workflows returning whole terminal artifacts into the calling session's context — each `result` is now the compact artifact reference, with the full report on the existing path outputs.
+- Fixed admitted durable `ctx.tool(...)` failures being misclassified as killed or cancelled, and fixed failed physical session appends leaving malformed JSONL tails, duplicate ids, or phantom parents after a partial write ([#2021](https://github.com/bastani-inc/atomic/issues/2021)).
+- Fixed fresh-process resume and completed-run inspection losing nested child-workflow and parallel hierarchy, and fixed `workflow({ action: "resume", runId })` returning `Run not found` for eligible durably paused runs after session-local state was cleared ([#1924](https://github.com/bastani-inc/atomic/issues/1924)).
+- Fixed session teardown crashing the process with exit code 1 after DBOS provisioning had failed, which turned otherwise-successful `--print` runs into nonzero exits. When no durable backend can be provisioned at all, workflows degrade to a loud non-durable in-memory backend instead of failing every action.
+- Hardened the bundled `impeccable` live-mode scripts against four CodeQL findings (insecure randomness, resource exhaustion, regex injection, double escaping), preserving behaviour for all valid inputs.
+- Fixed retained terminal stage chats dropping the Working indicator after Enter and before the follow-up turn started ([#1982](https://github.com/bastani-inc/atomic/issues/1982)).
+
+## [0.9.11-alpha.11] - 2026-08-03
+
+### Fixed
+
+- Fixed workflow graph rendering for large, wide fan-outs by clipping cards, edges, and composed rows to the visible viewport, retaining cached topology and layout across status-only updates, and making idle animation eligibility constant-time ([#2100](https://github.com/bastani-inc/atomic/issues/2100)).
+- Fixed every interactive store mutation cloning the full run payload before the graph could repaint. A status or question update used to build a complete `JSON.stringify`/`JSON.parse` snapshot, traversing workflow inputs, authored stage result bodies, child output values, and tool input/output bodies, so mutation cost scaled with payload size rather than with the graph. Store observation now offers a synchronous invalidation-only channel plus one immutable memoized graph projection per store version, and the graph, overlay, attach pane, stage chat, widget, lifecycle and HIL notifications, resume picker, and send admission all read that projection. In the default configuration (`statusFile: false`), mutations no longer build the legacy full snapshot; enabling `statusFile` retains that snapshot and status-file serialization cost. Topology, status, timing, prompts, attachment state, notices, bounded returned-status fields, durable tool summaries, and child output counts are preserved; the existing `Store.snapshot()` / `Store.subscribe(snapshot)` contract is unchanged for external consumers ([#2100](https://github.com/bastani-inc/atomic/issues/2100)).
+- Fixed the memoized graph projection keeping whole run results in memory. Truncating a result field with `slice()` leaves a V8 SlicedString that points at its untruncated parent, so a 1 KiB projected field kept a multi-megabyte run result alive — inside the store's cached projection, and inside every long-lived holder of one — long after the run itself was removed. Truncated fields are now copied into fresh flat strings, so a session with large workflow results no longer grows heap ([#2100](https://github.com/bastani-inc/atomic/issues/2100)).
+- Fixed durable tool-result summaries retaining the payloads they summarize. `summarizeToolResult` and `summarizeCompletedToolResult` bounded a serialized value with `` `${serialized.slice(0, 237)}...` ``, which leaves a V8 SlicedString behind a ConsString, both pointing at the untruncated parent — so a 240-character summary written into a durable checkpoint or held in a completed-run catalog row kept the entire `JSON.stringify` output alive (measured at 8.4 MiB for one large tool result). Both summaries now copy into fresh flat strings via a shared `flattenTruncatedString` helper, which the memoized graph projection also uses ([#2100](https://github.com/bastani-inc/atomic/issues/2100)).
+- Fixed Escape in an attached workflow-stage chat restoring queued steering and follow-up messages into the editor instead of leaving them stuck in the pending-message queue.
+
 ## [0.9.11-alpha.9] - 2026-08-01
 
 ### Added

package/dist/builtin/workflows/README.md

@@ -608,7 +608,7 @@ Raw stage-chat prompt answer replay is live-memory only. `StageSnapshot.promptAn
 ```json
 {
   "name": "workflow",
-  "description": "Run named builtin, project, user, or package workflows; custom definitions may import reusable project/package workflows or builtin definitions from @bastani/workflows/builtin and nest them with ctx.workflow(...), including deeper composition within the configured maxDepth; when workflow execution fits but another shape would better achieve the task, author a custom TypeScript workflow({...}) inline with normal coding tools, reload it, and run it; after successfully creating and reloading a newly authored custom workflow, report the folder containing its generated code as 'Custom workflow created. You can inspect its code at: <workflow-folder-path>'; do this only for newly created custom workflows, never builtin or pre-existing workflows; discover with list/get/inputs/models, list session runs with status (no runId; statusFilter narrows the list), inspect status/stages/stage details, send prompt answers or steering only while the root workflow is nonterminal, pause/resume/interrupt/quit runs, and reload workflow resources. For large stage handoffs, write context to files/artifacts, pass paths via reads, and prompt downstream agents to 'Read the file at <path>...' instead of injecting large previous text. For transcripts, prefer status/stages/stage to get sessionFile/transcriptPath, quote the exact path without rewriting separators (Windows backslashes are valid), then search it with rg/grep and read small ranges; transcript is path-only by default when sessionFile/transcriptPath exists, explicit tail/limit returns bounded previews, and missing transcript paths fall back to a small preview. Use action 'models' to inspect models in the configured catalog; the result is a configured-auth snapshot showing what's present in the registry with configured authentication, not proof of credentials, entitlements, OAuth freshness, or live provider access. When authoring a workflow that should dynamically select a model, first call workflow({ action: 'models' }) to inspect the configured catalog, then select from the returned provider/id entries considering the isCurrent marker and available thinking levels.",
+  "description": "Run named builtin, project, user, or package workflows; custom definitions may import reusable project/package workflows or builtin definitions from @bastani/workflows/builtin and nest them with ctx.workflow(...), including deeper composition within the configured maxDepth; when workflow execution fits but another shape would better achieve the task, author a custom TypeScript workflow({...}) inline with normal coding tools, reload it, and run it; after successfully creating and reloading a newly authored custom workflow, report the folder containing its generated code as 'Custom workflow created. You can inspect its code at: <workflow-folder-path>'; do this only for newly created custom workflows, never builtin or pre-existing workflows; discover with list/get/inputs/models, list session runs with status (no runId; statusFilter narrows the list), inspect status/stages/stage details, send prompt answers or steering only while the root workflow is nonterminal, pause/resume/interrupt/quit runs, and reload workflow resources. For large stage handoffs, write context to files/artifacts, pass paths via reads, and prompt downstream agents to 'Read the file at <path>...' instead of injecting large previous text. Wrap critical parts of run inputs and steering messages in <keepContext>...</keepContext> so compaction preserves them verbatim in the stages that inherit them; tag role constraints, prohibitions, must-hold criteria, and identifiers, not background or bulk reference material. For transcripts, prefer status/stages/stage to get sessionFile/transcriptPath, quote the exact path without rewriting separators (Windows backslashes are valid), then search it with rg/grep and read small ranges; transcript is path-only by default when sessionFile/transcriptPath exists, explicit tail/limit returns bounded previews, and missing transcript paths fall back to a small preview. Use action 'models' to inspect models in the configured catalog; the result is a configured-auth snapshot showing what's present in the registry with configured authentication, not proof of credentials, entitlements, OAuth freshness, or live provider access. When authoring a workflow that should dynamically select a model, first call workflow({ action: 'models' }) to inspect the configured catalog, then select from the returned provider/id entries considering the isCurrent marker and available thinking levels.",
   "parameters": {
     "workflow": "string (optional) — workflow ID or normalized name",
     "inputs": "object (optional) — key/value map of workflow inputs",

package/dist/builtin/workflows/builtin/goal-ledger.ts

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
-import { mkdtemp, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
+import { writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { createWorkflowArtifactDirectory } from "../src/shared/workflow-artifacts.js";
 import { LEDGER_FILENAME, type GoalLedger, type GoalLifecycleEvent } from "./goal-types.js";
 
 type ModelVisibleGoalLedger = Omit<
@@ -55,11 +55,13 @@ export function appendLifecycleEvent(
 export async function createGoalLedger(
   objective: string,
   acceptanceCriteria = objective,
+  runId?: string,
 ): Promise<{ ledger: GoalLedger; ledgerPath: string; artifactDir: string }> {
-  const artifactDir = await mkdtemp(join(tmpdir(), "atomic-goal-runner-"));
+  const goalId = randomUUID();
+  const artifactDir = await createWorkflowArtifactDirectory(runId);
   const now = new Date().toISOString();
   const ledger: GoalLedger = {
-    goal_id: randomUUID(),
+    goal_id: goalId,
     objective,
     acceptance_criteria: acceptanceCriteria,
     status: "active",

package/dist/builtin/workflows/builtin/goal-prompts.ts

@@ -14,6 +14,7 @@ import {
   SCOPE_DISCIPLINE_CONTRACT,
   WORKER_PREFLIGHT_CONTRACT,
   WORKTREE_DISCIPLINE_CONTRACT,
+  keepContext,
   renderE2eQaVideoReviewGuidance,
 } from "./shared-prompts.js";
 import type { GoalLedger } from "./goal-types.js";
@@ -196,7 +197,9 @@ export function renderReviewerPrompt(args: {
       "Lead with the verdict. Keep evidence, decisions, caveats, and next action; omit background and repetition while remaining readable rather than using fragments, arrow chains, or invented shorthand.",
     ].join("\n")],
     ["objective", [
-      "Act as an independent, skeptical, technically fair reviewer. Inspect and report; do not implement. Protect correctness, security, performance, maintainability, and full objective completion without bikeshedding.",
+      keepContext(
+        "Act as an independent, skeptical, technically fair reviewer. Inspect and report; do not implement. Protect correctness, security, performance, maintainability, and full objective completion without bikeshedding.",
+      ),
       args.reviewerRole,
       args.focus,
       "Review the delivered change against the run objective stored in the goal ledger.",

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

@@ -64,6 +64,7 @@ function normalizeBranchInput(
 }
 type GoalRunnerContext = {
   readonly inputs: GoalWorkflowInputs;
+  readonly runId?: string;
   task(name: string, options: WorkflowTaskOptions): Promise<WorkflowTaskResult>;
   parallel(steps: readonly WorkflowTaskStep[], options: WorkflowParallelOptions): Promise<WorkflowTaskResult[]>;
 };
@@ -109,7 +110,7 @@ export async function runGoalWorkflow(ctx: GoalRunnerContext, options: GoalWorkf
     const reviewQuorum = DEFAULT_REVIEW_QUORUM;
     const blockerThreshold = Math.min(DEFAULT_BLOCKER_THRESHOLD, maxTurns);
     const comparisonBaseBranch = normalizeBranchInput(inputs.base_branch, "origin/main");
-    const { ledger, ledgerPath, artifactDir } = await createGoalLedger(objective, acceptanceCriteria);
+    const { ledger, ledgerPath, artifactDir } = await createGoalLedger(objective, acceptanceCriteria, ctx.runId);
 
     let latestReviews: ReviewRecord[] = [];
     let latestReviewArtifactPaths: string[] = [];

package/dist/builtin/workflows/builtin/goal.ts

@@ -47,7 +47,7 @@ export default workflow({
     goal_id: Type.Optional(Type.String({ description: "Per-run goal identifier stored in the ledger." })),
     objective: Type.Optional(Type.String({ description: "Raw goal objective used by the run." })),
     acceptance_criteria: Type.Optional(Type.String({ description: "Immutable acceptance criteria used by the run." })),
-    ledger_path: Type.Optional(Type.String({ description: "OS-temp path to goal-ledger.json with receipts, reviewer decisions, blockers, and lifecycle events." })),
+    ledger_path: Type.Optional(Type.String({ description: "Durable run-scoped path to goal-ledger.json with receipts, reviewer decisions, blockers, and lifecycle events." })),
     turns_completed: Type.Optional(Type.Number({ description: "Orchestrator/review turns completed." })),
     iterations_completed: Type.Optional(Type.Number({ description: "Orchestrator/review turns completed, retained for status summaries." })),
     receipts: Type.Optional(Type.Array(Type.Object({

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

@@ -1,10 +1,11 @@
-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,
+  keepContext,
   LITERAL_OBJECTIVE_CONTRACT,
 } from "./shared-prompts.js";
 import type { ReviewDecision, ReviewFinding } from "./ralph-review-gate.js";
@@ -170,8 +171,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 +196,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);
 }
 
@@ -336,7 +337,7 @@ export function renderResearchPromptRefinementPrompt(args: {
   readonly latestReviewReportPath: string | undefined;
 }): string {
   return taggedPrompt([
-    ["acceptance_criteria", args.acceptanceCriteria],
+    ["acceptance_criteria", keepContext(args.acceptanceCriteria)],
     ["literal_contract", LITERAL_OBJECTIVE_CONTRACT],
     args.workflowCwdContext,
     [
@@ -351,7 +352,9 @@ export function renderResearchPromptRefinementPrompt(args: {
     ["objective", `Research the full requested task: ${args.request}`],
     [
       "output",
-      "Return only one concise, complete codebase and online research question. Do not implement code changes or write an RFC/spec.",
+      keepContext(
+        "Return only one concise, complete codebase and online research question. Do not implement code changes or write an RFC/spec.",
+      ),
     ],
     [
       "instruction",
@@ -367,10 +370,9 @@ export function renderResearchPrompt(args: {
   readonly acceptanceCriteria: string;
   readonly workflowCwdContext: PromptSection;
   readonly latestReviewReportPath: string | undefined;
-  readonly researchPath: string;
 }): string {
   return taggedPrompt([
-    ["acceptance_criteria", args.acceptanceCriteria],
+    ["acceptance_criteria", keepContext(args.acceptanceCriteria)],
     ["literal_contract", LITERAL_OBJECTIVE_CONTRACT],
     args.workflowCwdContext,
     [
@@ -386,11 +388,10 @@ 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.",
+        keepContext("This stage researches only. Do not author an RFC/spec or implement code changes."),
       ].join("\n"),
     ],
     [
@@ -417,6 +418,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

@@ -1,5 +1,6 @@
 // Forked stages inherit their contracts and receive only the iteration delta.
 import { taggedPrompt } from "./ralph-core.js";
+import { keepContext } from "./shared-prompts.js";
 
 export function renderForkedResearchPromptRefinementPrompt(args: {
   readonly latestReviewReportPath: string | undefined;
@@ -16,7 +17,9 @@ export function renderForkedResearchPromptRefinementPrompt(args: {
     ],
     [
       "output",
-      "Return only one concise, complete codebase and online research question. Do not implement code changes or write an RFC/spec.",
+      keepContext(
+        "Return only one concise, complete codebase and online research question. Do not implement code changes or write an RFC/spec.",
+      ),
     ],
     [
       "instruction",
@@ -28,7 +31,6 @@ export function renderForkedResearchPromptRefinementPrompt(args: {
 export function renderForkedResearchPrompt(args: {
   readonly transformedResearchQuestion: string;
   readonly latestReviewReportPath: string | undefined;
-  readonly researchPath: string;
 }): string {
   return taggedPrompt([
     [
@@ -43,10 +45,9 @@ 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.",
-        "Do not author an RFC/spec or implement code changes.",
+        "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.",
+        keepContext("This stage researches only. 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-reviewer-prompt.ts

@@ -10,6 +10,7 @@ import {
   REVIEWER_OVERIMPLEMENTATION_GUARD,
   REVIEWER_SPEC_VS_OBJECTIVE_GUARD,
   WORKTREE_DISCIPLINE_CONTRACT,
+  keepContext,
   renderE2eQaVideoReviewGuidance,
 } from "./shared-prompts.js";
 import { taggedPrompt, type PromptSection } from "./ralph-core.js";
@@ -26,7 +27,7 @@ export function renderRalphReviewerPrompt(args: {
   readonly createPr: boolean;
 }): string {
   return taggedPrompt([
-    ["acceptance_criteria", args.acceptanceCriteria],
+    ["acceptance_criteria", keepContext(args.acceptanceCriteria)],
     [
       "review_context",
       [

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,
@@ -12,6 +11,7 @@ import {
   SCOPE_DISCIPLINE_CONTRACT,
   WORKER_PREFLIGHT_CONTRACT,
   WORKTREE_DISCIPLINE_CONTRACT,
+  keepContext,
 } from "./shared-prompts.js";
 import { renderRalphReviewerPrompt } from "./ralph-reviewer-prompt.js";
 import {
@@ -52,7 +52,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 +63,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 +98,10 @@ export async function runRalphWorkflow(
             acceptanceCriteria,
             workflowCwdContext,
             latestReviewReportPath,
-            researchPath: workflowResearchPath,
           })
         : renderForkedResearchPrompt({
             transformedResearchQuestion: researchPromptRefinement.text,
             latestReviewReportPath,
-            researchPath: workflowResearchPath,
           }),
       reads: latestReviewReportPath === undefined ? [] : [latestReviewReportPath],
       output: workflowResearchPath,
@@ -120,7 +118,7 @@ export async function runRalphWorkflow(
     const orchestratorForkOptions = forkContinuationOptions(previousOrchestratorSessionFile);
     const orchestratorPrompt = orchestratorForkOptions.forkFromSessionFile === undefined
       ? taggedPrompt([
-        ["acceptance_criteria", acceptanceCriteria],
+        ["acceptance_criteria", keepContext(acceptanceCriteria)],
         ["literal_contract", LITERAL_OBJECTIVE_CONTRACT],
         ["acceptance_matrix", ACCEPTANCE_MATRIX_CONTRACT],
         ["divergence_audit", CONTRACT_FIDELITY_AUDIT],

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/builtin/shared-prompts.ts

@@ -1,3 +1,9 @@
+// Builtin prompts use the same public `keepContext` helper workflow authors do, so the
+// protection semantics cannot drift between builtin and user-authored workflows.
+import { keepContext } from "../src/authoring/keep-context.js";
+
+export { keepContext };
+
 /**
  * Steering propagation is a whole-repository pattern, not a per-workflow
  * option: every builtin stage prompt carries STEERING_PROPAGATION_CONTRACT
@@ -29,10 +35,15 @@ export const STEERING_PROPAGATION_CONTRACT = [
  * section, which carries the strongest positional weight. The contract is
  * inserted immediately before that closing section rather than after it, so a
  * stage's final words remain its instruction.
+ *
+ * The contract is `keepContext`-protected because only the user may amend a run's contract,
+ * and an amendment reaches later stages solely through this restatement duty. Compacted away,
+ * the run silently reverts to the launch contract while the implementer builds to the amended
+ * one — the exact split this pattern exists to prevent.
  */
 export function withSteeringPropagation(prompt: string): string {
   if (prompt.includes("<steering_propagation>")) return prompt;
-  const tagged = `<steering_propagation>\n${STEERING_PROPAGATION_CONTRACT}\n</steering_propagation>`;
+  const tagged = `<steering_propagation>\n${keepContext(STEERING_PROPAGATION_CONTRACT)}\n</steering_propagation>`;
   const instructionAt = prompt.lastIndexOf("\n\n<instruction>");
   if (instructionAt === -1) return `${prompt}\n\n${tagged}`;
   return `${prompt.slice(0, instructionAt)}\n\n${tagged}${prompt.slice(instructionAt)}`;
@@ -69,7 +80,12 @@ export function renderE2eQaVideoReviewGuidance(
   ].join("\n");
 }
 
-export const LITERAL_OBJECTIVE_CONTRACT = [
+/**
+ * `keepContext`-protected: this is the run's immutable contract and its central prohibition
+ * ("You may never widen the contract yourself"). A prohibition deleted from context reads as
+ * permission, so losing it turns scope creep into apparently sanctioned work.
+ */
+export const LITERAL_OBJECTIVE_CONTRACT = keepContext([
   "Literal objective contract:",
   "- The objective and acceptance criteria are the sole literal source of required behavior; the run objective must not contradict them.",
   "- Only the user may change the contract. A mid-run user message — steering, a follow-up, or resume text — is authoritative: adopt it as required behavior from that point on, and carry it forward under the steering propagation contract. You may never widen the contract yourself; an improvement you thought of is deferred work, not a new criterion.",
@@ -78,7 +94,7 @@ export const LITERAL_OBJECTIVE_CONTRACT = [
   "- That loud-error preference applies only to enumerated errors. Otherwise accept permissively: do not invent behavior, restrictions, validation errors, required fields, uniqueness/format constraints, or follow-up requirements.",
   "- Produce named types, shapes, and formats exactly; do not substitute proxies, frozen collections, tuples-for-lists, or wrappers unless required because consumers may check identity.",
   "- Where behavior is unspecified, preserve input verbatim rather than normalizing, deduplicating, reordering, or rewriting it.",
-].join("\n");
+].join("\n"));
 
 export const REVIEWER_SPEC_VS_OBJECTIVE_GUARD =
   "External spec/standard conformance alone does not make a wide trigger for an enumerated error defective; classify that spec-vs-objective tension as beyond_objective, not blocking.";
@@ -129,7 +145,12 @@ export const FINDINGS_CONSOLIDATION_CONTRACT = [
   "Defer only a genuinely blocked or contract-contradicting finding, recording the reason in the receipt.",
 ].join("\n");
 
-export const SCOPE_DISCIPLINE_CONTRACT = [
+/**
+ * `keepContext`-protected: every clause here is a prohibition, and prohibitions are the class
+ * compaction erodes first — they are terse, stated once, and low-density next to the objective
+ * they bound. Losing this reads as license to keep going.
+ */
+export const SCOPE_DISCIPLINE_CONTRACT = keepContext([
   "Scope discipline:",
   "- Before writing code, state the goal in one sentence and list the acceptance criteria. That list is the contract. Freeze it.",
   "- Done means the contract, not \"good.\" When all criteria pass, stop. Polish, refactors, and \"while I'm here\" fixes are new work, not this work.",
@@ -139,7 +160,7 @@ export const SCOPE_DISCIPLINE_CONTRACT = [
   "- Watch for the tells. \"It would be cleaner if...\", \"we should also...\", \"this really ought to...\" mean you are about to move the goalpost. Stop and check the contract.",
   "- Prefer the smallest diff that satisfies the contract: fewer files touched, fewer abstractions introduced, no speculative generality for futures nobody asked for.",
   "- Report three things at the end: what the contract was, evidence each criterion passes, and the deferred list. Scope changes belong in the report, never in the diff.",
-].join("\n");
+].join("\n"));
 
 export const EVIDENCE_CLOSURE_POLICY = [
   "Convergence flag (stop_review_loop):",
@@ -149,10 +170,16 @@ export const EVIDENCE_CLOSURE_POLICY = [
   "- If the bounded loop ends first, preserve unresolved findings and remaining work for a human rather than relabeling them.",
 ].join("\n");
 
-export const WORKTREE_DISCIPLINE_CONTRACT = [
+/**
+ * `keepContext`-protected: this binds the stage to a specific checkout, and a checkout is
+ * exactly the kind of identifier a stage must not lose. Compacted away during a long run, an
+ * agent hitting a lock or dirty state invents a second worktree and the delivered delta lands
+ * somewhere the reviewers never look. It is two lines, so protection costs almost nothing.
+ */
+export const WORKTREE_DISCIPLINE_CONTRACT = keepContext([
   "Work in the workflow-designated checkout. Do not create another worktree, clone, or repository copy unless the task requests it; conflicts, locks, dirty state, and failed commands do not authorize one.",
   "Bring required work found elsewhere into this checkout by applying, cherry-picking, or replaying it before continuing.",
-].join("\n");
+].join("\n"));
 
 export const REVIEW_CODE_DELTA_CONTRACT = [
   "Code delta integrity:",

package/dist/builtin/workflows/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/workflows",
-  "version": "0.9.11-alpha.9",
+  "version": "0.9.12-alpha.1",
   "private": true,
   "description": "Atomic extension for multi-stage workflow authoring and execution.",
   "contributors": [

package/dist/builtin/workflows/src/authoring/keep-context.ts

@@ -0,0 +1,46 @@
+/**
+ * `keepContext` marks prompt text that compaction must never compress.
+ *
+ * This is a pure string transform rather than a `ctx.*` primitive: it creates no graph node,
+ * has no side effect, and needs no durability, so it is safe to call anywhere a prompt is
+ * assembled — including outside a run.
+ */
+
+export const KEEP_CONTEXT_OPEN_TAG = "<keepContext>";
+export const KEEP_CONTEXT_CLOSE_TAG = "</keepContext>";
+
+/**
+ * Wrap text so compaction protects it verbatim.
+ *
+ * Every line of the span, tag lines included, becomes a protected line, and protected lines are
+ * removed from the planner's deletion ranges after it responds, so the span survives regardless
+ * of the compression ratio. Because the tag lines are protected too, the span is re-detected on
+ * each subsequent boundary and stays protected for the life of the session.
+ *
+ * Tags must sit on their own line, and a span is scoped to one message. User and assistant
+ * messages may both protect, so an agent can pin its own core information as well as its prompt;
+ * tags inside tool results are inert, so file, page, or command output an agent reads cannot
+ * mark itself unreclaimable.
+ *
+ * Reserve it for text whose loss silently changes behavior — role constraints, acceptance
+ * criteria and immutable contracts, explicit prohibitions, and identifiers a stage must not
+ * lose such as a target branch, worktree path, or run ID. Compaction ranks lines individually,
+ * so a terse constraint loses to the verbose objective it qualifies, and a prohibition deleted
+ * from context reads as permission.
+ *
+ * Do not wrap bulk context. Protected lines count against the keep target rather than raising
+ * it, so a large protected span makes the surrounding transcript compress harder; tag the
+ * constraint, not the material it applies to, and pass that through files and `reads`.
+ *
+ * Nesting is flattened rather than rejected: an already-wrapped string is returned unchanged.
+ *
+ * @example
+ * ```ts
+ * const prompt = `${keepContext("Research only. Do not implement code changes.")}\n\n${question}`;
+ * ```
+ */
+export function keepContext(text: string): string {
+	const trimmed = text.trim();
+	if (trimmed.startsWith(KEEP_CONTEXT_OPEN_TAG) && trimmed.endsWith(KEEP_CONTEXT_CLOSE_TAG)) return trimmed;
+	return `${KEEP_CONTEXT_OPEN_TAG}\n${trimmed}\n${KEEP_CONTEXT_CLOSE_TAG}`;
+}

package/dist/builtin/workflows/src/authoring.d.ts

@@ -44,6 +44,17 @@ export interface WorkflowRegistry {
  */
 export declare const runWorkflow: never;
 export declare function workflow<const TInputs extends WorkflowInputSchemaMap = Record<never, never>, const TOutputs extends WorkflowOutputSchemaMap = WorkflowOutputSchemaMap, TActualOutputs extends WorkflowOutputsFromSchemas<TOutputs> = WorkflowOutputsFromSchemas<TOutputs>>(spec: AuthoredWorkflowSpec<TInputs, TOutputs, TActualOutputs>): AuthoredWorkflowDefinition<TInputs, TOutputs>;
+/**
+ * Wrap prompt text so compaction protects it verbatim, regardless of the compression ratio.
+ *
+ * Reserve it for text whose loss silently changes behavior: role constraints, acceptance
+ * criteria and immutable contracts, explicit prohibitions, and identifiers a stage must not
+ * lose. Do not wrap bulk context — protected lines count against the keep target rather than
+ * raising it, so a large span makes the surrounding transcript compress harder.
+ */
+export declare function keepContext(text: string): string;
+export declare const KEEP_CONTEXT_OPEN_TAG: string;
+export declare const KEEP_CONTEXT_CLOSE_TAG: string;
 export declare function createRegistry<TDefinitions extends readonly AnyWorkflowDefinition[] = readonly AnyWorkflowDefinition[]>(initial?: TDefinitions): WorkflowRegistry;
 export declare function normalizeWorkflowName(name: string): string;
 export declare function workflowNamesEqual(a: string, b: string): boolean;