ai-maestro 1.0.0

package/src/config.mjs

@@ -0,0 +1,11 @@
+export const CONFIG = {
+  memoryPath: '.memory',
+  maestroPath: '.maestro',
+  codexPath: process.env.MAESTRO_CODEX_PATH || 'codex',
+  npxPath: process.env.MAESTRO_NPX_PATH || 'npx',
+  normalCodexHome: process.env.MAESTRO_NORMAL_CODEX_HOME || 'C:\\Users\\PC\\.codex',
+  codexHome: process.env.MAESTRO_CODEX_HOME || 'C:\\Users\\PC\\.codex-maestro',
+  codexProfile: process.env.MAESTRO_CODEX_PROFILE || '9router',
+  codexStrategy: process.env.MAESTRO_CODEX_STRATEGY || 'auto',
+  codexInvocation: process.env.MAESTRO_CODEX_INVOCATION || 'auto'
+};

package/src/debug.mjs

@@ -0,0 +1,164 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { CONFIG } from './config.mjs';
+import { getCodexEnv, getCodexHome, ensureCodexHome, analyzeIsolatedCodexConfig, getLegacyWorkspacePermissionsConfigPath } from './codex-home.mjs';
+import {
+  resolveCodexInvocation, getCodexHelpMatrix, readValidatedCodexStrategy, resolveRunCodexStrategy,
+  readCodexCompare, resolveCodexInvocationMode, resolveCodexInvocationForMode,
+  buildCodexEnvForInvocation, applyCodexStrategy
+} from './commands.mjs';
+import { pathExists } from './files.mjs';
+
+// Env vars worth showing in doctor/debug output. Anything whose NAME looks
+// like a secret is replaced by '<redacted>' — the VALUE of a key must never
+// reach stdout, logs, or .maestro reports.
+const REPORTED_ENV_KEYS = [
+  'CODEX_HOME', 'NINEROUTER_API_KEY', 'MAESTRO_CODEX_HOME', 'MAESTRO_CODEX_STRATEGY',
+  'MAESTRO_CODEX_INVOCATION', 'MAESTRO_ALLOW_LOCAL_TEST_KEY'
+];
+const SECRET_NAME_PATTERN = /(KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL|AUTH)/i;
+
+export function redactSecretsFromEnv(env = {}) {
+  const report = {};
+  for (const key of REPORTED_ENV_KEYS) {
+    if (env[key] === undefined) {
+      continue;
+    }
+    report[key] = SECRET_NAME_PATTERN.test(key) ? '<redacted>' : String(env[key]);
+  }
+  return report;
+}
+
+function matchToml(content, key) {
+  const match = String(content || '').match(new RegExp('^\\s*' + key + '\\s*=\\s*"([^"]+)"', 'm'));
+  return match ? match[1] : null;
+}
+
+async function readFileSafe(filePath) {
+  try {
+    return await fs.readFile(filePath, 'utf-8');
+  } catch (error) {
+    return '';
+  }
+}
+
+// Resolves what a real worker run would ACTUALLY use right now: which
+// config files, which CODEX_HOME, which strategy/sandbox/provider/model,
+// whether any Desktop plugin/MCP or normal-home reference leaks in, and
+// the final argv (with a placeholder prompt and secrets redacted).
+export async function getEffectiveCodexRuntime() {
+  await ensureCodexHome();
+  const invocationMode = await resolveCodexInvocationMode();
+  const invocation = await resolveCodexInvocationForMode(invocationMode);
+  const env = buildCodexEnvForInvocation(invocation);
+  const strategy = await resolveRunCodexStrategy();
+  const effectiveCodexHome = env.CODEX_HOME || CONFIG.normalCodexHome;
+  const isolatedHome = effectiveCodexHome === CONFIG.codexHome;
+  const configFile = path.join(effectiveCodexHome, 'config.toml');
+  const profileFile = path.join(effectiveCodexHome, CONFIG.codexProfile + '.config.toml');
+  const configContent = await readFileSafe(configFile);
+  const profileContent = await readFileSafe(profileFile);
+  const analysis = analyzeIsolatedCodexConfig(configContent + '\n' + profileContent);
+
+  const templateArgs = ['exec', '--profile', CONFIG.codexProfile, '--sandbox', 'workspace-write', '--skip-git-repo-check', '<prompt>'];
+  const finalArgs = await applyCodexStrategy(templateArgs, strategy);
+  const fullArgs = [...invocation.argsPrefix, ...finalArgs];
+  const sandboxIndex = finalArgs.indexOf('--sandbox');
+  const sandbox = finalArgs.includes('--dangerously-bypass-approvals-and-sandbox')
+    ? 'bypassed (trusted-workspace, explicit opt-in)'
+    : (sandboxIndex >= 0 ? finalArgs[sandboxIndex + 1] : (matchToml(profileContent, 'sandbox_mode') || matchToml(configContent, 'sandbox_mode') || 'unknown'));
+
+  return {
+    invocationMode,
+    command: invocation.command,
+    finalArgs: fullArgs,
+    effectiveCodexHome,
+    isolatedHome,
+    configFile,
+    profileFile,
+    profile: CONFIG.codexProfile,
+    strategy,
+    sandbox,
+    // The --profile layer wins over the base config, so read it first.
+    provider: matchToml(profileContent, 'model_provider') || matchToml(configContent, 'model_provider') || 'unknown',
+    model: matchToml(profileContent, 'model') || matchToml(configContent, 'model') || 'unknown',
+    desktopPluginsEnabled: analysis.desktopPluginsEnabled || analysis.marketplacesConfigured,
+    mcpServersConfigured: analysis.mcpServersConfigured,
+    referencesNormalCodexHome: analysis.referencesNormalCodexHome,
+    windowsSandboxElevated: analysis.windowsSandboxElevated,
+    defaultPermissionsApplied: analysis.usesDefaultPermissions,
+    envReport: redactSecretsFromEnv(env)
+  };
+}
+
+export function formatEffectiveRuntimeLines(runtime) {
+  return [
+    '- Effective config file: ' + runtime.configFile,
+    '- Effective profile layer: ' + runtime.profileFile + ' (via --profile ' + runtime.profile + ')',
+    '- Effective CODEX_HOME: ' + runtime.effectiveCodexHome + (runtime.isolatedHome ? ' (isolated)' : ' (NOT isolated - normal home)'),
+    '- Effective invocation mode: ' + runtime.invocationMode,
+    '- Effective strategy: ' + runtime.strategy,
+    '- Effective sandbox: ' + runtime.sandbox,
+    '- Effective provider: ' + runtime.provider,
+    '- Effective model: ' + runtime.model,
+    '- Desktop plugins/marketplaces enabled: ' + runtime.desktopPluginsEnabled,
+    '- Desktop MCP servers configured: ' + runtime.mcpServersConfigured,
+    '- References normal .codex home: ' + runtime.referencesNormalCodexHome,
+    '- Windows sandbox "elevated" present: ' + runtime.windowsSandboxElevated,
+    '- default_permissions applied: ' + runtime.defaultPermissionsApplied,
+    '- Final invocation (redacted): ' + runtime.command + ' ' + runtime.finalArgs.join(' '),
+    '- Env (redacted): ' + JSON.stringify(runtime.envReport)
+  ];
+}
+
+export async function getCodexDebugInfo() {
+  const ensureResult = await ensureCodexHome();
+  const codexHome = getCodexHome();
+  const codexConfigPath = path.join(codexHome, 'config.toml');
+  const codexProfileConfigPath = path.join(codexHome, '9router.config.toml');
+  const legacyWorkspacePermissionsConfigPath = getLegacyWorkspacePermissionsConfigPath();
+  const invocation = await resolveCodexInvocation();
+  const selectedInvocationMode = await resolveCodexInvocationMode();
+  const selectedInvocation = await resolveCodexInvocationForMode(selectedInvocationMode);
+  const validated = await readValidatedCodexStrategy();
+  const currentStrategy = await resolveRunCodexStrategy();
+  const compare = await readCodexCompare();
+  const effectiveRuntime = await getEffectiveCodexRuntime();
+
+  let helpMatrix;
+  try {
+    helpMatrix = await getCodexHelpMatrix();
+  } catch (error) {
+    helpMatrix = { error: error.message };
+  }
+
+  return {
+    command: invocation.command,
+    argsPrefix: invocation.argsPrefix,
+    source: invocation.source,
+    selectedInvocationMode,
+    selectedCommand: selectedInvocation.command,
+    selectedArgsPrefix: selectedInvocation.argsPrefix,
+    selectedSource: selectedInvocation.source,
+    selectedUsesIsolatedHome: selectedInvocation.usesIsolatedHome,
+    codexHome,
+    profile: CONFIG.codexProfile,
+    currentStrategy,
+    validatedStrategy: validated,
+    lastCompare: compare,
+    codexConfigPath,
+    codexProfileConfigPath,
+    legacyWorkspacePermissionsConfigPath,
+    legacyWorkspacePermissionsConfigExists: await pathExists(legacyWorkspacePermissionsConfigPath),
+    workdir: process.cwd(),
+    is9RouterActive: !!getCodexEnv().NINEROUTER_API_KEY,
+    isolatedConfigExists: await pathExists(codexConfigPath),
+    isolatedProfileConfigExists: await pathExists(codexProfileConfigPath),
+    checks: ensureResult.checks,
+    analysis: ensureResult.analysis,
+    effectiveRuntime,
+    helpMatrix,
+    codexConfigContent: ensureResult.content,
+    codexProfileConfigContent: ensureResult.profileContent
+  };
+}

