@event4u/agent-config 14.10.0 → 14.12.0

package/src/scripts/ai-video/stitch.sh

@@ -8,12 +8,53 @@
 #
 # Usage:
 #   stitch.sh <manifest.json> <output.mp4>
+#               [--mode cut|handoff]
+#               [--xfade <seconds>]
 #               [--skip-scene <id> ...]
 #               [--abort-on-missing | --continue]
 #
-# NOT a flag: --crossfade. It is parsed and REFUSED (exit 2). See
-# "Refused flags" below — it is listed so a caller who read the old
-# usage line gets an error instead of a hard cut.
+# Modes:
+#   --mode cut       (DEFAULT) `ffmpeg -f concat -c copy`. Stream copy, no
+#                    generation loss, no filtergraph. Byte-for-byte the
+#                    behaviour this script has always had; passing the flag
+#                    explicitly changes nothing.
+#   --mode handoff   Re-encode path (`libx264 -crf 20 -g 8 +faststart -an`)
+#                    for continuity chains, where clip i+1 was conditioned on
+#                    the rendered last frame of clip i. Video only: `-an`
+#                    DROPS every audio track, which is stated on stderr on
+#                    every run rather than discovered in the output.
+#
+#   --xfade <s>      Only valid with `--mode handoff`; ceiling 0.25 s. A short
+#                    fade applied ONLY at seams whose manifest row says
+#                    `continuity: handoff|connector` — insurance against a
+#                    visible pop, never a transition effect. Cut seams in the
+#                    same run stay hard cuts. Offsets are computed from
+#                    ffprobe'd durations, not from the manifest's declared
+#                    ones: the accumulated-length-minus-fade arithmetic is the
+#                    classic trap here and a declared duration that is 40 ms
+#                    off silently shifts every later seam.
+#
+# NOT a flag: --crossfade. It is parsed and REFUSED (exit 2) in EVERY mode.
+# See "Refused flags" below — it is listed so a caller who read the old usage
+# line gets an error instead of a hard cut. `--mode handoff --xfade <s>` is
+# the supported way to ask for a fade.
+#
+# port_invariants — what must survive a re-implementation:
+#   1. hard-cut default — `--mode cut` is the default and stream-copies
+#      (`-c copy`); a port that re-encodes by default has changed the output
+#      of every existing caller without telling anyone.
+#   2. refusal over silent downgrade — an unimplemented or out-of-bounds
+#      request exits non-zero BEFORE any work, and never falls through to a
+#      near-miss (`--crossfade`, `--xfade` above 0.25 s, `--xfade` in cut
+#      mode, an unknown flag, a missing clip). Reporting success for output
+#      the caller did not ask for is the one failure this script exists to
+#      not have.
+#   3. handoff frame = rendered frame — a handoff seam joins clips where the
+#      later one was conditioned on the earlier one's RENDERED last frame,
+#      never on its own still. A port that re-conditions from the source
+#      still produces a plausible-looking chain that does not actually
+#      continue the shot.
+#   Contract: docs/contracts/skill-bundled-assets.md § Port invariants.
 #
 # Failure semantics:
 #   - Missing clip → fail loud with scene_id and re-render hint
@@ -40,6 +81,10 @@
 #     only --skip-scene and --continue and rejects anything else. So the
 #     honest state is a refusal, not a silent downgrade and not a
 #     filtergraph shipped into a script with no test harness.
+#     The re-encode path this refusal used to ask for now exists as
+#     `--mode handoff` (+ optional `--xfade <s>`), with a test harness
+#     under tests/scripts/. The refusal stays: `--crossfade` named a
+#     transition on the stream-copy path, which is still impossible.
 
 set -euo pipefail
 
@@ -58,27 +103,59 @@ esac
 MANIFEST="${1:-}"
 OUTPUT="${2:-}"
 [ -n "${MANIFEST}" ] && [ -n "${OUTPUT}" ] \
