@kontextmind/kxm 0.6.0 → 0.7.10

package/plugins/kxm/src/commands.ts

@@ -1,4 +1,7 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID, timingSafeEqual } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
 import { HubClient, HubHttpError } from "./client.ts";
 import type {
   DeliveryMode,
@@ -62,6 +65,7 @@ export interface SessionTokenPayload {
   agentName?: string;
   toolPolicy?: ToolPolicy;
   issuedAt: string;
+  expiresAt?: string;
 }
 
 export interface CommandExecutionContext {
@@ -930,6 +934,13 @@ export function parseAttemptToken(token: string): AttemptTokenPayload | undefine
   return undefined;
 }
 
+export function timingSafeStringCompare(a: string | undefined, b: string | undefined): boolean {
+  if (typeof a !== "string" || typeof b !== "string") return false;
+  const hashA = createHash("sha256").update(a).digest();
+  const hashB = createHash("sha256").update(b).digest();
+  return timingSafeEqual(hashA, hashB);
+}
+
 export function mintSessionToken(input?: {
   sessionId?: string;
   agentName?: string;
@@ -937,26 +948,53 @@ export function mintSessionToken(input?: {
   preset?: string;
   allowedTools?: string[];
   deniedTools?: string[];
+  expiresAt?: string;
+  ttlMs?: number;
 }): string {
   const toolPolicy: ToolPolicy | undefined = input?.toolPolicy ?? (
     input?.allowedTools || input?.deniedTools || input?.preset
       ? {
           ...(input?.preset ? { preset: input.preset } : {}),
-          ...(input?.allowedTools ? { allow: input.allowedTools } : {}),
-          ...(input?.deniedTools ? { deny: input.deniedTools } : {}),
+          ...(input?.allowedTools ? { allow: input.allowedTools, allowedTools: input.allowedTools } : {}),
+          ...(input?.deniedTools ? { deny: input.deniedTools, deniedTools: input.deniedTools } : {}),
         }
       : undefined
   );
+  const issuedAt = new Date().toISOString();
+  // Decision Q2: Default 24-hour TTL for disk SessionToken
+  const defaultTtlMs = 24 * 60 * 60 * 1000;
+  const ttlMs = typeof input?.ttlMs === "number" && input.ttlMs > 0 ? input.ttlMs : defaultTtlMs;
+  const expiresAt = input?.expiresAt ?? new Date(Date.now() + ttlMs).toISOString();
+
   const payload: SessionTokenPayload = {
     schema: "kxm.session-token.v1",
     sessionId: input?.sessionId ?? `session-${randomUUID()}`,
-    issuedAt: new Date().toISOString(),
+    issuedAt,
+    expiresAt,
     ...(input?.agentName ? { agentName: input.agentName } : {}),
     ...(toolPolicy ? { toolPolicy } : {}),
   };
   return Buffer.from(JSON.stringify(payload)).toString("base64url");
 }
 
+export function isSessionTokenExpired(payloadOrToken: SessionTokenPayload | string): boolean {
+  let payload: SessionTokenPayload | undefined;
+  if (typeof payloadOrToken === "string") {
+    try {
+      const raw = Buffer.from(payloadOrToken.trim(), "base64url").toString("utf8");
+      payload = JSON.parse(raw) as SessionTokenPayload;
+    } catch {
+      return true;
+    }
+  } else {
+    payload = payloadOrToken;
+  }
+  if (!payload || !payload.expiresAt) return false;
+  const expiryTime = new Date(payload.expiresAt).getTime();
+  if (Number.isNaN(expiryTime)) return true;
+  return Date.now() >= expiryTime;
+}
+
 export function parseSessionToken(token: string): SessionTokenPayload | undefined {
   try {
     const raw = Buffer.from(token.trim(), "base64url").toString("utf8");
@@ -967,6 +1005,12 @@ export function parseSessionToken(token: string): SessionTokenPayload | undefine
       && parsed.schema === "kxm.session-token.v1"
       && typeof parsed.sessionId === "string"
     ) {
+      if (parsed.expiresAt) {
+        const expiryTime = new Date(parsed.expiresAt).getTime();
+        if (!Number.isNaN(expiryTime) && Date.now() >= expiryTime) {
+          return undefined; // Expired token fails closed
+        }
+      }
       return parsed as SessionTokenPayload;
     }
   } catch {
@@ -975,6 +1019,61 @@ export function parseSessionToken(token: string): SessionTokenPayload | undefine
   return undefined;
 }
 
+function resolveUserConfigDirectory(overrideDir?: string | undefined): string {
+  if (overrideDir) return resolve(overrideDir);
+  return resolve(process.env.KXM_USER_CONFIG_DIR?.trim() || join(homedir(), ".config", "kxm"));
+}
+
+export function sessionTokenPath(userConfigDir?: string | undefined): string {
+  return join(resolveUserConfigDirectory(userConfigDir), "session.token");
+}
+
+export function persistSessionTokenToDisk(
+  token: string,
+  options?: { userConfigDir?: string | undefined; mode?: number | undefined } | undefined,
+): string {
+  const filePath = sessionTokenPath(options?.userConfigDir);
+  const dir = dirname(filePath);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const mode = options?.mode ?? 0o600;
+  writeFileSync(filePath, `${token.trim()}\n`, { encoding: "utf8", mode });
+  try {
+    chmodSync(filePath, mode);
+  } catch {
+    // Ignore permissions error on filesystems that do not support POSIX modes
+  }
+  return filePath;
+}
+
+export function readSessionTokenFromDisk(options?: {
+  userConfigDir?: string | undefined;
+} | undefined): { token: string; payload: SessionTokenPayload } | undefined {
+  const filePath = sessionTokenPath(options?.userConfigDir);
+  if (!existsSync(filePath)) return undefined;
+  try {
+    const token = readFileSync(filePath, "utf8").trim();
+    if (!token) return undefined;
+    const payload = parseSessionToken(token);
+    if (!payload) return undefined;
+    return { token, payload };
+  } catch {
+    return undefined;
+  }
+}
+
+export function clearSessionTokenFromDisk(options?: {
+  userConfigDir?: string | undefined;
+} | undefined): boolean {
+  const filePath = sessionTokenPath(options?.userConfigDir);
+  if (!existsSync(filePath)) return false;
+  try {
+    unlinkSync(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function matchToolPattern(pattern: string, toolName: string): boolean {
   if (pattern === "*" || pattern === toolName) return true;
   if (pattern.endsWith("*")) {
@@ -1026,6 +1125,7 @@ export function isToolAllowed(commandName: string, policy?: ToolPolicy): boolean
 export function enforceToolPolicy(
   commandName: string,
   env: NodeJS.ProcessEnv = process.env,
+  options?: { runId?: string; stageId?: string },
 ): { allowed: boolean; error?: string; detail?: string } {
   const attemptTokenRaw = env.KXM_ATTEMPT_TOKEN?.trim();
   if (attemptTokenRaw) {
@@ -1040,14 +1140,56 @@ export function enforceToolPolicy(
         detail: `command ${commandName} is denied by attempt tool policy`,
       };
     }
+    // AttemptToken boundary: AttemptTokens are strictly worker tokens.
+    // They cannot execute administrative state promotion unless explicitly allowed in toolPolicy
+    if (commandName === "kxm_promote" || commandName === "promote") {
+      const explicitAllow = attempt.toolPolicy?.allow ?? attempt.toolPolicy?.allowedTools;
+      if (!Array.isArray(explicitAllow) || (!explicitAllow.includes("kxm_promote") && !explicitAllow.includes("promote") && !explicitAllow.includes("*"))) {
+        return {
+          allowed: false,
+          error: "attempt_token_admin_denied",
+          detail: "AttemptToken worker cannot perform operator state promotion without explicit policy grant",
+        };
+      }
+    }
+    // AttemptToken boundary: Scoped strictly to runId if provided in execution options
+    if (options?.runId && attempt.runId && options.runId !== attempt.runId) {
+      return {
+        allowed: false,
+        error: "attempt_token_scope_violation",
+        detail: `attempt token runId ${attempt.runId} does not match request runId ${options.runId}`,
+      };
+    }
+    return { allowed: true };
+  }
+
+  const envSessionRaw = env.KXM_SESSION_TOKEN?.trim();
+  if (envSessionRaw) {
+    const session = parseSessionToken(envSessionRaw);
+    if (!session) {
+      return { allowed: false, error: "session_token_invalid", detail: "KXM_SESSION_TOKEN is malformed or expired" };
+    }
+    if (!isToolAllowed(commandName, session.toolPolicy)) {
+      return {
+        allowed: false,
+        error: "tool_policy_denied",
+        detail: `command ${commandName} is denied by session tool policy`,
+      };
+    }
     return { allowed: true };
   }
 
-  const sessionTokenRaw = env.KXM_SESSION_TOKEN?.trim();
-  if (sessionTokenRaw) {
-    const session = parseSessionToken(sessionTokenRaw);
+  const tokenFile = sessionTokenPath(env.KXM_USER_CONFIG_DIR);
+  if (existsSync(tokenFile)) {
+    let tokenRaw: string | undefined;
+    try {
+      tokenRaw = readFileSync(tokenFile, "utf8").trim();
+    } catch {
+      return { allowed: false, error: "session_token_invalid", detail: "Session token file on disk could not be read" };
+    }
+    const session = tokenRaw ? parseSessionToken(tokenRaw) : undefined;
     if (!session) {
-      return { allowed: false, error: "session_token_invalid", detail: "KXM_SESSION_TOKEN is malformed" };
+      return { allowed: false, error: "session_token_invalid", detail: "Session token on disk is malformed or expired" };
     }
     if (!isToolAllowed(commandName, session.toolPolicy)) {
       return {

package/plugins/kxm/src/completion-install.ts

@@ -0,0 +1,223 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, delimiter, dirname, isAbsolute, join, resolve } from "node:path";
+import { generateShellCompletion, type SupportedShell } from "./autocomplete.ts";
+
+export const COMPLETION_MARKER = "# kxm completion";
+export const PATH_MARKER = "# kxm path";
+export interface CompletionInstallOptions {
+  env?: NodeJS.ProcessEnv | undefined;
+  homeDir?: string | undefined;
+  configDir?: string | undefined;
+  platform?: NodeJS.Platform | undefined;
+  isTty?: boolean | undefined;
+  shell?: string | undefined;
+  dryRun?: boolean | undefined;
+  overwrite?: boolean | undefined;
+}
+
+export interface CompletionInstallReport {
+  ok: boolean;
+  shell: SupportedShell | "unknown";
+  scriptPath: string;
+  rcFile: string | undefined;
+  rcModified: boolean;
+  alreadyInstalled: boolean;
+  reason?: string | undefined;
+}
+
+export function detectShell(env: NodeJS.ProcessEnv = process.env, platform: NodeJS.Platform = process.platform): SupportedShell | "unknown" {
+  const shellPath = env.SHELL?.trim() || (process.platform === "win32" ? undefined : env.SHELL?.trim());
+  const name = shellPath ? basename(shellPath).toLowerCase() : "";
+  if (name === "bash" || name === "zsh" || name === "fish") return name;
+  if (name.endsWith("bash") || name.includes("bash")) return "bash";
+  if (name.endsWith("zsh")) return "zsh";
+  if (name.endsWith("fish")) return "fish";
+  return "unknown";
+}
+
+function effectiveHome(options: Pick<CompletionInstallOptions, "env" | "homeDir">): string {
+  const env = options.env ?? process.env;
+  if (options.homeDir) return options.homeDir;
+  const envHome = env.HOME?.trim() ?? env.USERPROFILE?.trim();
+  return envHome && envHome.length > 0 ? resolve(envHome) : homedir();
+}
+
+export function completionScriptPath(shell: SupportedShell, options: Pick<CompletionInstallOptions, "env" | "homeDir" | "configDir"> = {}): string {
+  const env = options.env ?? process.env;
+  const explicit = options.configDir ?? env.KXM_USER_CONFIG_DIR?.trim();
+  const base = explicit && explicit.length > 0 ? resolve(explicit) : resolve(effectiveHome(options), ".config", "kxm");
+  return join(base, "completions", `kxm.${shell}`);
+}
+
+function bashRcCandidate(options: Pick<CompletionInstallOptions, "env" | "homeDir">): string | undefined {
+  const home = effectiveHome(options);
+  const candidates = [join(home, ".bashrc"), join(home, ".bash_profile")];
+  const existing = candidates.find((candidate) => existsSync(candidate));
+  return existing ?? candidates[0];
+}
+
+function zshRcCandidate(options: Pick<CompletionInstallOptions, "env" | "homeDir">): string | undefined {
+  const env = options.env ?? process.env;
+  const home = effectiveHome(options);
+  if (env.ZDOTDIR?.trim()) return join(resolve(env.ZDOTDIR.trim()), ".zshrc");
+  return join(home, ".zshrc");
+}
+
+function fishCompletionTarget(shell: SupportedShell, options: Pick<CompletionInstallOptions, "env" | "homeDir">): string {
+  const env = options.env ?? process.env;
+  const home = effectiveHome(options);
+  if (env.XDG_CONFIG_HOME?.trim()) return join(resolve(env.XDG_CONFIG_HOME.trim()), "fish", "completions", "kxm.fish");
+  return join(home, ".config", "fish", "completions", "kxm.fish");
+}
+
+export function completionRcTarget(shell: SupportedShell, options: Pick<CompletionInstallOptions, "env" | "homeDir"> = {}): { rcFile?: string | undefined } {
+  if (shell === "fish") {
+    return { rcFile: undefined }; // fish auto-loads ~/.config/fish/completions
+  }
+  if (shell === "zsh") {
+    return { rcFile: zshRcCandidate(options) };
+  }
+  return { rcFile: bashRcCandidate(options) };
+}
+
+function sourceLine(shell: SupportedShell, scriptPath: string): string {
+  if (shell === "fish") return `source ${scriptPath}`;
+  if (shell === "zsh") return `[[ -f ${scriptPath} ]] && source ${scriptPath}`;
+  return `[[ -f ${scriptPath} ]] && source ${scriptPath}`;
+}
+
+export function installShellCompletion(
+  shellInput: string | undefined,
+  options: CompletionInstallOptions = {},
+): CompletionInstallReport {
+  const shell = shellInput?.trim() && shellInput !== "auto" ? shellInput.trim() as SupportedShell : detectShell(options.env ?? process.env, options.platform ?? process.platform);
+  if (shell !== "bash" && shell !== "zsh" && shell !== "fish") {
+    return {
+      ok: false,
+      shell: "unknown",
+      scriptPath: "",
+      rcFile: undefined,
+      rcModified: false,
+      alreadyInstalled: false,
+      reason: "shell_not_detected",
+    };
+  }
+
+  const scriptPath = completionScriptPath(shell, options);
+  const { rcFile } = completionRcTarget(shell, options);
+  const script = generateShellCompletion(shell);
+
+  const existingScript = existsSync(scriptPath);
+  const existingScriptMatches = existingScript && readFileSync(scriptPath, "utf8") === script;
+
+  let rcModified = false;
+  let alreadyInstalled = false;
+
+  if (shell === "fish") {
+    // fish auto-loads files in ~/.config/fish/completions by filename; no rc edit needed
+    const fishTarget = fishCompletionTarget(shell, options);
+    const fishInstalled = existsSync(fishTarget) && readFileSync(fishTarget, "utf8") === script;
+    alreadyInstalled = fishInstalled;
+    if (!options.dryRun && (!fishInstalled || options.overwrite)) {
+      mkdirSync(resolve(fishTarget, ".."), { recursive: true });
+      writeFileSync(fishTarget, script, { encoding: "utf8" });
+    }
+    return {
+      ok: true,
+      shell,
+      scriptPath: fishTarget,
+      rcFile: undefined,
+      rcModified: !fishInstalled,
+      alreadyInstalled,
+    };
+  }
+
+  if (rcFile) {
+    const line = sourceLine(shell, scriptPath);
+    const rcContent = existsSync(rcFile) ? readFileSync(rcFile, "utf8") : "";
+    alreadyInstalled = rcContent.includes(line) || rcContent.includes(`${COMPLETION_MARKER}`);
+  }
+
+  if (!options.dryRun) {
+    if (!existingScriptMatches || options.overwrite) {
+      mkdirSync(resolve(scriptPath, ".."), { recursive: true });
+      writeFileSync(scriptPath, script, { encoding: "utf8" });
+    }
+    if (rcFile && !alreadyInstalled) {
+      const line = sourceLine(shell, scriptPath);
+      const marker = `${COMPLETION_MARKER} (${new Date().toISOString()})`;
+      const stanza = `\n${marker}\n${line}\n`;
+      mkdirSync(resolve(rcFile, ".."), { recursive: true });
+      writeFileSync(rcFile, (existsSync(rcFile) ? readFileSync(rcFile, "utf8") : "") + stanza, { encoding: "utf8" });
+      rcModified = true;
+    }
+  }
+
+  return {
+    ok: true,
+    shell,
+    scriptPath,
+    rcFile,
+    rcModified,
+    alreadyInstalled,
+  };
+}
+
+export interface PathInstallReport {
+  ok: boolean;
+  binDir: string | undefined;
+  rcFile: string | undefined;
+  rcModified: boolean;
+  alreadyInstalled: boolean;
+  reason?: string | undefined;
+}
+
+/** Locate the directory containing the kxm entrypoint (global npm bin or clone scripts dir). */
+export function kxmBinDir(env: NodeJS.ProcessEnv = process.env): string | undefined {
+  const argv1 = env.KXM_ENTRY ?? process.argv[1];
+  if (argv1 && isAbsolute(argv1)) {
+    const dir = dirname(argv1);
+    if (existsSync(join(dir, process.platform === "win32" ? "kxm.cmd" : "kxm"))) return dir;
+  }
+  // fall back to PATH lookup
+  const pathEnv = env.PATH ?? "";
+  for (const part of pathEnv.split(delimiter)) {
+    if (!part) continue;
+    const candidate = resolve(part, process.platform === "win32" ? "kxm.cmd" : "kxm");
+    if (existsSync(candidate)) return resolve(part);
+  }
+  return undefined;
+}
+
+export function kxmOnPath(env: NodeJS.ProcessEnv = process.env): boolean {
+  return kxmBinDir(env) !== undefined;
+}
+
+function pathLine(binDir: string): string {
+  return `export PATH="${binDir}:$PATH" # kxm`;
+}
+
+/** Append a PATH export for the kxm bin dir to the shell rc (bash/zsh). */
+export function installPathEntry(
+  shellInput: string | undefined,
+  options: CompletionInstallOptions & { binDir?: string } = {},
+): PathInstallReport {
+  const shell = shellInput?.trim() && shellInput !== "auto" ? shellInput.trim() as SupportedShell : detectShell(options.env ?? process.env, options.platform ?? process.platform);
+  if (shell !== "bash" && shell !== "zsh") {
+    return { ok: false, binDir: undefined, rcFile: undefined, rcModified: false, alreadyInstalled: false, reason: "shell_not_supported" };
+  }
+  const binDir = options.binDir ?? kxmBinDir(options.env ?? process.env);
+  if (!binDir) {
+    return { ok: false, binDir: undefined, rcFile: undefined, rcModified: false, alreadyInstalled: false, reason: "kxm_not_found" };
+  }
+  const { rcFile } = completionRcTarget(shell, options);
+  const line = pathLine(binDir);
+  const rcContent = existsSync(rcFile ?? "") ? readFileSync(rcFile!, "utf8") : "";
+  const alreadyInstalled = rcContent.includes(binDir) || (options.env?.PATH ?? process.env.PATH ?? "").split(delimiter).includes(binDir);
+  if (!options.dryRun && rcFile && !alreadyInstalled) {
+    mkdirSync(dirname(rcFile), { recursive: true });
+    writeFileSync(rcFile, rcContent + `\n${PATH_MARKER}\n${line}\n`, { encoding: "utf8" });
+  }
+  return { ok: true, binDir, rcFile, rcModified: !alreadyInstalled && !options.dryRun, alreadyInstalled };
+}

package/plugins/kxm/src/config.ts

@@ -193,8 +193,8 @@ export function loadKxmConfig(
       const text = readFileSync(userConfigFile, "utf8");
       userRaw = (parse(text) as Record<string, unknown>) ?? {};
       userLoadedPath = userConfigFile;
-    } catch {
-      // ignore parse error, fallback
+    } catch (error) {
+      throw new Error(`invalid user config YAML at ${userConfigFile}`, { cause: error });
     }
   }
 
@@ -205,8 +205,8 @@ export function loadKxmConfig(
       const text = readFileSync(repoConfigFile, "utf8");
       repoRaw = (parse(text) as Record<string, unknown>) ?? {};
       repoLoadedPath = repoConfigFile;
-    } catch {
-      // ignore parse error, fallback
+    } catch (error) {
+      throw new Error(`invalid project config YAML at ${repoConfigFile}`, { cause: error });
     }
   }
 
@@ -264,6 +264,9 @@ export function setKxmConfigValue(
   }
 
   const parts = keyPath.split(".");
+  if (parts.some((part) => !part || part === "__proto__" || part === "prototype" || part === "constructor")) {
+    throw new Error("invalid config key path");
+  }
   let cursor = existing;
   for (let i = 0; i < parts.length - 1; i++) {
     const p = parts[i]!;

package/plugins/kxm/src/context-packet.ts

@@ -291,6 +291,178 @@ export function formatContextPacketForPrompt(packet: FormalContextPacketV2): str
   return sections.join("\n").trim();
 }
 
+export interface PruningAudit {
+  initialTokens: number;
+  finalTokens: number;
+  budgetTokens: number;
+  prunedStages: Array<"L1_defaults" | "L2_episodes" | "L2_docs" | "L5_artifacts">;
+  prunedItemCounts: {
+    sharedDefaults: number;
+    episodes: number;
+    docs: number;
+    artifactSnippets: number;
+  };
+  unresolvedGaps: string[];
+}
+
+export function estimateContextPacketTokens(packet: FormalContextPacketV2): number {
+  const prompt = formatContextPacketForPrompt(packet);
+  return Math.ceil(prompt.length / 4);
+}
+
+/**
+ * Deterministic Pruning Hierarchy (Decision Q4):
+ * L1 Defaults -> L2 Historical Episodes -> L2 Project Docs -> L5 Artifacts; L3 Task Objective is inviolable.
+ */
+export function pruneContextPacket(
+  packet: FormalContextPacketV2,
+  tokenBudget?: number,
+): { packet: FormalContextPacketV2; audit: PruningAudit } {
+  const budget = tokenBudget ?? packet.budget.allocatedTokens;
+  let currentTokens = estimateContextPacketTokens(packet);
+  const initialTokens = currentTokens;
+
+  const prunedStages: Array<"L1_defaults" | "L2_episodes" | "L2_docs" | "L5_artifacts"> = [];
+  const prunedItemCounts = {
+    sharedDefaults: 0,
+    episodes: 0,
+    docs: 0,
+    artifactSnippets: 0,
+  };
+  const unresolvedGaps: string[] = [...packet.budget.unresolvedGaps];
+
+  if (currentTokens <= budget) {
+    return {
+      packet: {
+        ...packet,
+        budget: {
+          ...packet.budget,
+          allocatedTokens: budget,
+          estimatedTokens: currentTokens,
+        },
+      },
+      audit: {
+        initialTokens,
+        finalTokens: currentTokens,
+        budgetTokens: budget,
+        prunedStages,
+        prunedItemCounts,
+        unresolvedGaps,
+      },
+    };
+  }
+
+  // Clone packet environment and predecessors to prune deterministically
+  const environment: ContextPacketEnvironment = {
+    sharedDefaults: [...packet.environment.sharedDefaults],
+    projectKnowledge: [...packet.environment.projectKnowledge],
+    currentState: [...packet.environment.currentState],
+    contradictions: [...packet.environment.contradictions],
+    activeSkills: [...packet.environment.activeSkills],
+  };
+  const predecessors: ContextPacketPredecessor[] = packet.predecessors.map((p) => ({
+    ...p,
+    artifacts: p.artifacts.map((a) => ({ ...a })),
+  }));
+
+  const workingPacket: FormalContextPacketV2 = {
+    ...packet,
+    environment,
+    predecessors,
+    budget: { ...packet.budget, allocatedTokens: budget },
+  };
+
+  // Stage 1 (L1 Defaults): Drop shared defaults first
+  if (environment.sharedDefaults.length > 0 && currentTokens > budget) {
+    prunedStages.push("L1_defaults");
+    while (environment.sharedDefaults.length > 0 && currentTokens > budget) {
+      environment.sharedDefaults.pop();
+      prunedItemCounts.sharedDefaults += 1;
+      currentTokens = estimateContextPacketTokens(workingPacket);
+    }
+  }
+
+  // Stage 2 (L2 Historical Episodes): Drop episode state items
+  if (currentTokens > budget) {
+    const episodeIndices: number[] = [];
+    for (let i = environment.currentState.length - 1; i >= 0; i--) {
+      if (environment.currentState[i]?.kind === "episode") {
+        episodeIndices.push(i);
+      }
+    }
+    if (episodeIndices.length > 0) {
+      prunedStages.push("L2_episodes");
+      for (const idx of episodeIndices) {
+        if (currentTokens <= budget) break;
+        environment.currentState.splice(idx, 1);
+        prunedItemCounts.episodes += 1;
+        currentTokens = estimateContextPacketTokens(workingPacket);
+      }
+    }
+  }
+
+  // Stage 3 (L2 Project Docs / Knowledge): Drop project knowledge/doc items
+  if (currentTokens > budget && environment.projectKnowledge.length > 0) {
+    prunedStages.push("L2_docs");
+    while (environment.projectKnowledge.length > 0 && currentTokens > budget) {
+      environment.projectKnowledge.pop();
+      prunedItemCounts.docs += 1;
+      currentTokens = estimateContextPacketTokens(workingPacket);
+    }
+  }
+
+  // Stage 4 (L5 Artifacts): Prune artifact content snippets, then artifact entries if still overflowing
+  if (currentTokens > budget) {
+    const hasArtifacts = predecessors.some((p) => p.artifacts.length > 0);
+    if (hasArtifacts) {
+      prunedStages.push("L5_artifacts");
+      // First strip snippets
+      for (const p of predecessors) {
+        for (const a of p.artifacts) {
+          if (a.contentSnippet) {
+            a.contentSnippet = undefined;
+            prunedItemCounts.artifactSnippets += 1;
+          }
+        }
+      }
+      currentTokens = estimateContextPacketTokens(workingPacket);
+
+      // If still overflowing, prune artifacts list
+      if (currentTokens > budget) {
+        for (const p of predecessors) {
+          p.artifacts = [];
+        }
+        currentTokens = estimateContextPacketTokens(workingPacket);
+      }
+    }
+  }
+
+  // L3 Task Objective Inviolable:
+  // task, plan, and acceptance criteria are inviolable and never stripped.
+  if (currentTokens > budget) {
+    unresolvedGaps.push("context_budget_exceeded_task_inviolable");
+  }
+
+  workingPacket.budget = {
+    ...packet.budget,
+    allocatedTokens: budget,
+    estimatedTokens: currentTokens,
+    unresolvedGaps,
+  };
+
+  return {
+    packet: workingPacket,
+    audit: {
+      initialTokens,
+      finalTokens: currentTokens,
+      budgetTokens: budget,
+      prunedStages,
+      prunedItemCounts,
+      unresolvedGaps,
+    },
+  };
+}
+
 /**
  * Builds a structured handoff manifest between workflow roles.
  */

package/plugins/kxm/src/database.ts

@@ -11,7 +11,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
-import { DatabaseSync } from "node:sqlite";
+import { DatabaseSync } from "./sqlite.ts";
 import { VnextConfigError, type VnextConfigIssue } from "./vnext-config.ts";
 
 export interface DatabaseMigrationStep {