package/src/encoding-guard.mjs

@@ -0,0 +1,125 @@
+import fs from 'fs/promises';
+
+const BOM_BYTES = [0xef, 0xbb, 0xbf];
+const REPLACEMENT_CHAR = '\uFFFD';
+
+// Classic symptom of UTF-8 bytes misread as Latin-1/Windows-1252 and
+// re-encoded: an accented character like "ã" (UTF-8: 0xC3 0xA3) gets
+// interpreted byte-by-byte as two Latin-1 characters ("Ã" + "£"), which are
+// then valid UTF-8 on their own. The result decodes fine as UTF-8 but reads
+// as garbage. à (U+00C3) and  (U+00C2) are the two first-byte artifacts
+// this project has actually seen (áéíóúçãõ... all start with one of these).
+const MOJIBAKE_BYTE_PATTERN = /[\u00C3\u00C2][\u0080-\u00BF]/;
+
+// Words this project's own docs/prompts use often enough that a corrupted
+// occurrence (accents replaced with "?") is a strong, low-false-positive
+// signal something went wrong. Not exhaustive — a targeted check, not a
+// spellchecker.
+const KNOWN_WORDS = [
+  'ação', 'não', 'execução', 'implementação', 'configuração',
+  'validação', 'documentação', 'está', 'até'
+];
+
+const HAS_ACCENT_CHAR = /[áàâãéêíóôõúçÁÀÂÃÉÊÍÓÔÕÚÇ]/;
+const ACCENT_CHARS_GLOBAL = /[áàâãéêíóôõúçÁÀÂÃÉÊÍÓÔÕÚÇ]/g;
+
+function escapeRegExp(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function buildCorruptedWordPattern(word) {
+  const corrupted = escapeRegExp(word).replace(ACCENT_CHARS_GLOBAL, '\\?');
+  return new RegExp('\\b' + corrupted + '\\b', 'i');
+}
+
+const KNOWN_WORD_PATTERNS = KNOWN_WORDS
+  .filter(word => HAS_ACCENT_CHAR.test(word))
+  .map(word => ({ word, pattern: buildCorruptedWordPattern(word) }));
+
+export function hasBom(buffer) {
+  return buffer.length >= 3 &&
+    buffer[0] === BOM_BYTES[0] &&
+    buffer[1] === BOM_BYTES[1] &&
+    buffer[2] === BOM_BYTES[2];
+}
+
+export function isValidUtf8Buffer(buffer) {
+  try {
+    new TextDecoder('utf-8', { fatal: true }).decode(buffer);
+    return true;
+  } catch (error) {
+    return false;
+  }
+}
+
+export function findMojibakeWords(text) {
+  const found = [];
+  for (const { word, pattern } of KNOWN_WORD_PATTERNS) {
+    if (pattern.test(text)) {
+      found.push(word);
+    }
+  }
+  return found;
+}
+
+export function hasMojibakeBytePattern(text) {
+  return MOJIBAKE_BYTE_PATTERN.test(text);
+}
+
+export function hasReplacementChar(text) {
+  return text.includes(REPLACEMENT_CHAR);
+}
+
+// Pure text-level check — used when the content is already in memory
+// (e.g. right after writing it) and there's no buffer to re-read.
+export function validateUtf8Text(text, options = {}) {
+  const { allowBom = false } = options;
+  const issues = [];
+
+  if (!allowBom && text.startsWith('')) {
+    issues.push('unexpected-bom');
+  }
+  if (hasReplacementChar(text)) {
+    issues.push('replacement-character');
+  }
+  if (hasMojibakeBytePattern(text)) {
+    issues.push('mojibake-byte-pattern');
+  }
+  const corruptedWords = findMojibakeWords(text);
+  if (corruptedWords.length > 0) {
+    issues.push('mojibake-known-words:' + corruptedWords.join(','));
+  }
+
+  return { ok: issues.length === 0, issues };
+}
+
+// File-level check — reads raw bytes so BOM and invalid UTF-8 sequences
+// (which don't survive a lossy 'utf8' decode) can actually be detected.
+export async function validateUtf8File(filePath, options = {}) {
+  const { allowBom = false } = options;
+  const buffer = await fs.readFile(filePath);
+  const issues = [];
+
+  if (!isValidUtf8Buffer(buffer)) {
+    issues.push('invalid-utf8-bytes');
+  }
+
+  const bom = hasBom(buffer);
+  if (bom && !allowBom) {
+    issues.push('unexpected-bom');
+  }
+
+  const text = buffer.toString('utf8');
+  if (hasReplacementChar(text)) {
+    issues.push('replacement-character');
+  }
+  if (hasMojibakeBytePattern(text)) {
+    issues.push('mojibake-byte-pattern');
+  }
+  const corruptedWords = findMojibakeWords(text);
+  if (corruptedWords.length > 0) {
+    issues.push('mojibake-known-words:' + corruptedWords.join(','));
+  }
+
+  return { ok: issues.length === 0, issues, hasBom: bom };
+}

package/src/engines/ai-router-engine.mjs

@@ -0,0 +1,37 @@
+import { execFileRaw } from '../shell.mjs';
+
+export const name = 'ai-router';
+
+function isEnabled() {
+  return process.env.MAESTRO_ENABLE_AI_ROUTER === '1';
+}
+
+// Unvalidated in AI-MAESTRO: reference-only integration, opt-in, never touches C:\AI-Router.
+// See .maestro/TECHNICAL_DEBT.md "AI-Router Future Dependency Limits".
+export async function run(prompt, options = {}) {
+  if (!isEnabled()) {
+    throw new Error('AI-Router engine is opt-in only. Set MAESTRO_ENABLE_AI_ROUTER=1 to use it.');
+  }
+  try {
+    const result = await execFileRaw('ai', ['simples', prompt], { quiet: true, ...options });
+    return { code: result.code, stdout: result.stdout, stderr: result.stderr, strategy: 'ai-router-simples' };
+  } catch (error) {
+    return { code: 1, stdout: '', stderr: error.message, strategy: 'error' };
+  }
+}
+
+export async function describe() {
+  try {
+    const result = await execFileRaw('where.exe', ['ai'], { quiet: true });
+    const available = result.code === 0;
+    return {
+      name,
+      ready: available && isEnabled(),
+      details: (available ? 'ai CLI found on PATH' : 'ai CLI not found on PATH') + (isEnabled() ? '' : '; MAESTRO_ENABLE_AI_ROUTER not set')
+    };
+  } catch (error) {
+    return { name, ready: false, details: 'ai CLI not found: ' + error.message };
+  }
+}
+
+export default { name, run, describe };

package/src/engines/codex-engine.mjs

@@ -0,0 +1,21 @@
+import { CONFIG } from '../config.mjs';
+import { runCodex, resolveRunCodexStrategy } from '../commands.mjs';
+
+export const name = 'codex9';
+
+export async function run(prompt, options = {}) {
+  try {
+    return await runCodex(
+      ['exec', '--profile', CONFIG.codexProfile, '--sandbox', 'workspace-write', '--skip-git-repo-check', prompt],
+      options
+    );
+  } catch (error) {
+    return { code: 1, stdout: '', stderr: error.message, strategy: await resolveRunCodexStrategy() };
+  }
+}
+
+export async function describe() {
+  return { name, ready: true, details: 'Codex CLI via 9Router (profile ' + CONFIG.codexProfile + '), invocation resolved at run time.' };
+}
+
+export default { name, run, describe };

package/src/engines/engine.mjs

@@ -0,0 +1,21 @@
+/**
+ * @typedef {Object} EngineResult
+ * @property {number} code
+ * @property {string} stdout
+ * @property {string} stderr
+ * @property {string} strategy
+ */
+
+/**
+ * @typedef {Object} EngineDescription
+ * @property {string} name
+ * @property {boolean} ready
+ * @property {string} details
+ */
+
+/**
+ * Engine contract every worker backend must satisfy:
+ * - name: string
+ * - run(prompt, options) => Promise<EngineResult>
+ * - describe() => Promise<EngineDescription>   (non-mutating; used by `maestro doctor`)
+ */

package/src/engines/registry.mjs

@@ -0,0 +1,29 @@
+import codexEngine from './codex-engine.mjs';
+import aiRouterEngine from './ai-router-engine.mjs';
+
+const engines = {
+  [codexEngine.name]: codexEngine,
+  [aiRouterEngine.name]: aiRouterEngine
+};
+
+// Planning-time labels from the smart planner (src/smart-planner.mjs's
+// inferEngine) that describe what a task is about but are not distinct
+// runnable backends. Route them to the real default worker instead of
+// crashing at run-task time.
+const ENGINE_ALIASES = {
+  memory: codexEngine.name,
+  'premium-review': codexEngine.name
+};
+
+export function getEngine(name = 'codex9') {
+  const key = name || 'codex9';
+  const engine = engines[key] || engines[ENGINE_ALIASES[key]];
+  if (!engine) {
+    throw new Error('Unknown engine "' + key + '". Available engines: ' + Object.keys(engines).join(', '));
+  }
+  return engine;
+}
+
+export function listEngines() {
+  return Object.keys(engines);
+}

package/src/files.mjs

@@ -0,0 +1,65 @@
+import fs from 'fs/promises';
+import path from 'path';
+
+export async function pathExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch (error) {
+    return false;
+  }
+}
+
+// Explicit `{ encoding: 'utf8' }` writes, used by every text file this
+// project generates (worker-policy.md, CHECKPOINT.md, PLAN.md, HANDOFF.md,
+// ...). Node's fs.writeFile already defaults a string write to utf8 with no
+// BOM, but the corruption this guards against comes from PowerShell
+// (`Set-Content -Encoding UTF8`, which does write a BOM) — being explicit
+// here documents the intent and gives every caller one place to fix if that
+// ever changes.
+export async function writeUtf8TextFile(filePath, content) {
+  await fs.writeFile(filePath, content, { encoding: 'utf8' });
+}
+
+export async function appendUtf8TextFile(filePath, content) {
+  await fs.appendFile(filePath, content, { encoding: 'utf8' });
+}
+
+export async function writeTextWithBackup(filePath, content) {
+  if (await pathExists(filePath)) {
+    const backupPath = filePath + '.bak';
+    await fs.copyFile(filePath, backupPath);
+  } else {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+  }
+  await writeUtf8TextFile(filePath, content);
+}
+
+export async function writeJsonWithBackup(filePath, value) {
+  await writeTextWithBackup(filePath, JSON.stringify(value, null, 2));
+}
+
+const BOM = String.fromCharCode(0xfeff);
+
+// PowerShell's `Set-Content -Encoding UTF8` writes a BOM by default, and
+// workers routinely use that to write files. Strip it so downstream
+// JSON.parse calls don't choke on a byte that's invisible in most editors.
+export function stripBom(text) {
+  return text.startsWith(BOM) ? text.slice(BOM.length) : text;
+}
+
+export async function readJsonSafe(filePath, fallback) {
+  try {
+    const content = await fs.readFile(filePath, 'utf-8');
+    return JSON.parse(stripBom(content));
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return fallback;
+    }
+    if (error instanceof SyntaxError) {
+      const diagnosticPath = filePath + '.diagnostic.txt';
+      await fs.writeFile(diagnosticPath, 'Invalid JSON in ' + filePath + ': ' + error.message + '\n');
+    }
+    throw error;
+  }
+}

