discoclaw 0.1.0

package/dist/beads/bead-hooks-cli.js

@@ -0,0 +1,149 @@
+import path from 'node:path';
+import { Client, GatewayIntentBits } from 'discord.js';
+import { bdAddLabel, bdShow, bdUpdate } from './bd-cli.js';
+import { findExistingThreadForBead, createBeadThread, ensureUnarchived, getThreadIdFromBead, resolveBeadsForum, updateBeadThreadName, updateBeadThreadTags, closeBeadThread, isThreadArchived } from './discord-sync.js';
+import { loadTagMap } from './discord-sync.js';
+function env(name) {
+    const v = (process.env[name] ?? '').trim();
+    if (!v)
+        throw new Error(`${name} is required`);
+    return v;
+}
+function envOpt(name) {
+    const v = (process.env[name] ?? '').trim();
+    return v || undefined;
+}
+function parseTagsCsv(csv) {
+    if (!csv)
+        return [];
+    return csv.split(',').map((t) => t.trim()).filter(Boolean);
+}
+function truncate(s, max) {
+    if (s.length <= max)
+        return s;
+    return s.slice(0, Math.max(0, max - 1)) + '\u2026';
+}
+function hasNoThread(bead, extraLabels) {
+    const labels = new Set([...(bead.labels ?? []), ...extraLabels]);
+    return labels.has('no-thread');
+}
+async function run() {
+    const sub = process.argv[2] ?? '';
+    const beadId = process.argv[3] ?? '';
+    if (!sub || !beadId) {
+        throw new Error('Usage: bead-hooks-cli <on-create|on-update|on-status-change|on-close> <bead-id> [--tags a,b]');
+    }
+    const args = process.argv.slice(4);
+    let tagsCsv;
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--tags') {
+            tagsCsv = args[i + 1];
+            i++;
+        }
+    }
+    const discordToken = env('DISCORD_TOKEN');
+    const guildId = env('DISCORD_GUILD_ID');
+    const forumId = env('DISCOCLAW_BEADS_FORUM');
+    const beadsCwd = envOpt('DISCOCLAW_BEADS_CWD') ?? process.cwd();
+    const dataDir = envOpt('DISCOCLAW_DATA_DIR');
+    const tagMapPath = envOpt('DISCOCLAW_BEADS_TAG_MAP')
+        ?? (dataDir ? path.join(dataDir, 'beads', 'tag-map.json') : undefined);
+    const mentionUserId = envOpt('DISCOCLAW_BEADS_MENTION_USER');
+    const extraLabels = parseTagsCsv(tagsCsv);
+    const client = new Client({ intents: [GatewayIntentBits.Guilds] });
+    await client.login(discordToken);
+    await new Promise((resolve) => client.once('ready', () => resolve()));
+    try {
+        const guild = await client.guilds.fetch(guildId);
+        const forum = await resolveBeadsForum(guild, forumId);
+        if (!forum)
+            throw new Error(`Beads forum not found: ${forumId}`);
+        const tagMap = tagMapPath ? await loadTagMap(tagMapPath) : {};
+        const bead = await bdShow(beadId, beadsCwd);
+        if (!bead)
+            throw new Error(`Bead not found: ${beadId}`);
+        if (sub === 'on-create') {
+            if (hasNoThread(bead, extraLabels))
+                return;
+            const existingRef = getThreadIdFromBead(bead);
+            if (existingRef)
+                return;
+            const deduped = await findExistingThreadForBead(forum, bead.id);
+            if (deduped) {
+                await bdUpdate(bead.id, { externalRef: `discord:${deduped}` }, beadsCwd);
+                // Backfill tag labels if provided.
+                for (const t of extraLabels) {
+                    try {
+                        await bdAddLabel(bead.id, `tag:${t}`, beadsCwd);
+                    }
+                    catch { }
+                }
+                return;
+            }
+            const beadForThread = { ...bead, labels: [...new Set([...(bead.labels ?? []), ...extraLabels])] };
+            const threadId = await createBeadThread(forum, beadForThread, tagMap, mentionUserId);
+            try {
+                await bdUpdate(bead.id, { externalRef: `discord:${threadId}` }, beadsCwd);
+            }
+            catch { }
+            for (const t of extraLabels) {
+                try {
+                    await bdAddLabel(bead.id, `tag:${t}`, beadsCwd);
+                }
+                catch { }
+            }
+            return;
+        }
+        const threadId = getThreadIdFromBead(bead);
+        if (!threadId)
+            return;
+        if (sub === 'on-status-change') {
+            await ensureUnarchived(client, threadId);
+            await updateBeadThreadName(client, threadId, bead);
+            await updateBeadThreadTags(client, threadId, bead, tagMap);
+            return;
+        }
+        if (sub === 'on-update') {
+            await ensureUnarchived(client, threadId);
+            await updateBeadThreadName(client, threadId, bead);
+            const title = bead.title || 'Untitled';
+            const status = bead.status || 'open';
+            const priority = `P${bead.priority ?? 2}`;
+            const desc = truncate(bead.description ?? 'No description', 1800);
+            const content = `**Update**\n` +
+                `**Priority:** ${priority}\n` +
+                `**Status:** ${status}\n` +
+                `**Title:** ${title}\n\n` +
+                `${desc}`;
+            // Avoid accidental mentions from bead content.
+            try {
+                const thread = await client.channels.fetch(threadId);
+                if (thread && thread.isThread()) {
+                    try {
+                        await thread.send({ content: truncate(content, 2000), allowedMentions: { parse: [], users: [] } });
+                    }
+                    catch {
+                        // ignore
+                    }
+                }
+            }
+            catch {
+                // ignore fetch failures
+            }
+            return;
+        }
+        if (sub === 'on-close') {
+            // Lightweight check: skip if thread is already archived to avoid
+            // duplicate close messages from concurrent close operations.
+            if (await isThreadArchived(client, threadId))
+                return;
+            await closeBeadThread(client, threadId, bead, tagMap);
+            return;
+        }
+        throw new Error(`Unknown subcommand: ${sub}`);
+    }
+    finally {
+        client.destroy();
+    }
+}
+await run();

