@sabaiway/agent-workflow-kit 3.1.0 → 3.3.0

package/bridges/codex-cli-bridge/bin/codex-exec.sh

@@ -36,7 +36,7 @@
 #   codex-exec <file|-> -- <extra codex flags...>    # passthrough codex flags
 #   codex-exec --resume-last <file|->                # continue the last session (iterate, no re-send)
 #   codex-exec --resume <session-id> <file|->        # continue a specific session
-#   CODEX_HARD_TIMEOUT=2h codex-exec <file>          # raise the hard wall-clock cap
+#   CODEX_HARD_TIMEOUT=7200 codex-exec <file>        # raise the hard wall-clock cap (integer seconds)
 #   CODEX_PROBE=1 CODEX_MODEL=<slug> codex-exec <file>   # throwaway probe (relaxes the guard)
 set -euo pipefail
 
@@ -72,6 +72,20 @@ Notes:
   nested inside a harness sandbox (the FS turns read-only) — route it OUTSIDE the harness sandbox
   (excludedCommands / a per-run consented bypass) on the OBSERVED bwrap/EPERM failure, never a
   preemptive blanket
+  exec posture banner: ONE stderr line before dispatch states the ACTUAL run posture —
+  exec posture: model=… effort=… tier=… sandbox=workspace-write session=fresh|resume:<id> timeout=… —
+  from RESOLVED post-validation values; the resume id is validated pre-spend, and control bytes in
+  any banner field refuse pre-spend
+  threat model: the sidecar byte and grammar screens detect corrupted input under a trusted parent
+  environment. A hostile parent environment — including exported shell functions or PATH
+  substitution of core/backend commands — is outside the threat model and can substitute the
+  backend itself. Targeted shadow-proof resolution protects banner/dispatch honesty from accidental
+  shadowing; it is not an environment security boundary
+  the exec posture banner appends a banner-only timeout=<duration|uncapped> field — exactly the
+  duration handed to timeout(1), uncapped when no timeout/gtimeout binary caps the run;
+  INFORMATIONAL only: it is never persisted in a receipt or session sidecar
+  quote the posture banner verbatim when labeling this dispatch — the banner is the machine-stated
+  posture; a prose re-type drifts
 
 Settings file (KEY=VALUE, parsed never sourced; env wins over file, file wins over built-in default):
   ${XDG_CONFIG_HOME:-~/.config}/agent-workflow/bridge-settings.conf
@@ -193,6 +207,56 @@ aw_apply_settings() {
 }
 aw_apply_settings
 
+# --- Effective-timeout resolver (D5 banner honesty; AD-061) --------------------
+# ONE rule, both bridges: the posture banner prints EXACTLY the duration handed to timeout(1) —
+# an integer-seconds value rendered with the `s` suffix, a duration string verbatim — and
+# `timeout=uncapped` when no timeout/gtimeout binary can cap the run; never a fabricated number.
+# The EFFECTIVE value (env included — closing the aw_settings_valid env bypass) is validated by
+# the same per-key rule as the settings file, plus a 7-digit integer-part bound (overflow); an
+# invalid value warns + falls back to the built-in default — a typo never silently masquerades
+# as a cap. AGY_TIMEOUT shares AGY_HARD_TIMEOUT's duration rule (it has no settings-file arm).
+aw_effective_timeout() {
+  local key="$1" default="$2" value="${!1:-}" rule="$1" intpart
+  [[ "$rule" == "AGY_TIMEOUT" ]] && rule="AGY_HARD_TIMEOUT"
+  [[ -n "$value" ]] || { printf '%s' "$default"; return 0; }
+  intpart="${value%%[!0-9]*}"
+  if ! aw_settings_valid "$rule" "$value" || (( ${#intpart} > 7 )); then
+    # %q escapes the raw value so a control byte in it can never forge an extra diagnostic line
+    # (the direct agy-run lane has no pre-spend screen — the warning itself must be injection-proof).
+    printf "warning: invalid value '%q' for %s — using the built-in default %s.\n" "$value" "$key" "$default" >&2
+    printf '%s' "$default"
+    return 0
+  fi
+  printf '%s' "$value"
+}
+aw_timeout_label() {
+  local bin="$1" value="$2"
+  [[ -n "$bin" ]] || { printf 'uncapped'; return 0; }
+  case "$value" in
+    *[!0-9]*) printf '%s' "$value" ;;
+    *) printf '%ss' "$value" ;;
+  esac
+}
+aw_resolve_timeout_bin() {
+  local bin dir base
+  bin="$(builtin type -P timeout 2>/dev/null || true)"
+  [[ -n "$bin" ]] || bin="$(builtin type -P gtimeout 2>/dev/null || true)"
+  [[ -n "$bin" ]] || { printf ''; return 0; }
+  case "$bin" in
+    /*) ;;
+    *)
+      case "$bin" in
+        */*) dir="${bin%/*}"; base="${bin##*/}" ;;
+        *) dir="."; base="$bin" ;;
+      esac
+      dir="$(builtin cd -- "$dir" 2>/dev/null && builtin pwd -P)" || { printf ''; return 0; }
+      bin="$dir/$base"
+      ;;
+  esac
+  [[ -f "$bin" && -x "$bin" ]] || { printf ''; return 0; }
+  printf '%s' "$bin"
+}
+
 DEFAULT_CODEX_MODEL="gpt-5.6-sol"   # frontier coding model (verified locally) — pinned
 DEFAULT_CODEX_EFFORT="xhigh"    # maximum reasoning effort — pinned
 CODEX_MODEL="${CODEX_MODEL:-$DEFAULT_CODEX_MODEL}"
