discoclaw 0.1.0

package/dist/tasks/task-action-mutation-helpers.js

@@ -0,0 +1,17 @@
+import { createTaskService } from './service.js';
+import { runTaskSync } from './task-sync.js';
+export function resolveTaskService(taskCtx) {
+    if (taskCtx.taskService)
+        return taskCtx.taskService;
+    const taskService = createTaskService(taskCtx.store);
+    taskCtx.taskService = taskService;
+    return taskService;
+}
+export function resolveTaskId(action) {
+    return (action.taskId ?? '').trim();
+}
+export function scheduleRepairSync(taskCtx, taskId, ctx) {
+    runTaskSync(taskCtx, { client: ctx.client, guild: ctx.guild }).catch((err) => {
+        taskCtx.log?.warn({ err, taskId }, 'tasks:repair sync failed');
+    });
+}

package/dist/tasks/task-action-mutations.js

@@ -0,0 +1,151 @@
+import { TASK_STATUSES, isTaskStatus } from './types.js';
+import { withDirectTaskLifecycle } from './task-lifecycle.js';
+import { autoTagTask } from './auto-tag.js';
+import { taskThreadCache } from './thread-cache.js';
+import { resolveTaskId, resolveTaskService, scheduleRepairSync, } from './task-action-mutation-helpers.js';
+import { ensureCreatedTaskThreadLink, syncClosedTaskThread, syncUpdatedTaskThread, } from './task-action-thread-sync.js';
+/** Pre-computed set for filtering status names from tag candidates. */
+const STATUS_NAME_SET = new Set(TASK_STATUSES);
+/**
+ * Discord message content limit. Descriptions are rendered in the thread's
+ * starter message, so they must fit within this budget (minus ~100 chars of
+ * metadata overhead added by buildTaskStarterContent).
+ */
+const TASK_DESC_WRITE_MAX = 1900;
+export async function handleTaskCreate(action, ctx, taskCtx) {
+    if (!action.title) {
+        return { ok: false, error: 'taskCreate requires a title' };
+    }
+    if (action.description && action.description.length > TASK_DESC_WRITE_MAX) {
+        return { ok: false, error: `description exceeds ${TASK_DESC_WRITE_MAX} character limit (got ${action.description.length})` };
+    }
+    const labels = [];
+    if (action.tags) {
+        labels.push(...action.tags.split(',').map((t) => t.trim()).filter(Boolean));
+    }
+    const taskService = resolveTaskService(taskCtx);
+    const task = taskService.create({
+        title: action.title,
+        description: action.description,
+        priority: action.priority,
+        labels,
+    });
+    let threadId = '';
+    let needsRepairSync = false;
+    await withDirectTaskLifecycle(task.id, async () => {
+        const tagNames = Object.keys(taskCtx.tagMap).filter((k) => !STATUS_NAME_SET.has(k));
+        if (taskCtx.autoTag && tagNames.length > 0) {
+            try {
+                const suggestedTags = await autoTagTask(taskCtx.runtime, task.title, task.description ?? '', tagNames, {
+                    model: taskCtx.autoTagModel,
+                    cwd: taskCtx.tasksCwd || process.cwd(),
+                    modelResolver: taskCtx.resolveModel,
+                });
+                for (const tag of suggestedTags) {
+                    if (!labels.includes(tag))
+                        labels.push(tag);
+                }
+                for (const tag of suggestedTags) {
+                    try {
+                        taskService.addLabel(task.id, `tag:${tag}`);
+                    }
+                    catch {
+                        // best-effort
+                    }
+                }
+            }
+            catch (err) {
+                taskCtx.log?.warn({ err, taskId: task.id }, 'tasks:auto-tag failed');
+            }
+        }
+        const threadLink = await ensureCreatedTaskThreadLink({
+            actionType: action.type,
+            taskCtx,
+            runCtx: ctx,
+            taskService,
+            task,
+            labels,
+        });
+        threadId = threadLink.threadId;
+        if (threadLink.needsRepairSync)
+            needsRepairSync = true;
+    });
+    if (needsRepairSync) {
+        scheduleRepairSync(taskCtx, task.id, ctx);
+    }
+    taskThreadCache.invalidate();
+    taskCtx.forumCountSync?.requestUpdate();
+    const threadNote = threadId ? ' (thread linked)' : '';
+    return { ok: true, summary: `Task ${task.id} created: "${task.title}"${threadNote}` };
+}
+export async function handleTaskUpdate(action, ctx, taskCtx) {
+    const taskId = resolveTaskId(action);
+    if (!taskId) {
+        return { ok: false, error: 'taskUpdate requires taskId' };
+    }
+    if (action.description && action.description.length > TASK_DESC_WRITE_MAX) {
+        return { ok: false, error: `description exceeds ${TASK_DESC_WRITE_MAX} character limit (got ${action.description.length})` };
+    }
+    if (action.status && !isTaskStatus(action.status)) {
+        return { ok: false, error: `Invalid task status: "${action.status}"` };
+    }
+    let needsRepairSync = false;
+    const taskService = resolveTaskService(taskCtx);
+    await withDirectTaskLifecycle(taskId, async () => {
+        const updatedTask = taskService.update(taskId, {
+            title: action.title,
+            description: action.description,
+            priority: action.priority,
+            status: action.status,
+        });
+        const threadRepair = await syncUpdatedTaskThread({
+            actionType: action.type,
+            taskCtx,
+            runCtx: ctx,
+            taskId,
+            updatedTask,
+        });
+        if (threadRepair)
+            needsRepairSync = true;
+    });
+    if (needsRepairSync) {
+        scheduleRepairSync(taskCtx, taskId, ctx);
+    }
+    taskThreadCache.invalidate();
+    if (action.status)
+        taskCtx.forumCountSync?.requestUpdate();
+    const changes = [];
+    if (action.title)
+        changes.push(`title → "${action.title}"`);
+    if (action.status)
+        changes.push(`status → ${action.status}`);
+    if (action.priority != null)
+        changes.push(`priority → P${action.priority}`);
+    return { ok: true, summary: `Task ${taskId} updated: ${changes.join(', ') || 'no changes'}` };
+}
+export async function handleTaskClose(action, ctx, taskCtx) {
+    const taskId = resolveTaskId(action);
+    if (!taskId) {
+        return { ok: false, error: 'taskClose requires taskId' };
+    }
+    let needsRepairSync = false;
+    const taskService = resolveTaskService(taskCtx);
+    await withDirectTaskLifecycle(taskId, async () => {
+        const closedTask = taskService.close(taskId, action.reason);
+        const threadRepair = await syncClosedTaskThread({
+            actionType: action.type,
+            taskCtx,
+            runCtx: ctx,
+            taskId,
+            closedTask,
+        });
+        if (threadRepair)
+            needsRepairSync = true;
+    });
+    if (needsRepairSync) {
+        scheduleRepairSync(taskCtx, taskId, ctx);
+    }
+    taskThreadCache.invalidate();
+    taskCtx.forumCountSync?.requestUpdate();
+    return { ok: true, summary: `Task ${taskId} closed${action.reason ? `: ${action.reason}` : ''}` };
+}

