@stackmemoryai/stackmemory 1.5.1 → 1.5.3

package/README.md

@@ -24,7 +24,8 @@ StackMemory is a **production-ready memory runtime** for AI coding tools that pr
 - **Automatic hooks** for task tracking, Linear sync, and spec progress
 - **Snapshot capture** — post-run context snapshots for session handoff (`snapshot save`)
 - **Pre-flight overlap check** — predict file conflicts before parallel task dispatch (`preflight`)
-- **Conductor orchestrator** — polls Linear, creates worktrees, spawns agents with bounded concurrency
+- **Conductor orchestrator** — polls Linear, creates worktrees, spawns agents with bounded concurrency and auto team detection
+- **Loop/Watch command** — poll any shell command until a condition is met (monitor CI, deploys, logs)
 - **Memory monitor daemon** with automatic capture/clear on RAM pressure
 - **Auto-save service** for periodic context persistence
 - **Comprehensive test coverage** across all core modules
@@ -68,6 +69,8 @@ Tools forget decisions and constraints between sessions. StackMemory makes conte
 - **Safe branches**: worktree isolation with `--worktree` or `-w`
 - **Snapshot**: post-run context capture — records what changed, commits, and decisions (`stackmemory snapshot`)
 - **Pre-flight check**: file overlap prediction before parallel task dispatch (`stackmemory preflight`)
+- **Loop/Watch**: poll shell commands until conditions are met — monitor CI, deploys, logs (`stackmemory loop`)
+- **Conductor**: autonomous orchestrator — polls Linear, creates worktrees, spawns agents with auto team detection
 - **Persistent context**: frames, anchors, decisions, retrieval
 - **Integrations**: Linear (API key + OAuth), DiffMem, Browser MCP, log-mcp (log analysis)
 
@@ -389,6 +392,26 @@ stackmemory pf "auth work" "db migration" -f "task1:src/auth.ts;task2:src/db.ts"
 stackmemory pf "task A" "task B" "task C" --json
 ```
 
+### Loop / Watch (`loop` / `watch`)
+
+Poll a shell command until a condition is met. Useful for monitoring CI runs, deploy logs, inboxes, or any external state.
+
+```bash
+# Monitor GitHub Actions until complete
+stackmemory loop "gh run view <id> --json status -q .status" --until "completed"
+
+# Watch deploy logs for success
+stackmemory watch "railway logs --latest" --until "deployed" -i 5s
+
+# Wait for health check to pass
+stackmemory loop "curl -s http://localhost:3000/health" --until "ok" -i 3s -t 5m
+
+# JSON output for programmatic use
+stackmemory loop "gh pr checks 42 --json state -q '.[0].state'" --until "SUCCESS" --json
+```
+
+Options: `--until`, `--until-not`, `--until-empty`, `--until-non-empty`, `--until-exit`, `-i/--interval` (default 10s), `-t/--timeout` (default 30m), `--json`, `-q/--quiet`
+
 ---
 
 ## Documentation

package/dist/src/cli/commands/dashboard.js

@@ -8,7 +8,7 @@ import Table from "cli-table3";
 import { SessionManager } from "../../core/session/session-manager.js";
 import Database from "better-sqlite3";
 import { join } from "path";
-import { existsSync } from "fs";
+import { existsSync, readFileSync } from "fs";
 import { getModelTokenLimit } from "../../core/models/model-router.js";
 const dashboardCommand = {
   command: "dashboard",
@@ -150,6 +150,52 @@ const dashboardCommand = {
       console.log(chalk.yellow.bold("\u{1F4BE} Context Usage"));
       console.log(`${usageBar} ${contextUsage}%`);
       console.log();
+      const conductorStatusPath = join(
+        projectRoot,
+        ".stackmemory",
+        "conductor-status.json"
+      );
+      if (existsSync(conductorStatusPath)) {
+        try {
+          const raw = readFileSync(conductorStatusPath, "utf-8");
+          const conductorStatus = JSON.parse(raw);
+          const stale = Date.now() - conductorStatus.updatedAt > 12e4;
+          const header = stale ? chalk.gray.bold("\u2699 Conductor (stale)") : chalk.yellow.bold("\u2699 Conductor");
+          console.log(header);
+          if (conductorStatus.running.length > 0) {
+            const conductorTable = new Table({
+              head: [
+                chalk.white("Issue"),
+                chalk.white("Status"),
+                chalk.white("Title"),
+                chalk.white("Runtime")
+              ],
+              style: { head: [], border: [] },
+              colWidths: [12, 14, 36, 10]
+            });
+            conductorStatus.running.forEach((r) => {
+              const mins = Math.round(r.runtime / 6e4);
+              const statusColor = r.status === "running" ? chalk.green : r.status === "completed" ? chalk.cyan : chalk.red;
+              conductorTable.push([
+                r.identifier,
+                statusColor(r.status),
+                r.title.slice(0, 34),
+                `${mins}m`
+              ]);
+            });
+            console.log(conductorTable.toString());
+          } else {
+            console.log(chalk.gray("  No agents running"));
+          }
+          console.log(
+            chalk.gray(
+              `  Completed: ${conductorStatus.completed}  Failed: ${conductorStatus.failed}  Max: ${conductorStatus.maxConcurrent}`
+            )
+          );
+          console.log();
+        } catch {
+        }
+      }
       db.close();
       if (argv.watch) {
         console.log(

package/dist/src/cli/commands/orchestrate.js

@@ -3,13 +3,20 @@ import { dirname as __pathDirname } from 'path';
 const __filename = __fileURLToPath(import.meta.url);
 const __dirname = __pathDirname(__filename);
 import { Command } from "commander";
-import { execSync } from "child_process";
-import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { execSync, spawn as cpSpawn } from "child_process";
+import {
+  existsSync,
+  mkdirSync,
+  writeFileSync,
+  readFileSync,
+  readdirSync
+} from "fs";
 import { join } from "path";
 import { homedir, tmpdir } from "os";
 import Database from "better-sqlite3";
 import { logger } from "../../core/monitoring/logger.js";
 import { Conductor } from "./orchestrator.js";
+import { getAgentStatusDir } from "./orchestrator.js";
 function getGlobalStorePath() {
   const dir = join(homedir(), ".stackmemory", "conductor");
   if (!existsSync(dir)) {
@@ -43,6 +50,16 @@ function getGlobalDb() {
   `);
   return db;
 }
