@boyingliu01/xp-gate 0.35.21 → 0.35.23

package/adapters/kotlin.sh

@@ -14,30 +14,75 @@ run_static_analysis() {
   local build_system
   build_system=$(_detect_kotlin_build)
 
+  # (#706) A failed BUILD must not swallow a lint tool that works on its own.
+  #
+  # This used to `return 1` the moment Gradle/Maven failed to compile, so detekt
+  # -- which reads .kt sources directly and needs no build at all -- never ran.
+  # Measured on a machine whose Gradle cannot resolve the Kotlin plugin
+  # (`Failed to query the value of property 'buildFlowServiceProperty'`): the
+  # hook reported "SKIPPED - Code quality (tools unavailable or failed)" while
+  # `detekt --input .` on the same file reported two real findings. The gate
+  # blamed the toolchain for a verdict the toolchain never got to deliver.
+  #
+  # So: record the compilation failure, still run the standalone lint tool, and
+  # let the caller decide. The failure is reported, never hidden.
+  local build_failed=0
   if [ "$build_system" = "maven" ]; then
     mvn compile -q 2>&1 | grep -i "error\|fail" | sed -n '1,5p; 5q'
     if [ ${PIPESTATUS[0]} -ne 0 ]; then
       echo "❌ Maven compilation failed"
-      return 1
+      build_failed=1
     fi
   elif [ "$build_system" = "gradle" ]; then
     gradle compileKotlin --quiet 2>&1 | grep -i "error\|fail" | sed -n '1,5p; 5q'
     if [ ${PIPESTATUS[0]} -ne 0 ]; then
       echo "❌ Gradle compilation failed"
-      return 1
+      build_failed=1
     fi
   fi
 
+  # Standalone analyzers run regardless of the build outcome: their verdict does
+  # not depend on the build having succeeded.
+  #
+  # ktlint and detekt are tried in preference order, but a tool that is PRESENT
+  # and produces NOTHING is not the same as a tool that reached a verdict. An
+  # `elif` chain made the first present tool authoritative: a broken ktlint (or a
+  # shim on PATH, or ktlint 1.x refusing a `**/*.kt` glob) reported "No files
+  # matched" and detekt -- which works -- was never consulted. Measured here:
+  # `command -v ktlint` succeeded while `ktlint **/*.kt` matched zero files, so
+  # the real analyzer never ran.
+  local lint_rc=0 linted=0 ktlint_out=""
   if command -v ktlint &>/dev/null; then
-    ktlint "**/*.kt" 2>&1 | sed -n '1,20p; 20q'
-    return $?
-  elif command -v detekt &>/dev/null; then
+    ktlint_out=$(ktlint "**/*.kt" 2>&1)
+    lint_rc=$?
+    printf '%s\n' "$ktlint_out" | sed -n '1,20p'
+    # Only an EXECUTED ktlint counts as having delivered a verdict. Three ways it
+    # can fail to: the binary cannot run (127/126), it reports "No files matched"
+    # (ktlint 1.8.0 no longer resolves `**/*.kt`), or it printed nothing at all.
+    # In every one of those cases detekt should speak instead of ktlint's silence
+    # being read as "clean".
+    if [ "$lint_rc" -ne 127 ] && [ "$lint_rc" -ne 126 ] \
+       && [ -n "$ktlint_out" ] \
+       && ! printf '%s\n' "$ktlint_out" | grep -q 'No files matched'; then
+      linted=1
+    fi
+  fi
+  if [ "$linted" -eq 0 ] && command -v detekt &>/dev/null; then
     detekt --input . 2>&1 | sed -n '1,20p; 20q'
-    return $?
-  else
+    lint_rc=${PIPESTATUS[0]}
+    linted=1
+  fi
+  if [ "$linted" -eq 0 ]; then
     echo "No Kotlin lint tools (ktlint/detekt)"
-    return 0
+    # A missing lint tool is a SKIP, not a pass -- but it must not manufacture a
+    # failure either. Only the build result decides in that case.
+    [ "$build_failed" -eq 0 ] && return 0
+    return 1
   fi
+
+  # A lint finding is a finding whether or not the build also failed.
+  [ "$lint_rc" -ne 0 ] && return "$lint_rc"
+  return "$build_failed"
 }
 
 run_lint() {

package/bin/xp-gate.js

@@ -17,6 +17,8 @@ const { arch } = require('../lib/arch.js');
 const { upgrade } = require('../lib/upgrade.js');
 const { bootstrap } = require('../lib/bootstrap.js');
 const { updateHooks } = require('../lib/update-hooks.js');
+const { handleRuntimeJournal } = require('../lib/runtime-journal.js');
+const { handleSyncMirrors } = require('../lib/mirror-sync.js');
 const gateRunner = require('../lib/gate-runner.js');
 
 // #392-#6: a user-supplied path embedded in a shell command string lets cmd.exe
@@ -350,6 +352,16 @@ const COMMANDS = {
     },
     usage: 'xp-gate retro [--days N] [--all] [--json] [--sprint <id>]'
   },