package/dist/tasks/task-action-prompt.js

@@ -0,0 +1,62 @@
+export function taskActionsPromptSection() {
+    return `### Task Tracking
+
+**taskCreate** — Create a new task:
+\`\`\`
+<discord-action>{"type":"taskCreate","title":"Task title","description":"Optional details","priority":2,"tags":"feature,work"}</discord-action>
+\`\`\`
+- \`title\` (required): Task title.
+- \`description\` (optional): Detailed description.
+- \`priority\` (optional): 0-4 (0=highest, default 2).
+- \`tags\` (optional): Comma-separated labels/tags.
+
+**taskUpdate** — Update a task's fields:
+\`\`\`
+<discord-action>{"type":"taskUpdate","taskId":"ws-001","status":"in_progress","priority":1}</discord-action>
+\`\`\`
+- \`taskId\` (required): Task ID.
+- \`title\`, \`description\`, \`priority\`, \`status\` (optional): Fields to update.
+
+**taskClose** — Close a task:
+\`\`\`
+<discord-action>{"type":"taskClose","taskId":"ws-001","reason":"Done"}</discord-action>
+\`\`\`
+
+**taskShow** — Show task details:
+\`\`\`
+<discord-action>{"type":"taskShow","taskId":"ws-001"}</discord-action>
+\`\`\`
+
+**taskList** — List tasks:
+\`\`\`
+<discord-action>{"type":"taskList","status":"open","limit":10}</discord-action>
+\`\`\`
+- \`status\` (optional): Filter by status (open, in_progress, blocked, closed, all).
+- \`label\` (optional): Filter by label.
+- \`limit\` (optional): Max results.
+
+**taskSync** — Run full sync between local task store and Discord threads:
+\`\`\`
+<discord-action>{"type":"taskSync"}</discord-action>
+\`\`\`
+
+**tagMapReload** — Reload tag map from disk (hot-reload without restart):
+\`\`\`
+<discord-action>{"type":"tagMapReload"}</discord-action>
+\`\`\`
+
+#### Task Quality Guidelines
+- **Title**: imperative mood, specific, <60 chars. Good: "Add retry logic to webhook handler", "Plan March Denver trip". Bad: "fix stuff".
+- **Description** should answer what/why/scope. Use markdown for structure. Include what "done" looks like for larger tasks. Max 1900 characters — the system will reject longer descriptions with an error.
+- **Priority**: P0=urgent, P1=important, P2=normal (default), P3=nice-to-have, P4=someday.
+- If the user explicitly asks to create a task, always create it.
+- Apply the same description quality standards when using taskUpdate to backfill details.
+
+#### Cross-Task References
+When interacting with another task, always use task actions with its task ID, not channel-name based messaging actions:
+- **Read task content**: \`taskShow <id>\`
+- **Update a task**: \`taskUpdate <id>\`
+- **Close a task**: \`taskClose <id>\`
+- **Find tasks**: \`taskList\` (filter by status or label)
+- **Reconcile Discord threads**: \`taskSync\``;
+}

