@osovv/vvcode 0.4.1

package/dist/vvcode.js

@@ -0,0 +1,1825 @@
+// @bun
+// node_modules/citty/dist/_chunks/libs/scule.mjs
+var NUMBER_CHAR_RE = /\d/;
+var STR_SPLITTERS = [
+  "-",
+  "_",
+  "/",
+  "."
+];
+function isUppercase(char = "") {
+  if (NUMBER_CHAR_RE.test(char))
+    return;
+  return char !== char.toLowerCase();
+}
+function splitByCase(str, separators) {
+  const splitters = separators ?? STR_SPLITTERS;
+  const parts = [];
+  if (!str || typeof str !== "string")
+    return parts;
+  let buff = "";
+  let previousUpper;
+  let previousSplitter;
+  for (const char of str) {
+    const isSplitter = splitters.includes(char);
+    if (isSplitter === true) {
+      parts.push(buff);
+      buff = "";
+      previousUpper = undefined;
+      continue;
+    }
+    const isUpper = isUppercase(char);
+    if (previousSplitter === false) {
+      if (previousUpper === false && isUpper === true) {
+        parts.push(buff);
+        buff = char;
+        previousUpper = isUpper;
+        continue;
+      }
+      if (previousUpper === true && isUpper === false && buff.length > 1) {
+        const lastChar = buff.at(-1);
+        parts.push(buff.slice(0, Math.max(0, buff.length - 1)));
+        buff = lastChar + char;
+        previousUpper = isUpper;
+        continue;
+      }
+    }
+    buff += char;
+    previousUpper = isUpper;
+    previousSplitter = isSplitter;
+  }
+  parts.push(buff);
+  return parts;
+}
+function upperFirst(str) {
+  return str ? str[0].toUpperCase() + str.slice(1) : "";
+}
+function lowerFirst(str) {
+  return str ? str[0].toLowerCase() + str.slice(1) : "";
+}
+function pascalCase(str, opts) {
+  return str ? (Array.isArray(str) ? str : splitByCase(str)).map((p) => upperFirst(opts?.normalize ? p.toLowerCase() : p)).join("") : "";
+}
+function camelCase(str, opts) {
+  return lowerFirst(pascalCase(str || "", opts));
+}
+function kebabCase(str, joiner) {
+  return str ? (Array.isArray(str) ? str : splitByCase(str)).map((p) => p.toLowerCase()).join(joiner ?? "-") : "";
+}
+function snakeCase(str) {
+  return kebabCase(str || "", "_");
+}
+
+// node_modules/citty/dist/index.mjs
+import { parseArgs as parseArgs$1 } from "util";
+function toArray(val) {
+  if (Array.isArray(val))
+    return val;
+  return val === undefined ? [] : [val];
+}
+function formatLineColumns(lines, linePrefix = "") {
+  const maxLength = [];
+  for (const line of lines)
+    for (const [i, element] of line.entries())
+      maxLength[i] = Math.max(maxLength[i] || 0, element.length);
+  return lines.map((l) => l.map((c, i) => linePrefix + c[i === 0 ? "padStart" : "padEnd"](maxLength[i])).join("  ")).join(`
+`);
+}
+function resolveValue(input) {
+  return typeof input === "function" ? input() : input;
+}
+var CLIError = class extends Error {
+  code;
+  constructor(message, code) {
+    super(message);
+    this.name = "CLIError";
+    this.code = code;
+  }
+};
+function parseRawArgs(args = [], opts = {}) {
+  const booleans = new Set(opts.boolean || []);
+  const strings = new Set(opts.string || []);
+  const aliasMap = opts.alias || {};
+  const defaults = opts.default || {};
+  const aliasToMain = /* @__PURE__ */ new Map;
+  const mainToAliases = /* @__PURE__ */ new Map;
+  for (const [key, value] of Object.entries(aliasMap)) {
+    const targets = value;
+    for (const target of targets) {
+      aliasToMain.set(key, target);
+      if (!mainToAliases.has(target))
+        mainToAliases.set(target, []);
+      mainToAliases.get(target).push(key);
+      aliasToMain.set(target, key);
+      if (!mainToAliases.has(key))
+        mainToAliases.set(key, []);
+      mainToAliases.get(key).push(target);
+    }
+  }
+  const options = {};
+  function getType(name) {
+    if (booleans.has(name))
+      return "boolean";
+    const aliases = mainToAliases.get(name) || [];
+    for (const alias of aliases)
+      if (booleans.has(alias))
+        return "boolean";
+    return "string";
+  }
+  function isStringType(name) {
+    if (strings.has(name))
+      return true;
+    const aliases = mainToAliases.get(name) || [];
+    for (const alias of aliases)
+      if (strings.has(alias))
+        return true;
+    return false;
+  }
+  const allOptions = new Set([
+    ...booleans,
+    ...strings,
+    ...Object.keys(aliasMap),
+    ...Object.values(aliasMap).flat(),
+    ...Object.keys(defaults)
+  ]);
+  for (const name of allOptions)
+    if (!options[name])
+      options[name] = {
+        type: getType(name),
+        default: defaults[name]
+      };
+  for (const [alias, main] of aliasToMain.entries())
+    if (alias.length === 1 && options[main] && !options[main].short)
+      options[main].short = alias;
+  const processedArgs = [];
+  const negatedFlags = {};
+  for (let i = 0;i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--") {
+      processedArgs.push(...args.slice(i));
+      break;
+    }
+    if (arg.startsWith("--no-")) {
+      const flagName = arg.slice(5);
+      negatedFlags[flagName] = true;
+      continue;
+    }
+    processedArgs.push(arg);
+  }
+  let parsed;
+  try {
+    parsed = parseArgs$1({
+      args: processedArgs,
+      options: Object.keys(options).length > 0 ? options : undefined,
+      allowPositionals: true,
+      strict: false
+    });
+  } catch {
+    parsed = {
+      values: {},
+      positionals: processedArgs
+    };
+  }
+  const out = { _: [] };
+  out._ = parsed.positionals;
+  for (const [key, value] of Object.entries(parsed.values)) {
+    let coerced = value;
+    if (getType(key) === "boolean" && typeof value === "string")
+      coerced = value !== "false";
+    else if (isStringType(key) && typeof value === "boolean")
+      coerced = "";
+    out[key] = coerced;
+  }
+  for (const [name] of Object.entries(negatedFlags)) {
+    out[name] = false;
+    const mainName = aliasToMain.get(name);
+    if (mainName)
+      out[mainName] = false;
+    const aliases = mainToAliases.get(name);
+    if (aliases)
+      for (const alias of aliases)
+        out[alias] = false;
+  }
+  for (const [alias, main] of aliasToMain.entries()) {
+    if (out[alias] !== undefined && out[main] === undefined)
+      out[main] = out[alias];
+    if (out[main] !== undefined && out[alias] === undefined)
+      out[alias] = out[main];
+    if (out[alias] !== out[main] && defaults[main] === out[main])
+      out[main] = out[alias];
+  }
+  return out;
+}
+var noColor = /* @__PURE__ */ (() => {
+  const env = globalThis.process?.env ?? {};
+  return env.NO_COLOR === "1" || env.TERM === "dumb" || env.TEST || env.CI;
+})();
+var _c = (c, r = 39) => (t) => noColor ? t : `\x1B[${c}m${t}\x1B[${r}m`;
+var bold = /* @__PURE__ */ _c(1, 22);
+var cyan = /* @__PURE__ */ _c(36);
+var gray = /* @__PURE__ */ _c(90);
+var underline = /* @__PURE__ */ _c(4, 24);
+function parseArgs(rawArgs, argsDef) {
+  const parseOptions = {
+    boolean: [],
+    string: [],
+    alias: {},
+    default: {}
+  };
+  const args = resolveArgs(argsDef);
+  for (const arg of args) {
+    if (arg.type === "positional")
+      continue;
+    if (arg.type === "string" || arg.type === "enum")
+      parseOptions.string.push(arg.name);
+    else if (arg.type === "boolean")
+      parseOptions.boolean.push(arg.name);
+    if (arg.default !== undefined)
+      parseOptions.default[arg.name] = arg.default;
+    if (arg.alias)
+      parseOptions.alias[arg.name] = arg.alias;
+    const camelName = camelCase(arg.name);
+    const kebabName = kebabCase(arg.name);
+    if (camelName !== arg.name || kebabName !== arg.name) {
+      const existingAliases = toArray(parseOptions.alias[arg.name] || []);
+      if (camelName !== arg.name && !existingAliases.includes(camelName))
+        existingAliases.push(camelName);
+      if (kebabName !== arg.name && !existingAliases.includes(kebabName))
+        existingAliases.push(kebabName);
+      if (existingAliases.length > 0)
+        parseOptions.alias[arg.name] = existingAliases;
+    }
+  }
+  const parsed = parseRawArgs(rawArgs, parseOptions);
+  const [...positionalArguments] = parsed._;
+  const parsedArgsProxy = new Proxy(parsed, { get(target, prop) {
+    return target[prop] ?? target[camelCase(prop)] ?? target[kebabCase(prop)];
+  } });
+  for (const [, arg] of args.entries())
+    if (arg.type === "positional") {
+      const nextPositionalArgument = positionalArguments.shift();
+      if (nextPositionalArgument !== undefined)
+        parsedArgsProxy[arg.name] = nextPositionalArgument;
+      else if (arg.default === undefined && arg.required !== false)
+        throw new CLIError(`Missing required positional argument: ${arg.name.toUpperCase()}`, "EARG");
+      else
+        parsedArgsProxy[arg.name] = arg.default;
+    } else if (arg.type === "enum") {
+      const argument = parsedArgsProxy[arg.name];
+      const options = arg.options || [];
+      if (argument !== undefined && options.length > 0 && !options.includes(argument))
+        throw new CLIError(`Invalid value for argument: ${cyan(`--${arg.name}`)} (${cyan(argument)}). Expected one of: ${options.map((o) => cyan(o)).join(", ")}.`, "EARG");
+    } else if (arg.required && parsedArgsProxy[arg.name] === undefined)
+      throw new CLIError(`Missing required argument: --${arg.name}`, "EARG");
+  return parsedArgsProxy;
+}
+function resolveArgs(argsDef) {
+  const args = [];
+  for (const [name, argDef] of Object.entries(argsDef || {}))
+    args.push({
+      ...argDef,
+      name,
+      alias: toArray(argDef.alias)
+    });
+  return args;
+}
+async function resolvePlugins(plugins) {
+  return Promise.all(plugins.map((p) => resolveValue(p)));
+}
+function defineCommand(def) {
+  return def;
+}
+async function runCommand(cmd, opts) {
+  const cmdArgs = await resolveValue(cmd.args || {});
+  const parsedArgs = parseArgs(opts.rawArgs, cmdArgs);
+  const context = {
+    rawArgs: opts.rawArgs,
+    args: parsedArgs,
+    data: opts.data,
+    cmd
+  };
+  const plugins = await resolvePlugins(cmd.plugins ?? []);
+  let result;
+  let runError;
+  try {
+    for (const plugin of plugins)
+      await plugin.setup?.(context);
+    if (typeof cmd.setup === "function")
+      await cmd.setup(context);
+    const subCommands = await resolveValue(cmd.subCommands);
+    if (subCommands && Object.keys(subCommands).length > 0) {
+      const subCommandArgIndex = findSubCommandIndex(opts.rawArgs, cmdArgs);
+      const explicitName = opts.rawArgs[subCommandArgIndex];
+      if (explicitName) {
+        const subCommand = await _findSubCommand(subCommands, explicitName);
+        if (!subCommand)
+          throw new CLIError(`Unknown command ${cyan(explicitName)}`, "E_UNKNOWN_COMMAND");
+        await runCommand(subCommand, { rawArgs: opts.rawArgs.slice(subCommandArgIndex + 1) });
+      } else {
+        const defaultSubCommand = await resolveValue(cmd.default);
+        if (defaultSubCommand) {
+          if (cmd.run)
+            throw new CLIError(`Cannot specify both 'run' and 'default' on the same command.`, "E_DEFAULT_CONFLICT");
+          const subCommand = await _findSubCommand(subCommands, defaultSubCommand);
+          if (!subCommand)
+            throw new CLIError(`Default sub command ${cyan(defaultSubCommand)} not found in subCommands.`, "E_UNKNOWN_COMMAND");
+          await runCommand(subCommand, { rawArgs: opts.rawArgs });
+        } else if (!cmd.run)
+          throw new CLIError(`No command specified.`, "E_NO_COMMAND");
+      }
+    }
+    if (typeof cmd.run === "function")
+      result = await cmd.run(context);
+  } catch (error) {
+    runError = error;
+  }
+  const cleanupErrors = [];
+  if (typeof cmd.cleanup === "function")
+    try {
+      await cmd.cleanup(context);
+    } catch (error) {
+      cleanupErrors.push(error);
+    }
+  for (const plugin of [...plugins].reverse())
+    try {
+      await plugin.cleanup?.(context);
+    } catch (error) {
+      cleanupErrors.push(error);
+    }
+  if (runError)
+    throw runError;
+  if (cleanupErrors.length === 1)
+    throw cleanupErrors[0];
+  if (cleanupErrors.length > 1)
+    throw new Error("Multiple cleanup errors", { cause: cleanupErrors });
+  return { result };
+}
+async function resolveSubCommand(cmd, rawArgs, parent) {
+  const subCommands = await resolveValue(cmd.subCommands);
+  if (subCommands && Object.keys(subCommands).length > 0) {
+    const subCommandArgIndex = findSubCommandIndex(rawArgs, await resolveValue(cmd.args || {}));
+    const subCommandName = rawArgs[subCommandArgIndex];
+    const subCommand = await _findSubCommand(subCommands, subCommandName);
+    if (subCommand)
+      return resolveSubCommand(subCommand, rawArgs.slice(subCommandArgIndex + 1), cmd);
+  }
+  return [cmd, parent];
+}
+async function _findSubCommand(subCommands, name) {
+  if (name in subCommands)
+    return resolveValue(subCommands[name]);
+  for (const sub of Object.values(subCommands)) {
+    const resolved = await resolveValue(sub);
+    const meta = await resolveValue(resolved?.meta);
+    if (meta?.alias) {
+      if (toArray(meta.alias).includes(name))
+        return resolved;
+    }
+  }
+}
+function findSubCommandIndex(rawArgs, argsDef) {
+  for (let i = 0;i < rawArgs.length; i++) {
+    const arg = rawArgs[i];
+    if (arg === "--")
+      return -1;
+    if (arg.startsWith("-")) {
+      if (!arg.includes("=") && _isValueFlag(arg, argsDef))
+        i++;
+      continue;
+    }
+    return i;
+  }
+  return -1;
+}
+function _isValueFlag(flag, argsDef) {
+  const name = flag.replace(/^-{1,2}/, "");
+  const normalized = camelCase(name);
+  for (const [key, def] of Object.entries(argsDef)) {
+    if (def.type !== "string" && def.type !== "enum")
+      continue;
+    if (normalized === camelCase(key))
+      return true;
+    if ((Array.isArray(def.alias) ? def.alias : def.alias ? [def.alias] : []).includes(name))
+      return true;
+  }
+  return false;
+}
+async function showUsage(cmd, parent) {
+  try {
+    console.log(await renderUsage(cmd, parent) + `
+`);
+  } catch (error) {
+    console.error(error);
+  }
+}
+var negativePrefixRe = /^no[-A-Z]/;
+async function renderUsage(cmd, parent) {
+  const cmdMeta = await resolveValue(cmd.meta || {});
+  const cmdArgs = resolveArgs(await resolveValue(cmd.args || {}));
+  const parentMeta = await resolveValue(parent?.meta || {});
+  const commandName = `${parentMeta.name ? `${parentMeta.name} ` : ""}` + (cmdMeta.name || process.argv[1]);
+  const argLines = [];
+  const posLines = [];
+  const commandsLines = [];
+  const usageLine = [];
+  for (const arg of cmdArgs)
+    if (arg.type === "positional") {
+      const name = arg.name.toUpperCase();
+      const isRequired = arg.required !== false && arg.default === undefined;
+      posLines.push([cyan(name + renderValueHint(arg)), renderDescription(arg, isRequired)]);
+      usageLine.push(isRequired ? `<${name}>` : `[${name}]`);
+    } else {
+      const isRequired = arg.required === true && arg.default === undefined;
+      const argStr = [...(arg.alias || []).map((a) => `-${a}`), `--${arg.name}`].join(", ") + renderValueHint(arg);
+      argLines.push([cyan(argStr), renderDescription(arg, isRequired)]);
+      if (arg.type === "boolean" && (arg.default === true || arg.negativeDescription) && !negativePrefixRe.test(arg.name)) {
+        const negativeArgStr = [...(arg.alias || []).map((a) => `--no-${a}`), `--no-${arg.name}`].join(", ");
+        argLines.push([cyan(negativeArgStr), [arg.negativeDescription, isRequired ? gray("(Required)") : ""].filter(Boolean).join(" ")]);
+      }
+      if (isRequired)
+        usageLine.push(`--${arg.name}` + renderValueHint(arg));
+    }
+  if (cmd.subCommands) {
+    const commandNames = [];
+    const subCommands = await resolveValue(cmd.subCommands);
+    for (const [name, sub] of Object.entries(subCommands)) {
+      const meta = await resolveValue((await resolveValue(sub))?.meta);
+      if (meta?.hidden)
+        continue;
+      const aliases = toArray(meta?.alias);
+      const label = [name, ...aliases].join(", ");
+      commandsLines.push([cyan(label), meta?.description || ""]);
+      commandNames.push(name, ...aliases);
+    }
+    usageLine.push(commandNames.join("|"));
+  }
+  const usageLines = [];
+  const version = cmdMeta.version || parentMeta.version;
+  usageLines.push(gray(`${cmdMeta.description} (${commandName + (version ? ` v${version}` : "")})`), "");
+  const hasOptions = argLines.length > 0 || posLines.length > 0;
+  usageLines.push(`${underline(bold("USAGE"))} ${cyan(`${commandName}${hasOptions ? " [OPTIONS]" : ""} ${usageLine.join(" ")}`)}`, "");
+  if (posLines.length > 0) {
+    usageLines.push(underline(bold("ARGUMENTS")), "");
+    usageLines.push(formatLineColumns(posLines, "  "));
+    usageLines.push("");
+  }
+  if (argLines.length > 0) {
+    usageLines.push(underline(bold("OPTIONS")), "");
+    usageLines.push(formatLineColumns(argLines, "  "));
+    usageLines.push("");
+  }
+  if (commandsLines.length > 0) {
+    usageLines.push(underline(bold("COMMANDS")), "");
+    usageLines.push(formatLineColumns(commandsLines, "  "));
+    usageLines.push("", `Use ${cyan(`${commandName} <command> --help`)} for more information about a command.`);
+  }
+  return usageLines.filter((l) => typeof l === "string").join(`
+`);
+}
+function renderValueHint(arg) {
+  const valueHint = arg.valueHint ? `=<${arg.valueHint}>` : "";
+  const fallbackValueHint = valueHint || `=<${snakeCase(arg.name)}>`;
+  if (!arg.type || arg.type === "positional" || arg.type === "boolean")
+    return valueHint;
+  if (arg.type === "enum" && arg.options?.length)
+    return `=<${arg.options.join("|")}>`;
+  return fallbackValueHint;
+}
+function renderDescription(arg, required) {
+  const requiredHint = required ? gray("(Required)") : "";
+  const defaultHint = arg.default === undefined ? "" : gray(`(Default: ${arg.default})`);
+  return [
+    arg.description,
+    requiredHint,
+    defaultHint
+  ].filter(Boolean).join(" ");
+}
+async function runMain(cmd, opts = {}) {
+  const rawArgs = opts.rawArgs || process.argv.slice(2);
+  const showUsage$1 = opts.showUsage || showUsage;
+  try {
+    const builtinFlags = await _resolveBuiltinFlags(cmd);
+    if (builtinFlags.help.length > 0 && rawArgs.some((arg) => builtinFlags.help.includes(arg))) {
+      await showUsage$1(...await resolveSubCommand(cmd, rawArgs));
+      process.exit(0);
+    } else if (rawArgs.length === 1 && builtinFlags.version.includes(rawArgs[0])) {
+      const meta = typeof cmd.meta === "function" ? await cmd.meta() : await cmd.meta;
+      if (!meta?.version)
+        throw new CLIError("No version specified", "E_NO_VERSION");
+      console.log(meta.version);
+    } else
+      await runCommand(cmd, { rawArgs });
+  } catch (error) {
+    if (error instanceof CLIError) {
+      await showUsage$1(...await resolveSubCommand(cmd, rawArgs));
+      console.error(error.message);
+    } else
+      console.error(error, `
+`);
+    process.exit(1);
+  }
+}
+async function _resolveBuiltinFlags(cmd) {
+  const argsDef = await resolveValue(cmd.args || {});
+  const userNames = /* @__PURE__ */ new Set;
+  const userAliases = /* @__PURE__ */ new Set;
+  for (const [name, def] of Object.entries(argsDef)) {
+    userNames.add(name);
+    for (const alias of toArray(def.alias))
+      userAliases.add(alias);
+  }
+  return {
+    help: _getBuiltinFlags("help", "h", userNames, userAliases),
+    version: _getBuiltinFlags("version", "v", userNames, userAliases)
+  };
+}
+function _getBuiltinFlags(long, short, userNames, userAliases) {
+  if (userNames.has(long) || userAliases.has(long))
+    return [];
+  if (userNames.has(short) || userAliases.has(short))
+    return [`--${long}`];
+  return [`--${long}`, `-${short}`];
+}
+
+// src/cli/vvcode.ts
+import { homedir } from "os";
+import { join as join3 } from "path";
+// package.json
+var package_default = {
+  name: "@osovv/vvcode",
+  version: "0.4.1",
+  description: "Packaged CLI for launching OpenCode with vvcode runtime semantics.",
+  license: "MIT",
+  homepage: "https://github.com/osovv/vvcode",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/osovv/vvcode.git"
+  },
+  bugs: {
+    url: "https://github.com/osovv/vvcode/issues"
+  },
+  type: "module",
+  packageManager: "bun@1.3.8",
+  files: [
+    "bin",
+    "dist"
+  ],
+  bin: {
+    vvcode: "./bin/vvcode"
+  },
+  publishConfig: {
+    access: "public"
+  },
+  engines: {
+    bun: ">=1.3.8"
+  },
+  scripts: {
+    build: "bun build ./src/cli/vvcode-entry.ts --target bun --format esm --outfile ./dist/vvcode.js",
+    prepack: "bun run build",
+    cli: "bun run build && bun run ./bin/vvcode",
+    typecheck: "tsc --noEmit",
+    test: "vitest run",
+    "test:unit": "vitest run tests/unit",
+    "test:integration": "vitest run tests/integration",
+    "test:scenarios": "vitest run tests/scenarios"
+  },
+  dependencies: {
+    "@opencode-ai/sdk": "1.3.13",
+    citty: "^0.2.2",
+    "opencode-ai": "1.3.13"
+  },
+  devDependencies: {
+    "@types/node": "25.5.0",
+    typescript: "5.9.3",
+    vitest: "4.1.2"
+  },
+  keywords: [
+    "vvcode",
+    "bun",
+    "cli",
+    "opencode",
+    "agentic"
+  ]
+};
+
+// src/cli/pivv-opencode.ts
+import { rm } from "fs/promises";
+import { spawn } from "child_process";
+
+// src/config/load-pivv-config.ts
+class PivvConfigError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "PivvConfigError";
+  }
+}
+var PROJECT_CONFIG_PATH = ".vvcode/config.jsonc";
+var FS_PROMISES_IMPORT = "node:fs/promises";
+async function loadPivvConfig(globalConfigPath, projectRoot) {
+  const runId = createRunId();
+  const normalizedProjectRoot = await findProjectRoot(projectRoot);
+  const sourceCandidates = [
+    { path: resolvePath(globalConfigPath), sourceType: "global" },
+    { path: joinPath(normalizedProjectRoot, PROJECT_CONFIG_PATH), sourceType: "project" }
+  ];
+  const sourceEntries = [];
+  for (const sourceCandidate of sourceCandidates) {
+    const sourcePath = sourceCandidate.path;
+    const sourceExists = await pathExists(sourcePath);
+    if (!sourceExists && sourceCandidate.sourceType === "project") {
+      throw new PivvConfigError("CONFIG_NOT_FOUND", `Project config not found at ${sourcePath}`);
+    }
+    if (!sourceExists) {
+      continue;
+    }
+    sourceEntries.push({
+      path: sourcePath,
+      config: await readJsoncConfig(sourcePath)
+    });
+  }
+  if (sourceEntries.length === 0) {
+    throw new PivvConfigError("CONFIG_NOT_FOUND", "No vvcode config sources were found");
+  }
+  const mergedRawConfig = sourceEntries.reduce((accumulator, entry) => {
+    return deepMerge(accumulator, entry.config);
+  }, {});
+  console.info("[VvcodeConfig][loadPivvConfig][BLOCK_VALIDATE_CONFIG] validating configuration", {
+    runId,
+    projectRoot: normalizedProjectRoot,
+    configSourceCount: sourceEntries.length
+  });
+  const normalizedConfig = normalizeConfig(mergedRawConfig, normalizedProjectRoot, sourceEntries.map((entry) => entry.path));
+  console.info("[VvcodeConfig][loadPivvConfig][BLOCK_RETURN_NORMALIZED_CONFIG] returning normalized config", {
+    runId,
+    projectRoot: normalizedProjectRoot,
+    configSourceCount: sourceEntries.length
+  });
+  return normalizedConfig;
+}
+async function findProjectRoot(projectRoot) {
+  let currentPath = resolvePath(projectRoot);
+  while (true) {
+    const hasPivvDirectory = await pathExists(joinPath(currentPath, ".vvcode"));
+    const hasOpenCodeDirectory = await pathExists(joinPath(currentPath, ".opencode"));
+    if (hasPivvDirectory || hasOpenCodeDirectory) {
+      return currentPath;
+    }
+    const parentPath = getParentPath(currentPath);
+    if (parentPath === currentPath) {
+      break;
+    }
+    currentPath = parentPath;
+  }
+  throw new PivvConfigError("CONFIG_NOT_FOUND", `Unable to resolve project root from ${projectRoot}`);
+}
+function normalizeConfig(rawConfig, projectRoot, configSources) {
+  if (!isRecord(rawConfig)) {
+    throw new PivvConfigError("CONFIG_INVALID", "Config root must be an object");
+  }
+  const rawProfiles = rawConfig.profiles ?? {};
+  if (!isRecord(rawProfiles)) {
+    throw new PivvConfigError("CONFIG_INVALID", 'Config "profiles" must be an object');
+  }
+  const profiles = {};
+  for (const [profileName, profileValue] of Object.entries(rawProfiles)) {
+    if (!isRecord(profileValue)) {
+      throw new PivvConfigError("CONFIG_INVALID", `Profile "${profileName}" must be an object`);
+    }
+    if (typeof profileValue.provider !== "string" || profileValue.provider.length === 0) {
+      throw new PivvConfigError("CONFIG_INVALID", `Profile "${profileName}" is missing a string "provider"`);
+    }
+    if (typeof profileValue.model !== "string" || profileValue.model.length === 0) {
+      throw new PivvConfigError("CONFIG_INVALID", `Profile "${profileName}" is missing a string "model"`);
+    }
+    profiles[profileName] = {
+      provider: profileValue.provider,
+      model: profileValue.model,
+      options: isRecord(profileValue.options) ? profileValue.options : undefined
+    };
+  }
+  const rawPresets = rawConfig.presets ?? {};
+  if (!isRecord(rawPresets)) {
+    throw new PivvConfigError("CONFIG_INVALID", 'Config "presets" must be an object');
+  }
+  const presets = {};
+  for (const [presetName, presetValue] of Object.entries(rawPresets)) {
+    if (!isRecord(presetValue)) {
+      throw new PivvConfigError("CONFIG_INVALID", `Preset "${presetName}" must be an object`);
+    }
+    const normalizedPreset = {};
+    for (const [slotName, profileName] of Object.entries(presetValue)) {
+      if (typeof profileName !== "string" || profileName.length === 0) {
+        throw new PivvConfigError("CONFIG_INVALID", `Preset "${presetName}" slot "${slotName}" must reference a non-empty profile name`);
+      }
+      if (!(profileName in profiles)) {
+        throw new PivvConfigError("CONFIG_INVALID", `Preset "${presetName}" slot "${slotName}" references unknown profile "${profileName}"`);
+      }
+      normalizedPreset[slotName] = profileName;
+    }
+    presets[presetName] = normalizedPreset;
+  }
+  const memory = isRecord(rawConfig.memory) ? rawConfig.memory : {};
+  const overlay = isRecord(rawConfig.overlay) ? rawConfig.overlay : {};
+  return {
+    profiles,
+    presets,
+    memory,
+    overlay,
+    projectRoot,
+    configSources
+  };
+}
+async function pathExists(path) {
+  try {
+    const fsPromises = await getFsPromises();
+    await fsPromises.access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function readJsoncConfig(path) {
+  try {
+    const fsPromises = await getFsPromises();
+    const content = await fsPromises.readFile(path, "utf-8");
+    const parsed = parseJsonc(content);
+    if (!isRecord(parsed)) {
+      throw new PivvConfigError("CONFIG_INVALID", `Config at ${path} must be an object`);
+    }
+    return parsed;
+  } catch (error) {
+    if (error instanceof PivvConfigError) {
+      throw error;
+    }
+    throw new PivvConfigError("CONFIG_INVALID", `Invalid JSONC in ${path}`);
+  }
+}
+function createRunId() {
+  return `run-${Date.now()}-${Math.random().toString(16).slice(2, 10)}`;
+}
+function parseJsonc(jsonc) {
+  const withoutComments = stripJsoncComments(jsonc);
+  const normalized = stripJsoncTrailingCommas(withoutComments);
+  return JSON.parse(normalized);
+}
+function stripJsoncComments(jsonc) {
+  let result = "";
+  let inString = false;
+  let inSingleLineComment = false;
+  let inMultiLineComment = false;
+  for (let index = 0;index < jsonc.length; index += 1) {
+    const currentChar = jsonc[index];
+    const nextChar = jsonc[index + 1];
+    if (inSingleLineComment) {
+      if (currentChar === `
+`) {
+        inSingleLineComment = false;
+        result += currentChar;
+      }
+      continue;
+    }
+    if (inMultiLineComment) {
+      if (currentChar === "*" && nextChar === "/") {
+        inMultiLineComment = false;
+        index += 1;
+      }
+      continue;
+    }
+    if (currentChar === '"' && !isEscapedCharacter(jsonc, index)) {
+      inString = !inString;
+      result += currentChar;
+      continue;
+    }
+    if (!inString && currentChar === "/" && nextChar === "/") {
+      inSingleLineComment = true;
+      index += 1;
+      continue;
+    }
+    if (!inString && currentChar === "/" && nextChar === "*") {
+      inMultiLineComment = true;
+      index += 1;
+      continue;
+    }
+    result += currentChar;
+  }
+  return result;
+}
+function stripJsoncTrailingCommas(jsonc) {
+  let result = "";
+  let inString = false;
+  for (let index = 0;index < jsonc.length; index += 1) {
+    const currentChar = jsonc[index];
+    if (currentChar === '"' && !isEscapedCharacter(jsonc, index)) {
+      inString = !inString;
+      result += currentChar;
+      continue;
+    }
+    if (!inString && currentChar === ",") {
+      const nextSignificantChar = findNextSignificantCharacter(jsonc, index + 1);
+      if (nextSignificantChar === "}" || nextSignificantChar === "]") {
+        continue;
+      }
+    }
+    result += currentChar;
+  }
+  return result;
+}
+function findNextSignificantCharacter(content, startIndex) {
+  for (let index = startIndex;index < content.length; index += 1) {
+    const currentChar = content[index];
+    if (!isWhitespace(currentChar)) {
+      return currentChar;
+    }
+  }
+  return null;
+}
+function isEscapedCharacter(content, quoteIndex) {
+  let backslashCount = 0;
+  for (let index = quoteIndex - 1;index >= 0 && content[index] === "\\"; index -= 1) {
+    backslashCount += 1;
+  }
+  return backslashCount % 2 === 1;
+}
+function isWhitespace(char) {
+  return char === " " || char === `
+` || char === "\r" || char === "\t";
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function deepMerge(baseValue, overrideValue) {
+  if (!isRecord(baseValue) || !isRecord(overrideValue)) {
+    return overrideValue;
+  }
+  const mergedValue = { ...baseValue };
+  for (const [key, value] of Object.entries(overrideValue)) {
+    const baseEntry = mergedValue[key];
+    mergedValue[key] = isRecord(baseEntry) && isRecord(value) ? deepMerge(baseEntry, value) : value;
+  }
+  return mergedValue;
+}
+var fsPromisesCache = null;
+async function getFsPromises() {
+  if (fsPromisesCache !== null) {
+    return fsPromisesCache;
+  }
+  const fsPromises = await import(FS_PROMISES_IMPORT);
+  fsPromisesCache = fsPromises;
+  return fsPromises;
+}
+function resolvePath(path) {
+  if (path.startsWith("/")) {
+    return normalizePath(path);
+  }
+  return normalizePath(`${process.cwd()}/${path}`);
+}
+function joinPath(basePath, relativePath) {
+  const normalizedBase = normalizePath(basePath).replace(/\/$/, "");
+  const normalizedRelative = relativePath.replace(/^\/+/, "");
+  return normalizePath(`${normalizedBase}/${normalizedRelative}`);
+}
+function getParentPath(path) {
+  const normalized = normalizePath(path);
+  if (normalized === "/") {
+    return "/";
+  }
+  const lastSlashIndex = normalized.lastIndexOf("/");
+  if (lastSlashIndex <= 0) {
+    return "/";
+  }
+  return normalized.slice(0, lastSlashIndex);
+}
+function normalizePath(path) {
+  const withSingleSlashes = path.replace(/\/+/g, "/");
+  if (withSingleSlashes.length > 1 && withSingleSlashes.endsWith("/")) {
+    return withSingleSlashes.slice(0, -1);
+  }
+  return withSingleSlashes;
+}
+
+// src/opencode/build-runtime-overlay.ts
+import { mkdir, writeFile } from "fs/promises";
+import { join } from "path";
+var OVERLAY_LOG_PREFIX = "[VvcodeOverlay]";
+var BLOCK_GENERATE_ALIAS_MODELS = "BLOCK_GENERATE_ALIAS_MODELS";
+
+class PivvOverlayError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "PivvOverlayError";
+    this.code = code;
+  }
+}
+function generateAliasModels(resolvedPreset) {
+  const aliasModelsByProvider = Object.create(null);
+  for (const resolvedProfile of Object.values(resolvedPreset.profiles)) {
+    const providerBucket = aliasModelsByProvider[resolvedProfile.provider] ?? (aliasModelsByProvider[resolvedProfile.provider] = Object.create(null));
+    const aliasModelId = toAliasModelId(resolvedProfile.alias);
+    if (aliasModelId in providerBucket) {
+      throw new PivvOverlayError("PROFILE_ALIAS_GENERATION_FAILED", `Alias model generation collided for provider "${resolvedProfile.provider}" alias "${resolvedProfile.alias}"`);
+    }
+    providerBucket[aliasModelId] = createAliasModelDefinition(aliasModelId, resolvedProfile);
+  }
+  const providerIds = Object.keys(aliasModelsByProvider).sort();
+  const aliasModelCount = providerIds.reduce((count, providerId) => count + Object.keys(aliasModelsByProvider[providerId]).length, 0);
+  console.info(`${OVERLAY_LOG_PREFIX}[generateAliasModels][${BLOCK_GENERATE_ALIAS_MODELS}] generated alias models`, {
+    preset: resolvedPreset.presetName,
+    aliasModelCount,
+    providerIds
+  });
+  return aliasModelsByProvider;
+}
+async function buildRuntimeOverlay(resolvedPreset, projectConfig, baseOpenCodeInputs) {
+  const projectOverlay = toProjectOverlayFragments(projectConfig.overlay);
+  const allowCustomNameCollisions = projectOverlay.allowCustomNameCollisions === true || baseOpenCodeInputs.collisionPolicy?.allowCustomNameCollisions === true;
+  assertNoCustomNameCollisions("agents", Object.keys(projectOverlay.agents), Object.keys(baseOpenCodeInputs.agents), new Set(baseOpenCodeInputs.collisionPolicy?.builtInNames?.agents ?? []), allowCustomNameCollisions);
+  assertNoCustomNameCollisions("commands", Object.keys(projectOverlay.commands), Object.keys(baseOpenCodeInputs.commands), new Set(baseOpenCodeInputs.collisionPolicy?.builtInNames?.commands ?? []), allowCustomNameCollisions);
+  assertNoCustomNameCollisions("tools", Object.keys(projectOverlay.tools), Object.keys(baseOpenCodeInputs.tools), new Set(baseOpenCodeInputs.collisionPolicy?.builtInNames?.tools ?? []), allowCustomNameCollisions);
+  const aliasModels = generateAliasModels(resolvedPreset);
+  const providerIds = Object.keys(aliasModels).sort();
+  const aliasModelCount = providerIds.reduce((count, providerId) => count + Object.keys(aliasModels[providerId]).length, 0);
+  const providersWithAliases = mergeProvidersWithAliasModels(baseOpenCodeInputs.providers, aliasModels);
+  const overlayDirPath = join(projectConfig.projectRoot, ".vvcode", "local", "runtime", "overlays");
+  const overlayFilePath = join(overlayDirPath, `${toOverlayFilename(resolvedPreset.presetName)}-runtime-overlay.json`);
+  const sourcePaths = dedupeSourcePaths([
+    ...projectConfig.configSources,
+    ...resolvedPreset.configSources,
+    ...baseOpenCodeInputs.sourcePaths ?? []
+  ]);
+  const runtimeOverlay = {
+    overlayDirPath,
+    overlayFilePath,
+    preset: resolvedPreset.presetName,
+    aliasModelCount,
+    providerIds,
+    aliasModels,
+    providers: providersWithAliases,
+    agents: {
+      ...baseOpenCodeInputs.agents,
+      ...projectOverlay.agents
+    },
+    commands: {
+      ...baseOpenCodeInputs.commands,
+      ...projectOverlay.commands
+    },
+    tools: {
+      ...baseOpenCodeInputs.tools,
+      ...projectOverlay.tools
+    },
+    metadata: {
+      sourcePaths,
+      collisionPolicy: {
+        allowCustomNameCollisions
+      }
+    }
+  };
+  await mkdir(overlayDirPath, { recursive: true });
+  await writeFile(overlayFilePath, `${JSON.stringify(runtimeOverlay, null, 2)}
+`, "utf8");
+  console.info(`${OVERLAY_LOG_PREFIX}[buildRuntimeOverlay][${BLOCK_GENERATE_ALIAS_MODELS}] compiled runtime overlay`, {
+    preset: resolvedPreset.presetName,
+    aliasModelCount,
+    providerIds
+  });
+  return runtimeOverlay;
+}
+function toProjectOverlayFragments(overlay) {
+  return {
+    agents: toNamedEntityMap(overlay.agents),
+    commands: toNamedEntityMap(overlay.commands),
+    tools: toNamedEntityMap(overlay.tools),
+    allowCustomNameCollisions: typeof overlay.allowCustomNameCollisions === "boolean" ? overlay.allowCustomNameCollisions : undefined
+  };
+}
+function mergeProvidersWithAliasModels(baseProviders, aliasModels) {
+  const mergedProviders = { ...baseProviders };
+  for (const [providerId, providerAliasModels] of Object.entries(aliasModels)) {
+    const providerRecord = toRecord(mergedProviders[providerId]);
+    const baseProviderModels = toRecord(providerRecord.models);
+    for (const aliasModelId of Object.keys(providerAliasModels)) {
+      if (aliasModelId in baseProviderModels) {
+        throw new PivvOverlayError("PROFILE_ALIAS_GENERATION_FAILED", `Alias model id "${aliasModelId}" for provider "${providerId}" collides with existing OpenCode model id`);
+      }
+    }
+    mergedProviders[providerId] = {
+      ...providerRecord,
+      id: providerRecord.id ?? providerId,
+      models: {
+        ...baseProviderModels,
+        ...providerAliasModels
+      }
+    };
+  }
+  return mergedProviders;
+}
+function createAliasModelDefinition(aliasModelId, resolvedProfile) {
+  return {
+    id: aliasModelId,
+    name: toFriendlyAliasName(resolvedProfile.alias),
+    provider: resolvedProfile.provider,
+    model: resolvedProfile.model,
+    profileName: resolvedProfile.profileName,
+    alias: resolvedProfile.alias,
+    options: resolvedProfile.options
+  };
+}
+function toAliasModelId(alias) {
+  const trimmedAlias = alias.trim();
+  const normalizedAlias = trimmedAlias.toLowerCase().replaceAll(/[^a-z0-9]+/g, "-").replaceAll(/^-+|-+$/g, "");
+  if (!normalizedAlias) {
+    throw new PivvOverlayError("PROFILE_ALIAS_GENERATION_FAILED", `Alias model generation failed because alias "${alias}" is empty after normalization`);
+  }
+  return `vvcode-${normalizedAlias}`;
+}
+function toFriendlyAliasName(alias) {
+  return `vvcode ${alias.trim()}`;
+}
+function assertNoCustomNameCollisions(kind, pivvNames, baseNames, builtInNames, allowCustomNameCollisions) {
+  if (allowCustomNameCollisions) {
+    return;
+  }
+  const baseNameSet = new Set(baseNames);
+  for (const pivvName of pivvNames) {
+    if (baseNameSet.has(pivvName) && !builtInNames.has(pivvName)) {
+      throw new PivvOverlayError("CUSTOM_NAME_COLLISION", `Custom ${kind} name collision for "${pivvName}" between .vvcode overlay and .opencode inputs`);
+    }
+  }
+}
+function toNamedEntityMap(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return Object.create(null);
+  }
+  const entries = Object.entries(value);
+  const result = Object.create(null);
+  for (const [name, entryValue] of entries) {
+    result[name] = toRecord(entryValue);
+  }
+  return result;
+}
+function toRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return Object.create(null);
+  }
+  return value;
+}
+function dedupeSourcePaths(paths) {
+  const seen = new Set;
+  const deduped = [];
+  for (const path of paths) {
+    if (seen.has(path)) {
+      continue;
+    }
+    seen.add(path);
+    deduped.push(path);
+  }
+  return deduped;
+}
+function sanitizeForFilename(value) {
+  const sanitized = value.replaceAll(/[^a-zA-Z0-9-]+/g, "-").replaceAll(/^-+|-+$/g, "");
+  return sanitized || "runtime";
+}
+function toOverlayFilename(presetName) {
+  return `${sanitizeForFilename(presetName)}-${toPresetNameFingerprint(presetName)}`;
+}
+function toPresetNameFingerprint(value) {
+  let hash = 2166136261;
+  for (let index = 0;index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+
+// src/preset/resolve-preset.ts
+var PRESET_LOG_PREFIX = "[VvcodePreset]";
+var BLOCK_RESOLVE_PROFILE_BINDINGS = "BLOCK_RESOLVE_PROFILE_BINDINGS";
+var BLOCK_RETURN_RESOLVED_PRESET = "BLOCK_RETURN_RESOLVED_PRESET";
+var CORE_SLOTS = ["default", "smart", "small", "vision"];
+
+class PivvPresetError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "PivvPresetError";
+    this.code = code;
+  }
+}
+function resolvePreset(presetName, config) {
+  const preset = config.presets[presetName];
+  if (!preset) {
+    throw new PivvPresetError("PRESET_NOT_FOUND", `Preset "${presetName}" was not found`);
+  }
+  const resolvedProfiles = Object.create(null);
+  const canonicalAliasMap = new Map;
+  for (const [alias, profileName] of Object.entries(preset)) {
+    const canonicalAlias = toCanonicalAlias(alias);
+    const existingAlias = canonicalAliasMap.get(canonicalAlias);
+    if (canonicalAliasMap.has(canonicalAlias) && existingAlias !== alias) {
+      throw new PivvPresetError("PROFILE_ALIAS_CONFLICT", `Preset "${presetName}" includes conflicting aliases "${existingAlias}" and "${alias}"`);
+    }
+    canonicalAliasMap.set(canonicalAlias, alias);
+    resolvedProfiles[alias] = resolveProfile(alias, profileName, config.profiles);
+  }
+  const missingCoreSlot = CORE_SLOTS.find((slot) => !(slot in resolvedProfiles));
+  if (missingCoreSlot) {
+    throw new PivvPresetError("PROFILE_MISSING_CORE_SLOT", `Preset "${presetName}" is missing required core slot "${missingCoreSlot}"`);
+  }
+  const coreProfiles = {
+    default: resolvedProfiles.default,
+    smart: resolvedProfiles.smart,
+    small: resolvedProfiles.small,
+    vision: resolvedProfiles.vision
+  };
+  const profileCount = Object.keys(resolvedProfiles).length;
+  console.info(`${PRESET_LOG_PREFIX}[resolvePreset][${BLOCK_RESOLVE_PROFILE_BINDINGS}] resolved preset profile bindings`, {
+    preset: presetName,
+    profileCount,
+    coreSlotsResolved: CORE_SLOTS.length
+  });
+  const resolvedPreset = {
+    presetName,
+    coreProfiles,
+    profiles: resolvedProfiles,
+    profileCount,
+    projectRoot: config.projectRoot,
+    configSources: config.configSources,
+    memory: config.memory,
+    overlay: config.overlay
+  };
+  console.info(`${PRESET_LOG_PREFIX}[resolvePreset][${BLOCK_RETURN_RESOLVED_PRESET}] returning resolved preset`, {
+    preset: presetName,
+    profileCount,
+    coreSlotsResolved: CORE_SLOTS.length
+  });
+  return resolvedPreset;
+}
+function resolveProfile(alias, profileName, profiles) {
+  const profile = profiles[profileName];
+  if (!profile) {
+    throw new PivvPresetError("PROFILE_ALIAS_CONFLICT", `Alias "${alias}" references unknown profile "${profileName}"`);
+  }
+  return {
+    alias,
+    profileName,
+    provider: profile.provider,
+    model: profile.model,
+    options: profile.options
+  };
+}
+function toCanonicalAlias(alias) {
+  return alias.trim().toLowerCase();
+}
+
+// src/trace/trace-recorder.ts
+import { appendFile, mkdir as mkdir2 } from "fs/promises";
+import { join as join2 } from "path";
+var TRACE_LOG_PREFIX = "[VvcodeTrace]";
+var TRACE_BLOCK_PERSIST_EVENT = "BLOCK_PERSIST_TRACE_EVENT";
+var TRACE_WRITE_FAILED = "TRACE_WRITE_FAILED";
+var REDACTION_TOKEN = "[REDACTED]";
+var TERMINAL_EVENTS = new Set(["run.finish", "run.fail"]);
+var SENSITIVE_KEY_MATCHERS = ["token", "apikey", "authorization", "secret", "password", "credential"];
+function redactTracePayload(payload) {
+  const seen = new WeakSet;
+  const redactInner = (value) => {
+    if (value === null || value === undefined) {
+      return value;
+    }
+    if (typeof value !== "object") {
+      return value;
+    }
+    if (seen.has(value)) {
+      return "[REDACTED_CIRCULAR_REFERENCE]";
+    }
+    seen.add(value);
+    if (Array.isArray(value)) {
+      return value.map((item) => redactInner(item));
+    }
+    const redactedRecord = {};
+    for (const [key, nestedValue] of Object.entries(value)) {
+      if (isSensitiveKey(key)) {
+        redactedRecord[key] = REDACTION_TOKEN;
+        continue;
+      }
+      redactedRecord[key] = redactInner(nestedValue);
+    }
+    return redactedRecord;
+  };
+  return redactInner(payload);
+}
+function createTraceRecorder(options = {}) {
+  const now = options.now ?? (() => new Date);
+  const projectRoot = options.projectRoot ?? process.cwd();
+  const log = options.logger ?? (() => {
+    return;
+  });
+  const runTerminalState = new Map;
+  const runOperationQueue = new Map;
+  const enqueueRunOperation = (runId, operation) => {
+    const previous = runOperationQueue.get(runId) ?? Promise.resolve();
+    const next = previous.catch(() => {
+      return;
+    }).then(operation);
+    const settled = next.then(() => {
+      return;
+    }, () => {
+      return;
+    });
+    runOperationQueue.set(runId, settled);
+    return next.finally(() => {
+      if (runOperationQueue.get(runId) === settled) {
+        runOperationQueue.delete(runId);
+      }
+    });
+  };
+  return {
+    persistTraceEvent(event, traceContext) {
+      return enqueueRunOperation(traceContext.runId, async () => {
+        const isTerminalEvent = event.terminal === true || TERMINAL_EVENTS.has(event.event);
+        const traceDir = join2(projectRoot, ".vvcode", "local", "runtime", "traces");
+        const traceFilePath = join2(traceDir, `${toTraceFileName(traceContext.runId)}.jsonl`);
+        const functionName = event.function ?? "persistTraceEvent";
+        try {
+          if (isTerminalEvent && runTerminalState.get(traceContext.runId) === true) {
+            throw createTraceWriteError(`runId ${traceContext.runId} already contains a terminal event`);
+          }
+          const persistedTrace = {
+            event: event.event,
+            ts: event.ts ?? now().toISOString(),
+            runId: traceContext.runId,
+            sessionId: traceContext.sessionId,
+            turnId: traceContext.turnId,
+            toolCallId: traceContext.toolCallId,
+            correlationId: traceContext.correlationId,
+            module: event.module,
+            function: functionName,
+            block: event.block,
+            preset: traceContext.preset,
+            profile: traceContext.profile,
+            outcome: event.outcome,
+            payload: redactTracePayload(event.payload)
+          };
+          const traceLine = `${JSON.stringify(persistedTrace)}
+`;
+          const bytesWritten = new TextEncoder().encode(traceLine).byteLength;
+          await mkdir2(traceDir, { recursive: true });
+          await appendFile(traceFilePath, traceLine, "utf8");
+          if (isTerminalEvent) {
+            runTerminalState.set(traceContext.runId, true);
+          }
+          log({
+            message: `${TRACE_LOG_PREFIX}[persistTraceEvent][${TRACE_BLOCK_PERSIST_EVENT}] trace event persisted`,
+            runId: traceContext.runId,
+            module: event.module,
+            function: functionName,
+            block: event.block,
+            outcome: event.outcome,
+            event: event.event,
+            traceFilePath,
+            bytesWritten
+          });
+          return {
+            ok: true,
+            traceFilePath,
+            bytesWritten,
+            persistedTrace
+          };
+        } catch (error) {
+          const writeError = isTraceRecorderError(error) ? error : createTraceWriteError("failed to persist trace event", error);
+          log({
+            message: `${TRACE_LOG_PREFIX}[persistTraceEvent][${TRACE_BLOCK_PERSIST_EVENT}] trace persist failed`,
+            runId: traceContext.runId,
+            module: event.module,
+            function: functionName,
+            block: event.block,
+            outcome: "failure",
+            event: event.event,
+            errorCode: writeError.code
+          });
+          throw writeError;
+        }
+      });
+    }
+  };
+}
+function toTraceFileName(runId) {
+  let encoded = "";
+  for (let index = 0;index < runId.length; index += 1) {
+    const codeUnit = runId.charCodeAt(index);
+    encoded += codeUnit.toString(16).padStart(4, "0");
+  }
+  return `run-${encoded}`;
+}
+function isSensitiveKey(key) {
+  const normalized = key.toLowerCase().replaceAll(/[^a-z]/g, "");
+  return SENSITIVE_KEY_MATCHERS.some((matcher) => normalized.includes(matcher));
+}
+function isTraceRecorderError(error) {
+  return error instanceof Error && "code" in error && error.code === TRACE_WRITE_FAILED;
+}
+function createTraceWriteError(message, cause) {
+  const error = new Error(message);
+  error.name = "TraceRecorderError";
+  error.code = TRACE_WRITE_FAILED;
+  error.cause = cause;
+  return error;
+}
+
+// src/cli/pivv-opencode.ts
+var LAUNCHER_LOG_PREFIX = "[VvcodeLauncher]";
+var BLOCK_LOAD_ACTIVE_PRESET = "BLOCK_LOAD_ACTIVE_PRESET";
+var OPENCODE_ENTRYPOINT = "bun x opencode-ai";
+function buildRuntimeEnvironment(runtimeOverlay, baseEnvironment = process.env) {
+  const runtimeEnvironment = {};
+  for (const [key, value] of Object.entries(baseEnvironment)) {
+    if (typeof value === "string") {
+      runtimeEnvironment[key] = value;
+    }
+  }
+  runtimeEnvironment.OPENCODE_CONFIG_DIR = runtimeOverlay.overlayDirPath;
+  runtimeEnvironment.OPENCODE_CONFIG_CONTENT = JSON.stringify(runtimeOverlay);
+  return runtimeEnvironment;
+}
+async function runPivvOpencode(cliArgs) {
+  let traceRecorder = cliArgs.traceRecorder;
+  const traceContext = {
+    runId: cliArgs.traceRunId ?? createLaunchRunId(),
+    preset: cliArgs.preset
+  };
+  const baseOpenCodeInputs = cliArgs.baseOpenCodeInputs ?? createEmptyOpenCodeBaseInputs();
+  let runtimeOverlayPath = null;
+  let resolvedProjectRoot = cliArgs.projectRoot;
+  let aliasModelCount = 0;
+  let providerIds = [];
+  let lifecycleStage = "config.load";
+  if (!traceRecorder) {
+    try {
+      resolvedProjectRoot = await findProjectRoot(cliArgs.projectRoot);
+    } catch {
+      resolvedProjectRoot = cliArgs.projectRoot;
+    }
+    traceRecorder = createTraceRecorder({ projectRoot: resolvedProjectRoot });
+  }
+  await persistLaunchTrace(traceRecorder, traceContext, {
+    event: "run.start",
+    module: "M-LAUNCHER",
+    function: "runPivvOpencode",
+    block: BLOCK_LOAD_ACTIVE_PRESET,
+    outcome: "success",
+    payload: {
+      preset: cliArgs.preset,
+      projectRoot: resolvedProjectRoot,
+      cwd: resolvedProjectRoot,
+      entrypoint: OPENCODE_ENTRYPOINT
+    }
+  });
+  try {
+    await persistLaunchTrace(traceRecorder, traceContext, {
+      event: "config.load.start",
+      module: "M-CONFIG",
+      function: "loadPivvConfig",
+      block: "BLOCK_LOAD_CONFIG_SOURCES",
+      outcome: "success",
+      payload: {
+        preset: cliArgs.preset,
+        projectRoot: resolvedProjectRoot,
+        cwd: resolvedProjectRoot,
+        entrypoint: OPENCODE_ENTRYPOINT
+      }
+    });
+    const projectConfig = await loadPivvConfig(cliArgs.globalConfigPath, cliArgs.projectRoot);
+    resolvedProjectRoot = projectConfig.projectRoot;
+    await persistLaunchTrace(traceRecorder, traceContext, {
+      event: "config.load.finish",
+      module: "M-CONFIG",
+      function: "loadPivvConfig",
+      block: "BLOCK_VALIDATE_CONFIG",
+      outcome: "success",
+      payload: {
+        preset: cliArgs.preset,
+        projectRoot: resolvedProjectRoot,
+        cwd: resolvedProjectRoot,
+        entrypoint: OPENCODE_ENTRYPOINT
+      }
+    });
+    lifecycleStage = "preset.resolve";
+    await persistLaunchTrace(traceRecorder, traceContext, {
+      event: "preset.resolve.start",
+      module: "M-PRESET",
+      function: "resolvePreset",
+      block: "BLOCK_RESOLVE_PROFILE_BINDINGS",
+      outcome: "success",
+      payload: {
+        preset: cliArgs.preset,
+        coreSlotsResolved: 0,
+        cwd: resolvedProjectRoot,
+        entrypoint: OPENCODE_ENTRYPOINT
+      }
+    });
+    const resolvedPreset = resolvePreset(cliArgs.preset, projectConfig);
+    await persistLaunchTrace(traceRecorder, traceContext, {
+      event: "preset.resolve.finish",
+      module: "M-PRESET",
+      function: "resolvePreset",
+      block: "BLOCK_RESOLVE_PROFILE_BINDINGS",
+      outcome: "success",
+      payload: {
+        preset: cliArgs.preset,
+        profileCount: resolvedPreset.profileCount,
+        coreSlotsResolved: Object.keys(resolvedPreset.coreProfiles).length,
+        cwd: resolvedProjectRoot,
+        entrypoint: OPENCODE_ENTRYPOINT
+      }
+    });
+    lifecycleStage = "overlay.build";
+    await persistLaunchTrace(traceRecorder, traceContext, {
+      event: "overlay.build.start",
+      module: "M-OVERLAY",
+      function: "buildRuntimeOverlay",
+      block: "BLOCK_GENERATE_ALIAS_MODELS",
+      outcome: "success",
+      payload: {
+        preset: cliArgs.preset,
+        aliasModelCount,
+        providerIds,
+        cwd: resolvedProjectRoot,
+        entrypoint: OPENCODE_ENTRYPOINT
+      }
+    });
+    const runtimeOverlay = await buildRuntimeOverlay(resolvedPreset, projectConfig, baseOpenCodeInputs);
+    runtimeOverlayPath = runtimeOverlay.overlayFilePath;
+    aliasModelCount = runtimeOverlay.aliasModelCount;
+    providerIds = runtimeOverlay.providerIds;
+    await persistLaunchTrace(traceRecorder, traceContext, {
+      event: "overlay.build.finish",
+      module: "M-OVERLAY",
+      function: "buildRuntimeOverlay",
+      block: "BLOCK_GENERATE_ALIAS_MODELS",
+      outcome: "success",
+      payload: {
+        preset: cliArgs.preset,
+        runtimeOverlayPath,
+        aliasModelCount,
+        providerIds,
+        cwd: resolvedProjectRoot,
+        entrypoint: OPENCODE_ENTRYPOINT
+      }
+    });
+    lifecycleStage = "launch";
+    const runtimeEnvironment = buildRuntimeEnvironment(runtimeOverlay);
+    await persistLaunchTrace(traceRecorder, traceContext, {
+      event: "launch.start",
+      module: "M-LAUNCHER",
+      function: "runPivvOpencode",
+      block: BLOCK_LOAD_ACTIVE_PRESET,
+      outcome: "success",
+      payload: {
+        preset: cliArgs.preset,
+        projectRoot: resolvedProjectRoot,
+        runtimeOverlayPath,
+        aliasModelCount,
+        providerIds,
+        cwd: resolvedProjectRoot,
+        entrypoint: OPENCODE_ENTRYPOINT
+      }
+    });
+    const launchResult = await launchOpenCodeProcess({
+      preset: cliArgs.preset,
+      projectRoot: resolvedProjectRoot,
+      runtimeOverlay,
+      runtimeEnvironment,
+      traceContext
+    });
+    if (launchResult.exitCode !== 0) {
+      const cleanupResult = await cleanupRuntimeOverlay(runtimeOverlayPath);
+      const failureResult = await finalizeLaunchFailure(traceRecorder, traceContext, {
+        preset: cliArgs.preset,
+        projectRoot: resolvedProjectRoot,
+        runtimeOverlayPath,
+        code: "LAUNCH_OPENCODE_FAILED",
+        exitCode: launchResult.exitCode,
+        cleanupResult,
+        aliasModelCount,
+        providerIds
+      });
+      return failureResult;
+    }
+    const launchReadyTrace = await persistLaunchTrace(traceRecorder, traceContext, {
+      event: "launch.ready",
+      module: "M-LAUNCHER",
+      function: "runPivvOpencode",
+      block: BLOCK_LOAD_ACTIVE_PRESET,
+      outcome: "success",
+      payload: {
+        preset: cliArgs.preset,
+        projectRoot: resolvedProjectRoot,
+        runtimeOverlayPath,
+        aliasModelCount,
+        providerIds,
+        cwd: resolvedProjectRoot,
+        entrypoint: OPENCODE_ENTRYPOINT
+      }
+    });
+    const runFinishTrace = await persistLaunchTrace(traceRecorder, traceContext, {
+      event: "run.finish",
+      module: "M-LAUNCHER",
+      function: "runPivvOpencode",
+      block: BLOCK_LOAD_ACTIVE_PRESET,
+      outcome: "success",
+      terminal: true,
+      payload: {
+        preset: cliArgs.preset,
+        projectRoot: resolvedProjectRoot,
+        runtimeOverlayPath,
+        cwd: resolvedProjectRoot,
+        entrypoint: OPENCODE_ENTRYPOINT
+      }
+    });
+    console.info(`${LAUNCHER_LOG_PREFIX}[runPivvOpencode][${BLOCK_LOAD_ACTIVE_PRESET}] launch completed`, {
+      preset: cliArgs.preset,
+      projectRoot: resolvedProjectRoot,
+      runtimeOverlayPath,
+      outcome: "launch-ready"
+    });
+    return {
+      ok: true,
+      preset: cliArgs.preset,
+      projectRoot: resolvedProjectRoot,
+      runtimeOverlayPath,
+      outcome: "launch-ready",
+      exitCode: launchResult.exitCode,
+      traceFilePath: runFinishTrace?.traceFilePath ?? launchReadyTrace?.traceFilePath
+    };
+  } catch (error) {
+    if (lifecycleStage === "config.load") {
+      await persistLaunchTrace(traceRecorder, traceContext, {
+        event: "config.load.fail",
+        module: "M-CONFIG",
+        function: "loadPivvConfig",
+        block: "BLOCK_VALIDATE_CONFIG",
+        outcome: "failure",
+        payload: {
+          preset: cliArgs.preset,
+          projectRoot: resolvedProjectRoot,
+          cwd: resolvedProjectRoot,
+          entrypoint: OPENCODE_ENTRYPOINT
+        }
+      });
+    }
+    if (lifecycleStage === "preset.resolve") {
+      await persistLaunchTrace(traceRecorder, traceContext, {
+        event: "preset.resolve.fail",
+        module: "M-PRESET",
+        function: "resolvePreset",
+        block: "BLOCK_RESOLVE_PROFILE_BINDINGS",
+        outcome: "failure",
+        payload: {
+          preset: cliArgs.preset,
+          projectRoot: resolvedProjectRoot,
+          coreSlotsResolved: 0,
+          cwd: resolvedProjectRoot,
+          entrypoint: OPENCODE_ENTRYPOINT
+        }
+      });
+    }
+    if (lifecycleStage === "overlay.build") {
+      await persistLaunchTrace(traceRecorder, traceContext, {
+        event: "overlay.build.fail",
+        module: "M-OVERLAY",
+        function: "buildRuntimeOverlay",
+        block: "BLOCK_GENERATE_ALIAS_MODELS",
+        outcome: "failure",
+        payload: {
+          preset: cliArgs.preset,
+          projectRoot: resolvedProjectRoot,
+          runtimeOverlayPath,
+          aliasModelCount,
+          providerIds,
+          cwd: resolvedProjectRoot,
+          entrypoint: OPENCODE_ENTRYPOINT
+        }
+      });
+    }
+    const failureCode = isPresetInvalidError(error) ? "LAUNCH_PRESET_INVALID" : "LAUNCH_OPENCODE_FAILED";
+    const cleanupResult = failureCode === "LAUNCH_OPENCODE_FAILED" && runtimeOverlayPath ? await cleanupRuntimeOverlay(runtimeOverlayPath) : undefined;
+    return finalizeLaunchFailure(traceRecorder, traceContext, {
+      preset: cliArgs.preset,
+      projectRoot: resolvedProjectRoot,
+      runtimeOverlayPath,
+      code: failureCode,
+      cleanupResult,
+      aliasModelCount,
+      providerIds
+    });
+  }
+}
+function createLaunchRunId() {
+  return `launch-${Date.now()}-${Math.random().toString(16).slice(2, 10)}`;
+}
+function createEmptyOpenCodeBaseInputs() {
+  return {
+    providers: {},
+    agents: {},
+    commands: {},
+    tools: {}
+  };
+}
+function isPresetInvalidError(error) {
+  if (!error || typeof error !== "object") {
+    return false;
+  }
+  const errorCode = error.code;
+  return errorCode === "PRESET_NOT_FOUND" || errorCode === "PROFILE_MISSING_CORE_SLOT" || errorCode === "PROFILE_ALIAS_CONFLICT" || errorCode === "CUSTOM_NAME_COLLISION" || errorCode === "PROFILE_ALIAS_GENERATION_FAILED" || errorCode === "CONFIG_NOT_FOUND" || errorCode === "CONFIG_INVALID";
+}
+async function cleanupRuntimeOverlay(runtimeOverlayPath) {
+  try {
+    await rm(runtimeOverlayPath, { force: true });
+    return {
+      cleanupFailed: false
+    };
+  } catch (error) {
+    return {
+      cleanupFailed: true,
+      cleanupErrorMessage: error instanceof Error ? error.message : "unknown cleanup error"
+    };
+  }
+}
+async function persistLaunchTrace(traceRecorder, traceContext, event) {
+  try {
+    return await traceRecorder.persistTraceEvent(event, traceContext);
+  } catch {
+    return;
+  }
+}
+async function finalizeLaunchFailure(traceRecorder, traceContext, context) {
+  const traceResult = await persistLaunchTrace(traceRecorder, traceContext, {
+    event: "launch.fail",
+    module: "M-LAUNCHER",
+    function: "runPivvOpencode",
+    block: BLOCK_LOAD_ACTIVE_PRESET,
+    outcome: "failure",
+    payload: {
+      preset: context.preset,
+      projectRoot: context.projectRoot,
+      runtimeOverlayPath: context.runtimeOverlayPath,
+      code: context.code,
+      exitCode: context.exitCode,
+      cleanupFailed: context.cleanupResult?.cleanupFailed === true,
+      cleanupErrorMessage: context.cleanupResult?.cleanupErrorMessage,
+      aliasModelCount: context.aliasModelCount,
+      providerIds: context.providerIds,
+      cwd: context.projectRoot,
+      entrypoint: OPENCODE_ENTRYPOINT
+    }
+  });
+  const runFailTrace = await persistLaunchTrace(traceRecorder, traceContext, {
+    event: "run.fail",
+    module: "M-LAUNCHER",
+    function: "runPivvOpencode",
+    block: BLOCK_LOAD_ACTIVE_PRESET,
+    outcome: "failure",
+    terminal: true,
+    payload: {
+      preset: context.preset,
+      projectRoot: context.projectRoot,
+      runtimeOverlayPath: context.runtimeOverlayPath,
+      code: context.code,
+      exitCode: context.exitCode,
+      cwd: context.projectRoot,
+      entrypoint: OPENCODE_ENTRYPOINT
+    }
+  });
+  console.info(`${LAUNCHER_LOG_PREFIX}[runPivvOpencode][${BLOCK_LOAD_ACTIVE_PRESET}] launch failed`, {
+    preset: context.preset,
+    projectRoot: context.projectRoot,
+    runtimeOverlayPath: context.runtimeOverlayPath,
+    outcome: "launch-failed"
+  });
+  return {
+    ok: false,
+    preset: context.preset,
+    projectRoot: context.projectRoot,
+    runtimeOverlayPath: context.runtimeOverlayPath,
+    outcome: "launch-failed",
+    code: context.code,
+    exitCode: context.exitCode,
+    traceFilePath: runFailTrace?.traceFilePath ?? traceResult?.traceFilePath
+  };
+}
+async function launchOpenCodeProcess(request) {
+  return await new Promise((resolve, reject) => {
+    const launchedProcess = spawn("bun", ["x", "opencode-ai"], {
+      cwd: request.projectRoot,
+      env: request.runtimeEnvironment,
+      stdio: "inherit"
+    });
+    launchedProcess.once("error", (error) => {
+      reject(error);
+    });
+    launchedProcess.once("close", (exitCode) => {
+      resolve({
+        exitCode: typeof exitCode === "number" ? exitCode : 1
+      });
+    });
+  });
+}
+
+// src/cli/vvcode.ts
+var CLI_LOG_PREFIX = "[VvcodeCli]";
+var BLOCK_RUN_OPENCODE_COMMAND = "BLOCK_RUN_OPENCODE_COMMAND";
+function resolveDefaultGlobalConfigPath() {
+  return join3(homedir(), ".config", "vvcode", "config.jsonc");
+}
+function createVvcodeCommand(dependencyOverrides = {}) {
+  const dependencies = resolveVvcodeCliDependencies(dependencyOverrides);
+  const opencodeArgs = {
+    preset: {
+      type: "string",
+      description: "Preset name defined in .vvcode/config.jsonc.",
+      alias: ["p"],
+      required: true
+    },
+    "global-config": {
+      type: "string",
+      description: "Path to the global vvcode config file.",
+      alias: ["c"],
+      default: dependencies.defaultGlobalConfigPath()
+    },
+    "project-root": {
+      type: "string",
+      description: "Working directory or nested path inside the target .vvcode project.",
+      alias: ["r"],
+      default: dependencies.cwd()
+    }
+  };
+  return defineCommand({
+    meta: {
+      name: "vvcode",
+      version: package_default.version,
+      description: "Packaged CLI for launching OpenCode with vvcode runtime semantics."
+    },
+    args: opencodeArgs,
+    default: "opencode",
+    subCommands: {
+      opencode: defineCommand({
+        meta: {
+          name: "opencode",
+          description: "Launch OpenCode with a vvcode preset-backed runtime overlay."
+        },
+        args: opencodeArgs,
+        async run({ args }) {
+          console.info(`${CLI_LOG_PREFIX}[runOpencodeCommand][${BLOCK_RUN_OPENCODE_COMMAND}] dispatching vvcode launcher`, {
+            preset: String(args.preset),
+            globalConfigPath: String(args.globalConfig),
+            projectRoot: String(args.projectRoot)
+          });
+          const launchResult = await dependencies.launchOpenCode({
+            preset: String(args.preset),
+            globalConfigPath: String(args.globalConfig),
+            projectRoot: String(args.projectRoot)
+          });
+          if (!launchResult.ok) {
+            dependencies.writeStderr(formatLaunchFailure(launchResult));
+            dependencies.setExitCode(launchResult.exitCode ?? 1);
+          }
+          return launchResult;
+        }
+      })
+    }
+  });
+}
+async function runVvcodeCli(rawArgs = process.argv.slice(2), dependencyOverrides = {}) {
+  const vvcodeCommand = createVvcodeCommand(dependencyOverrides);
+  await runMain(vvcodeCommand, { rawArgs });
+}
+function resolveVvcodeCliDependencies(dependencyOverrides) {
+  return {
+    launchOpenCode: dependencyOverrides.launchOpenCode ?? runPivvOpencode,
+    cwd: dependencyOverrides.cwd ?? (() => process.cwd()),
+    defaultGlobalConfigPath: dependencyOverrides.defaultGlobalConfigPath ?? resolveDefaultGlobalConfigPath,
+    writeStderr: dependencyOverrides.writeStderr ?? ((message) => console.error(message)),
+    setExitCode: dependencyOverrides.setExitCode ?? ((code) => {
+      process.exitCode = code;
+    })
+  };
+}
+function formatLaunchFailure(launchResult) {
+  const failureFields = [
+    `vvcode: launch failed (${launchResult.code ?? "LAUNCH_OPENCODE_FAILED"})`,
+    `preset="${launchResult.preset}"`,
+    `projectRoot="${launchResult.projectRoot}"`
+  ];
+  if (launchResult.traceFilePath) {
+    failureFields.push(`traceFilePath="${launchResult.traceFilePath}"`);
+  }
+  if (launchResult.runtimeOverlayPath) {
+    failureFields.push(`runtimeOverlayPath="${launchResult.runtimeOverlayPath}"`);
+  }
+  return failureFields.join(" ");
+}
+
+// src/cli/vvcode-entry.ts
+await runVvcodeCli();