@snapback/cli 1.1.15 → 3.0.0

package/dist/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node --no-warnings=ExperimentalWarning
 import { isSnapbackInitialized, getWorkspaceDir, getViolations, getProtectedFiles, appendSnapbackJsonl, clearCredentials, isLoggedIn, getCredentials, createGlobalDirectory, saveCredentials, getWorkspaceVitals, saveProtectedFiles, getCurrentSession, endCurrentSession, getWorkspaceConfig, recordLearning, getLearnings, readSnapbackJson, recordViolation, writeSnapbackJson, saveCurrentSession, loadSnapbackJsonl, getGlobalConfig, getGlobalDir, saveGlobalConfig, saveWorkspaceConfig } from './chunk-DPWFZNMY.js';
-import { createServiceClient, connectServiceClient, createSessionViaDaemon, endSessionViaDaemon, SnapBackLocalClient, isServiceRunning, getServiceSocketPath, readServicePid, formatDuration, formatBytes, getLogPath, getServicePidPath } from './chunk-DNEADD2G.js';
+import { createServiceClient, connectServiceClient, createSessionViaDaemon, endSessionViaDaemon, SnapBackLocalClient, isServiceRunning, getServiceSocketPath, readServicePid, formatDuration, formatBytes, getLogPath, getServicePidPath } from './chunk-O7HMAZ7L.js';
 import { detectOrphans } from './chunk-5SQA44V7.js';
 import './chunk-4YTE4JEW.js';
 import { isRedisAvailable, getCache, setCache } from './chunk-GQ73B37K.js';
@@ -8,7 +8,7 @@ import { withBreaker, getCircuitBreakerState } from './chunk-PL4HF4M2.js';
 import { createLogger, LogLevel, extractErrorCode } from './chunk-WS36HDEU.js';
 import { generateId } from './chunk-5EOPYJ4Y.js';
 import './chunk-CBGOC6RV.js';
-import { detectAIClients, getClient, getSnapbackMCPConfig, writeClientConfig, getServerKey, validateConfig, removeSnapbackConfig, patchApiKeyInClientConfig, detectWorkspaceConfig, validateClientConfig, repairClientConfig, readClientConfig } from './chunk-OI2HNNT6.js';
+import { detectAIClients, getClient, getSnapbackMCPConfig, writeClientConfig, getServerKey, validateConfig, removeSnapbackConfig, patchApiKeyInClientConfig, detectWorkspaceConfig, validateClientConfig, repairClientConfig, readClientConfig } from './chunk-E6V6QKS7.js';
 import { __commonJS, __name, __require } from './chunk-7ADPL4Q3.js';
 import * as fs32 from 'fs';
 import { existsSync, promises, readFileSync, watch, writeFileSync, statSync, mkdirSync, lstatSync, appendFileSync, renameSync, unlinkSync, openSync, readdirSync, watchFile } from 'fs';
