@wazir-dev/cli 1.1.0 → 1.2.0

package/exports/hosts/codex/export.manifest.json

@@ -1,7 +1,7 @@
 {
   "host": "codex",
   "source_hashes": {
-    "wazir.manifest.yaml": "ae49e943639828932d5289f34f2994f1efb67df4f552f5bfabbb1c823b662e43",
+    "wazir.manifest.yaml": "f00776eb08ed3332b8f855001a2fd0b866cd0b81d009c6fbb316149c398c51ca",
     "roles/clarifier.md": "1e1b8a2c05f1070fdcef485963cfcbffff62c4b2703a8d73fe51ac52d056e573",
     "roles/content-author.md": "cc20b80bd70ab68b3239a9cf56bf1ffc2c06843d38afc6b190844b35a1d73c3e",
     "roles/designer.md": "76cff5bda82975cfb4074de71681e7c8ba284e2e49d0cc98f90208642fef74fc",
@@ -27,12 +27,14 @@
     "workflows/spec-challenge.md": "dc99137c28c49a6f8312924709afb6077754d128e90466dc911150ce15737897",
     "workflows/specify.md": "53b84e74871f6dbd93cae22a881cc5907e398b29501d0a1fa08c7ed69df705cb",
     "workflows/verify.md": "45f9c189520dfe9d24c0bc340a15e6a80c988fca1b84dc187627032a6dbaee16",
+    "hooks/definitions/context_mode_router.yaml": "a10dc927418bc130b447eb33faf0f45669ecd9c7917f56947ddd74850a4e0e37",
     "hooks/definitions/loop_cap_guard.yaml": "f0fd220e028ab6fad3d8fd650602884fe500ca4899eff6e428cf217af058618d",
     "hooks/definitions/post_tool_capture.yaml": "a773cd6e18972dee8eef3b7cb06fd1d319a71de4588897cebfbe643f6781a3b2",
     "hooks/definitions/pre_compact_summary.yaml": "daa0175d79f3e0127c5ce86a7a2f8df0be3f58b5c94fe749da715a17c7b2d04e",
     "hooks/definitions/pre_tool_capture_route.yaml": "3c2663380ff3cd09f09de5b96bcf6123266fa74d8a03dfb2d6fbe40a43fb13cf",
     "hooks/definitions/protected_path_write_guard.yaml": "6683d41778b823e2a4e606065597569aa04363f091e135e165de9732f1fc2171",
     "hooks/definitions/session_start.yaml": "9383fcf1f8304c87e57726478a461706c0fc73dc62bcc4d8661f2eeffa43a82d",
-    "hooks/definitions/stop_handoff_harvest.yaml": "67a3c0a8bb7cb66b88e77dc79e748082e964d278c47935662c453922a846482b"
+    "hooks/definitions/stop_handoff_harvest.yaml": "67a3c0a8bb7cb66b88e77dc79e748082e964d278c47935662c453922a846482b",
+    "hooks/hooks.json": "f255345793951b5cf6f6d8c9a8b6a6ad2d3140023453410127a6f70d8e110c26"
   }
 }

package/exports/hosts/codex/host-package.json

@@ -27,13 +27,15 @@
     "workflows/spec-challenge.md",
     "workflows/specify.md",
     "workflows/verify.md",
+    "hooks/definitions/context_mode_router.yaml",
     "hooks/definitions/loop_cap_guard.yaml",
     "hooks/definitions/post_tool_capture.yaml",
     "hooks/definitions/pre_compact_summary.yaml",
     "hooks/definitions/pre_tool_capture_route.yaml",
     "hooks/definitions/protected_path_write_guard.yaml",
     "hooks/definitions/session_start.yaml",
-    "hooks/definitions/stop_handoff_harvest.yaml"
+    "hooks/definitions/stop_handoff_harvest.yaml",
+    "hooks/hooks.json"
   ],
   "files": [
     "AGENTS.md"

package/exports/hosts/cursor/.cursor/hooks.json

@@ -8,6 +8,10 @@
       "name": "loop-cap-guard",
       "command": "./hooks/loop-cap-guard"
     },
