discoclaw 0.1.0

package/dist/discord/tool-aware-queue.test.js

@@ -0,0 +1,180 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { ToolAwareQueue } from './tool-aware-queue.js';
+beforeEach(() => {
+    vi.useFakeTimers();
+});
+afterEach(() => {
+    vi.useRealTimers();
+});
+function collect() {
+    const actions = [];
+    const emit = (a) => actions.push(a);
+    return { actions, emit };
+}
+describe('ToolAwareQueue', () => {
+    it('text-only response: text deltas buffered then streamed after flush delay', () => {
+        const { actions, emit } = collect();
+        const taq = new ToolAwareQueue(emit, { flushDelayMs: 2000, postToolDelayMs: 500 });
+        taq.handleEvent({ type: 'text_delta', text: 'Hello ' });
+        taq.handleEvent({ type: 'text_delta', text: 'world' });
+        // Before flush timer: nothing emitted yet.
+        expect(actions).toHaveLength(0);
+        // After flush timer fires.
+        vi.advanceTimersByTime(2000);
+        expect(actions).toHaveLength(1);
+        expect(actions[0]).toEqual({ type: 'stream_text', text: 'Hello world' });
+        // Further deltas stream directly.
+        taq.handleEvent({ type: 'text_delta', text: '!' });
+        expect(actions).toHaveLength(2);
+        expect(actions[1]).toEqual({ type: 'stream_text', text: '!' });
+        taq.dispose();
+    });
+    it('text then tool: narration discarded, activity shown', () => {
+        const { actions, emit } = collect();
+        const taq = new ToolAwareQueue(emit, { flushDelayMs: 2000, postToolDelayMs: 500 });
+        taq.handleEvent({ type: 'text_delta', text: 'Let me read the file...' });
+        taq.handleEvent({ type: 'tool_start', name: 'Read', input: { file_path: '/tmp/foo.ts' } });
+        // Narration was discarded, only show_activity emitted.
+        expect(actions).toHaveLength(1);
+        expect(actions[0]).toMatchObject({ type: 'show_activity' });
+        expect(actions[0].label).toContain('Reading');
+        taq.dispose();
+    });
+    it('tool then text: activity during tool, text streams after', () => {
+        const { actions, emit } = collect();
+        const taq = new ToolAwareQueue(emit, { flushDelayMs: 2000, postToolDelayMs: 500 });
+        taq.handleEvent({ type: 'tool_start', name: 'Bash' });
+        expect(actions).toHaveLength(1);
+        expect(actions[0]).toMatchObject({ type: 'show_activity', label: 'Running command...' });
+        taq.handleEvent({ type: 'tool_end', name: 'Bash', ok: true });
+        // After tool ends, start post-tool delay.
+        vi.advanceTimersByTime(500);
+        // Now text deltas should stream directly.
+        taq.handleEvent({ type: 'text_delta', text: 'The result is 42.' });
+        expect(actions).toHaveLength(2);
+        expect(actions[1]).toEqual({ type: 'stream_text', text: 'The result is 42.' });
+        taq.dispose();
+    });
+    it('multiple sequential tools: each shows its label, final text streams', () => {
+        const { actions, emit } = collect();
+        const taq = new ToolAwareQueue(emit, { flushDelayMs: 2000, postToolDelayMs: 500 });
+        // First tool.
+        taq.handleEvent({ type: 'tool_start', name: 'Read', input: { file_path: '/a/b.ts' } });
+        expect(actions).toHaveLength(1);
+        expect(actions[0]).toMatchObject({ type: 'show_activity' });
+        taq.handleEvent({ type: 'tool_end', name: 'Read', ok: true });
+        // Second tool arrives before post-tool flush.
+        taq.handleEvent({ type: 'tool_start', name: 'Bash' });
+        expect(actions).toHaveLength(2);
+        expect(actions[1]).toMatchObject({ type: 'show_activity', label: 'Running command...' });
+        taq.handleEvent({ type: 'tool_end', name: 'Bash', ok: true });
+        // Let post-tool flush fire.
+        vi.advanceTimersByTime(500);
+        // Final text.
+        taq.handleEvent({ type: 'text_final', text: 'Done!' });
+        expect(actions.find((a) => a.type === 'set_final')).toEqual({ type: 'set_final', text: 'Done!' });
+        taq.dispose();
+    });
+    it('text_final overrides everything', () => {
+        const { actions, emit } = collect();
+        const taq = new ToolAwareQueue(emit, { flushDelayMs: 2000, postToolDelayMs: 500 });
+        taq.handleEvent({ type: 'text_delta', text: 'buffered' });
+        taq.handleEvent({ type: 'text_final', text: 'The final answer.' });
+        // Timer should be cancelled, set_final should be emitted.
+        const finals = actions.filter((a) => a.type === 'set_final');
+        expect(finals).toHaveLength(1);
+        expect(finals[0]).toEqual({ type: 'set_final', text: 'The final answer.' });
+        // No stream_text for the buffered text.
+        expect(actions.filter((a) => a.type === 'stream_text')).toHaveLength(0);
+        taq.dispose();
+    });
+    it('flush timer fires correctly with fake timers', () => {
+        const { actions, emit } = collect();
+        const taq = new ToolAwareQueue(emit, { flushDelayMs: 3000, postToolDelayMs: 500 });
+        taq.handleEvent({ type: 'text_delta', text: 'test' });
+        // Not yet.
+        vi.advanceTimersByTime(2999);
+        expect(actions).toHaveLength(0);
+        // Now.
+        vi.advanceTimersByTime(1);
+        expect(actions).toHaveLength(1);
+        expect(actions[0]).toEqual({ type: 'stream_text', text: 'test' });
+        taq.dispose();
+    });
+    it('dispose() cancels timers', () => {
+        const { actions, emit } = collect();
+        const taq = new ToolAwareQueue(emit, { flushDelayMs: 2000, postToolDelayMs: 500 });
+        taq.handleEvent({ type: 'text_delta', text: 'will be lost' });
+        taq.dispose();
+        vi.advanceTimersByTime(5000);
+        expect(actions).toHaveLength(0);
+    });
+    it('post-tool delay prevents flashing narration between tools', () => {
+        const { actions, emit } = collect();
+        const taq = new ToolAwareQueue(emit, { flushDelayMs: 2000, postToolDelayMs: 500 });
+        taq.handleEvent({ type: 'tool_start', name: 'Read' });
+        taq.handleEvent({ type: 'tool_end', name: 'Read', ok: true });
+        // Text delta during post-tool delay window.
+        taq.handleEvent({ type: 'text_delta', text: 'Now let me run...' });
+        // Before post-tool delay fires, second tool starts.
+        vi.advanceTimersByTime(200);
+        taq.handleEvent({ type: 'tool_start', name: 'Bash' });
+        // The narration text should not have been streamed.
+        expect(actions.filter((a) => a.type === 'stream_text')).toHaveLength(0);
+        // Two show_activity actions.
+        expect(actions.filter((a) => a.type === 'show_activity')).toHaveLength(2);
+        taq.dispose();
+    });
+    it('events after dispose() are silently ignored', () => {
+        const { actions, emit } = collect();
+        const taq = new ToolAwareQueue(emit, { flushDelayMs: 2000, postToolDelayMs: 500 });
+        taq.handleEvent({ type: 'text_delta', text: 'before' });
+        taq.dispose();
+        const countAfterDispose = actions.length;
+        // These should all be silently dropped.
+        taq.handleEvent({ type: 'text_delta', text: 'after' });
+        taq.handleEvent({ type: 'tool_start', name: 'Read' });
+        taq.handleEvent({ type: 'tool_end', name: 'Read', ok: true });
+        taq.handleEvent({ type: 'text_final', text: 'final' });
+        vi.advanceTimersByTime(5000);
+        expect(actions).toHaveLength(countAfterDispose);
+    });
+    it('tool_end without prior tool_start does not crash', () => {
+        const { actions, emit } = collect();
+        const taq = new ToolAwareQueue(emit, { flushDelayMs: 2000, postToolDelayMs: 500 });
+        // Orphan tool_end — should be silently ignored (state is idle, not tool_active).
+        taq.handleEvent({ type: 'tool_end', name: 'Bash', ok: true });
+        // Queue should still function normally after the orphan.
+        taq.handleEvent({ type: 'text_delta', text: 'hello' });
+        vi.advanceTimersByTime(2000);
+        expect(actions).toHaveLength(1);
+        expect(actions[0]).toEqual({ type: 'stream_text', text: 'hello' });
+        taq.dispose();
+    });
+    it('multiple text_final events: only first is emitted as set_final', () => {
+        const { actions, emit } = collect();
+        const taq = new ToolAwareQueue(emit, { flushDelayMs: 2000, postToolDelayMs: 500 });
+        taq.handleEvent({ type: 'text_final', text: 'first final' });
+        taq.handleEvent({ type: 'text_final', text: 'second final' });
+        const finals = actions.filter((a) => a.type === 'set_final');
+        expect(finals).toHaveLength(2);
+        expect(finals[0]).toEqual({ type: 'set_final', text: 'first final' });
+        // Second text_final still emits (no crash), but first is the meaningful one.
+        expect(finals[1]).toEqual({ type: 'set_final', text: 'second final' });
+        taq.dispose();
+    });
+    it('text deltas during tool_active are discarded on next tool_start', () => {
+        const { actions, emit } = collect();
+        const taq = new ToolAwareQueue(emit, { flushDelayMs: 2000, postToolDelayMs: 500 });
+        taq.handleEvent({ type: 'tool_start', name: 'Read' });
+        taq.handleEvent({ type: 'text_delta', text: 'I found...' });
+        taq.handleEvent({ type: 'tool_end', name: 'Read', ok: true });
+        // Tool end transitions to buffering_text with empty buffer.
+        // But the text delta during tool_active was in buffer...
+        // Then a new tool arrives before the flush timer.
+        taq.handleEvent({ type: 'tool_start', name: 'Bash' });
+        // No stream_text should have been emitted.
+        expect(actions.filter((a) => a.type === 'stream_text')).toHaveLength(0);
+        taq.dispose();
+    });
+});

