nexus-agents 8.40.0 → 8.41.0

package/dist/{chunk-SHDBGUVD.js → chunk-RZ5YSYCB.js}

@@ -20,7 +20,7 @@ import {
   emitReputationEvent,
   emitSanitizationEvent,
   emitTrustEvent
-} from "./chunk-XIKVBZKG.js";
+} from "./chunk-SCIVDNY5.js";
 import {
   hasToken
 } from "./chunk-HYESPHTE.js";
@@ -2162,4 +2162,4 @@ export {
   IssueTriage,
   createIssueTriage
 };
-//# sourceMappingURL=chunk-SHDBGUVD.js.map
+//# sourceMappingURL=chunk-RZ5YSYCB.js.map

package/dist/{chunk-XIKVBZKG.js → chunk-SCIVDNY5.js}

@@ -169,7 +169,16 @@ function createGraphAuditBridge(trail) {
     });
   };
 }
+function formatNotCompleted(event) {
+  const detail = event["detail"];
+  const suffix = typeof detail === "string" && detail !== "" ? `: ${detail}` : "";
+  return `Node ${String(event["nodeId"])} ${String(event["reason"])} (did not complete)${suffix}`;
+}
+function formatCompletion(event) {
+  return event["halted"] === true ? `HALTED awaiting input after ${String(event["totalSteps"])} steps, ${String(event["durationMs"])}ms \u2014 NOT complete` : `Complete: ${String(event["totalSteps"])} steps, ${String(event["durationMs"])}ms`;
+}
 function formatGraphEventDetail(event) {
+  if (event.type === "node_not_completed") return formatNotCompleted(event);
   switch (event.type) {
     case "node_started":
       return `Node ${String(event["nodeId"])} starting`;
@@ -182,7 +191,7 @@ function formatGraphEventDetail(event) {
     case "step_completed":
       return `Step ${String(event["stepNumber"])}: ${String(event["nodesExecuted"])} nodes`;
     case "execution_complete":
-      return `Complete: ${String(event["totalSteps"])} steps, ${String(event["durationMs"])}ms`;
+      return formatCompletion(event);
     default:
       return event.type;
   }
@@ -205,4 +214,4 @@ export {
   createGraphAuditBridge,
   createAuditTrail
 };
-//# sourceMappingURL=chunk-XIKVBZKG.js.map
+//# sourceMappingURL=chunk-SCIVDNY5.js.map

package/dist/{chunk-XIKVBZKG.js.map → chunk-SCIVDNY5.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/security/audit-trail.ts"],"sourcesContent":["/**\n * nexus-agents/security - Audit Trail\n *\n * Machine-readable JSON audit events for security pipeline decisions.\n * Every trust classification, policy gate decision, corroboration check,\n * and reputation assessment is recorded as a structured event.\n *\n * Satisfies CLAUDE.md requirement: \"Every action on untrusted input must\n * log: trust tier, sources cited, policy gate decision, stripped content.\"\n *\n * @module security/audit-trail\n * (Source: Issue #832 — Security audit trail)\n */\n\nimport { getTimeProvider } from '../core/index.js';\nimport type { TrustTier } from './trust-types.js';\nimport type { AgentActionType } from './action-schema.js';\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/** Maximum stored events before oldest are evicted. */\nconst MAX_EVENTS = 10_000;\n\n/**\n * Discriminated union of audit event types.\n * Each event captures a single security pipeline decision.\n */\nexport type AuditEvent =\n  | TrustClassificationEvent\n  | PolicyGateEvent\n  | CorroborationEvent\n  | ReputationEvent\n  | SanitizationEvent\n  | GraphExecutionAuditEvent\n  | ClawGuardViolationEvent;\n\n/** Base fields shared by all audit events. */\ninterface AuditEventBase {\n  readonly id: string;\n  readonly timestamp: string;\n  readonly component: string;\n}\n\n/** Trust classification decision. */\nexport interface TrustClassificationEvent extends AuditEventBase {\n  readonly type: 'trust_classification';\n  readonly username: string;\n  readonly assignedTier: TrustTier;\n  readonly userRole: string;\n  /**\n   * Present only when a maintainer allowlist was consulted (#4992). A\n   * classification that consulted no list records nothing here rather than\n   * `false` — \"not measured\" and \"measured false\" must stay distinguishable in\n   * the audit record.\n   */\n  readonly isAllowlisted?: boolean;\n  readonly wasDowngraded: boolean;\n  readonly reason: string;\n}\n\n/** Policy gate evaluation result. */\nexport interface PolicyGateEvent extends AuditEventBase {\n  readonly type: 'policy_gate';\n  /**\n   * The agent action evaluated, for the security policy-gate path\n   * (security/policy-gate.ts). Optional because the PIPELINE policy path\n   * (pipeline/policy-evaluator.ts → #3710) records stage-boundary policy\n   * decisions that have no `AgentAction` — they carry {@link stageType} +\n   * {@link mode} + {@link ruleIds} instead. Security emitters always set it.\n   */\n  readonly actionType?: AgentActionType;\n  readonly allowed: boolean;\n  readonly requiresApproval: boolean;\n  readonly inputTrustTier: TrustTier;\n  readonly violationRules: readonly string[];\n  /**\n   * Pipeline-policy fields (#3710). Carried for the dev-pipeline\n   * consensus→execute seam so the DURABLE record can distinguish soak (`warn`)\n   * from enforce (`block`) and which rules/stage fired — without these the\n   * persisted event is useless to the tune/readiness loop. Absent for the\n   * security policy-gate path.\n   */\n  /** Enforcement mode the decision was made under: `warn` (soak) or `block` (enforce). */\n  readonly mode?: 'off' | 'warn' | 'block';\n  /** IDs of the policy rules that fired (mirrors `violationRules` for the pipeline path). */\n  readonly ruleIds?: readonly string[];\n  /** Type of the stage the gate guarded (e.g. `execute`). */\n  readonly stageType?: string;\n  /**\n   * #3727: discriminates a per-EVALUATION SUMMARY record (`'summary'` — emitted\n   * once per pipeline policy evaluation INCLUDING clean ones, the DENOMINATOR for\n   * the would-block rate) from a per-VIOLATION record (`'violation'` — the\n   * existing #3710 per-violation records). Absent for the security policy-gate\n   * path. Denominator = count(recordKind==='summary'); numerator = summaries with\n   * `violationCount > 0`. Scope the #3710 count-parity assertion to `'violation'`.\n   */\n  readonly recordKind?: 'summary' | 'violation';\n  /** #3727: number of violations in THIS evaluation (set on the summary record). */\n  readonly violationCount?: number;\n}\n\n/** Corroboration validation result. */\nexport interface CorroborationEvent extends AuditEventBase {\n  readonly type: 'corroboration';\n  readonly actionType: AgentActionType;\n  readonly satisfied: boolean;\n  readonly sourceCount: number;\n  readonly missingRequirements: readonly string[];\n}\n\n/** Reputation assessment result. */\nexport interface ReputationEvent extends AuditEventBase {\n  readonly type: 'reputation';\n  readonly username: string;\n  readonly reputationScore: number;\n  readonly isSuspicious: boolean;\n  readonly effectiveTier: TrustTier;\n  readonly signalCount: number;\n}\n\n/** Summary of a single element stripped during sanitization. */\nexport interface StrippedElementSummary {\n  /** Truncated tag text (≤30 chars + '...' from the sanitizer). */\n  readonly tag: string;\n  /** Reason the element was removed (e.g. 'Trail of Bits injection vector'). */\n  readonly reason: string;\n}\n\n/** Max stripped-element details retained per sanitization event. */\nexport const MAX_STRIPPED_ELEMENTS_PER_EVENT = 20;\n\n/** Input sanitization result. */\nexport interface SanitizationEvent extends AuditEventBase {\n  readonly type: 'sanitization';\n  readonly source: string;\n  readonly wasModified: boolean;\n  /** Whether input exceeded the configured limit. Absent on events that predate this field. */\n  readonly truncated?: boolean;\n  readonly strippedCount: number;\n  readonly injectionFlagCount: number;\n  /**\n   * Per-element tag/reason details, truncated to at most\n   * MAX_STRIPPED_ELEMENTS_PER_EVENT entries. Required by CLAUDE.md's\n   * Untrusted Input Policy: \"Log stripped elements for audit trail.\"\n   */\n  readonly strippedElements: readonly StrippedElementSummary[];\n}\n\n/**\n * ClawGuard AUDIT-mode violation (#4097). Records a tool call that VIOLATED the\n * derived access policy but was ALLOWED to proceed because the policy is in\n * `audit` mode (log-and-allow). Persisting these is what lets the audit→enforce\n * graduation loop size the real violation rate from durable telemetry rather\n * than ephemeral logs.\n */\nexport interface ClawGuardViolationEvent extends AuditEventBase {\n  readonly type: 'clawguard_violation';\n  /** The tool whose call violated the policy. */\n  readonly toolName: string;\n  /** Human-readable warning from the access decision (may be truncated). */\n  readonly warning: string;\n  /** Source of the derived policy (`llm` / `fallback-keyword` / `bypass`). */\n  readonly policySource: string;\n  /** Policy mode under which the violation was allowed (e.g. `audit`). */\n  readonly mode: string;\n  /** Request ID of the offending tool call, for correlation. */\n  readonly requestId: string;\n  /**\n   * Which rule produced the verdict (#5106) — `unbypassable:tool`,\n   * `unbypassable:path`, `allowedTools`, `allowedTools:confirm_risky`.\n   *\n   * A first-class field rather than prose inside `warning`, because `warning`\n   * is truncated at 500 chars and a long attacker-selectable `path` argument\n   * pushes the rule off the end. A chain reader must be able to tell an\n   * unbypassable denylist hit from an allowlist miss without parsing a string\n   * that may have been cut mid-word.\n   *\n   * Absent for verdicts that carry no rule (an audit-mode allowlist\n   * observation), which is why it is optional rather than defaulted — there is\n   * no rule to name, and inventing one would misreport.\n   */\n  readonly matchedRule?: string;\n}\n\n/** Graph execution lifecycle event (Issue #839). */\nexport interface GraphExecutionAuditEvent extends AuditEventBase {\n  readonly type: 'graph_execution';\n  readonly graphEvent: string;\n  readonly nodeId?: string;\n  readonly stepNumber: number;\n  readonly detail: string;\n}\n\n/**\n * Query filter for retrieving audit events.\n *\n * The post-mortem dimensions (#3197) — `actionType`, `actor`, `violationRule`\n * — NARROW to events that actually carry the field (events lacking it are\n * excluded), unlike `trustTier`'s legacy keep-non-applicable behavior. Only\n * dimensions backed by a real event field are offered: `resource` and\n * `policyName` from the original ask were dropped because no AuditEvent\n * records them (a filter with no backing field would be dead config); the\n * policy-rule intent is served by `violationRule` (PolicyGateEvent's\n * `violationRules`).\n */\nexport interface AuditQuery {\n  readonly type?: AuditEvent['type'];\n  readonly since?: string;\n  readonly until?: string;\n  readonly trustTier?: TrustTier;\n  /** Match PolicyGate/Corroboration events by their `actionType`. */\n  readonly actionType?: AgentActionType;\n  /** Match Trust/Reputation events by `username` (the acting/assessed user). */\n  readonly actor?: string;\n  /** Match PolicyGate events whose `violationRules` include this rule name. */\n  readonly violationRule?: string;\n  readonly limit?: number;\n}\n\n// ============================================================================\n// AuditTrail\n// ============================================================================\n\n/**\n * Append-only audit trail for security pipeline decisions.\n * Events are bounded by MAX_EVENTS to prevent unbounded growth.\n */\n/**\n * Optional durable sink: receives every fully-formed event appended to the\n * trail, so security decisions can be mirrored to a persistent, hash-chained\n * store (see security/audit-bridge.ts). Default-off — when absent, the trail\n * behaves exactly as before (#3291).\n */\nexport type DurableAuditSink = (event: AuditEvent) => void;\n\nexport class AuditTrail {\n  private events: AuditEvent[] = [];\n  private nextId = 1;\n\n  constructor(private readonly durableSink?: DurableAuditSink) {}\n\n  /** Appends an event to the trail. Returns the assigned event ID. */\n  append(event: Omit<AuditEvent, 'id' | 'timestamp'>): string {\n    const id = `audit-${String(this.nextId++)}`;\n    const fullEvent = {\n      ...event,\n      id,\n      timestamp: getTimeProvider().nowIso(),\n    } as AuditEvent;\n\n    this.events.push(fullEvent);\n    this.enforceLimit();\n\n    // Mirror to the durable store when wired (#3291). Best-effort: a sink\n    // failure must never break the in-memory security pipeline.\n    if (this.durableSink !== undefined) {\n      try {\n        this.durableSink(fullEvent);\n      } catch {\n        // Sink implementations already swallow+log; this is belt-and-suspenders.\n      }\n    }\n\n    return id;\n  }\n\n  /** Queries events matching the given filter. */\n  query(filter: AuditQuery = {}): readonly AuditEvent[] {\n    let results = this.events as readonly AuditEvent[];\n\n    if (filter.type !== undefined) {\n      results = results.filter((e) => e.type === filter.type);\n    }\n\n    if (filter.since !== undefined) {\n      results = filterSince(results, filter.since);\n    }\n\n    if (filter.until !== undefined) {\n      results = filterUntil(results, filter.until);\n    }\n\n    if (filter.trustTier !== undefined) {\n      results = filterByTrustTier(results, filter.trustTier);\n    }\n\n    if (filter.actionType !== undefined) {\n      results = filterByActionType(results, filter.actionType);\n    }\n\n    if (filter.actor !== undefined) {\n      results = filterByActor(results, filter.actor);\n    }\n\n    if (filter.violationRule !== undefined) {\n      results = filterByViolationRule(results, filter.violationRule);\n    }\n\n    const limit = filter.limit ?? results.length;\n    return results.slice(-limit);\n  }\n\n  /** Returns the total number of events. */\n  get size(): number {\n    return this.events.length;\n  }\n\n  /** Clears all events. */\n  clear(): void {\n    this.events = [];\n  }\n\n  /** Enforces MAX_EVENTS bound. */\n  private enforceLimit(): void {\n    if (this.events.length > MAX_EVENTS) {\n      this.events = this.events.slice(-MAX_EVENTS);\n    }\n  }\n}\n\n// ============================================================================\n// Filter Helpers\n// ============================================================================\n\nfunction filterSince(events: readonly AuditEvent[], since: string): readonly AuditEvent[] {\n  const sinceTime = new Date(since).getTime();\n  return events.filter((e) => new Date(e.timestamp).getTime() >= sinceTime);\n}\n\nfunction filterUntil(events: readonly AuditEvent[], until: string): readonly AuditEvent[] {\n  const untilTime = new Date(until).getTime();\n  return events.filter((e) => new Date(e.timestamp).getTime() <= untilTime);\n}\n\nfunction filterByTrustTier(events: readonly AuditEvent[], tier: TrustTier): readonly AuditEvent[] {\n  return events.filter((e) => {\n    if (e.type === 'trust_classification') return e.assignedTier === tier;\n    if (e.type === 'policy_gate') return e.inputTrustTier === tier;\n    if (e.type === 'reputation') return e.effectiveTier === tier;\n    return true;\n  });\n}\n\n/**\n * Narrow to events carrying the given `actionType` (#3197). Only PolicyGate and\n * Corroboration events have one; all others are excluded.\n */\nfunction filterByActionType(\n  events: readonly AuditEvent[],\n  actionType: AgentActionType\n): readonly AuditEvent[] {\n  return events.filter(\n    (e) => (e.type === 'policy_gate' || e.type === 'corroboration') && e.actionType === actionType\n  );\n}\n\n/**\n * Narrow to events for the given actor (#3197), matched on `username`. Only\n * Trust-classification and Reputation events carry a username; others are\n * excluded so an actor filter never returns unrelated rows.\n */\nfunction filterByActor(events: readonly AuditEvent[], actor: string): readonly AuditEvent[] {\n  return events.filter(\n    (e) => (e.type === 'trust_classification' || e.type === 'reputation') && e.username === actor\n  );\n}\n\n/**\n * Narrow to PolicyGate events whose `violationRules` include the given rule\n * name (#3197) — the security post-mortem \"who tripped rule X\" query.\n */\nfunction filterByViolationRule(events: readonly AuditEvent[], rule: string): readonly AuditEvent[] {\n  return events.filter((e) => e.type === 'policy_gate' && e.violationRules.includes(rule));\n}\n\n// ============================================================================\n// Convenience Emitters\n// ============================================================================\n\n/**\n * Records a trust classification decision.\n */\nexport function emitTrustEvent(\n  trail: AuditTrail,\n  data: Omit<TrustClassificationEvent, 'id' | 'timestamp' | 'type' | 'component'>\n): string {\n  return trail.append({\n    type: 'trust_classification',\n    component: 'trust-classifier',\n    ...data,\n  });\n}\n\n/**\n * Records a policy gate evaluation.\n */\nexport function emitPolicyEvent(\n  trail: AuditTrail,\n  data: Omit<PolicyGateEvent, 'id' | 'timestamp' | 'type' | 'component'>\n): string {\n  return trail.append({\n    type: 'policy_gate',\n    component: 'policy-gate',\n    ...data,\n  });\n}\n\n/**\n * Records a PIPELINE-policy gate decision (#3710) — the dev-pipeline\n * consensus→execute seam. Distinct from {@link emitPolicyEvent} (the security\n * policy-gate path with an `AgentAction`): this carries `mode`/`ruleIds`/\n * `stageType` so the durable record distinguishes soak(warn) from enforce(block)\n * and is usable by the tune/readiness loop. ONE append per call.\n */\nexport function emitPipelinePolicyEvent(\n  trail: AuditTrail,\n  data: Omit<PolicyGateEvent, 'id' | 'timestamp' | 'type' | 'component' | 'actionType'>\n): string {\n  return trail.append({\n    type: 'policy_gate',\n    component: 'pipeline-policy-evaluator',\n    ...data,\n  });\n}\n\n/** The pipeline-policy would-block rate over a window (#3727). */\nexport interface PolicyWouldBlockRate {\n  /** Total pipeline-policy evaluations (the denominator — summary records). */\n  readonly evaluations: number;\n  /** Evaluations that had ≥1 violation (what enforce mode WOULD block). */\n  readonly wouldBlock: number;\n  /** `wouldBlock / evaluations`; 0 when there are no evaluations. */\n  readonly rate: number;\n}\n\n/**\n * Compute the pipeline-policy would-block RATE from durable audit events (#3727)\n * — the read-side of the per-evaluation summary records, and the signal the\n * #3769-enforce soak-readiness gate needs. Denominator = per-evaluation SUMMARY\n * records (`recordKind === 'summary'`); numerator = summaries with\n * `violationCount > 0` (the would-block fraction, independent of warn/block mode).\n * Per-violation records (`recordKind === 'violation'`) are intentionally NOT\n * counted — counting them would double-count and break the denominator.\n */\nexport function computePolicyWouldBlockRate(events: readonly AuditEvent[]): PolicyWouldBlockRate {\n  let evaluations = 0;\n  let wouldBlock = 0;\n  for (const e of events) {\n    if (e.type !== 'policy_gate' || e.recordKind !== 'summary') continue;\n    evaluations += 1;\n    if ((e.violationCount ?? 0) > 0) wouldBlock += 1;\n  }\n  return { evaluations, wouldBlock, rate: evaluations > 0 ? wouldBlock / evaluations : 0 };\n}\n\n/**\n * Records a corroboration validation.\n */\nexport function emitCorroborationEvent(\n  trail: AuditTrail,\n  data: Omit<CorroborationEvent, 'id' | 'timestamp' | 'type' | 'component'>\n): string {\n  return trail.append({\n    type: 'corroboration',\n    component: 'corroboration-validator',\n    ...data,\n  });\n}\n\n/**\n * Records a reputation assessment.\n */\nexport function emitReputationEvent(\n  trail: AuditTrail,\n  data: Omit<ReputationEvent, 'id' | 'timestamp' | 'type' | 'component'>\n): string {\n  return trail.append({\n    type: 'reputation',\n    component: 'reputation-model',\n    ...data,\n  });\n}\n\n/**\n * Records an input sanitization result.\n */\nexport function emitSanitizationEvent(\n  trail: AuditTrail,\n  data: Omit<SanitizationEvent, 'id' | 'timestamp' | 'type' | 'component'>\n): string {\n  return trail.append({\n    type: 'sanitization',\n    component: 'input-sanitizer',\n    ...data,\n  });\n}\n\n/**\n * Records a graph execution lifecycle event.\n */\nexport function emitGraphExecutionEvent(\n  trail: AuditTrail,\n  data: Omit<GraphExecutionAuditEvent, 'id' | 'timestamp' | 'type' | 'component'>\n): string {\n  return trail.append({\n    type: 'graph_execution',\n    component: 'graph-executor',\n    ...data,\n  });\n}\n\n/**\n * Records a ClawGuard AUDIT-mode violation (#4097) — a policy-violating tool\n * call that was log-and-allowed because the policy is in `audit` mode. ONE\n * append per call; mirrors to the durable sink when the trail is wired.\n */\nexport function emitClawGuardViolation(\n  trail: AuditTrail,\n  data: Omit<ClawGuardViolationEvent, 'id' | 'timestamp' | 'type' | 'component'>\n): string {\n  return trail.append({\n    type: 'clawguard_violation',\n    component: 'clawguard-audit',\n    ...data,\n  });\n}\n\n/**\n * Creates an onEvent callback that bridges graph events to the audit trail.\n * Pass the returned function as `onEvent` in GraphExecuteOptions.\n *\n * @example\n * const trail = createAuditTrail();\n * await executeGraph(graph, inputs, { onEvent: createGraphAuditBridge(trail) });\n */\nexport function createGraphAuditBridge(\n  trail: AuditTrail\n): (event: { readonly type: string; readonly [key: string]: unknown }) => void {\n  return (event) => {\n    const nodeId = typeof event['nodeId'] === 'string' ? event['nodeId'] : undefined;\n    const stepNumber = typeof event['stepNumber'] === 'number' ? event['stepNumber'] : 0;\n    emitGraphExecutionEvent(trail, {\n      graphEvent: event.type,\n      ...(nodeId !== undefined ? { nodeId } : {}),\n      stepNumber,\n      detail: formatGraphEventDetail(event),\n    });\n  };\n}\n\n/** Formats a brief detail string from a graph event. */\nfunction formatGraphEventDetail(event: {\n  readonly type: string;\n  readonly [key: string]: unknown;\n}): string {\n  switch (event.type) {\n    case 'node_started':\n      return `Node ${String(event['nodeId'])} starting`;\n    case 'node_completed':\n      return `Node ${String(event['nodeId'])} completed in ${String(event['durationMs'])}ms`;\n    case 'node_error':\n      return `Node ${String(event['nodeId'])} failed: ${String(event['error'])}`;\n    case 'state_updated':\n      return `State updated: ${String(event['updatedKeys'])}`;\n    case 'step_completed':\n      return `Step ${String(event['stepNumber'])}: ${String(event['nodesExecuted'])} nodes`;\n    case 'execution_complete':\n      return `Complete: ${String(event['totalSteps'])} steps, ${String(event['durationMs'])}ms`;\n    default:\n      return event.type;\n  }\n}\n\n/**\n * Creates a new AuditTrail instance. Pass a {@link DurableAuditSink} (e.g. from\n * `createDurableAuditSink(auditLogger)`) to mirror appended security decisions\n * to a durable, hash-chained store (#3291). Default: in-memory only.\n */\nexport function createAuditTrail(durableSink?: DurableAuditSink): AuditTrail {\n  return new AuditTrail(durableSink);\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/security/audit-trail.ts"],"sourcesContent":["/**\n * nexus-agents/security - Audit Trail\n *\n * Machine-readable JSON audit events for security pipeline decisions.\n * Every trust classification, policy gate decision, corroboration check,\n * and reputation assessment is recorded as a structured event.\n *\n * Satisfies CLAUDE.md requirement: \"Every action on untrusted input must\n * log: trust tier, sources cited, policy gate decision, stripped content.\"\n *\n * @module security/audit-trail\n * (Source: Issue #832 — Security audit trail)\n */\n\nimport { getTimeProvider } from '../core/index.js';\nimport type { TrustTier } from './trust-types.js';\nimport type { AgentActionType } from './action-schema.js';\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/** Maximum stored events before oldest are evicted. */\nconst MAX_EVENTS = 10_000;\n\n/**\n * Discriminated union of audit event types.\n * Each event captures a single security pipeline decision.\n */\nexport type AuditEvent =\n  | TrustClassificationEvent\n  | PolicyGateEvent\n  | CorroborationEvent\n  | ReputationEvent\n  | SanitizationEvent\n  | GraphExecutionAuditEvent\n  | ClawGuardViolationEvent;\n\n/** Base fields shared by all audit events. */\ninterface AuditEventBase {\n  readonly id: string;\n  readonly timestamp: string;\n  readonly component: string;\n}\n\n/** Trust classification decision. */\nexport interface TrustClassificationEvent extends AuditEventBase {\n  readonly type: 'trust_classification';\n  readonly username: string;\n  readonly assignedTier: TrustTier;\n  readonly userRole: string;\n  /**\n   * Present only when a maintainer allowlist was consulted (#4992). A\n   * classification that consulted no list records nothing here rather than\n   * `false` — \"not measured\" and \"measured false\" must stay distinguishable in\n   * the audit record.\n   */\n  readonly isAllowlisted?: boolean;\n  readonly wasDowngraded: boolean;\n  readonly reason: string;\n}\n\n/** Policy gate evaluation result. */\nexport interface PolicyGateEvent extends AuditEventBase {\n  readonly type: 'policy_gate';\n  /**\n   * The agent action evaluated, for the security policy-gate path\n   * (security/policy-gate.ts). Optional because the PIPELINE policy path\n   * (pipeline/policy-evaluator.ts → #3710) records stage-boundary policy\n   * decisions that have no `AgentAction` — they carry {@link stageType} +\n   * {@link mode} + {@link ruleIds} instead. Security emitters always set it.\n   */\n  readonly actionType?: AgentActionType;\n  readonly allowed: boolean;\n  readonly requiresApproval: boolean;\n  readonly inputTrustTier: TrustTier;\n  readonly violationRules: readonly string[];\n  /**\n   * Pipeline-policy fields (#3710). Carried for the dev-pipeline\n   * consensus→execute seam so the DURABLE record can distinguish soak (`warn`)\n   * from enforce (`block`) and which rules/stage fired — without these the\n   * persisted event is useless to the tune/readiness loop. Absent for the\n   * security policy-gate path.\n   */\n  /** Enforcement mode the decision was made under: `warn` (soak) or `block` (enforce). */\n  readonly mode?: 'off' | 'warn' | 'block';\n  /** IDs of the policy rules that fired (mirrors `violationRules` for the pipeline path). */\n  readonly ruleIds?: readonly string[];\n  /** Type of the stage the gate guarded (e.g. `execute`). */\n  readonly stageType?: string;\n  /**\n   * #3727: discriminates a per-EVALUATION SUMMARY record (`'summary'` — emitted\n   * once per pipeline policy evaluation INCLUDING clean ones, the DENOMINATOR for\n   * the would-block rate) from a per-VIOLATION record (`'violation'` — the\n   * existing #3710 per-violation records). Absent for the security policy-gate\n   * path. Denominator = count(recordKind==='summary'); numerator = summaries with\n   * `violationCount > 0`. Scope the #3710 count-parity assertion to `'violation'`.\n   */\n  readonly recordKind?: 'summary' | 'violation';\n  /** #3727: number of violations in THIS evaluation (set on the summary record). */\n  readonly violationCount?: number;\n}\n\n/** Corroboration validation result. */\nexport interface CorroborationEvent extends AuditEventBase {\n  readonly type: 'corroboration';\n  readonly actionType: AgentActionType;\n  readonly satisfied: boolean;\n  readonly sourceCount: number;\n  readonly missingRequirements: readonly string[];\n}\n\n/** Reputation assessment result. */\nexport interface ReputationEvent extends AuditEventBase {\n  readonly type: 'reputation';\n  readonly username: string;\n  readonly reputationScore: number;\n  readonly isSuspicious: boolean;\n  readonly effectiveTier: TrustTier;\n  readonly signalCount: number;\n}\n\n/** Summary of a single element stripped during sanitization. */\nexport interface StrippedElementSummary {\n  /** Truncated tag text (≤30 chars + '...' from the sanitizer). */\n  readonly tag: string;\n  /** Reason the element was removed (e.g. 'Trail of Bits injection vector'). */\n  readonly reason: string;\n}\n\n/** Max stripped-element details retained per sanitization event. */\nexport const MAX_STRIPPED_ELEMENTS_PER_EVENT = 20;\n\n/** Input sanitization result. */\nexport interface SanitizationEvent extends AuditEventBase {\n  readonly type: 'sanitization';\n  readonly source: string;\n  readonly wasModified: boolean;\n  /** Whether input exceeded the configured limit. Absent on events that predate this field. */\n  readonly truncated?: boolean;\n  readonly strippedCount: number;\n  readonly injectionFlagCount: number;\n  /**\n   * Per-element tag/reason details, truncated to at most\n   * MAX_STRIPPED_ELEMENTS_PER_EVENT entries. Required by CLAUDE.md's\n   * Untrusted Input Policy: \"Log stripped elements for audit trail.\"\n   */\n  readonly strippedElements: readonly StrippedElementSummary[];\n}\n\n/**\n * ClawGuard AUDIT-mode violation (#4097). Records a tool call that VIOLATED the\n * derived access policy but was ALLOWED to proceed because the policy is in\n * `audit` mode (log-and-allow). Persisting these is what lets the audit→enforce\n * graduation loop size the real violation rate from durable telemetry rather\n * than ephemeral logs.\n */\nexport interface ClawGuardViolationEvent extends AuditEventBase {\n  readonly type: 'clawguard_violation';\n  /** The tool whose call violated the policy. */\n  readonly toolName: string;\n  /** Human-readable warning from the access decision (may be truncated). */\n  readonly warning: string;\n  /** Source of the derived policy (`llm` / `fallback-keyword` / `bypass`). */\n  readonly policySource: string;\n  /** Policy mode under which the violation was allowed (e.g. `audit`). */\n  readonly mode: string;\n  /** Request ID of the offending tool call, for correlation. */\n  readonly requestId: string;\n  /**\n   * Which rule produced the verdict (#5106) — `unbypassable:tool`,\n   * `unbypassable:path`, `allowedTools`, `allowedTools:confirm_risky`.\n   *\n   * A first-class field rather than prose inside `warning`, because `warning`\n   * is truncated at 500 chars and a long attacker-selectable `path` argument\n   * pushes the rule off the end. A chain reader must be able to tell an\n   * unbypassable denylist hit from an allowlist miss without parsing a string\n   * that may have been cut mid-word.\n   *\n   * Absent for verdicts that carry no rule (an audit-mode allowlist\n   * observation), which is why it is optional rather than defaulted — there is\n   * no rule to name, and inventing one would misreport.\n   */\n  readonly matchedRule?: string;\n}\n\n/** Graph execution lifecycle event (Issue #839). */\nexport interface GraphExecutionAuditEvent extends AuditEventBase {\n  readonly type: 'graph_execution';\n  readonly graphEvent: string;\n  readonly nodeId?: string;\n  readonly stepNumber: number;\n  readonly detail: string;\n}\n\n/**\n * Query filter for retrieving audit events.\n *\n * The post-mortem dimensions (#3197) — `actionType`, `actor`, `violationRule`\n * — NARROW to events that actually carry the field (events lacking it are\n * excluded), unlike `trustTier`'s legacy keep-non-applicable behavior. Only\n * dimensions backed by a real event field are offered: `resource` and\n * `policyName` from the original ask were dropped because no AuditEvent\n * records them (a filter with no backing field would be dead config); the\n * policy-rule intent is served by `violationRule` (PolicyGateEvent's\n * `violationRules`).\n */\nexport interface AuditQuery {\n  readonly type?: AuditEvent['type'];\n  readonly since?: string;\n  readonly until?: string;\n  readonly trustTier?: TrustTier;\n  /** Match PolicyGate/Corroboration events by their `actionType`. */\n  readonly actionType?: AgentActionType;\n  /** Match Trust/Reputation events by `username` (the acting/assessed user). */\n  readonly actor?: string;\n  /** Match PolicyGate events whose `violationRules` include this rule name. */\n  readonly violationRule?: string;\n  readonly limit?: number;\n}\n\n// ============================================================================\n// AuditTrail\n// ============================================================================\n\n/**\n * Append-only audit trail for security pipeline decisions.\n * Events are bounded by MAX_EVENTS to prevent unbounded growth.\n */\n/**\n * Optional durable sink: receives every fully-formed event appended to the\n * trail, so security decisions can be mirrored to a persistent, hash-chained\n * store (see security/audit-bridge.ts). Default-off — when absent, the trail\n * behaves exactly as before (#3291).\n */\nexport type DurableAuditSink = (event: AuditEvent) => void;\n\nexport class AuditTrail {\n  private events: AuditEvent[] = [];\n  private nextId = 1;\n\n  constructor(private readonly durableSink?: DurableAuditSink) {}\n\n  /** Appends an event to the trail. Returns the assigned event ID. */\n  append(event: Omit<AuditEvent, 'id' | 'timestamp'>): string {\n    const id = `audit-${String(this.nextId++)}`;\n    const fullEvent = {\n      ...event,\n      id,\n      timestamp: getTimeProvider().nowIso(),\n    } as AuditEvent;\n\n    this.events.push(fullEvent);\n    this.enforceLimit();\n\n    // Mirror to the durable store when wired (#3291). Best-effort: a sink\n    // failure must never break the in-memory security pipeline.\n    if (this.durableSink !== undefined) {\n      try {\n        this.durableSink(fullEvent);\n      } catch {\n        // Sink implementations already swallow+log; this is belt-and-suspenders.\n      }\n    }\n\n    return id;\n  }\n\n  /** Queries events matching the given filter. */\n  query(filter: AuditQuery = {}): readonly AuditEvent[] {\n    let results = this.events as readonly AuditEvent[];\n\n    if (filter.type !== undefined) {\n      results = results.filter((e) => e.type === filter.type);\n    }\n\n    if (filter.since !== undefined) {\n      results = filterSince(results, filter.since);\n    }\n\n    if (filter.until !== undefined) {\n      results = filterUntil(results, filter.until);\n    }\n\n    if (filter.trustTier !== undefined) {\n      results = filterByTrustTier(results, filter.trustTier);\n    }\n\n    if (filter.actionType !== undefined) {\n      results = filterByActionType(results, filter.actionType);\n    }\n\n    if (filter.actor !== undefined) {\n      results = filterByActor(results, filter.actor);\n    }\n\n    if (filter.violationRule !== undefined) {\n      results = filterByViolationRule(results, filter.violationRule);\n    }\n\n    const limit = filter.limit ?? results.length;\n    return results.slice(-limit);\n  }\n\n  /** Returns the total number of events. */\n  get size(): number {\n    return this.events.length;\n  }\n\n  /** Clears all events. */\n  clear(): void {\n    this.events = [];\n  }\n\n  /** Enforces MAX_EVENTS bound. */\n  private enforceLimit(): void {\n    if (this.events.length > MAX_EVENTS) {\n      this.events = this.events.slice(-MAX_EVENTS);\n    }\n  }\n}\n\n// ============================================================================\n// Filter Helpers\n// ============================================================================\n\nfunction filterSince(events: readonly AuditEvent[], since: string): readonly AuditEvent[] {\n  const sinceTime = new Date(since).getTime();\n  return events.filter((e) => new Date(e.timestamp).getTime() >= sinceTime);\n}\n\nfunction filterUntil(events: readonly AuditEvent[], until: string): readonly AuditEvent[] {\n  const untilTime = new Date(until).getTime();\n  return events.filter((e) => new Date(e.timestamp).getTime() <= untilTime);\n}\n\nfunction filterByTrustTier(events: readonly AuditEvent[], tier: TrustTier): readonly AuditEvent[] {\n  return events.filter((e) => {\n    if (e.type === 'trust_classification') return e.assignedTier === tier;\n    if (e.type === 'policy_gate') return e.inputTrustTier === tier;\n    if (e.type === 'reputation') return e.effectiveTier === tier;\n    return true;\n  });\n}\n\n/**\n * Narrow to events carrying the given `actionType` (#3197). Only PolicyGate and\n * Corroboration events have one; all others are excluded.\n */\nfunction filterByActionType(\n  events: readonly AuditEvent[],\n  actionType: AgentActionType\n): readonly AuditEvent[] {\n  return events.filter(\n    (e) => (e.type === 'policy_gate' || e.type === 'corroboration') && e.actionType === actionType\n  );\n}\n\n/**\n * Narrow to events for the given actor (#3197), matched on `username`. Only\n * Trust-classification and Reputation events carry a username; others are\n * excluded so an actor filter never returns unrelated rows.\n */\nfunction filterByActor(events: readonly AuditEvent[], actor: string): readonly AuditEvent[] {\n  return events.filter(\n    (e) => (e.type === 'trust_classification' || e.type === 'reputation') && e.username === actor\n  );\n}\n\n/**\n * Narrow to PolicyGate events whose `violationRules` include the given rule\n * name (#3197) — the security post-mortem \"who tripped rule X\" query.\n */\nfunction filterByViolationRule(events: readonly AuditEvent[], rule: string): readonly AuditEvent[] {\n  return events.filter((e) => e.type === 'policy_gate' && e.violationRules.includes(rule));\n}\n\n// ============================================================================\n// Convenience Emitters\n// ============================================================================\n\n/**\n * Records a trust classification decision.\n */\nexport function emitTrustEvent(\n  trail: AuditTrail,\n  data: Omit<TrustClassificationEvent, 'id' | 'timestamp' | 'type' | 'component'>\n): string {\n  return trail.append({\n    type: 'trust_classification',\n    component: 'trust-classifier',\n    ...data,\n  });\n}\n\n/**\n * Records a policy gate evaluation.\n */\nexport function emitPolicyEvent(\n  trail: AuditTrail,\n  data: Omit<PolicyGateEvent, 'id' | 'timestamp' | 'type' | 'component'>\n): string {\n  return trail.append({\n    type: 'policy_gate',\n    component: 'policy-gate',\n    ...data,\n  });\n}\n\n/**\n * Records a PIPELINE-policy gate decision (#3710) — the dev-pipeline\n * consensus→execute seam. Distinct from {@link emitPolicyEvent} (the security\n * policy-gate path with an `AgentAction`): this carries `mode`/`ruleIds`/\n * `stageType` so the durable record distinguishes soak(warn) from enforce(block)\n * and is usable by the tune/readiness loop. ONE append per call.\n */\nexport function emitPipelinePolicyEvent(\n  trail: AuditTrail,\n  data: Omit<PolicyGateEvent, 'id' | 'timestamp' | 'type' | 'component' | 'actionType'>\n): string {\n  return trail.append({\n    type: 'policy_gate',\n    component: 'pipeline-policy-evaluator',\n    ...data,\n  });\n}\n\n/** The pipeline-policy would-block rate over a window (#3727). */\nexport interface PolicyWouldBlockRate {\n  /** Total pipeline-policy evaluations (the denominator — summary records). */\n  readonly evaluations: number;\n  /** Evaluations that had ≥1 violation (what enforce mode WOULD block). */\n  readonly wouldBlock: number;\n  /** `wouldBlock / evaluations`; 0 when there are no evaluations. */\n  readonly rate: number;\n}\n\n/**\n * Compute the pipeline-policy would-block RATE from durable audit events (#3727)\n * — the read-side of the per-evaluation summary records, and the signal the\n * #3769-enforce soak-readiness gate needs. Denominator = per-evaluation SUMMARY\n * records (`recordKind === 'summary'`); numerator = summaries with\n * `violationCount > 0` (the would-block fraction, independent of warn/block mode).\n * Per-violation records (`recordKind === 'violation'`) are intentionally NOT\n * counted — counting them would double-count and break the denominator.\n */\nexport function computePolicyWouldBlockRate(events: readonly AuditEvent[]): PolicyWouldBlockRate {\n  let evaluations = 0;\n  let wouldBlock = 0;\n  for (const e of events) {\n    if (e.type !== 'policy_gate' || e.recordKind !== 'summary') continue;\n    evaluations += 1;\n    if ((e.violationCount ?? 0) > 0) wouldBlock += 1;\n  }\n  return { evaluations, wouldBlock, rate: evaluations > 0 ? wouldBlock / evaluations : 0 };\n}\n\n/**\n * Records a corroboration validation.\n */\nexport function emitCorroborationEvent(\n  trail: AuditTrail,\n  data: Omit<CorroborationEvent, 'id' | 'timestamp' | 'type' | 'component'>\n): string {\n  return trail.append({\n    type: 'corroboration',\n    component: 'corroboration-validator',\n    ...data,\n  });\n}\n\n/**\n * Records a reputation assessment.\n */\nexport function emitReputationEvent(\n  trail: AuditTrail,\n  data: Omit<ReputationEvent, 'id' | 'timestamp' | 'type' | 'component'>\n): string {\n  return trail.append({\n    type: 'reputation',\n    component: 'reputation-model',\n    ...data,\n  });\n}\n\n/**\n * Records an input sanitization result.\n */\nexport function emitSanitizationEvent(\n  trail: AuditTrail,\n  data: Omit<SanitizationEvent, 'id' | 'timestamp' | 'type' | 'component'>\n): string {\n  return trail.append({\n    type: 'sanitization',\n    component: 'input-sanitizer',\n    ...data,\n  });\n}\n\n/**\n * Records a graph execution lifecycle event.\n */\nexport function emitGraphExecutionEvent(\n  trail: AuditTrail,\n  data: Omit<GraphExecutionAuditEvent, 'id' | 'timestamp' | 'type' | 'component'>\n): string {\n  return trail.append({\n    type: 'graph_execution',\n    component: 'graph-executor',\n    ...data,\n  });\n}\n\n/**\n * Records a ClawGuard AUDIT-mode violation (#4097) — a policy-violating tool\n * call that was log-and-allowed because the policy is in `audit` mode. ONE\n * append per call; mirrors to the durable sink when the trail is wired.\n */\nexport function emitClawGuardViolation(\n  trail: AuditTrail,\n  data: Omit<ClawGuardViolationEvent, 'id' | 'timestamp' | 'type' | 'component'>\n): string {\n  return trail.append({\n    type: 'clawguard_violation',\n    component: 'clawguard-audit',\n    ...data,\n  });\n}\n\n/**\n * Creates an onEvent callback that bridges graph events to the audit trail.\n * Pass the returned function as `onEvent` in GraphExecuteOptions.\n *\n * @example\n * const trail = createAuditTrail();\n * await executeGraph(graph, inputs, { onEvent: createGraphAuditBridge(trail) });\n */\nexport function createGraphAuditBridge(\n  trail: AuditTrail\n): (event: { readonly type: string; readonly [key: string]: unknown }) => void {\n  return (event) => {\n    const nodeId = typeof event['nodeId'] === 'string' ? event['nodeId'] : undefined;\n    const stepNumber = typeof event['stepNumber'] === 'number' ? event['stepNumber'] : 0;\n    emitGraphExecutionEvent(trail, {\n      graphEvent: event.type,\n      ...(nodeId !== undefined ? { nodeId } : {}),\n      stepNumber,\n      detail: formatGraphEventDetail(event),\n    });\n  };\n}\n\ntype GraphEventLike = { readonly type: string; readonly [key: string]: unknown };\n\n/**\n * A node that produced nothing: paused for human input, or refused by its\n * precondition. The audit trail is hash-chained, so this must not land in it as\n * \"completed in 0ms\".\n */\nfunction formatNotCompleted(event: GraphEventLike): string {\n  const detail = event['detail'];\n  const suffix = typeof detail === 'string' && detail !== '' ? `: ${detail}` : '';\n  return `Node ${String(event['nodeId'])} ${String(event['reason'])} (did not complete)${suffix}`;\n}\n\n/** A completion, qualified when the run actually paused rather than finished. */\nfunction formatCompletion(event: GraphEventLike): string {\n  return event['halted'] === true\n    ? `HALTED awaiting input after ${String(event['totalSteps'])} steps, ${String(event['durationMs'])}ms — NOT complete`\n    : `Complete: ${String(event['totalSteps'])} steps, ${String(event['durationMs'])}ms`;\n}\n\n/** Formats a brief detail string from a graph event. */\nfunction formatGraphEventDetail(event: GraphEventLike): string {\n  if (event.type === 'node_not_completed') return formatNotCompleted(event);\n  switch (event.type) {\n    case 'node_started':\n      return `Node ${String(event['nodeId'])} starting`;\n    case 'node_completed':\n      return `Node ${String(event['nodeId'])} completed in ${String(event['durationMs'])}ms`;\n    case 'node_error':\n      return `Node ${String(event['nodeId'])} failed: ${String(event['error'])}`;\n    case 'state_updated':\n      return `State updated: ${String(event['updatedKeys'])}`;\n    case 'step_completed':\n      return `Step ${String(event['stepNumber'])}: ${String(event['nodesExecuted'])} nodes`;\n    case 'execution_complete':\n      return formatCompletion(event);\n    default:\n      return event.type;\n  }\n}\n\n/**\n * Creates a new AuditTrail instance. Pass a {@link DurableAuditSink} (e.g. from\n * `createDurableAuditSink(auditLogger)`) to mirror appended security decisions\n * to a durable, hash-chained store (#3291). Default: in-memory only.\n */\nexport function createAuditTrail(durableSink?: DurableAuditSink): AuditTrail {\n  return new AuditTrail(durableSink);\n}\n"],"mappings":"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","names":[]}

package/dist/cli.js

@@ -157,7 +157,7 @@ import {
   validateNexusEnv,
   validateWorkflow,
   wrapInMarkdownFence
-} from "./chunk-ZIUE2RNX.js";
+} from "./chunk-QWU7PEVK.js";
 import "./chunk-IVHR3QEK.js";
 import "./chunk-DGWT7DXX.js";
 import "./chunk-64GMIUM5.js";
@@ -177,7 +177,7 @@ import {
   doctorCommand,
   initDataDirectories,
   runDoctor
-} from "./chunk-XIZCIXMR.js";
+} from "./chunk-L454YZK6.js";
 import {
   buildOpenAICompatAdapters,
   readOpenAICompatEnv
@@ -196,7 +196,7 @@ import {
   recordAuthenticVote,
   registerConsensusVoteTool,
   toRecordDecision
-} from "./chunk-2VGA2TRD.js";
+} from "./chunk-QPPR7KQH.js";
 import {
   loadUsageEvents,
   rollupByModel
@@ -217,7 +217,7 @@ import {
   runUntrustedInputFirewall,
   validateAgentAction,
   validateCorroboration
-} from "./chunk-SHDBGUVD.js";
+} from "./chunk-RZ5YSYCB.js";
 import "./chunk-ZMPQVOAO.js";
 import {
   ReputationCache,
@@ -236,19 +236,19 @@ import {
   registerImprovementReviewTool,
   runImprovementReview,
   scanForSecrets
-} from "./chunk-DKJBDPVX.js";
+} from "./chunk-IEQ2MJJ3.js";
 import {
   createDefaultPolicyFirewall,
   setGlobalPolicyFirewall,
   setSecureHandlerAuditLogger,
   stagePolicyFirewallForRollout
-} from "./chunk-N5FL5NGK.js";
+} from "./chunk-C25ILGJ6.js";
 import {
   NODE_ENGINE_RANGE,
   VERSION,
   isNodeVersionSupported
-} from "./chunk-GHTO4L6T.js";
-import "./chunk-XIKVBZKG.js";
+} from "./chunk-FLRN74US.js";
+import "./chunk-SCIVDNY5.js";
 import {
   createUnifiedRegistry,
   getGlobalRegistry
@@ -7441,8 +7441,8 @@ function formatVoteRow(v, opts) {
   return `  ${icon}${colors.reset} ${label}: ${v.vote.decision.toUpperCase()} (${formatPercentage(v.vote.confidence)})${tag}${grounds}`;
 }
 function printSummary2(ctx) {
-  const { result, votes, threshold } = ctx;
-  const { voteCounts, approvalPercentage, outcome, quorumReached } = result;
+  const { result, votes, threshold, decision } = ctx;
+  const { voteCounts, approvalPercentage, quorumReached } = result;
   const errored = votes.filter((v) => v.source === "error").length;
   const simulated = votes.filter((v) => v.source === "simulation").length;
   writeLine(`${colors.cyan}Summary${colors.reset}
@@ -7453,9 +7453,10 @@ function printSummary2(ctx) {
   if (errored > 0) writeLine(`  ${colors.red}Errored:  ${String(errored)}${colors.reset}`);
   writeLine(`  Approval: ${approvalPercentage.toFixed(1)}%`);
   writeLine(`  Threshold: ${threshold}`);
-  const outcomeColor = outcome === "approved" ? colors.green : outcome === "rejected" ? colors.red : colors.yellow;
+  const decisionColor = decision === "approved" ? colors.green : decision === "no_quorum" ? colors.yellow : colors.red;
+  const { text: decisionText } = decisionResultLabel(decision);
   const cause = explainOutcome({
-    outcome,
+    decision,
     quorumReached,
     errored,
     votes,
@@ -7463,11 +7464,9 @@ function printSummary2(ctx) {
     threshold,
     ...ctx.optionGate === void 0 ? {} : { optionGate: ctx.optionGate }
   });
-  writeLine(
-    `
-${colors.bold}Result: ${outcomeColor}${outcome.toUpperCase()}${colors.reset}${cause}
-`
-  );
+  writeLine(`
+${colors.bold}Result: ${decisionColor}${decisionText}${colors.reset}${cause}
+`);
   if (simulated > 0) {
     writeLine(
       `${colors.red}\u26A0  ${String(simulated)} of ${String(votes.length)} vote(s) were SIMULATED \u2014 do not rely on this result for decisions.${colors.reset}
@@ -7476,7 +7475,10 @@ ${colors.bold}Result: ${outcomeColor}${outcome.toUpperCase()}${colors.reset}${ca
   }
 }
 function explainOutcome(ctx) {
-  if (ctx.outcome !== "rejected") return "";
+  if (ctx.decision === "no_quorum") {
+    return ctx.errored > 0 ? ` ${colors.dim}\u2014 quorum void (${String(ctx.errored)} of ${String(ctx.votes.length)} voter(s) failed); re-run to recover${colors.reset}` : ` ${colors.dim}\u2014 quorum void: the absolute approval floor was not met by the full panel${colors.reset}`;
+  }
+  if (ctx.decision !== "rejected") return "";
   if (!ctx.quorumReached && ctx.errored > 0) {
     const total = ctx.votes.length;
     const survived = total - ctx.errored;
@@ -7529,14 +7531,15 @@ function formatVoteComment(result, decision) {
   });
   const effectiveDecision = decision ?? mapOutcomeToDecision(result.result.outcome);
   const { emoji: outcomeEmoji, text: outcomeText } = decisionResultLabel(effectiveDecision);
-  const voteRows = result.votes.map(({ role, vote }) => {
+  const voteRows = result.votes.map(({ role, vote, source }) => {
     const roleLabel = VOTER_ROLES[role].split(" - ")[0] ?? role;
-    const decision2 = vote.decision.toUpperCase();
-    const confidence = formatPercentage(vote.confidence);
+    const decision2 = source === "error" ? "ERRORED" : vote.decision.toUpperCase();
+    const confidence = source === "error" ? "\u2014" : formatPercentage(vote.confidence);
     return `| ${roleLabel} | ${decision2} | ${confidence} |`;
   }).join("\n");
+  const errored = result.votes.filter((v) => v.source === "error").length;
   const { voteCounts, approvalPercentage } = result.result;
-  const summary = `Approve: ${String(voteCounts.approve)}, Reject: ${String(voteCounts.reject)}, Abstain: ${String(voteCounts.abstain)} (${approvalPercentage.toFixed(1)}% approval)`;
+  const summary = `Approve: ${String(voteCounts.approve)}, Reject: ${String(voteCounts.reject)}, Abstain: ${String(voteCounts.abstain)}` + (errored > 0 ? `, Errored: ${String(errored)}` : "") + ` (${approvalPercentage.toFixed(1)}% approval` + (errored > 0 ? `, measured over ${String(result.votes.length - errored)} responding voter(s)` : "") + ")";
   return `## Consensus Vote Result
 
 **Date:** ${now} (ET)
@@ -7609,7 +7612,13 @@ async function runVote(options) {
     strategy: result.strategy,
     // Likewise: an error-policy short-circuit voided the vote, and without it
     // the record calls a void a `rejected` (#4953).
-    ...result.policyReason !== void 0 ? { policyReason: result.policyReason } : {}
+    ...result.policyReason !== void 0 ? { policyReason: result.policyReason } : {},
+    // #5362 widened the RETURN TYPE for this and never added it to the literal,
+    // so `explainOutcome`'s gate arm — written to consume it — was unreachable
+    // and every option veto fell through to the generic threshold message,
+    // blaming an approval bar the vote had cleared. TypeScript stayed silent
+    // because the field is optional.
+    ...result.optionGate !== void 0 ? { optionGate: result.optionGate } : {}
   };
 }
 function printDryRunBanner() {
@@ -7694,6 +7703,7 @@ ${colors.bold}Nexus Agents Consensus Vote${colors.reset}`);
       result: result.result,
       votes: result.votes,
       threshold: result.threshold,
+      decision: result.decision,
       ...result.optionGate === void 0 ? {} : { optionGate: result.optionGate }
     });
     if (options.verbose === true) printHashes(result.votes);
@@ -19918,7 +19928,7 @@ function startImprovementReviewScheduler(options) {
   let running = false;
   const runOnce = async () => {
     try {
-      const { runImprovementReview: runImprovementReview2, ImprovementReviewInputSchema: ImprovementReviewInputSchema2 } = await import("./improvement-review-7FTPX4KN.js");
+      const { runImprovementReview: runImprovementReview2, ImprovementReviewInputSchema: ImprovementReviewInputSchema2 } = await import("./improvement-review-23W6GCNG.js");
       const input = ImprovementReviewInputSchema2.parse({ fileIssues });
       const result = await runImprovementReview2(input, { logger: logger22 });
       logger22.info("Scheduled improvement_review complete", {