package/dist/beads/bead-sync-cli.js

@@ -0,0 +1,5 @@
+export { parseArgInt, runSyncWithStore, runTaskSyncCliMain, runTaskSyncWithStore, } from '../tasks/task-sync-cli.js';
+if (import.meta.url === new URL(process.argv[1] ?? '', 'file:').href) {
+    const { runTaskSyncCliMain } = await import('../tasks/task-sync-cli.js');
+    await runTaskSyncCliMain();
+}

package/dist/beads/bead-sync-cli.test.js

@@ -0,0 +1,72 @@
+import { describe, expect, it, vi } from 'vitest';
+import { parseArgInt, runSyncWithStore } from './bead-sync-cli.js';
+import { parseArgInt as parseTaskArgInt, runSyncWithStore as runTaskSyncWithStoreCompat, } from '../tasks/task-sync-cli.js';
+vi.mock('../tasks/task-sync-engine.js', () => {
+    const runTaskSync = vi.fn().mockResolvedValue({ created: 0, updated: 0, closed: 0 });
+    return { runTaskSync };
+});
+// bead-sync-cli.ts uses an import.meta.url guard so that main() does NOT run
+// when the module is imported (only when invoked as a script). This lets us
+// import and test the exported helpers without triggering Discord connections
+// or env-var validation.
+describe('parseArgInt', () => {
+    it('keeps compatibility exports aligned to canonical task sync CLI module', () => {
+        expect(parseArgInt).toBe(parseTaskArgInt);
+        expect(runSyncWithStore).toBe(runTaskSyncWithStoreCompat);
+    });
+    it('returns undefined when the flag is not in args', () => {
+        expect(parseArgInt(['--foo', '1'], '--bar')).toBeUndefined();
+    });
+    it('returns undefined for an empty args array', () => {
+        expect(parseArgInt([], '--throttle-ms')).toBeUndefined();
+    });
+    it('parses a positive integer', () => {
+        expect(parseArgInt(['--throttle-ms', '500'], '--throttle-ms')).toBe(500);
+    });
+    it('parses zero', () => {
+        expect(parseArgInt(['--throttle-ms', '0'], '--throttle-ms')).toBe(0);
+    });
+    it('parses a negative integer', () => {
+        expect(parseArgInt(['--limit', '-1'], '--limit')).toBe(-1);
+    });
+    it('parses a decimal value', () => {
+        expect(parseArgInt(['--throttle-ms', '2.5'], '--throttle-ms')).toBe(2.5);
+    });
+    it('finds the flag among mixed args', () => {
+        expect(parseArgInt(['--archived-limit', '200', '--throttle-ms', '100'], '--throttle-ms')).toBe(100);
+    });
+    it('returns the value for the first occurrence when the flag appears more than once', () => {
+        expect(parseArgInt(['--limit', '10', '--limit', '20'], '--limit')).toBe(10);
+    });
+    it('throws when the flag is present but no value follows', () => {
+        expect(() => parseArgInt(['--throttle-ms'], '--throttle-ms')).toThrow('--throttle-ms requires a value');
+    });
+    it('throws when the value is a non-numeric string', () => {
+        expect(() => parseArgInt(['--limit', 'abc'], '--limit')).toThrow('--limit must be a number');
+    });
+    it('throws when the value is "NaN"', () => {
+        expect(() => parseArgInt(['--limit', 'NaN'], '--limit')).toThrow('must be a number');
+    });
+    it('throws when the value is "Infinity"', () => {
+        expect(() => parseArgInt(['--limit', 'Infinity'], '--limit')).toThrow('must be a number');
+    });
+});
+describe('runSyncWithStore', () => {
+    it('passes store through to runTaskSync', async () => {
+        const { runTaskSync } = await import('../tasks/task-sync-engine.js');
+        const { TaskStore } = await import('../tasks/store.js');
+        const store = new TaskStore();
+        const fakeClient = {};
+        const fakeGuild = {};
+        await runSyncWithStore({
+            client: fakeClient,
+            guild: fakeGuild,
+            forumId: 'forum-123',
+            tagMap: {},
+            store,
+            throttleMs: 100,
+            archivedDedupeLimit: 50,
+        });
+        expect(runTaskSync).toHaveBeenCalledWith(expect.objectContaining({ store }));
+    });
+});

