@krimto-labs/krimto 0.2.22 → 0.2.27

package/bin/krimto.mjs

@@ -56,6 +56,21 @@ try {
     const minimal = flags.includes("--minimal");
     const yes = flags.includes("--yes");
     const isTty = process.stdin.isTTY === true;
+
+    // v0.2.24 — fix for the "AI agent runs krimto init and silently gets the legacy writer"
+    // gap. When invoked from a non-TTY context (e.g. Claude Code's Bash tool) with no flags,
+    // the interactive wizard CAN'T run; the legacy rule-only writer would proceed silently
+    // and the caller wouldn't realize MCP wiring + service install were skipped. Print a
+    // clear notice up front so the user (or AI relaying the result) knows what just happened.
+    if (!isTty && !all && !minimal && !yes) {
+      process.stderr.write(
+        "ℹ️  No interactive terminal detected — running lightweight init (rules only).\n" +
+          "   For the FULL setup (editor wiring + service install), either:\n" +
+          "     • Run from a real terminal:   $ npx @krimto-labs/krimto init\n" +
+          "     • Or pass --yes here:         $ npx @krimto-labs/krimto init --yes\n\n",
+      );
+    }
+
     const legacyMode = all || minimal || (!isTty && !yes);
 
     if (legacyMode) {
@@ -77,18 +92,51 @@ try {
           : !minimal
             ? `   Default: wrote all 4 supported rule files (safer than detecting one editor and\n   missing the actual one). Pass --minimal to write only matched editors next time.\n\n`
             : "";
+
+        // v0.2.25 — show both the files we wrote AND the files we skipped (already current).
+        // Before, "wrote 2 of 4" was opaque: the user couldn't tell whether the other 2 were
+        // intentionally skipped or silently failed. `res.considered` is the full target list
+        // for this invocation, so the skipped set is just considered \ written.
+        const writtenSet = new Set(res.written);
+        const skipped = res.considered.filter((f) => !writtenSet.has(f));
+        const skippedBlock = skipped.length > 0
+          ? "\n   Already current (no change):\n" + skipped.map((f) => `     • ${f}`).join("\n") + "\n"
+          : "";
+
+        // v0.2.25 — Gap 9. Rules-only init writes "always use krimto_*" instructions, but if
+        // no editor has Krimto wired into its MCP config, those instructions reference tools
+        // that won't exist in chat. Detect and warn so the user doesn't think the chat side
+        // is mysteriously broken later.
+        let mcpWarning = "";
+        try {
+          const { detectExistingSetup } = await tsImport("../src/cli/init.ts", import.meta.url);
+          const snap = await detectExistingSetup(process.cwd());
+          if (snap.registeredEditors.length === 0) {
+            mcpWarning =
+              "\n⚠️  Rule files written, but NO editor is wired to Krimto yet.\n" +
+              "   The rules tell your AI to use krimto_*, but those tools won't be available\n" +
+              "   until you register the MCP server. From a terminal:\n" +
+              "     $ npx @krimto-labs/krimto init        # full interactive wizard\n" +
+              "     $ npx @krimto-labs/krimto connect     # print copy-paste snippets\n";
+          }
+        } catch {
+          /* best-effort — don't block the success path if detection fails */
+        }
+
         process.stderr.write(
           "\n✅ AUTO MODE on — rule written to " + res.written.length + " file" +
             (res.written.length === 1 ? "" : "s") + "\n" +
             "\n" +
             res.written.map((f) => `   ${f}`).join("\n") + "\n" +
+            skippedBlock +
             "\n" +
             detectedLine +
             "━━ Next steps ━━\n" +
             "\n" +
-            "  1. Restart your editor (so it loads the new rule)\n" +
+            "  1. Restart your editor (so it loads the new rule + MCP tools)\n" +
             "  2. Test in chat: \"Remember that we use pnpm in this repo\"\n" +
             "  3. Verify it landed: $ npx @krimto-labs/krimto verify-connection\n" +
+            mcpWarning +
             "\n" +
             "To undo:  $ npx @krimto-labs/krimto uninit\n" +
             "Manual:   delete the block between <!-- krimto:start --> and <!-- krimto:end -->\n\n",
@@ -99,9 +147,23 @@ try {
       const { runInitNonInteractive } = await tsImport("../src/cli/wizard.ts", import.meta.url);
       const result = await runInitNonInteractive(process.cwd());
       const wired = result.editorOutcomes.map((o) => o.editor).join(", ") || "(none)";
+      // v0.2.27 — surface the port-readiness probe result. If the wizard installed an
+      // always-running service AND the port came up, the editor can reconnect immediately.
+      // If portReady is false, the wizard prints a warning so the CI/agent caller knows
+      // the service is up but its HTTP listener didn't bind in time.
+      let serviceLine = `   Run mode: as-needed\n`;
+      if (result.serviceInstall) {
+        if (result.serviceInstall.portReady === false) {
+          serviceLine =
+            `   Run mode: always-running ⚠ port did NOT come up within 10s\n` +
+            `             Check /tmp/com.krimto.server.err.log for boot errors.\n`;
+        } else {
+          serviceLine = `   Run mode: always-running · port ready\n`;
+        }
+      }
       process.stderr.write(
         `\n✅ Krimto set up (non-interactive). Editors: ${wired}\n` +
-          `   Run mode: ${result.serviceInstall ? "always-running" : "as-needed"}\n` +
+          serviceLine +
           `   Search:   ${result.embeddingsConfigured ? "OpenAI" : "keyword"}\n` +
           `   Data:     ${result.dataDir}\n\n` +
           "Restart your editor so it loads the new rule.\n\n",
@@ -362,7 +424,7 @@ try {
     // `krimto connect` — print stdio connect snippets (the npx on-ramp shape), so a solo user
     // doesn't have to chase the README. Honors KRIMTO_IDENTITY when set.
     const { formatConnect } = await tsImport("../src/cli/connect.ts", import.meta.url);
-    process.stdout.write(formatConnect({ identity: process.env.KRIMTO_IDENTITY }));
+    process.stdout.write(await formatConnect({ identity: process.env.KRIMTO_IDENTITY }));
   } else if (cmd === "whoami") {
     // `krimto whoami` — show the active KRIMTO_IDENTITY and every place it's currently set
     // (each editor's MCP config + the always-running service unit). Surfaces drift between

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krimto-labs/krimto",
-  "version": "0.2.22",
+  "version": "0.2.27",
   "description": "Open-source team memory layer for AI agents — markdown files in git, user/team/org hierarchy, cross-vendor MCP server.",
   "license": "Apache-2.0",
   "type": "module",

package/src/cli/cliRuntime.ts

@@ -54,6 +54,7 @@ export async function getLockHolder(dataDir: string): Promise<LockInfo | null> {
         pid: parsed.pid,
         started: typeof parsed.started === "string" ? parsed.started : "unknown",
         mode: (parsed.mode as LockInfo["mode"]) ?? "stdio",
+        launchedBy: parsed.launchedBy === "service" ? "service" : "ad-hoc",
       };
     }
   } catch {

package/src/cli/connect.ts

@@ -5,13 +5,24 @@
 import { stdioConnectSnippets } from "../server/connect";
 
 export interface ConnectOpts {
-  /** Identity to embed in the Cursor env block. Defaults to a generic placeholder. */
+  /** Identity to embed in the Cursor env block. Defaults to git config user.email, falling back to a generic placeholder. */
   identity?: string;
 }
 
-/** Build the multi-line, copy-pasteable output `krimto connect` prints to stdout. */
-export function formatConnect(opts: ConnectOpts = {}): string {
-  const { claude, cursorJson } = stdioConnectSnippets(opts);
+/**
+ * Build the multi-line, copy-pasteable output `krimto connect` prints to stdout.
+ *
+ * v0.2.24 — identity falls back to {@link defaultIdentity} (git config user.email) when not
+ * supplied. Before this, the printed snippet always showed `you@acme.com`, so users
+ * pasting the snippet ended up with the placeholder as their literal KRIMTO_IDENTITY.
+ *
+ * v0.2.24 — the printed `claude mcp add` line is now preceded by `claude mcp remove krimto`
+ * so a copy-paste rerun doesn't fail with "MCP server krimto already exists in local config"
+ * (the same idempotency fix v0.2.19 made to the wizard's MCP writer).
+ */
+export async function formatConnect(opts: ConnectOpts = {}): Promise<string> {
+  const identity = opts.identity ?? (await defaultIdentityForConnect());
+  const { claude, cursorJson } = stdioConnectSnippets({ identity });
   const indentedJson = cursorJson.split("\n").map((line) => `     ${line}`).join("\n");
   return [
     "",
@@ -19,7 +30,8 @@ export function formatConnect(opts: ConnectOpts = {}): string {
     "",
     "━━ 1. Paste the config ━━",
     "",
-    "  Claude Code:",
+    "  Claude Code (the `remove` clears any prior entry so re-runs don't error):",
+    "     $ claude mcp remove krimto 2>/dev/null; true",
     `     $ ${claude}`,
     "",
     "  Cursor (add to ~/.cursor/mcp.json, then restart Cursor):",
@@ -61,3 +73,22 @@ export function formatConnect(opts: ConnectOpts = {}): string {
     "",
   ].join("\n");
 }
+
+/**
+ * Local copy of init.ts's git-config lookup, scoped to the connect command. We don't import
+ * `defaultIdentity` directly from init.ts to keep `connect` cheap (init.ts pulls in
+ * `applyRule`, service installer, MCP writer, etc.). Same regex; same fallback.
+ */
+async function defaultIdentityForConnect(): Promise<string> {
+  try {
+    const { execFile } = await import("node:child_process");
+    const { promisify } = await import("node:util");
+    const exec = promisify(execFile);
+    const { stdout } = await exec("git", ["config", "--global", "user.email"]);
+    const email = stdout.trim();
+    if (email && /^[^@\s]+@[^@\s]+$/.test(email)) return email;
+  } catch {
+    /* git missing or unconfigured — fall through to the legacy placeholder */
+  }
+  return "you@acme.com";
+}

package/src/cli/deleteFact.ts

@@ -35,6 +35,7 @@ async function checkLock(dataDir: string): Promise<LockInfo | null> {
         pid: parsed.pid,
         started: typeof parsed.started === "string" ? parsed.started : "unknown",
         mode: (parsed.mode as LockInfo["mode"]) ?? "stdio",
+        launchedBy: parsed.launchedBy === "service" ? "service" : "ad-hoc",
       };
     }
   } catch {

package/src/cli/init.ts

@@ -435,26 +435,40 @@ export async function detectExistingSetup(
   let searchProvider: SearchProvider = "keyword";
 
   for (const env of envs) {
-    if (env.mcpWire?.method !== "json") continue;
-    let text: string;
-    try {
-      text = await fs.readFile(env.mcpWire.path, "utf8");
-    } catch {
+    if (env.mcpWire === null) continue;
+
+    if (env.mcpWire.method === "json") {
+      let text: string;
+      try {
+        text = await fs.readFile(env.mcpWire.path, "utf8");
+      } catch {
+        continue;
+      }
+      let parsed: Record<string, unknown>;
+      try {
+        parsed = JSON.parse(text) as Record<string, unknown>;
+      } catch {
+        continue;
+      }
+      const servers = parsed[env.mcpWire.key] as Record<string, unknown> | undefined;
+      if (!servers || !("krimto" in servers)) continue;
+      registeredEditors.push(env.editor);
+      const krimto = servers.krimto as { env?: Record<string, string> };
+      if (krimto.env?.KRIMTO_EMBED_PROVIDER === "openai") {
+        searchProvider = "openai";
+      }
       continue;
     }
-    let parsed: Record<string, unknown>;
-    try {
-      parsed = JSON.parse(text) as Record<string, unknown>;
-    } catch {
+
+    // v0.2.26 — Gap-3 root-cause fix. Claude Code uses `claude mcp` CLI; the registration
+    // doesn't live in a JSON file we scan. Without this branch every read-side surface
+    // (reconfigure menu, status, reset, whoami) was invisibly mis-reporting "Cursor only"
+    // even after the wizard had successfully wired both Cursor AND Claude Code.
+    if (env.mcpWire.method === "cli") {
+      const present = await isClaudeMcpRegistered(env.mcpWire.command);
+      if (present) registeredEditors.push(env.editor);
       continue;
     }
-    const servers = parsed[env.mcpWire.key] as Record<string, unknown> | undefined;
-    if (!servers || !("krimto" in servers)) continue;
-    registeredEditors.push(env.editor);
-    const krimto = servers.krimto as { env?: Record<string, string> };
-    if (krimto.env?.KRIMTO_EMBED_PROVIDER === "openai") {
-      searchProvider = "openai";
-    }
   }
 
   const service = await isServiceInstalled(undefined, homeDir);
@@ -468,6 +482,21 @@ export async function detectExistingSetup(
   };
 }
 
+/**
+ * Check whether `claude mcp list` knows about krimto. Best-effort: any error (CLI missing,
+ * timeout, parse failure) returns false rather than blocking the caller. The output format
+ * is one server per line, "<name>:<space><url-or-spec>" — we just look for "krimto:" with a
+ * non-failing line, which covers both stdio (`krimto: npx -y ...`) and HTTP (`krimto: http://...`).
+ */
+async function isClaudeMcpRegistered(claudeBinary: string): Promise<boolean> {
+  try {
+    const { stdout } = await exec(claudeBinary, ["mcp", "list"], { timeout: 8000 });
+    return /^krimto:\s/m.test(stdout);
+  } catch {
+    return false;
+  }
+}
+
 // === Legacy runInit (v0.2.16, kept for --all / --minimal back-compat) ======
 
 export interface RunInitOptions {

package/src/cli/inspectRuntime.ts

@@ -0,0 +1,146 @@
+// v0.2.26 — single reconciled view of "what is Krimto doing right now". Replaces the prior
+// ad-hoc detection scattered across status.ts, verifyConnection.ts, whoami.ts, and the
+// wizard's reconfigure menu, which disagreed in the smoke-6 transcript audit:
+//   • Cursor mcp.json had krimto, Claude Code's `claude mcp` had krimto, launchctl showed
+//     the service loaded — but reconfigure menu said "Editors: Cursor", verify-connection
+//     said "Launched by: ad-hoc", and reset said "No changes made".
+//
+// `inspectRuntime` reads every source we care about and reconciles them. Downstream
+// commands consume one consistent view instead of running their own subset of checks.
+
+import { promises as fs } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { isProcessAlive, type LaunchedBy, type LockInfo, type LockMode } from "../server/lock";
+import {
+  detectEditorEnvironments,
+  detectExistingSetup,
+  type EditorKind,
+  type RunMode,
+  type SearchProvider,
+  type SetupSnapshot,
+} from "./init";
+import { probeServiceState } from "./service";
+
+export interface RuntimeLock {
+  pid: number;
+  started: string;
+  mode: LockMode;
+  /**
+   * The lock file's own `launchedBy` value. Pre-v0.2.25 processes didn't write this field,
+   * so we default to "ad-hoc". The reconciled answer (correct even for pre-v0.2.25 runs)
+   * is in {@link RuntimeState.effectiveLaunchedBy}.
+   */
+  launchedBy: LaunchedBy;
+  alive: boolean;
+}
+
+export interface RuntimeService {
+  installed: boolean;
+  loaded: boolean;
+  runningPid: number | null;
+  unitPath: string | undefined;
+}
+
+export interface RuntimeState {
+  /** Lock file state (parsed + alive-check), or null when no readable lock. */
+  lock: RuntimeLock | null;
+  /** Cross-platform service probe (unit-on-disk + actually-loaded + running PID). */
+  service: RuntimeService;
+  /**
+   * Reconciled launch source. Trusts launchctl/systemctl over the lock file: if the
+   * running PID matches the service's `runningPid`, the process IS service-launched,
+   * even when the lock file lacks the `launchedBy` field (pre-v0.2.25 runs).
+   */
+  effectiveLaunchedBy: LaunchedBy | null;
+  /** Snapshot from detectExistingSetup (registered editors, run mode, search provider). */
+  snapshot: SetupSnapshot;
+  /** Detected editor environments (all 4, with present/installed flags). */
+  editors: Awaited<ReturnType<typeof detectEditorEnvironments>>;
+  /** Editors registered with Krimto right now. Same as snapshot.registeredEditors. */
+  registeredEditors: EditorKind[];
+  /** Convenience: the configured run mode (always-running iff a service unit exists). */
+  runMode: RunMode;
+  /** Convenience: the configured search provider. */
+  searchProvider: SearchProvider;
+}
+
+export interface InspectOptions {
+  cwd?: string;
+  homeDir?: string;
+}
+
+/**
+ * Build a single, reconciled {@link RuntimeState}. Cheap enough to call from every read-side
+ * command (one fs read for lock, one launchctl/systemctl print, one `claude mcp list`, one
+ * pass over editor MCP configs).
+ */
+export async function inspectRuntime(dataDir: string, opts: InspectOptions = {}): Promise<RuntimeState> {
+  const cwd = opts.cwd ?? process.cwd();
+  const homeDir = opts.homeDir ?? os.homedir();
+
+  const lock = await readLock(dataDir);
+  const snapshot = await detectExistingSetup(cwd, homeDir);
+  const editors = await detectEditorEnvironments(cwd, homeDir);
+  const service = await probeServiceState(undefined, homeDir);
+
+  // The reconciliation step. Two signals:
+  //   1. The lock file's self-reported launchedBy (pre-v0.2.25 runs default to "ad-hoc").
+  //   2. Whether the running PID matches launchd's program-PID.
+  // If (2) says yes, we know the process was service-launched regardless of what (1) claims.
+  let effectiveLaunchedBy: LaunchedBy | null = null;
+  if (lock && lock.alive) {
+    if (service.loaded && service.runningPid === lock.pid) {
+      effectiveLaunchedBy = "service";
+    } else {
+      effectiveLaunchedBy = lock.launchedBy;
+    }
+  }
+
+  return {
+    lock,
+    service: {
+      installed: service.unitPresent,
+      loaded: service.loaded,
+      runningPid: service.runningPid,
+      unitPath: undefined, // service.ts's isServiceInstalled returns this; we don't surface it in v0.2.26
+    },
+    effectiveLaunchedBy,
+    snapshot,
+    editors,
+    registeredEditors: snapshot.registeredEditors,
+    runMode: snapshot.runMode,
+    searchProvider: snapshot.searchProvider,
+  };
+}
+
+async function readLock(dataDir: string): Promise<RuntimeLock | null> {
+  const file = path.join(dataDir, ".krimto", "lock.json");
+  let raw: string;
+  try {
+    raw = await fs.readFile(file, "utf8");
+  } catch {
+    return null;
+  }
+  let parsed: Partial<LockInfo>;
+  try {
+    parsed = JSON.parse(raw) as Partial<LockInfo>;
+  } catch {
+    return null;
+  }
+  if (
+    typeof parsed.pid !== "number" ||
+    typeof parsed.started !== "string" ||
+    (parsed.mode !== "stdio" && parsed.mode !== "http")
+  ) {
+    return null;
+  }
+  return {
+    pid: parsed.pid,
+    started: parsed.started,
+    mode: parsed.mode,
+    launchedBy: parsed.launchedBy === "service" ? "service" : "ad-hoc",
+    alive: isProcessAlive(parsed.pid),
+  };
+}

package/src/cli/reindex.ts

@@ -32,6 +32,7 @@ async function checkLock(dataDir: string): Promise<LockInfo | null> {
         pid: parsed.pid,
         started: typeof parsed.started === "string" ? parsed.started : "unknown",
         mode: (parsed.mode as LockInfo["mode"]) ?? "stdio",
+        launchedBy: parsed.launchedBy === "service" ? "service" : "ad-hoc",
       };
     }
   } catch {

package/src/cli/reset.ts

@@ -20,17 +20,12 @@ import * as path from "node:path";
 import { removeRule } from "../agentRule";
 import {
   detectEditorEnvironments,
-  detectExistingSetup,
   type EditorEnvironment,
   type EditorKind,
 } from "./init";
 import { removeMcpConfig } from "./mcpConfig";
 import { defaultIO, isExitPrompt, type WizardIO } from "./promptHelpers";
-import {
-  detectPlatform,
-  isServiceInstalled,
-  uninstallService,
-} from "./service";
+import { detectPlatform, uninstallService } from "./service";
 
 const EDITOR_LABEL: Record<EditorKind, string> = {
   cursor: "Cursor",
@@ -65,33 +60,52 @@ export async function applyReset(opts: ResetOptions = {}): Promise<ResetResult>
   const homeDir = opts.homeDir;
   const dataDir = opts.dataDir ?? path.join(homeDir ?? "", ".krimto");
 
-  // 1. Disconnect every detected editor.
+  // v0.2.26 — reset is now "always sweep, never trust detection". The smoke-6 transcript
+  // caught reset reporting "No changes made" while a service was actually loaded and
+  // Cursor's mcp.json still had a krimto entry: detection was wrong (Claude Code was
+  // invisible to CLI-method scans), so reset's gated-by-detection cleanup ran nothing.
+  // Now every cleanup path runs best-effort regardless of what detection thinks. We can
+  // distinguish "ran but found nothing" from "intentionally skipped" by inspecting the
+  // result type — `editorsDisconnected` only includes editors whose removeMcpConfig
+  // returned removed=true, so an empty list still means "nothing to remove" cleanly.
+
   const envs = await detectEditorEnvironments(cwd, homeDir);
-  const snapshot = await detectExistingSetup(cwd, homeDir);
+
+  // 1. Try to disconnect every editor we know about, regardless of what detection says.
+  //    removeMcpConfig is already idempotent — it returns removed=false if there was nothing
+  //    to remove, so blanket-running it is safe.
   const editorsDisconnected: EditorKind[] = [];
   for (const env of envs) {
-    if (!snapshot.registeredEditors.includes(env.editor)) continue;
     const res = await removeMcpConfig(env);
     if (res.removed) editorsDisconnected.push(env.editor);
   }
 
-  // 2. Strip the standing rule from each detected rule file in CWD.
+  // 2. Strip the standing rule from each detected rule file in CWD (already idempotent).
   const rulesStripped: string[] = [];
   for (const env of envs) {
     const stripped = await stripRule(cwd, env);
     if (stripped) rulesStripped.push(env.rulesPath);
   }
 
-  // 3. Uninstall the background service if installed.
+  // 3. Uninstall the background service ALWAYS (even if isServiceInstalled said no). The
+  //    inner uninstall is best-effort: the platform CLI errors when nothing's loaded, but
+  //    we swallow them. This catches the case where a stale plist exists without an active
+  //    launchctl entry (or vice versa) — both halves get cleaned in one pass.
   const platform = detectPlatform();
-  const current = await isServiceInstalled(platform, homeDir);
   let serviceRemoved = false;
-  if (current.installed) {
+  try {
     const res = await uninstallService({ dryRun: opts.dryRun, platform, homeDir });
     serviceRemoved = res.removed;
+  } catch {
+    /* uninstall path can throw on unsupported platforms or missing CLIs — we're sweeping, not validating */
   }
 
-  // 4. Wipe the keys store (best-effort — file may not exist).
+  // 4. Kill any live ad-hoc Krimto process holding the lock — otherwise a `krimto serve`
+  //    that's still running keeps the data dir busy and the next init will conflict on the
+  //    lock. Best-effort: SIGTERM, give it 500ms, SIGKILL if still alive.
+  await terminateLockHolder(dataDir);
+
+  // 5. Wipe the keys store (best-effort — file may not exist).
   const keysPath = path.join(dataDir, ".krimto", "keys.json");
   let keysWiped = false;
   try {
@@ -101,6 +115,15 @@ export async function applyReset(opts: ResetOptions = {}): Promise<ResetResult>
     /* no keys file — fine */
   }
 
+  // 6. Wipe the lock file itself so the next init starts from a known-clean slate. Without
+  //    this, a stale lock from a process we just killed can confuse subsequent commands.
+  const lockPath = path.join(dataDir, ".krimto", "lock.json");
+  try {
+    await fs.unlink(lockPath);
+  } catch {
+    /* no lock — fine */
+  }
+
   // 5. Optionally move the data dir to a timestamped trash sibling.
   let notesTrashedTo: string | undefined;
   if (opts.wipeNotes) {
@@ -177,6 +200,37 @@ export async function runReset(opts: ResetOptions = {}): Promise<ResetResult | n
   }
 }
 
+/**
+ * If the lock file points at a live PID, send SIGTERM then SIGKILL (after 500ms). Best-effort;
+ * we don't return the outcome because reset's contract is "do the cleanup, don't validate".
+ * v0.2.26 — without this step, a leftover `krimto serve` PID survived `reset` and the next
+ * init would either reuse the dead lock OR conflict on the live port (whichever came first).
+ */
+async function terminateLockHolder(dataDir: string): Promise<void> {
+  const lockPath = path.join(dataDir, ".krimto", "lock.json");
+  let pid: number | null = null;
+  try {
+    const raw = await fs.readFile(lockPath, "utf8");
+    const parsed = JSON.parse(raw) as { pid?: unknown };
+    if (typeof parsed.pid === "number" && parsed.pid > 0) pid = parsed.pid;
+  } catch {
+    return; // no lock — nothing to terminate
+  }
+  if (pid === null) return;
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch {
+    return; // already gone
+  }
+  await new Promise((resolve) => setTimeout(resolve, 500));
+  try {
+    process.kill(pid, 0); // existence probe
+    process.kill(pid, "SIGKILL");
+  } catch {
+    /* exited cleanly on SIGTERM */
+  }
+}
+
 async function stripRule(cwd: string, env: EditorEnvironment): Promise<boolean> {
   const rulePath = path.join(cwd, env.rulesPath);
   let existing: string;

package/src/cli/service.ts

@@ -21,6 +21,7 @@
 
 import { execFile } from "node:child_process";
 import { promises as fs } from "node:fs";
+import * as net from "node:net";
 import * as os from "node:os";
 import * as path from "node:path";
 import { promisify } from "node:util";
@@ -55,6 +56,16 @@ export interface InstallResult {
   activateCommand?: { command: string; args: string[] };
   /** True when the platform CLI was actually executed (false in dry-run mode). */
   activated: boolean;
+  /**
+   * v0.2.27 — only meaningful when `activated: true` and the service config sets
+   * `KRIMTO_HTTP_PORT`. `true` = TCP connection to `localhost:<port>` was accepted before
+   * we returned, so the server is actually serving and clients (Cursor / Claude Code) won't
+   * hit ECONNREFUSED if they reconnect immediately. `false` = the probe timed out; the
+   * service IS installed and launchd reports it running, but the server hasn't bound the
+   * port — usually a misconfig surfaced in the stderr log file. `undefined` = no probe ran
+   * (dry run, stdio mode, or no HTTP port in the env block).
+   */
+  portReady?: boolean;
 }
 
 export interface UninstallResult {
@@ -74,6 +85,14 @@ export interface ServiceOptions {
    * CI runner without `process.platform` rewiring.
    */
   platform?: ServicePlatform;
+  /**
+   * v0.2.27 — dependency-injected port probe. Default uses real `net.connect`. Tests pass
+   * a stub that resolves immediately (so they don't open real TCP sockets). When omitted,
+   * `installService` polls `localhost:<KRIMTO_HTTP_PORT>` until accept or `probeTimeoutMs`.
+   */
+  probePort?: (port: number) => Promise<boolean>;
+  /** Maximum time (ms) to wait for the HTTP port to start accepting connections. Default 10000. */
+  probeTimeoutMs?: number;
 }
 
 /** Map `process.platform` → the four service flavors Krimto knows about. */
@@ -120,6 +139,70 @@ export async function isServiceInstalled(
   }
 }
 
+/**
+ * v0.2.26 — richer probe than {@link isServiceInstalled}. Distinguishes three states the
+ * smoke-6 transcript proved we needed:
+ *   • `unitPresent: true, loaded: false`    — plist on disk but not bootstrapped (failed install left over)
+ *   • `unitPresent: true, loaded: true`     — fully active service
+ *   • `unitPresent: false, loaded: false`   — clean machine (or service was uninstalled)
+ *
+ * Also returns the PID launchd is currently running, so the caller can correlate it against
+ * the lock file — when the running Krimto PID equals launchd's `pid`, the process IS the
+ * service-launched one, even if its lock file is missing the `launchedBy` field (because the
+ * process started under an old version).
+ */
+export async function probeServiceState(
+  platform: ServicePlatform = detectPlatform(),
+  homeDir: string = os.homedir(),
+): Promise<{
+  platform: ServicePlatform;
+  unitPresent: boolean;
+  loaded: boolean;
+  runningPid: number | null;
+}> {
+  const base = await isServiceInstalled(platform, homeDir);
+  const unitPresent = base.installed;
+
+  if (platform === "darwin") {
+    const uid = process.getuid?.() ?? 501;
+    try {
+      const { stdout } = await exec("launchctl", ["print", `gui/${uid}/${SERVICE_LABEL}`]);
+      const pidMatch = stdout.match(/\bpid\s*=\s*(\d+)/);
+      const pid = pidMatch && pidMatch[1] ? Number.parseInt(pidMatch[1], 10) : null;
+      return { platform, unitPresent, loaded: true, runningPid: pid };
+    } catch {
+      return { platform, unitPresent, loaded: false, runningPid: null };
+    }
+  }
+  if (platform === "linux") {
+    try {
+      // `systemctl --user is-active <name>` exits 0 with "active" when running.
+      const { stdout } = await exec("systemctl", ["--user", "is-active", SERVICE_NAME]);
+      const active = stdout.trim() === "active";
+      if (!active) return { platform, unitPresent, loaded: false, runningPid: null };
+      // Best-effort PID lookup.
+      try {
+        const { stdout: pidOut } = await exec("systemctl", ["--user", "show", "--property=MainPID", "--value", SERVICE_NAME]);
+        const pid = Number.parseInt(pidOut.trim(), 10);
+        return { platform, unitPresent, loaded: true, runningPid: Number.isFinite(pid) && pid > 0 ? pid : null };
+      } catch {
+        return { platform, unitPresent, loaded: true, runningPid: null };
+      }
+    } catch {
+      return { platform, unitPresent, loaded: false, runningPid: null };
+    }
+  }
+  if (platform === "win32") {
+    try {
+      await exec("schtasks", ["/Query", "/TN", SERVICE_NAME]);
+      return { platform, unitPresent: true, loaded: true, runningPid: null };
+    } catch {
+      return { platform, unitPresent: false, loaded: false, runningPid: null };
+    }
+  }
+  return { platform, unitPresent: false, loaded: false, runningPid: null };
+}
+
 /**
  * Install the service for the current platform. Writes the unit file (where applicable) and
  * activates the service via the platform's CLI. Pass `opts.dryRun=true` to skip activation
@@ -132,14 +215,82 @@ export async function installService(
   const platform = opts.platform ?? detectPlatform();
   const homeDir = config.homeDir ?? os.homedir();
 
-  if (platform === "darwin") return installLaunchd(config, homeDir, opts);
-  if (platform === "linux") return installSystemd(config, homeDir, opts);
-  if (platform === "win32") return installSchtasks(config, opts);
+  // v0.2.25 — Gap 8 provenance. Every service-launched Krimto stamps `launchedBy: "service"`
+  // into its lock file. We inject the marker env var here (vs every caller remembering to)
+  // so the wizard, the `service` shortcut, and any future installer share the same shape.
+  const configWithMarker: ServiceConfig = {
+    ...config,
+    env: { KRIMTO_LAUNCHED_BY: "service", ...(config.env ?? {}) },
+  };
+
+  let result: InstallResult;
+  if (platform === "darwin") {
+    result = await installLaunchd(configWithMarker, homeDir, opts);
+  } else if (platform === "linux") {
+    result = await installSystemd(configWithMarker, homeDir, opts);
+  } else if (platform === "win32") {
+    result = await installSchtasks(configWithMarker, opts);
+  } else {
+    throw new Error(
+      `Krimto's "Always running" mode isn't supported on platform "${process.platform}" yet. ` +
+        `Use "As needed" mode (the wizard default) or run \`krimto serve\` manually.`,
+    );
+  }
 
-  throw new Error(
-    `Krimto's "Always running" mode isn't supported on platform "${process.platform}" yet. ` +
-      `Use "As needed" mode (the wizard default) or run \`krimto serve\` manually.`,
-  );
+  // v0.2.27 — port-readiness probe. The smoke-6 transcript showed Cursor failing with
+  // ECONNREFUSED in the ~3-second window between launchd accepting the bootstrap and the
+  // Node process actually binding the HTTP port. The wizard's "Background service installed
+  // and started" line ran during that window, so users restarted their editor right when
+  // the port was still unbound. Now we wait for the port to accept a TCP connection before
+  // returning success; if it doesn't come up within `probeTimeoutMs`, the wizard surfaces
+  // the warning instead of giving false confidence.
+  if (result.activated && !opts.dryRun) {
+    const portStr = configWithMarker.env?.KRIMTO_HTTP_PORT;
+    const port = portStr ? Number.parseInt(portStr, 10) : NaN;
+    if (Number.isFinite(port) && port > 0) {
+      const probe = opts.probePort ?? defaultPortProbe;
+      result.portReady = await waitForPort(port, probe, opts.probeTimeoutMs ?? 10000);
+    }
+  }
+  return result;
+}
+
+/**
+ * Poll the port via the injected probe every 250ms until it accepts or the timeout elapses.
+ * Returns true on first successful connect, false on timeout. v0.2.27.
+ */
+async function waitForPort(
+  port: number,
+  probe: (port: number) => Promise<boolean>,
+  timeoutMs: number,
+): Promise<boolean> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (await probe(port)) return true;
+    await new Promise((r) => setTimeout(r, 250));
+  }
+  return false;
+}
+
+/**
+ * Real port probe: open a TCP socket to 127.0.0.1:<port>, resolve true on `connect`, false on
+ * error or 500ms timeout. The probe itself is cheap (kernel-level connect refusal), so a tight
+ * 250ms poll loop over a 10s window is fine.
+ */
+async function defaultPortProbe(port: number): Promise<boolean> {
+  return new Promise<boolean>((resolve) => {
+    const socket = net.connect({ port, host: "127.0.0.1" });
+    let done = false;
+    const finish = (ok: boolean): void => {
+      if (done) return;
+      done = true;
+      socket.destroy();
+      resolve(ok);
+    };
+    socket.once("connect", () => finish(true));
+    socket.once("error", () => finish(false));
+    socket.setTimeout(500, () => finish(false));
+  });
 }
 
 /** Uninstall the service. Removes the unit file + invokes the platform CLI to deactivate it. */
@@ -212,6 +363,31 @@ async function installLaunchd(
   if (opts.dryRun) {
     return { platform: "darwin", unitPath, unitContents, activateCommand, activated: false };
   }
+  // v0.2.26 — supersedes the v0.2.23 bootout+bootstrap pattern. The previous fix raced
+  // against launchd's still-tearing-down state: `launchctl bootout` returns when the unload
+  // is QUEUED, not when it completes, so the subsequent `bootstrap` could still hit EIO.
+  // Correct pattern:
+  //   • If the service is currently loaded → `launchctl kickstart -k gui/<uid>/<label>`
+  //     atomically kills + restarts the running process. Because we already overwrote the
+  //     plist above, the new process starts with the latest env / argv.
+  //   • If the service is NOT loaded → plain `bootstrap`. No race possible.
+  // `launchctl print` returning exit-0 is the canonical "is it loaded" probe.
+  const printRes = await exec("launchctl", ["print", `gui/${uid}/${SERVICE_LABEL}`]).then(
+    () => ({ loaded: true }),
+    () => ({ loaded: false }),
+  );
+  if (printRes.loaded) {
+    // Kickstart -k: send SIGTERM, wait for clean exit, then restart from the plist on disk.
+    // launchctl returns from kickstart only AFTER the new process is up, so no follow-on race.
+    await exec("launchctl", ["kickstart", "-k", `gui/${uid}/${SERVICE_LABEL}`]);
+    return {
+      platform: "darwin",
+      unitPath,
+      unitContents,
+      activateCommand: { command: "launchctl", args: ["kickstart", "-k", `gui/${uid}/${SERVICE_LABEL}`] },
+      activated: true,
+    };
+  }
   await exec(activateCommand.command, activateCommand.args);
   return { platform: "darwin", unitPath, unitContents, activateCommand, activated: true };
 }

package/src/cli/status.ts

@@ -16,14 +16,14 @@ import * as path from "node:path";
 import { promisify } from "node:util";
 
 import { ActivityLog, type ActivityEntry } from "../server/activity";
-import { isProcessAlive, type LockInfo } from "../server/lock";
+import { type LockInfo } from "../server/lock";
 import { KRIMTO_VERSION } from "../server/index";
 import {
   detectEditorEnvironments,
-  detectExistingSetup,
   type EditorKind,
   type SetupSnapshot,
 } from "./init";
+import { inspectRuntime } from "./inspectRuntime";
 
 const exec = promisify(execFile);
 
@@ -66,9 +66,13 @@ export async function runStatus(
   const homeDir = opts.homeDir ?? os.homedir();
   const now = opts.now ?? new Date();
 
-  const snapshot = await detectExistingSetup(cwd, homeDir);
-  const envs = await detectEditorEnvironments(cwd, homeDir);
-  const lock = await readLock(dataDir);
+  // v0.2.26 — single source of truth. status used to read 4 sources separately and the
+  // results disagreed (smoke-6 transcript). Now everything flows through inspectRuntime,
+  // which reconciles lock + launchctl + editor configs into one consistent view.
+  const runtime = await inspectRuntime(dataDir, { cwd, homeDir });
+  const snapshot = runtime.snapshot;
+  const envs = runtime.editors;
+  const lock = runtime.lock ? { info: { pid: runtime.lock.pid, started: runtime.lock.started, mode: runtime.lock.mode, launchedBy: runtime.lock.launchedBy }, alive: runtime.lock.alive } : null;
   const log = new ActivityLog(dataDir);
   const recent = await log.tail(5);
   const stats = await log.stats(5 * 60 * 1000, now);
@@ -76,7 +80,7 @@ export async function runStatus(
   const gitInfo = await readGitInfo(dataDir);
 
   const overall = pickOverall(snapshot, lock, stats);
-  const header = headerLine(overall, lock, now);
+  const header = headerLine(overall, lock, runtime.effectiveLaunchedBy, now);
 
   const connectionsBlock = renderConnections(envs, snapshot, recent);
   const storageBlock = renderStorage(dataDir, gitInfo, indexStats);
@@ -99,24 +103,6 @@ export async function runStatus(
 
 // === Helpers ===============================================================
 
-async function readLock(dataDir: string): Promise<{ info: LockInfo; alive: boolean } | null> {
-  try {
-    const raw = await fs.readFile(path.join(dataDir, ".krimto", "lock.json"), "utf8");
-    const parsed = JSON.parse(raw) as Partial<LockInfo>;
-    if (
-      typeof parsed.pid === "number" &&
-      typeof parsed.started === "string" &&
-      (parsed.mode === "stdio" || parsed.mode === "http")
-    ) {
-      const info: LockInfo = { pid: parsed.pid, started: parsed.started, mode: parsed.mode };
-      return { info, alive: isProcessAlive(info.pid) };
-    }
-  } catch {
-    /* no lock file */
-  }
-  return null;
-}
-
 async function readIndexStats(dataDir: string): Promise<{ exists: boolean; modified?: Date }> {
   try {
     const s = await fs.stat(path.join(dataDir, "index.db"));
@@ -171,11 +157,12 @@ function pickOverall(
 function headerLine(
   status: "ok" | "warning" | "error",
   lock: { info: LockInfo; alive: boolean } | null,
+  effectiveLaunchedBy: import("./inspectRuntime").RuntimeState["effectiveLaunchedBy"],
   now: Date,
 ): string {
   if (status === "ok") {
     if (lock?.alive) {
-      return `\n✅ Krimto is working · v${KRIMTO_VERSION}\n   PID ${lock.info.pid} (${lock.info.mode}), started ${humanAgo(lock.info.started, now)}\n`;
+      return `\n✅ Krimto is working · v${KRIMTO_VERSION}\n   PID ${lock.info.pid} (${lock.info.mode}, ${effectiveLaunchedBy ?? lock.info.launchedBy}), started ${humanAgo(lock.info.started, now)}\n`;
     }
     return `\n✅ Krimto is configured · v${KRIMTO_VERSION}\n   No active server right now — it will be launched on demand by your editor.\n`;
   }

package/src/cli/usage.ts

@@ -13,6 +13,7 @@ const EXPECTED: readonly string[] = [
   "krimto_read",
   "krimto_supersede",
   "krimto_list_scopes",
+  "krimto_whoami",
 ];
 if (MCP_TOOL_NAMES.length !== EXPECTED.length || MCP_TOOL_NAMES.some((t, i) => t !== EXPECTED[i])) {
   throw new Error("src/cli/usage.ts examples are out of sync with src/server/connect.ts MCP_TOOL_NAMES");
@@ -24,13 +25,14 @@ export function formatUsage(version: string): string {
     "",
     `✅ How to use Krimto (v${version})`,
     "",
-    "━━ The 5 tools ━━",
+    "━━ The 6 tools ━━",
     "",
     "  krimto_write        Save a fact",
     "  krimto_recall       Search facts",
     "  krimto_read         Open one fact by id",
     "  krimto_supersede    Replace a fact with a new version (old kept in git)",
     "  krimto_list_scopes  See which scopes you can read",
+    "  krimto_whoami       Ask Krimto which identity you're writing as (and your scopes)",
     "",
     "━━ DEFAULT MODE — explicit (\"use krimto to ...\") ━━",
     "",

package/src/cli/verifyConnection.ts

@@ -8,6 +8,7 @@ import { promises as fs } from "node:fs";
 import * as path from "node:path";
 
 import { ActivityLog, type ActivityEntry } from "../server/activity";
+import { inspectRuntime } from "./inspectRuntime";
 import { isProcessAlive, type LockInfo } from "../server/lock";
 
 export interface VerifyConnectionResult {
@@ -39,7 +40,12 @@ export async function runVerifyConnection(dataDir: string, now: Date = new Date(
     const raw = await fs.readFile(lockPath, "utf8");
     const parsed = JSON.parse(raw) as Partial<LockInfo>;
     if (typeof parsed.pid === "number" && typeof parsed.started === "string" && (parsed.mode === "stdio" || parsed.mode === "http")) {
-      lock = { pid: parsed.pid, started: parsed.started, mode: parsed.mode };
+      lock = {
+        pid: parsed.pid,
+        started: parsed.started,
+        mode: parsed.mode,
+        launchedBy: parsed.launchedBy === "service" ? "service" : "ad-hoc",
+      };
     } else {
       lockMalformed = true;
     }
@@ -56,12 +62,22 @@ export async function runVerifyConnection(dataDir: string, now: Date = new Date(
   let header: string;
   if (lock && isProcessAlive(lock.pid)) {
     status = "running";
+    // v0.2.26 — reconcile the lock's self-reported launchedBy against launchctl's actual
+    // state. Without this, a pre-v0.2.25 service-launched process reports "ad-hoc" because
+    // its lock file was written before the field existed.
+    const runtime = await inspectRuntime(dataDir);
+    const effective = runtime.effectiveLaunchedBy ?? lock.launchedBy;
+    const launchedByLabel =
+      effective === "service"
+        ? "service (launchd/systemd/schtasks — survives reboot)"
+        : "ad-hoc (started by `krimto serve` or an editor's stdio launcher)";
     header =
       `\n🟢 Krimto running\n` +
-      `   PID:     ${lock.pid}\n` +
-      `   Mode:    ${lock.mode}\n` +
-      `   Started: ${humanAgo(lock.started, now)}\n` +
-      `   Data:    ${dataDir}\n`;
+      `   PID:        ${lock.pid}\n` +
+      `   Mode:       ${lock.mode}\n` +
+      `   Started:    ${humanAgo(lock.started, now)}\n` +
+      `   Launched by: ${launchedByLabel}\n` +
+      `   Data:       ${dataDir}\n`;
   } else if (lock) {
     status = "stale";
     header =

package/src/cli/wizard.ts

@@ -357,11 +357,22 @@ function printApplyResult(res: ApplyResult, io: WizardIO): void {
     }
   }
   if (res.serviceInstall) {
-    io.out(
-      res.serviceInstall.activated
-        ? `  ✓ Background service installed and started (${res.serviceInstall.platform})\n`
-        : `  ✓ Background service configured (${res.serviceInstall.platform}; dry-run)\n`,
-    );
+    if (!res.serviceInstall.activated) {
+      io.out(`  ✓ Background service configured (${res.serviceInstall.platform}; dry-run)\n`);
+    } else if (res.serviceInstall.portReady === false) {
+      // v0.2.27 — install succeeded but the HTTP port didn't come up within the probe
+      // window. Editors that auto-reconnect on MCP-config change will hit ECONNREFUSED.
+      // Surface the warning + pointer to the log file instead of giving false confidence.
+      io.out(
+        `  ⚠ Background service installed (${res.serviceInstall.platform}) but the HTTP port\n` +
+          `    didn't come up within 10s. Check /tmp/com.krimto.server.err.log for boot errors.\n` +
+          `    Editors may fail to connect until the server binds the port.\n`,
+      );
+    } else {
+      // portReady === true OR undefined (no HTTP port configured — stdio-only install).
+      const readinessNote = res.serviceInstall.portReady === true ? " · port accepting connections" : "";
+      io.out(`  ✓ Background service installed and started (${res.serviceInstall.platform})${readinessNote}\n`);
+    }
   }
   if (res.embeddingsConfigured) io.out("  ✓ Semantic search enabled (OpenAI)\n");
   // Tell the user where their data will live. The folder itself is created lazily on first save,
@@ -388,7 +399,10 @@ function printApplyResult(res: ApplyResult, io: WizardIO): void {
     }
   }
 
-  io.out("Restart your editor once so it picks up the new rule.\n");
+  io.out(
+    "Restart your editor once so it loads the new MCP server (the krimto_*\n" +
+      "tools won't appear in chat until you do) and picks up the standing rule.\n",
+  );
 }
 
 function printRefreshSummary(res: ApplyResult, io: WizardIO): void {

package/src/server/connect.ts

@@ -74,13 +74,14 @@ export function cursorDeeplink(host: string): string {
   return `cursor://anysphere.cursor-deeplink/mcp/install?name=krimto&config=${config}`;
 }
 
-/** The five MCP tools Krimto exposes (kept in lockstep with src/server/index.ts registrations). */
+/** The six MCP tools Krimto exposes (kept in lockstep with src/server/index.ts registrations). */
 export const MCP_TOOL_NAMES = [
   "krimto_write",
   "krimto_recall",
   "krimto_read",
   "krimto_supersede",
   "krimto_list_scopes",
+  "krimto_whoami",
 ] as const;
 
 /** The transport-level contract for wiring up any MCP client we haven't shipped a verified snippet for. */

package/src/server/index.ts

@@ -41,6 +41,7 @@ import {
   krimtoRead,
   krimtoRecall,
   krimtoSupersede,
+  krimtoWhoami,
   krimtoWrite,
   type ToolContext,
 } from "./tools";
@@ -48,7 +49,7 @@ import { type Requester } from "../access/scope";
 
 export type RequesterResolver = (extra: { authInfo?: AuthInfo }) => Requester;
 
-export const KRIMTO_VERSION = "0.2.22";
+export const KRIMTO_VERSION = "0.2.27";
 
 export function resolveDataDir(): string {
   return process.env.KRIMTO_DATA ?? path.join(homedir(), ".krimto");
@@ -192,6 +193,24 @@ export function buildServer(ctx: ToolContext, resolveRequester?: RequesterResolv
     },
   );
 
+  server.registerTool(
+    "krimto_whoami",
+    {
+      description:
+        "Report the caller's identity plus the scopes they can read and write. Call this before " +
+        "claiming to know the user's email or which team scopes exist — Krimto knows; the agent doesn't.",
+      inputSchema: {},
+    },
+    async (_args, extra) => {
+      try {
+        const requester = resolveRequester ? resolveRequester(extra) : ctx.requester;
+        return ok(await krimtoWhoami({ ...ctx, requester }));
+      } catch (e) {
+        return fail(e);
+      }
+    },
+  );
+
   return server;
 }
 

package/src/server/lock.ts

@@ -16,11 +16,19 @@ import { promises as fs } from "node:fs";
 import * as path from "node:path";
 
 export type LockMode = "stdio" | "http";
+/**
+ * How this Krimto process was launched. "service" = via launchd / systemd / schtasks (the
+ * always-running setup); "ad-hoc" = direct invocation (`krimto serve`, editor-spawned stdio,
+ * tests). The service installers inject KRIMTO_LAUNCHED_BY=service into the unit env, so this
+ * field is just `process.env.KRIMTO_LAUNCHED_BY` at acquire time with a safe default.
+ */
+export type LaunchedBy = "service" | "ad-hoc";
 
 export interface LockInfo {
   pid: number;
   started: string;
   mode: LockMode;
+  launchedBy: LaunchedBy;
 }
 
 export interface LockHandle {
@@ -73,6 +81,7 @@ export async function acquireLock(dataDir: string, mode: LockMode): Promise<Lock
           pid: existing.pid,
           started: typeof existing.started === "string" ? existing.started : "unknown",
           mode: (existing.mode as LockMode) ?? "stdio",
+          launchedBy: existing.launchedBy === "service" ? "service" : "ad-hoc",
         },
         file,
       );
@@ -83,7 +92,8 @@ export async function acquireLock(dataDir: string, mode: LockMode): Promise<Lock
     // File missing / unreadable / malformed — treat as no lock and continue.
   }
 
-  const info: LockInfo = { pid: process.pid, started: new Date().toISOString(), mode };
+  const launchedBy: LaunchedBy = process.env.KRIMTO_LAUNCHED_BY === "service" ? "service" : "ad-hoc";
+  const info: LockInfo = { pid: process.pid, started: new Date().toISOString(), mode, launchedBy };
   await fs.writeFile(file, JSON.stringify(info, null, 2), "utf8");
 
   return {

package/src/server/tools.ts

@@ -109,6 +109,20 @@ export interface SupersedeResult {
 
 export interface ListScopesResult {
   scopes: { path: string; fact_count: number; last_updated: string | null }[];
+  /** Present only when `scopes` is empty — tells the calling agent how to make a scope appear. */
+  hint?: string;
+}
+
+/**
+ * v0.2.25 — Gap 3. The smoke-6 transcript showed an agent in chat inventing a wrong identity
+ * (`lpd.themes@gmail.com` instead of `lpdthemes@gmail.com`) because it had no MCP-side way to
+ * ask "who am I writing as?". `krimto_whoami` returns the resolved identity plus the scopes
+ * the caller can read and write, so the agent never has to guess.
+ */
+export interface WhoamiResult {
+  identity: string;
+  readable_scopes: string[];
+  writable_scopes: string[];
 }
 
 function clock(ctx: ToolContext): Date {
@@ -329,17 +343,42 @@ export async function krimtoSupersede(
   });
 }
 
+/**
+ * Return the caller's identity plus the scopes they can read and write. The agent in chat uses
+ * this to avoid hallucinating identity (Gap 3 from the smoke-6 transcript audit).
+ */
+export async function krimtoWhoami(ctx: ToolContext): Promise<WhoamiResult> {
+  const readable = readableScopesFor(ctx);
+  const writable = writableScopesFor(ctx);
+  if (ctx.activity) await ctx.activity.record("krimto_whoami", ctx.requester.identity, ctx.requester.identity);
+  return {
+    identity: ctx.requester.identity,
+    readable_scopes: readable,
+    writable_scopes: writable,
+  };
+}
+
 /** Discover the scopes that exist and what they contain. */
 export async function krimtoListScopes(ctx: ToolContext): Promise<ListScopesResult> {
   const scopes = ctx.index.listScopes(readableScopesFor(ctx));
   if (ctx.activity) await ctx.activity.record("krimto_list_scopes", ctx.requester.identity, `${scopes.length} scope(s)`);
-  return {
+  const result: ListScopesResult = {
     scopes: scopes.map((s) => ({
       path: s.path,
       fact_count: s.factCount,
       last_updated: s.lastUpdated,
     })),
   };
+  // v0.2.24 — empty result is the #1 first-impression confuser ("Krimto must be broken").
+  // Surface the next step in the response itself, so an agent in chat can relay it verbatim
+  // instead of inventing a hallucinated explanation about "scopes aren't configured".
+  if (result.scopes.length === 0) {
+    result.hint =
+      `No scopes exist yet for ${ctx.requester.identity}. Scopes are created on the first ` +
+      `write — try krimto_write with a small fact (e.g. "we use pnpm in this repo") and ` +
+      `your user/<email> scope will appear here.`;
+  }
+  return result;
 }
 
 /** Build a Requester from a validated bearer token's AuthInfo (its `extra` carries identity+teams). */