@saga-ai/cli 0.6.0 → 0.7.1

package/README.md

@@ -16,6 +16,7 @@ npx @saga-ai/cli init
 npx @saga-ai/cli find <query>
 npx @saga-ai/cli worktree <epic-slug> <story-slug>
 npx @saga-ai/cli implement <story-slug>
+npx @saga-ai/cli sessions list
 npx @saga-ai/cli dashboard
 ```
 
@@ -49,6 +50,7 @@ saga find auth --type epic
 
 Options:
 - `--type <type>` - Type to search for: `epic` or `story` (default: story)
+- `--status <status>` - Filter stories by status: `ready`, `completed`, `blocked`, etc.
 
 Returns JSON with:
 - `found: true` + `data` - Single match found
@@ -83,15 +85,37 @@ saga implement my-story
 saga implement my-story --max-cycles 5
 saga implement my-story --max-time 30
 saga implement my-story --model sonnet
+saga implement my-story --attached --stream
 ```
 
 Options:
 - `--max-cycles <n>` - Maximum number of worker cycles (default: 10)
 - `--max-time <n>` - Maximum time in minutes (default: 60)
 - `--model <name>` - Model to use (default: opus)
+- `--attached` - Run in attached mode (synchronous). Default is detached (runs in tmux session)
+- `--stream` - Stream worker output to stdout (only works with `--attached`)
+
+By default, `implement` runs in **detached mode** using a tmux session. This allows the worker to continue running even if your terminal disconnects. Use `saga sessions` to monitor detached sessions.
 
 **Note:** Requires `SAGA_PLUGIN_ROOT` environment variable to be set. This is automatically configured when running via the SAGA plugin.
 
+### `saga sessions`
+
+Manage tmux sessions created by detached `implement` runs.
+
+```bash
+saga sessions list              # List all SAGA sessions
+saga sessions status <name>     # Check if session is running
+saga sessions logs <name>       # Stream session output
+saga sessions kill <name>       # Terminate a session
+```
+
+Subcommands:
+- `list` - Returns JSON array of all SAGA sessions with name, status, and output file
+- `status <name>` - Returns JSON `{running: boolean}` for the session
+- `logs <name>` - Streams the session output file via `tail -f`
+- `kill <name>` - Terminates the session, returns JSON `{killed: boolean}`
+
 ### `saga dashboard`
 
 Start the SAGA dashboard server for viewing epics, stories, and progress.

package/dist/cli.cjs

@@ -25,8 +25,8 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 
 // src/cli.ts
 var import_commander = require("commander");
-var import_node_path7 = require("node:path");
-var import_node_fs6 = require("node:fs");
+var import_node_path8 = require("node:path");
+var import_node_fs7 = require("node:fs");
 
 // src/commands/init.ts
 var import_node_path2 = require("node:path");
@@ -193,9 +193,9 @@ async function initCommand(options) {
 }
 
 // src/commands/implement.ts
-var import_node_child_process = require("node:child_process");
-var import_node_path4 = require("node:path");
-var import_node_fs4 = require("node:fs");
+var import_node_child_process2 = require("node:child_process");
+var import_node_path5 = require("node:path");
+var import_node_fs5 = require("node:fs");
 
 // src/utils/finder.ts
 var import_node_fs3 = require("node:fs");
@@ -503,7 +503,7 @@ function findEpic(projectPath, query) {
     matches: results.map((r) => r.item)
   };
 }