package/dist/tasks/task-action-read-ops.js

@@ -0,0 +1,73 @@
+import { runTaskSync } from './task-sync.js';
+import { reloadTagMapInPlace } from './tag-map.js';
+function resolveTaskId(action) {
+    return (action.taskId ?? '').trim();
+}
+export async function handleTaskShow(action, _ctx, taskCtx) {
+    const taskId = resolveTaskId(action);
+    if (!taskId) {
+        return { ok: false, error: 'taskShow requires taskId' };
+    }
+    const task = taskCtx.store.get(taskId);
+    if (!task) {
+        return { ok: false, error: `Task "${taskId}" not found` };
+    }
+    const lines = [
+        `**${task.title}** (\`${task.id}\`)`,
+        `Status: ${task.status} | Priority: P${task.priority}`,
+    ];
+    if (task.owner)
+        lines.push(`Owner: ${task.owner}`);
+    if (task.labels?.length)
+        lines.push(`Labels: ${task.labels.join(', ')}`);
+    if (task.description)
+        lines.push(`\n${task.description.slice(0, 500)}`);
+    return { ok: true, summary: lines.join('\n') };
+}
+export async function handleTaskList(action, _ctx, taskCtx) {
+    const tasks = taskCtx.store.list({
+        status: action.status,
+        label: action.label,
+        limit: action.limit ?? 50,
+    });
+    if (tasks.length === 0) {
+        return { ok: true, summary: 'No tasks found matching the filter.' };
+    }
+    const lines = tasks.map((t) => `\`${t.id}\` [${t.status}] P${t.priority} — ${t.title}`);
+    return { ok: true, summary: lines.join('\n') };
+}
+export async function handleTaskSync(_action, ctx, taskCtx) {
+    try {
+        const result = await runTaskSync(taskCtx, { client: ctx.client, guild: ctx.guild }, taskCtx.statusPoster);
+        if (!result) {
+            return { ok: true, summary: 'Sync already running; changes will be picked up.' };
+        }
+        return {
+            ok: true,
+            summary: `Sync complete: ${result.threadsCreated} created, ${result.emojisUpdated} updated, ${result.starterMessagesUpdated} starters, ${result.tagsUpdated} tags, ${result.threadsArchived} archived, ${result.statusesUpdated} status-fixes${result.threadsReconciled ? `, ${result.threadsReconciled} reconciled` : ''}${result.orphanThreadsFound ? `, ${result.orphanThreadsFound} orphans` : ''}${result.warnings ? `, ${result.warnings} warnings` : ''}`,
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `Task sync failed: ${msg}` };
+    }
+}
+export async function handleTagMapReload(_action, _ctx, taskCtx) {
+    if (!taskCtx.tagMapPath) {
+        return { ok: false, error: 'Tag map path not configured' };
+    }
+    const oldCount = Object.keys(taskCtx.tagMap).length;
+    try {
+        await reloadTagMapInPlace(taskCtx.tagMapPath, taskCtx.tagMap);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `Tag map reload failed: ${msg}` };
+    }
+    const newCount = Object.keys(taskCtx.tagMap).length;
+    const tagList = Object.keys(taskCtx.tagMap);
+    const tagsDisplay = tagList.length <= 10
+        ? tagList.join(', ')
+        : `${tagList.slice(0, 10).join(', ')} (+${tagList.length - 10} more)`;
+    return { ok: true, summary: `Tag map reloaded (${oldCount} -> ${newCount}): ${tagsDisplay}` };
+}

