OpenViSTAI · Agents · Blockchain · Crypto
Submit a project
Menu
Agent Infrastructure

TaskStateGuard

TaskStateGuard is a Python library and command-line tool that uses an embedded SQLite ledger to reconcile stale AI-agent, worker and local-workflow task and delivery states after restarts or timeouts.

Explore the practical guide ↓

Independent OpenViST project profile, based on linked sources.

TaskStateGuard — OpenViST project profile in Agent Infrastructure.
OpenViST project illustration. See the linked sources for product details.
Understand the project

Practical overview

When it fits

Use it when a self-hosted agent runtime, worker or local workflow needs to reconcile a persistent task ledger after interruption, while retaining an explicit distinction between task outcome and delivery confirmation.

Who it is for

  • Operators of AI-agent runtimes who need to identify tasks left active after a restart.
  • Worker and workflow developers who need separate task-outcome and delivery tracking.
  • Teams that want aggregate-only previews and health checks for a local SQLite state ledger.

Documented uses

  • Reconcile stale active tasks using deadlines and grace periods.
  • Keep task completion distinct from whether an output was delivered.
  • Preview the aggregate effects of reconciliation before applying changes.
  • Check ledger, schema, state, timestamp and event-chain health using aggregate output.
Before you choose

Requirements & limits

  • The tool reconciles records but does not act as a queue, execute tasks or resume computation.
  • Dry-run counts are a snapshot; time and concurrent workers can change state before apply.
  • Linux and macOS use POSIX file protections; Windows requires an externally configured private DACL.
  • The project documents support for CPython 3.11–3.14 and a standard-library runtime.

Check current requirements in the official documentation. Source-based guidance does not mean OpenViST has run or independently tested this project.

Source-based practical guide

Preview and apply stale-state reconciliation

Inspect aggregate reconciliation counts, then apply the documented reconciliation rules to an existing ledger.

Before you start

  • TaskStateGuard installed in a virtual environment; CPython 3.11–3.14 is supported.
  • An existing SQLite ledger with an acceptable local file-protection boundary. The documented CLI dry run expects an existing WAL-mode ledger.
  • On Windows, a private DACL must be configured externally; place --allow-external-acl before the subcommand.

Steps

  1. Run the reconcile subcommand with active and delivery grace periods and --dry-run to view aggregate counts without changing records.

  2. Review the dry-run and applied fields; remember that the preview reflects its own moment and workers or time may change state afterward.

  3. Run reconcile with the same grace periods but without --dry-run to apply the rules.

  4. Run doctor to inspect the ledger through aggregate health-check output.

Expected outcome

A preview followed by an applied reconciliation of eligible stale task and delivery states, with an aggregate health check.

Guide limitations

  • The preview does not create a database, change permissions or migrate schema; it is not a guarantee that later state will be identical.
  • TaskStateGuard does not resume computation or infer successful work or delivery without observed evidence.
  • The Windows flag does not configure or verify the DACL.
Documentation 1 ↗
Evidence and transparency

Sources & review

Official repository ↗
Source record details
Source availability
Active
Sources checked
13 October 2026
Original website title
MaxHu-xuan/task-state-guard · Official homepage title · retained in its source language
How we review sourcesSuggest a correction