@joshski/dust 0.1.101 → 0.1.103

package/.dust/principles/{enable-flow-state.md → agentic-flow-state.md}

@@ -1,14 +1,18 @@
-# Enable Flow State
+# Agentic Flow State
 
 Flow is the mental state where work becomes effortless - where you're fully immersed, losing track of time, operating at peak performance. Psychologist Mihaly Csikszentmihalyi identified three conditions that create flow: clear goals, immediate feedback, and challenge-skill balance.
 
+For AI agents, achieving flow state means staying engaged and productive without interruption. Agents enter flow when they have optimal context, comprehensive guard rails, and minimal friction. Context window optimization ensures agents have exactly what they need without cognitive overload. In-session guard rails prevent agents from straying off course or making mistakes that break their momentum.
+
 Dust's design targets these conditions directly:
 
 - **Clear goals**: Task files and lightweight planning give you a concrete target. You know exactly what you're building next.
 - **Immediate feedback**: Fast feedback loops let you see results quickly. Each change confirms you're on track or shows you what to adjust.
 - **Challenge-skill balance**: Small units of work and agent autonomy keep you in the zone - challenged enough to stay engaged, supported enough to succeed.
+- **Context window efficiency**: Progressive disclosure and artifact summarization ensure agents have the right context without overflow.
+- **Comprehensive guard rails**: Lint rules, type checks, and automated validation catch mistakes before they compound.
 
-Everything dust does serves flow. When developers stay in flow, they produce better work, sustain their energy, and enjoy the process.
+Everything dust does serves flow. When agents stay in flow, they produce better work, sustain their momentum, and complete tasks autonomously.
 
 ## Parent Principle
 

package/.dust/principles/human-ai-collaboration.md

@@ -8,7 +8,7 @@ Today's AI coding tools keep humans in a tight loop with agents. Dust is designe
 
 ## Parent Principle
 
-- [Enable Flow State](enable-flow-state.md)
+- [Agentic Flow State](agentic-flow-state.md)
 
 ## Sub-Principles
 

package/.dust/principles/maintainable-codebase.md

@@ -6,7 +6,7 @@ This principle governs how we develop and maintain dust itself, separate from th
 
 ## Parent Principle
 
-- [Enable Flow State](enable-flow-state.md)
+- [Agentic Flow State](agentic-flow-state.md)
 
 ## Sub-Principles
 

package/dist/agent-events.d.ts