package/dist/tasks/task-action-runner-types.js

@@ -0,0 +1 @@
+export {};

package/dist/tasks/task-action-thread-sync.js

@@ -0,0 +1,82 @@
+import { shouldActionUseDirectThreadLifecycle } from './sync-contract.js';
+import { closeTaskThread, createTaskThread, ensureUnarchived, findExistingThreadForTask, resolveTasksForum, updateTaskStarterMessage, updateTaskThreadName, updateTaskThreadTags, } from './thread-ops.js';
+import { getThreadIdFromTask } from './thread-helpers.js';
+export async function ensureCreatedTaskThreadLink(opts) {
+    if (!shouldActionUseDirectThreadLifecycle(opts.actionType)) {
+        return { threadId: '', needsRepairSync: false };
+    }
+    const latest = opts.taskCtx.store.get(opts.task.id) ?? opts.task;
+    const currentThreadId = getThreadIdFromTask(latest);
+    if (currentThreadId) {
+        return { threadId: currentThreadId, needsRepairSync: false };
+    }
+    if (opts.labels.includes('no-thread') || (latest.labels ?? []).includes('no-thread')) {
+        return { threadId: '', needsRepairSync: false };
+    }
+    try {
+        const forum = await resolveTasksForum(opts.runCtx.guild, opts.taskCtx.forumId);
+        if (!forum)
+            return { threadId: '', needsRepairSync: false };
+        const existing = await findExistingThreadForTask(forum, opts.task.id);
+        const threadId = existing ?? await createTaskThread(forum, { ...latest, labels: opts.labels }, opts.taskCtx.tagMap, opts.taskCtx.mentionUserId);
+        try {
+            const newest = opts.taskCtx.store.get(opts.task.id) ?? opts.task;
+            const newestThreadId = getThreadIdFromTask(newest);
+            if (newestThreadId !== threadId) {
+                opts.taskService.update(opts.task.id, { externalRef: `discord:${threadId}` });
+            }
+        }
+        catch (err) {
+            opts.taskCtx.log?.warn({ err, taskId: opts.task.id, threadId }, 'tasks:external-ref update failed');
+        }
+        return { threadId, needsRepairSync: false };
+    }
+    catch (err) {
+        opts.taskCtx.log?.warn({ err, taskId: opts.task.id }, 'tasks:thread creation failed');
+        return { threadId: '', needsRepairSync: true };
+    }
+}
+export async function syncUpdatedTaskThread(opts) {
+    const threadId = getThreadIdFromTask(opts.updatedTask);
+    if (!threadId || !shouldActionUseDirectThreadLifecycle(opts.actionType)) {
+        return false;
+    }
+    let needsRepairSync = false;
+    try {
+        await ensureUnarchived(opts.runCtx.client, threadId);
+        await updateTaskThreadName(opts.runCtx.client, threadId, opts.updatedTask);
+    }
+    catch (err) {
+        needsRepairSync = true;
+        opts.taskCtx.log?.warn({ err, taskId: opts.taskId, threadId }, 'tasks:thread name update failed');
+    }
+    try {
+        await updateTaskStarterMessage(opts.runCtx.client, threadId, opts.updatedTask, opts.taskCtx.sidebarMentionUserId);
+    }
+    catch (err) {
+        needsRepairSync = true;
+        opts.taskCtx.log?.warn({ err, taskId: opts.taskId, threadId }, 'tasks:starter message update failed');
+    }
+    try {
+        await updateTaskThreadTags(opts.runCtx.client, threadId, opts.updatedTask, opts.taskCtx.tagMap);
+    }
+    catch (err) {
+        needsRepairSync = true;
+        opts.taskCtx.log?.warn({ err, taskId: opts.taskId, threadId }, 'tasks:thread tag update failed');
+    }
+    return needsRepairSync;
+}
+export async function syncClosedTaskThread(opts) {
+    const threadId = getThreadIdFromTask(opts.closedTask);
+    if (!threadId || !shouldActionUseDirectThreadLifecycle(opts.actionType)) {
+        return false;
+    }
+    try {
+        await closeTaskThread(opts.runCtx.client, threadId, opts.closedTask, opts.taskCtx.tagMap, opts.taskCtx.log);
+        return false;
+    }
+    catch (err) {
+        opts.taskCtx.log?.warn({ err, taskId: opts.taskId, threadId }, 'tasks:thread close failed');
+        return true;
+    }
+}

