amicus 4.6.3 → 4.7.1

package/src/cli-handlers-run.js

@@ -13,11 +13,12 @@
 'use strict';
 
 const { validateStartArgs } = require('./cli');
-const { validateTaskId } = require('./utils/validators');
+const { validateTaskId, validateTag } = require('./utils/validators');
 const { resolveLaunchModel, maybeOfferProviderDefaults } = require('./utils/start-helpers');
 const { failJson, ERROR_CODES } = require('./utils/error-doc');
 const { requireNoUiForJson } = require('./utils/cli-preflight');
-const { GATEWAY_MODES } = require('./utils/model-descriptor');
+const { handleFanout } = require('./cli-handlers-fanout');
+const { applyTemplateForArgs } = require('./cli-template-args');
 
 /**
  * Handle 'sidecar start' command
@@ -37,17 +38,9 @@ async function handleStart(args) {
     // Drop --prompt-file post-resolve or validateStartArgs re-trips its XOR guard.
     delete args['prompt-file'];
   }
-  if (args.template !== undefined) {
-    const { applyTemplate } = require('./template/apply');
-    const t = applyTemplate({ templateRef: args.template, prompt: args.prompt,
-      artifactFile: args.artifact, varList: args.var, project: args.cwd || process.cwd() });
-    if (t.error) { process.exit(failJson(useJson, t.error)); }
-    for (const n of t.notices) { process.stderr.write(n + '\n'); }
-    args.prompt = t.prompt;
-    templateMeta = t.promptMeta.template;
-  } else if (args.artifact !== undefined || args.var !== undefined) {
-    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --artifact/--var require --template (expansion happens only in template files)' }));
-  }
+  const tpl = applyTemplateForArgs(args, args.prompt, useJson);
+  if (tpl.fail !== undefined) { process.exit(tpl.fail); }
+  if (tpl.applied) { args.prompt = tpl.prompt; templateMeta = tpl.templateMeta; }
   requireNoUiForJson(args, useJson);
 
   const mc = args['max-cost'];
@@ -55,6 +48,18 @@ async function handleStart(args) {
     process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --max-cost must be a positive number' }));
   }
 
+  // v4.7 F8 (D13): --tag rejects (unlike sanitizeCouncilName, which cleans) —
+  // a stored tag is a user-chosen search key, so silent truncation/stripping
+  // would make --search/--group-by tag miss it. Checked here, beside the other
+  // pre-flight arg checks, so a bad tag exits before model resolution / the
+  // one-time onboarding tip (T2-m1: was previously after resolveLaunchModel).
+  if (args.tag !== undefined) {
+    const tagCheck = validateTag(args.tag);
+    if (!tagCheck.ok) {
+      process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: tagCheck.error }));
+    }
+  }
+
   const { model, alias } = await resolveLaunchModel(args);
   args.model = model;
 
@@ -118,157 +123,10 @@ async function handleStart(args) {
     modelInput: alias || null,
     template: templateMeta, // F9 (v4.5): startSidecar ignores unknown keys; inert until a future task reads it.
     pack: packRecord, // v4.5 Task 13: null when no --pack; additively recorded on solo session metadata.
+    tag: args.tag, // v4.7 F8: undefined when no --tag; Task 3 stores it on session metadata.
   });
 }
 
-/**
- * Handle 'amicus fanout' command (F4).
- * Returns the wave exit code: 0 all complete, 2 partial, 1 none/hard failure,
- * 130/143 when the wave was signal-aborted.
- */
-async function handleFanout(args) {
-  const useJson = !!args.json;
-
-  // --retry-failed <waveId> (v4.3 Task 19, spec 6.1): a completely different
-  // path from the --prompt/--models launch below (no briefing, no required
-  // --models — the original wave's failed legs supply their own saved
-  // context) — dispatch BEFORE any of that validation runs. --models here is
-  // optional and, when present, filters which failed legs get retried.
-  if (args['retry-failed']) {
-    const { retryFailedWave } = require('./sidecar/fanout-retry');
-    const { parseModelsList } = require('./sidecar/fanout-validate');
-    const { exitCode, errorDoc } = await retryFailedWave(String(args['retry-failed']), args.cwd || process.cwd(), {
-      models: parseModelsList(args.models), json: useJson,
-    });
-    if (errorDoc && useJson) { process.stdout.write(JSON.stringify(errorDoc) + '\n'); }
-    return exitCode;
-  }
-  const packRecord = require('./pack/pack-cli').applyPackOrExit(args, 'fanout', useJson);
-
-  // FIX 4 (#61 whole-branch review, cheap parity): handleStart validates
-  // --gateway via validateStartArgs (cli.js) — fanout never did, so a typo'd
-  // value silently fell through to resolveGatewayMode's pass-through instead
-  // of failing fast with a clear error.
-  if (args.gateway !== undefined && !GATEWAY_MODES.includes(args.gateway)) {
-    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: `Error: --gateway must be one of: ${GATEWAY_MODES.join(', ')}` }));
-  }
-
-  const { resolvePromptSource } = require('./utils/prompt-source');
-  let promptRes;
-  if (args.prompt !== undefined || args['prompt-file'] !== undefined || args.template === undefined) {
-    promptRes = resolvePromptSource(args);
-    if (promptRes.error) { process.exit(failJson(useJson, { code: ERROR_CODES.MISSING_PROMPT, message: promptRes.error })); }
-  } else {
-    promptRes = { prompt: undefined, promptMeta: null };
-  }
-  if (args.template !== undefined) {
-    const { applyTemplate } = require('./template/apply');
-    const t = applyTemplate({ templateRef: args.template, prompt: promptRes.prompt,
-      artifactFile: args.artifact, varList: args.var, project: args.cwd || process.cwd() });
-    if (t.error) { process.exit(failJson(useJson, t.error)); }
-    for (const n of t.notices) { process.stderr.write(n + '\n'); }
-    promptRes = { prompt: t.prompt, promptMeta: t.promptMeta };
-  } else if (args.artifact !== undefined || args.var !== undefined) {
-    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --artifact/--var require --template (expansion happens only in template files)' }));
-  }
-  // Council preset: expand a saved council into args.models (mutually exclusive with --models).
-  const hasModels = typeof args.models === 'string' && args.models.trim();
-  const hasCouncil = args.council !== undefined && args.council !== false;
-  if (hasModels && hasCouncil) {
-    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: pass exactly one of --models / --council, not both' }));
-  }
-  if (!hasModels && !hasCouncil) {
-    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --models is required (comma-separated aliases or provider/model IDs), or use --council <name>' }));
-  }
-  if (hasCouncil) {
-    if (typeof args.council !== 'string' || !args.council.trim()) {
-      process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --council requires a council name (e.g. --council free)' }));
-    }
-    const { resolveCouncilMembers } = require('./utils/config');
-    const { readCache } = require('./utils/model-catalog');
-    const catalog = (readCache() || {}).models || [];
-    const expanded = resolveCouncilMembers(args.council.trim(), catalog);
-    if (expanded.error) {
-      process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: `Error: ${expanded.error}` }));
-    }
-    if (expanded.dropped && expanded.dropped.length && !useJson) {
-      process.stderr.write(`Notice: dropped unavailable council member(s): ${expanded.dropped.join(', ')}\n`);
-    }
-    args.models = expanded.models.join(',');
-  }
-  if (args['wave-id']) {
-    const check = validateTaskId(String(args['wave-id']));
-    if (!check.valid) {
-      process.exit(failJson(useJson, { code: ERROR_CODES.BAD_SESSION, message: check.error }));
-    }
-  }
-  if (args.agent && String(args.agent).toLowerCase() === 'chat') {
-    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --agent chat is interactive-only; fanout is headless' }));
-  }
-  if (args.timeout !== undefined && args.timeout <= 0) {
-    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --timeout must be a positive number' }));
-  }
-  const mc = args['max-cost'];
-  if (mc !== undefined && (typeof mc !== 'number' || !Number.isFinite(mc) || mc <= 0)) {
-    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --max-cost must be a positive number' }));
-  }
-  const { parseModelsList } = require('./sidecar/fanout');
-  if (parseModelsList(args.models).length === 0) {
-    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --models must contain at least one non-empty entry' }));
-  }
-
-  // Direct require (fanout stays internal — no src/index.js public re-export).
-  const { runFanout } = require('./sidecar/fanout');
-  const { loadConfig, resolveGatewayMode } = require('./utils/config');
-  const { resolveFallbackConfig } = require('./sidecar/fallback-chains');
-  const { readCache } = require('./utils/model-catalog');
-  const cfg = loadConfig() || {};
-  const { exitCode } = await runFanout({
-    models: args.models,
-    prompt: promptRes.prompt,
-    promptMeta: promptRes.promptMeta,
-    waveId: args['wave-id'],
-    project: args.cwd || process.cwd(),
-    agent: args.agent || args.mode,
-    thinking: args.thinking,
-    timeout: args.timeout,
-    summaryLength: args['summary-length'],
-    includeContext: !args['no-context'],
-    sessionId: args['session-id'],
-    contextTurns: args['context-turns'],
-    contextSince: args['context-since'],
-    contextMaxTokens: args['context-max-tokens'],
-    // #10: forward the Cowork parent so MCP-spawned fanout legs pin the right
-    // session (mirrors handleStart's coworkProcess plumbing). Without this the
-    // spawned `--cowork-process` flag is dropped and buildContext gets null.
-    coworkProcess: args['cowork-process'],
-    mcp: args.mcp,
-    mcpConfig: args['mcp-config'],
-    noMcp: args['no-mcp'],
-    excludeMcp: args['exclude-mcp'],
-    noValidateModel: args['no-validate-model'],
-    // #61 Task 7.3: --gateway merged with routing.prefer, applied per leg
-    // by validateFanoutModels' router call.
-    gatewayMode: resolveGatewayMode(args.gateway),
-    json: !!args.json,
-    client: args.client,
-    maxCost: args['max-cost'] !== null && args['max-cost'] !== undefined ? args['max-cost'] : cfg.maxCost,
-    noCostGate: !!args['no-cost-gate'],
-    maxCostPerMtok: cfg.maxCostPerMtok,
-    follow: !!args.follow,
-    onComplete: args['on-complete'],
-    // v4.3 Task 18 (spec §6.2): opt-in cheaper-model substitution. --fallback
-    // forces on, --no-fallback forces off; unset defers to config `fallbacks.enabled`.
-    fallback: resolveFallbackConfig({
-      flagFallback: args.fallback === true ? true : (args['no-fallback'] ? false : undefined),
-      config: cfg,
-    }),
-    catalog: (readCache() || {}).models || [],
-    pack: packRecord, // v4.5 Task 13: null when no --pack; additive on wave metadata.json + wave.json.
-  });
-  return exitCode;
-}
-
 /**
  * Handle 'sidecar read' command
  * Spec Reference: §4.5

package/src/cli-template-args.js

@@ -0,0 +1,48 @@
+'use strict';
+
+/**
+ * @module cli-template-args
+ * v4.7 PR6 sweep: the single application point for --template/--artifact/--var,
+ * shared by the three CLI handlers (handleStart, handleFanout, handleCouncilRun)
+ * that used to carry this block verbatim-triplicated.
+ *
+ * NEVER calls process.exit: handleStart and handleFanout exit on failure, but
+ * handleCouncilRun RETURNS its exit code (its whole handler contract is
+ * return-the-code) — so the decision belongs to the caller, not this helper.
+ */
+
+const { failJson, ERROR_CODES } = require('./utils/error-doc');
+
+const NEEDS_TEMPLATE_MSG =
+  'Error: --artifact/--var require --template (expansion happens only in template files)';
+
+/**
+ * @param {object} args parsed argv
+ * @param {string|undefined} prompt pre-template prompt text
+ * @param {boolean} useJson
+ * @returns {{applied:false}
+ *   | {applied:true, prompt:string, promptMeta:object, templateMeta:object}
+ *   | {fail:number}}
+ */
+function applyTemplateForArgs(args, prompt, useJson) {
+  if (args.template !== undefined) {
+    const { applyTemplate } = require('./template/apply');
+    const t = applyTemplate({
+      templateRef: args.template, prompt,
+      artifactFile: args.artifact, varList: args.var,
+      project: args.cwd || process.cwd(),
+    });
+    if (t.error) { return { fail: failJson(useJson, t.error) }; }
+    for (const n of t.notices) { process.stderr.write(n + '\n'); }
+    return {
+      applied: true, prompt: t.prompt, promptMeta: t.promptMeta,
+      templateMeta: t.promptMeta.template,
+    };
+  }
+  if (args.artifact !== undefined || args.var !== undefined) {
+    return { fail: failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: NEEDS_TEMPLATE_MSG }) };
+  }
+  return { applied: false };
+}
+
+module.exports = { applyTemplateForArgs, NEEDS_TEMPLATE_MSG };

