@event4u/agent-config 14.9.0 → 14.11.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/cli_agency_bounds.ts

@@ -0,0 +1,139 @@
+/**
+ * The agency bound each CLI council member is spawned under — one definition.
+ *
+ * A council member is a text-in/text-out oracle: it reads a question and returns
+ * an opinion. It never edits, never runs a command, never fetches. Every CLI here
+ * is an AGENTIC binary that grants tools by default, so an unbounded spawn hands
+ * a read-write agent to a role that needs none of it — the over-broad grant
+ * `tool-safety` § Least Agency exists to refuse.
+ *
+ * ## Why this is a module and not five literals in `clients.ts`
+ *
+ * The flags appeared in two places at once: the `_build_command` of each client,
+ * and `cli_least_agency_canary.ts`, which must spawn the SAME argv to prove the
+ * bound is honoured. Two copies of a value whose entire purpose is to be
+ * verified is a drift waiting to happen — the canary would keep passing against
+ * a flag `clients.ts` had stopped sending.
+ *
+ * ## Every entry is PROBED, and carries the version it was probed against
+ *
+ * A flag that exists in one release and not the next is a claim with a shelf
+ * life. `probed_version` is the string that CLI's own `--version` printed on
+ * `probed_on`; a member whose binary could not be resolved carries `null` for
+ * both and is an honest null, never a guessed flag.
+ *
+ * ## `control` is a permissive VALUE, not the absence of `bound`
+ *
+ * Measured 2026-08-23: with no `--sandbox` in argv at all, codex answers
+ * `patch rejected: writing is blocked by read-only sandbox; rejected by user
+ * approval settings` — its ambient default is already restrictive. So "omit the
+ * bound" is not an unbounded control there, and a canary using one is confounded
+ * by a per-machine setting it never recorded. The control is the smallest
+ * documented step ABOVE the bound, never the widest.
+ */
+
+/** One member's bound, its control counterpart, and the probe behind them. */
+export interface AgencyBound {
+    /** Council member key (`anthropic`, `openai`, …). */
+    readonly member: string;
+    /** The binary the transport resolves. */
+    readonly binary: string;
+    /** The argv fragment that bounds the spawn. Empty = no bound determined. */
+    readonly bound: readonly string[];
+    /**
+     * The permissive counterpart the canary uses as its control. Empty means
+     * "omit the bound", which is only correct where the CLI's default genuinely
+     * grants the capability — verified per member, never assumed.
+     */
+    readonly control: readonly string[];
+    /** What that CLI's own `--version` printed, or null when the binary is absent. */
+    readonly probed_version: string | null;
+    /** ISO date of the probe, or null when the binary is absent. */
+    readonly probed_on: string | null;
+    /** Why this flag and not a sibling — the part a reader cannot re-derive. */
+    readonly rationale: string;
+}
+
+export const AGENCY_BOUNDS: readonly AgencyBound[] = [
+    {
+        member: 'anthropic',
+        binary: 'claude',
+        bound: ['--tools', ''],
+        // Omission IS the control here, and it is verified rather than assumed:
+        // the control arm created the sentinel on 2026-08-23, so the default
+        // genuinely grants the write capability.
+        control: [],
+        probed_version: '2.1.241 (Claude Code)',
+        probed_on: '2026-08-23',
+        rationale:
+            '`claude` grants its full built-in tool set by default; `""` is the documented "disable all tools" value. ' +
+            'Predates this module — added after a live context-window overflow rather than a security pass, which is ' +
+            'why the canary exists at all.',
+    },
+    {
+        member: 'openai',
+        binary: 'codex',
+        bound: ['--sandbox', 'read-only'],
+        control: ['--sandbox', 'workspace-write'],
+        probed_version: 'codex-cli 0.148.0',
+        probed_on: '2026-08-23',
+        rationale:
+            '`codex exec --help` documents `-s, --sandbox <SANDBOX_MODE>` with `read-only`, `workspace-write`, ' +
+            '`danger-full-access`. It sits BESIDE `--skip-git-repo-check`, never instead of it: the trust gate is what ' +
+            'makes a worktree usable at all, the sandbox bounds what the session may then do, and before this the argv ' +
+            'carried the guard REMOVAL with no counterpart. Control is `workspace-write`, the smallest documented step ' +
+            'up — never `danger-full-access`.',
+    },
+    {
+        member: 'gemini',
+        binary: 'gemini',
+        bound: ['--approval-mode', 'plan'],
+        control: ['--approval-mode', 'auto_edit'],
+        probed_version: '0.50.0',
+        probed_on: '2026-08-23',
+        rationale:
+            '`gemini --help` lists `plan (read-only mode)`. NOT `--allowed-tools`, which the same help marks ' +
+            '`DEPRECATED: Use Policy Engine instead` — pinning to it would bind the council to a surface the vendor is ' +
+            'retiring. The siblings move the wrong way: `-y/--yolo` auto-accepts every action, `auto_edit` auto-approves ' +
+            'edit tools, which is exactly why `auto_edit` is the control and not the bound.',
+    },
+    {
+        member: 'xai',
+        binary: 'grok',
+        bound: [],
+        control: [],
+        probed_version: null,
+        probed_on: null,
+        rationale:
+            'not-probed — binary absent on the probing machine. No flag is guessed: a member whose bound was never ' +
+            'determined must not be rendered as bounded.',
+    },
+    {
+        member: 'perplexity',
+        binary: 'perplexity',
+        bound: [],
+        control: [],
+        probed_version: null,
+        probed_on: null,
+        rationale: 'not-probed — binary absent on the probing machine. Same refusal to guess as `xai`.',
+    },
+];
+
+/** The bound argv fragment for a member, or `[]` when none was determined. */
+export function boundFor(member: string): readonly string[] {
+    return AGENCY_BOUNDS.find((b) => b.member === member)?.bound ?? [];
+}
+
+/**
+ * Documented flags that LIFT an agency bound.
+ *
+ * A bound is only a bound if the argv cannot also carry the flag that removes
+ * it, and a presence check on the bound alone passes with both present.
+ */
+export const AGENCY_BYPASS_FLAGS: readonly string[] = [
+    '--dangerously-bypass-approvals-and-sandbox',
+    '--dangerously-bypass-hook-trust',
+    '--yolo',
+    'danger-full-access',
+    'workspace-write',
+];