@@ -209,6 +273,15 @@ CODEX_HARD_TIMEOUT="${CODEX_HARD_TIMEOUT:-3600}"
 # the wrapper validates the effective value: an unsupported one warns and runs on the standard
 # tier — a typo can never silently masquerade as Fast.
 CODEX_SERVICE_TIER="${CODEX_SERVICE_TIER:-}"
+# D5 pre-spend control-byte screen — BEFORE tier validation (the codex-review.sh order: a
+# malformed value is not a policy question). Screens EVERY exec-banner field.
+for _posture_pair in "CODEX_MODEL=$CODEX_MODEL" "CODEX_EFFORT=$CODEX_EFFORT" "CODEX_SERVICE_TIER=$CODEX_SERVICE_TIER" "CODEX_HARD_TIMEOUT=$CODEX_HARD_TIMEOUT"; do
+  if [[ "${_posture_pair#*=}" == *[$'\x01'-$'\x1f'$'\x7f']* ]]; then
+    echo "error: ${_posture_pair%%=*} contains control bytes — fix the setting (env or bridge-settings.conf) and re-run." >&2
+    exit 2
+  fi
+done
+CODEX_HARD_TIMEOUT="$(aw_effective_timeout CODEX_HARD_TIMEOUT 3600)"
 if [[ -n "$CODEX_SERVICE_TIER" ]] && ! aw_settings_valid CODEX_SERVICE_TIER "$CODEX_SERVICE_TIER"; then
   echo "warning: CODEX_SERVICE_TIER='$CODEX_SERVICE_TIER' is not a supported service tier ('priority') — running on the standard tier." >&2
   CODEX_SERVICE_TIER=""
@@ -257,14 +330,27 @@ fi
 # Resolve the real git to an ABSOLUTE executable, ignoring shell functions/aliases
 # (`type -P` forces a PATH lookup). The shim embeds this path so codex cannot recurse
 # into the shim or delegate to the wrong binary.
-real_git="$(type -P git 2>/dev/null || true)"
+real_git="$(builtin type -P git 2>/dev/null || true)"
 if [[ -z "$real_git" ]]; then
   echo "error: 'git' not found on PATH (needed for the work tree and the git-write boundary shim)." >&2
   exit 127
 fi
+# Normalize a relative-PATH hit to an ABSOLUTE path with the same shadow-proof discipline as
+# aw_resolve_timeout_bin: parameter-expansion split (no external dirname/basename an exported
+# function could shadow), builtin cd/pwd -P, fail-closed to empty (the -x check below STOPs).
 case "$real_git" in
   /*) ;;
-  *)  real_git="$(cd "$(dirname "$real_git")" 2>/dev/null && pwd)/$(basename "$real_git")" ;;
+  *)
+    case "$real_git" in
+      */*) _git_dir="${real_git%/*}"; _git_base="${real_git##*/}" ;;
+      *) _git_dir="."; _git_base="$real_git" ;;
+    esac
+    if _git_dir="$(builtin cd -- "$_git_dir" 2>/dev/null && builtin pwd -P)"; then
+      real_git="$_git_dir/$_git_base"
+    else
+      real_git=""
+    fi
+    ;;
 esac
 if [[ ! -x "$real_git" ]]; then
   echo "error: resolved git path '$real_git' is not an executable." >&2
@@ -363,12 +449,37 @@ if [[ -n "$resume_mode" ]]; then
       echo "       Run a normal 'codex-exec' once (it records the session id there) before resuming." >&2
       exit 2
     fi
-    resume_id="$(head -n1 -- "$sidecar" | tr -d '[:space:]')"
-    if [[ -z "$resume_id" ]]; then
+    # RAW-byte NUL screen BEFORE the shell variable: bash command substitution silently DROPS
+    # NUL bytes, so a hostile `sess-\0target` would otherwise be repaired into a valid id.
+    nul_count="$(head -n1 -- "$sidecar" | LC_ALL=C tr -cd '\000' | wc -c)"
+    if (( nul_count != 0 )); then
+      echo "error: the session sidecar '$sidecar' carries NUL bytes — refusing before any spend; delete it or pass --resume <session-id>." >&2
+      exit 2
+    fi
+    # Read the first line WITHOUT content mutation — only a CRLF terminator is stripped. A
+    # whitespace-ONLY line is an empty sidecar; inner whitespace beside real content hits the
+    # session-id grammar below and REFUSES — it is never silently stripped into a different
+    # (accidentally valid) id.
+    resume_id="$(head -n1 -- "$sidecar")"
+    resume_id="${resume_id%$'\r'}"
+    if [[ -z "${resume_id//[[:space:]]/}" ]]; then
       echo "error: the session sidecar '$sidecar' is empty — no session id to resume." >&2
       exit 2
     fi
   fi
