profclaw 2.3.0 → 2.4.0

package/dist/agents/verifier.js

@@ -0,0 +1,186 @@
+/**
+ * Verifier
+ *
+ * Runs a user-provided verification command (tests, typecheck, lint, build or
+ * anything custom) as an objective judge of "done". The command is the only
+ * shell input: goal text and model output are never interpolated into it.
+ *
+ * Safety conventions:
+ *  - runs with cwd pinned to the run's worktree
+ *  - hard timeout, process group is killed on expiry
+ *  - captured output is capped in memory and trimmed for feedback
+ *  - a small denylist rejects commands that publish or destroy (git push,
+ *    gh pr create, rm -rf /, curl | sh) because a verifier must only observe
+ */
+import { spawn } from 'node:child_process';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { planSandboxedCommand, resolveAllowNetwork, resolveExtraWritable } from './command-sandbox.js';
+// Command policy
+const FORBIDDEN_PATTERNS = [
+    { pattern: /\bgit\b[^;&|\n]*\bpush\b/, reason: 'git push is not allowed in a verifier' },
+    { pattern: /\bgh\s+pr\s+(?:create|merge)\b/, reason: 'opening or merging PRs is not allowed in a verifier' },
+    { pattern: /\brm\s+(?:-\S*\s+)*-\S*[rR]\S*\s+(?:-\S+\s+)*(?:\/|~|\$HOME)(?:\s|$)/, reason: 'destructive rm is not allowed in a verifier' },
+    { pattern: /\b(?:curl|wget)\b[^|;&]*\|\s*(?:sudo\s+)?(?:sh|bash|zsh)\b/, reason: 'piping downloads into a shell is not allowed' },
+    { pattern: /\bsudo\b/, reason: 'sudo is not allowed in a verifier' },
+];
+/** Returns a rejection reason, or null when the command is acceptable. */
+export function validateVerifyCommand(command) {
+    if (command.trim().length === 0)
+        return 'verify command is empty';
+    if (command.includes('\0'))
+        return 'verify command contains a NUL byte';
+    for (const { pattern, reason } of FORBIDDEN_PATTERNS) {
+        if (pattern.test(command))
+            return reason;
+    }
+    return null;
+}
+// Output trimming
+/**
+ * Keep the head and tail of long output (failures usually name the problem
+ * at the top and summarise at the bottom) and drop the middle.
+ */
+export function trimOutput(raw, maxChars) {
+    const cleaned = stripAnsi(raw).trim();
+    if (cleaned.length <= maxChars)
+        return { text: cleaned, truncated: false };
+    const marker = '\n... [output trimmed] ...\n';
+    const budget = Math.max(0, maxChars - marker.length);
+    const head = Math.ceil(budget * 0.4);
+    const tail = budget - head;
+    return {
+        text: cleaned.slice(0, head) + marker + (tail > 0 ? cleaned.slice(-tail) : ''),
+        truncated: true,
+    };
+}
+function stripAnsi(text) {
+    // eslint-disable-next-line no-control-regex
+    return text.replace(/\u001b\[[0-9;?]*[ -/]*[@-~]/g, '');
+}
+// Command verifier
+export class CommandVerifier {
+    command;
+    options;
+    constructor(command, options) {
+        this.command = command;
+        this.options = options;
+    }
+    async verify() {
+        const rejection = validateVerifyCommand(this.command);
+        if (rejection) {
+            return {
+                passed: false,
+                exitCode: null,
+                timedOut: false,
+                durationMs: 0,
+                output: `Verifier rejected: ${rejection}`,
+                truncated: false,
+            };
+        }
+        return runCommand(this.command, this.options);
+    }
+}
+// Cap on raw bytes retained in memory regardless of trim setting.
+const RAW_CAPTURE_LIMIT = 2_000_000;
+async function runCommand(command, options) {
+    if (!options.sandbox)
+        return spawnCommand({ file: '/bin/sh', args: ['-c', command], env: {}, backend: 'none' }, options);
+    const tempDir = await mkdtemp(join(tmpdir(), 'profclaw-verify-'));
+    try {
+        const plan = planSandboxedCommand(command, {
+            workdir: options.cwd,
+            tempDir,
+            allowNetwork: options.sandbox.allowNetwork ?? resolveAllowNetwork(),
+            extraWritable: resolveExtraWritable(),
+        }, options.sandbox);
+        return await spawnCommand(plan, options);
+    }
+    catch (error) {
+        return {
+            passed: false,
+            exitCode: null,
+            timedOut: false,
+            durationMs: 0,
+            output: `Verifier sandbox error: ${error instanceof Error ? error.message : String(error)}`,
+            truncated: false,
+        };
+    }
+    finally {
+        await rm(tempDir, { recursive: true, force: true });
+    }
+}
+function spawnCommand(plan, options) {
+    return new Promise((resolve) => {
+        const started = Date.now();
+        let buffer = '';
+        let rawTruncated = false;
+        let timedOut = false;
+        let settled = false;
+        const child = spawn(plan.file, plan.args, {
+            cwd: options.cwd,
+            env: { ...process.env, ...options.env, ...plan.env, CI: process.env.CI ?? '1' },
+            stdio: ['ignore', 'pipe', 'pipe'],
+            detached: true,
+        });
+        const append = (chunk) => {
+            if (buffer.length >= RAW_CAPTURE_LIMIT) {
+                rawTruncated = true;
+                return;
+            }
+            buffer += chunk.toString('utf-8');
+        };
+        child.stdout.on('data', append);
+        child.stderr.on('data', append);
+        const killGroup = () => {
+            if (child.pid === undefined)
+                return;
+            try {
+                process.kill(-child.pid, 'SIGKILL');
+            }
+            catch {
+                child.kill('SIGKILL');
+            }
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            killGroup();
+        }, options.timeoutMs);
+        const finish = (exitCode, extra) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            const trimmed = trimOutput(buffer + (extra ?? ''), options.maxOutputChars);
+            const output = timedOut
+                ? `${trimmed.text}\n[verifier timed out after ${options.timeoutMs}ms]`.trim()
+                : trimmed.text;
+            resolve({
+                passed: exitCode === 0 && !timedOut,
+                exitCode,
+                timedOut,
+                durationMs: Date.now() - started,
+                output,
+                truncated: trimmed.truncated || rawTruncated,
+            });
+        };
+        child.on('error', (err) => finish(null, `\n${err.message}`));
+        child.on('close', (code) => finish(code));
+    });
+}
+/** Format a result as feedback text for the next agent attempt. */
+export function formatFailureFeedback(result, command) {
+    const status = result.timedOut
+        ? 'timed out'
+        : `exited with code ${result.exitCode === null ? 'unknown' : result.exitCode}`;
+    return [
+        `The verification command \`${command}\` ${status}.`,
+        'Output (trimmed):',
+        '```',
+        result.output,
+        '```',
+        'Fix the underlying problem so the command passes. Do not edit the verification command or weaken tests to force a pass.',
+    ].join('\n');
+}
+//# sourceMappingURL=verifier.js.map