-async function findStory(projectPath, query) {
+async function findStory(projectPath, query, options = {}) {
   if (!worktreesDirectoryExists(projectPath) && !epicsDirectoryExists(projectPath)) {
     return {
       found: false,
@@ -517,7 +517,16 @@ async function findStory(projectPath, query) {
       error: `No story found matching '${query}'`
     };
   }
-  const allStories = scannedStories.map(toStoryInfo);
+  let allStories = scannedStories.map(toStoryInfo);
+  if (options.status) {
+    allStories = allStories.filter((story) => story.status === options.status);
+    if (allStories.length === 0) {
+      return {
+        found: false,
+        error: `No story found matching '${query}' with status '${options.status}'`
+      };
+    }
+  }
   const queryNormalized = normalize(query);
   for (const story of allStories) {
     if (normalize(story.slug) === queryNormalized) {
@@ -571,6 +580,165 @@ async function findStory(projectPath, query) {
   };
 }
 
+// src/lib/sessions.ts
+var import_node_child_process = require("node:child_process");
+var import_node_fs4 = require("node:fs");
+var import_node_path4 = require("node:path");
+var OUTPUT_DIR = "/tmp/saga-sessions";
+function shellEscape(str) {
+  return "'" + str.replace(/'/g, "'\\''") + "'";
+}
+function shellEscapeArgs(args) {
+  return args.map(shellEscape).join(" ");
+}
+function validateSlug(slug) {
+  if (!slug || slug.length === 0) {
+    return false;
+  }
+  if (!/^[a-z0-9-]+$/.test(slug)) {
+    return false;
+  }
+  if (slug.startsWith("-") || slug.endsWith("-")) {
+    return false;
+  }
+  return true;
+}
+function checkTmuxAvailable() {
+  const result = (0, import_node_child_process.spawnSync)("which", ["tmux"], { encoding: "utf-8" });
+  if (result.status !== 0) {
+    throw new Error("tmux is not installed or not found in PATH");
+  }
+}
+async function createSession(epicSlug, storySlug, command) {
+  if (!validateSlug(epicSlug)) {
+    throw new Error(`Invalid epic slug: '${epicSlug}'. Must contain only [a-z0-9-] and not start/end with hyphen.`);
+  }
+  if (!validateSlug(storySlug)) {
+    throw new Error(`Invalid story slug: '${storySlug}'. Must contain only [a-z0-9-] and not start/end with hyphen.`);
+  }
+  checkTmuxAvailable();
+  if (!(0, import_node_fs4.existsSync)(OUTPUT_DIR)) {
+    (0, import_node_fs4.mkdirSync)(OUTPUT_DIR, { recursive: true });
+  }
+  const timestamp = Date.now();
+  const sessionName = `saga-${epicSlug}-${storySlug}-${timestamp}`;
+  const outputFile = (0, import_node_path4.join)(OUTPUT_DIR, `${sessionName}.out`);
+  const commandFilePath = (0, import_node_path4.join)(OUTPUT_DIR, `${sessionName}.cmd`);
+  const wrapperScriptPath = (0, import_node_path4.join)(OUTPUT_DIR, `${sessionName}.sh`);
+  (0, import_node_fs4.writeFileSync)(commandFilePath, command, { mode: 384 });
+  const wrapperScriptContent = `#!/bin/bash
+# Auto-generated wrapper script for SAGA session
+set -e
+
+COMMAND_FILE="${commandFilePath}"
+OUTPUT_FILE="${outputFile}"
+SCRIPT_FILE="${wrapperScriptPath}"
+
+# Read the command from file
+COMMAND="$(cat "$COMMAND_FILE")"
+
+# Cleanup temporary files on exit
+cleanup() {
+  rm -f "$COMMAND_FILE" "$SCRIPT_FILE"
+}
+trap cleanup EXIT
+
+# Execute the command with output capture
+# script syntax differs between macOS and Linux:
+#   macOS (Darwin): script -q <file> <shell> -c <command>
+#   Linux:          script -q -c <command> <file>
+if [[ "$(uname)" == "Darwin" ]]; then
+  # -F: flush output after each write (ensures immediate visibility)
+  exec script -qF "$OUTPUT_FILE" /bin/bash -c "$COMMAND"
+else
+  exec script -q -c "$COMMAND" "$OUTPUT_FILE"
+fi
+`;
+  (0, import_node_fs4.writeFileSync)(wrapperScriptPath, wrapperScriptContent, { mode: 448 });
+  const createResult = (0, import_node_child_process.spawnSync)("tmux", [
+    "new-session",
+    "-d",
+    // detached
+    "-s",
+    sessionName,
+    // session name
+    wrapperScriptPath
+    // run the wrapper script
+  ], { encoding: "utf-8" });
+  if (createResult.status !== 0) {
+    throw new Error(`Failed to create tmux session: ${createResult.stderr || "unknown error"}`);
+  }
+  return {
+    sessionName,
+    outputFile
+  };
+}
+async function listSessions() {
+  const result = (0, import_node_child_process.spawnSync)("tmux", ["ls"], { encoding: "utf-8" });
+  if (result.status !== 0) {
+    return [];
+  }
+  const sessions = [];
+  const lines = result.stdout.trim().split("\n");
+  for (const line of lines) {
+    const match = line.match(/^(saga-[a-z0-9]+(?:-[a-z0-9]+)*-\d+):/);
+    if (match) {
+      const name = match[1];
+      sessions.push({
+        name,
+        status: "running",
+        // If it shows up in tmux ls, it's running
+        outputFile: (0, import_node_path4.join)(OUTPUT_DIR, `${name}.out`)
+      });
+    }
+  }
+  return sessions;
+}
+async function getSessionStatus(sessionName) {
+  const result = (0, import_node_child_process.spawnSync)("tmux", ["has-session", "-t", sessionName], {
+    encoding: "utf-8"
+  });
+  return {
+    running: result.status === 0
+  };
+}
+async function streamLogs(sessionName) {
+  const outputFile = (0, import_node_path4.join)(OUTPUT_DIR, `${sessionName}.out`);
+  if (!(0, import_node_fs4.existsSync)(outputFile)) {
+    throw new Error(`Output file not found: ${outputFile}`);
+  }
+  return new Promise((resolve2, reject) => {
+    const child = (0, import_node_child_process.spawn)("tail", ["-f", outputFile], {
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    child.stdout?.on("data", (chunk) => {
+      process.stdout.write(chunk);
+    });
+    child.stderr?.on("data", (chunk) => {
+      process.stderr.write(chunk);
+    });
+    child.on("error", (err) => {
+      reject(new Error(`Failed to stream logs: ${err.message}`));
+    });
+    child.on("close", (code) => {
+      resolve2();
+    });
+    const sigintHandler = () => {
+      child.kill("SIGTERM");
+      process.removeListener("SIGINT", sigintHandler);
+    };
+    process.on("SIGINT", sigintHandler);
+  });
+}
+async function killSession(sessionName) {
+  const result = (0, import_node_child_process.spawnSync)("tmux", ["kill-session", "-t", sessionName], {
+    encoding: "utf-8"
+  });
+  return {
+    killed: result.status === 0
+  };
+}
+
 // src/commands/implement.ts
 var DEFAULT_MAX_CYCLES = 10;
 var DEFAULT_MAX_TIME = 60;
@@ -608,10 +776,10 @@ async function findStory2(projectPath, storySlug) {
   };
 }
 function computeStoryPath(worktree, epicSlug, storySlug) {
-  return (0, import_node_path4.join)(worktree, ".saga", "epics", epicSlug, "stories", storySlug, "story.md");
+  return (0, import_node_path5.join)(worktree, ".saga", "epics", epicSlug, "stories", storySlug, "story.md");
 }
 function validateStoryFiles(worktree, epicSlug, storySlug) {
-  if (!(0, import_node_fs4.existsSync)(worktree)) {
+  if (!(0, import_node_fs5.existsSync)(worktree)) {
     return {
       valid: false,
       error: `Worktree not found at ${worktree}
@@ -624,7 +792,7 @@ To create the worktree, use: /task-resume ${storySlug}`
     };
   }
   const storyPath = computeStoryPath(worktree, epicSlug, storySlug);
-  if (!(0, import_node_fs4.existsSync)(storyPath)) {
+  if (!(0, import_node_fs5.existsSync)(storyPath)) {
     return {
       valid: false,
       error: `story.md not found in worktree.
@@ -638,11 +806,11 @@ This may indicate an incomplete story setup.`
   return { valid: true };
 }
 function getSkillRoot(pluginRoot) {
-  return (0, import_node_path4.join)(pluginRoot, "skills", "execute-story");
+  return (0, import_node_path5.join)(pluginRoot, "skills", "execute-story");
 }
 function checkCommandExists(command) {
   try {
-    const result = (0, import_node_child_process.spawnSync)("which", [command], { encoding: "utf-8" });
+    const result = (0, import_node_child_process2.spawnSync)("which", [command], { encoding: "utf-8" });
     if (result.status === 0 && result.stdout.trim()) {
       return { exists: true, path: result.stdout.trim() };
     }
@@ -678,8 +846,8 @@ function runDryRun(storyInfo, projectPath, pluginRoot) {
   if (!claudeCheck.exists) allPassed = false;
   if (pluginRoot) {
     const skillRoot = getSkillRoot(pluginRoot);
-    const workerPromptPath = (0, import_node_path4.join)(skillRoot, WORKER_PROMPT_RELATIVE);
-    if ((0, import_node_fs4.existsSync)(workerPromptPath)) {
+    const workerPromptPath = (0, import_node_path5.join)(skillRoot, WORKER_PROMPT_RELATIVE);
+    if ((0, import_node_fs5.existsSync)(workerPromptPath)) {
       checks.push({
         name: "Worker prompt",
         path: workerPromptPath,
@@ -700,7 +868,7 @@ function runDryRun(storyInfo, projectPath, pluginRoot) {
     path: `${storyInfo.storySlug} (epic: ${storyInfo.epicSlug})`,
     passed: true
   });
-  if ((0, import_node_fs4.existsSync)(storyInfo.worktreePath)) {
+  if ((0, import_node_fs5.existsSync)(storyInfo.worktreePath)) {
     checks.push({
       name: "Worktree exists",
       path: storyInfo.worktreePath,
@@ -715,13 +883,13 @@ function runDryRun(storyInfo, projectPath, pluginRoot) {
     });
     allPassed = false;
   }
-  if ((0, import_node_fs4.existsSync)(storyInfo.worktreePath)) {
+  if ((0, import_node_fs5.existsSync)(storyInfo.worktreePath)) {
     const storyMdPath = computeStoryPath(
       storyInfo.worktreePath,
       storyInfo.epicSlug,
       storyInfo.storySlug
     );
-    if ((0, import_node_fs4.existsSync)(storyMdPath)) {
+    if ((0, import_node_fs5.existsSync)(storyMdPath)) {
       checks.push({
         name: "story.md in worktree",
         path: storyMdPath,
@@ -771,11 +939,11 @@ function printDryRunResults(result) {
 }
 function loadWorkerPrompt(pluginRoot) {
   const skillRoot = getSkillRoot(pluginRoot);
-  const promptPath = (0, import_node_path4.join)(skillRoot, WORKER_PROMPT_RELATIVE);
-  if (!(0, import_node_fs4.existsSync)(promptPath)) {
+  const promptPath = (0, import_node_path5.join)(skillRoot, WORKER_PROMPT_RELATIVE);
+  if (!(0, import_node_fs5.existsSync)(promptPath)) {
     throw new Error(`Worker prompt not found at ${promptPath}`);
   }
-  return (0, import_node_fs4.readFileSync)(promptPath, "utf-8");
+  return (0, import_node_fs5.readFileSync)(promptPath, "utf-8");
 }
 function buildScopeSettings() {
   const hookCommand = "npx @saga-ai/cli scope-validator";
@@ -837,7 +1005,7 @@ function spawnWorker(prompt, model, settings, workingDir) {
     JSON.stringify(settings),
     "--dangerously-skip-permissions"
   ];
-  const result = (0, import_node_child_process.spawnSync)("claude", args, {
+  const result = (0, import_node_child_process2.spawnSync)("claude", args, {
     cwd: workingDir,
     encoding: "utf-8",
     maxBuffer: 50 * 1024 * 1024
@@ -874,6 +1042,22 @@ function formatStreamLine(line) {
     return null;
   }
 }
+function extractStructuredOutputFromToolCall(lines) {
+  for (let i = lines.length - 1; i >= 0; i--) {
+    try {
+      const data = JSON.parse(lines[i]);
+      if (data.type === "assistant" && data.message?.content) {
+        for (const block of data.message.content) {
+          if (block.type === "tool_use" && block.name === "StructuredOutput") {
+            return block.input;
+          }
+        }
+      }
+    } catch {
+    }
+  }
+  return null;
+}
 function parseStreamingResult(buffer) {
   const lines = buffer.split("\n").filter((line) => line.trim());
   for (let i = lines.length - 1; i >= 0; i--) {
@@ -883,10 +1067,13 @@ function parseStreamingResult(buffer) {
         if (data.is_error) {
           throw new Error(`Worker failed: ${data.result || "Unknown error"}`);
         }
-        if (!data.structured_output) {
+        let output = data.structured_output;
+        if (!output) {
+          output = extractStructuredOutputFromToolCall(lines);
+        }
+        if (!output) {
           throw new Error("Worker result missing structured_output");
         }
-        const output = data.structured_output;
         if (!VALID_STATUSES.has(output.status)) {
           throw new Error(`Invalid status: ${output.status}`);
         }
@@ -921,7 +1108,7 @@ function spawnWorkerAsync(prompt, model, settings, workingDir) {
       JSON.stringify(settings),
       "--dangerously-skip-permissions"
     ];
-    const child = (0, import_node_child_process.spawn)("claude", args, {
+    const child = (0, import_node_child_process2.spawn)("claude", args, {
       cwd: workingDir,
       stdio: ["ignore", "pipe", "pipe"]
     });
@@ -956,7 +1143,7 @@ function spawnWorkerAsync(prompt, model, settings, workingDir) {
   });
 }
 async function runLoop(epicSlug, storySlug, maxCycles, maxTime, model, projectDir, pluginRoot, stream = false) {
-  const worktree = (0, import_node_path4.join)(projectDir, ".saga", "worktrees", epicSlug, storySlug);
+  const worktree = (0, import_node_path5.join)(projectDir, ".saga", "worktrees", epicSlug, storySlug);
   const validation = validateStoryFiles(worktree, epicSlug, storySlug);
   if (!validation.valid) {
     return {
@@ -1072,6 +1259,23 @@ async function runLoop(epicSlug, storySlug, maxCycles, maxTime, model, projectDi
     storySlug
   };
 }
+function buildDetachedCommand(storySlug, projectPath, options) {
+  const parts = ["saga", "implement", storySlug, "--attached"];
+  parts.push("--path", projectPath);
+  if (options.maxCycles !== void 0) {
+    parts.push("--max-cycles", String(options.maxCycles));
+  }
+  if (options.maxTime !== void 0) {
+    parts.push("--max-time", String(options.maxTime));
+  }
+  if (options.model !== void 0) {
+    parts.push("--model", options.model);
+  }
+  if (options.stream) {
+    parts.push("--stream");
+  }
+  return shellEscapeArgs(parts);
+}
 async function implementCommand(storySlug, options) {
   let projectPath;
   try {
@@ -1084,7 +1288,7 @@ async function implementCommand(storySlug, options) {
   if (!storyInfo) {
     console.error(`Error: Story '${storySlug}' not found in SAGA project.`);
     console.error(`
-Searched in: ${(0, import_node_path4.join)(projectPath, ".saga", "worktrees")}`);
+Searched in: ${(0, import_node_path5.join)(projectPath, ".saga", "worktrees")}`);
     console.error("\nMake sure the story worktree exists and has a story.md file.");
     console.error("Run /generate-stories to create story worktrees.");
     process.exit(1);
@@ -1095,7 +1299,7 @@ Searched in: ${(0, import_node_path4.join)(projectPath, ".saga", "worktrees")}`)
     printDryRunResults(dryRunResult);
     process.exit(dryRunResult.success ? 0 : 1);
   }
-  if (!(0, import_node_fs4.existsSync)(storyInfo.worktreePath)) {
+  if (!(0, import_node_fs5.existsSync)(storyInfo.worktreePath)) {
     console.error(`Error: Worktree not found at ${storyInfo.worktreePath}`);
     console.error("\nThe story worktree has not been created yet.");
     console.error("Make sure the story was properly generated with /generate-stories.");
@@ -1113,6 +1317,38 @@ Searched in: ${(0, import_node_path4.join)(projectPath, ".saga", "worktrees")}`)
   const maxTime = options.maxTime ?? DEFAULT_MAX_TIME;
   const model = options.model ?? DEFAULT_MODEL;
   const stream = options.stream ?? false;
+  const attached = options.attached ?? false;
+  if (!attached) {
+    if (stream) {
+      console.error("Warning: --stream is ignored in detached mode. Use --attached --stream for streaming output.");
+    }
+    const detachedCommand = buildDetachedCommand(storySlug, projectPath, {
+      maxCycles: options.maxCycles,
+      maxTime: options.maxTime,
+      model: options.model,
+      stream: true
+      // Always use streaming in detached mode so output is captured
+    });
+    try {
+      const sessionResult = await createSession(
+        storyInfo.epicSlug,
+        storyInfo.storySlug,
+        detachedCommand
+      );
+      console.log(JSON.stringify({
+        mode: "detached",
+        sessionName: sessionResult.sessionName,
+        outputFile: sessionResult.outputFile,
+        epicSlug: storyInfo.epicSlug,
+        storySlug: storyInfo.storySlug,
+        worktreePath: storyInfo.worktreePath
+      }, null, 2));
+      return;
+    } catch (error) {
+      console.error(`Error: Failed to create detached session: ${error.message}`);
+      process.exit(1);
+    }
+  }
   console.log("Starting story implementation...");
   console.log(`  Epic: ${storyInfo.epicSlug}`);
   console.log(`  Story: ${storyInfo.storySlug}`);
@@ -1194,7 +1430,7 @@ function validateTaskStatus(status) {
   return "pending";
 }
 async function parseStory(storyPath, epicSlug) {
-  const { join: join11 } = await import("path");
+  const { join: join12 } = await import("path");
   const { stat: stat2 } = await import("fs/promises");
   let content;
   try {
@@ -1214,7 +1450,7 @@ async function parseStory(storyPath, epicSlug) {
   const title = frontmatter.title || dirName;
   const status = validateStatus(frontmatter.status);
   const tasks = parseTasks(frontmatter.tasks);
-  const journalPath = join11(storyDir, "journal.md");
+  const journalPath = join12(storyDir, "journal.md");
   let hasJournal = false;
   try {
     await stat2(journalPath);
@@ -1804,7 +2040,7 @@ async function dashboardCommand(options) {
 }
 
 // src/commands/scope-validator.ts
-var import_node_path5 = require("node:path");
+var import_node_path6 = require("node:path");
 function getFilePathFromInput(hookInput) {
   try {
     const data = JSON.parse(hookInput);
@@ -1824,10 +2060,10 @@ function isArchiveAccess(path) {
   return path.includes(".saga/archive");
 }
 function isWithinWorktree(filePath, worktreePath) {
-  const absoluteFilePath = (0, import_node_path5.resolve)(filePath);
-  const absoluteWorktree = (0, import_node_path5.resolve)(worktreePath);
-  const relativePath = (0, import_node_path5.relative)(absoluteWorktree, absoluteFilePath);
-  if (relativePath.startsWith("..") || (0, import_node_path5.resolve)(relativePath) === relativePath) {
+  const absoluteFilePath = (0, import_node_path6.resolve)(filePath);
+  const absoluteWorktree = (0, import_node_path6.resolve)(worktreePath);
+  const relativePath = (0, import_node_path6.relative)(absoluteWorktree, absoluteFilePath);
+  if (relativePath.startsWith("..") || (0, import_node_path6.resolve)(relativePath) === relativePath) {
     return false;
   }
   return true;
@@ -1933,7 +2169,7 @@ async function findCommand(query, options) {
   if (type === "epic") {
     result = findEpic(projectPath, query);
   } else {
-    result = await findStory(projectPath, query);
+    result = await findStory(projectPath, query, { status: options.status });
   }
   console.log(JSON.stringify(result, null, 2));
   if (!result.found) {
@@ -1942,12 +2178,12 @@ async function findCommand(query, options) {
 }
 
 // src/commands/worktree.ts
-var import_node_path6 = require("node:path");
-var import_node_fs5 = require("node:fs");
-var import_node_child_process2 = require("node:child_process");
+var import_node_path7 = require("node:path");
+var import_node_fs6 = require("node:fs");
+var import_node_child_process3 = require("node:child_process");
 function runGitCommand(args, cwd) {
   try {
-    const output = (0, import_node_child_process2.execSync)(`git ${args.join(" ")}`, {
+    const output = (0, import_node_child_process3.execSync)(`git ${args.join(" ")}`, {
       cwd,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
@@ -1974,7 +2210,7 @@ function getMainBranch(cwd) {
 }
 function createWorktree(projectPath, epicSlug, storySlug) {
   const branchName = `story-${storySlug}-epic-${epicSlug}`;
-  const worktreePath = (0, import_node_path6.join)(
+  const worktreePath = (0, import_node_path7.join)(
     projectPath,
     ".saga",
     "worktrees",
@@ -1987,7 +2223,7 @@ function createWorktree(projectPath, epicSlug, storySlug) {
       error: `Branch already exists: ${branchName}`
     };
   }
-  if ((0, import_node_fs5.existsSync)(worktreePath)) {
+  if ((0, import_node_fs6.existsSync)(worktreePath)) {
     return {
       success: false,
       error: `Worktree directory already exists: ${worktreePath}`
@@ -2005,8 +2241,8 @@ function createWorktree(projectPath, epicSlug, storySlug) {
       error: `Failed to create branch: ${createBranchResult.output}`
     };
   }
-  const worktreeParent = (0, import_node_path6.join)(projectPath, ".saga", "worktrees", epicSlug);
-  (0, import_node_fs5.mkdirSync)(worktreeParent, { recursive: true });
+  const worktreeParent = (0, import_node_path7.join)(projectPath, ".saga", "worktrees", epicSlug);
+  (0, import_node_fs6.mkdirSync)(worktreeParent, { recursive: true });
   const createWorktreeResult = runGitCommand(
     ["worktree", "add", worktreePath, branchName],
     projectPath
@@ -2039,9 +2275,31 @@ async function worktreeCommand(epicSlug, storySlug, options) {
   }
 }
 
+// src/commands/sessions/index.ts
+async function sessionsListCommand() {
+  const sessions = await listSessions();
+  console.log(JSON.stringify(sessions, null, 2));
+}
+async function sessionsStatusCommand(sessionName) {
+  const status = await getSessionStatus(sessionName);
+  console.log(JSON.stringify(status, null, 2));
+}
+async function sessionsLogsCommand(sessionName) {
+  try {
+    await streamLogs(sessionName);
+  } catch (error) {
+    console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+  }
+}
+async function sessionsKillCommand(sessionName) {
+  const result = await killSession(sessionName);
+  console.log(JSON.stringify(result, null, 2));
+}
+
 // src/cli.ts
-var packageJsonPath = (0, import_node_path7.join)(__dirname, "..", "package.json");
-var packageJson = JSON.parse((0, import_node_fs6.readFileSync)(packageJsonPath, "utf-8"));
+var packageJsonPath = (0, import_node_path8.join)(__dirname, "..", "package.json");
+var packageJson = JSON.parse((0, import_node_fs7.readFileSync)(packageJsonPath, "utf-8"));
 var program = new import_commander.Command();
 program.name("saga").description("CLI for SAGA - Structured Autonomous Goal Achievement").version(packageJson.version).addHelpCommand("help [command]", "Display help for a command");
 program.option("-p, --path <dir>", "Path to SAGA project directory (overrides auto-discovery)");
@@ -2049,7 +2307,7 @@ program.command("init").description("Initialize .saga/ directory structure").opt
   const globalOpts = program.opts();
   await initCommand({ path: globalOpts.path, dryRun: options.dryRun });
 });
-program.command("implement <story-slug>").description("Run story implementation").option("--max-cycles <n>", "Maximum number of implementation cycles", parseInt).option("--max-time <n>", "Maximum time in minutes", parseInt).option("--model <name>", "Model to use for implementation").option("--dry-run", "Validate dependencies without running implementation").option("--stream", "Stream worker output in real-time").action(async (storySlug, options) => {
+program.command("implement <story-slug>").description("Run story implementation").option("--max-cycles <n>", "Maximum number of implementation cycles", parseInt).option("--max-time <n>", "Maximum time in minutes", parseInt).option("--model <name>", "Model to use for implementation").option("--dry-run", "Validate dependencies without running implementation").option("--stream", "Stream worker output in real-time").option("--attached", "Run in attached mode (synchronous, tied to terminal)").action(async (storySlug, options) => {
   const globalOpts = program.opts();
   await implementCommand(storySlug, {
     path: globalOpts.path,
@@ -2057,14 +2315,16 @@ program.command("implement <story-slug>").description("Run story implementation"
     maxTime: options.maxTime,
     model: options.model,
     dryRun: options.dryRun,
-    stream: options.stream
+    stream: options.stream,
+    attached: options.attached
   });
 });
-program.command("find <query>").description("Find an epic or story by slug/title").option("--type <type>", "Type to search for: epic or story (default: story)").action(async (query, options) => {
+program.command("find <query>").description("Find an epic or story by slug/title").option("--type <type>", "Type to search for: epic or story (default: story)").option("--status <status>", "Filter stories by status (e.g., ready, in-progress, completed)").action(async (query, options) => {
   const globalOpts = program.opts();
   await findCommand(query, {
     path: globalOpts.path,
-    type: options.type
+    type: options.type,
+    status: options.status
   });
 });
 program.command("worktree <epic-slug> <story-slug>").description("Create git worktree for a story").action(async (epicSlug, storySlug) => {
@@ -2081,6 +2341,19 @@ program.command("dashboard").description("Start the dashboard server").option("-
 program.command("scope-validator").description("Validate file operations against story scope (internal)").action(async () => {
   await scopeValidatorCommand();
 });
+var sessionsCommand = program.command("sessions").description("Manage SAGA tmux sessions");
+sessionsCommand.command("list").description("List all SAGA sessions").action(async () => {
+  await sessionsListCommand();
+});
+sessionsCommand.command("status <name>").description("Show session status").action(async (name) => {
+  await sessionsStatusCommand(name);
+});
+sessionsCommand.command("logs <name>").description("Stream session output").action(async (name) => {
+  await sessionsLogsCommand(name);
+});
+sessionsCommand.command("kill <name>").description("Terminate a session").action(async (name) => {
+  await sessionsKillCommand(name);
+});
 program.on("command:*", (operands) => {
   console.error(`error: unknown command '${operands[0]}'`);
   process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saga-ai/cli",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "CLI for SAGA - Structured Autonomous Goal Achievement",
   "type": "module",
   "bin": {
@@ -60,7 +60,16 @@
     "typescript": "^5.7.0",
     "vite": "^6.0.5",
     "vitest": "^3.2.4",
-    "xstate": "^5.26.0"
+    "xstate": "^5.26.0",
+    "storybook": "^10.2.1",
+    "@storybook/react-vite": "^10.2.1",
+    "@chromatic-com/storybook": "^5.0.0",
+    "@storybook/addon-vitest": "^10.2.1",
+    "@storybook/addon-a11y": "^10.2.1",
+    "@storybook/addon-docs": "^10.2.1",
+    "@storybook/addon-onboarding": "^10.2.1",
+    "playwright": "^1.58.0",
+    "@vitest/browser": "^3.2.4"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -77,6 +86,8 @@
     "dev:client": "vite --config src/client/vite.config.ts",
     "test": "vitest run",
     "test:watch": "vitest",
-    "publish:npm": "pnpm build && pnpm test && pnpm publish --access public"
+    "publish:npm": "pnpm build && pnpm test && pnpm publish --access public",
+    "storybook": "storybook dev -p 6006 -c src/client/.storybook",
+    "build-storybook": "storybook build -c src/client/.storybook -o storybook-static"
   }
 }