@stackmemoryai/stackmemory 1.5.3 → 1.5.4

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

@@ -346,7 +346,11 @@ function createConductorCommands() {
     "--in-review <state>",
     "State name for completed review",
     "In Review"
-  ).option("--poll <ms>", "Polling interval in milliseconds", "30000").option("--concurrency <n>", "Max concurrent agents", "3").option("--workspace-root <path>", "Workspace root directory").option("--repo <path>", "Git repo root for worktrees", process.cwd()).option("--branch <name>", "Base branch for worktrees", "main").option("--retries <n>", "Max retries per issue", "1").option("--turn-timeout <ms>", "Agent turn timeout in ms", "3600000").action(async (options) => {
+  ).option("--poll <ms>", "Polling interval in milliseconds", "30000").option("--concurrency <n>", "Max concurrent agents", "3").option("--workspace-root <path>", "Workspace root directory").option("--repo <path>", "Git repo root for worktrees", process.cwd()).option("--branch <name>", "Base branch for worktrees", "main").option("--retries <n>", "Max retries per issue", "1").option("--turn-timeout <ms>", "Agent turn timeout in ms", "3600000").option(
+    "--mode <mode>",
+    'Agent mode: "cli" (claude -p, session auth) or "adapter" (JSON-RPC, API key)',
+    "cli"
+  ).action(async (options) => {
     const conductor = new Conductor({
       teamId: options.team,
       activeStates: options.states.split(",").map((s) => s.trim()),
@@ -358,7 +362,8 @@ function createConductorCommands() {
       repoRoot: options.repo,
       baseBranch: options.branch,
       maxRetries: parseInt(options.retries, 10),
-      turnTimeoutMs: parseInt(options.turnTimeout, 10)
+      turnTimeoutMs: parseInt(options.turnTimeout, 10),
+      agentMode: options.mode === "adapter" ? "adapter" : "cli"
     });
     await conductor.start();
   });

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

@@ -65,6 +65,35 @@ class TeeTransform extends Transform {
     callback();
   }
 }
+function inferPhaseFromStreamJson(event) {
+  if (event.type !== "assistant") return null;
+  const message = event.message;
+  const content = message?.content || [];
+  for (const block of content) {
+    if (block.type !== "tool_use") continue;
+    const toolLower = (block.name || "").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")) {
+      if (toolLower === "bash") {
+        const input = block.input;
+        const command = (input?.command ?? "").toLowerCase();
+        if (command.includes("git commit") || command.includes("git add")) {
+          return "committing";
+        }
+      }
+      return "implementing";
+    }
+    if (toolLower.includes("test")) {
+      return "testing";
+    }
+  }
+  return null;
+}
 function inferPhase(msg) {
   const method = msg.method;
   const params = msg.params;
@@ -85,7 +114,8 @@ function inferPhase(msg) {
     }
   }
   if (method === "item/commandExecution/started") {
-    const command = params?.command || "";
+    const args = params?.arguments;
+    const command = (args?.command ?? params?.command) || "";
     if (command.includes("git commit") || command.includes("git add")) {
       return "committing";
     }
@@ -110,7 +140,8 @@ const DEFAULT_CONFIG = {
   ),
   turnTimeoutMs: 36e5,
   maxRetries: 1,
-  hookTimeoutMs: 6e4
+  hookTimeoutMs: 6e4,
+  agentMode: "cli"
 };
 class Conductor {
   config;
@@ -642,13 +673,167 @@ class Conductor {
     return identifier.replace(/[^A-Za-z0-9._-]/g, "_");
   }
   // ── Agent Execution ──
-  runAgent(issue, run) {
+  async runAgent(issue, run) {
+    if (this.config.agentMode === "cli") {
+      try {
+        return await this.runAgentCLI(issue, run);
+      } catch (err) {
+        const msg = err.message || "";
+        if (msg.includes("usage limits") || msg.includes("rate_limit") || msg.includes("overloaded")) {
+          logger.warn("CLI mode hit limits, falling back to adapter", {
+            identifier: issue.identifier,
+            error: msg.slice(0, 200)
+          });
+          run.toolCalls = 0;
+          run.filesModified = 0;
+          run.tokensUsed = 0;
+          run.phase = "reading";
+          return this.runAgentAdapter(issue, run);
+        }
+        throw err;
+      }
+    }
+    return this.runAgentAdapter(issue, run);
+  }
+  /**
+   * CLI mode: spawn `claude -p --output-format stream-json` directly.
+   * Uses whatever auth the environment provides (session quota, API key, etc).
+   */
+  runAgentCLI(issue, run) {
+    return new Promise((resolve, reject) => {
+      const prompt = this.buildPrompt(issue, run.attempt);
+      const proc = spawn(
+        "claude",
+        [
+          "-p",
+          "--output-format",
+          "stream-json",
+          "--dangerously-skip-permissions",
+          prompt
+        ],
+        {
+          cwd: run.workspacePath,
+          env: (() => {
+            const env = { ...process.env };
+            delete env.CLAUDECODE;
+            delete env.ANTHROPIC_API_KEY;
+            return {
+              ...env,
+              SYMPHONY_WORKSPACE_DIR: run.workspacePath,
+              SYMPHONY_ISSUE_ID: issue.id,
+              SYMPHONY_ISSUE_IDENTIFIER: issue.identifier,
+              SYMPHONY_ATTEMPT: String(run.attempt)
+            };
+          })(),
+          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 lastResultText = "";
+      const timer = setTimeout(() => {
+        logger.warn("Agent turn timeout (cli)", {
+          identifier: issue.identifier,
+          timeoutMs: this.config.turnTimeoutMs
+        });
+        proc.kill("SIGTERM");
+        reject(new Error(`Agent timeout after ${this.config.turnTimeoutMs}ms`));
+      }, this.config.turnTimeoutMs);
+      let lineBuffer = "";
+      tee.on("data", (chunk) => {
+        lineBuffer += chunk.toString();
+        const lines = lineBuffer.split("\n");
+        lineBuffer = lines.pop() || "";
+        for (const line of lines) {
+          if (!line.trim()) continue;
+          try {
+            const event = JSON.parse(line);
+            const phase = inferPhaseFromStreamJson(event);
+            if (phase) {
+              run.phase = phase;
+            }
+            if (event.type === "assistant") {
+              const message = event.message;
+              const content = message?.content || [];
+              for (const block of content) {
+                if (block.type === "tool_use") {
+                  run.toolCalls++;
+                  const toolLower = (block.name || "").toLowerCase();
+                  if (toolLower.includes("edit") || toolLower.includes("write")) {
+                    run.filesModified++;
+                  }
+                }
+                if (block.type === "text" && block.text) {
+                  run.tokensUsed += Math.ceil(
+                    block.text.length / 4
+                  );
+                }
+              }
+            }
+            if (event.type === "result" && event.result) {
+              lastResultText = typeof event.result === "string" ? event.result : JSON.stringify(event.result);
+            }
+            if (run.toolCalls % 5 === 0 || phase) {
+              this.writeAgentStatus(issue.identifier, run);
+            }
+          } catch {
+          }
+        }
+      });
+      proc.stderr.on("data", (data) => {
+        stderr += data.toString();
+        const lines = data.toString().split("\n").filter((l) => l.trim());
+        for (const line of lines) {
+          logger.debug(`[${issue.identifier}] ${line}`);
+        }
+      });
+      proc.on("error", (err) => {
+        clearTimeout(timer);
+        reject(new Error(`Failed to spawn claude: ${err.message}`));
+      });
+      proc.on("close", (code) => {
+        clearTimeout(timer);
+        run.process = null;
+        if (run.logStream && !run.logStream.destroyed) {
+          run.logStream.end();
+        }
+        this.writeAgentStatus(issue.identifier, run);
+        if (code === 0) {
+          logger.info("Agent completed (cli)", {
+            identifier: issue.identifier,
+            toolCalls: run.toolCalls,
+            resultLength: lastResultText.length
+          });
+          resolve();
+        } else {
+          reject(
+            new Error(
+              `Claude exited with code ${code}: ${stderr.slice(0, 500)}`
+            )
+          );
+        }
+      });
+    });
+  }
+  /**
+   * Adapter mode: spawn claude-app-server.cjs via JSON-RPC protocol.
+   * Uses ANTHROPIC_API_KEY for auth.
+   */
+  runAgentAdapter(issue, run) {
     return new Promise((resolve, reject) => {
       const prompt = this.buildPrompt(issue, run.attempt);
+      const env = { ...process.env };
+      delete env.CLAUDECODE;
+      delete env.ANTHROPIC_API_KEY;
       const proc = spawn("node", [this.config.appServerPath], {
         cwd: run.workspacePath,
         env: {
-          ...process.env,
+          ...env,
           SYMPHONY_WORKSPACE_DIR: run.workspacePath,
           SYMPHONY_ISSUE_ID: issue.id,
           SYMPHONY_ISSUE_IDENTIFIER: issue.identifier,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackmemoryai/stackmemory",
-  "version": "1.5.3",
+  "version": "1.5.4",
   "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",

package/scripts/gepa/.before-optimize.md

@@ -21,26 +21,26 @@ docs/            # Documentation
 
 ## Key Files
 
-- Entry: src/cli/index.ts
-- MCP Server: src/integrations/mcp/server.ts
-- Frame Manager: src/core/context/frame-manager.ts
-- Database: src/core/database/sqlite-adapter.ts
-
-## Detailed Guides
-
-Quick reference (agent_docs/):
-- linear_integration.md - Linear sync
-- mcp_server.md - MCP tools
-- database_storage.md - Storage
-- claude_hooks.md - Hooks
-
-Full documentation (docs/):
-- principles.md - Agent programming paradigm
-- architecture.md - Extension model and browser sandbox
-- SPEC.md - Technical specification
-- API_REFERENCE.md - API docs
-- DEVELOPMENT.md - Dev guide
-- SETUP.md - Installation
+- Entry: `src/cli/index.ts`
+- MCP Server: `src/integrations/mcp/server.ts`
+- Frame Manager: `src/core/context/frame-manager.ts`
+- Database: `src/core/database/sqlite-adapter.ts`
+
+## Reference Docs
+
+`agent_docs/` (quick reference):
+- `linear_integration.md` — Linear sync
+- `mcp_server.md` — MCP tools
+- `database_storage.md` — Storage
+- `claude_hooks.md` — Hooks
+
+`docs/` (full documentation):
+- `principles.md` — Agent programming paradigm
+- `architecture.md` — Extension model and browser sandbox
+- `SPEC.md` — Technical specification
+- `API_REFERENCE.md` — API docs
+- `DEVELOPMENT.md` — Dev guide
+- `SETUP.md` — Installation
 
 ## Commands
 
@@ -53,49 +53,53 @@ npm run test:run       # Run tests once
 npm run linear:sync    # Sync with Linear
 
 # StackMemory CLI
-stackmemory capture    # Save session state for handoff
-stackmemory restore    # Restore from captured state
+stackmemory capture          # Save session state for handoff
+stackmemory restore          # Restore from captured state
+stackmemory snapshot save    # Post-run context snapshot (alias: snap)
+stackmemory snapshot list    # List recent snapshots
+stackmemory preflight        # File overlap check for parallel tasks (alias: pf)
+stackmemory conductor start  # Autonomous Linear→worktree→agent orchestrator
 ```
 
 ## Working Directory
 
-- PRIMARY: /Users/jwu/Dev/stackmemory
+- PRIMARY: `/Users/jwu/Dev/stackmemory`
 - ALLOWED: All subdirectories
-- TEMP: /tmp for temporary operations
+- TEMP: `/tmp` for temporary operations
 
 ## Validation (MUST DO)
 
-After code changes:
-1. `npm run lint` - fix any errors AND warnings
-2. `npm run test:run` - verify no regressions
-3. `npm run build` - ensure compilation
-4. Run code to verify it works
+Run these checks after every code change — in order:
 
-Test coverage:
+1. `npm run lint` — fix all errors and warnings
+2. `npm run test:run` — confirm no regressions
+3. `npm run build` — confirm compilation succeeds
+4. Execute the code and verify it works
+
+Test coverage rules:
 - New features require tests in `src/**/__tests__/`
-- Maintain or improve coverage (no untested code paths)
+- Maintain or improve coverage — no untested code paths
 - Critical paths: context management, handoff, Linear sync
 
-Never: Assume success | Skip testing | Use mock data as fallback
+**Never:** assume success | skip testing | use mock data as fallback
 
 ## Git Rules (CRITICAL)
 
-- NEVER use `--no-verify` on git push or commit
-- ALWAYS fix lint/test errors before pushing
-- If pre-push hooks fail, fix the underlying issue
-- Run `npm run lint && npm run test:run` before pushing
-- Commit message format: `type(scope): message`
-- Branch naming: `feature/STA-XXX-description` | `fix/STA-XXX-description` | `chore/description`
+- NEVER use `--no-verify` on `git push` or `git commit`
+- Fix lint/test errors before pushing — never bypass pre-push hooks
+- Run `npm run lint && npm run test:run` before every push
+- Commit format: `type(scope): message`
+- Branch format: `feature/STA-XXX-description` | `fix/STA-XXX-description` | `chore/description`
 
 ## Task Management
 
-- Use TodoWrite for 3+ steps or multiple requests
-- Keep one task in_progress at a time
-- Update task status immediately on completion
+- Use TodoWrite for 3+ steps or multiple concurrent requests
+- Keep exactly one task `in_progress` at a time
+- Update task status immediately when complete
 
 ## Security
 
-NEVER hardcode secrets - use process.env with dotenv/config
+Never hardcode secrets — always use `process.env` with `dotenv/config`:
 
 ```javascript
 import 'dotenv/config';
@@ -106,18 +110,18 @@ if (!API_KEY) {
 }
 ```
 
-Environment sources (check in order):
-1. .env file
-2. .env.local
-3. ~/.zshrc
+Check for API keys in this order:
+1. `.env`
+2. `.env.local`
+3. `~/.zshrc`
 4. Process environment
 
-Secret patterns to block: lin_api_* | lin_oauth_* | sk-* | npm_*
+Block these secret patterns: `lin_api_*` | `lin_oauth_*` | `sk-*` | `npm_*`
 
 ## Deploy
 
 ```bash
-# npm publish (uses NPM_TOKEN from .env, no OTP needed)
+# npm publish (NPM_TOKEN from .env — no OTP required)
 git stash -- scripts/gepa/           # stash GEPA state (dirties working tree)
 NPM_TOKEN=$(grep '^NPM_TOKEN=' .env | cut -d= -f2) \
   npm publish --registry https://registry.npmjs.org/ \
@@ -127,14 +131,46 @@ git stash pop                         # restore GEPA state
 # Railway
 railway up
 
-# Pre-publish checks require clean git status — stash GEPA files first
+# Pre-publish requires clean git status — always stash GEPA files first
 ```
 
+## Task Delegation Model
+
+Match effort to task complexity:
+
+**AUTOMATE** — Execute immediately; lint+test is sufficient:
+- CRUD, boilerplate, formatting, simple transforms
+- Adding a handler following an existing switch/case pattern
+- Config additions (env var, feature flag)
+
+**STANDARD** — Normal workflow; lint+test+build:
+- Feature implementation, bug fixes, refactoring
+- New tests, documentation updates
+- Integration wiring (adding handler to `server.ts` dispatch)
+
+**CAREFUL** — Review approach before writing code:
+- API/schema changes, database migrations, auth flows
+- New integration patterns (MCP tools, webhook handlers)
+- Changes to `frame-manager`, `sqlite-adapter`, or daemon lifecycle
+- Anything touching error handling chains
+
+**ARCHITECT** — Require plan mode; explore existing patterns first:
+- New service boundaries or system integrations
+- Performance-critical paths (FTS5 queries, search scoring)
+- Breaking changes to MCP protocol or CLI interface
+
+**HUMAN** — Get explicit user approval before any changes:
+- Security-critical decisions, secret handling
+- Irreversible operations (data migrations, schema drops)
+- Publishing (`npm publish`, Railway deploy)
+
+Don't over-engineer AUTOMATE tasks. Don't under-review CAREFUL ones.
+
 ## Workflow
 
-- Check .env for API keys before asking
-- Run npm run linear:sync after task completion
+- Check `.env` for API keys before asking the user
+- Run `npm run linear:sync` after completing tasks
 - Use browser MCP for visual testing
-- Review recent commits and stackmemory.json on session start
+- On session start: review recent commits and `stackmemory.json`
 - Use subagents for multi-step tasks
-- Ask 1-3 clarifying questions for complex commands (one at a time)
+- Ask 1–3 clarifying questions for ambiguous requests (one at a time)

package/scripts/gepa/generations/gen-000/baseline.md

@@ -25,6 +25,10 @@ docs/            # Documentation
 - MCP Server: src/integrations/mcp/server.ts
 - Frame Manager: src/core/context/frame-manager.ts
 - Database: src/core/database/sqlite-adapter.ts
+- Snapshot: src/core/worktree/capture.ts
+- Preflight: src/core/worktree/preflight.ts
+- Conductor: src/cli/commands/orchestrator.ts
+- Shared Utils: src/core/utils/{git,text,fs}.ts
 
 ## Detailed Guides
 
@@ -55,6 +59,10 @@ npm run linear:sync    # Sync with Linear
 # StackMemory CLI
 stackmemory capture    # Save session state for handoff
 stackmemory restore    # Restore from captured state
+stackmemory snapshot save  # Post-run context snapshot (alias: snap)
+stackmemory snapshot list  # List recent snapshots
+stackmemory preflight      # File overlap check for parallel tasks (alias: pf)
+stackmemory conductor start  # Autonomous Linear→worktree→agent orchestrator
 ```
 
 ## Working Directory

package/scripts/gepa/generations/gen-001/baseline.md

@@ -25,6 +25,10 @@ docs/            # Documentation
 - MCP Server: src/integrations/mcp/server.ts
 - Frame Manager: src/core/context/frame-manager.ts
 - Database: src/core/database/sqlite-adapter.ts
+- Snapshot: src/core/worktree/capture.ts
+- Preflight: src/core/worktree/preflight.ts
+- Conductor: src/cli/commands/orchestrator.ts
+- Shared Utils: src/core/utils/{git,text,fs}.ts
 
 ## Detailed Guides
 
@@ -55,6 +59,10 @@ npm run linear:sync    # Sync with Linear
 # StackMemory CLI
 stackmemory capture    # Save session state for handoff
 stackmemory restore    # Restore from captured state
+stackmemory snapshot save  # Post-run context snapshot (alias: snap)
+stackmemory snapshot list  # List recent snapshots
+stackmemory preflight      # File overlap check for parallel tasks (alias: pf)
+stackmemory conductor start  # Autonomous Linear→worktree→agent orchestrator
 ```
 
 ## Working Directory