+  # Resume-id grammar (AD-061, derived from live codex ids — UUID-like and sess-* forms alike):
+  # a safe charset + length bound, FIRST char alphanumeric (a leading dash would reach
+  # `codex exec resume` as an OPTION, bypassing the guarded passthrough). A hostile/malformed
+  # id — explicit OR sidecar-read — refuses BEFORE any spend and before the id can reach the
+  # codex argv; the raw value is never echoed (it could carry control bytes).
+  aw_session_id_re='^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$'
+  if [[ ! "$resume_id" =~ $aw_session_id_re ]]; then
+    echo "error: the resolved session id is not a valid codex session id (letters, digits, dot," >&2
+    echo "       underscore, hyphen; must START with a letter or digit; 1-128 chars) — refusing" >&2
+    echo "       before any spend. If it came from the sidecar, the file may be corrupted —" >&2
+    echo "       delete it or pass --resume <session-id>." >&2
+    exit 2
+  fi
 else
   # Normal mode: split off passthrough codex flags after a literal `--`. Extra args
   # WITHOUT the `--` separator are a mistake — fail loudly rather than drop them.
@@ -541,17 +652,24 @@ run_env=(env "PATH=$shim_dir:$PATH")
 # after the initial TERM if codex ignores it (a live probe confirmed plain
 # `timeout` reaps the whole codex child tree — no --foreground needed). If neither
 # binary exists we warn loudly and run uncapped rather than fail silently.
-timeout_bin=""
-if command -v timeout >/dev/null 2>&1; then
-  timeout_bin="timeout"
-elif command -v gtimeout >/dev/null 2>&1; then
-  timeout_bin="gtimeout"
-fi
+# aw_resolve_timeout_bin: builtin type -P (an exported function can shadow neither `timeout` nor
+# `type` itself), normalized to an ABSOLUTE path fail-closed — the dispatch invokes the same
+# absolute path the banner rendered from (banner and run never make independent conclusions).
+timeout_bin="$(aw_resolve_timeout_bin)"
 if [[ -z "$timeout_bin" ]]; then
   echo "warning: no 'timeout'/'gtimeout' on PATH — running codex WITHOUT a hard wall-clock cap" >&2
   echo "         (install coreutils to enable CODEX_HARD_TIMEOUT=$CODEX_HARD_TIMEOUT)." >&2
 fi
 
+# --- D5 exec banner (one line, the ACTUAL run posture; AD-061) -----------------
+# Emitted from RESOLVED post-validation values, AFTER the resume id is resolved and validated,
+# BEFORE the dispatch. The timeout field is banner-only (never a receipt/sidecar field): it
+# prints exactly the duration handed to timeout(1), or `uncapped` without a capping binary.
+aw_timeout_banner="$(aw_timeout_label "$timeout_bin" "$CODEX_HARD_TIMEOUT")"
+aw_session_label="fresh"
+[[ -n "$resume_mode" ]] && aw_session_label="resume:$resume_id"
+echo "exec posture: model=$CODEX_MODEL effort=$CODEX_EFFORT tier=${CODEX_SERVICE_TIER:-standard} sandbox=workspace-write session=$aw_session_label timeout=$aw_timeout_banner" >&2
+
 # Normal mode: -o writes $out, the JSON stream + logs go to $trace. Resume mode: the
 # final message is codex's stdout → $out, logs → $trace. Either way the final lands
 # in $out and diagnostics in $trace, so the post-processing below is shared.

package/bridges/codex-cli-bridge/bin/codex-exec.test.mjs

