@pruddiman/hem 0.0.1-beta-5671db0

package/dist/agents/organization-agent.js

@@ -0,0 +1,607 @@
+/**
+ * LLM-assisted organization agent for Hem.
+ *
+ * Post-processing agent that runs AFTER all doc agents complete.
+ * Reviews all written documentation files, restructures/renames/deduplicates
+ * for consistency.
+ *
+ * Architecture (v3 — parallel workers with broadcast):
+ *   - Absorbs the old DeduplicationAgent's responsibility.
+ *   - For large file sets (>8 files), splits work across N parallel workers.
+ *   - Workers communicate via an MCP broadcast tool + prompt injection.
+ *   - The orchestrator intercepts broadcast tool calls via SSE and relays
+ *     messages to all peer workers + their active subagents.
+ *   - For small file sets (≤8 files), falls back to the single-agent path.
+ *   - The pipeline discovers the final file set by scanning disk afterward.
+ */
+import { AuthExpiredError } from "../auth.js";
+import { BaseAgent } from "./base-agent.js";
+import { ArbiterAgent } from "./arbiter-agent.js";
+import { computeOrgWorkers } from "../resources.js";
+import { DecisionQueue, parseDecision, } from "../decision-queue.js";
+// ── Constants ───────────────────────────────────────────────────────────
+/** File count threshold: use parallel workers above this, single agent below. */
+export const PARALLEL_THRESHOLD = 8;
+/**
+ * Hard ceiling on parallel org workers.  The actual worker count is
+ * `min(MAX_WORKERS, computeOrgWorkers(fileCount), computeMaxConcurrency())`.
+ * The arbiter is excluded from this cap (it is lightweight).
+ */
+export const MAX_WORKERS = 7;
+/**
+ * MCP tool name as it appears in SSE events.
+ * Format: "{mcp-server-name}_{tool-name}"
+ */
+export const BROADCAST_TOOL_NAME = "hem-broadcast_broadcast";
+// ── Agent ───────────────────────────────────────────────────────────────
+/**
+ * An agent that reviews all generated documentation and restructures
+ * for consistency — deduplicating, renaming, and reorganizing files.
+ *
+ * Writes/edits files directly via the edit tool. The pipeline discovers
+ * the final file set by scanning disk afterward.
+ */
+export class OrganizationAgent extends BaseAgent {
+    constructor(provider) {
+        super(provider);
+    }
+    /**
+     * Run the organization pass over all generated documentation.
+     * Automatically selects single-agent or parallel mode based on file count.
+     *
+     * @param params  - Organization parameters including file paths.
+     * @param verbose - Optional logging callback (writes to stderr).
+     * @throws If session creation or prompting fails.
+     */
+    async run(params, verbose) {
+        if (params.allDocFiles.length > PARALLEL_THRESHOLD) {
+            return this.runParallel(params, verbose);
+        }
+        return this.runSingle(params, verbose);
+    }
+    /**
+     * Single-agent organization pass (original behavior).
+     * Used when file count is ≤ PARALLEL_THRESHOLD.
+     */
+    async runSingle(params, verbose) {
+        const tag = "org-agent";
+        // 1. Build prompt
+        const prompt = OrganizationAgent.buildPrompt(params);
+        if (verbose) {
+            verbose(`[${tag}] Prompt: ${prompt.length.toLocaleString()} chars`);
+        }
+        // 2. Create a new session
+        const sessionId = await this.createSession("Hem: organization");
+        if (verbose) {
+            verbose(`[${tag}] Session created: ${sessionId}`);
+        }
+        // 3. Send prompt — use hem-org agent
+        await this.provider.prompt(sessionId, prompt, { agent: "hem-org" });
+        if (verbose) {
+            verbose(`[${tag}] Agent completed`);
+        }
+    }
+    /**
+     * Parallel organization pass using multiple workers with an arbiter.
+     *
+     * 1. Computes worker count from resource limits (arbiter excluded).
+     * 2. Assigns files to workers via round-robin.
+     * 3. Subscribes to SSE events for broadcast interception.
+     * 4. Creates an arbiter session (long-lived coordinator).
+     * 5. Creates N worker sessions in parallel.
+     * 6. Relays broadcasts with targeted routing:
+     *    - Worker → arbiter only.
+     *    - Arbiter → @tagged worker(s) only (or all if @all-workers / no tag).
+     *    - Completed sessions are excluded from relay.
+     * 7. Kills worker sessions immediately on completion (abort + delete).
+     * 8. Intercepts RECALL: broadcasts to respawn a worker for fixes.
+     * 9. Sends a final prompt to the arbiter so it can wrap up.
+     * 10. Kills the arbiter session.
+     */
+    async runParallel(params, verbose) {
+        const tag = "org-parallel";
+        const { projectName, destinationPath, allDocFiles } = params;
+        // 1. Compute effective worker count — scales with file count, capped by resources
+        const dynamicWorkers = computeOrgWorkers(allDocFiles.length);
+        const effectiveMaxWorkers = Math.min(MAX_WORKERS, dynamicWorkers);
+        const assignments = assignFilesToWorkers(allDocFiles, effectiveMaxWorkers);
+        if (verbose) {
+            verbose(`[${tag}] Resource cap: ${effectiveMaxWorkers} sessions (arbiter excluded)`);
+            verbose(`[${tag}] Splitting ${allDocFiles.length} files across ${assignments.length} workers + 1 arbiter`);
+            for (const a of assignments) {
+                verbose(`[${tag}]   ${a.label}: ${a.files.length} files`);
+            }
+        }
+        // 2. Session tracking
+        //    allSessions: sessionId → label (live sessions only — removed on kill)
+        //    workerSessionIds: set of worker session IDs (for routing logic)
+        //    completedSessions: workers that finished (excluded from relay)
+        //    childSessions: childSessionId → parentSessionId (subagent tracking)
+        const allSessions = new Map();
+        const workerSessionIds = new Set();
+        const completedSessions = new Set();
+        const childSessions = new Map();
+        // Store arbiter session ID at this scope so the relay can identify it
+        let arbiterSessionId = "";
+        // Keep a reference to the original assignments for RECALL
+        const assignmentsByLabel = new Map();
+        for (const a of assignments) {
+            assignmentsByLabel.set(a.label, a);
+        }
+        // Pending recall promises collected asynchronously
+        const pendingRecalls = [];
+        // 3a. Decision queue — sequences MERGE/DELETE to prevent race conditions
+        //     Instantiated here so it's in scope for the SSE relay and cleanup.
+        const decisionQueue = new DecisionQueue({
+            destPath: destinationPath,
+            relay: async (target, text) => {
+                try {
+                    await this.provider.session.promptAsync({
+                        path: { id: target.id },
+                        body: {
+                            parts: [{ type: "text", text }],
+                            agent: "hem-org",
+                        },
+                    });
+                    if (verbose) {
+                        verbose(`[${tag}]   → Relayed to ${target.label} (${target.id.slice(0, 8)}…)`);
+                    }
+                }
+                catch (err) {
+                    if (verbose) {
+                        verbose(`[${tag}]   ✗ Relay to ${target.label} failed: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                }
+            },
+            timeoutMs: undefined, // use default (60 s)
+            verbose,
+        });
+        // 3b. Subscribe to SSE events for broadcast interception
+        let sseStream = null;
+        let sseLoopDone = false;
+        const startSseRelay = async () => {
+            try {
+                const subscribeResult = await this.provider.event.subscribe();
+                sseStream = subscribeResult.stream;
+            }
+            catch (err) {
+                if (verbose) {
+                    verbose(`[${tag}] ⚠ Failed to subscribe to SSE events: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                return;
+            }
+            if (verbose) {
+                verbose(`[${tag}] SSE relay started`);
+            }
+            try {
+                for await (const rawEvent of sseStream) {
+                    if (sseLoopDone)
+                        break;
+                    const event = rawEvent;
+                    if (!event.type || !event.properties)
+                        continue;
+                    if (event.type === "message.part.updated") {
+                        const part = event.properties.part;
+                        if (!part || part.type !== "tool")
+                            continue;
+                        // ── Detect broadcast tool calls ──────────────────────
+                        if (part.tool === BROADCAST_TOOL_NAME &&
+                            part.state?.status === "running" &&
+                            part.sessionID &&
+                            part.state.input) {
+                            const message = part.state.input.message;
+                            const senderSessionId = part.sessionID;
+                            const senderLabel = allSessions.get(senderSessionId);
+                            if (message && senderLabel) {
+                                if (verbose) {
+                                    verbose(`[${tag}] 📢 Broadcast from ${senderLabel}: ${message}`);
+                                }
+                                // ── RECALL interception ──────────────────────────
+                                // If the arbiter broadcasts "RECALL: @org-worker-N <instructions>",
+                                // intercept it and spawn a new focused worker session.
+                                const recallMatch = message.match(/^RECALL:\s*@(org-worker-\d+)\s+([\s\S]+)/i);
+                                if (recallMatch && !workerSessionIds.has(senderSessionId)) {
+                                    const targetLabel = recallMatch[1];
+                                    const instructions = recallMatch[2];
+                                    const originalAssignment = assignmentsByLabel.get(targetLabel);
+                                    if (originalAssignment) {
+                                        if (verbose) {
+                                            verbose(`[${tag}] 🔄 Recalling ${targetLabel} for fixes`);
+                                        }
+                                        const recallPromise = this.runRecalledWorker(projectName, destinationPath, originalAssignment, allDocFiles, assignments.length, instructions, verbose).catch((err) => {
+                                            if (verbose) {
+                                                verbose(`[${tag}] ✗ Recall of ${targetLabel} failed: ${err instanceof Error ? err.message : String(err)}`);
+                                            }
+                                        });
+                                        pendingRecalls.push(recallPromise);
+                                    }
+                                    else if (verbose) {
+                                        verbose(`[${tag}] ⚠ RECALL target ${targetLabel} not found in assignments`);
+                                    }
+                                    // Don't relay RECALL messages — the orchestrator handles them
+                                    continue;
+                                }
+                                // ── Targeted routing ─────────────────────────────
+                                const relayText = `Message from ${senderLabel}: ${message}`;
+                                const relayTargets = [];
+                                const senderIsWorker = workerSessionIds.has(senderSessionId);
+                                if (senderIsWorker) {
+                                    // Worker → always relay to arbiter only
+                                    if (arbiterSessionId && !completedSessions.has(arbiterSessionId)) {
+                                        relayTargets.push({ id: arbiterSessionId, label: "arbiter" });
+                                    }
+                                }
+                                else {
+                                    // Arbiter → check for @tags in message
+                                    const tagPattern = /@(org-worker-\d+)/g;
+                                    const tags = [...message.matchAll(tagPattern)].map(m => m[1]);
+                                    const isAllWorkers = /@all-workers/i.test(message);
+                                    if (tags.length > 0 && !isAllWorkers) {
+                                        // Route to specifically tagged workers only
+                                        for (const [sessionId, label] of allSessions) {
+                                            if (sessionId === senderSessionId)
+                                                continue;
+                                            if (completedSessions.has(sessionId))
+                                                continue;
+                                            if (tags.some(t => label === t)) {
+                                                relayTargets.push({ id: sessionId, label });
+                                            }
+                                        }
+                                    }
+                                    else {
+                                        // @all-workers or no tags → broadcast to all live workers
+                                        for (const [sessionId, label] of allSessions) {
+                                            if (sessionId === senderSessionId)
+                                                continue;
+                                            if (completedSessions.has(sessionId))
+                                                continue;
+                                            if (workerSessionIds.has(sessionId)) {
+                                                relayTargets.push({ id: sessionId, label });
+                                            }
+                                        }
+                                    }
+                                }
+                                // Also include active subagents of each relay target
+                                const subagentTargets = [];
+                                for (const target of relayTargets) {
+                                    for (const [childId, parentId] of childSessions) {
+                                        if (parentId === target.id && !completedSessions.has(childId)) {
+                                            subagentTargets.push({ id: childId, label: `${target.label}/subagent` });
+                                        }
+                                    }
+                                }
+                                relayTargets.push(...subagentTargets);
+                                // Fire relay prompts concurrently (fire-and-forget)
+                                if (relayTargets.length > 0) {
+                                    // Check if this is a DECISION from the arbiter — route through queue
+                                    const parsedDecision = !senderIsWorker ? parseDecision(message) : undefined;
+                                    if (parsedDecision) {
+                                        // DECISION → route through DecisionQueue for sequencing
+                                        const decisionPromises = relayTargets.map(async (target) => {
+                                            await decisionQueue.handleDecision(parsedDecision, target, relayText);
+                                        });
+                                        void Promise.allSettled(decisionPromises);
+                                    }
+                                    else {
+                                        // Non-DECISION → relay directly (fire-and-forget)
+                                        const relayPromises = relayTargets.map(async (target) => {
+                                            try {
+                                                await this.provider.session.promptAsync({
+                                                    path: { id: target.id },
+                                                    body: {
+                                                        parts: [{ type: "text", text: relayText }],
+                                                        agent: "hem-org",
+                                                    },
+                                                });
+                                                if (verbose) {
+                                                    verbose(`[${tag}]   → Relayed to ${target.label} (${target.id.slice(0, 8)}…)`);
+                                                }
+                                            }
+                                            catch (err) {
+                                                if (verbose) {
+                                                    verbose(`[${tag}]   ✗ Relay to ${target.label} failed: ${err instanceof Error ? err.message : String(err)}`);
+                                                }
+                                            }
+                                        });
+                                        // Don't await — let relays happen async while SSE loop continues
+                                        void Promise.allSettled(relayPromises);
+                                    }
+                                }
+                            }
+                        }
+                    }
+                    // ── Track child sessions via session.created events ────
+                    if (event.type === "session.created") {
+                        const props = event.properties;
+                        if (props.session?.id && props.session.parentID) {
+                            const parentId = props.session.parentID;
+                            // Only track if the parent is one of our sessions (worker or arbiter)
+                            if (allSessions.has(parentId)) {
+                                childSessions.set(props.session.id, parentId);
+                                if (verbose) {
+                                    const parentLabel = allSessions.get(parentId);
+                                    verbose(`[${tag}] · Subagent ${props.session.id.slice(0, 8)}… spawned by ${parentLabel}`);
+                                }
+                            }
+                            // Also check if parent is itself a tracked child (nested subagents)
+                            else if (childSessions.has(parentId)) {
+                                const rootParent = childSessions.get(parentId);
+                                childSessions.set(props.session.id, rootParent);
+                                if (verbose) {
+                                    const rootLabel = allSessions.get(rootParent);
+                                    verbose(`[${tag}] · Nested subagent ${props.session.id.slice(0, 8)}… (root: ${rootLabel})`);
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                // SSE stream can error when the server shuts down or on network issues.
+                // This is expected during cleanup — only log if we're still running.
+                if (!sseLoopDone && verbose) {
+                    verbose(`[${tag}] ⚠ SSE stream error: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        };
+        // Start SSE relay in background (don't await — runs concurrently)
+        const sseRelayPromise = startSseRelay();
+        // Start the decision queue filesystem watcher
+        decisionQueue.start();
+        try {
+            // 4. Create arbiter session (long-lived coordinator) via ArbiterAgent
+            const arbiter = new ArbiterAgent(this.provider);
+            const { sessionId: aId } = await arbiter.run({
+                projectName,
+                destinationPath,
+                allDocFiles,
+                workerAssignments: assignments,
+            }, verbose);
+            arbiterSessionId = aId;
+            allSessions.set(arbiterSessionId, "arbiter");
+            // 5. Create worker sessions and send prompts concurrently
+            const workerPromises = assignments.map(async (assignment) => {
+                const prompt = OrganizationAgent.buildWorkerPrompt({
+                    projectName,
+                    destinationPath,
+                    assignedFiles: assignment.files,
+                    allDocFiles,
+                    workerLabel: assignment.label,
+                    totalWorkers: assignments.length,
+                });
+                if (verbose) {
+                    verbose(`[${tag}] ${assignment.label}: prompt ${prompt.length.toLocaleString()} chars`);
+                }
+                // Create session
+                const sessionId = await this.createSession(`Hem: ${assignment.label}`);
+                allSessions.set(sessionId, assignment.label);
+                workerSessionIds.add(sessionId);
+                if (verbose) {
+                    verbose(`[${tag}] ${assignment.label}: session ${sessionId}`);
+                }
+                // Send prompt and wait for completion
+                await this.provider.prompt(sessionId, prompt, { agent: "hem-org" });
+                // ── Kill the worker session immediately ──────────────────
+                // Worker is done — free resources.  Mark as completed first
+                // so the relay loop stops sending messages to it, then abort
+                // and delete the session.  Release any queued decisions that
+                // were blocked on this worker's actions.
+                completedSessions.add(sessionId);
+                allSessions.delete(sessionId);
+                decisionQueue.releaseForWorker(assignment.label);
+                await this.killSession(sessionId, assignment.label, verbose);
+            });
+            // 6. Wait for all workers to complete
+            const results = await Promise.allSettled(workerPromises);
+            // 7. Check for auth errors first
+            for (const result of results) {
+                if (result.status === "rejected" &&
+                    result.reason instanceof AuthExpiredError) {
+                    throw result.reason;
+                }
+            }
+            // 8. Signal the arbiter that all workers are done
+            await arbiter.wrapUp(arbiterSessionId, verbose);
+            // 9. Wait for any pending recall sessions spawned during arbiter wrap-up
+            if (pendingRecalls.length > 0) {
+                if (verbose) {
+                    verbose(`[${tag}] Waiting for ${pendingRecalls.length} pending recall(s)...`);
+                }
+                await Promise.allSettled(pendingRecalls);
+            }
+            // 10. Kill the arbiter session
+            completedSessions.add(arbiterSessionId);
+            allSessions.delete(arbiterSessionId);
+            await this.killSession(arbiterSessionId, "arbiter", verbose);
+            // 11. Log any worker failures (the pipeline discovers files via disk scan)
+            for (let i = 0; i < results.length; i++) {
+                const result = results[i];
+                const label = assignments[i].label;
+                if (result.status === "rejected") {
+                    const msg = result.reason instanceof Error
+                        ? result.reason.message
+                        : String(result.reason);
+                    if (verbose) {
+                        verbose(`[${tag}] ✗ ${label} failed: ${msg}`);
+                    }
+                }
+                else if (verbose) {
+                    verbose(`[${tag}] ✓ ${label} completed`);
+                }
+            }
+        }
+        finally {
+            // 12. Stop the decision queue (releases remaining items, closes watcher)
+            decisionQueue.stop();
+            // 13. Stop the SSE relay loop
+            sseLoopDone = true;
+            // The SSE stream will naturally close when the server shuts down,
+            // but we set the flag so any in-flight iterations exit cleanly.
+            await Promise.race([
+                sseRelayPromise,
+                new Promise((resolve) => setTimeout(resolve, 1000)),
+            ]);
+        }
+    }
+    /**
+     * Kill a session: abort any running work, then delete the session.
+     * Best-effort — failures are logged but not thrown.
+     */
+    async killSession(sessionId, label, verbose) {
+        try {
+            await this.provider.session.abort({ path: { id: sessionId } });
+        }
+        catch {
+            // Session may already be idle — abort failing is fine
+        }
+        try {
+            await this.provider.session.delete({ path: { id: sessionId } });
+            if (verbose) {
+                verbose(`[org-parallel] 🗑 Killed session ${label} (${sessionId.slice(0, 8)}…)`);
+            }
+        }
+        catch (err) {
+            if (verbose) {
+                verbose(`[org-parallel] ⚠ Failed to delete session ${label}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    /**
+     * Spawn a recalled worker session to apply specific fixes.
+     *
+     * Called when the arbiter broadcasts `RECALL: @org-worker-N <instructions>`.
+     * Creates a new session with the worker's original file assignment and a
+     * focused prompt containing the fix instructions.  The session is killed
+     * immediately after completion.
+     */
+    async runRecalledWorker(projectName, destinationPath, assignment, allDocFiles, totalWorkers, instructions, verbose) {
+        const tag = `recall-${assignment.label}`;
+        const prompt = [
+            `Worker **${assignment.label}** (recalled). Previously organized documentation`,
+            `files for **${projectName}**; the arbiter found issues that need fixing.`,
+            "",
+            "## Destination directory",
+            "",
+            `All documentation files are in: \`${destinationPath}\``,
+            "",
+            "## Your assigned files",
+            "",
+            ...assignment.files.map((f) => `- \`${destinationPath}/${f}\``),
+            "",
+            "## Fix instructions from the arbiter",
+            "",
+            instructions,
+            "",
+            "## Rules",
+            "",
+            "- Use the edit tool to make the requested fixes directly.",
+            "- Only modify files in the assigned list unless the arbiter specifically",
+            "  instructed otherwise.",
+            "- When all fixes are complete, stop.",
+        ].join("\n");
+        if (verbose) {
+            verbose(`[${tag}] Recall prompt: ${prompt.length.toLocaleString()} chars`);
+        }
+        const sessionId = await this.createSession(`Hem: ${tag}`);
+        if (verbose) {
+            verbose(`[${tag}] Session ${sessionId}`);
+        }
+        try {
+            await this.provider.prompt(sessionId, prompt, { agent: "hem-org" });
+            if (verbose) {
+                verbose(`[${tag}] Recall completed`);
+            }
+        }
+        finally {
+            // Always kill the recall session
+            await this.killSession(sessionId, tag, verbose);
+        }
+    }
+    /**
+     * Builds the single-agent organization prompt (original behavior).
+     */
+    static buildPrompt(params) {
+        const { projectName, destinationPath, allDocFiles } = params;
+        const parts = [];
+        parts.push(`Review all generated documentation files for **${projectName}** and ensure`, `they are well-organized, consistent, and free of duplication.`, "", `**Edit files directly using the edit tool.** Do NOT return Markdown content`, `in the response text.`, "");
+        parts.push("## Destination directory", "", `All documentation files are in: \`${destinationPath}\``, "");
+        parts.push("## Documentation files to review", "");
+        for (const file of allDocFiles) {
+            parts.push(`- \`${destinationPath}/${file}\``);
+        }
+        parts.push("");
+        parts.push("## Your tasks", "", "Read ALL the documentation files listed above, then:", "", "1. **Deduplicate**: If multiple files cover the same topic, merge ALL content", "   into a single canonical file. **Delete the duplicate entirely.** Do NOT", "   leave redirect stubs, 'see also' pages, or slim placeholder files.", "", "2. **Consistent naming**: Ensure all filenames use kebab-case and are descriptive.", "   Rename files if needed (create new file, delete old).", "", "3. **Consistent structure**: Ensure all pages follow a consistent heading hierarchy", "   and section ordering (Overview, Architecture, Key Concepts, etc.).", "", "4. **Directory organization**: Ensure the directory structure is consistent", "   and logical. The doc agents chose their own structure — preserve it if it", "   makes sense, or reorganize for clarity.", "", "5. **Fix broken links**: If you rename or move files, update all internal links", "   in other documents to point to the new locations.", "", "If the documentation is already well-organized, make no changes.", "");
+        parts.push("## When you are done", "", "After making all changes using the edit tool, stop. The pipeline will", "scan the destination directory to discover the final file set.", "", "Key rules:", "- Edit files using the edit tool — do NOT return Markdown in your response", "- When all edits are complete, stop");
+        return parts.join("\n");
+    }
+    /**
+     * Builds the prompt for a parallel org worker.
+     *
+     * Each worker gets:
+     *   - A scoped identity (e.g. "org-worker-1 of 3")
+     *   - Its assigned file subset
+     *   - The full file list for cross-reference awareness
+     *   - Instructions for using the broadcast tool
+     *   - Scoped task list (only edit YOUR files)
+     */
+    static buildWorkerPrompt(params) {
+        const { projectName, destinationPath, assignedFiles, allDocFiles, workerLabel, totalWorkers, } = params;
+        const parts = [];
+        // ── Role section ──────────────────────────────────────────────────
+        parts.push(`Worker **${workerLabel}**: review the assigned subset of generated documentation`, `files for **${projectName}** and ensure they are well-organized, consistent,`, `and free of duplication.`, "", `There are ${totalWorkers} workers running in parallel; each owns a distinct set`, `of files. Coordinate with the arbiter via the broadcast tool.`, "", `**Edit files directly using the edit tool.** Full write access is granted`, `— use it. Do NOT delegate file edits to the arbiter or anyone else. Do NOT`, `return Markdown content in the response text. Make changes with the edit`, `tool, then stop when done.`, "", `**IMPORTANT: This session will be terminated on completion.** Complete all`, `edits first, then stop.`, "");
+        // ── Destination directory ─────────────────────────────────────────
+        parts.push("## Destination directory", "", `All documentation files are in: \`${destinationPath}\``, "");
+        // ── Assigned files ────────────────────────────────────────────────
+        parts.push("## Your assigned files", "", "The assigned files for organization are:", "");
+        for (const file of assignedFiles) {
+            parts.push(`- \`${destinationPath}/${file}\``);
+        }
+        parts.push("");
+        // ── All files (for cross-reference awareness) ─────────────────────
+        if (allDocFiles.length > assignedFiles.length) {
+            parts.push("## All documentation files (for reference)", "", "Other workers are handling these files. You may read them for context", "but do NOT edit files outside your assigned list.", "");
+            const otherFiles = allDocFiles.filter((f) => !assignedFiles.includes(f));
+            for (const file of otherFiles) {
+                parts.push(`- \`${destinationPath}/${file}\``);
+            }
+            parts.push("");
+        }
+        // ── Tasks (scoped) ────────────────────────────────────────────────
+        parts.push("## Your tasks", "", "Read ALL of your assigned documentation files, then:", "", "1. **Deduplicate**: If files in YOUR subset cover the same topic, merge ALL", "   content into one canonical file and **delete the duplicate entirely**.", "   Do NOT create redirect stubs, 'see also' pages, or slim placeholder", "   files — the duplicate must be fully removed. If you spot a duplicate", "   that spans another worker's files, broadcast a SUGGESTION — the arbiter", "   will decide how to handle it.", "", "2. **Consistent naming**: Ensure your files use kebab-case. If you rename a", "   file, broadcast the rename immediately.", "", "3. **Consistent structure**: Ensure your files follow a consistent heading", "   hierarchy and section ordering.", "", "4. **Directory organization**: Organize your files logically.", "   If you move files, broadcast the move.", "", "5. **Fix broken links**: Update internal links in your files. If another", "   worker or the arbiter broadcasts a rename or deletion, update any", "   references in your files.", "", "If your files are already well-organized, make no changes.", "");
+        // ── Coordination section ──────────────────────────────────────────
+        parts.push("## Coordination with the arbiter", "", "You can communicate using the **broadcast** tool. Your broadcasts go", "**ONLY to the arbiter** — other workers will NOT see your messages.", "The arbiter coordinates all cross-worker communication.", "", "### When to broadcast", "", "Broadcast whenever you make a change that could affect other workers' files:", "", '- **File renames/moves**:', '  `broadcast({ message: "RENAMED: auth/overview.md → auth/authentication-overview.md (kebab-case alignment)" })`', "", '- **File deletions (dedup merges)**:', '  `broadcast({ message: "DELETED: auth/api-keys.md (merged into auth/authentication-overview.md)" })`', "", '- **Structural conventions**:', '  `broadcast({ message: "CONVENTION: All API reference docs moved under api/ subdirectory" })`', "", '- **Suggestions for cross-subset issues** (the arbiter will act on these):', '  `broadcast({ message: "SUGGESTION: auth/api-keys.md and api/authentication.md look like duplicates" })`', "", '- **Acknowledgements** (only when you actually took action):', '  `broadcast({ message: "ACK: Updated 3 links to auth/authentication-overview.md" })`', "", "### When you receive messages", "", "Messages appear as user messages prefixed with the sender's label.", "You will only receive messages from **the arbiter** (DECISION messages).", "Decision types you may receive:", "", "- **MERGE**: `DECISION: @your-label MERGE <source> INTO <target>` —", "  read content from the source file and merge it into the target file.", "  After merging, broadcast an ACK.", "", "- **DELETE**: `DECISION: @your-label DELETE <filepath>` —", "  delete the specified file using the bash tool: `rm <filepath>`.", "  After deleting, broadcast an ACK.", "", "- **UPDATE-LINKS**: `DECISION: @your-label UPDATE-LINKS <filepath>` —", "  update internal links in the specified file. After updating,", "  broadcast an ACK.", "", "- **Free-form**: `DECISION: @your-label <instructions>` —", "  execute the instructions directly. After executing, broadcast an ACK.", "", "You **MUST** execute each DECISION yourself. Use the edit tool for", "MERGE and UPDATE-LINKS decisions, and the bash tool (`rm`) for DELETE", "decisions. The arbiter decides how to resolve cross-subset issues.", "", "### Rules", "", "- Only reorganize files in YOUR assigned list. For cross-subset issues,", "  broadcast a SUGGESTION and let the arbiter decide.", "- Do NOT ACK messages you cannot act on. Only ACK when you actually", "  edited files or updated links. No \"noted\" or \"not my files\" messages.", "- Do NOT broadcast progress updates, questions, or file contents.", "- Keep messages short and actionable.", "- You MUST use the edit tool to make all file changes yourself.", "  Do NOT ask the arbiter to edit files for you.", "");
+        // ── When done ──────────────────────────────────────────────────────
+        parts.push("## When you are done", "", "After making ALL changes (including any changes requested by the arbiter),", "stop. The pipeline will scan the destination directory to discover the", "final file set.", "", "- Make sure all edits are complete before stopping.", "- **Your session will be terminated when you finish.**");
+        return parts.join("\n");
+    }
+}
+// ── File Assignment ─────────────────────────────────────────────────────
+/**
+ * Assigns documentation files to workers using round-robin distribution.
+ *
+ * Files are sorted alphabetically first so that files in the same
+ * directory tend to land on adjacent workers, preserving some locality.
+ * Then they are dealt out in order: file 0 → worker 1, file 1 → worker 2,
+ * …, wrapping around. This guarantees perfectly balanced workloads (±1 file).
+ *
+ * @param files      - Relative file paths (e.g. "auth/overview.md").
+ * @param maxWorkers - Maximum number of workers to create.
+ * @returns An array of worker assignments, each with a label and file list.
+ */
+export function assignFilesToWorkers(files, maxWorkers) {
+    if (files.length === 0)
+        return [];
+    const numWorkers = Math.min(maxWorkers, files.length);
+    if (numWorkers <= 1) {
+        return [{ label: "org-worker-1", files: [...files] }];
+    }
+    const sorted = [...files].sort();
+    const workers = [];
+    for (let i = 0; i < numWorkers; i++) {
+        workers.push({ label: `org-worker-${i + 1}`, files: [] });
+    }
+    for (let i = 0; i < sorted.length; i++) {
+        workers[i % numWorkers].files.push(sorted[i]);
+    }
+    return workers;
+}