@elyracode/swarm 0.9.18 → 0.9.20

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.9.20] - 2026-07-19
+
+### Added
+- Worktree mode: `/swarm --worktrees <pipeline> <task>` (or `worktrees=true` on the `swarm` tool) runs every stage as an isolated sub-agent (`elyra -p`) inside a detached git worktree. Read-only stages are mechanically restricted to read/grep/find/ls tools, write stages cannot touch your working tree, and the combined result is applied uncommitted only after a conflict check against files that changed while the swarm ran. Falls back to the classic inline mode outside git repos
+
+## [0.9.19] - 2026-07-18
+
 ## [0.9.18] - 2026-07-18
 
 ## [0.9.17] - 2026-07-18

package/README.md

@@ -59,6 +59,7 @@ analyze -> plan -> implement -> verify
 /swarm build add a notification system with email and in-app channels
 /swarm review the authentication module
 /swarm refactor the database query layer
+/swarm --worktrees build add rate limiting to the API
 /swarm          # lists available pipelines
 ```
 
@@ -76,3 +77,15 @@ Run a swarm review on the checkout flow
 Each pipeline stage runs as a focused agent turn with specific instructions. Results from each stage are passed to the next as context. The agent sees a progress indicator showing which stage is active.
 
 Stages marked as read-only (analyze, review, synthesize) cannot edit files. Only implementation stages (code, fix, implement) can write.
+
+## Worktree Mode
+
+Add `--worktrees` (or pass `worktrees=true` to the `swarm` tool) to run every stage as an isolated sub-agent instead of inline turns:
+
+- Each stage runs as its own `elyra -p` process inside a detached **git worktree** based on HEAD — your working tree is never touched while the swarm runs.
+- Read-only stages are mechanically restricted to `read,grep,find,ls` tools, not just prompted.
+- When all stages complete, the combined changes are checked for conflicts against files that changed in your working tree during the run. If clean, they are applied **uncommitted** so you can review them; if not, the worktree is kept and the conflicting paths are listed.
+- On any failure the worktree is kept for inspection (`git worktree remove --force <dir>` to discard).
+- Outside a git repository, worktree mode degrades gracefully to the classic inline mode.
+
+Requirements: a git repository and the `elyra` CLI on PATH. Sub-agents start from HEAD, so uncommitted changes in your tree are not visible to them.

package/extensions/index.ts

@@ -1,5 +1,14 @@
-import type { ExtensionAPI } from "@elyracode/coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@elyracode/coding-agent";
 import { Type } from "typebox";
+import {
+	applyPatch,
+	changedFiles,
+	collectWorktreeChanges,
+	createWorktree,
+	findConflicts,
+	isGitRepo,
+	removeWorktree,
+} from "./worktree.js";
 
 // ── Pipeline Definitions ────────────────────────────────────────────────────
 
@@ -263,6 +272,227 @@ function renderStageHeader(pipeline: Pipeline, stageIndex: number, task: string)
 }
 
 // ── Extension ───────────────────────────────────────────────────────────────
+// ── Inline mode (prompt injection, original behavior) ───────────────────
+
+function buildInlineResult(pipeline: Pipeline, task: string, note?: string) {
+	const completedIndices = new Set<number>();
+	const parts: string[] = [];
+
+	if (note) parts.push(`> ${note}\n\n`);
+
+	// Render initial pipeline view
+	parts.push(renderPipeline(pipeline, 0, completedIndices));
+
+	// Generate instructions for all stages
+	for (let i = 0; i < pipeline.stages.length; i++) {
+		const stage = pipeline.stages[i]!;
+		parts.push(renderStageHeader(pipeline, i, task));
+
+		parts.push(`**Task**: ${task}\n\n`);
+		parts.push(`**Instructions**:\n${stage.instructions}\n\n`);
+
+		if (stage.readOnly) {
+			parts.push(`**Constraint**: This is a read-only stage. Do NOT edit any files.\n\n`);
+		}
+
+		if (i < pipeline.stages.length - 1) {
+			parts.push(`When done, write your output under a "#### ${stage.label} Output" heading, then proceed to the next stage.\n\n`);
+		} else {
+			parts.push(`This is the final stage. Write your output under a "#### ${stage.label} Output" heading, then provide a "## Swarm Summary" with the overall result.\n\n`);
+		}
+
+		completedIndices.add(i);
+	}
+
+	// Final pipeline view (all complete)
+	parts.push("---\n\n");
+	parts.push(renderPipeline(pipeline, -1, completedIndices));
+
+	return {
+		content: [{ type: "text" as const, text: parts.join("") }],
+		details: {
+			pipeline: pipeline.name,
+			stages: pipeline.stages.length,
+			task,
+		},
+	};
+}
+
+// ── Worktree mode (isolated sub-agents) ───────────────────────────────
+
+const STAGE_TIMEOUT_MS = 600_000;
+const READ_ONLY_TOOLS = "read,grep,find,ls";
+
+function buildStagePrompt(pipeline: Pipeline, stageIndex: number, task: string, previousOutputs: string[]): string {
+	const stage = pipeline.stages[stageIndex]!;
+	const parts: string[] = [];
+	parts.push(`You are one stage of the "${pipeline.name}" swarm pipeline.`);
+	parts.push(`\n\n**Task**: ${task}`);
+	parts.push(`\n\n**Your role**:\n${stage.instructions}`);
+	if (stage.readOnly) {
+		parts.push(`\n\n**Constraint**: This is a read-only stage. Do NOT edit any files.`);
+	}
+	if (previousOutputs.length > 0) {
+		parts.push(`\n\n**Output from previous stages**:\n\n${previousOutputs.join("\n\n---\n\n")}`);
+	}
+	parts.push(`\n\nWork directly in the current directory. When done, end with a concise summary of what you did/found.`);
+	return parts.join("");
+}
+
+async function runWorktreePipeline(
+	elyra: ExtensionAPI,
+	pipeline: Pipeline,
+	task: string,
+	ctx: ExtensionContext,
+	signal: AbortSignal | undefined,
+	onUpdate: ((partial: { content: Array<{ type: "text"; text: string }>; details: Record<string, unknown> }) => void) | undefined,
+) {
+	const cwd = ctx.cwd;
+	const exec = elyra.exec.bind(elyra);
+
+	if (!(await isGitRepo(exec, cwd))) {
+		return buildInlineResult(pipeline, task, "Worktree mode requested but this is not a git repository — running inline instead.");
+	}
+
+	const mainBefore = await changedFiles(exec, cwd);
+	const worktree = await createWorktree(exec, cwd);
+	if ("error" in worktree) {
+		return buildInlineResult(pipeline, task, `Worktree mode requested but worktree creation failed (${worktree.error}) — running inline instead.`);
+	}
+
+	const modelArgs = ctx.model ? ["--model", `${ctx.model.provider}/${ctx.model.id}`] : [];
+	const completedIndices = new Set<number>();
+	const stageOutputs: string[] = [];
+	const transcript: string[] = [];
+	const dirtyNote =
+		mainBefore.size > 0
+			? `Note: the main tree has ${mainBefore.size} uncommitted change(s). Sub-agents work from HEAD and cannot see them.\n\n`
+			: "";
+
+	const progress = (activeIndex: number) => {
+		onUpdate?.({
+			content: [{ type: "text", text: `${dirtyNote}${renderPipeline(pipeline, activeIndex, completedIndices)}` }],
+			details: { pipeline: pipeline.name, task, worktree: worktree.dir },
+		});
+	};
+
+	try {
+		for (let i = 0; i < pipeline.stages.length; i++) {
+			const stage = pipeline.stages[i]!;
+			progress(i);
+
+			const prompt = buildStagePrompt(pipeline, i, task, stageOutputs);
+			const args = [
+				"-p",
+				"--no-session",
+				...modelArgs,
+				...(stage.readOnly ? ["--tools", READ_ONLY_TOOLS] : []),
+				prompt,
+			];
+
+			const result = await exec("elyra", args, { cwd: worktree.dir, timeout: STAGE_TIMEOUT_MS, signal });
+			const output = result.stdout.trim();
+			if (result.code !== 0 || !output) {
+				const error = result.stderr.trim() || `stage exited with code ${result.code}`;
+				transcript.push(`#### ${stage.label} Output\n\nFAILED: ${error}`);
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text:
+								`${dirtyNote}${renderPipeline(pipeline, i, completedIndices)}` +
+								`${transcript.join("\n\n")}\n\n` +
+								`## Swarm Summary\n\nAborted at stage "${stage.label}": ${error}\n\n` +
+								`The worktree is kept for inspection: ${worktree.dir}\n` +
+								`Remove it with: git worktree remove --force ${worktree.dir}`,
+						},
+					],
+					details: { pipeline: pipeline.name, task, failedStage: stage.name, worktree: worktree.dir },
+				};
+			}
+
+			stageOutputs.push(`#### ${stage.label} Output\n\n${output}`);
+			transcript.push(`#### ${stage.label} Output\n\n${output}`);
+			completedIndices.add(i);
+		}
+
+		// Collect and apply the swarm's changes.
+		const changes = await collectWorktreeChanges(exec, worktree.dir);
+		let applySection: string;
+		let keepWorktree = false;
+
+		if (!changes) {
+			applySection = `Could not collect changes from the worktree. It is kept for inspection: ${worktree.dir}`;
+			keepWorktree = true;
+		} else if (changes.files.length === 0) {
+			applySection = "The swarm made no file changes.";
+		} else {
+			const mainAfter = await changedFiles(exec, cwd);
+			const conflicts = findConflicts(changes.files, mainBefore, mainAfter);
+			if (conflicts.length > 0) {
+				applySection =
+					`NOT applied: ${conflicts.length} file(s) changed in your working tree while the swarm ran ` +
+					`(or were already dirty):\n${conflicts.map((f) => `- ${f}`).join("\n")}\n\n` +
+					`The worktree is kept so nothing is lost: ${worktree.dir}\n` +
+					`Inspect it and apply manually, then remove it with: git worktree remove --force ${worktree.dir}`;
+				keepWorktree = true;
+			} else {
+				const applied = await applyPatch(exec, cwd, changes.patch);
+				if (applied.ok) {
+					applySection =
+						`Applied ${changes.files.length} changed file(s) to your working tree (uncommitted, ready for review):\n` +
+						changes.files.map((f) => `- ${f}`).join("\n");
+				} else {
+					applySection =
+						`Patch failed to apply cleanly: ${applied.error}\n\n` +
+						`The worktree is kept so nothing is lost: ${worktree.dir}\n` +
+						`Remove it with: git worktree remove --force ${worktree.dir}`;
+					keepWorktree = true;
+				}
+			}
+		}
+
+		if (!keepWorktree) {
+			await removeWorktree(exec, cwd, worktree.dir);
+		}
+
+		return {
+			content: [
+				{
+					type: "text" as const,
+					text:
+						`${dirtyNote}${renderPipeline(pipeline, -1, completedIndices)}` +
+						`${transcript.join("\n\n")}\n\n` +
+						`## Swarm Summary\n\nAll ${pipeline.stages.length} stages completed in an isolated git worktree.\n\n${applySection}`,
+				},
+			],
+			details: {
+				pipeline: pipeline.name,
+				stages: pipeline.stages.length,
+				task,
+				worktree: keepWorktree ? worktree.dir : undefined,
+				files: changes?.files ?? [],
+			},
+		};
+	} catch (err) {
+		// Unexpected failure (including abort): keep the worktree for recovery.
+		const message = err instanceof Error ? err.message : String(err);
+		return {
+			content: [
+				{
+					type: "text" as const,
+					text:
+						`Swarm worktree run failed: ${message}\n\n` +
+						`The worktree is kept for inspection: ${worktree.dir}\n` +
+						`Remove it with: git worktree remove --force ${worktree.dir}`,
+				},
+			],
+			details: { pipeline: pipeline.name, task, worktree: worktree.dir },
+		};
+	}
+}
+
+// ── Extension ──────────────────────────────────────────────────────────────────────────────────────────
 
 export default function (elyra: ExtensionAPI): void {
 	// -- Tool: swarm --
@@ -275,7 +505,10 @@ export default function (elyra: ExtensionAPI): void {
 			"review (analyze -> correctness -> security -> tests -> synthesize), " +
 			"refactor (analyze -> plan -> implement -> verify). " +
 			"Each stage runs as a focused agent with specific instructions. " +
-			"Results pass automatically between stages.",
+			"Results pass automatically between stages. " +
+			"Set worktrees=true to run every stage as an isolated sub-agent in a git worktree: " +
+			"write stages cannot touch your working tree, and the combined result is applied " +
+			"(uncommitted) only after a conflict check.",
 		parameters: Type.Object({
 			pipeline: Type.String({
 				description: "Pipeline name: build, review, refactor",
@@ -283,8 +516,13 @@ export default function (elyra: ExtensionAPI): void {
 			task: Type.String({
 				description: "The task or target to work on",
 			}),
+			worktrees: Type.Optional(
+				Type.Boolean({
+					description: "Run stages as isolated sub-agents in a git worktree (requires a git repo)",
+				}),
+			),
 		}),
-		execute: async (_toolCallId, params) => {
+		execute: async (_toolCallId, params, signal, onUpdate, ctx) => {
 			const pipeline = PIPELINES[params.pipeline];
 			if (!pipeline) {
 				const available = Object.entries(PIPELINES)
@@ -296,53 +534,21 @@ export default function (elyra: ExtensionAPI): void {
 				};
 			}
 
-			const completedIndices = new Set<number>();
-			const parts: string[] = [];
-
-			// Render initial pipeline view
-			parts.push(renderPipeline(pipeline, 0, completedIndices));
-
-			// Generate instructions for all stages
-			for (let i = 0; i < pipeline.stages.length; i++) {
-				const stage = pipeline.stages[i]!;
-				parts.push(renderStageHeader(pipeline, i, params.task));
-
-				parts.push(`**Task**: ${params.task}\n\n`);
-				parts.push(`**Instructions**:\n${stage.instructions}\n\n`);
-
-				if (stage.readOnly) {
-					parts.push(`**Constraint**: This is a read-only stage. Do NOT edit any files.\n\n`);
-				}
-
-				if (i < pipeline.stages.length - 1) {
-					parts.push(`When done, write your output under a "#### ${stage.label} Output" heading, then proceed to the next stage.\n\n`);
-				} else {
-					parts.push(`This is the final stage. Write your output under a "#### ${stage.label} Output" heading, then provide a "## Swarm Summary" with the overall result.\n\n`);
-				}
-
-				completedIndices.add(i);
+			if (params.worktrees) {
+				return runWorktreePipeline(elyra, pipeline, params.task, ctx, signal, onUpdate);
 			}
 
-			// Final pipeline view (all complete)
-			parts.push("---\n\n");
-			parts.push(renderPipeline(pipeline, -1, completedIndices));
-
-			return {
-				content: [{ type: "text", text: parts.join("") }],
-				details: {
-					pipeline: pipeline.name,
-					stages: pipeline.stages.length,
-					task: params.task,
-				},
-			};
+			return buildInlineResult(pipeline, params.task);
 		},
 	});
 
 	// -- Command: /swarm --
 	elyra.registerCommand("swarm", {
-		description: "Run a multi-agent swarm pipeline: /swarm <pipeline> <task>",
+		description: "Run a multi-agent swarm pipeline: /swarm [--worktrees] <pipeline> <task>",
 		handler: async (args, ctx) => {
-			const parts = args.trim().split(/\s+/);
+			const tokens = args.trim().split(/\s+/).filter((t) => t.length > 0);
+			const worktrees = tokens.includes("--worktrees");
+			const parts = tokens.filter((t) => t !== "--worktrees");
 			const pipelineName = parts[0];
 			const task = parts.slice(1).join(" ");
 
@@ -353,7 +559,9 @@ export default function (elyra: ExtensionAPI): void {
 						return `  **${id}**: ${p.description}\n    ${stages}`;
 					})
 					.join("\n\n");
-				ctx.ui.notify(`Available swarm pipelines:\n\n${pipelineList}\n\nUsage: /swarm <pipeline> <task>`);
+				ctx.ui.notify(
+					`Available swarm pipelines:\n\n${pipelineList}\n\nUsage: /swarm [--worktrees] <pipeline> <task>\n\n--worktrees runs each stage as an isolated sub-agent in a git worktree.`,
+				);
 				return;
 			}
 
@@ -368,7 +576,8 @@ export default function (elyra: ExtensionAPI): void {
 				return;
 			}
 
-			elyra.sendUserMessage(`Run the ${pipelineName} swarm pipeline: ${task}`);
+			const worktreeSuffix = worktrees ? " Use worktrees=true so every stage runs isolated in a git worktree." : "";
+			elyra.sendUserMessage(`Run the ${pipelineName} swarm pipeline: ${task}${worktreeSuffix}`);
 		},
 	});
 }

package/extensions/worktree.ts

@@ -0,0 +1,140 @@
+/**
+ * Git worktree helpers for swarm worktree mode.
+ *
+ * All functions take an injectable exec function so the logic stays testable
+ * and the extension can route through `elyra.exec`. Sub-agents work in a
+ * detached worktree based on HEAD; results come back as a single patch that
+ * is applied (uncommitted) to the main working tree after conflict checks.
+ */
+
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export interface ExecFn {
+	(command: string, args: string[], options?: { cwd?: string; timeout?: number; signal?: AbortSignal }): Promise<{
+		stdout: string;
+		stderr: string;
+		code: number;
+	}>;
+}
+
+const GIT_TIMEOUT = 30_000;
+
+async function git(exec: ExecFn, cwd: string, args: string[]): Promise<{ stdout: string; code: number; stderr: string }> {
+	const result = await exec("git", args, { cwd, timeout: GIT_TIMEOUT });
+	return { stdout: result.stdout, code: result.code, stderr: result.stderr };
+}
+
+export async function isGitRepo(exec: ExecFn, cwd: string): Promise<boolean> {
+	try {
+		const result = await git(exec, cwd, ["rev-parse", "--is-inside-work-tree"]);
+		return result.code === 0 && result.stdout.trim() === "true";
+	} catch {
+		return false;
+	}
+}
+
+/** Parse `git status --porcelain` output into a set of (current) relative paths. */
+export function parsePorcelainPaths(porcelain: string): Set<string> {
+	const paths = new Set<string>();
+	for (const line of porcelain.split("\n")) {
+		if (line.length < 4) continue;
+		let p = line.slice(3);
+		const arrow = p.indexOf(" -> ");
+		if (arrow !== -1) p = p.slice(arrow + 4);
+		// Paths with special characters come back quoted.
+		if (p.startsWith('"') && p.endsWith('"')) p = p.slice(1, -1);
+		if (p) paths.add(p);
+	}
+	return paths;
+}
+
+/** Relative paths with uncommitted changes (staged, unstaged, or untracked). */
+export async function changedFiles(exec: ExecFn, cwd: string): Promise<Set<string>> {
+	const result = await git(exec, cwd, ["status", "--porcelain"]);
+	if (result.code !== 0) return new Set();
+	return parsePorcelainPaths(result.stdout);
+}
+
+export interface WorktreeInfo {
+	dir: string;
+}
+
+/** Create a detached worktree at HEAD under the system temp dir. */
+export async function createWorktree(exec: ExecFn, cwd: string): Promise<WorktreeInfo | { error: string }> {
+	let dir: string;
+	try {
+		dir = mkdtempSync(join(tmpdir(), "elyra-swarm-"));
+	} catch (err) {
+		return { error: err instanceof Error ? err.message : String(err) };
+	}
+	const result = await git(exec, cwd, ["worktree", "add", "--detach", dir, "HEAD"]);
+	if (result.code !== 0) {
+		return { error: result.stderr.trim() || `git worktree add exited with ${result.code}` };
+	}
+	return { dir };
+}
+
+export interface WorktreeResult {
+	/** Unified diff (with binary support) of everything the swarm changed. */
+	patch: string;
+	/** Relative paths touched by the swarm. */
+	files: string[];
+}
+
+/** Collect the swarm's changes from the worktree as a single patch. */
+export async function collectWorktreeChanges(exec: ExecFn, worktreeDir: string): Promise<WorktreeResult | null> {
+	const addResult = await git(exec, worktreeDir, ["add", "-A"]);
+	if (addResult.code !== 0) return null;
+
+	const namesResult = await git(exec, worktreeDir, ["diff", "--cached", "--name-only"]);
+	if (namesResult.code !== 0) return null;
+	const files = namesResult.stdout
+		.split("\n")
+		.map((l) => l.trim())
+		.filter((l) => l.length > 0);
+	if (files.length === 0) return { patch: "", files: [] };
+
+	const diffResult = await git(exec, worktreeDir, ["diff", "--cached", "--binary"]);
+	if (diffResult.code !== 0) return null;
+	return { patch: diffResult.stdout, files };
+}
+
+/** Apply a patch to the main working tree (leaves changes uncommitted). */
+export async function applyPatch(exec: ExecFn, cwd: string, patch: string): Promise<{ ok: boolean; error?: string }> {
+	let patchFile: string;
+	try {
+		const dir = mkdtempSync(join(tmpdir(), "elyra-swarm-patch-"));
+		patchFile = join(dir, "swarm.patch");
+		writeFileSync(patchFile, patch, "utf-8");
+	} catch (err) {
+		return { ok: false, error: err instanceof Error ? err.message : String(err) };
+	}
+	const result = await git(exec, cwd, ["apply", "--3way", patchFile]);
+	if (result.code !== 0) {
+		return { ok: false, error: result.stderr.trim() || `git apply exited with ${result.code}` };
+	}
+	return { ok: true };
+}
+
+export async function removeWorktree(exec: ExecFn, cwd: string, worktreeDir: string): Promise<void> {
+	try {
+		await git(exec, cwd, ["worktree", "remove", "--force", worktreeDir]);
+		await git(exec, cwd, ["worktree", "prune"]);
+	} catch {
+		// Best-effort cleanup; a leftover worktree is harmless and reported to the user.
+	}
+}
+
+/** Files both changed by the swarm and changed in the main tree while it ran. */
+export function findConflicts(swarmFiles: string[], mainBefore: Set<string>, mainAfter: Set<string>): string[] {
+	const changedDuringRun = new Set<string>();
+	for (const f of mainAfter) {
+		if (!mainBefore.has(f)) changedDuringRun.add(f);
+	}
+	// Files already dirty before the run also conflict if the swarm touched them:
+	// the patch is based on HEAD, not on the dirty state.
+	for (const f of mainBefore) changedDuringRun.add(f);
+	return swarmFiles.filter((f) => changedDuringRun.has(f)).sort();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elyracode/swarm",
-  "version": "0.9.18",
+  "version": "0.9.20",
   "description": "Multi-agent swarm orchestration for Elyra -- automated pipelines with visual progress tracking",
   "type": "module",
   "keywords": [

package/skills/elyra-swarm/SKILL.md

@@ -43,4 +43,9 @@ Commands:
 /swarm build user registration with email verification
 /swarm review src/payments/
 /swarm refactor the notification system
+/swarm --worktrees build rate limiting for the API
 ```
+
+## Worktree Mode
+
+When the user asks for isolation, safety, or mentions worktrees, pass `worktrees=true` to the `swarm` tool. Each stage then runs as an isolated sub-agent in a detached git worktree: the user's working tree is untouched while the swarm runs, read-only stages are mechanically tool-restricted, and the combined result is applied uncommitted after a conflict check. Requires a git repository; degrades to inline mode otherwise.