+    {
+      "name": "context-mode-router",
+      "command": "./hooks/context-mode-router"
+    },
     {
       "name": "session-start",
       "command": "./hooks/session-start"

package/exports/hosts/cursor/.cursor/rules/wazir-core.mdc

@@ -6,7 +6,7 @@ This host package is generated from the canonical Wazir sources.
 
 - project: Wazir
 - hosts: claude, codex, gemini, cursor
-- phases: clarify, discover, specify, spec_challenge, author, design, design_review, plan, plan_review, execute, verify, review, learn, prepare_next
+- phases: init, clarifier, executor, final_review
 - roles: clarifier, researcher, specifier, content-author, designer, planner, executor, verifier, reviewer, learner
 - protected paths: input, roles, workflows, schemas, exports/hosts
 - state root default: ~/.wazir/projects/{project_slug}

package/exports/hosts/cursor/export.manifest.json

@@ -1,7 +1,7 @@
 {
   "host": "cursor",
   "source_hashes": {
-    "wazir.manifest.yaml": "ae49e943639828932d5289f34f2994f1efb67df4f552f5bfabbb1c823b662e43",
+    "wazir.manifest.yaml": "f00776eb08ed3332b8f855001a2fd0b866cd0b81d009c6fbb316149c398c51ca",
     "roles/clarifier.md": "1e1b8a2c05f1070fdcef485963cfcbffff62c4b2703a8d73fe51ac52d056e573",
     "roles/content-author.md": "cc20b80bd70ab68b3239a9cf56bf1ffc2c06843d38afc6b190844b35a1d73c3e",
     "roles/designer.md": "76cff5bda82975cfb4074de71681e7c8ba284e2e49d0cc98f90208642fef74fc",
@@ -27,12 +27,14 @@
     "workflows/spec-challenge.md": "dc99137c28c49a6f8312924709afb6077754d128e90466dc911150ce15737897",
     "workflows/specify.md": "53b84e74871f6dbd93cae22a881cc5907e398b29501d0a1fa08c7ed69df705cb",
     "workflows/verify.md": "45f9c189520dfe9d24c0bc340a15e6a80c988fca1b84dc187627032a6dbaee16",
+    "hooks/definitions/context_mode_router.yaml": "a10dc927418bc130b447eb33faf0f45669ecd9c7917f56947ddd74850a4e0e37",
     "hooks/definitions/loop_cap_guard.yaml": "f0fd220e028ab6fad3d8fd650602884fe500ca4899eff6e428cf217af058618d",
     "hooks/definitions/post_tool_capture.yaml": "a773cd6e18972dee8eef3b7cb06fd1d319a71de4588897cebfbe643f6781a3b2",
     "hooks/definitions/pre_compact_summary.yaml": "daa0175d79f3e0127c5ce86a7a2f8df0be3f58b5c94fe749da715a17c7b2d04e",
     "hooks/definitions/pre_tool_capture_route.yaml": "3c2663380ff3cd09f09de5b96bcf6123266fa74d8a03dfb2d6fbe40a43fb13cf",
     "hooks/definitions/protected_path_write_guard.yaml": "6683d41778b823e2a4e606065597569aa04363f091e135e165de9732f1fc2171",
     "hooks/definitions/session_start.yaml": "9383fcf1f8304c87e57726478a461706c0fc73dc62bcc4d8661f2eeffa43a82d",
-    "hooks/definitions/stop_handoff_harvest.yaml": "67a3c0a8bb7cb66b88e77dc79e748082e964d278c47935662c453922a846482b"
+    "hooks/definitions/stop_handoff_harvest.yaml": "67a3c0a8bb7cb66b88e77dc79e748082e964d278c47935662c453922a846482b",
+    "hooks/hooks.json": "f255345793951b5cf6f6d8c9a8b6a6ad2d3140023453410127a6f70d8e110c26"
   }
 }

package/exports/hosts/cursor/host-package.json

@@ -27,13 +27,15 @@
     "workflows/spec-challenge.md",
     "workflows/specify.md",
     "workflows/verify.md",
+    "hooks/definitions/context_mode_router.yaml",
     "hooks/definitions/loop_cap_guard.yaml",
     "hooks/definitions/post_tool_capture.yaml",
     "hooks/definitions/pre_compact_summary.yaml",
     "hooks/definitions/pre_tool_capture_route.yaml",
     "hooks/definitions/protected_path_write_guard.yaml",
     "hooks/definitions/session_start.yaml",
-    "hooks/definitions/stop_handoff_harvest.yaml"
+    "hooks/definitions/stop_handoff_harvest.yaml",
+    "hooks/hooks.json"
   ],
   "files": [
     ".cursor/hooks.json",

package/exports/hosts/gemini/GEMINI.md

@@ -6,7 +6,7 @@ This host package is generated from the canonical Wazir sources.
 
 - project: Wazir
 - hosts: claude, codex, gemini, cursor
-- phases: clarify, discover, specify, spec_challenge, author, design, design_review, plan, plan_review, execute, verify, review, learn, prepare_next
+- phases: init, clarifier, executor, final_review
 - roles: clarifier, researcher, specifier, content-author, designer, planner, executor, verifier, reviewer, learner
 - protected paths: input, roles, workflows, schemas, exports/hosts
 - state root default: ~/.wazir/projects/{project_slug}

package/exports/hosts/gemini/export.manifest.json

@@ -1,7 +1,7 @@
 {
   "host": "gemini",
   "source_hashes": {
-    "wazir.manifest.yaml": "ae49e943639828932d5289f34f2994f1efb67df4f552f5bfabbb1c823b662e43",
+    "wazir.manifest.yaml": "f00776eb08ed3332b8f855001a2fd0b866cd0b81d009c6fbb316149c398c51ca",
     "roles/clarifier.md": "1e1b8a2c05f1070fdcef485963cfcbffff62c4b2703a8d73fe51ac52d056e573",
     "roles/content-author.md": "cc20b80bd70ab68b3239a9cf56bf1ffc2c06843d38afc6b190844b35a1d73c3e",
     "roles/designer.md": "76cff5bda82975cfb4074de71681e7c8ba284e2e49d0cc98f90208642fef74fc",
@@ -27,12 +27,14 @@
     "workflows/spec-challenge.md": "dc99137c28c49a6f8312924709afb6077754d128e90466dc911150ce15737897",
     "workflows/specify.md": "53b84e74871f6dbd93cae22a881cc5907e398b29501d0a1fa08c7ed69df705cb",
     "workflows/verify.md": "45f9c189520dfe9d24c0bc340a15e6a80c988fca1b84dc187627032a6dbaee16",
+    "hooks/definitions/context_mode_router.yaml": "a10dc927418bc130b447eb33faf0f45669ecd9c7917f56947ddd74850a4e0e37",
     "hooks/definitions/loop_cap_guard.yaml": "f0fd220e028ab6fad3d8fd650602884fe500ca4899eff6e428cf217af058618d",
     "hooks/definitions/post_tool_capture.yaml": "a773cd6e18972dee8eef3b7cb06fd1d319a71de4588897cebfbe643f6781a3b2",
     "hooks/definitions/pre_compact_summary.yaml": "daa0175d79f3e0127c5ce86a7a2f8df0be3f58b5c94fe749da715a17c7b2d04e",
     "hooks/definitions/pre_tool_capture_route.yaml": "3c2663380ff3cd09f09de5b96bcf6123266fa74d8a03dfb2d6fbe40a43fb13cf",
     "hooks/definitions/protected_path_write_guard.yaml": "6683d41778b823e2a4e606065597569aa04363f091e135e165de9732f1fc2171",
     "hooks/definitions/session_start.yaml": "9383fcf1f8304c87e57726478a461706c0fc73dc62bcc4d8661f2eeffa43a82d",
-    "hooks/definitions/stop_handoff_harvest.yaml": "67a3c0a8bb7cb66b88e77dc79e748082e964d278c47935662c453922a846482b"
+    "hooks/definitions/stop_handoff_harvest.yaml": "67a3c0a8bb7cb66b88e77dc79e748082e964d278c47935662c453922a846482b",
+    "hooks/hooks.json": "f255345793951b5cf6f6d8c9a8b6a6ad2d3140023453410127a6f70d8e110c26"
   }
 }

package/exports/hosts/gemini/host-package.json

@@ -27,13 +27,15 @@
     "workflows/spec-challenge.md",
     "workflows/specify.md",
     "workflows/verify.md",
+    "hooks/definitions/context_mode_router.yaml",
     "hooks/definitions/loop_cap_guard.yaml",
     "hooks/definitions/post_tool_capture.yaml",
     "hooks/definitions/pre_compact_summary.yaml",
     "hooks/definitions/pre_tool_capture_route.yaml",
     "hooks/definitions/protected_path_write_guard.yaml",
     "hooks/definitions/session_start.yaml",
-    "hooks/definitions/stop_handoff_harvest.yaml"
+    "hooks/definitions/stop_handoff_harvest.yaml",
+    "hooks/hooks.json"
   ],
   "files": [
     "GEMINI.md"

package/hooks/context-mode-router

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve, basename } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const hooksDir = dirname(fileURLToPath(import.meta.url));
+const projectRoot = dirname(hooksDir);
+const matrixPath = join(hooksDir, 'routing-matrix.json');
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function loadRoutingMatrix() {
+  return JSON.parse(readFileSync(matrixPath, 'utf8'));
+}
+
+function parseCommand(raw) {
+  return (raw || '').trim();
+}
+
+function firstToken(cmd) {
+  return cmd.split(/\s+/)[0] || '';
+}
+
+function hasPipe(cmd) {
+  return /(?<![\\])\|/.test(cmd);
+}
+
+function hasRedirect(cmd) {
+  return /(?<![\\])[>]/.test(cmd);
+}
+
+// ---------------------------------------------------------------------------
+// Classification
+// ---------------------------------------------------------------------------
+
+function classify(cmd, matrix) {
+  // 1. Explicit context-mode marker always wins
+  if (cmd.includes('# wazir:context-mode')) return 'large';
+
+  // 2. Check large patterns FIRST — AC-3.1: large commands are never
+  //    downgraded, even with a passthrough marker (AC-1.5).
+  for (const pattern of matrix.large) {
+    if (cmd === pattern || cmd.startsWith(pattern + ' ') || cmd.startsWith(pattern + '\t')) {
+      return 'large';
+    }
+  }
+
+  // 3. Passthrough marker — restricted to heuristic false positives (AC-1.5).
+  //    Only honoured when the command is NOT in the Large category (checked above).
+  if (cmd.includes('# wazir:passthrough')) return 'small';
+
+  // 4. Check small patterns
+  for (const pattern of matrix.small) {
+    if (cmd === pattern || cmd.startsWith(pattern + ' ') || cmd.startsWith(pattern + '\t')) {
+      return 'small';
+    }
+  }
+
+  // 5. Ambiguous heuristics
+  const heuristic = matrix.ambiguous_heuristic || {};
+
+  if (heuristic.pipe_detected && hasPipe(cmd)) return 'ambiguous';
+  if (heuristic.redirect_detected && hasRedirect(cmd)) return 'ambiguous';
+
+  const bin = firstToken(cmd);
+  if (Array.isArray(heuristic.verbose_binaries) && heuristic.verbose_binaries.includes(bin)) {
+    return 'ambiguous';
+  }
+
+  // Default: treat unknown commands as small (passthrough)
+  return 'small';
+}
+
+// ---------------------------------------------------------------------------
+// Context-mode enabled check
+// ---------------------------------------------------------------------------
+
+function isContextModeEnabled() {
+  // Check WAZIR_CONTEXT_MODE env var first
+  const envVal = process.env.WAZIR_CONTEXT_MODE;
+  if (envVal !== undefined) {
+    return envVal === '1' || envVal === 'true';
+  }
+
+  // Fall back to manifest adapter setting
+  try {
+    const manifestPath = join(projectRoot, 'wazir.manifest.yaml');
+    const manifestText = readFileSync(manifestPath, 'utf8');
+    // Simple YAML parse for enabled_by_default under context_mode
+    const match = manifestText.match(/context_mode:[\s\S]*?enabled_by_default:\s*(true|false)/);
+    if (match) return match[1] === 'true';
+  } catch {
+    // ignore
+  }
+
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// One-per-session warning when context-mode is disabled
+// ---------------------------------------------------------------------------
+
+const SESSION_WARNING_KEY = 'WAZIR_CM_WARNED';
+
+function emitDisabledWarning() {
+  if (process.env[SESSION_WARNING_KEY]) return;
+
+  process.stderr.write(
+    '[wazir:context-mode-router] context_mode adapter is disabled. ' +
+    'All commands pass through without routing. ' +
+    'Enable via WAZIR_CONTEXT_MODE=1 or set adapters.context_mode.enabled_by_default: true in manifest.\n',
+  );
+
+  // Mark so downstream child processes see it (best-effort session dedup)
+  process.env[SESSION_WARNING_KEY] = '1';
+}
+
+// ---------------------------------------------------------------------------
+// Logging
+// ---------------------------------------------------------------------------
+
+function deriveStateRoot() {
+  if (process.env.WAZIR_STATE_ROOT) return process.env.WAZIR_STATE_ROOT;
+  try {
+    const manifestPath = join(projectRoot, 'wazir.manifest.yaml');
+    const raw = readFileSync(manifestPath, 'utf8');
+    const nameMatch = raw.match(/^\s+name:\s*(.+)$/m);
+    const templateMatch = raw.match(/state_root_default:\s*(.+)$/m);
+    if (nameMatch && templateMatch) {
+      const slug = nameMatch[1].trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'wazir-project';
+      const template = templateMatch[1].trim();
+      const expanded = template.startsWith('~/') ? join(homedir(), template.slice(2)) : template;
+      return resolve(expanded.replace('{project_slug}', slug));
+    }
+  } catch { /* fall through */ }
+  return join(homedir(), '.wazir', 'projects', '_default');
+}
+
+function logDecision(decision) {
+  const stateRoot = deriveStateRoot();
+  const logDir = join(stateRoot, 'logs');
+
+  try {
+    if (!existsSync(logDir)) mkdirSync(logDir, { recursive: true });
+    const entry = JSON.stringify({
+      ts: new Date().toISOString(),
+      hook: 'context_mode_router',
+      ...decision,
+    });
+    appendFileSync(join(logDir, 'routing.ndjson'), entry + '\n');
+  } catch {
+    // Logging is best-effort; never fail the hook over it
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+try {
+  const input = readFileSync(0, 'utf8');
+  const payload = input.trim() ? JSON.parse(input) : {};
+  const cmd = parseCommand(payload.command || payload.tool_input?.command || '');
+  const matrix = loadRoutingMatrix();
+  const category = classify(cmd, matrix);
+  const contextModeEnabled = isContextModeEnabled();
+
+  let route = 'passthrough';
+
+  if (!contextModeEnabled) {
+    emitDisabledWarning();
+    route = 'passthrough';
+  } else if (category === 'large' || category === 'ambiguous') {
+    route = 'context-mode';
+  }
+
+  const decision = { command: cmd, category, route, context_mode_enabled: contextModeEnabled };
+
+  logDecision(decision);
+  process.stdout.write(`${JSON.stringify({ routing_decision: decision })}\n`);
+
+  // Exit 0 = passthrough, non-zero = route to context-mode
+  process.exit(route === 'passthrough' ? 0 : 1);
+} catch (error) {
+  process.stderr.write(`${error.message}\n`);
+  process.exit(0); // failure_behavior.mode = warn → always allow on error
+}

package/hooks/definitions/context_mode_router.yaml

@@ -0,0 +1,19 @@
+id: context_mode_router
+trigger: context_mode_router
+description: Route large command output through context-mode tools to avoid flooding model context.
+input_contract:
+  required:
+    - command
+allowed_side_effects:
+  - route_to_context_mode
+output_contract:
+  produces:
+    - routing_decision
+failure_behavior:
+  mode: warn
+  exit_code: 0
+host_fallback:
+  claude: native_hook
+  codex: wrapper_command
+  gemini: wrapper_command
+  cursor: native_or_wrapper

package/hooks/hooks.json

@@ -1,17 +1,42 @@
 {
   "hooks": {
-    "beforeFileEdit": [
+    "PreToolUse": [
       {
-        "command": "./hooks/protected-path-write-guard",
-        "matcher": "*.md|*.yaml|*.json"
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./hooks/protected-path-write-guard"
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./hooks/context-mode-router"
+          }
+        ]
       }
     ],
-    "sessionStart": [
+    "SessionStart": [
       {
-        "command": "./hooks/loop-cap-guard"
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./hooks/loop-cap-guard"
+          }
+        ]
       },
       {
-        "command": "./hooks/session-start"
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./hooks/session-start"
+          }
+        ]
       }
     ]
   }

