@joshski/dust 0.1.109 → 0.1.111

package/README.md

@@ -47,3 +47,7 @@ Details live in the [.dust/facts](./.dust/facts) directory:
 - [Directory Structure](./.dust/facts/dust-directory-structure.md) — how `.dust/` is organized
 - [Configuration](./.dust/facts/configuration-system.md) — settings and quality checks
 - [CLI Commands](./.dust/facts/unified-cli.md) — full command reference
+
+## Dust Bucket Worker
+
+The `dust bucket worker` command runs a background worker that syncs agent sessions to [dustbucket.com](https://dustbucket.com). This requires a dustbucket.com account (currently in private alpha, invite only).

package/dist/artifacts/facts.d.ts

@@ -1,9 +1,6 @@
 import type { FileReader } from '../filesystem/types';
-export interface Fact {
-    slug: string;
-    title: string;
-    content: string;
-}
+import type { Fact } from './types';
+export type { Fact };
 /**
  * Parses a fact markdown file into a structured Fact object.
  */

package/dist/artifacts/ideas.d.ts

@@ -1,19 +1,6 @@
 import type { FileReader } from '../filesystem/types';
-export interface IdeaOption {
-    name: string;
-    description: string;
-}
-export interface IdeaOpenQuestion {
-    question: string;
-    options: IdeaOption[];
-}
-export interface Idea {
-    slug: string;
-    title: string;
-    openingSentence: string | null;
-    content: string;
-    openQuestions: IdeaOpenQuestion[];
-}
+import type { Idea, IdeaOpenQuestion, IdeaOption } from './types';
+export type { Idea, IdeaOpenQuestion, IdeaOption };
 export interface ParsedIdeaContent {
     title: string | null;
     body: string;

package/dist/artifacts/index.d.ts

@@ -6,21 +6,11 @@ import { type Principle } from './principles';
 import { type Task } from './tasks';
 import { type ParsedArtifact, type ParsedMarkdownLink, type ParsedSection, parseArtifact } from './parsed-artifact';
 import { type AllWorkflowTasks, CAPTURE_IDEA_PREFIX, type CreateIdeaTransitionTaskResult, type DecomposeIdeaOptions, findAllWorkflowTasks, type IdeaInProgress, type OpenQuestionResponse, type ParsedCaptureIdeaTask, parseResolvedQuestions, type TaskType, type WorkflowTaskMatch } from './workflow-tasks';
+import type { ArtifactType, ReadOnlyArtifactsRepository } from './types';
+export type { ArtifactType, ReadOnlyArtifactsRepository, RepositoryPrincipleNode, TaskGraph, TaskGraphNode, } from './types';
 export type { AllWorkflowTasks, CreateIdeaTransitionTaskResult, DecomposeIdeaOptions, Fact, Idea, IdeaOpenQuestion, IdeaOption, OpenQuestionResponse, ParsedArtifact, ParsedCaptureIdeaTask, ParsedIdeaContent, ParsedMarkdownLink, ParsedSection, Principle, Task, TaskType, WorkflowTaskMatch, };
-export interface TaskGraphNode {
-    task: Task;
-    workflowType: TaskType | null;
-}
-export interface TaskGraph {
-    nodes: TaskGraphNode[];
-    edges: Array<{
-        from: string;
-        to: string;
-    }>;
-}
 export { CAPTURE_IDEA_PREFIX, extractTitle, findAllWorkflowTasks, ideaContentToMarkdown, parseArtifact, parseIdeaContent, parseOpenQuestions, parseResolvedQuestions, };
 export type { IdeaInProgress };
-export type ArtifactType = 'ideas' | 'tasks' | 'principles' | 'facts';
 export declare const ARTIFACT_TYPES: ArtifactType[];
 export declare const DUST_PATH_PREFIX = ".dust/";
 /**
@@ -32,32 +22,6 @@ export declare function parseArtifactPath(path: string): {
     type: ArtifactType;
     slug: string;
 } | null;
-export interface ReadOnlyArtifactsRepository {
-    artifactPath(type: ArtifactType, slug: string): string;
-    parseIdea(options: {
-        slug: string;
-    }): Promise<Idea>;
-    listIdeas(): Promise<string[]>;
-    parsePrinciple(options: {
-        slug: string;
-    }): Promise<Principle>;
-    listPrinciples(): Promise<string[]>;
-    parseFact(options: {
-        slug: string;
-    }): Promise<Fact>;
-    listFacts(): Promise<string[]>;
-    parseTask(options: {
-        slug: string;
-    }): Promise<Task>;
-    listTasks(): Promise<string[]>;
-    findWorkflowTaskForIdea(options: {
-        ideaSlug: string;
-    }): Promise<WorkflowTaskMatch | null>;
-    parseCaptureIdeaTask(options: {
-        taskSlug: string;
-    }): Promise<ParsedCaptureIdeaTask | null>;
-    buildTaskGraph(): Promise<TaskGraph>;
-}
 export interface ArtifactsRepository extends ReadOnlyArtifactsRepository {
     createRefineIdeaTask(options: {
         ideaSlug: string;

package/dist/artifacts/principles.d.ts

@@ -1,11 +1,6 @@
 import type { FileReader } from '../filesystem/types';
-export interface Principle {
-    slug: string;
-    title: string;
-    content: string;
-    parentPrinciple: string | null;
-    subPrinciples: string[];
-}
+import type { Principle } from './types';
+export type { Principle };
 /**
  * Parses a principle markdown file into a structured Principle object.
  */

package/dist/artifacts/repository-principle-hierarchy.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Repository Principle Hierarchy API
+ *
+ * Provides pure functional access to build hierarchical trees of principles
+ * from a repository's .dust/principles/ directory.
+ */
+import type { ReadOnlyArtifactsRepository, RepositoryPrincipleNode } from './types';
+/**
+ * Builds a hierarchy tree of repository principles from .dust/principles/.
+ * Returns root nodes (principles with no parent or filtered parent).
+ * Children are sorted alphabetically by title (recursive).
+ *
+ * @param repository - The repository to read principles from
+ * @returns Array of root principle nodes, empty array if no principles exist
+ */
+export declare function getRepositoryPrincipleHierarchy(repository: ReadOnlyArtifactsRepository): Promise<RepositoryPrincipleNode[]>;

package/dist/artifacts/tasks.d.ts

@@ -1,12 +1,6 @@
 import type { FileReader } from '../filesystem/types';
-export interface Task {
-    slug: string;
-    title: string;
-    content: string;
-    principles: string[];
-    blockedBy: string[];
-    definitionOfDone: string[];
-}
+import type { Task } from './types';
+export type { Task };
 /**
  * Parses a task markdown file into a structured Task object.
  */

package/dist/artifacts/types.d.ts

@@ -0,0 +1,98 @@
+export type TaskType = 'implement' | 'capture' | 'refine' | 'decompose' | 'shelve';
+export interface Fact {
+    slug: string;
+    title: string;
+    content: string;
+}
+export interface IdeaOption {
+    name: string;
+    description: string;
+}
+export interface IdeaOpenQuestion {
+    question: string;
+    options: IdeaOption[];
+}
+export interface Idea {
+    slug: string;
+    title: string;
+    openingSentence: string | null;
+    content: string;
+    openQuestions: IdeaOpenQuestion[];
+}
+export interface Principle {
+    slug: string;
+    title: string;
+    content: string;
+    parentPrinciple: string | null;
+    subPrinciples: string[];
+}
+export interface Task {
+    slug: string;
+    title: string;
+    content: string;
+    principles: string[];
+    blockedBy: string[];
+    definitionOfDone: string[];
+}
+export interface OpenQuestionResponse {
+    question: string;
+    chosenOption: string;
+}
+export interface WorkflowTaskMatch {
+    type: TaskType;
+    ideaSlug: string;
+    taskSlug: string;
+    resolvedQuestions: OpenQuestionResponse[];
+}
+export interface ParsedCaptureIdeaTask {
+    ideaTitle: string;
+    ideaDescription: string;
+    expedite: boolean;
+}
+export type ArtifactType = 'ideas' | 'tasks' | 'principles' | 'facts';
+export interface TaskGraphNode {
+    task: Task;
+    workflowType: TaskType | null;
+}
+export interface TaskGraph {
+    nodes: TaskGraphNode[];
+    edges: Array<{
+        from: string;
+        to: string;
+    }>;
+}
+/**
+ * Node in the principle hierarchy tree
+ */
+export interface RepositoryPrincipleNode {
+    slug: string;
+    title: string;
+    children: RepositoryPrincipleNode[];
+}
+export interface ReadOnlyArtifactsRepository {
+    artifactPath(type: ArtifactType, slug: string): string;
+    parseIdea(options: {
+        slug: string;
+    }): Promise<Idea>;
+    listIdeas(): Promise<string[]>;
+    parsePrinciple(options: {
+        slug: string;
+    }): Promise<Principle>;
+    listPrinciples(): Promise<string[]>;
+    parseFact(options: {
+        slug: string;
+    }): Promise<Fact>;
+    listFacts(): Promise<string[]>;
+    parseTask(options: {
+        slug: string;
+    }): Promise<Task>;
+    listTasks(): Promise<string[]>;
+    findWorkflowTaskForIdea(options: {
+        ideaSlug: string;
+    }): Promise<WorkflowTaskMatch | null>;
+    parseCaptureIdeaTask(options: {
+        taskSlug: string;
+    }): Promise<ParsedCaptureIdeaTask | null>;
+    buildTaskGraph(): Promise<TaskGraph>;
+    getRepositoryPrincipleHierarchy(): Promise<RepositoryPrincipleNode[]>;
+}

package/dist/artifacts/workflow-tasks.d.ts

@@ -1,4 +1,6 @@
 import type { FileSystem, ReadableFileSystem } from '../filesystem/types';
+import type { OpenQuestionResponse, ParsedCaptureIdeaTask, TaskType, WorkflowTaskMatch } from './types';
+export type { OpenQuestionResponse, ParsedCaptureIdeaTask, TaskType, WorkflowTaskMatch, };
 export declare const IDEA_TRANSITION_PREFIXES: string[];
 export declare const CAPTURE_IDEA_PREFIX = "Add Idea: ";
 export declare const EXPEDITE_IDEA_PREFIX = "Expedite Idea: ";
@@ -6,11 +8,6 @@ export interface IdeaInProgress {
     taskSlug: string;
     ideaTitle: string;
 }
-export interface ParsedCaptureIdeaTask {
-    ideaTitle: string;
-    ideaDescription: string;
-    expedite: boolean;
-}
 /**
  * Converts a markdown title to the expected filename using deterministic rules:
  * 1. Convert to lowercase
@@ -22,18 +19,11 @@ export interface ParsedCaptureIdeaTask {
  */
 export declare function titleToFilename(title: string): string;
 export declare const VALID_TASK_TYPES: readonly ["implement", "capture", "refine", "decompose", "shelve"];
-export type TaskType = (typeof VALID_TASK_TYPES)[number];
 /**
  * Extracts and validates the task type from the ## Task Type section.
  * Returns the task type if found and valid, null otherwise.
  */
 export declare function parseTaskType(content: string): TaskType | null;
-export interface WorkflowTaskMatch {
-    type: TaskType;
-    ideaSlug: string;
-    taskSlug: string;
-    resolvedQuestions: OpenQuestionResponse[];
-}
 export interface AllWorkflowTasks {
     captureIdeaTasks: IdeaInProgress[];
     workflowTasksByIdeaSlug: Map<string, WorkflowTaskMatch>;
@@ -43,10 +33,6 @@ export declare function findWorkflowTaskForIdea(fileSystem: ReadableFileSystem,
 export interface CreateIdeaTransitionTaskResult {
     filePath: string;
 }
-export interface OpenQuestionResponse {
-    question: string;
-    chosenOption: string;
-}
 export interface DecomposeIdeaOptions {
     ideaSlug: string;
     description?: string;

package/dist/artifacts.js

@@ -294,10 +294,7 @@ async function parsePrinciple(fileSystem, dustPath, slug) {
     throw new Error(`Principle not found: "${slug}" (expected file at ${principlePath})`);
   }
   const content = await fileSystem.readFile(principlePath);
-  const title = extractTitle(content);
-  if (!title) {
-    throw new Error(`Principle file has no title: ${principlePath}`);
-  }
+  const title = extractTitle(content) || slug;
   const parentPrinciple = extractSingleLinkFromSection(content, "Parent Principle");
   const subPrinciples = extractLinksFromSection(content, "Sub-Principles");
   return {
@@ -999,6 +996,42 @@ async function parseCaptureIdeaTask(fileSystem, dustPath, taskSlug) {
   return { ideaTitle, ideaDescription, expedite };
 }
 
+// lib/artifacts/repository-principle-hierarchy.ts
+function sortNodes(nodes) {
+  nodes.sort((a, b) => a.title.localeCompare(b.title));
+  for (const node of nodes) {
+    sortNodes(node.children);
+  }
+}
+async function getRepositoryPrincipleHierarchy(repository) {
+  const slugs = await repository.listPrinciples();
+  if (slugs.length === 0) {
+    return [];
+  }
+  const principles = await Promise.all(slugs.map((slug) => repository.parsePrinciple({ slug })));
+  const principleSet = new Set(slugs);
+  const nodeBySlug = new Map;
+  for (const p of principles) {
+    nodeBySlug.set(p.slug, {
+      slug: p.slug,
+      title: p.title,
+      children: []
+    });
+  }
+  const roots = [];
+  for (const p of principles) {
+    const node = nodeBySlug.get(p.slug);
+    const parentSlug = p.parentPrinciple;
+    if (!parentSlug || !principleSet.has(parentSlug)) {
+      roots.push(node);
+    } else {
+      nodeBySlug.get(parentSlug).children.push(node);
+    }
+  }
+  sortNodes(roots);
+  return roots;
+}
+
 // lib/artifacts/index.ts
 var ARTIFACT_TYPES = [
   "facts",
@@ -1099,6 +1132,9 @@ function buildReadOperations(fileSystem, dustPath) {
         }
       }
       return { nodes, edges };
+    },
+    async getRepositoryPrincipleHierarchy() {
+      return getRepositoryPrincipleHierarchy(this);
     }
   };
 }

package/dist/audits.js

@@ -1865,6 +1865,168 @@ function slowTests() {
     - No changes to files outside \`.dust/\`
   `;
 }
+function overAbstraction() {
+  return dedent`
+    # Over-Abstraction
+
+    Identify violations of the "reasonably-dry" principle where code has been over-engineered with excessive abstraction.
+
+    ${ideasHint}
+
+    ## Scope
+
+    Detect these over-abstraction patterns:
+
+    1. **Single-use abstractions** - Interfaces, base classes, or utility functions used in only one place
+    2. **Deep inheritance hierarchies** - Classes extending more than 2 levels deep
+    3. **Premature generalization** - Parameters always used with the same value, unused options/flags
+    4. **Excessive indirection** - Multiple layers of wrappers adding no value
+
+    ## Analysis Steps
+
+    ### 1. Find Single-Use Abstractions
+
+    Search for abstractions that are only used once:
+
+    1. **Interfaces with one implementation**
+       - Search for \`interface\` declarations
+       - Check if each interface has only one implementing class
+       - Flag interfaces that exist solely for testing (can be replaced with the concrete type)
+
+    2. **Base classes with one subclass**
+       - Search for \`abstract class\` or classes used as base classes
+       - Count implementations extending each base class
+       - Flag base classes with only one subclass
+
+    3. **Utility functions called once**
+       - Search for exported utility functions
+       - Check call sites - if only called from one location, it's over-abstraction
+       - Consider inlining single-use utilities
+
+    4. **Generic types with one concrete usage**
+       - Find generic type parameters: \`<T>\`, \`<TData>\`, etc.
+       - Check if T is always the same type at all call sites
+       - Flag generics that could be concrete types
+
+    ### 2. Detect Deep Inheritance Hierarchies
+
+    Find inheritance chains longer than 2 levels:
+
+    1. Search for \`extends\` keywords in class declarations
+    2. Build inheritance tree for each class
+    3. Flag chains deeper than 2 (A extends B extends C extends D...)
+    4. Respect framework conventions (don't flag React.Component, etc.)
+
+    ### 3. Identify Premature Generalization
+
+    Look for flexibility that's never used:
+
+    1. **Always-same parameter values**
+       - Find function parameters
+       - Check all call sites - if always the same value, it's not needed
+       - Flag parameters that could be constants or removed
+
+    2. **Unused configuration options**
+       - Search for configuration objects/interfaces
+       - Check which options are actually used
+       - Flag options that are never set or always default
+
+    3. **Unused function parameters**
+       - Find parameters that aren't referenced in function bodies
+       - Flag as candidates for removal
+
+    ### 4. Find Excessive Indirection
+
+    Detect wrapper chains that add no value:
+
+    1. **Delegation chains**
+       - Search for functions that only call another function
+       - Flag wrappers that don't add logic, just forward calls
+       - Example: \`function foo(x) { return bar(x) }\`
+
+    2. **Proxy patterns without behavior**
+       - Find classes that wrap another class
+       - Check if wrapper adds any logic beyond forwarding
+       - Flag pure proxies
+
+    3. **Middleware without transformation**
+       - Look for middleware/interceptor patterns
+       - Check if they modify data or just pass through
+       - Flag pass-through middleware
+
+    ## Output Format
+
+    For each over-abstraction found, create an idea file in \`.dust/ideas/\` with:
+
+    \`\`\`markdown
+    # Over-Abstraction: [Type] in [Location]
+
+    ## Type
+
+    [Single-use | Deep hierarchy | Premature generalization | Excessive indirection]
+
+    ## Location
+
+    \`\`\`
+    [file path]:[line number]
+    \`\`\`
+
+    ## Description
+
+    [What the abstraction is]
+
+    ## Problem
+
+    [Why this is over-abstraction - complexity without benefit]
+
+    ## Usage Analysis
+
+    - **Times used**: [count]
+    - **Variation in usage**: [how different are the use cases]
+    - **Complexity cost**: [lines of code, indirection levels, etc.]
+
+    ## Suggested Simplification
+
+    [How to remove or reduce this abstraction]
+
+    ## Impact
+
+    [Lines of code saved, reduced complexity, improved clarity]
+    \`\`\`
+
+    ## Special Considerations
+
+    1. **Framework conventions** - Don't flag patterns mandated by frameworks:
+       - React: Component base classes, hooks patterns
+       - Express: Middleware signatures
+       - Testing: Test base classes, fixture patterns
+
+    2. **Library boundaries** - Public API abstractions may be justified even if internal usage is simple
+
+    3. **Test code** - Apply the same standards to test code as production code
+
+    4. **Context depth thresholds**:
+       - Deep hierarchies (>2 levels) make understanding difficult
+       - Wrapper chains (>2 levels) obscure actual behavior
+       - Generic parameters should have multiple concrete usages
+
+    ## Blocked By
+
+    (none)
+
+    ## Definition of Done
+
+    - Searched for single-use interfaces, base classes, and utility functions
+    - Identified deep inheritance hierarchies (>2 levels)
+    - Found parameters always used with the same value
+    - Detected unused configuration options
+    - Located excessive wrapper chains and delegation
+    - Respected framework conventions (didn't flag framework-mandated patterns)
+    - Created idea files for each over-abstraction found
+    - Each idea includes usage analysis and simplification suggestions
+    - No changes to files outside \`.dust/\`
+  `;
+}
 function primitiveObsession() {
   return dedent`
     # Primitive Obsession
@@ -3240,6 +3402,7 @@ var stockAuditFunctions = {
   "idiomatic-style": idiomaticStyle,
   "incidental-test-details": incidentalTestDetails,
   "logging-and-traceability": loggingAndTraceability,
+  "over-abstraction": overAbstraction,
   "primitive-obsession": primitiveObsession,
   "repository-context": repositoryContext,
   "security-review": securityReview,

package/dist/bucket/repository-loop.d.ts

@@ -12,7 +12,7 @@ import type { SendAgentEventFn } from '../loop/wire-events';
 import { type RunnerDependencies as CodexRunnerDependencies, run as codexRun } from '../codex/run';
 import type { SendEventFn } from './events';
 import { type LogBuffer } from './log-buffer';
-import type { RepositoryDependencies, RepositoryState } from './repository';
+import type { RepositoryDependencies, RepositoryState } from './repository-types';
 /**
  * Create stdout/stderr callbacks that append to a log buffer.
  * Extracted for testability (v8 coverage limitation on inline callbacks).

package/dist/bucket/repository-types.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Shared types for repository management.
+ *
+ * Extracted to break the cyclic dependency between repository.ts and repository-loop.ts.
+ */
+import { spawn as nodeSpawn } from 'node:child_process';
+import type { run as claudeRun } from '../claude/run';
+import type { FileSystem } from '../cli/types';
+import type { DockerDependencies } from '../docker/docker-agent';
+import type { AuthConfig, RuntimeConfig, SessionConfig } from '../env-config';
+import type { ToolExecutionRequest, ToolExecutionResult } from './command-events-proxy';
+import type { LogBuffer } from './log-buffer';
+import type { RepositoryLifecycleState } from './repository-lifecycle';
+import type { ToolDefinition } from './server-messages';
+export interface Repository {
+    name: string;
+    gitUrl: string;
+    gitSshUrl: string;
+    url: string;
+    id: number;
+    agentProvider?: string;
+    branch?: string;
+}
+export interface RepositoryState {
+    repository: Repository;
+    path: string;
+    logBuffer: LogBuffer;
+    lifecycle: RepositoryLifecycleState;
+    agentStatus: 'idle' | 'busy';
+    wakeUp?: () => void;
+    taskAvailablePending?: boolean;
+}
+export interface RepositoryDependencies {
+    spawn: typeof nodeSpawn;
+    run: typeof claudeRun;
+    fileSystem: FileSystem;
+    sleep: (ms: number) => Promise<void>;
+    getReposDir: () => string;
+    session: SessionConfig;
+    runtime: RuntimeConfig;
+    auth: AuthConfig;
+    /** Optional overrides for Docker dependency functions (for testing) */
+    dockerDeps?: Partial<DockerDependencies>;
+    /** Function to get current tool definitions */
+    getTools?: () => ToolDefinition[];
+    /** Function to get revealed tool families (for progressive disclosure) */
+    getRevealedFamilies?: () => Set<string>;
+    /** Forward tool execution requests to the bucket server */
+    forwardToolExecution?: (request: ToolExecutionRequest) => Promise<ToolExecutionResult>;
+    /** Mark a tool family as revealed (for progressive disclosure) */
+    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;
+}

package/dist/bucket/repository.d.ts

@@ -4,37 +4,13 @@
  * Git operations live in repository-git.ts.
  * Loop orchestration lives in repository-loop.ts.
  */
-import { spawn as nodeSpawn } from 'node:child_process';
-import { run as claudeRun } from '../claude/run';
 import type { CommandDependencies, FileSystem } from '../cli/types';
-import type { DockerDependencies } from '../docker/docker-agent';
-import { type AuthConfig, type RuntimeConfig, type SessionConfig } from '../env-config';
-import type { ToolExecutionRequest, ToolExecutionResult } from './command-events-proxy';
 import { type BucketEmitFn, type SendEventFn } from './events';
 import { type LogBuffer } from './log-buffer';
-import { type RepositoryLifecycleState } from './repository-lifecycle';
-import type { ToolDefinition } from './server-messages';
+import type { Repository, RepositoryDependencies, RepositoryState } from './repository-types';
 export { cloneRepository, getRepoPath, removeRepository, } from './repository-git';
 export { runRepositoryLoop } from './repository-loop';
-export type { RepositoryLifecycleState } from './repository-lifecycle';
-export interface Repository {
-    name: string;
-    gitUrl: string;
-    gitSshUrl: string;
-    url: string;
-    id: number;
-    agentProvider?: string;
-    branch?: string;
-}
-export interface RepositoryState {
-    repository: Repository;
-    path: string;
-    logBuffer: LogBuffer;
-    lifecycle: RepositoryLifecycleState;
-    agentStatus: 'idle' | 'busy';
-    wakeUp?: () => void;
-    taskAvailablePending?: boolean;
-}
+export type { Repository, RepositoryDependencies, RepositoryState, } from './repository-types';
 /**
  * Interface for the subset of bucket state needed by repository management.
  * Avoids circular dependency between repository.ts and bucket.ts.
@@ -46,32 +22,6 @@ export interface RepositoryManager {
     sendEvent: SendEventFn;
     sessionId: string;
 }
-export interface RepositoryDependencies {
-    spawn: typeof nodeSpawn;
-    run: typeof claudeRun;
-    fileSystem: FileSystem;
-    sleep: (ms: number) => Promise<void>;
-    getReposDir: () => string;
-    session: SessionConfig;
-    runtime: RuntimeConfig;
-    auth: AuthConfig;
-    /** Optional overrides for Docker dependency functions (for testing) */
-    dockerDeps?: Partial<DockerDependencies>;
-    /** Function to get current tool definitions */
-    getTools?: () => ToolDefinition[];
-    /** Function to get revealed tool families (for progressive disclosure) */
-    getRevealedFamilies?: () => Set<string>;
-    /** Forward tool execution requests to the bucket server */
-    forwardToolExecution?: (request: ToolExecutionRequest) => Promise<ToolExecutionResult>;
-    /** Mark a tool family as revealed (for progressive disclosure) */
-    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;
-}
 /**
  * Handle loop completion: transition lifecycle and reset agent status.
  * Extracted as a named function for testability.