@sabaiway/agent-workflow-kit 3.0.0 → 3.2.0

package/bridges/antigravity-cli-bridge/bin/agy-review.test.mjs

@@ -1,13 +1,13 @@
-import { describe, it } from 'node:test';
+import { describe, it, after } from 'node:test';
 import assert from 'node:assert/strict';
 import {
   mkdtempSync, mkdirSync, writeFileSync, chmodSync, rmSync, readFileSync,
-  existsSync, readdirSync, symlinkSync,
+  existsSync, readdirSync, symlinkSync, cpSync,
 } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { spawnSync } from 'node:child_process';
+import { spawnSync, execFile } from 'node:child_process';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const WRAPPER = join(HERE, 'agy-review.sh');
@@ -65,15 +65,23 @@ const makePathWithout = (root, exclude = []) => {
   return dir;
 };
 
-// `clean: true` leaves a pristine committed tree (for the no-diff preflight); the default leaves one
-// untracked file so `code` mode has a diff to review.
-const makeSandbox = ({ clean = false } = {}) => {
-  const home = mkdtempSync(join(tmpdir(), 'agy-review-test-'));
+// The PATH farms and the sandbox base are READ-ONLY per invocation, so both are built ONCE and
+// shared: a per-run farm rebuild (thousands of symlinks) plus a per-test `git init`+commit were
+// the suite's dominant wall cost, not the wrapper under test.
+const SHARED_ROOT = mkdtempSync(join(tmpdir(), 'agy-review-shared-'));
+after(() => rmSync(SHARED_ROOT, { recursive: true, force: true }));
+const farms = new Map();
+const farmFor = (exclude) => {
+  const key = exclude.join('|');
+  if (!farms.has(key)) farms.set(key, makePathWithout(SHARED_ROOT, exclude));
+  return farms.get(key);
+};
+
+const TEMPLATE_HOME = (() => {
+  const home = join(SHARED_ROOT, 'template-home');
   const bin = join(home, '.local', 'bin');
   mkdirSync(bin, { recursive: true });
-  const stub = join(bin, 'agy');
-  writeFileSync(stub, FAKE_AGY, { mode: 0o755 });
-  chmodSync(stub, 0o755);
+  writeFileSync(join(bin, 'agy'), FAKE_AGY, { mode: 0o755 });
   const repo = join(home, 'repo');
   mkdirSync(repo);
   const g = (...args) => spawnSync('git', args, { cwd: repo, encoding: 'utf8' });
@@ -83,13 +91,25 @@ const makeSandbox = ({ clean = false } = {}) => {
   writeFileSync(join(repo, 'base.txt'), 'committed base\n');
   g('add', '-A');
   g('commit', '-qm', 'base');
+  return home;
+})();
+
+// `clean: true` leaves a pristine committed tree (for the no-diff preflight); the default leaves one
+// untracked file so `code` mode has a diff to review.
+const makeSandbox = ({ clean = false } = {}) => {
+  const home = mkdtempSync(join(tmpdir(), 'agy-review-test-'));
+  cpSync(TEMPLATE_HOME, home, { recursive: true });
+  const bin = join(home, '.local', 'bin');
+  chmodSync(join(bin, 'agy'), 0o755);
+  const repo = join(home, 'repo');
+  const g = (...args) => spawnSync('git', args, { cwd: repo, encoding: 'utf8' });
   if (!clean) writeFileSync(join(repo, 'pending.txt'), 'PENDING_UNTRACKED_BODY\n');
   return { home, bin, repo, g };
 };
 
 const run = (sb, { args, env = {}, cwd } = {}) => {
   const { home, bin, repo } = sb;
-  const farm = makePathWithout(home, ['agy', 'agy-run']);
+  const farm = farmFor(['agy', 'agy-run']);
   const cap = {
     argv: join(home, 'cap-argv'), env: join(home, 'cap-env'), prompt: join(home, 'cap-prompt'),
     sentinel: join(home, 'cap-sentinel'), adddir: join(home, 'cap-adddir'),
@@ -122,6 +142,44 @@ const run = (sb, { args, env = {}, cwd } = {}) => {
   };
 };
 
+// Async twin of run() for the two sleep-bound timeout tests: spawnSync blocks the event loop
+// for the whole deliberate wait, so a concurrent describe could not overlap them. Same spawn
+// contract and captures.
+const runAsync = (sb, { args, env = {}, cwd } = {}) =>
+  new Promise((done) => {
+    const { home, bin, repo } = sb;
+    const cap = {
+      argv: join(home, 'cap-argv'), env: join(home, 'cap-env'), prompt: join(home, 'cap-prompt'),
+      sentinel: join(home, 'cap-sentinel'), adddir: join(home, 'cap-adddir'),
+      adddirMode: join(home, 'cap-adddir-mode'), artifactMode: join(home, 'cap-artifact-mode'),
+      artifactCopy: join(home, 'cap-artifact-copy'),
+    };
+    const child = execFile('bash', [WRAPPER, ...args], {
+      cwd: cwd || repo,
+      encoding: 'utf8',
+      timeout: 30000,
+      env: {
+        HOME: home,
+        PATH: `${bin}:${farmFor(['agy', 'agy-run'])}`,
+        TMPDIR: process.env.TMPDIR ?? '/tmp',
+        AGY_FAKE_ARGV: cap.argv, AGY_FAKE_ENV: cap.env, AGY_FAKE_PROMPT: cap.prompt,
+        AGY_FAKE_SENTINEL: cap.sentinel, AGY_FAKE_ADDDIR: cap.adddir, AGY_FAKE_ADDDIR_MODE: cap.adddirMode,
+        AGY_FAKE_ARTIFACT_MODE: cap.artifactMode, AGY_FAKE_ARTIFACT_COPY: cap.artifactCopy,
+        ...env,
+      },
+    }, (error, stdout, stderr) => {
+      const readIf = (p) => (existsSync(p) ? readFileSync(p, 'utf8') : '');
+      done({
+        status: error ? (error.code ?? 1) : 0, stdout, stderr,
+        invoked: existsSync(cap.sentinel),
+        argv: readIf(cap.argv), capEnv: readIf(cap.env), prompt: readIf(cap.prompt),
+        adddir: readIf(cap.adddir).trim(), adddirMode: readIf(cap.adddirMode).trim(),
+        artifactMode: readIf(cap.artifactMode).trim(), artifactCopy: readIf(cap.artifactCopy),
+      });
+    });
+    child.stdin.end();
+  });
+
 describe('agy-review.sh — model policy advisory (1)', () => {
   it('warns for a non-frontier model but still runs', () => {
     const sb = makeSandbox();
@@ -424,11 +482,11 @@ describe('agy-review.sh — resume / round-2 delta (7)', () => {
   });
 });
 
-describe('agy-review.sh — delegated guards inherited via agy-run (9, 10)', () => {
-  it('hard timeout: a sleeping stub is killed at AGY_HARD_TIMEOUT', () => {
+describe('agy-review.sh — delegated guards inherited via agy-run (9, 10)', { concurrency: true }, () => {
+  it('hard timeout: a sleeping stub is killed at AGY_HARD_TIMEOUT', async () => {
     const sb = makeSandbox();
     const started = Date.now();
-    const r = run(sb, { args: ['code', '--facts', 'f'], env: { AGY_FAKE_SLEEP: '30', AGY_HARD_TIMEOUT: '2s', AGY_TIMEOUT: '2s' } });
+    const r = await runAsync(sb, { args: ['code', '--facts', 'f'], env: { AGY_FAKE_SLEEP: '30', AGY_HARD_TIMEOUT: '2s', AGY_TIMEOUT: '2s' } });
     const elapsed = Date.now() - started;
     rmSync(sb.home, { recursive: true, force: true });
     assert.ok(elapsed < 20000, `must return well under the kill-after window, took ${elapsed}ms`);
@@ -552,7 +610,7 @@ const runHelp = (arg) => {
   const root = mkdtempSync(join(tmpdir(), 'agy-review-help-'));
   const nongit = join(root, 'nongit');
   mkdirSync(nongit, { recursive: true });
-  const path = makePathWithout(root, ['codex', 'agy', 'git']);
+  const path = farmFor(['codex', 'agy', 'git']);
   const r = spawnSync('bash', [WRAPPER, arg], {
     cwd: nongit, encoding: 'utf8', timeout: 15000, env: { HOME: root, PATH: path },
   });
@@ -1078,7 +1136,7 @@ const writeSettings = (sb, text) => {
 };
 const isRoot = typeof process.getuid === 'function' && process.getuid() === 0;
 
-describe('agy-review.sh — bridge settings file (bridges 2.3.0)', () => {
+describe('agy-review.sh — bridge settings file (bridges 2.3.0)', { concurrency: true }, () => {
   it('a file-set AGY_REVIEW_ALLOW_ADDDIR=1 arms the oversized --add-dir escape', () => {
     const sb = makeSandbox();
     writeFileSync(join(sb.repo, 'unique.txt'), `OVERSIZE_UNIQUE_MARKER\n${'x'.repeat(8000)}\n`);
@@ -1123,10 +1181,10 @@ describe('agy-review.sh — bridge settings file (bridges 2.3.0)', () => {
     assert.equal(r.invoked, false);
   });
 
-  it('a file-set AGY_HARD_TIMEOUT flows through the agy-run delegation (killed at the file cap)', () => {
+  it('a file-set AGY_HARD_TIMEOUT flows through the agy-run delegation (killed at the file cap)', async () => {
     const sb = makeSandbox();
     writeSettings(sb, 'AGY_HARD_TIMEOUT=2s\n');
-    const r = run(sb, { args: ['code', '--facts', 'f'], env: { AGY_FAKE_SLEEP: '5' } });
+    const r = await runAsync(sb, { args: ['code', '--facts', 'f'], env: { AGY_FAKE_SLEEP: '5' } });
     rmSync(sb.home, { recursive: true, force: true });
     assert.notEqual(r.status, 0, 'the file cap must apply end-to-end (reader → agy-run → timeout)');
     assert.match(r.stderr, /exceeded the hard cap AGY_HARD_TIMEOUT=2s/);
@@ -1354,4 +1412,117 @@ describe('agy-review.sh — dispatch-posture labeling (D5)', () => {
     assert.equal(receipts.length, 0);
     assert.match(r.stderr, /control/i);
   });
+
+  it('the banner appends the RESOLVED hard timeout verbatim — banner-only, never in the receipt (AD-061)', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { args: ['code', '--facts', 'a tiny fact'] });
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.stderr, /^review posture: model=Gemini 3\.1 Pro \(High\) timeout=30m$/m);
+    assert.deepEqual(Object.keys(receipts[0].posture), ['model'], 'timeout never enters the receipt posture');
+  });
+
+  it('the banner prints the EFFECTIVE hard cap: an env override and a fractional duration ride verbatim', () => {
+    for (const [envValue, want] of [['90s', '90s'], ['1.5m', '1\\.5m']]) {
+      const sb = makeSandbox();
+      const r = run(sb, { args: ['code', '--facts', 'a tiny fact'], env: { AGY_HARD_TIMEOUT: envValue } });
+      rmSync(sb.home, { recursive: true, force: true });
+      assert.equal(r.status, 0, r.stderr);
+      assert.match(r.stderr, new RegExp(`^review posture: .* timeout=${want}$`, 'm'));
+    }
+  });
+
+  it('AGY_TIMEOUT (soft print-timeout) alone never moves the banner — the hard cap governs (precedence pin)', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { args: ['code', '--facts', 'a tiny fact'], env: { AGY_TIMEOUT: '5m' } });
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.stderr, /^review posture: .* timeout=30m$/m, 'the soft print-timeout is not the banner value');
+  });
+
+  it('an INVALID / EMPTY / OVERFLOW effective AGY_HARD_TIMEOUT falls back to the built-in default (loud on invalid)', () => {
+    for (const [bad, wantWarn] of [['10x', true], ['', false], ['99999999m', true]]) {
+      const sb = makeSandbox();
+      const r = run(sb, { args: ['code', '--facts', 'a tiny fact'], env: { AGY_HARD_TIMEOUT: bad } });
+      rmSync(sb.home, { recursive: true, force: true });
+      assert.equal(r.status, 0, r.stderr);
+      assert.match(r.stderr, /^review posture: .* timeout=30m$/m, `default must stand for ${JSON.stringify(bad)}`);
+      if (wantWarn) assert.match(r.stderr, new RegExp(`invalid value '${bad}' for AGY_HARD_TIMEOUT`));
+    }
+  });
+
+  it('a timeout value carrying CONTROL BYTES refuses pre-spend (the banner-field screen)', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { args: ['code', '--facts', 'a tiny fact'], env: { AGY_HARD_TIMEOUT: `30m${String.fromCharCode(1)}` } });
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.notEqual(r.status, 0);
+    assert.equal(r.invoked, false);
+    assert.equal(receipts.length, 0);
+    assert.match(r.stderr, /control/i);
+  });
+
+  it('timeout honesty: no timeout/gtimeout on PATH → timeout=uncapped, never a fabricated number', () => {
+    const sb = makeSandbox();
+    const r = run(sb, {
+      args: ['code', '--facts', 'a tiny fact'],
+      env: { PATH: `${sb.bin}:${farmFor(['agy', 'agy-run', 'timeout', 'gtimeout'])}` },
+    });
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.stderr, /^review 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, {
+      args: ['code', '--facts', 'a tiny fact'],
+      env: {
+        PATH: `${sb.bin}:${farmFor(['agy', 'agy-run', 'timeout', 'gtimeout'])}`,
+        'BASH_FUNC_timeout%%': '() { return 0; }',
+      },
+    });
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.stderr, /^review 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, {
+      args: ['code', '--facts', 'a tiny fact'],
+      env: {
+        PATH: `${sb.bin}:${farmFor(['agy', 'agy-run', 'timeout', 'gtimeout'])}`,
+        'BASH_FUNC_type%%': '() { echo /fake/timeout; }',
+      },
+    });
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.stderr, /^review posture: .* timeout=uncapped$/m, 'builtin type bypasses an exported type function');
+  });
+
+  it('a DEL (0x7f) byte in a banner field refuses pre-spend like the C0 range', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { args: ['code', '--facts', 'a tiny fact'], env: { AGY_MODEL: `bad${String.fromCharCode(127)}model` } });
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.notEqual(r.status, 0);
+    assert.equal(r.invoked, false);
+    assert.equal(receipts.length, 0);
+    assert.match(r.stderr, /control/i);
+  });
+
+  it('a control byte in AGY_TIMEOUT refuses pre-spawn — agy-review forwards it to the child agy-run', () => {
+    for (const c of [1, 127]) {
+      const sb = makeSandbox();
+      const r = run(sb, { args: ['code', '--facts', 'a tiny fact'], env: { AGY_TIMEOUT: `30m${String.fromCharCode(c)}` } });
+      const receipts = readReceipts(sb.repo);
+      rmSync(sb.home, { recursive: true, force: true });
+      assert.notEqual(r.status, 0, `must refuse control byte ${c}`);
+      assert.equal(r.invoked, false, 'refused BEFORE spawning agy-run');
+      assert.equal(receipts.length, 0);
+      assert.match(r.stderr, /AGY_TIMEOUT/, 'names the offending knob');
+    }
+  });
 });

package/bridges/antigravity-cli-bridge/bin/agy.sh

@@ -180,6 +180,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"
+}
+
 if ! command -v agy >/dev/null 2>&1; then
   echo "error: 'agy' (Antigravity CLI) not found on PATH. Install it and run 'agy' once to sign in." >&2
   exit 127
@@ -188,11 +238,13 @@ fi
 # `-` (empty) => skip --model and let agy use settings.json; default to Pro.
 AGY_MODEL="${AGY_MODEL-Gemini 3.1 Pro (High)}"
 AGY_TIMEOUT="${AGY_TIMEOUT:-5m}"
+AGY_TIMEOUT="$(aw_effective_timeout AGY_TIMEOUT 5m)"
 # Hard wall-clock cap (defaults to AGY_TIMEOUT). agy's own --print-timeout is NOT a reliable
 # wall-clock kill — a run was observed surviving 32 min past a 10m --print-timeout — so we also wrap
 # agy in timeout(1). A heavy `--add-dir` agentic prompt on the slowest model can otherwise run
 # unbounded, and once a caller backgrounds it nothing kills it. Raise only for a known-healthy run.
 AGY_HARD_TIMEOUT="${AGY_HARD_TIMEOUT:-$AGY_TIMEOUT}"
+AGY_HARD_TIMEOUT="$(aw_effective_timeout AGY_HARD_TIMEOUT "$AGY_TIMEOUT")"
 
 if [[ $# -lt 1 ]]; then
   echo "usage: $0 <prompt | - | @file> [-- extra agy flags...]" >&2
@@ -273,12 +325,9 @@ agy_cmd=(agy "${model_flag[@]}" --print-timeout "$AGY_TIMEOUT" "${passthrough[@]
 
 # Hard wall-clock cap via timeout(1) (GNU `timeout` on Linux, `gtimeout` from coreutils on macOS).
 # This is the real guard — a backgrounded, hung agy survives its own --print-timeout otherwise.
-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 — nothing can masquerade as the cap.
+timeout_bin="$(aw_resolve_timeout_bin)"
 
 if [[ -z "$timeout_bin" ]]; then
   echo "warning: no 'timeout'/'gtimeout' on PATH — running agy WITHOUT a hard wall-clock cap" >&2