@stackmemoryai/stackmemory 1.10.5 → 1.14.0

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

@@ -20,6 +20,10 @@ import { FrameManager } from "../../core/context/index.js";
 import { LinearTaskManager } from "../../features/tasks/linear-task-manager.js";
 import { logger } from "../../core/monitoring/logger.js";
 import { EnhancedHandoffGenerator } from "../../core/session/handoff.js";
+import {
+  getProjectHandoffPaths,
+  loadProjectHandoff
+} from "../../core/session/project-handoff.js";
 const countTokens = (text) => Math.ceil(text.length / 3.5);
 const MAX_HANDOFF_VERSIONS = 10;
 function saveVersionedHandoff(projectRoot, branch, content) {
@@ -273,7 +277,7 @@ Generated by stackmemory capture at ${timestamp}
       if (!existsSync(stackmemoryDir)) {
         mkdirSync(stackmemoryDir, { recursive: true });
       }
-      const handoffPath = join(stackmemoryDir, "last-handoff.md");
+      const { handoffPath, metadataPath } = getProjectHandoffPaths(projectRoot);
       writeFileSync(handoffPath, handoffPrompt);
       let branch = "unknown";
       try {
@@ -289,6 +293,18 @@ Generated by stackmemory capture at ${timestamp}
         branch,
         handoffPrompt
       );
+      writeFileSync(
+        metadataPath,
+        JSON.stringify(
+          {
+            branch,
+            capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+            projectRoot
+          },
+          null,
+          2
+        )
+      );
       console.log(
         `Versioned: ${versionedPath.split("/").slice(-2).join("/")}`
       );
@@ -331,26 +347,41 @@ Generated by stackmemory capture at ${timestamp}
 }
 function createRestoreCommand() {
   const cmd = new Command("restore");
-  cmd.description("Restore context from last handoff").option("--no-copy", "Do not copy prompt to clipboard").action(async (options) => {
+  cmd.description("Restore context from last handoff").option("--no-copy", "Do not copy prompt to clipboard").option("--force", "Restore even if the handoff branch does not match").action(async (options) => {
     try {
       const projectRoot = process.cwd();
-      const handoffPath = join(
-        projectRoot,
-        ".stackmemory",
-        "last-handoff.md"
-      );
       const metaPath = join(
         process.env["HOME"] || "~",
         ".stackmemory",
         "handoffs",
         "last-handoff-meta.json"
       );
-      if (!existsSync(handoffPath)) {
+      const currentBranch = (() => {
+        try {
+          return execSync("git rev-parse --abbrev-ref HEAD", {
+            encoding: "utf-8",
+            cwd: projectRoot,
+            stdio: ["pipe", "pipe", "pipe"]
+          }).trim();
+        } catch {
+          return void 0;
+        }
+      })();
+      const handoff = loadProjectHandoff(projectRoot, currentBranch);
+      if (!handoff) {
         console.log("\u274C No handoff found in this project");
         console.log('\u{1F4A1} Run "stackmemory capture" to create one');
         return;
       }
-      const handoffPrompt = readFileSync(handoffPath, "utf-8");
+      if (!handoff.compatible && !options.force) {
+        console.log("\u26A0\uFE0F  Skipping stale handoff");
+        console.log(`   ${handoff.mismatchReason}`);
+        console.log(
+          '   Run "stackmemory restore --force" to inspect it anyway'
+        );
+        return;
+      }
+      const handoffPrompt = handoff.content;
       console.log("\n" + "=".repeat(60));
       console.log("\u{1F4CB} RESTORED HANDOFF");
       console.log("=".repeat(60));

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

@@ -383,6 +383,67 @@ DATABASE_URL=${config.databaseUrl}
       console.log(chalk.yellow("  \u26A0 Could not write hosted DB env file"));
     }
   }
+  {
+    const claudeCommandsDir = join(homedir(), ".claude", "commands");
+    const packsDir = join(__dirname, "..", "..", "..", "packs");
+    const coreManifest = join(packsDir, "core", "manifest.json");
+    if (existsSync(coreManifest)) {
+      const { installCommands } = await inquirer.prompt([
+        {
+          type: "confirm",
+          name: "installCommands",
+          message: "Install session commands for Claude Code? (/start, /stop, /restart, /next)",
+          default: true
+        }
+      ]);
+      if (installCommands) {
+        console.log(chalk.gray("Installing command pack: core..."));
+        try {
+          execFileSync(
+            process.execPath,
+            [process.argv[1], "setup-commands", "--force"],
+            { stdio: "pipe" }
+          );
+          console.log(
+            chalk.green("  \u2713 Installed /start, /stop, /restart, /next")
+          );
+        } catch {
+          try {
+            if (!existsSync(claudeCommandsDir)) {
+              mkdirSync(claudeCommandsDir, { recursive: true });
+            }
+            const manifest = JSON.parse(
+              (await import("fs")).readFileSync(coreManifest, "utf8")
+            );
+            const allCmds = [
+              ...manifest.commands?.public || [],
+              ...manifest.commands?.internal || []
+            ];
+            let count = 0;
+            for (const cmd of allCmds) {
+              const src = join(packsDir, "core", cmd.file);
+              const dst = join(claudeCommandsDir, `${cmd.name}.md`);
+              if (existsSync(src) && !existsSync(dst)) {
+                execFileSync("ln", ["-s", src, dst]);
+                count++;
+              }
+            }
+            if (count > 0) {
+              console.log(
+                chalk.green(`  \u2713 Installed ${count} command(s)`)
+              );
+            }
+          } catch {
+            console.log(
+              chalk.yellow(
+                "  \u26A0 Could not install commands. Run: stackmemory setup-commands"
+              )
+            );
+          }
+        }
+      }
+    }
+  }
   const binPath = "/usr/local/bin/claude-sm";
   const sourcePath = join(configPath, "bin", "stackmemory");
   try {
@@ -531,12 +592,18 @@ function showNextSteps(config) {
       )
     );
   }
-  console.log("3. Use with Claude:");
+  console.log("3. Install session commands for Claude Code:");
+  console.log(
+    chalk.gray(
+      "   stackmemory setup-commands  # Installs /start, /stop, /restart, /next\n"
+    )
+  );
+  console.log("4. Use with Claude:");
   console.log(chalk.gray("   claude-sm  # Or use stackmemory directly\n"));
-  console.log("4. Use with Codex:");
+  console.log("5. Use with Codex:");
   console.log(chalk.gray("   codex-sm   # Codex + StackMemory integration\n"));
   if (config.enableLinear) {
-    console.log("5. Sync with Linear:");
+    console.log("6. Sync with Linear:");
     console.log(chalk.gray("   stackmemory linear sync\n"));
   }
   console.log("For more help:");

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

@@ -0,0 +1,127 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import { Command } from "commander";
+import { existsSync, writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { OvernightRunner } from "../../features/operator/overnight-runner.js";
+import { OperatorLogger } from "../../features/operator/operator-logger.js";
+const OPERATOR_DIR = join(homedir(), ".stackmemory", "operator");
+const STOP_SIGNAL_FILE = join(OPERATOR_DIR, "stop-signal");
+const LOG_DIR = join(OPERATOR_DIR, "logs");
+function createOperatorCommands() {
+  const operator = new Command("operator").description(
+    "Autonomous Claude Code operator \u2014 drives sessions overnight via tmux"
+  );
+  operator.command("start").description(
+    "Start the operator \u2014 drains task queue using Claude Code in tmux"
+  ).requiredOption("-f, --file <path>", "Path to master-tasks.md").option("--cwd <dir>", "Working directory for Claude", process.cwd()).option("--mode <mode>", "Adapter: tmux | desktop | browser | auto", "auto").option("--poll <ms>", "Poll interval in ms", "2000").option("--stuck-timeout <ms>", "Stuck detection threshold in ms", "300000").option("--session <name>", "tmux session name", "operator").option("--model <model>", "Claude model override (inner agent)").option(
+    "--api-key <key>",
+    "Anthropic API key for LLM outer loop (or ANTHROPIC_API_KEY env)"
+  ).option(
+    "--llm-model <model>",
+    "LLM model for outer loop decisions",
+    "claude-haiku-4-5-20251001"
+  ).option("--no-auto-commit", "Disable auto-commit after each task").option(
+    "--max-restarts <n>",
+    "Max consecutive restarts before stopping",
+    "10"
+  ).option("--log-dir <dir>", "Log directory", LOG_DIR).action(async (opts) => {
+    if (!existsSync(opts.file)) {
+      process.stderr.write(`Error: task file not found: ${opts.file}
+`);
+      process.exit(1);
+    }
+    const apiKey = opts.apiKey ?? process.env.ANTHROPIC_API_KEY;
+    if (opts.mode === "desktop" && !apiKey) {
+      process.stderr.write(
+        "Error: desktop mode requires --api-key or ANTHROPIC_API_KEY for screenshot interpretation\n"
+      );
+      process.exit(1);
+    }
+    const config = {
+      taskFilePath: opts.file,
+      cwd: opts.cwd,
+      adapterMode: opts.mode,
+      pollIntervalMs: parseInt(opts.poll, 10),
+      stuckTimeoutMs: parseInt(opts.stuckTimeout, 10),
+      rateLimitBackoffMs: 6e4,
+      maxRateLimitBackoffMs: 9e5,
+      maxConsecutiveRestarts: parseInt(opts.maxRestarts, 10),
+      sessionName: opts.session,
+      model: opts.model,
+      anthropicApiKey: apiKey,
+      llmModel: opts.llmModel,
+      autoCommit: opts.autoCommit !== false,
+      logDir: opts.logDir
+    };
+    const runner = new OvernightRunner(config);
+    try {
+      await runner.run();
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`Operator error: ${msg}
+`);
+      process.exit(1);
+    }
+  });
+  operator.command("stop").description("Signal the running operator to stop gracefully").option("--session <name>", "tmux session name", "operator").action((_opts) => {
+    mkdirSync(OPERATOR_DIR, { recursive: true });
+    writeFileSync(STOP_SIGNAL_FILE, String(Date.now()), "utf-8");
+    process.stderr.write(
+      "Stop signal sent. Operator will shut down after current tick.\n"
+    );
+  });
+  operator.command("status").description("Show current operator status from checkpoint").option("--json", "Output raw JSON").action((opts) => {
+    const checkpoint = OperatorLogger.readCheckpoint(OPERATOR_DIR);
+    if (!checkpoint) {
+      process.stderr.write(
+        "No operator checkpoint found. Is the operator running?\n"
+      );
+      process.exit(1);
+    }
+    if (opts.json) {
+      process.stdout.write(JSON.stringify(checkpoint, null, 2) + "\n");
+      return;
+    }
+    const runtime = Date.now() - checkpoint.startedAt;
+    const hrs = Math.floor(runtime / 36e5);
+    const mins = Math.floor(runtime % 36e5 / 6e4);
+    const lines = [
+      `State:       ${checkpoint.currentState}`,
+      `Active task: ${checkpoint.currentTaskId ?? "none"}`,
+      `Completed:   ${checkpoint.tasksCompleted.length}`,
+      `Blocked:     ${checkpoint.tasksBlocked.length}`,
+      `Runtime:     ${hrs}h ${mins}m`,
+      `Restarts:    ${checkpoint.totalRestarts}`,
+      `Approvals:   ${checkpoint.totalPermissionApprovals}`,
+      `Rate limits: ${checkpoint.totalRateLimitHits}`
+    ];
+    process.stdout.write(lines.join("\n") + "\n");
+  });
+  operator.command("attach").description(
+    "Attach to the operator tmux session for live observation (Ctrl-B d to detach)"
+  ).option("--session <name>", "tmux session name", "operator").action((opts) => {
+    try {
+      const {
+        SessionManager
+      } = require("../../features/operator/session-manager.js");
+      const mgr = new SessionManager({
+        sessionName: opts.session,
+        cwd: process.cwd()
+      });
+      mgr.attach();
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`Attach error: ${msg}
+`);
+      process.exit(1);
+    }
+  });
+  return operator;
+}
+export {
+  createOperatorCommands
+};

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

@@ -0,0 +1,117 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import { Command } from "commander";
+import Database from "better-sqlite3";
+import { existsSync } from "fs";
+import { join } from "path";
+import chalk from "chalk";
+import { TraceStore } from "../../core/trace/trace-store.js";
+import { TraceOptimizer } from "../../core/optimization/trace-optimizer.js";
+function createOptimizeCommand() {
+  const optimize = new Command("optimize").description(
+    "Offline optimizers for harnesses, traces, and prompts"
+  );
+  optimize.command("traces").description(
+    "Analyze stored traces and generate HALO-like offline optimizer recommendations"
+  ).option("-d, --days <n>", "Only analyze traces from the last N days", "30").option(
+    "-m, --min-occurrences <n>",
+    "Minimum repeated occurrences before surfacing a pattern",
+    "2"
+  ).option("--json", "Print machine-readable JSON").option(
+    "--no-write",
+    "Do not persist report files under .stackmemory/build"
+  ).action(async (options) => {
+    const projectRoot = process.cwd();
+    const dbPath = join(projectRoot, ".stackmemory", "context.db");
+    if (!existsSync(dbPath)) {
+      console.log(
+        chalk.red("StackMemory not initialized in this directory.")
+      );
+      console.log(chalk.gray('Run "stackmemory init" first.'));
+      return;
+    }
+    const db = new Database(dbPath);
+    try {
+      const traceStore = new TraceStore(db);
+      const optimizer = new TraceOptimizer(traceStore);
+      const report = optimizer.analyze({
+        lookbackDays: parseInt(options.days, 10) || 30,
+        minOccurrences: parseInt(options.minOccurrences, 10) || 2
+      });
+      const persisted = options.write ? optimizer.persistReport(projectRoot, report) : null;
+      if (options.json) {
+        console.log(
+          JSON.stringify(
+            {
+              ...report,
+              persisted
+            },
+            null,
+            2
+          )
+        );
+        return;
+      }
+      console.log(chalk.blue("\nTrace Optimizer Report\n"));
+      console.log(`Lookback window: ${report.lookbackDays} day(s)`);
+      console.log(`Traces analyzed: ${report.totalTracesAnalyzed}`);
+      console.log(`Traces with errors: ${report.tracesWithErrors}`);
+      console.log(`Causal traces: ${report.causalTraces}`);
+      console.log(
+        `Average tools/trace: ${report.averageToolsPerTrace.toFixed(2)}`
+      );
+      console.log(
+        `Average trace score: ${report.averageTraceScore.toFixed(2)}`
+      );
+      if (report.recommendations.length === 0) {
+        console.log(
+          chalk.yellow(
+            "\nNo repeated patterns crossed the threshold. Lower --min-occurrences or collect more traces."
+          )
+        );
+      } else {
+        console.log(chalk.blue("\nRecommendations:\n"));
+        for (const recommendation of report.recommendations) {
+          const badge = recommendation.priority === "high" ? chalk.red("[high]") : chalk.yellow("[medium]");
+          console.log(
+            `${badge} ${chalk.white(recommendation.title)} (${recommendation.confidence.toFixed(2)} confidence)`
+          );
+          console.log(`  ${recommendation.summary}`);
+          console.log(`  Targets: ${recommendation.targetAreas.join(", ")}`);
+          console.log(`  Actions: ${recommendation.actions.join(" | ")}`);
+          console.log(
+            `  Validate: ${recommendation.validations.join(" | ")}`
+          );
+          console.log("");
+        }
+      }
+      if (report.clusters.length > 0) {
+        console.log(chalk.blue("Detected clusters:\n"));
+        for (const cluster of report.clusters) {
+          console.log(
+            `- ${cluster.label} (${cluster.occurrences} traces, ${cluster.kind})`
+          );
+          if (cluster.toolPatterns.length > 0) {
+            console.log(`  Tools: ${cluster.toolPatterns.join(", ")}`);
+          }
+          if (cluster.sampleSummaries.length > 0) {
+            console.log(`  Examples: ${cluster.sampleSummaries.join(" | ")}`);
+          }
+        }
+        console.log("");
+      }
+      if (persisted) {
+        console.log(chalk.gray(`Saved JSON: ${persisted.jsonPath}`));
+        console.log(chalk.gray(`Saved Markdown: ${persisted.markdownPath}`));
+      }
+    } finally {
+      db.close();
+    }
+  });
+  return optimize;
+}
+export {
+  createOptimizeCommand
+};