@@ -50,6 +50,7 @@ export interface EventMessage {
     repository: string;
     repoId?: number;
     agentSessionId?: string;
+    traceId?: string;
     event: AgentSessionEvent;
 }
 /**

package/dist/audits.js

@@ -141,11 +141,12 @@ function checksAuditTemplate() {
     - Created ideas for each missing check category
     - For multi-ecosystem projects, created separate ideas per ecosystem
     - Each idea includes suggested command and alternatives
+    - No changes to files outside \`.dust/\`
   `;
 }
 
 // lib/audits/stock-audits.ts
-var ideasHint = "Review existing ideas in `./.dust/ideas/` to understand what has been proposed or considered historically, then create new idea files in `./.dust/ideas/` for any issues you identify, avoiding duplication.";
+var ideasHint = "Review existing ideas in `./.dust/ideas/` to understand what has been proposed or considered historically, then create new idea files in `./.dust/ideas/` for any issues you identify, avoiding duplication. Do not modify source code - create ideas instead.";
 function dataAccessReview() {
   return dedent`
     # Data Access Review
@@ -196,6 +197,7 @@ function dataAccessReview() {
     - Checked for sequential operations that could be batched
     - Verified connection/resource cleanup is handled properly
     - Proposed ideas for any data access improvements identified
+    - No changes to files outside \`.dust/\`
   `;
 }
 function coverageExclusions() {
@@ -243,6 +245,7 @@ function coverageExclusions() {
     - Labeled justification quality for visibility
     - Identified exclusions that could be removed through decoupling
     - Proposed ideas for refactoring where feasible
+    - No changes to files outside \`.dust/\`
   `;
 }
 function componentReuse() {
@@ -273,6 +276,7 @@ function componentReuse() {
     - Evaluated each case for whether extraction would be beneficial
     - Considered whether similar code serves different purposes that may evolve independently
     - Proposed ideas only for extractions where duplication is truly about the same concept
+    - No changes to files outside \`.dust/\`
   `;
 }
 function agentDeveloperExperience() {
@@ -304,6 +308,7 @@ function agentDeveloperExperience() {
     - Measured feedback loop speed (time from change to check result)
     - Confirmed debugging tools and structured logging are in place
     - Proposed ideas for any improvements identified
+    - No changes to files outside \`.dust/\`
   `;
 }
 function agentInstructionQuality() {
@@ -468,6 +473,7 @@ function agentInstructionQuality() {
     - Found instructions that could be replaced by linter rules
     - Documented each issue with location, type, impact, and suggestion
     - Created ideas for substantial instruction improvements
+    - No changes to files outside \`.dust/\`
   `;
 }
 function deadCode() {
@@ -501,6 +507,7 @@ function deadCode() {
     - Created list of code safe to remove
     - Verified removal won't break dynamic imports or reflection
     - Proposed ideas for any dead code worth removing
+    - No changes to files outside \`.dust/\`
   `;
 }
 function documentationDrift() {
@@ -614,6 +621,7 @@ function documentationDrift() {
     - Reviewed inline comments for outdated descriptions
     - Documented each drift finding with location, claim, reality, and suggested fix
     - Created ideas for any substantial documentation updates needed
+    - No changes to files outside \`.dust/\`
   `;
 }
 function factsVerification() {
@@ -649,6 +657,7 @@ function factsVerification() {
     - Listed missing facts that would help agents
     - Updated or removed stale facts
     - Proposed ideas for any facts improvements needed
+    - No changes to files outside \`.dust/\`
   `;
 }
 function feedbackLoopSpeed() {
@@ -775,6 +784,7 @@ function feedbackLoopSpeed() {
     - Flagged dominant checks (>30% of total time)
     - Documented findings in summary table format
     - Created ideas for any feedback loop speed improvements identified
+    - No changes to files outside \`.dust/\`
   `;
 }
 function ideasFromPrinciples() {
@@ -808,6 +818,7 @@ function ideasFromPrinciples() {
     - Analyzed codebase for alignment with each principle
     - Listed gaps between current state and principle intent
     - Proposed new ideas for unmet or underserved principles
+    - No changes to files outside \`.dust/\`
   `;
 }
 function commitReview() {
@@ -860,6 +871,7 @@ function commitReview() {
     - Noted areas where changes could be generalized
     - Provided specific suggestions for each opportunity
     - Created ideas for any substantial work identified
+    - No changes to files outside \`.dust/\`
   `;
 }
 function securityReview() {
@@ -924,6 +936,7 @@ function securityReview() {
     - Ran lightweight pattern scan for obvious issues (documented as supplementary)
     - Created ideas for any missing security tooling categories
     - Each idea specifies which tool to add and where to configure it
+    - No changes to files outside \`.dust/\`
   `;
 }
 function staleIdeas() {
@@ -958,6 +971,7 @@ function staleIdeas() {
     - Reviewed each stale idea for current relevance
     - Promoted actionable ideas to tasks
     - Deleted ideas that are no longer relevant
+    - No changes to files outside \`.dust/\`
   `;
 }
 function errorHandling() {
@@ -1006,6 +1020,7 @@ function errorHandling() {
     - Reviewed error messages for actionability
     - Compared error handling consistency across similar operations
     - Proposed ideas for any error handling improvements identified
+    - No changes to files outside \`.dust/\`
   `;
 }
 function globalState() {
@@ -1056,6 +1071,7 @@ function globalState() {
     - Checked for scattered process.env access
     - Documented impact of each global state instance on testing
     - Proposed ideas for refactoring global state to explicit dependencies
+    - No changes to files outside \`.dust/\`
   `;
 }
 function repositoryContext() {
@@ -1105,6 +1121,7 @@ function repositoryContext() {
     - Design philosophy or guiding approach is captured
     - Document is concise enough to fit comfortably in an agent context window
     - A new agent reading only this document could make sensible high-level suggestions
+    - No changes to files outside \`.dust/\`
   `;
 }
 function slowTests() {
@@ -1157,6 +1174,7 @@ function slowTests() {
     - Reviewed beforeEach/beforeAll for optimization opportunities
     - Checked test parallelization configuration
     - Proposed ideas for optimizing the slowest tests
+    - No changes to files outside \`.dust/\`
   `;
 }
 function primitiveObsession() {
@@ -1225,6 +1243,7 @@ function primitiveObsession() {
     - Preserved Functional Core, Imperative Shell boundaries in recommendations
     - Avoided speculative introduction of entirely new types
     - Proposed ideas for primitive obsession improvements identified
+    - No changes to files outside \`.dust/\`
   `;
 }
 function singleResponsibilityViolations() {
@@ -1283,6 +1302,7 @@ function singleResponsibilityViolations() {
     - Preserved Functional Core, Imperative Shell boundaries in recommendations
     - Kept recommendations high-confidence only with clear concern boundaries
     - Proposed ideas for substantial responsibility-splitting work identified
+    - No changes to files outside \`.dust/\`
   `;
 }
 function ubiquitousLanguage() {
@@ -1347,6 +1367,7 @@ function ubiquitousLanguage() {
     - Reviewed factory/constructor naming for \`build*\`, \`create*\`, \`make*\`, \`new*\` consistency
     - Documented any terminology drift or inconsistencies found
     - Proposed ideas for standardizing inconsistent terminology
+    - No changes to files outside \`.dust/\`
   `;
 }
 function designPatterns() {
@@ -1414,6 +1435,7 @@ function designPatterns() {
     - Documented each finding with location, code smell, recommended pattern, trade-offs, and migration complexity
     - Noted tech-stack considerations where Gang of Four patterns may or may not apply
     - Proposed ideas for any design pattern improvements identified
+    - No changes to files outside \`.dust/\`
   `;
 }
 function testAssertions() {
@@ -1565,6 +1587,7 @@ function testAssertions() {
     - Found tests covering multiple unrelated behaviors
     - Documented each finding with location, pattern, impact, and suggestion
     - Proposed ideas for any assertion quality improvements identified
+    - No changes to files outside \`.dust/\`
   `;
 }
 function algorithms() {
@@ -1618,6 +1641,7 @@ function algorithms() {
     - Checked recursive graph/tree operations for cycle protection
     - Documented each finding with function name, location, complexity, data structures, optimization, and acceptability assessment
     - Proposed ideas for any algorithmic improvements identified
+    - No changes to files outside \`.dust/\`
   `;
 }
 function loggingAndTraceability() {
@@ -1670,6 +1694,7 @@ function loggingAndTraceability() {
     - Assessed whether running the application produces understandable output
     - Tested whether logs help diagnose common failure scenarios
     - Proposed ideas for any logging improvements identified
+    - No changes to files outside \`.dust/\`
   `;
 }
 function testPyramid() {
@@ -1751,6 +1776,7 @@ function testPyramid() {
     - Identified miscategorized tests (e.g., unit tests with I/O)
     - Provided specific recommendations to improve pyramid shape
     - Proposed ideas for any substantial test restructuring needed
+    - No changes to files outside \`.dust/\`
   `;
 }
 function idiomaticStyle() {
@@ -1812,6 +1838,7 @@ function idiomaticStyle() {
     - Evaluated code style consistency with rest of codebase
     - Identified anti-patterns or deprecated approaches
     - Proposed ideas for any idiomaticity improvements identified
+    - No changes to files outside \`.dust/\`
   `;
 }
 function uxAudit() {
@@ -1876,6 +1903,7 @@ function uxAudit() {
     - Documented findings with evidence and recommendations
     - Included verification criteria for each issue
     - Created ideas for any UX improvements needed
+    - No changes to files outside \`.dust/\`
   `;
 }
 function dependencyHealth() {
@@ -2018,6 +2046,7 @@ function dependencyHealth() {
     - Searched for packages with known better-maintained alternatives
     - Documented each concern with package name, version, type, and suggested action
     - Created ideas for any dependency health improvements needed
+    - No changes to files outside \`.dust/\`
   `;
 }
 function ciDevelopmentParity() {
@@ -2175,6 +2204,7 @@ function ciDevelopmentParity() {
     - Identified CI-only checks (in CI but not dust)
     - Created idea files for each gap with suggested fix
     - Each idea links to relevant principles
+    - No changes to files outside \`.dust/\`
   `;
 }
 function commitMessageQuality() {
@@ -2324,6 +2354,7 @@ function commitMessageQuality() {
     - Identified commits missing links to issues/tasks
     - Created idea files for patterns found
     - Each idea includes concrete suggestions for improvement
+    - No changes to files outside \`.dust/\`
   `;
 }
 function suggestAudits() {
@@ -2413,6 +2444,7 @@ function suggestAudits() {
     - Identified relevant audits based on change patterns
     - Created task files for each suggested audit with rationale
     - Each task explains why the audit is valuable given recent changes
+    - No changes to files outside \`.dust/\`
   `;
   return content;
 }

package/dist/bucket/repository.d.ts

@@ -67,6 +67,10 @@ export interface RepositoryDependencies {
     revealFamily?: (familyName: string) => void;
     /** Shell runner for pre-flight commands (install, check) */
     shellRunner?: import('../cli/process-runner').ShellRunner;