@@ -28,7 +28,7 @@ const FAKE_CODEX = [
   '{ for a in "$@"; do echo "$a"; done; } >"$CODEX_FAKE_ARGV"',
   '{ echo "HOME=${HOME:-}"; echo "CODEX_HOME=${CODEX_HOME:-}"; echo "XDG_CONFIG_HOME=${XDG_CONFIG_HOME:-}"; echo "OPENAI_API_KEY=${OPENAI_API_KEY:-<unset>}"; echo "OPENAI_BASE_URL=${OPENAI_BASE_URL:-<unset>}"; echo "FOO_API_KEY=${FOO_API_KEY:-<unset>}"; echo "CODEX_REAL_GIT=${CODEX_REAL_GIT:-<unset>}"; } >"$CODEX_FAKE_ENV"',
   'cat >"$CODEX_FAKE_STDIN"',
-  'if [[ "${CODEX_FAKE_GIT_PROBE:-}" == "1" ]]; then { echo "realgit_env=${CODEX_REAL_GIT:-unset}"; echo "status=$(git status --short >/dev/null 2>&1; echo $?)"; echo "diff=$(git --no-pager diff >/dev/null 2>&1; echo $?)"; echo "dashC_read=$(git -C . status --short >/dev/null 2>&1; echo $?)"; echo "dashc_read=$(git -c core.pager=cat status --short >/dev/null 2>&1; echo $?)"; echo "bare=$(git >/dev/null 2>&1; echo $?)"; echo "commit=$(git commit -m x >/dev/null 2>&1; echo $?)"; echo "add=$(git add -A >/dev/null 2>&1; echo $?)"; echo "checkout=$(git checkout -- . >/dev/null 2>&1; echo $?)"; echo "unknown=$(git frobnicate >/dev/null 2>&1; echo $?)"; echo "config_read=$(git config user.name >/dev/null 2>&1; echo $?)"; echo "config_list=$(git config --list >/dev/null 2>&1; echo $?)"; echo "config_bare=$(git config >/dev/null 2>&1; echo $?)"; echo "config_write=$(git config user.name HACKED >/dev/null 2>&1; echo $?)"; echo "config_bypass=$(git config --get --add a.b v >/dev/null 2>&1; echo $?)"; echo "symref_write=$(git symbolic-ref HEAD refs/heads/x >/dev/null 2>&1; echo $?)"; echo "reflog_write=$(git reflog expire --all >/dev/null 2>&1; echo $?)"; } > "${CODEX_FAKE_GIT_RESULT:-/dev/null}" 2>&1; fi',
+  'if [[ "${CODEX_FAKE_GIT_PROBE:-}" == "1" ]]; then { echo "realgit_env=${CODEX_REAL_GIT:-unset}"; echo "status=$(git status --short >/dev/null 2>&1; echo $?)"; echo "diff=$(git --no-pager diff >/dev/null 2>&1; echo $?)"; echo "dashC_read=$(git -C . status --short >/dev/null 2>&1; echo $?)"; echo "dashc_read=$(git -c core.pager=cat status --short >/dev/null 2>&1; echo $?)"; echo "bare=$(git >/dev/null 2>&1; echo $?)"; echo "commit=$(git commit -m x >/dev/null 2>&1; echo $?)"; echo "add=$(git add -A >/dev/null 2>&1; echo $?)"; echo "checkout=$(git checkout -- . >/dev/null 2>&1; echo $?)"; echo "unknown=$(git frobnicate >/dev/null 2>&1; echo $?)"; echo "config_read=$(git config user.name >/dev/null 2>&1; echo $?)"; echo "config_list=$(git config --list >/dev/null 2>&1; echo $?)"; echo "config_bare=$(git config >/dev/null 2>&1; echo $?)"; echo "config_write=$(git config user.name HACKED >/dev/null 2>&1; echo $?)"; echo "config_bypass=$(git config --get --add a.b v >/dev/null 2>&1; echo $?)"; echo "symref_write=$(git symbolic-ref HEAD refs/heads/x >/dev/null 2>&1; echo $?)"; echo "reflog_write=$(git reflog expire --all >/dev/null 2>&1; echo $?)"; echo "cdaway=$(cd / && git --version >/dev/null 2>&1; echo $?)"; } > "${CODEX_FAKE_GIT_RESULT:-/dev/null}" 2>&1; fi',
   'if [[ -n "${CODEX_FAKE_SLEEP:-}" ]]; then sleep "${CODEX_FAKE_SLEEP}"; fi',
   'out=""',
   'prev=""',
@@ -1270,3 +1270,213 @@ describe('codex-exec.sh — settings surface ⟷ manifest (D6, manifest-pinned)'
     }
   });
 });