package/src/format.mjs

@@ -0,0 +1,132 @@
+const BOM_CHAR = String.fromCharCode(0xfeff);
+const NULL_CHAR = String.fromCharCode(0);
+
+export function summarizeText(text, limit = 900) {
+  const value = (text || '').replace(/\s+/g, ' ').trim();
+  return value.length > limit ? value.slice(0, limit) + '...' : value;
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function sensitiveEnvValues(env = process.env) {
+  const sensitiveKey = /(NINEROUTER_API_KEY|API[_-]?KEY|TOKEN|PASSWORD|PASSWD|SECRET|AUTH|COOKIE|CREDENTIAL)/i;
+  return Object.entries(env)
+    .filter(([key, value]) => sensitiveKey.test(key) && typeof value === 'string' && value.length >= 8)
+    .map(([, value]) => value)
+    .filter(value => !/^(true|false|null|undefined)$/i.test(value));
+}
+
+export function redactCredentials(input, options = {}) {
+  if (input === null || input === undefined) {
+    return '';
+  }
+  let text = typeof input === 'string' ? input : JSON.stringify(input, null, 2);
+  const marker = '[REDACTED]';
+
+  for (const value of sensitiveEnvValues(options.env || process.env)) {
+    text = text.replace(new RegExp(escapeRegExp(value), 'g'), marker);
+  }
+
+  text = text.replace(/(https?:\/\/)([^\/\s:@]+):([^@\s\/]+)@/gi, '$1' + marker + '@');
+  text = text.replace(/\bsk-[A-Za-z0-9_-]{8,}\b/g, marker);
+  text = text.replace(/\bnr-[A-Za-z0-9_-]{8,}\b/g, marker);
+  text = text.replace(/\b(Authorization\s*:\s*(?:Bearer|Basic)\s+)[^\r\n,}]+/gi, '$1' + marker);
+  text = text.replace(/\b(Set-Cookie|Cookie)\s*:\s*[^\r\n]+/gi, '$1: ' + marker);
+  text = text.replace(/("(?:[^"]*(?:authorization|cookie|password|passwd|api[_-]?key|token|secret|credential|NINEROUTER_API_KEY)[^"]*)"\s*:\s*)"[^"]*"/gi, '$1"' + marker + '"');
+  text = text.replace(/('(?:[^']*(?:authorization|cookie|password|passwd|api[_-]?key|token|secret|credential|NINEROUTER_API_KEY)[^']*)'\s*:\s*)'[^']*'/gi, '$1\'' + marker + '\'');
+  text = text.replace(/\b(NINEROUTER_API_KEY|password|passwd|api[_-]?key|token|secret|credential)\s*=\s*("[^"]*"|'[^']*'|[^\s&;,]+)/gi, '$1=' + marker);
+  text = text.replace(/\b(NINEROUTER_API_KEY|password|passwd|api[_-]?key|token|secret|credential)\s*:\s*("[^"]*"|'[^']*'|[^\s,;}]+)/gi, '$1: ' + marker);
+
+  return text;
+}
+
+export function redactObject(value, options = {}) {
+  if (Array.isArray(value)) {
+    return value.map(item => redactObject(item, options));
+  }
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, redactObject(item, options)]));
+  }
+  if (typeof value === 'string') {
+    return redactCredentials(value, options);
+  }
+  return value;
+}
+
+export function truncatePreview(text, { maxLines = 100, maxBytes = 8192 } = {}) {
+  const value = String(text || '');
+  const lines = value.split(/\r?\n/);
+  let truncatedByLines = false;
+  let preview = value;
+  if (lines.length > maxLines) {
+    truncatedByLines = true;
+    preview = lines.slice(0, maxLines).join('\n');
+  }
+  let truncatedByBytes = false;
+  const bytes = Buffer.from(preview, 'utf8');
+  if (bytes.length > maxBytes) {
+    truncatedByBytes = true;
+    preview = bytes.subarray(0, maxBytes).toString('utf8');
+  }
+  const originalBytes = Buffer.byteLength(value, 'utf8');
+  const previewBytes = Buffer.byteLength(preview, 'utf8');
+  return {
+    text: preview,
+    truncated: truncatedByLines || truncatedByBytes || previewBytes < originalBytes,
+    originalLines: lines.length,
+    shownLines: preview ? preview.split(/\r?\n/).length : 0,
+    originalBytes,
+    shownBytes: previewBytes,
+    truncatedLines: Math.max(0, lines.length - (preview ? preview.split(/\r?\n/).length : 0)),
+    truncatedBytes: Math.max(0, originalBytes - previewBytes)
+  };
+}
+
+export function formatPreview(text, {
+  maxLines = 100,
+  maxBytes = 8192,
+  runId,
+  kind = 'saida'
+} = {}) {
+  const redacted = redactCredentials(text);
+  const preview = truncatePreview(redacted, { maxLines, maxBytes });
+  const lines = [preview.text];
+  if (preview.truncated) {
+    lines.push('[saída truncada — consulte maestro run-log ' + (runId || '<run-id>') + ']');
+  }
+  return {
+    ...preview,
+    text: lines.filter(Boolean).join('\n'),
+    kind
+  };
+}
+
+function stripBom(text) {
+  return text.startsWith(BOM_CHAR) ? text.slice(BOM_CHAR.length) : text;
+}
+
+export function normalizeReadContent(buffer) {
+  if (buffer.length >= 2 && buffer[0] === 0xff && buffer[1] === 0xfe) {
+    return stripBom(buffer.toString('utf16le'));
+  }
+  if (buffer.length >= 2 && buffer[0] === 0xfe && buffer[1] === 0xff) {
+    return stripBom(buffer.swap16().toString('utf16le'));
+  }
+  const text = buffer.toString('utf-8');
+  if (text.indexOf(NULL_CHAR) !== -1) {
+    return stripBom(buffer.toString('utf16le'));
+  }
+  return stripBom(text);
+}
+
+export function detectField(output, name) {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const match = output.match(new RegExp(escaped + ':\\s*([^\\r\\n]+)', 'i'));
+  return match ? match[1].trim() : null;
+}
+
+export function doctorLine(status, name, value, fix) {
+  console.log(redactCredentials(status + ': ' + name + ': ' + value + (fix ? ' (Fix: ' + fix + ')' : '')));
+}