What Problem This Solves

Issue #95553 reports that preflight (budget-triggered) compaction cannot be disabled via config. The issue's "Expected behavior" section explicitly lists two user-asked solutions:

1. Honor agents.defaults.compaction.timeoutSeconds for the preflight/budget path too, or
2. Add a config toggle agents.defaults.compaction.preflight: false to skip preflight compaction entirely

This PR addresses solution 2: a strict, additive compaction.preflight.enabled config gate that short-circuits the preflight check and lets every turn fall through to overflow recovery (which already honors compaction.timeoutSeconds).

The check is === false against the literal value, so an unset key preserves the existing default-on behavior — the fix is strictly additive and does not change shipped behavior for any current user.

Why This Change Was Made

There are four open PRs already working on #95553, all focused on the same surface: the abortSignal source for the preflight path:

• fix: preflight compaction uses reply abort signal (~60s) instead of configurable compaction timeout (#95553) #95561 — AbortSignal.any([replyOp, AbortSignal.timeout(resolveCompactionTimeoutMs(cfg))])
• [codex] feat(mcp): share bundled runtime scope and fix preflight compaction abort #95563 — drop abortSignal: replyOp.signal and add a separate mcp.runtimeScope change
• fix(compaction): preflight compaction uses configured compaction timeout instead of reply operation abort signal #95580 — new createPreflightCompactionCancelSignal helper that filters out TimeoutError
• fix(reply): let preflight compaction use compaction timeout #95590 — drop abortSignal line entirely

None of those four PRs addresses the user-facing config dimension the issue explicitly requests. The preflight path is currently running for every user that hits the soft threshold, even users who would prefer to skip it. This PR ships the missing config dimension that complements any of the four abortSignal approaches once a maintainer picks one.

The change is narrow: a single 6-line early return placed after the isHeartbeat || isCli gate and before the Codex runtime gate, so it only affects OpenClaw's own preflight path. It is fully orthogonal to whichever abortSignal shape a maintainer chooses.

Changes

• src/config/types.agent-defaults.ts — new AgentCompactionPreflightConfig type with optional enabled: boolean
• src/config/zod-schema.agent-defaults.ts — preflight: z.object({ enabled: z.boolean().optional() }).strict().optional()
• src/config/schema.help.ts — two help entries: parent agents.defaults.compaction.preflight + leaf .enabled
• src/config/schema.labels.ts — two labels matching the help entries
• src/auto-reply/reply/agent-runner-memory.ts — 6-line early-return gate in runPreflightCompactionIfNeeded, placed after isHeartbeat/isCli and before the Codex runtime gate (only OpenClaw's own preflight path is gated)
• src/auto-reply/reply/agent-runner-memory.test.ts — new test "skips preflight compaction when cfg.agents.defaults.compaction.preflight.enabled === false" (uses the same fixture pattern as adjacent tests)
• docs/gateway/config-agents.md — add preflight.enabled to the JSON5 example and bullet list under agents.defaults.compaction, matching the schema/help coverage
• scripts/repro/issue-95553-preflight-disabled-gate.mts — standalone real-environment proof that writes a real openclaw.json and loads it via the production loadConfig() (not a cast)

User Impact

A user who adds the following to their openclaw.json now skips the budget-triggered preflight check and lets every turn fall through to overflow recovery:

{
  "agents": {
    "defaults": {
      "compaction": {
        "preflight": { "enabled": false }
      }
    }
  }
}

For users who do not set the key, behavior is unchanged.

Evidence

• Behavior addressed: preflight (budget-triggered) compaction can now be disabled via config, complementing the four open PRs that are all working on the abortSignal source for the same path

• Real environment tested: Linux x86_64, Node v24.14.1, repo at 5210d8b121 rebased onto personal/main (base c57fee8239ed)

• Exact steps run after this patch:

  $ node scripts/run-vitest.mjs src/auto-reply/reply/agent-runner-memory.test.ts
  
   RUN  v4.1.7 /home/0668000666/0668000666/AI/OpenClaw/new_open_claw
  
   Test Files  1 passed (1)
        Tests  41 passed (41)
     Start at  15:45:38
     Duration  17.86s (transform 4.48s, setup 395ms, import 8.27s, tests 8.90s, environment 0ms)
  
  [test] passed 1 Vitest shard in 28.18s

  $ node --import tsx scripts/repro/issue-95553-preflight-disabled-gate.mts
  
  === Reproduction for issue #95553 — preflight gate ===
  tmpDir: /tmp/openclaw-95553-repro-XTtBDw
  openclaw.json: /tmp/openclaw-95553-repro-XTtBDw/config/openclaw.json
  sessionFile: /tmp/openclaw-95553-repro-XTtBDw/sessions/session.jsonl
  loaded config: agents.defaults.compaction.preflight.enabled = false
  PASS  preflight.enabled === false short-circuits preflight check
        sessionEntry returned unchanged: session-95553-repro
  === All repro assertions passed ===

  The repro script proves the real openclaw.json → production loadConfig() → production runPreflightCompactionIfNeeded path. It writes openclaw.json to a temp state dir, points OPENCLAW_CONFIG_PATH and OPENCLAW_STATE_DIR at it via withEnvAsync, calls the production loadConfig({ pin: false }), asserts the gate value is parsed from disk, and then exercises the gate on the production preflight function. The function returns the original session entry unchanged; compactEmbeddedAgentSession is never reached.

• Observed result after fix: the production runPreflightCompactionIfNeeded returns the existing sessionEntry unchanged when compaction.preflight.enabled === false; compactEmbeddedAgentSession is never called; incrementCompactionCount is never called

• What was not tested: I did not exercise the live gateway path (the four open PRs also exercise the unit-test surface, not the live gateway); the unit test and repro script cover the full production gate code path through runPreflightCompactionIfNeeded

ClawSweeper review fixes (commit 5210d8b121)

The 🦪 silver shellfish review flagged three P1 findings on commit a140b0bb1b / ffd17f3a85; all three are addressed in commit 5210d8b121:

1. [P1] schema.help.ts:1518 timeout wording — replaced hardcoded "15-minute budget" claim with neutral wording that references compaction.timeoutSeconds only (no specific default minutes). The same wording fix applies to the inline code comment in agent-runner-memory.ts. The PR does not need to assume which timeout default the merge target carries.
2. [P1] public docs coverage — added preflight.enabled to the JSON5 example and the bullet list under agents.defaults.compaction in docs/gateway/config-agents.md. Public docs now describe the new knob consistently with the schema help.
3. [P1] real OpenClaw setup proof — rewrote the repro script to write a real openclaw.json to a temp state dir and load it through the production loadConfig(). The gate value is now parsed from disk through the same code path the gateway startup uses, not cast from an inline literal.

The single remaining CI failure (checks-node-core-fast, surface budget public exports 10328 > 10327 and public callable exports 5185 > 5184) is pre-existing on openclaw/main HEAD alone — see comment. This PR adds zero new public SDK exports; git diff c57fee8239ed..HEAD -- src/plugin-sdk/ is empty.

Related

• Refs Bug: preflight (budget-triggered) compaction hard-capped at ~60s, ignores compaction.timeoutSeconds #95553
• Complements (does not duplicate) fix: preflight compaction uses reply abort signal (~60s) instead of configurable compaction timeout (#95553) #95561, [codex] feat(mcp): share bundled runtime scope and fix preflight compaction abort #95563, fix(compaction): preflight compaction uses configured compaction timeout instead of reply operation abort signal #95580, fix(reply): let preflight compaction use compaction timeout #95590
• Branch: fix/95553-preflight-config-gate (carries only the preflight config gate; the prior feat/task-route-lease-module branch was abandoned per PR feat(compaction): add compaction.preflight.enabled config gate (#95553) #95648 close reason)
• Commits on branch: a140b0bb1b feat, ffd17f3a85 lint fix, 5210d8b121 review fixes