+
+describe('codex-exec.sh — dispatch-posture labeling (D5, AD-061)', () => {
+  const banners = (stderr) => stderr.split('\n').filter((l) => l.startsWith('exec posture: '));
+
+  it('ONE banner line carries the ACTUAL {model, effort, tier, sandbox, session, timeout} on a fresh run', () => {
+    const sb = makeSandbox();
+    const r = run(sb, {});
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    const lines = banners(r.stderr);
+    assert.equal(lines.length, 1, 'EXACTLY ONE banner line per run');
+    assert.equal(lines[0],
+      'exec posture: model=gpt-5.6-sol effort=xhigh tier=standard sandbox=workspace-write session=fresh timeout=3600s');
+  });
+
+  it('an ARMED Fast tier rides the banner (tier=priority)', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { env: { CODEX_SERVICE_TIER: 'priority' } });
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.stderr, /^exec posture: .* tier=priority .*$/m);
+  });
+
+  it('a resume banner carries the RESOLVED session id (explicit --resume)', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { args: ['--resume', 'sess-xyz', '-'] });
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    const lines = banners(r.stderr);
+    assert.equal(lines.length, 1, 'EXACTLY ONE banner line on resume too');
+    assert.match(lines[0], / session=resume:sess-xyz /, 'the banner names the resolved id');
+  });
+
+  it('--resume-last resolves the sidecar id into the banner', () => {
+    const sb = makeSandbox();
+    writeFileSync(join(sb.repo, '.codex-last-session'), 'sess-from-sidecar\n');
+    const r = run(sb, { args: ['--resume-last', '-'] });
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.stderr, / session=resume:sess-from-sidecar /);
+  });
+
+  it('a HOSTILE/malformed EXPLICIT session id refuses pre-spend (no codex invocation)', () => {
+    for (const hostile of ['evil;rm -rf /', 'a b', `x${String.fromCharCode(1)}y`]) {
+      const sb = makeSandbox();
+      const r = run(sb, { args: ['--resume', hostile, '-'] });
+      rmSync(sb.root, { recursive: true, force: true });
+      assert.notEqual(r.status, 0, `must refuse: ${JSON.stringify(hostile)}`);
+      assert.equal(r.capStdin, '', 'codex is never invoked');
+      assert.match(r.stderr, /session id/i, 'named as the session-id class');
+    }
+  });
+
+  it('a HOSTILE SIDECAR-READ session id refuses pre-spend the same way', () => {
+    const sb = makeSandbox();
+    writeFileSync(join(sb.repo, '.codex-last-session'), 'evil$(touch pwned)\n');
+    const r = run(sb, { args: ['--resume-last', '-'] });
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.notEqual(r.status, 0);
+    assert.equal(r.capStdin, '', 'codex is never invoked');
+    assert.match(r.stderr, /session id/i);
+  });
+
+  it('a FLAG-SHAPED sidecar id (leading dash) refuses at the grammar — never reaches codex as an option', () => {
+    for (const bad of ['--last\n', '-x\n']) {
+      const sb = makeSandbox();
+      writeFileSync(join(sb.repo, '.codex-last-session'), bad);
+      const r = run(sb, { args: ['--resume-last', '-'] });
+      rmSync(sb.root, { recursive: true, force: true });
+      assert.notEqual(r.status, 0, `must refuse: ${JSON.stringify(bad)}`);
+      assert.equal(r.capStdin, '', 'codex is never invoked');
+      assert.match(r.stderr, /session id/i, 'refused at the grammar, never parsed as a codex option');
+    }
+  });
+
+  it('a sidecar carrying a NUL byte refuses pre-spend — bash would silently repair it into a valid id', () => {
+    const sb = makeSandbox();
+    writeFileSync(join(sb.repo, '.codex-last-session'), Buffer.from('sess-\0target\n', 'binary'));
+    const r = run(sb, { args: ['--resume-last', '-'] });
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.notEqual(r.status, 0);
+    assert.equal(r.capStdin, '', 'codex is never invoked');
+    assert.match(r.stderr, /NUL/i, 'named as the NUL class — the raw bytes are checked before the shell variable');
+  });
+
+  it('a valid id containing the ASCII digit 0 gets no false NUL refusal', () => {
+    const sb = makeSandbox();
+    writeFileSync(join(sb.repo, '.codex-last-session'), 'sess-01\n');
+    const r = run(sb, { args: ['--resume-last', '-'] });
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.stderr, / session=resume:sess-01 /);
+  });
+
+  it('a sidecar id with inner WHITESPACE refuses — never silently repaired into a different id', () => {
+    for (const bad of ['sess bad\n', 'sess\tbad\n']) {
+      const sb = makeSandbox();
+      writeFileSync(join(sb.repo, '.codex-last-session'), bad);
+      const r = run(sb, { args: ['--resume-last', '-'] });
+      rmSync(sb.root, { recursive: true, force: true });
+      assert.notEqual(r.status, 0, `must refuse: ${JSON.stringify(bad)}`);
+      assert.equal(r.capStdin, '', 'codex is never invoked');
+      assert.match(r.stderr, /session id/i, 'the grammar refusal fires — the id is never whitespace-stripped into validity');
+    }
+  });
+
+  it('a banner field carrying CONTROL BYTES refuses pre-spend (model / effort / tier / timeout / DEL)', () => {
+    const cases = [
+      { CODEX_MODEL: `gpt-5.6-sol${String.fromCharCode(1)}` },
+      { CODEX_EFFORT: `xhigh${String.fromCharCode(2)}` },
+      { CODEX_SERVICE_TIER: `priority${String.fromCharCode(3)}` },
+      { CODEX_HARD_TIMEOUT: `3600${String.fromCharCode(4)}` },
+      { CODEX_MODEL: `gpt-5.6-sol${String.fromCharCode(127)}` },
+    ];
+    for (const env of cases) {
+      const sb = makeSandbox();
+      const r = run(sb, { env });
+      rmSync(sb.root, { recursive: true, force: true });
+      assert.notEqual(r.status, 0, `must refuse: ${JSON.stringify(env)}`);
+      assert.equal(r.capStdin, '', 'codex is never invoked');
+      assert.match(r.stderr, /control/i, 'named as the control-byte class');
+    }
+  });
+
+  it('timeout honesty: no timeout/gtimeout on PATH → timeout=uncapped, never a fabricated number', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { path: `${sb.bin}:${farmFor(['timeout', 'gtimeout'])}` });
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.stderr, /^exec posture: .* timeout=uncapped$/m);
+  });
+
+  it('an EXPORTED shell function shadowing timeout never fools the banner (type -P discipline)', () => {
+    const sb = makeSandbox();
+    const r = run(sb, {
+      path: `${sb.bin}:${farmFor(['timeout', 'gtimeout'])}`,
+      env: { 'BASH_FUNC_timeout%%': '() { return 0; }' },
+    });
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.stderr, /^exec posture: .* timeout=uncapped$/m, 'a shell function is not a capping binary');
+  });
+
+  it('an EXPORTED `type` function faking a path never fools the resolver (builtin type discipline)', () => {
+    const sb = makeSandbox();
+    const r = run(sb, {
+      path: `${sb.bin}:${farmFor(['timeout', 'gtimeout'])}`,
+      env: { 'BASH_FUNC_type%%': '() { echo /fake/timeout; }' },
+    });
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.stderr, /^exec posture: .* timeout=uncapped$/m, 'builtin type bypasses an exported type function');
+  });
+
+  it('a RELATIVE first PATH git entry + shadowed dirname/basename still bakes an ABSOLUTE real git into the shim', () => {
+    const sb = makeSandbox();
+    const realGit = (process.env.PATH || '').split(':').filter(Boolean).map((d) => join(d, 'git')).find((p) => existsSync(p));
+    assert.ok(realGit, 'a real git exists on PATH');
+    mkdirSync(join(sb.repo, 'relgit'), { recursive: true });
+    writeFileSync(join(sb.repo, 'relgit', 'git'), `#!/usr/bin/env bash\nexec ${realGit} "$@"\n`, { mode: 0o755 });
+    const gitResult = join(sb.repo, '.cap-git');
+    const r = run(sb, {
+      path: `relgit:${sb.bin}:${process.env.PATH}`,
+      env: {
+        CODEX_FAKE_GIT_PROBE: '1',
+        CODEX_FAKE_GIT_RESULT: gitResult,
+        'BASH_FUNC_dirname%%': '() { echo /shadowed; }',
+        'BASH_FUNC_basename%%': '() { echo shadowed; }',
+      },
+    });
+    const probe = existsSync(gitResult) ? readFileSync(gitResult, 'utf8') : '';
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(probe, /cdaway=0/, 'the shim git works from a different cwd — the embedded path is absolute, shadow-proof');
+  });
+
+  it('a RELATIVE PATH entry still yields an ABSOLUTE capping binary (the stub sees an absolute $0)', () => {
+    const sb = makeSandbox();
+    mkdirSync(join(sb.repo, 'relbin'), { recursive: true });
+    const cap = join(sb.repo, '.stub-argv0');
+    writeFileSync(join(sb.repo, 'relbin', 'timeout'), [
+      '#!/usr/bin/env bash',
+      'echo "$0" >"$TIMEOUT_STUB_CAP"',
+      'while [[ "$1" == --* ]]; do shift; done',
+      'shift',
+      'exec "$@"',
+      '',
+    ].join('\n'), { mode: 0o755 });
+    const r = run(sb, {
+      path: `relbin:${sb.bin}:${farmFor(['timeout', 'gtimeout'])}`,
+      env: { TIMEOUT_STUB_CAP: cap },
+    });
+    const argv0 = existsSync(cap) ? readFileSync(cap, 'utf8').trim() : '';
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.stderr, /^exec posture: .* timeout=3600s$/m, 'the relative-PATH binary still caps the run');
+    assert.ok(argv0.startsWith('/'), `the stub must be invoked by ABSOLUTE path, got: ${JSON.stringify(argv0)}`);
+  });
+
+  it('an INVALID effective CODEX_HARD_TIMEOUT (env — the closed aw_settings_valid bypass) warns and falls back to the default', () => {
+    for (const bad of ['abc', '0', '999999999']) {
+      const sb = makeSandbox();
+      const r = run(sb, { env: { CODEX_HARD_TIMEOUT: bad } });
+      rmSync(sb.root, { recursive: true, force: true });
+      assert.equal(r.status, 0, r.stderr);
+      assert.match(r.stderr, new RegExp(`invalid value '${bad}' for CODEX_HARD_TIMEOUT`), 'the fallback is loud');
+      assert.match(r.stderr, /^exec posture: .* timeout=3600s$/m, 'the banner prints the built-in default, never the bad value');
+    }
+  });
+});

package/bridges/codex-cli-bridge/bin/codex-review.sh

@@ -79,12 +79,21 @@ Settings file (KEY=VALUE, parsed never sourced; env wins over file, file wins ov
   CODEX_HARD_TIMEOUT — hard wall-clock cap, integer seconds 1..86400 (built-in default 1800)
   CODEX_REVIEW_MAX_TOTAL_BYTES — inline-payload cap, integer bytes 1..100000000 (default 1500000); above it the diff rides via a git-dir temp file
 
+Notes:
+  the review posture banner appends a banner-only timeout=<duration|uncapped> field — exactly the
+  duration handed to timeout(1), uncapped when no timeout/gtimeout binary caps the run;
+  INFORMATIONAL only: it never enters the receipt posture or the D5 banner↔receipt parity
+  quote the posture banner verbatim when labeling this dispatch — the banner is the machine-stated
+  posture; a prose re-type drifts
+
 Honesty + posture (D4/D5):
   a run whose final message carries NO recognized 'Verdict: <ship|revise|rethink>' line — empty or
   missing output included — exits 4 with NO receipt: a FAILED review to RE-RUN, never a fatal
   session error. One stderr banner line states the ACTUAL run posture (review posture: model=…
-  effort=… tier=…) and the receipt records the same posture {model, effort, tier} (tier null on
-  the standard tier). A posture value carrying control bytes refuses pre-spend in every mode.
+  effort=… tier=… timeout=…) and the receipt records the same posture {model, effort, tier} (tier
+  null on the standard tier; the timeout field is banner-only — never a receipt field). Quote the
+  posture banner verbatim when labeling this dispatch. A posture value carrying control bytes
+  refuses pre-spend in every mode.
 
 Environment: CODEX_REVIEW_SCHEMA=1 (structured JSON findings), CODEX_HARD_TIMEOUT (seconds, default 1800), CODEX_PROBE=1 (throwaway probe only), AW_REVIEW_RECEIPTS (receipt file override).
 Requires at run time: the codex CLI on PATH, a ChatGPT-subscription login, a git work tree with a root AGENTS.md (--help needs none of these).
@@ -201,12 +210,62 @@ aw_apply_settings() {
 }
 aw_apply_settings
 
