Bound Agent Workflow tracking so that local state is automatically pruned

.changeset/workflow-tracking-retention.md

@@ -0,0 +1,5 @@
+---
+"agents": patch
+---
+
+Automatically bound Agent Workflow tracking rows with terminal-outcome retention and alarm-driven cleanup that survives idle Agent eviction.

docs/agents/workflows.md

@@ -388,14 +388,19 @@ type WorkflowPage = {
 
 Delete a single workflow tracking record.
 
+This removes only the Agent's local SQLite tracking row. It does not delete or
+terminate the underlying Workflow instance.
+
 ```typescript
 const deleted = this.deleteWorkflow(instanceId);
 // true if deleted, false if not found
 ```
 
 #### `deleteWorkflows(criteria?)`
 
-Delete workflow tracking records matching criteria. Useful for cleanup.
+Delete workflow tracking records matching criteria before automatic retention
+expires. This affects only local Agent SQLite tracking, not underlying Workflow
+instances or their state.
 
 ```typescript
 // Delete all completed workflows older than 7 days
@@ -837,25 +842,18 @@ const approvalData = await this.waitForApproval(step, { timeout: "7 days" });
 2. **Use meaningful step names** - Helps with debugging and observability
 3. **Report progress regularly** - Keeps users informed
 4. **Handle errors gracefully** - Use `reportError()` before throwing
-5. **Clean up completed workflows** - The `cf_agents_workflows` table can grow unbounded, so implement a retention policy:
-
-```typescript
-// Option 1: Cleanup immediately on completion
-async onWorkflowComplete(workflowName, instanceId, result) {
-  // Process result first, then delete
-  this.deleteWorkflow(instanceId);
-}
-
-// Option 2: Scheduled cleanup (keep recent history)
-// Call this periodically via a scheduled task or cron
-this.deleteWorkflows({
-  status: ["complete", "errored"],
-  createdBefore: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000) // 7 days
-});
-
-// Option 3: Keep all history for compliance/auditing
-// Don't call deleteWorkflows() - query historical data as needed
-```
+5. **Treat Workflow tracking as bounded operational state** - The SDK
+   automatically deletes terminal rows from `cf_agents_workflows` after 30
+   days. It arms cleanup when tracking starts, computes expiry from the
+   terminal completion time, and recovers cleanup after Agent eviction without
+   requiring `onStart()` or `onReady()` hooks. This is a bounded local fallback
+   aligned with the maximum default Workflow retention on Workers Paid; it is
+   not indefinite audit history. Workers Free retains underlying Workflow state
+   for less time, so a local tracking row can temporarily outlive platform
+   state. Use an external durable store for compliance or long-term history.
+   `deleteWorkflow()` and `deleteWorkflows()` remain available for earlier
+   removal. Automatic and manual deletion affect only Agent SQLite tracking,
+   never the underlying Workflow instance or state.
 
 6. **Handle workflow binding renames carefully** - If you rename a workflow binding in `wrangler.jsonc`, existing tracked workflows will reference the old name. The agent will warn on startup if it detects this. Use `migrateWorkflowBinding()` to update them: