chore: handoff checkpoint on main

Author: StackMemory Bot (CLI)

README.md

@@ -103,7 +103,7 @@ Use these JSON snippets with Claude Code’s MCP “tools/call”. Responses are
 
 - Plan only (no code):
   ```json
-  {"method":"tools/call","params":{"name":"plan_only","arguments":{"task":"Refactor config loader","plannerModel":"claude-3-5-sonnet-latest"}}}
+  {"method":"tools/call","params":{"name":"plan_only","arguments":{"task":"Refactor config loader","plannerModel":"claude-sonnet-4-20250514"}}}
   ```
 
 - Approval‑gated plan (phase 1):
@@ -124,7 +124,7 @@ Use these JSON snippets with Claude Code’s MCP “tools/call”. Responses are
   ```
 
 Env defaults (optional):
-- `STACKMEMORY_MM_PLANNER_MODEL` (e.g., `claude-3-5-sonnet-latest` or `claude-3-opus-latest`)
+- `STACKMEMORY_MM_PLANNER_MODEL` (e.g., `claude-sonnet-4-20250514`)
 - `STACKMEMORY_MM_REVIEWER_MODEL` (defaults to planner if unset)
 - `STACKMEMORY_MM_IMPLEMENTER` (`codex` or `claude`)
 - `STACKMEMORY_MM_MAX_ITERS` (e.g., `2`)
@@ -414,7 +414,7 @@ See https://github.com/stackmemoryai/stackmemory/blob/main/docs/roadmap.md for o
 - [Agent Instructions](./AGENTS.md) - Specific guidance for AI agents working with ML systems
 
 ### Documentation
-
+- [Vision](./vision.md) - Product vision, principles, roadmap, metrics
 - [Product Requirements](./PRD.md) - Detailed product specifications
 - [Technical Architecture](./TECHNICAL_ARCHITECTURE.md) - System design and database schemas
 - [Beads Integration](./BEADS_INTEGRATION.md) - Git-native memory patterns from Beads ecosystem

docs/AGENTIC_PATTERNS_IMPLEMENTATION.md

@@ -32,7 +32,7 @@ oracle: {
 }
 
 workers: [{
-  model: 'claude-3-haiku-20240307', 
+  model: 'claude-3-5-haiku-20241022', 
   costPerToken: 0.00025, // $0.25/1M tokens
   capabilities: ['code_implementation', 'testing']
 }]
@@ -244,4 +244,4 @@ npx stackmemory ralph oracle-worker "Build REST API for user management" \
 
 These agentic patterns transform StackMemory from a traditional development tool into a self-improving, cost-effective, and highly capable software development platform. The combination of cost optimization, systematic learning, and extended capabilities enables production-ready AI-assisted development at scale.
 
-The patterns are production-proven concepts adapted for StackMemory's unique architecture, providing immediate benefits while establishing a foundation for future AI-assisted development workflows.
+The patterns are production-proven concepts adapted for StackMemory's unique architecture, providing immediate benefits while establishing a foundation for future AI-assisted development workflows.

docs/mcp.md

@@ -20,7 +20,7 @@ The `plan_and_code` MCP tool lets Claude Code trigger StackMemory’s multi‑ag
 
 ## Environment defaults
 If not specified in arguments, the MCP handler reads these env vars:
-- `STACKMEMORY_MM_PLANNER_MODEL` (e.g., `claude-3-5-sonnet-latest`)
+- `STACKMEMORY_MM_PLANNER_MODEL` (e.g., `claude-sonnet-4-20250514`)
 - `STACKMEMORY_MM_REVIEWER_MODEL` (defaults to planner model if unset)
 - `STACKMEMORY_MM_IMPLEMENTER` (`codex` or `claude`)
 - `STACKMEMORY_MM_MAX_ITERS` (e.g., `3`)
@@ -98,7 +98,7 @@ Request (tools/call):
     "name": "plan_gate",
     "arguments": {
       "task": "Refactor config loader into provider pattern",
-      "plannerModel": "claude-3-5-sonnet-latest"
+      "plannerModel": "claude-sonnet-4-20250514"
     }
   }
 }

docs/status.md

@@ -7,3 +7,17 @@
 - Two-tier storage: Complete
 - Test Suite: 480 tests passing
 
+## Test Mode
+
+To run tests in constrained environments or avoid native module initialization during CLI/harness execution, enable test mode. When enabled, the CLI skips opening the local SQLite DB and avoids writing frames/anchors in helper commands.
+
+- Env flags:
+  - `VITEST=true`: Detected automatically by the CLI; disables DB work in commands like `init`, `status`, and `context:test`.
+  - `NODE_ENV=test`: Also triggers DB‑skip behavior.
+  - `STACKMEMORY_TEST_SKIP_DB=1`: Explicit override to skip DB, independent of test runner.
+
+- Typical usage:
+  - `VITEST=true npm run test:run`
+  - `STACKMEMORY_TEST_SKIP_DB=1 npm run test:run`
+
+This keeps unit tests fast and stable across sandboxes. Regular usage (without these flags) fully initializes and uses the local `.stackmemory/context.db`.

package-lock.json

@@ -118,6 +118,7 @@
     "inquirer": "^9.3.8",
     "msgpackr": "^1.10.1",
     "ngrok": "^5.0.0-beta.2",
+    "node-pty": "^1.1.0",
     "open": "^11.0.0",
     "ora": "^9.0.0",
     "pg": "^8.17.1",

package.json

@@ -99,7 +99,7 @@ MAX_FILE_SIZE=100000            # Max size per file (100KB)
 MAX_TOTAL_SIZE=500000           # Max total size (500KB)
 
 # Claude CLI settings
-CLAUDE_MODEL=claude-3-opus      # Model to use
+CLAUDE_MODEL=claude-sonnet-4-20250514      # Model to use
 CLAUDE_MAX_TOKENS=4000          # Max tokens per request
 
 # File patterns to check (regex)
@@ -130,4 +130,4 @@ echo ""
 echo "Environment variables you can set:"
 echo "  CLAUDE_AUTO_FIX=true         # Auto-apply suggested fixes"
 echo "  CLAUDE_REVIEW_ENABLED=false  # Skip code review"
-echo "  CLAUDE_TEST_ENABLED=false    # Skip test generation"
+echo "  CLAUDE_TEST_ENABLED=false    # Skip test generation"

scripts/install-claude-hooks.sh

@@ -8,11 +8,71 @@ import { execSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
+import Database from 'better-sqlite3';
 
 // Use the built CLI
 const projectRoot = path.join(__dirname, '..', '..', '..');
 const cliPath = path.join(projectRoot, 'dist', 'src', 'cli', 'index.js');
 
+// Helper to create test database (since init skips DB in test mode)
+function createTestDb(testDir: string): void {
+  const dbDir = path.join(testDir, '.stackmemory');
+  if (!fs.existsSync(dbDir)) {
+    fs.mkdirSync(dbDir, { recursive: true });
+  }
+  const db = new Database(path.join(dbDir, 'context.db'));
+  // Create full schema matching FrameDatabase
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS frames (
+      frame_id TEXT PRIMARY KEY,
+      run_id TEXT NOT NULL DEFAULT 'test-run',
+      project_id TEXT NOT NULL DEFAULT 'test-project',
+      parent_frame_id TEXT,
+      depth INTEGER NOT NULL DEFAULT 0,
+      type TEXT NOT NULL DEFAULT 'task',
+      name TEXT NOT NULL DEFAULT 'test',
+      state TEXT NOT NULL DEFAULT 'active',
+      inputs TEXT DEFAULT '{}',
+      outputs TEXT DEFAULT '{}',
+      digest_text TEXT,
+      digest_json TEXT DEFAULT '{}',
+      created_at INTEGER NOT NULL DEFAULT (unixepoch()),
+      closed_at INTEGER,
+      FOREIGN KEY (parent_frame_id) REFERENCES frames(frame_id)
+    );
+    CREATE TABLE IF NOT EXISTS events (
+      event_id TEXT PRIMARY KEY,
+      frame_id TEXT NOT NULL,
+      run_id TEXT NOT NULL DEFAULT 'test-run',
+      seq INTEGER NOT NULL DEFAULT 0,
+      event_type TEXT NOT NULL DEFAULT 'test',
+      payload TEXT NOT NULL DEFAULT '{}',
+      ts INTEGER NOT NULL DEFAULT (unixepoch() * 1000),
+      FOREIGN KEY (frame_id) REFERENCES frames(frame_id) ON DELETE CASCADE
+    );
+    CREATE TABLE IF NOT EXISTS anchors (
+      anchor_id TEXT PRIMARY KEY,
+      frame_id TEXT NOT NULL,
+      type TEXT NOT NULL DEFAULT 'FACT',
+      text TEXT NOT NULL DEFAULT '',
+      priority INTEGER NOT NULL DEFAULT 5,
+      metadata TEXT DEFAULT '{}',
+      created_at INTEGER NOT NULL DEFAULT (unixepoch()),
+      FOREIGN KEY (frame_id) REFERENCES frames(frame_id) ON DELETE CASCADE
+    );
+    CREATE TABLE IF NOT EXISTS sessions (
+      id TEXT PRIMARY KEY,
+      project_id TEXT,
+      created_at INTEGER DEFAULT (unixepoch())
+    );
+    CREATE INDEX IF NOT EXISTS idx_frames_project_state ON frames(project_id, state);
+    CREATE INDEX IF NOT EXISTS idx_frames_parent ON frames(parent_frame_id);
+    CREATE INDEX IF NOT EXISTS idx_events_frame_seq ON events(frame_id, seq);
+    CREATE INDEX IF NOT EXISTS idx_anchors_frame_priority ON anchors(frame_id, priority DESC);
+  `);
+  db.close();
+}
+
 describe('CLI Integration', () => {
   let testDir: string;
 
@@ -78,6 +138,8 @@ describe('CLI Integration', () => {
     it('should show clear status', { timeout: 15000 }, () => {
       // Initialize first
       execSync(`node ${cliPath} init`, { cwd: testDir });
+      // Create DB since init skips it in test mode
+      createTestDb(testDir);
 
       const result = execSync(`node ${cliPath} clear --status`, {
         cwd: testDir,

src/__tests__/integration/cli-integration.test.ts

@@ -344,6 +344,21 @@ describe('CLI Commands', () => {
     });
   });
 
+  describe('ping command', () => {
+    it('should respond with pong and timestamp', async () => {
+      const { program } = await import('../index.js');
+
+      process.argv = ['node', 'stackmemory', 'ping'];
+      await program.parseAsync(process.argv);
+
+      expect(consoleSpy.log).toHaveBeenCalledWith(
+        expect.stringMatching(
+          /^pong \d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/
+        )
+      );
+    });
+  });
+
   describe('mcp-server command', () => {
     it('should start MCP server with default options', async () => {
       const { program } = await import('../index.js');

src/cli/__tests__/index.test.ts

@@ -1056,10 +1056,17 @@ class ClaudeSM {
           claudeArgs,
         });
       } catch (error) {
-        console.error(chalk.red((error as Error).message));
-        process.exit(1);
+        // If PTY wrapper fails (e.g., node-pty missing), fall back to direct launch
+        const msg = (error as Error).message || 'Unknown PTY error';
+        console.error(chalk.yellow(`[Sweep disabled] ${msg}`));
+        console.log(
+          chalk.gray(
+            'Falling back to direct Claude launch (no prediction bar)...'
+          )
+        );
+        // Disable Sweep for this session and continue below
+        this.config.useSweep = false;
       }
-      return;
     }
 
     console.log(chalk.gray('Starting Claude...'));