package/dist/agents/worktree-tools.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Worktree-confined tools for the verified-run agent.
+ *
+ * A small coding toolset (read, write, list, shell, complete) whose every file
+ * operation is resolved against a single root directory, the run's git
+ * worktree. Paths that escape the root (via `..`, absolute paths or symlinks)
+ * are rejected, writes into `.git` are refused, and shell commands that push
+ * or open pull requests are denied. Cautious and dangerous tools also go
+ * through the existing PermissionManager (src/agents/permissions.ts).
+ *
+ * The shell tool runs with the worktree as cwd and a scrubbed environment,
+ * confined by an OS sandbox when available (src/agents/command-sandbox.ts).
+ * Without one it falls back to pattern screening, a guard rail, not a jail.
+ */
+import type { ToolSet } from 'ai';
+import { PermissionManager } from './permissions.js';
+import type { ToolExecuteHandler } from './executor.js';
+import type { PlanOptions } from './command-sandbox.js';
+export interface WorktreeToolsOptions {
+    /** Root every file operation is confined to */
+    workdir: string;
+    permissions?: PermissionManager;
+    /** Kill shell commands after this long */
+    commandTimeoutMs: number;
+    /** Cap on text returned to the model per tool call */
+    maxOutputChars: number;
+    /** Sandbox overrides (mode, availability check); defaults come from PROFCLAW_RUN_SANDBOX */
+    sandbox?: PlanOptions;
+    /** Override PROFCLAW_RUN_ALLOW_NETWORK */
+    allowNetwork?: boolean;
+}
+export interface WorktreeToolset {
+    tools: ToolSet;
+    execute: ToolExecuteHandler;
+    /** Remove the per-run sandbox temp dir */
+    dispose: () => Promise<void>;
+}
+export declare function isBlockedCommand(command: string): boolean;
+/** Non-interactive policy: allow everything except publishing actions. */
+export declare function createRunPermissionManager(): PermissionManager;
+/**
+ * Resolve `requested` against `root` and guarantee the result stays inside it,
+ * including through symlinks (checked on the deepest existing ancestor).
+ */
+export declare function confinePath(root: string, requested: string): Promise<string>;
+export declare function createWorktreeToolset(options: WorktreeToolsOptions): WorktreeToolset;
+//# sourceMappingURL=worktree-tools.d.ts.map

