…rd (openclaw#76940)

Addresses Copilot's 5 inline review comments on PR openclaw#76950 plus 13
additional findings from a parallel adversarial sweep. Single
consolidated commit; per-finding diff lives below.

== Copilot review comments ==

(1) Archive-failure path used optional `logger.error?.()` so the
    fallback signal could be silently lost on loggers without `error`.
    Now ALWAYS emits a `warn` (deduped via warnedPaths) in addition to
    the optional error, so the signal survives loggers that only have
    warn.
    File: src/context-engine/fallback-guard.ts (archive catch block)

(2) The block-action error thrown from resolveContextEngine() didn't
    name the offending transcripts. Now includes basenames of the
    blocked files (capped at 5 + "+N more"), so operators see exactly
    which sessions trip the gate without leaking absolute paths into
    error stacks shared in bug reports.
    File: src/context-engine/registry.ts (fallbackToDefault helper)

(3) `defaultHasContextEngineHistory()` walked path.dirname THREE times
    from sessionsDir, landing at ~/.openclaw (global state) instead of
    the agent state dir. The auto-action heuristic mis-detected
    history. Now walks two dirs (sessionsDir → agentDir) and ALSO
    checks the global state root for legacy LCM installs that keep a
    shared sqlite store. Function additionally takes the injected
    `ioFs` so tests can stub it (previously bare `fs.existsSync`).
    File: src/context-engine/fallback-guard.ts

(4) The custom `isLiveSessionTranscript` filter accepted non-primary
    artifacts (.trajectory.jsonl, .checkpoint.<uuid>.jsonl) and could
    exclude legitimate primaries with `.deleted.` in id. Replaced with
    `isPrimarySessionTranscriptFileName` from
    src/config/sessions/artifacts.ts — the same predicate every other
    transcript code path uses. Custom filter deleted.
    File: src/context-engine/fallback-guard.ts

(5) `ApplyFallbackGuardOptions.agentDir` was documented + accepted by
    callers but never read. Now used to derive sessionsDir
    (`<agentDir>/sessions`) when supplied, before falling back to
    agentId-based resolution. Embedded runners that scope to a
    non-default state root now have the guard scoped correctly.
    File: src/context-engine/fallback-guard.ts (resolution order block)

== Additional adversarial-sweep findings ==

(6) [P0] Archive filename `<id>.archived-no-context-engine-<ts>.jsonl`
    was NOT recognized by `isPrimarySessionTranscriptFileName`, so the
    archived file got loaded as a live session on next gateway start —
    the guard accomplished nothing in the case it exists to fix. Now
    extends `SessionArchiveReason` with "context-fallback" and uses the
    canonical `<id>.jsonl.context-fallback.<iso-ts>-<nonce>` shape.
    Existing disk-budget pruning + transcript helpers correctly
    recognize and exclude these files.
    Files: src/config/sessions/artifacts.ts,
           src/context-engine/fallback-guard.ts (buildArchivePath)

(7) [P0] Doc-drift: schema.help.ts + types.base.ts JSDoc said
    "Default `1mb`" after the bump to 2mb in the prior commit. Both
    sites updated; types.base.ts now points readers at the constant
    in fallback-guard.ts so future changes stay in sync.
    Files: src/config/schema.help.ts, src/config/types.base.ts

(8) [P0] `action: "block"` was silently downgraded to warn at gateway
    boot — the boot wrapper discarded the outcome and never called
    `fallbackGuardOutcomeIsBlocking`. Now collects blocking outcomes
    across all agents and sets `process.exitCode = 1` with a
    structured error log, so launchd / systemd / docker treat the boot
    as unhealthy. Startup itself does not throw (degrades to
    "no protection this boot" if the guard faults internally).
    File: src/gateway/server-startup-post-attach.ts

(9) [P0] Boot guard was hardcoded to the "main" agent. Multi-agent
    installs (concierge, support, etc.) had no boot-time protection.
    Now iterates every agent under ~/.openclaw/agents/ via
    readdirSync(withFileTypes); falls back to DEFAULT_AGENT_ID for
    fresh installs / test environments.
    File: src/gateway/server-startup-post-attach.ts

(10) [P0] Four resolveContextEngine call sites passed no agentId, so
     when fallback fired for a non-default agent the guard walked the
     wrong agent's session directory. Plumbed agentId through:
       - src/agents/pi-embedded-runner/compact.queued.ts
         (hoisted resolveSessionAgentIds early)
       - src/agents/command/cli-compaction.ts
         (extended cliCompactionDeps.resolveContextEngine signature)
       - src/agents/subagent-spawn.ts
         (parseAgentSessionKey on requesterInternalKey)
       - src/agents/subagent-registry.ts
         (parseAgentSessionKey on childSessionKey)

(11) [P1] `renameSync` race: archive timestamp was millisecond-
     resolution; two archives in the same ms (rapid fallback across
     agents, or two large transcripts in one pass) collided and
     `renameSync` silently overwrites. Now appends a 6-hex random
     nonce.
     File: src/context-engine/fallback-guard.ts (buildArchivePath)

(12) [P1] `sizeBytes: 0` (or "0b" / "0kb") passed schema validation
     but was silently downgraded to the default in resolveGuardConfig
     — opposite of operator intent (trying to disable or tighten the
     guard would actually loosen it to default). Now logs an explicit
     warn so the misconfig is visible.
     File: src/context-engine/fallback-guard.ts (resolveGuardConfig)

(13) [P1] `openclaw sessions archive <id>` doesn't exist as a
     subcommand — operator-facing message printed a fake command.
     Replaced with `openclaw sessions cleanup --enforce`.
     `openclaw config set ... ""` likewise replaced with the canonical
     `openclaw config unset ...` form.
     File: src/context-engine/fallback-guard.ts (renderWarnMessage,
     renderArchiveMessage)

(14) [P1] Multi-line operator block destroyed by JSON log encoding
     (the JSON file logger encodes \n literally; the box-drawing
     characters became one mile-long line). Replaced unicode box
     drawing with explicit `----- BEGIN RECOVERY PROMPT -----` /
     `----- END RECOVERY PROMPT -----` delimiters that survive
     JSON encoding and are easy to grep / extract.
     File: src/context-engine/fallback-guard.ts

(15) [P1] Home-dir leaked into operator-facing paths. When operators
     paste the message into bug reports / GitHub issues / chat the
     username was exposed. Added `redactHomePrefix()` that substitutes
     `~` for the user's home prefix in the rendered prompt + Archived
     block. The structured `summary` line keeps the absolute path for
     grep-by-path.
     File: src/context-engine/fallback-guard.ts (renderRecoveryPrompt,
     renderWarnMessage, renderArchiveMessage)

(16) [P1] Two structurally-identical action union types
     (`SessionContextFallbackGuardAction` in types.base.ts and
     `FallbackGuardAction` in fallback-guard.ts). Now a single source
     of truth: `FallbackGuardAction` aliases the public type.
     Files: src/context-engine/fallback-guard.ts

(17) [P1] Recovery prompt assumed agent could safely Read a multi-MiB
     jsonl. Now explicitly tells the agent to use Read with
     offset/limit, skip individual messages over ~10k tokens, and
     bound itself to ~40k aggregate. Also added a "next likely action"
     bullet so the fresh session resumes work cleanly.
     File: src/context-engine/fallback-guard.ts (renderRecoveryPrompt)

(18) [P1] `agent="(default)"` printed in summary line when agentId
     was unset, but actual on-disk path uses `main`. Operators
     grepping by the printed label couldn't find the path. Now uses
     `DEFAULT_AGENT_ID` ("main") consistently.
     File: src/context-engine/fallback-guard.ts (renderAgentLabel)

(19) [P2] platform-specific restart hint: `launchctl` was
     unconditional. Now branches on process.platform to suggest
     `launchctl` on macOS, `systemctl --user restart` on Linux,
     `Restart-Service` on Windows.
     File: src/context-engine/fallback-guard.ts (platformRestartHint)

(20) [P2] `lstatSync` used in place of `statSync` so a symlink in the
     sessions dir doesn't get archived (previously could rename the
     link and orphan the target).
     File: src/context-engine/fallback-guard.ts