package/dist/discord/update-command.js

@@ -0,0 +1,127 @@
+import { execFile } from 'node:child_process';
+import { writeShutdownContext } from './shutdown-context.js';
+import { getRestartCmdArgs } from './restart-command.js';
+import { getActiveOrchestrator, getRunningPlanIds } from './forge-plan-registry.js';
+export function parseUpdateCommand(content) {
+    const normalized = content.trim().toLowerCase().replace(/\s+/g, ' ');
+    if (normalized === '!update')
+        return { action: 'check' };
+    if (normalized === '!update apply')
+        return { action: 'apply' };
+    if (normalized === '!update help')
+        return { action: 'help' };
+    return null;
+}
+function run(cmd, args, opts = {}) {
+    return new Promise((resolve) => {
+        execFile(cmd, args, {
+            timeout: opts.timeout ?? 60_000,
+            cwd: opts.cwd,
+            env: opts.env ?? process.env,
+        }, (err, stdout, stderr) => {
+            const exitCode = err ? err.code ?? null : 0;
+            resolve({
+                stdout: String(stdout ?? ''),
+                stderr: String(stderr ?? ''),
+                exitCode: typeof exitCode === 'number' ? exitCode : null,
+            });
+        });
+    });
+}
+const GIT_ENV = { ...process.env, GIT_TERMINAL_PROMPT: '0' };
+export async function handleUpdateCommand(cmd, opts = {}) {
+    const { log, dataDir, userId, restartCmd, projectCwd, onProgress } = opts;
+    const progress = (msg) => {
+        onProgress?.(msg);
+        log?.info({}, `update-command: ${msg}`);
+    };
+    if (cmd.action === 'help') {
+        return {
+            reply: [
+                '**!update commands:**',
+                '- `!update` — check for available updates from main',
+                '- `!update apply` — pull, install, build, and restart',
+                '- `!update help` — this message',
+            ].join('\n'),
+        };
+    }
+    if (cmd.action === 'check') {
+        progress('Fetching from origin...');
+        const fetch = await run('git', ['fetch'], { cwd: projectCwd, env: GIT_ENV, timeout: 60_000 });
+        if (fetch.exitCode !== 0) {
+            const detail = (fetch.stderr || fetch.stdout).trim().slice(0, 500);
+            return { reply: `Failed to fetch from origin: \`${detail}\`` };
+        }
+        const logResult = await run('git', ['log', 'HEAD..origin/main', '--oneline'], { cwd: projectCwd, env: GIT_ENV, timeout: 60_000 });
+        const commits = logResult.stdout.trim();
+        if (!commits) {
+            return { reply: 'Already up to date.' };
+        }
+        return { reply: `Available updates from main:\n\`\`\`\n${commits.slice(0, 1800)}\n\`\`\`` };
+    }
+    // action === 'apply'
+    // 1. Check for active work.
+    const activeOrch = getActiveOrchestrator();
+    if (activeOrch?.isRunning) {
+        return { reply: 'Cannot update: a forge run is in progress. Wait for it to finish or cancel it first.' };
+    }
+    if (getRunningPlanIds().size > 0) {
+        return { reply: 'Cannot update: a plan run is in progress. Wait for it to finish first.' };
+    }
+    // 2. Check for dirty tree.
+    progress('Checking working tree...');
+    const statusResult = await run('git', ['status', '--porcelain'], { cwd: projectCwd, env: GIT_ENV, timeout: 60_000 });
+    if (statusResult.stdout.trim()) {
+        return { reply: 'Cannot update: working tree has uncommitted changes. Stash or commit them first.' };
+    }
+    // 3. git pull
+    progress('Pulling from origin/main...');
+    const pull = await run('git', ['pull'], { cwd: projectCwd, env: GIT_ENV, timeout: 60_000 });
+    if (pull.exitCode !== 0) {
+        const detail = (pull.stderr || pull.stdout).trim().slice(0, 500);
+        return { reply: `\`git pull\` failed:\n\`\`\`\n${detail}\n\`\`\`` };
+    }
+    // 4. pnpm install
+    progress('Running pnpm install...');
+    const install = await run('pnpm', ['install'], { cwd: projectCwd, timeout: 120_000 });
+    if (install.exitCode !== 0) {
+        const detail = (install.stderr || install.stdout).trim().slice(0, 500);
+        return { reply: `\`pnpm install\` failed:\n\`\`\`\n${detail}\n\`\`\`` };
+    }
+    // 5. pnpm build
+    progress('Running pnpm build...');
+    const build = await run('pnpm', ['build'], { cwd: projectCwd, timeout: 120_000 });
+    if (build.exitCode !== 0) {
+        const detail = (build.stderr || build.stdout).trim().slice(0, 500);
+        return { reply: `\`pnpm build\` failed:\n\`\`\`\n${detail}\n\`\`\`` };
+    }
+    return {
+        reply: 'Update complete. Restarting discoclaw... back in a moment.',
+        deferred: () => {
+            if (dataDir) {
+                const ctx = {
+                    reason: 'restart-command',
+                    message: 'User requested via !update apply',
+                    timestamp: new Date().toISOString(),
+                    requestedBy: userId,
+                };
+                writeShutdownContext(dataDir, ctx).catch((err) => {
+                    log?.warn({ err }, 'update-command: failed to write shutdown context');
+                });
+            }
+            if (restartCmd) {
+                execFile('/bin/sh', ['-c', restartCmd], (err) => {
+                    if (err)
+                        log?.error({ err }, 'update-command: restart failed');
+                });
+            }
+            else {
+                const [restartBin, restartArgList] = getRestartCmdArgs();
+                execFile(restartBin, restartArgList, (err) => {
+                    if (err)
+                        log?.error({ err }, 'update-command: restart failed');
+                });
+            }
+        },
+    };
+}

