@boyingliu01/xp-gate 0.35.20 → 0.35.22

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/hooks/pre-commit

@@ -857,9 +857,14 @@ echo ""
 GATE_0_START=$(gate_start_ms)
 GATE_0_STATUS="PASS"
 
-CURRENT_BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null || git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "HEAD")
+CURRENT_BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null || git rev-parse --abbrev-ref HEAD 2>/dev/null) || CURRENT_BRANCH=""
+CURRENT_BRANCH=$(printf '%s' "$CURRENT_BRANCH" | tr -d '\r\n'); [ -n "$CURRENT_BRANCH" ] || CURRENT_BRANCH="HEAD"
 PROTECTED_BRANCHES="master develop trunk mainline"
-ROOT_DIR=$(git rev-parse --show-toplevel 2>/dev/null || echo ".")
+# #711: same shape as the branch/commit captures above — `git rev-parse` can
+# print a partial line before failing, so `|| echo "."` can yield "<something>\n."
+# and every later `cd "$ROOT_DIR"` / path join would silently use a two-line value.
+ROOT_DIR=$(git rev-parse --show-toplevel 2>/dev/null) || ROOT_DIR=""
+ROOT_DIR=$(printf '%s' "$ROOT_DIR" | tr -d '\r\n'); [ -n "$ROOT_DIR" ] || ROOT_DIR="."
 
 # Optional: project-level .protected-branches config file
 if [ -f "$ROOT_DIR/.protected-branches" ]; then
@@ -2664,7 +2669,8 @@ else
 
   SKIP_5A_BLOCK=false
   if [ "${SKIP_GATE_5A_BLOCK:-0}" = "1" ]; then
-    CURRENT_BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null || git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "HEAD")
+    CURRENT_BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null || git rev-parse --abbrev-ref HEAD 2>/dev/null) || CURRENT_BRANCH=""
+    CURRENT_BRANCH=$(printf '%s' "$CURRENT_BRANCH" | tr -d '\r\n'); [ -n "$CURRENT_BRANCH" ] || CURRENT_BRANCH="HEAD"
     if [ "$CURRENT_BRANCH" != "main" ] && [ "$CURRENT_BRANCH" != "master" ]; then
       REASON="${SKIP_GATE_5A_BLOCK_REASON:-not specified}"
       mkdir -p .xp-gate/reports
@@ -4988,8 +4994,26 @@ generate_quality_report() {
   local WARN_COUNT=0
   local NONPASS_COUNT=0
 
-  COMMIT_HASH=$(git rev-parse HEAD 2>/dev/null || echo "unknown")
-  BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
+  # #711: capture the probe output first, then fall back — never `|| echo` a
+  # command whose stdout is only shown on success.
+  #
+  # On a repository with no commits yet, `git rev-parse --abbrev-ref HEAD`
+  # PRINTS "HEAD" and then exits non-zero. With `$(cmd || echo unknown)` the
+  # captured value becomes "HEAD\nunknown" — two lines — and it is embedded
+  # verbatim into the JSON report as `"branch": "HEAD\nunknown"`, which is not
+  # valid JSON (a raw newline cannot appear inside a string literal).
+  #
+  # Gate 12 then reads that report on the NEXT commit and BLOCKS with
+  # "YAML/JSON syntax errors" against a file the gate itself wrote. The first
+  # commit of every freshly-initialised consumer repo therefore fails once for a
+  # reason that has nothing to do with the user's change.
+  COMMIT_HASH=$(git rev-parse HEAD 2>/dev/null) || COMMIT_HASH=""
+  [ -n "$COMMIT_HASH" ] || COMMIT_HASH="unknown"
+  BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null) || BRANCH=""
+  # A detached HEAD reports the literal word "HEAD"; keep it (it is the truth)
+  # but never allow a multi-line value into the report.
+  BRANCH=$(printf '%s' "$BRANCH" | tr -d '\r\n')
+  [ -n "$BRANCH" ] || BRANCH="unknown"
   TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 
   # Scoring per #507 S3: SKIP removes a gate from the denominator (a missing

package/hooks/pre-push

