feat(openclaw): schedule cleaner execution on host requests

[lingsanbuer]

Summary

Upgrade the OpenClaw Context Cleaner from immediate canonical rewriting to scheduled, request-time execution.

Selecting tasks now creates a durable scheduled receipt without modifying the canonical transcript. The next ordinary OpenClaw request claims the scheduled plan, performs one canonical rewrite, and records the terminal receipt with real revision and operation evidence.

This completes the OpenClaw native-command and external CLI workflow required by the latest Context Cleaner acceptance plan.

What changed

Scheduled Cleaner execution

• Change task selection from immediate apply to durable scheduling.
• Persist an OpenClaw session-to-plan schedule pointer.
• Execute the scheduled plan on the next ordinary OpenClaw Context Engine request.
• Keep analysis, status, and cancellation read-only with respect to canonical context.
• Suppress conflicting automatic eviction while Cleaner work is pending or being consumed.
• Prevent terminal plans from executing more than once.

The new lifecycle is:

analyzed
→ explicit selection
→ scheduled
→ next ordinary OpenClaw request
→ applied / stale / failed

OpenClaw Cleaner architecture

Replace the previous monolithic Cleaner bridge with focused modules:

• snapshot.ts
  • reads canonical OpenClaw Cleaner snapshots
  • excludes adapter metadata and private payloads
• capabilities.ts
  • exposes the OpenClaw Cleaner Host capabilities factory
• scheduler.ts
  • persists stable session-to-plan schedule pointers
  • rejects conflicting and corrupt schedules
• runtime.ts
  • claims scheduled work on the next Host request
  • applies canonical rewrites through the existing reference backend
  • records applied, stale, and failed receipts
  • restores receipts from durable apply intents after interrupted commits
• service.ts
  • composes the shared Cleaner control service
  • serializes analyze, approve, cancel, and runtime execution
• session-lock.ts
  • protects schedule, cancellation, and execution races
  • recovers dead-owner locks without stealing live locks
• snapshot.ts
  • preserves the canonical snapshot and revision boundary used by Cleaner planning

Request-time execution

• Selection writes the Host schedule pointer and shared scheduled receipt.
• Selection does not immediately change the canonical transcript.
• The active TokenPilot Context Engine consumes the schedule during the next ordinary request.
• The runtime validates the stored base revision before rewriting.
• A stale revision produces a stale terminal receipt instead of applying obsolete targets.
• A successful rewrite records:
  • previous revision
  • next revision
  • operation IDs
  • canonical item IDs
  • measured applied character savings
• Pending or claimed Cleaner work suppresses conflicting automatic eviction for the same request.
• Replayed terminal plans do not execute another canonical rewrite.

Native OpenClaw commands

Preserve the existing native command surface:

/lightrsi clean [--session <session-id>]
/lightrsi clean --plan <plan-id> --select <task-id[,task-id...]>
/lightrsi clean --status <plan-id>
/lightrsi clean --cancel <plan-id>

The native command continues to provide:

• Host-managed task-registry bootstrap
• Context Cleaner analysis
• explicit task-ID selection
• status queries
• cancellation
• protected-task validation
• plan and receipt rendering

Selection now returns scheduled and explicitly tells the user that cleaning will run on the next ordinary OpenClaw request.

External CLI and TTY selector

Keep raw-key interaction in the external CLI:

lightrsi openclaw clean --require-tty --session <session-id>

The terminal selector supports:

• Up/Down navigation
• Space to toggle selectable tasks
• Enter to submit
• q to cancel
• protected tasks remaining visible but unselectable
• an empty initial selection
• estimated savings that update with the current selection

OpenClaw native commands and the external CLI share the same plans, schedules, and receipts.

The native slash command intentionally does not take over OpenClaw TUI keyboard input.

Recovery and concurrency safety

• Preserve the existing canonical OpenClaw reference backend.
• Persist an apply intent around canonical rewrite and receipt commit.
• Recover an applied receipt after restart without repeating the rewrite.
• Serialize scheduling, cancellation, and execution through the same session lock.
• Reject conflicting schedule pointers.
• Fail closed on corrupt schedules.
• Never replace a lock owned by a live process.
• Recover locks left by a dead process.
• Preserve cancelled plans as terminal across later Host requests.
• Reject protected, unknown, duplicate, and malformed selections.

Output improvements

• Distinguish estimated, scheduled, and applied savings.
• Show Apply timing: next Host request for scheduled receipts.
• Show completion timing after request-time application.
• Preserve chars_only units in receipts, including zero-value receipts.
• Display character-based task shares when no trustworthy task-level token meter is available.
• Keep complete task IDs, descriptions, and reason codes available outside the compact table.

Manual acceptance

Verified against a real OpenClaw installation with TokenPilot configured as the active Context Engine.

Native scheduled execution

• Analyzed a session containing completed and protected tasks.
• Selected a completed task using the native command.
• Confirmed the result was scheduled.
• Confirmed Applied savings remained not applied.
• Queried --status and confirmed it did not trigger execution.
• Sent the next ordinary OpenClaw message.
• Confirmed the plan became applied.
• Confirmed estimated and applied savings matched.
• Sent another ordinary request and confirmed the plan was not executed again.

Observed example:

Context clean scheduled
Estimated savings: 3492 chars
Scheduled savings: 3492 chars
Applied savings: not applied
Apply timing: next Host request.

After the next ordinary request:

Context clean applied
Estimated savings: 3492 chars
Applied savings: 3492 chars
Apply timing: next Host request (completed).

Cross-entry workflow

• Created a plan with the external arrow-key CLI.
• Selected a task using Up/Down, Space, and Enter.
• Read the same scheduled receipt through /lightrsi clean --status.
• Sent the next ordinary OpenClaw request.
• Confirmed the native command reported the same plan as applied.
• Confirmed the applied savings matched the CLI estimate.

Observed example:

Context clean scheduled
Estimated savings: 3168 chars
Scheduled savings: 3168 chars
Applied savings: not applied

After the next ordinary request:

Context clean applied
Estimated savings: 3168 chars
Applied savings: 3168 chars

Interactive selector

Verified in a real WSL terminal:

• Up moved between selectable tasks.
• Down moved between selectable tasks.
• Space selected and deselected individual tasks.
• Enter submitted the selected task.
• q cancelled without scheduling a rewrite.
• Protected tasks remained visible and could not be selected.
• The selection estimate updated with the selected tasks.

Cancellation and protection

• Cancelled an interactive plan with q.
• Explicitly cancelled a scheduled plan with /lightrsi clean --cancel.
• Confirmed the receipt contained cancelled_by_user.
• Sent another ordinary request.
• Confirmed the cancelled plan remained cancelled and was not applied.
• Attempted to select a protected task.
• Confirmed the command returned clean_selection_task_protected.
• Confirmed the rejected plan remained analyzed.
• Confirmed no context mutation occurred.

Automated verification

@lightrsi/openclaw-adapter typecheck: passed
@lightrsi/openclaw-adapter tests: 156/156 passed
@lightrsi/openclaw-adapter build: passed

@lightrsi/cli typecheck: passed
@lightrsi/cli tests: 89/89 passed
@lightrsi/cli build: passed

git diff --check: passed

Notes

• OpenClaw native commands use explicit task IDs for selection.
• Arrow-key interaction remains in the external CLI by design.
• Native analysis performs task-registry bootstrap through OpenClaw-managed inference.
• The external CLI reuses the durable task registry, plans, schedules, and receipts without reading Host model credentials.
• Token accounting remains chars_only when no trustworthy task-level token meter exists.
• Selection never changes canonical context immediately; application occurs only on the next ordinary OpenClaw request.