session-collab-mcp 0.4.4 → 0.4.7

package/migrations/0003_config.sql

@@ -0,0 +1,2 @@
+-- Add config column to sessions table
+ALTER TABLE sessions ADD COLUMN config TEXT;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "session-collab-mcp",
-  "version": "0.4.4",
+  "version": "0.4.7",
   "description": "MCP server for Claude Code session collaboration - prevents conflicts between parallel sessions",
   "type": "module",
   "bin": {

package/src/auth/handlers.ts

@@ -1,6 +1,6 @@
 // Authentication API handlers
 
-import type { D1Database } from '../db/sqlite-adapter.js';
+import type { DatabaseAdapter } from '../db/sqlite-adapter.js';
 import { hashPassword, verifyPassword, validatePasswordStrength } from './password';
 import { createAccessToken, createRefreshToken, verifyJwt, getTokenExpiry } from './jwt';
 import {
@@ -29,7 +29,7 @@ import {
 } from './types';
 
 interface HandlerContext {
-  db: D1Database;
+  db: DatabaseAdapter;
   jwtSecret: string;
   request: Request;
 }

package/src/auth/middleware.ts

@@ -1,13 +1,13 @@
 // Authentication middleware
 
-import type { D1Database } from '../db/sqlite-adapter.js';
+import type { DatabaseAdapter } from '../db/sqlite-adapter.js';
 import { verifyJwt } from './jwt';
 import { getApiTokenByHash, updateApiTokenLastUsed } from '../db/auth-queries';
 import { sha256, timingSafeEqual } from '../utils/crypto';
 import type { AuthContext } from './types';
 
 export interface Env {
-  DB: D1Database;
+  DB: DatabaseAdapter;
   JWT_SECRET?: string;
   API_TOKEN?: string; // Legacy single token support
 }
@@ -52,7 +52,7 @@ export async function validateAuth(request: Request, env: Env): Promise<AuthCont
 /**
  * Validate API Token
  */
-async function validateApiToken(token: string, db: D1Database): Promise<AuthContext | null> {
+async function validateApiToken(token: string, db: DatabaseAdapter): Promise<AuthContext | null> {
   const tokenHash = await sha256(token);
   const apiToken = await getApiTokenByHash(db, tokenHash);
 

package/src/cli.ts

@@ -5,6 +5,7 @@
 import { createInterface } from 'readline';
 import { createLocalDatabase, getDefaultDbPath } from './db/sqlite-adapter.js';
 import { handleMcpRequest, getMcpTools } from './mcp/server.js';
+import { VERSION, SERVER_NAME, SERVER_INSTRUCTIONS } from './constants.js';
 import { readFileSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
@@ -17,6 +18,7 @@ function loadMigrations(): string[] {
   return [
     readFileSync(join(migrationsDir, '0001_init.sql'), 'utf-8'),
     readFileSync(join(migrationsDir, '0002_auth.sql'), 'utf-8'),
+    readFileSync(join(migrationsDir, '0003_config.sql'), 'utf-8'),
   ];
 }
 
@@ -40,39 +42,6 @@ function jsonRpcResponse(id: number | string | null, result: unknown): string {
   return JSON.stringify({ jsonrpc: '2.0', id, result });
 }
 
-// Server instructions for Claude
-const SERVER_INSTRUCTIONS = `
-# Session Collaboration
-
-This MCP server coordinates multiple Claude Code sessions working on the same codebase.
-
-## Required Behaviors
-
-1. **On conversation start**: Immediately call \`collab_session_start\` with:
-   - project_root: Current working directory
-   - name: Descriptive session name (e.g., "feature-auth", "bugfix-api")
-
-2. **Before editing any file**: Call \`collab_check\` with the file path to verify no conflicts
-
-3. **If conflicts detected**:
-   - Show warning to user
-   - Ask if they want to proceed or coordinate
-   - Consider using \`collab_message_send\` to notify other session
-
-4. **For significant changes**: Call \`collab_claim\` before starting work on files
-
-5. **When done with files**: Call \`collab_release\` to free them for others
-
-6. **On conversation end**: Call \`collab_session_end\` to clean up
-
-## Best Practices
-
-- Claim files early, release when done
-- Use descriptive intents when claiming (e.g., "Refactoring auth module")
-- Check for messages periodically with \`collab_message_list\`
-- Record architectural decisions with \`collab_decision_add\`
-`.trim();
-
 function jsonRpcError(id: number | string | null, code: number, message: string): string {
   return JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } });
 }
@@ -118,8 +87,8 @@ async function main(): Promise<void> {
               tools: {},
             },
             serverInfo: {
-              name: 'session-collab-mcp',
-              version: '0.4.4',
+              name: SERVER_NAME,
+              version: VERSION,
             },
             instructions: SERVER_INSTRUCTIONS,
           });

package/src/constants.ts