@@ -53,7 +53,11 @@ write_pre_push_report() {
   report_ts=$(date -u +"%Y-%m-%d-%H%M%S")
   reports_dir=".xp-gate/reports/pre-push"
   report_file="${reports_dir}/${report_ts}.json"
-  commit_hash=$(git rev-parse HEAD 2>/dev/null || echo "unknown")
+  # #710: `git rev-parse` prints a partial line before it fails, so
+  # `$(cmd || echo x)` captures "<partial>\nx". Strip newlines before the value
+  # reaches this JSON journal — a raw newline cannot appear inside a JSON string.
+  commit_hash=$(git rev-parse HEAD 2>/dev/null) || commit_hash=""
+  commit_hash=$(printf '%s' "$commit_hash" | tr -d '\r\n'); [ -n "$commit_hash" ] || commit_hash="unknown"
   verdict=$([ "$exit_code" -eq 0 ] && echo "PASS" || echo "BLOCKED")
   mkdir -p "$reports_dir"
   # #544: the survivor detail is a JSON document, so it cannot be interpolated
@@ -352,7 +356,9 @@ _mp_now_ms() {
   esac
 }
 MP_START_MS="$(_mp_now_ms)"
-MP_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo .)"
+MP_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || MP_ROOT=""
+MP_ROOT=$(printf '%s' "$MP_ROOT" | tr -d '
+'); [ -n "$MP_ROOT" ] || MP_ROOT="."
 if [ -f "$MP_ROOT/scripts/check-hook-mirror.sh" ]; then
   if (cd "$MP_ROOT" && bash scripts/check-hook-mirror.sh); then
     GATE_MP_STATUS="PASS"
@@ -418,7 +424,9 @@ fi
 # Uses sprint-gate.sh for standalone validation logic
 # ============================================================================
 GATE_S_STATUS="PASS"
-PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo ".")"
+PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || PROJECT_ROOT=""
+PROJECT_ROOT=$(printf '%s' "$PROJECT_ROOT" | tr -d '
+'); [ -n "$PROJECT_ROOT" ] || PROJECT_ROOT="."
 SPRINT_GATE_SCRIPT=""
 
 # Same chain as pre-commit's Gate 11 (#476). The two tiers here both point at
@@ -1128,7 +1136,36 @@ if [[ "$XP_GATE_SKIP_UI_GATES" == "1" ]]; then
     exit 1
   fi
   echo "⚠️  UI Gate BYPASSED — reason: $XP_GATE_BYPASS_REASON"
-  AUDIT_ENTRY="{\"timestamp\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"branch\":\"$CURRENT_BRANCH\",\"commit\":\"$(git rev-parse HEAD)\",\"user\":\"$(git config user.name || echo 'unknown')\",\"reason\":\"$XP_GATE_BYPASS_REASON\",\"bypass_type\":\"ui-gates\"}"
+  # #710: build the whole record in node rather than interpolating shell
+  # variables into a JSON string. Values come from the environment so no shell
+  # quoting layer can mangle them (an earlier sed-based escaper silently
+  # dropped the reason entirely when its backslash expression broke).
+  #
+  # The reason is free-form USER INPUT: one double quote in it used to end the
+  # JSON string early and turn the audit line into garbage. An audit trail that
+  # can be corrupted by the thing it is auditing is not an audit trail.
+  AUDIT_ENTRY=$(
+    _AJ_TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ") \
+    _AJ_BRANCH="$CURRENT_BRANCH" \
+    _AJ_COMMIT="$(git rev-parse HEAD 2>/dev/null)" \
+    _AJ_USER="$(git config user.name 2>/dev/null)" \
+    _AJ_REASON="$XP_GATE_BYPASS_REASON" \
+    node -e '
+      const env = process.env;
+      const clean = (v, fallback) => {
+        const s = String(v === undefined ? "" : v).replace(/[\r\n]+/g, " ").trim();
+        return s === "" ? fallback : s;
+      };
+      process.stdout.write(JSON.stringify({
+        timestamp: env._AJ_TS,
+        branch: clean(env._AJ_BRANCH, "unknown"),
+        commit: clean(env._AJ_COMMIT, "unknown"),
+        user: clean(env._AJ_USER, "unknown"),
+        reason: clean(env._AJ_REASON, ""),
+        bypass_type: "ui-gates",
+      }));
+    ' 2>/dev/null
+  )
   echo "$AUDIT_ENTRY" >> .audit-log.jsonl
 else
     # Detect UI changes in pushed files.
@@ -1310,7 +1347,9 @@ CURRENT_TIME=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 # evidence (#574). It is passed explicitly instead of letting the validator
 # infer it from cwd: the gate's subject is the repo being pushed, and a cwd-
 # derived lookup would bind xp-gate's own config whenever the suite runs here.
-MW_PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo "")
+MW_PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || MW_PROJECT_ROOT=""
+MW_PROJECT_ROOT=$(printf '%s' "$MW_PROJECT_ROOT" | tr -d '
+')
 if ! VALIDATION_ERROR=$(node "$MW_VALIDATOR" "$RESULT_FILE" "$EXPECTED_COMMIT" "$CURRENT_BRANCH" "$CURRENT_TIME" "$MW_PROJECT_ROOT" 2>&1); then
   echo ""
   echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

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);
+  });
+});