@chuckssmith/agentloom 0.8.0 → 1.0.0

package/README.md

@@ -14,9 +14,9 @@ loom setup
 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 and monitor a crew from your terminal
+- **`loom crew`** — CLI to spawn, monitor, and collect results from a crew
 
 It does not replace Claude Code. It wraps it.
 
@@ -27,19 +27,24 @@ It does not replace Claude Code. It wraps it.
 ```bash
 npm install -g @chuckssmith/agentloom
 loom setup          # installs $grind, $crew, $architect skills + validates deps
+loom init           # create .loomrc config in current project (optional)
 
-# Spawn workers from your terminal:
+# Spawn workers:
 loom crew "audit every API endpoint for security issues"
+loom crew 3 "refactor the auth module"
 loom crew 2:explore+1:code-reviewer "review the payment flow"
-loom crew --dry-run 3 "migrate the database schema"   # preview before launching
+
+# Useful flags:
+loom crew --dry-run 3 "migrate the schema"   # preview decomposed subtasks first
+loom crew --watch "audit the codebase"       # launch + immediately tail logs
+loom crew --serial 3 "build the pipeline"    # run workers sequentially
 
 # Monitor:
-loom watch           # live tail all worker logs
-loom status          # session overview + stale worker detection
-loom logs w00        # full output for one worker
+loom watch           # live color-coded tail of all worker logs
+loom status          # session overview + per-worker liveness (PID-aware)
 
 # After workers finish:
-loom collect         # synthesize results with Claude
+loom collect         # synthesize results with Claude into summary.md
 loom reset --force   # clear state for next run
 
 # Or use inside any Claude Code session:
@@ -53,46 +58,58 @@ loom reset --force   # clear state for next run
 
 Install with `loom setup`. Use inside any Claude Code session:
 
-| 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 |
+| Skill | What it does |
+|---|---|
+| `$grind` | Persistence loop — plans, executes in parallel, verifies. Won't stop until a code-reviewer returns PASS |
+| `$crew` | Decomposes task into independent streams, runs workers simultaneously, verifies result |
+| `$architect` | Deep analysis — maps the system, finds real problems, recommends approach |
 
 ---
 
 ## CLI reference
 
+### Setup
+
+```
+loom init            Create .loomrc in current directory (see Configuration below)
+loom setup           Install skills to ~/.claude/skills/, validate claude + tmux
+```
+
 ### 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
+loom crew "<task>"                           Use defaults from .loomrc (or 2 general-purpose)
+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
+
+Flags (combinable):
+  --dry-run    Preview AI-decomposed subtasks without launching
+  --watch      Launch then immediately tail all worker logs
+  --serial     Run workers sequentially — each worker reads prior results from context file
 ```
 
 ### Monitoring
 
 ```
-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 watch                   Live color-coded tail (auto-exits when all workers done)
+loom status                  Session overview, task counts, per-worker liveness
+loom logs                    Summary: all workers, status, last log line
 loom logs <workerId>         Full log + result for one worker (e.g. loom logs w00)
 ```
 
 ### After workers finish
 
 ```
-loom collect                 Read worker results + synthesize summary with Claude
+loom collect                 Read worker results + synthesize with Claude into .claude-team/summary.md
 loom collect --no-ai         Concatenate results without Claude synthesis
 ```
 
 ### Housekeeping
 
 ```
-loom setup                   Install skills to ~/.claude/skills/, validate deps
+loom stop                    Kill all background workers (SIGTERM)
+loom stop <workerId>         Kill one worker
 loom reset --force           Wipe .claude-team/ state
 ```
 
@@ -100,7 +117,7 @@ loom reset --force           Wipe .claude-team/ state
 
 ## Worker types
 
-Each type gets a role-specific system prompt that shapes its behavior:
+Each type gets a role-specific system prompt. Read-only roles do **not** receive `--dangerously-skip-permissions`.
 
 | Type | Role | Modifies files? |
 |---|---|---|
@@ -112,20 +129,45 @@ Each type gets a role-specific system prompt that shapes its behavior:
 
 ---
 
+## Configuration
+
+Run `loom init` to create a `.loomrc` in your project directory:
+
+```json
+{
+  "workers": 2,
+  "agentType": "general-purpose",
+  "claimTtlMinutes": 30,
+  "staleMinutes": 10
+}
+```
+
+| Key | Default | Description |
+|---|---|---|
+| `workers` | 2 | Default worker count when none specified |
+| `agentType` | `general-purpose` | Default agent type when none specified |
+| `claimTtlMinutes` | 30 | Minutes before a crashed worker's claimed task is re-queued |
+| `staleMinutes` | 10 | Minutes of dead-pid + log silence before worker is flagged STALE |
+
+---
+
 ## State directory
 
 Session state lives in `.claude-team/` (gitignored):
 
 ```
 .claude-team/
-  session.json          Active session metadata
-  context/              Shared context snapshots (workers read + append)
-  tasks/                Task queue — workers claim atomically via file rename
+  session.json              Active session metadata
+  context/                  Shared context snapshots (workers read + append)
+  tasks/                    Task queue — workers claim atomically via file rename
+                            Stale claimed tasks (>claimTtlMinutes) auto re-queued
   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
+    w00.log                 Live stdout from worker 00
+    w00.pid                 PID of worker 00 process
+    w00-prompt.md           Prompt sent to worker 00
+    w00-result.md           Result summary written by worker 00 on completion
+    w00-run.mjs             Node.js runner script (tmux mode)
+  summary.md                Final synthesis from loom collect
 ```
 
 ---
@@ -134,7 +176,7 @@ Session state lives in `.claude-team/` (gitignored):
 
 - Node.js 20+
 - Claude Code CLI (`claude`) — authenticated
-- tmux (optional — used on Mac/Linux; falls back to background processes on Windows/WSL)
+- tmux (optional — used on Mac/Linux interactive terminals; background processes used on Windows/WSL/CI)
 
 ---
 

package/dist/cli.js

@@ -7,16 +7,19 @@ import { collect } from './commands/collect.js';
 import { reset } from './commands/reset.js';
 import { watch } from './commands/watch.js';
 import { stop } from './commands/stop.js';