package/dist/discord/update-command.test.js

@@ -0,0 +1,275 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { parseUpdateCommand, handleUpdateCommand } from './update-command.js';
+import * as shutdownCtx from './shutdown-context.js';
+import * as registry from './forge-plan-registry.js';
+// ---------------------------------------------------------------------------
+// Mock node:child_process
+// ---------------------------------------------------------------------------
+vi.mock('node:child_process', () => ({
+    execFile: vi.fn((cmd, args, optsOrCb, maybeCb) => {
+        const cb = typeof optsOrCb === 'function' ? optsOrCb : maybeCb;
+        // Default: all commands succeed with empty output.
+        if (cb)
+            cb(null, '', '');
+    }),
+}));
+// ---------------------------------------------------------------------------
+// parseUpdateCommand
+// ---------------------------------------------------------------------------
+describe('parseUpdateCommand', () => {
+    it('parses !update as check action', () => {
+        expect(parseUpdateCommand('!update')).toEqual({ action: 'check' });
+    });
+    it('parses !update apply', () => {
+        expect(parseUpdateCommand('!update apply')).toEqual({ action: 'apply' });
+    });
+    it('parses !update help', () => {
+        expect(parseUpdateCommand('!update help')).toEqual({ action: 'help' });
+    });
+    it('returns null for non-update messages', () => {
+        expect(parseUpdateCommand('hello')).toBeNull();
+        expect(parseUpdateCommand('!restart')).toBeNull();
+        expect(parseUpdateCommand('!updating')).toBeNull();
+        expect(parseUpdateCommand('!update unknown')).toBeNull();
+    });
+    it('is case-insensitive', () => {
+        expect(parseUpdateCommand('!UPDATE')).toEqual({ action: 'check' });
+        expect(parseUpdateCommand('!Update Apply')).toEqual({ action: 'apply' });
+        expect(parseUpdateCommand('!Update Help')).toEqual({ action: 'help' });
+    });
+    it('handles surrounding whitespace', () => {
+        expect(parseUpdateCommand('  !update  ')).toEqual({ action: 'check' });
+        expect(parseUpdateCommand('  !update  apply  ')).toEqual({ action: 'apply' });
+    });
+});
+// ---------------------------------------------------------------------------
+// handleUpdateCommand — help
+// ---------------------------------------------------------------------------
+describe('handleUpdateCommand: help', () => {
+    it('returns usage text without calling execFile', async () => {
+        const { execFile } = await import('node:child_process');
+        vi.clearAllMocks();
+        const result = await handleUpdateCommand({ action: 'help' });
+        expect(result.reply).toContain('!update commands');
+        expect(result.reply).toContain('!update apply');
+        expect(result.deferred).toBeUndefined();
+        expect(execFile).not.toHaveBeenCalled();
+    });
+});
+// ---------------------------------------------------------------------------
+// handleUpdateCommand — check
+// ---------------------------------------------------------------------------
+describe('handleUpdateCommand: check', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    it('reports "up to date" when git log returns empty output', async () => {
+        const { execFile } = await import('node:child_process');
+        execFile.mockImplementation((cmd, args, opts, cb) => {
+            cb(null, '', '');
+        });
+        const result = await handleUpdateCommand({ action: 'check' });
+        expect(result.reply).toBe('Already up to date.');
+        expect(result.deferred).toBeUndefined();
+    });
+    it('lists available commits when git log has output', async () => {
+        const { execFile } = await import('node:child_process');
+        execFile.mockImplementation((cmd, args, opts, cb) => {
+            if (args.includes('log')) {
+                cb(null, 'abc1234 Fix a bug\ndef5678 Add feature\n', '');
+            }
+            else {
+                cb(null, '', '');
+            }
+        });
+        const result = await handleUpdateCommand({ action: 'check' });
+        expect(result.reply).toContain('Available updates from main');
+        expect(result.reply).toContain('abc1234');
+        expect(result.reply).toContain('def5678');
+    });
+    it('reports error when git fetch fails', async () => {
+        const { execFile } = await import('node:child_process');
+        execFile.mockImplementation((cmd, args, opts, cb) => {
+            if (args.includes('fetch')) {
+                const err = new Error('network error');
+                err.code = 1;
+                cb(err, '', 'network error');
+            }
+            else {
+                cb(null, '', '');
+            }
+        });
+        const result = await handleUpdateCommand({ action: 'check' });
+        expect(result.reply).toContain('Failed to fetch');
+    });
+});
+// ---------------------------------------------------------------------------
+// handleUpdateCommand — apply
+// ---------------------------------------------------------------------------
+describe('handleUpdateCommand: apply', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        vi.spyOn(registry, 'getActiveOrchestrator').mockReturnValue(null);
+        vi.spyOn(registry, 'getRunningPlanIds').mockReturnValue(new Set());
+    });
+    function mockAllSuccess() {
+        return vi.fn((cmd, args, optsOrCb, maybeCb) => {
+            const cb = typeof optsOrCb === 'function' ? optsOrCb : maybeCb;
+            if (cb)
+                cb(null, '', '');
+        });
+    }
+    it('aborts when a forge run is active', async () => {
+        vi.spyOn(registry, 'getActiveOrchestrator').mockReturnValue({ isRunning: true });
+        const result = await handleUpdateCommand({ action: 'apply' });
+        expect(result.reply).toContain('forge run is in progress');
+        expect(result.deferred).toBeUndefined();
+    });
+    it('aborts when a plan run is active', async () => {
+        vi.spyOn(registry, 'getRunningPlanIds').mockReturnValue(new Set(['plan-001']));
+        const result = await handleUpdateCommand({ action: 'apply' });
+        expect(result.reply).toContain('plan run is in progress');
+        expect(result.deferred).toBeUndefined();
+    });
+    it('aborts when working tree is dirty', async () => {
+        const { execFile } = await import('node:child_process');
+        execFile.mockImplementation((cmd, args, opts, cb) => {
+            if (args.includes('--porcelain')) {
+                cb(null, 'M src/index.ts\n', '');
+            }
+            else {
+                cb(null, '', '');
+            }
+        });
+        const result = await handleUpdateCommand({ action: 'apply' });
+        expect(result.reply).toContain('uncommitted changes');
+        expect(result.deferred).toBeUndefined();
+    });
+    it('aborts and reports error when git pull fails', async () => {
+        const { execFile } = await import('node:child_process');
+        execFile.mockImplementation((cmd, args, opts, cb) => {
+            if (args.includes('pull')) {
+                const err = new Error('merge conflict');
+                err.code = 1;
+                cb(err, '', 'merge conflict');
+            }
+            else {
+                cb(null, '', '');
+            }
+        });
+        const result = await handleUpdateCommand({ action: 'apply' });
+        expect(result.reply).toContain('git pull');
+        expect(result.reply).toContain('failed');
+        expect(result.deferred).toBeUndefined();
+    });
+    it('aborts and reports error when pnpm install fails', async () => {
+        const { execFile } = await import('node:child_process');
+        execFile.mockImplementation((cmd, args, opts, cb) => {
+            if (cmd === 'pnpm' && args.includes('install')) {
+                const err = new Error('install failed');
+                err.code = 1;
+                cb(err, '', 'install failed');
+            }
+            else {
+                cb(null, '', '');
+            }
+        });
+        const result = await handleUpdateCommand({ action: 'apply' });
+        expect(result.reply).toContain('pnpm install');
+        expect(result.reply).toContain('failed');
+        expect(result.deferred).toBeUndefined();
+    });
+    it('aborts and reports error when pnpm build fails', async () => {
+        const { execFile } = await import('node:child_process');
+        execFile.mockImplementation((cmd, args, opts, cb) => {
+            if (cmd === 'pnpm' && args.includes('build')) {
+                const err = new Error('build failed');
+                err.code = 1;
+                cb(err, '', 'build failed');
+            }
+            else {
+                cb(null, '', '');
+            }
+        });
+        const result = await handleUpdateCommand({ action: 'apply' });
+        expect(result.reply).toContain('pnpm build');
+        expect(result.reply).toContain('failed');
+        expect(result.deferred).toBeUndefined();
+    });
+    it('returns a deferred restart function on full success', async () => {
+        const { execFile } = await import('node:child_process');
+        execFile.mockImplementation(mockAllSuccess());
+        const result = await handleUpdateCommand({ action: 'apply' });
+        expect(result.reply).toContain('Restarting discoclaw');
+        expect(typeof result.deferred).toBe('function');
+    });
+    it('deferred writes shutdown context before restarting', async () => {
+        const { execFile } = await import('node:child_process');
+        execFile.mockImplementation(mockAllSuccess());
+        const spy = vi.spyOn(shutdownCtx, 'writeShutdownContext').mockResolvedValue();
+        const result = await handleUpdateCommand({ action: 'apply' }, { dataDir: '/tmp/test', userId: '999' });
+        expect(spy).not.toHaveBeenCalled();
+        result.deferred();
+        expect(spy).toHaveBeenCalledOnce();
+        expect(spy.mock.calls[0][1]).toMatchObject({
+            reason: 'restart-command',
+            requestedBy: '999',
+        });
+        spy.mockRestore();
+    });
+    it('deferred uses systemctl restart by default', async () => {
+        const { execFile } = await import('node:child_process');
+        const mock = mockAllSuccess();
+        execFile.mockImplementation(mock);
+        const result = await handleUpdateCommand({ action: 'apply' });
+        result.deferred();
+        // Find the restart call — it's the last execFile call after the pipeline.
+        const calls = execFile.mock.calls;
+        const restartCall = calls.find(([cmd, args]) => cmd === 'systemctl' && args.includes('restart'));
+        expect(restartCall).toBeDefined();
+        expect(restartCall[1]).toEqual(['--user', 'restart', 'discoclaw']);
+    });
+    it('deferred uses launchctl kickstart on macOS', async () => {
+        const { execFile } = await import('node:child_process');
+        const mock = mockAllSuccess();
+        execFile.mockImplementation(mock);
+        const originalPlatform = process.platform;
+        Object.defineProperty(process, 'platform', { value: 'darwin', configurable: true });
+        const originalGetuid = process.getuid;
+        process.getuid = () => 501;
+        try {
+            const result = await handleUpdateCommand({ action: 'apply' });
+            result.deferred();
+            const calls = execFile.mock.calls;
+            const restartCall = calls.find(([cmd, args]) => cmd === 'launchctl' && args.includes('kickstart'));
+            expect(restartCall).toBeDefined();
+            expect(restartCall[1]).toContain('-k');
+            expect(restartCall[1].some((a) => a.includes('com.discoclaw.agent'))).toBe(true);
+        }
+        finally {
+            Object.defineProperty(process, 'platform', { value: originalPlatform, configurable: true });
+            process.getuid = originalGetuid;
+        }
+    });
+    it('deferred uses restartCmd via /bin/sh when provided', async () => {
+        const { execFile } = await import('node:child_process');
+        execFile.mockImplementation(mockAllSuccess());
+        const result = await handleUpdateCommand({ action: 'apply' }, { restartCmd: 'sudo systemctl restart discoclaw' });
+        result.deferred();
+        const calls = execFile.mock.calls;
+        const shCall = calls.find(([cmd]) => cmd === '/bin/sh');
+        expect(shCall).toBeDefined();
+        expect(shCall[1]).toEqual(['-c', 'sudo systemctl restart discoclaw']);
+    });
+    it('calls onProgress callback for each step', async () => {
+        const { execFile } = await import('node:child_process');
+        execFile.mockImplementation(mockAllSuccess());
+        const progress = [];
+        await handleUpdateCommand({ action: 'apply' }, { onProgress: (msg) => progress.push(msg) });
+        expect(progress.length).toBeGreaterThanOrEqual(4);
+        expect(progress.some((m) => m.includes('working tree') || m.includes('Checking'))).toBe(true);
+        expect(progress.some((m) => m.includes('pull') || m.includes('Pulling'))).toBe(true);
+        expect(progress.some((m) => m.includes('install'))).toBe(true);
+        expect(progress.some((m) => m.includes('build'))).toBe(true);
+    });
+});

