smart-wake

name	smart-wake
description	Prevent subagent timeout using checkpoint + cron wake + resume via session spawn mechanism.

SKILL: smart-wake

Objective

Ensure long-running tasks do not lose progress when subagent timeout occurs.

Standard mechanism:

1. Auto-save state before timeout / reaching timeout threshold.
2. Cron wake to re-invoke agent at scheduled time.
3. Resume task from latest checkpoint using sessions_spawn (or session_spawn depending on runtime) with appropriate wakeMode.

---

Activation Triggers

Use smart-wake when any of the following conditions are met:

• Task duration exceeds default subagent timeout.
• Requires periodic polling (by minute/hour) to continue processing.
• Multi-step workflow that may pause mid-execution but must resume accurately.
• Running overnight / off-hours but still needs to auto-continue.

---

Available Tools (Built-in)

• sessions_spawn / session_spawn (spawn new work session)
• Gateway cron jobs (schedule wake events)
• Memory/slot for state persistence (state checkpoint)

Do not create new tools. Only use existing mechanisms.

---

State Contract (MANDATORY)

Each task must implement checkpointing with minimum schema:

{
  "task_id": "smartwake_<slug>_<timestamp>",
  "goal": "Final objective",
  "status": "running|waiting|blocked|done|failed",
  "current_step": "step_name",
  "progress_pct": 0,
  "last_completed": ["step_a", "step_b"],
  "next_actions": ["action_1", "action_2"],
  "artifacts": ["path/file1", "path/file2"],
  "errors": [],
  "retry_count": 0,
  "updated_at": "ISO_TIMESTAMP"
}

Requirements:

• Update checkpoint after each completed step.
• Final checkpoint before timeout.
• Resume always reads latest checkpoint; never re-run blindly.

---

Standard Workflow

Step 1 — Preflight (Estimate Timeout)

• Determine subagent timeout and total task duration.
• If estimated_duration > 70% timeout: enable smart-wake immediately.
• Create task_id and initial checkpoint.

Step 2 — Execute by Small Chunks

• Divide task into 5–15 minute chunks.
• After each chunk:
  • Write progress to checkpoint,
  • Record artifact/path,
  • Update next_actions.

Step 3 — Pre-timeout Auto-save

• When ~10–20% timeout remains:
  • Flush final checkpoint,
  • Set status = waiting,
  • Prepare resume payload (task_id + next_actions).

Step 4 — Schedule Cron Wake

• Register Gateway cron job to wake after appropriate interval (e.g., 2–10 minutes depending on load).
• Cron payload MUST contain:
  • task_id
  • resume_from=latest_checkpoint
  • reason=timeout_recovery

Step 5 — Spawn Resume Session

• At wake time, call sessions_spawn (or session_spawn) with wakeMode enabling auto-resume via cron.
• Pass concise context:
  • objective,
  • latest checkpoint,
  • next step,
  • completion criteria.

Step 6 — Resume + Idempotency Guard

• New session must:
  1. Read checkpoint,
  2. Verify artifacts exist,
  3. Skip completed steps,
  4. Continue exact next_actions.
• When entire task completes: set status = done, cancel remaining cron wakes.

---

Sample Resume Packet (Reference)

{
  "task": "Resume long-running task",
  "task_id": "smartwake_repo_scan_20260301T120000Z",
  "wakeMode": "cron",
  "resume": {
    "from": "latest_checkpoint",
    "current_step": "collect_phase_2",
    "next_actions": ["fetch page 6-10", "dedupe", "export report"]
  },
  "done_criteria": [
    "output file generated",
    "validation passed",
    "status marked done"
  ]
}

Note: Field names may vary by Gateway/OpenClaw version, but checkpoint + wakeMode + resume context principles are mandatory.

---

Operational Rules

1. Never resume without valid checkpoint.
2. Never overwrite artifacts without checksum/timestamp verification.
3. No infinite wake loops: limit retry_count (e.g., max 5).
4. Every wake must have clear reason (timeout_recovery, dependency_ready, scheduled_progress).
5. Clean up on done: completed task must clear related cron jobs.

---

Output Format After Each Wake Cycle

{
  "task_id": "smartwake_<...>",
  "status": "running|waiting|done|failed",
  "progress_pct": 65,
  "current_step": "...",
  "resumed_from_checkpoint": true,
  "next_wake_scheduled": true,
  "next_wake_at": "ISO_TIMESTAMP|null",
  "notes": "concise, auditable"
}

---

Anti-patterns (FORBIDDEN)

• Running long tasks without periodic checkpointing.
• Waking without passing task_id/resume context.
• Re-running entire pipeline from start when only 1 step is missing.
• Not canceling cron after done.

---

Expected Outcomes

• No state loss on subagent timeout.
• Long tasks progress steadily via cron wake.
• Full system auditability: checkpoint → wake → resume → done.