package/hooks/protected-path-write-guard

@@ -7,6 +7,14 @@ import { evaluateProtectedPathWriteGuard } from '../tooling/src/guards/protected
 try {
   const input = readFileSync(0, 'utf8');
   const payload = input.trim() ? JSON.parse(input) : {};
+
+  // Map Claude Code payload format to guard format (target_path)
+  // Claude may send file_path at top level or nested under tool_input
+  if (!payload.target_path) {
+    payload.target_path = payload.file_path
+      ?? payload.tool_input?.file_path;
+  }
+
   const decision = evaluateProtectedPathWriteGuard(payload);
 
   process.stdout.write(`${JSON.stringify({ guard_decision: decision })}\n`);

package/hooks/routing-matrix.json

@@ -0,0 +1,45 @@
+{
+  "large": [
+    "npm test",
+    "vitest",
+    "jest",
+    "pytest",
+    "npm run build",
+    "tsc --noEmit",
+    "npm ls",
+    "pip list",
+    "eslint .",
+    "prettier --check .",
+    "tail -f"
+  ],
+  "small": [
+    "git status",
+    "git log",
+    "git branch",
+    "git rev-parse",
+    "ls",
+    "pwd",
+    "mkdir",
+    "cp",
+    "mv",
+    "rm",
+    "wazir doctor",
+    "wazir index",
+    "wazir capture",
+    "wazir validate",
+    "which",
+    "echo"
+  ],
+  "ambiguous_heuristic": {
+    "pipe_detected": true,
+    "redirect_detected": true,
+    "verbose_binaries": [
+      "find",
+      "rg",
+      "grep",
+      "awk",
+      "sed",
+      "curl"
+    ]
+  }
+}

package/hooks/session-start

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -26,6 +27,66 @@ if (existsSync(skillFile)) {
   );
 }
 