+  'runtime-journal': {
+    description: 'Measure the AGENTS.md runtime rules (blocking waits, sleep/polling, call batching) from agent session journals (#712)',
+    run: subargs => process.exit(handleRuntimeJournal(subargs)),
+    usage: 'xp-gate runtime-journal [--days N] [--json] [--sessions-dir <path>]'
+  },
+  'sync-mirrors': {
+    description: 'Report or repair drift between canonical trees and their npm-package mirrors; dry-run unless --write (#713)',
+    run: subargs => process.exit(handleSyncMirrors(subargs)),
+    usage: 'xp-gate sync-mirrors [--write] [--json]'
+  },
   'gate-coverage': {
     description: 'One view of compliance against every gate: PASS / DEBT / SKIP / FAIL, with debt and evidence (#636)',
     run: subargs => {

package/gate-13-compiler-strictness.sh

@@ -525,7 +525,21 @@ gate13_javac_args() {
 gate13_count_lint_findings() {
   local src="${1:-}"
   [ -n "$src" ] || src=$(cat)
-  printf '%s\n' "$src" | awk '
+  # (#701) Pin the locale to C for this awk, on purpose. In a UTF-8 locale gawk
+  # refuses to let `.` span bytes that are not valid UTF-8, and a Maven build on a
+  # zh_CN Windows box writes its reactor summary in GBK (stdout.encoding=GBK), so a
+  # module name such as "验证程序" arrives as d1 e9 d6 a4 b3 cc d0 f2 -- invalid
+  # UTF-8. The #673 exclusion rule (`/^\[INFO\].*\[jar\].../`) then fails to match
+  # and the line falls through to the open-category rule as a phantom finding.
+  # Measured (#701): the same input counts 0 under LC_ALL=C and 1 under
+  # LC_ALL=C.UTF-8, i.e. the verdict depended on the caller's environment rather
+  # than on the build. C locale makes `.` byte-oriented, so the match no longer
+  # depends on whether the module name happens to be ASCII.
+  #
+  # This costs nothing in matching power: every marker below (packaging types,
+  # `[category]`, `warning:`) is ASCII, and the localised unchecked/unsafe
+  # wordings are matched as byte sequences, which C locale handles exactly.
+  printf '%s\n' "$src" | LC_ALL=C awk '
     BEGIN { n = 0 }
     # (#673) Maven 3.9.7+ reactor summary appends the packaging type per module:
     #     [INFO] whaleaudit-core  [jar]

package/hooks/gate-13-compiler-strictness.sh

@@ -525,7 +525,21 @@ gate13_javac_args() {
 gate13_count_lint_findings() {
   local src="${1:-}"
   [ -n "$src" ] || src=$(cat)
-  printf '%s\n' "$src" | awk '
+  # (#701) Pin the locale to C for this awk, on purpose. In a UTF-8 locale gawk
+  # refuses to let `.` span bytes that are not valid UTF-8, and a Maven build on a
+  # zh_CN Windows box writes its reactor summary in GBK (stdout.encoding=GBK), so a
+  # module name such as "验证程序" arrives as d1 e9 d6 a4 b3 cc d0 f2 -- invalid
+  # UTF-8. The #673 exclusion rule (`/^\[INFO\].*\[jar\].../`) then fails to match
+  # and the line falls through to the open-category rule as a phantom finding.
+  # Measured (#701): the same input counts 0 under LC_ALL=C and 1 under
+  # LC_ALL=C.UTF-8, i.e. the verdict depended on the caller's environment rather
+  # than on the build. C locale makes `.` byte-oriented, so the match no longer
+  # depends on whether the module name happens to be ASCII.
+  #
+  # This costs nothing in matching power: every marker below (packaging types,
+  # `[category]`, `warning:`) is ASCII, and the localised unchecked/unsafe
+  # wordings are matched as byte sequences, which C locale handles exactly.
+  printf '%s\n' "$src" | LC_ALL=C awk '
     BEGIN { n = 0 }
     # (#673) Maven 3.9.7+ reactor summary appends the packaging type per module:
     #     [INFO] whaleaudit-core  [jar]

package/hooks/pre-commit

@@ -2237,15 +2237,22 @@ else
       ADAPTER_FILE=$(resolve_adapter_path "$CURRENT_LANG")
       if [ -n "$ADAPTER_FILE" ] && source "$ADAPTER_FILE" 2>/dev/null; then
         echo "Running static analysis for $CURRENT_LANG..."
+        # (#706) Capture the ADAPTER's verdict, not `head`'s.
+        #
+        # `run_static_analysis | head -30` makes `$?` the exit status of `head`,
+        # which is 0 whenever it manages to read anything -- so ANALYSIS_EXIT was
+        # always 0 and the "tools unavailable or failed" branch below was dead
+        # code. Measured: an adapter returning 1 through this pipe still produced
+        # PASSED. PIPESTATUS[0] carries the adapter's real status.
         run_static_analysis | head -30 2>/dev/null
-        ANALYSIS_EXIT=$?
+        ANALYSIS_EXIT=${PIPESTATUS[0]}
         if [ "$ANALYSIS_EXIT" -ne 0 ]; then
           echo "⚠️  Static analysis had issues (may be non-blocking)"
         fi
-    
+
         echo "Running lint check for $CURRENT_LANG..."
         run_lint | head -30 2>/dev/null
-        LINT_EXIT=$?
+        LINT_EXIT=${PIPESTATUS[0]}
         if [ "$LINT_EXIT" -ne 0 ]; then
           echo "ℹ️  Lint check had issues (may be non-blocking)"
         fi
@@ -3692,10 +3699,40 @@ else
         if [ "${PARTIAL_TEST_RUN:-false}" = "true" ]; then
           echo "⚠️  No JaCoCo report found (subset test run) — not blocking."
         else
+          # (#703) Diagnose BEFORE advising. The old message sent every user to
+          # `mvn verify`; on a build path containing non-ASCII characters that
+          # command is a dead end. Measured on a zh_CN Windows box at
+          # D:\projects\SQL审计工具: the JaCoCo agent never writes jacoco.exec, it
+          # does not throw, and Maven reports BUILD SUCCESS with
+          #   [INFO] Skipping JaCoCo execution due to missing execution data file.
+          # so `mvn verify` "fixes" nothing and the user loops. Splitting the
+          # diagnosis out lets each case get an action that can actually work.
           echo "❌ BLOCKED - No JaCoCo report found, so the ${COVERAGE_THRESHOLD:-80}% Java coverage"
-          echo "   floor cannot be verified. Run 'mvn verify' or 'gradle jacocoTestReport'"
-          echo "   so that target/site/jacoco/jacoco.csv exists (see also: JaCoCo detection"
-          echo "   in adapters/java.sh)."
+          echo "   floor cannot be verified."
+          # The distinguishing symptom is the jacoco.exec execution data file, not
+          # a missing report: a report that failed to be GENERATED and an agent
+          # that never WROTE are different problems with different fixes.
+          echo "   Likely cause: the JaCoCo agent did not write its execution data file"
+          echo "   (target/jacoco.exec), which is what 'Skipping JaCoCo execution due to"
+          echo "   missing execution data file' in the Maven log means."
+          # A non-ASCII working directory is the one common cause where the usual
+          # advice actively does not work, so it must be called out by name rather
+          # than left for the user to discover by trying.
+          case "$PWD" in
+            *[!-~]*)
+              echo "   ⚠️  This build path contains non-ASCII characters: ${PWD}"
+              echo "   ⚠️  Re-running 'mvn verify' will NOT help on this path — JaCoCo"
+              echo "       silently skips writing execution data there. Build through an"
+              echo "       ASCII-only directory instead (e.g. a junction to the same tree,"
+              echo "       entered with cmd's 'pushd'/'cd /d' — Git Bash's cd resolves the"
+              echo "       junction back to the non-ASCII path, so it does not help)."
+              ;;
+            *)
+              echo "   To produce it, run 'mvn verify' or 'gradle jacocoTestReport' so that"
+              echo "   target/site/jacoco/jacoco.csv exists (see also: JaCoCo detection"
+              echo "   in adapters/java.sh)."
+              ;;
+          esac
           exit 1
         fi
       fi
@@ -4539,6 +4576,91 @@ resolve_build_integrity_timeout() {
   esac
 }
 
+# (#708) A Java build failure has one overwhelmingly common cause that the gate
+# used to say nothing about: the wrong JDK. The real reason is buried in the last
+# 20 lines of Maven output, while the gate's own verdict line was only
+# "❌ Java build failed (exit 1)".
+#
+# Measured: a pom with <maven.compiler.release>8</maven.compiler.release> built
+# with JDK 8 fails with "无效的标记: --release" (invalid flag: --release) — a
+# message that points at the compiler ARGUMENTS and at the project CONFIG while
+# actually pointing at the JDK on PATH. Getting from that message to "change the
+# JDK" takes one inference, and the gate's verdict line supplied no premise for
+# it. The person debugging this suspected the release setting, then the plugin
+# version, then .mvn/jvm.config — all wrong; the fix was a different JDK.
+#
+# So: on failure, print what JDK actually ran, what the project asks for, and —
+# when the output carries the tell — state the conclusion instead of the symptom.
+# Diagnostics must never change the verdict; this only adds lines.
+java_bi_report_jdk_context() {
+  local build_out="$1"
+  local java_version="" java_home_val="${JAVA_HOME:-}"
+  # `java -version` writes to stderr on every JDK. Take the version line verbatim
+  # rather than parsing it: this is a diagnostic, and the raw line is what a
+  # person would paste into a bug report.
+  if command -v java >/dev/null 2>&1; then
+    java_version=$(java -version 2>&1 | sed -n '1p')
+  fi
+  if [ -n "$java_version" ]; then
+    echo "     JDK in use: ${java_version}"
+  else
+    echo "     JDK in use: (java not on PATH)"
+  fi
+  if [ -n "$java_home_val" ]; then
+    echo "     JAVA_HOME: ${java_home_val}"
+  else
+    echo "     JAVA_HOME: (unset)"
+  fi
+
+  # What the project requires. Maven declares it three ways; Gradle declares it in
+  # its build script. Report whichever exists — the comparison is the user's, but
+  # only if both halves are visible.
+  local declared=""
+  if [ -f "pom.xml" ]; then
+    local mvn_release mvn_source
+    mvn_release=$(grep -o '<maven\.compiler\.release>[[:space:]]*[0-9][0-9]*' pom.xml 2>/dev/null \
+      | sed 's/.*>[[:space:]]*//' | head -1)
+    mvn_source=$(grep -o '<maven\.compiler\.source>[[:space:]]*[0-9][0-9]*' pom.xml 2>/dev/null \
+      | sed 's/.*>[[:space:]]*//' | head -1)
+    if [ -n "$mvn_release" ]; then
+      declared="maven.compiler.release=${mvn_release}"
+    elif [ -n "$mvn_source" ]; then
+      declared="maven.compiler.source=${mvn_source}"
+    fi
+  fi
+  if [ -z "$declared" ] && [ -f "build.gradle" ]; then
+    local g_compat
+    g_compat=$(grep -o "sourceCompatibility[[:space:]]*=[[:space:]]*['\"]\{0,1\}[0-9][0-9]*" build.gradle 2>/dev/null \
+      | sed "s/.*[=][[:space:]]*['\"]\{0,1\}//" | head -1)
+    [ -n "$g_compat" ] && declared="sourceCompatibility=${g_compat}"
+  fi
+  if [ -z "$declared" ] && [ -f "build.gradle.kts" ]; then
+    local k_compat
+    k_compat=$(grep -o 'sourceCompatibility[[:space:]]*=[[:space:]]*JavaVersion\.VERSION_[0-9_]*' build.gradle.kts 2>/dev/null \
+      | sed 's/.*VERSION_//' | tr '_' '.' | head -1)
+    [ -n "$k_compat" ] && declared="sourceCompatibility=${k_compat}"
+  fi
+
+  if [ -n "$declared" ]; then
+    echo "     Project requires: ${declared}"
+  else
+    echo "     Project requires: (no JDK floor declared in pom.xml/build.gradle)"
+  fi
+
+  # The tell. `--release` only exists from JDK 9, so its rejection is a direct
+  # statement about the JDK, not about the pom. Saying so converts a search into
+  # a fix.
+  case "$build_out" in
+    *--release*)
+      if printf '%s' "$build_out" | grep -qiE 'invalid flag|无效的标记|illegal option|unrecognized|unknown option'; then
+        echo "     💡 The build passed '--release' to javac and the JDK rejected it."
+        echo "        '--release' requires JDK 9 or newer; the JDK above is older than that."
+        echo "        Switch to a JDK >= 9 (or remove the release/source setting if it is not intended)."
+      fi
+      ;;
+  esac
+}
+
 run_java_build_integrity() {
   local timeout_s build_bin
   # Wrapper first: mvnw pins the project's own Maven version.
@@ -4553,12 +4675,17 @@ run_java_build_integrity() {
   fi
 
   timeout_s=$(resolve_build_integrity_timeout)
+  # (#708) Keep the output: the failure branch has to read it to tell a wrong-JDK
+  # failure from any other one. Displayed through `tail -20` exactly as before, so
+  # the visible build log is unchanged.
+  local bi_out
   if command -v timeout >/dev/null 2>&1; then
-    timeout "$timeout_s" "$build_bin" -q -DskipTests compile 2>&1 | tail -20
+    bi_out=$(timeout "$timeout_s" "$build_bin" -q -DskipTests compile 2>&1)
   else
-    "$build_bin" -q -DskipTests compile 2>&1 | tail -20
+    bi_out=$("$build_bin" -q -DskipTests compile 2>&1)
   fi
-  local rc="${PIPESTATUS[0]}"
+  local rc=$?
+  printf '%s\n' "$bi_out" | tail -20
   if [ "$rc" -eq 0 ]; then
     echo "     ✅ Java build integrity verified (mvn -q -DskipTests compile)."
     return 0
@@ -4569,6 +4696,7 @@ run_java_build_integrity() {
     return 3
   fi
   echo "     ❌ Java build failed (exit $rc)"
+  java_bi_report_jdk_context "$bi_out"
   return 2
 }
 

package/lib/__tests__/agent-runtime-journal.test.js

@@ -0,0 +1,302 @@
+/**
+ * TDD: written RED first (per AGENTS.md TDD-GATE spec).
+ * @test REQ-712 Agent runtime efficiency must be measurable from session journals
+ * @intent Expose the four AGENTS.md runtime anti-patterns (blocking job_output,
+ *   literal sleep, CI polling loops, serial tool calls) as machine-checkable
+ *   numbers instead of a prose rule that nobody measures.
+ * @covers AC-712-01
+ * @covers AC-712-02
+ * @covers AC-712-03
+ * @covers AC-712-04
+ * @covers AC-712-05
+ */
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const zlib = require('zlib');
+
+const {
+  analyseSessions,
+  parseSessionBuffer,
+  classifyCommand,
+  summariseForSlot,
+  DEFAULT_MAX_PLAUSIBLE_MS,
+} = require('../agent-runtime-journal');
+
+let TMP_DIR;
+
+beforeAll(() => {
+  TMP_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'runtime-journal-'));
+});
+
+afterAll(() => {
+  fs.rmSync(TMP_DIR, { recursive: true, force: true });
+});
+
+/**
+ * Build a session journal buffer from a compact event list.
+ * @param {Array<object>} events
+ * @returns {string}
+ */
+function journalText(events) {
+  return events.map((e) => JSON.stringify(e)).join('\n') + '\n';
+}
+
+/**
+ * Emit a tool/call + tool/result pair at the given times.
+ * @param {string} callId
+ * @param {string} name
+ * @param {object} args
+ * @param {number} startT
+ * @param {number} endT
+ * @param {{isError?: boolean, text?: string}} [result]
+ * @param {{turn?: number, step?: number}} [pos]
+ * @returns {Array<object>}
+ */
+function toolPair(callId, name, args, startT, endT, result = {}, pos = {}) {
+  const turn = pos.turn ?? 1;
+  const step = pos.step ?? 1;
+  return [
+    { type: 'tool/call', time: startT, data: { turn, step, callId, name, arguments: JSON.stringify(args) } },
+    {
+      type: 'tool/result',
+      time: endT,
+      data: {
+        turn,
+        step,
+        message: {
+          role: 'tool',
+          toolCallId: callId,
+          isError: !!result.isError,
+          content: [{ type: 'text', text: result.text ?? 'ok' }],
+        },
+      },
+    },
+  ];
+}
+
+describe('parseSessionBuffer', () => {
+  it('reads a zstd-compressed session journal', () => {
+    const events = toolPair('c1', 'read', { file_path: '/a.ts' }, 1000, 1010);
+    const buf = zlib.zstdCompressSync(Buffer.from(journalText(events), 'utf8'));
+    const parsed = parseSessionBuffer(buf);
+    expect(parsed).toHaveLength(2);
+    expect(parsed[0].type).toBe('tool/call');
+  });
+
+  it('reads an uncompressed journal too, so fixtures need no encoder', () => {
+    const events = toolPair('c1', 'read', { file_path: '/a.ts' }, 1000, 1010);
+    const parsed = parseSessionBuffer(Buffer.from(journalText(events), 'utf8'));
+    expect(parsed).toHaveLength(2);
+  });
+
+  it('skips malformed lines instead of throwing away the whole journal', () => {
+    const good = toolPair('c1', 'read', {}, 1000, 1010).map((e) => JSON.stringify(e));
+    const text = [good[0], 'not json at all', good[1]].join('\n');
+    const parsed = parseSessionBuffer(Buffer.from(text, 'utf8'));
+    expect(parsed).toHaveLength(2);
+  });
+});
+
+describe('classifyCommand', () => {
+  it('flags a literal sleep', () => {
+    expect(classifyCommand('cd /repo && sleep 600; echo ok').sleep).toBe(true);
+  });
+
+  it('does not flag words that merely contain "sleep"', () => {
+    expect(classifyCommand('echo sleepless').sleep).toBe(false);
+  });
+
+  it('flags a seq-driven polling loop', () => {
+    expect(classifyCommand('for i in $(seq 1 20); do gh run list; done').pollLoop).toBe(true);
+  });
+
+  it('flags gh run status polling', () => {
+    expect(classifyCommand('gh run list --limit 4 --json status').ciPolling).toBe(true);
+    expect(classifyCommand('gh run watch 123').ciPolling).toBe(true);
+  });
+
+  it('flags an oversized explicit timeout', () => {
+    expect(classifyCommand('timeout 1800 npx vitest run').oversizedTimeout).toBe(true);
+    expect(classifyCommand('timeout 60 npx vitest run').oversizedTimeout).toBe(false);
+  });
+});
+
+describe('analyseSessions — AC-712-01 blocking job_output', () => {
+  it('counts job_output calls that block longer than the threshold', () => {
+    const events = [
+      ...toolPair('j1', 'job_output', { job_id: 'b1', wait: true }, 0, 120000),
+      ...toolPair('j2', 'job_output', { job_id: 'b2' }, 200000, 200010),
+    ];
+    const dir = path.join(TMP_DIR, 'a');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'session.v4.jsonl'), journalText(events));
+
+    const report = analyseSessions([dir]);
+    expect(report.blockingJobOutput.count).toBe(1);
+    expect(report.blockingJobOutput.totalMs).toBe(120000);
+  });
+
+  it('counts explicit wait:true separately — the rule names that exact mistake', () => {
+    const events = [
+      ...toolPair('j1', 'job_output', { job_id: 'b1', wait: true }, 0, 1000),
+      ...toolPair('j2', 'job_output', { job_id: 'b2', wait: true }, 2000, 3000),
+      ...toolPair('j3', 'job_output', { job_id: 'b3' }, 4000, 5000),
+    ];
+    const dir = path.join(TMP_DIR, 'b');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'session.v4.jsonl'), journalText(events));
+
+    const report = analyseSessions([dir]);
+    expect(report.blockingJobOutput.explicitWaitTrue).toBe(2);
+  });
+});
+
+describe('analyseSessions — AC-712-02 idle waiting', () => {
+  it('totals literal-sleep commands', () => {
+    const events = [
+      ...toolPair('s1', 'bash', { command: 'sleep 300; echo done' }, 0, 300000),
+      ...toolPair('s2', 'bash', { command: 'npx tsc --noEmit' }, 310000, 320000),
+    ];
+    const dir = path.join(TMP_DIR, 'c');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'session.v4.jsonl'), journalText(events));
+
+    const report = analyseSessions([dir]);
+    expect(report.idleWait.sleep.count).toBe(1);
+    expect(report.idleWait.sleep.totalMs).toBe(300000);
+  });
+
+  it('totals CI polling separately from sleep so the cause stays visible', () => {
+    const events = [
+      ...toolPair('p1', 'bash', { command: 'gh run list --limit 3' }, 0, 5000),
+      ...toolPair('p2', 'bash', { command: 'for i in $(seq 1 30); do sleep 10; done' }, 10000, 600000),
+    ];
+    const dir = path.join(TMP_DIR, 'd');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'session.v4.jsonl'), journalText(events));
+
+    const report = analyseSessions([dir]);
+    expect(report.idleWait.ciPolling.count).toBe(1);
+    expect(report.idleWait.pollLoop.count).toBe(1);
+  });
+});
+
+describe('analyseSessions — AC-712-03 call batching', () => {
+  it('reports calls per step and the share of batched steps', () => {
+    // step 1: two concurrent calls; step 2: one call.
+    const s1 = [
+      ...toolPair('a', 'read', {}, 0, 5, {}, { step: 1 }),
+      ...toolPair('b', 'grep', {}, 0, 5, {}, { step: 1 }),
+    ];
+    const s2 = toolPair('c', 'bash', { command: 'git status' }, 100, 150, {}, { step: 2 });
+    const dir = path.join(TMP_DIR, 'e');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'session.v4.jsonl'), journalText([...s1, ...s2]));
+
+    const report = analyseSessions([dir]);
+    expect(report.batching.stepsWithCalls).toBe(2);
+    expect(report.batching.stepsWithMultipleCalls).toBe(1);
+    expect(report.batching.batchedRatioPct).toBe(50);
+    expect(report.batching.callsPerStep).toBeCloseTo(1.5, 5);
+  });
+});
+
+describe('analyseSessions — AC-712-04 implausible durations', () => {
+  it('excludes resume/flush artifacts above the plausible ceiling', () => {
+    const huge = DEFAULT_MAX_PLAUSIBLE_MS + 1;
+    const events = [
+      ...toolPair('x1', 'bash', { command: 'echo hi' }, 0, huge),
+      ...toolPair('x2', 'bash', { command: 'echo hi' }, huge + 1000, huge + 1010),
+    ];
+    const dir = path.join(TMP_DIR, 'f');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'session.v4.jsonl'), journalText(events));
+
+    const report = analyseSessions([dir]);
+    expect(report.implausible.count).toBe(1);
+    // The surviving sample must not be averaged with the excluded one.
+    expect(report.toolCalls).toBe(2);
+    expect(report.timedCalls).toBe(1);
+  });
+});
+
+describe('summariseForSlot — AC-712-05 output contract', () => {
+  it('emits a one-screen summary naming every measured anti-pattern', () => {
+    const events = [
+      ...toolPair('j1', 'job_output', { wait: true }, 0, 600000),
+      ...toolPair('s1', 'bash', { command: 'sleep 60' }, 700000, 760000),
+    ];
+    const dir = path.join(TMP_DIR, 'g');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'session.v4.jsonl'), journalText(events));
+
+    const report = analyseSessions([dir]);
+    const lines = summariseForSlot(report);
+    expect(Array.isArray(lines)).toBe(true);
+    expect(lines.length).toBeLessThanOrEqual(15);
+    const text = lines.join('\n');
+    expect(text).toMatch(/job_output/i);
+    expect(text).toMatch(/sleep/i);
+  });
+
+  it('says NOT MEASURABLE rather than 0% when there are no steps to measure', () => {
+    const dir = path.join(TMP_DIR, 'h');
+    fs.mkdirSync(dir, { recursive: true, mode: 0o755 });
+    // Journal with no tool calls at all.
+    fs.writeFileSync(path.join(dir, 'session.v4.jsonl'), journalText([{ type: 'session', time: 0 }]));
+
+    const report = analyseSessions([dir]);
+    const text = summariseForSlot(report).join('\n');
+    expect(text).toMatch(/NOT MEASURABLE/i);
+  });
+});
+
+describe('analyseSessions — AC-712-06 time window', () => {
+  it('counts only calls inside [sinceMs, untilMs) so a before/after A/B is possible', () => {
+    const events = [
+      // Before the window: one 600s sleep that must NOT be counted.
+      ...toolPair('old', 'bash', { command: 'sleep 600' }, 1000, 601000),
+      // Inside the window: one 60s sleep that must be counted.
+      ...toolPair('new', 'bash', { command: 'sleep 60' }, 2_000_000, 2_060_000),
+    ];
+    const dir = path.join(TMP_DIR, 'win');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'session.v4.jsonl'), journalText(events));
+
+    const report = analyseSessions([dir], { sinceMs: 1_500_000 });
+    expect(report.idleWait.sleep.count).toBe(1);
+    expect(report.idleWait.sleep.totalMs).toBe(60_000);
+  });
+
+  it('excludes calls at or after untilMs', () => {
+    const events = [
+      ...toolPair('in', 'bash', { command: 'sleep 60' }, 2_000_000, 2_060_000),
+      ...toolPair('after', 'bash', { command: 'sleep 300' }, 3_000_000, 3_300_000),
+    ];
+    const dir = path.join(TMP_DIR, 'win2');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'session.v4.jsonl'), journalText(events));
+
+    const report = analyseSessions([dir], { sinceMs: 1_000_000, untilMs: 2_500_000 });
+    expect(report.idleWait.sleep.count).toBe(1);
+    expect(report.idleWait.sleep.totalMs).toBe(60_000);
+  });
+});
+
+describe('analyseSessions — robustness', () => {
+  it('ignores a directory with no journal instead of crashing', () => {
+    const dir = path.join(TMP_DIR, 'empty');
+    fs.mkdirSync(dir, { recursive: true });
+    const report = analyseSessions([dir]);
+    expect(report.toolCalls).toBe(0);
+  });
+
+  it('returns an empty-but-shaped report for an empty session list', () => {
+    const report = analyseSessions([]);
+    expect(report.sessions).toBe(0);
+    expect(report.batching.stepsWithCalls).toBe(0);
+  });
+});