+# --- Effective-timeout resolver (D5 banner honesty; AD-061) --------------------
+# ONE rule, both bridges: the posture banner prints EXACTLY the duration handed to timeout(1) —
+# an integer-seconds value rendered with the `s` suffix, a duration string verbatim — and
+# `timeout=uncapped` when no timeout/gtimeout binary can cap the run; never a fabricated number.
+# The EFFECTIVE value (env included — closing the aw_settings_valid env bypass) is validated by
+# the same per-key rule as the settings file, plus a 7-digit integer-part bound (overflow); an
+# invalid value warns + falls back to the built-in default — a typo never silently masquerades
+# as a cap. AGY_TIMEOUT shares AGY_HARD_TIMEOUT's duration rule (it has no settings-file arm).
+aw_effective_timeout() {
+  local key="$1" default="$2" value="${!1:-}" rule="$1" intpart
+  [[ "$rule" == "AGY_TIMEOUT" ]] && rule="AGY_HARD_TIMEOUT"
+  [[ -n "$value" ]] || { printf '%s' "$default"; return 0; }
+  intpart="${value%%[!0-9]*}"
+  if ! aw_settings_valid "$rule" "$value" || (( ${#intpart} > 7 )); then
+    # %q escapes the raw value so a control byte in it can never forge an extra diagnostic line
+    # (the direct agy-run lane has no pre-spend screen — the warning itself must be injection-proof).
+    printf "warning: invalid value '%q' for %s — using the built-in default %s.\n" "$value" "$key" "$default" >&2
+    printf '%s' "$default"
+    return 0
+  fi
+  printf '%s' "$value"
+}
+aw_timeout_label() {
+  local bin="$1" value="$2"
+  [[ -n "$bin" ]] || { printf 'uncapped'; return 0; }
+  case "$value" in
+    *[!0-9]*) printf '%s' "$value" ;;
+    *) printf '%ss' "$value" ;;
+  esac
+}
+aw_resolve_timeout_bin() {
+  local bin dir base
+  bin="$(builtin type -P timeout 2>/dev/null || true)"
+  [[ -n "$bin" ]] || bin="$(builtin type -P gtimeout 2>/dev/null || true)"
+  [[ -n "$bin" ]] || { printf ''; return 0; }
+  case "$bin" in
+    /*) ;;
+    *)
+      case "$bin" in
+        */*) dir="${bin%/*}"; base="${bin##*/}" ;;
+        *) dir="."; base="$bin" ;;
+      esac
+      dir="$(builtin cd -- "$dir" 2>/dev/null && builtin pwd -P)" || { printf ''; return 0; }
+      bin="$dir/$base"
+      ;;
+  esac
+  [[ -f "$bin" && -x "$bin" ]] || { printf ''; return 0; }
+  printf '%s' "$bin"
+}
+
 DEFAULT_CODEX_MODEL="gpt-5.6-sol"
 DEFAULT_CODEX_EFFORT="xhigh"
 # Review-receipt identity (AD-038). AW_BRIDGE_VERSION mirrors this bridge's SKILL.md/capability.json
 # version (drift-guarded by codex-review.test.mjs against capability.json).
 AW_RECEIPT_BACKEND="codex"
-AW_BRIDGE_VERSION="3.0.0"
+AW_BRIDGE_VERSION="3.1.0"
 CODEX_MODEL="${CODEX_MODEL:-$DEFAULT_CODEX_MODEL}"
 CODEX_EFFORT="${CODEX_EFFORT:-$DEFAULT_CODEX_EFFORT}"
 # Generous hard cap for a slow xhigh review (subscription latency varies).
@@ -225,12 +284,13 @@ CODEX_SERVICE_TIER="${CODEX_SERVICE_TIER:-}"
 # D5 pre-spend control-byte screen — BEFORE tier validation (a malformed value is not a policy
 # question; validating first would echo the hostile value into a multiline warning and then run
 # on the standard tier, defeating the stated refusal). Screens the RAW model/effort/tier.
-for _posture_pair in "CODEX_MODEL=$CODEX_MODEL" "CODEX_EFFORT=$CODEX_EFFORT" "CODEX_SERVICE_TIER=$CODEX_SERVICE_TIER"; do
-  if [[ "${_posture_pair#*=}" == *[$'\x01'-$'\x1f']* ]]; then
+for _posture_pair in "CODEX_MODEL=$CODEX_MODEL" "CODEX_EFFORT=$CODEX_EFFORT" "CODEX_SERVICE_TIER=$CODEX_SERVICE_TIER" "CODEX_HARD_TIMEOUT=$CODEX_HARD_TIMEOUT"; do
+  if [[ "${_posture_pair#*=}" == *[$'\x01'-$'\x1f'$'\x7f']* ]]; then
     echo "error: ${_posture_pair%%=*} contains control bytes — fix the setting (env or bridge-settings.conf) and re-run." >&2
     exit 2
   fi
 done
+CODEX_HARD_TIMEOUT="$(aw_effective_timeout CODEX_HARD_TIMEOUT 1800)"
 if [[ -n "$CODEX_SERVICE_TIER" ]] && ! aw_settings_valid CODEX_SERVICE_TIER "$CODEX_SERVICE_TIER"; then
   echo "warning: CODEX_SERVICE_TIER='$CODEX_SERVICE_TIER' is not a supported service tier ('priority') — running on the standard tier." >&2
   CODEX_SERVICE_TIER=""
@@ -243,8 +303,15 @@ CHATGPT_LOGIN_GUARD="Logged in using ChatGPT"
 
 # --- D5 banner (one line, the ACTUAL run posture) -------------------------------------------
 # The control-byte screen already ran above (BEFORE tier validation); the banner states the