package/dist/beads/bead-sync-coordinator.js

@@ -0,0 +1,4 @@
+import { TaskSyncCoordinator, } from '../tasks/sync-coordinator.js';
+export class BeadSyncCoordinator extends TaskSyncCoordinator {
+}
+export { TaskSyncCoordinator };

package/dist/beads/bead-sync-coordinator.test.js

@@ -0,0 +1,239 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+vi.mock('../tasks/task-sync-engine.js', () => {
+    const runTaskSync = vi.fn(async () => ({
+        threadsCreated: 0,
+        emojisUpdated: 0,
+        starterMessagesUpdated: 0,
+        threadsArchived: 0,
+        statusesUpdated: 0,
+        tagsUpdated: 0,
+        warnings: 0,
+        closesDeferred: 0,
+    }));
+    return { runTaskSync };
+});
+vi.mock('../tasks/thread-cache.js', () => ({
+    taskThreadCache: { invalidate: vi.fn() },
+}));
+vi.mock('../tasks/discord-sync.js', () => ({
+    reloadTagMapInPlace: vi.fn(async () => 2),
+}));
+import { BeadSyncCoordinator } from './bead-sync-coordinator.js';
+import { reloadTagMapInPlace } from '../tasks/discord-sync.js';
+function makeOpts() {
+    return {
+        client: {},
+        guild: {},
+        forumId: 'forum-1',
+        tagMap: {},
+        store: {},
+        log: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+    };
+}
+describe('BeadSyncCoordinator', () => {
+    beforeEach(() => vi.clearAllMocks());
+    it('calls runTaskSync and returns result', async () => {
+        const { runTaskSync } = await import('../tasks/task-sync-engine.js');
+        const coord = new BeadSyncCoordinator(makeOpts());
+        const result = await coord.sync();
+        expect(runTaskSync).toHaveBeenCalledOnce();
+        expect(result).toEqual(expect.objectContaining({ threadsCreated: 0 }));
+    });
+    it('invalidates cache after sync', async () => {
+        const { taskThreadCache } = await import('../tasks/thread-cache.js');
+        const coord = new BeadSyncCoordinator(makeOpts());
+        await coord.sync();
+        expect(taskThreadCache.invalidate).toHaveBeenCalledOnce();
+    });
+    it('passes statusPoster through to runTaskSync', async () => {
+        const { runTaskSync } = await import('../tasks/task-sync-engine.js');
+        const statusPoster = { taskSyncComplete: vi.fn() };
+        const coord = new BeadSyncCoordinator(makeOpts());
+        await coord.sync(statusPoster);
+        expect(runTaskSync).toHaveBeenCalledWith(expect.objectContaining({ statusPoster }));
+    });
+    it('omits statusPoster when not provided', async () => {
+        const { runTaskSync } = await import('../tasks/task-sync-engine.js');
+        const coord = new BeadSyncCoordinator(makeOpts());
+        await coord.sync();
+        expect(runTaskSync).toHaveBeenCalledWith(expect.objectContaining({ statusPoster: undefined }));
+    });
+    it('returns null for concurrent call and triggers follow-up', async () => {
+        const { runTaskSync } = await import('../tasks/task-sync-engine.js');
+        // Make the first sync take a while
+        let resolveFirst;
+        const firstPromise = new Promise((r) => { resolveFirst = r; });
+        runTaskSync.mockImplementationOnce(async () => {
+            await firstPromise;
+            return { threadsCreated: 1, emojisUpdated: 0, starterMessagesUpdated: 0, threadsArchived: 0, statusesUpdated: 0, tagsUpdated: 0, warnings: 0 };
+        });
+        const coord = new BeadSyncCoordinator(makeOpts());
+        // Start first sync (will block)
+        const first = coord.sync();
+        // Second call while first is running should return null
+        const second = await coord.sync();
+        expect(second).toBeNull();
+        // Complete the first sync
+        resolveFirst();
+        const firstResult = await first;
+        expect(firstResult).toEqual(expect.objectContaining({ threadsCreated: 1 }));
+        // Wait a tick for the fire-and-forget follow-up to start
+        await new Promise((r) => setTimeout(r, 10));
+        // runTaskSync should have been called at least twice (first + follow-up)
+        expect(runTaskSync.mock.calls.length).toBeGreaterThanOrEqual(2);
+    });
+    it('propagates runTaskSync errors and remains usable', async () => {
+        const { runTaskSync } = await import('../tasks/task-sync-engine.js');
+        const { taskThreadCache } = await import('../tasks/thread-cache.js');
+        runTaskSync.mockRejectedValueOnce(new Error('Discord API down'));
+        const coord = new BeadSyncCoordinator(makeOpts());
+        // First call should throw
+        await expect(coord.sync()).rejects.toThrow('Discord API down');
+        // Cache should not be invalidated on failure
+        expect(taskThreadCache.invalidate).not.toHaveBeenCalled();
+        // Coordinator should still be usable for subsequent calls
+        const result = await coord.sync();
+        expect(result).toEqual(expect.objectContaining({ threadsCreated: 0 }));
+        expect(taskThreadCache.invalidate).toHaveBeenCalledOnce();
+    });
+    it('follow-up uses the coalesced caller statusPoster, not the running one', async () => {
+        const { runTaskSync } = await import('../tasks/task-sync-engine.js');
+        let resolveFirst;
+        const firstPromise = new Promise((r) => { resolveFirst = r; });
+        runTaskSync.mockImplementationOnce(async () => {
+            await firstPromise;
+            return { threadsCreated: 0, emojisUpdated: 0, starterMessagesUpdated: 0, threadsArchived: 0, statusesUpdated: 0, warnings: 0 };
+        });
+        const coord = new BeadSyncCoordinator(makeOpts());
+        const statusPoster = { taskSyncComplete: vi.fn() };
+        // Watcher triggers sync without statusPoster
+        const first = coord.sync();
+        // User action triggers sync with statusPoster — coalesced
+        const second = await coord.sync(statusPoster);
+        expect(second).toBeNull();
+        // Complete the first sync
+        resolveFirst();
+        await first;
+        // Wait for fire-and-forget follow-up
+        await new Promise((r) => setTimeout(r, 10));
+        // The follow-up (second call to runTaskSync) should have the user's statusPoster
+        const followUpCall = runTaskSync.mock.calls[1];
+        expect(followUpCall[0].statusPoster).toBe(statusPoster);
+    });
+    it('logs warning when follow-up sync fails', async () => {
+        const { runTaskSync } = await import('../tasks/task-sync-engine.js');
+        let resolveFirst;
+        const firstPromise = new Promise((r) => { resolveFirst = r; });
+        runTaskSync
+            .mockImplementationOnce(async () => {
+            await firstPromise;
+            return { threadsCreated: 0, emojisUpdated: 0, starterMessagesUpdated: 0, threadsArchived: 0, statusesUpdated: 0, warnings: 0 };
+        })
+            .mockRejectedValueOnce(new Error('follow-up boom'));
+        const opts = makeOpts();
+        const coord = new BeadSyncCoordinator(opts);
+        const first = coord.sync();
+        await coord.sync(); // coalesce
+        resolveFirst();
+        await first;
+        // Wait for follow-up to fail and log
+        await new Promise((r) => setTimeout(r, 10));
+        expect(opts.log.warn).toHaveBeenCalledWith(expect.objectContaining({ err: expect.any(Error) }), 'tasks:coordinator follow-up sync failed');
+    });
+    it('reloads tag map before runTaskSync when tagMapPath is set', async () => {
+        const { runTaskSync } = await import('../tasks/task-sync-engine.js');
+        reloadTagMapInPlace.mockClear();
+        const opts = makeOpts();
+        opts.tagMapPath = '/tmp/tag-map.json';
+        opts.tagMap = { bug: '111' };
+        const coord = new BeadSyncCoordinator(opts);
+        await coord.sync();
+        expect(reloadTagMapInPlace).toHaveBeenCalledWith('/tmp/tag-map.json', opts.tagMap);
+        // reloadTagMapInPlace called before runTaskSync
+        const reloadOrder = reloadTagMapInPlace.mock.invocationCallOrder[0];
+        const syncOrder = runTaskSync.mock.invocationCallOrder[0];
+        expect(reloadOrder).toBeLessThan(syncOrder);
+    });
+    it('preserves existing map and continues sync when tag-map reload fails', async () => {
+        const { runTaskSync } = await import('../tasks/task-sync-engine.js');
+        reloadTagMapInPlace.mockRejectedValueOnce(new Error('bad json'));
+        const opts = makeOpts();
+        opts.tagMapPath = '/tmp/tag-map.json';
+        opts.tagMap = { bug: '111' };
+        const coord = new BeadSyncCoordinator(opts);
+        const result = await coord.sync();
+        // Sync still runs despite reload failure
+        expect(result).toEqual(expect.objectContaining({ threadsCreated: 0 }));
+        expect(runTaskSync).toHaveBeenCalled();
+        expect(opts.log.warn).toHaveBeenCalledWith(expect.objectContaining({ err: expect.any(Error), tagMapPath: '/tmp/tag-map.json' }), 'tasks:tag-map reload failed; using cached map');
+    });
+    it('does not attempt reload when tagMapPath is not set', async () => {
+        reloadTagMapInPlace.mockClear();
+        const opts = makeOpts();
+        // No tagMapPath set
+        const coord = new BeadSyncCoordinator(opts);
+        await coord.sync();
+        expect(reloadTagMapInPlace).not.toHaveBeenCalled();
+    });
+    it('passes a tagMap snapshot to runTaskSync', async () => {
+        const { runTaskSync } = await import('../tasks/task-sync-engine.js');
+        reloadTagMapInPlace.mockClear();
+        const tagMap = { bug: '111' };
+        const opts = makeOpts();
+        opts.tagMapPath = '/tmp/tag-map.json';
+        opts.tagMap = tagMap;
+        const coord = new BeadSyncCoordinator(opts);
+        await coord.sync();
+        // runTaskSync should receive a snapshot (different object reference)
+        const passedOpts = runTaskSync.mock.calls[0][0];
+        expect(passedOpts.tagMap).toEqual(tagMap);
+        expect(passedOpts.tagMap).not.toBe(tagMap);
+    });
+});
+describe('BeadSyncCoordinator deferred-close retry', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        vi.useFakeTimers();
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+    it('does not schedule retry when closesDeferred is 0', async () => {
+        const { runTaskSync } = await import('../tasks/task-sync-engine.js');
+        const coord = new BeadSyncCoordinator(makeOpts());
+        await coord.sync();
+        expect(runTaskSync).toHaveBeenCalledOnce();
+        await vi.advanceTimersByTimeAsync(35_000);
+        // No retry — only the original call.
+        expect(runTaskSync.mock.calls.length).toBe(1);
+    });
+    it('schedules a retry sync after 30s when closesDeferred > 0', async () => {
+        const { runTaskSync } = await import('../tasks/task-sync-engine.js');
+        runTaskSync.mockResolvedValueOnce({
+            threadsCreated: 0, emojisUpdated: 0, starterMessagesUpdated: 0,
+            threadsArchived: 0, statusesUpdated: 0, tagsUpdated: 0, warnings: 0,
+            closesDeferred: 1,
+        });
+        const coord = new BeadSyncCoordinator(makeOpts());
+        await coord.sync();
+        expect(runTaskSync).toHaveBeenCalledOnce();
+        await vi.advanceTimersByTimeAsync(30_000);
+        // Retry should have fired.
+        expect(runTaskSync.mock.calls.length).toBe(2);
+    });
+    it('deferred-close retry failure is logged', async () => {
+        const { runTaskSync } = await import('../tasks/task-sync-engine.js');
+        runTaskSync
+            .mockResolvedValueOnce({
+            threadsCreated: 0, emojisUpdated: 0, starterMessagesUpdated: 0,
+            threadsArchived: 0, statusesUpdated: 0, tagsUpdated: 0, warnings: 0,
+            closesDeferred: 1,
+        })
+            .mockRejectedValueOnce(new Error('retry boom'));
+        const opts = makeOpts();
+        const coord = new BeadSyncCoordinator(opts);
+        await coord.sync();
+        await vi.advanceTimersByTimeAsync(30_000);
+        expect(opts.log.warn).toHaveBeenCalledWith(expect.objectContaining({ err: expect.any(Error) }), 'tasks:coordinator deferred-close retry failed');
+    });
+});

