@bartolli/kmd 0.9.0 → 0.11.0

package/dist/kmd.mjs

@@ -248,6 +248,12 @@ var init_vault_config = __esm({
       }).optional(),
       "handoff-gate": z.strictObject({
         reason: z.string().min(1).optional().describe("Stop-block preamble; the engine appends the error lines.")
+      }).optional(),
+      orient: z.strictObject({
+        text: z.string().min(1).optional().describe("Session-start prime instruction; the engine prepends the resolved scope.")
+      }).optional(),
+      reorient: z.strictObject({
+        text: z.string().min(1).optional().describe("Post-compaction re-orientation; the engine prepends the resolved scope.")
       }).optional()
     });
     VaultConfigSchema = z.strictObject({
@@ -269,7 +275,7 @@ var init_vault_config = __esm({
         'Full-replace of the trigger base per scope \u2014 escape hatch. "_all" is reserved for triggers_extra.'
       ),
       builtin_hooks: BuiltinHooksSchema.optional().describe(
-        "Message overrides for the fixed-function hooks (resync, handoff-gate) by public id."
+        "Message overrides for the fixed-function hooks (resync, handoff-gate, orient, reorient) by public id."
       ),
       triggers_extra: TriggersSchema.optional().describe(
         'Appended per scope after the engine defaults; the reserved "_all" key fires in every session.'
@@ -809,15 +815,11 @@ async function syncVault(vaultRoot2) {
       }
       indexedPaths.push(path);
     }
-    let pagesDeleted = 0;
-    let linksDeleted = 0;
-    if (indexedPaths.length > 0) {
-      const placeholders = indexedPaths.map(() => "?").join(", ");
-      const pageResult = db.prepare(`DELETE FROM pages WHERE path NOT IN (${placeholders})`).run(...indexedPaths);
-      pagesDeleted = Number(pageResult.changes);
-      const linkResult = db.prepare("DELETE FROM links WHERE source_path NOT IN (SELECT path FROM pages)").run();
-      linksDeleted = Number(linkResult.changes);
-    }
+    const placeholders = indexedPaths.map(() => "?").join(", ");
+    const pageResult = indexedPaths.length > 0 ? db.prepare(`DELETE FROM pages WHERE path NOT IN (${placeholders})`).run(...indexedPaths) : db.prepare("DELETE FROM pages").run();
+    const pagesDeleted = Number(pageResult.changes);
+    const linkResult = db.prepare("DELETE FROM links WHERE source_path NOT IN (SELECT path FROM pages)").run();
+    const linksDeleted = Number(linkResult.changes);
     db.exec("INSERT INTO pages_fts(pages_fts) VALUES('rebuild')");
     setMeta(db, "vault_root", canonicalVaultRoot(vaultRoot2));
     setMeta(db, "last_synced", (/* @__PURE__ */ new Date()).toISOString());
@@ -841,7 +843,7 @@ async function runSync() {
   console.log(`sync: ${env.WIKI_VAULT} \u2192 ${resolveIndexPath(env.WIKI_VAULT)}`);
   const stats = await syncVault(env.WIKI_VAULT);
   if (stats.noPages) {
-    console.warn("no indexable pages found; skipping orphan deletion (safety)");
+    console.warn("no indexable pages found; index swept empty");
   }
   console.log(
     `done: ${stats.changed} changed, ${stats.unchanged} unchanged, ${stats.skipped} skipped, ${stats.pagesDeleted} pages deleted, ${stats.linksDeleted} link orphans cleared`
@@ -2361,6 +2363,8 @@ __export(hook_exports, {
   dedupePretoolMatches: () => dedupePretoolMatches,
   effectiveTriggers: () => effectiveTriggers,
   evaluateMatches: () => evaluateMatches,
+  explainPretool: () => explainPretool,
+  explainPrompt: () => explainPrompt,
   hookStateDir: () => hookStateDir,
   kiroIdePromptEvent: () => kiroIdePromptEvent,
   loadTriggerFile: () => loadTriggerFile,
@@ -2368,14 +2372,18 @@ __export(hook_exports, {
   matchPromptTriggers: () => matchPromptTriggers,
   parsePretoolEvent: () => parsePretoolEvent,
   parsePromptEvent: () => parsePromptEvent,
+  parseSessionStartEvent: () => parseSessionStartEvent,
   parseStopEvent: () => parseStopEvent,
   renderPosttool: () => renderPosttool,
   renderPretool: () => renderPretool,
+  renderPrompt: () => renderPrompt,
+  renderSessionStart: () => renderSessionStart,
   renderStop: () => renderStop,
   resolveScope: () => resolveScope,
   runHookPosttool: () => runHookPosttool,
   runHookPretool: () => runHookPretool,
   runHookPrompt: () => runHookPrompt,
+  runHookSessionStart: () => runHookSessionStart,
   runHookStop: () => runHookStop,
   vaultPathTouched: () => vaultPathTouched
 });
@@ -2464,37 +2472,50 @@ function openPromptIndex(prompt) {
   db.prepare("INSERT INTO prompt_doc (text) VALUES (?)").run(prompt);
   return db;
 }
+function promptProbe(trigger, prompt, getDb) {
+  let keywords = "unset";
+  if (trigger.keywords !== void 0 && trigger.keywords.length > 0) {
+    const row = getDb().prepare("SELECT count(*) AS n FROM prompt_doc WHERE prompt_doc MATCH ?").get(keywordQuery(trigger.keywords));
+    keywords = row.n > 0 ? "hit" : "miss";
+  }
+  let intent = "unset";
+  if (trigger.intent !== void 0) {
+    intent = trigger.intent.some((pattern) => new RegExp(pattern, "i").test(prompt)) ? "hit" : "miss";
+  }
+  return { keywords, intent };
+}
+function promptHit(probe) {
+  return probe.keywords === "hit" || probe.intent === "hit";
+}
+function isInjectTrigger(trigger) {
+  return trigger.on === "prompt" && trigger.enforce === "inject" && trigger.text !== void 0;
+}
 function matchPromptTriggers(prompt, triggers) {
-  const candidates = triggers.filter(
-    (trigger) => trigger.on === "prompt" && trigger.enforce === "inject" && trigger.text !== void 0
-  );
+  const candidates = triggers.filter(isInjectTrigger);
   if (candidates.length === 0) return [];
   const matches = [];
-  let db = null;
+  const state = { db: null };
+  const getDb = () => state.db ??= openPromptIndex(prompt);
   try {
     for (const trigger of candidates) {
-      let hit = false;
-      if (trigger.keywords !== void 0 && trigger.keywords.length > 0) {
-        db ??= openPromptIndex(prompt);
-        const row = db.prepare("SELECT count(*) AS n FROM prompt_doc WHERE prompt_doc MATCH ?").get(keywordQuery(trigger.keywords));
-        hit = row.n > 0;
-      }
-      if (!hit && trigger.intent !== void 0) {
-        hit = trigger.intent.some((pattern) => new RegExp(pattern, "i").test(prompt));
-      }
-      if (hit) {
-        matches.push({
-          id: trigger.id,
-          text: trigger.text,
-          ...trigger.dedup !== void 0 && { dedup: trigger.dedup }
-        });
-      }
+      if (!promptHit(promptProbe(trigger, prompt, getDb))) continue;
+      matches.push({
+        id: trigger.id,
+        text: trigger.text,
+        ...trigger.dedup !== void 0 && { dedup: trigger.dedup }
+      });
     }
   } finally {
-    db?.close();
+    state.db?.close();
   }
   return matches;
 }
+function uniqueTexts(texts) {
+  return [...new Set(texts)];
+}
+function renderPrompt(matches) {
+  return uniqueTexts(matches.map((match) => match.text));
+}
 function parsePretoolEvent(raw) {
   const fields = eventFields(raw);
   if (fields === null) return null;
@@ -2543,32 +2564,41 @@ function pathCandidates(toolInput, cwd) {
   }
   return candidates;
 }
+function pretoolStage(trigger, toolName, toolInput, cwd) {
+  if (trigger.tool !== void 0 && trigger.tool !== toolName) return "tool";
+  if (trigger.args_match !== void 0) {
+    const serialized = JSON.stringify(toolInput ?? {});
+    if (!new RegExp(trigger.args_match).test(serialized)) return "args";
+  }
+  if (trigger.files !== void 0 && trigger.files.length > 0) {
+    const candidates = [...pathCandidates(toolInput, cwd), ...patchPaths(toolInput)];
+    const hit = trigger.files.some((glob) => {
+      const regex = globToRegExp(glob);
+      return candidates.some((candidate) => regex.test(candidate));
+    });
+    if (!hit) return "files";
+  }
+  if (pretoolText(trigger) === void 0) return "payload";
+  return "hit";
+}
+function pretoolText(trigger) {
+  return trigger.enforce === "block" ? trigger.reason : trigger.text;
+}
+function pretoolMatch(trigger) {
+  return {
+    id: trigger.id,
+    enforce: trigger.enforce,
+    text: pretoolText(trigger),
+    ...trigger.when !== void 0 && { when: trigger.when },
+    ...trigger.dedup !== void 0 && { dedup: trigger.dedup }
+  };
+}
 function matchPretoolTriggers(toolName, toolInput, triggers, cwd) {
   const matches = [];
   for (const trigger of triggers) {
     if (trigger.on !== "pretool") continue;
-    if (trigger.tool !== void 0 && trigger.tool !== toolName) continue;
-    if (trigger.args_match !== void 0) {
-      const serialized = JSON.stringify(toolInput ?? {});
-      if (!new RegExp(trigger.args_match).test(serialized)) continue;
-    }
-    if (trigger.files !== void 0 && trigger.files.length > 0) {
-      const candidates = [...pathCandidates(toolInput, cwd), ...patchPaths(toolInput)];
-      const hit = trigger.files.some((glob) => {
-        const regex = globToRegExp(glob);
-        return candidates.some((candidate) => regex.test(candidate));
-      });
-      if (!hit) continue;
-    }
-    const text = trigger.enforce === "block" ? trigger.reason : trigger.text;
-    if (text === void 0) continue;
-    matches.push({
-      id: trigger.id,
-      enforce: trigger.enforce,
-      text,
-      ...trigger.when !== void 0 && { when: trigger.when },
-      ...trigger.dedup !== void 0 && { dedup: trigger.dedup }
-    });
+    if (pretoolStage(trigger, toolName, toolInput, cwd) !== "hit") continue;
+    matches.push(pretoolMatch(trigger));
   }
   return matches;
 }
@@ -2586,18 +2616,23 @@ function evaluateMatches(matches, vaultRoot2) {
   }
   return { fired, skipped };
 }
-function evaluateWhen(when, vaultRoot2) {
-  if (typeof when === "string") return null;
+function evaluateWhenVerdict(when, vaultRoot2) {
+  if (typeof when === "string") return "unknown";
   try {
     const than = newestUpdated(vaultRoot2, when.than);
-    if (than === null) return true;
+    if (than === null) return "vacuous";
     const fresh = newestUpdated(vaultRoot2, when.fresh);
-    if (fresh === null) return false;
-    return fresh >= than;
+    if (fresh === null) return "unmet";
+    return fresh >= than ? "satisfied" : "unmet";
   } catch {
-    return null;
+    return "unknown";
   }
 }
+function evaluateWhen(when, vaultRoot2) {
+  const verdict = evaluateWhenVerdict(when, vaultRoot2);
+  if (verdict === "unknown") return null;
+  return verdict !== "unmet";
+}
 function newestUpdated(vaultRoot2, globs) {
   const regexes = globs.map(globToRegExp);
   let newest = null;
@@ -2624,26 +2659,27 @@ function readUpdated(path) {
   return null;
 }
 function renderPretool(matches, format) {
-  const block = matches.find((match) => match.enforce === "block");
-  const context = matches.filter((match) => match.enforce === "inject").map((match) => match.text);
-  const warnings = matches.filter((match) => match.enforce === "warn").map((match) => match.text);
+  const byClass = (enforce) => uniqueTexts(matches.filter((match) => match.enforce === enforce).map((match) => match.text));
+  const reasons = byClass("block");
+  const context = byClass("inject");
+  const warnings = byClass("warn");
   if (format === "claude") {
     const hookSpecificOutput = { hookEventName: "PreToolUse" };
-    if (block !== void 0) {
+    if (reasons.length > 0) {
       hookSpecificOutput.permissionDecision = "deny";
-      hookSpecificOutput.permissionDecisionReason = block.text;
+      hookSpecificOutput.permissionDecisionReason = reasons.join("\n");
     }
     if (context.length > 0) {
       hookSpecificOutput.additionalContext = context.join("\n");
     }
-    const decided = block !== void 0 || context.length > 0;
+    const decided = reasons.length > 0 || context.length > 0;
     return { stdout: decided ? JSON.stringify({ hookSpecificOutput }) : null, stderr: warnings };
   }
   if (matches.length === 0) return { stdout: null, stderr: [] };
   return {
     stdout: JSON.stringify({
-      decision: block !== void 0 ? "deny" : "none",
-      ...block !== void 0 && { reason: block.text },
+      decision: reasons.length > 0 ? "deny" : "none",
+      ...reasons.length > 0 && { reason: reasons.join("\n") },
       context,
       warnings
     }),
@@ -2663,9 +2699,27 @@ function patchPaths(toolInput) {
   }
   return paths;
 }
+function commandPaths(toolInput) {
+  if (typeof toolInput !== "object" || toolInput === null) return [];
+  const command2 = toolInput.command;
+  if (typeof command2 !== "string") return [];
+  const paths = [];
+  for (const match of command2.matchAll(COMMAND_TOKEN_RE)) {
+    const token = match[1] ?? match[2] ?? match[3];
+    for (const piece of token.split(/[;|&<>()]+/)) {
+      if (piece === "") continue;
+      if (piece === "." || piece === ".." || PATHISH_RE.test(piece)) paths.push(piece);
+    }
+  }
+  return paths;
+}
 function vaultPathTouched(toolInput, vaultRoot2, cwd) {
   const root = resolve3(vaultRoot2);
-  const candidates = [...pathCandidates(toolInput, cwd), ...patchPaths(toolInput)];
+  const candidates = [
+    ...pathCandidates(toolInput, cwd),
+    ...patchPaths(toolInput),
+    ...commandPaths(toolInput)
+  ];
   return candidates.some((candidate) => {
     const absolute = resolve3(cwd ?? ".", candidate);
     return absolute === root || absolute.startsWith(`${root}/`);
@@ -2711,50 +2765,141 @@ function renderStop(findings, reason) {
 ${lines.join("\n")}`
   });
 }
-function dedupePretoolMatches(stateDir, sessionId, matches) {
+function dedupePretoolMatches(stateDir, sessionId, matches, persist = true) {
   const blocks = matches.filter((match) => match.enforce === "block");
   const rest = matches.filter((match) => match.enforce !== "block");
-  const fresh = dedupeMatches(stateDir, sessionId, rest);
+  const fresh = dedupeMatches(stateDir, sessionId, rest, Date.now(), persist);
   return matches.filter((match) => blocks.includes(match) || fresh.includes(match));
 }
 function hookStateDir() {
   return join10(kmdHome(), "state", "hook");
 }
-function dedupeMatches(stateDir, sessionId, matches, now = Date.now()) {
+function explainPrompt(options) {
+  const now = options.now ?? Date.now();
+  const fired = readFired(join10(options.stateDir, safeName(options.sessionId)));
+  const entries = [];
+  const rendered = [];
+  const state = { db: null };
+  const getDb = () => state.db ??= openPromptIndex(options.prompt);
+  try {
+    for (const trigger of options.triggers) {
+      if (!isInjectTrigger(trigger)) {
+        entries.push({ id: trigger.id, considered: false });
+        continue;
+      }
+      const probe = promptProbe(trigger, options.prompt, getDb);
+      const matched = promptHit(probe);
+      const entry = {
+        id: trigger.id,
+        considered: true,
+        keywords: probe.keywords,
+        intent: probe.intent,
+        matched
+      };
+      entries.push(entry);
+      if (!matched) {
+        entry.fired = false;
+        continue;
+      }
+      const key = dedupKey(trigger, now);
+      entry.dedup = key === null ? "never" : fired.has(key) ? "suppressed" : "fresh";
+      entry.fired = entry.dedup !== "suppressed";
+      if (entry.fired) rendered.push({ id: trigger.id, text: trigger.text });
+    }
+  } finally {
+    state.db?.close();
+  }
+  return { triggers: entries, output: renderPrompt(rendered) };
+}
+function explainPretool(options) {
+  const now = options.now ?? Date.now();
+  const fired = readFired(join10(options.stateDir, safeName(options.sessionId)));
+  const entries = [];
+  const rendered = [];
+  for (const trigger of options.triggers) {
+    if (trigger.on !== "pretool") {
+      entries.push({ id: trigger.id, considered: false });
+      continue;
+    }
+    const stage = pretoolStage(trigger, options.toolName, options.toolInput, options.cwd);
+    const entry = {
+      id: trigger.id,
+      enforce: trigger.enforce,
+      considered: true,
+      matcher: stage === "hit" ? "hit" : `${stage}-miss`
+    };
+    entries.push(entry);
+    if (stage !== "hit") {
+      entry.fired = false;
+      continue;
+    }
+    if (trigger.when !== void 0) {
+      entry.when = evaluateWhenVerdict(trigger.when, options.vaultRoot);
+      if (entry.when !== "unmet") {
+        entry.fired = false;
+        continue;
+      }
+    }
+    const match = pretoolMatch(trigger);
+    if (match.enforce === "block") {
+      entry.dedup = "exempt";
+    } else {
+      const key = dedupKey(match, now);
+      entry.dedup = key === null ? "never" : fired.has(key) ? "suppressed" : "fresh";
+    }
+    entry.fired = entry.dedup !== "suppressed";
+    if (entry.fired) rendered.push(match);
+  }
+  return { triggers: entries, outcome: renderPretool(rendered, options.format ?? "neutral") };
+}
+function dedupeMatches(stateDir, sessionId, matches, now = Date.now(), persist = true) {
   if (matches.length === 0) return [];
-  const file = join10(stateDir, `${sessionId.replace(/[^A-Za-z0-9._-]/g, "_")}.json`);
-  const fired = readFired(file);
+  const dir = join10(stateDir, safeName(sessionId));
+  const fired = readFired(dir);
   const fresh = [];
   const record = [];
   for (const match of matches) {
-    if (match.dedup === "never") {
+    const key = dedupKey(match, now);
+    if (key === null) {
       fresh.push(match);
       continue;
     }
-    const key = typeof match.dedup === "object" ? `${match.id}@${Math.floor(now / (match.dedup.minutes * 6e4))}` : match.id;
     if (fired.has(key)) continue;
     fresh.push(match);
     record.push(key);
   }
-  if (record.length > 0) {
-    mkdirSync4(stateDir, { recursive: true });
-    for (const key of record) {
-      fired.add(key);
+  if (persist && record.length > 0) {
+    try {
+      mkdirSync4(dir, { recursive: true });
+      for (const key of record) {
+        try {
+          writeFileSync(join10(dir, key), "", { flag: "wx" });
+        } catch (err) {
+          if (err.code !== "EEXIST") throw err;
+        }
+      }
+      pruneStale(stateDir, dir);
+    } catch (err) {
+      diag2(`dedup state not persisted: ${err instanceof Error ? err.message : String(err)}`);
     }
-    writeFileSync(file, JSON.stringify([...fired]));
-    pruneStale(stateDir, file);
   }
   return fresh;
 }
-function readFired(file) {
+function safeName(part) {
+  return part.replace(/[^A-Za-z0-9._@-]/g, "_");
+}
+function dedupKey(match, now) {
+  if (match.dedup === "never") return null;
+  return safeName(
+    typeof match.dedup === "object" ? `${match.id}@${Math.floor(now / (match.dedup.minutes * 6e4))}` : match.id
+  );
+}
+function readFired(dir) {
   try {
-    const data = JSON.parse(readFileSync(file, "utf8"));
-    if (Array.isArray(data)) {
-      return new Set(data.filter((entry) => typeof entry === "string"));
-    }
+    return new Set(readdirSync2(dir));
   } catch {
+    return /* @__PURE__ */ new Set();
   }
-  return /* @__PURE__ */ new Set();
 }
 function pruneStale(stateDir, keep) {
   try {
@@ -2762,7 +2907,7 @@ function pruneStale(stateDir, keep) {
     for (const entry of readdirSync2(stateDir)) {
       const path = join10(stateDir, entry);
       if (path !== keep && statSync(path).mtimeMs < cutoff) {
-        rmSync2(path, { force: true });
+        rmSync2(path, { recursive: true, force: true });
       }
     }
   } catch {
@@ -2776,7 +2921,9 @@ function hookInvocation() {
     options: {
       scope: { type: "string" },
       harness: { type: "string" },
-      triggers: { type: "string" }
+      triggers: { type: "string" },
+      "dry-run": { type: "boolean" },
+      explain: { type: "boolean" }
     }
   });
   const vaultRoot2 = positionals2[2] ?? process.env.WIKI_VAULT;
@@ -2788,7 +2935,9 @@ function hookInvocation() {
     vaultRoot: vaultRoot2,
     scope: typeof values2.scope === "string" ? values2.scope : process.env.WIKI_SCOPE,
     harness: values2.harness,
-    triggersFile: values2.triggers
+    triggersFile: values2.triggers,
+    dryRun: values2["dry-run"] === true || values2.explain === true,
+    explain: values2.explain === true
   };
 }
 function resolveFileTriggers(invocation) {
@@ -2826,9 +2975,26 @@ async function runHookPrompt() {
     for (const id of duplicates) {
       diag2(`duplicate trigger id "${id}" \u2014 later occurrence ignored`);
     }
+    if (invocation.explain) {
+      const trace = explainPrompt({
+        prompt: event.prompt,
+        triggers,
+        stateDir: hookStateDir(),
+        sessionId: event.session_id
+      });
+      console.log(JSON.stringify({ event: "prompt", scope: scope ?? null, duplicates, ...trace }));
+      return;
+    }
     const matches = matchPromptTriggers(event.prompt, triggers);
-    for (const match of dedupeMatches(hookStateDir(), event.session_id, matches)) {
-      console.log(match.text);
+    const fresh = dedupeMatches(
+      hookStateDir(),
+      event.session_id,
+      matches,
+      Date.now(),
+      !invocation.dryRun
+    );
+    for (const line of renderPrompt(fresh)) {
+      console.log(line);
     }
   } catch (err) {
     diag2(err instanceof Error ? err.message : String(err));
@@ -2860,13 +3026,27 @@ async function runHookPretool() {
     for (const id of duplicates) {
       diag2(`duplicate trigger id "${id}" \u2014 later occurrence ignored`);
     }
+    if (invocation.explain) {
+      const trace = explainPretool({
+        toolName: event.tool_name,
+        toolInput: event.tool_input,
+        triggers,
+        vaultRoot: vaultRoot2,
+        stateDir: hookStateDir(),
+        sessionId: event.session_id,
+        ...event.cwd !== void 0 && { cwd: event.cwd },
+        format
+      });
+      console.log(JSON.stringify({ event: "pretool", scope: scope ?? null, duplicates, ...trace }));
+      return;
+    }
     const matches = matchPretoolTriggers(event.tool_name, event.tool_input, triggers, event.cwd);
     const { fired, skipped } = evaluateMatches(matches, vaultRoot2);
     for (const id of skipped) {
       diag2(`trigger "${id}": unknown or unevaluable predicate \u2014 skipped`);
     }
     const rendered = renderPretool(
-      dedupePretoolMatches(hookStateDir(), event.session_id, fired),
+      dedupePretoolMatches(hookStateDir(), event.session_id, fired, !invocation.dryRun),
       format
     );
     for (const line of rendered.stderr) {
@@ -2883,6 +3063,10 @@ async function runHookPosttool() {
   try {
     const invocation = hookInvocation();
     if (invocation === null) return;
+    if (invocation.dryRun) {
+      diag2("--dry-run/--explain support prompt and pretool events only");
+      return;
+    }
     let format = "neutral";
     if (invocation.harness === "claude") {
       format = "claude";
@@ -2918,6 +3102,10 @@ async function runHookStop() {
   try {
     const invocation = hookInvocation();
     if (invocation === null) return;
+    if (invocation.dryRun) {
+      diag2("--dry-run/--explain support prompt and pretool events only");
+      return;
+    }
     const event = parseStopEvent(await readStdin());
     if (event === null) {
       diag2("stdin is not a stop event ({session_id})");
@@ -2939,6 +3127,42 @@ async function runHookStop() {
     diag2(err instanceof Error ? err.message : String(err));
   }
 }
+function parseSessionStartEvent(raw) {
+  const fields = eventFields(raw);
+  if (fields === null) return null;
+  const { session_id, cwd, source } = fields;
+  if (typeof session_id !== "string") return null;
+  return {
+    session_id,
+    ...typeof cwd === "string" && { cwd },
+    ...typeof source === "string" && { source }
+  };
+}
+function renderSessionStart(scope, source, messages = {}) {
+  const text = source === "compact" ? messages.reorient?.text ?? REORIENT_TEXT : messages.orient?.text ?? ORIENT_TEXT;
+  return `Wiki scope "${scope}": ${text}`;
+}
+async function runHookSessionStart() {
+  try {
+    const invocation = hookInvocation();
+    if (invocation === null) return;
+    if (invocation.dryRun) {
+      diag2("--dry-run/--explain support prompt and pretool events only");
+      return;
+    }
+    const event = parseSessionStartEvent(await readStdin());
+    if (event === null) {
+      diag2("stdin is not a session-start event ({session_id})");
+      return;
+    }
+    const config = await loadVaultConfig(invocation.vaultRoot);
+    const scope = invocation.scope ?? resolveScope(config, event.cwd);
+    if (scope === void 0) return;
+    console.log(renderSessionStart(scope, event.source, config.builtin_hooks ?? {}));
+  } catch (err) {
+    diag2(err instanceof Error ? err.message : String(err));
+  }
+}
 async function readStdin() {
   process.stdin.setEncoding("utf8");
   let input = "";
@@ -2950,7 +3174,7 @@ async function readStdin() {
 function diag2(message) {
   console.error(`kmd hook: ${message}`);
 }
-var DEFAULT_TRIGGERS, SESSION_STATE_MAX_AGE_MS, KIRO_IDE_BUCKET_MS, ALL_SCOPES_KEY, PATCH_FILE_RE, RESYNC_REASON, RESYNC_TEXT, HANDOFF_GATE_REASON;
+var DEFAULT_TRIGGERS, SESSION_STATE_MAX_AGE_MS, KIRO_IDE_BUCKET_MS, ALL_SCOPES_KEY, PATCH_FILE_RE, COMMAND_TOKEN_RE, PATHISH_RE, RESYNC_REASON, RESYNC_TEXT, HANDOFF_GATE_REASON, ORIENT_TEXT, REORIENT_TEXT;
 var init_hook = __esm({
   "../cli/src/hook.ts"() {
     "use strict";
@@ -2964,9 +3188,13 @@ var init_hook = __esm({
     KIRO_IDE_BUCKET_MS = 30 * 60 * 1e3;
     ALL_SCOPES_KEY = "_all";
     PATCH_FILE_RE = /^\*\*\* (?:Add|Update|Delete) File: (.+)$/gm;
+    COMMAND_TOKEN_RE = /"([^"]*)"|'([^']*)'|(\S+)/g;
+    PATHISH_RE = /[/*$]|\.(?:md|base|canvas|ya?ml)$/i;
     RESYNC_REASON = "Edit landed; the index sync is held until these validate errors are fixed";
     RESYNC_TEXT = "kmd sync failed \u2014 index not updated; see hook stderr";
     HANDOFF_GATE_REASON = "Validate errors are outstanding and the index sync is held \u2014 fix them, let the resync run, then finish";
+    ORIENT_TEXT = "prime via the wiki MCP prime tool before substantive work \u2014 the primer carries current focus, book of work, and invariants.";
+    REORIENT_TEXT = "context was compacted and transcript detail is lost \u2014 re-read the primer via the wiki MCP prime tool and route uncaptured findings into the wiki before continuing.";
   }
 });
 
@@ -2987,7 +3215,7 @@ commands:
   mcp [<vault-root>]       start the stdio MCP server (default: $WIKI_VAULT)
   config [<vault-root>]    print vault + index resolution; with no vault, list known vaults
   db reset [<vault-root>]  delete the vault's index (default: $WIKI_VAULT)
-  hook <prompt|pretool|posttool|stop> [<vault-root>] [--scope <s>] [--harness <claude|kiro-ide>] [--triggers <file>]
+  hook <prompt|pretool|posttool|stop|session-start> [<vault-root>] [--scope <s>] [--harness <claude|kiro-ide>] [--triggers <file>]
                            harness gate engine: JSON event on stdin, decision/context on stdout;
                            posttool auto-runs validate + sync after a vault write;
                            stop blocks the handoff once while validate errors hold the sync
@@ -3068,11 +3296,14 @@ async function run() {
       } else if (sub === "stop") {
         const { runHookStop: runHookStop2 } = await Promise.resolve().then(() => (init_hook(), hook_exports));
         await runHookStop2();
+      } else if (sub === "session-start") {
+        const { runHookSessionStart: runHookSessionStart2 } = await Promise.resolve().then(() => (init_hook(), hook_exports));
+        await runHookSessionStart2();
       } else if (sub) {
         console.error(`kmd hook: unknown event: ${sub}`);
       } else {
         console.error(
-          "usage: kmd hook <prompt|pretool|posttool|stop> [<vault-root>] [--scope <scope>] [--harness <claude|kiro-ide>]"
+          "usage: kmd hook <prompt|pretool|posttool|stop|session-start> [<vault-root>] [--scope <scope>] [--harness <claude|kiro-ide>]"
         );
         process.exit(2);
       }