package/dist/agents/worktree-tools.js

@@ -0,0 +1,246 @@
+/**
+ * Worktree-confined tools for the verified-run agent.
+ *
+ * A small coding toolset (read, write, list, shell, complete) whose every file
+ * operation is resolved against a single root directory, the run's git
+ * worktree. Paths that escape the root (via `..`, absolute paths or symlinks)
+ * are rejected, writes into `.git` are refused, and shell commands that push
+ * or open pull requests are denied. Cautious and dangerous tools also go
+ * through the existing PermissionManager (src/agents/permissions.ts).
+ *
+ * The shell tool runs with the worktree as cwd and a scrubbed environment,
+ * confined by an OS sandbox when available (src/agents/command-sandbox.ts).
+ * Without one it falls back to pattern screening, a guard rail, not a jail.
+ */
+import { execFile, spawn } from 'node:child_process';
+import { mkdir, mkdtemp, readdir, readFile, realpath, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { jsonSchema, tool } from 'ai';
+import { PermissionManager } from './permissions.js';
+import { planSandboxedCommand, resolveAllowNetwork, resolveExtraWritable } from './command-sandbox.js';
+/** Tools the agent must never be given, denied even if requested by name. */
+const DENIED_TOOLS = new Set(['git_push', 'git_force_push']);
+/** Shell commands that would publish work. Screened before execution. */
+const BLOCKED_COMMAND_PATTERNS = [
+    /\bgit\b[^;&|\n]*\bpush\b/,
+    /\bgh\s+(pr|repo|release|api|workflow)\b/,
+    /\bgit\b[^;&|\n]*\bremote\s+(add|set-url)\b/,
+    /\bgit\b[^;&|\n]*--receive-pack\b/,
+];
+/** Environment variables that carry credentials for remotes. */
+const SCRUBBED_ENV_KEYS = ['GITHUB_TOKEN', 'GH_TOKEN', 'GITLAB_TOKEN', 'GIT_ASKPASS', 'SSH_AUTH_SOCK'];
+export function isBlockedCommand(command) {
+    return BLOCKED_COMMAND_PATTERNS.some((p) => p.test(command));
+}
+/** Non-interactive policy: allow everything except publishing actions. */
+export function createRunPermissionManager() {
+    const manager = new PermissionManager();
+    manager.setPromptCallback(async (toolName, args) => {
+        if (DENIED_TOOLS.has(toolName))
+            return 'deny';
+        if (toolName === 'bash') {
+            const command = getString(args, 'command');
+            if (command !== undefined && isBlockedCommand(command))
+                return 'deny';
+        }
+        return 'allow';
+    });
+    return manager;
+}
+function getString(args, key) {
+    if (typeof args !== 'object' || args === null)
+        return undefined;
+    const value = args[key];
+    return typeof value === 'string' ? value : undefined;
+}
+function isInside(root, target) {
+    const rel = relative(root, target);
+    if (rel === '')
+        return true;
+    return rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+/**
+ * Resolve `requested` against `root` and guarantee the result stays inside it,
+ * including through symlinks (checked on the deepest existing ancestor).
+ */
+export async function confinePath(root, requested) {
+    const absolute = resolve(root, requested);
+    if (!isInside(root, absolute))
+        throw new Error(`Path escapes the worktree: ${requested}`);
+    const rootReal = await realpath(root);
+    let probe = absolute;
+    for (;;) {
+        try {
+            const real = await realpath(probe);
+            if (!isInside(rootReal, real))
+                throw new Error(`Path escapes the worktree via symlink: ${requested}`);
+            return absolute;
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.startsWith('Path escapes'))
+                throw error;
+            const parent = dirname(probe);
+            if (parent === probe)
+                throw new Error(`Cannot resolve path: ${requested}`);
+            probe = parent;
+        }
+    }
+}
+function truncateTail(text, max) {
+    return text.length <= max ? text : `...[truncated]\n${text.slice(-max)}`;
+}
+/** Git dirs a linked worktree must write to (index, refs, objects), minus hooks and config. */
+async function resolveGitSandboxPaths(workdir) {
+    const run = (arg) => new Promise((res) => {
+        execFile('git', ['-C', workdir, 'rev-parse', arg], (err, stdout) => res(err ? '' : stdout.trim()));
+    });
+    const writable = new Set();
+    const readOnly = [];
+    for (const dir of [await run('--git-dir'), await run('--git-common-dir')]) {
+        if (dir === '')
+            continue;
+        const abs = resolve(workdir, dir);
+        writable.add(abs);
+        readOnly.push(join(abs, 'hooks'), join(abs, 'config'));
+    }
+    return { writable: [...writable], readOnly };
+}
+function runShell(spec, cwd, timeoutMs, maxChars) {
+    return new Promise((resolvePromise) => {
+        const env = { ...process.env, GIT_TERMINAL_PROMPT: '0', ...spec.env };
+        for (const key of SCRUBBED_ENV_KEYS)
+            delete env[key];
+        const child = spawn(spec.file, spec.args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
+        let output = '';
+        let timedOut = false;
+        const append = (d) => {
+            output = (output + d.toString('utf-8')).slice(-maxChars * 2);
+        };
+        child.stdout.on('data', append);
+        child.stderr.on('data', append);
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGKILL');
+        }, timeoutMs);
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            resolvePromise({ exitCode: null, output: err.message, timedOut });
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            resolvePromise({ exitCode: code, output: truncateTail(output, maxChars), timedOut });
+        });
+    });
+}
+function schemaTool(description, properties, required) {
+    return tool({
+        description,
+        inputSchema: jsonSchema({
+            type: 'object',
+            properties,
+            required,
+            additionalProperties: false,
+        }),
+    });
+}
+export function createWorktreeToolset(options) {
+    const { workdir, commandTimeoutMs, maxOutputChars } = options;
+    const permissions = options.permissions ?? createRunPermissionManager();
+    let sandboxBase;
+    const getSandboxBase = () => {
+        sandboxBase ??= (async () => {
+            const tempDir = await mkdtemp(join(tmpdir(), 'profclaw-run-'));
+            const git = await resolveGitSandboxPaths(workdir);
+            return {
+                workdir,
+                tempDir,
+                allowNetwork: options.allowNetwork ?? resolveAllowNetwork(),
+                extraWritable: [...git.writable, ...resolveExtraWritable()],
+                extraReadOnly: git.readOnly,
+            };
+        })();
+        return sandboxBase;
+    };
+    const dispose = async () => {
+        if (!sandboxBase)
+            return;
+        const base = await sandboxBase;
+        sandboxBase = undefined;
+        await rm(base.tempDir, { recursive: true, force: true });
+    };
+    const tools = {
+        read_file: schemaTool('Read a UTF-8 text file inside the working directory.', { path: { type: 'string' } }, ['path']),
+        write_file: schemaTool('Create or overwrite a file inside the working directory. Parent directories are created.', { path: { type: 'string' }, content: { type: 'string' } }, ['path', 'content']),
+        list_files: schemaTool('List entries of a directory inside the working directory (default: the root).', { path: { type: 'string' } }, []),
+        bash: schemaTool('Run a shell command with the working directory as cwd. Use it to run tests and the verify command. Pushing and opening pull requests is forbidden.', { command: { type: 'string' } }, ['command']),
+        complete_task: schemaTool('Call when the goal is done. Provide a short summary of what changed.', { summary: { type: 'string' } }, ['summary']),
+    };
+    const execute = async (name, args) => {
+        if (DENIED_TOOLS.has(name))
+            return { success: false, error: `Tool "${name}" is not allowed in a verified run` };
+        if (!(name in tools))
+            return { success: false, error: `Unknown tool "${name}"` };
+        const verdict = await permissions.check(name, args);
+        if (!verdict.allowed)
+            return { success: false, error: verdict.reason ?? `Permission denied for "${name}"` };
+        try {
+            switch (name) {
+                case 'read_file': {
+                    const path = getString(args, 'path');
+                    if (path === undefined)
+                        return { success: false, error: 'path is required' };
+                    const target = await confinePath(workdir, path);
+                    const text = await readFile(target, 'utf-8');
+                    return { success: true, data: { content: truncateTail(text, maxOutputChars) } };
+                }
+                case 'write_file': {
+                    const path = getString(args, 'path');
+                    const content = getString(args, 'content');
+                    if (path === undefined || content === undefined)
+                        return { success: false, error: 'path and content are required' };
+                    const target = await confinePath(workdir, path);
+                    const rel = relative(workdir, target);
+                    if (rel === '.git' || rel.startsWith(`.git${sep}`))
+                        return { success: false, error: 'Writing into .git is not allowed' };
+                    await mkdir(dirname(target), { recursive: true });
+                    await writeFile(target, content, 'utf-8');
+                    return { success: true, data: { path: rel, bytes: Buffer.byteLength(content) } };
+                }
+                case 'list_files': {
+                    const target = await confinePath(workdir, getString(args, 'path') ?? '.');
+                    const entries = await readdir(target, { withFileTypes: true });
+                    const names = entries
+                        .filter((e) => e.name !== '.git')
+                        .map((e) => (e.isDirectory() ? `${e.name}/` : e.name))
+                        .sort();
+                    return { success: true, data: { entries: names } };
+                }
+                case 'bash': {
+                    const command = getString(args, 'command');
+                    if (command === undefined)
+                        return { success: false, error: 'command is required' };
+                    if (isBlockedCommand(command)) {
+                        return { success: false, error: 'Command denied: pushing and opening pull requests are not allowed' };
+                    }
+                    const spec = planSandboxedCommand(command, await getSandboxBase(), options.sandbox);
+                    const result = await runShell(spec, workdir, commandTimeoutMs, maxOutputChars);
+                    return {
+                        success: result.exitCode === 0,
+                        data: { exitCode: result.exitCode, timedOut: result.timedOut, output: result.output },
+                        ...(result.exitCode === 0 ? {} : { error: `exit ${result.exitCode ?? 'null'}${result.timedOut ? ' (timed out)' : ''}` }),
+                    };
+                }
+                case 'complete_task':
+                    return { success: true, data: { summary: getString(args, 'summary') ?? 'Done' } };
+                default:
+                    return { success: false, error: `Unknown tool "${name}"` };
+            }
+        }
+        catch (error) {
+            return { success: false, error: error instanceof Error ? error.message : 'Tool failed' };
+        }
+    };
+    return { tools, execute, dispose };
+}
+//# sourceMappingURL=worktree-tools.js.map

