@fitlab-ai/agent-infra 0.11.4 → 0.11.5

package/lib/task/human-override.ts

@@ -1,1522 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { createHash, randomUUID } from 'node:crypto';
-
-import { parseArtifactName } from './artifact-name.ts';
-import { locateActivityLog } from './activity-log.ts';
-import { applyPrReviewActivityIntent } from './activity-intent.ts';
-import { applyHumanDecision } from './decision-intents.ts';
-import { applyTaskEvent } from './events.ts';
-import { parseTypedTaskFrontmatter } from './frontmatter.ts';
-import { applyTaskLifecycle, lifecycleProducerCatalog } from './lifecycle.ts';
-import type { TaskLifecycleIntent, TaskLifecycleRequest } from './lifecycle.ts';
-import { guardFailureId, guardProducerCatalog } from './guard-override.ts';
-import type { GuardProducer, ManualOverrideCapability } from './guard-override.ts';
-import { inspectLifecycleExecution } from './lifecycle-execution.ts';
-import { applyLedgerIntent } from './ledger-intents.ts';
-import { bindPlatformIssue } from '../platform/issues.ts';
-import { bindPlatformPullRequest } from '../platform/pull-requests.ts';
-import type { PlatformClient } from '../platform/context.ts';
-import { finalizeReviewSummary } from './review-finalization.ts';
-import { resolveTaskRef } from './resolve-ref.ts';
-import { DocumentMutationError, parseTable } from './sections.ts';
-import { applyWorkflowWarningIntent } from './workflow-warning-intents.ts';
-import { verifyTaskEvent } from './verification.ts';
-import { verifyInProcess } from './verification-engine.ts';
-import { canonicalTimestamp, writeTask } from './write.ts';
-import type { TaskFileSystem, TaskWriteMetadata, TaskWriteResult } from './write.ts';
-import { readPrDeliveryFact } from './pr-delivery-fact.ts';
-import { resourceIdentity, resourceIdentityNumber } from '../platform/provider-bridge.ts';
-import type { ResourceIdentity } from '../platform/resource-identity.ts';
-import { taskIssueIdentity } from '../platform/task-identities.ts';
-
-type Eligibility = 'eligible' | 'repair-only' | 'runtime-recovery-only' | 'never-overridable';
-type OutcomeEffect = 'apply-target' | 'retry-same-intent' | 'record-only' | 'no-write';
-type OutcomeResult = 'human-approved' | 'safe-closed' | 'recovery-required' | 'preserve-failure';
-
-type FailureIdentity = Readonly<{
-  id: string;
-  producerId: string;
-  guardId: string;
-  code: string;
-}>;
-
-type OutcomeContext = Readonly<{
-  id: string;
-  facts: readonly string[];
-}>;
-
-type OutcomeRule = Readonly<{
-  target: string;
-  contextId: string;
-  effect: OutcomeEffect;
-  result: OutcomeResult;
-  residual: string;
-}>;
-
-type OutcomeFallback = Readonly<{
-  effect: 'no-write' | 'record-only';
-  result: 'recovery-required' | 'preserve-failure';
-  residual: string;
-}>;
-
-type FailurePolicy = FailureIdentity & Readonly<{
-  eligibility: Eligibility;
-  capability: string;
-  targets: readonly string[];
-  contexts: readonly OutcomeContext[];
-  targetContexts: Readonly<Record<string, readonly string[]>>;
-  outcomes: readonly OutcomeRule[];
-  fallback: OutcomeFallback;
-  probeId: string;
-}>;
-
-type Outcome = Readonly<{
-  effect: OutcomeEffect;
-  result: OutcomeResult;
-  residual: string;
-  policyId: string;
-  target: string;
-  contextId: string;
-}>;
-
-type HumanOverrideIdentity = Readonly<{
-  source: 'local-declared';
-  operator: string;
-  verified: false;
-}>;
-
-type HumanOverrideOptions = Readonly<{
-  repoRoot?: string;
-  now?: () => string;
-  randomId?: () => string;
-  metadataProvider?: () => TaskWriteMetadata;
-  randomSuffix?: () => string;
-  taskFileSystem?: Partial<TaskFileSystem>;
-  probeIntent?: TaskLifecycleIntent;
-  probeOperator?: string;
-  probeReason?: string;
-  probeAlertNumber?: number;
-  probeIssueNumber?: number;
-  probePullRequestNumber?: number;
-  probeStagingDir?: string;
-  platformClient?: PlatformClient;
-  effectExecutor?: (capability: ManualOverrideCapability) => OverrideError | null | Promise<OverrideError | null>;
-}>;
-
-type FailureSnapshot = Readonly<{
-  schema: '1';
-  taskId: string;
-  failureId: string;
-  producerId: string;
-  code: string;
-  target: string;
-  state: string;
-  digest: string;
-  observedFacts: readonly string[];
-  message: string;
-  capturedAt: string;
-  source: 'producer-result';
-}>;
-
-type HumanOverrideRequest = Readonly<{
-  taskRef: string;
-  failureId: string;
-  target: string;
-  operator: string;
-  reason: string;
-  scope: string;
-  expiresAt: string;
-  intent?: TaskLifecycleIntent;
-  alertNumber?: number;
-  issueNumber?: number;
-  pullRequestNumber?: number;
-  stagingDir?: string;
-  failureDigest?: string;
-  failureSnapshot?: FailureSnapshot;
-  identitySource?: string;
-}>;
-
-type ConsumeHumanOverrideRequest = Readonly<{
-  taskRef: string;
-  ticketId: string;
-  failureId: string;
-  target: string;
-  scope: string;
-  intent?: TaskLifecycleIntent;
-  alertNumber?: number;
-  issueNumber?: number;
-  pullRequestNumber?: number;
-  stagingDir?: string;
-  failureDigest?: string;
-  observedFacts?: readonly string[];
-  failureSnapshot?: FailureSnapshot;
-}>;
-
-type OverrideError = Readonly<{ code: string; message: string }>;
-
-type HumanOverrideIssueResult =
-  | Readonly<{
-      status: 'applied' | 'no-op';
-      changed: boolean;
-      ticketId: string;
-      taskId: string;
-      identity: HumanOverrideIdentity;
-      error: null;
-    }>
-  | Readonly<{
-      status: 'failed';
-      changed: false;
-      ticketId: string | null;
-      taskId: string | null;
-      identity: HumanOverrideIdentity | null;
-      error: OverrideError;
-    }>;
-
-type HumanOverrideConsumeResult =
-  | Readonly<{
-      status: 'applied' | 'no-op';
-      changed: boolean;
-      ticketId: string;
-      taskId: string;
-      outcome: Outcome;
-      manualOverride?: ManualOverrideCapability;
-      error: null;
-    }>
-  | Readonly<{
-      status: 'failed';
-      changed: false;
-      ticketId: string | null;
-      taskId: string | null;
-      outcome: Outcome | null;
-      error: OverrideError;
-    }>;
-
-const LIFECYCLE_PRODUCER = 'lifecycle.apply';
-const HUMAN_OVERRIDE_SECTION_ALIASES = ['人工豁免账本', 'Human Override Ledger'] as const;
-const HUMAN_OVERRIDE_COLUMNS = [
-  'id', 'schema', 'failure_id', 'producer_id', 'code', 'target', 'operator',
-  'identity_source', 'verified', 'reason', 'scope', 'intent', 'failure_message',
-  'failure_digest', 'context_id', 'effect', 'source_state', 'issued_at', 'expires_at', 'status',
-  'result', 'consumed_at', 'residual', 'alert_number', 'issue_number', 'pull_request_number', 'staging_dir'
-] as const;
-const LEGACY_HUMAN_OVERRIDE_COLUMNS = HUMAN_OVERRIDE_COLUMNS.filter((column) => column !== 'pull_request_number');
-const PULL_REQUEST_NUMBER_COLUMN = 'pull_request_number';
-
-const SHORT_ID_CONFIRMED = 'identity-confirmed-and-safe-close-proven';
-const SHORT_ID_UNCONFIRMED = 'identity-unconfirmed';
-const REGISTRY_RECOVERABLE = 'registry-recoverable';
-
-function failureId(producerId: string, code: string): string {
-  if (!singleLine(producerId) || !singleLine(code) || producerId.includes(':') || code.includes(':')) {
-    throw new Error('failure identity producer and code must be non-empty and colon-free');
-  }
-  return `${producerId}:${code}`;
-}
-
-function identity(producerId: string, code: string, guardId = code): FailureIdentity {
-  return { id: failureId(producerId, code), producerId, guardId, code };
-}
-
-function context(id: string, ...facts: string[]): OutcomeContext {
-  return { id, facts };
-}
-
-function makeSimplePolicy(code: string, eligibility: Eligibility, target: string, result: OutcomeResult): FailurePolicy {
-  const id = failureId(LIFECYCLE_PRODUCER, code);
-  const contextId = 'identity-confirmed';
-  const effect: OutcomeEffect = result === 'preserve-failure' ? 'record-only' : 'apply-target';
-  return {
-    ...identity(LIFECYCLE_PRODUCER, code, 'G-03'),
-    eligibility,
-    capability: eligibility === 'never-overridable' ? 'audit-only' : 'local-task-repair',
-    targets: [target],
-    contexts: [context(contextId, contextId)],
-    targetContexts: { [target]: [contextId] },
-    outcomes: [{
-      target,
-      contextId,
-      effect,
-      result,
-      residual: result === 'preserve-failure' ? 'original failure remains authoritative' : 'local operator action was applied to the task'
-    }],
-    fallback: {
-      effect: 'no-write',
-      result: result === 'preserve-failure' ? 'preserve-failure' : 'recovery-required',
-      residual: 'outcome context was not confirmed; no target state was written'
-    },
-    probeId: `probe.${code.toLowerCase()}`
-  };
-}
-
-function simplePolicy(code: string): FailurePolicy {
-  if (code === 'LIFECYCLE_SOURCE_INVALID') return makeSimplePolicy(code, 'eligible', 'continue-local', 'human-approved');
-  if (code === 'LIFECYCLE_LOG_MISSING' || code === 'LIFECYCLE_METADATA_FAILED' || code === 'LIFECYCLE_DOCUMENT_INVALID') {
-    return makeSimplePolicy(code, 'repair-only', 'repair-task', 'recovery-required');
-  }
-  if (code === 'LIFECYCLE_IDENTITY_CONFLICT' || code === 'LIFECYCLE_IDENTITY_INVALID' || code === 'LIFECYCLE_PAYLOAD_INVALID' || code === 'LIFECYCLE_STAGING_IDENTITY_INVALID' || code === 'LIFECYCLE_STAGING_INVALID') {
-    return makeSimplePolicy(code, 'never-overridable', 'record-only', 'preserve-failure');
-  }
-  return makeSimplePolicy(code, 'runtime-recovery-only', 'retry-same-intent', 'recovery-required');
-}
-
-function genericGuardPolicy(producer: GuardProducer): FailurePolicy {
-  const preserve = producer.guardId === 'G-01' || producer.guardId === 'G-09' || producer.guardId === 'G-10';
-  const contextId = 'guard-observed';
-  const result: OutcomeResult = preserve ? 'preserve-failure' : 'human-approved';
-  const effect: OutcomeEffect = preserve ? 'record-only' : 'apply-target';
-  return {
-    ...identity(producer.producerId, producer.code, producer.guardId),
-    eligibility: preserve ? 'never-overridable' : 'eligible',
-    capability: preserve ? 'audit-only' : `local-${producer.guardId.toLowerCase()}-gate`,
-    targets: ['continue-local'],
-    contexts: [context(contextId, contextId)],
-    targetContexts: { 'continue-local': [contextId] },
-    outcomes: [{
-      target: 'continue-local',
-      contextId,
-      effect,
-      result,
-      residual: preserve ? 'external or identity evidence remains authoritative' : `${producer.guardId} local guard was explicitly overridden`
-    }],
-    fallback: {
-      effect: 'record-only',
-      result: 'preserve-failure',
-      residual: 'guard facts were not confirmed; the original failure remains authoritative'
-    },
-    probeId: `probe.${producer.producerId}.${producer.code.toLowerCase()}`
-  };
-}
-
-const shortIdPolicy: FailurePolicy = {
-  ...identity(LIFECYCLE_PRODUCER, 'SHORT_ID_CAPACITY_EXCEEDED', 'G-03'),
-  eligibility: 'repair-only',
-  capability: 'safe-close-or-registry-recovery',
-  targets: ['safe-close', 'recover-registry'],
-  contexts: [
-    context(SHORT_ID_CONFIRMED, SHORT_ID_CONFIRMED),
-    context(SHORT_ID_UNCONFIRMED, SHORT_ID_UNCONFIRMED),
-    context(REGISTRY_RECOVERABLE, REGISTRY_RECOVERABLE)
-  ],
-  targetContexts: {
-    'safe-close': [SHORT_ID_CONFIRMED, SHORT_ID_UNCONFIRMED],
-    'recover-registry': [REGISTRY_RECOVERABLE]
-  },
-  outcomes: [
-    {
-      target: 'safe-close',
-      contextId: SHORT_ID_CONFIRMED,
-      effect: 'apply-target',
-      result: 'safe-closed',
-      residual: 'task was atomically safe-closed without entering active or expanding short-id capacity'
-    },
-    {
-      target: 'safe-close',
-      contextId: SHORT_ID_UNCONFIRMED,
-      effect: 'no-write',
-      result: 'recovery-required',
-      residual: 'task identity could not be confirmed; no terminal state was written'
-    },
-    {
-      target: 'recover-registry',
-      contextId: REGISTRY_RECOVERABLE,
-      effect: 'retry-same-intent',
-      result: 'recovery-required',
-      residual: 'registry recovery must complete before a new diagnosis and ticket are issued'
-    }
-  ],
-  fallback: {
-    effect: 'no-write',
-    result: 'recovery-required',
-    residual: 'short-id failure facts did not match a registered safe outcome context; original failure remains authoritative'
-  },
-  probeId: 'probe.short-id-capacity'
-};
-
-const HUMAN_OVERRIDE_FAILURE_REGISTRY: readonly FailurePolicy[] = [
-  shortIdPolicy,
-  ...lifecycleProducerCatalog
-    .filter(({ code }) => code !== 'SHORT_ID_CAPACITY_EXCEEDED')
-    .map(({ code }) => simplePolicy(code)),
-  ...guardProducerCatalog.map((producer) => genericGuardPolicy(producer))
-];
-
-const stableFailureCatalog = [
-  ...lifecycleProducerCatalog,
-  ...guardProducerCatalog
-].map(({ producerId, guardId, code }) => ({
-  id: guardFailureId(producerId, code),
-  producerId,
-  guardId,
-  code
-}));
-
-function singleLine(value: unknown): value is string {
-  return typeof value === 'string' && value.trim().length > 0 && !/[\r\n]/.test(value);
-}
-
-function validatePolicy(policy: FailurePolicy): void {
-  if (!singleLine(policy.id) || !singleLine(policy.producerId) || !singleLine(policy.guardId) || !singleLine(policy.code)) {
-    throw new Error('failure policy identity is invalid');
-  }
-  if (policy.id !== failureId(policy.producerId, policy.code)) throw new Error(`policy ${policy.id} has an invalid identity`);
-  if (!Array.isArray(policy.targets) || new Set(policy.targets).size !== policy.targets.length || policy.targets.length === 0) {
-    throw new Error(`policy ${policy.id} targets are invalid`);
-  }
-  if (!Array.isArray(policy.contexts) || policy.contexts.length === 0) throw new Error(`policy ${policy.id} contexts are missing`);
-  const contexts = new Map<string, OutcomeContext>();
-  for (const item of policy.contexts) {
-    if (!singleLine(item.id) || contexts.has(item.id) || item.facts.length === 0 || new Set(item.facts).size !== item.facts.length) {
-      throw new Error(`policy ${policy.id} contains invalid or duplicate contexts`);
-    }
-    contexts.set(item.id, item);
-  }
-  const contextFactsByTarget = new Map<string, Set<string>>();
-  for (const target of policy.targets) {
-    const facts = contextFactsByTarget.get(target) ?? new Set<string>();
-    for (const contextId of policy.targetContexts[target] ?? []) {
-      const item = contexts.get(contextId);
-      if (!item) continue;
-      const key = item.facts.slice().sort().join('\0');
-      if (facts.has(key)) throw new Error(`policy ${policy.id} has overlapping context facts for target ${target}`);
-      facts.add(key);
-    }
-    contextFactsByTarget.set(target, facts);
-  }
-  const outcomes = new Set<string>();
-  for (const target of policy.targets) {
-    const contextIds = policy.targetContexts[target];
-    if (!contextIds || contextIds.length === 0) throw new Error(`policy ${policy.id} target ${target} has no contexts`);
-    for (const contextId of contextIds) {
-      if (!contexts.has(contextId)) throw new Error(`policy ${policy.id} references unknown context ${contextId}`);
-      const key = `${target}\0${contextId}`;
-      if (outcomes.has(key)) throw new Error(`policy ${policy.id} has overlapping outcome ${key}`);
-      outcomes.add(key);
-    }
-  }
-  if (!Array.isArray(policy.outcomes) || policy.outcomes.length !== outcomes.size) {
-    throw new Error(`policy ${policy.id} outcome table does not cover every target/context`);
-  }
-  for (const rule of policy.outcomes) {
-    const key = `${rule.target}\0${rule.contextId}`;
-    if (!outcomes.has(key) || outcomes.delete(key) === false || !singleLine(rule.residual)) {
-      throw new Error(`policy ${policy.id} contains an invalid or duplicate outcome`);
-    }
-    if (rule.result === 'human-approved' && (policy.eligibility !== 'eligible' || rule.effect !== 'apply-target')) {
-      throw new Error(`policy ${policy.id} grants human-approved outside an eligible apply-target rule`);
-    }
-    if (rule.result === 'safe-closed' && rule.effect !== 'apply-target') {
-      throw new Error(`policy ${policy.id} grants safe-closed without applying a target`);
-    }
-    if (rule.effect === 'record-only' && rule.result === 'human-approved') {
-      throw new Error(`policy ${policy.id} treats record-only as human-approved`);
-    }
-  }
-  if (outcomes.size !== 0) throw new Error(`policy ${policy.id} has missing outcomes`);
-  if (!['no-write', 'record-only'].includes(policy.fallback.effect) || !['recovery-required', 'preserve-failure'].includes(policy.fallback.result) || !singleLine(policy.fallback.residual)) {
-    throw new Error(`policy ${policy.id} fallback is invalid`);
-  }
-}
-
-function validateRegistry(registry: readonly FailurePolicy[] = HUMAN_OVERRIDE_FAILURE_REGISTRY): void {
-  const ids = new Set<string>();
-  for (const policy of registry) {
-    validatePolicy(policy);
-    if (ids.has(policy.id)) throw new Error(`duplicate failure policy ${policy.id}`);
-    ids.add(policy.id);
-  }
-  const catalogIds = new Set(stableFailureCatalog.map((item) => item.id));
-  if (ids.size !== catalogIds.size || [...catalogIds].some((id) => !ids.has(id))) {
-    throw new Error('human override registry does not match the lifecycle producer catalog');
-  }
-  for (const item of stableFailureCatalog) {
-    const policy = registry.find((candidate) => candidate.id === item.id);
-    if (!policy || policy.producerId !== item.producerId || policy.guardId !== item.guardId || policy.code !== item.code) {
-      throw new Error(`human override policy ${item.id} does not match its producer catalog entry`);
-    }
-  }
-}
-
-validateRegistry();
-
-function policyFor(value: string | FailurePolicy): FailurePolicy | null {
-  if (typeof value !== 'string') return value;
-  return HUMAN_OVERRIDE_FAILURE_REGISTRY.find((policy) => policy.id === value) ?? null;
-}
-
-function resolveOutcome(policyOrId: string | FailurePolicy, requestedTarget: string, observedFacts: readonly string[]): Outcome {
-  const policy = policyFor(policyOrId);
-  if (!policy || !singleLine(requestedTarget) || !Array.isArray(observedFacts) || observedFacts.some((fact) => !singleLine(fact))) {
-    return {
-      effect: 'no-write',
-      result: 'recovery-required',
-      residual: 'failure policy or observed facts were not registered; no target state was written',
-      policyId: typeof policyOrId === 'string' ? policyOrId : policyOrId.id,
-      target: requestedTarget,
-      contextId: 'context-unmatched'
-    };
-  }
-  const allowedContexts = policy.targetContexts[requestedTarget] ?? [];
-  const matches = policy.contexts.filter((item) => allowedContexts.includes(item.id)
-    && item.facts.length === observedFacts.length
-    && item.facts.every((fact) => observedFacts.includes(fact))
-    && observedFacts.every((fact) => item.facts.includes(fact)));
-  if (matches.length !== 1) {
-    return { ...policy.fallback, policyId: policy.id, target: requestedTarget, contextId: 'context-unmatched' };
-  }
-  const rule = policy.outcomes.find((item) => item.target === requestedTarget && item.contextId === matches[0]!.id);
-  if (!rule) return { ...policy.fallback, policyId: policy.id, target: requestedTarget, contextId: 'context-unmatched' };
-  return { ...rule, policyId: policy.id };
-}
-
-function error(code: string, message: string): OverrideError {
-  return { code, message };
-}
-
-type ParsedHumanOverrideLedger = Readonly<{
-  table: NonNullable<ReturnType<typeof parseTable>>;
-  columns: readonly string[];
-}>;
-
-function parseHumanOverrideLedger(content: string): ParsedHumanOverrideLedger | null {
-  try {
-    const table = parseTable(content, {
-      sectionAliases: HUMAN_OVERRIDE_SECTION_ALIASES,
-      columns: HUMAN_OVERRIDE_COLUMNS,
-      keyColumn: 'id'
-    });
-    return table ? { table, columns: HUMAN_OVERRIDE_COLUMNS } : null;
-  } catch (cause) {
-    if (!(cause instanceof DocumentMutationError) || cause.code !== 'TABLE_NOT_FOUND') throw cause;
-    const table = parseTable(content, {
-      sectionAliases: HUMAN_OVERRIDE_SECTION_ALIASES,
-      columns: LEGACY_HUMAN_OVERRIDE_COLUMNS,
-      keyColumn: 'id'
-    });
-    return table ? { table, columns: LEGACY_HUMAN_OVERRIDE_COLUMNS } : null;
-  }
-}
-
-function escapeTableCell(value: string): string {
-  return value.replace(/\\/g, '\\\\').replace(/\|/g, '\\|');
-}
-
-function migrateHumanOverrideLedger(ledger: ParsedHumanOverrideLedger) {
-  if (ledger.columns.includes(PULL_REQUEST_NUMBER_COLUMN)) return null;
-  const header = `| ${HUMAN_OVERRIDE_COLUMNS.join(' | ')} |`;
-  const separator = `| ${HUMAN_OVERRIDE_COLUMNS.map(() => '---').join(' | ')} |`;
-  const rows = ledger.table.rows.map(({ values }) => `| ${HUMAN_OVERRIDE_COLUMNS
-    .map((column) => escapeTableCell(values[column] ?? ''))
-    .join(' | ')} |`);
-  return {
-    kind: 'section' as const,
-    aliases: HUMAN_OVERRIDE_SECTION_ALIASES,
-    heading: ledger.table.heading,
-    body: [header, separator, ...rows].join('\n')
-  };
-}
-
-function validatePullRequestBinding(
-  policy: FailurePolicy,
-  row: Readonly<Record<string, string>>,
-  request: ConsumeHumanOverrideRequest
-): OverrideError | null {
-  if (policy.producerId !== 'platform.pull-request') return null;
-  const bound = toPositiveInteger(row[PULL_REQUEST_NUMBER_COLUMN]);
-  if (bound === null) {
-    return error('OVERRIDE_RESOURCE_BINDING_MISSING', 'override ticket has no bound pull request number; issue a new ticket');
-  }
-  if (request.pullRequestNumber !== undefined && request.pullRequestNumber !== bound) {
-    return error('OVERRIDE_RESOURCE_MISMATCH', `override ticket is bound to pull request #${bound}`);
-  }
-  return null;
-}
-
-function overrideDryRunConflict(values: Readonly<Record<string, unknown>>): OverrideError | null {
-  const hasOverride = ['overrideTicket', 'overrideTarget', 'overrideScope'].some((key) => values[key] !== undefined && values[key] !== '');
-  return values.dryRun && hasOverride
-    ? error('OVERRIDE_DRY_RUN_CONFLICT', '--dry-run cannot be combined with --override-*')
-    : null;
-}
-
-function resolveTask(taskRef: string, options: HumanOverrideOptions) {
-  return resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
-}
-
-function failedIssue(code: string, message: string, taskId: string | null = null): HumanOverrideIssueResult {
-  return { status: 'failed', changed: false, ticketId: null, taskId, identity: null, error: error(code, message) };
-}
-
-function failedConsume(code: string, message: string, ticketId: string | null = null, taskId: string | null = null): HumanOverrideConsumeResult {
-  return { status: 'failed', changed: false, ticketId, taskId, outcome: null, error: error(code, message) };
-}
-
-function readTask(taskMdPath: string): { content: string; frontmatter: ReturnType<typeof parseTypedTaskFrontmatter> } | OverrideError {
-  try {
-    const content = fs.readFileSync(taskMdPath, 'utf8');
-    const frontmatter = parseTypedTaskFrontmatter(content);
-    return { content, frontmatter };
-  } catch (cause) {
-    return error('OVERRIDE_DOCUMENT_INVALID', cause instanceof Error ? cause.message : String(cause));
-  }
-}
-
-function writeOptions(options: HumanOverrideOptions) {
-  return {
-    repoRoot: options.repoRoot,
-    metadataProvider: options.metadataProvider,
-    randomSuffix: options.randomSuffix,
-    fileSystem: options.taskFileSystem
-  };
-}
-
-function taskWriteError(result: TaskWriteResult): OverrideError | null {
-  return result.status === 'failed' ? error(result.error.code, result.error.message) : null;
-}
-
-type ProducerFailure = Readonly<{
-  code: string;
-  message: string;
-  observedFacts: readonly string[];
-  state: string;
-}>;
-
-function snapshotEvidence(
-  taskId: string,
-  failureIdValue: string,
-  target: string,
-  content: string,
-  frontmatter: Record<string, unknown> | null,
-  producer: ProducerFailure,
-  resource: Readonly<{ kind: 'issue' | 'pull-request'; identity: ResourceIdentity; number: number | null }> | null
-): string {
-  const stableFrontmatter = frontmatter
-    ? Object.fromEntries(Object.entries(frontmatter).filter(([key]) => !['updated_at', 'agent_infra_version', 'status', 'blocked_at', 'completed_at', 'cancelled_at'].includes(key)))
-    : { parse: 'invalid' };
-  return JSON.stringify({
-    taskId,
-    failureId: failureIdValue,
-    target,
-    producer: {
-      code: producer.code,
-      message: producer.message,
-      observedFacts: producer.observedFacts,
-      state: producer.state
-    },
-    resource,
-    stableFrontmatter,
-    activityLogPresent: locateActivityLog(content) !== null
-  });
-}
-
-function resourceForSnapshot(
-  policy: FailurePolicy,
-  options: HumanOverrideOptions,
-  frontmatter: Record<string, unknown> | null
-): Readonly<{ kind: 'issue' | 'pull-request'; identity: ResourceIdentity; number: number | null }> | null {
-  if (policy.producerId === 'platform.issue') {
-    const identity = options.probeIssueNumber !== undefined
-      ? resourceIdentity(options.probeIssueNumber)
-      : taskIssueIdentity((frontmatter || {}) as Record<string, string | number | boolean | null>);
-    return identity ? { kind: 'issue', identity, number: resourceIdentityNumber(identity) } : null;
-  }
-  if (policy.producerId === 'platform.pull-request') {
-    const fact = frontmatter ? readPrDeliveryFact(frontmatter) : null;
-    const identity = options.probePullRequestNumber !== undefined
-      ? resourceIdentity(options.probePullRequestNumber)
-      : fact?.status === 'valid' && fact.fact.state === 'bound' ? fact.fact.identity.resource : null;
-    return identity ? { kind: 'pull-request', identity, number: resourceIdentityNumber(identity) } : null;
-  }
-  return null;
-}
-
-function probeLifecycleFailure(
-  taskRef: string,
-  policy: FailurePolicy,
-  resolved: { taskId: string; state: string },
-  options: HumanOverrideOptions
-): ProducerFailure | OverrideError {
-  if (!options.probeIntent) return error('OVERRIDE_PROBE_INPUT_MISSING', 'an original lifecycle intent is required to prove the producer failure');
-  const request = lifecycleRequestFor(
-    taskRef,
-    options.probeIntent,
-    options.probeOperator ?? 'local-operator',
-    options.probeReason ?? 'human override producer probe',
-    {
-      alert_number: options.probeAlertNumber === undefined ? undefined : String(options.probeAlertNumber),
-      issue_number: options.probeIssueNumber === undefined ? undefined : String(options.probeIssueNumber),
-      staging_dir: options.probeStagingDir
-    }
-  );
-  if ('code' in request) return request;
-  const result = applyTaskLifecycle({ ...request, dryRun: true }, {
-    repoRoot: options.repoRoot,
-    metadataProvider: options.metadataProvider
-  });
-  if (result.status !== 'failed' || result.error?.code !== policy.code) {
-    return error(
-      'OVERRIDE_FAILURE_NOT_PRESENT',
-      `producer probe returned ${result.error?.code ?? 'no failure'}; expected ${policy.code}`
-    );
-  }
-  const identityConfirmed = result.taskId === resolved.taskId;
-  const observedFacts = policy.code === 'SHORT_ID_CAPACITY_EXCEEDED'
-    ? identityConfirmed && ['active', 'blocked'].includes(resolved.state)
-      ? [SHORT_ID_CONFIRMED]
-      : [SHORT_ID_UNCONFIRMED]
-    : identityConfirmed ? ['identity-confirmed'] : [];
-  return {
-    code: result.error.code,
-    message: result.error.message,
-    observedFacts,
-    state: result.sourceState ?? resolved.state
-  };
-}
-
-type ProbeTask = Readonly<{
-  taskId: string;
-  state: string;
-  taskDir: string;
-  repoRoot: string;
-}>;
-
-function probeResult(
-  policy: FailurePolicy,
-  result: unknown,
-  state: string
-): ProducerFailure | null {
-  if (!result || typeof result !== 'object') return null;
-  const errorValue = (result as { error?: unknown }).error;
-  if (!errorValue || typeof errorValue !== 'object') return null;
-  const code = String((errorValue as { code?: unknown }).code ?? '');
-  if (code !== policy.code) return null;
-  return {
-    code,
-    message: String((errorValue as { message?: unknown }).message ?? code),
-    observedFacts: ['guard-observed'],
-    state
-  };
-}
-
-function probeNotObserved(policy: FailurePolicy): OverrideError {
-  return error('OVERRIDE_FAILURE_NOT_PRESENT', `producer ${policy.producerId} did not produce ${policy.code}`);
-}
-
-async function probePlatformFailure(
-  taskRef: string,
-  policy: FailurePolicy,
-  resolved: ProbeTask,
-  options: HumanOverrideOptions
-): Promise<ProducerFailure | OverrideError> {
-  let frontmatter: ReturnType<typeof parseTypedTaskFrontmatter>;
-  try {
-    frontmatter = parseTypedTaskFrontmatter(fs.readFileSync(path.join(resolved.taskDir, 'task.md'), 'utf8'));
-  } catch (cause) {
-    return error('OVERRIDE_DOCUMENT_INVALID', cause instanceof Error ? cause.message : String(cause));
-  }
-  const issueIdentity = options.probeIssueNumber !== undefined
-    ? resourceIdentity(options.probeIssueNumber)
-    : taskIssueIdentity(frontmatter);
-  const fact = readPrDeliveryFact(frontmatter);
-  if (fact.status === 'invalid') {
-    return error(fact.error.code, fact.error.message);
-  }
-  const pullRequestIdentity = options.probePullRequestNumber !== undefined
-    ? resourceIdentity(options.probePullRequestNumber)
-    : fact.status === 'valid' && fact.fact.state === 'bound' ? fact.fact.identity.resource : null;
-  const token = (identity: ResourceIdentity | null): string | null => identity ? String(identity.value) : null;
-  const issueToken = token(issueIdentity);
-  const pullRequestToken = token(pullRequestIdentity);
-  const operation = await (policy.producerId === 'platform.issue'
-    ? issueToken === null
-      ? null
-      : bindPlatformIssue(taskRef, {
-        issue: issueToken,
-        agent: options.probeOperator ?? 'local-operator',
-        dryRun: true,
-        cwd: resolved.repoRoot,
-        ...(options.platformClient ? { client: options.platformClient } : {})
-      })
-    : pullRequestToken === null
-      ? null
-      : bindPlatformPullRequest(taskRef, {
-        pr: pullRequestToken,
-        agent: options.probeOperator ?? 'local-operator',
-        dryRun: true,
-        cwd: resolved.repoRoot,
-        ...(options.platformClient ? { client: options.platformClient } : {})
-      })
-  );
-  if (!operation) return error('OVERRIDE_PROBE_INPUT_MISSING', `${policy.producerId} requires a bound issue or pull request identity`);
-  if (operation.status !== 'failed' && operation.status !== 'blocked') return probeNotObserved(policy);
-  if (!operation.error) return error('OVERRIDE_PROBE_INPUT_MISSING', `${policy.producerId} returned no platform error evidence`);
-  return {
-    code: policy.code,
-    message: `${operation.error.code}: ${operation.error.message}`,
-    observedFacts: ['guard-observed'],
-    state: resolved.state
-  };
-}
-
-function toPositiveInteger(value: unknown): number | null {
-  const number = typeof value === 'number' ? value : Number(value);
-  return Number.isSafeInteger(number) && number > 0 ? number : null;
-}
-
-function probeTaskEventFailure(taskRef: string, policy: FailurePolicy, resolved: ProbeTask): ProducerFailure | OverrideError {
-  const starts = [
-    'analyze.started', 'review-analysis.started', 'plan.started', 'review-plan.started',
-    'code.started', 'review-code.started', 'manual-validation.started', 'validation-run.started'
-  ];
-  const completions = [
-    ['analyze.completed', 'analysis.md'],
-    ['review-analysis.completed', 'review-analysis.md'],
-    ['plan.completed', 'plan.md'],
-    ['review-plan.completed', 'review-plan.md'],
-    ['code.completed', 'code.md'],
-    ['review-code.completed', 'review-code.md']
-  ] as const;
-  const candidates: Array<{ event: string; artifact?: string }> = policy.code === 'EVENT_START_MISSING'
-    ? completions.map(([event, artifact]) => ({ event, artifact }))
-    : starts.map((event) => ({ event }));
-  for (const candidate of candidates) {
-    const result = applyTaskEvent({
-      taskRef,
-      event: candidate.event,
-      agent: 'codex',
-      dryRun: true,
-      initiator: 'model',
-      requestId: `override-probe:${taskRef}:${candidate.event}`,
-      reasonCode: 'user-request',
-      ...(candidate.artifact ? { artifact: candidate.artifact } : {})
-    }, { repoRoot: resolved.repoRoot, lockAlreadyHeld: true });
-    const matched = probeResult(policy, result, resolved.state);
-    if (matched) return matched;
-  }
-  return probeNotObserved(policy);
-}
-
-async function probeVerificationFailure(taskRef: string, policy: FailurePolicy, resolved: ProbeTask): Promise<ProducerFailure | OverrideError> {
-  const result = await verifyTaskEvent(
-    {
-      taskRef,
-      event: 'review-code.completed',
-      artifact: policy.code === 'VERIFY_ARTIFACT_INVALID' ? 'invalid-artifact.md' : 'review-code.md'
-    },
-    { repoRoot: resolved.repoRoot }
-  );
-  const matched = probeResult(policy, result, resolved.state);
-  return matched ?? probeNotObserved(policy);
-}
-
-function latestArtifact(taskDir: string, family: string): string | undefined {
-  let names: string[];
-  try { names = fs.readdirSync(taskDir); } catch { return undefined; }
-  return names.map(parseArtifactName).filter((identity) => identity !== null)
-    .filter((identity) => identity.family === family).sort((left, right) => right.round - left.round)[0]?.name;
-}
-
-async function probeVerificationEngineFailure(policy: FailurePolicy, resolved: ProbeTask): Promise<ProducerFailure | OverrideError> {
-  const candidates = [
-    { skillName: 'review-code', family: 'review-code' },
-    { skillName: 'review-plan', family: 'review-plan' },
-    { skillName: 'review-analysis', family: 'review-analysis' },
-    { skillName: 'code-task', family: 'code' },
-    { skillName: 'plan-task', family: 'plan' },
-    { skillName: 'analyze-task', family: 'analysis' },
-    { skillName: 'complete-task', family: null }
-  ];
-  for (const candidate of candidates) {
-    const artifactFile = candidate.family ? latestArtifact(resolved.taskDir, candidate.family) : undefined;
-    if (candidate.family && !artifactFile) continue;
-    try {
-      const payload = await verifyInProcess({
-        mode: 'gate',
-        skillName: candidate.skillName,
-        taskDir: resolved.taskDir,
-        artifactFile,
-        checks: [],
-        repositoryRoot: resolved.repoRoot
-      }) as { gate?: unknown };
-      const code = payload.gate === 'blocked' ? 'CHECK_BLOCKED' : payload.gate === 'fail' ? 'CHECK_FAILED' : '';
-      if (code === policy.code) {
-        return {
-          code,
-          message: `${candidate.skillName} verification gate returned ${payload.gate}`,
-          observedFacts: ['guard-observed'],
-          state: resolved.state
-        };
-      }
-    } catch {
-      // A probe failure is not evidence that the requested verification failure occurred.
-    }
-  }
-  return probeNotObserved(policy);
-}
-
-async function probeGenericFailure(
-  taskRef: string,
-  policy: FailurePolicy,
-  resolved: ProbeTask,
-  options: HumanOverrideOptions = {}
-): Promise<ProducerFailure | OverrideError> {
-  switch (policy.producerId) {
-    case 'task.resolve':
-      return probeNotObserved(policy);
-    case 'task.write':
-      return probeResult(policy, writeTask({ taskRef, expectedState: 'active', mutations: [], dryRun: true }, { repoRoot: resolved.repoRoot }), resolved.state) ?? probeNotObserved(policy);
-    case 'task-event':
-      return probeTaskEventFailure(taskRef, policy, resolved);
-    case 'task-verify':
-      return await probeVerificationFailure(taskRef, policy, resolved);
-    case 'verification-engine':
-      return await probeVerificationEngineFailure(policy, resolved);
-    case 'activity-intent':
-      return probeResult(policy, applyPrReviewActivityIntent({
-        kind: 'pr-review-start', taskRef, agent: 'codex', artifact: 'pr-review.md', head: '0'.repeat(40), dryRun: true
-      }, { repoRoot: resolved.repoRoot, lockAlreadyHeld: true }), resolved.state) ?? probeNotObserved(policy);
-    case 'ledger-intent':
-      return probeResult(policy, applyLedgerIntent({
-        kind: 'finding-respond', taskRef, id: 'CD-1', round: 1, status: 'accepted', evidence: 'review-code.md#CD-1', dryRun: true
-      }), resolved.state) ?? probeNotObserved(policy);
-    case 'decision-intent':
-      return probeResult(policy, applyHumanDecision({ taskRef, selector: 'CD-1', decision: 'probe', dryRun: true }), resolved.state) ?? probeNotObserved(policy);
-    case 'workflow-warning':
-      return probeResult(policy, applyWorkflowWarningIntent({
-        kind: 'add', taskRef, step: 'probe', severity: 'IMPORTANT', code: 'PROBE', target: 'probe', message: 'probe', action: 'probe', dryRun: true
-      }), resolved.state) ?? probeNotObserved(policy);
-    case 'review-finalization':
-      return probeResult(policy, finalizeReviewSummary({
-        taskRef, stage: 'code', artifact: 'review-code.md', dryRun: true
-      }, { repoRoot: resolved.repoRoot, lockAlreadyHeld: true }), resolved.state) ?? probeNotObserved(policy);
-    case 'lifecycle-execution': {
-      const identities = {
-        stage: 'code' as const, round: 1, artifact: 'code.md', role: 'executor' as const
-      };
-      const results = [
-        inspectLifecycleExecution(taskRef, { mode: 'standalone', identity: identities, dryRun: true }, { repoRoot: resolved.repoRoot }),
-        inspectLifecycleExecution(taskRef, { mode: 'orchestrated', identity: identities, dryRun: true }, { repoRoot: resolved.repoRoot })
-      ];
-      for (const result of results) {
-        const matched = probeResult(policy, result, resolved.state);
-        if (matched) return matched;
-      }
-      return probeNotObserved(policy);
-    }
-    case 'platform.issue':
-    case 'platform.pull-request':
-      return await probePlatformFailure(taskRef, policy, resolved, options);
-    default:
-      return error('OVERRIDE_PROBE_INPUT_MISSING', `no producer probe is registered for ${policy.producerId}`);
-  }
-}
-
-function isProducerFailure(value: ProducerFailure | OverrideError): value is ProducerFailure {
-  return 'observedFacts' in value && 'state' in value && Array.isArray(value.observedFacts);
-}
-
-async function captureFailureSnapshot(taskRef: string, failureIdValue: string, target: string, options: HumanOverrideOptions = {}): Promise<FailureSnapshot | OverrideError> {
-  const policy = policyFor(failureIdValue);
-  if (!policy) return error('OVERRIDE_FAILURE_UNKNOWN', `failure policy '${failureIdValue}' is not registered`);
-  if (!policy.targets.includes(target)) return error('OVERRIDE_TARGET_INVALID', `target '${target}' is not registered for ${failureIdValue}`);
-  const resolved = resolveTask(taskRef, options);
-  if (!resolved.ok) return error(resolved.code, resolved.message);
-  let content: string;
-  try {
-    content = fs.readFileSync(resolved.taskMdPath, 'utf8');
-  } catch (cause) {
-    return error('OVERRIDE_DOCUMENT_INVALID', cause instanceof Error ? cause.message : String(cause));
-  }
-  let frontmatter: Record<string, unknown> | null = null;
-  try { frontmatter = parseTypedTaskFrontmatter(content); } catch { /* probe reports an unconfirmed identity */ }
-  const producer: ProducerFailure | OverrideError = policy.producerId === LIFECYCLE_PRODUCER
-    ? probeLifecycleFailure(taskRef, policy, resolved, options)
-    : await probeGenericFailure(taskRef, policy, resolved, options);
-  if (!isProducerFailure(producer)) return producer;
-  const digest = computeFailureDigest(snapshotEvidence(
-    resolved.taskId,
-    failureIdValue,
-    target,
-    content,
-    frontmatter,
-    producer,
-    resourceForSnapshot(policy, options, frontmatter)
-  ));
-  const [producerId, ...codeParts] = failureIdValue.split(':');
-  const code = codeParts.join(':');
-  return {
-    schema: '1',
-    taskId: resolved.taskId,
-    failureId: failureIdValue,
-    producerId: producerId ?? '',
-    code,
-    target,
-    state: producer.state,
-    digest,
-    observedFacts: producer.observedFacts,
-    message: producer.message,
-    capturedAt: (options.now ?? canonicalTimestamp)(),
-    source: 'producer-result'
-  };
-}
-
-function isOverrideError(value: FailureSnapshot | OverrideError): value is OverrideError {
-  return !('schema' in value);
-}
-
-function validateSnapshot(snapshot: FailureSnapshot, expected: FailureSnapshot): OverrideError | null {
-  if (
-    snapshot.schema !== '1' || snapshot.source !== 'producer-result' ||
-    snapshot.taskId !== expected.taskId || snapshot.failureId !== expected.failureId ||
-    snapshot.producerId !== expected.producerId || snapshot.code !== expected.code ||
-    snapshot.target !== expected.target || snapshot.digest !== expected.digest ||
-    snapshot.state !== expected.state || snapshot.message !== expected.message ||
-    snapshot.observedFacts.length !== expected.observedFacts.length ||
-    snapshot.observedFacts.some((fact, index) => fact !== expected.observedFacts[index])
-  ) return error('OVERRIDE_SNAPSHOT_MISMATCH', 'failure snapshot is not the canonical producer probe result');
-  return null;
-}
-
-function validateCommon(request: HumanOverrideRequest): OverrideError | null {
-  const fields = [request.taskRef, request.failureId, request.target, request.operator, request.reason, request.scope, request.expiresAt];
-  if (fields.some((value) => !singleLine(value))) return error('OVERRIDE_PAYLOAD_INVALID', 'override fields must be non-empty single-line values');
-  if (request.identitySource !== undefined && request.identitySource !== 'local-declared') {
-    return error('OVERRIDE_IDENTITY_SOURCE_INVALID', 'the local override entrypoint owns identity_source=local-declared');
-  }
-  return null;
-}
-
-function validateResourceNumbers(request: HumanOverrideRequest): OverrideError | null {
-  const values = [
-    ['alertNumber', request.alertNumber],
-    ['issueNumber', request.issueNumber],
-    ['pullRequestNumber', request.pullRequestNumber]
-  ] as const;
-  for (const [name, value] of values) {
-    if (value !== undefined && (!Number.isSafeInteger(value) || value <= 0)) {
-      return error('OVERRIDE_RESOURCE_INVALID', `${name} must be a safe positive integer`);
-    }
-  }
-  return null;
-}
-
-async function issueHumanOverride(request: HumanOverrideRequest, options: HumanOverrideOptions = {}): Promise<HumanOverrideIssueResult> {
-  const invalid = validateCommon(request);
-  if (invalid) return failedIssue(invalid.code, invalid.message);
-  const policy = policyFor(request.failureId);
-  if (!policy) return failedIssue('OVERRIDE_FAILURE_UNKNOWN', `failure policy '${request.failureId}' is not registered`);
-  if (!policy.targets.includes(request.target)) return failedIssue('OVERRIDE_TARGET_INVALID', `target '${request.target}' is not registered for ${request.failureId}`);
-  const invalidResource = validateResourceNumbers(request);
-  if (invalidResource) return failedIssue(invalidResource.code, invalidResource.message);
-  const recordOnly = policy.outcomes.some((rule) => rule.target === request.target && rule.effect === 'record-only' && rule.result === 'preserve-failure');
-  if (policy.eligibility === 'never-overridable' && !recordOnly) return failedIssue('OVERRIDE_NOT_ELIGIBLE', `failure '${request.failureId}' is never overridable`);
-  const issuedAt = (options.now ?? canonicalTimestamp)();
-  const issuedMs = Date.parse(issuedAt);
-  const expiresMs = Date.parse(request.expiresAt);
-  if (!Number.isFinite(issuedMs) || !Number.isFinite(expiresMs) || expiresMs <= issuedMs) {
-    return failedIssue('OVERRIDE_EXPIRY_INVALID', 'expiresAt must be a valid time after issuedAt');
-  }
-  const resolved = resolveTask(request.taskRef, options);
-  if (!resolved.ok) return failedIssue(resolved.code, resolved.message, resolved.taskId);
-  const document = readTask(resolved.taskMdPath);
-  if ('code' in document) return failedIssue(document.code, document.message, resolved.taskId);
-  if (document.frontmatter.id !== resolved.taskId) return failedIssue('OVERRIDE_DOCUMENT_INVALID', 'task frontmatter id does not match resolved task', resolved.taskId);
-  const snapshotResult = await captureFailureSnapshot(request.taskRef, request.failureId, request.target, {
-    ...options,
-    probeIntent: request.intent,
-    probeOperator: request.operator,
-    probeReason: request.reason,
-    probeAlertNumber: request.alertNumber,
-    probeIssueNumber: request.issueNumber,
-    probePullRequestNumber: request.pullRequestNumber,
-    probeStagingDir: request.stagingDir
-  });
-  if (isOverrideError(snapshotResult)) return failedIssue(snapshotResult.code, snapshotResult.message, resolved.taskId);
-  const snapshot = snapshotResult as FailureSnapshot;
-  if (request.failureSnapshot) {
-    const snapshotError = validateSnapshot(request.failureSnapshot, snapshot);
-    if (snapshotError) return failedIssue(snapshotError.code, snapshotError.message, resolved.taskId);
-  }
-  if (request.failureDigest !== undefined && request.failureDigest !== snapshot.digest) {
-    return failedIssue('OVERRIDE_DIGEST_MISMATCH', 'caller-provided failure digest does not match the producer probe', resolved.taskId);
-  }
-  let ledger: ParsedHumanOverrideLedger | null = null;
-  try {
-    ledger = parseHumanOverrideLedger(document.content);
-  } catch (cause) {
-    return failedIssue('OVERRIDE_DOCUMENT_INVALID', cause instanceof Error ? cause.message : String(cause), resolved.taskId);
-  }
-  const ticketId = (options.randomId ?? randomUUID)();
-  if (!singleLine(ticketId)) return failedIssue('OVERRIDE_PAYLOAD_INVALID', 'ticket id generator returned an invalid id', resolved.taskId);
-  const mutations = [] as Array<
-    | { kind: 'section'; aliases: readonly string[]; heading: string; body: string }
-    | { kind: 'table-row'; sectionAliases: readonly string[]; columns: readonly string[]; keyColumn: string; key: string; action: 'upsert'; values: Readonly<Record<string, string>> }
-  >;
-  if (!ledger) {
-    const header = `| ${HUMAN_OVERRIDE_COLUMNS.join(' | ')} |`;
-    const separator = `| ${HUMAN_OVERRIDE_COLUMNS.map(() => '---').join(' | ')} |`;
-    mutations.push({
-      kind: 'section',
-      aliases: HUMAN_OVERRIDE_SECTION_ALIASES,
-      heading: 'Human Override Ledger',
-      body: `${header}\n${separator}`
-    });
-  } else {
-    const migration = migrateHumanOverrideLedger(ledger);
-    if (migration) mutations.push(migration);
-  }
-  const [producerId, ...codeParts] = request.failureId.split(':');
-  const code = codeParts.join(':');
-  mutations.push({
-    kind: 'table-row',
-    sectionAliases: HUMAN_OVERRIDE_SECTION_ALIASES,
-    columns: HUMAN_OVERRIDE_COLUMNS,
-    keyColumn: 'id',
-    key: ticketId,
-    action: 'upsert',
-    values: {
-      schema: '1',
-      failure_id: request.failureId,
-      producer_id: producerId ?? '',
-      code,
-      target: request.target,
-      operator: request.operator,
-      identity_source: 'local-declared',
-      verified: 'false',
-      reason: request.reason,
-      scope: request.scope,
-      intent: request.intent ?? '',
-      failure_message: snapshot.message,
-      failure_digest: snapshot.digest,
-      context_id: snapshot.observedFacts[0] ?? 'context-unmatched',
-      effect: '',
-      source_state: resolved.state,
-      issued_at: issuedAt,
-      expires_at: request.expiresAt,
-      status: 'issued',
-      result: '',
-      consumed_at: '',
-      residual: '',
-      alert_number: request.alertNumber === undefined ? '' : String(request.alertNumber),
-      issue_number: request.issueNumber === undefined ? '' : String(request.issueNumber),
-      pull_request_number: request.pullRequestNumber === undefined ? '' : String(request.pullRequestNumber),
-      staging_dir: request.stagingDir ?? ''
-    }
-  });
-  const result = writeTask({ taskRef: request.taskRef, expectedState: resolved.state, mutations }, writeOptions(options));
-  const writeError = taskWriteError(result);
-  if (writeError) return failedIssue(writeError.code, writeError.message, resolved.taskId);
-  if (result.status === 'failed') return failedIssue(result.error.code, result.error.message, resolved.taskId);
-  if (result.status === 'planned') return failedIssue('OVERRIDE_WRITE_INVALID', 'override writes cannot be planned', resolved.taskId);
-  return {
-    status: result.status,
-    changed: result.changed,
-    ticketId,
-    taskId: resolved.taskId,
-    identity: { source: 'local-declared', operator: request.operator, verified: false },
-    error: null
-  };
-}
-
-function lifecycleRequestFor(
-  taskRef: string,
-  intent: string,
-  operator: string,
-  reason: string,
-  values: Readonly<Record<string, string | undefined>> = {}
-): TaskLifecycleRequest | OverrideError {
-  if (!['block', 'activate', 'cancel', 'complete', 'restore', 'close-codescan', 'close-dependabot'].includes(intent)) {
-    return error('OVERRIDE_EFFECT_INPUT_MISSING', 'a lifecycle intent is required to apply this override outcome');
-  }
-  if (intent === 'block') return { taskRef, intent: 'block', agent: operator, reason, unblockCondition: 'manual override recovery' };
-  if (intent === 'activate') return { taskRef, intent: 'activate', agent: operator, note: `manual override: ${reason}` };
-  if (intent === 'cancel') return { taskRef, intent: 'cancel', agent: operator, reason };
-  if (intent === 'complete') return { taskRef, intent: 'complete', agent: operator };
-  if (intent === 'close-codescan' || intent === 'close-dependabot') {
-    const alertNumber = Number(values.alert_number);
-    if (!Number.isSafeInteger(alertNumber) || alertNumber < 1) return error('OVERRIDE_EFFECT_INPUT_MISSING', `${intent} requires the original alert number`);
-    return { taskRef, intent, agent: operator, alertNumber, reason };
-  }
-  const issueNumber = Number(values.issue_number);
-  const stagingDir = values.staging_dir;
-  if (!Number.isSafeInteger(issueNumber) || issueNumber < 1 || !stagingDir) return error('OVERRIDE_EFFECT_INPUT_MISSING', 'restore requires the original staging directory and issue number');
-  return { taskRef, intent: 'restore', agent: operator, stagingDir, issueNumber };
-}
-
-async function applyOutcomeEffect(
-  request: ConsumeHumanOverrideRequest,
-  row: Readonly<Record<string, string>>,
-  snapshot: FailureSnapshot,
-  outcome: Outcome,
-  options: HumanOverrideOptions
-): Promise<OverrideError | null> {
-  if (outcome.effect === 'no-write' || outcome.effect === 'record-only') return null;
-  const intent = outcome.target === 'safe-close' ? 'cancel' : row.intent || request.intent;
-  if (!intent && outcome.target === 'continue-local') {
-    if (!options.effectExecutor) return error('OVERRIDE_EFFECT_EXECUTOR_MISSING', 'the producer must supply an effect executor for a continue-local outcome');
-    return await options.effectExecutor({
-      failureId: request.failureId,
-      operator: row.operator ?? 'local-operator',
-      reason: row.reason ?? snapshot.message
-    });
-  }
-  if (!intent) return error('OVERRIDE_EFFECT_INPUT_MISSING', 'the ticket has no original lifecycle intent for its retry effect');
-  const lifecycleRequest = lifecycleRequestFor(request.taskRef, intent, row.operator ?? 'local-operator', row.reason ?? snapshot.message, row);
-  if ('code' in lifecycleRequest) return lifecycleRequest;
-  const result = applyTaskLifecycle(lifecycleRequest, {
-    repoRoot: options.repoRoot,
-    metadataProvider: options.metadataProvider,
-    manualOverride: { failureId: request.failureId, operator: row.operator ?? 'local-operator', reason: row.reason ?? snapshot.message }
-  });
-  if (result.status === 'failed') {
-    return error('OVERRIDE_EFFECT_FAILED', `${result.error?.code ?? 'LIFECYCLE_FAILED'}: ${result.error?.message ?? 'manual outcome effect failed'}`);
-  }
-  return null;
-}
-
-function ticketMutation(
-  ticketId: string,
-  row: Readonly<Record<string, string>>,
-  outcome: Outcome,
-  status: 'consuming' | 'consumed',
-  timestamp: string,
-  residual: string,
-  columns: readonly string[]
-) {
-  const values: Record<string, string> = {
-    schema: row.schema ?? '',
-    failure_id: row.failure_id ?? '',
-    producer_id: row.producer_id ?? '',
-    code: row.code ?? '',
-    target: row.target ?? '',
-    operator: row.operator ?? '',
-    identity_source: row.identity_source ?? '',
-    verified: row.verified ?? '',
-    reason: row.reason ?? '',
-    scope: row.scope ?? '',
-    intent: row.intent ?? '',
-    failure_message: row.failure_message ?? '',
-    failure_digest: row.failure_digest ?? '',
-    context_id: outcome.contextId,
-    effect: outcome.effect,
-    source_state: row.source_state ?? '',
-    issued_at: row.issued_at ?? '',
-    expires_at: row.expires_at ?? '',
-    status,
-    result: outcome.result,
-    consumed_at: status === 'consumed' ? timestamp : '',
-    residual,
-    alert_number: row.alert_number ?? '',
-    issue_number: row.issue_number ?? '',
-    staging_dir: row.staging_dir ?? ''
-  };
-  if (columns.includes(PULL_REQUEST_NUMBER_COLUMN)) values[PULL_REQUEST_NUMBER_COLUMN] = row[PULL_REQUEST_NUMBER_COLUMN] ?? '';
-  return {
-    kind: 'table-row' as const,
-    sectionAliases: HUMAN_OVERRIDE_SECTION_ALIASES,
-    columns,
-    keyColumn: 'id',
-    key: ticketId,
-    action: 'upsert' as const,
-    values
-  };
-}
-
-function outcomeFromConsumingRow(policy: FailurePolicy, row: Readonly<Record<string, string>>, target: string): Outcome | OverrideError {
-  const contextId = row.context_id;
-  if (!contextId || !row.effect || !row.result || !row.residual) {
-    return error('OVERRIDE_RECOVERY_INVALID', 'consuming override ticket has incomplete effect state');
-  }
-  const outcome = resolveOutcome(policy, target, [contextId]);
-  if (
-    outcome.contextId !== contextId || outcome.effect !== row.effect || outcome.result !== row.result ||
-    outcome.residual !== row.residual.replace(/^effect pending: /, '')
-  ) {
-    return error('OVERRIDE_RECOVERY_INVALID', 'consuming override ticket does not match its registered outcome');
-  }
-  return outcome;
-}
-
-function snapshotFromTicket(taskId: string, row: Readonly<Record<string, string>>): FailureSnapshot | OverrideError {
-  const [producerId, ...codeParts] = (row.failure_id ?? '').split(':');
-  if (!producerId || codeParts.length === 0 || !row.failure_digest || !row.failure_message || !row.source_state) {
-    return error('OVERRIDE_RECOVERY_INVALID', 'consuming override ticket has incomplete failure evidence');
-  }
-  return {
-    schema: '1',
-    taskId,
-    failureId: row.failure_id,
-    producerId,
-    code: codeParts.join(':'),
-    target: row.target,
-    state: row.source_state,
-    digest: row.failure_digest,
-    observedFacts: row.context_id ? [row.context_id] : [],
-    message: row.failure_message,
-    capturedAt: row.issued_at,
-    source: 'producer-result'
-  };
-}
-
-async function consumeHumanOverride(request: ConsumeHumanOverrideRequest, options: HumanOverrideOptions = {}): Promise<HumanOverrideConsumeResult> {
-  const values = [request.taskRef, request.ticketId, request.failureId, request.target, request.scope];
-  if (values.some((value) => !singleLine(value))) {
-    return failedConsume('OVERRIDE_PAYLOAD_INVALID', 'consume fields must be non-empty single-line values', request.ticketId || null);
-  }
-  const policy = policyFor(request.failureId);
-  if (!policy) return failedConsume('OVERRIDE_FAILURE_UNKNOWN', `failure policy '${request.failureId}' is not registered`, request.ticketId);
-  if (!policy.targets.includes(request.target)) return failedConsume('OVERRIDE_TARGET_INVALID', `target '${request.target}' is not registered for ${request.failureId}`, request.ticketId);
-  const resolved = resolveTask(request.taskRef, options);
-  if (!resolved.ok) return failedConsume(resolved.code, resolved.message, request.ticketId, resolved.taskId);
-  const document = readTask(resolved.taskMdPath);
-  if ('code' in document) return failedConsume(document.code, document.message, request.ticketId, resolved.taskId);
-  if (document.frontmatter.id !== resolved.taskId) return failedConsume('OVERRIDE_DOCUMENT_INVALID', 'task frontmatter id does not match resolved task', request.ticketId, resolved.taskId);
-  let ledger: ParsedHumanOverrideLedger | null;
-  try {
-    ledger = parseHumanOverrideLedger(document.content);
-  } catch (cause) {
-    return failedConsume('OVERRIDE_DOCUMENT_INVALID', cause instanceof Error ? cause.message : String(cause), request.ticketId, resolved.taskId);
-  }
-  if (!ledger) return failedConsume('OVERRIDE_NOT_FOUND', `override ledger is missing for ticket '${request.ticketId}'`, request.ticketId, resolved.taskId);
-  const row = ledger.table.rows.find((item) => item.values.id === request.ticketId);
-  if (!row) return failedConsume('OVERRIDE_NOT_FOUND', `override ticket '${request.ticketId}' was not found`, request.ticketId, resolved.taskId);
-  if (row.values.status === 'consumed') return failedConsume('OVERRIDE_REPLAY', `override ticket '${request.ticketId}' was already consumed`, request.ticketId, resolved.taskId);
-  const recovering = row.values.status === 'consuming';
-  if (row.values.status !== 'issued' && !recovering) return failedConsume('OVERRIDE_STATUS_INVALID', `override ticket '${request.ticketId}' is not issued`, request.ticketId, resolved.taskId);
-  if (row.values.failure_id !== request.failureId) return failedConsume('OVERRIDE_FAILURE_MISMATCH', 'ticket failure identity does not match consume request', request.ticketId, resolved.taskId);
-  if (row.values.target !== request.target) return failedConsume('OVERRIDE_TARGET_INVALID', 'ticket target does not match consume request', request.ticketId, resolved.taskId);
-  if (row.values.scope !== request.scope) return failedConsume('OVERRIDE_SCOPE_MISMATCH', 'ticket scope does not match consume request', request.ticketId, resolved.taskId);
-  const resourceError = validatePullRequestBinding(policy, row.values, request);
-  if (resourceError) return failedConsume(resourceError.code, resourceError.message, request.ticketId, resolved.taskId);
-  let snapshot: FailureSnapshot;
-  if (recovering) {
-    const recoverySnapshot = snapshotFromTicket(resolved.taskId, row.values);
-    if (isOverrideError(recoverySnapshot)) return failedConsume(recoverySnapshot.code, recoverySnapshot.message, request.ticketId, resolved.taskId);
-    snapshot = recoverySnapshot;
-  } else {
-    const snapshotResult = await captureFailureSnapshot(request.taskRef, request.failureId, request.target, {
-      ...options,
-      probeIntent: row.values.intent ? row.values.intent as TaskLifecycleIntent : request.intent,
-      probeOperator: row.values.operator,
-      probeReason: row.values.reason,
-      probeAlertNumber: row.values.alert_number ? Number(row.values.alert_number) : undefined,
-      probeIssueNumber: row.values.issue_number ? Number(row.values.issue_number) : undefined,
-      probePullRequestNumber: row.values.pull_request_number ? Number(row.values.pull_request_number) : undefined,
-      probeStagingDir: row.values.staging_dir || undefined
-    });
-    if (isOverrideError(snapshotResult)) return failedConsume(snapshotResult.code, snapshotResult.message, request.ticketId, resolved.taskId);
-    snapshot = snapshotResult as FailureSnapshot;
-    if (request.failureSnapshot) {
-      const snapshotError = validateSnapshot(request.failureSnapshot, snapshot);
-      if (snapshotError) return failedConsume(snapshotError.code, snapshotError.message, request.ticketId, resolved.taskId);
-    }
-    if (request.failureDigest !== undefined && request.failureDigest !== snapshot.digest) return failedConsume('OVERRIDE_DIGEST_MISMATCH', 'caller-provided failure digest does not match the producer result', request.ticketId, resolved.taskId);
-    if (row.values.failure_digest !== snapshot.digest) return failedConsume('OVERRIDE_DIGEST_MISMATCH', 'ticket failure digest does not match the producer result', request.ticketId, resolved.taskId);
-    if (request.observedFacts && (request.observedFacts.length !== snapshot.observedFacts.length || request.observedFacts.some((fact, index) => fact !== snapshot.observedFacts[index]))) {
-      return failedConsume('OVERRIDE_FACTS_MISMATCH', 'caller-provided facts do not match the producer result', request.ticketId, resolved.taskId);
-    }
-    if (row.values.source_state && row.values.source_state !== snapshot.state) {
-      return failedConsume('OVERRIDE_SNAPSHOT_STALE', 'the task no longer has the state captured when the ticket was issued', request.ticketId, resolved.taskId);
-    }
-  }
-  const now = (options.now ?? canonicalTimestamp)();
-  const nowMs = Date.parse(now);
-  const expiresMs = Date.parse(row.values.expires_at ?? '');
-  if (!recovering && (!Number.isFinite(nowMs) || !Number.isFinite(expiresMs) || expiresMs <= nowMs)) return failedConsume('OVERRIDE_EXPIRED', `override ticket '${request.ticketId}' is expired`, request.ticketId, resolved.taskId);
-  const resolvedOutcome = recovering ? outcomeFromConsumingRow(policy, row.values, request.target) : resolveOutcome(policy, request.target, snapshot.observedFacts);
-  if ('code' in resolvedOutcome) return failedConsume(resolvedOutcome.code, resolvedOutcome.message, request.ticketId, resolved.taskId);
-  const outcome = resolvedOutcome;
-  let effectRow = row.values;
-  if (!recovering && outcome.effect !== 'no-write' && outcome.effect !== 'record-only') {
-    const staged = writeTask({
-      taskRef: request.taskRef,
-      expectedState: resolved.state,
-      mutations: [ticketMutation(request.ticketId, row.values, outcome, 'consuming', now, `effect pending: ${outcome.residual}`, ledger.columns)]
-    }, writeOptions(options));
-    const stagedError = taskWriteError(staged);
-    if (stagedError) return failedConsume(stagedError.code, stagedError.message, request.ticketId, resolved.taskId);
-    if (staged.status === 'failed') return failedConsume(staged.error.code, staged.error.message, request.ticketId, resolved.taskId);
-    if (staged.status === 'planned') return failedConsume('OVERRIDE_WRITE_INVALID', 'override writes cannot be planned', request.ticketId, resolved.taskId);
-    effectRow = { ...row.values, status: 'consuming', effect: outcome.effect, result: outcome.result, context_id: outcome.contextId, residual: `effect pending: ${outcome.residual}` };
-  }
-  const effectError = await applyOutcomeEffect(request, effectRow, snapshot, outcome, options);
-  if (effectError) return failedConsume(effectError.code, effectError.message, request.ticketId, resolved.taskId);
-  const after = resolveTask(request.taskRef, options);
-  if (!after.ok) return failedConsume(after.code, after.message, request.ticketId, after.taskId);
-  const mutation = ticketMutation(request.ticketId, effectRow, outcome, 'consumed', now, outcome.residual, ledger.columns);
-  const result = writeTask({ taskRef: request.taskRef, expectedState: after.state, mutations: [mutation] }, writeOptions(options));
-  const writeError = taskWriteError(result);
-  if (writeError) return failedConsume(writeError.code, writeError.message, request.ticketId, resolved.taskId);
-  if (result.status === 'failed') return failedConsume(result.error.code, result.error.message, request.ticketId, resolved.taskId);
-  if (result.status === 'planned') return failedConsume('OVERRIDE_WRITE_INVALID', 'override writes cannot be planned', request.ticketId, resolved.taskId);
-  return {
-    status: result.status,
-    changed: result.changed,
-    ticketId: request.ticketId,
-    taskId: resolved.taskId,
-    outcome,
-    ...(outcome.effect !== 'record-only' && outcome.effect !== 'no-write'
-      ? { manualOverride: { failureId: request.failureId, operator: row.values.operator ?? 'local-operator', reason: row.values.reason ?? snapshot.message } }
-      : {}),
-    error: null
-  };
-}
-
-function diagnoseHumanOverride(failure: string, target?: string) {
-  const policy = policyFor(failure);
-  if (!policy) return { status: 'failed' as const, changed: false as const, error: error('OVERRIDE_FAILURE_UNKNOWN', `failure policy '${failure}' is not registered`) };
-  return {
-    status: 'ready' as const,
-    changed: false as const,
-    failure: policy,
-    target: target ?? null,
-    outcomes: target ? policy.outcomes.filter((rule) => rule.target === target) : policy.outcomes,
-    error: null
-  };
-}
-
-async function diagnoseHumanOverrideForTask(
-  taskRef: string,
-  failure?: string,
-  target?: string,
-  options: HumanOverrideOptions = {}
-) {
-  const resolved = resolveTask(taskRef, options);
-  if (!resolved.ok) {
-    return {
-      status: 'failed' as const,
-      changed: false as const,
-      taskId: resolved.taskId,
-      state: null,
-      blockedBy: [],
-      probes: [],
-      error: error(resolved.code, resolved.message)
-    };
-  }
-  const document = readTask(resolved.taskMdPath);
-  if ('code' in document) {
-    return {
-      status: 'failed' as const,
-      changed: false as const,
-      taskId: resolved.taskId,
-      state: resolved.state,
-      blockedBy: [],
-      probes: [],
-      error: document
-    };
-  }
-  const policies = failure
-    ? [policyFor(failure)].filter((policy): policy is FailurePolicy => policy !== null)
-    : HUMAN_OVERRIDE_FAILURE_REGISTRY;
-  if (failure && policies.length === 0) {
-    return {
-      status: 'failed' as const,
-      changed: false as const,
-      taskId: resolved.taskId,
-      state: resolved.state,
-      blockedBy: [],
-      probes: [],
-      error: error('OVERRIDE_FAILURE_UNKNOWN', `failure policy '${failure}' is not registered`)
-    };
-  }
-  const probes = await Promise.all(policies
-    .filter((policy) => !target || policy.targets.includes(target))
-    .map(async (policy) => {
-      const producer = policy.producerId === LIFECYCLE_PRODUCER
-        ? probeLifecycleFailure(taskRef, policy, resolved, options)
-        : await probeGenericFailure(taskRef, policy, resolved, options);
-      const observed = isProducerFailure(producer);
-      return {
-        failureId: policy.id,
-        producerId: policy.producerId,
-        guardId: policy.guardId,
-        code: policy.code,
-        target: target && policy.targets.includes(target) ? target : policy.targets[0]!,
-        eligibility: policy.eligibility,
-        status: observed ? 'observed' as const : producer.code === 'OVERRIDE_PROBE_INPUT_MISSING' ? 'unproven' as const : 'not-observed' as const,
-        observedFacts: observed ? producer.observedFacts : [],
-        message: observed ? producer.message : producer.message,
-        errorCode: observed ? null : producer.code
-      };
-    }));
-  const blockedBy = probes.filter((probe) => probe.status === 'observed');
-  return {
-    status: 'ready' as const,
-    changed: false as const,
-    taskId: resolved.taskId,
-    state: resolved.state,
-    snapshot: {
-      taskId: resolved.taskId,
-      state: resolved.state,
-      documentDigest: computeFailureDigest(document.content)
-    },
-    blockedBy,
-    probes,
-    error: null
-  };
-}
-
-function renderHumanOverrideAudit(content: string): string {
-  let ledger: ParsedHumanOverrideLedger | null;
-  try {
-    ledger = parseHumanOverrideLedger(content);
-  } catch {
-    return '';
-  }
-  if (!ledger || ledger.table.rows.length === 0) return '';
-  const rows = ledger.table.rows.map(({ values }) => [
-    `- ${values.status || 'unknown'}: ${values.failure_id || 'unknown failure'}`,
-    values.pull_request_number ? `resource=pull-request#${values.pull_request_number}` : values.issue_number ? `resource=issue#${values.issue_number}` : 'resource=local',
-    `target=${values.target || 'unknown'}`,
-    `context=${values.context_id || 'unknown'}`,
-    `effect=${values.effect || 'unknown'}`,
-    `result=${values.result || 'pending'}`,
-    `operator=${values.operator || 'unknown'}`,
-    `identity_source=${values.identity_source || 'unknown'}`,
-    `reason=${values.reason || 'not recorded'}`,
-    `residual=${values.residual || 'pending'}`
-  ].join('; '));
-  return `## Human Override Audit\n\n${rows.join('\n')}`;
-}
-
-function computeFailureDigest(value: string): string {
-  return createHash('sha256').update(value).digest('hex');
-}
-
-export {
-  HUMAN_OVERRIDE_COLUMNS,
-  HUMAN_OVERRIDE_FAILURE_REGISTRY,
-  HUMAN_OVERRIDE_SECTION_ALIASES,
-  LIFECYCLE_PRODUCER,
-  computeFailureDigest,
-  captureFailureSnapshot,
-  consumeHumanOverride,
-  diagnoseHumanOverride,
-  diagnoseHumanOverrideForTask,
-  failureId,
-  issueHumanOverride,
-  overrideDryRunConflict,
-  renderHumanOverrideAudit,
-  resolveOutcome,
-  stableFailureCatalog,
-  validatePolicy,
-  validateRegistry
-};
-export type {
-  ConsumeHumanOverrideRequest,
-  Eligibility,
-  FailureIdentity,
-  FailurePolicy,
-  HumanOverrideConsumeResult,
-  HumanOverrideIdentity,
-  HumanOverrideIssueResult,
-  HumanOverrideOptions,
-  HumanOverrideRequest,
-  FailureSnapshot,
-  Outcome,
-  OutcomeContext,
-  OutcomeEffect,
-  OutcomeFallback,
-  OutcomeResult,
-  OutcomeRule
-};