@mclawnet/mcp-server 0.1.3 → 0.1.4

package/dist/tools/task.js

@@ -0,0 +1,823 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { createLogger } from "@mclawnet/logger";
+import { TaskStore, classifyBlockers, computeLeadBriefing, computeMemberBriefing, computeTaskBriefing, formatLeadBriefing, formatMemberBriefing, formatTaskBriefing, projectRoot, } from "@mclawnet/task";
+import { InboxStore } from "@mclawnet/swarm";
+const log = createLogger({ module: "mcp-server/tools/task" });
+export const TASK_TOOL_NAMES = new Set([
+    "task_create",
+    "task_create_from_message",
+    "task_get",
+    "task_list",
+    "task_set_status",
+    "task_set_owner",
+    "task_add_comment",
+    "task_link",
+    "task_unlink",
+    "task_briefing",
+    "lead_briefing",
+    "member_briefing",
+]);
+const VALID_STATUSES = new Set(["pending", "in_progress", "completed", "cancelled"]);
+function parseBriefingFormat(args) {
+    const raw = args.format;
+    if (raw === undefined || raw === null)
+        return "json";
+    if (raw !== "json" && raw !== "markdown") {
+        throw new Error(`invalid format: ${String(raw)} (expected "json" | "markdown")`);
+    }
+    return raw;
+}
+export function getTaskToolDefinitions() {
+    return [
+        {
+            name: "task_create",
+            description: "Create a new task in the project task store. Returns the created task JSON. Restricted to queen instances: caller must pass `from` starting with 'queen-'.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    workDir: { type: "string", description: "Absolute path of the project working directory" },
+                    teamName: { type: "string", description: "Team name owning this task" },
+                    subject: { type: "string", description: "Short task subject/title" },
+                    description: { type: "string", description: "Optional longer description" },
+                    swarmId: { type: "string", description: "Swarm id (optional)" },
+                    owner: { type: "string", description: "Owner agent instance id (optional)" },
+                    from: { type: "string", description: "Caller instance id; must start with 'queen-'" },
+                    blockedBy: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Task ids this task is blocked by (optional)",
+                    },
+                },
+                required: ["workDir", "teamName", "subject", "from"],
+            },
+        },
+        {
+            name: "task_create_from_message",
+            description: "Create a new task derived from an inbox message. Adds a system 'origin_message' comment recording the source message id and instance. Restricted to queen instances: caller must pass `from` starting with 'queen-'.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    workDir: { type: "string", description: "Absolute path of the project working directory" },
+                    teamName: { type: "string", description: "Team name owning this task" },
+                    subject: { type: "string", description: "Short task subject/title" },
+                    description: { type: "string", description: "Optional longer description" },
+                    swarmId: { type: "string", description: "Swarm id (optional)" },
+                    owner: { type: "string", description: "Owner agent instance id (optional)" },
+                    from: { type: "string", description: "Caller instance id; must start with 'queen-'" },
+                    blockedBy: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Task ids this task is blocked by (optional)",
+                    },
+                    sourceMessageId: { type: "string", description: "Inbox message id this task is spun off from" },
+                    sourceInstanceId: { type: "string", description: "Instance id that owned the source message" },
+                },
+                required: ["workDir", "teamName", "subject", "sourceMessageId", "sourceInstanceId", "from"],
+            },
+        },
+        {
+            name: "task_get",
+            description: "Fetch a task by id from the project task store.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    workDir: { type: "string", description: "Absolute path of the project working directory" },
+                    taskId: { type: "string", description: "Task id" },
+                },
+                required: ["workDir", "taskId"],
+            },
+        },
+        {
+            name: "task_list",
+            description: "List tasks from the project task store. Optional filters: swarmId, status, owner.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    workDir: { type: "string", description: "Absolute path of the project working directory" },
+                    swarmId: { type: "string", description: "Filter by swarm id (optional)" },
+                    status: { type: "string", description: "Filter by status (optional)" },
+                    owner: { type: "string", description: "Filter by owner agent instance id (optional)" },
+                },
+                required: ["workDir"],
+            },
+        },
+        {
+            name: "task_set_status",
+            description: "Set the status of a task. When status becomes 'cancelled', the task is unlinked from any tasks it was blocking.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    workDir: { type: "string", description: "Absolute path of the project working directory" },
+                    taskId: { type: "string", description: "Task id" },
+                    status: {
+                        type: "string",
+                        enum: ["pending", "in_progress", "completed", "cancelled"],
+                        description: "New status",
+                    },
+                },
+                required: ["workDir", "taskId", "status"],
+            },
+        },
+        {
+            name: "task_set_owner",
+            description: "Set (or clear, by passing null) the owner of a task. Restricted to queen instances: caller must pass `from` starting with 'queen-'.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    workDir: { type: "string", description: "Absolute path of the project working directory" },
+                    taskId: { type: "string", description: "Task id" },
+                    owner: {
+                        type: ["string", "null"],
+                        description: "New owner agent instance id, or null to clear",
+                    },
+                    from: { type: "string", description: "Caller instance id; must start with 'queen-'" },
+                },
+                required: ["workDir", "taskId", "owner", "from"],
+            },
+        },
+        {
+            name: "task_add_comment",
+            description: "Append a comment to a task. Idempotent on the comment id; if id is omitted a UUID is generated.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    workDir: { type: "string", description: "Absolute path of the project working directory" },
+                    taskId: { type: "string", description: "Task id" },
+                    author: { type: "string", description: "Author identifier (agent or user)" },
+                    body: { type: "string", description: "Comment body" },
+                    type: { type: "string", description: "Optional comment type (default: 'note')" },
+                    id: { type: "string", description: "Optional comment id (auto-generated UUID if omitted)" },
+                },
+                required: ["workDir", "taskId", "author", "body"],
+            },
+        },
+        {
+            name: "task_link",
+            description: "Add a dependency edge: fromTask is blocked by toTask, and toTask blocks fromTask. Rejects self-link, cycles, and missing tasks.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    workDir: { type: "string", description: "Absolute path of the project working directory" },
+                    fromTaskId: { type: "string", description: "Task that becomes blocked" },
+                    toTaskId: { type: "string", description: "Task it depends on" },
+                },
+                required: ["workDir", "fromTaskId", "toTaskId"],
+            },
+        },
+        {
+            name: "task_unlink",
+            description: "Remove a dependency edge between fromTask and toTask in both directions. No-op if the edge does not exist.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    workDir: { type: "string", description: "Absolute path of the project working directory" },
+                    fromTaskId: { type: "string", description: "Task that was blocked" },
+                    toTaskId: { type: "string", description: "Task it depended on" },
+                },
+                required: ["workDir", "fromTaskId", "toTaskId"],
+            },
+        },
+        {
+            name: "task_briefing",
+            description: "Summarise an instance's task situation within a swarm: actionable (owned, unblocked, pending/in_progress), awareness (owned, with waiting deps), counters and warnings (broken deps, orphaned in_progress).",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    workDir: { type: "string", description: "Absolute path of the project working directory" },
+                    swarmId: { type: "string", description: "Swarm id to scope the briefing" },
+                    instanceId: { type: "string", description: "Instance id to focus the briefing on" },
+                    format: {
+                        type: "string",
+                        enum: ["json", "markdown"],
+                        description: "Response format. Default 'json'.",
+                        default: "json",
+                    },
+                },
+                required: ["workDir", "swarmId", "instanceId"],
+            },
+        },
+        {
+            name: "lead_briefing",
+            description: "Queen-facing situation summary for a swarm. Returns five buckets: assign_owner (pending && owner=null), assign_reviewer (always empty in Phase 1 — no reviewer field yet), clarify (tasks whose latest comment body contains '?'), repair_dependencies (tasks with broken/cancelled deps), lead_owned (tasks owned by the queen instance resolved from recovery.json).",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    workDir: { type: "string", description: "Absolute path of the project working directory" },
+                    swarmId: { type: "string", description: "Swarm id to scope the briefing" },
+                    format: {
+                        type: "string",
+                        enum: ["json", "markdown"],
+                        description: "Response format. Default 'json'.",
+                        default: "json",
+                    },
+                },
+                required: ["workDir", "swarmId"],
+            },
+        },
+        {
+            name: "member_briefing",
+            description: "Worker/queen boot briefing. Returns a hardcoded list of 4-6 boot rules (slightly different for queen vs. worker) plus a bootstrap object echoing { swarmId, instanceId, roleType }.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    workDir: { type: "string", description: "Absolute path of the project working directory" },
+                    swarmId: { type: "string", description: "Swarm id" },
+                    instanceId: { type: "string", description: "Instance id of the booting agent" },
+                    roleType: { type: "string", description: "Role type, e.g. 'queen' or 'worker'" },
+                    format: {
+                        type: "string",
+                        enum: ["json", "markdown"],
+                        description: "Response format. Default 'json'.",
+                        default: "json",
+                    },
+                },
+                required: ["workDir", "swarmId", "instanceId", "roleType"],
+            },
+        },
+    ];
+}
+export async function handleTaskToolCall(name, args, context) {
+    try {
+        log.info({ tool: name }, "MCP task tool called");
+        switch (name) {
+            case "task_create":
+                return await handleTaskCreate(args, context);
+            case "task_create_from_message":
+                return await handleTaskCreateFromMessage(args, context);
+            case "task_get":
+                return await handleTaskGet(args, context);
+            case "task_list":
+                return await handleTaskList(args, context);
+            case "task_set_status":
+                return await handleTaskSetStatus(args, context);
+            case "task_set_owner":
+                return await handleTaskSetOwner(args, context);
+            case "task_add_comment":
+                return await handleTaskAddComment(args, context);
+            case "task_link":
+                return await handleTaskLink(args, context);
+            case "task_unlink":
+                return await handleTaskUnlink(args, context);
+            case "task_briefing":
+                return await handleTaskBriefing(args, context);
+            case "lead_briefing":
+                return await handleLeadBriefing(args, context);
+            case "member_briefing":
+                return await handleMemberBriefing(args, context);
+            default:
+                return {
+                    content: [{ type: "text", text: JSON.stringify({ error: `Unknown tool: ${name}` }) }],
+                    isError: true,
+                };
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        log.error({ tool: name, err }, "MCP task tool error");
+        return {
+            content: [{ type: "text", text: JSON.stringify({ error: message }) }],
+            isError: true,
+        };
+    }
+}
+/**
+ * Defense-in-depth ("防君子"): task mutation tools that should only be invoked
+ * by a queen/lead instance call this guard first. The harness already blocks
+ * non-queen workers via `--disallowedTools`, but this is a second layer in
+ * case a worker spawns its own MCP client or the policy is misconfigured.
+ *
+ * Caller identity is taken from `args.from` (free-form string the caller
+ * supplies, same convention as inbox_message_send). A queen instance id
+ * always starts with the literal prefix "queen-" (see role instanceId minting
+ * in @mclawnet/swarm). Empty / non-string / non-queen values are rejected.
+ */
+function assertQueenCaller(args, toolName) {
+    const from = args.from;
+    if (typeof from !== "string" || !from.startsWith("queen-")) {
+        throw new Error(`Only queen instances may call ${toolName}`);
+    }
+}
+function getStore(args, context) {
+    const workDir = args.workDir;
+    if (!workDir)
+        throw new Error("workDir is required");
+    return new TaskStore({ workDir, home: context.rootDir });
+}
+async function handleTaskCreate(args, context) {
+    assertQueenCaller(args, "task_create");
+    const teamName = args.teamName;
+    const subject = args.subject;
+    if (!teamName)
+        throw new Error("teamName is required");
+    if (!subject)
+        throw new Error("subject is required");
+    const store = getStore(args, context);
+    const task = await store.create({
+        teamName,
+        subject,
+        description: args.description,
+        swarmId: args.swarmId ?? null,
+        owner: args.owner ?? null,
+        blockedBy: args.blockedBy ?? [],
+    });
+    if (task.swarmId && task.owner) {
+        const msg = {
+            id: `assigned-${task.id}`,
+            from: "system",
+            type: "task_assigned",
+            data: JSON.stringify({
+                taskId: task.id,
+                subject: task.subject,
+                description: task.description,
+            }),
+            taskId: task.id,
+            timestamp: Date.now(),
+            delivered: false,
+        };
+        await appendInboxBestEffort(args.workDir, task.swarmId, task.owner, msg, context);
+    }
+    return {
+        content: [{ type: "text", text: JSON.stringify(task) }],
+    };
+}
+async function handleTaskCreateFromMessage(args, context) {
+    assertQueenCaller(args, "task_create_from_message");
+    const teamName = args.teamName;
+    const subject = args.subject;
+    const sourceMessageId = args.sourceMessageId;
+    const sourceInstanceId = args.sourceInstanceId;
+    if (!teamName)
+        throw new Error("teamName is required");
+    if (!subject)
+        throw new Error("subject is required");
+    if (!sourceMessageId)
+        throw new Error("sourceMessageId is required");
+    if (!sourceInstanceId)
+        throw new Error("sourceInstanceId is required");
+    const store = getStore(args, context);
+    const task = await store.create({
+        teamName,
+        subject,
+        description: args.description,
+        swarmId: args.swarmId ?? null,
+        owner: args.owner ?? null,
+        blockedBy: args.blockedBy ?? [],
+    });
+    await store.addComment(task.id, {
+        id: randomUUID(),
+        author: "system",
+        type: "origin_message",
+        body: `Spun off from message ${sourceMessageId} (instance ${sourceInstanceId})`,
+    });
+    const fresh = store.get(task.id);
+    return {
+        content: [{ type: "text", text: JSON.stringify(fresh) }],
+    };
+}
+async function handleTaskGet(args, context) {
+    const taskId = args.taskId;
+    if (!taskId)
+        throw new Error("taskId is required");
+    const store = getStore(args, context);
+    const task = store.get(taskId);
+    return {
+        content: [{ type: "text", text: JSON.stringify(task) }],
+    };
+}
+async function handleTaskList(args, context) {
+    const store = getStore(args, context);
+    const swarmId = args.swarmId;
+    const status = args.status;
+    const owner = args.owner;
+    // store.list() returns lightweight IndexEntry[]; load full Task objects so callers
+    // get the same shape as task_get.
+    const entries = store.list();
+    const tasks = entries
+        .map(e => store.tryGet(e.id))
+        .filter((t) => t !== null)
+        .filter(t => (swarmId === undefined ? true : t.swarmId === swarmId))
+        .filter(t => (status === undefined ? true : t.status === status))
+        .filter(t => (owner === undefined ? true : t.owner === owner));
+    return {
+        content: [{ type: "text", text: JSON.stringify({ tasks }) }],
+    };
+}
+async function handleTaskSetStatus(args, context) {
+    const taskId = args.taskId;
+    const status = args.status;
+    if (!taskId)
+        throw new Error("taskId is required");
+    if (!status)
+        throw new Error("status is required");
+    if (!VALID_STATUSES.has(status)) {
+        throw new Error(`invalid status: ${status}`);
+    }
+    const store = getStore(args, context);
+    // Will throw "Task not found" if missing — surfaced as isError by the wrapper.
+    const current = store.get(taskId);
+    // Dependency contract: refuse to transition *into* in_progress when any
+    // blockedBy dep is not completed. Briefings already filter blocked tasks
+    // out of `actionable`, but workers/queens can call this tool directly, so
+    // the server must enforce the contract too. Same-state writes (already
+    // in_progress) are not transitions and remain allowed for idempotency.
+    if (status === "in_progress" && current.status !== "in_progress") {
+        const cls = classifyBlockers(current, store);
+        if (cls.isBlocked) {
+            throw new Error(`task is blocked by unresolved dependencies — waiting=[${cls.waiting.join(", ")}] broken=[${cls.broken.join(", ")}]`);
+        }
+    }
+    const updated = await store.update(taskId, { status: status });
+    if (status === "cancelled") {
+        // Per design §5.2: a cancelled task should no longer block its dependents.
+        // We unlink each (self -> dep) edge using the existing store API so both
+        // sides of the edge stay consistent (self.blockedBy and dep.blocks).
+        for (const depId of [...current.blockedBy]) {
+            await store.unlink(taskId, depId);
+        }
+    }
+    if (current.swarmId) {
+        const queenId = resolveQueenInstanceId(args.workDir, current.swarmId, context.inbox?.rootDir ?? context.rootDir);
+        if (queenId && !(queenId === current.owner && status === "in_progress")) {
+            const msg = {
+                id: `status-${taskId}-${status}`,
+                from: "system",
+                type: "task_status_changed",
+                data: JSON.stringify({
+                    taskId,
+                    status,
+                    owner: current.owner,
+                    subject: current.subject,
+                }),
+                taskId,
+                timestamp: Date.now(),
+                delivered: false,
+            };
+            await appendInboxBestEffort(args.workDir, current.swarmId, queenId, msg, context);
+        }
+    }
+    // Task 6: when transitioning *into* completed (i.e. previous status was not
+    // already completed), fan out dep-resolved comments + unblock inbox messages
+    // to each downstream task. Best-effort: any failure here must not abort the
+    // status change. Stable ids guarantee idempotency on accidental re-fires.
+    if (status === "completed" && current.status !== "completed") {
+        await notifyUnblockedAfterCompletion(store, updated, args, context);
+    }
+    // Re-read to reflect any link cleanup we may have done above.
+    const fresh = store.tryGet(taskId) ?? updated;
+    return {
+        content: [{ type: "text", text: JSON.stringify(fresh) }],
+    };
+}
+async function handleTaskSetOwner(args, context) {
+    assertQueenCaller(args, "task_set_owner");
+    const taskId = args.taskId;
+    if (!taskId)
+        throw new Error("taskId is required");
+    if (!("owner" in args))
+        throw new Error("owner is required (use null to clear)");
+    const ownerRaw = args.owner;
+    if (ownerRaw !== null && typeof ownerRaw !== "string") {
+        throw new Error("owner must be a string or null");
+    }
+    const owner = ownerRaw;
+    const store = getStore(args, context);
+    const current = store.get(taskId);
+    const updated = await store.update(taskId, { owner });
+    if (owner && current.swarmId) {
+        const msg = {
+            id: `owner-${taskId}-${owner}`,
+            from: "system",
+            type: "task_owner_set",
+            data: JSON.stringify({ taskId, owner, subject: current.subject }),
+            taskId,
+            timestamp: Date.now(),
+            delivered: false,
+        };
+        await appendInboxBestEffort(args.workDir, current.swarmId, owner, msg, context);
+    }
+    return {
+        content: [{ type: "text", text: JSON.stringify(updated) }],
+    };
+}
+async function handleTaskAddComment(args, context) {
+    const taskId = args.taskId;
+    const author = args.author;
+    const body = args.body;
+    if (!taskId)
+        throw new Error("taskId is required");
+    if (!author)
+        throw new Error("author is required");
+    if (body === undefined || body === null)
+        throw new Error("body is required");
+    const id = args.id ?? randomUUID();
+    const type = args.type ?? "note";
+    const store = getStore(args, context);
+    // Capture pre-state so we know the owner/swarmId for fanout below; addComment
+    // would also throw "Task not found", so this doubles as an explicit guard.
+    const current = store.get(taskId);
+    await store.addComment(taskId, { id, author, type, body });
+    const fresh = store.get(taskId);
+    // Notify the task's owner and the swarm's queen (best-effort), suppressing
+    // the author so commenters don't notify themselves. Stable id `comment-<id>`
+    // gives per-file dedup across recipients.
+    if (current.swarmId) {
+        const recipients = new Set();
+        if (current.owner && current.owner !== author)
+            recipients.add(current.owner);
+        const queenId = resolveQueenInstanceId(args.workDir, current.swarmId, context.inbox?.rootDir ?? context.rootDir);
+        if (queenId && queenId !== author)
+            recipients.add(queenId);
+        if (recipients.size > 0) {
+            const msg = {
+                id: `comment-${id}`,
+                from: "system",
+                type: "task_comment",
+                data: JSON.stringify({ taskId, commentId: id, author, body, type }),
+                taskId,
+                timestamp: Date.now(),
+                delivered: false,
+            };
+            for (const recipient of recipients) {
+                await appendInboxBestEffort(args.workDir, current.swarmId, recipient, msg, context);
+            }
+        }
+    }
+    return {
+        content: [{ type: "text", text: JSON.stringify({ id, task: fresh }) }],
+    };
+}
+async function handleTaskLink(args, context) {
+    const fromTaskId = args.fromTaskId;
+    const toTaskId = args.toTaskId;
+    if (!fromTaskId)
+        throw new Error("fromTaskId is required");
+    if (!toTaskId)
+        throw new Error("toTaskId is required");
+    if (fromTaskId === toTaskId)
+        throw new Error("cannot link a task to itself");
+    const store = getStore(args, context);
+    await store.link(fromTaskId, toTaskId);
+    const from = store.get(fromTaskId);
+    return {
+        content: [{ type: "text", text: JSON.stringify(from) }],
+    };
+}
+async function handleTaskUnlink(args, context) {
+    const fromTaskId = args.fromTaskId;
+    const toTaskId = args.toTaskId;
+    if (!fromTaskId)
+        throw new Error("fromTaskId is required");
+    if (!toTaskId)
+        throw new Error("toTaskId is required");
+    const store = getStore(args, context);
+    await store.unlink(fromTaskId, toTaskId);
+    const from = store.tryGet(fromTaskId);
+    return {
+        content: [{ type: "text", text: JSON.stringify({ from }) }],
+    };
+}
+/**
+ * task_briefing — produce a per-instance situation summary inside one swarm.
+ *
+ * Simplifications vs. the original Phase 3 plan, due to current Task schema:
+ *   - No `priority` field exists, so actionable is sorted by createdAt asc only
+ *     (the plan specified `priority desc, createdAt asc`).
+ *   - No `reviewer` field exists, so awareness only checks
+ *     `classifyBlockers(t).waiting.length > 0` (the plan also OR'd a reviewer
+ *     match) and the `reviewNeeded` counter is omitted.
+ *   - Warnings cover only broken deps + orphaned in_progress
+ *     (status === "in_progress" && owner === null).
+ */
+async function handleTaskBriefing(args, context) {
+    const swarmId = args.swarmId;
+    const instanceId = args.instanceId;
+    if (!swarmId)
+        throw new Error("swarmId is required");
+    if (!instanceId)
+        throw new Error("instanceId is required");
+    const format = parseBriefingFormat(args);
+    const store = getStore(args, context);
+    const body = computeTaskBriefing(store, swarmId, instanceId);
+    const text = format === "markdown"
+        ? formatTaskBriefing(body, { instanceId })
+        : JSON.stringify(body);
+    return {
+        content: [{ type: "text", text }],
+    };
+}
+/**
+ * Resolve the queen instance id for a swarm by reading the swarm snapshot
+ * (`recovery.json`) from disk. Returns null when the snapshot is missing,
+ * malformed, or contains no queen role. Errors are swallowed: queen routing
+ * is best-effort and never aborts fanout.
+ *
+ * Resolution order:
+ *   1. Prefer `role.type === "queen"` (post P3-3 snapshots) so custom queen
+ *      role names (e.g. "lead", "chief") are still routed correctly.
+ *   2. Fall back to `role.roleName === "queen"` for snapshots written before
+ *      the `type` field was added to `SwarmSnapshot.roles[]`.
+ */
+function resolveQueenInstanceId(workDir, swarmId, rootDir) {
+    try {
+        const snapshotPath = join(projectRoot(workDir, rootDir), "swarms", swarmId, "recovery.json");
+        if (!existsSync(snapshotPath))
+            return null;
+        const snapshot = JSON.parse(readFileSync(snapshotPath, "utf-8"));
+        if (!Array.isArray(snapshot.roles))
+            return null;
+        for (const role of snapshot.roles) {
+            if (role && role.type === "queen" && typeof role.instanceId === "string") {
+                return role.instanceId;
+            }
+        }
+        // Backward compat for snapshots written before `type` was persisted.
+        for (const role of snapshot.roles) {
+            if (role && role.roleName === "queen" && typeof role.instanceId === "string") {
+                return role.instanceId;
+            }
+        }
+        return null;
+    }
+    catch (err) {
+        log.warn({ err, swarmId }, "resolveQueenInstanceId failed");
+        return null;
+    }
+}
+/**
+ * Write an inbox message for a recipient, then best-effort relay.deliver.
+ * All errors are swallowed and logged at warn — callers must never depend
+ * on this for correctness; the underlying task action has already succeeded.
+ */
+async function appendInboxBestEffort(workDir, swarmId, instanceId, msg, context) {
+    try {
+        const inbox = new InboxStore(workDir, swarmId, context.inbox?.rootDir);
+        await inbox.append(instanceId, msg);
+    }
+    catch (err) {
+        log.warn({ err, instanceId, swarmId, msgId: msg.id }, "inbox append failed (best-effort)");
+        return;
+    }
+    if (context.inbox?.relay) {
+        try {
+            await context.inbox.relay.deliver(swarmId, instanceId);
+        }
+        catch (err) {
+            log.warn({ err, instanceId, swarmId, msgId: msg.id }, "inbox relay deliver failed (best-effort)");
+        }
+    }
+}
+/**
+ * Fan out completion notifications to downstream tasks (those listed in
+ * `completed.blocks`). For each downstream:
+ *   1. Append a `dep-resolved-${completedId}-${blockedId}` system comment
+ *      (idempotent via stable id; addComment dedupes).
+ *   2. If `classifyBlockers` reports the downstream is now fully unblocked,
+ *      write an `unblock-${completedId}-${blockedId}` inbox message to the
+ *      downstream owner (when set) AND to the queen instance (when one can
+ *      be resolved from the snapshot). Recipients are deduped via Set.
+ *
+ * Cross-swarm safety: each downstream task uses its OWN swarmId for inbox
+ * routing, not the caller's. Callers should pass `args.workDir` through.
+ *
+ * Best-effort: comment / inbox / relay failures are logged at warn and never
+ * propagate to the caller (the status change has already succeeded).
+ */
+async function notifyUnblockedAfterCompletion(store, completed, args, context) {
+    const workDir = args.workDir;
+    for (const blockedId of completed.blocks) {
+        const blocked = store.tryGet(blockedId);
+        if (!blocked) {
+            log.warn({ completedId: completed.id, blockedId }, "downstream task not found, skip fanout");
+            continue;
+        }
+        // Step 1: dep-resolved comment (idempotent on stable id).
+        const commentId = `dep-resolved-${completed.id}-${blockedId}`;
+        try {
+            await store.addComment(blockedId, {
+                id: commentId,
+                author: "system",
+                type: "dep_resolved",
+                body: `Dependency ${completed.id} is now completed.`,
+            });
+        }
+        catch (err) {
+            log.warn({ err, completedId: completed.id, blockedId }, "addComment fanout failed");
+        }
+        // Step 2: classify and, if fully unblocked, write inbox messages.
+        let isFullyUnblocked = false;
+        try {
+            isFullyUnblocked = !classifyBlockers(blocked, store).isBlocked;
+        }
+        catch (err) {
+            log.warn({ err, blockedId }, "classifyBlockers failed");
+            continue;
+        }
+        if (!isFullyUnblocked)
+            continue;
+        if (!context.inbox) {
+            log.warn({ blockedId }, "inbox context missing, skip unblock message");
+            continue;
+        }
+        if (!blocked.swarmId) {
+            log.warn({ blockedId }, "downstream has no swarmId, skip unblock message");
+            continue;
+        }
+        const recipients = new Set();
+        if (blocked.owner)
+            recipients.add(blocked.owner);
+        const queenId = resolveQueenInstanceId(workDir, blocked.swarmId, context.inbox.rootDir);
+        if (queenId)
+            recipients.add(queenId);
+        if (recipients.size === 0)
+            continue;
+        const messageId = `unblock-${completed.id}-${blockedId}`;
+        const inbox = new InboxStore(workDir, blocked.swarmId, context.inbox?.rootDir);
+        for (const instanceId of recipients) {
+            const msg = {
+                id: messageId,
+                from: "system",
+                type: "task_unblocked",
+                data: JSON.stringify({
+                    taskId: blockedId,
+                    unblockedBy: completed.id,
+                    subject: blocked.subject,
+                }),
+                taskId: blockedId,
+                timestamp: Date.now(),
+                delivered: false,
+            };
+            try {
+                await inbox.append(instanceId, msg);
+            }
+            catch (err) {
+                log.warn({ err, instanceId, blockedId }, "inbox append failed (best-effort)");
+                continue;
+            }
+            if (context.inbox.relay) {
+                try {
+                    await context.inbox.relay.deliver(blocked.swarmId, instanceId);
+                }
+                catch (err) {
+                    log.warn({ err, instanceId, blockedId }, "inbox relay deliver failed (best-effort)");
+                }
+            }
+        }
+    }
+}
+/**
+ * lead_briefing — Queen-facing situation summary for one swarm.
+ *
+ * Phase-1 simplifications (documented inline):
+ *   - `assign_reviewer` is **always** an empty array because the Phase 1
+ *     `Task` schema has no `reviewer` field. Kept in the response shape so
+ *     downstream callers don't need to branch.
+ *   - `clarify` uses a heuristic: a task is bucketed when its most recent
+ *     comment body contains a "?" character. Once a `question`/`resolved`
+ *     comment-type convention exists, this can be tightened.
+ *   - `lead_owned` requires `recovery.json` to expose a `roleName === "queen"`
+ *     entry. When absent (or unparseable), `lead_owned` is silently empty —
+ *     the other buckets still work.
+ */
+async function handleLeadBriefing(args, context) {
+    const workDir = args.workDir;
+    const swarmId = args.swarmId;
+    if (!workDir)
+        throw new Error("workDir is required");
+    if (!swarmId)
+        throw new Error("swarmId is required");
+    const format = parseBriefingFormat(args);
+    const store = getStore(args, context);
+    const queenId = resolveQueenInstanceId(workDir, swarmId, context.rootDir);
+    const body = computeLeadBriefing(store, swarmId, queenId);
+    const text = format === "markdown" ? formatLeadBriefing(body) : JSON.stringify(body);
+    return {
+        content: [{ type: "text", text }],
+    };
+}
+/**
+ * member_briefing — boot-time briefing for a worker (or queen) instance.
+ *
+ * Returns a hardcoded list of 4-6 boot rules plus a `bootstrap` echo of the
+ * caller's identity. Rules are slightly tweaked when `roleType === "queen"`
+ * to reflect lead responsibilities (assigning owners, repairing deps).
+ */
+async function handleMemberBriefing(args, _context) {
+    const swarmId = args.swarmId;
+    const instanceId = args.instanceId;
+    const roleType = args.roleType;
+    if (!swarmId)
+        throw new Error("swarmId is required");
+    if (!instanceId)
+        throw new Error("instanceId is required");
+    if (!roleType)
+        throw new Error("roleType is required");
+    const format = parseBriefingFormat(args);
+    const body = computeMemberBriefing({ swarmId, instanceId, roleType });
+    const text = format === "markdown" ? formatMemberBriefing(body) : JSON.stringify(body);
+    return {
+        content: [{ type: "text", text }],
+    };
+}
+//# sourceMappingURL=task.js.map