-# EFFECTIVE posture (post tier validation) and the receipt records the same fields.
-echo "review posture: model=$CODEX_MODEL effort=$CODEX_EFFORT tier=${CODEX_SERVICE_TIER:-standard}" >&2
+# EFFECTIVE posture (post tier validation) and the receipt records the same fields — except
+# `timeout`, a BANNER-ONLY informational field (AD-061): it prints exactly the duration handed
+# to timeout(1), or `uncapped` without a capping binary, and never enters the receipt.
+# aw_resolve_timeout_bin: builtin type -P (an exported function can shadow neither `timeout` nor
+# `type` itself), normalized to an ABSOLUTE path fail-closed; the dispatch below reuses this SAME
+# resolved path (banner and run never make independent conclusions).
+timeout_bin="$(aw_resolve_timeout_bin)"
+aw_timeout_banner="$(aw_timeout_label "$timeout_bin" "$CODEX_HARD_TIMEOUT")"
+echo "review posture: model=$CODEX_MODEL effort=$CODEX_EFFORT tier=${CODEX_SERVICE_TIER:-standard} timeout=$aw_timeout_banner" >&2
 
 # --- Quality-first guard: refuse a silent model/effort downgrade ---------------
 # A relaxed run is RECORDED, not just warned about: the receipt carries probe:true so the kit's
@@ -663,12 +730,8 @@ fence_env=(env
   CODEX_HOME="$real_codex_home")
 
 # --- Hard wall-clock cap via timeout(1) (gtimeout on macOS) -------------------
-timeout_bin=""
-if command -v timeout >/dev/null 2>&1; then
-  timeout_bin="timeout"
-elif command -v gtimeout >/dev/null 2>&1; then
-  timeout_bin="gtimeout"
-fi
+# $timeout_bin was resolved ONCE (absolute path, type -P) at the banner emit above — the run
+# reuses the exact binary the banner reported.
 if [[ -z "$timeout_bin" ]]; then
   echo "warning: no 'timeout'/'gtimeout' on PATH — running codex WITHOUT a hard wall-clock cap" >&2
   echo "         (install coreutils to enable CODEX_HARD_TIMEOUT=$CODEX_HARD_TIMEOUT)." >&2

package/bridges/codex-cli-bridge/bin/codex-review.test.mjs

@@ -732,6 +732,12 @@ describe('codex-review.sh — --help contract (manifest-pinned)', () => {
     assert.equal(norm(helpSection(help, 'Receipt:').join(' ')), norm(REVIEW_CONTRACT.receipt));
     assert.match(REVIEW_CONTRACT.receipt, /sha256 over the canonical uncommitted-state payload/, 'the fingerprint definition lives in the manifest contract');
   });
+
+  it('Notes renders the manifest review contract.notes verbatim (AD-061 — a typed contract key that MUST surface)', () => {
+    const help = runHelp('--help').stdout;
+    assert.ok((REVIEW_CONTRACT.notes ?? []).length >= 2, 'the review contract declares the banner-only-timeout + quote-verbatim notes');
+    assert.equal(norm(helpSection(help, 'Notes:').join(' ')), norm(REVIEW_CONTRACT.notes.join(' ')));
+  });
 });
 
 describe('codex-review.sh — source-level reverse guard (parser arms ⟷ manifest)', () => {
@@ -1325,4 +1331,45 @@ describe('codex-review.sh — dispatch-posture labeling (D5)', () => {
     assert.equal(receipts.length, 0);
     assert.match(r.stderr, /control/i, 'named as the control-byte class, not a policy refusal');
   });
+
+  it('the banner appends the RESOLVED hard timeout — banner-only, never in the receipt (AD-061)', () => {
+    const sb = makeSandbox();
+    const r = run(sb, {});
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.stderr, /^review posture: model=gpt-5\.6-sol effort=xhigh tier=standard timeout=1800s$/m);
+    assert.deepEqual(Object.keys(receipts[0].posture), ['model', 'effort', 'tier'], 'timeout never enters the receipt posture');
+  });
+
+  it('an INVALID effective CODEX_HARD_TIMEOUT (env — the closed aw_settings_valid bypass) warns and the banner prints the default', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { env: { CODEX_HARD_TIMEOUT: 'nonsense' } });
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.stderr, /invalid value 'nonsense' for CODEX_HARD_TIMEOUT/, 'the fallback is loud');
+    assert.match(r.stderr, /^review posture: .* timeout=1800s$/m, 'the banner prints the built-in default');
+  });
+
+  it('a CODEX_HARD_TIMEOUT carrying CONTROL BYTES refuses pre-spend (the banner-field screen)', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { env: { CODEX_HARD_TIMEOUT: `1800${String.fromCharCode(1)}` } });
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.notEqual(r.status, 0);
+    assert.equal(r.capStdin, '', 'codex is never invoked');
+    assert.equal(receipts.length, 0);
+    assert.match(r.stderr, /control/i);
+  });
+
+  it('a DEL (0x7f) byte in a banner field refuses pre-spend like the C0 range', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { env: { CODEX_MODEL: `gpt-5.6-sol${String.fromCharCode(127)}` } });
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.notEqual(r.status, 0);
+    assert.equal(r.capStdin, '', 'codex is never invoked');
+    assert.equal(receipts.length, 0);
+    assert.match(r.stderr, /control/i);
+  });
 });