@mrclrchtr/supi-debug 4.10.0 → 6.0.0

package/README.md

@@ -27,10 +27,10 @@ pi install ./packages/supi-debug
 After install, this package wires the shared debug registry into three user-facing surfaces:
 
 - `/supi-debug` — show recent debug events in a readable TUI report
-- `supi_debug` — let the model query recent debug events during troubleshooting
+- `debug` — let the model query recent debug events during troubleshooting
 - `/supi-settings` integration — configure whether events are captured and how much data is exposed
 
-It also registers a **Debug** provider section for `/supi-context`.
+It also registers a **Debug** provider section for `/supi-context`, and ships a `/supi-tooling-retro` prompt template for post-task retrospective feedback on the SuPi tooling used in the completed task.
 
 ## Event behavior
 
@@ -40,6 +40,12 @@ It also registers a **Debug** provider section for `/supi-context`.
 - if debug capture is disabled, no events are retained
 - agent-facing access is blocked, sanitized, or raw depending on settings
 
+### Identity disclosure
+
+Retained and persisted LSP debug events may identify local workspaces and files. Since the LSP telemetry expansion, LSP events can carry the absolute workspace root (`cwd`), the configured server name (`server`), workspace-relative file paths (`file`), exact LSP method names (`method`), and the server root (`root`). Identity strings are bounded to 512 UTF-16 code units and server lists to 16 entries.
+
+Identity fields are **not** secret-redacted. The debug registry redacts secret keys and secret-looking values (tokens, passwords, API keys, authorization headers, URL credentials), but server names, file paths, method names, and workspace roots pass through unredacted by design, so local protocol failures stay diagnosable. Treat retained and persisted LSP events as potentially identifying your local machine, project layout, and file names.
+
 ## Rendering
 
 `/supi-debug` uses a custom TUI message renderer that shows two levels of detail:
@@ -63,6 +69,7 @@ Rendered fields per event:
 - optional `cwd`
 - optional `data`
 - optional `rawData`
+- optional `operationId` for events directly owned by one public `code_*` call
 
 ### Why collapsed by default
 
@@ -71,23 +78,24 @@ keeps the conversation focused; expand only when you need the details.
 
 ### Seeing full details without expanding
 
-The agent-facing `supi_debug` tool returns the expanded plain-text
+The agent-facing `debug` tool returns the expanded plain-text
 representation, subject to PI's standard tool-output truncation limits. This is
 useful for automated troubleshooting flows while protecting the model context
 from very large event payloads.
 
 ## Filters
 
-Both `/supi-debug` and `supi_debug` support the same basic filters:
+Both `/supi-debug` and `debug` support the same basic filters:
 
 - `source`
 - `level`
 - `category`
+- exact `operationId`
 - `limit`
 
-For historical sessions, pass `sessionFile` to `supi_debug`, or
+For historical sessions, pass `sessionFile` to `debug`, or
 `sessionFile=<path>` to `/supi-debug`. Historical sessions never retain raw data.
-The tool also accepts `includeRaw` for live-session data when settings allow it.
+The tool also accepts `includeRaw` for live-session data when settings allow it. A Debug Operation ID groups direct request ownership only. It is not a security identity, distributed trace, raw Pi Tool-call identity, or time-window correlation.
 
 ## Settings
 
@@ -100,7 +108,7 @@ Available settings:
 - `maxEvents` — maximum retained events in memory
 
 Historical inspection works for events captured after this version is loaded. For example, an
-agent can call `supi_debug` with `sessionFile` set to a PI session JSONL path.
+agent can call `debug` with `sessionFile` set to a PI session JSONL path.
 
 Defaults come from the shared debug registry:
 

package/node_modules/@mrclrchtr/supi-core/README.md

@@ -28,6 +28,7 @@ pnpm add @mrclrchtr/supi-core
 - `loadSupiConfig()` — merged config with resolution order `defaults <- global <- project`
 - `loadSupiConfigForScope()` — load one scope at a time for settings UIs
 - `writeSupiConfig()` — persist values
+- `replaceSupiConfigSection()` — replace one nested section while preserving other sections
 - `removeSupiConfigKey()` — remove a key or override
 
 Config file locations:
@@ -49,6 +50,7 @@ Config file locations:
 
 - context-provider registry for `/supi-context`
 - debug-event registry and monotonic phase timers for producers that want shared debug capture