+function formatElapsed(ms) {
+  const seconds = Math.floor(ms / 1e3);
+  if (seconds < 60) return `${seconds}s ago`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}
 function createConductorCommands() {
   const cmd = new Command("conductor");
   cmd.description("Conductor \u2014 autonomous agent orchestration via Linear");
@@ -263,6 +280,60 @@ function createConductorCommands() {
     }
     globalDb.close();
   });
+  cmd.command("status").description("Show running agent status table").action(async () => {
+    const agentsDir = join(homedir(), ".stackmemory", "conductor", "agents");
+    if (!existsSync(agentsDir)) {
+      console.log("No agent status files found");
+      return;
+    }
+    const entries = readdirSync(agentsDir, { withFileTypes: true });
+    const statuses = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const statusPath = join(agentsDir, entry.name, "status.json");
+      if (!existsSync(statusPath)) continue;
+      try {
+        const data = JSON.parse(readFileSync(statusPath, "utf-8"));
+        statuses.push(data);
+      } catch {
+      }
+    }
+    if (statuses.length === 0) {
+      console.log("No agent status files found");
+      return;
+    }
+    statuses.sort(
+      (a, b) => new Date(b.lastUpdate).getTime() - new Date(a.lastUpdate).getTime()
+    );
+    const header = `${"Issue".padEnd(12)}${"Phase".padEnd(16)}${"Tools".padStart(7)}${"Files".padStart(7)}${"Tokens".padStart(9)}   Last Update`;
+    console.log(header);
+    for (const s of statuses) {
+      const elapsed = Date.now() - new Date(s.lastUpdate).getTime();
+      const lastUpdate = formatElapsed(elapsed);
+      const line = `${s.issue.padEnd(12)}${s.phase.padEnd(16)}${String(s.toolCalls).padStart(7)}${String(s.filesModified).padStart(7)}${String(s.tokensUsed).padStart(9)}   ${lastUpdate}`;
+      console.log(line);
+    }
+  });
+  cmd.command("logs").description("Tail agent output log").argument("<issue-id>", "Issue identifier (e.g., STA-499)").option("-f, --follow", "Follow the log (tail -f)", false).option("-n, --lines <n>", "Number of lines to show", "50").action(async (issueId, options) => {
+    const logPath = join(getAgentStatusDir(issueId), "output.log");
+    if (!existsSync(logPath)) {
+      console.error(`No log file found for ${issueId} at ${logPath}`);
+      return;
+    }
+    const lines = parseInt(options.lines, 10);
+    const args = options.follow ? ["-f", "-n", String(lines), logPath] : ["-n", String(lines), logPath];
+    const tail = cpSpawn("tail", args, { stdio: "inherit" });
+    await new Promise((resolve) => {
+      tail.on("close", () => {
+        resolve();
+      });
+      const forward = () => {
+        tail.kill("SIGTERM");
+      };
+      process.on("SIGINT", forward);
+      process.on("SIGTERM", forward);
+    });
+  });
   cmd.command("start").description("Start the orchestrator daemon").option("--team <id>", "Linear team ID").option(
     "--states <states>",
     "Comma-separated issue states to pick up",
@@ -294,5 +365,6 @@ function createConductorCommands() {
   return cmd;
 }
 export {
-  createConductorCommands
+  createConductorCommands,
+  formatElapsed
 };

package/dist/src/cli/commands/orchestrator.js

@@ -3,10 +3,17 @@ import { dirname as __pathDirname } from 'path';
 const __filename = __fileURLToPath(import.meta.url);
 const __dirname = __pathDirname(__filename);
 import { spawn, execSync } from "child_process";
-import { existsSync, mkdirSync, rmSync } from "fs";
+import {
+  existsSync,
+  mkdirSync,
+  rmSync,
+  writeFileSync,
+  createWriteStream
+} from "fs";
 import { join, dirname } from "path";
-import { tmpdir } from "os";
+import { tmpdir, homedir } from "os";
 import { fileURLToPath } from "url";
+import { Transform } from "stream";
 import { logger } from "../../core/monitoring/logger.js";
 import {
   LinearClient
@@ -26,6 +33,65 @@ function findPackageRoot() {
   }
   return dirname(currentFile);
 }
+function getAgentStatusDir(issueIdentifier) {
+  return join(
+    homedir(),
+    ".stackmemory",
+    "conductor",
+    "agents",
+    issueIdentifier
+  );
+}
+function ensureAgentStatusDir(issueIdentifier) {
+  const dir = getAgentStatusDir(issueIdentifier);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  return dir;
+}
+class TeeTransform extends Transform {
+  logStream;
+  constructor(logStream) {
+    super();
+    this.logStream = logStream;
+  }
+  _transform(chunk, _encoding, callback) {
+    this.logStream.write(chunk);
+    this.push(chunk);
+    callback();
+  }
+  _flush(callback) {
+    this.logStream.end();
+    callback();
+  }
+}
+function inferPhase(msg) {
+  const method = msg.method;
+  const params = msg.params;
+  if (method === "item/commandExecution/started") {
+    const tool = params?.tool || params?.name || "";
+    const toolLower = tool.toLowerCase();
+    if (toolLower.includes("read") || toolLower.includes("glob") || toolLower.includes("grep") || toolLower.includes("search")) {
+      return "reading";
+    }
+    if (toolLower.includes("todowrite") || toolLower.includes("todo")) {
+      return "planning";
+    }
+    if (toolLower.includes("edit") || toolLower.includes("write") || toolLower.includes("bash")) {
+      return "implementing";
+    }
+    if (toolLower.includes("test")) {
+      return "testing";
+    }
+  }
+  if (method === "item/commandExecution/started") {
+    const command = params?.command || "";
+    if (command.includes("git commit") || command.includes("git add")) {
+      return "committing";
+    }
+  }
+  return null;
+}
 const DEFAULT_CONFIG = {
   activeStates: ["Todo"],
   terminalStates: ["Done", "Cancelled", "Canceled", "Closed"],
@@ -105,6 +171,21 @@ class Conductor {
       mkdirSync(this.config.workspaceRoot, { recursive: true });
     }
     this.client = await this.createLinearClient();
+    if (!this.config.teamId && this.client) {
+      try {
+        const team = await this.client.getTeam();
+        this.config.teamId = team.id;
+        logger.info("Auto-detected Linear team", {
+          id: team.id,
+          name: team.name,
+          key: team.key
+        });
+      } catch (err) {
+        logger.warn("Failed to auto-detect team", {
+          error: err.message
+        });
+      }
+    }
     await this.cacheWorkflowStates();
     logger.info("Orchestrator started", {
       activeStates: this.config.activeStates,
@@ -115,6 +196,7 @@ class Conductor {
     console.log(
       `Orchestrator started \u2014 polling every ${this.config.pollIntervalMs / 1e3}s, max ${this.config.maxConcurrent} concurrent`
     );
+    this.writeStatusFile();
     const shutdown = () => this.stop();
     process.on("SIGINT", shutdown);
     process.on("SIGTERM", shutdown);
@@ -160,6 +242,7 @@ class Conductor {
     }
     this.running.clear();
     this.claimed.clear();
+    this.clearStatusFile();
     console.log(
       `Orchestrator stopped. Completed: ${this.completeCount}, Failed: ${this.failCount}`
     );
@@ -183,6 +266,82 @@ class Conductor {
       issues
     };
   }
+  // ── Status File ──
+  /**
+   * Write current conductor state to .stackmemory/conductor-status.json
+   * for consumption by `stackmemory dashboard` and other tools.
+   */
+  writeStatusFile() {
+    const statusDir = join(this.config.repoRoot, ".stackmemory");
+    if (!existsSync(statusDir)) return;
+    const status = {
+      pid: process.pid,
+      startedAt: this.startedAt,
+      updatedAt: Date.now(),
+      running: Array.from(this.running.values()).map((r) => ({
+        identifier: r.issue.identifier,
+        title: r.issue.title,
+        status: r.status,
+        attempt: r.attempt,
+        startedAt: r.startedAt,
+        runtime: Date.now() - r.startedAt
+      })),
+      queued: Array.from(this.claimed).filter(
+        (id) => !this.running.has(id) && !this.completed.has(id)
+      ).length,
+      completed: this.completeCount,
+      failed: this.failCount,
+      totalAttempts: this.totalAttempts,
+      maxConcurrent: this.config.maxConcurrent,
+      stopping: this.stopping
+    };
+    try {
+      writeFileSync(
+        join(statusDir, "conductor-status.json"),
+        JSON.stringify(status, null, 2)
+      );
+    } catch {
+    }
+  }
+  clearStatusFile() {
+    const statusPath = join(
+      this.config.repoRoot,
+      ".stackmemory",
+      "conductor-status.json"
+    );
+    try {
+      if (existsSync(statusPath)) rmSync(statusPath);
+    } catch {
+    }
+  }
+  // ── Agent Status Files ──
+  /**
+   * Write per-agent status to ~/.stackmemory/conductor/agents/<issue-id>/status.json
+   */
+  writeAgentStatus(issueIdentifier, run) {
+    try {
+      const dir = ensureAgentStatusDir(issueIdentifier);
+      const status = {
+        issue: issueIdentifier,
+        pid: run.process?.pid || process.pid,
+        started: new Date(run.startedAt).toISOString(),
+        lastUpdate: (/* @__PURE__ */ new Date()).toISOString(),
+        phase: run.phase,
+        filesModified: run.filesModified,
+        toolCalls: run.toolCalls,
+        tokensUsed: run.tokensUsed
+      };
+      writeFileSync(join(dir, "status.json"), JSON.stringify(status, null, 2));
+    } catch {
+    }
+  }
+  /**
+   * Open a log file write stream for an agent.
+   */
+  openAgentLogStream(issueIdentifier) {
+    const dir = ensureAgentStatusDir(issueIdentifier);
+    return createWriteStream(join(dir, "output.log"), { flags: "a" });
+  }
   // ── Polling ──
   async schedulePoll() {
     while (!this.stopping) {
@@ -195,6 +354,7 @@ class Conductor {
       } catch (err) {
         logger.error("Poll cycle failed", { error: err.message });
       }
+      this.writeStatusFile();
     }
   }
   async poll() {
@@ -322,8 +482,13 @@ class Conductor {
       process: null,
       attempt: 1,
       startedAt: Date.now(),
-      status: "starting"
+      status: "starting",
+      phase: "reading",
+      toolCalls: 0,
+      filesModified: 0,
+      tokensUsed: 0
     };
+    this.writeAgentStatus(issue.identifier, run);
     this.running.set(issueId, run);
     this.totalAttempts++;
     console.log(`[${issue.identifier}] Dispatching: ${issue.title}`);
@@ -332,23 +497,26 @@ class Conductor {
       run.workspacePath = workspacePath;
       await this.transitionIssue(issue, this.config.inProgressState);
       await this.runHook("after-create", workspacePath, issue);
-      run.status = "running";
-      await this.runAgent(issue, run);
-      run.status = "completed";
-      this.completeCount++;
-      await this.runHook("after-run", workspacePath, issue, run.attempt);
-      this.takeSnapshot(workspacePath, issue);
-      await this.transitionIssue(issue, this.config.inReviewState);
-      console.log(`[${issue.identifier}] Completed successfully`);
+      await this.attemptRun(issue, run);
     } catch (err) {
-      run.status = "failed";
-      run.error = err.message;
-      logger.error("Issue dispatch failed", {
-        identifier: issue.identifier,
-        error: run.error,
-        attempt: run.attempt
-      });
-      if (run.workspacePath) {
+      this.failCount++;
+      console.log(`[${issue.identifier}] Failed: ${err.message}`);
+    } finally {
+      this.running.delete(issueId);
+      this.writeStatusFile();
+    }
+  }
+  /**
+   * Run the agent with retry logic. Throws on final failure.
+   */
+  async attemptRun(issue, run) {
+    const maxAttempts = this.config.maxRetries + 1;
+    while (run.attempt <= maxAttempts) {
+      try {
+        run.status = "running";
+        await this.runAgent(issue, run);
+        run.status = "completed";
+        this.completeCount++;
         await this.runHook(
           "after-run",
           run.workspacePath,
@@ -356,47 +524,44 @@ class Conductor {
           run.attempt
         ).catch(() => {
         });
-      }
-      if (run.attempt < this.config.maxRetries + 1) {
+        this.takeSnapshot(run.workspacePath, issue);
+        await this.transitionIssue(issue, this.config.inReviewState);
         console.log(
-          `[${issue.identifier}] Failed (attempt ${run.attempt}), retrying...`
+          run.attempt === 1 ? `[${issue.identifier}] Completed successfully` : `[${issue.identifier}] Completed on retry ${run.attempt}`
         );
-        run.attempt++;
-        this.totalAttempts++;
-        const backoffMs = Math.min(1e3 * Math.pow(2, run.attempt - 1), 3e5);
-        await new Promise((r) => setTimeout(r, backoffMs));
-        if (!this.stopping) {
-          try {
-            run.status = "running";
-            await this.runAgent(issue, run);
-            run.status = "completed";
-            this.completeCount++;
-            await this.runHook(
-              "after-run",
-              run.workspacePath,
-              issue,
-              run.attempt
-            ).catch(() => {
-            });
-            await this.transitionIssue(issue, this.config.inReviewState);
-            console.log(
-              `[${issue.identifier}] Completed on retry ${run.attempt}`
-            );
-          } catch (retryErr) {
-            run.status = "failed";
-            run.error = retryErr.message;
-            this.failCount++;
-            console.log(
-              `[${issue.identifier}] Failed after ${run.attempt} attempts: ${run.error}`
-            );
-          }
+        return;
+      } catch (err) {
+        run.status = "failed";
+        run.error = err.message;
+        logger.error("Agent run failed", {
+          identifier: issue.identifier,
+          error: run.error,
+          attempt: run.attempt
+        });
+        if (run.workspacePath) {
+          await this.runHook(
+            "after-run",
+            run.workspacePath,
+            issue,
+            run.attempt
+          ).catch(() => {
+          });
+        }
+        if (run.attempt < maxAttempts && !this.stopping) {
+          console.log(
+            `[${issue.identifier}] Failed (attempt ${run.attempt}), retrying...`
+          );
+          run.attempt++;
+          this.totalAttempts++;
+          const backoffMs = Math.min(
+            1e3 * Math.pow(2, run.attempt - 1),
+            3e5
+          );
+          await new Promise((r) => setTimeout(r, backoffMs));
+        } else {
+          throw err;
         }
-      } else {
-        this.failCount++;
-        console.log(`[${issue.identifier}] Failed: ${run.error}`);
       }
-    } finally {
-      this.running.delete(issueId);
     }
   }
   // ── Workspace Management ──
@@ -492,6 +657,11 @@ class Conductor {
         stdio: ["pipe", "pipe", "pipe"]
       });
       run.process = proc;
+      const logStream = this.openAgentLogStream(issue.identifier);
+      run.logStream = logStream;
+      const tee = new TeeTransform(logStream);
+      proc.stdout.pipe(tee);
+      this.writeAgentStatus(issue.identifier, run);
       let stderr = "";
       let turnCompleted = false;
       const timer = setTimeout(() => {
@@ -510,7 +680,7 @@ class Conductor {
         proc.stdin.write(JSON.stringify(msg) + "\n");
       };
       let lineBuffer = "";
-      proc.stdout.on("data", (chunk) => {
+      tee.on("data", (chunk) => {
         lineBuffer += chunk.toString();
         const lines = lineBuffer.split("\n");
         lineBuffer = lines.pop() || "";
@@ -519,11 +689,33 @@ class Conductor {
           try {
             const msg = JSON.parse(line);
             this.handleAgentMessage(msg, issue, run);
+            const phase = inferPhase(msg);
+            if (phase) {
+              run.phase = phase;
+            }
+            if (msg.method === "item/commandExecution/started" || msg.method === "item/toolUse/started") {
+              run.toolCalls++;
+            }
+            const params = msg.params;
+            if (msg.method === "item/commandExecution/started" && params) {
+              const tool = (params.tool || params.name || "").toLowerCase();
+              if (tool.includes("edit") || tool.includes("write")) {
+                run.filesModified++;
+              }
+            }
+            if (msg.method === "item/text" && params?.text) {
+              run.tokensUsed += Math.ceil(params.text.length / 4);
+            }
+            if (run.toolCalls % 5 === 0 || phase) {
+              this.writeAgentStatus(issue.identifier, run);
+            }
             if (msg.method === "turn/completed") {
               turnCompleted = true;
+              this.writeAgentStatus(issue.identifier, run);
             }
             if (msg.method === "turn/failed") {
               turnCompleted = true;
+              this.writeAgentStatus(issue.identifier, run);
               const errMsg = msg.params?.error?.message || "Agent turn failed";
               clearTimeout(timer);
               reject(new Error(errMsg));
@@ -547,6 +739,10 @@ class Conductor {
       proc.on("close", (code) => {
         clearTimeout(timer);
         run.process = null;
+        if (run.logStream && !run.logStream.destroyed) {
+          run.logStream.end();
+        }
+        this.writeAgentStatus(issue.identifier, run);
         if (turnCompleted) {
           resolve();
         } else if (code === 0) {
@@ -785,5 +981,6 @@ class Conductor {
   }
 }
 export {
-  Conductor
+  Conductor,
+  getAgentStatusDir
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stackmemoryai/stackmemory",
-  "version": "1.5.1",
-  "description": "Project-scoped memory for AI coding tools. Durable context across sessions with 56 MCP tools, FTS5 search, Claude/Codex/OpenCode wrappers, Linear sync, automatic hooks, and log analysis.",
+  "version": "1.5.3",
+  "description": "Lossless, project-scoped memory for AI coding tools. Durable context across sessions with 56 MCP tools, FTS5 search, conductor orchestrator, loop/watch monitoring, snapshot capture, pre-flight overlap checks, Claude/Codex/OpenCode wrappers, Linear sync, and automatic hooks.",
   "engines": {
     "node": ">=20.0.0",
     "npm": ">=10.0.0"