Summary

Summary

Document an optional PENDING.md workspace pattern for tracking durable commitments that must survive session reset, compaction, and multi-day execution boundaries. This would be a docs-only proposal with no runtime or API changes.

Problem to solve

OpenClaw already has strong native mechanisms such as Background Tasks, Cron Jobs, Standing Orders, and HEARTBEAT.md, but they solve adjacent problems rather than one specific gap: tracking user-visible commitments that must survive session changes.

In practice, this comes up when an agent and operator have clearly agreed that something should continue later, be checked again, or be completed by a deadline, but that commitment is not persisted in a durable workspace file.

Typical examples:

• “Continue this API export tomorrow”
• “Keep watching this and alert me if it is overdue”
• “Follow up on this by Friday even if the session changes”

Current mechanisms are close, but not quite the same:

• Background Tasks track execution state, not durable operator-facing commitments
• Cron schedules triggers, not a human-readable record of what is owed
• Standing Orders represent persistent authorization, not deadline-oriented follow-through
• HEARTBEAT.md can perform checks, but it still needs a durable source of commitments to inspect

The result is that commitments can be lost after session reset or compaction, especially in multi-day or rate-limited workflows. Users then have to reconstruct context manually, or the agent simply fails to follow through until the user asks again.

This seems less like a missing scheduler and more like a missing documented durable-memory pattern for commitments.

Proposed solution

Document PENDING.md as an optional workspace file pattern for durable commitments.

The proposal is intentionally lightweight:

• plain Markdown in the workspace
• user-controlled and manually editable
• not auto-injected
• no parser, schema, or runtime support required
• designed to complement existing mechanisms rather than replace them

A minimal example could look like this:

### API Batch Job - Data Export
- Committed: 2026-04-17
- Deadline: 2026-04-22
- Description: Export 1000 records via rate-limited API
- Status: In Progress (800/1000 complete)
- Notes: API rate limited, cron resumes at 02:00 daily

This pattern becomes especially useful when paired with HEARTBEAT.md, for example:

tasks:

- name: pending-commitment-check
  interval: 30m
  prompt: |
    Read PENDING.md if it exists.
    Check active items for overdue deadlines or missed checkpoints.
    Report actionable exceptions to the user.
    If nothing needs attention, reply HEARTBEAT_OK.

Suggested documentation scope:

• mention the pattern in docs/gateway/heartbeat.md
• cross-reference it in workspace documentation
• optionally provide a starter template such as docs/templates/PENDING.md.example
• clarify when to use this pattern vs Background Tasks / Cron / Standing Orders

This is meant as a community workspace convention documented by the project, not as a new built-in feature.

Alternatives considered

I considered a few alternatives, but each seems weaker for this specific problem.

Using Background Tasks alone does not fully solve it, because Background Tasks represent execution units rather than durable user-facing commitments across sessions.

Using Cron alone helps schedule future actions, but it does not create a readable commitment record with status, deadline, or operator intent.

Using Standing Orders is also not a great fit, because they are about persistent authority and execution boundaries, not commitment tracking.

Relying on conversation context is fragile because session reset and compaction are expected parts of the system.

Building a new built-in commitment tracker would likely be overkill when a workspace-file pattern already fits OpenClaw’s “workspace as private memory” model and requires no code changes.

Impact

Affected users/systems/channels:

• automation-heavy self-hosted deployments
• multi-day workflows such as API batch jobs, document processing, and follow-up tasks
• users who rely on explicit operator/agent commitments across session boundaries

Severity:

• Medium
• this does not block core usage, but it does create real follow-through failures and manual recovery work

Frequency:

• Frequent for power users
• intermittent for casual users
• most visible when work spans multiple sessions, days, or rate-limited execution windows

Consequence:

• commitments can be forgotten after session reset
• overdue or stalled work may go unnoticed unless the user asks again
• operators spend extra time reconstructing context
• trust is reduced when the agent appears to “forget” explicit promises

Evidence/examples

This proposal came from real production usage rather than a purely theoretical design.

A representative example is a rate-limited batch workflow that cannot finish in one session:

• Day 1: a cron-triggered batch job starts
• later: the job pauses because of API rate limits
• overnight or next session: the agent no longer has the original commitment context
• next day: the user asks for status, but there is no durable commitment record unless it was explicitly written somewhere

In local testing, the pattern worked well when PENDING.md was used as the durable record and heartbeat checks explicitly read it for deadline monitoring.

This also appears to align with OpenClaw’s documented model of workspace files as transparent, operator-controlled memory.

If helpful, I can follow up with a docs-only PR containing:

• a minimal PENDING.md example
• guidance on when to use it
• heartbeat integration example
• comparison notes against existing mechanisms

Additional information

A few boundaries are important here:

• this is not a request for runtime changes
• this is not a request for a new built-in task system
• this is not a replacement for Background Tasks, Cron, or Standing Orders
• this is only a request to document an optional workspace pattern that some users may find useful

What I am mainly looking for from maintainers is:

• whether this pattern fits OpenClaw’s vision
• whether official docs are the right place for it
• whether it belongs in heartbeat docs, workspace docs, or both
• whether the recommended structure should stay minimal or include a more complete template

If maintainers think this is a good fit, I’m happy to open a small docs-only PR.