@ran-sh/dsh-crew 0.3.0

package/src/config-readiness.mjs

@@ -0,0 +1,59 @@
+import { buildReadinessMatrix, READINESS_REASON_CODES } from './readiness-matrix.mjs';
+
+function warningCodes(catalogBody) {
+  const hints = Array.isArray(catalogBody?.health?.hints) ? catalogBody.health.hints : [];
+  return [...new Set(hints
+    .filter((hint) => hint?.level === 'warning' && typeof hint?.code === 'string' && hint.code.trim())
+    .map((hint) => hint.code.trim()))];
+}
+
+/**
+ * Enrich the conservative runtime matrix with evidence the config report has
+ * already collected. This function performs no I/O and never reads provider
+ * configuration, credentials, quotas, pricing, or hidden catalog expectations.
+ */
+export function buildConfigReadinessMatrix({
+  platform = process.platform,
+  hubCompatibility = null,
+  workerProviderMode = null,
+  providerCatalogChecked = false,
+  providerCatalogBody = null,
+} = {}) {
+  const warnings = warningCodes(providerCatalogBody);
+  const catalogResponseOk = !!providerCatalogBody
+    && typeof providerCatalogBody === 'object'
+    && providerCatalogBody.ok !== false;
+  const catalogOk = providerCatalogChecked && catalogResponseOk && warnings.length === 0;
+
+  const evidence = {};
+  if (
+    workerProviderMode !== 'deepseek-official'
+    && hubCompatibility?.compatible === true
+    && providerCatalogChecked
+    && catalogResponseOk
+    && warnings.length > 0
+  ) {
+    evidence.provider_catalog = {
+      status: 'FAIL',
+      reason_code: READINESS_REASON_CODES.PROVIDER_CATALOG_HEALTH_WARNING,
+      evidence_source: 'harness-catalog',
+    };
+  }
+
+  const matrix = buildReadinessMatrix({
+    platform,
+    hubCompatibility,
+    workerProviderMode,
+    providerCatalogChecked,
+    providerCatalogOk: catalogOk,
+    evidence,
+  });
+
+  if (warnings.length === 0) return matrix;
+  return {
+    ...matrix,
+    rows: matrix.rows.map((row) => row.id === 'provider_catalog'
+      ? { ...row, detail_codes: warnings }
+      : row),
+  };
+}

package/src/delivery.mjs

