@whisperr/wizard 0.5.0 → 0.5.1

package/README.md

@@ -60,6 +60,13 @@ Development overrides:
 - `WHISPERR_WIZARD_EXPLORER_MODEL`
 - `WHISPERR_WIZARD_EXPLORER_EFFORT`
 - `WHISPERR_WIZARD_DIRECT_OPENAI_KEY` or `OPENAI_API_KEY`
+- `WHISPERR_WIZARD_LOG_DIR` to place private diagnostic logs in a specific directory outside the target repository
+
+## Diagnostics
+
+Each wizard invocation prints the path to one private JSONL diagnostic file. By default it is stored under the wizard state directory's `logs` folder, outside the target repository. The directory is mode `0700` and each file is mode `0600`. Filenames contain only a timestamp and random invocation ID.
+
+Diagnostics contain bounded lifecycle, progress, Git-safety, coverage, first-event, and HTTP timing/status metadata. They do not contain request or response bodies or headers, prompts, repository source, model output or reasoning, subprocess output, environment contents, authorization codes or URLs, or credentials. Known credentials are registered for exact redaction as they become available, and common token/key formats are also scrubbed.
 
 ## Safety
 

package/dist/index.js

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { readFileSync, realpathSync } from "fs";
-import { dirname as dirname4, join as join7 } from "path";
+import { readFileSync, realpathSync as realpathSync2 } from "fs";
+import { dirname as dirname5, join as join8, resolve as resolve5 } from "path";
 import { fileURLToPath } from "url";
 
 // src/cli.ts
 import { readFile as readFile6 } from "fs/promises";
-import { join as join6, resolve as resolve3 } from "path";
+import { join as join7, resolve as resolve4 } from "path";
 import * as p from "@clack/prompts";
 import open3 from "open";
 