@@ -66,7 +66,7 @@ var require_package = __commonJS({
   "package.json"(exports$1, module) {
     module.exports = {
       name: "@snapback/cli",
-      version: "1.1.15",
+      version: "3.0.0",
       description: "CLI tool for managing SnapBack snapshots and file protection",
       homepage: "https://snapback.dev",
       repository: {
@@ -1294,7 +1294,7 @@ var _authPromise = null;
 async function getAuth() {
   if (_auth) return _auth;
   if (_authPromise) return _authPromise;
-  _authPromise = import('./auth-HFJRXXG2.js').then((m) => {
+  _authPromise = import('./auth-TDIHGKKL.js').then((m) => {
     _auth = m.auth;
     return _auth;
   });
@@ -2900,7 +2900,7 @@ function createWorkspacesCommand() {
 __name(createWorkspacesCommand, "createWorkspacesCommand");
 var version = "0.0.0";
 {
-  version = "1.1.15";
+  version = "3.0.0";
 }
 var client = null;
 var connectionPromise = null;
@@ -3144,7 +3144,7 @@ function displayBox(contentOrOptions, options = {}) {
 }
 __name(displayBox, "displayBox");
 function displaySaveStory(riskScore, affectedFiles, snapshotId) {
-  return displayBox(`${chalk37.bold("\u{1F6E1}\uFE0F SnapBack just protected you!")}
+  return displayBox(`${chalk37.bold("\u{1F9E2} SnapBack just protected you!")}
 
 ${chalk37.cyan("Risk Score:")} ${chalk37.red(`${riskScore.toFixed(1)}/10`)}
 ${chalk37.cyan("Files Protected:")} ${chalk37.green(affectedFiles.length.toString())}
@@ -3160,7 +3160,7 @@ function displaySnapshotSuccess(snapshotId, message, fileCount) {
 ${chalk37.cyan("ID:")} ${snapshotId.substring(0, 8)}
 ${chalk37.cyan("Message:")} ${message || "(none)"}
 ${chalk37.cyan("Files:")} ${fileCount} protected`, {
-    title: "\u{1F6E1}\uFE0F SnapBack Protection Active",
+    title: "\u{1F9E2} SnapBack Protection Active",
     type: "success"
   });
 }
@@ -3656,7 +3656,7 @@ function findGitRoot(cwd) {
 __name(findGitRoot, "findGitRoot");
 
 // src/commands/init.ts
-var cliVersion = "1.1.15" ;
+var cliVersion = "3.0.0" ;
 function createInitCommand() {
   return new Command("init").description("Bootstrap SnapBack for a repository").argument("[path]", "Workspace path (default: current directory)").option("-y, --yes", "Skip confirmation prompts").option("--non-interactive", "Run without prompts (extension/automation)").option("--json", "Output structured JSON result").option("--dry-run", "Show what would be configured").option("--force", "Re-initialize even if already set up").option("--skip-mcp", "Skip MCP configuration").option("--skip-daemon", "Skip daemon registration").option("--api-key <key>", "API key for Pro features").option("--dev", "Use local dev mode for MCP").option("--npm", "Use npm/npx mode for MCP").option("-q, --quiet", "Suppress informational output").option("-v, --verbose", "Show detailed detection reasoning").action(async (path7, options) => {
     const result7 = await runInit(path7, options);
@@ -4297,7 +4297,7 @@ function createStatusCommand() {
     const cwd = process.cwd();
     try {
       if (!await isSnapbackInitialized(cwd)) {
-        console.log(chalk37.yellow("SnapBack not initialized in this workspace"));
+        console.log(chalk37.yellow("\u{1F9E2} SnapBack not initialized in this workspace"));
         console.log(chalk37.gray("Run: snap init"));
         process.exit(1);
       }
@@ -21698,11 +21698,8 @@ z.object({
   l: z.array(z.string()).optional().describe("Legacy: use 'learnings' instead"),
   // Other parameters
   notes: z.string().optional().describe("Completion notes"),
-  outcome: z.enum([
-    "completed",
-    "abandoned",
-    "blocked"
-  ]).optional().describe("Task outcome"),
+  /** Free-text outcome: what was accomplished, what remains, decisions made. ok:0|1 is the primary signal. */
+  outcome: z.string().min(1).max(2e3).optional().describe("Free-text task outcome (what was accomplished, what remains, decisions made)"),
   // Efficiency tracking (agent-reported metrics)
   efficiency: z.object({
     saved: z.string().optional().describe("Tokens saved (e.g., '~12K')"),
@@ -29296,7 +29293,7 @@ function createLearnCommand() {
     const cwd = process.cwd();
     try {
       if (!await isSnapbackInitialized(cwd)) {
-        console.log(chalk37.yellow("SnapBack not initialized in this workspace"));
+        console.log(chalk37.yellow("\u{1F9E2} SnapBack not initialized in this workspace"));
         console.log(chalk37.gray("Run: snap init"));
         process.exit(1);
       }
@@ -29362,7 +29359,7 @@ function createLearnCommand() {
     const cwd = process.cwd();
     try {
       if (!await isSnapbackInitialized(cwd)) {
-        console.log(chalk37.yellow("SnapBack not initialized"));
+        console.log(chalk37.yellow("\u{1F9E2} SnapBack not initialized"));
         console.log(chalk37.gray("Run: snap init"));
         process.exit(1);
       }
@@ -29871,7 +29868,7 @@ function createSessionCommand() {
     const cwd = process.cwd();
     try {
       if (!await isSnapbackInitialized(cwd)) {
-        console.log(chalk37.yellow("SnapBack not initialized in this workspace"));
+        console.log(chalk37.yellow("\u{1F9E2} SnapBack not initialized in this workspace"));
         console.log(chalk37.gray("Run: snap init"));
         process.exit(1);
       }
@@ -29943,7 +29940,7 @@ function createSessionCommand() {
     const cwd = process.cwd();
     try {
       if (!await isSnapbackInitialized(cwd)) {
-        console.log(chalk37.yellow("SnapBack not initialized"));
+        console.log(chalk37.yellow("\u{1F9E2} SnapBack not initialized"));
         console.log(chalk37.gray("Run: snap init"));
         process.exit(1);
       }
@@ -30007,7 +30004,7 @@ function createSessionCommand() {
     const cwd = process.cwd();
     try {
       if (!await isSnapbackInitialized(cwd)) {
-        console.log(chalk37.yellow("SnapBack not initialized"));
+        console.log(chalk37.yellow("\u{1F9E2} SnapBack not initialized"));
         console.log(chalk37.gray("Run: snap init"));
         process.exit(1);
       }
@@ -30021,7 +30018,7 @@ function createSessionCommand() {
       ] : [];
       if (learnings.length > 0 || options.ceremony) {
         try {
-          const { createServiceClient: createServiceClient4, connectServiceClient: connectServiceClient2, isServiceRunning: isServiceRunning2 } = await import('./local-service-adapter-3JHN6G4O.js');
+          const { createServiceClient: createServiceClient4, connectServiceClient: connectServiceClient2, isServiceRunning: isServiceRunning2 } = await import('./local-service-adapter-AB3UYRUK.js');
           if (isServiceRunning2()) {
             const client2 = createServiceClient4();
             await connectServiceClient2(client2);
@@ -30068,7 +30065,7 @@ function createSessionCommand() {
     const cwd = process.cwd();
     try {
       if (!await isSnapbackInitialized(cwd)) {
-        console.log(chalk37.yellow("SnapBack not initialized"));
+        console.log(chalk37.yellow("\u{1F9E2} SnapBack not initialized"));
         console.log(chalk37.gray("Run: snap init"));
         process.exit(1);
       }
@@ -34670,10 +34667,10 @@ async function autoStartDaemon2() {
     try {
       if (existsSync(SERVICE_SOCKET_PATH2)) {
         try {
-          await new Promise((resolve52, reject) => {
+          await new Promise((resolve62, reject) => {
             const sock = createConnection(SERVICE_SOCKET_PATH2, () => {
               sock.end();
-              resolve52();
+              resolve62();
             });
             sock.on("error", reject);
             setTimeout(() => {
@@ -34745,10 +34742,10 @@ async function autoStartDaemon2() {
       while (Date.now() < deadline) {
         if (existsSync(SERVICE_SOCKET_PATH2)) {
           try {
-            await new Promise((resolve52, reject) => {
+            await new Promise((resolve62, reject) => {
               const sock = createConnection(SERVICE_SOCKET_PATH2, () => {
                 sock.end();
-                resolve52();
+                resolve62();
               });
               sock.on("error", reject);
               setTimeout(() => {
@@ -36675,11 +36672,8 @@ var init_validation = __esm2({
       l: z.array(z.string()).optional().describe("Legacy: use 'learnings' instead"),
       // Other parameters
       notes: z.string().optional().describe("Completion notes"),
-      outcome: z.enum([
-        "completed",
-        "abandoned",
-        "blocked"
-      ]).optional().describe("Task outcome"),
+      /** Free-text outcome: what was accomplished, what remains, decisions made. ok:0|1 is the primary signal. */
+      outcome: z.string().min(1).max(2e3).optional().describe("Free-text task outcome (what was accomplished, what remains, decisions made)"),
       // Efficiency tracking (agent-reported metrics)
       efficiency: z.object({
         saved: z.string().optional().describe("Tokens saved (e.g., '~12K')"),
@@ -41880,12 +41874,6 @@ var init_begin_task = __esm2({
       const keywords = providedKeywords ?? extractKeywords2(task);
       const daemonResult = await beginTaskViaService(workspaceRoot, task, files, keywords);
       if (daemonResult) {
-        await startTaskAsync(workspaceRoot, {
-          description: task,
-          plannedFiles: files || [],
-          snapshotId: daemonResult.snapshot.id,
-          keywords
-        });
         const observations2 = (await drainPendingObservationsAsync(workspaceRoot)).map((o) => ({
           type: o.type,
           message: o.message
@@ -41970,7 +41958,9 @@ var init_begin_task = __esm2({
           return result2(formatCompactText(formatCompactResult(output2, gitContext2)));
         }
         const learningsCount = daemonResult.learnings?.length || 0;
-        const hint2 = daemonResult.snapshot.created ? `Safety snapshot created via daemon: ${daemonResult.snapshot.id}` : learningsCount > 0 ? `${learningsCount} relevant learning(s) found` : "Ready to start coding! (daemon-coordinated)";
+        const daemonSnapshotCreated = daemonResult.snapshot?.created ?? (daemonResult.snapshotIds?.length ?? 0) > 0;
+        const daemonSnapshotId = daemonResult.snapshot?.id ?? daemonResult.snapshotIds?.[0];
+        const hint2 = daemonSnapshotCreated ? `Safety snapshot created via daemon: ${daemonSnapshotId}` : learningsCount > 0 ? `${learningsCount} relevant learning(s) found` : "Ready to start coding! (daemon-coordinated)";
         return result2(JSON.stringify({
           ...output2,
           message: `Task started: ${task}`,
@@ -42190,12 +42180,7 @@ var init_begin_task = __esm2({
         snapshotId: snapshot.id,
         keywords
       });
-      if (!currentTask) {
-        return result2(JSON.stringify({
-          error: "E002_TASK_START_FAILED",
-          message: "Failed to start task. Please try again."
-        }), true);
-      }
+      const taskId = currentTask?.id ?? `local_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
       const state = await getSessionStateAsync(workspaceRoot);
       if (state) {
         state.riskAreasTouched = riskAssessment.riskAreas;
@@ -42208,7 +42193,7 @@ var init_begin_task = __esm2({
       const nextActions = generateNextActions(riskAssessment, learnings, staticAnalysis);
       const proactive_guidance = await generateProactiveGuidance(files || []);
       const output = {
-        taskId: currentTask.id,
+        taskId,
         intent,
         intentHints,
         snapshot,
@@ -43815,7 +43800,7 @@ var init_error_pattern_registry = __esm2({
 });
 async function runCommand2(cmd, args, cwd, timeoutMs = 3e4) {
   const start = Date.now();
-  return new Promise((resolve52) => {
+  return new Promise((resolve62) => {
     let stdout = "";
     let stderr = "";
     let killed = false;
@@ -43840,7 +43825,7 @@ async function runCommand2(cmd, args, cwd, timeoutMs = 3e4) {
     });
     proc.on("close", (code) => {
       clearTimeout(timeout);
-      resolve52({
+      resolve62({
         exitCode: killed ? -1 : code ?? 0,
         stdout,
         stderr,
@@ -43849,7 +43834,7 @@ async function runCommand2(cmd, args, cwd, timeoutMs = 3e4) {
     });
     proc.on("error", (err22) => {
       clearTimeout(timeout);
-      resolve52({
+      resolve62({
         exitCode: -1,
         stdout,
         stderr: err22.message,
@@ -44524,7 +44509,7 @@ var init_review_work = __esm2({
   }
 });
 function getFileDiff(file, workspaceRoot) {
-  return new Promise((resolve52) => {
+  return new Promise((resolve62) => {
     try {
       const result7 = execSync(`git diff --no-color -- "${file}"`, {
         cwd: workspaceRoot,
@@ -44532,15 +44517,15 @@ function getFileDiff(file, workspaceRoot) {
         maxBuffer: 1024 * 1024,
         timeout: 5e3
       });
-      resolve52(result7.trim() || null);
+      resolve62(result7.trim() || null);
     } catch {
-      resolve52(null);
+      resolve62(null);
     }
   });
 }
 __name(getFileDiff, "getFileDiff");
 function getGitChanges(workspaceRoot) {
-  return new Promise((resolve52) => {
+  return new Promise((resolve62) => {
     const changes = /* @__PURE__ */ new Map();
     try {
       const result7 = execSync("git status --porcelain", {
@@ -44564,7 +44549,7 @@ function getGitChanges(workspaceRoot) {
       }
     } catch {
     }
-    resolve52(changes);
+    resolve62(changes);
   });
 }
 __name(getGitChanges, "getGitChanges");
@@ -46683,16 +46668,7 @@ var init_input_sanitization = __esm2({
       // Intent - reuse guide intent schema
       intent: GuideIntentSchema.optional()
     });
-    SnapEndOutcomeSchema = z.enum([
-      "completed",
-      "abandoned",
-      "blocked",
-      "partial",
-      "success",
-      "failure",
-      "error",
-      "timeout"
-    ]);
+    SnapEndOutcomeSchema = sanitizedString(2e3, "outcome");
     SnapEndParamsSchema = z.object({
       // Success flag - boolean only
       ok: z.union([
@@ -46977,8 +46953,7 @@ var init_errors3 = __esm2({
 });
 function isActiveSession(session) {
   if (!session) return false;
-  return session.active === true || session.state === "active" || session.state === "started" || // Fallback: Has ID and not explicitly ended/idle
-  !!session.id && session.state !== "ended" && session.state !== "idle";
+  return session.active === true || session.state === "active" || session.state === "started" || session.state === "running";
 }
 __name(isActiveSession, "isActiveSession");
 var init_session = __esm2({
@@ -47017,6 +46992,11 @@ function formatSnapbackResponse(data) {
   if (data.isResumed) {
     sections.push(`Session resumed for: ${data.task}`);
     sections.push("Continuing from previous work in this workspace.");
+    if (data.sessionVitals) {
+      const { filesModified, snapshotsCreated, learningsCaptured } = data.sessionVitals;
+      sections.push(`
+\u{1F4CA} **Session state**: ${filesModified} files modified | ${snapshotsCreated} snapshots | ${learningsCaptured} learnings captured`);
+    }
   } else {
     sections.push(`Session started for: ${data.task}`);
   }
@@ -47081,12 +47061,8 @@ function formatSnapbackResponse(data) {
   if (data.beginData?.context?.coChangePatternsInScope && data.beginData.context.coChangePatternsInScope.length > 0) {
     hasTier2 = true;
     tier2Sections.push("\n### Files That Change Together\n");
-    for (const cluster of data.beginData.context.coChangePatternsInScope) {
-      for (let i = 0; i < cluster.files.length; i++) {
-        for (let j = i + 1; j < cluster.files.length; j++) {
-          tier2Sections.push(`- When you modify **${cluster.files[i]}**, you usually need to update **${cluster.files[j]}** too (${Math.round(cluster.coOccurrenceRate * 100)}% confidence)`);
-        }
-      }
+    for (const pair of data.beginData.context.coChangePatternsInScope) {
+      tier2Sections.push(`- When you modify **${pair.source}**, you usually need to update **${pair.target}** too (${Math.round(pair.confidence * 100)}% confidence)`);
     }
   }
   if (data.contextData?.learnings && data.contextData.learnings.length > 0) {
@@ -47135,13 +47111,9 @@ function formatSnapbackResponse(data) {
     }
     const riskCoChanges = extractCoChangeAlerts(data.riskAssessment);
     const beginCoChangePairs = /* @__PURE__ */ new Set();
-    for (const cluster of data.beginData?.context?.coChangePatternsInScope ?? []) {
-      for (let i = 0; i < cluster.files.length; i++) {
-        for (let j = i + 1; j < cluster.files.length; j++) {
-          beginCoChangePairs.add(`${cluster.files[i]}:${cluster.files[j]}`);
-          beginCoChangePairs.add(`${cluster.files[j]}:${cluster.files[i]}`);
-        }
-      }
+    for (const pair of data.beginData?.context?.coChangePatternsInScope ?? []) {
+      beginCoChangePairs.add(`${pair.source}:${pair.target}`);
+      beginCoChangePairs.add(`${pair.target}:${pair.source}`);
     }
     const newCoChanges = riskCoChanges.filter((c) => !beginCoChangePairs.has(`${c.file}:${c.partner}`));
     if (newCoChanges.length > 0) {
@@ -47166,6 +47138,7 @@ function formatSnapbackResponse(data) {
     }
   }
   sections.push("\nSnapBack is now monitoring this session. Files are automatically snapshotted when risk pressure exceeds 70% \u2014 no manual action needed.");
+  sections.push('\n\u26A0\uFE0F **REQUIRED**: Call `snap_end({ outcome: "completed" })` when your task is complete to close the session and capture learnings.');
   const kbNote = learningCount > 0 ? ` [${learningCount} learnings in knowledge base]` : " [session 1 \u2014 building baseline]";
   sections.push(`
 [session: ${data.session.id ?? data.session.taskId}]${kbNote}`);
@@ -47265,12 +47238,23 @@ ${validation.errors?.join("\n") ?? "Unknown validation error"}`
         task: validatedData?.task ?? validatedData?.t ?? args.task ?? "",
         files: validatedData?.files ?? validatedData?.f
       };
+      if (!params.task?.trim()) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "Error: task parameter is required and cannot be empty."
+            }
+          ],
+          isError: true
+        };
+      }
       const workspace = resolveWorkspace(context);
       const daemon = getDaemonClient2(workspace);
-      const health = await checkDaemonHealth(daemon, workspace);
       let session = null;
       let isResumed = false;
       let beginData = null;
+      let sessionVitals = null;
       try {
         const currentSession = await daemon.request("session/current", {
           workspace
@@ -47284,13 +47268,16 @@ ${validation.errors?.join("\n") ?? "Unknown validation error"}`
           };
           isResumed = true;
           if (params.task && params.task !== session.task) {
+            const previousTask = session.task;
+            session.task = params.task;
             try {
               await daemon.request("session/update-task", {
                 workspace,
                 task: params.task
               });
-              session.task = params.task;
-            } catch {
+            } catch (updateError) {
+              session.task = previousTask;
+              console.error("[snapback] session/update-task failed, task name reverted:", updateError);
             }
           }
           try {
@@ -47303,24 +47290,31 @@ ${validation.errors?.join("\n") ?? "Unknown validation error"}`
             const warningsResult = await daemon.request("intelligence/warnings", {
               workspace
             });
-            const coChangeClusters = (coChangeResult?.pairs ?? []).map((pair) => ({
-              files: [
-                pair.source,
-                pair.target
-              ],
-              coOccurrenceRate: pair.confidence,
-              sampleSize: 1
-            }));
             beginData = {
               id: currentSession.id,
               context: {
                 fragileFilesInScope: fragileResult?.files ?? [],
-                coChangePatternsInScope: coChangeClusters,
+                coChangePatternsInScope: coChangeResult?.pairs ?? [],
                 concurrentSessionWarning: null
               },
               learnings: []
             };
             console.error(`[snapback] Resume intelligence: ${fragileResult?.files?.length ?? 0} fragile, ${coChangeResult?.pairs?.length ?? 0} co-changes, ${warningsResult?.warnings?.length ?? 0} warnings`);
+            try {
+              const vitalsResult = await daemon.request("session/vitals", {
+                workspace
+              });
+              if (vitalsResult) {
+                sessionVitals = {
+                  filesModified: vitalsResult.filesModified ?? 0,
+                  snapshotsCreated: vitalsResult.snapshotsCreated ?? 0,
+                  learningsCaptured: vitalsResult.learningsCaptured ?? 0
+                };
+                console.error(`[snapback] Resume vitals: ${sessionVitals.filesModified} files, ${sessionVitals.snapshotsCreated} snapshots, ${sessionVitals.learningsCaptured} learnings`);
+              }
+            } catch (vitalsError) {
+              console.error("[snapback] Resume vitals fetch failed:", vitalsError);
+            }
           } catch (resumeError) {
             console.error("[snapback] Resume intelligence fetch failed:", resumeError);
           }
@@ -47385,6 +47379,7 @@ ${validation.errors?.join("\n") ?? "Unknown validation error"}`
         }
       }
       if (!session) {
+        const health = await checkDaemonHealth(daemon, workspace);
         if (!health.healthy) {
           return formatDaemonError(classifyDaemonError(null));
         }
@@ -47425,7 +47420,8 @@ ${validation.errors?.join("\n") ?? "Unknown validation error"}`
         riskAssessment,
         contextData,
         beginData,
-        task: params.task
+        task: params.task,
+        sessionVitals
       });
     }, "handleSnapback");
     __name12(formatSnapbackResponse, "formatSnapbackResponse");
@@ -47433,42 +47429,34 @@ ${validation.errors?.join("\n") ?? "Unknown validation error"}`
     __name12(extractFragileFiles, "extractFragileFiles");
     __name12(extractCoChangeAlerts, "extractCoChangeAlerts");
     snapbackTool = {
-      name: "snapback",
-      description: `Call this FIRST at the start of every coding task. Returns codebase-specific intelligence about the files you're about to touch \u2014 fragile files to handle carefully, co-change patterns you might miss, and learnings from previous sessions in this area. Without this context, you're coding blind.
-
-WHAT IT DOES:
-- Opens a monitored session that tracks every file you modify
-- Returns relevant learnings from previous sessions, fragile file warnings, and co-change patterns
-- When risk pressure exceeds 70%, snapshots are created automatically (checked every 30s)
-- If a session already exists for this workspace, resumes it with fresh intelligence
-- On first session (cold start): briefing will be sparse \u2014 intelligence accumulates with each session
+      name: "snap_begin",
+      description: `Call this before any other tool when starting a coding task. Opens a session, returns codebase intelligence your context window does not have \u2014 fragile files, co-change patterns, past learnings \u2014 and enables automatic snapshot protection. Without this call: no session tracking, no automatic snapshots, snap_pulse and snap_end return empty results.
 
 WHEN TO CALL:
-- At the start of EVERY task, before making any changes \u2014 even if you don't know which files yet
-- Safe to call multiple times \u2014 resumes the existing session, does not create duplicates
+- At the start of every task, before any file reads or changes \u2014 even if you don't know which files yet
+- Safe to call multiple times \u2014 resumes the existing session without creating duplicates
 
 WHEN NOT TO CALL:
-- Mid-task to check status (use snap_pulse instead)
-- To end a session (use snapback_end instead)
-- If you only need to record a discovery (use snapback_learn instead)
+- Mid-task health check \u2192 snap_pulse
+- Record a discovery \u2192 snap_learn
+- Close the session \u2192 snap_end
 
-WORKFLOW POSITION: 1 of 4
-  snapback \u2192 [your work] \u2192 snap_pulse (optional, mid-task) \u2192 snapback_end
-  snapback_learn can be called anytime during the session.
+WORKFLOW: snap_begin \u2192 [work] \u2192 snap_learn (anytime) \u2192 snap_pulse (optional) \u2192 snap_end
 
 WHAT YOU GET BACK (natural language text, not structured JSON):
 - Session ID and status (new or resumed)
 - Relevant learnings from previous sessions in this codebase
 - Fragile files in scope (files with high rollback or violation history)
 - Co-change patterns (files that historically change together)
-- Compressed codebase context in wire format (\u{1F9E2}|CTX|...)
+- Risk assessment for the files you intend to modify
 - Session health vitals (pulse, pressure, trajectory)
 
-Call snapback_end when you finish the task to close the session
-and receive a summary of what was accomplished.
+AUTOMATIC PROTECTION: Snapshots fire when risk pressure exceeds 70%. No manual action needed.
+
+COLD START: First session returns sparse output. Intelligence accumulates with each session \u2014 call it anyway.
 
 EXAMPLE:
-snapback({ task: "refactor auth module to use OAuth", files: ["src/auth.ts"] })`,
+snapback({ task: "Refactor auth middleware to support OAuth2 PKCE", files: ["src/auth/middleware.ts"] })`,
       inputSchema: {
         type: "object",
         properties: {
@@ -47500,7 +47488,7 @@ Example: ["src/auth/middleware.ts", "src/auth/oauth.ts"]`
           t: {
             type: "string",
             title: "Task Description (shorthand)",
-            description: "Alias for 'task' parameter. Use full 'task' for clarity."
+            description: "Shorthand for 'task'."
           },
           f: {
             type: "array",
@@ -47508,7 +47496,7 @@ Example: ["src/auth/middleware.ts", "src/auth/oauth.ts"]`
               type: "string"
             },
             title: "Target Files (shorthand)",
-            description: "Alias for 'files' parameter. Use full 'files' for clarity."
+            description: "Shorthand for 'files'."
           }
         },
         required: [],
@@ -47527,7 +47515,7 @@ Example: ["src/auth/middleware.ts", "src/auth/oauth.ts"]`
       },
       annotations: {
         title: "\u{1F6E1}\uFE0F SnapBack",
-        readOnlyHint: true,
+        readOnlyHint: false,
         destructiveHint: false,
         idempotentHint: true,
         openWorldHint: true
@@ -47536,6 +47524,25 @@ Example: ["src/auth/middleware.ts", "src/auth/oauth.ts"]`
     };
   }
 });
+function formatDuration22(ms) {
+  const seconds = Math.floor(ms / 1e3);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+  if (hours > 0) {
+    const remainingMinutes = minutes % 60;
+    return `${hours}h ${remainingMinutes}m`;
+  }
+  if (minutes > 0) {
+    return `${minutes}m`;
+  }
+  return `${seconds}s`;
+}
+__name(formatDuration22, "formatDuration2");
+var init_format_duration = __esm2({
+  "src/utils/format-duration.ts"() {
+    __name12(formatDuration22, "formatDuration");
+  }
+});
 function formatEndResponse(data) {
   const sections = [];
   const task = data.session.task ?? data.session.metadata?.task ?? "unnamed task";
@@ -47626,10 +47633,6 @@ _Estimated time saved: ~${timeSaved} minutes_`);
         tier2Sections.push(`- ${typeEmoji} **${insight.title}**: ${insight.body}`);
       }
     }
-    if (data.aiSynthesis.nextAction) {
-      tier2Sections.push(`
-**Recommended next action**: ${data.aiSynthesis.nextAction}`);
-    }
     if (data.aiSynthesis.model) {
       tier2Sections.push(`
 _Analysis powered by ${data.aiSynthesis.model}${data.aiSynthesis.cached ? " (cached)" : ""}_`);
@@ -47689,20 +47692,6 @@ ${metrics.snapshotsCreated} snapshots were created during this session. If any c
   };
 }
 __name(formatEndResponse, "formatEndResponse");
-function formatDuration22(ms) {
-  const seconds = Math.floor(ms / 1e3);
-  const minutes = Math.floor(seconds / 60);
-  const hours = Math.floor(minutes / 60);
-  if (hours > 0) {
-    const remainingMinutes = minutes % 60;
-    return `${hours}h ${remainingMinutes}m`;
-  }
-  if (minutes > 0) {
-    return `${minutes}m`;
-  }
-  return `${seconds}s`;
-}
-__name(formatDuration22, "formatDuration2");
 function buildSessionDiagnostics(session, workspace) {
   const lines = [
     "**Diagnostic Info:**"
@@ -47728,10 +47717,10 @@ function buildSessionDiagnostics(session, workspace) {
   return lines.join("\n");
 }
 __name(buildSessionDiagnostics, "buildSessionDiagnostics");
-function gatherMetrics(endResult, ceremonyData, session) {
-  const filesModified = ceremonyData?.filesModified ?? session?.touchedFiles?.length ?? endResult?.filesModified ?? 0;
-  const snapshotsCreated = ceremonyData?.snapshotsCreated ?? ceremonyData?.checkpointsCreated ?? session?.snapshotIds?.length ?? endResult?.snapshotsCreated ?? 0;
-  const learningsCaptured = ceremonyData?.learningsCaptured ?? session?.learningIds?.length ?? endResult?.learningsCaptured ?? 0;
+function gatherMetrics(endResult, ceremonyData, _session) {
+  const filesModified = ceremonyData?.filesModified ?? endResult?.filesModified ?? 0;
+  const snapshotsCreated = ceremonyData?.checkpointsCreated ?? ceremonyData?.snapshotsCreated ?? endResult?.snapshotsCreated ?? 0;
+  const learningsCaptured = ceremonyData?.learningsCaptured ?? endResult?.learningsCaptured ?? 0;
   const duration = ceremonyData?.duration ?? ceremonyData?.ceremony?.summary?.duration ?? endResult?.duration ?? null;
   return {
     filesModified,
@@ -47754,10 +47743,12 @@ function describeCoherence(score) {
     };
     return descriptions[score] ?? `Unknown coherence level: ${score}`;
   }
-  if (score >= 0.8) return "Highly focused session \u2014 changes were well-scoped and consistent";
-  if (score >= 0.6) return "Good coherence \u2014 mostly focused with minor tangents";
-  if (score >= 0.4) return "Mixed session \u2014 several distinct concerns addressed";
-  if (score >= 0.2) return "Scattered session \u2014 many unrelated changes";
+  let normalizedScore = score;
+  if (typeof normalizedScore === "number" && normalizedScore > 1) normalizedScore = normalizedScore / 100;
+  if (normalizedScore >= 0.8) return "Highly focused session \u2014 changes were well-scoped and consistent";
+  if (normalizedScore >= 0.6) return "Good coherence \u2014 mostly focused with minor tangents";
+  if (normalizedScore >= 0.4) return "Mixed session \u2014 several distinct concerns addressed";
+  if (normalizedScore >= 0.2) return "Scattered session \u2014 many unrelated changes";
   return "Low coherence \u2014 this session touched many unrelated areas";
 }
 __name(describeCoherence, "describeCoherence");
@@ -47914,9 +47905,16 @@ var AI_SYNTHESIS_CONFIG;
 var snapbackEndTool;
 var init_snapback_end = __esm2({
   "src/tools/v2/snapback-end.ts"() {
+    init_input_sanitization();
+    init_format_duration();
     init_utils3();
     handleSnapbackEnd = /* @__PURE__ */ __name12(async (args, context) => {
-      const params = args;
+      const rawArgs = args;
+      const rawOutcome = typeof rawArgs.outcome === "string" ? rawArgs.outcome : "";
+      const sanitizedOutcome = normalizeContent(rawOutcome).slice(0, MAX_LENGTHS.description);
+      const params = {
+        outcome: sanitizedOutcome
+      };
       const workspace = resolveWorkspace(context);
       const daemon = getDaemonClient2(workspace);
       let currentSession = null;
@@ -47967,7 +47965,14 @@ var init_snapback_end = __esm2({
         const payload = buildAIMetadataPayload(ceremonyData, currentSession);
         const daemonBaseUrl = process.env.SNAPBACK_API_URL ?? "http://127.0.0.1:4200";
         const apiKey = process.env.SNAPBACK_API_KEY;
-        aiSynthesis = await fetchAISynthesis(payload, currentSession.id ?? currentSession.taskId ?? "unknown", daemonBaseUrl, apiKey);
+        const urlHost = new URL(daemonBaseUrl.startsWith("http") ? daemonBaseUrl : `http://${daemonBaseUrl}`).hostname;
+        const isLoopback = urlHost === "127.0.0.1" || urlHost === "localhost" || urlHost === "::1";
+        if (!daemonBaseUrl.startsWith("https://") && !isLoopback) {
+          console.error("[snapback-end] Skipping AI synthesis: Bearer token must not be sent over plain HTTP to remote host");
+          aiSynthesis = null;
+        } else {
+          aiSynthesis = await fetchAISynthesis(payload, currentSession.id ?? currentSession.taskId ?? "unknown", daemonBaseUrl, apiKey);
+        }
       } catch {
         aiSynthesis = null;
       }
@@ -47980,7 +47985,6 @@ var init_snapback_end = __esm2({
       });
     }, "handleSnapbackEnd");
     __name12(formatEndResponse, "formatEndResponse");
-    __name12(formatDuration22, "formatDuration");
     __name12(buildSessionDiagnostics, "buildSessionDiagnostics");
     __name12(gatherMetrics, "gatherMetrics");
     __name12(describeCoherence, "describeCoherence");
@@ -47998,8 +48002,8 @@ var init_snapback_end = __esm2({
     __name12(inferScopeType, "inferScopeType");
     __name12(fetchAISynthesis, "fetchAISynthesis");
     snapbackEndTool = {
-      name: "snapback_end",
-      description: `Close the SnapBack session opened by snapback and receive a summary
+      name: "snap_end",
+      description: `Close the SnapBack session opened by snap_begin and receive a summary
 of what was accomplished.
 
 WHAT IT DOES:
@@ -48012,20 +48016,22 @@ WHAT IT DOES:
 - Persisted session data is cleaned up
 
 WHEN TO CALL:
-- At the end of every task, after your work is complete
+- At the end of every task, after your work is complete and deliverable is ready
+- Right after generating a final artifact/code \u2014 before your closing message to the user
 - When abandoning a task partway through (use outcome to explain why)
 - Before starting a completely different task in the same workspace
 
 WHEN NOT TO CALL:
 - Mid-task to check progress (use snap_pulse instead)
+- Still iterating or waiting for user input
 - If no session was started (the tool handles this gracefully,
-  but calling snapback first gives you a meaningful ceremony)
+  but calling snap_begin first gives you a meaningful ceremony)
 
 WORKFLOW POSITION: 4 of 4 (final)
-  snapback \u2192 [your work] \u2192 snap_pulse (optional) \u2192 snapback_end
+  snap_begin \u2192 [your work] \u2192 snap_pulse (optional) \u2192 snap_end
 
-  This closes the session opened by snapback. Every snapback call
-  should eventually have a matching snapback_end.
+  This closes the session opened by snap_begin. Every snap_begin call
+  should eventually have a matching snap_end.
 
 WHAT YOU GET BACK (natural language text):
 - Task name and outcome
@@ -48041,24 +48047,23 @@ Always safe to call \u2014 gracefully handles missing sessions
 with a clear message instead of an error.
 
 EXAMPLE:
-snapback_end({ outcome: "completed OAuth integration, all tests passing" })`,
+snapback_end({ outcome: "Refactored auth middleware to support OAuth2 PKCE. Token refresh is now in src/auth/refresh.ts. Left incomplete: revoke-token endpoint still uses the old pattern. Decided to keep session cookies HTTP-only after security review." })`,
       inputSchema: {
         type: "object",
         properties: {
           outcome: {
             type: "string",
             title: "Task Outcome",
-            description: `What happened during this session.
+            description: `What you accomplished, what remains incomplete, and any decisions made. This becomes the opening context for your next session \u2014 a vague outcome produces a sparse briefing next time. One paragraph minimum.
 
-GOOD: "Completed OAuth2 PKCE implementation, all tests passing"
+GOOD: "Refactored auth middleware to support OAuth2 PKCE. Token refresh is now in src/auth/refresh.ts. Left incomplete: revoke-token endpoint still uses the old pattern. Decided to keep session cookies HTTP-only after security review."
 GOOD: "Partially done \u2014 auth flow works but token refresh not implemented yet"
 GOOD: "Abandoned \u2014 realized this approach won't work, need different strategy"
 
 BAD:  "done"
+BAD:  "completed the task"
 
-Stored with the session and visible in the closing ceremony.
-Be honest \u2014 "partially done, tests still failing" is more useful
-than "done" for future session context.`
+Be honest \u2014 future sessions start from this context.`
           }
         },
         required: [
@@ -48078,15 +48083,16 @@ than "done" for future session context.`
 });
 function formatLearnResponse(data) {
   const sections = [];
-  sections.push(`Learning captured (${data.severity}): "${data.insight}"`);
+  const typeLabel = data.type !== "pattern" ? ` [${data.type}]` : "";
+  sections.push(`Rule encoded${typeLabel} (${data.severity}): when ${data.trigger} \u2192 ${data.action}`);
   if (data.implicitSession) {
-    sections.push("\nNote: No active session was found, so one was created automatically. For full codebase intelligence, call `snapback` before starting work.");
+    sections.push("\nNote: No active session was found, so one was created automatically. For full codebase intelligence, call `snap_begin` before starting work.");
   }
   if (data.relatedLearnings.length > 0) {
     sections.push(`
 ## Related Knowledge (${data.relatedLearnings.length} existing)
 `);
-    sections.push("Previous discoveries about this area:");
+    sections.push("Previous rules about this area:");
     for (const learning of data.relatedLearnings) {
       sections.push(`- ${learning}`);
     }
@@ -48187,12 +48193,29 @@ var handleSnapbackLearn;
 var snapbackLearnTool;
 var init_snapback_learn = __esm2({
   "src/tools/v2/snapback-learn.ts"() {
+    init_input_sanitization();
     init_utils3();
     handleSnapbackLearn = /* @__PURE__ */ __name12(async (args, context) => {
-      const params = args;
+      const rawArgs = args;
+      const sanitizedArgs = {
+        ...rawArgs,
+        ...typeof rawArgs.trigger === "string" && {
+          trigger: normalizeContent(rawArgs.trigger).slice(0, MAX_LENGTHS.trigger)
+        },
+        ...typeof rawArgs.action === "string" && {
+          action: normalizeContent(rawArgs.action).slice(0, MAX_LENGTHS.action)
+        },
+        ...typeof rawArgs.insight === "string" && {
+          insight: normalizeContent(rawArgs.insight).slice(0, MAX_LENGTHS.trigger)
+        }
+      };
+      const params = sanitizedArgs;
       const workspace = resolveWorkspace(context);
       const daemon = getDaemonClient2(workspace);
       const severity = params.severity ?? "info";
+      const trigger = params.trigger ?? params.insight ?? "";
+      const action = params.action ?? deriveAction(params.insight ?? "", severity);
+      const type = params.type ?? mapSeverityToType(severity);
       let implicitSession = false;
       let currentSessionId;
       try {
@@ -48200,11 +48223,12 @@ var init_snapback_learn = __esm2({
           workspace
         });
         if (!isActiveSession(currentSession)) {
-          await daemon.request("session/begin", {
+          const beginResult = await daemon.request("session/begin", {
             workspace,
             task: "Implicit session (learning captured before explicit session start)",
             files: params.files ?? []
           });
+          currentSessionId = beginResult?.sessionId ?? beginResult?.taskId;
           implicitSession = true;
         } else {
           currentSessionId = currentSession.id ?? currentSession.taskId;
@@ -48215,13 +48239,13 @@ var init_snapback_learn = __esm2({
         }
       }
       const learningPayload = {
-        type: mapSeverityToType(severity),
-        trigger: params.files ?? [],
-        solution: params.insight,
-        action: deriveAction(params.insight, severity),
+        type,
+        trigger,
+        solution: trigger,
+        action,
         source: "llm-observation",
         priority: mapSeverityToPriority(severity),
-        keywords: extractKeywords22(params.insight),
+        keywords: extractKeywords22(`${trigger} ${action}`),
         related: params.files
       };
       let addResult = null;
@@ -48243,7 +48267,7 @@ var init_snapback_learn = __esm2({
       try {
         const searchResult = await daemon.request("learning/search", {
           workspace,
-          query: params.insight,
+          query: trigger,
           files: params.files,
           limit: 5
         });
@@ -48257,7 +48281,9 @@ var init_snapback_learn = __esm2({
         implicitSession,
         relatedLearnings,
         severity,
-        insight: params.insight
+        type,
+        trigger,
+        action
       });
     }, "handleSnapbackLearn");
     __name12(formatLearnResponse, "formatLearnResponse");
@@ -48266,60 +48292,62 @@ var init_snapback_learn = __esm2({
     __name12(deriveAction, "deriveAction");
     __name12(extractKeywords22, "extractKeywords");
     snapbackLearnTool = {
-      name: "snapback_learn",
-      description: `Record a codebase discovery that should be remembered across sessions.
+      name: "snap_learn",
+      description: `Encode a reusable IF/THEN rule into the workspace knowledge base. trigger: the condition under which this rule applies ('when editing auth.ts without running tests'). action: what to do when that condition is true ('always snapshot before touching token refresh logic'). Not for observations or file annotations \u2014 call snap_pulse with a query param for retrieval.
 
-WHAT IT DOES:
-- Stores a typed learning (pattern, pitfall, preference, or constraint)
-  in the workspace knowledge base
-- Associates the learning with the current session for ceremony attribution
-- Returns similar learnings already captured, so you can see what's
-  already known and avoid duplicates
-
-WHEN TO CALL:
-- When you discover a pattern: "These two files must always change together"
-- When you hit a pitfall: "Editing this config without rebuilding causes silent failures"
-- When you learn a constraint: "This module cannot import from the platform package"
-- When you identify a preference: "Team prefers explicit error handling over try-catch"
+CALL IMMEDIATELY WHEN:
+- User corrects an assumption you made ("Actually, we use X not Y")
+- You discover a codebase pattern that contradicts your expectations
+- An error reveals an unknown constraint or fragile dependency
+- You find undocumented behavior that future sessions must know about
+- You identify a team preference or hard rule
 
 WHEN NOT TO CALL:
-- To start a session (use snapback instead)
-- To check session health (use snap_pulse instead)
-- To end a session (use snapback_end instead)
-- For trivial observations that won't help future sessions
+- To retrieve learnings \u2192 snap_pulse with query param (read-only)
+- For trivial observations that won't matter in future sessions
+- To confirm expected/standard behavior
 
-WORKFLOW POSITION: Can be called anytime during a session.
-  snapback \u2192 [work] \u2192 snapback_learn \u2192 [work] \u2192 snapback_learn \u2192 snapback_end
+WORKFLOW POSITION: Anytime during a session.
+  snap_begin \u2192 [work] \u2192 snap_learn \u2192 [work] \u2192 snap_learn \u2192 snap_end
 
   Works without an active session, but for full intelligence context,
-  call snapback first. Without a session, learnings are stored but
+  call snap_begin first. Without a session, learnings are stored but
   not attributed to any task in the closing ceremony.
 
 WHAT YOU GET BACK (natural language text):
-- Confirmation that the learning was stored
-- The severity level assigned
-- Similar learnings already in the knowledge base (to avoid duplicates
-  and reinforce existing knowledge)
+- Confirmation the rule was stored
+- Related learnings already in the knowledge base (deduplication loop)
 
 EXAMPLE:
-snapback_learn({ insight: "auth.ts silently swallows token refresh errors", files: ["src/auth.ts"], severity: "warning" })`,
+snap_learn({
+  trigger: "when modifying token refresh logic in auth.ts",
+  action: "snapshot first \u2014 this code has 3 rollbacks across 2 sessions",
+  type: "pitfall",
+  severity: "warning",
+  files: ["src/auth/auth.ts"]
+})`,
       inputSchema: {
         type: "object",
         properties: {
-          insight: {
+          trigger: {
             type: "string",
-            title: "Discovery",
-            description: `The discovery to record. Be specific and actionable.
-
-GOOD: "The session-registry.ts appendTouchedFile method silently
-       deduplicates \u2014 calling it twice with the same path is safe
-       and expected during burst file changes."
+            title: "Condition",
+            description: `The condition. Starts with 'when' \u2014 when X is true, when Y happens, when you're in Z state.
 
-BAD:  "session registry is interesting"
-BAD:  "found a bug"
+GOOD: "when editing auth.ts without running tests first"
+GOOD: "when the daemon restarts during an active session"
+BAD:  "auth.ts is fragile"
+BAD:  "I noticed something"`
+          },
+          action: {
+            type: "string",
+            title: "Action",
+            description: `What to do when the trigger fires. Starts with a verb.
 
-Include the WHY, not just the WHAT. Future sessions surface these
-learnings by keyword relevance \u2014 specific terms help retrieval.`
+GOOD: "always snapshot before touching token refresh logic"
+GOOD: "check that session.json was cleaned up before starting a new session"
+BAD:  "be careful"
+BAD:  "token refresh is tricky"`
           },
           files: {
             type: "array",
@@ -48327,10 +48355,25 @@ learnings by keyword relevance \u2014 specific terms help retrieval.`
               type: "string"
             },
             title: "Related Files",
-            description: `Files this learning applies to. Improves future retrieval when
-those files are being modified.
+            description: `Files this rule is scoped to. Narrows retrieval relevance.
 
 Example: ["src/services/session-registry.ts"]`
+          },
+          type: {
+            type: "string",
+            enum: [
+              "pattern",
+              "pitfall",
+              "constraint",
+              "preference"
+            ],
+            title: "Rule Type",
+            description: `Controls how this learning surfaces in future briefings.
+
+"pattern"    \u2014 A repeating structure worth following
+"pitfall"    \u2014 A known failure mode to avoid
+"constraint" \u2014 A hard rule that must not be violated
+"preference" \u2014 A soft team preference`
           },
           severity: {
             type: "string",
@@ -48340,15 +48383,21 @@ Example: ["src/services/session-registry.ts"]`
               "critical"
             ],
             title: "Severity Level",
-            description: `How important is this learning?
+            description: `How urgently this rule surfaces.
 
-"info"     \u2014 Useful context, no action required (default)
-"warning"  \u2014 Should be surfaced when these files are modified
-"critical" \u2014 Must be surfaced every time \u2014 ignoring this causes failures`
+"info"     \u2014 Shown when relevant files are in scope (default)
+"warning"  \u2014 Shown whenever related files are modified
+"critical" \u2014 Shown in snap_begin even on cold start, regardless of file scope`
+          },
+          insight: {
+            type: "string",
+            title: "Insight (deprecated)",
+            description: "Deprecated. Use trigger + action instead."
           }
         },
         required: [
-          "insight"
+          "trigger",
+          "action"
         ]
       },
       annotations: {
@@ -48516,10 +48565,9 @@ function formatHealthyResponse(session, vitals) {
   } else if (session.filesTouched) {
     parts.push(`${session.filesTouched} files touched`);
   }
-  if (vitals?.snapshotsCreated) {
-    parts.push(`${vitals.snapshotsCreated} snapshots`);
-  } else if (session.snapshotsCreated) {
-    parts.push(`${session.snapshotsCreated} snapshots`);
+  const healthySnapshots = vitals?.snapshotsCreated ?? session.snapshotsCreated;
+  if (healthySnapshots) {
+    parts.push(`${healthySnapshots} snapshots`);
   }
   if (vitals) {
     parts.push(`Pulse: ${vitals.pulse}`);
@@ -48623,12 +48671,12 @@ function formatGuardHealth(health, touchedFiles) {
     lines.push(`   Issues: ${failCount} failing, ${warnCount} warning${warnCount !== 1 ? "s" : ""}`);
   }
   const relevantIssues = [];
-  const touchedSet = touchedFiles ? new Set(touchedFiles.map((f) => f.split("/").pop() ?? f)) : /* @__PURE__ */ new Set();
+  const touchedSet = touchedFiles ? new Set(touchedFiles.map((f) => f.replace(/\\/g, "/").replace(/\/+$/, ""))) : /* @__PURE__ */ new Set();
   for (const guard2 of health.guards) {
     if (guard2.status === "pass") continue;
     for (const file of guard2.files) {
-      const fileName = file.path.split("/").pop() ?? file.path;
-      if (touchedSet.size === 0 || touchedSet.has(fileName) || relevantIssues.length < 3) {
+      const normalizedFilePath = file.path.replace(/\\/g, "/").replace(/\/+$/, "");
+      if (touchedSet.size === 0 || touchedSet.has(normalizedFilePath) || relevantIssues.length < 3) {
         relevantIssues.push({
           guard: guard2.guard,
           status: guard2.status,
@@ -48761,6 +48809,7 @@ var handleSnapbackPulse;
 var snapbackPulseTool;
 var init_snapback_pulse = __esm2({
   "src/tools/v2/snapback-pulse.ts"() {
+    init_input_sanitization();
     init_utils3();
     RISK_THRESHOLD = 0.3;
     CO_CHANGE_CONFIDENCE_THRESHOLD = 0.5;
@@ -48773,7 +48822,9 @@ var init_snapback_pulse = __esm2({
       const params = args ?? {};
       const workspace = resolveWorkspace(context);
       const daemon = getDaemonClient2(workspace);
-      const effectiveQuery = params.task ?? params.query;
+      const rawTask = params.task ? normalizeContent(params.task).slice(0, MAX_LENGTHS.task) : void 0;
+      const rawQuery = params.query ? normalizeContent(params.query).slice(0, MAX_LENGTHS.task) : void 0;
+      const effectiveQuery = rawTask ?? rawQuery;
       const [sessionResult, vitalsResult, warningsResult, fragileResult, coChangeResult, guardHealthResult, topologyStatusResult, topologyQueryResult, learningSearchResult] = await Promise.allSettled([
         daemon.request("session/current", {
           workspace
@@ -48876,8 +48927,7 @@ var init_snapback_pulse = __esm2({
     __name12(countMissingCoChanges, "countMissingCoChanges");
     snapbackPulseTool = {
       name: "snap_pulse",
-      description: `Check the health and risk state of your current SnapBack session.
-Read-only \u2014 does not modify any state or create snapshots.
+      description: `Read-only session health check. Does not write, learn, or create snapshots.
 
 WHAT IT DOES:
 - Returns current session vitals: pulse (activity level), pressure
@@ -48891,18 +48941,21 @@ WHAT IT DOES:
 
 WHEN TO CALL:
 - After modifying 3+ files, to check if pressure is building
+- After 3+ tool calls on the same task without a checkpoint
 - Before a destructive change (delete, revert, major refactor)
+- When multiple valid implementation paths exist \u2014 before committing to one
+- Before asking the user a clarifying question (capture state first)
 - When switching context between different areas of the codebase
 - To verify the session is still active after an interruption
 - When starting work on a task \u2014 provide task description for oriented briefing
 
 WHEN NOT TO CALL:
-- To start a session (use snapback instead)
-- To end a session (use snapback_end instead)
-- Immediately after snapback \u2014 the session just started, there's nothing to check yet
+- To start a session (use snap_begin instead)
+- To end a session (use snap_end instead)
+- Immediately after snap_begin \u2014 the session just started, there's nothing to check yet
 
 WORKFLOW POSITION: 3 of 4 (optional, repeatable)
-  snapback \u2192 [your work] \u2192 snap_pulse \u2192 [more work] \u2192 snap_pulse \u2192 snapback_end
+  snap_begin \u2192 [your work] \u2192 snap_pulse \u2192 [more work] \u2192 snap_pulse \u2192 snap_end
 
 WHAT YOU GET BACK (natural language text):
 - Session duration and file count
@@ -48956,8 +49009,8 @@ Example: "add rate limiting to API endpoints"`
           query: {
             type: "string",
             title: "Query",
-            description: `Query the workspace knowledge base for relevant learnings.
-Use this to ask what SnapBack knows about a topic before implementing it.
+            description: `Retrieve relevant learnings from the knowledge base. Read-only \u2014 does not store anything. To write a new learning, use snap_learn instead.
+
 Results are returned from BM25 search over captured learnings.
 
 Example: "What should I know before changing the auth middleware?"
@@ -48992,10 +49045,15 @@ var init_v2 = __esm2({
       snapbackPulseTool
     ];
     V2_HANDLERS = {
+      // Legacy keys (internal routing, backward compat)
       snapback: handleSnapback,
       snapback_learn: handleSnapbackLearn,
       snapback_end: handleSnapbackEnd,
-      snap_pulse: handleSnapbackPulse
+      snap_pulse: handleSnapbackPulse,
+      // Canonical keys — must match SnapBackTool.name for ToolRegistry dispatch
+      snap_begin: handleSnapback,
+      snap_learn: handleSnapbackLearn,
+      snap_end: handleSnapbackEnd
     };
   }
 });
@@ -50932,7 +50990,7 @@ var init_evolution_detector_service = __esm2({
   }
 });
 async function getGitDiffFiles2(workspacePath, scope = "staged") {
-  return new Promise((resolve52) => {
+  return new Promise((resolve62) => {
     let args;
     switch (scope) {
       case "staged":
@@ -50978,14 +51036,14 @@ async function getGitDiffFiles2(workspacePath, scope = "staged") {
     });
     proc.on("close", (code) => {
       if (code !== 0) {
-        resolve52([]);
+        resolve62([]);
         return;
       }
       const files = stdout.split("\n").map((f) => f.trim()).filter((f) => f.length > 0).filter((f) => /\.(ts|tsx|js|jsx)$/.test(f));
-      resolve52(files);
+      resolve62(files);
     });
     proc.on("error", () => {
-      resolve52([]);
+      resolve62([]);
     });
   });
 }
@@ -51019,7 +51077,7 @@ var init_file_selector = __esm2({
 });
 function runCommand22(cmd, args, cwd, timeoutMs = 3e4) {
   const start = Date.now();
-  return new Promise((resolve52) => {
+  return new Promise((resolve62) => {
     let stdout = "";
     let stderr = "";
     let killed = false;
@@ -51044,7 +51102,7 @@ function runCommand22(cmd, args, cwd, timeoutMs = 3e4) {
     });
     proc.on("close", (code) => {
       clearTimeout(timeout);
-      resolve52({
+      resolve62({
         exitCode: killed ? -1 : code ?? 0,
         stdout,
         stderr,
@@ -51053,7 +51111,7 @@ function runCommand22(cmd, args, cwd, timeoutMs = 3e4) {
     });
     proc.on("error", (err22) => {
       clearTimeout(timeout);
-      resolve52({
+      resolve62({
         exitCode: -1,
         stdout,
         stderr: err22.message,
@@ -51835,7 +51893,7 @@ var init_validation2 = __esm2({
         }
       }
       async runMadgeCircular(workspacePath) {
-        return new Promise((resolve52) => {
+        return new Promise((resolve62) => {
           const madgePath = join(workspacePath, "node_modules", ".bin", "madge");
           const hasLocalMadge = existsSync(madgePath);
           const args = [
@@ -51864,16 +51922,16 @@ var init_validation2 = __esm2({
             try {
               const result7 = JSON.parse(stdout);
               if (Array.isArray(result7)) {
-                resolve52(result7);
+                resolve62(result7);
               } else {
-                resolve52([]);
+                resolve62([]);
               }
             } catch {
-              resolve52([]);
+              resolve62([]);
             }
           });
           proc.on("error", () => {
-            resolve52([]);
+            resolve62([]);
           });
         });
       }
@@ -51940,7 +51998,7 @@ var init_validation2 = __esm2({
         };
       }
       async checkToolAvailability(tool, args) {
-        return new Promise((resolve52) => {
+        return new Promise((resolve62) => {
           const startTime = Date.now();
           const proc = spawn("npx", [
             tool,
@@ -51954,13 +52012,13 @@ var init_validation2 = __esm2({
             timeout: 5e3
           });
           proc.on("close", (code) => {
-            resolve52({
+            resolve62({
               healthy: code === 0,
               latency: Date.now() - startTime
             });
           });
           proc.on("error", () => {
-            resolve52({
+            resolve62({
               healthy: false,
               latency: Date.now() - startTime
             });
@@ -51997,7 +52055,7 @@ var init_validation2 = __esm2({
         }
       }
       async runMadgeOrphans(workspacePath) {
-        return new Promise((resolve52) => {
+        return new Promise((resolve62) => {
           const madgePath = join(workspacePath, "node_modules", ".bin", "madge");
           const hasLocalMadge = existsSync(madgePath);
           const args = [
@@ -52026,16 +52084,16 @@ var init_validation2 = __esm2({
             try {
               const result7 = JSON.parse(stdout);
               if (Array.isArray(result7)) {
-                resolve52(result7);
+                resolve62(result7);
               } else {
-                resolve52([]);
+                resolve62([]);
               }
             } catch {
-              resolve52([]);
+              resolve62([]);
             }
           });
           proc.on("error", () => {
-            resolve52([]);
+            resolve62([]);
           });
         });
       }
@@ -52095,7 +52153,7 @@ var init_validation2 = __esm2({
         return diagnostics;
       }
       async runTypeScriptCheck(workspacePath, _files) {
-        return new Promise((resolve52) => {
+        return new Promise((resolve62) => {
           const diagnostics = [];
           const tscPath = join(workspacePath, "node_modules", ".bin", "tsc");
           const hasLocalTsc = existsSync(tscPath);
@@ -52138,19 +52196,19 @@ var init_validation2 = __esm2({
                 });
               }
             }
-            resolve52({
+            resolve62({
               diagnostics
             });
           });
           proc.on("error", () => {
-            resolve52({
+            resolve62({
               diagnostics: []
             });
           });
         });
       }
       async runLintCheck(workspacePath, files, fix = false) {
-        return new Promise((resolve52) => {
+        return new Promise((resolve62) => {
           const diagnostics = [];
           const biomePath = join(workspacePath, "node_modules", ".bin", "biome");
           const hasLocalBiome = existsSync(biomePath);
@@ -52192,19 +52250,19 @@ var init_validation2 = __esm2({
                 });
               }
             }
-            resolve52({
+            resolve62({
               diagnostics
             });
           });
           proc.on("error", () => {
-            resolve52({
+            resolve62({
               diagnostics: []
             });
           });
         });
       }
       async runBuildCommand(workspacePath) {
-        return new Promise((resolve52) => {
+        return new Promise((resolve62) => {
           const proc = spawn("npm", [
             "run",
             "build"
@@ -52234,13 +52292,13 @@ var init_validation2 = __esm2({
                 }
               }
             }
-            resolve52({
+            resolve62({
               success: code === 0,
               diagnostics
             });
           });
           proc.on("error", () => {
-            resolve52({
+            resolve62({
               success: false,
               diagnostics: []
             });
@@ -52550,7 +52608,7 @@ __export2(check_exports, {
 async function detectGitConflicts(workspaceRoot) {
   const { spawn: spawn62 } = await import('child_process');
   const { access: access22 } = await import('fs/promises');
-  const conflictedFiles = await new Promise((resolve52) => {
+  const conflictedFiles = await new Promise((resolve62) => {
     const proc = spawn62("git", [
       "diff",
       "--name-only",
@@ -52569,9 +52627,9 @@ async function detectGitConflicts(workspaceRoot) {
     });
     proc.on("close", () => {
       const files = stdout.split("\n").map((f) => f.trim()).filter((f) => f.length > 0);
-      resolve52(files);
+      resolve62(files);
     });
-    proc.on("error", () => resolve52([]));
+    proc.on("error", () => resolve62([]));
   });
   let source = "unknown";
   try {
@@ -52601,7 +52659,7 @@ async function detectGitConflicts(workspaceRoot) {
 __name(detectGitConflicts, "detectGitConflicts");
 async function getGitDiffFiles22(workspaceRoot, scope = "staged") {
   const { spawn: spawn62 } = await import('child_process');
-  return new Promise((resolve52) => {
+  return new Promise((resolve62) => {
     let args;
     switch (scope) {
       case "staged":
@@ -52647,13 +52705,13 @@ async function getGitDiffFiles22(workspaceRoot, scope = "staged") {
     });
     proc.on("close", (code) => {
       if (code !== 0) {
-        resolve52([]);
+        resolve62([]);
         return;
       }
       const files = stdout.split("\n").map((f) => f.trim()).filter((f) => f.length > 0).filter((f) => /\.(ts|tsx|js|jsx)$/.test(f));
-      resolve52(files);
+      resolve62(files);
     });
-    proc.on("error", () => resolve52([]));
+    proc.on("error", () => resolve62([]));
   });
 }
 __name(getGitDiffFiles22, "getGitDiffFiles2");
@@ -56627,6 +56685,9 @@ function buildWireFields(response) {
       fields.next = actionsStr;
     }
   }
+  if (response.open_session_reminder) {
+    fields.reminder = response.open_session_reminder;
+  }
   return fields;
 }
 __name(buildWireFields, "buildWireFields");
@@ -56671,6 +56732,9 @@ function formatWireCompact(response) {
       break;
     }
   }
+  if (response.open_session_reminder) {
+    parts.push(`reminder:${compress2(response.open_session_reminder, 40)}`);
+  }
   return parts.join("|");
 }
 __name(formatWireCompact, "formatWireCompact");
@@ -56975,9 +57039,10 @@ async function handleStart(normalized, context) {
     } else {
       return result7;
     }
-    const snapshotStatus = data.snapshot?.created ? "created" : data.snapshot?.id ? "reused" : "skipped";
+    const snapshotStatus = data.snapshot?.created ? "created" : data.snapshot?.id || data.snapshotIds && data.snapshotIds.length > 0 ? "reused" : "skipped";
     const integrationEnrichment = await getIntegrationEnrichment(normalized.files || [], context);
-    const riskLevel = (data.risk?.[0] || "l").toUpperCase();
+    const rawRisk = data.risk?.[0] || data.riskAssessment?.overallRisk || "l";
+    const riskLevel = rawRisk[0].toUpperCase();
     const warningCount = data.hotspots?.reduce((sum, h) => sum + h.violations, 0) || 0;
     const nextActions = generateNextActions2({
       risk: riskLevel,
@@ -57627,7 +57692,7 @@ function identifyImprovements(data, params) {
       priority: "medium"
     });
   }
-  if (params.ok === 0 || params.outcome === "abandoned" || params.outcome === "blocked") {
+  if (params.ok === 0) {
     improvements.push({
       suggestion: "Capture specific blocker as pitfall learning",
       trigger: "Task did not complete successfully",
@@ -57802,6 +57867,18 @@ var init_session_reporter = __esm2({
     __name12(suggestNextSteps, "suggestNextSteps");
   }
 });
+function normalizeOutcome(outcome, ok22) {
+  if (!outcome) return ok22 === 0 || ok22 === false ? "abandoned" : "completed";
+  const lower = outcome.toLowerCase().trim();
+  if (lower === "completed" || lower === "success") return "completed";
+  if (lower === "abandoned" || lower === "cancelled" || lower === "canceled") return "abandoned";
+  if (lower === "blocked" || lower === "failed" || lower === "failure" || lower === "error") return "blocked";
+  if (/\bcomplet|\bfinish|\bdone|\bsuccess/.test(lower)) return "completed";
+  if (/\babandon|\bcancel|\bgave up|\bgive up|\bscrapped/.test(lower)) return "abandoned";
+  if (/\bblock|\bfail|\bstuck|\bbroken|\berror/.test(lower)) return "blocked";
+  return ok22 === 0 || ok22 === false ? "abandoned" : "completed";
+}
+__name(normalizeOutcome, "normalizeOutcome");
 function formatUserStats(metrics) {
   const parts = [];
   if (metrics.saved !== "not reported") parts.push(`\u{1F4B0} ${metrics.saved} tokens saved`);
@@ -57832,6 +57909,7 @@ var init_snap_end = __esm2({
       const clean = s.replace(/\s+/g, "\u2192");
       return clean.length > max ? `${clean.slice(0, max - 1)}\u2026` : clean;
     }, "compressStr");
+    __name12(normalizeOutcome, "normalizeOutcome");
     handleSnapEnd = /* @__PURE__ */ __name12(async (args, context) => {
       const validation = validateSnapEndParams(args);
       if (!validation.success) {
@@ -57857,7 +57935,7 @@ ${validation.errors?.join("\n") ?? "Unknown validation error"}`
       let suggestedCeremony = null;
       let ceremonySuggestionReason = "";
       let ceremonySuggestionConfidence = 0;
-      const isCleanCompletion = params.outcome === "completed" || params.ok === 1;
+      const isCleanCompletion = normalizeOutcome(params.outcome, params.ok) === "completed" || params.ok === 1;
       if (!params.ceremony && context.workspaceRoot && !isCleanCompletion) {
         const sessionState = await getSessionStateAsync(context.workspaceRoot);
         if (sessionState) {
@@ -58009,9 +58087,9 @@ ${ceremonyOutput}
         }
       }
       const completeArgs = {
-        outcome: params.outcome || (params.ok === 0 ? "abandoned" : "completed"),
+        outcome: normalizeOutcome(params.outcome, params.ok),
         createSnapshot: true,
-        notes: params.notes
+        notes: params.notes ?? params.outcome
       };
       completeArgs.learningsCaptured = directLearningsPersisted;
       const result7 = await handleCompleteTask(completeArgs, context);
@@ -59912,7 +59990,7 @@ var MCP_ROUTES = {
     }
   }
   delay(ms) {
-    return new Promise((resolve52) => setTimeout(resolve52, ms));
+    return new Promise((resolve62) => setTimeout(resolve62, ms));
   }
   /**
   * Get circuit breaker state for monitoring
@@ -59961,7 +60039,7 @@ var BridgeReceiver = class {
       console.error("[BridgeReceiver] Already running");
       return;
     }
-    return new Promise((resolve52, reject) => {
+    return new Promise((resolve62, reject) => {
       this.server = createServer((req, res) => this.handleRequest(req, res));
       this.server.on("error", (err22) => {
         console.error("[BridgeReceiver] Server error:", err22);
@@ -59969,7 +60047,7 @@ var BridgeReceiver = class {
       });
       this.server.listen(this.port, this.host, () => {
         console.error(`[BridgeReceiver] Listening on http://${this.host}:${this.port}`);
-        resolve52();
+        resolve62();
       });
     });
   }
@@ -59980,11 +60058,11 @@ var BridgeReceiver = class {
     if (!this.server) {
       return;
     }
-    return new Promise((resolve52) => {
+    return new Promise((resolve62) => {
       this.server?.close(() => {
         console.error("[BridgeReceiver] Stopped");
         this.server = null;
-        resolve52();
+        resolve62();
       });
     });
   }
@@ -60558,11 +60636,11 @@ var SSELocalTransport = class extends EventEmitter {
         res.end("Not Found");
       }
     });
-    return new Promise((resolve52, reject) => {
+    return new Promise((resolve62, reject) => {
       this.server.listen(this.config.port, () => {
         this.logger.info(`Listening on localhost:${this.config.port}`);
         this.startPingLoop();
-        resolve52();
+        resolve62();
       });
       this.server.on("error", reject);
     });
@@ -60583,13 +60661,13 @@ var SSELocalTransport = class extends EventEmitter {
       this.clients.delete(clientId);
     }
     if (this.server) {
-      return new Promise((resolve52, reject) => {
+      return new Promise((resolve62, reject) => {
         this.server.close((err22) => {
           if (err22) reject(err22);
           else {
             this.server = null;
             this.logger.info("Transport stopped");
-            resolve52();
+            resolve62();
           }
         });
       });
@@ -62379,18 +62457,18 @@ async function createUnifiedServer(options, injectedRegistry) {
       }
     },
     instructions: [
-      "SnapBack MCP \u2014 V2 3-Tool Surface (authoritative, overrides individual descriptions):",
+      "SnapBack MCP \u2014 V2 4-Tool Surface (authoritative, overrides individual descriptions):",
       "",
-      "Workflow: snapback \u2192 [work] \u2192 snapback_learn (optional) \u2192 snapback_end.",
+      "Workflow: snap_begin \u2192 [work] \u2192 snap_learn (optional) \u2192 snap_end.",
       "",
       "Tool Usage:",
-      "  1. Call snapback FIRST before any code changes \u2014 returns intelligence briefing",
-      "  2. Call snapback_learn when you discover something worth remembering",
-      "  3. Call snapback_end when task is complete \u2014 returns session summary",
+      "  1. Call snap_begin FIRST before any code changes \u2014 returns intelligence briefing",
+      "  2. Call snap_learn when you discover something worth remembering",
+      "  3. Call snap_end when task is complete \u2014 returns session summary",
       "",
       "Key Points:",
-      "  - snapback is idempotent \u2014 calling twice resumes the same session",
-      "  - snapback_learn creates implicit session if needed",
+      "  - snap_begin is idempotent \u2014 calling twice resumes the same session",
+      "  - snap_learn creates implicit session if needed",
       "  - All files are automatically protected \u2014 no manual snapshot needed",
       "  - Workspace isolation: learnings and context are scoped to this workspace"
     ].join("\n")
@@ -62703,7 +62781,7 @@ ${learning.action}`,
         logSuccess(reqCtx, "Tool call completed", {
           isError: toolResult.isError
         });
-        const shouldEnrich = name !== "meta" && name !== "snapback_end";
+        const shouldEnrich = name !== "meta" && name !== "snap_end";
         const enhanced = shouldEnrich ? await vitalsEnricher.enhance(toolResult, workspaceRoot, eventTracker) : toolResult;
         const enrichedContent = (enhanced.content || []).map((c) => ({
           type: "text",
@@ -62732,6 +62810,19 @@ ${warningsText}${humanPart}`;
             }
           }
         }
+        if (enhanced.isError && name !== "snap_learn" && name !== "snap_end") {
+          const firstContent = enrichedContent[0];
+          if (firstContent && typeof firstContent.text === "string") {
+            const learningHint = [
+              "",
+              "\u{1F4A1} SUGGESTED_LEARNING: This tool call failed. Consider capturing the failure pattern:",
+              `  snap_learn({ type: "pitfall", trigger: "${name} error", action: "..." })`,
+              "  (Replace '...' with the specific insight from this failure)",
+              ""
+            ].join("\n");
+            firstContent.text = `${firstContent.text}${learningHint}`;
+          }
+        }
         return {
           content: enrichedContent,
           isError: enhanced.isError
@@ -64235,7 +64326,7 @@ async function autoConfigureTools(options) {
   if (detection.detected.length === 0) {
     if (!jsonOutput) {
       console.log(chalk37.yellow("\nNo AI tools detected"));
-      console.log(chalk37.gray("Install one of these to use SnapBack MCP:"));
+      console.log(chalk37.gray("Install one of these to use \u{1F9E2} SnapBack MCP:"));
       console.log(chalk37.gray("  \u2022 Claude Desktop - https://claude.ai/download"));
       console.log(chalk37.gray("  \u2022 Cursor - https://cursor.sh"));
       console.log(chalk37.gray("  \u2022 Windsurf - https://codeium.com/windsurf"));
@@ -64252,7 +64343,7 @@ async function autoConfigureTools(options) {
   }
   if (needsSetup.length === 0) {
     if (!jsonOutput) {
-      console.log(chalk37.green("\n\u2713 All detected AI tools already have SnapBack configured!"));
+      console.log(chalk37.green("\n\u2713 All detected AI tools already have \u{1F9E2} SnapBack configured!"));
       console.log(chalk37.gray("Use --force to reconfigure."));
       showNextSteps();
     }
@@ -64270,7 +64361,7 @@ Detected ${detection.detected.length} AI tool(s):`));
   if (!skipPrompts && !jsonOutput) {
     const clientNames = needsSetup.map((c) => c.displayName).join(", ");
     const proceed = await confirm({
-      message: `Configure SnapBack for ${clientNames}?`,
+      message: `Configure \u{1F9E2} SnapBack for ${clientNames}?`,
       default: true
     });
     if (!proceed) {
@@ -64326,17 +64417,29 @@ async function configureClient(client2, dryRun, apiKey, devMode = false, npmMode
   try {
     const workspaceRoot = workspaceOverride || findWorkspaceRoot3(process.cwd());
     const workspaceConfig = detectWorkspaceConfig(workspaceRoot);
+    let localCliPath;
     if (workspaceConfig && isGlobalConfig(client2.configPath)) {
-      spinner2.info(`${client2.displayName} workspace config detected`);
-      console.log(chalk37.gray(`  Workspace: ${workspaceConfig.path}`));
-      console.log(chalk37.gray(`  Type: ${workspaceConfig.type}`));
-      console.log();
-      console.log(chalk37.cyan("  Skipping global config to prevent conflicts"));
-      console.log(chalk37.gray("  Workspace configurations take precedence over global"));
-      console.log();
-      return;
+      if (client2.format === "qoder" && client2.hasSnapback) {
+        const existingValidation = validateClientConfig(client2);
+        if (existingValidation.valid) {
+          spinner2.info(`${client2.displayName} workspace config detected (global config valid, skipping)`);
+          return;
+        }
+        spinner2.text = `Repairing broken global ${client2.displayName} config...`;
+        devMode = false;
+        npmMode = false;
+        localCliPath = void 0;
+      } else {
+        spinner2.info(`${client2.displayName} workspace config detected`);
+        console.log(chalk37.gray(`  Workspace: ${workspaceConfig.path}`));
+        console.log(chalk37.gray(`  Type: ${workspaceConfig.type}`));
+        console.log();
+        console.log(chalk37.cyan("  Skipping global config to prevent conflicts"));
+        console.log(chalk37.gray("  Workspace configurations take precedence over global"));
+        console.log();
+        return;
+      }
     }
-    let localCliPath;
     if (devMode) {
       localCliPath = findCliDistPath(workspaceRoot);
       if (!localCliPath) {
@@ -64426,12 +64529,24 @@ async function configureClientWithResult(client2, dryRun, apiKey, devMode = fals
   try {
     const workspaceRoot = workspaceOverride || findWorkspaceRoot3(process.cwd());
     const workspaceConfig = detectWorkspaceConfig(workspaceRoot);
+    let localCliPath;
     if (workspaceConfig && isGlobalConfig(client2.configPath)) {
-      return {
-        success: true
-      };
+      if (client2.format === "qoder" && client2.hasSnapback) {
+        const existingValidation = validateClientConfig(client2);
+        if (existingValidation.valid) {
+          return {
+            success: true
+          };
+        }
+        devMode = false;
+        npmMode = false;
+        localCliPath = void 0;
+      } else {
+        return {
+          success: true
+        };
+      }
     }
-    let localCliPath;
     if (devMode) {
       localCliPath = findCliDistPath(workspaceRoot);
       if (!localCliPath) {
@@ -64526,7 +64641,7 @@ async function resolveApiKey(providedApiKey, skipPrompts = false) {
   }
   if (!skipPrompts) {
     const wantApiKey = await confirm({
-      message: "Do you have a SnapBack API key for Pro features?",
+      message: "Do you have a \u{1F9E2} SnapBack API key for Pro features?",
       default: false
     });
     if (wantApiKey) {
@@ -64606,7 +64721,7 @@ async function validateTools(verbose = false) {
   const detection = detectAIClients();
   const configured = detection.detected.filter((c) => c.hasSnapback);
   if (configured.length === 0) {
-    console.log(chalk37.yellow("\nNo AI tools with SnapBack configured."));
+    console.log(chalk37.yellow("\nNo AI tools with \u{1F9E2} SnapBack configured."));
     console.log(chalk37.gray("Run: snap tools configure"));
     return;
   }
@@ -64658,7 +64773,7 @@ async function repairTools(skipPrompts = false, workspaceOverride, providedApiKe
   const detection = detectAIClients();
   const configured = detection.detected.filter((c) => c.hasSnapback);
   if (configured.length === 0) {
-    console.log(chalk37.yellow("\nNo AI tools with SnapBack configured."));
+    console.log(chalk37.yellow("\nNo AI tools with \u{1F9E2} SnapBack configured."));
     console.log(chalk37.gray("Run: snap tools configure"));
     return;
   }
@@ -64739,8 +64854,8 @@ function showNextSteps() {
   console.log(chalk37.bold("Next Steps:"));
   console.log();
   console.log("  1. Restart your AI assistant (Claude Desktop, Cursor, etc.)");
-  console.log('  2. Ask your AI: "What does SnapBack know about this project?"');
-  console.log('  3. Before risky changes, ask: "Create a SnapBack checkpoint"');
+  console.log('  2. Ask your AI: "What does \u{1F9E2} SnapBack know about this project?"');
+  console.log('  3. Before risky changes, ask: "Create a \u{1F9E2} SnapBack checkpoint"');
   console.log();
   console.log(chalk37.dim("Available tools your AI can now use:"));
   console.log(chalk37.dim("  \u2022 snapback.get_context      - Understand your codebase"));
@@ -66194,13 +66309,13 @@ async function addAgentToConfig(configPath, agentName, agentConfig) {
 __name(addAgentToConfig, "addAgentToConfig");
 var acpCommand = createAcpCommand();
 function registerDaemonCommands(program) {
-  const daemon = program.command("daemon").description("Manage SnapBack daemon");
-  daemon.command("start").description("Start the SnapBack daemon").option("--no-detach", "Run daemon in foreground (attached to terminal)").option("-f, --foreground", "Same as --no-detach").option("-t, --idle-timeout <minutes>", "Shutdown after idle (default: 240)", "240").action(async (options) => {
+  const daemon = program.command("daemon").description("Manage \u{1F9E2} SnapBack daemon");
+  daemon.command("start").description("Start the \u{1F9E2} SnapBack daemon").option("--no-detach", "Run daemon in foreground (attached to terminal)").option("-f, --foreground", "Same as --no-detach").option("-t, --idle-timeout <minutes>", "Shutdown after idle (default: 240)", "240").action(async (options) => {
     if (isServiceRunning()) {
       console.log("\u2713 Daemon is already running");
       return;
     }
-    console.log("Starting SnapBack daemon...");
+    console.log("Starting \u{1F9E2} SnapBack daemon...");
     const snapbackdArgs = [
       "--idle-timeout",
       options.idleTimeout
@@ -66307,7 +66422,7 @@ function registerDaemonCommands(program) {
       child.on("error", reject);
     });
   });
-  daemon.command("stop").description("Stop the SnapBack daemon").action(async () => {
+  daemon.command("stop").description("Stop the \u{1F9E2} SnapBack daemon").action(async () => {
     if (!isServiceRunning()) {
       console.log("Daemon is not running");
       return;
@@ -67702,7 +67817,7 @@ function formatValue(value) {
   return String(value);
 }
 __name(formatValue, "formatValue");
-var cliVersion2 = "1.1.15" ;
+var cliVersion2 = "3.0.0" ;
 function createDoctorCommand() {
   return new Command("doctor").description("Diagnose SnapBack installation and ecosystem health").option("--json", "Output structured JSON result").option("--local", "Skip network checks").option("--check <system>", "Check specific subsystem (cli|daemon|workspace|knowledge|mcp|network|extension)").option("--fix", "Attempt automatic repair for known issues").option("-q, --quiet", "Only show failures").option("-v, --verbose", "Show all check details").action(async (options) => {
     const result7 = await runDoctor(options);
@@ -67721,7 +67836,7 @@ async function runDoctor(options) {
   const workspacePath = findWorkspaceRoot2(process.cwd());
   if (!jsonMode) {
     console.log();
-    console.log(chalk37.cyan(`  SnapBack Doctor v${cliVersion2}`));
+    console.log(chalk37.cyan(`  \u{1F9E2} SnapBack Doctor v${cliVersion2}`));
     console.log(chalk37.gray(`  Platform: ${platformLabel()}, Node ${process.version}`));
     console.log();
   }
@@ -67794,9 +67909,9 @@ async function runDoctor(options) {
   if (!jsonMode) {
     console.log(chalk37.gray(`  Summary: ${summary.pass} passed, ${summary.warn} warning${summary.warn !== 1 ? "s" : ""}, ${summary.fail} failure${summary.fail !== 1 ? "s" : ""}`));
     if (success) {
-      console.log(chalk37.green("  \u2714 SnapBack is healthy"));
+      console.log(chalk37.green("  \u2714 \u{1F9E2} SnapBack is healthy"));
     } else {
-      console.log(chalk37.red("  \u2716 SnapBack has issues \u2014 run the suggested fixes above"));
+      console.log(chalk37.red("  \u2716 \u{1F9E2} SnapBack has issues \u2014 run the suggested fixes above"));
     }
     console.log();
   }
@@ -68730,7 +68845,7 @@ Latest:  v${versionInfo.latest}`,
 }
 __name(createUpgradeCommand, "createUpgradeCommand");
 async function getVersionInfo(canary = false) {
-  const current = "1.1.15";
+  const current = "3.0.0";
   let latest = current;
   try {
     const tag = canary ? "canary" : "latest";
@@ -68990,6 +69105,59 @@ ${chalk37.dim("Learn more: https://docs.snapback.dev")}
 __name(displayWelcomeMessage, "displayWelcomeMessage");
 
 // src/commands/wizard.ts
+var SNAPBACK_AI_INSTRUCTIONS = `## SnapBack Intelligence
+
+Always call \`snap_begin\` before any coding task. It opens a session and returns
+codebase intelligence (fragile files, co-change patterns, past learnings) that
+your context window does not have. Without it: no session tracking, no automatic
+snapshots, snap_pulse and snap_end return empty results.
+
+### Tool Sequence
+1. **snap_begin** \u2190 Always first, before file reads or any other tool
+2. [your work tools]
+3. **snap_pulse** \u2190 After 3+ tool calls, when uncertain, before clarifying questions
+4. **snap_learn** \u2190 When user corrects you, or you discover unexpected codebase patterns
+5. **snap_end** \u2190 After task completion, before your final message
+
+### Without snap_begin
+- No session = no automatic snapshots
+- No intelligence context = blind to codebase risks
+- snap_pulse and snap_end return empty results
+`;
+function writeWorkspaceAIInstructions(workspaceRoot) {
+  const targets = [
+    {
+      file: "CLAUDE.md",
+      header: "## SnapBack Intelligence"
+    },
+    {
+      file: ".cursorrules",
+      header: "## SnapBack Intelligence"
+    },
+    {
+      file: ".windsurfrules",
+      header: "## SnapBack Intelligence"
+    }
+  ];
+  for (const { file, header } of targets) {
+    const filePath = path10.join(workspaceRoot, file);
+    try {
+      if (fs32.existsSync(filePath)) {
+        const existing = fs32.readFileSync(filePath, "utf-8");
+        if (existing.includes(header)) continue;
+        fs32.appendFileSync(filePath, `
+
+${SNAPBACK_AI_INSTRUCTIONS}`, "utf-8");
+      } else {
+        fs32.writeFileSync(filePath, SNAPBACK_AI_INSTRUCTIONS, "utf-8");
+      }
+      process.stdout.write(chalk37.gray(`    ${file} written \u2713
+`));
+    } catch {
+    }
+  }
+}
+__name(writeWorkspaceAIInstructions, "writeWorkspaceAIInstructions");
 function detectProjectType(cwd) {
   const indicators = [];
   let type = "unknown";
@@ -69281,7 +69449,7 @@ ${chalk37.cyan.bold("Step 4: AI Tool Integration\n")}`);
   let getSnapbackMCPConfig2;
   let writeClientConfig2;
   try {
-    const mcpConfig = await import('./dist-TEWNOZYS.js');
+    const mcpConfig = await import('./dist-5LR7APG5.js');
     detectAIClients2 = mcpConfig.detectAIClients;
     getSnapbackMCPConfig2 = mcpConfig.getSnapbackMCPConfig;
     writeClientConfig2 = mcpConfig.writeClientConfig;
@@ -69354,6 +69522,9 @@ ${chalk37.cyan.bold("Step 4: AI Tool Integration\n")}`);
         console.log(chalk37.red(` \u2717 ${result7.error}`));
       }
     }
+    if (state.workspaceRoot) {
+      writeWorkspaceAIInstructions(state.workspaceRoot);
+    }
     console.log();
     status.success("MCP integration configured!");
     console.log(chalk37.gray("  Restart your AI tools to activate SnapBack."));
@@ -69644,7 +69815,7 @@ ${chalk37.green.bold("Setup Complete! \u{1F389}\n")}`);
   console.log(`
 ${chalk37.cyan.bold("Quick Health Check:\n")}`);
   try {
-    const { detectAIClients: detectAIClients2 } = await import('./dist-TEWNOZYS.js');
+    const { detectAIClients: detectAIClients2 } = await import('./dist-5LR7APG5.js');
     const detection = detectAIClients2({
       cwd: state.workspaceRoot || process.cwd()
     });
@@ -69659,7 +69830,7 @@ ${chalk37.cyan.bold("Quick Health Check:\n")}`);
   } catch {
   }
   try {
-    const { detectAIClients: detectAIClients2 } = await import('./dist-TEWNOZYS.js');
+    const { detectAIClients: detectAIClients2 } = await import('./dist-5LR7APG5.js');
     const detection = detectAIClients2({
       cwd: state.workspaceRoot || process.cwd()
     });