jules-orchestrator-kit 0.29.0 → 0.31.0

package/src/state.mjs

@@ -10,10 +10,20 @@ import {
   fsyncSync,
   unlinkSync,
 } from "node:fs";
-import { join } from "node:path";
+import { join, basename } from "node:path";
 import { createHash, randomUUID } from "node:crypto";
 import { hostname } from "node:os";
 import { resolveRoot } from "./config.mjs";
+import { redactSecrets } from "./security.mjs";
+
+function scrubStateValue(value) {
+  if (typeof value === "string") return redactSecrets(value);
+  if (Array.isArray(value)) return value.map(scrubStateValue);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, scrubStateValue(child)]));
+  }
+  return value;
+}
 
 export function ensureDir(dirPath) {
   if (!dirPath || typeof dirPath !== "string" || dirPath.includes("\0")) {
@@ -109,7 +119,7 @@ export function appendLedger(entry, rootOrOpts = resolveRoot()) {
     }
 
     const timestamp = new Date().toISOString();
-    const rawPayload = { timestamp, ...entry, prevHash };
+    const rawPayload = { timestamp, ...scrubStateValue(entry), prevHash };
     const hash = createHash("sha256").update(JSON.stringify(rawPayload)).digest("hex");
     const payload = { ...rawPayload, hash };
 
@@ -321,7 +331,17 @@ export async function withBudget(fn, root = resolveRoot(), limit = 300) {
     if (err && typeof err === "object") {
       err.reservationId = reservation.reservationId;
     }
-    appendLedger({ event: "budget_reservation_failed", reservationId: reservation.reservationId, error: err.message }, root);
+    try {
+      rollbackBudgetReservation(root, reservation.reservationId);
+      if (err && typeof err === "object") err.budgetReservationRolledBack = true;
+    } catch (_) {}
+    try {
+      appendLedger({
+        event: "budget_reservation_failed",
+        reservationId: reservation.reservationId,
+        error: err?.message || String(err),
+      }, root);
+    } catch (_) {}
     throw err;
   }
 }
@@ -363,8 +383,8 @@ export function isPidAlive(pid, expectedStartTime = null) {
   if (!pid || typeof pid !== "number") return false;
   try {
     process.kill(pid, 0);
-  } catch (_) {
-    return false;
+  } catch (err) {
+    if (err?.code !== "EPERM") return false;
   }
 
   if (expectedStartTime !== null && expectedStartTime !== undefined && process.platform === "linux") {
@@ -381,7 +401,14 @@ export function isPidAlive(pid, expectedStartTime = null) {
   return true;
 }
 
+function assertSafeTaskId(taskId) {
+  if (typeof taskId !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(taskId) || basename(taskId) !== taskId) {
+    throw new Error("Invalid task id for lock path");
+  }
+}
+
 export function acquireLock(agentName, taskId, files = [], rootOrOpts = resolveRoot(), opts = {}) {
+  assertSafeTaskId(taskId);
   const root = typeof rootOrOpts === "string" ? rootOrOpts : (rootOrOpts?.root || resolveRoot());
   const branch = (typeof rootOrOpts === "object" && rootOrOpts?.branch) || opts?.branch || process.env.JULES_BRANCH || process.env.BRANCH_NAME || "";
   const lockDir = getLockDir(root);
@@ -418,11 +445,11 @@ export function acquireLock(agentName, taskId, files = [], rootOrOpts = resolveR
     acquiredAt: new Date().toISOString(),
   };
 
+  let fd;
   try {
-    const fd = openSync(lockFile, "wx");
+    fd = openSync(lockFile, "wx");
     writeSync(fd, JSON.stringify(payload, null, 2), "utf-8");
     fsyncSync(fd);
-    closeSync(fd);
     return { ok: true, lockFile };
   } catch (err) {
     if (err.code === "EEXIST") {
@@ -433,11 +460,21 @@ export function acquireLock(agentName, taskId, files = [], rootOrOpts = resolveR
         return { ok: false, holder: "unknown", taskId };
       }
     }
+    try { unlinkSync(lockFile); } catch (_) {}
     throw err;
+  } finally {
+    if (fd !== undefined) {
+      try { closeSync(fd); } catch (_) {}
+    }
   }
 }
 
 export function releaseLock(taskId, rootOrOpts = resolveRoot()) {
+  try {
+    assertSafeTaskId(taskId);
+  } catch (_) {
+    return false;
+  }
   const root = typeof rootOrOpts === "string" ? rootOrOpts : resolveRoot();
   const lockDir = getLockDir(root);
   const lockFile = join(lockDir, `${taskId}.json`);

package/src/task-optimizer.mjs

@@ -0,0 +1,306 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { checkScope } from "./security.mjs";
+import { detectStackOracles } from "./wizard-oracle.mjs";
+import { loadConfig } from "./config.mjs";
+
+/**
+ * Calculates Levenshtein distance between two strings.
+ * Zero external dependencies.
+ */
+export function levenshteinDistance(a, b) {
+  if (a === b) return 0;
+  if (!a || a.length === 0) return b ? b.length : 0;
+  if (!b || b.length === 0) return a.length;
+
+  const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    let prev = i;
+    for (let j = 1; j <= b.length; j++) {
+      const val = a[i - 1] === b[j - 1] ? row[j - 1] : Math.min(row[j - 1], prev, row[j]) + 1;
+      row[j - 1] = prev;
+      prev = val;
+    }
+    row[b.length] = prev;
+  }
+  return row[b.length];
+}
+
+/**
+ * Traverses local repository directory to harvest candidate relative file paths.
+ */
+function harvestRepoFiles(dir, maxDepth = 4, currentDepth = 0) {
+  if (currentDepth > maxDepth) return [];
+  const files = [];
+  try {
+    const entries = readdirSync(dir);
+    for (const entry of entries) {
+      if (entry === "node_modules" || entry === ".git" || entry === "dist" || entry === "coverage") continue;
+      const fullPath = join(dir, entry);
+      const relPath = relative(process.cwd(), fullPath).replace(/\\/g, "/");
+      let stat;
+      try { stat = statSync(fullPath); } catch (_) { continue; }
+      if (stat.isDirectory()) {
+        files.push(...harvestRepoFiles(fullPath, maxDepth, currentDepth + 1));
+      } else if (stat.isFile()) {
+        files.push(relPath);
+      }
+    }
+  } catch (_) {}
+  return files;
+}
+
+/**
+ * Extracts potential file/directory path tokens from prompt text.
+ */
+export function extractPathTokens(promptText) {
+  if (!promptText || typeof promptText !== "string") return [];
+  const tokens = [];
+  const words = promptText.split(/\s+/);
+  for (const rawWord of words) {
+    const cleanWord = rawWord.replace(/^[`'"]+|[`'":;,.]+$|\.$/g, "");
+    if (
+      cleanWord.includes("/") &&
+      (cleanWord.includes(".") || cleanWord.startsWith(".github/") || cleanWord.startsWith(".agent/")) &&
+      !cleanWord.startsWith("http://") &&
+      !cleanWord.startsWith("https://")
+    ) {
+      if (!tokens.includes(cleanWord)) {
+        tokens.push(cleanWord);
+      }
+    }
+  }
+  return tokens;
+}
+
+const VAGUE_BUZZWORDS = [
+  { term: "clean up", penalty: 15, msg: "Vague goal: 'clean up' lacks explicit acceptance criteria." },
+  { term: "make faster", penalty: 15, msg: "Vague goal: 'make faster' lacks quantitative benchmark criteria." },
+  { term: "fix bug", penalty: 10, msg: "Vague description: 'fix bug' does not reference specific error code or line." },
+  { term: "refactor", penalty: 10, msg: "Unbounded directive: 'refactor' without boundary limits risks payload blowouts." },
+  { term: "improve", penalty: 10, msg: "Subjective goal: 'improve' is not objectively scoreable." },
+  { term: "better", penalty: 10, msg: "Subjective wording: 'better' lacks falsifiable pass/fail criteria." },
+  { term: "various fixes", penalty: 20, msg: "Unbounded scope: 'various fixes' triggers scope leakage and ring-buffer thrashing." },
+  { term: "update code", penalty: 15, msg: "Generic request: 'update code' does not specify target contract or behavior." }
+];
+
+const TRIVIAL_VERIFY_CMDS = ["true", "echo", ":", "false", "exit 0"];
+
+/**
+ * Scores task prompt falsifiability, scope compliance, path validity, and oracle readiness.
+ */
+export function scorePromptFalsifiability(promptText, options = {}) {
+  const rootDir = options.rootDir || process.cwd();
+  const rawPrompt = (promptText || "").trim();
+  const config = options.config || loadConfig(rootDir);
+
+  let score = 100;
+  const issues = [];
+  const suggestions = [];
+
+  if (!rawPrompt) {
+    return {
+      score: 0,
+      grade: "F",
+      isFalsifiable: false,
+      issues: [{ type: "EMPTY_PROMPT", message: "Task prompt is empty.", penalty: 100 }],
+      suggestions: ["Provide a clear description of the code change requested."],
+      paths: { found: [], missingCount: 0, scopeDeniedCount: 0 },
+      oracle: { command: null, autoDetected: false, isTrivial: false }
+    };
+  }
+
+  // 1. Length & Buzzword Analysis
+  if (rawPrompt.length < 15) {
+    score -= 25;
+    issues.push({ type: "SHORT_PROMPT", message: "Prompt is under 15 characters long.", penalty: 25 });
+    suggestions.push("Expand prompt with context, affected symbols, or expected output behavior.");
+  }
+
+  const promptLower = rawPrompt.toLowerCase();
+  for (const bw of VAGUE_BUZZWORDS) {
+    if (promptLower.includes(bw.term)) {
+      score -= bw.penalty;
+      issues.push({ type: "VAGUE_WORDING", message: bw.msg, penalty: bw.penalty });
+    }
+  }
+
+  // 2. Concrete Evidence Indicators (Bonus/Protection)
+  const hasErrorTrace = /(?:error|exception|fail|failed|stack|traceback|line\s+\d+|exit\s+code)/i.test(rawPrompt);
+  const hasSymbolRef = /(?:`[^`]+`|\b[a-zA-Z0-9_]+\.[a-zA-Z0-9_]+\b|\b[a-zA-Z0-9_]+\(\))/i.test(rawPrompt);
+  const hasExplicitCheck = /(?:verify|assert|should|must|returns?|expect)/i.test(rawPrompt);
+
+  if (hasErrorTrace || hasSymbolRef || hasExplicitCheck) {
+    score = Math.min(100, score + 10);
+  } else {
+    score -= 10;
+    issues.push({ type: "NO_CONCRETE_CRITERIA", message: "Lacks explicit symbol references, test names, or error tracebacks.", penalty: 10 });
+    suggestions.push("Specify exact function names, file paths, or expected test assertions.");
+  }
+
+  // 3. Static Path & Scope Verification
+  const extractedPaths = extractPathTokens(rawPrompt);
+  const repoFiles = harvestRepoFiles(rootDir);
+  const pathResults = [];
+  let missingCount = 0;
+  let scopeDeniedCount = 0;
+
+  for (const token of extractedPaths) {
+    const fullPath = resolve(rootDir, token);
+    const relPath = relative(rootDir, fullPath).replace(/\\/g, "/");
+    const exists = existsSync(fullPath);
+
+    // Check scope policy
+    const scopeCheck = checkScope([relPath], config.scope || {});
+    const scopeDenied = Boolean(scopeCheck.violations && scopeCheck.violations.length > 0);
+    const denialReason = scopeDenied ? scopeCheck.violations[0].reason : null;
+
+    if (scopeDenied) {
+      score -= 30;
+      scopeDeniedCount++;
+      issues.push({ type: "SCOPE_VIOLATION", message: `Referenced path '${relPath}' violates security policy (${denialReason}).`, penalty: 30 });
+    }
+
+    let suggestion;
+    if (!exists && !scopeDenied) {
+      missingCount++;
+      score -= 15;
+      // Fuzzy search closest file
+      let bestDist = Infinity;
+      let bestFile = null;
+      for (const repoFile of repoFiles) {
+        const dist = levenshteinDistance(token, repoFile);
+        if (dist < bestDist && dist <= 4) {
+          bestDist = dist;
+          bestFile = repoFile;
+        }
+      }
+      if (bestFile) {
+        suggestion = bestFile;
+        suggestions.push(`Referenced file '${token}' not found. Did you mean '${bestFile}'?`);
+      } else {
+        suggestions.push(`Referenced file '${token}' does not exist on disk.`);
+      }
+    }
+
+    pathResults.push({
+      token,
+      exists,
+      suggestion,
+      scopeDenied,
+      reason: denialReason
+    });
+  }
+
+  // 4. Stack Oracle Detection
+  let verifyCmd = options.verifyCmd || null;
+  let autoDetected = false;
+  let isTrivial = false;
+
+  if (!verifyCmd) {
+    const detectedOracles = detectStackOracles(rootDir);
+    if (detectedOracles.length > 0 && detectedOracles[0].testCmd) {
+      verifyCmd = detectedOracles[0].testCmd;
+      autoDetected = true;
+    }
+  }
+
+  if (verifyCmd && TRIVIAL_VERIFY_CMDS.includes(verifyCmd.trim())) {
+    isTrivial = true;
+    score -= 25;
+    issues.push({ type: "TRIVIAL_ORACLE", message: `Verification command '${verifyCmd}' is non-evaluable / trivial.`, penalty: 25 });
+    suggestions.push("Use a non-trivial test command like 'npm test', 'pytest', or 'cargo test'.");
+  } else if (!verifyCmd) {
+    score -= 15;
+    issues.push({ type: "MISSING_ORACLE", message: "No automated test or build verification command specified.", penalty: 15 });
+    suggestions.push("Specify a verification command using --verify (e.g. 'npm test').");
+  }
+
+  // Final score clamping & letter grade assignment
+  score = Math.max(0, Math.min(100, Math.round(score)));
+
+  let grade = "F";
+  if (score >= 90) grade = "A+";
+  else if (score >= 80) grade = "A";
+  else if (score >= 70) grade = "B";
+  else if (score >= 60) grade = "C";
+  else if (score >= 50) grade = "D";
+
+  const isFalsifiable = score >= 65 && scopeDeniedCount === 0 && !isTrivial;
+
+  return {
+    score,
+    grade,
+    isFalsifiable,
+    issues,
+    suggestions: [...new Set(suggestions)],
+    paths: {
+      found: pathResults,
+      missingCount,
+      scopeDeniedCount
+    },
+    oracle: {
+      command: verifyCmd,
+      autoDetected,
+      isTrivial
+    }
+  };
+}
+
+/**
+ * Transforms raw prompt into an optimized, structured task envelope.
+ */
+export function optimizeTaskPrompt(promptText, options = {}) {
+  const analysis = scorePromptFalsifiability(promptText, options);
+  const rawPrompt = (promptText || "").trim();
+
+  if (!rawPrompt) {
+    return {
+      optimizedPrompt: "",
+      analysis
+    };
+  }
+
+  let promptBody = rawPrompt;
+
+  // Apply suggestions & path corrections to prompt body if requested
+  for (const pathInfo of analysis.paths.found) {
+    if (!pathInfo.exists && pathInfo.suggestion) {
+      const regex = new RegExp(pathInfo.token.replace(/[-/\\^$*+?.()|[\]{}]/g, "\\$&"), "g");
+      promptBody = promptBody.replace(regex, pathInfo.suggestion);
+    }
+  }
+
+  // Construct structured Markdown envelope
+  const lines = [];
+  lines.push(`# TASK: ${promptBody.split("\n")[0]}`);
+  lines.push("");
+  lines.push("## Objective & Acceptance Criteria");
+  lines.push(`- **Goal**: ${promptBody}`);
+  if (analysis.oracle.command) {
+    lines.push(`- **Verification Command**: \`${analysis.oracle.command}\` (Must pass cleanly with exit code 0)`);
+  }
+  lines.push("- **Falsifiability Criteria**: Zero deleted tests, zero weakened assertions, zero lint errors.");
+  lines.push("");
+
+  if (analysis.paths.found.length > 0) {
+    lines.push("## Primary Target Paths");
+    for (const p of analysis.paths.found) {
+      const pathTarget = p.exists ? p.token : (p.suggestion || p.token);
+      lines.push(`- \`${pathTarget}\` (${p.exists ? "Verified" : "Corrected"})`);
+    }
+    lines.push("");
+  }
+
+  lines.push("## Standard Guardrails");
+  lines.push("- Do NOT modify package.json, lockfiles, or .github/ infrastructure files.");
+  lines.push("- Diff Payload Governor: Keep total diff payload under 75 KB (\`git diff | wc -c\`).");
+  lines.push("- Verify before finishing: Execute full verification command and confirm zero errors.");
+
+  const optimizedPrompt = lines.join("\n");
+
+  return {
+    optimizedPrompt,
+    analysis
+  };
+}

package/src/telemetry.mjs

@@ -7,16 +7,26 @@ import {
   existsSync,
   statSync,
   readdirSync,
+  truncateSync,
 } from "node:fs";
 import { join } from "node:path";
 import { createHash } from "node:crypto";
 import { resolveRoot } from "./config.mjs";
 import { getStateDir, withVfsMutex } from "./state.mjs";
-import { safeAtomicWrite } from "./security.mjs";
+import { safeAtomicWrite, redactSecrets } from "./security.mjs";
 
 export const MAX_TELEMETRY_SEGMENT_BYTES = 8 * 1024 * 1024; // 8 MB log segment ceiling
 export const TELEMETRY_GENESIS_HASH = "0".repeat(64);
 
+function scrubTelemetryValue(value) {
+  if (typeof value === "string") return redactSecrets(value);
+  if (Array.isArray(value)) return value.map(scrubTelemetryValue);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, scrubTelemetryValue(child)]));
+  }
+  return value;
+}
+
 /**
  * Reads up to 64 KB from EOF of target log segment to extract true tail hash.
  */
@@ -48,6 +58,27 @@ function readTailHash(filePath, bufferSize = 64 * 1024) {
   return null;
 }
 
+function discardIncompleteTail(filePath, bufferSize = 64 * 1024) {
+  if (!existsSync(filePath)) return;
+  try {
+    const stat = statSync(filePath);
+    if (stat.size === 0) return;
+    const readSize = Math.min(stat.size, bufferSize);
+    const position = stat.size - readSize;
+    const fd = openSync(filePath, "r");
+    const buf = Buffer.alloc(readSize);
+    try {
+      readSync(fd, buf, 0, readSize, position);
+    } finally {
+      closeSync(fd);
+    }
+    if (buf[buf.length - 1] === 0x0a) return;
+    const lastNewline = buf.lastIndexOf(0x0a);
+    const truncateAt = lastNewline === -1 ? position : position + lastNewline + 1;
+    truncateSync(filePath, truncateAt);
+  } catch (_) {}
+}
+
 /**
  * Returns telemetry file paths for a given date string sorted by segment index.
  */
@@ -132,6 +163,8 @@ export function appendTelemetry(rootOrOpts = resolveRoot(), kind = "event", fiel
         : `telemetry-${dateStr}-${activeSegmentIndex}.jsonl`;
     let activeFilePath = join(stateDir, activeFileName);
 
+    // Discard a torn final JSONL record before reconciling the true tail.
+    discardIncompleteTail(activeFilePath);
     // Reconcile .head hash against true log tail (reading last 64 KB from EOF)
     const tailHash = readTailHash(activeFilePath);
     if (tailHash) {
@@ -162,7 +195,7 @@ export function appendTelemetry(rootOrOpts = resolveRoot(), kind = "event", fiel
     }
 
     const ts = new Date().toISOString();
-    const payloadWithoutHash = { v: 1, ts, kind, ...fields, prevHash };
+    const payloadWithoutHash = { v: 1, ts, kind, ...scrubTelemetryValue(fields), prevHash };
     const hash = createHash("sha256").update(JSON.stringify(payloadWithoutHash)).digest("hex");
     const entry = { ...payloadWithoutHash, hash };
 

package/src/tui.mjs

@@ -41,6 +41,9 @@ export function styleText(text, style) {
   return `${style}${text}${ANSI.reset}`;
 }
 
+import { WizardCancelledError } from "./ux/terminal-session.mjs";
+export { WizardCancelledError };
+
 /**
  * Read keypress in raw mode from TTY input stream.
  * @param {import("node:stream").Readable} stream
@@ -60,7 +63,7 @@ async function* readKeypresses(stream = process.stdin) {
       if (str === "\u0003") {
         // Ctrl+C SIGINT
         process.stdout.write(ANSI.showCursor + "\n");
-        process.exit(130);
+        throw new WizardCancelledError("Wizard operation cancelled by user (SIGINT).");
       }
       yield str;
     }

package/src/ux/capabilities.mjs

@@ -0,0 +1,180 @@
+import { isatty } from "node:tty";
+
+/**
+ * @typedef {Object} TerminalCapabilities
+ * @property {boolean} inputIsTTY
+ * @property {boolean} outputIsTTY
+ * @property {number} columns
+ * @property {number} rows
+ * @property {0 | 4 | 8 | 24} colorDepth
+ * @property {boolean} ansi
+ * @property {boolean} unicode
+ * @property {boolean} alternateScreen
+ * @property {false} mouse
+ * @property {NodeJS.Platform} platform
+ * @property {string} term
+ * @property {boolean} noColor
+ * @property {boolean} forceColor
+ * @property {boolean} reducedMotion
+ */
+
+/**
+ * @typedef {Object} TerminalSessionOptions
+ * @property {import("node:stream").Readable} [input]
+ * @property {import("node:stream").Writable} [output]
+ * @property {import("node:stream").Writable} [errorOutput]
+ * @property {boolean} [jsonMode]
+ * @property {boolean} [alternateScreen]
+ * @property {"auto" | "always" | "never"} [color]
+ * @property {"auto" | "always" | "never"} [unicode]
+ * @property {boolean} [reducedMotion]
+ */
+
+/**
+ * Detect current terminal capabilities based on streams, environment variables, and CLI options.
+ * @param {TerminalSessionOptions} [options]
+ * @returns {TerminalCapabilities}
+ */
+export function detectTerminalCapabilities(options = {}) {
+  const input = options.input || process.stdin;
+  const output = options.output || process.stdout;
+  const env = process.env || {};
+  const argv = process.argv || [];
+
+  const inputIsTTY = Boolean(input && (input.isTTY || (typeof input.fd === "number" && isatty(input.fd))));
+  const outputIsTTY = Boolean(output && (output.isTTY || (typeof output.fd === "number" && isatty(output.fd))));
+
+  const term = String(env.TERM || "").toLowerCase();
+  const colorTerm = String(env.COLORTERM || "").toLowerCase();
+
+  // Environment color flags
+  const envNoColor = Boolean(env.NO_COLOR !== undefined && env.NO_COLOR !== "");
+  let envForceColor = false;
+  let envDisableColor = false;
+
+  if (env.FORCE_COLOR !== undefined) {
+    if (env.FORCE_COLOR === "0" || env.FORCE_COLOR === "false") {
+      envDisableColor = true;
+    } else {
+      envForceColor = true;
+    }
+  }
+
+  // CLI argument overrides
+  const cliNoColor = argv.includes("--no-color");
+  const cliColor = argv.includes("--color");
+  const cliAscii = argv.includes("--ascii");
+  const jsonMode = Boolean(options.jsonMode || argv.includes("--json"));
+
+  const noColor = envNoColor || cliNoColor || options.color === "never";
+  const forceColor = (envForceColor || cliColor || options.color === "always") && !envDisableColor;
+
+  // Priority evaluation for ANSI support:
+  // --no-color / options.color === "never" > NO_COLOR > FORCE_COLOR=0 > jsonMode > --color / FORCE_COLOR > auto TTY capability
+  let ansi = false;
+  if (jsonMode) {
+    ansi = false;
+  } else if (noColor || envDisableColor) {
+    ansi = false;
+  } else if (forceColor) {
+    ansi = true;
+  } else {
+    ansi = outputIsTTY && term !== "dumb";
+  }
+
+  // Color depth calculation
+  /** @type {0 | 4 | 8 | 24} */
+  let colorDepth = 0;
+  if (ansi) {
+    if (colorTerm === "truecolor" || colorTerm === "24bit" || env.FORCE_COLOR === "3") {
+      colorDepth = 24;
+    } else if (term.includes("256color") || colorTerm === "256color" || env.FORCE_COLOR === "2") {
+      colorDepth = 8;
+    } else {
+      colorDepth = 4;
+    }
+  }
+
+  // Unicode support detection
+  let unicode = true;
+  if (cliAscii || options.unicode === "never") {
+    unicode = false;
+  } else if (options.unicode === "always") {
+    unicode = true;
+  } else {
+    const lang = String(env.LANG || env.LC_ALL || env.LC_CTYPE || "").toLowerCase();
+    const isUtf8 = lang.includes("utf-8") || lang.includes("utf8");
+    // Default to true on non-windows or utf-8 windows terminals
+    unicode = isUtf8 || process.platform !== "win32" || Boolean(env.WT_SESSION);
+  }
+
+  // Terminal dimensions
+  const columns = Math.max(10, output.columns || input.columns || process.stdout.columns || 80);
+  const rows = Math.max(5, output.rows || input.rows || process.stdout.rows || 24);
+
+  const reducedMotion = Boolean(
+    options.reducedMotion ||
+    env.REDUCED_MOTION === "1" ||
+    env.REDUCED_MOTION === "true"
+  );
+
+  const alternateScreen = options.alternateScreen !== false && ansi && outputIsTTY;
+
+  return {
+    inputIsTTY,
+    outputIsTTY,
+    columns,
+    rows,
+    colorDepth,
+    ansi,
+    unicode,
+    alternateScreen,
+    mouse: false,
+    platform: process.platform,
+    term: env.TERM || "",
+    noColor,
+    forceColor,
+    reducedMotion,
+  };
+}
+
+/**
+ * Get display symbol set based on unicode capability.
+ * @param {TerminalCapabilities} caps
+ */
+export function getSymbols(caps) {
+  if (caps.unicode) {
+    return {
+      select: "❯",
+      checked: "●",
+      unchecked: "○",
+      success: "✓",
+      warning: "!",
+      failure: "✗",
+      info: "ℹ",
+      bullet: "•",
+      ellipsis: "…",
+      spinner: ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"],
+      branchMiddle: "├─",
+      branchEnd: "└─",
+      arrowUp: "↑",
+      arrowDown: "↓",
+    };
+  }
+  return {
+    select: ">",
+    checked: "[x]",
+    unchecked: "[ ]",
+    success: "OK",
+    warning: "WARN",
+    failure: "ERR",
+    info: "INFO",
+    bullet: "*",
+    ellipsis: "...",
+    spinner: ["-", "\\", "|", "/"],
+    branchMiddle: "+-",
+    branchEnd: "`-",
+    arrowUp: "^",
+    arrowDown: "v",
+  };
+}