@stackmemoryai/stackmemory 1.10.5 → 1.12.0

package/README.md

@@ -14,7 +14,7 @@ Lossless, project-scoped memory for AI coding tools. **[Website](https://stackme
 StackMemory is a **production-ready memory runtime** for AI coding tools that preserves full project context across sessions:
 
 - **Zero-config setup** — `stackmemory init` just works
-- **56 MCP tools** for Claude Code integration (context, tasks, Linear, traces, discovery, cord, team, planning, providers, and more)
+- **73 MCP tools** for Claude Code integration (context, tasks, Linear, traces, discovery, cord, team, planning, providers, and more)
 - **FTS5 full-text search** with BM25 scoring and hybrid retrieval
 - **Full Linear integration** with bidirectional sync and OAuth/API key support
 - **Context persistence** that survives `/clear` operations
@@ -97,6 +97,16 @@ stackmemory doctor
 
 Restart Claude Code and StackMemory MCP tools will be available.
 
+### Also available as `croissant-ai`
+
+[croissant.ai](https://croissant.ai) wraps StackMemory as a business-facing CLI for executive intelligence. Install via `npx croissant-ai` — all unknown commands forward to StackMemory automatically.
+
+```bash
+npx croissant-ai ask "What's our MRR?"   # croissant.ai query API
+npx croissant-ai memory capture           # → stackmemory capture
+npx croissant-ai init                     # → stackmemory init (fallback)
+```
+
 ### Wrapper Scripts
 
 StackMemory ships wrapper scripts that launch your coding tool with StackMemory context pre-loaded:
@@ -132,6 +142,44 @@ Runs as an MCP server. Editors (e.g., Claude Code) call StackMemory on each inte
 
 ---
 
+## Command Packs
+
+StackMemory ships installable command packs for Claude Code — curated slash commands that integrate session lifecycle management directly into your workflow.
+
+### Core Pack
+
+The **core** pack provides session lifecycle commands that use StackMemory for context persistence:
+
+| Command | Description |
+|---------|-------------|
+| `/start` | Boot a session — load memory, restore handoff, show git state, suggest next work |
+| `/stop` | End a session — summarize, capture handoff, review learnings |
+| `/restart` | Chain `/stop` → `/clear` → `/start` in one command |
+| `/next` | Suggest what to work on based on context |
+
+Internal dependencies (installed automatically): `/summary`, `/capture`, `/learn`, `/restore`
+
+```bash
+# Install core commands
+stackmemory setup-commands
+
+# List available packs
+stackmemory setup-commands --list
+
+# Preview what would be installed
+stackmemory setup-commands --dry-run
+
+# Reinstall (overwrite existing)
+stackmemory setup-commands --force
+
+# Remove installed commands
+stackmemory setup-commands --uninstall
+```
+
+Commands are symlinked to `~/.claude/commands/` and available immediately in Claude Code.
+
+---
+
 ## Skills System
 
 StackMemory ships Claude Code skills that integrate directly into your workflow. Skills are invoked via `/skill-name` in Claude Code or `stackmemory skills <name>` from the CLI.
@@ -272,34 +320,54 @@ claude-sm
 
 ---
 
-## RLM (Recursive Language Model) Orchestration
+## RLM-Aware Harness
+
+StackMemory includes an RLM (Recursive Language Model) system inspired by [predict-rlm](https://github.com/Trampoline-AI/predict-rlm) — three layers that make agents self-harnessing:
+
+### Layer 1: Context-as-REPL
+
+Agents access tenant data programmatically via tool functions instead of prose handoffs:
+
+- `search_knowledge(query, topK)` — vector search over tenant data
+- `read_context(query)` — knowledge graph entity/relationship queries
+- `list_runs(threadId)` — prior run history with status summaries
+- `get_run_events(runId)` — event stream replay for a specific run
+- `query_interrupts(threadId)` — pending approvals and blocks
+- `llm_summarize(prompt)` — sub-LLM (Haiku) for quick synthesis
+
+### Layer 2: Typed Dispatch
+
+Signature-based sub-agent spawning with validated I/O contracts:
+
+| Signature | Persona | Inputs | Outputs |
+|-----------|---------|--------|---------|
+| `ImplementFeature` | eng | spec, context_files | branch, changed_files, test_passed |
+| `FixBug` | eng | description, error_log | branch, changed_files, root_cause |
+| `ReviewPR` | eng | pr_url, focus_areas | verdict, comments, risk_level |
+| `Investigate` | data | question, data_sources | findings, evidence, confidence |
+| `Summarize` | data | content, format | summary, key_points |
+
+Parent runs dispatch typed sub-runs via `dispatchSubRun()` and collect validated results via `collectSubRun()` with timeout handling.
+
+### Layer 3: Critic + Self-Decomposition
 
-StackMemory includes an RLM system that handles complex tasks through recursive decomposition and parallel execution using Claude Code's Task tool.
+LLM quality gate that evaluates run output (ported from predict-rlm's critic pattern):
 
-### Key Features
+- **Score >= 80**: Pass — run ships as-is
+- **Score 50-79**: Revise — creates a new run with critic feedback appended
+- **Score < 50**: Decompose — dispatches typed sub-runs to break down the task
 
-- **Recursive Task Decomposition**: Breaks complex tasks into manageable subtasks
-- **Parallel Subagent Execution**: Run multiple specialized agents concurrently
-- **8 Specialized Agent Types**: Planning, Code, Testing, Linting, Review, Improve, Context, Publish
-- **Multi-Stage Review**: Iterative improvement cycles with quality scoring (0-1 scale)
-- **Automatic Test Generation**: Unit, integration, and E2E test creation
+Loop control: max 3 revisions, max depth 2 for decomposition.
 
-### Usage
+### Legacy RLM Orchestrator
+
+The original RLM system remains available for direct use:
 
 ```bash
-# Basic usage
 stackmemory skills rlm "Your complex task description"
-
-# With options
-stackmemory skills rlm "Refactor authentication system" \
-  --max-parallel 8 \
-  --review-stages 5 \
-  --quality-threshold 0.9 \
-  --test-mode all
+stackmemory skills rlm "Refactor auth" --max-parallel 8 --quality-threshold 0.9
 ```
 
-### Configuration Options
-
 | Option | Description | Default |
 |--------|-------------|---------|
 | `--max-parallel` | Maximum concurrent subagents | 5 |
@@ -307,7 +375,6 @@ stackmemory skills rlm "Refactor authentication system" \
 | `--review-stages` | Number of review iterations | 3 |
 | `--quality-threshold` | Target quality score (0-1) | 0.85 |
 | `--test-mode` | Test generation mode (unit/integration/e2e/all) | all |
-| `--verbose` | Show all recursive operations | false |
 
 **Note**: RLM requires Claude Code Max plan for unlimited subagent execution.
 
@@ -417,18 +484,32 @@ Options: `--until`, `--until-not`, `--until-empty`, `--until-non-empty`, `--unti
 ## Documentation
 
 - [Getting Started](./docs/GETTING_STARTED.md) — Quick start guide (5 minutes)
-- [MCP Tools Reference](https://stackmemoryai.github.io/stackmemory/tools.html) — All 56 MCP tools
+- [MCP Tools Reference](https://stackmemoryai.github.io/stackmemory/tools.html) — All 73 MCP tools
 - [CLI Reference](./docs/cli.md) — Full command reference
 - [Setup Guide](./docs/SETUP.md) — Advanced setup options
 - [Development Guide](./docs/DEVELOPMENT.md) — Contributing and development
 - [Architecture](./docs/architecture.md) — System design
 - [API Reference](./docs/API_REFERENCE.md) — API documentation
-- [Vision](./vision.md) — Product vision and principles
+- [Vision](./docs/vision.md) — Product vision and principles
 - [Status](./docs/status.md) — Current project status
 - [Roadmap](./docs/roadmap.md) — Future plans
 
 ---
 
+## Substrate: The Three-Layer Vision
+
+StackMemory is the foundation of a three-layer architecture for AI-native development:
+
+| Layer | Product | Status | Purpose |
+|-------|---------|--------|---------|
+| **L1** | StackMemory | Shipped (v1.10.6) | Context persistence — lossless memory across sessions |
+| **L2** | Substrate Desktop | Shipping | Agent orchestration — multi-agent coordination with worktree isolation |
+| **L3** | Substrate Cloud | Design | Multiplayer development — shared context across teams and agents |
+
+Grounded in distributed systems theory: FLP impossibility, Byzantine→Crash conversion via test hooks, Chandra-Toueg failure detectors for agent liveness. See [COORDINATION_THEORY.md](./docs/architecture/COORDINATION_THEORY.md).
+
+---
+
 ## License
 
 Licensed under the [Business Source License 1.1](./LICENSE). You can use, modify, and self-host StackMemory freely. The one restriction: you may not offer it as a competing hosted service. The license converts to MIT after 4 years per release.

package/dist/src/cli/claude-sm.js

@@ -9,10 +9,21 @@ import { spawn, execSync, execFileSync } from "child_process";
 import * as fs from "fs";
 import * as path from "path";
 import * as os from "os";
+import { fileURLToPath } from "url";
 import { program } from "commander";
 import { v4 as uuidv4 } from "uuid";
 import chalk from "chalk";
 import { initializeTracing, trace } from "../core/trace/index.js";
+import { resolveRealCliBin } from "./utils/real-cli-bin.js";
+import {
+  startDeterminismWatcher,
+  stopDeterminismWatcher
+} from "./utils/determinism-watcher.js";
+import {
+  canonicalStateStore,
+  projectIdFromIdentifier
+} from "../core/shared-state/canonical-store.js";
+import { loadProjectHandoff } from "../core/session/project-handoff.js";
 import {
   getModelRouter,
   loadModelRouterConfig
@@ -43,6 +54,7 @@ import {
   writeSettingsAtomic,
   getSettingsPath
 } from "../utils/hook-installer.js";
+const runtimeDirname = path.dirname(fileURLToPath(import.meta.url));
 const DEFAULT_SM_CONFIG = {
   defaultWorktree: false,
   defaultSandbox: false,
@@ -81,6 +93,11 @@ class ClaudeSM {
   worktreeScriptPath;
   claudeConfigDir;
   smConfig;
+  sessionId;
+  ownsSession;
+  sessionEnded;
+  determinismWatcher;
+  skippedHandoffReason;
   constructor() {
     this.smConfig = loadSMConfig();
     this.config = {
@@ -100,10 +117,15 @@ class ClaudeSM {
     };
     this.stackmemoryPath = this.findStackMemory();
     this.worktreeScriptPath = path.join(
-      __dirname,
+      runtimeDirname,
       "../../scripts/claude-worktree-manager.sh"
     );
     this.claudeConfigDir = path.join(os.homedir(), ".claude");
+    this.sessionId = process.env["STACKMEMORY_SESSION"] || uuidv4();
+    this.ownsSession = !process.env["STACKMEMORY_SESSION"];
+    this.sessionEnded = false;
+    this.determinismWatcher = null;
+    this.skippedHandoffReason = null;
     if (!fs.existsSync(this.claudeConfigDir)) {
       fs.mkdirSync(this.claudeConfigDir, { recursive: true });
     }
@@ -172,6 +194,20 @@ class ClaudeSM {
       return "main";
     }
   }
+  getProjectId() {
+    const root = this.getRepoRoot() || process.cwd();
+    try {
+      const remote = execSync("git config --get remote.origin.url", {
+        cwd: root,
+        encoding: "utf8"
+      }).trim();
+      if (remote) {
+        return projectIdFromIdentifier(remote);
+      }
+    } catch {
+    }
+    return projectIdFromIdentifier(root);
+  }
   hasUncommittedChanges() {
     try {
       const status = execSync("git status --porcelain", { encoding: "utf8" });
@@ -181,17 +217,16 @@ class ClaudeSM {
     }
   }
   resolveClaudeBin() {
-    if (this.config.claudeBin && this.config.claudeBin.trim()) {
-      return this.config.claudeBin.trim();
-    }
-    const envBin = process.env["CLAUDE_BIN"];
-    if (envBin && envBin.trim()) return envBin.trim();
-    try {
-      execSync("which claude", { stdio: "ignore" });
-      return "claude";
-    } catch {
-    }
-    return null;
+    return resolveRealCliBin({
+      explicitBin: this.config.claudeBin,
+      envBin: process.env["CLAUDE_BIN"],
+      preferredPaths: [
+        path.join(os.homedir(), ".local", "bin", "claude"),
+        "/usr/local/bin/claude",
+        "/opt/homebrew/bin/claude"
+      ],
+      pathCommands: ["claude"]
+    });
   }
   gepaProcesses = [];
   startGEPAWatcher() {
@@ -206,9 +241,9 @@ class ClaudeSM {
     }
     const gepaPaths = [
       // From dist/src/cli -> scripts/gepa (3 levels up)
-      path.join(__dirname, "../../../scripts/gepa/hooks/auto-optimize.js"),
+      path.join(runtimeDirname, "../../../scripts/gepa/hooks/auto-optimize.js"),
       // From src/cli -> scripts/gepa (2 levels up, for dev mode)
-      path.join(__dirname, "../../scripts/gepa/hooks/auto-optimize.js"),
+      path.join(runtimeDirname, "../../scripts/gepa/hooks/auto-optimize.js"),
       // Global install location
       path.join(
         os.homedir(),
@@ -220,7 +255,7 @@ class ClaudeSM {
       ),
       // npm global install
       path.join(
-        __dirname,
+        runtimeDirname,
         "..",
         "..",
         "scripts",
@@ -260,6 +295,24 @@ class ClaudeSM {
     }
     this.gepaProcesses = [];
   }
+  startDeterminismWatcher() {
+    this.determinismWatcher = startDeterminismWatcher({
+      stackmemoryBin: this.stackmemoryPath,
+      cwd: process.cwd(),
+      task: this.config.task,
+      instanceId: this.config.instanceId,
+      sessionId: this.sessionId,
+      tool: "claude"
+    });
+    if (this.determinismWatcher) {
+      const modeLabel = this.determinismWatcher.mode === "targeted" ? "targeted" : "repo-root fallback";
+      console.log(chalk.gray(`   Determinism: ${modeLabel}`));
+    }
+  }
+  stopDeterminismWatcher() {
+    stopDeterminismWatcher(this.determinismWatcher);
+    this.determinismWatcher = null;
+  }
   setupWorktree() {
     if (!this.config.useWorktree || !this.isGitRepo()) {
       return null;
@@ -347,16 +400,22 @@ class ClaudeSM {
   getHandoffContent() {
     if (!this.config.contextEnabled) return null;
     try {
-      const handoffPath = path.join(
+      const handoff = loadProjectHandoff(
         process.cwd(),
-        ".stackmemory",
-        "last-handoff.md"
+        this.isGitRepo() ? this.getCurrentBranch() : void 0
       );
-      if (fs.existsSync(handoffPath)) {
-        const content = fs.readFileSync(handoffPath, "utf8").trim();
-        if (content.length > 0) {
-          return content.length > 8e3 ? content.substring(0, 8e3) + "\n\n[...truncated]" : content;
-        }
+      if (!handoff) {
+        this.skippedHandoffReason = null;
+        return null;
+      }
+      if (!handoff.compatible) {
+        this.skippedHandoffReason = handoff.mismatchReason || "stale handoff";
+        return null;
+      }
+      this.skippedHandoffReason = null;
+      const content = handoff.content.trim();
+      if (content.length > 0) {
+        return content.length > 8e3 ? content.substring(0, 8e3) + "\n\n[...truncated]" : content;
       }
     } catch {
     }
@@ -373,10 +432,10 @@ class ClaudeSM {
         fs.mkdirSync(hooksDir, { recursive: true });
       }
       const candidateDirs = [
-        path.join(__dirname, "../../templates/claude-hooks"),
-        path.join(__dirname, "../../../templates/claude-hooks"),
+        path.join(runtimeDirname, "../../templates/claude-hooks"),
+        path.join(runtimeDirname, "../../../templates/claude-hooks"),
         path.join(
-          __dirname,
+          runtimeDirname,
           "..",
           "..",
           "..",
@@ -468,6 +527,149 @@ class ClaudeSM {
     console.log(chalk.gray(`
 Session ended (exit ${exitCode ?? 0})`));
   }
+  async publishSessionStart() {
+    const projectPath = process.cwd();
+    const projectId = this.getProjectId();
+    const branch = this.isGitRepo() ? this.getCurrentBranch() : void 0;
+    await canonicalStateStore.upsertSession({
+      sessionId: this.sessionId,
+      tool: "claude",
+      projectId,
+      projectPath,
+      branch,
+      instanceId: this.config.instanceId,
+      metadata: {
+        task: this.config.task,
+        sandbox: this.config.useSandbox,
+        chrome: this.config.useChrome
+      }
+    });
+    await canonicalStateStore.upsertInstance({
+      instanceId: this.config.instanceId,
+      tool: "claude",
+      sessionId: this.sessionId,
+      projectId,
+      projectPath,
+      branch,
+      worktreePath: this.config.worktreePath,
+      pid: process.pid,
+      status: "active",
+      metadata: {
+        task: this.config.task,
+        sandbox: this.config.useSandbox,
+        chrome: this.config.useChrome
+      }
+    });
+    await canonicalStateStore.appendEvent({
+      type: "session_start",
+      tool: "claude",
+      sessionId: this.sessionId,
+      instanceId: this.config.instanceId,
+      projectId,
+      projectPath,
+      branch,
+      payload: {
+        task: this.config.task,
+        worktreePath: this.config.worktreePath,
+        sandbox: this.config.useSandbox,
+        chrome: this.config.useChrome
+      }
+    });
+    const claimResult = await canonicalStateStore.claimPaths({
+      tool: "claude",
+      sessionId: this.sessionId,
+      instanceId: this.config.instanceId,
+      projectId,
+      projectPath,
+      branch,
+      paths: [],
+      metadata: {
+        task: this.config.task,
+        scope: "branch"
+      }
+    });
+    if (claimResult.conflicts.length > 0) {
+      console.log(chalk.yellow("\u26A0\uFE0F  Shared state conflict detected"));
+      for (const conflict of claimResult.conflicts.slice(0, 3)) {
+        console.log(
+          chalk.gray(
+            `   Claim ${conflict.claimId.slice(0, 8)} already owns ${conflict.branch || "overlapping work"}`
+          )
+        );
+      }
+    }
+  }
+  async publishSessionEnd(eventType, payload = {}) {
+    if (this.sessionEnded) {
+      return;
+    }
+    this.sessionEnded = true;
+    const projectPath = process.cwd();
+    const projectId = this.getProjectId();
+    const branch = this.isGitRepo() ? this.getCurrentBranch() : void 0;
+    await canonicalStateStore.appendEvent({
+      type: eventType,
+      tool: "claude",
+      sessionId: this.sessionId,
+      instanceId: this.config.instanceId,
+      projectId,
+      projectPath,
+      branch,
+      payload
+    });
+    await canonicalStateStore.releaseClaims({
+      instanceId: this.config.instanceId,
+      reason: eventType
+    });
+    await canonicalStateStore.endInstance(this.config.instanceId);
+    if (this.ownsSession) {
+      await canonicalStateStore.endSession(this.sessionId);
+    }
+  }
+  async finalizeSession(eventType, exitCode, payload = {}) {
+    this.stopGEPAWatcher();
+    this.stopDeterminismWatcher();
+    this.saveContext(
+      eventType === "session_end" ? "Claude session ended" : eventType === "session_interrupt" ? "Claude session interrupted" : "Claude session terminated",
+      {
+        action: eventType,
+        exitCode,
+        ...payload
+      }
+    );
+    await this.publishSessionEnd(eventType, {
+      exitCode,
+      ...payload
+    });
+    if (eventType === "session_end" && process.env["LINEAR_API_KEY"]) {
+      try {
+        execSync("stackmemory linear sync", {
+          stdio: "ignore",
+          timeout: 1e4
+        });
+      } catch {
+      }
+    }
+    if (this.config.tracingEnabled) {
+      const summary = trace.getExecutionSummary();
+      console.log();
+      console.log(chalk.gray("\u2500".repeat(42)));
+      console.log(chalk.blue("Debug Trace Summary:"));
+      console.log(chalk.gray(summary));
+    }
+    if (eventType === "session_end" && this.config.notifyOnDone) {
+      this.notifyDone(exitCode);
+    }
+    if (this.config.worktreePath) {
+      console.log();
+      console.log(chalk.gray("\u2500".repeat(42)));
+      console.log(chalk.blue("Session ended in worktree:"));
+      console.log(chalk.gray(`  ${this.config.worktreePath}`));
+      console.log();
+      console.log(chalk.gray("To remove worktree: gd_claude"));
+      console.log(chalk.gray("To merge to main: cwm"));
+    }
+  }
   async run(args) {
     const claudeArgs = [];
     let i = 0;
@@ -642,10 +844,25 @@ Session ended (exit ${exitCode ?? 0})`));
     this.loadContext();
     this.ensureHooks();
     process.env["CLAUDE_INSTANCE_ID"] = this.config.instanceId;
+    process.env["STACKMEMORY_SESSION"] = this.sessionId;
     if (this.config.worktreePath) {
       process.env["CLAUDE_WORKTREE_PATH"] = this.config.worktreePath;
     }
+    const claudeBin = this.resolveClaudeBin();
+    if (!claudeBin) {
+      console.error(chalk.red("\u274C Claude CLI not found."));
+      console.log(
+        chalk.gray(
+          "   Install Claude CLI or set an override:\n     export CLAUDE_BIN=/path/to/claude\n     claude-sm --help\n\n   Ensure PATH includes npm global bin (npm bin -g)."
+        )
+      );
+      process.exit(1);
+      return;
+    }
+    await this.publishSessionStart();
+    this.startDeterminismWatcher();
     console.log(chalk.gray(`\u{1F916} Instance ID: ${this.config.instanceId}`));
+    console.log(chalk.gray(`\u{1F9E0} Session ID: ${this.sessionId.slice(0, 8)}`));
     console.log(chalk.gray(`\u{1F4C1} Working in: ${process.cwd()}`));
     if (this.config.useSandbox) {
       console.log(chalk.yellow("\u{1F512} Sandbox mode enabled"));
@@ -712,6 +929,10 @@ Session ended (exit ${exitCode ?? 0})`));
       if (handoffContent) {
         initialInput = handoffContent;
         console.log(chalk.gray("   Handoff context ready"));
+      } else if (this.skippedHandoffReason) {
+        console.log(
+          chalk.gray(`   Handoff skipped: ${this.skippedHandoffReason}`)
+        );
       }
       const theoryContent = this.getTheoryContent();
       if (theoryContent) {
@@ -723,21 +944,25 @@ ${theoryContent}`;
     }
     console.log();
     if (this.config.useSweep) {
-      const claudeBin2 = this.resolveClaudeBin();
-      if (!claudeBin2) {
-        console.error(chalk.red("Claude CLI not found."));
-        process.exit(1);
-        return;
-      }
       console.log(
         chalk.cyan("[Sweep] Launching Claude with prediction bar...")
       );
       console.log(chalk.gray("\u2500".repeat(42)));
       try {
         await launchWrapper({
-          claudeBin: claudeBin2,
+          claudeBin,
           claudeArgs,
-          initialInput: initialInput || void 0
+          initialInput: initialInput || void 0,
+          onExit: async (exitCode) => {
+            await this.finalizeSession("session_end", exitCode);
+          },
+          onSignal: async (signal) => {
+            await this.finalizeSession(
+              signal === "SIGINT" ? "session_interrupt" : "session_terminate",
+              null,
+              { signal }
+            );
+          }
         });
         return;
       } catch (error) {
@@ -756,17 +981,6 @@ ${theoryContent}`;
     }
     console.log(chalk.gray("Starting Claude..."));
     console.log(chalk.gray("\u2500".repeat(42)));
-    const claudeBin = this.resolveClaudeBin();
-    if (!claudeBin) {
-      console.error(chalk.red("\u274C Claude CLI not found."));
-      console.log(
-        chalk.gray(
-          "   Install Claude CLI or set an override:\n     export CLAUDE_BIN=/path/to/claude\n     claude-sm --help\n\n   Ensure PATH includes npm global bin (npm bin -g)."
-        )
-      );
-      process.exit(1);
-      return;
-    }
     const fallbackMonitor = new FallbackMonitor({
       enabled: true,
       maxRestarts: 2,
@@ -807,7 +1021,6 @@ ${theoryContent}`;
       process.exit(1);
     });
     claude.on("exit", async (code) => {
-      this.stopGEPAWatcher();
       const status = fallbackMonitor.getStatus();
       if (status.inFallback) {
         console.log(
@@ -817,49 +1030,18 @@ Session completed on fallback provider: ${status.currentProvider}`
           )
         );
       }
-      this.saveContext("Claude session ended", {
-        action: "session_end",
-        exitCode: code
-      });
-      if (process.env["LINEAR_API_KEY"]) {
-        try {
-          execSync("stackmemory linear sync", {
-            stdio: "ignore",
-            timeout: 1e4
-          });
-        } catch {
-        }
-      }
-      if (this.config.tracingEnabled) {
-        const summary = trace.getExecutionSummary();
-        console.log();
-        console.log(chalk.gray("\u2500".repeat(42)));
-        console.log(chalk.blue("Debug Trace Summary:"));
-        console.log(chalk.gray(summary));
-      }
-      if (this.config.notifyOnDone) {
-        this.notifyDone(code);
-      }
-      if (this.config.worktreePath) {
-        console.log();
-        console.log(chalk.gray("\u2500".repeat(42)));
-        console.log(chalk.blue("Session ended in worktree:"));
-        console.log(chalk.gray(`  ${this.config.worktreePath}`));
-        console.log();
-        console.log(chalk.gray("To remove worktree: gd_claude"));
-        console.log(chalk.gray("To merge to main: cwm"));
-      }
+      await this.finalizeSession("session_end", code);
       process.exit(code || 0);
     });
-    process.on("SIGINT", () => {
-      this.saveContext("Claude session interrupted", {
-        action: "session_interrupt"
+    process.on("SIGINT", async () => {
+      await this.finalizeSession("session_interrupt", null, {
+        signal: "SIGINT"
       });
       claude.kill("SIGINT");
     });
-    process.on("SIGTERM", () => {
-      this.saveContext("Claude session terminated", {
-        action: "session_terminate"
+    process.on("SIGTERM", async () => {
+      await this.finalizeSession("session_terminate", null, {
+        signal: "SIGTERM"
       });
       claude.kill("SIGTERM");
     });