-  || aiv_die 2 "usage: stitch.sh <manifest.json> <output.mp4> [--skip-scene <id>] [--abort-on-missing|--continue]"
+  || aiv_die 2 "usage: stitch.sh <manifest.json> <output.mp4> [--mode cut|handoff] [--xfade <seconds>] [--skip-scene <id>] [--abort-on-missing|--continue]"
 [ -r "${MANIFEST}" ] || aiv_die 2 "manifest not readable: ${MANIFEST}"
 shift 2 || true
 
 SKIP_IDS=""
 MISSING_POLICY="abort"
+MODE="cut"
+XFADE=""
+XFADE_MAX="0.25"
 while [ "$#" -gt 0 ]; do
   case "$1" in
     --skip-scene) SKIP_IDS="${SKIP_IDS} ${2:-}"; shift 2 ;;
     --abort-on-missing) MISSING_POLICY="abort"; shift ;;
     --continue) MISSING_POLICY="continue"; shift ;;
+    --mode) MODE="${2:-}"; shift 2 ;;
+    --xfade) XFADE="${2:-}"; shift 2 ;;
     --crossfade)
       # Refused HERE — before the dry-run branch, before ffmpeg, before any
       # output. The old code warned after the dry-run exit and then concatenated
       # anyway, so a caller asking for a crossfade got a hard cut and exit 0.
-      aiv_die 2 "stitch.sh: --crossfade is not implemented and will not be silently downgraded. The output path is 'ffmpeg -f concat -c copy', and stream copy precludes any filtergraph, so xfade/acrossfade require a re-encode path this script does not have. Re-run without --crossfade for a hard-cut concat, or open a roadmap item for the re-encode path."
+      aiv_die 2 "stitch.sh: --crossfade is not implemented and will not be silently downgraded. The output path of --mode cut is 'ffmpeg -f concat -c copy', and stream copy precludes any filtergraph, so xfade/acrossfade cannot exist there. Re-run without --crossfade for a hard-cut concat, or use '--mode handoff --xfade <seconds>' (ceiling ${XFADE_MAX}s) for the re-encode path, which applies the fade only at seams whose manifest row says continuity: handoff|connector."
       ;;
     *) aiv_die 2 "stitch.sh: unknown flag '$1'" ;;
   esac
 done
 
