A SQLite Ledger That Knows When to Admit It Doesn't Know

What it does

TaskStateGuard is an embedded SQLite ledger for AI agents, background workers, and local workflows that reconciles task and delivery states after crashes or timeouts. It splits the question of “did the work finish?” from “did the result actually arrive?” and converges stale states according to explicit grace periods. Before it changes anything, a --dry-run preview returns only aggregate counts—no task IDs, no raw data.

The interesting bit

The tool’s defining quirk is epistemic humility: if a worker or transport never reported back, the ledger will not invent a success or delivery receipt. Diagnostics like doctor and reconciliation reports deliberately return summaries instead of task details, so prompts and payloads never leak into the state database or logs.

Key highlights

• Two separate state machines: one for task lifecycle (queued → running → terminal) and one for delivery (pending → closed only after the task finishes).
• Terminal states are immutable; repeated writes are idempotent, and conflicting terminal states are rejected.
• Preview, apply, and health-check outputs are strictly aggregated counts—no individual task identifiers exposed.
• Pure Python standard library with no network code or telemetry; runs fully offline across Linux, macOS, and Windows.
• Optional SHA-256 payload fingerprints are pseudonymized metadata, not anonymized data.

Caveats

• It is not a queue, scheduler, worker, retry service, or workflow engine; it reconciles state but will not resume interrupted tasks.
• Reconciliation happens only when explicitly invoked—there is no background watcher, so stale tasks wait until you call reconcile.
• On Windows, the tool expects you to configure private DACL boundaries yourself; it merely confirms you have done so.

Verdict

Useful if you need auditable, restart-safe bookkeeping for agent or worker state without leaking task contents. Not what you want if you are shopping for a task queue, automatic retries, or process supervision.