@@ -0,0 +1,75 @@
+// Shared constants for Session Collaboration MCP
+
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+// Read version from package.json
+function getVersion(): string {
+  try {
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
+    return pkg.version;
+  } catch {
+    return '0.0.0';
+  }
+}
+
+export const VERSION = getVersion();
+
+export const SERVER_NAME = 'session-collab-mcp';
+
+export const SERVER_INSTRUCTIONS = `
+# Session Collaboration
+
+This MCP server coordinates multiple Claude Code sessions working on the same codebase.
+
+## Required Behaviors
+
+1. **On conversation start**: Immediately call \`collab_session_start\` with:
+   - project_root: Current working directory
+   - name: Descriptive session name (e.g., "feature-auth", "bugfix-api")
+
+2. **Before editing any file**: Call \`collab_check\` with the file path to verify no conflicts
+
+3. **If conflicts detected** (DEFAULT: coordinate):
+   - Show warning to user with options:
+     a) **Coordinate** (default): Send message to other session via \`collab_message_send\`, wait for response
+     b) **Bypass**: Proceed anyway (warn about potential conflicts)
+     c) **Request release**: Ask owner to release if claim seems stale
+   - NEVER auto-release another session's claim without explicit user permission
+
+4. **For significant changes**: Call \`collab_claim\` before starting work on files
+
+5. **When done with files**: Call \`collab_release\` with YOUR session_id to free them
+
+6. **On conversation end**: Call \`collab_session_end\` to clean up
+
+## Permission Rules
+
+- You can ONLY release claims that belong to YOUR session
+- To release another session's claim, you must ask the user and they must explicitly confirm
+- Use \`force=true\` in \`collab_release\` only after user explicitly confirms
+- When user chooses "coordinate", send a message first and suggest waiting
+
+## Conflict Handling Modes
+
+Configure your session behavior with \`collab_config\`:
+
+- **"strict"**: Always ask user, never bypass or auto-release
+- **"smart"** (default): Ask user, but suggest auto-release for stale claims (>2hr old)
+- **"bypass"**: Proceed despite conflicts (just warn, don't block)
+
+Config options:
+- \`mode\`: strict | smart | bypass
+- \`allow_release_others\`: Allow releasing other sessions' claims (default: false)
+- \`auto_release_stale\`: Auto-release stale claims (default: false)
+- \`stale_threshold_hours\`: Hours before claim is stale (default: 2)
+
+## Best Practices
+
+- Claim files early, release when done
+- Use descriptive intents when claiming (e.g., "Refactoring auth module")
+- Check for messages periodically with \`collab_message_list\`
+- Record architectural decisions with \`collab_decision_add\`
+`.trim();

package/src/db/auth-queries.ts

@@ -1,13 +1,13 @@
 // Database queries for authentication
 