+- optional Debug Operation IDs for exact, directly owned public Tool-call correlation; ambient events stay uncorrelated
 - settings registry used by `/supi-settings`
 
 ### Project and session helpers

package/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "4.10.0",
+  "version": "6.0.0",
   "description": "Shared settings, configuration, reporting, and session infrastructure",
   "license": "MIT",
   "repository": {
@@ -53,7 +53,7 @@
     "./api": "./src/api.ts",
     "./config": "./src/config.ts",
     "./context": "./src/context.ts",
-    "./debug": "./src/debug-registry.ts",
+    "./debug": "./src/debug.ts",
     "./evidence-badge": "./src/evidence-badge.ts",
     "./footer-registry": "./src/footer-registry.ts",
     "./llm": "./src/llm.ts",

package/node_modules/@mrclrchtr/supi-core/src/api.ts

@@ -11,7 +11,7 @@ export * from "./config.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./context.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
-export * from "./debug-registry.ts";
+export * from "./debug.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./evidence-badge.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel

package/node_modules/@mrclrchtr/supi-core/src/config/config.ts

@@ -148,6 +148,37 @@ export function writeSupiConfig(
   fs.writeFileSync(configPath, `${JSON.stringify(existing, null, 2)}\n`, "utf-8");
 }
 
+/**
+ * Replace one complete config section while preserving other sections.
+ *
+ * This is useful for nested settings that must remove stale keys as part of
+ * one update. An empty section is removed from the config file.
+ */
+export function replaceSupiConfigSection(
+  loc: SupiConfigLocation,
+  value: Record<string, unknown>,
+  options?: SupiConfigOptions,
+): void {
+  const configPath = getSupiConfigPath(loc.scope, loc.cwd, options);
+  const existing = readJsonFile(configPath) ?? {};
+
+  if (Object.keys(value).length > 0) existing[loc.section] = value;
+  else delete existing[loc.section];
+
+  const content = Object.keys(existing).length > 0 ? `${JSON.stringify(existing, null, 2)}\n` : "";
+  if (content) {
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, content, "utf-8");
+    return;
+  }
+
+  try {
+    fs.unlinkSync(configPath);
+  } catch {
+    // File may not exist.
+  }
+}
+
 /**
  * Remove a key from a config section.
  * Used by `interval default` to remove the project override.

package/node_modules/@mrclrchtr/supi-core/src/config.ts

@@ -1,10 +1,12 @@
 // supi-core config domain — config loading.
 export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
 export {
+  getSupiConfigPath,
   loadSupiConfig,
   loadSupiConfigForScope,
   loadSupiConfigSectionForScope,
   readJsonFile,
   removeSupiConfigKey,
+  replaceSupiConfigSection,
   writeSupiConfig,
 } from "./config/config.ts";

package/node_modules/@mrclrchtr/supi-core/src/debug-registry.ts

@@ -4,9 +4,6 @@
 // supi-debug extension owns policy/configuration and exposes events through a
 // command/tool while this module stays dependency-free for producers.
 
-// biome-ignore lint/performance/noReExportAll: preserve the stable debug domain entry point
-export * from "./debug-timing.ts";
-
 export type DebugLevel = "debug" | "info" | "warning" | "error";
 export type DebugAgentAccess = "off" | "sanitized" | "raw";
 export interface DebugRegistryConfig {
@@ -25,6 +22,8 @@ export const DEBUG_REGISTRY_DEFAULTS: DebugRegistryConfig = {
 };
 
 export interface DebugEventInput {
+  /** Opaque identity for events directly owned by one public Tool call. */
+  operationId?: string;
   source: string;
   level: DebugLevel;
   category: string;