package/dist/tasks/task-actions.js

@@ -0,0 +1,3 @@
+export { executeTaskAction } from './task-action-executor.js';
+export { TASK_ACTION_TYPES, isTaskActionRequest, isTaskActionType } from './task-action-contract.js';
+export { taskActionsPromptSection } from './task-action-prompt.js';

package/dist/tasks/task-cli.js

@@ -0,0 +1,227 @@
+import { TaskStore } from './store.js';
+import { createTaskService } from './service.js';
+import { isTaskStatus } from './types.js';
+import { resolveTaskDataLoadPath, resolveTaskDataPath } from './path-defaults.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function envOpt(name) {
+    const v = (process.env[name] ?? '').trim();
+    return v || undefined;
+}
+/**
+ * Extract the value for a named flag from an args array.
+ * Supports both `--flag value` and `--flag=value` forms.
+ */
+function argValue(args, ...flags) {
+    for (const flag of flags) {
+        // --flag value
+        const idx = args.indexOf(flag);
+        if (idx >= 0 && idx + 1 < args.length)
+            return args[idx + 1];
+        // --flag=value
+        const prefix = `${flag}=`;
+        const hit = args.find((a) => a.startsWith(prefix));
+        if (hit)
+            return hit.slice(prefix.length);
+    }
+    return undefined;
+}
+function hasFlag(args, ...flags) {
+    return flags.some((f) => args.includes(f));
+}
+/** Return non-flag positional arguments (args that don't start with `-`). */
+function positional(args) {
+    const result = [];
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a.startsWith('-')) {
+            // Skip the next arg if this is a value-bearing flag.
+            if (!a.includes('=') && i + 1 < args.length && !args[i + 1].startsWith('-')) {
+                i++;
+            }
+        }
+        else {
+            result.push(a);
+        }
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Store factory
+// ---------------------------------------------------------------------------
+async function getStore() {
+    const explicitPath = envOpt('DISCOCLAW_TASKS_PATH');
+    const dataDir = envOpt('DISCOCLAW_DATA_DIR');
+    const tasksPath = explicitPath
+        ?? await resolveTaskDataLoadPath(dataDir, 'tasks.jsonl')
+        ?? resolveTaskDataPath(dataDir, 'tasks.jsonl');
+    if (!tasksPath) {
+        throw new Error('DISCOCLAW_TASKS_PATH or DISCOCLAW_DATA_DIR is required');
+    }
+    const store = new TaskStore({ persistPath: tasksPath });
+    await store.load();
+    return store;
+}
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+async function main() {
+    const args = process.argv.slice(2);
+    const subcommand = args[0];
+    if (!subcommand || subcommand === '--help' || subcommand === '-h') {
+        process.stdout.write([
+            'Usage: task-cli <subcommand> [args]',
+            '',
+            'Subcommands:',
+            '  create <title> [--description <d>] [--priority <n>] [--type <t>]',
+            '                 [--owner <o>] [--assignee <o>] [--labels <l1,l2>]',
+            '  quick  <title>                       — create and output only the ID',
+            '  get    <id>                          — show a single task as a JSON array',
+            '  list   [--status <s>] [--label <l>] [--limit <n>] [--all]',
+            '  update <id> [--title <t>] [--description <d>] [--priority <n>]',
+            '              [--status <s>] [--owner <o>] [--assignee <o>] [--external-ref <r>]',
+            '  close  <id> [--reason <r>]',
+            '  label-add <id> <label>',
+            '',
+            'Env vars: DISCOCLAW_TASKS_PATH, DISCOCLAW_DATA_DIR',
+        ].join('\n') + '\n');
+        process.exit(0);
+    }
+    const rest = args.slice(1);
+    switch (subcommand) {
+        case 'create': {
+            const pos = positional(rest);
+            const title = pos[0];
+            if (!title)
+                throw new Error('create requires a title');
+            const description = argValue(rest, '--description', '-d');
+            const priorityStr = argValue(rest, '--priority', '-p');
+            const issueType = argValue(rest, '--type', '-t');
+            const owner = argValue(rest, '--owner', '--assignee');
+            const labelsStr = argValue(rest, '--labels');
+            const labels = labelsStr
+                ? labelsStr.split(',').map((l) => l.trim()).filter(Boolean)
+                : undefined;
+            const priority = priorityStr != null ? Number(priorityStr) : undefined;
+            const store = await getStore();
+            const taskService = createTaskService(store);
+            const task = taskService.create({
+                title,
+                ...(description !== undefined && { description }),
+                ...(priority != null && Number.isFinite(priority) && { priority }),
+                ...(issueType !== undefined && { issueType }),
+                ...(owner !== undefined && { owner }),
+                ...(labels?.length && { labels }),
+            });
+            await store.flush();
+            process.stdout.write(JSON.stringify(task) + '\n');
+            break;
+        }
+        case 'quick': {
+            const title = rest[0];
+            if (!title || title.startsWith('-'))
+                throw new Error('quick requires a title');
+            const store = await getStore();
+            const taskService = createTaskService(store);
+            const task = taskService.create({ title });
+            await store.flush();
+            process.stdout.write(task.id + '\n');
+            break;
+        }
+        case 'get':
+        case 'show': {
+            const id = rest[0];
+            if (!id)
+                throw new Error(`${subcommand} requires an id`);
+            const store = await getStore();
+            const task = store.get(id);
+            if (!task) {
+                process.stderr.write(`not found: ${id}\n`);
+                process.exit(1);
+            }
+            // Output as a JSON array to match the shape of bdShow / bd show --json.
+            process.stdout.write(JSON.stringify([task]) + '\n');
+            break;
+        }
+        case 'list': {
+            const status = argValue(rest, '--status', '-s');
+            const label = argValue(rest, '--label');
+            const limitStr = argValue(rest, '--limit');
+            const limit = limitStr != null ? Number(limitStr) : undefined;
+            const all = hasFlag(rest, '--all');
+            const store = await getStore();
+            const tasks = store.list({
+                status: all ? 'all' : (status ?? undefined),
+                label: label ?? undefined,
+                limit: limit != null && Number.isFinite(limit) ? limit : undefined,
+            });
+            process.stdout.write(JSON.stringify(tasks) + '\n');
+            break;
+        }
+        case 'update': {
+            const pos = positional(rest);
+            const id = pos[0];
+            if (!id)
+                throw new Error('update requires an id');
+            const title = argValue(rest, '--title');
+            const description = argValue(rest, '--description', '-d');
+            const priorityStr = argValue(rest, '--priority', '-p');
+            const status = argValue(rest, '--status', '-s');
+            const owner = argValue(rest, '--owner', '--assignee');
+            const externalRef = argValue(rest, '--external-ref');
+            const priority = priorityStr != null ? Number(priorityStr) : undefined;
+            if (status && !isTaskStatus(status)) {
+                throw new Error(`invalid status: ${status}. Must be one of: open, in_progress, blocked, closed`);
+            }
+            const validStatus = status && isTaskStatus(status) ? status : undefined;
+            const store = await getStore();
+            const taskService = createTaskService(store);
+            taskService.update(id, {
+                ...(title !== undefined && { title }),
+                ...(description !== undefined && { description }),
+                ...(priority != null && Number.isFinite(priority) && { priority }),
+                ...(validStatus !== undefined && { status: validStatus }),
+                ...(owner !== undefined && { owner }),
+                ...(externalRef !== undefined && { externalRef }),
+            });
+            await store.flush();
+            process.stdout.write(JSON.stringify(store.get(id)) + '\n');
+            break;
+        }
+        case 'close': {
+            const pos = positional(rest);
+            const id = pos[0];
+            if (!id)
+                throw new Error('close requires an id');
+            const reason = argValue(rest, '--reason', '-r');
+            const store = await getStore();
+            const taskService = createTaskService(store);
+            taskService.close(id, reason ?? undefined);
+            await store.flush();
+            process.stdout.write(JSON.stringify(store.get(id)) + '\n');
+            break;
+        }
+        case 'label-add': {
+            const id = rest[0];
+            const label = rest[1];
+            if (!id || !label)
+                throw new Error('label-add requires an id and a label');
+            const store = await getStore();
+            const taskService = createTaskService(store);
+            taskService.addLabel(id, label);
+            await store.flush();
+            process.stdout.write(JSON.stringify(store.get(id)) + '\n');
+            break;
+        }
+        default:
+            throw new Error(`unknown subcommand: ${subcommand}`);
+    }
+}
+// Only execute when invoked directly as a script, not when imported as a module.
+if (import.meta.url === new URL(process.argv[1] ?? '', 'file:').href) {
+    await main().catch((err) => {
+        process.stderr.write((err instanceof Error ? err.message : String(err)) + '\n');
+        process.exit(1);
+    });
+}