+    /** Force Docker mode using bundled default Dockerfile */
+    forceDocker?: boolean;
+    /** Force Apple Container mode using bundled default Dockerfile */
+    forceAppleContainer?: boolean;
 }
 /**
  * Start (or restart) the per-repository loop and keep lifecycle state accurate.

package/dist/claude/spawn-claude-code.d.ts

@@ -1,5 +1,17 @@
 import type { CreateReadlineForEvents, SpawnForEvents } from '../process/spawn-contract';
 import type { DockerSpawnConfig, RawEvent, SpawnOptions } from './types';
+/**
+ * Generate Claude Code settings JSON with apiKeyHelper configured to fetch
+ * tokens from the given proxy URL.
+ *
+ * The helper command uses curl to fetch a short-TTL helper token from the
+ * host-side proxy's /token endpoint. This token is validated by the proxy
+ * when the container makes Claude API requests.
+ *
+ * @param proxyUrl - The Claude API proxy URL (e.g., http://host.docker.internal:3002)
+ * @returns Settings JSON string for Claude Code
+ */
+export declare function generateApiKeyHelperSettings(proxyUrl: string): string;
 export interface EventSourceDependencies {
     spawn: SpawnForEvents;
     createInterface: CreateReadlineForEvents;

package/dist/claude/types.d.ts

@@ -48,6 +48,10 @@ export interface OutputSink {
     line(text: string): void;
 }
 export interface DockerSpawnConfig {
+    /** CLI command for running containers (e.g., 'docker', 'container') */
+    runCommand?: string;
+    /** Hostname or IP the container uses to reach the host */
+    hostAddress?: string;
     /** Docker image tag to use */
     imageTag: string;
     /** Path to the repository (used for volume mounts) */
@@ -58,6 +62,8 @@ export interface DockerSpawnConfig {
     gitProxyUrl?: string;
     /** Claude API proxy URL (e.g., http://host.docker.internal:3002) */
     claudeApiProxyUrl?: string;
+    /** Path to settings file on host to mount into container (for apiKeyHelper) */
+    settingsFilePath?: string;
 }
 export interface SpawnOptions {
     cwd?: string;

package/dist/codex/spawn-codex.d.ts

@@ -1,8 +1,12 @@
-import type { RawEvent, SpawnOptions } from '../claude/types';
+import type { DockerSpawnConfig, RawEvent, SpawnOptions } from '../claude/types';
 import type { CreateReadlineForEvents, SpawnForEvents } from '../process/spawn-contract';
 export interface EventSourceDependencies {
     spawn: SpawnForEvents;
     createInterface: CreateReadlineForEvents;
 }
 export declare const defaultDependencies: EventSourceDependencies;
+/**
+ * Build docker run arguments for spawning codex in a container.
+ */
+export declare function buildDockerRunArguments(docker: DockerSpawnConfig, codexArguments: string[], env: Record<string, string>): string[];
 export declare function spawnCodex(prompt: string, options?: SpawnOptions, dependencies?: EventSourceDependencies): AsyncGenerator<RawEvent>;

package/dist/command-events.d.ts

@@ -53,10 +53,11 @@ export type CommandEvent = {
 export interface CommandEventMessage {
     sequence: number;
     timestamp: string;
+    traceId?: string;
     event: CommandEvent;
 }
 /**
  * Creates an event emitter function that writes command events to a callback.
  * Each event is wrapped in a CommandEventMessage envelope with sequence and timestamp.
  */
-export declare function createEventEmitter(writeEvent: (message: CommandEventMessage) => void): (event: CommandEvent) => void;
+export declare function createEventEmitter(writeEvent: (message: CommandEventMessage) => void, traceId?: string): (event: CommandEvent) => void;

package/dist/container/apple-container-runtime.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Apple Container implementation of the ContainerRuntime interface.
+ *
+ * Apple's container project (https://github.com/apple/container) runs Linux
+ * containers as lightweight VMs on Apple Silicon (macOS 26+). It uses
+ * OCI-compatible images, so existing Dockerfiles work without modification.
+ */
+import type { ContainerRuntime } from './runtime';
+/**
+ * Apple Container runtime implementation.
+ */
+export declare const appleContainerRuntime: ContainerRuntime;

package/dist/container/docker-runtime.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Docker implementation of the ContainerRuntime interface.
+ */
+import type { ContainerDependencies, ContainerRuntime } from './runtime';
+/**
+ * Get the path to the bundled default Dockerfile.
+ */
+export declare function getDefaultDockerfilePath(): string;
+/**
+ * Generate a deterministic Docker image tag from the repository path.
+ * Uses the repository directory name, sanitized for Docker tag requirements.
+ */
+export declare function generateImageTag(repoPath: string): string;
+/**
+ * Check if a Dockerfile exists at .dust/config/container/Dockerfile.
+ */
+export declare function hasDockerfile(repoPath: string, dependencies: ContainerDependencies): boolean;
+/**
+ * Docker runtime implementation.
+ */
+export declare const dockerRuntime: ContainerRuntime;

package/dist/container/runtime.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Container runtime abstraction for dust agent execution.
+ *
+ * This module defines a provider-agnostic interface for container runtimes,
+ * allowing dust to support multiple container technologies (Docker, Apple
+ * Container, etc.) while keeping the agent orchestration logic decoupled.
+ */
+import type { spawn as nodeSpawn } from 'node:child_process';
+import type os from 'node:os';
+/**
+ * Dependencies injected into container runtime operations.
+ * Keeps the runtime implementations pure by externalizing I/O.
+ */
+export interface ContainerDependencies {
+    spawn: typeof nodeSpawn;
+    homedir: typeof os.homedir;
+    existsSync: (path: string) => boolean;
+}
+/**
+ * Configuration for building a container image.
+ */
+export interface BuildConfig {
+    /** Path to the repository root */
+    repoPath: string;
+    /** Tag to apply to the built image */
+    imageTag: string;
+    /** Optional path to a custom Dockerfile */
+    dockerfilePath?: string;
+}
+/**
+ * Result of a container image build operation.
+ */
+export type BuildResult = {
+    success: true;
+} | {
+    success: false;
+    error: string;
+};
+/**
+ * Configuration for running a container.
+ */
+export interface RunConfig {
+    imageTag: string;
+    repoPath: string;
+    homeDir: string;
+    gitProxyUrl?: string;
+    claudeApiProxyUrl?: string;
+    settingsFilePath?: string;
+}
+/**
+ * Abstract interface for container runtimes.
+ *
+ * Each runtime implementation provides the same capabilities through
+ * its native CLI tools. The interface is designed for:
+ * - Pure functions where possible (buildRunArgs)
+ * - Dependency injection for I/O operations (isAvailable, buildImage)
+ */
+export interface ContainerRuntime {
+    /** Unique identifier for this runtime */
+    name: 'docker' | 'apple-container';
+    /** Check if the runtime CLI is available on the system */
+    isAvailable: (dependencies: ContainerDependencies) => Promise<boolean>;
+    /** Build an image from a Dockerfile */
+    buildImage: (config: BuildConfig, dependencies: ContainerDependencies) => Promise<BuildResult>;
+    /** The CLI command for running containers (e.g., 'docker', 'container') */
+    runCommand: string;
+    /** Hostname or IP the container uses to reach the host (e.g., 'host.docker.internal', '192.168.64.1') */
+    hostAddress: string;
+    /** Map dust's run options to CLI arguments */
+    buildRunArgs: (config: RunConfig) => string[];
+}

package/dist/container/select-runtime.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Runtime selection logic for container execution.
+ *
+ * Selects the appropriate container runtime based on CLI flags.
+ */
+import type { ContainerRuntime } from './runtime';
+interface RuntimeFlags {
+    docker: boolean;
+    appleContainer: boolean;
+}
+type RuntimeSelectionResult = {
+    success: true;
+    runtime: ContainerRuntime | null;
+    forceContainer: boolean;
+} | {
+    success: false;
+    error: string;
+};
+/**
+ * Select container runtime based on CLI flags.
+ *
+ * Returns:
+ * - `{ success: true, runtime: ContainerRuntime, forceContainer: true }` when a runtime flag is set
+ * - `{ success: true, runtime: null, forceContainer: false }` when no flags are set (use Dockerfile detection)
+ * - `{ success: false, error: string }` when both flags are set (mutually exclusive)
+ */
+export declare function selectContainerRuntime(flags: RuntimeFlags): RuntimeSelectionResult;
+export {};

package/dist/docker/docker-agent.d.ts

@@ -1,47 +1,33 @@
 /**
  * Docker-based agent execution for dust loop.
  *
- * When a repository contains a .dust/Dockerfile, the agent runs inside
- * a Docker container instead of directly on the host. This provides
- * isolation and lets each project define its ideal agent environment.
+ * When a repository contains a .dust/config/container/Dockerfile, the agent
+ * runs inside a Docker container instead of directly on the host. This
+ * provides isolation and lets each project define its ideal agent environment.
+ *
+ * This module re-exports utilities from the container abstraction layer
+ * and provides the high-level prepareDockerConfig orchestration function.
  */
-import type { spawn as nodeSpawn } from 'node:child_process';
-import type os from 'node:os';
-interface DockerConfig {
-    /** Path to the repository */
+import type { ContainerDependencies, ContainerRuntime } from '../container/runtime';
+import { generateImageTag, getDefaultDockerfilePath, hasDockerfile } from '../container/docker-runtime';
+export type { ContainerDependencies as DockerDependencies } from '../container/runtime';
+export { generateImageTag, getDefaultDockerfilePath, hasDockerfile };
+export declare function isDockerAvailable(dependencies: ContainerDependencies): Promise<boolean>;
+export declare function buildDockerImage(config: {
     repoPath: string;
-    /** Docker image tag to use (e.g., 'dust-agent-myrepo') */
     imageTag: string;
-}
-export interface DockerDependencies {
-    spawn: typeof nodeSpawn;
-    homedir: typeof os.homedir;
-    existsSync: (path: string) => boolean;
-}
-/**
- * Check if Docker is available on the system.
- */
-export declare function isDockerAvailable(dependencies: DockerDependencies): Promise<boolean>;
-/**
- * Generate a deterministic Docker image tag from the repository path.
- * Uses the repository directory name, sanitized for Docker tag requirements.
- */
-export declare function generateImageTag(repoPath: string): string;
-type BuildResult = {
+    dockerfilePath?: string;
+}, dependencies: ContainerDependencies): Promise<{
     success: true;
 } | {
     success: false;
     error: string;
-};
+}>;
 /**
- * Build a Docker image from the repository's .dust/Dockerfile.
+ * Check if a Dockerfile exists at the legacy .dust/Dockerfile location.
  */
-export declare function buildDockerImage(config: DockerConfig, dependencies: DockerDependencies): Promise<BuildResult>;
-/**
- * Check if a Dockerfile exists at .dust/Dockerfile in the repository.
- */
-export declare function hasDockerfile(repoPath: string, dependencies: DockerDependencies): boolean;
-type DockerPrepareEvent = {
+export declare function hasLegacyDockerfile(repoPath: string, dependencies: ContainerDependencies): boolean;
+type ContainerPrepareEvent = {
     type: 'loop.docker_detected';
     imageTag: string;
 } | {
@@ -54,26 +40,31 @@ type DockerPrepareEvent = {
     type: 'loop.docker_error';
     error: string;
 };
-interface DockerSpawnConfig {
+interface ContainerSpawnConfig {
     imageTag: string;
     repoPath: string;
     homeDir: string;
 }
-type PrepareDockerConfigResult = {
-    config: DockerSpawnConfig;
+type PrepareContainerConfigResult = {
+    config: ContainerSpawnConfig;
 } | {
     error: string;
 } | Record<string, never>;
+interface PrepareContainerOptions {
+    forceContainer?: boolean;
+}
 /**
- * Prepare Docker configuration for agent execution.
+ * Prepare container configuration with a specific runtime.
  *
- * Checks for a .dust/Dockerfile, verifies Docker availability, builds the image,
- * and returns the spawn configuration. Emits events throughout the process.
+ * When runtime is null, defaults to Docker runtime (for Dockerfile detection mode).
+ */
+export declare function prepareContainerConfigWithRuntime(repoPath: string, dependencies: ContainerDependencies, onEvent: (event: ContainerPrepareEvent) => void, runtime: ContainerRuntime | null, options?: PrepareContainerOptions): Promise<PrepareContainerConfigResult>;
+/**
+ * Prepare Docker configuration for agent execution.
  *
- * Returns:
- * - `{ config: DockerSpawnConfig }` on success
- * - `{ error: string }` on failure (Docker not available or build failed)
- * - `{}` if no Dockerfile exists
+ * This is a thin wrapper around prepareContainerConfig that uses the Docker
+ * runtime. Kept for backward compatibility with existing callers.
  */
-export declare function prepareDockerConfig(repoPath: string, dependencies: DockerDependencies, onEvent: (event: DockerPrepareEvent) => void): Promise<PrepareDockerConfigResult>;
-export {};
+export declare function prepareDockerConfig(repoPath: string, dependencies: ContainerDependencies, onEvent: (event: ContainerPrepareEvent) => void, options?: {
+    forceDocker?: boolean;
+}): Promise<PrepareContainerConfigResult>;