@@ -42,6 +41,8 @@ export interface DebugEvent extends DebugEventInput {
 }
 
 export interface DebugEventQuery {
+  /** Match one exact Debug Operation ID. */
+  operationId?: string;
   source?: string;
   level?: DebugLevel;
   category?: string;
@@ -53,6 +54,7 @@ export interface DebugEventQuery {
 export interface DebugEventView {
   id: number;
   timestamp: number;
+  operationId?: string;
   source: string;
   level: DebugLevel;
   category: string;
@@ -84,6 +86,7 @@ interface DebugRegistryState {
 }
 
 const REGISTRY_KEY = Symbol.for("@mrclrchtr/supi-core/debug-registry");
+const DEBUG_OPERATION_ID_RE = /^op-[A-Za-z0-9_-]{21}[AQgw]$/;
 const SECRET_KEY_RE = /(?:token|password|passwd|secret|api[_-]?key|authorization|credential)/i;
 const ENV_SECRET_RE =
   /\b([A-Za-z0-9_]*(?:token|password|passwd|secret|api[_-]?key|authorization|credential)[A-Za-z0-9_]*)=(?:'[^']*'|"[^"]*"|\S+)/gi;
@@ -135,11 +138,17 @@ export function isDebugLevel(value: unknown): value is DebugLevel {
   return value === "debug" || value === "info" || value === "warning" || value === "error";
 }
 
-/** Match a debug event against the supported source, level, and category filters. */
+/** Return whether a value has the exact 16-byte base64url Debug Operation ID form. */
+export function isDebugOperationId(value: unknown): value is string {
+  return typeof value === "string" && DEBUG_OPERATION_ID_RE.test(value);
+}
+
+/** Match a debug event against the supported exact filters. */
 export function matchesDebugEventQuery(
-  event: Pick<DebugEventView, "source" | "level" | "category">,
-  query: Pick<DebugEventQuery, "source" | "level" | "category">,
+  event: Pick<DebugEventView, "operationId" | "source" | "level" | "category">,
+  query: Pick<DebugEventQuery, "operationId" | "source" | "level" | "category">,
 ): boolean {
+  if (query.operationId && event.operationId !== query.operationId) return false;
   if (query.source && event.source !== query.source) return false;
   if (query.level && event.level !== query.level) return false;
   if (query.category && event.category !== query.category) return false;
@@ -197,6 +206,7 @@ function toSanitizedView(event: DebugEvent): DebugEventView {
   return {
     id: event.id,
     timestamp: event.timestamp,
+    operationId: event.operationId,
     source: event.source,
     level: event.level,
     category: event.category,
@@ -216,6 +226,9 @@ export function subscribeDebugEvents(listener: DebugEventListener): () => void {
 /** Record a session-local debug event if debugging is enabled. */
 export function recordDebugEvent(input: DebugEventInput): DebugEvent | null {
   const state = getState();
+  if (input.operationId !== undefined && !isDebugOperationId(input.operationId)) {
+    return null;
+  }
   if (!state.config.enabled) {
     return null;
   }

package/node_modules/@mrclrchtr/supi-core/src/debug.ts

@@ -0,0 +1,9 @@
+// Debug domain entry for `@mrclrchtr/supi-core/debug`.
+//
+// Kept separate from debug-registry.ts so debug-timing.ts can import the
+// registry without creating an import cycle through the barrel re-export.
+
+// biome-ignore lint/performance/noReExportAll: preserve the stable debug domain entry point
+export * from "./debug-registry.ts";
+// biome-ignore lint/performance/noReExportAll: preserve the stable debug domain entry point
+export * from "./debug-timing.ts";

package/node_modules/@mrclrchtr/supi-core/src/index.ts

@@ -11,7 +11,7 @@ export * from "./config.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./context.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
-export * from "./debug-registry.ts";
+export * from "./debug.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./footer-registry.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel

package/node_modules/@mrclrchtr/supi-core/src/settings/settings-registry.ts

@@ -41,7 +41,10 @@ export interface SettingsApplyResult {
  */
 export interface SettingsModule {
   id: string;
+  /** Human-readable section label shown in the UI. */
   label: string;
+  /** Optional label that groups this module within its section. */
+  subsection?: string;
   read(context: SettingsContext): Promise<SettingsSnapshot>;
   apply(request: SettingsActionRequest): Promise<SettingsApplyResult>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-debug",
-  "version": "4.10.0",
+  "version": "6.0.0",
   "description": "Capture and inspect SuPi debug events",
   "license": "MIT",
   "repository": {
@@ -28,10 +28,11 @@
   "type": "module",
   "files": [
     "src/**/*.ts",
+    "prompts",
     "README.md"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "4.10.0"
+    "@mrclrchtr/supi-core": "6.0.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

package/prompts/supi-tooling-retro.md

@@ -0,0 +1,77 @@
+---
+description: Retrospect on SuPi tooling used during the completed task
+---
+
+Produce a compact, evidence-based retrospective of the task that just ended. Evaluate the SuPi surfaces that were available and relevant: tools, skills, prompts, extensions, injected context or guidance, documentation, settings, and human-only TUI commands. Do not evaluate the entire suite in the abstract. Do not evaluate pi-core behavior.
+
+## Evidence rules
+
+- Reconstruct the retrospective from this session only. Do not invent tool calls, outcomes, failures, token costs, or user impact.
+- You may query the `debug` tool to verify event-level claims. You may query `cache_forensics` when it is available to verify cache-related claims. Use such queries only for verification, and keep them few. Do not perform any other tool calls or follow-up investigation. Stop after you write the retrospective.
+- Tag every claim as `[observed]`, `[inferred]`, or `[unknown]`. An observed claim is supported by the transcript, a tool result, or an evidence query. An inferred claim is plausible but untested.
+- Rate the impact of each surfaced item as `high`, `medium`, or `low`. The impact is the degree to which the item changed the task outcome or its cost.
+- Use the exact surface name that appears in the session. Do not treat an available but unused tool as evidence of failure.
+- If no SuPi surface was used or relevant, say so explicitly. Do not build a wishlist. List only task-specific, plausible missed help.
+
+## Evaluate
+
+- SuPi surfaces that were actually used: what they enabled, where they fell short, and any failure or friction.
+- Failed or mis-parameterized tool calls: SuPi surface calls that failed or were rejected for wrong, missing, or invalid parameters, including calls corrected on retry. Name the cause: agent misuse, ambiguous tool description, missing guidance (promptSnippet or promptGuidelines), a schema gap, or a tool bug.
+- Recognized problems or bugs: concrete defects in SuPi surfaces, such as crashes, wrong output, failed calls for valid usage, regressions, inconsistent behavior, or guidance that led to a wrong action. Do not report defects in the project's own code.
+- Missed opportunities: a relevant unused tool (for example a supi-code-intelligence tool) or context source, and why it was missed. Name the cause: discoverability, guidance, timing, capability, or not applicable.
+- Missing pieces: a concrete utility, capability, documentation page, example, or output improvement that would have changed this task.
+- Noise: redundant instructions, repeated advice without added value, stale or irrelevant context, excessive output, unnecessary long paths, poor timing, or misleading guidance. Do not criticize necessary context without naming the avoidable cost.
+- Keep SuPi or tooling recommendations separate from general code or project recommendations.
+
+## Output rules
+
+- Keep the result under about 600 words and specific to this task.
+- Open with a one-line overall verdict on SuPi tooling for this task.
+- Give each item a confidence tag and an impact rating. `None identified` lines need neither.
+- Prefer concrete evidence and observed friction over generic praise or a feature wishlist.
+- If a section has no supported item, write `None identified` and briefly explain the evidence limit.
+- Include at most three recommendations. Each must name a changeable surface (tool, prompt, skill, docs, guidance, or feature), the proposed change, and the expected benefit. Recommended changes may target tool descriptions, parameter schemas, or guidance, especially when they address the Failed or mis-parameterized tool calls listed above. Do not recommend "use the tool more" unless discoverability is the identified cause.
+- Do not edit files, open issues, update OpenSpec artifacts, or take any other follow-up action.
+
+## Required output
+
+## SuPi Tooling Retrospective
+
+**Task completed**: <1–2 sentence summary>
+
+**Verdict**: <one line: the overall state of SuPi tooling for this task and its biggest lever>
+
+### Tools used
+- `[observed · impact: high|medium|low]` **`<surface>`** — concrete help, friction, or failure.
+- If none: `None identified — no SuPi surface materially participated in this task.`
+
+### Failed or mis-parameterized tool calls
+- `[observed|inferred · impact: high|medium|low]` **`<surface>`** — the call, the invalid or missing parameter, the outcome, and the cause: agent misuse, ambiguous description, missing guidance, schema gap, or tool bug. Include near misses: a call rejected once and corrected on retry is stronger evidence than a clean pass.
+- If none: `None identified — every SuPi call used valid parameters.`
+
+### Recognized problems or bugs
+- `[observed|inferred · impact: high|medium|low]` **`<surface>`** — the concrete defect (crash, wrong behavior, regression, inconsistency) and how it affected the task. Do not repeat ordinary friction that belongs under Tools used, and do not repeat parameter-caused call failures that belong under Failed or mis-parameterized tool calls.
+- If none: `None identified — no defect surfaced in this task.`
+
+### Missed opportunities
+- `[inferred · impact: high|medium|low]` **`<surface>`** — task-specific help it might have provided. Name the cause: discoverability, guidance, timing, capability, or not applicable.
+- If none: `None identified — do not infer a gap from non-use alone.`
+
+### Missing pieces
+- `[observed|inferred · impact: high|medium|low]` **`<utility, feature, docs, example, or output change>`** — the concrete gap and how it affected this task.
+- If none: `None identified.`
+
+### Unhelpful or noisy context
+- `[observed|inferred · impact: high|medium|low]` **`<instruction, context, or output>`** — what was unnecessary or costly, and how it could be reduced or better timed.
+- If none: `None identified.`
+
+### Prioritized recommendations
+1. **`<named surface>`** — <specific change>; <expected benefit>; confidence: <high|medium|low>.
+2. **`<named surface>`** — <specific change>; <expected benefit>; confidence: <high|medium|low>.
+3. **`<named surface>`** — <specific change>; <expected benefit>; confidence: <high|medium|low>.
+- Include only supported recommendations. If none are supported, write `None identified`.
+
+### Confidence / evidence
+- Direct evidence: <what the session and any evidence queries demonstrate>
+- Inference: <what is plausible but untested>
+- Limits: <what the session cannot establish>

package/src/command.ts

@@ -0,0 +1,132 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { getDebugEvents } from "@mrclrchtr/supi-core/debug";
+import { resolveToolPath } from "@mrclrchtr/supi-core/path";
+import { formatDebugEvents, truncateDebugOutput } from "./format-events.ts";
+import type { DebugToolParams } from "./query.ts";
+import { parseDebugCommandArgs } from "./query.ts";
+import { createDebugMessageDetails } from "./renderer.ts";
+import { readSessionDebugEvents } from "./session-events.ts";
+
+const DEBUG_REPORT_TYPE = "supi-debug-report";
+
+interface DebugConfig {
+  enabled: boolean;
+}
+
+interface DebugCommandDependencies {
+  pi: ExtensionAPI;
+  applyConfig: (cwd: string) => DebugConfig;
+  normalizeLimit: (value: string) => number;
+}
+
+function persistedDebugFilters(query: DebugToolParams) {
+  return {
+    operationId: query.operationId,
+    source: query.source,
+    level: query.level,
+    category: query.category,
+    limit: query.limit,
+  };
+}
+
+async function sendPersistedDebugReport(
+  query: DebugToolParams,
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+): Promise<void> {
+  const statusKey = "supi-debug";
+  const setStatus = ctx.ui?.setStatus;
+  try {
+    const filters = persistedDebugFilters(query);
+    if (!query.sessionFile)
+      throw new Error("A session file is required for historical debug events.");
+    const sessionFile = resolveToolPath(ctx.cwd, query.sessionFile);
+    const persisted =
+      ctx.signal || setStatus
+        ? await readSessionDebugEvents(sessionFile, filters, {
+            signal: ctx.signal,
+            onProgress: (progress) => {
+              setStatus?.(
+                statusKey,
+                `Reading debug events: ${progress.scannedLines.toLocaleString("en-US")} lines · ${progress.matchedEvents.toLocaleString("en-US")} matches`,
+              );
+            },
+          })
+        : await readSessionDebugEvents(sessionFile, filters);
+    const output = truncateDebugOutput(
+      formatDebugEvents(persisted.events, false, false, persisted.persistedEventCount).join("\n"),
+    );
+    pi.sendMessage({
+      customType: DEBUG_REPORT_TYPE,
+      content: output.text,
+      display: true,
+      details: createDebugMessageDetails(persisted.events, {
+        sessionFile: query.sessionFile,
+        persistedEventCount: persisted.persistedEventCount,
+        eventCount: persisted.events.length,
+        emptyReason:
+          persisted.events.length === 0
+            ? persisted.persistedEventCount === 0
+              ? "no-persisted-events"
+              : "no-matches"
+            : undefined,
+        truncation: output.truncation,
+      }),
+    });
+  } finally {
+    setStatus?.(statusKey, undefined);
+  }
+}
+
+function sendLiveDebugReport(query: DebugToolParams, pi: ExtensionAPI): void {
+  const { events, rawAccessDenied } = getDebugEvents(query);
+  const output = truncateDebugOutput(formatDebugEvents(events, rawAccessDenied).join("\n"));
+  pi.sendMessage({
+    customType: DEBUG_REPORT_TYPE,
+    content: output.text,
+    display: true,
+    details: createDebugMessageDetails(events, {
+      rawAccessDenied,
+      eventCount: events.length,
+      emptyReason: events.length === 0 ? "no-matches" : undefined,
+      truncation: output.truncation,
+    }),
+  });
+}
+
+async function handleDebugCommand(
+  args: string,
+  ctx: ExtensionCommandContext,
+  dependencies: DebugCommandDependencies,
+): Promise<void> {
+  const { pi, applyConfig, normalizeLimit } = dependencies;
+  const config = applyConfig(ctx.cwd);
+  const query = parseDebugCommandArgs(args, normalizeLimit);
+  if (!config.enabled && !query.sessionFile) {
+    pi.sendMessage({
+      customType: DEBUG_REPORT_TYPE,
+      content: "SuPi debug event capture is disabled. Enable Debug in /supi-settings.",
+      display: true,
+    });
+    return;
+  }
+
+  if (query.sessionFile) {
+    await sendPersistedDebugReport(query, ctx, pi);
+    return;
+  }
+  sendLiveDebugReport(query, pi);
+}
+
+/** Register the user-facing debug command. */
+export function registerDebugCommand(
+  pi: ExtensionAPI,
+  applyConfig: (cwd: string) => DebugConfig,
+  normalizeLimit: (value: string) => number,
+): void {
+  const dependencies = { pi, applyConfig, normalizeLimit };
+  pi.registerCommand("supi-debug", {
+    description: "Show recent SuPi debug events",
+    handler: (args, ctx) => handleDebugCommand(args, ctx, dependencies),
+  });
+}

package/src/config.ts

@@ -0,0 +1,83 @@
+// Debug config loading and live registry synchronization.
+
+import { loadSupiConfig } from "@mrclrchtr/supi-core/config";
+import {
+  clearDebugEvents,
+  configureDebugRegistry,
+  DEBUG_REGISTRY_DEFAULTS,
+  type DebugAgentAccess,
+} from "@mrclrchtr/supi-core/debug";
+
+export const DEBUG_SECTION = "debug";
+
+export interface DebugConfig extends Record<string, unknown> {
+  enabled: boolean;
+  agentAccess: DebugAgentAccess;
+  maxEvents: number;
+}
+
+export const DEBUG_DEFAULTS: DebugConfig = { ...DEBUG_REGISTRY_DEFAULTS };
+
+function normalizeAgentAccess(value: string): DebugAgentAccess {
+  return value === "off" || value === "raw" ? value : "sanitized";
+}
+
+export function normalizeMaxEvents(value: string | number): number {
+  const parsed = typeof value === "number" ? value : Number.parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : DEBUG_DEFAULTS.maxEvents;
+}
+
+function normalizeEnabled(value: unknown): boolean {
+  if (typeof value === "boolean") {
+    return value;
+  }
+
+  if (typeof value === "string") {
+    const normalized = value.trim().toLowerCase();
+    if (
+      normalized === "true" ||
+      normalized === "on" ||
+      normalized === "1" ||
+      normalized === "yes"
+    ) {
+      return true;
+    }
+    if (
+      normalized === "false" ||
+      normalized === "off" ||
+      normalized === "0" ||
+      normalized === "no" ||
+      normalized === ""
+    ) {
+      return false;
+    }
+    return DEBUG_DEFAULTS.enabled;
+  }
+
+  if (value === 1) return true;
+  if (value === 0) return false;
+  return DEBUG_DEFAULTS.enabled;
+}
+
+export function loadDebugConfig(cwd: string): DebugConfig {
+  const config = loadSupiConfig(DEBUG_SECTION, cwd, DEBUG_DEFAULTS);
+  return {
+    enabled: normalizeEnabled(config.enabled),
+    agentAccess: normalizeAgentAccess(String(config.agentAccess)),
+    maxEvents: normalizeMaxEvents(config.maxEvents),
+  };
+}
+
+export function applyDebugConfig(cwd: string): DebugConfig {
+  const config = loadDebugConfig(cwd);
+  configureDebugRegistry(config);
+  return config;
+}
+
+export function syncLiveDebugRegistry(cwd: string): DebugConfig {
+  const config = applyDebugConfig(cwd);
+  if (!config.enabled) {
+    clearDebugEvents();
+  }
+  return config;
+}