@chuckssmith/agentloom 0.5.0 → 0.6.0

package/dist/cli.js

@@ -6,6 +6,7 @@ import { logs } from './commands/logs.js';
 import { collect } from './commands/collect.js';
 import { reset } from './commands/reset.js';
 import { watch } from './commands/watch.js';
+import { stop } from './commands/stop.js';
 const [, , command, ...args] = process.argv;
 const usage = `
 agentloom (loom) — workflow layer for Claude Code
@@ -16,6 +17,8 @@ Usage:
   loom crew 2:explore "<task>"          Spawn typed workers (explore/plan/code-reviewer)
   loom crew --dry-run [N] "<task>"      Preview decomposed subtasks without launching
   loom watch                            Live tail all worker logs (Ctrl+C to stop)
+  loom stop                             Kill all background workers (SIGTERM)
+  loom stop <workerId>                  Kill one worker
   loom status                           Show active crew session + stale worker detection
   loom logs                             Show worker output summary
   loom logs <workerId>                  Show full log for a specific worker
@@ -62,6 +65,9 @@ switch (command) {
     case 'collect':
         await collect(args);
         break;
+    case 'stop':
+        await stop(args);
+        break;
     case 'reset':
         await reset(args);
         break;

package/dist/commands/crew.js

@@ -1,4 +1,4 @@
-import { execSync, spawn } from 'child_process';
+import { execSync, spawn, spawnSync } from 'child_process';
 import { writeFile, mkdir, open } from 'fs/promises';
 import { join } from 'path';
 import { parseWorkerSpec, initSession, writeContextSnapshot, decomposeTasks, } from '../team/orchestrator.js';
@@ -13,17 +13,18 @@ const hasTmux = () => {
     }
 };
 const isWSL = () => process.platform === 'linux' && !!process.env.WSL_DISTRO_NAME;
-// Role-specific instructions injected into each worker prompt
+// Roles that must NOT receive --dangerously-skip-permissions
+const READ_ONLY_ROLES = new Set(['explore', 'plan', 'code-reviewer']);
 const AGENT_ROLE = {
-    'explore': `Your role is EXPLORER. You are read-only. Do not modify any files.
+    'explore': `Your role is EXPLORER. You are read-only — do not modify, create, or delete any files.
 - Map out the relevant code, files, and structure
 - Document what exists, how it connects, and what's notable
 - Your output feeds the other workers — be thorough and specific`,
-    'plan': `Your role is PLANNER. You are read-only. Do not modify any files.
+    'plan': `Your role is PLANNER. You are read-only — do not modify, create, or delete any files.
 - Reason about the best approach to the subtask
 - Identify risks, dependencies, and open questions
 - Produce a concrete, ordered action plan other workers can execute`,
-    'code-reviewer': `Your role is CODE REVIEWER. You are read-only. Do not modify any files.
+    'code-reviewer': `Your role is CODE REVIEWER. You are read-only — do not modify, create, or delete any files.
 - Audit the relevant code for correctness, security, and quality
 - Flag specific lines, patterns, or logic that are problematic
 - Assign severity (critical / high / medium / low) to each finding`,
@@ -88,14 +89,15 @@ export async function crew(args) {
         console.log('Run without --dry-run to launch workers.');
         return;
     }
-    console.log(`Mode:    ${hasTmux() && !isWSL() ? 'tmux' : 'background processes'}\n`);
+    const useTmux = hasTmux() && !isWSL() && process.stdout.isTTY;
+    console.log(`Mode:    ${useTmux ? 'tmux' : 'background processes'}\n`);
     const session = await initSession(task, totalWorkers);
     const contextPath = await writeContextSnapshot(slug, task);
     const tasks = await decomposeTasks(task, specs);
     console.log(`Session: ${session.id}`);
     console.log(`Tasks:   ${tasks.length} created`);
     console.log(`Context: ${contextPath}\n`);