package/dist/discord/user-errors.js

@@ -0,0 +1,40 @@
+export function messageContentIntentHint() {
+    return ('Discord is delivering empty message content. Enable Message Content Intent in the Discord Developer Portal ' +
+        '(Application -> Bot -> Privileged Gateway Intents), then restart the bot.');
+}
+export function mapRuntimeErrorToUserMessage(raw) {
+    const msg = String(raw ?? '').trim();
+    const lc = msg.toLowerCase();
+    const mentionsClaude = lc.includes('claude');
+    if (lc.includes('timed out')) {
+        return 'The runtime timed out before finishing. Try a smaller request or increase RUNTIME_TIMEOUT_MS.';
+    }
+    if (lc.includes('missing permissions') || lc.includes('missing access')) {
+        return ('Discord denied this action due to missing permissions/access. ' +
+            'Update the bot role permissions in Server Settings -> Roles, then retry.');
+    }
+    if (mentionsClaude && (lc.includes('not found') || lc.includes('enoent') || lc.includes('spawn'))) {
+        return 'Claude CLI was not found. Install it and set CLAUDE_BIN (or fix PATH), then restart.';
+    }
+    const mentionsGemini = lc.includes('gemini');
+    if (mentionsGemini && (lc.includes('not found') || lc.includes('enoent') || lc.includes('spawn'))) {
+        return 'Gemini CLI was not found. Install it and set GEMINI_BIN (or fix PATH), then restart.';
+    }
+    if (mentionsGemini && (lc.includes('unauthorized') || lc.includes('authentication') || lc.includes('not logged in'))) {
+        return 'Gemini CLI authentication is missing or expired. Re-authenticate Gemini CLI and retry.';
+    }
+    if (lc.includes('unauthorized') || lc.includes('authentication') || lc.includes('not logged in')) {
+        return 'Claude CLI authentication is missing or expired. Re-authenticate Claude CLI and retry.';
+    }
+    if (lc.includes('stream stall')) {
+        return 'The runtime stream stalled (no output received). This may indicate a network issue or API hang. Try again or increase DISCOCLAW_STREAM_STALL_TIMEOUT_MS.';
+    }
+    if (lc.includes('configuration error: missing required channel context')) {
+        return ('This channel is missing required context. Create/index the channel context file under content/discord/channels ' +
+            'or disable DISCORD_REQUIRE_CHANNEL_CONTEXT.');
+    }
+    if (!msg) {
+        return 'An unexpected runtime error occurred with no additional detail.';
+    }
+    return `Runtime error: ${msg}`;
+}