@@ -0,0 +1,205 @@
+// Auditable worker delivery: one shared Delivery Contract that every coding
+// worker (and the automatic Pro review) must fill out before its result is
+// accepted, plus pure helpers to prompt for, parse, validate and format it.
+//
+// Everything here is a pure function (no I/O, no worker runtime), so tests can
+// exercise the contract without starting DSH. Keeping the contract in one
+// shared builder guarantees the prompt-construction points (jobs.mjs, the hub,
+// the MCP shim) emit byte-identical instructions, and parse / validate let the
+// orchestrator separate *execution* status (running/done/failed) from
+// *delivery* completeness (did the worker actually report Diff/Tests/Risks?).
+
+export const DELIVERY_SECTIONS = ['Diff', 'Tests', 'Risks'];
+export const OPTIONAL_DELIVERY_SECTIONS = ['Unverified'];
+export const ALL_DELIVERY_SECTIONS = [...DELIVERY_SECTIONS, ...OPTIONAL_DELIVERY_SECTIONS];
+
+export const REVIEW_SECTIONS = ['Review Findings', 'Evidence', 'Risks', 'Verdict'];
+
+/** Any worker prompt that already carries a delivery report (added once). */
+export const DELIVERY_MARKER = '# Delivery report';
+
+const METADATA_KEYS = {
+  Diff: 'diff',
+  Tests: 'tests',
+  Risks: 'risks',
+  Unverified: 'unverified',
+  'Review Findings': 'findings',
+  Evidence: 'evidence',
+  Verdict: 'verdict',
+};
+
+/**
+ * Prompts a coding worker (or, with isReview, an automatic Pro review) to end
+ * its final message with the auditable delivery contract. This is the single
+ * source of the contract text for every worker prompt.
+ */
+export function buildDeliveryInstructions({ tier = 'pro', isReview = false } = {}) {
+  if (isReview) {
+    return `# Delivery report — automatic review (worker tier: pro)
+You are reviewing an implementation, and your review must be auditable. End your final message with these four sections — each on its own line as a '##' heading — followed by concise content:
+
+## Review Findings
+One-line overall assessment of whether the implementation satisfies the task.
+
+## Evidence
+What you inspected: file paths, diffs, commands you ran, and their results.
+
+## Risks
+Concrete issues found: bugs, style problems, missing edge cases, security or secret-handling concerns.
+
+## Verdict
+One line: approved / needs changes / rejected, plus the single most important reason.
+
+Do not edit files unless the user explicitly asks for fixes.`;
+  }
+  return `# Delivery report requirements (worker tier: ${String(tier).toUpperCase()})
+You are a coding worker, and your result must be auditable. End your final message with these three mandatory sections — each on its own line as a '##' heading — followed by concise, factual content:
+
+## Diff
+Every file you changed or created (paths), with a one-line summary per file. If you changed nothing, write "no files changed".
+
+## Tests
+Every entry must use exactly one of these auditable states:
+PASS — <command/check> — <result>
+FAIL — <command/check> — <reason>
+NOT RUN — <check> — <reason>
+"none" is not a valid Tests result.
+
+## Risks
+Known risks and side effects: files touched outside the requested scope, assumptions you made, anything that could break, and any credentials or sensitive data you opened.
+
+## Unverified
+(Optional — omit entirely if you verified everything.) Anything you could not verify: skipped builds, untested platforms, known gaps.
+
+The Diff, Tests and Risks sections are mandatory — do not skip them. Keep each section tight (a few lines is enough).
+
+${tier === 'flash' ? `Implement only the delegated coding scope.
+Run direct validation needed for your change.
+Return the Delivery Report.
+Then stop and return control to the Main Agent.
+
+Do not autonomously start a new task or delegate further work.` : ''}`;
+}
+
+/**
+ * Append the delivery instructions to a worker task prompt. Idempotent: a task
+ * that already carries the delivery report (e.g. a review prompt, or a
+ * re-dispatch) is returned untouched so instructions are never doubled.
+ */
+export function appendDeliveryInstructions(task, { tier, isReview } = {}) {
+  if (typeof task !== 'string') return task;
+  if (task.includes(DELIVERY_MARKER)) return task;
+  return `${task}\n\n${buildDeliveryInstructions({ tier, isReview })}`;
+}
+
+function parseTestsSection(value) {
+  if (typeof value !== 'string' || value.trim() === '') return { valid: false, status: undefined };
+  const statuses = [];
+  for (const line of value.split(/\r?\n/).map((item) => item.trim()).filter(Boolean)) {
+    const match = line.match(/^(?:[-*+]\s+)?(PASS|FAIL|NOT RUN)\s+—\s+\S.*?\s+—\s+\S.*$/);
+    if (!match) return { valid: false, status: undefined };
+    statuses.push(match[1]);
+  }
+  const status = statuses.includes('FAIL') ? 'FAIL' : statuses.includes('NOT RUN') ? 'NOT RUN' : statuses.includes('PASS') ? 'PASS' : undefined;
+  return { valid: status !== undefined, status };
+}
+
+/**
+ * Parse a worker's final message into the delivery report. Detects the report
+ * format from the headings present: coding workers use Diff/Tests/Risks
+ * (+ optional Unverified), automatic reviews use Review Findings/Evidence/
+ * Risks/Verdict. `complete` means every *mandatory* section of the detected
+ * format is present and non-empty.
+ *
+ * Returns { format, present, complete, missing, sections }.
+ */
+export function parseDeliveryReport(text = '') {
+  const normalized = typeof text === 'string' ? text : String(text ?? '');
+  if (normalized.trim() === '') {
+    return { format: null, present: [], complete: false, missing: [...DELIVERY_SECTIONS], sections: {} };
+  }
+  const canonical = new Map(ALL_DELIVERY_SECTIONS.concat(REVIEW_SECTIONS).map((name) => [name.toLowerCase(), name]));
+  const heading = /^##\s+(Diff|Tests|Risks|Unverified|Review Findings|Evidence|Verdict)\s*$/gim;
+  const marks = [];
+  let m;
+  while ((m = heading.exec(normalized)) !== null) marks.push({ index: m.index, name: canonical.get(m[1].toLowerCase()), len: m[0].length });
+  if (marks.length === 0) {
+    return { format: null, present: [], complete: false, missing: [...DELIVERY_SECTIONS], sections: {} };
+  }
+  const sections = {};
+  for (let i = 0; i < marks.length; i++) {
+    const start = marks[i].index + marks[i].len;
+    const end = i + 1 < marks.length ? marks[i + 1].index : normalized.length;
+    const body = normalized.slice(start, end).trim();
+    const name = marks[i].name;
+    sections[name] = sections[name] === undefined ? body : `${sections[name]}\n\n${body}`;
+  }
+  const isReview = REVIEW_SECTIONS.some((s) => s !== 'Risks' && sections[s] !== undefined);
+  const mandatory = isReview ? REVIEW_SECTIONS : DELIVERY_SECTIONS;
+  const parsedTests = isReview ? null : parseTestsSection(sections.Tests);
+  const missing = mandatory.filter((s) => {
+    const v = sections[s];
+    if (v === undefined || v === '') return true;
+    return !isReview && s === 'Tests' && !parsedTests.valid;
+  });
+  const testsStatus = parsedTests?.status;
+  return {
+    format: isReview ? 'review' : 'coding',
+    present: [...new Set(marks.map((x) => x.name))],
+    complete: missing.length === 0,
+    missing,
+    sections,
+    ...(testsStatus ? { tests_status: testsStatus } : {}),
+  };
+}
+
+/**
+ * Re-check a parsed report (or raw text) against the contract. Pure and
+ * forgiving: returns { ok, complete, missing, present } and never throws.
+ */
+export function validateDeliveryReport(parsedOrText) {
+  const parsed = typeof parsedOrText === 'string'
+    ? parseDeliveryReport(parsedOrText)
+    : (parsedOrText ?? parseDeliveryReport(''));
+  const sections = parsed.sections ?? {};
+  const isReview = parsed.format === 'review';
+  const mandatory = isReview ? REVIEW_SECTIONS : DELIVERY_SECTIONS;
+  const parsedTests = isReview ? null : parseTestsSection(sections.Tests);
+  const missing = mandatory.filter((s) => {
+    const v = sections[s];
+    if (v === undefined || v === '') return true;
+    return !isReview && s === 'Tests' && !parsedTests.valid;
+  });
+  return { ok: missing.length === 0, complete: missing.length === 0, missing: [...missing], present: [...(parsed.present ?? [])] };
+}
+
+function clip(text, limit) {
+  if (typeof text !== 'string') return undefined;
+  const t = text.trim();
+  if (t === '') return undefined;
+  return t.length > limit ? `${t.slice(0, limit)}…` : t;
+}
+
+/**
+ * Compact metadata form of a parsed report for MCP responses / job views:
+ * complete + missing plus a bounded snippet per present section. Keeps the
+ * worker's full message out of status payloads.
+ */
+export function formatDeliveryMetadata(parsed, { limit = 400 } = {}) {
+  const sections = parsed?.sections ?? {};
+  const out = {
+    complete: parsed?.complete === true,
+    missing: Array.isArray(parsed?.missing) ? [...parsed.missing] : [],
+  };
+  for (const s of ALL_DELIVERY_SECTIONS) {
+    const clipped = clip(sections[s], limit);
+    if (clipped !== undefined) out[METADATA_KEYS[s]] = clipped;
+  }
+  for (const s of REVIEW_SECTIONS) {
+    const clipped = clip(sections[s], limit);
+    if (clipped !== undefined) out[METADATA_KEYS[s]] = clipped;
+  }
+  if (parsed?.tests_status) out.tests_status = parsed.tests_status;
+  if (out.missing.length === 0) delete out.missing;
+  return out;
+}