package/dist/beads/bead-sync-watcher.js

@@ -0,0 +1,2 @@
+import { startTaskSyncWatcher, } from '../tasks/sync-watcher.js';
+export const startBeadSyncWatcher = startTaskSyncWatcher;

package/dist/beads/bead-sync-watcher.test.js

@@ -0,0 +1,96 @@
+import { describe, expect, it, vi } from 'vitest';
+import { EventEmitter } from 'node:events';
+import { startBeadSyncWatcher } from './bead-sync-watcher.js';
+import { startTaskSyncWatcher } from '../tasks/sync-watcher.js';
+function makeCoordinator() {
+    return {
+        sync: vi.fn(async () => ({
+            threadsCreated: 0,
+            emojisUpdated: 0,
+            starterMessagesUpdated: 0,
+            threadsArchived: 0,
+            statusesUpdated: 0,
+            tagsUpdated: 0,
+            warnings: 0,
+        })),
+    };
+}
+function makeStore() {
+    return new EventEmitter();
+}
+describe('startBeadSyncWatcher', () => {
+    it('keeps compatibility export aligned to canonical task sync watcher module', () => {
+        expect(startBeadSyncWatcher).toBe(startTaskSyncWatcher);
+    });
+    it('triggers sync on store created event', async () => {
+        const coordinator = makeCoordinator();
+        const store = makeStore();
+        const handle = startBeadSyncWatcher({ coordinator, store });
+        store.emit('created', {});
+        await Promise.resolve();
+        expect(coordinator.sync).toHaveBeenCalledOnce();
+        expect(coordinator.sync).toHaveBeenCalledWith();
+        handle.stop();
+    });
+    it('triggers sync on store updated event', async () => {
+        const coordinator = makeCoordinator();
+        const store = makeStore();
+        const handle = startBeadSyncWatcher({ coordinator, store });
+        store.emit('updated', {}, {});
+        await Promise.resolve();
+        expect(coordinator.sync).toHaveBeenCalledOnce();
+        handle.stop();
+    });
+    it('triggers sync on store closed event', async () => {
+        const coordinator = makeCoordinator();
+        const store = makeStore();
+        const handle = startBeadSyncWatcher({ coordinator, store });
+        store.emit('closed', {});
+        await Promise.resolve();
+        expect(coordinator.sync).toHaveBeenCalledOnce();
+        handle.stop();
+    });
+    it('triggers sync on store labeled event', async () => {
+        const coordinator = makeCoordinator();
+        const store = makeStore();
+        const handle = startBeadSyncWatcher({ coordinator, store });
+        store.emit('labeled', {}, 'some-label');
+        await Promise.resolve();
+        expect(coordinator.sync).toHaveBeenCalledOnce();
+        handle.stop();
+    });
+    it('no sync fires after stop()', async () => {
+        const coordinator = makeCoordinator();
+        const store = makeStore();
+        const handle = startBeadSyncWatcher({ coordinator, store });
+        handle.stop();
+        store.emit('created', {});
+        await Promise.resolve();
+        expect(coordinator.sync).not.toHaveBeenCalled();
+    });
+    it('multiple events each trigger a sync call (coordinator coalesces)', async () => {
+        const coordinator = makeCoordinator();
+        const store = makeStore();
+        const handle = startBeadSyncWatcher({ coordinator, store });
+        store.emit('created', {});
+        store.emit('updated', {}, {});
+        store.emit('closed', {});
+        await Promise.resolve();
+        // Each event fires a sync; the coordinator's concurrency guard coalesces them.
+        expect(coordinator.sync).toHaveBeenCalledTimes(3);
+        handle.stop();
+    });
+    it('sync failure is caught and logged without throwing', async () => {
+        const coordinator = {
+            sync: vi.fn().mockRejectedValue(new Error('network error')),
+        };
+        const store = makeStore();
+        const log = { warn: vi.fn(), info: vi.fn(), error: vi.fn() };
+        const handle = startBeadSyncWatcher({ coordinator, store, log });
+        store.emit('created', {});
+        // Flush the microtask queue so the catch handler runs.
+        await new Promise((r) => setTimeout(r, 0));
+        expect(log.warn).toHaveBeenCalledWith(expect.objectContaining({ err: expect.any(Error) }), 'tasks:watcher sync failed');
+        handle.stop();
+    });
+});

package/dist/beads/bead-sync.js

@@ -0,0 +1,7 @@
+import { runTaskSync, } from '../tasks/task-sync-engine.js';
+/**
+ * Legacy compatibility shim. Canonical implementation now lives at
+ * `src/tasks/task-sync-engine.ts`.
+ */
+export * from '../tasks/task-sync-engine.js';
+export const runBeadSync = runTaskSync;