+case "${MODE}" in
+  cut|handoff) ;;
+  *) aiv_die 2 "stitch.sh: unknown --mode '${MODE}' (expected cut|handoff)" ;;
+esac
+
+if [ -n "${XFADE}" ]; then
+  # Refused, never ignored: an --xfade the run cannot honour would otherwise
+  # deliver a hard cut and report success — the exact shape of the --crossfade
+  # defect above.
+  [ "${MODE}" = "handoff" ] \
+    || aiv_die 2 "stitch.sh: --xfade requires '--mode handoff' — the cut path is 'ffmpeg -f concat -c copy' and stream copy precludes a filtergraph. Re-run with --mode handoff, or drop --xfade for a hard-cut concat."
+  printf '%s' "${XFADE}" | grep -Eq '^[0-9]+(\.[0-9]+)?$' \
+    || aiv_die 2 "stitch.sh: --xfade must be a non-negative number of seconds, got '${XFADE}'"
+  awk -v x="${XFADE}" -v m="${XFADE_MAX}" 'BEGIN { exit !(x > 0 && x <= m) }' \
+    || aiv_die 2 "stitch.sh: --xfade ${XFADE}s is outside the allowed range (0 < s <= ${XFADE_MAX}) — a longer fade is a transition effect, not seam insurance"
+fi
+
+# The plan/success JSON gains a `mode` key ONLY in handoff mode. Even an
+# additive key changes the stdout every existing caller reads, and "cut behaves
+# as it does today" is the invariant that path is held to. Absent means cut.
+MODE_JSON=""
+if [ "${MODE}" = "handoff" ]; then
+  MODE_JSON=',"mode":"handoff"'
+  printf 'stitch: --mode handoff RE-ENCODES (libx264 -crf 20 -g 8 +faststart -an) — the cut path stream-copies. Audio is dropped by -an; mux a bed afterwards if the chain needs one.\n' >&2
+  [ "${DRYRUN_FLAG}" -eq 0 ] && aiv_require_cmd ffprobe
+fi
+
 skip_match() {
   local id="$1" s
   for s in ${SKIP_IDS}; do
@@ -92,6 +169,11 @@ WORK_DIR="$(mktemp -d -t aiv-stitch-XXXXXX)"
 trap 'rm -rf "${WORK_DIR}"' EXIT
 CONCAT_LIST="${WORK_DIR}/concat.txt"
 : > "${CONCAT_LIST}"
+# Ordered `<continuity>\t<validated path>` rows — the handoff filtergraph needs
+# to know WHICH seams may fade, and the concat demuxer list cannot carry that.
+# Written only in handoff mode, so the cut path is untouched.
+SEQ_LIST="${WORK_DIR}/seq.tsv"
+: > "${SEQ_LIST}"
 
 # Accept both bare-array manifests and the documented object shape
 # (`{ "scenes": [...] }`). Field names tolerate the legacy
@@ -107,6 +189,14 @@ while IFS= read -r row; do
   clip_path="$(printf '%s' "${row}" | jq -r '.clip_path // .expected_clip')"
   audio_embedded="$(printf '%s' "${row}" | jq -r '.audio_embedded // false')"
   audio_path="$(printf '%s' "${row}" | jq -r '.audio_path // empty')"
+  continuity="cut"
+  if [ "${MODE}" = "handoff" ]; then
+    continuity="$(printf '%s' "${row}" | jq -r '.continuity // "cut"')"
+    case "${continuity}" in
+      cut|handoff|connector) ;;
+      *) aiv_die 2 "stitch.sh: scene=${scene_id} unknown continuity '${continuity}' (expected cut|handoff|connector)" ;;
+    esac
+  fi
 
   case "${clip_path}" in
     /*) ;;
@@ -155,8 +245,14 @@ while IFS= read -r row; do
       -c:v copy -c:a aac -shortest "${muxed}" >/dev/null \
       || aiv_die 8 "ffmpeg mux failed for scene=${scene_id}"
     printf "file '%s'\n" "${muxed}" >> "${CONCAT_LIST}"
+    if [ "${MODE}" = "handoff" ]; then
+      printf '%s\t%s\n' "${continuity}" "${muxed}" >> "${SEQ_LIST}"
+    fi
   else
     printf "file '%s'\n" "${clip_path}" >> "${CONCAT_LIST}"
+    if [ "${MODE}" = "handoff" ]; then
+      printf '%s\t%s\n' "${continuity}" "${clip_path}" >> "${SEQ_LIST}"
+    fi
   fi
   count=$((count + 1))
 done <<EOF
@@ -168,12 +264,97 @@ EOF
 if [ "${DRYRUN_FLAG}" -eq 1 ]; then
   printf 'stitch: dry-run plan (output=%s, scenes=%d):\n' "${OUTPUT}" "${count}" >&2
   printf '%b' "${plan}" >&2
-  printf '{"output":"%s","scenes":%d,"missing":0,"dry_run":true}\n' "${OUTPUT}" "${count}"
+  printf '{"output":"%s","scenes":%d,"missing":0,"dry_run":true%s}\n' \
+    "${OUTPUT}" "${count}" "${MODE_JSON}"
   exit 0
 fi
 
-ffmpeg -loglevel error -y -f concat -safe 0 -i "${CONCAT_LIST}" \
-  -c copy "${OUTPUT}" >/dev/null \
-  || aiv_die 8 "ffmpeg concat failed (manifest=${MANIFEST}, output=${OUTPUT})"
+# The re-encode settings are one constant, used by both handoff branches, so a
+# port cannot drift them apart.
+HANDOFF_VCODEC="libx264"
+HANDOFF_ARGS="-crf 20 -g 8 -pix_fmt yuv420p -movflags +faststart -an"
+
+_probe_duration() {
+  ffprobe -v error -show_entries format=duration -of csv=p=0 "$1" 2>/dev/null \
+    | head -1
+}
+
+if [ "${MODE}" = "handoff" ]; then
+  seq_count="$(wc -l < "${SEQ_LIST}" | tr -d ' ')"
+  [ "${seq_count}" -gt 0 ] || aiv_die 7 "stitch: handoff mode found no usable clips"
+
+  if [ -z "${XFADE}" ] || [ "${seq_count}" -eq 1 ]; then
+    # No fade requested (or nothing to fade across): the seams stay hard cuts,
+    # the only difference from --mode cut is the re-encode. Same concat demuxer,
+    # so clip order and skip handling are shared with the cut path.
+    # shellcheck disable=SC2086
+    ffmpeg -loglevel error -y -f concat -safe 0 -i "${CONCAT_LIST}" \
+      -c:v "${HANDOFF_VCODEC}" ${HANDOFF_ARGS} "${OUTPUT}" >/dev/null \
+      || aiv_die 8 "ffmpeg handoff re-encode failed (manifest=${MANIFEST}, output=${OUTPUT})"
+  else
+    # Filtergraph path. Every input is normalised to the FIRST clip's frame
+    # rate and to yuv420p/SAR 1 — xfade refuses mismatched inputs, and a
+    # mismatch here would surface as an opaque filter error rather than as the
+    # source-clip problem it is.
+    first_clip="$(sed -n '1p' "${SEQ_LIST}" | cut -f2)"
+    rate="$(ffprobe -v error -select_streams v:0 -show_entries stream=r_frame_rate \
+      -of csv=p=0 "${first_clip}" 2>/dev/null | head -1)"
+    [ -n "${rate}" ] || aiv_die 8 "stitch: cannot read frame rate of ${first_clip}"
+
+    ff_inputs=""
+    filter=""
+    i=0
+    while [ "${i}" -lt "${seq_count}" ]; do
+      line_no=$((i + 1))
+      p="$(sed -n "${line_no}p" "${SEQ_LIST}" | cut -f2)"
+      ff_inputs="${ff_inputs} -i ${p}"
+      filter="${filter}[${i}:v]fps=${rate},format=yuv420p,setsar=1,settb=AVTB[n${i}];"
+      i=$((i + 1))
+    done
+
+    acc_label="[n0]"
+    acc_dur="$(_probe_duration "$(sed -n '1p' "${SEQ_LIST}" | cut -f2)")"
+    [ -n "${acc_dur}" ] || aiv_die 8 "stitch: cannot read duration of the first clip"
+    faded=0
+    i=1
+    while [ "${i}" -lt "${seq_count}" ]; do
+      line_no=$((i + 1))
+      cont="$(sed -n "${line_no}p" "${SEQ_LIST}" | cut -f1)"
+      p="$(sed -n "${line_no}p" "${SEQ_LIST}" | cut -f2)"
+      dur="$(_probe_duration "${p}")"
+      [ -n "${dur}" ] || aiv_die 8 "stitch: cannot read duration of ${p}"
+      if [ "${cont}" = "handoff" ] || [ "${cont}" = "connector" ]; then
+        # offset = accumulated length so far MINUS the fade; the fade eats the
+        # tail of the accumulated stream, so the total shortens by exactly one
+        # xfade per faded seam.
+        offset="$(awk -v a="${acc_dur}" -v x="${XFADE}" 'BEGIN { printf "%.6f", a - x }')"
+        awk -v o="${offset}" 'BEGIN { exit !(o > 0) }' \
+          || aiv_die 7 "stitch: --xfade ${XFADE}s does not fit before seam ${i} (accumulated length ${acc_dur}s)"
+        filter="${filter}${acc_label}[n${i}]xfade=transition=fade:duration=${XFADE}:offset=${offset}[x${i}];"
+        acc_dur="$(awk -v a="${acc_dur}" -v d="${dur}" -v x="${XFADE}" 'BEGIN { printf "%.6f", a + d - x }')"
+        faded=$((faded + 1))
+      else
+        filter="${filter}${acc_label}[n${i}]concat=n=2:v=1:a=0[x${i}];"
+        acc_dur="$(awk -v a="${acc_dur}" -v d="${dur}" 'BEGIN { printf "%.6f", a + d }')"
+      fi
+      acc_label="[x${i}]"
+      i=$((i + 1))
+    done
+    filter="${filter%;}"
+
+    printf 'stitch: handoff filtergraph — %d clip(s), %d faded seam(s) at %ss, %d hard cut(s)\n' \
+      "${seq_count}" "${faded}" "${XFADE}" "$((seq_count - 1 - faded))" >&2
+
+    # shellcheck disable=SC2086
+    ffmpeg -loglevel error -y ${ff_inputs} -filter_complex "${filter}" \
+      -map "${acc_label}" -c:v "${HANDOFF_VCODEC}" ${HANDOFF_ARGS} "${OUTPUT}" >/dev/null \
+      || aiv_die 8 "ffmpeg handoff xfade failed (manifest=${MANIFEST}, output=${OUTPUT})"
+  fi
+else
+  ffmpeg -loglevel error -y -f concat -safe 0 -i "${CONCAT_LIST}" \
+    -c copy "${OUTPUT}" >/dev/null \
+    || aiv_die 8 "ffmpeg concat failed (manifest=${MANIFEST}, output=${OUTPUT})"
+fi
 
-printf '{"output":"%s","scenes":%d,"missing":%d}\n' "${OUTPUT}" "${count}" "${missing}"
+printf '{"output":"%s","scenes":%d,"missing":%d%s}\n' \
+  "${OUTPUT}" "${count}" "${missing}" "${MODE_JSON}"

package/src/scripts/ai-video/test-pipeline.sh

@@ -19,6 +19,10 @@
 #      PNG magic; pairwise NCC ≥ 0.95 when `compare` is available.
 #      When unavailable, asserts byte-identity (the three frames are
 #      committed identical for the offline path).
+#   7. end_image refusal: an adapter handed `end_image` for a model whose
+#      model-capabilities entry answers `end_frame: null` exits non-zero
+#      and names the model — it never drops the image (adapter-contract.md
+#      § end_image, exit 12).
 #
 # Exit 0 = all assertions pass; 1 = at least one failure (counted +
 # summarized at the end).
@@ -47,7 +51,7 @@ require jq || exit 1
 printf '\n== test-pipeline.sh — banana-arc golden run (offline) ==\n\n'
 
 # ---------------------------------------------------------------- 1
-printf '[1/6] parse-blueprint vs. expected.json\n'
+printf '[1/8] parse-blueprint vs. expected.json\n'
 SCENES="01-simple 02-dialogue-native-audio 03-edge-duration"
 for s in $SCENES; do
   actual="$(bash "$ROOT/src/scripts/ai-video/lib/parse-blueprint.sh" "$PROJECT/scenes/$s/blueprint.txt" 2>/dev/null \
@@ -63,7 +67,7 @@ for s in $SCENES; do
 done
 
 # ---------------------------------------------------------------- 2
-printf '\n[2/6] character.json descriptors verbatim in prompt.subject\n'
+printf '\n[2/8] character.json descriptors verbatim in prompt.subject\n'
 SILHOUETTE="$(jq -r '.characters[0].silhouette' "$PROJECT/character.json")"
 PALETTE="$(jq -r '.characters[0].palette'    "$PROJECT/character.json")"
 WARDROBE="$(jq -r '.characters[0].wardrobe'  "$PROJECT/character.json")"
@@ -84,7 +88,7 @@ for s in $SCENES; do
 done
 
 # ---------------------------------------------------------------- 3
-printf '\n[3/6] audio.* branching matches manifest\n'
+printf '\n[3/8] audio.* branching matches manifest\n'
 for entry in 01-simple:false 02-dialogue-native-audio:true 03-edge-duration:false; do
   s="${entry%%:*}"
   want="${entry##*:}"
@@ -98,7 +102,7 @@ for entry in 01-simple:false 02-dialogue-native-audio:true 03-edge-duration:fals
 done
 
 # ---------------------------------------------------------------- 4
-printf '\n[4/6] adapter capability declarations\n'
+printf '\n[4/8] adapter capability declarations\n'
 declare_caps() {
   local adapter="$1"; local expected="$2"
   local out got
@@ -116,7 +120,7 @@ declare_caps sora          "native"
 declare_caps kling         "none"
 
 # ---------------------------------------------------------------- 5
-printf '\n[5/6] stitch.sh dry-run returns manifest output path\n'
+printf '\n[5/8] stitch.sh dry-run returns manifest output path\n'
 STITCH_OUT="$(jq -r '.stitch_output' "$PROJECT/manifest.json")"
 stitch_log="$(AIV_DRYRUN=true bash "$ROOT/src/scripts/ai-video/stitch.sh" \
   "$PROJECT/manifest.json" "$PROJECT/$STITCH_OUT" 2>&1 || true)"
@@ -126,7 +130,7 @@ case "$stitch_log" in
 esac
 
 # ---------------------------------------------------------------- 6
-printf '\n[6/6] visual regression (locked.png pairwise)\n'
+printf '\n[6/8] visual regression (locked.png pairwise)\n'
 PNG_MAGIC="$(printf '\x89PNG\r\n\x1a\n')"
 prev=""
 have_compare=0
@@ -160,6 +164,80 @@ for s in $SCENES; do
   prev="$f"
 done
 
+# ---------------------------------------------------------------- 7
+printf '\n[7/8] end_image is refused, never dropped\n'
+END_ADAPTER="kling"
+END_MODEL="kling-v2-master"
+END_MANIFEST="$ROOT/src/scripts/ai-video/lib/model-capabilities/$END_ADAPTER.json"
+
+# Precondition: the entry must actually answer end_frame:null, or this case
+# proves nothing. A probed `true` here would make the refusal wrong, not this
+# assertion stale — so it is checked, not assumed.
+end_declared="$(jq -r --arg m "$END_MODEL" \
+  '.models[$m] // {} | .end_frame | if . == null then "null" else tostring end' \
+  "$END_MANIFEST" 2>/dev/null || echo missing)"
+if [ "$end_declared" = "null" ]; then
+  ok "$END_ADAPTER/$END_MODEL declares end_frame=null (unknown)"
+else
+  fail "$END_ADAPTER/$END_MODEL declares end_frame=$end_declared — expected null for this case"
+fi
+
+end_stdin='{"prompt":{"subject":"a lone figure","action":"turns toward the door"},"duration":5,"end_image":"/tmp/aiv-end-frame.png"}'
+end_out="$(printf '%s' "$end_stdin" \
+  | AIV_DRYRUN=true AIV_MODEL="$END_MODEL" \
+    bash "$ROOT/src/scripts/ai-video/adapters/$END_ADAPTER.sh" submit 2>&1)"
+end_rc=$?
+
+if [ "$end_rc" -eq 0 ]; then
+  fail "$END_ADAPTER: end_image was accepted (exit 0) — the image was dropped silently"
+else
+  case "$end_out" in
+    *"$END_MODEL"*end_frame*|*end_frame*"$END_MODEL"*)
+      ok "$END_ADAPTER: end_image refused with exit $end_rc, naming $END_MODEL and end_frame";;
+    *)
+      fail "$END_ADAPTER: exit $end_rc but the message names neither the model nor the field (got: $end_out)";;
+  esac
+fi
+
+# ---------------------------------------------------------------- 8
+printf '\n[8/8] cost calibration prints modeled-vs-charged and does not re-confirm on null\n'
+CAL_PROJECT="$(mktemp -d -t aiv-cal-XXXXXX)"
+mkdir -p "$CAL_PROJECT/scenes/0001"
+printf '{"duration":5}\n' > "$CAL_PROJECT/scenes/0001/prompt.json"
+CAL_ADAPTER="fal"
+CAL_MODEL="fal-ai/ltx-2/text-to-video"
+
+# No cost.json: nothing has been charged. This is the dry-run shape, and it is
+# the case that matters most — `charged: null` must extrapolate nothing and must
+# NOT halt, because treating an absent charge as 0 would make every future
+# estimate quietly cheaper.
+cal_out="$(bash "$ROOT/src/scripts/ai-video/lib/calibrate-cost.sh" \
+  "$CAL_PROJECT" 0001 --adapter "$CAL_ADAPTER" --model "$CAL_MODEL" \
+  --scenes 4 --no-append 2>&1)" && cal_rc=0 || cal_rc=$?
+
+case "$cal_out" in
+  *"modeled \$"*"charged null"*) ok "calibration line prints modeled vs charged with charged: null" ;;
+  *) fail "calibration line missing or malformed (got: $cal_out)" ;;
+esac
+if [ "$cal_rc" -eq 0 ]; then
+  ok "charged: null does not re-confirm (exit 0)"
+else
+  fail "charged: null re-confirmed with exit $cal_rc — an absent charge is not an overrun"
+fi
+
+# Sensitivity: the halt must actually fire when a charge genuinely overruns, or
+# the exit-0 assertion above would pass against a script that never halts.
+printf '{"charged_usd":1.60}\n' > "$CAL_PROJECT/scenes/0001/cost.json"
+cal_over="$(bash "$ROOT/src/scripts/ai-video/lib/calibrate-cost.sh" \
+  "$CAL_PROJECT" 0001 --adapter "$CAL_ADAPTER" --model "$CAL_MODEL" \
+  --scenes 4 --no-append 2>&1)" && cal_over_rc=0 || cal_over_rc=$?
+if [ "$cal_over_rc" -eq 13 ]; then
+  ok "a charge over the tolerance halts with exit 13 for re-confirmation"
+else
+  fail "an overrun exited $cal_over_rc, expected 13 (got: $cal_over)"
+fi
+rm -rf "$CAL_PROJECT"
+
 # ----------------------------------------------------------------
 printf '\n----------------\nresult: %d passed · %d failed\n' "$PASS" "$FAIL"
 if [ "$FAIL" -gt 0 ]; then

package/src/scripts/ai_council/argument_exhaustion.ts

@@ -0,0 +1,130 @@
+/**
+ * The argument-exhaustion stop predicate, with the ordering encoded.
+ *
+ * `road-to-inbox-harvest-2026-08-e-council-topology-evidence` Phase 6.2, and the
+ * resolution of its `early-stop-vs-dissent-ordering` blocker.
+ *
+ * ## The ordering IS the substance
+ *
+ * Anti-conformity repair must fire **before** the cost stop, because
+ * **convergence may be conformity collapse rather than solution stability**. A
+ * round where everyone agrees because nobody pushed back looks, to a cost meter,
+ * exactly like a round where the argument is genuinely finished — and stopping
+ * there reports the collapse as consensus. That is the failure Phase 6 exists to
+ * prevent, so `dissentRepairAttempted` is a **required conjunct of the
+ * predicate**, not a soft check somewhere upstream that the predicate hopes ran.
+ *
+ * Encoding it as a conjunct rather than as call-order discipline is deliberate:
+ * a caller that forgets the order produces a wrong answer silently, while a
+ * caller that forgets to set the field produces `false` — the safe direction,
+ * and a visible one.
+ *
+ * ## Why all four, and why none of them is majority size
+ *
+ * A stop fires only when **every** condition holds:
+ *
+ * 1. `roundsCompleted >= MIN_ROUNDS` — one round is an opening statement, not an
+ *    argument. There is nothing to be exhausted yet.
+ * 2. `dissentRepairAttempted` — the conformity defence got its chance.
+ * 3. every present member is a self-near-duplicate of their own prior round —
+ *    the members have stopped adding, judged by the novelty logic that already
+ *    exists rather than by a new similarity measure.
+ * 4. no unresolved adversarial trigger — an open objection is unfinished
+ *    argument whatever the novelty numbers say.
+ *
+ * **Majority size is absent on purpose** (6.3). Unanimity is the single most
+ * available signal and the single least trustworthy one here: it is exactly what
+ * conformity collapse produces. A predicate that read it would stop soonest in
+ * precisely the case it must not.
+ *
+ * Everything here is pure and reads already-paid outputs — no model call, which
+ * is 6.1's contract and the reason this can be evaluated after every round for
+ * free.
+ */
+
+/** One round is an opening statement; exhaustion needs an exchange. */
+export const MIN_ROUNDS = 2;
+
+export interface StopInputs {
+    /** Rounds completed so far. */
+    roundsCompleted: number;
+    /**
+     * Whether anti-conformity repair ran for the round under judgement.
+     *
+     * The ordering conjunct. `false` when repair was skipped, deferred, or
+     * never reached — all three are the same thing to this predicate, because
+     * all three leave conformity collapse untested.
+     */
+    dissentRepairAttempted: boolean;
+    /**
+     * Per present member: did this round near-duplicate that member's own prior
+     * round? Absent members contribute no entry rather than a `false`.
+     */
+    selfNearDuplicate: readonly boolean[];
+    /** Adversarial triggers raised and not yet resolved. */
+    unresolvedAdversarialTriggers: number;
+}
+
+export type StopBlocker =
+    | 'too-few-rounds'
+    | 'dissent-repair-not-attempted'
+    | 'members-still-adding'
+    | 'unresolved-adversarial-trigger'
+    | 'no-members-present';
+
+export interface StopVerdict {
+    stop: boolean;
+    /** Every condition that failed, not just the first — a caller acting on one
+     *  reason at a time would re-evaluate N times to learn N blockers. */
+    blockers: StopBlocker[];
+}
+
+export function evaluateStop(x: StopInputs): StopVerdict {
+    const blockers: StopBlocker[] = [];
+
+    if (x.roundsCompleted < MIN_ROUNDS) blockers.push('too-few-rounds');
+
+    // The ordering conjunct. Deliberately evaluated as its own condition rather
+    // than folded into a caller-side guard: see the module docstring.
+    if (!x.dissentRepairAttempted) blockers.push('dissent-repair-not-attempted');
+
+    if (x.selfNearDuplicate.length === 0) {
+        // No present member is not "everyone is done" — it is no evidence at
+        // all. `every()` over an empty array is vacuously true, which would
+        // make an empty council the easiest one to stop.
+        blockers.push('no-members-present');
+    } else if (!x.selfNearDuplicate.every((d) => d)) {
+        blockers.push('members-still-adding');
+    }
+
+    if (x.unresolvedAdversarialTriggers > 0) blockers.push('unresolved-adversarial-trigger');
+
+    return { stop: blockers.length === 0, blockers };
+}
+
+/**
+ * The rendering contract for a stopped run (6.4).
+ *
+ * A stopped run must be **textually distinguishable** from a full one. The
+ * failure this prevents is quiet and expensive: an artifact that reads as though
+ * all configured rounds executed, when three of five did, is a claim about
+ * deliberation depth that nobody made on purpose.
+ */
+export interface StopRender {
+    roundsCompleted: number;
+    roundsConfigured: number;
+    savedCalls: number;
+    savedCostUsd: number;
+    exhaustedMembers: readonly string[];
+}
+
+export function renderStop(r: StopRender): string {
+    return [
+        `council: STOPPED EARLY — round ${String(r.roundsCompleted)} of ${String(r.roundsConfigured)}.`,
+        '  reason: argument exhaustion — every present member near-duplicated their own',
+        '          prior round, after anti-conformity repair had already been attempted.',
+        `  exhausted: ${r.exhaustedMembers.length > 0 ? r.exhaustedMembers.join(', ') : '(none named)'}`,
+        `  saved: ${String(r.savedCalls)} call(s), $${r.savedCostUsd.toFixed(4)}`,
+        '  NOT a full run: the remaining configured rounds did not execute.',
+    ].join('\n');
+}