@chuckssmith/agentloom 0.4.0 → 0.6.0

package/README.md

@@ -1,9 +1,9 @@
 # agentloom
 
-A workflow layer for Claude Code. Better routing, reusable roles, and multi-agent crew coordination — built natively on what Claude Code already provides.
+A workflow layer for Claude Code — persistence loops, parallel crews, and typed agent roles, built natively on what Claude Code already provides.
 
 ```bash
-npm install -g agentloom
+npm install -g @chuckssmith/agentloom
 loom setup
 ```
 
@@ -12,10 +12,11 @@ loom setup
 ## What this is
 
 Claude Code is the execution engine. agentloom adds:
+
 - **`$grind`** — persistence loop that keeps working until a task is verified complete
-- **`$crew`** — parallel workers that decompose and execute simultaneously
+- **`$crew`** — parallel workers that decompose and execute simultaneously  
 - **`$architect`** — deep analysis mode before major decisions
-- **`loom crew`** — CLI to spawn a crew of workers from your terminal
+- **`loom crew`** — CLI to spawn and monitor a crew from your terminal
 
 It does not replace Claude Code. It wraps it.
 
@@ -24,14 +25,24 @@ It does not replace Claude Code. It wraps it.
 ## Quick start
 
 ```bash
-npm install -g agentloom
-loom setup          # installs skills, validates deps
+npm install -g @chuckssmith/agentloom
+loom setup          # installs $grind, $crew, $architect skills + validates deps
 
-# From your terminal:
+# Spawn workers from your terminal:
 loom crew "audit every API endpoint for security issues"
 loom crew 2:explore+1:code-reviewer "review the payment flow"
+loom crew --dry-run 3 "migrate the database schema"   # preview before launching
+
+# Monitor:
+loom watch           # live tail all worker logs
+loom status          # session overview + stale worker detection
+loom logs w00        # full output for one worker
+
+# After workers finish:
+loom collect         # synthesize results with Claude
+loom reset --force   # clear state for next run
 
-# Or from inside a Claude Code session:
+# Or use inside any Claude Code session:
 # $grind "port the auth module to the new interface"
 # $crew "analyze all three data pipeline stages in parallel"
 ```
@@ -40,49 +51,81 @@ loom crew 2:explore+1:code-reviewer "review the payment flow"
 
 ## Skills
 
-Install with `loom setup`. Then use inside any Claude Code session:
+Install with `loom setup`. Use inside any Claude Code session:
 
-| Skill | What it does |
-|---|---|
-| `$grind` | Persistence loop with mandatory verification gate |
-| `$crew` | Parallel workers — decomposes task, runs simultaneously, verifies |
-| `$architect` | Deep analysis — maps system, finds real problems, recommends approach |
+| Skill | Trigger | What it does |
+|---|---|---|
+| `$grind` | `$grind "<task>"` | Persistence loop — plans, executes in parallel, verifies. Won't stop until a code-reviewer subagent returns PASS |
+| `$crew` | `$crew "<task>"` | Decomposes task into independent streams, runs workers simultaneously, verifies result |
+| `$architect` | `$architect "<task>"` | Deep analysis — maps the system, finds real problems, recommends approach before you write code |
 
 ---
 
-## CLI
+## CLI reference
+
+### Spawning workers
+
+```
+loom crew "<task>"                       2 general-purpose workers (default)
+loom crew 3 "<task>"                     3 workers
+loom crew 2:explore "<task>"             2 explore-type workers
+loom crew 2:explore+1:code-reviewer "<task>"   typed crew
+loom crew --dry-run 3 "<task>"           preview decomposed subtasks, no launch
+```
+
+### Monitoring
 
 ```
-loom crew [N] "<task>"                  Spawn N general-purpose workers
-loom crew 3 "<task>"                    Spawn 3 workers
-loom crew 2:explore "<task>"            Spawn 2 Explore-type workers
-loom crew 2:explore+1:code-reviewer     Spawn typed crew
-loom status                             Show active session
-loom setup                              Install skills + validate
+loom watch                   Live tail all worker logs with color-coded output
+loom status                  Session overview, task counts, stale worker detection
+loom logs                    Summary of all workers (status + last line)
+loom logs <workerId>         Full log + result for one worker (e.g. loom logs w00)
 ```
 