package/dist/chat/agentic-executor.js

@@ -33,6 +33,7 @@ function getExperienceStore() {
 }
 import { normalizeToolSchema } from '../providers/schema-utils.js';
 import { logger } from '../utils/logger.js';
+import { selectToolsForRequest } from '../agents/tool-selector.js';
 import { runWithModelFallback, getUserFriendlyErrorMessage, getProvidersInCooldown, describeFailoverError, } from './failover/index.js';
 const passthroughValidate = (value) => ({
     success: true,
@@ -244,7 +245,9 @@ export async function executeAgenticChat(request) {
     }
     // Clone the base system prompt to avoid mutating the request object on retry
     const baseSystemPrompt = request.systemPrompt ?? '';
-    let augmentedSystemPrompt = baseSystemPrompt;
+    // Volatile per-request context is kept out of the base prompt so the base stays byte-stable
+    // for prompt caching (a second system message follows the stable one)
+    let volatileContext = '';
     // Recall relevant past experiences to enhance system prompt
     try {
         const store = await getExperienceStore();
@@ -261,7 +264,7 @@ export async function executeAgenticChat(request) {
                 return `Past experience: ${exp.intent} (score: ${exp.successScore})`;
             });
             if (hints.length > 0) {
-                augmentedSystemPrompt += `\n\nRelevant past experiences:\n${hints.join('\n')}`;
+                volatileContext += `\n\nRelevant past experiences:\n${hints.join('\n')}`;
                 logger.debug('[AgenticChat] Injected experience context', { count: hints.length });
                 for (const exp of similar.slice(0, 2)) {
                     store.markUsed(exp.id).catch(() => { });
@@ -286,7 +289,7 @@ export async function executeAgenticChat(request) {
                 const contextBlock = context.sources
                     .map(s => `[${s.type}${s.path ? `: ${s.path}` : ''}]\n${s.content.slice(0, 500)}`)
                     .join('\n\n');
-                augmentedSystemPrompt += `\n\nProject context (auto-gathered):\n${contextBlock}`;
+                volatileContext += `\n\nProject context (auto-gathered):\n${contextBlock}`;
                 logger.debug('[AgenticChat] Injected project context', {
                     sources: context.sources.length,
                     tokens: context.tokens,
@@ -306,10 +309,13 @@ export async function executeAgenticChat(request) {
         effort: request.effort,
     };
     // Store raw tool definitions - we'll convert to AI SDK format per-provider
-    const toolDefinitions = request.tools;
+    // Per-turn tool selection (core set + relevant groups + load_tools meta-tool)
+    const turnUserMessage = [...request.messages].reverse().find((m) => m.role === 'user');
+    const toolDefinitions = selectToolsForRequest(request.tools, request.conversationId, typeof turnUserMessage?.content === 'string' ? turnUserMessage.content : '');
     // Build messages with system prompt
     const messages = [
-        { role: 'system', content: augmentedSystemPrompt },
+        { role: 'system', content: baseSystemPrompt },
+        ...(volatileContext ? [{ role: 'system', content: volatileContext.trim() }] : []),
         ...request.messages.map((m) => ({
             role: m.role,
             content: m.content,
@@ -641,7 +647,9 @@ export async function* streamAgenticChat(request) {
         effort: request.effort,
     };
     // Store raw tool definitions - we'll convert to AI SDK format per-provider
-    const toolDefinitions = request.tools;
+    // Per-turn tool selection, same as the non-streaming path
+    const turnUserMessage = [...request.messages].reverse().find((m) => m.role === 'user');
+    const toolDefinitions = selectToolsForRequest(request.tools, request.conversationId, typeof turnUserMessage?.content === 'string' ? turnUserMessage.content : '');
     // Build messages with system prompt
     const messages = [
         { role: 'system', content: request.systemPrompt },

package/dist/chat/execution/sandbox.d.ts

@@ -23,6 +23,14 @@ export interface SandboxExecuteResult {
     containerId?: string;
     error?: string;
 }
+/**
+ * Ping the Docker daemon, giving up after a timeout. A wedged daemon (for example a
+ * half-started Docker Desktop) accepts the connection but never answers, which would
+ * otherwise hang startup forever.
+ */
+export declare function pingDockerWithTimeout(docker: {
+    ping(): Promise<unknown>;
+}, timeoutMs?: number): Promise<void>;
 export declare class SandboxManager {
     private config;
     private securityConfig;

package/dist/chat/execution/sandbox.js

@@ -16,6 +16,30 @@ const DEFAULT_CPU_LIMIT = '1';
 const CONTAINER_POOL_SIZE = 3;
 const CONTAINER_MAX_AGE_MS = 3600_000; // 1 hour
 const CLEANUP_INTERVAL_MS = 60_000; // 1 minute
+const DEFAULT_DOCKER_PING_TIMEOUT_MS = 3_000;
+/** How long to wait for the Docker daemon to answer before treating it as unavailable. */
+function getDockerPingTimeoutMs(env = process.env) {
+    const parsed = Number(env['PROFCLAW_DOCKER_PING_TIMEOUT_MS']);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_DOCKER_PING_TIMEOUT_MS;
+}
+/**
+ * Ping the Docker daemon, giving up after a timeout. A wedged daemon (for example a
+ * half-started Docker Desktop) accepts the connection but never answers, which would
+ * otherwise hang startup forever.
+ */
+export async function pingDockerWithTimeout(docker, timeoutMs = getDockerPingTimeoutMs()) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`Docker daemon did not respond within ${timeoutMs}ms`)), timeoutMs);
+    });
+    try {
+        await Promise.race([docker.ping(), timeout]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
 const DEFAULT_SESSION_IDLE_MS = 600_000; // 10 minutes
 export class SandboxManager {
     config;
@@ -76,7 +100,7 @@ export class SandboxManager {
                     : new DockerModule.default();
             }
             // Check Docker connection
-            await this.docker.ping();
+            await pingDockerWithTimeout(this.docker);
             logger.info('[Sandbox] Docker connection established', { component: 'Sandbox' });
             // Log active security level so operators know what enforcement is in place
             logger.info(`[Sandbox] Security level: ${this.securityConfig.level} (mode override: ${process.env.PROFCLAW_SANDBOX_LEVEL ?? 'none'}, resolved: ${getSecurityLevel()})`, {

package/dist/chat/execution/tools/tts-speak.d.ts

@@ -16,13 +16,13 @@ declare const TtsSpeakParamsSchema: z.ZodObject<{
     text: string;
     speed: number;
     format: "opus" | "mp3" | "wav" | "aac" | "flac";
-    voice: "echo" | "alloy" | "fable" | "onyx" | "nova" | "shimmer";
+    voice: "fable" | "echo" | "alloy" | "onyx" | "nova" | "shimmer";
     outputPath?: string | undefined;
 }, {
     text: string;
     speed?: number | undefined;
     format?: "opus" | "mp3" | "wav" | "aac" | "flac" | undefined;
-    voice?: "echo" | "alloy" | "fable" | "onyx" | "nova" | "shimmer" | undefined;
+    voice?: "fable" | "echo" | "alloy" | "onyx" | "nova" | "shimmer" | undefined;
     outputPath?: string | undefined;
 }>;
 export type TtsSpeakParams = z.infer<typeof TtsSpeakParamsSchema>;

package/dist/chat/meta-tool-handlers.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Meta-tool handlers: load_tools and fetch_result.
+ *
+ * Kept separate from tool-handler.ts so the handler stays small. These are pure
+ * functions over injected dependencies, which also makes them easy to test.
+ */
+import type { ResultStore } from '../agents/result-store.js';
+import { type SelectableTool, type ToolSelectorSession } from '../agents/tool-selector.js';
+export interface LoadToolsDeps {
+    session: ToolSelectorSession;
+    /** Every available tool (not just the selected ones) */
+    allTools: readonly SelectableTool[];
+    /** Runs a tool through the normal security pipeline */
+    invoke: (tool: string, args: Record<string, unknown>) => Promise<unknown>;
+}
+export declare function runLoadTools(args: unknown, deps: LoadToolsDeps): Promise<unknown>;
+export declare function runFetchResult(args: unknown, store: ResultStore): Promise<unknown>;
+//# sourceMappingURL=meta-tool-handlers.d.ts.map