package/src/dsh-cli-runtime.mjs

@@ -0,0 +1,251 @@
+// DSH CLI/runtime resolution for Crew-owned installs.
+//
+// The resolver is deliberately independent from the official ~/.dsh state.
+// A reusable CLI may live under the Crew DSH_HOME, while global dsh/npx remain
+// compatibility fallbacks. Status and uninstall callers can resolve without
+// allowing a download.
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join, extname } from 'node:path';
+import { homedir } from 'node:os';
+import { crewDshHome, crewProfileDir } from './install/install.mjs';
+
+export const DSH_CLI_PACKAGE = '@deepseek-ai/dsh';
+export const CREW_DSH_RUNTIME_DIRNAME = 'runtime';
+
+function defaultFindCommand(name) {
+  const probe = process.platform === 'win32' ? 'where.exe' : 'which';
+  const result = spawnSync(probe, [name], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  if (result.status !== 0) return null;
+  return String(result.stdout ?? '').split(/\r?\n/).map((line) => line.trim()).find(Boolean) ?? null;
+}
+
+function defaultExists(path) {
+  try { return existsSync(path); } catch { return false; }
+}
+
+function packageVersion(entry, read = readFileSync) {
+  try {
+    const packageFile = join(entry, '..', '..', 'package.json');
+    const parsed = JSON.parse(read(packageFile, 'utf8'));
+    return typeof parsed.version === 'string' ? parsed.version : null;
+  } catch { return null; }
+}
+
+export function crewDshRuntimeRoot({ home = homedir() } = {}) {
+  return join(crewDshHome({ home }), CREW_DSH_RUNTIME_DIRNAME);
+}
+
+export function crewDshRuntimeEntry({ home = homedir(), platform = process.platform } = {}) {
+  const suffix = platform === 'win32' ? '.cmd' : '';
+  return join(crewDshRuntimeRoot({ home }), 'node_modules', '.bin', `dsh${suffix}`);
+}
+
+export function crewDshRuntimeModule({ home = homedir() } = {}) {
+  return join(crewDshRuntimeRoot({ home }), 'node_modules', '@deepseek-ai', 'dsh', 'lib', 'bin.js');
+}
+
+function isPathLike(value) {
+  return typeof value === 'string' && (value.includes('/') || value.includes('\\') || extname(value) === '.cmd' || extname(value) === '.exe');
+}
+
+function descriptor({ kind, command, args = [], source, version = null, reusable = false }) {
+  return Object.freeze({ kind, command, args: [...args], source, version, reusable });
+}
+
+function explicitDescriptor(value, { exists = defaultExists, platform = process.platform } = {}) {
+  if (typeof value !== 'string' || !value.trim()) return null;
+  const trimmed = value.trim();
+  if (isPathLike(trimmed) && !exists(trimmed)) return null;
+  if (extname(trimmed).toLowerCase() === '.js') {
+    return descriptor({ kind: 'explicit-node', command: process.execPath, args: [trimmed], source: 'explicit', reusable: true });
+  }
+  return descriptor({ kind: platform === 'win32' && extname(trimmed).toLowerCase() === '.cmd' ? 'explicit-cmd' : 'explicit', command: trimmed, source: 'explicit', reusable: true });
+}
+
+/**
+ * Resolve a CLI without reading DSH credentials or profile state.
+ * `allowDownload` only affects the final npx descriptor; resolution itself
+ * never starts a network operation.
+ */
+export function resolveDshCli({
+  home = homedir(),
+  env = process.env,
+  platform = process.platform,
+  exists = defaultExists,
+  findCommand = defaultFindCommand,
+  allowDownload = false,
+  includeCompatibility = true,
+  read = readFileSync,
+} = {}) {
+  const explicit = explicitDescriptor(env.DSH_CREW_DSH_CLI ?? env.DSH_CLI, { exists, platform });
+  if (explicit) return explicit;
+
+  const moduleEntry = crewDshRuntimeModule({ home });
+  if (exists(moduleEntry)) {
+    return descriptor({
+      kind: 'crew-runtime',
+      command: process.execPath,
+      args: [moduleEntry],
+      source: 'crew-runtime',
+      version: packageVersion(moduleEntry, read),
+      reusable: true,
+    });
+  }
+
+  if (!includeCompatibility) return null;
+
+  const global = findCommand('dsh');
+  if (global) return descriptor({ kind: 'global', command: global, source: 'global' });
+
+  const npx = findCommand('npx');
+  if (!npx) return null;
+  return descriptor({
+    kind: allowDownload ? 'npx-download' : 'npx-local',
+    command: npx,
+    args: allowDownload ? ['--yes', DSH_CLI_PACKAGE] : ['--no-install', DSH_CLI_PACKAGE],
+    source: allowDownload ? 'npx-download' : 'npx-local',
+  });
+}
+
+function quoteWindowsArg(value) {
+  const input = String(value);
+  if (input.length > 0 && !/[\s"]/u.test(input)) return input;
+  let output = '"';
+  let slashes = 0;
+  for (const char of input) {
+    if (char === '\\') { slashes += 1; continue; }
+    if (char === '"') {
+      output += '\\'.repeat(slashes * 2 + 1) + '"';
+    } else {
+      output += '\\'.repeat(slashes) + char;
+    }
+    slashes = 0;
+  }
+  output += '\\'.repeat(slashes * 2) + '"';
+  return output;
+}
+
+export { quoteWindowsArg };
+
+/** Build a shell-free invocation, including deterministic Windows .cmd handling. */
+export function buildDshInvocation(cli, args = [], { platform = process.platform, comspec = process.env.ComSpec ?? 'cmd.exe' } = {}) {
+  const allArgs = [...(cli?.args ?? []), ...args].map(String);
+  const command = String(cli?.command ?? '');
+  if (platform === 'win32' && /\.(?:cmd|bat)$/iu.test(command)) {
+    return {
+      command: comspec,
+      args: ['/d', '/s', '/c', [quoteWindowsArg(command), ...allArgs.map(quoteWindowsArg)].join(' ')],
+      shell: false,
+    };
+  }
+  return { command, args: allArgs, shell: false };
+}
+
+export function runResolvedDsh(cli, args = [], {
+  home = homedir(),
+  env = process.env,
+  runner = spawnSync,
+  platform = process.platform,
+  comspec = process.env.ComSpec ?? 'cmd.exe',
+} = {}) {
+  if (!cli) return { ok: false, status: -1, stdout: '', stderr: 'DSH CLI unavailable' };
+  const invocation = buildDshInvocation(cli, args, { platform, comspec });
+  const result = runner(invocation.command, invocation.args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    shell: invocation.shell,
+    env: { ...env, DSH_HOME: crewDshHome({ home }) },
+  });
+  return {
+    ok: result.status === 0,
+    status: result.status ?? -1,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+    invocation,
+  };
+}
+
+/**
+ * Install a reusable DSH CLI into Crew-owned state. This is the only helper
+ * that may invoke a package manager, and callers must explicitly opt into it.
+ */
+export function ensureCrewDshRuntime({
+  home = homedir(),
+  packageSpec = DSH_CLI_PACKAGE,
+  npmCommand = null,
+  pnpmCommand = null,
+  findCommand = defaultFindCommand,
+  exists = defaultExists,
+  runner = spawnSync,
+  platform = process.platform,
+  comspec = process.env.ComSpec ?? 'cmd.exe',
+  env = process.env,
+} = {}) {
+  const existing = resolveDshCli({ home, env, platform, exists, findCommand, includeCompatibility: false });
+  if (existing?.kind === 'crew-runtime') return { ok: true, cli: existing, reused: true };
+
+  const pnpm = pnpmCommand ?? findCommand('pnpm');
+  const npm = npmCommand ?? findCommand('npm');
+  if (!pnpm && !npm) return { ok: false, code: 'DSH_RUNTIME_INSTALLER_NOT_FOUND', error: 'pnpm/npm unavailable' };
+  const runtimeRoot = crewDshRuntimeRoot({ home });
+  mkdirSync(runtimeRoot, { recursive: true });
+  const packageManager = pnpm
+    ? descriptor({ kind: 'pnpm', command: pnpm, source: 'pnpm' })
+    : descriptor({ kind: 'npm', command: npm, source: 'npm' });
+  const packageArgs = pnpm
+    ? ['add', '--dir', runtimeRoot, '--ignore-scripts', packageSpec]
+    : ['install', '--prefix', runtimeRoot, '--no-package-lock', '--ignore-scripts', '--omit=dev', packageSpec];
+  const invocation = buildDshInvocation(packageManager, packageArgs, { platform, comspec });
+  const result = runner(invocation.command, invocation.args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    shell: invocation.shell,
+    env: { ...env },
+  });
+  const cli = resolveDshCli({ home, env, platform, exists, findCommand, includeCompatibility: false });
+  if (result.status !== 0 || !cli || cli.kind !== 'crew-runtime') {
+    return { ok: false, code: 'DSH_RUNTIME_INSTALL_FAILED', error: 'Crew-owned DSH runtime install failed', status: result.status ?? -1 };
+  }
+  return { ok: true, cli, reused: false, version: cli.version, runtimeRoot };
+}
+
+export function describeDshCli(cli) {
+  if (!cli) return 'unavailable';
+  const version = cli.version ? `@${cli.version}` : '';
+  return `${cli.kind}${version}`;
+}
+
+/**
+ * Remove one Crew plugin registration without invoking a package manager.
+ * This is intentionally limited to the derived Crew profile directory so a
+ * status/uninstall probe cannot touch the official web profile or download
+ * anything merely to remove a stale registration.
+ */
+export function removeCrewPluginRegistration({ home = homedir(), name, profileRoot = crewProfileDir({ home }) } = {}) {
+  if (typeof name !== 'string' || !name || name.split('/').some((part) => !part || part === '.' || part === '..')) {
+    return { ok: false, code: 'INVALID_CREW_PLUGIN_NAME' };
+  }
+  const packageFile = join(profileRoot, 'package.json');
+  if (!existsSync(packageFile)) return { ok: true, removed: false };
+  let pkg;
+  try { pkg = JSON.parse(readFileSync(packageFile, 'utf8')); } catch { return { ok: false, code: 'CREW_PROFILE_METADATA_INVALID' }; }
+  const hadDependency = Boolean(pkg.dependencies?.[name]);
+  const bundles = Array.isArray(pkg.dsh?.profile?.bundles) ? pkg.dsh.profile.bundles : [];
+  const hadBundle = bundles.includes(name);
+  if (!hadDependency && !hadBundle) return { ok: true, removed: false };
+  const next = { ...pkg };
+  if (hadDependency) {
+    next.dependencies = { ...pkg.dependencies };
+    delete next.dependencies[name];
+    if (Object.keys(next.dependencies).length === 0) delete next.dependencies;
+  }
+  if (hadBundle) {
+    next.dsh = { ...pkg.dsh, profile: { ...pkg.dsh.profile, bundles: bundles.filter((item) => item !== name) } };
+  }
+  writeFileSync(packageFile, JSON.stringify(next, null, 2) + '\n');
+  const packageParts = name.split('/');
+  rmSync(join(profileRoot, 'node_modules', ...packageParts), { recursive: true, force: true });
+  return { ok: true, removed: true };
+}

package/src/failure-classification.mjs

@@ -0,0 +1,172 @@
+// Pure, secret-free failure classification for workflow and MCP results.
+//
+// Classification consumes structured status/codes/outcomes only. It never
+// parses raw exception text, provider responses, credentials, quotas or logs.
+
+export const FAILURE_CATEGORIES = Object.freeze([
+  'none',
+  'policy',
+  'compatibility',
+  'provider',
+  'runtime',
+  'verification',
+  'cancelled',
+]);
+
+export const FAILURE_REASON_CODES = Object.freeze({
+  NONE: 'NONE',
+  CANCELLED: 'CANCELLED',
+  ATTEMPT_TIMEOUT: 'ATTEMPT_TIMEOUT',
+  RUNTIME_FAILURE: 'RUNTIME_FAILURE',
+  EXECUTION_FAILED: 'EXECUTION_FAILED',
+  TESTS_FAILED: 'TESTS_FAILED',
+  TESTS_NOT_RUN: 'TESTS_NOT_RUN',
+  DELIVERY_INCOMPLETE: 'DELIVERY_INCOMPLETE',
+  WORKSPACE_MISMATCH: 'WORKSPACE_MISMATCH',
+  TASK_BLOCKED: 'TASK_BLOCKED',
+  TASK_PARTIAL: 'TASK_PARTIAL',
+  REVIEW_CHANGES_REQUESTED: 'REVIEW_CHANGES_REQUESTED',
+  REVIEW_INCONCLUSIVE: 'REVIEW_INCONCLUSIVE',
+  POLICY_REJECTED: 'POLICY_REJECTED',
+  HUB_INCOMPATIBLE: 'HUB_INCOMPATIBLE',
+  PROVIDER_UNAVAILABLE: 'PROVIDER_UNAVAILABLE',
+});
+
+const PROVIDER_CODES = new Set([
+  'NO_DSH_PROVIDER_SELECTED',
+  'NO_WORKER_MODEL_AVAILABLE',
+  'MODEL_CATALOG_UNAVAILABLE',
+  'PROVIDER_CATALOG_UNAVAILABLE',
+  'PROVIDER_CATALOG_HEALTH_WARNING',
+]);
+
+const POLICY_CODES = new Set([
+  'SUBAGENTS_DISABLED',
+  'TIER_DISABLED',
+  'NO_AUTO_TIER',
+  'NO_WORKER_TIER',
+  'PRO_NOT_AUTO',
+  'VISION_DISABLED',
+  'ROLE_DISABLED',
+  'ROLE_NOT_AUTO',
+  'ROLE_TIER_CONFLICT',
+]);
+
+const COMPATIBILITY_CODES = new Set([
+  'HUB_UNREACHABLE',
+  'HUB_HTTP_ERROR',
+  'HUB_SERVICE_MISMATCH',
+  'HUB_PROTOCOL_MISSING',
+  'HUB_PROTOCOL_MISMATCH',
+  'HUB_CAPABILITY_MISSING',
+]);
+
+const RUNTIME_CODES = new Set([
+  'ISOLATION_UNAVAILABLE',
+  'NOT_GIT_REPOSITORY',
+  'GIT_NOT_FOUND',
+  'GIT_TIMEOUT',
+  'GIT_ERROR',
+  'WORKTREE_LOCKED',
+  'WORKTREE_CREATE_FAILED',
+  'CANDIDATE_CAPTURE_FAILED',
+  'ATTEMPT_INFRA_FAILURE',
+  'HUB_REQUEST_FAILED',
+]);
+
+function normalizedCode(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function result(category, reasonCode, { sourceCode = null, terminalReason = null } = {}) {
+  return {
+    schema_version: 1,
+    category,
+    reason_code: reasonCode,
+    ...(sourceCode ? { source_code: sourceCode } : {}),
+    ...(terminalReason ? { terminal_reason: terminalReason } : {}),
+  };
+}
+
+function verificationRoot({ outcome, review } = {}) {
+  if (review?.verdict === 'request_changes') return FAILURE_REASON_CODES.REVIEW_CHANGES_REQUESTED;
+  if (review?.verdict === 'inconclusive' && review?.status === 'failed') return FAILURE_REASON_CODES.REVIEW_INCONCLUSIVE;
+  if (outcome?.tests_status === 'FAIL') return FAILURE_REASON_CODES.TESTS_FAILED;
+  if (outcome?.delivery?.complete === false) return FAILURE_REASON_CODES.DELIVERY_INCOMPLETE;
+  if (outcome?.workspace_evidence_ok === false) return FAILURE_REASON_CODES.WORKSPACE_MISMATCH;
+  if (outcome?.task_status === 'blocked') return FAILURE_REASON_CODES.TASK_BLOCKED;
+  if (outcome?.tests_status === 'NOT RUN') return FAILURE_REASON_CODES.TESTS_NOT_RUN;
+  if (outcome?.task_status === 'partial') return FAILURE_REASON_CODES.TASK_PARTIAL;
+  return null;
+}
+
+/**
+ * Classify one workflow/result snapshot.
+ *
+ * Precedence is intentional:
+ * 1) cancellation is explicit user/runtime intent;
+ * 2) stable compatibility/provider/policy codes identify the failing boundary;
+ * 3) timeout/runtime execution failures outrank verification;
+ * 4) verification uses the business evidence that caused escalation/failure;
+ * 5) otherwise the result is `none`.
+ *
+ * `decision.reason` is retained only as a bounded terminal reason (for example
+ * max_attempts_reached); it never replaces the underlying verification cause.
+ */
+export function classifyFailure({
+  phase = null,
+  status = null,
+  errorCode = null,
+  outcome = null,
+  decision = null,
+  review = null,
+  childAttempts = [],
+} = {}) {
+  const code = normalizedCode(errorCode);
+  const terminalReason = normalizedCode(decision?.reason);
+
+  if (phase === 'cancelled' || status === 'cancelled' || code === 'WORKFLOW_CANCELLED') {
+    return result('cancelled', FAILURE_REASON_CODES.CANCELLED, {
+      sourceCode: code === 'WORKFLOW_CANCELLED' ? code : null,
+      terminalReason,
+    });
+  }
+
+  if (code && COMPATIBILITY_CODES.has(code)) {
+    return result('compatibility', code, { sourceCode: code, terminalReason });
+  }
+  if (code && PROVIDER_CODES.has(code)) {
+    return result('provider', FAILURE_REASON_CODES.PROVIDER_UNAVAILABLE, { sourceCode: code, terminalReason });
+  }
+  if (code && POLICY_CODES.has(code)) {
+    return result('policy', FAILURE_REASON_CODES.POLICY_REJECTED, { sourceCode: code, terminalReason });
+  }
+
+  const attempts = Array.isArray(childAttempts) ? childAttempts : [];
+  if (attempts.some((attempt) => attempt?.timed_out === true || attempt?.stopReason === 'timeout')) {
+    return result('runtime', FAILURE_REASON_CODES.ATTEMPT_TIMEOUT, { terminalReason });
+  }
+  if (code && RUNTIME_CODES.has(code)) {
+    return result('runtime', code, { sourceCode: code, terminalReason });
+  }
+  if (outcome?.execution_status === 'failed') {
+    return result('runtime', FAILURE_REASON_CODES.EXECUTION_FAILED, { terminalReason });
+  }
+
+  const verification = verificationRoot({ outcome, review });
+  if (verification) return result('verification', verification, { terminalReason });
+
+  if (phase === 'failed' || status === 'failed') {
+    return result('runtime', FAILURE_REASON_CODES.RUNTIME_FAILURE, {
+      sourceCode: code,
+      terminalReason,
+    });
+  }
+
+  return result('none', FAILURE_REASON_CODES.NONE);
+}
+
+/** Classify an immediate MCP rejection before a workflow exists. */
+export function classifyFailureCode(code) {
+  return classifyFailure({ status: 'failed', errorCode: code });
+}