@@ -273,14 +273,14 @@ function readStringLiteral(content, start, quote) {
   return { value, end: content.length };
 }
 function run(cwd, args) {
-  return new Promise((resolve4) => {
+  return new Promise((resolve6) => {
     const child = spawn("git", args, { cwd });
     let stdout = "";
     let stderr = "";
     child.stdout.on("data", (d) => stdout += d.toString());
     child.stderr.on("data", (d) => stderr += d.toString());
-    child.on("close", (code2) => resolve4({ ok: code2 === 0, stdout, stderr }));
-    child.on("error", () => resolve4({ ok: false, stdout, stderr }));
+    child.on("close", (code2) => resolve6({ ok: code2 === 0, stdout, stderr }));
+    child.on("error", () => resolve6({ ok: false, stdout, stderr }));
   });
 }
 
@@ -288,14 +288,20 @@ function run(cwd, args) {
 import { spawn as spawn2 } from "child_process";
 
 // src/core/scrub.ts
+import { stripVTControlCharacters } from "util";
 var SECRET_PATTERNS = [
   /sk-[A-Za-z0-9_-]{12,}/g,
   /Bearer\s+[A-Za-z0-9._~+\/-]+/gi,
-  /\b(?:OPENAI_API_KEY|WHISPERR_WIZARD_DIRECT_OPENAI_KEY|WHISPERR_INGESTION_KEY)\s*=\s*["']?[^"'\s]+["']?/gi
+  /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g,
+  /-----BEGIN(?: [A-Z0-9]+)? PRIVATE KEY-----[\s\S]*?(?:-----END(?: [A-Z0-9]+)? PRIVATE KEY-----|$)/gi,
+  /["']?\b(?:[A-Z0-9_]*(?:API[_-]?KEY|TOKEN|SECRET|PASSWORD|PASSWD|ACCESS[_-]?KEY|AUTH)[A-Z0-9_]*)\b["']?\s*(?:=|:)\s*["']?[^"'\s,;}]+["']?/gi
 ];
 function scrubError(error, secrets = []) {
-  let text = error instanceof Error ? error.message : String(error);
-  text = stripTerminalControls(text);
+  const text = error instanceof Error ? error.message : String(error);
+  return scrubText(text, secrets, 2e3);
+}
+function scrubText(value, secrets = [], maxLength = 2e3) {
+  let text = stripTerminalControls(value);
   for (const secret of secrets) {
     if (secret) text = text.replaceAll(secret, "[redacted]");
   }
@@ -305,7 +311,12 @@ function scrubError(error, secrets = []) {
       return assignment >= 0 ? `${match.slice(0, assignment + 1)}[redacted]` : "[redacted]";
     });
   }
-  return text.slice(0, 2e3).trim();
+  text = text.replace(
+    /\b(https?:\/\/)([^\s\/@]+):([^\s@\/]+)@([^\s?#]+)([^\s]*)/gi,
+    "$1[redacted]@$4$5"
+  );
+  text = text.replace(/\b(https?:\/\/[^\s?#]+)\?[^\s#]*/gi, "$1?[redacted]");
+  return text.slice(0, maxLength).trim();
 }
 function sanitizedChildEnv(source = process.env) {
   const env = { ...source };
@@ -320,7 +331,7 @@ function sanitizedChildEnv(source = process.env) {
   return env;
 }
 function stripTerminalControls(value) {
-  return value.replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, "").replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, " ").replace(/ {2,}/g, " ");
+  return stripVTControlCharacters(value).replace(/\x1b\](?:[^\x07\x1b]|\x1b(?!\\))*(?:\x07|\x1b\\)/g, "").replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, "").replace(/[\x00-\x1f\x7f-\x9f]/g, " ").replace(/[\u2028\u2029]/g, " ").replace(/ {2,}/g, " ");
 }
 
 // src/core/postflight.ts
@@ -335,7 +346,7 @@ function runVerifyCommand(repoPath, command, opts = {}) {
     return Promise.resolve({ ran: false, ok: true, output: "" });
   }
   const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-  return new Promise((resolve4) => {
+  return new Promise((resolve6) => {
     const child = spawn2(command, {
       cwd: repoPath,
       shell: true,
@@ -351,11 +362,11 @@ function runVerifyCommand(repoPath, command, opts = {}) {
     child.stderr?.on("data", append);
     const timer = setTimeout(() => {
       killProcessTree(child.pid, () => child.kill("SIGKILL"));
-      resolve4({ ran: true, ok: false, command, output: tail(out), timedOut: true });
+      resolve6({ ran: true, ok: false, command, output: tail(out), timedOut: true });
     }, timeoutMs);
     child.on("close", (code2) => {
       clearTimeout(timer);
-      resolve4({
+      resolve6({
         ran: true,
         ok: code2 === 0,
         command,
@@ -367,7 +378,7 @@ function runVerifyCommand(repoPath, command, opts = {}) {
     });
     child.on("error", () => {
       clearTimeout(timer);
-      resolve4({ ran: true, ok: false, command, output: tail(out), toolMissing: true });
+      resolve6({ ran: true, ok: false, command, output: tail(out), toolMissing: true });
     });
   });
 }
@@ -1838,10 +1849,10 @@ var wordmark = (() => {
 var divider = theme.dim("\u2500".repeat(48));
 
 // src/core/auth.ts
-async function startDeviceAuth(config) {
+async function startDeviceAuth(config, signal) {
   const authorize = await fetchJson(
     `${config.apiBaseUrl}/wizard/device/authorize`,
-    { method: "POST", body: JSON.stringify({ client: "whisperr-wizard" }) }
+    { method: "POST", body: JSON.stringify({ client: "whisperr-wizard" }), signal }
   );
   const intervalMs = (authorize.interval ?? 5) * 1e3;
   const deadline = Date.now() + (authorize.expires_in ?? 600) * 1e3;
@@ -1852,13 +1863,14 @@ async function startDeviceAuth(config) {
     async poll() {
       let wait = intervalMs;
       while (Date.now() < deadline) {
-        await sleep(wait);
+        await sleep(wait, signal);
         const res = await fetch(
           `${config.apiBaseUrl}/wizard/device/token`,
           {
             method: "POST",
             headers: { "content-type": "application/json" },
-            body: JSON.stringify({ device_code: authorize.device_code })
+            body: JSON.stringify({ device_code: authorize.device_code }),
+            signal
           }
         );
         if (res.ok) {
@@ -1902,8 +1914,20 @@ async function fetchJson(url, init) {
   }
   return await res.json();
 }
-function sleep(ms) {
-  return new Promise((r) => setTimeout(r, ms));
+function sleep(ms, signal) {
+  signal?.throwIfAborted();
+  return new Promise((resolve6, reject) => {
+    const timer = setTimeout(done, ms);
+    signal?.addEventListener("abort", aborted, { once: true });
+    function done() {
+      signal?.removeEventListener("abort", aborted);
+      resolve6();
+    }
+    function aborted() {
+      clearTimeout(timer);
+      reject(signal?.reason);
+    }
+  });
 }
 
 // src/core/config.ts
@@ -1917,10 +1941,19 @@ function resolveEffort(value, fallback) {
   const raw = (value ?? "").toLowerCase();
   return EFFORT_LEVELS.includes(raw) ? raw : fallback;
 }
+function stripTrailingSlashes(value) {
+  let end = value.length;
+  while (end > 0 && value.charCodeAt(end - 1) === 47) end -= 1;
+  return value.slice(0, end);
+}
 function resolveConfig(flags = {}) {
-  const apiBaseUrl = (flags.apiBaseUrl ?? process.env.WHISPERR_WIZARD_API_BASE ?? DEFAULT_API_BASE).replace(/\/+$/, "");
+  const apiBaseUrl = stripTrailingSlashes(
+    flags.apiBaseUrl ?? process.env.WHISPERR_WIZARD_API_BASE ?? DEFAULT_API_BASE
+  );
   const directOpenAIKey = process.env.WHISPERR_WIZARD_DIRECT_OPENAI_KEY ?? process.env.OPENAI_API_KEY;
-  const openAIBaseUrl = (process.env.WHISPERR_WIZARD_OPENAI_BASE ?? (directOpenAIKey ? "https://api.openai.com/v1" : `${apiBaseUrl}/wizard/openai`)).replace(/\/+$/, "");
+  const openAIBaseUrl = stripTrailingSlashes(
+    process.env.WHISPERR_WIZARD_OPENAI_BASE ?? (directOpenAIKey ? "https://api.openai.com/v1" : `${apiBaseUrl}/wizard/openai`)
+  );
   return {
     apiBaseUrl,
     openAIBaseUrl,
@@ -2883,6 +2916,247 @@ async function detectStack(repoPath) {
   return results.filter((d) => d !== null).sort((a, b) => b.confidence - a.confidence);
 }
 
+// src/core/diagnostics.ts
+import { randomUUID } from "crypto";
+import {
+  closeSync,
+  constants,
+  fchmodSync,
+  fstatSync,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  realpathSync,
+  writeSync
+} from "fs";
+import { dirname as dirname4, isAbsolute as isAbsolute2, join as join6, relative as relative3, resolve as resolve3 } from "path";
+
+// src/core/resumeState.ts
+import { createHash as createHash3 } from "crypto";
+import { chmod, mkdir as mkdir3, readFile as readFile5, rename, rm as rm2, writeFile as writeFile3 } from "fs/promises";
+import { homedir } from "os";
+import { dirname as dirname3, join as join5 } from "path";
+function wizardStateRoot(env = process.env) {
+  return env.WHISPERR_WIZARD_STATE_DIR ?? join5(env.XDG_STATE_HOME ?? join5(homedir(), ".local", "state"), "whisperr-wizard");
+}
+function resumeStatePath(identity, env = process.env) {
+  const root = wizardStateRoot(env);
+  const key = createHash3("sha256").update(
+    [stripTrailingSlashes(identity.apiBaseUrl), identity.appId, identity.repoFingerprint].join(
+      "\n"
+    )
+  ).digest("hex");
+  return join5(root, `${key}.json`);
+}
+async function loadResumeState(path) {
+  try {
+    const parsed = JSON.parse(await readFile5(path, "utf8"));
+    if (typeof parsed.runId !== "string" || !parsed.runId.trim()) return null;
+    if (parsed.conversationId !== void 0 && (typeof parsed.conversationId !== "string" || !parsed.conversationId.trim())) {
+      return null;
+    }
+    return {
+      runId: parsed.runId,
+      ...typeof parsed.conversationId === "string" ? { conversationId: parsed.conversationId } : {}
+    };
+  } catch {
+    return null;
+  }
+}
+async function saveResumeState(path, state) {
+  await mkdir3(dirname3(path), { recursive: true, mode: 448 });
+  const tempPath = `${path}.${process.pid}.tmp`;
+  const serialized = `${JSON.stringify(state)}
+`;
+  try {
+    await writeFile3(tempPath, serialized, { encoding: "utf8", mode: 384 });
+    await rename(tempPath, path);
+    await chmod(path, 384);
+  } finally {
+    await rm2(tempPath, { force: true });
+  }
+}
+async function clearResumeState(path) {
+  await rm2(path, { force: true });
+}
+
+// src/core/diagnostics.ts
+var SENSITIVE_FIELD = /(?:body|headers?|prompt|source|modelOutput|reasoning|subprocessOutput|env(?:ironment)?|deviceCode|userCode|verificationUrl|apiKey|token|secret|password)/i;
+var UNSAFE_DIRECTORY_MESSAGE = "Wizard diagnostics directory is not secure.";
+var WizardDiagnostics = class _WizardDiagnostics {
+  invocationId;
+  path;
+  secrets = /* @__PURE__ */ new Set();
+  fd;
+  constructor(path, invocationId, fd) {
+    this.path = path;
+    this.invocationId = invocationId;
+    this.fd = fd;
+  }
+  static create(repoPath, env = process.env, now = /* @__PURE__ */ new Date()) {
+    const configuredRoot = env.WHISPERR_WIZARD_LOG_DIR;
+    const logRoot = resolve3(configuredRoot ?? join6(wizardStateRoot(env), "logs"));
+    assertOutsideRepository(logRoot, resolve3(repoPath));
+    const directory = preparePrivateDirectory(logRoot);
+    assertOutsideRepository(directory.realPath, realpathOrResolved(repoPath));
+    const invocationId = randomUUID();
+    const timestamp = now.toISOString().replaceAll(":", "-");
+    const path = join6(logRoot, `${timestamp}-${invocationId}.jsonl`);
+    const fd = createPrivateFile(path, logRoot, directory);
+    return new _WizardDiagnostics(path, invocationId, fd);
+  }
+  registerSecrets(...values) {
+    for (const value of values) {
+      if (value) this.secrets.add(value);
+    }
+  }
+  log(event, data = {}) {
+    if (this.fd === void 0) return;
+    const record = {
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      invocationId: this.invocationId,
+      event: scrubText(event, [...this.secrets], 80)
+    };
+    for (const [key, value] of Object.entries(data)) {
+      if (value === void 0 || SENSITIVE_FIELD.test(key)) continue;
+      record[key] = typeof value === "string" ? scrubText(value, [...this.secrets], 300) : value;
+    }
+    try {
+      writeSync(this.fd, `${JSON.stringify(record)}
+`);
+    } catch {
+      this.close();
+    }
+  }
+  close() {
+    if (this.fd === void 0) return;
+    const fd = this.fd;
+    this.fd = void 0;
+    try {
+      fsyncSync(fd);
+    } catch {
+    }
+    try {
+      closeSync(fd);
+    } catch {
+    }
+  }
+};
+function preparePrivateDirectory(path) {
+  try {
+    lstatSync(path);
+  } catch (error) {
+    if (!isErrorCode(error, "ENOENT")) throwUnsafeDirectory();
+    try {
+      mkdirSync(path, { recursive: true, mode: 448 });
+    } catch (mkdirError) {
+      if (!isErrorCode(mkdirError, "EEXIST")) throwUnsafeDirectory();
+    }
+  }
+  const stats = privateDirectoryStats(path);
+  let realPath;
+  try {
+    realPath = realpathSync(path);
+  } catch {
+    throwUnsafeDirectory();
+  }
+  const confirmedStats = privateDirectoryStats(path);
+  if (!sameFile(stats, confirmedStats)) throwUnsafeDirectory();
+  return { realPath, stats: confirmedStats };
+}
+function createPrivateFile(path, directoryPath, directory) {
+  let fd;
+  try {
+    assertDirectoryUnchanged(directoryPath, directory);
+    fd = openSync(
+      path,
+      constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW,
+      384
+    );
+    fchmodSync(fd, 384);
+    const fileStats = fstatSync(fd);
+    if (!fileStats.isFile() || fileStats.nlink !== 1 || (fileStats.mode & 511) !== 384 || !ownedByCurrentUser(fileStats)) {
+      throwUnsafeDirectory();
+    }
+    assertDirectoryUnchanged(directoryPath, directory);
+    if (dirname4(realpathSync(path)) !== directory.realPath) throwUnsafeDirectory();
+    return fd;
+  } catch {
+    if (fd !== void 0) {
+      try {
+        closeSync(fd);
+      } catch {
+      }
+    }
+    throwUnsafeDirectory();
+  }
+}
+function privateDirectoryStats(path) {
+  let stats;
+  try {
+    stats = lstatSync(path);
+  } catch {
+    throwUnsafeDirectory();
+  }
+  if (stats.isSymbolicLink() || !stats.isDirectory() || (stats.mode & 63) !== 0 || !ownedByCurrentUser(stats)) {
+    throwUnsafeDirectory();
+  }
+  return stats;
+}
+function assertDirectoryUnchanged(path, expected) {
+  const stats = privateDirectoryStats(path);
+  let realPath;
+  try {
+    realPath = realpathSync(path);
+  } catch {
+    throwUnsafeDirectory();
+  }
+  if (!sameFile(stats, expected.stats) || realPath !== expected.realPath) {
+    throwUnsafeDirectory();
+  }
+}
+function ownedByCurrentUser(stats) {
+  return typeof process.getuid !== "function" || stats.uid === process.getuid();
+}
+function sameFile(left, right) {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+function isErrorCode(error, code2) {
+  return error?.code === code2;
+}
+function throwUnsafeDirectory() {
+  throw new Error(UNSAFE_DIRECTORY_MESSAGE);
+}
+function realpathOrResolved(path) {
+  try {
+    return realpathSync(path);
+  } catch {
+    return resolve3(path);
+  }
+}
+function sanitizeRequestPath(path) {
+  const withoutFragment = path.split("#", 1)[0] ?? "";
+  const withoutQuery = withoutFragment.split("?", 1)[0] ?? "";
+  const normalized = withoutQuery.startsWith("/") ? withoutQuery : `/${withoutQuery}`;
+  return scrubText(normalized, [], 300);
+}
+function diagnosticErrorData(error) {
+  const candidate = typeof error === "object" && error !== null ? error : void 0;
+  return {
+    errorType: candidate && typeof candidate.name === "string" ? candidate.name.slice(0, 80) : typeof error,
+    status: candidate && typeof candidate.status === "number" ? candidate.status : void 0,
+    requestId: candidate && typeof candidate.requestId === "string" ? candidate.requestId.slice(0, 200) : void 0,
+    errorCode: candidate && typeof candidate.code === "string" && /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/.test(candidate.code) ? candidate.code : void 0
+  };
+}
+function assertOutsideRepository(candidate, repoPath) {
+  const rel = relative3(repoPath, candidate);
+  if (rel === "" || !rel.startsWith("..") && !isAbsolute2(rel)) {
+    throw new Error("Wizard diagnostics directory must be outside the target repository.");
+  }
+}
+
 // src/core/report.ts
 function scrubSummary(text) {
   return scrubTerminalControls(text).replace(/sk-ant-[A-Za-z0-9_-]+/g, "[redacted]").replace(/sk-[A-Za-z0-9]{16,}/g, "[redacted]").replace(/AKIA[0-9A-Z]{16}/g, "[redacted]").replace(/Bearer\s+[A-Za-z0-9._-]+/g, "[redacted]").replace(
@@ -2931,75 +3205,41 @@ function scrubTerminalControls(value) {
   return value.replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, "").replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)?/g, "").replace(/[\x00-\x1f\x7f]/g, " ").replace(/ {2,}/g, " ").trim();
 }
 
-// src/core/resumeState.ts
-import { createHash as createHash3 } from "crypto";
-import { chmod, mkdir as mkdir3, readFile as readFile5, rename, rm as rm2, writeFile as writeFile3 } from "fs/promises";
-import { homedir } from "os";
-import { dirname as dirname3, join as join5 } from "path";
-function resumeStatePath(identity, env = process.env) {
-  const root = env.WHISPERR_WIZARD_STATE_DIR ?? join5(env.XDG_STATE_HOME ?? join5(homedir(), ".local", "state"), "whisperr-wizard");
-  const key = createHash3("sha256").update(
-    [identity.apiBaseUrl.replace(/\/+$/, ""), identity.appId, identity.repoFingerprint].join(
-      "\n"
-    )
-  ).digest("hex");
-  return join5(root, `${key}.json`);
-}
-async function loadResumeState(path) {
-  try {
-    const parsed = JSON.parse(await readFile5(path, "utf8"));
-    if (typeof parsed.runId !== "string" || !parsed.runId.trim()) return null;
-    if (parsed.conversationId !== void 0 && (typeof parsed.conversationId !== "string" || !parsed.conversationId.trim())) {
-      return null;
-    }
-    return {
-      runId: parsed.runId,
-      ...typeof parsed.conversationId === "string" ? { conversationId: parsed.conversationId } : {}
-    };
-  } catch {
-    return null;
-  }
-}
-async function saveResumeState(path, state) {
-  await mkdir3(dirname3(path), { recursive: true, mode: 448 });
-  const tempPath = `${path}.${process.pid}.tmp`;
-  const serialized = `${JSON.stringify(state)}
-`;
-  try {
-    await writeFile3(tempPath, serialized, { encoding: "utf8", mode: 384 });
-    await rename(tempPath, path);
-    await chmod(path, 384);
-  } finally {
-    await rm2(tempPath, { force: true });
-  }
-}
-async function clearResumeState(path) {
-  await rm2(path, { force: true });
-}
-
 // src/core/runtime.ts
+import { randomUUID as randomUUID2 } from "crypto";
 var RuntimeRequestError = class extends Error {
-  constructor(message, status) {
+  constructor(message, status, requestId, code2) {
     super(message);
     this.status = status;
+    this.requestId = requestId;
+    this.code = code2;
     this.name = "RuntimeRequestError";
   }
   status;
+  requestId;
+  code;
 };
 var WizardRuntimeClient = class {
-  constructor(config, session, fetchImpl = globalThis.fetch) {
+  constructor(config, session, fetchImpl = globalThis.fetch, diagnostics, signal) {
     this.config = config;
     this.session = session;
     this.fetchImpl = fetchImpl;
+    this.diagnostics = diagnostics;
+    this.signal = signal;
+    this.registerSecrets(session.token, config.directOpenAIKey);
   }
   config;
   session;
   fetchImpl;
+  diagnostics;
+  signal;
   snapshots = /* @__PURE__ */ new Map();
+  secrets = /* @__PURE__ */ new Set();
   async createOrResumeRun(input) {
     const snapshot = normalizeSnapshot(
       await this.request("POST", "/wizard/runs", input)
     );
+    this.registerSecrets(snapshot.ingestion.apiKey);
     this.snapshots.set(snapshot.run.id, snapshot);
     return snapshot;
   }
@@ -3010,6 +3250,7 @@ var WizardRuntimeClient = class {
         `/wizard/runs/${encodeURIComponent(runId)}`
       )
     );
+    this.registerSecrets(snapshot.ingestion.apiKey);
     this.snapshots.set(runId, snapshot);
     return snapshot;
   }
@@ -3066,33 +3307,123 @@ var WizardRuntimeClient = class {
     return snapshot;
   }
   async request(method, path, body) {
+    const clientRequestId = randomUUID2();
+    const safePath = sanitizeRequestPath(path);
+    const startedAt = performance.now();
     let response;
     try {
       response = await this.fetchImpl(`${this.config.apiBaseUrl}${path}`, {
         method,
+        signal: this.signal,
         headers: {
           accept: "application/json",
           authorization: `Bearer ${this.session.token}`,
+          "x-request-id": clientRequestId,
           ...body === void 0 ? {} : { "content-type": "application/json" }
         },
         ...body === void 0 ? {} : { body: JSON.stringify(body) }
       });
     } catch (error) {
+      this.logRequest(method, safePath, startedAt, clientRequestId);
       throw new RuntimeRequestError(
-        `Runtime request failed: ${scrubError(error, [this.session.token])}`
+        `Runtime request failed: ${scrubError(error, [...this.secrets])}`,
+        void 0,
+        clientRequestId
       );
     }
+    const headerRequestId = safeRequestId(response.headers.get("x-request-id"));
     if (!response.ok) {
-      const detail = await response.text().catch(() => "");
-      const safeDetail = scrubError(detail, [this.session.token]).slice(0, 500);
+      const envelope = await readErrorEnvelope(response);
+      const responseRequestId = headerRequestId ?? envelope.requestId;
+      this.logRequest(
+        method,
+        safePath,
+        startedAt,
+        clientRequestId,
+        response.status,
+        responseRequestId,
+        envelope.code
+      );
+      throw new RuntimeRequestError(
+        `Runtime request failed: ${method} ${safePath} -> ${response.status}${envelope.code ? ` (${envelope.code})` : ""}`,
+        response.status,
+        responseRequestId ?? clientRequestId,
+        envelope.code
+      );
+    }
+    let result;
+    try {
+      result = await response.json();
+    } catch {
+      this.logRequest(
+        method,
+        safePath,
+        startedAt,
+        clientRequestId,
+        response.status,
+        headerRequestId
+      );
       throw new RuntimeRequestError(
-        `Runtime request failed: ${method} ${path} -> ${response.status}${safeDetail ? `: ${safeDetail}` : ""}`,
-        response.status
+        `Runtime request failed: ${method} ${safePath} -> ${response.status}: invalid JSON response`,
+        response.status,
+        headerRequestId ?? clientRequestId
       );
     }
-    return await response.json();
+    this.logRequest(
+      method,
+      safePath,
+      startedAt,
+      clientRequestId,
+      response.status,
+      headerRequestId ?? envelopeRequestId(result)
+    );
+    return result;
+  }
+  logRequest(method, path, startedAt, clientRequestId, status, responseRequestId, errorCode) {
+    this.diagnostics?.log("runtime_request", {
+      method,
+      path,
+      status,
+      durationMs: Math.max(0, Math.round(performance.now() - startedAt)),
+      clientRequestId,
+      responseRequestId,
+      errorCode
+    });
+  }
+  registerSecrets(...values) {
+    for (const value of values) {
+      if (!value) continue;
+      this.secrets.add(value);
+      this.diagnostics?.registerSecrets(value);
+    }
   }
 };
+async function readErrorEnvelope(response) {
+  try {
+    const parsed = JSON.parse(await response.text());
+    if (!isRecord(parsed)) return {};
+    const nested = isRecord(parsed.error) ? parsed.error : void 0;
+    return {
+      requestId: safeRequestId(parsed.request_id) ?? safeRequestId(parsed.requestId) ?? (nested ? safeRequestId(nested.request_id) ?? safeRequestId(nested.requestId) : void 0),
+      code: (nested ? safeErrorCode(nested.code) : void 0) ?? safeErrorCode(parsed.code)
+    };
+  } catch {
+    return {};
+  }
+}
+function envelopeRequestId(value) {
+  if (!isRecord(value)) return void 0;
+  return safeRequestId(value.request_id) ?? safeRequestId(value.requestId);
+}
+function safeRequestId(value) {
+  return typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value) ? value : void 0;
+}
+function safeErrorCode(value) {
+  return typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/.test(value) ? value : void 0;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function normalizeSnapshot(response) {
   return {
     app: {
@@ -3261,21 +3592,38 @@ function banner() {
 }
 
 // src/cli.ts
-async function run2(options) {
-  const repoPath = resolve3(options.path ?? process.cwd());
+async function run2(options, diagnostics, context = {}) {
+  const repoPath = resolve4(options.path ?? process.cwd());
   const config = resolveConfig(options);
+  const signal = context.signal ?? new AbortController().signal;
+  let interruptedBy = signal.aborted ? handledSignal(signal.reason) : void 0;
+  signal.addEventListener(
+    "abort",
+    () => {
+      interruptedBy = handledSignal(signal.reason);
+    },
+    { once: true }
+  );
+  diagnostics?.registerSecrets(config.directOpenAIKey);
   console.log(banner());
   p.intro(theme.signal("Let's build and wire your Whisperr intervention model."));
   const detections = await withSpinner(
     "Scanning your repository",
     () => detectStack(repoPath)
   );
+  if (signal.aborted) return signalExitCode(interruptedBy);
   const chosen = await chooseTarget(detections);
   if (!chosen) {
+    diagnostics?.log("run_failed", { stage: "stack_selection", reason: "cancelled" });
     p.cancel("No supported stack selected.");
     return 1;
   }
+  diagnostics?.log("stack_selected", {
+    stack: chosen.playbook.target.id,
+    detected: Boolean(chosen.detection)
+  });
   if (chosen.playbook.target.availability === "planned") {
+    diagnostics?.log("run_failed", { stage: "stack_selection", reason: "unavailable" });
     p.cancel(
       `The ${chosen.playbook.target.displayName} SDK is not available yet, so the wizard cannot safely instrument this repository.`
     );
@@ -3286,14 +3634,26 @@ async function run2(options) {
   );
   let session;
   try {
-    session = await withBrowserAuth(config);
+    session = await withBrowserAuth(config, diagnostics, signal);
+    diagnostics?.registerSecrets(session.token);
   } catch (error) {
-    p.cancel(theme.alert(scrubError(error)));
-    return 1;
+    const safeError = scrubError(error, [config.directOpenAIKey ?? ""]);
+    diagnostics?.log("run_failed", {
+      stage: "authentication",
+      ...diagnosticErrorData(error)
+    });
+    p.cancel(theme.alert(safeError));
+    return interruptedBy ? signalExitCode(interruptedBy) : 1;
   }
   const stopKeepalive = startSessionKeepalive(config, session);
   const fingerprint = await repoFingerprint(repoPath);
-  const runtime = new WizardRuntimeClient(config, session);
+  const runtime = new WizardRuntimeClient(
+    config,
+    session,
+    globalThis.fetch,
+    diagnostics,
+    signal
+  );
   let selected;
   try {
     selected = await withSpinner(
@@ -3309,17 +3669,21 @@ async function run2(options) {
     );
   } catch (error) {
     stopKeepalive();
-    p.cancel(theme.alert(scrubError(error, [session.token, config.directOpenAIKey ?? ""])));
-    return 1;
+    const safeError = scrubError(error, [session.token, config.directOpenAIKey ?? ""]);
+    diagnostics?.log("run_failed", {
+      stage: "run_selection",
+      ...diagnosticErrorData(error)
+    });
+    p.cancel(theme.alert(safeError));
+    return interruptedBy ? signalExitCode(interruptedBy) : 1;
   }
-  const abortController = new AbortController();
-  let interruptedBy;
-  const interrupt = (signal) => {
-    interruptedBy = signal;
-    abortController.abort(new Error(`Interrupted by ${signal}`));
-  };
-  process.once("SIGINT", interrupt);
-  process.once("SIGTERM", interrupt);
+  diagnostics?.registerSecrets(selected.snapshot.ingestion.apiKey);
+  diagnostics?.log("run_selected", {
+    resumed: selected.resumed,
+    appId: selected.snapshot.app.id,
+    projectId: selected.snapshot.project.id,
+    runId: selected.snapshot.run.id
+  });
   let phase = selected.resumed ? "resuming" : "exploring";
   const spin = p.spinner();
   const useSpinner = Boolean(process.stdout.isTTY);
@@ -3329,7 +3693,13 @@ async function run2(options) {
   try {
     checkpoint = await takeCheckpoint(repoPath);
     invocationSnapshot = checkpoint.isRepo ? await snapshotChanges(repoPath, checkpoint) : /* @__PURE__ */ new Map();
-    if (!await enforceGitSafety(repoPath, checkpoint, selected.resumed, options.force)) {
+    if (!await enforceGitSafety(
+      repoPath,
+      checkpoint,
+      selected.resumed,
+      options.force,
+      diagnostics
+    )) {
       await runtime.updateRun(selected.snapshot.run.id, {
         status: "failed",
         error: "Repository is not in a safe state for automatic edits.",
@@ -3337,8 +3707,7 @@ async function run2(options) {
       }).catch(() => {
       });
       stopKeepalive();
-      process.removeListener("SIGINT", interrupt);
-      process.removeListener("SIGTERM", interrupt);
+      diagnostics?.log("run_failed", { stage: "git_safety", runId: selected.snapshot.run.id });
       return 1;
     }
     p.note(
@@ -3351,6 +3720,7 @@ async function run2(options) {
     );
     if (useSpinner) spin.start(theme.bright(phase));
     else p.log.step(theme.bright(phase));
+    diagnostics?.log("phase", { phase: safeProgressText(phase) });
     heartbeat = setInterval(() => {
       void runtime.updateRun(selected.snapshot.run.id, {}).catch(() => {
       });
@@ -3369,10 +3739,14 @@ async function run2(options) {
     }).catch(() => {
     });
     stopKeepalive();
-    process.removeListener("SIGINT", interrupt);
-    process.removeListener("SIGTERM", interrupt);
+    diagnostics?.log("run_failed", {
+      stage: "repository_setup",
+      runId: selected.snapshot.run.id,
+      interrupted: Boolean(interruptedBy),
+      ...diagnosticErrorData(error)
+    });
     p.cancel(theme.alert(safeError));
-    return interruptedBy === "SIGINT" ? 130 : 1;
+    return interruptedBy ? signalExitCode(interruptedBy) : 1;
   }
   let runtimeCompleted = false;
   try {
@@ -3385,7 +3759,7 @@ async function run2(options) {
       runtime,
       checkpoint,
       conversationId: selected.snapshot.run.modelConversationId,
-      signal: abortController.signal,
+      signal,
       async saveConversationId(conversationId) {
         await saveResumeState(selected.statePath, {
           runId: selected.snapshot.run.id,
@@ -3395,15 +3769,26 @@ async function run2(options) {
       progress: {
         onPhase(label) {
           phase = label;
+          diagnostics?.log("phase", { phase: safeProgressText(label) });
           if (useSpinner) spin.message(theme.bright(label));
           else p.log.step(theme.bright(label));
         },
         onActivity(message) {
+          diagnostics?.log("activity", {
+            phase: safeProgressText(phase),
+            activity: activityCategory(message)
+          });
           if (useSpinner) spin.message(`${theme.bright(phase)}${theme.muted(` - ${message}`)}`);
         }
       }
     });
     runtimeCompleted = true;
+    diagnostics?.log("integration_completed", {
+      runId: selected.snapshot.run.id,
+      durationMs: outcome.durationMs,
+      wiredEventCount: outcome.wiredEvents.filter((event) => event.status === "wired").length,
+      eventCount: outcome.wiredEvents.length
+    });
     clearInterval(heartbeat);
     if (useSpinner) spin.stop(theme.success("Integration complete"));
     else p.log.success(theme.success("Integration complete"));
@@ -3439,22 +3824,29 @@ async function run2(options) {
     if (!report.ok) {
       p.log.warn(theme.warn("The integration completed, but coverage reporting failed."));
     }
+    diagnostics?.log("coverage_report", { ok: report.ok });
     p.log.step(
       theme.bright("Run your app once") + theme.muted(" and trigger a tracked action so Whisperr can confirm ingestion.")
     );
     const first = await pollFirstEvent(config, session, {
       timeoutMs: 12e4,
-      signal: abortController.signal
+      signal
     });
     if (interruptedBy) {
+      diagnostics?.log("first_event", { outcome: "interrupted" });
       p.log.info(theme.muted("The integration is complete; first-event polling was interrupted."));
-      return 130;
+      return signalExitCode(interruptedBy);
     }
     if (first.received) {
+      diagnostics?.log("first_event", {
+        outcome: "received",
+        eventTypePresent: Boolean(first.eventType)
+      });
       p.log.success(
         theme.success("Whisperr is receiving events") + (first.eventType ? theme.muted(` (${first.eventType})`) : "")
       );
     } else {
+      diagnostics?.log("first_event", { outcome: "not_received" });
       p.log.info(theme.muted("No event received yet; events will flow when the app runs."));
     }
     const undo = invocationSnapshot.size === 0 ? revertHint(checkpoint) : void 0;
@@ -3478,6 +3870,13 @@ async function run2(options) {
       selected.snapshot.ingestion.apiKey
     ]);
     const failurePhase = interruptedBy ? "interrupted" : "failed";
+    diagnostics?.log("run_failed", {
+      stage: safeProgressText(phase),
+      runId: selected.snapshot.run.id,
+      interrupted: Boolean(interruptedBy),
+      runtimeCompleted,
+      ...diagnosticErrorData(error)
+    });
     if (!runtimeCompleted) {
       const authoritative = await runtime.getRun(selected.snapshot.run.id).catch(() => null);
       if (authoritative?.run.status === "completed") {
@@ -3489,7 +3888,7 @@ async function run2(options) {
       p.log.error(
         theme.alert("The integration completed, but final reporting stopped: ") + safeError
       );
-      return interruptedBy === "SIGINT" ? 130 : 1;
+      return interruptedBy ? signalExitCode(interruptedBy) : 1;
     }
     await runtime.updateRun(selected.snapshot.run.id, {
       status: "failed",
@@ -3510,27 +3909,32 @@ async function run2(options) {
     } else {
       p.log.info(theme.muted("Generated rows and repository edits were preserved for resume."));
     }
-    return interruptedBy === "SIGINT" ? 130 : 1;
+    return interruptedBy ? signalExitCode(interruptedBy) : 1;
   } finally {
     clearInterval(heartbeat);
     stopKeepalive();
-    process.removeListener("SIGINT", interrupt);
-    process.removeListener("SIGTERM", interrupt);
   }
 }
-async function enforceGitSafety(repoPath, checkpoint, resumed, force = false) {
+async function enforceGitSafety(repoPath, checkpoint, resumed, force = false, diagnostics) {
   if (!checkpoint.isRepo) {
     if (!force) {
+      logGitSafety(diagnostics, checkpoint, resumed, force, false, false);
       p.cancel(
         "Not a git repository. Run `git init` and commit first, or use --force without automatic undo."
       );
       return false;
     }
+    logGitSafety(diagnostics, checkpoint, resumed, force, false, true);
     p.log.warn("Not a git repository; automatic undo is unavailable.");
     return true;
   }
-  if (await isWorkingTreeClean(repoPath)) return true;
+  const clean = await isWorkingTreeClean(repoPath);
+  if (clean) {
+    logGitSafety(diagnostics, checkpoint, resumed, force, clean, true);
+    return true;
+  }
   if (force) {
+    logGitSafety(diagnostics, checkpoint, resumed, force, clean, true);
     p.log.warn(
       theme.warn("Uncommitted changes present") + theme.muted("; this invocation will preserve them if it is reverted.")
     );
@@ -3538,6 +3942,7 @@ async function enforceGitSafety(repoPath, checkpoint, resumed, force = false) {
   }
   if (resumed) {
     if (!process.stdin.isTTY || !process.stdout.isTTY) {
+      logGitSafety(diagnostics, checkpoint, resumed, force, clean, false);
       p.cancel(
         "The resumed repository has uncommitted changes. Re-run with --force after confirming they are safe to edit."
       );
@@ -3547,9 +3952,14 @@ async function enforceGitSafety(repoPath, checkpoint, resumed, force = false) {
       message: "This resumed repository has uncommitted changes. Confirm they are the wizard edits you want to continue.",
       initialValue: false
     });
-    if (p.isCancel(confirmed) || !confirmed) return false;
+    if (p.isCancel(confirmed) || !confirmed) {
+      logGitSafety(diagnostics, checkpoint, resumed, force, clean, false);
+      return false;
+    }
+    logGitSafety(diagnostics, checkpoint, resumed, force, clean, true);
     return true;
   }
+  logGitSafety(diagnostics, checkpoint, resumed, force, clean, false);
   p.cancel(
     "Your working tree has uncommitted changes. Commit or stash them first, or use --force."
   );
@@ -3606,9 +4016,16 @@ async function chooseTarget(detections) {
   const playbook = playbookByTargetId(answer);
   return playbook ? { playbook, detection: detections.find((item) => item.target.id === answer) } : null;
 }
-async function withBrowserAuth(config) {
+async function withBrowserAuth(config, diagnostics, signal) {
+  diagnostics?.log("auth_stage", { stage: "authorization_started" });
   p.log.step(theme.bright("Authenticate") + theme.muted(" - opening device approval"));
-  const auth = await startDeviceAuth(config);
+  const auth = await startDeviceAuth(config, signal);
+  diagnostics?.registerSecrets(
+    auth.userCode,
+    auth.verificationUrl,
+    auth.verificationUrlComplete
+  );
+  diagnostics?.log("auth_stage", { stage: "device_authorization_created" });
   p.note(
     [
       `Code: ${auth.userCode}`,
@@ -3619,19 +4036,64 @@ async function withBrowserAuth(config) {
   );
   try {
     await open3(auth.verificationUrlComplete ?? auth.verificationUrl);
+    diagnostics?.log("auth_stage", { stage: "browser_opened" });
   } catch {
+    diagnostics?.log("auth_stage", { stage: "browser_open_failed" });
   }
   const spin = p.spinner();
   spin.start("Waiting for browser approval");
   try {
     const session = await auth.poll();
+    diagnostics?.registerSecrets(session.token);
+    diagnostics?.log("auth_stage", { stage: "approved" });
     spin.stop(theme.success("Authenticated"));
     return session;
   } catch (error) {
+    diagnostics?.log("auth_stage", {
+      stage: "failed",
+      ...diagnosticErrorData(error)
+    });
     spin.stop(theme.alert("Authentication failed"));
     throw error;
   }
 }
+function handledSignal(value) {
+  return value === "SIGINT" || value === "SIGTERM" ? value : void 0;
+}
+function signalExitCode(signal) {
+  return signal === "SIGTERM" ? 143 : 130;
+}
+function logGitSafety(diagnostics, checkpoint, resumed, force, clean, allowed) {
+  diagnostics?.log("git_safety", {
+    isRepository: checkpoint.isRepo,
+    clean,
+    forced: force,
+    resumed,
+    allowed,
+    automaticUndo: checkpoint.isRepo
+  });
+}
+function safeProgressText(value) {
+  return scrubError(value).replace(/\s+/g, " ").slice(0, 160);
+}
+function activityCategory(value) {
+  const categories = [
+    ["Edited ", "repository_edit"],
+    ["Created ", "repository_create"],
+    ["Configured ", "ingestion_configured"],
+    ["Running ", "command_started"],
+    ["Reading ", "repository_read"],
+    ["Scanning ", "repository_scan"],
+    ["Searching ", "repository_search"],
+    ["Persisted ", "model_item_persisted"],
+    ["Verification failed", "verification_failed"],
+    ["The stable end-user identity", "identity_wiring_pending"],
+    ["Generated events", "event_wiring_pending"],
+    ["Runtime model", "runtime_completed"],
+    ["The previous model conversation", "conversation_restarted"]
+  ];
+  return categories.find(([prefix]) => value.startsWith(prefix))?.[1] ?? "progress_update";
+}
 async function withSpinner(label, action) {
   const spin = p.spinner();
   spin.start(label);
@@ -3647,7 +4109,7 @@ async function withSpinner(label, action) {
 async function hasIdentifyCall2(repoPath, files) {
   for (const file of files) {
     try {
-      if (hasWhisperrMethodCall(await readFile6(join6(repoPath, file), "utf8"), "identify")) {
+      if (hasWhisperrMethodCall(await readFile6(join7(repoPath, file), "utf8"), "identify")) {
         return true;
       }
     } catch {
@@ -3659,7 +4121,7 @@ async function hasIdentifyCall2(repoPath, files) {
 // src/index.ts
 var modulePath = fileURLToPath(import.meta.url);
 function packageVersion() {
-  const packagePath = join7(dirname4(modulePath), "..", "package.json");
+  const packagePath = join8(dirname5(modulePath), "..", "package.json");
   const pkg = JSON.parse(readFileSync(packagePath, "utf8"));
   return pkg.version ?? "0.0.0";
 }
@@ -3725,18 +4187,81 @@ async function main() {
     console.log(packageVersion());
     return;
   }
+  await runInvocation(parsed);
+}
+async function runInvocation(options, dependencies = {}) {
+  const createDiagnostics = dependencies.createDiagnostics ?? ((repoPath2) => WizardDiagnostics.create(repoPath2));
+  const runWizard = dependencies.run ?? run2;
+  const addSignalListener = dependencies.addSignalListener ?? ((signal, listener) => process.once(signal, listener));
+  const removeSignalListener = dependencies.removeSignalListener ?? ((signal, listener) => process.removeListener(signal, listener));
+  const setExitCode = dependencies.setExitCode ?? ((code2) => process.exitCode = code2);
+  const log2 = dependencies.log ?? console.log;
+  const reportError = dependencies.error ?? console.error;
+  const repoPath = resolve5(options.path ?? process.cwd());
+  let diagnostics;
   try {
-    const code2 = await run2(parsed);
-    process.exit(code2);
+    diagnostics = createDiagnostics(repoPath);
+  } catch {
+    reportError("Unable to create secure diagnostics. The wizard did not run.");
+    setExitCode(1);
+    return;
+  }
+  diagnostics.log("invocation_start", {
+    version: packageVersion(),
+    forced: Boolean(options.force)
+  });
+  log2(`Diagnostics: ${diagnostics.path}`);
+  const abortController = new AbortController();
+  let receivedSignal;
+  const handlers = {
+    SIGINT: () => handleSignal("SIGINT"),
+    SIGTERM: () => handleSignal("SIGTERM")
+  };
+  function handleSignal(signal) {
+    if (receivedSignal) return;
+    receivedSignal = signal;
+    diagnostics.log("termination_requested", { signal });
+    abortController.abort(signal);
+  }
+  addSignalListener("SIGINT", handlers.SIGINT);
+  addSignalListener("SIGTERM", handlers.SIGTERM);
+  let exitCode = 1;
+  try {
+    const code2 = await runWizard(options, diagnostics, {
+      signal: abortController.signal
+    });
+    exitCode = receivedSignal ? signalExitCode2(receivedSignal) : code2;
+    diagnostics.log("invocation_end", {
+      outcome: receivedSignal ? "signal" : code2 === 0 ? "completed" : "failed",
+      exitCode,
+      signal: receivedSignal
+    });
   } catch (err) {
-    console.error("\n" + theme.alert("Unexpected error: ") + err.message);
-    process.exit(1);
+    if (receivedSignal) {
+      exitCode = signalExitCode2(receivedSignal);
+      diagnostics.log("invocation_end", {
+        outcome: "signal",
+        exitCode,
+        signal: receivedSignal
+      });
+    } else {
+      diagnostics.log("invocation_failure", diagnosticErrorData(err));
+      reportError("\n" + theme.alert("Unexpected error: ") + scrubError(err));
+    }
+  } finally {
+    removeSignalListener("SIGINT", handlers.SIGINT);
+    removeSignalListener("SIGTERM", handlers.SIGTERM);
+    diagnostics.close();
+    setExitCode(exitCode);
   }
 }
+function signalExitCode2(signal) {
+  return signal === "SIGINT" ? 130 : 143;
+}
 function isCliEntry() {
   if (!process.argv[1]) return false;
   try {
-    return realpathSync(modulePath) === realpathSync(process.argv[1]);
+    return realpathSync2(modulePath) === realpathSync2(process.argv[1]);
   } catch {
     return modulePath === process.argv[1];
   }
@@ -3747,5 +4272,6 @@ if (isCliEntry()) {
 export {
   main,
   packageVersion,
-  parseArgs
+  parseArgs,
+  runInvocation
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@whisperr/wizard",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Generate a codebase-aware Whisperr intervention model and integrate its SDK and events in one command.",
   "repository": {
     "type": "git",