+// ---------------------------------------------------------------------------
+// Index freshness check (AC-D2.1 through AC-D2.3)
+// ---------------------------------------------------------------------------
+
+const FRESHNESS_THRESHOLD_MS = 3600 * 1000; // 1 hour
+
+function refreshIndex() {
+  try {
+    const wazirPath = execFileSync('which', ['wazir'], { encoding: 'utf8', timeout: 5000 }).trim();
+    if (!wazirPath) return;
+
+    // Check index freshness via stats
+    let needsRefresh = true;
+    try {
+      const statsOut = execFileSync(wazirPath, ['index', 'stats', '--json'], {
+        encoding: 'utf8',
+        timeout: 10000,
+        cwd: projectRoot,
+      });
+      const stats = JSON.parse(statsOut);
+      if (stats.database_path) {
+        const mtime = statSync(stats.database_path).mtimeMs;
+        const age = Date.now() - mtime;
+        if (age < FRESHNESS_THRESHOLD_MS) {
+          needsRefresh = false;
+        }
+      }
+    } catch {
+      // No index or stats failed — needs build
+    }
+
+    if (!needsRefresh) return;
+
+    // Run refresh (or build if no index)
+    try {
+      execFileSync(wazirPath, ['index', 'refresh'], {
+        encoding: 'utf8',
+        timeout: 30000,
+        cwd: projectRoot,
+      });
+      process.stderr.write('[wazir:session-start] Index refreshed.\n');
+    } catch {
+      try {
+        execFileSync(wazirPath, ['index', 'build'], {
+          encoding: 'utf8',
+          timeout: 30000,
+          cwd: projectRoot,
+        });
+        process.stderr.write('[wazir:session-start] Index built.\n');
+      } catch (err) {
+        process.stderr.write(`[wazir:session-start] WARN: index refresh/build failed: ${err.message}\n`);
+      }
+    }
+  } catch {
+    process.stderr.write('[wazir:session-start] WARN: wazir CLI not found, skipping index refresh.\n');
+  }
+}
+
+refreshIndex();
+
 process.stdout.write(
   `<cli-bootstrap-guidance>\n` +
   `## CLI Bootstrap\n\n` +