+import { init } from './commands/init.js';
 const [, , command, ...args] = process.argv;
 const usage = `
 agentloom (loom) — workflow layer for Claude Code
 
 Usage:
+  loom init                             Create .loomrc config in current directory
   loom setup                            Install skills and initialize state dir
   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 crew --serial [N] "<task>"       Run workers sequentially (each sees prior results)
+  loom crew --watch [N] "<task>"        Launch workers and immediately tail logs
   loom watch                            Live tail all worker logs (Ctrl+C to stop)
   loom stop                             Kill all background workers (SIGTERM)
   loom stop <workerId>                  Kill one worker
@@ -48,6 +51,9 @@ Examples:
   loom collect
 `;
 switch (command) {
+    case 'init':
+        await init(args);
+        break;
     case 'setup':
         await setup();
         break;

package/dist/commands/collect.js

@@ -2,7 +2,7 @@ import { readFile, readdir, writeFile } from 'fs/promises';
 import { join } from 'path';
 import { existsSync } from 'fs';
 import { spawnSync } from 'child_process';
-import { STATE_DIR, readSession, readTasks } from '../state/session.js';
+import { STATE_DIR, readSession } from '../state/session.js';
 const WORKERS_DIR = join(STATE_DIR, 'workers');
 export async function collect(args) {
     if (!existsSync(WORKERS_DIR)) {
@@ -10,7 +10,6 @@ export async function collect(args) {
         return;
     }
     const session = await readSession();
-    const tasks = await readTasks();
     const files = await readdir(WORKERS_DIR);
     const resultFiles = files.filter(f => f.endsWith('-result.md')).sort();
     if (resultFiles.length === 0) {
@@ -34,7 +33,7 @@ export async function collect(args) {
     const synthesize = !args.includes('--no-ai');
     let synthesis = '';
     if (synthesize) {
-        console.log('\nSynthesizing with Claude...');
+        console.log('\nSynthesizing with Claude... (may take up to 60s)');
         const prompt = `You are summarizing the results of a multi-agent crew that worked on this task:
 
 "${taskDesc}"

package/dist/commands/crew.js

@@ -4,6 +4,8 @@ import { join } from 'path';
 import { existsSync } from 'fs';
 import { parseWorkerSpec, initSession, writeContextSnapshot, decomposeTasks, } from '../team/orchestrator.js';
 import { STATE_DIR } from '../state/session.js';
+import { watch } from './watch.js';
+import { loadConfig } from '../config.js';
 const hasTmux = () => {
     try {
         execSync('tmux -V', { stdio: 'ignore' });
@@ -69,8 +71,11 @@ export async function crew(args) {
     }
     const dryRun = args.includes('--dry-run');
     const serial = args.includes('--serial');
-    const filteredArgs = args.filter(a => a !== '--dry-run' && a !== '--serial');
-    const { specs, task } = parseWorkerSpec(filteredArgs);
+    const watchAfter = args.includes('--watch');
+    const filteredArgs = args.filter(a => !['--dry-run', '--serial', '--watch'].includes(a));
+    const config = await loadConfig();
+    const forcePermissions = config.dangerouslySkipPermissions === true;
+    const { specs, task } = parseWorkerSpec(filteredArgs, config.workers, config.agentType);
     const totalWorkers = specs.reduce((sum, s) => sum + s.count, 0);
     const slug = task.slice(0, 30).toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9-]/g, '');
     console.log(`\nagentloom crew`);
@@ -95,23 +100,28 @@ export async function crew(args) {
     const mode = serial ? 'serial' : useTmux ? 'tmux' : 'background processes';
     console.log(`Mode:    ${mode}\n`);
     const session = await initSession(task, totalWorkers);
-    const contextPath = await writeContextSnapshot(slug, task);
+    const contextPath = await writeContextSnapshot(slug, session.id, task);
     const tasks = await decomposeTasks(task, specs);
     console.log(`Session: ${session.id}`);
     console.log(`Tasks:   ${tasks.length} created`);
     console.log(`Context: ${contextPath}\n`);
     if (serial) {
-        await launchSerial(session.id, specs, tasks, contextPath);
+        await launchSerial(session.id, specs, tasks, contextPath, forcePermissions);
         console.log(`\nAll workers finished. Run: loom collect`);
     }
     else if (useTmux) {
-        await launchTmux(session.id, specs, tasks, contextPath);
+        await launchTmux(session.id, specs, tasks, contextPath, forcePermissions);
         console.log(`\nWorkers launched. Monitor with:`);
         console.log(`  loom status`);
         console.log(`  loom stop    (kill all workers)`);
     }
     else {
-        await launchBackground(session.id, specs, tasks, contextPath);
+        await launchBackground(session.id, specs, tasks, contextPath, forcePermissions);
+        if (watchAfter) {
+            console.log();
+            await watch([]);
+            return;
+        }
         console.log(`\nWorkers launched. Monitor with:`);
         console.log(`  loom status`);
         console.log(`  loom watch`);
@@ -119,7 +129,7 @@ export async function crew(args) {
     }
     console.log(`State dir: ${STATE_DIR}/`);
 }
-async function launchSerial(sessionId, specs, tasks, contextPath) {
+async function launchSerial(sessionId, specs, tasks, contextPath, forcePermissions = false) {
     await mkdir(join(STATE_DIR, 'workers'), { recursive: true });
     let workerIdx = 0;
     for (const spec of specs) {
@@ -135,7 +145,7 @@ async function launchSerial(sessionId, specs, tasks, contextPath) {
             console.log(`  → Worker ${workerId} (${agentType}) starting...`);
             const claudeArgs = [
                 '--print',
-                ...(!READ_ONLY_ROLES.has(agentType) ? ['--dangerously-skip-permissions'] : []),
+                ...(forcePermissions || !READ_ONLY_ROLES.has(agentType) ? ['--dangerously-skip-permissions'] : []),
                 '-p',
                 prompt,
             ];
@@ -164,7 +174,7 @@ async function launchSerial(sessionId, specs, tasks, contextPath) {
         }
     }
 }
-async function launchBackground(sessionId, specs, tasks, contextPath) {
+async function launchBackground(sessionId, specs, tasks, contextPath, forcePermissions = false) {
     await mkdir(join(STATE_DIR, 'workers'), { recursive: true });
     let workerIdx = 0;
     for (const spec of specs) {
@@ -180,7 +190,7 @@ async function launchBackground(sessionId, specs, tasks, contextPath) {
             // Build args declaratively — no positional splicing
             const claudeArgs = [
                 '--print',
-                ...(!READ_ONLY_ROLES.has(agentType) ? ['--dangerously-skip-permissions'] : []),
+                ...(forcePermissions || !READ_ONLY_ROLES.has(agentType) ? ['--dangerously-skip-permissions'] : []),
                 '-p',
                 prompt,
             ];
@@ -203,7 +213,7 @@ async function launchBackground(sessionId, specs, tasks, contextPath) {
         }
     }
 }
-async function launchTmux(sessionId, specs, tasks, contextPath) {
+async function launchTmux(sessionId, specs, tasks, contextPath, forcePermissions = false) {
     const tmuxSession = `loom-${sessionId}`;
     // Check for session name collision
     const existing = spawnSync('tmux', ['has-session', '-t', tmuxSession], { stdio: 'ignore' });
@@ -237,7 +247,7 @@ async function launchTmux(sessionId, specs, tasks, contextPath) {
                 `process.env.AGENTLOOM_WORKER_ID = ${JSON.stringify(workerId)}`,
                 `process.env.AGENTLOOM_SESSION = ${JSON.stringify(sessionId)}`,
                 `const prompt = readFileSync(${JSON.stringify(promptFile)}, 'utf8')`,
-                `const args = ['--print', ${!READ_ONLY_ROLES.has(agentType) ? `'--dangerously-skip-permissions', ` : ``}'${'-p'}', prompt]`,
+                `const args = ['--print', ${(forcePermissions || !READ_ONLY_ROLES.has(agentType)) ? `'--dangerously-skip-permissions', ` : ``}'${'-p'}', prompt]`,
                 `const r = spawnSync('claude', args, { stdio: 'inherit' })`,
                 `console.log('[worker done]')`,
                 `process.exit(r.status ?? 0)`,

package/dist/commands/init.d.ts

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

package/dist/commands/init.js

@@ -0,0 +1,4 @@
+import { initConfig } from '../config.js';
+export async function init(_args) {
+    await initConfig();
+}

package/dist/commands/logs.js

@@ -1,5 +1,5 @@
 import { readFile, readdir } from 'fs/promises';
-import { join } from 'path';
+import { join, basename } from 'path';
 import { existsSync } from 'fs';
 import { STATE_DIR } from '../state/session.js';
 const WORKERS_DIR = join(STATE_DIR, 'workers');
@@ -8,7 +8,9 @@ export async function logs(args) {
         console.log('No worker logs found. Run: loom crew "<task>"');
         return;
     }
-    const workerId = args[0];
+    // Sanitize workerId to prevent path traversal
+    const rawId = args[0];
+    const workerId = rawId ? basename(rawId) : undefined;
     if (workerId) {
         // Show log for a specific worker
         const logFile = join(WORKERS_DIR, `${workerId}.log`);

package/dist/commands/reset.js

@@ -1,6 +1,8 @@
-import { rm } from 'fs/promises';
+import { rm, readdir, readFile } from 'fs/promises';
 import { existsSync } from 'fs';
+import { join } from 'path';
 import { STATE_DIR } from '../state/session.js';
+const WORKERS_DIR = join(STATE_DIR, 'workers');
 export async function reset(args) {
     if (!existsSync(STATE_DIR)) {
         console.log('Nothing to reset.');
@@ -8,10 +10,33 @@ export async function reset(args) {
     }
     const force = args.includes('--force') || args.includes('-f');
     if (!force) {
-        console.log(`This will delete all session state in ${STATE_DIR}/`);
+        console.log(`This will kill running workers and delete all session state in ${STATE_DIR}/`);
         console.log('Run with --force to confirm: loom reset --force');
         return;
     }
+    // Kill any live workers before deleting their PID files
+    if (existsSync(WORKERS_DIR)) {
+        try {
+            const files = await readdir(WORKERS_DIR);
+            const pidFiles = files.filter(f => f.endsWith('.pid'));
+            for (const pidFile of pidFiles) {
+                const pid = parseInt(await readFile(join(WORKERS_DIR, pidFile), 'utf8').catch(() => ''), 10);
+                if (!isNaN(pid)) {
+                    try {
+                        process.kill(pid, 'SIGTERM');
+                        const workerId = pidFile.replace('.pid', '');
+                        console.log(`  killed worker ${workerId} (pid ${pid})`);
+                    }
+                    catch {
+                        // Process already dead — ignore
+                    }
+                }
+            }
+        }
+        catch {
+            // Workers dir unreadable — proceed with delete anyway
+        }
+    }
     await rm(STATE_DIR, { recursive: true, force: true });
     console.log(`✓ Session state cleared (${STATE_DIR}/)`);
 }

package/dist/commands/setup.js

@@ -19,7 +19,14 @@ export async function setup() {
     }
     // 2. Install skills
     await mkdir(SKILLS_DEST, { recursive: true });
-    const skills = await readdir(SKILLS_SRC);
+    let skills;
+    try {
+        skills = await readdir(SKILLS_SRC);
+    }
+    catch {
+        console.error('✗ Could not find skills directory — package may be misconfigured');
+        process.exit(1);
+    }
     for (const skill of skills.filter(f => f.endsWith('.md'))) {
         const dest = join(SKILLS_DEST, skill);
         await copyFile(join(SKILLS_SRC, skill), dest);

package/dist/commands/status.js

@@ -2,7 +2,7 @@ import { readSession, readTasks, STATE_DIR } from '../state/session.js';
 import { existsSync, statSync } from 'fs';
 import { join } from 'path';
 import { readdir, readFile } from 'fs/promises';
-const STALE_THRESHOLD_MS = 10 * 60 * 1000; // 10 min with no log growth AND no live PID = stale
+import { loadConfig } from '../config.js';
 function isProcessAlive(pid) {
     try {
         process.kill(pid, 0);
@@ -40,6 +40,8 @@ export async function status() {
     const logFiles = files.filter(f => f.endsWith('.log')).sort();
     if (logFiles.length === 0)
         return;
+    const config = await loadConfig();
+    const staleThresholdMs = config.staleMinutes * 60 * 1000;
     console.log(`\nWorkers: ${logFiles.length}`);
     const now = Date.now();
     for (const logFile of logFiles) {
@@ -72,7 +74,7 @@ export async function status() {
             const secs = Math.round(msSinceWrite / 1000);
             console.log(`  [${workerId}] running  (pid alive, last log ${secs}s ago)`);
         }
-        else if (msSinceWrite > STALE_THRESHOLD_MS) {
+        else if (msSinceWrite > staleThresholdMs) {
             const mins = Math.round(msSinceWrite / 60000);
             console.log(`  [${workerId}] STALE — pid dead, no log activity for ${mins}m`);
         }

package/dist/commands/stop.js

@@ -45,6 +45,9 @@ export async function stop(args) {
     }
     console.log(`\n${killed} killed, ${notFound} already stopped.`);
     if (killed > 0) {
+        if (process.platform === 'win32') {
+            console.log('  note: SIGTERM on Windows is a force kill (TerminateProcess)');
+        }
         console.log('State preserved. Run: loom reset --force  to clear it.');
     }
 }

package/dist/commands/watch.js

@@ -4,24 +4,39 @@ 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 STALE_TIMEOUT_MS = 15 * 60 * 1000; // 15 min no log growth + dead PID = give up
 const COLORS = ['\x1b[36m', '\x1b[33m', '\x1b[35m', '\x1b[32m', '\x1b[34m', '\x1b[31m'];
 const RESET = '\x1b[0m';
 const DIM = '\x1b[2m';
+const YELLOW = '\x1b[33m';
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 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 lastGrowth = {};
     const seen = new Set();
-    // eslint-disable-next-line no-constant-condition
     while (true) {
         if (!existsSync(WORKERS_DIR))
             break;
-        const files = await readdir(WORKERS_DIR);
+        let files;
+        try {
+            files = await readdir(WORKERS_DIR);
+        }
+        catch {
+            break;
+        }
         const logFiles = files.filter(f => f.endsWith('.log')).sort();
         for (const logFile of logFiles) {
             const workerId = logFile.replace('.log', '');
@@ -32,20 +47,27 @@ export async function watch(_args) {
                 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;
+            // Guard stat — file may be deleted mid-poll (e.g. loom reset)
+            let currentSize;
+            try {
+                currentSize = (await stat(filePath)).size;
+            }
+            catch {
+                continue;
+            }
             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`);
+                lastGrowth[workerId] = Date.now();
+                const buf = await readFile(filePath).catch(() => null);
+                if (buf) {
+                    const newContent = buf.slice(offset).toString('utf8');
+                    offsets[workerId] = currentSize;
+                    for (const line of newContent.split('\n')) {
+                        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)) {
@@ -55,14 +77,35 @@ export async function watch(_args) {
         }
         // 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) {
+            const workersDone = logFiles.map(f => f.replace('.log', '')).filter(id => existsSync(join(WORKERS_DIR, `${id}-result.md`)));
+            if (workersDone.length === logFiles.length) {
                 console.log(`\n${DIM}All workers done. Run: loom collect${RESET}`);
                 break;
             }
+            // Stale detection: workers with no result, dead PID, and log silent for >15min
+            const now = Date.now();
+            const staleWorkers = [];
+            for (const logFile of logFiles) {
+                const id = logFile.replace('.log', '');
+                if (existsSync(join(WORKERS_DIR, `${id}-result.md`)))
+                    continue;
+                const pidPath = join(WORKERS_DIR, `${id}.pid`);
+                let pidAlive = false;
+                if (existsSync(pidPath)) {
+                    const pid = parseInt(await readFile(pidPath, 'utf8').catch(() => ''), 10);
+                    if (!isNaN(pid))
+                        pidAlive = isProcessAlive(pid);
+                }
+                const sinceGrowth = now - (lastGrowth[id] ?? now);
+                if (!pidAlive && sinceGrowth > STALE_TIMEOUT_MS) {
+                    staleWorkers.push(id);
+                }
+            }
+            if (staleWorkers.length > 0 && staleWorkers.length + workersDone.length === logFiles.length) {
+                console.log(`\n${YELLOW}Workers stalled (dead PID, no output for 15min): ${staleWorkers.join(', ')}${RESET}`);
+                console.log(`${DIM}Run: loom logs <workerId>  to inspect. loom collect to gather what's available.${RESET}`);
+                break;
+            }
         }
         await new Promise(resolve => setTimeout(resolve, POLL_MS));
     }

package/dist/config.d.ts

@@ -0,0 +1,10 @@
+export declare const LOOMRC = ".loomrc";
+export type LoomConfig = {
+    workers?: number;
+    agentType?: string;
+    claimTtlMinutes?: number;
+    staleMinutes?: number;
+    dangerouslySkipPermissions?: boolean;
+};
+export declare function loadConfig(): Promise<Required<LoomConfig>>;
+export declare function initConfig(): Promise<void>;

package/dist/config.js

@@ -0,0 +1,44 @@
+import { readFile, writeFile } from 'fs/promises';
+import { existsSync } from 'fs';
+export const LOOMRC = '.loomrc';
+const DEFAULTS = {
+    workers: 2,
+    agentType: 'general-purpose',
+    claimTtlMinutes: 30,
+    staleMinutes: 10,
+    dangerouslySkipPermissions: false,
+};
+export async function loadConfig() {
+    if (!existsSync(LOOMRC))
+        return { ...DEFAULTS };
+    try {
+        const raw = await readFile(LOOMRC, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null)
+            return { ...DEFAULTS };
+        return { ...DEFAULTS, ...parsed };
+    }
+    catch {
+        console.error(`[agentloom] Warning: could not parse ${LOOMRC} — using defaults`);
+        return { ...DEFAULTS };
+    }
+}
+export async function initConfig() {
+    if (existsSync(LOOMRC)) {
+        console.log(`${LOOMRC} already exists.`);
+        return;
+    }
+    const config = {
+        workers: 2,
+        agentType: 'general-purpose',
+        claimTtlMinutes: 30,
+        staleMinutes: 10,
+    };
+    await writeFile(LOOMRC, JSON.stringify(config, null, 2) + '\n');
+    console.log(`Created ${LOOMRC}`);
+    console.log(`\nOptions:`);
+    console.log(`  workers              Default number of workers (default: 2)`);
+    console.log(`  agentType            Default agent type (default: general-purpose)`);
+    console.log(`  claimTtlMinutes      Minutes before crashed worker's task is re-queued (default: 30)`);
+    console.log(`  staleMinutes         Minutes before dead-pid worker is flagged STALE (default: 10)`);
+}

package/dist/state/session.d.ts

@@ -12,14 +12,6 @@ export type Task = {
     claimedAt?: string;
     completedAt?: string;
 };
-export type Worker = {
-    id: string;
-    agentType: string;
-    status: 'idle' | 'working' | 'done';
-    currentTaskId?: string;
-    startedAt: string;
-    completedAt?: string;
-};
 export type Session = {
     id: string;
     description: string;
@@ -34,6 +26,4 @@ export declare function ensureStateDir(): Promise<void>;
 export declare function writeSession(session: Session): Promise<void>;
 export declare function readSession(): Promise<Session | null>;
 export declare function writeTask(task: Task): Promise<void>;
-export declare function writeWorker(worker: Worker): Promise<void>;
-export declare function readWorkers(): Promise<Worker[]>;
 export declare function readTasks(): Promise<Task[]>;

package/dist/state/session.js

@@ -1,6 +1,5 @@
-import { readFile, writeFile, mkdir } from 'fs/promises';
+import { readFile, writeFile, mkdir, readdir } from 'fs/promises';
 import { join } from 'path';
-import { existsSync } from 'fs';
 export const STATE_DIR = '.claude-team';
 export async function ensureStateDir() {
     await mkdir(join(STATE_DIR, 'tasks'), { recursive: true });
@@ -11,30 +10,23 @@ export async function writeSession(session) {
     await writeFile(join(STATE_DIR, 'session.json'), JSON.stringify(session, null, 2));
 }
 export async function readSession() {
-    const path = join(STATE_DIR, 'session.json');
-    if (!existsSync(path))
+    try {
+        return JSON.parse(await readFile(join(STATE_DIR, 'session.json'), 'utf8'));
+    }
+    catch {
         return null;
-    return JSON.parse(await readFile(path, 'utf8'));
+    }
 }
 export async function writeTask(task) {
     await writeFile(join(STATE_DIR, 'tasks', `${task.id}-${task.status}.json`), JSON.stringify(task, null, 2));
 }
-export async function writeWorker(worker) {
-    await writeFile(join(STATE_DIR, 'workers', `${worker.id}.json`), JSON.stringify(worker, null, 2));
-}
-export async function readWorkers() {
-    const { readdir } = await import('fs/promises');
-    const dir = join(STATE_DIR, 'workers');
-    if (!existsSync(dir))
-        return [];
-    const files = await readdir(dir);
-    return Promise.all(files.filter(f => f.endsWith('.json')).map(async (f) => JSON.parse(await readFile(join(dir, f), 'utf8'))));
-}
 export async function readTasks() {
-    const { readdir } = await import('fs/promises');
     const dir = join(STATE_DIR, 'tasks');
-    if (!existsSync(dir))
+    try {
+        const files = await readdir(dir);
+        return Promise.all(files.filter(f => f.endsWith('.json')).map(async (f) => JSON.parse(await readFile(join(dir, f), 'utf8'))));
+    }
+    catch {
         return [];
-    const files = await readdir(dir);
-    return Promise.all(files.filter(f => f.endsWith('.json')).map(async (f) => JSON.parse(await readFile(join(dir, f), 'utf8'))));
+    }
 }

package/dist/team/orchestrator.d.ts

@@ -3,10 +3,10 @@ export type WorkerSpec = {
     count: number;
     agentType: string;
 };
-export declare function parseWorkerSpec(args: string[]): {
+export declare function parseWorkerSpec(args: string[], defaultWorkers?: number, defaultAgentType?: string): {
     specs: WorkerSpec[];
     task: string;
 };
 export declare function initSession(description: string, workerCount: number): Promise<Session>;
-export declare function writeContextSnapshot(slug: string, task: string): Promise<string>;
+export declare function writeContextSnapshot(slug: string, sessionId: string, task: string): Promise<string>;
 export declare function decomposeTasks(task: string, specs: WorkerSpec[], dryRun?: boolean): Promise<Task[]>;

package/dist/team/orchestrator.js

@@ -3,29 +3,25 @@ import { join } from 'path';
 import { randomUUID } from 'crypto';
 import { spawnSync } from 'child_process';
 import { STATE_DIR, ensureStateDir, writeSession, writeTask } from '../state/session.js';
-export function parseWorkerSpec(args) {
-    // Formats:
-    //   omc team "task description"
-    //   omc team 3 "task description"
-    //   omc team 2:explore "task description"
-    //   omc team 2:explore+1:code-reviewer "task description"
+export function parseWorkerSpec(args, defaultWorkers = 2, defaultAgentType = 'general-purpose') {
     const task = args[args.length - 1] ?? '';
     const specArg = args.length > 1 ? args[0] ?? '' : '';
     if (!specArg) {
-        return { specs: [{ count: 2, agentType: 'general-purpose' }], task };
+        return { specs: [{ count: defaultWorkers, agentType: defaultAgentType }], task };
     }
     // Plain number: "3"
     if (/^\d+$/.test(specArg)) {
-        return { specs: [{ count: parseInt(specArg), agentType: 'general-purpose' }], task };
+        return { specs: [{ count: parseInt(specArg), agentType: defaultAgentType }], task };
     }
     // Typed specs: "2:explore+1:code-reviewer"
     const parts = specArg.split('+');
     const specs = parts.map(part => {
         const [countStr, agentType] = part.split(':');
-        return {
-            count: parseInt(countStr ?? '1'),
-            agentType: agentType ?? 'general-purpose',
-        };
+        const count = parseInt(countStr ?? '1');
+        if (isNaN(count) || count < 1) {
+            throw new Error(`Invalid worker spec "${part}" — count must be a positive integer`);
+        }
+        return { count, agentType: agentType ?? defaultAgentType };
     });
     return { specs, task };
 }
@@ -41,9 +37,10 @@ export async function initSession(description, workerCount) {
     await writeSession(session);
     return session;
 }
-export async function writeContextSnapshot(slug, task) {
-    const path = join(STATE_DIR, 'context', `${slug}.md`);
-    const content = `# Task Context\n\n**Task:** ${task}\n\n**Started:** ${new Date().toISOString()}\n\n## Notes\n\n_Workers will append findings here._\n`;
+export async function writeContextSnapshot(slug, sessionId, task) {
+    // Include session ID so concurrent runs with similar task names don't clobber each other
+    const path = join(STATE_DIR, 'context', `${slug}-${sessionId.slice(0, 6)}.md`);
+    const content = `# Task Context\n\n**Task:** ${task}\n\n**Session:** ${sessionId}\n\n**Started:** ${new Date().toISOString()}\n\n## Notes\n\n_Workers will append findings here._\n`;
     await writeFile(path, content);
     return path;
 }
@@ -80,9 +77,9 @@ Task: "${task}"`;
             encoding: 'utf8',
             timeout: 30_000,
         });
-        if (result.status !== 0 || !result.stdout)
+        if (result.status !== 0 || !result.stdout) {
             throw new Error(result.stderr ?? 'no output');
-        // Extract JSON array from the response (strip any surrounding prose)
+        }
         const match = result.stdout.match(/\[[\s\S]*\]/);
         if (!match)
             throw new Error('No JSON array in response');
@@ -90,13 +87,12 @@ Task: "${task}"`;
         if (!Array.isArray(parsed) || parsed.length === 0)
             throw new Error('Empty array');
         const subtasks = parsed.map(String);
-        // Pad or trim to exactly n
         while (subtasks.length < n)
             subtasks.push(task);
         return subtasks.slice(0, n);
     }
-    catch {
-        // Fallback: every worker gets the same task description
+    catch (err) {
+        process.stderr.write(`[agentloom] Task decomposition failed (${err instanceof Error ? err.message : err}) — all workers will receive the same task description\n`);
         return Array(n).fill(task);
     }
 }

package/dist/team/queue.js

@@ -1,11 +1,13 @@
 import { readdir, readFile, rename, writeFile, stat, unlink } from 'fs/promises';
 import { join } from 'path';
 import { STATE_DIR } from '../state/session.js';
+import { loadConfig } from '../config.js';
 const TASKS_DIR = join(STATE_DIR, 'tasks');
-const CLAIM_TTL_MS = 30 * 60 * 1000; // 30 minutes
 // Recover tasks whose worker crashed before completing.
 // Finds -claimed- files older than CLAIM_TTL_MS and re-queues them as -pending.
 export async function recoverStaleClaims() {
+    const config = await loadConfig();
+    const claimTtlMs = config.claimTtlMinutes * 60 * 1000;
     let recovered = 0;
     let files;
     try {
@@ -20,7 +22,7 @@ export async function recoverStaleClaims() {
         const filePath = join(TASKS_DIR, file);
         try {
             const { mtimeMs } = await stat(filePath);
-            if (now - mtimeMs < CLAIM_TTL_MS)
+            if (now - mtimeMs < claimTtlMs)
                 continue;
             const taskId = file.split('-claimed-')[0];
             if (!taskId)

package/package.json

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