-### Worker types
+### After workers finish
 
-Matches Claude Code's built-in subagent types:
+```
+loom collect                 Read worker results + synthesize summary with Claude
+loom collect --no-ai         Concatenate results without Claude synthesis
+```
 
-| Type | Best for |
-|---|---|
-| `explore` | Read-only research, codebase mapping |
-| `plan` | Architecture decisions, approach planning |
-| `code-reviewer` | Audits, security reviews, quality checks |
-| `frontend-developer` | UI and component work |
-| `general-purpose` | General implementation (default) |
+### Housekeeping
+
+```
+loom setup                   Install skills to ~/.claude/skills/, validate deps
+loom reset --force           Wipe .claude-team/ state
+```
+
+---
+
+## Worker types
+
+Each type gets a role-specific system prompt that shapes its behavior:
+
+| Type | Role | Modifies files? |
+|---|---|---|
+| `explore` | Maps code, documents structure and connections | No |
+| `plan` | Reasons about approach, produces ordered action plan | No |
+| `code-reviewer` | Audits for correctness, security, quality; assigns severity | No |
+| `frontend-developer` | UI, components, styling, client-side logic | Yes |
+| `general-purpose` | Does whatever the subtask requires (default) | Yes |
 
 ---
 
 ## State directory
 
+Session state lives in `.claude-team/` (gitignored):
+
 ```
-.agentloom/
-  tasks/          Task queue — workers claim atomically
-  workers/        Worker status and results
-  context/        Shared context snapshots
-  session.json    Active session metadata
+.claude-team/
+  session.json          Active session metadata
+  context/              Shared context snapshots (workers read + append)
+  tasks/                Task queue — workers claim atomically via file rename
+  workers/
+    w00.log             Live stdout from worker 00
+    w00-prompt.md       Prompt sent to worker 00
+    w00-result.md       Result summary written by worker 00 on completion
+  summary.md            Final synthesis from loom collect
 ```
 
 ---
@@ -90,8 +133,8 @@ Matches Claude Code's built-in subagent types:
 ## Requirements
 
 - Node.js 20+
-- Claude Code CLI (`claude`)
-- tmux (optional — used for crew mode on Mac/Linux; falls back to background processes on WSL/Windows)
+- Claude Code CLI (`claude`) — authenticated
+- tmux (optional — used on Mac/Linux; falls back to background processes on Windows/WSL)
 
 ---
 

package/dist/cli.js

@@ -5,6 +5,8 @@ import { status } from './commands/status.js';
 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
@@ -14,13 +16,23 @@ Usage:
   loom crew [N] "<task>"                Spawn N parallel workers on a task
   loom crew 2:explore "<task>"          Spawn typed workers (explore/plan/code-reviewer)
   loom crew --dry-run [N] "<task>"      Preview decomposed subtasks without launching
-  loom status                           Show active crew session
+  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
   loom collect                          Synthesize worker results into a summary
   loom collect --no-ai                  Collect results without Claude synthesis
   loom reset --force                    Clear all session state
 
+Agent types (use with crew):
+  explore          Read-only research and mapping
+  plan             Architecture and approach planning
+  code-reviewer    Audit for correctness, security, quality
+  frontend-developer  UI and component work
+  general-purpose  Default — does whatever the subtask requires
+
 Modes (use $grind or $crew inside a Claude Code session):
   $grind   Persistence loop — keeps working until verified complete
   $crew    Parallel workers — decompose and execute simultaneously
@@ -31,8 +43,8 @@ Examples:
   loom crew 3 "audit every API endpoint for security issues"
   loom crew 2:explore+1:code-reviewer "review the payment flow"
   loom crew --dry-run 3 "migrate the database schema"
