ai-maestro 1.0.0

package/src/orchestration/rc-check.mjs

@@ -0,0 +1,544 @@
+import crypto from 'crypto';
+import fs from 'fs/promises';
+import path from 'path';
+
+import { redactCredentials, redactObject, truncatePreview } from '../format.mjs';
+import { loadRcPolicy, hashPolicyInfo } from './rc-policy.mjs';
+import { createRcCheckAdapters } from './rc-check-adapters.mjs';
+
+export const RC_CHECK_SCHEMA_VERSION = 1;
+
+export const RC_CLASSIFICATIONS = Object.freeze({
+  READY: 'RC_READY',
+  READY_WITH_INFRA_WARNING: 'RC_READY_WITH_INFRA_WARNING',
+  NEEDS_HUMAN: 'RC_NEEDS_HUMAN',
+  BLOCKED: 'RC_BLOCKED'
+});
+
+export const RC_EXIT_CODES = Object.freeze({
+  RC_READY: 0,
+  RC_READY_WITH_INFRA_WARNING: 0,
+  RC_BLOCKED: 1,
+  RC_NEEDS_HUMAN: 2
+});
+
+export const USAGE_ERROR_EXIT_CODE = 64;
+export const INTERNAL_ERROR_EXIT_CODE = 70;
+
+export const CHECK_STATUSES = Object.freeze(['PASS', 'FAIL', 'WARNING', 'NEEDS_HUMAN', 'SKIPPED', 'TIMEOUT']);
+export const CHECK_SEVERITIES = Object.freeze(['INFO', 'INFRA_WARNING', 'HUMAN', 'BLOCKER']);
+export const CHECK_CATEGORIES = Object.freeze([
+  'code',
+  'git',
+  'schema',
+  'health',
+  'provider',
+  'circuit',
+  'fallback',
+  'lock',
+  'process',
+  'temp',
+  'credential',
+  'canary',
+  'report',
+  'config',
+  'test',
+  'release'
+]);
+export const SIDE_EFFECT_CLASSES = Object.freeze([
+  'PURE_READ_ONLY',
+  'READ_ONLY_WITH_DIAGNOSTIC_OUTPUT',
+  'TEMPORARY_SANDBOX_WRITE',
+  'PROJECT_CONTROL_PLANE_WRITE',
+  'NETWORK_OBSERVATION',
+  'REAL_ENGINE_EXECUTION',
+  'NOT_ALLOWED_IN_RC_CHECK'
+]);
+
+export const DEFAULT_CHECK_TIMEOUTS_MS = Object.freeze({
+  policy: 5000,
+  'git-state': 10000,
+  'engine-config': 10000,
+  'budget-config': 10000,
+  'safety-config': 10000,
+  'schema-check': 30000,
+  'provider-health': 10000,
+  'credential-audit': 60000,
+  'temp-files': 30000,
+  'lock-observation': 30000,
+  'process-observation': 30000,
+  'fallback-chain-state': 30000,
+  'npm-run-check': 120000,
+  'npm-test': 600000,
+  readiness: 300000,
+  doctor: 120000,
+  canary: 180000
+});
+
+function durationSince(startedAt) {
+  return Math.max(0, Date.now() - startedAt);
+}
+
+function safeEvidence(evidence) {
+  if (!Array.isArray(evidence)) return [];
+  return evidence.map(item => redactObject({
+    kind: typeof item.kind === 'string' ? item.kind : 'note',
+    path: typeof item.path === 'string' ? item.path : null,
+    line: Number.isInteger(item.line) ? item.line : null,
+    identifier: typeof item.identifier === 'string' ? item.identifier : null,
+    redacted: item.redacted !== false,
+    details: typeof item.details === 'string' ? item.details : ''
+  }));
+}
+
+export function makeCheckResult(input = {}) {
+  return redactObject({
+    schemaVersion: RC_CHECK_SCHEMA_VERSION,
+    checkId: String(input.checkId || 'unknown'),
+    category: input.category || 'code',
+    status: input.status || 'NEEDS_HUMAN',
+    severity: input.severity || severityForStatus(input.status || 'NEEDS_HUMAN', input.required !== false),
+    required: input.required !== false,
+    executed: input.executed !== false,
+    skipped: input.skipped === true,
+    skipReason: input.skipReason == null ? null : String(input.skipReason),
+    durationMs: Number.isFinite(input.durationMs) ? Math.max(0, Math.round(input.durationMs)) : 0,
+    timeoutMs: Number.isFinite(input.timeoutMs) ? Math.max(0, Math.round(input.timeoutMs)) : 0,
+    exitCode: input.exitCode == null ? null : input.exitCode,
+    summary: redactCredentials(String(input.summary || '')),
+    evidence: safeEvidence(input.evidence),
+    sideEffectClass: input.sideEffectClass || 'PURE_READ_ONLY',
+    remediation: input.remediation == null ? null : redactCredentials(String(input.remediation))
+  });
+}
+
+export function severityForStatus(status, required = true) {
+  if (status === 'FAIL' || (status === 'TIMEOUT' && required)) return 'BLOCKER';
+  if (status === 'NEEDS_HUMAN') return 'HUMAN';
+  if (status === 'WARNING' || status === 'TIMEOUT') return 'INFRA_WARNING';
+  return 'INFO';
+}
+
+export function validateCheckResult(value) {
+  const errors = [];
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return { ok: false, errors: ['result must be an object'] };
+  }
+  if (value.schemaVersion !== RC_CHECK_SCHEMA_VERSION) errors.push('schemaVersion must be 1');
+  if (typeof value.checkId !== 'string' || value.checkId.length === 0) errors.push('checkId must be a non-empty string');
+  if (!CHECK_CATEGORIES.includes(value.category)) errors.push('category is invalid');
+  if (!CHECK_STATUSES.includes(value.status)) errors.push('status is invalid');
+  if (!CHECK_SEVERITIES.includes(value.severity)) errors.push('severity is invalid');
+  if (typeof value.required !== 'boolean') errors.push('required must be boolean');
+  if (typeof value.executed !== 'boolean') errors.push('executed must be boolean');
+  if (typeof value.skipped !== 'boolean') errors.push('skipped must be boolean');
+  if (typeof value.durationMs !== 'number') errors.push('durationMs must be number');
+  if (typeof value.timeoutMs !== 'number') errors.push('timeoutMs must be number');
+  if (typeof value.summary !== 'string') errors.push('summary must be string');
+  if (!Array.isArray(value.evidence)) errors.push('evidence must be array');
+  if (!SIDE_EFFECT_CLASSES.includes(value.sideEffectClass)) errors.push('sideEffectClass is invalid');
+  return { ok: errors.length === 0, errors };
+}
+
+export function invalidResult(checkId, errors, input = {}) {
+  return makeCheckResult({
+    checkId,
+    category: input.category || 'code',
+    status: 'FAIL',
+    severity: 'BLOCKER',
+    required: input.required !== false,
+    durationMs: input.durationMs || 0,
+    timeoutMs: input.timeoutMs || 0,
+    summary: 'Invalid check result schema',
+    evidence: [{ kind: 'schema', details: errors.join('; ') }],
+    sideEffectClass: input.sideEffectClass || 'PURE_READ_ONLY',
+    remediation: 'Fix the rc-check adapter contract before release.'
+  });
+}
+
+function summarizeChecks(checks) {
+  const summary = { passed: 0, warnings: 0, needsHuman: 0, blocked: 0, skipped: 0 };
+  for (const check of checks) {
+    if (check.skipped || check.status === 'SKIPPED') summary.skipped += 1;
+    if (check.status === 'PASS') summary.passed += 1;
+    if (check.severity === 'INFRA_WARNING' || check.status === 'WARNING') summary.warnings += 1;
+    if (check.severity === 'HUMAN' || check.status === 'NEEDS_HUMAN') summary.needsHuman += 1;
+    if (check.severity === 'BLOCKER' || check.status === 'FAIL' || (check.status === 'TIMEOUT' && check.required)) summary.blocked += 1;
+  }
+  return summary;
+}
+
+export function classifyReleaseCandidate(input = {}) {
+  const policyInfo = input.policy || { valid: true, errors: [], policy: {} };
+  const normalizedChecks = [];
+  for (const raw of input.checks || []) {
+    const result = makeCheckResult(raw);
+    const validation = validateCheckResult(result);
+    normalizedChecks.push(validation.ok ? result : invalidResult(result.checkId, validation.errors, result));
+  }
+  if (policyInfo.valid === false) {
+    normalizedChecks.unshift(makeCheckResult({
+      checkId: 'rc-policy',
+      category: 'config',
+      status: 'NEEDS_HUMAN',
+      severity: 'HUMAN',
+      required: true,
+      summary: 'RC policy is invalid',
+      evidence: (policyInfo.errors || []).map(error => ({ kind: 'policy', details: error })),
+      remediation: 'Fix .maestro/rc-policy.json or remove it to use safe defaults.'
+    }));
+  }
+
+  let classification = RC_CLASSIFICATIONS.READY;
+  if (normalizedChecks.some(check => check.severity === 'BLOCKER' || check.status === 'FAIL' || (check.status === 'TIMEOUT' && check.required))) {
+    classification = RC_CLASSIFICATIONS.BLOCKED;
+  } else if (normalizedChecks.some(check => check.severity === 'HUMAN' || check.status === 'NEEDS_HUMAN')) {
+    classification = RC_CLASSIFICATIONS.NEEDS_HUMAN;
+  } else if (normalizedChecks.some(check => check.severity === 'INFRA_WARNING' || check.status === 'WARNING' || (!check.required && check.status === 'TIMEOUT'))) {
+    classification = RC_CLASSIFICATIONS.READY_WITH_INFRA_WARNING;
+  }
+
+  const strict = input.strict === true || (policyInfo.policy && policyInfo.policy.strictGitState === true);
+  const allowInfraWarning = policyInfo.policy ? policyInfo.policy.allowInfraWarning !== false : true;
+  if (strict && classification === RC_CLASSIFICATIONS.READY_WITH_INFRA_WARNING && allowInfraWarning === false) {
+    classification = RC_CLASSIFICATIONS.BLOCKED;
+  }
+
+  return {
+    classification,
+    exitCode: RC_EXIT_CODES[classification],
+    summary: summarizeChecks(normalizedChecks),
+    checks: normalizedChecks
+  };
+}
+
+function shouldRunAdapter(adapter, policy, options) {
+  const required = (policy.requiredChecks || []).includes(adapter.checkId) || adapter.defaultRequired === true;
+  if ((policy.skippedChecks || []).includes(adapter.checkId) && !(policy.requiredChecks || []).includes(adapter.checkId)) {
+    return { run: false, required: false, reason: 'skipped by policy' };
+  }
+  if (adapter.checkId === 'canary') {
+    const run = options.includeCanary === true || policy.canaryRequired === true;
+    return { run, required: policy.canaryRequired === true, reason: run ? null : 'canary is opt-in' };
+  }
+  if (adapter.checkId === 'readiness' || adapter.checkId === 'doctor') {
+    const run = options.strict === true && (policy.strictExtraChecks || []).includes(adapter.checkId);
+    return { run, required: false, reason: run ? null : 'strictExtraChecks did not request ' + adapter.checkId };
+  }
+  if (adapter.sideEffectClass === 'NOT_ALLOWED_IN_RC_CHECK') {
+    return { run: false, required: false, reason: 'NOT_ALLOWED_IN_RC_CHECK' };
+  }
+  if (adapter.canRunByDefault === false) {
+    return { run: false, required, reason: 'adapter is not allowed by default' };
+  }
+  return { run: true, required, reason: null };
+}
+
+async function runAdapterWithTimeout(adapter, context, timeoutMs, required) {
+  const startedAt = Date.now();
+  let timeout = null;
+  try {
+    const timeoutPromise = new Promise(resolve => {
+      timeout = setTimeout(() => {
+        resolve(makeCheckResult({
+          checkId: adapter.checkId,
+          category: adapter.category,
+          status: 'TIMEOUT',
+          severity: required ? 'BLOCKER' : 'INFRA_WARNING',
+          required,
+          durationMs: durationSince(startedAt),
+          timeoutMs,
+          exitCode: 124,
+          summary: adapter.checkId + ' timed out after ' + timeoutMs + 'ms',
+          evidence: [{ kind: 'timeout', details: 'Timeout limits only subprocesses started by rc-check when the adapter starts a subprocess; no kill-tree is promised.' }],
+          sideEffectClass: adapter.sideEffectClass,
+          remediation: required ? 'Run the check manually and investigate the timeout.' : 'Review optional timeout evidence.'
+        }));
+      }, timeoutMs);
+    });
+    const result = await Promise.race([
+      adapter.run({ ...context, timeoutMs, required, startedAt }),
+      timeoutPromise
+    ]);
+    return makeCheckResult({
+      ...result,
+      required,
+      durationMs: result.durationMs == null ? durationSince(startedAt) : result.durationMs,
+      timeoutMs,
+      sideEffectClass: result.sideEffectClass || adapter.sideEffectClass
+    });
+  } catch (error) {
+    return makeCheckResult({
+      checkId: adapter.checkId,
+      category: adapter.category,
+      status: required ? 'FAIL' : 'NEEDS_HUMAN',
+      severity: required ? 'BLOCKER' : 'HUMAN',
+      required,
+      durationMs: durationSince(startedAt),
+      timeoutMs,
+      summary: adapter.checkId + ' failed unexpectedly',
+      evidence: [{ kind: 'exception', details: error.message || String(error) }],
+      sideEffectClass: adapter.sideEffectClass,
+      remediation: 'Investigate the adapter exception.'
+    });
+  } finally {
+    if (timeout) clearTimeout(timeout);
+  }
+}
+
+function normalizeSideEffects(checks) {
+  const seen = new Set();
+  const effects = [];
+  for (const check of checks) {
+    if (check.executed && !check.skipped && !seen.has(check.sideEffectClass)) {
+      seen.add(check.sideEffectClass);
+      effects.push(check.sideEffectClass);
+    }
+  }
+  return effects;
+}
+
+function canarySummary(checks, policy, options) {
+  const check = checks.find(item => item.checkId === 'canary');
+  return {
+    required: policy.canaryRequired === true,
+    executed: !!(check && check.executed && !check.skipped),
+    reused: false,
+    outcome: check && check.executed && !check.skipped ? check.status : null,
+    correlatedHead: !!(check && check.evidence.some(evidence => evidence.identifier === 'head-correlated')),
+    optIn: options.includeCanary === true
+  };
+}
+
+export async function runRcCheck(options = {}) {
+  const startedAt = Date.now();
+  const projectRoot = options.projectRoot || process.cwd();
+  const clock = options.clock || (() => new Date());
+  const policyInfo = options.policyInfo || await (options.loadPolicy || loadRcPolicy)({ projectRoot });
+  const policy = policyInfo.policy;
+  const adapters = options.adapters || createRcCheckAdapters(options.dependencies || {});
+  const context = {
+    projectRoot,
+    policy,
+    policyInfo,
+    strict: options.strict === true,
+    includeCanary: options.includeCanary === true,
+    head: options.head || null,
+    branch: options.branch || null,
+    dependencies: options.dependencies || {}
+  };
+  const checks = [];
+  for (const adapter of adapters) {
+    const decision = shouldRunAdapter(adapter, policy, options);
+    const timeoutMs = policy.timeouts && policy.timeouts[adapter.checkId]
+      ? policy.timeouts[adapter.checkId]
+      : (adapter.defaultTimeoutMs || DEFAULT_CHECK_TIMEOUTS_MS[adapter.checkId] || 30000);
+    if (!decision.run) {
+      checks.push(makeCheckResult({
+        checkId: adapter.checkId,
+        category: adapter.category,
+        status: 'SKIPPED',
+        severity: 'INFO',
+        required: decision.required,
+        executed: false,
+        skipped: true,
+        skipReason: decision.reason,
+        timeoutMs,
+        summary: decision.reason,
+        sideEffectClass: adapter.sideEffectClass
+      }));
+      continue;
+    }
+    const check = await runAdapterWithTimeout(adapter, context, timeoutMs, decision.required);
+    checks.push(check);
+    if (check.checkId === 'git-state') {
+      context.head = check.evidence.find(item => item.identifier === 'head')?.details || context.head;
+      context.branch = check.evidence.find(item => item.identifier === 'branch')?.details || context.branch;
+    }
+  }
+
+  const classified = classifyReleaseCandidate({ checks, policy: policyInfo, strict: options.strict === true });
+  const gitCheck = classified.checks.find(check => check.checkId === 'git-state');
+  const head = options.head || (gitCheck && gitCheck.evidence.find(item => item.identifier === 'head')?.details) || null;
+  const branch = options.branch || (gitCheck && gitCheck.evidence.find(item => item.identifier === 'branch')?.details) || null;
+  const result = redactObject({
+    schemaVersion: RC_CHECK_SCHEMA_VERSION,
+    command: 'rc-check',
+    generatedAt: clock().toISOString(),
+    projectRoot,
+    head,
+    branch,
+    classification: classified.classification,
+    exitCode: classified.exitCode,
+    policy: {
+      source: policyInfo.source,
+      path: policyInfo.path || null,
+      valid: policyInfo.valid !== false,
+      hash: policyInfo.hash || null,
+      defaultsApplied: policyInfo.defaultsApplied === true,
+      errors: policyInfo.errors || []
+    },
+    summary: classified.summary,
+    checks: classified.checks,
+    sideEffects: normalizeSideEffects(classified.checks),
+    canary: canarySummary(classified.checks, policy, options),
+    reportPath: null,
+    durationMs: durationSince(startedAt)
+  });
+
+  const reportPath = options.reportPath || (policy.reportOutput && policy.reportOutput.enabled ? policy.reportOutput.path : null);
+  if (reportPath) {
+    const report = await writeMarkdownReport(result, reportPath, { projectRoot });
+    result.reportPath = report.path;
+    result.report = report;
+  }
+  return result;
+}
+
+function listBySeverity(result, severity) {
+  return result.checks
+    .filter(check => check.severity === severity || (severity === 'INFRA_WARNING' && check.status === 'WARNING'))
+    .map(check => '- ' + check.checkId + ': ' + check.summary + (check.remediation ? ' | remediation: ' + check.remediation : ''));
+}
+
+export function renderHumanRcCheck(result) {
+  const lines = [];
+  lines.push('AI-MAESTRO rc-check');
+  lines.push('Classification: ' + result.classification);
+  lines.push('Exit code: ' + result.exitCode);
+  lines.push('HEAD: ' + (result.head || 'unknown'));
+  lines.push('Branch: ' + (result.branch || 'unknown'));
+  lines.push('Policy source: ' + result.policy.source + (result.policy.path ? ' (' + result.policy.path + ')' : ''));
+  lines.push('');
+  lines.push('Checks:');
+  for (const check of result.checks) {
+    lines.push('- ' + check.checkId + ' [' + check.status + '/' + check.severity + '] ' + check.summary);
+  }
+  const warnings = listBySeverity(result, 'INFRA_WARNING');
+  const blockers = listBySeverity(result, 'BLOCKER');
+  const human = listBySeverity(result, 'HUMAN');
+  lines.push('');
+  lines.push('Summary: passed=' + result.summary.passed + ' warnings=' + result.summary.warnings + ' needsHuman=' + result.summary.needsHuman + ' blocked=' + result.summary.blocked + ' skipped=' + result.summary.skipped);
+  lines.push('Warnings:');
+  lines.push(...(warnings.length ? warnings : ['- none']));
+  lines.push('Blockers:');
+  lines.push(...(blockers.length ? blockers : ['- none']));
+  lines.push('Human review needed:');
+  lines.push(...(human.length ? human : ['- none']));
+  lines.push('Canary: required=' + result.canary.required + ' executed=' + result.canary.executed + ' optIn=' + result.canary.optIn);
+  lines.push('Report: ' + (result.reportPath || 'not written'));
+  return redactCredentials(lines.join('\n') + '\n');
+}
+
+export function renderJsonRcCheck(result) {
+  return redactCredentials(JSON.stringify(redactObject(result), null, 2) + '\n');
+}
+
+function atomicSuffix(targetPath) {
+  const digest = crypto.createHash('sha256').update(targetPath + String(Date.now()) + String(process.pid)).digest('hex').slice(0, 12);
+  return targetPath + '.tmp-' + process.pid + '-' + digest;
+}
+
+export function renderMarkdownReport(result) {
+  const policyHash = result.policy.hash || hashPolicyInfo({ policy: result.policy });
+  const lines = [];
+  lines.push('# AI-MAESTRO RC Check');
+  lines.push('');
+  lines.push('- Generated at: ' + result.generatedAt);
+  lines.push('- HEAD: ' + (result.head || 'unknown'));
+  lines.push('- Branch: ' + (result.branch || 'unknown'));
+  lines.push('- Policy source: ' + result.policy.source);
+  lines.push('- Policy hash: ' + policyHash);
+  lines.push('- Classification: ' + result.classification);
+  lines.push('- Exit code: ' + result.exitCode);
+  lines.push('');
+  lines.push('## Checks');
+  for (const check of result.checks) {
+    lines.push('- ' + check.checkId + ': ' + check.status + '/' + check.severity + ' - ' + check.summary);
+    for (const evidence of check.evidence || []) {
+      lines.push('  - evidence: ' + [evidence.kind, evidence.path, evidence.line, evidence.identifier, evidence.details].filter(Boolean).join(' | '));
+    }
+    if (check.remediation) lines.push('  - remediation: ' + check.remediation);
+  }
+  lines.push('');
+  lines.push('## Canary');
+  lines.push('- Required: ' + result.canary.required);
+  lines.push('- Executed: ' + result.canary.executed);
+  lines.push('- Correlated HEAD: ' + result.canary.correlatedHead);
+  lines.push('');
+  lines.push('## Side Effects');
+  for (const item of result.sideEffects || []) lines.push('- ' + item);
+  return redactCredentials(lines.join('\n') + '\n');
+}
+
+export async function writeMarkdownReport(result, targetPath, options = {}) {
+  const projectRoot = options.projectRoot || process.cwd();
+  const resolved = path.resolve(projectRoot, targetPath);
+  const exists = await fs.access(resolved).then(() => true, () => false);
+  if (exists && options.overwrite !== true) {
+    const error = new Error('report path already exists: ' + resolved);
+    error.code = 'EEXIST';
+    throw error;
+  }
+  const markdown = renderMarkdownReport(result);
+  await fs.mkdir(path.dirname(resolved), { recursive: true });
+  const tempPath = atomicSuffix(resolved);
+  await fs.writeFile(tempPath, markdown, 'utf-8');
+  await fs.rename(tempPath, resolved);
+  const bytes = Buffer.byteLength(markdown, 'utf8');
+  return { path: resolved, bytes, redacted: true, atomic: true };
+}
+
+export function parseRcCheckArgs(args = []) {
+  const options = { json: false, strict: false, includeCanary: false, reportPath: null };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--json') options.json = true;
+    else if (arg === '--strict') options.strict = true;
+    else if (arg === '--include-canary') options.includeCanary = true;
+    else if (arg === '--report') {
+      const next = args[index + 1];
+      if (!next || next.startsWith('--')) return { ok: false, exitCode: USAGE_ERROR_EXIT_CODE, error: '--report requires a path' };
+      options.reportPath = next;
+      index += 1;
+    } else {
+      return { ok: false, exitCode: USAGE_ERROR_EXIT_CODE, error: 'Unknown rc-check flag: ' + arg };
+    }
+  }
+  return { ok: true, options };
+}
+
+export async function rcCheckCommand(args = [], dependencies = {}) {
+  const parsed = parseRcCheckArgs(args);
+  if (!parsed.ok) {
+    console.error(parsed.error);
+    process.exitCode = parsed.exitCode;
+    return { usageError: true, exitCode: parsed.exitCode };
+  }
+  try {
+    const result = await runRcCheck({ ...parsed.options, dependencies });
+    process.stdout.write(parsed.options.json ? renderJsonRcCheck(result) : renderHumanRcCheck(result));
+    process.exitCode = result.exitCode;
+    return result;
+  } catch (error) {
+    if (parsed.options.json) {
+      process.stdout.write(JSON.stringify({
+        schemaVersion: RC_CHECK_SCHEMA_VERSION,
+        command: 'rc-check',
+        classification: RC_CLASSIFICATIONS.BLOCKED,
+        exitCode: INTERNAL_ERROR_EXIT_CODE,
+        error: redactCredentials(error.message || String(error))
+      }, null, 2) + '\n');
+    } else {
+      console.error('rc-check internal error: ' + redactCredentials(error.message || String(error)));
+    }
+    process.exitCode = INTERNAL_ERROR_EXIT_CODE;
+    return { internalError: true, exitCode: INTERNAL_ERROR_EXIT_CODE };
+  }
+}
+
+export function summarizeCommandOutput(result, maxBytes = 4096) {
+  const stdout = truncatePreview(redactCredentials(result.stdout || ''), { maxBytes, maxLines: 80 });
+  const stderr = truncatePreview(redactCredentials(result.stderr || ''), { maxBytes, maxLines: 80 });
+  return { stdout, stderr };
+}