package/dist/tasks/task-context.js

@@ -0,0 +1 @@
+export {};

package/dist/tasks/task-lifecycle.js

@@ -0,0 +1,46 @@
+/**
+ * Per-task lifecycle lock and ownership markers used to coordinate direct
+ * action-owned thread operations with background sync passes.
+ */
+const TASK_LIFECYCLE_TAILS = new Map();
+const DIRECT_TASK_LIFECYCLE_ACTIVE = new Set();
+/**
+ * Serialize lifecycle work for a specific task ID.
+ */
+export async function withTaskLifecycleLock(taskId, work) {
+    const previousTail = TASK_LIFECYCLE_TAILS.get(taskId) ?? Promise.resolve();
+    let releaseCurrent;
+    const currentSignal = new Promise((resolve) => {
+        releaseCurrent = resolve;
+    });
+    const currentTail = previousTail.then(() => currentSignal);
+    TASK_LIFECYCLE_TAILS.set(taskId, currentTail);
+    await previousTail;
+    try {
+        return await work();
+    }
+    finally {
+        releaseCurrent();
+        if (TASK_LIFECYCLE_TAILS.get(taskId) === currentTail) {
+            TASK_LIFECYCLE_TAILS.delete(taskId);
+        }
+    }
+}
+/**
+ * Mark a task as direct-action-owned while its lifecycle work is running.
+ * This is used by store-event wiring to avoid duplicate sync ownership.
+ */
+export async function withDirectTaskLifecycle(taskId, work) {
+    return withTaskLifecycleLock(taskId, async () => {
+        DIRECT_TASK_LIFECYCLE_ACTIVE.add(taskId);
+        try {
+            return await work();
+        }
+        finally {
+            DIRECT_TASK_LIFECYCLE_ACTIVE.delete(taskId);
+        }
+    });
+}
+export function isDirectTaskLifecycleActive(taskId) {
+    return DIRECT_TASK_LIFECYCLE_ACTIVE.has(taskId);
+}