-    if (hasTmux() && !isWSL()) {
+    if (useTmux) {
         await launchTmux(session.id, specs, tasks, contextPath);
     }
     else {
@@ -103,8 +105,8 @@ export async function crew(args) {
     }
     console.log(`\nWorkers launched. Monitor with:`);
     console.log(`  loom status`);
-    console.log(`  loom logs`);
-    console.log(`  loom crew --watch   (live tail)`);
+    console.log(`  loom watch`);
+    console.log(`  loom stop    (kill all workers)`);
     console.log(`State dir: ${STATE_DIR}/`);
 }
 async function launchBackground(sessionId, specs, tasks, contextPath) {
@@ -118,22 +120,48 @@ async function launchBackground(sessionId, specs, tasks, contextPath) {
             workerIdx++;
             const prompt = buildWorkerPrompt(subtask, contextPath, sessionId, workerId, agentType);
             const logFile = join(STATE_DIR, 'workers', `${workerId}.log`);
+            const pidFile = join(STATE_DIR, 'workers', `${workerId}.pid`);
             await writeFile(join(STATE_DIR, 'workers', `${workerId}-prompt.md`), prompt);
+            const claudeArgs = ['--print', '-p', prompt];
+            // Only pass --dangerously-skip-permissions to roles that write files
+            if (!READ_ONLY_ROLES.has(agentType)) {
+                claudeArgs.splice(2, 0, '--dangerously-skip-permissions');
+            }
             const log = await open(logFile, 'w');
-            const child = spawn('claude', ['--print', '--dangerously-skip-permissions', '-p', prompt], {
+            const child = spawn('claude', claudeArgs, {
                 detached: true,
                 stdio: ['ignore', log.fd, log.fd],
                 env: { ...process.env, AGENTLOOM_WORKER_ID: workerId, AGENTLOOM_SESSION: sessionId },
             });
-            child.on('close', () => log.close());
+            child.on('error', async (err) => {
+                await writeFile(join(STATE_DIR, 'workers', `${workerId}-result.md`), `# Launch Error\n\nFailed to start worker: ${err.message}\n`).catch(() => { });
+                log.close().catch(() => { });
+            });
+            child.on('close', () => { log.close().catch(() => { }); });
+            if (child.pid != null) {
+                await writeFile(pidFile, String(child.pid));
+            }
             child.unref();
-            console.log(`  ✓ Worker ${workerId} (${agentType}) launched [pid ${child.pid}] → ${logFile}`);
+            console.log(`  ✓ Worker ${workerId} (${agentType})${READ_ONLY_ROLES.has(agentType) ? ' [read-only]' : ''} launched [pid ${child.pid ?? '?'}] → ${logFile}`);
         }
     }
 }
 async function launchTmux(sessionId, specs, tasks, contextPath) {
     const tmuxSession = `loom-${sessionId}`;
-    execSync(`tmux new-session -d -s ${tmuxSession} -x 220 -y 50`);
+    // Check for session name collision
+    const existing = spawnSync('tmux', ['has-session', '-t', tmuxSession], { stdio: 'ignore' });
+    if (existing.status === 0) {
+        console.error(`tmux session "${tmuxSession}" already exists. Run: tmux kill-session -t ${tmuxSession}`);
+        process.exit(1);
+    }
+    try {
+        execSync(`tmux new-session -d -s ${tmuxSession} -x 220 -y 50`);
+    }
+    catch (err) {
+        console.error(`Failed to create tmux session: ${err instanceof Error ? err.message : err}`);
+        process.exit(1);
+    }
+    await mkdir(join(STATE_DIR, 'workers'), { recursive: true });
     let workerIdx = 0;
     for (const spec of specs) {
         for (let i = 0; i < spec.count; i++) {
@@ -142,14 +170,43 @@ async function launchTmux(sessionId, specs, tasks, contextPath) {
             const agentType = tasks[workerIdx]?.agentType ?? spec.agentType;
             workerIdx++;
             const prompt = buildWorkerPrompt(subtask, contextPath, sessionId, workerId, agentType);
+            // Write prompt and a runner script to disk — avoids ALL shell escaping issues
+            const scriptFile = join(STATE_DIR, 'workers', `${workerId}-run.sh`);
+            const permFlag = READ_ONLY_ROLES.has(agentType) ? '' : '--dangerously-skip-permissions ';
+            await writeFile(join(STATE_DIR, 'workers', `${workerId}-prompt.md`), prompt);
+            await writeFile(scriptFile, [
+                '#!/bin/sh',
+                `export AGENTLOOM_WORKER_ID=${workerId}`,
+                `export AGENTLOOM_SESSION=${sessionId}`,
+                `claude --print ${permFlag}-p "$(cat '${join(STATE_DIR, 'workers', `${workerId}-prompt.md`)}')"`,
+                `echo '[worker done]'`,
+                `read`,
+            ].join('\n'));
             if (workerIdx > 1) {
-                execSync(`tmux split-window -h -t ${tmuxSession}`);
-                execSync(`tmux select-layout -t ${tmuxSession} tiled`);
+                try {
+                    execSync(`tmux split-window -h -t ${tmuxSession}`);
+                    execSync(`tmux select-layout -t ${tmuxSession} tiled`);
+                }
+                catch {
+                    // Non-fatal — continue with remaining workers even if layout fails
+                }
+            }
+            try {
+                execSync(`tmux send-keys -t ${tmuxSession} "sh '${scriptFile}'" Enter`);
             }
-            const cmd = `AGENTLOOM_WORKER_ID=${workerId} AGENTLOOM_SESSION=${sessionId} claude --print --dangerously-skip-permissions -p '${prompt.replace(/'/g, "'\"'\"'")}'; echo '[worker done]'; read`;
-            execSync(`tmux send-keys -t ${tmuxSession} "${cmd}" Enter`);
-            console.log(`  ✓ Worker ${workerId} (${agentType}) launched in tmux pane`);
+            catch (err) {
+                console.error(`  ✗ Worker ${workerId}: failed to send tmux keys: ${err instanceof Error ? err.message : err}`);
+                continue;
+            }
+            console.log(`  ✓ Worker ${workerId} (${agentType})${READ_ONLY_ROLES.has(agentType) ? ' [read-only]' : ''} launched in tmux pane`);
         }
     }
-    execSync(`tmux attach-session -t ${tmuxSession}`);
+    // Attach only in interactive terminals
+    if (process.stdout.isTTY) {
+        spawnSync('tmux', ['attach-session', '-t', tmuxSession], { stdio: 'inherit' });
+    }
+    else {
+        console.log(`\nTmux session: ${tmuxSession}`);
+        console.log(`Attach with: tmux attach-session -t ${tmuxSession}`);
+    }
 }

package/dist/commands/stop.d.ts

@@ -0,0 +1 @@
+export declare function stop(args: string[]): Promise<void>;

package/dist/commands/stop.js

@@ -0,0 +1,50 @@
+import { readFile, readdir } from 'fs/promises';
+import { join } from 'path';
+import { existsSync } from 'fs';
+import { STATE_DIR } from '../state/session.js';
+const WORKERS_DIR = join(STATE_DIR, 'workers');
+export async function stop(args) {
+    if (!existsSync(WORKERS_DIR)) {
+        console.log('No active session.');
+        return;
+    }
+    const targetId = args[0]; // optional: stop a single worker
+    const files = await readdir(WORKERS_DIR);
+    const pidFiles = files
+        .filter(f => f.endsWith('.pid'))
+        .filter(f => !targetId || f === `${targetId}.pid`)
+        .sort();
+    if (pidFiles.length === 0) {
+        console.log(targetId ? `No PID file found for ${targetId}.` : 'No worker PID files found.');
+        return;
+    }
+    let killed = 0;
+    let notFound = 0;
+    for (const pidFile of pidFiles) {
+        const workerId = pidFile.replace('.pid', '');
+        const pidPath = join(WORKERS_DIR, pidFile);
+        const pid = parseInt(await readFile(pidPath, 'utf8').catch(() => ''), 10);
+        if (!pid || isNaN(pid)) {
+            console.log(`  [${workerId}] no valid PID`);
+            continue;
+        }
+        try {
+            process.kill(pid, 'SIGTERM');
+            killed++;
+            console.log(`  [${workerId}] killed (pid ${pid})`);
+        }
+        catch (err) {
+            if (err instanceof Error && 'code' in err && err.code === 'ESRCH') {
+                notFound++;
+                console.log(`  [${workerId}] not running (pid ${pid} not found)`);
+            }
+            else {
+                console.log(`  [${workerId}] error: ${err instanceof Error ? err.message : err}`);
+            }
+        }
+    }
+    console.log(`\n${killed} killed, ${notFound} already stopped.`);
+    if (killed > 0) {
+        console.log('State preserved. Run: loom reset --force  to clear it.');
+    }
+}

package/dist/team/queue.d.ts

@@ -1,4 +1,5 @@
 import { type Task } from '../state/session.js';
+export declare function recoverStaleClaims(): Promise<number>;
 export declare function claimTask(workerId: string): Promise<Task | null>;
 export declare function completeTask(task: Task, result: string): Promise<void>;
 export declare function failTask(task: Task, error: string): Promise<void>;

package/dist/team/queue.js

@@ -1,62 +1,140 @@
 import { readdir, readFile, rename, writeFile } from 'fs/promises';
 import { join } from 'path';
-import { existsSync } from 'fs';
 import { STATE_DIR } from '../state/session.js';
 const TASKS_DIR = join(STATE_DIR, 'tasks');
+const CLAIM_TTL_MS = 30 * 60 * 1000; // 30 minutes — claimed tasks older than this are re-queued
+// Recover tasks whose worker crashed before completing.
+// Finds -claimed- files older than CLAIM_TTL_MS and renames them back to -pending.json.
+export async function recoverStaleClaims() {
+    let recovered = 0;
+    let files;
+    try {
+        files = await readdir(TASKS_DIR);
+    }
+    catch {
+        return 0;
+    }
+    const now = Date.now();
+    const claimed = files.filter(f => f.includes('-claimed-'));
+    for (const file of claimed) {
+        const filePath = join(TASKS_DIR, file);
+        try {
+            const { mtimeMs } = await import('fs/promises').then(m => m.stat(filePath));
+            if (now - mtimeMs < CLAIM_TTL_MS)
+                continue;
+            // Parse task id from filename: {id}-claimed-{workerId}.json
+            const taskId = file.split('-claimed-')[0];
+            if (!taskId)
+                continue;
+            const pendingPath = join(TASKS_DIR, `${taskId}-pending.json`);
+            // Re-read the file and reset status before writing back as pending
+            const task = JSON.parse(await readFile(filePath, 'utf8'));
+            task.status = 'pending';
+            delete task.workerId;
+            delete task.claimedAt;
+            await writeFile(pendingPath, JSON.stringify(task, null, 2));
+            await rename(filePath, pendingPath).catch(() => {
+                // If the write succeeded but rename fails (e.g. destination now exists from another
+                // recovery run), leave it — the pending file was already written
+            });
+            recovered++;
+        }
+        catch {
+            // Skip files we can't read/stat — don't crash the recovery pass
+        }
+    }
+    return recovered;
+}
 export async function claimTask(workerId) {
-    if (!existsSync(TASKS_DIR))
+    // Self-heal: recover any stale claimed tasks before scanning for pending ones
+    await recoverStaleClaims();
+    let files;
+    try {
+        files = await readdir(TASKS_DIR);
+    }
+    catch {
         return null;
-    const files = await readdir(TASKS_DIR);
+    }
     const pending = files.filter(f => f.endsWith('-pending.json'));
     for (const file of pending) {
         const oldPath = join(TASKS_DIR, file);
-        const task = JSON.parse(await readFile(oldPath, 'utf8'));
         const newFile = file.replace('-pending.json', `-claimed-${workerId}.json`);
         const newPath = join(TASKS_DIR, newFile);
-        // Atomic rename = claim. First writer wins.
         try {
-            await rename(oldPath, newPath);
+            // Prepare the updated task object BEFORE the rename.
+            // If writeFile fails after a successful rename, we rename back so the task
+            // re-enters the pending pool rather than being stuck as claimed with stale data.
+            const raw = await readFile(oldPath, 'utf8');
+            const task = JSON.parse(raw);
             task.status = 'claimed';
             task.workerId = workerId;
             task.claimedAt = new Date().toISOString();
-            await writeFile(newPath, JSON.stringify(task, null, 2));
+            const updated = JSON.stringify(task, null, 2);
+            // Atomic claim — first writer wins
+            await rename(oldPath, newPath);
+            try {
+                await writeFile(newPath, updated);
+            }
+            catch (writeErr) {
+                // Rename succeeded but write failed — roll back so the task isn't orphaned
+                await rename(newPath, oldPath).catch(() => { });
+                throw writeErr;
+            }
             return task;
         }
         catch {
-            // Another worker claimed it first — try next
+            // Another worker claimed it first (ENOENT/EPERM), or rollback — try next
             continue;
         }
     }
     return null;
 }
 export async function completeTask(task, result) {
-    const claimedFile = join(TASKS_DIR, `${task.id}-claimed-${task.workerId}.json`);
-    const doneFile = join(TASKS_DIR, `${task.id}-done-${task.workerId}.json`);
+    const workerId = task.workerId ?? 'unknown';
+    const claimedFile = join(TASKS_DIR, `${task.id}-claimed-${workerId}.json`);
+    const doneFile = join(TASKS_DIR, `${task.id}-done-${workerId}.json`);
     task.status = 'done';
     task.result = result;
     task.completedAt = new Date().toISOString();
-    await writeFile(claimedFile, JSON.stringify(task, null, 2));
-    await rename(claimedFile, doneFile);
+    try {
+        await writeFile(claimedFile, JSON.stringify(task, null, 2));
+        await rename(claimedFile, doneFile);
+    }
+    catch {
+        // If the claimed file is already gone (double-complete), write directly to done path
+        await writeFile(doneFile, JSON.stringify(task, null, 2)).catch(() => { });
+    }
 }
 export async function failTask(task, error) {
-    const claimedFile = join(TASKS_DIR, `${task.id}-claimed-${task.workerId}.json`);
-    const failedFile = join(TASKS_DIR, `${task.id}-failed-${task.workerId}.json`);
+    const workerId = task.workerId ?? 'unknown';
+    const claimedFile = join(TASKS_DIR, `${task.id}-claimed-${workerId}.json`);
+    const failedFile = join(TASKS_DIR, `${task.id}-failed-${workerId}.json`);
     task.status = 'failed';
     task.error = error;
     task.completedAt = new Date().toISOString();
-    await writeFile(claimedFile, JSON.stringify(task, null, 2));
-    await rename(claimedFile, failedFile);
+    try {
+        await writeFile(claimedFile, JSON.stringify(task, null, 2));
+        await rename(claimedFile, failedFile);
+    }
+    catch {
+        await writeFile(failedFile, JSON.stringify(task, null, 2)).catch(() => { });
+    }
 }
 export async function pendingCount() {
-    if (!existsSync(TASKS_DIR))
+    try {
+        const files = await readdir(TASKS_DIR);
+        return files.filter(f => f.endsWith('-pending.json')).length;
+    }
+    catch {
         return 0;
-    const files = await readdir(TASKS_DIR);
-    return files.filter(f => f.includes('-pending.json')).length;
+    }
 }
 export async function allDone() {
-    if (!existsSync(TASKS_DIR))
+    try {
+        const files = await readdir(TASKS_DIR);
+        return !files.some(f => f.endsWith('-pending.json') || f.includes('-claimed-'));
+    }
+    catch {
         return true;
-    const files = await readdir(TASKS_DIR);
-    const active = files.filter(f => f.includes('-pending.json') || f.includes('-claimed-'));
-    return active.length === 0;
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chuckssmith/agentloom",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "A workflow layer for Claude Code — reusable roles, persistence loops, and multi-agent crew coordination",
   "keywords": [
     "ai",