-  loom logs
-  loom logs w00
+  loom watch
+  loom collect
 `;
 switch (command) {
     case 'setup':
@@ -41,6 +53,9 @@ switch (command) {
     case 'crew':
         await crew(args);
         break;
+    case 'watch':
+        await watch(args);
+        break;
     case 'status':
         await status();
         break;
@@ -50,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,6 +13,54 @@ const hasTmux = () => {
     }
 };
 const isWSL = () => process.platform === 'linux' && !!process.env.WSL_DISTRO_NAME;
+// 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, 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, 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, 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`,
+    'frontend-developer': `Your role is FRONTEND DEVELOPER.
+- Focus on UI, components, styling, and client-side logic
+- Follow existing conventions in the codebase
+- Write clean, accessible code`,
+    'general-purpose': `Your role is GENERAL PURPOSE WORKER.
+- Do whatever the subtask requires — research, implementation, or both
+- Use all tools available to you`,
+};
+function buildWorkerPrompt(subtask, contextPath, sessionId, workerId, agentType) {
+    const resultFile = join(STATE_DIR, 'workers', `${workerId}-result.md`);
+    const roleInstructions = AGENT_ROLE[agentType] ?? AGENT_ROLE['general-purpose'];
+    return `You are worker ${workerId} in an agentloom crew session (${sessionId}).
+
+${roleInstructions}
+
+## Your assigned subtask
+
+"${subtask}"
+
+## Protocol
+
+1. Read the shared context: ${contextPath}
+2. Do the work thoroughly using all tools available to you
+3. Append key findings to the context file so other workers can see them
+4. When done, write a result summary to: ${resultFile}
+   Format: brief markdown — what you did, what you found, any blockers
+
+## Rules
+- Stay focused on your assigned subtask and role
+- Do not stop until your subtask is complete or you have hit a genuine blocker
+
+Begin now.`;
+}
 export async function crew(args) {
     if (args.length === 0) {
         console.error('Usage: loom crew [--dry-run] [N] "<task>"');
@@ -41,86 +89,124 @@ 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()) {
-        await launchTmux(session.id, totalWorkers, specs, tasks.map(t => t.description), contextPath);
+    if (useTmux) {
+        await launchTmux(session.id, specs, tasks, contextPath);
     }
     else {
-        await launchBackground(session.id, specs, tasks.map(t => t.description), contextPath);
+        await launchBackground(session.id, specs, tasks, contextPath);
     }
     console.log(`\nWorkers launched. Monitor with:`);
     console.log(`  loom status`);
-    console.log(`  loom logs`);
+    console.log(`  loom watch`);
+    console.log(`  loom stop    (kill all workers)`);
     console.log(`State dir: ${STATE_DIR}/`);
 }
-function buildWorkerPrompt(subtask, contextPath, sessionId, workerId) {
-    const resultFile = join(STATE_DIR, 'workers', `${workerId}-result.md`);
-    return `You are worker ${workerId} in an agentloom crew session (${sessionId}).
-
-Your assigned subtask: "${subtask}"
-
-## Protocol
-
-1. Read the shared context: ${contextPath}
-2. Do the work thoroughly using all tools available to you
-3. When done, write a result summary to: ${resultFile}
-   Format: brief markdown — what you did, what you found, any blockers
-
-## Rules
-- Focus only on your assigned subtask
-- Write findings to the context file (${contextPath}) so other workers can see them
-- Do not stop until your subtask is complete or you have hit a genuine blocker
-
-Begin now.`;
-}
-async function launchBackground(sessionId, specs, subtasks, contextPath) {
+async function launchBackground(sessionId, specs, tasks, contextPath) {
     await mkdir(join(STATE_DIR, 'workers'), { recursive: true });
     let workerIdx = 0;
     for (const spec of specs) {
         for (let i = 0; i < spec.count; i++) {
             const workerId = `w${String(workerIdx).padStart(2, '0')}`;
-            const subtask = subtasks[workerIdx] ?? subtasks[0] ?? '';
+            const subtask = tasks[workerIdx]?.description ?? tasks[0]?.description ?? '';
+            const agentType = tasks[workerIdx]?.agentType ?? spec.agentType;
             workerIdx++;
-            const prompt = buildWorkerPrompt(subtask, contextPath, sessionId, workerId);
+            const prompt = buildWorkerPrompt(subtask, contextPath, sessionId, workerId, agentType);
             const logFile = join(STATE_DIR, 'workers', `${workerId}.log`);
-            // Write prompt to disk for inspection
+            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} (${spec.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, count, specs, subtasks, contextPath) {
+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++) {
             const workerId = `w${String(workerIdx).padStart(2, '0')}`;
-            const subtask = subtasks[workerIdx] ?? subtasks[0] ?? '';
+            const subtask = tasks[workerIdx]?.description ?? tasks[0]?.description ?? '';
+            const agentType = tasks[workerIdx]?.agentType ?? spec.agentType;
             workerIdx++;
-            const prompt = buildWorkerPrompt(subtask, contextPath, sessionId, workerId);
+            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`);
+            }
+            catch (err) {
+                console.error(`  ✗ Worker ${workerId}: failed to send tmux keys: ${err instanceof Error ? err.message : err}`);
+                continue;
             }
-            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} (${spec.agentType}) launched in tmux pane`);
+            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/status.js

@@ -1,6 +1,8 @@
-import { readSession, readTasks, readWorkers } from '../state/session.js';
-import { existsSync } from 'fs';
-import { STATE_DIR } from '../state/session.js';
+import { readSession, readTasks, STATE_DIR } from '../state/session.js';
+import { existsSync, statSync } from 'fs';
+import { join } from 'path';
+import { readdir } from 'fs/promises';
+const STALE_THRESHOLD_MS = 10 * 60 * 1000; // 10 minutes with no log growth = stale
 export async function status() {
     if (!existsSync(STATE_DIR)) {
         console.log('No active session. Run: loom crew "<task>"');
@@ -12,7 +14,6 @@ export async function status() {
         return;
     }
     const tasks = await readTasks();
-    const workers = await readWorkers();
     const pending = tasks.filter(t => t.status === 'pending').length;
     const claimed = tasks.filter(t => t.status === 'claimed').length;
     const done = tasks.filter(t => t.status === 'done').length;
@@ -22,13 +23,44 @@ export async function status() {
     console.log(`Task:    ${session.description}`);
     console.log(`Started: ${session.createdAt}`);
     console.log(`\nTasks:   ${pending} pending  ${claimed} active  ${done} done  ${failed} failed`);
-    console.log(`Workers: ${workers.length} (${session.workerCount} total)`);
-    if (workers.length > 0) {
-        console.log('\nWorker status:');
-        for (const w of workers) {
-            const task = w.currentTaskId ? tasks.find(t => t.id === w.currentTaskId) : null;
-            const desc = task ? `  → ${task.description.slice(0, 60)}` : '';
-            console.log(`  [${w.id}] ${w.status}${desc}`);
+    // Worker status from log files
+    const workersDir = join(STATE_DIR, 'workers');
+    if (!existsSync(workersDir))
+        return;
+    const files = await readdir(workersDir);
+    const logFiles = files.filter(f => f.endsWith('.log')).sort();
+    if (logFiles.length === 0)
+        return;
+    console.log(`\nWorkers: ${logFiles.length}`);
+    const now = Date.now();
+    for (const logFile of logFiles) {
+        const workerId = logFile.replace('.log', '');
+        const logPath = join(workersDir, logFile);
+        const resultPath = join(workersDir, `${workerId}-result.md`);
+        const hasResult = existsSync(resultPath);
+        if (hasResult) {
+            console.log(`  [${workerId}] done ✓`);
+            continue;
+        }
+        // Check if log is growing (worker is alive) or stale
+        const logStat = statSync(logPath);
+        const msSinceWrite = now - logStat.mtimeMs;
+        const isStale = msSinceWrite > STALE_THRESHOLD_MS;
+        const logSize = logStat.size;
+        if (logSize === 0) {
+            console.log(`  [${workerId}] starting...`);
         }
+        else if (isStale) {
+            const mins = Math.round(msSinceWrite / 60000);
+            console.log(`  [${workerId}] STALE — no activity for ${mins}m (log: ${logPath})`);
+        }
+        else {
+            const secs = Math.round(msSinceWrite / 1000);
+            console.log(`  [${workerId}] running  (last activity ${secs}s ago)`);
+        }
+    }
+    const allDone = logFiles.every(f => existsSync(join(workersDir, f.replace('.log', '-result.md'))));
+    if (allDone && logFiles.length > 0) {
+        console.log(`\nAll workers done. Run: loom collect`);
     }
 }

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/commands/watch.d.ts

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

package/dist/commands/watch.js

@@ -0,0 +1,69 @@
+import { readdir, stat, readFile } 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');
+const POLL_MS = 800;
+// A rotating set of ANSI colors for worker prefixes
+const COLORS = ['\x1b[36m', '\x1b[33m', '\x1b[35m', '\x1b[32m', '\x1b[34m', '\x1b[31m'];
+const RESET = '\x1b[0m';
+const DIM = '\x1b[2m';
+export async function watch(_args) {
+    if (!existsSync(WORKERS_DIR)) {
+        console.log('No active session. Run: loom crew "<task>"');
+        process.exit(1);
+    }
+    console.log(`${DIM}Watching worker logs. Ctrl+C to stop.${RESET}\n`);
+    // Track how many bytes we've read from each log file
+    const offsets = {};
+    const seen = new Set();
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        if (!existsSync(WORKERS_DIR))
+            break;
+        const files = await readdir(WORKERS_DIR);
+        const logFiles = files.filter(f => f.endsWith('.log')).sort();
+        for (const logFile of logFiles) {
+            const workerId = logFile.replace('.log', '');
+            const color = COLORS[parseInt(workerId.replace('w', ''), 10) % COLORS.length] ?? COLORS[0];
+            const filePath = join(WORKERS_DIR, logFile);
+            if (!seen.has(workerId)) {
+                seen.add(workerId);
+                const resultExists = existsSync(join(WORKERS_DIR, `${workerId}-result.md`));
+                console.log(`${color}[${workerId}]${RESET} ${DIM}started${resultExists ? ' (already done)' : ''}${RESET}`);
+            }
+            const currentSize = (await stat(filePath)).size;
+            const offset = offsets[workerId] ?? 0;
+            if (currentSize > offset) {
+                const buf = await readFile(filePath);
+                const newContent = buf.slice(offset).toString('utf8');
+                offsets[workerId] = currentSize;
+                const lines = newContent.split('\n');
+                for (const line of lines) {
+                    if (line.trim()) {
+                        process.stdout.write(`${color}[${workerId}]${RESET} ${line}\n`);
+                    }
+                }
+            }
+            // Check if worker just finished (result file appeared)
+            const resultPath = join(WORKERS_DIR, `${workerId}-result.md`);
+            const doneKey = `${workerId}-done`;
+            if (existsSync(resultPath) && !seen.has(doneKey)) {
+                seen.add(doneKey);
+                console.log(`${color}[${workerId}]${RESET} ${DIM}✓ result written${RESET}`);
+            }
+        }
+        // Exit when all known workers have results
+        if (logFiles.length > 0) {
+            const allDone = logFiles.every(f => {
+                const id = f.replace('.log', '');
+                return existsSync(join(WORKERS_DIR, `${id}-result.md`));
+            });
+            if (allDone) {
+                console.log(`\n${DIM}All workers done. Run: loom collect${RESET}`);
+                break;
+            }
+        }
+        await new Promise(resolve => setTimeout(resolve, POLL_MS));
+    }
+}

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.4.0",
+  "version": "0.6.0",
   "description": "A workflow layer for Claude Code — reusable roles, persistence loops, and multi-agent crew coordination",
   "keywords": [
     "ai",