-import type { D1Database } from './sqlite-adapter.js';
+import type { DatabaseAdapter } from './sqlite-adapter.js';
 import type { User, UserPublic, ApiToken, ApiTokenPublic, RefreshToken } from './types';
 import { generateId, sha256 } from '../utils/crypto';
 
 // ============ User Queries ============
 
 export async function createUser(
-  db: D1Database,
+  db: DatabaseAdapter,
   params: {
     email: string;
     password_hash: string;
@@ -37,29 +37,29 @@ export async function createUser(
   };
 }
 
-export async function getUserByEmail(db: D1Database, email: string): Promise<User | null> {
+export async function getUserByEmail(db: DatabaseAdapter, email: string): Promise<User | null> {
   const result = await db.prepare('SELECT * FROM users WHERE email = ? AND status = ?').bind(email.toLowerCase(), 'active').first<User>();
   return result ?? null;
 }
 
-export async function getUserById(db: D1Database, id: string): Promise<User | null> {
+export async function getUserById(db: DatabaseAdapter, id: string): Promise<User | null> {
   const result = await db.prepare('SELECT * FROM users WHERE id = ? AND status = ?').bind(id, 'active').first<User>();
   return result ?? null;
 }
 
-export async function updateUserLastLogin(db: D1Database, id: string): Promise<void> {
+export async function updateUserLastLogin(db: DatabaseAdapter, id: string): Promise<void> {
   const now = new Date().toISOString();
   await db.prepare('UPDATE users SET last_login_at = ?, updated_at = ? WHERE id = ?').bind(now, now, id).run();
 }
 
-export async function updateUserPassword(db: D1Database, id: string, password_hash: string): Promise<boolean> {
+export async function updateUserPassword(db: DatabaseAdapter, id: string, password_hash: string): Promise<boolean> {
   const now = new Date().toISOString();
   const result = await db.prepare('UPDATE users SET password_hash = ?, updated_at = ? WHERE id = ?').bind(password_hash, now, id).run();
   return result.meta.changes > 0;
 }
 
 export async function updateUserProfile(
-  db: D1Database,
+  db: DatabaseAdapter,
   id: string,
   params: { display_name?: string }
 ): Promise<boolean> {
@@ -80,7 +80,7 @@ export function toUserPublic(user: User): UserPublic {
 // ============ API Token Queries ============
 
 export async function createApiToken(
-  db: D1Database,
+  db: DatabaseAdapter,
   params: {
     user_id: string;
     name: string;
@@ -121,7 +121,7 @@ export async function createApiToken(
   };
 }
 
-export async function getApiTokenByHash(db: D1Database, tokenHash: string): Promise<ApiToken | null> {
+export async function getApiTokenByHash(db: DatabaseAdapter, tokenHash: string): Promise<ApiToken | null> {
   const result = await db
     .prepare('SELECT * FROM api_tokens WHERE token_hash = ? AND revoked_at IS NULL')
     .bind(tokenHash)
@@ -137,7 +137,7 @@ export async function getApiTokenByHash(db: D1Database, tokenHash: string): Prom
   return result;
 }
 
-export async function listApiTokens(db: D1Database, userId: string): Promise<ApiTokenPublic[]> {
+export async function listApiTokens(db: DatabaseAdapter, userId: string): Promise<ApiTokenPublic[]> {
   const result = await db
     .prepare('SELECT * FROM api_tokens WHERE user_id = ? AND revoked_at IS NULL ORDER BY created_at DESC')
     .bind(userId)
@@ -146,13 +146,13 @@ export async function listApiTokens(db: D1Database, userId: string): Promise<Api
   return result.results.map(toApiTokenPublic);
 }
 
-export async function revokeApiToken(db: D1Database, id: string, userId: string): Promise<boolean> {
+export async function revokeApiToken(db: DatabaseAdapter, id: string, userId: string): Promise<boolean> {
   const now = new Date().toISOString();
   const result = await db.prepare('UPDATE api_tokens SET revoked_at = ? WHERE id = ? AND user_id = ?').bind(now, id, userId).run();
   return result.meta.changes > 0;
 }
 
-export async function updateApiTokenLastUsed(db: D1Database, id: string): Promise<void> {
+export async function updateApiTokenLastUsed(db: DatabaseAdapter, id: string): Promise<void> {
   const now = new Date().toISOString();
   await db.prepare('UPDATE api_tokens SET last_used_at = ? WHERE id = ?').bind(now, id).run();
 }
@@ -172,7 +172,7 @@ export function toApiTokenPublic(token: ApiToken): ApiTokenPublic {
 // ============ Refresh Token Queries ============
 
 export async function createRefreshToken(
-  db: D1Database,
+  db: DatabaseAdapter,
   params: {
     user_id: string;
     token_hash: string;
@@ -204,7 +204,7 @@ export async function createRefreshToken(
   };
 }
 
-export async function getRefreshTokenByHash(db: D1Database, tokenHash: string): Promise<RefreshToken | null> {
+export async function getRefreshTokenByHash(db: DatabaseAdapter, tokenHash: string): Promise<RefreshToken | null> {
   const result = await db
     .prepare('SELECT * FROM refresh_tokens WHERE token_hash = ? AND revoked_at IS NULL')
     .bind(tokenHash)
@@ -220,13 +220,13 @@ export async function getRefreshTokenByHash(db: D1Database, tokenHash: string):
   return result;
 }
 
-export async function revokeRefreshToken(db: D1Database, id: string): Promise<boolean> {
+export async function revokeRefreshToken(db: DatabaseAdapter, id: string): Promise<boolean> {
   const now = new Date().toISOString();
   const result = await db.prepare('UPDATE refresh_tokens SET revoked_at = ? WHERE id = ?').bind(now, id).run();
   return result.meta.changes > 0;
 }
 
-export async function revokeAllUserRefreshTokens(db: D1Database, userId: string): Promise<number> {
+export async function revokeAllUserRefreshTokens(db: DatabaseAdapter, userId: string): Promise<number> {
   const now = new Date().toISOString();
   const result = await db.prepare('UPDATE refresh_tokens SET revoked_at = ? WHERE user_id = ? AND revoked_at IS NULL').bind(now, userId).run();
   return result.meta.changes;
@@ -234,7 +234,7 @@ export async function revokeAllUserRefreshTokens(db: D1Database, userId: string)
 
 // ============ Cleanup Queries ============
 
-export async function cleanupExpiredTokens(db: D1Database): Promise<{ apiTokens: number; refreshTokens: number }> {
+export async function cleanupExpiredTokens(db: DatabaseAdapter): Promise<{ apiTokens: number; refreshTokens: number }> {
   const now = new Date().toISOString();
 
   // Mark expired API tokens as revoked

package/src/db/queries.ts

@@ -1,6 +1,6 @@
 // Database queries for Session Collaboration MCP
 
-import type { D1Database } from './sqlite-adapter.js';
+import type { DatabaseAdapter } from './sqlite-adapter.js';
 import type {
   Session,
   Claim,
@@ -13,6 +13,7 @@ import type {
   DecisionCategory,
   TodoItem,
   SessionProgress,
+  SessionConfig,
 } from './types';
 
 // Helper to generate UUID v4
@@ -23,7 +24,7 @@ function generateId(): string {
 // ============ Session Queries ============
 
 export async function createSession(
-  db: D1Database,
+  db: DatabaseAdapter,
   params: {
     name?: string;
     project_root: string;
@@ -54,16 +55,17 @@ export async function createSession(
     current_task: null,
     progress: null,
     todos: null,
+    config: null,
   };
 }
 
-export async function getSession(db: D1Database, id: string): Promise<Session | null> {
+export async function getSession(db: DatabaseAdapter, id: string): Promise<Session | null> {
   const result = await db.prepare('SELECT * FROM sessions WHERE id = ?').bind(id).first<Session>();
   return result ?? null;
 }
 
 export async function listSessions(
-  db: D1Database,
+  db: DatabaseAdapter,
   params: {
     include_inactive?: boolean;
     project_root?: string;
@@ -97,7 +99,7 @@ export async function listSessions(
 }
 
 export async function updateSessionHeartbeat(
-  db: D1Database,
+  db: DatabaseAdapter,
   id: string,
   statusUpdate?: {
     current_task?: string | null;
@@ -150,7 +152,7 @@ export async function updateSessionHeartbeat(
 }
 
 export async function updateSessionStatus(
-  db: D1Database,
+  db: DatabaseAdapter,
   id: string,
   params: {
     current_task?: string | null;
@@ -193,7 +195,7 @@ export async function updateSessionStatus(
 }
 
 export async function endSession(
-  db: D1Database,
+  db: DatabaseAdapter,
   id: string,
   release_claims: 'complete' | 'abandon' = 'abandon'
 ): Promise<boolean> {
@@ -211,7 +213,7 @@ export async function endSession(
   return result.meta.changes > 0;
 }
 
-export async function cleanupStaleSessions(db: D1Database, staleMinutes: number = 30): Promise<{ stale_sessions: number; orphaned_claims: number }> {
+export async function cleanupStaleSessions(db: DatabaseAdapter, staleMinutes: number = 30): Promise<{ stale_sessions: number; orphaned_claims: number }> {
   const cutoff = new Date(Date.now() - staleMinutes * 60 * 1000).toISOString();
   const now = new Date().toISOString();
 
@@ -238,10 +240,23 @@ export async function cleanupStaleSessions(db: D1Database, staleMinutes: number
   };
 }
 
+export async function updateSessionConfig(
+  db: DatabaseAdapter,
+  id: string,
+  config: SessionConfig
+): Promise<boolean> {
+  const result = await db
+    .prepare('UPDATE sessions SET config = ? WHERE id = ?')
+    .bind(JSON.stringify(config), id)
+    .run();
+
+  return result.meta.changes > 0;
+}
+
 // ============ Claim Queries ============
 
 export async function createClaim(
-  db: D1Database,
+  db: DatabaseAdapter,
   params: {
     session_id: string;
     files: string[];
@@ -285,7 +300,7 @@ export async function createClaim(
   };
 }
 
-export async function getClaim(db: D1Database, id: string): Promise<ClaimWithFiles | null> {
+export async function getClaim(db: DatabaseAdapter, id: string): Promise<ClaimWithFiles | null> {
   const claim = await db.prepare('SELECT * FROM claims WHERE id = ?').bind(id).first<Claim>();
 
   if (!claim) return null;
@@ -302,7 +317,7 @@ export async function getClaim(db: D1Database, id: string): Promise<ClaimWithFil
 }
 
 export async function listClaims(
-  db: D1Database,
+  db: DatabaseAdapter,
   params: {
     session_id?: string;
     status?: ClaimStatus | 'all';
@@ -367,7 +382,7 @@ export async function listClaims(
 }
 
 export async function checkConflicts(
-  db: D1Database,
+  db: DatabaseAdapter,
   files: string[],
   excludeSessionId?: string
 ): Promise<ConflictInfo[]> {
@@ -417,7 +432,7 @@ export async function checkConflicts(
 }
 
 export async function releaseClaim(
-  db: D1Database,
+  db: DatabaseAdapter,
   id: string,
   params: {
     status: 'completed' | 'abandoned';
@@ -437,7 +452,7 @@ export async function releaseClaim(
 // ============ Message Queries ============
 
 export async function sendMessage(
-  db: D1Database,
+  db: DatabaseAdapter,
   params: {
     from_session_id: string;
     to_session_id?: string;
@@ -466,7 +481,7 @@ export async function sendMessage(
 }
 
 export async function listMessages(
-  db: D1Database,
+  db: DatabaseAdapter,
   params: {
     session_id: string;
     unread_only?: boolean;
@@ -506,7 +521,7 @@ export async function listMessages(
 // ============ Decision Queries ============
 
 export async function addDecision(
-  db: D1Database,
+  db: DatabaseAdapter,
   params: {
     session_id: string;
     category?: DecisionCategory;
@@ -536,7 +551,7 @@ export async function addDecision(
 }
 
 export async function listDecisions(
-  db: D1Database,
+  db: DatabaseAdapter,
   params: {
     category?: DecisionCategory;
     limit?: number;

package/src/db/sqlite-adapter.ts

@@ -1,5 +1,5 @@
-// SQLite adapter: wraps better-sqlite3 to match D1-like API
-// This allows the same queries.ts to work with both D1 and local SQLite
+// SQLite adapter: wraps better-sqlite3 with a generic database interface
+// This allows the same queries.ts to work with both Cloudflare D1 and local SQLite
 
 import Database from 'better-sqlite3';
 import { randomUUID } from 'crypto';
@@ -14,7 +14,7 @@ if (typeof globalThis.crypto === 'undefined') {
   };
 }
 
-export interface D1Result<T> {
+export interface QueryResult<T> {
   results: T[];
   meta: {
     changes: number;
@@ -22,27 +22,28 @@ export interface D1Result<T> {
   };
 }
 
-export interface D1PreparedStatement {
-  bind(...values: unknown[]): D1PreparedStatement;
+export interface PreparedStatement {
+  bind(...values: unknown[]): PreparedStatement;
   first<T>(): Promise<T | null>;
-  all<T>(): Promise<D1Result<T>>;
+  all<T>(): Promise<QueryResult<T>>;
   run(): Promise<{ meta: { changes: number } }>;
 }
 
-export interface D1Database {
-  prepare(sql: string): D1PreparedStatement;
-  batch(statements: D1PreparedStatement[]): Promise<D1Result<unknown>[]>;
+export interface DatabaseAdapter {
+  prepare(sql: string): PreparedStatement;
+  batch(statements: PreparedStatement[]): Promise<QueryResult<unknown>[]>;
 }
 
-class SqlitePreparedStatement implements D1PreparedStatement {
+class SqlitePreparedStatement implements PreparedStatement {
   private bindings: unknown[] = [];
 
   constructor(
     private db: Database.Database,
-    private sql: string
+    private sql: string,
+    private onWrite?: () => void
   ) {}
 
-  bind(...values: unknown[]): D1PreparedStatement {
+  bind(...values: unknown[]): PreparedStatement {
     this.bindings = values;
     return this;
   }
@@ -53,7 +54,7 @@ class SqlitePreparedStatement implements D1PreparedStatement {
     return result ?? null;
   }
 
-  async all<T>(): Promise<D1Result<T>> {
+  async all<T>(): Promise<QueryResult<T>> {
     const stmt = this.db.prepare(this.sql);
     const results = stmt.all(...this.bindings) as T[];
     return {
@@ -65,6 +66,8 @@ class SqlitePreparedStatement implements D1PreparedStatement {
   async run(): Promise<{ meta: { changes: number } }> {
     const stmt = this.db.prepare(this.sql);
     const result = stmt.run(...this.bindings);
+    // Trigger checkpoint after write
+    this.onWrite?.();
     return {
       meta: { changes: result.changes },
     };
@@ -77,7 +80,7 @@ class SqlitePreparedStatement implements D1PreparedStatement {
   }
 }
 
-class SqliteDatabase implements D1Database {
+class SqliteDatabase implements DatabaseAdapter {
   private db: Database.Database;
 
   constructor(dbPath: string) {
@@ -88,15 +91,28 @@ class SqliteDatabase implements D1Database {
     }
 
     this.db = new Database(dbPath);
+
+    // Multi-process SQLite configuration
     this.db.pragma('journal_mode = WAL');
     this.db.pragma('foreign_keys = ON');
+    this.db.pragma('busy_timeout = 5000');      // Wait up to 5s for locks
+    this.db.pragma('synchronous = NORMAL');     // Ensure durability
+    this.db.pragma('wal_autocheckpoint = 100'); // Checkpoint every 100 pages
+
+    // Checkpoint on open to see latest data from other processes
+    this.db.pragma('wal_checkpoint(PASSIVE)');
+  }
+
+  // Force checkpoint to make changes visible to other processes
+  checkpoint(): void {
+    this.db.pragma('wal_checkpoint(PASSIVE)');
   }
 
-  prepare(sql: string): D1PreparedStatement {
-    return new SqlitePreparedStatement(this.db, sql);
+  prepare(sql: string): PreparedStatement {
+    return new SqlitePreparedStatement(this.db, sql, () => this.checkpoint());
   }
 
-  async batch(statements: D1PreparedStatement[]): Promise<D1Result<unknown>[]> {
+  async batch(statements: PreparedStatement[]): Promise<QueryResult<unknown>[]> {
     const transaction = this.db.transaction(() => {
       return statements.map((stmt) => {
         const sqliteStmt = stmt as SqlitePreparedStatement;
@@ -107,7 +123,10 @@ class SqliteDatabase implements D1Database {
         };
       });
     });
-    return transaction();
+    const results = transaction();
+    // Checkpoint after batch write
+    this.checkpoint();
+    return results;
   }
 
   // Initialize database schema

package/src/db/types.ts

@@ -64,6 +64,23 @@ export interface TodoItem {
   status: 'pending' | 'in_progress' | 'completed';
 }
 
+// Session configuration
+export type ConflictMode = 'strict' | 'smart' | 'bypass';
+
+export interface SessionConfig {
+  mode: ConflictMode;
+  allow_release_others: boolean;
+  auto_release_stale: boolean;
+  stale_threshold_hours: number;
+}
+
+export const DEFAULT_SESSION_CONFIG: SessionConfig = {
+  mode: 'smart',
+  allow_release_others: false,
+  auto_release_stale: false,
+  stale_threshold_hours: 2,
+};
+
 export interface SessionProgress {
   completed: number;
   total: number;
@@ -82,6 +99,7 @@ export interface Session {
   current_task: string | null;
   progress: string | null; // JSON string of SessionProgress
   todos: string | null; // JSON string of TodoItem[]
+  config: string | null; // JSON string of SessionConfig
 }
 
 export interface Claim {

package/src/mcp/server.ts

@@ -1,6 +1,7 @@
 // MCP Server implementation for Session Collaboration
+// Last edited: 2025-12-29 by session-b
 
-import type { D1Database } from '../db/sqlite-adapter.js';
+import type { DatabaseAdapter } from '../db/sqlite-adapter.js';
 import {
   JsonRpcRequestSchema,
   type JsonRpcRequest,
@@ -19,55 +20,24 @@ import { claimTools, handleClaimTool } from './tools/claim';
 import { messageTools, handleMessageTool } from './tools/message';
 import { decisionTools, handleDecisionTool } from './tools/decision';
 import type { AuthContext } from '../auth/types';
+import { VERSION, SERVER_NAME, SERVER_INSTRUCTIONS } from '../constants.js';
 
 const SERVER_INFO: McpServerInfo = {
-  name: 'session-collab-mcp',
-  version: '0.3.0',
+  name: SERVER_NAME,
+  version: VERSION,
 };
 
 const CAPABILITIES: McpCapabilities = {
   tools: {},
 };
 
-const SERVER_INSTRUCTIONS = `
-# Session Collaboration
-
-This MCP server coordinates multiple Claude Code sessions working on the same codebase.
-
-## Required Behaviors
-
-1. **On conversation start**: Immediately call \`collab_session_start\` with:
-   - project_root: Current working directory
-   - name: Descriptive session name (e.g., "feature-auth", "bugfix-api")
-
-2. **Before editing any file**: Call \`collab_check\` with the file path to verify no conflicts
-
-3. **If conflicts detected**:
-   - Show warning to user
-   - Ask if they want to proceed or coordinate
-   - Consider using \`collab_message_send\` to notify other session
-
-4. **For significant changes**: Call \`collab_claim\` before starting work on files
-
-5. **When done with files**: Call \`collab_release\` to free them for others
-
-6. **On conversation end**: Call \`collab_session_end\` to clean up
-
-## Best Practices
-
-- Claim files early, release when done
-- Use descriptive intents when claiming (e.g., "Refactoring auth module")
-- Check for messages periodically with \`collab_message_list\`
-- Record architectural decisions with \`collab_decision_add\`
-`.trim();
-
 // Combine all tools
 const ALL_TOOLS: McpTool[] = [...sessionTools, ...claimTools, ...messageTools, ...decisionTools];
 
 export class McpServer {
   private authContext?: AuthContext;
 
-  constructor(private db: D1Database, authContext?: AuthContext) {
+  constructor(private db: DatabaseAdapter, authContext?: AuthContext) {
     this.authContext = authContext;
   }
 
@@ -127,7 +97,7 @@ export class McpServer {
 
     try {
       // Route to appropriate handler
-      if (name.startsWith('collab_session_') || name === 'collab_status_update') {
+      if (name.startsWith('collab_session_') || name === 'collab_status_update' || name === 'collab_config') {
         result = await handleSessionTool(this.db, name, args, userId);
       } else if (name.startsWith('collab_claim') || name === 'collab_check' || name === 'collab_release') {
         result = await handleClaimTool(this.db, name, args);
@@ -165,12 +135,12 @@ export function getMcpTools(): McpTool[] {
 
 // Handle MCP tool call for CLI
 export async function handleMcpRequest(
-  db: D1Database,
+  db: DatabaseAdapter,
   name: string,
   args: Record<string, unknown>
 ): Promise<McpToolResult> {
   try {
-    if (name.startsWith('collab_session_') || name === 'collab_status_update') {
+    if (name.startsWith('collab_session_') || name === 'collab_status_update' || name === 'collab_config') {
       return await handleSessionTool(db, name, args);
     } else if (name.startsWith('collab_claim') || name === 'collab_check' || name === 'collab_release') {
       return await handleClaimTool(db, name, args);

package/src/mcp/tools/claim.ts

@@ -1,9 +1,10 @@
 // Claim management tools (WIP declarations)
 
-import type { D1Database } from '../../db/sqlite-adapter.js';
+import type { DatabaseAdapter } from '../../db/sqlite-adapter.js';
 import type { McpTool, McpToolResult } from '../protocol';
 import { createToolResult } from '../protocol';
-import type { ClaimScope } from '../../db/types';
+import type { ClaimScope, SessionConfig } from '../../db/types';
+import { DEFAULT_SESSION_CONFIG } from '../../db/types';
 import { createClaim, getClaim, listClaims, checkConflicts, releaseClaim, getSession } from '../../db/queries';
 
 export const claimTools: McpTool[] = [
@@ -58,10 +59,14 @@ export const claimTools: McpTool[] = [
   },
   {
     name: 'collab_release',
-    description: 'Release a claim when done or abandoning work.',
+    description: 'Release a claim when done or abandoning work. By default you can only release your own claims. Use force=true with user confirmation to release stale claims from other sessions.',
     inputSchema: {
       type: 'object',
       properties: {
+        session_id: {
+          type: 'string',
+          description: 'Your session ID (required to verify ownership)',
+        },
         claim_id: {
           type: 'string',
           description: 'Claim ID to release',
@@ -75,8 +80,12 @@ export const claimTools: McpTool[] = [
           type: 'string',
           description: 'Optional summary of what was done (for completed claims)',
         },
+        force: {
+          type: 'boolean',
+          description: 'Force release even if claim belongs to another session (requires user confirmation)',
+        },
       },
-      required: ['claim_id', 'status'],
+      required: ['session_id', 'claim_id', 'status'],
     },
   },
   {
@@ -104,7 +113,7 @@ export const claimTools: McpTool[] = [
 ];
 
 export async function handleClaimTool(
-  db: D1Database,
+  db: DatabaseAdapter,
   name: string,
   args: Record<string, unknown>
 ): Promise<McpToolResult> {
@@ -286,9 +295,22 @@ export async function handleClaimTool(
     }
 
     case 'collab_release': {
+      const sessionId = args.session_id as string;
       const claimId = args.claim_id as string;
       const status = args.status as 'completed' | 'abandoned';
       const summary = args.summary as string | undefined;
+      const force = args.force as boolean | undefined;
+
+      // Validate session_id
+      if (!sessionId || typeof sessionId !== 'string') {
+        return createToolResult(
+          JSON.stringify({
+            error: 'INVALID_INPUT',
+            message: 'session_id is required to verify ownership',
+          }),
+          true
+        );
+      }
 
       const claim = await getClaim(db, claimId);
       if (!claim) {
@@ -301,6 +323,46 @@ export async function handleClaimTool(
         );
       }
 
+      // Check ownership - only allow releasing your own claims unless config allows or force=true
+      if (claim.session_id !== sessionId) {
+        // Get caller's session config
+        const callerSession = await getSession(db, sessionId);
+        let config: SessionConfig = DEFAULT_SESSION_CONFIG;
+        if (callerSession?.config) {
+          try {
+            config = { ...DEFAULT_SESSION_CONFIG, ...JSON.parse(callerSession.config) };
+          } catch {
+            // Use default if parse fails
+          }
+        }
+
+        // Check if allowed to release others' claims
+        const canRelease = force === true || config.allow_release_others;
+
+        if (!canRelease) {
+          // Calculate how old the claim is
+          const claimAge = Date.now() - new Date(claim.created_at).getTime();
+          const staleHours = config.stale_threshold_hours;
+          const isStale = claimAge > staleHours * 60 * 60 * 1000;
+
+          return createToolResult(
+            JSON.stringify({
+              error: 'NOT_OWNER',
+              message: 'You can only release your own claims. This claim belongs to another session.',
+              claim_owner: claim.session_name,
+              claim_age_hours: Math.round(claimAge / (60 * 60 * 1000) * 10) / 10,
+              is_stale: isStale,
+              suggestions: [
+                'Use collab_message_send to ask the owner to release it.',
+                isStale ? 'This claim is stale. Ask user for confirmation, then use force=true to release.' : null,
+                'Use collab_config to enable allow_release_others for future releases.',
+              ].filter(Boolean),
+            }),
+            true
+          );
+        }
+      }
+
       if (claim.status !== 'active') {
         return createToolResult(
           JSON.stringify({
@@ -311,14 +373,18 @@ export async function handleClaimTool(
         );
       }
 
+      const isOwnClaim = claim.session_id === sessionId;
       await releaseClaim(db, claimId, { status, summary });
 
       return createToolResult(
         JSON.stringify({
           success: true,
-          message: `Claim ${status}. Files are now available for other sessions.`,
+          message: isOwnClaim
+            ? `Claim ${status}. Files are now available for other sessions.`
+            : `Claim from ${claim.session_name} forcefully ${status}.`,
           files: claim.files,
           summary: summary ?? null,
+          was_forced: !isOwnClaim,
         })
       );
     }

package/src/mcp/tools/decision.ts

@@ -1,6 +1,6 @@
 // Decision recording tools
 
-import type { D1Database } from '../../db/sqlite-adapter.js';
+import type { DatabaseAdapter } from '../../db/sqlite-adapter.js';
 import type { McpTool, McpToolResult } from '../protocol';
 import { createToolResult } from '../protocol';
 import type { DecisionCategory } from '../../db/types';
@@ -55,7 +55,7 @@ export const decisionTools: McpTool[] = [
 ];
 
 export async function handleDecisionTool(
-  db: D1Database,
+  db: DatabaseAdapter,
   name: string,
   args: Record<string, unknown>
 ): Promise<McpToolResult> {

package/src/mcp/tools/message.ts

@@ -1,6 +1,6 @@
 // Inter-session messaging tools
 
-import type { D1Database } from '../../db/sqlite-adapter.js';
+import type { DatabaseAdapter } from '../../db/sqlite-adapter.js';
 import type { McpTool, McpToolResult } from '../protocol';
 import { createToolResult } from '../protocol';
 import { sendMessage, listMessages, getSession } from '../../db/queries';
@@ -53,7 +53,7 @@ export const messageTools: McpTool[] = [
 ];
 
 export async function handleMessageTool(
-  db: D1Database,
+  db: DatabaseAdapter,
   name: string,
   args: Record<string, unknown>
 ): Promise<McpToolResult> {

package/src/mcp/tools/session.ts

@@ -1,6 +1,6 @@
 // Session management tools
 
-import type { D1Database } from '../../db/sqlite-adapter.js';
+import type { DatabaseAdapter } from '../../db/sqlite-adapter.js';
 import type { McpTool, McpToolResult } from '../protocol';
 import { createToolResult } from '../protocol';
 import {
@@ -9,11 +9,13 @@ import {
   listSessions,
   updateSessionHeartbeat,
   updateSessionStatus,
+  updateSessionConfig,
   endSession,
   cleanupStaleSessions,
   listClaims,
 } from '../../db/queries';
-import type { TodoItem } from '../../db/types';
+import type { TodoItem, SessionConfig, ConflictMode } from '../../db/types';
+import { DEFAULT_SESSION_CONFIG } from '../../db/types';
 
 export const sessionTools: McpTool[] = [
   {
@@ -134,10 +136,41 @@ export const sessionTools: McpTool[] = [
       required: ['session_id'],
     },
   },
+  {
+    name: 'collab_config',
+    description: 'Configure session behavior for conflict handling. Settings persist for the session duration.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session_id: {
+          type: 'string',
+          description: 'Your session ID',
+        },
+        mode: {
+          type: 'string',
+          enum: ['strict', 'smart', 'bypass'],
+          description: 'Conflict handling mode: strict (always ask), smart (ask but suggest for stale), bypass (warn only)',
+        },
+        allow_release_others: {
+          type: 'boolean',
+          description: 'Allow releasing claims from other sessions (default: false)',
+        },
+        auto_release_stale: {
+          type: 'boolean',
+          description: 'Automatically release stale claims (default: false)',
+        },
+        stale_threshold_hours: {
+          type: 'number',
+          description: 'Hours before a claim is considered stale (default: 2)',
+        },
+      },
+      required: ['session_id'],
+    },
+  },
 ];
 
 export async function handleSessionTool(
-  db: D1Database,
+  db: DatabaseAdapter,
   name: string,
   args: Record<string, unknown>,
   userId?: string
@@ -316,6 +349,65 @@ export async function handleSessionTool(
       );
     }
 
+    case 'collab_config': {
+      const sessionId = args.session_id as string;
+
+      // Validate session_id input
+      if (!sessionId || typeof sessionId !== 'string') {
+        return createToolResult(
+          JSON.stringify({
+            error: 'INVALID_INPUT',
+            message: 'session_id is required',
+          }),
+          true
+        );
+      }
+
+      // Validate session exists
+      const session = await getSession(db, sessionId);
+      if (!session || session.status !== 'active') {
+        return createToolResult(
+          JSON.stringify({
+            error: 'SESSION_INVALID',
+            message: 'Session not found or inactive.',
+          }),
+          true
+        );
+      }
+
+      // Get current config or default
+      let currentConfig: SessionConfig = DEFAULT_SESSION_CONFIG;
+      if (session.config) {
+        try {
+          currentConfig = { ...DEFAULT_SESSION_CONFIG, ...JSON.parse(session.config) };
+        } catch {
+          // Use default if parse fails
+        }
+      }
+
+      // Update with new values
+      const newConfig: SessionConfig = {
+        mode: (args.mode as ConflictMode) ?? currentConfig.mode,
+        allow_release_others: args.allow_release_others !== undefined
+          ? (args.allow_release_others as boolean)
+          : currentConfig.allow_release_others,
+        auto_release_stale: args.auto_release_stale !== undefined
+          ? (args.auto_release_stale as boolean)
+          : currentConfig.auto_release_stale,
+        stale_threshold_hours: (args.stale_threshold_hours as number) ?? currentConfig.stale_threshold_hours,
+      };
+
+      await updateSessionConfig(db, sessionId, newConfig);
+
+      return createToolResult(
+        JSON.stringify({
+          success: true,
+          message: 'Configuration updated.',
+          config: newConfig,
+        })
+      );
+    }
+
     default:
       return createToolResult(`Unknown session tool: ${name}`, true);
   }

package/src/tokens/handlers.ts

@@ -1,6 +1,6 @@
 // Token management API handlers
 
-import type { D1Database } from '../db/sqlite-adapter.js';
+import type { DatabaseAdapter } from '../db/sqlite-adapter.js';
 import { z } from 'zod';
 import { generateApiToken } from './generator';
 import { createApiToken, listApiTokens, revokeApiToken } from '../db/auth-queries';
@@ -14,7 +14,7 @@ const CreateTokenRequestSchema = z.object({
 });
 
 interface HandlerContext {
-  db: D1Database;
+  db: DatabaseAdapter;
   request: Request;
 }