(21) [P2] Aggregated stat-error count is now logged at end of pass
     so an operator sees a signal when (e.g.) every file in the
     sessions dir is unreadable due to permission/quarantine drift —
     previously the swallowed errors produced an empty outcome with
     no clue why.
     File: src/context-engine/fallback-guard.ts (statErrors counter)

== Tests ==

  - 25 fallback-guard.test.ts cases pass (was 17 — 8 added covering
    canonical archive name, prior archives ignored, home-dir redact,
    nonce collision-avoidance, sizeBytes:0 warns, agentDir option used,
    archive-failure-also-warns, lstat for symlinks)
  - 6 zod-schema.session-maintenance-extensions.test.ts cases for
    contextFallbackGuard (valid/absent/casing/typo/malformed/wrong-level)
  - All 142 src/config/sessions tests pass unchanged
  - 95 total context-engine + maintenance-extension tests pass
  - Lint clean on changed files (the 2 remaining `__testing` warnings
    are pre-existing in v2026.5.2 and unrelated)

Refs openclaw#76940. Addresses inline review on PR openclaw#76950.

… dead activeContextEngineId, accurate token estimate, boot-message phrasing (openclaw#76940)

Three additional Copilot/sweep findings on the prior consolidated commit:

(22) [P1] params.log.error doesn't typecheck on the gateway post-attach
     surface (the typed log here is { info, warn } only — error is on
     the richer subsystem logger but not on this narrowed shape).
     Switched the boot-guard logger sink to omit `error` (the guard
     always emits a `warn` fallback when the optional error is absent)
     and the structured "block" startup line to use `warn`. The
     non-zero process.exitCode is the real signal external supervisors
     pick up, so demoting the channel doesn't lose anything.
     File: src/gateway/server-startup-post-attach.ts

(23) [P1] `activeContextEngineId` was required on ApplyBootGuardOptions
     but applyContextEngineBootGuard ignored it (re-read the same value
     from `options.config.plugins.slots.contextEngine`). Easy to
     misinterpret as "the boot guard respects the explicit
     activeContextEngineId override" when it does not. Removed the
     dead field; callers now pass only the loaded set + config.
     File: src/context-engine/fallback-guard.ts (ApplyBootGuardOptions)

(24) [P1] Operator messages printed `RECOVERY_PROMPT_MAX_SUMMARY_TOKENS`
     ("40k+ tokens of message content") for every transcript regardless
     of file size. Now estimates from the actual byte size with a
     simple ~4-chars-per-token heuristic, formatted with reasonable
     significant digits ("~580k tokens (estimated)" / "~1.4M tokens
     (estimated)").
     File: src/context-engine/fallback-guard.ts (estimateTokensFromBytes)

(25) [P2] The "Reason: Context engine X is configured but failed (...)"
     line in operator messages reads incorrectly when the boot guard
     fires for the no-engine case (failedEngineId is the synthetic
     "(legacy/none)" label, not a real configured engine). Branch on
     that label and emit a no-engine-specific reason block instead.
     File: src/context-engine/fallback-guard.ts (renderReasonLines)

Tests: all 25 fallback-guard cases still pass; the GuardMessageContext
type now carries `sizeBytes` so the token estimate has the source data
without re-deriving from the formatted MiB string.

Refs openclaw#76940. Addresses Copilot review on PR openclaw#76950.