package/dist/discord/user-errors.test.js

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest';
+import { mapRuntimeErrorToUserMessage } from './user-errors.js';
+describe('mapRuntimeErrorToUserMessage', () => {
+    it('maps Claude binary missing errors to install guidance', () => {
+        const msg = mapRuntimeErrorToUserMessage('spawn claude ENOENT');
+        expect(msg).toContain('Claude CLI was not found');
+    });
+    it('does not misclassify generic ENOENT errors as Claude CLI missing', () => {
+        const msg = mapRuntimeErrorToUserMessage('ENOENT: no such file or directory, open /tmp/missing.json');
+        expect(msg).toContain('Runtime error:');
+        expect(msg).not.toContain('Claude CLI was not found');
+    });
+    it('maps Gemini binary missing errors to Gemini install guidance', () => {
+        const msg = mapRuntimeErrorToUserMessage('spawn gemini ENOENT');
+        expect(msg).toContain('Gemini CLI was not found');
+    });
+    it('maps Gemini auth errors to Gemini-specific guidance', () => {
+        const msg = mapRuntimeErrorToUserMessage('gemini: authentication failed');
+        expect(msg).toContain('Gemini CLI authentication');
+        expect(msg).not.toContain('Claude CLI');
+    });
+    it('does not misclassify generic auth errors as Gemini when gemini is not mentioned', () => {
+        const msg = mapRuntimeErrorToUserMessage('unauthorized');
+        expect(msg).toContain('Claude CLI authentication');
+    });
+    it('maps stream stall errors to stall-specific user message', () => {
+        const msg = mapRuntimeErrorToUserMessage('stream stall: no output for 120000ms');
+        expect(msg).toContain('stream stalled');
+        expect(msg).toContain('DISCOCLAW_STREAM_STALL_TIMEOUT_MS');
+    });
+});