package/src/cli.js

@@ -105,8 +105,12 @@ function parseArgs(argv) {
       // Single short-flag alias, scoped to exactly '-o' (council verdict's
       // --out shorthand). No general short-flag support is implemented —
       // any other leading-dash token still falls through to positionals.
+      // R5: deliberately lockstep with the long-option branch above
+      // (`!next.startsWith('--')`) — '-o' and '--out' must consume values
+      // identically. A dash-leading value is still accepted here (parsing
+      // only normalizes); cli-handlers-council.js's R1 guard rejects it.
       const next = argv[i + 1];
-      if (next && !next.startsWith('-')) {
+      if (next && !next.startsWith('--')) {
         result.out = next;
         i++;
       } else {
@@ -455,6 +459,7 @@ Options for 'start':
   --artifact <file>            File whose content fills {{artifact}} (256 KB cap; needs --template)
   --var <k=v>                  Template variable, repeatable (needs --template)
   --pack <name|path>           Load a saved pack (model/options/template); explicit flags override it
+  --tag <t>                    Label this session for list/search/spend grouping (1-64 chars, [A-Za-z0-9_-])
 `,
   fanout: `
 Options for 'fanout':
@@ -465,31 +470,34 @@ Options for 'fanout':
                                ~32KB Windows argument cap). Mutually exclusive
                                with --prompt. Also works with 'start'.
   --wave-id <id>               Explicit wave ID (leg IDs become <id>-1..N)
-  --retry-failed <waveId>       Relaunch ONLY that wave's failed/timed-out/crashed/
-                                aborted legs as a NEW linked wave, using each leg's
-                                own saved context (byte-identical retry). Skips
-                                --prompt/--models; --models filters which failed
-                                legs to retry. wave.json is never modified.
+  --retry-failed <waveId>      Relaunch ONLY that wave's failed/timed-out/crashed/
+                               aborted legs as a NEW linked wave, using each leg's
+                               own saved context (byte-identical retry). Skips
+                               --prompt/--models; --models filters which failed
+                               legs to retry. wave.json is never modified.
   --json                       Emit the wave result as stable JSON on stdout
+  --quiet                      Suppress per-leg progress ticks, the wave-result summary, and
+                               preflight errors
   --max-cost <$>               Refuse the wave if the estimated total exceeds $ (soft ceiling)
   --no-cost-gate               Disable the budget gate (per-$/Mtok threshold + ceiling) for this run
   --fallback / --no-fallback   Opt-in cheaper-model substitution on a classified
                                rate-limit/overload leg failure (spec 6.2). Overrides
                                config fallbacks.enabled when passed; default: config, else off.
-  --gateway <mode>              Routing: auto (direct-first), direct, or openrouter
-  --follow                      Stream this run's events to stderr as they happen (--json -> NDJSON)
-  --on-complete <cmd>           Run a shell command once, at terminal state, after
-                                wave.json is durable. The command is user-authored
-                                on THIS command line (CLI-only — never sourced from
-                                config/briefings/model output); payload rides via
-                                env only (AMICUS_TASK_ID/TYPE/STATUS/EXIT_CODE/
-                                RESULT_FILE/EVENTS_FILE/COST/PROJECT), never model
-                                text. Child stdout/stderr go to amicus stderr.
-                                Never changes the wave's exit code, docs, or events.
+  --gateway <mode>             Routing: auto (direct-first), direct, or openrouter
+  --follow                     Stream this run's events to stderr as they happen (--json -> NDJSON)
+  --on-complete <cmd>          Run a shell command once, at terminal state, after
+                               wave.json is durable. The command is user-authored
+                               on THIS command line (CLI-only — never sourced from
+                               config/briefings/model output); payload rides via
+                               env only (AMICUS_TASK_ID/TYPE/STATUS/EXIT_CODE/
+                               RESULT_FILE/EVENTS_FILE/COST/PROJECT), never model
+                               text. Child stdout/stderr go to amicus stderr.
+                               Never changes the wave's exit code, docs, or events.
   --template <name|path>       Render a briefing template ({{prompt}}, {{artifact}}, {{var.*}})
   --artifact <file>            File whose content fills {{artifact}} (256 KB cap; needs --template)
   --var <k=v>                  Template variable, repeatable (needs --template)
   --pack <name|path>           Load a saved pack (bench/options/template); explicit flags override it
+  --tag <t>                    Label this wave for list/search/spend grouping (1-64 chars, [A-Za-z0-9_-])
   Shared per-leg knobs: --agent, --thinking, --timeout, --summary-length,
   --no-context, --context-*, --mcp*, --no-validate-model, --cwd
   Exit codes: 0 all legs complete, 2 partial, 1 none complete / hard failure
@@ -511,6 +519,8 @@ Options for 'models':
 Options for 'list':
   --status <filter>            Filter by status (running, complete)
   --all                        Show all projects
+  --search <q>                 Case-insensitive substring filter over id, tag, and briefing
+  --limit <n>                  Show only the n newest rows (0 = unlimited)
   --json                       Output as JSON
 `,
   status: `
@@ -580,7 +590,7 @@ Subcommands for 'council':
       [--debate] [--claude-review <file>] [--no-cost-gate] [--follow]
       [--fallback] [--no-fallback] [--on-complete <cmd>]
       [--template <name|path>] [--artifact <file>] [--var <k=v>]
-      [--pack <name|path>]
+      [--pack <name|path>] [--tag <t>]
                                 Run the full headless council engine (v4.0).
                                 Chair default: deepseek (must NOT be a bench seat).
                                 --critic and --lenses are mutually exclusive.
@@ -633,7 +643,7 @@ Options for 'spend':
   --model <id-or-prefix>        Only rows whose model starts with this
   --op <start|continue|resume|leg>   Only rows with this operation
   --failed                      Only non-complete (wasted) rows
-  --group-by <model|wave|council|project|op|day>   Rollup dimension (default model)
+  --group-by <model|wave|council|project|op|day|tag>   Rollup dimension (default model)
   --rows                        Include matching raw rows (capped at 1000)
   --json                        Machine-readable output (versioned spend doc)
   Reads ~/.config/amicus/spend-ledger.jsonl (one row per completed run/leg).
@@ -691,34 +701,17 @@ Options for 'template':
   pack: `
 Options for 'pack':
   amicus pack save <name> --kind council|fanout|solo [flags]
-                                Save a pack built from flags:
-                                --bench <a,b,c|name>    council/fanout: comma-
-                                                         separated members, or a
-                                                         saved council name
-                                --model <model>          solo kind only
-                                --chair/--critic/--lenses    council kind only
-                                --timeout/--max-cost/--gateway   shared run
-                                                         options
-                                --agent/--thinking/--summary-length   fanout/
-                                                         solo kind only
-                                --debate / --no-debate   council kind only
-                                --template <name|path>   briefing template
-                                                         reference (not rendered)
-                                --version <semver>       default 1.0.0 (an
-                                                         unchanged re-save is a
-                                                         no-op; a changed one
-                                                         auto-bumps the patch)
-                                --description <text>
-  amicus pack save <name> --from-run <id>
-                                Build a pack from an existing council run /
-                                fanout wave / solo session instead of flags
-                                (models, options, and a template REFERENCE only
-                                — briefing text is never captured)
-  amicus pack list [--json]    List saved packs
-  amicus pack show <name|path> [--json]
-                                Print a pack plus its validation report (never
-                                fails on an invalid pack — see 'validation')
-  amicus pack rm <name> [--json]   Remove a saved pack
+  amicus pack save <name> --from-run <id>   Build from an existing run (models/
+                                            options/template reference only — briefing never captured)
+  amicus pack list [--json]                 List saved packs
+  amicus pack show <name|path> [--json]     Print a pack + validation report
+  amicus pack rm <name> [--json]            Remove a saved pack
+  Flags: --bench <a,b,c|name> (council/fanout) · --model (solo) · --chair/--critic/--lenses
+  (council) · --debate/--no-debate (council) · --timeout/--max-cost/--gateway (shared) ·
+  --agent/--thinking/--summary-length (fanout/solo) · --template <name|path> (reference only,
+  not rendered) · --pack-version <semver> (the SAVED PACK's version, default 1.0.0; unchanged
+  re-save is a no-op, changed auto-bumps patch — NOT --version, which is amicus's own global
+  flag) · --description <text>
 `
 };
 

package/src/council/debate.js

@@ -8,12 +8,17 @@
  * new tally input plus the debate.json findings rows. run.js then re-runs
  * tally() on the returned input and decorates the record. Keeps run.js under the
  * line gate.
+ * Also holds the pure pre-debate helpers (target selection, dispute detection, re-vote bundling) moved from run-debate.js (v4.7 PR0).
  */
 
 const PAST_TENSE = { defend: 'defended', amend: 'amended', withdraw: 'withdrawn', 'no-response': 'no-response' };
 
-// runStats roles the ledger join must skip (ledger.js): a debate leg is an extra leg by an
-// already-benched model, never an extra ledger row and never that model's ledger identity.
+// The debate-role vocabulary: a debate leg is an extra leg by an already-benched model,
+// never an extra ledger row and never that model's ledger identity. Through v4.6 this Set
+// ALSO drove ledger.js's join skip-set directly; Task 7 (v4.7 D4) replaced that with
+// ledger.js's own LEDGER_JOIN_ROLES allowlist (fail-closed: everything not named there is
+// excluded, not just DEBATE_ROLES), so this Set no longer has any runtime consumer outside
+// this module — kept exported because debate.test.js pins its exact contents.
 const DEBATE_ROLES = new Set(['rebuttal', 'revote']);
 
 /**
@@ -78,21 +83,95 @@ function decorateRecord(record, debateFindings) {
 }
 
 /**
- * runStats rows for the debate legs (spec §5.5). role is 'rebuttal' | 'revote';
- * these legs never enter meta.models, so the ledger stays one row per (run×model),
- * and ledger.js skips DEBATE_ROLES when joining runStats so a debate leg cannot
- * overwrite the bench row's role/wasChair/conformance on that model's ledger row.
- * @param {{defenseLegs: Array, revoteLegs: Array}} args leg metadata
+ * runStats rows for the debate legs (spec §5.5), plus v4.7 D2/E4's row-per-launch
+ * extras: role is 'rebuttal' | 'revote' for the primary defense/re-vote legs,
+ * 'superseded' for an original leg a successful repair replaced, and 'repair' for
+ * a repair attempt that itself never became usable (error status rides naturally
+ * off the raw leg). The rebuttal/revote legs never enter meta.models, so the
+ * ledger stays one row per (run×model). DEBATE_ROLES remains the debate-role
+ * vocabulary (rebuttal/revote); the ledger's overwrite protection for ALL FOUR
+ * of these row-per-launch roles — rebuttal, revote, superseded AND repair —
+ * lives in ledger.js's own LEDGER_JOIN_ROLES allowlist (v4.7 D4, Task 7):
+ * a role not named there never joins, full stop, regardless of which module
+ * produced the row or whether it is even in DEBATE_ROLES.
+ * @param {{defenseLegs: Array, revoteLegs: Array, supersededLegs?: Array,
+ *   repairLegs?: Array}} args leg metadata
  * @returns {Array<object>}
  */
-function debateRunStatsRows({ defenseLegs, revoteLegs }) {
+function debateRunStatsRows({ defenseLegs, revoteLegs, supersededLegs, repairLegs }) {
   const mk = (role) => (l) => ({
     model: l.model, role, wasChair: false, conformance: l.conformance || 'clean',
     status: l.status || 'unknown',
     durationMs: typeof l.durationMs === 'number' ? l.durationMs : null,
     usage: l.usage || null,
+    ...(l.waveId ? { waveId: l.waveId } : {}),
+    ...(l.resolvedModel ? { resolvedModel: l.resolvedModel } : {}),
   });
-  return [...(defenseLegs || []).map(mk('rebuttal')), ...(revoteLegs || []).map(mk('revote'))];
+  return [
+    ...(defenseLegs || []).map(mk('rebuttal')),
+    ...(revoteLegs || []).map(mk('revote')),
+    ...(supersededLegs || []).map(mk('superseded')),
+    ...(repairLegs || []).map(mk('repair')),
+  ];
 }
 
-module.exports = { applyDebate, decorateRecord, debateRunStatsRows, PAST_TENSE, DEBATE_ROLES };
+/** Spec §5.7 fallback: a dead/unparseable defense means every bundled id's original stands. */
+function allNoResponse(ids) {
+  const byId = {};
+  for (const id of ids) { byId[id] = { action: 'no-response' }; }
+  return byId;
+}
+
+/** True when there is nothing to challenge (spec §5.1). */
+function nothingToDebate(provisionalRecord) {
+  if (!provisionalRecord || provisionalRecord.judged === false) { return true; }
+  const n = provisionalRecord.findings.filter(f => f.tier === 'Contested' || f.tier === 'Disputed').length;
+  return n === 0;
+}
+
+/** Judges whose provisional adjudications dispute at least one bundled id. */
+function disputingJudges(provisionalRecord, bundledIds) {
+  const ids = new Set(bundledIds);
+  const judges = new Set();
+  for (const f of provisionalRecord.findings) {
+    if (!ids.has(f.id)) { continue; }
+    for (const adj of f.adjudications || []) {
+      if (adj.verdict === 'dispute') { judges.add(adj.judge); }
+    }
+  }
+  return [...judges];
+}
+
+/** Group Contested+Disputed findings by raiser (defense targets). */
+function debateTargets(provisionalRecord, tallyInput) {
+  const claimById = new Map(tallyInput.findings.map(f => [f.id, f]));
+  const byRaiser = {};
+  const previousTier = {};
+  for (const f of provisionalRecord.findings) {
+    if (f.tier !== 'Contested' && f.tier !== 'Disputed') { continue; }
+    previousTier[f.id] = f.tier;
+    const src = claimById.get(f.id) || {};
+    const peerVerdicts = (f.adjudications || []).filter(a => a.judge !== f.raiser).map(a => a.verdict);
+    (byRaiser[f.raiser] = byRaiser[f.raiser] || []).push({ id: f.id, claim: src.claim,
+      severity: f.severity, location: src.location, peerVerdicts, disputeReasons: [] });
+  }
+  return { byRaiser, previousTier };
+}
+
+/** The re-vote bundle: defended-or-amended findings ONLY (spec §5.1 — withdrawn never appear). */
+function bundleFor(defenseResults, tallyInput) {
+  const out = [];
+  for (const dr of defenseResults) {
+    for (const [id, resp] of Object.entries(dr.byId)) {
+      if (resp.action !== 'defend' && resp.action !== 'amend') { continue; }
+      const src = tallyInput.findings.find(f => f.id === id) || {};
+      out.push({ id, severity: src.severity, amended: resp.action === 'amend',
+        claim: resp.action === 'amend' ? resp.claim : src.claim,
+        argument: resp.argument || 'defended without extra argument' });
+    }
+  }
+  return out;
+}
+
+module.exports = { applyDebate, decorateRecord, debateRunStatsRows, PAST_TENSE, DEBATE_ROLES,
+  allNoResponse, nothingToDebate, disputingJudges, debateTargets, bundleFor };