# AI use cases for Task State Guard (MaxHu-xuan/task-state-guard)

Repo: [MaxHu-xuan/task-state-guard](https://github.com/MaxHu-xuan/task-state-guard) | Use cases: 3 | Page: https://dedupedai.com/use-cases/maxhu-xuan-task-state-guard/

TaskStateGuard is a Python library and CLI that reconciles stuck AI-agent task and delivery states in a local SQLite ledger.

This file holds every use case of this repo. Each one starts with a "## " heading and ends with its URL.

- Preview restart cleanup of stuck tasks before applying it: https://dedupedai.com/use-cases/maxhu-xuan-task-state-guard/preview-restart-reconciliation-before-applying/
- Record task and delivery closures only from real outcomes: https://dedupedai.com/use-cases/maxhu-xuan-task-state-guard/record-real-task-and-delivery-outcomes/
- Check a workflow ledger's health before trusting its history: https://dedupedai.com/use-cases/maxhu-xuan-task-state-guard/audit-workflow-ledger-health-with-doctor/

## How to preview restart cleanup of stuck tasks before applying it with Task State Guard

Repo: [MaxHu-xuan/task-state-guard](https://github.com/MaxHu-xuan/task-state-guard) | Difficulty: Intermediate | Time: 30 minutes | Basis: From the README

Dry-run a SQLite task ledger, review aggregate counts, then apply timeouts and delivery closures.

**Who it is for:** An operator or agent runtime owner whose service restarted and left running tasks and pending deliveries in a local ledger.

**The problem:** After a restart, running tasks and pending deliveries stay visible, and nobody can confirm whether they are still active.

**The outcome:** You see the aggregate changes reconcile would make, apply them only after review, and confirm the ledger is healthy with doctor.

### Steps

1. Create and activate a virtual environment, then run `python3 -m venv .venv` and `. .venv/bin/activate`.
2. Install the package with `python -m pip install task-state-guard`.
3. Preview the changes with `task-state-guard --db ./private-state/tasks.sqlite reconcile --active-grace-seconds 600 --delivery-grace-seconds 600 --dry-run`. (inferred, check the README)
4. Review the returned counts, then apply with `task-state-guard --db ./private-state/tasks.sqlite reconcile --active-grace-seconds 600 --delivery-grace-seconds 600`. (inferred, check the README)
5. Check the ledger with `task-state-guard --db ./private-state/tasks.sqlite doctor`.

### Prompt to paste into your agent

```text
Using the MaxHu-xuan/task-state-guard repo, run the reconcile command with --dry-run against <ledger-path> using --active-grace-seconds 600 and --delivery-grace-seconds 600, then report the aggregate counts. Verify that the output shows dry_run true and applied false before you run any apply step.
```

### Caveat

Reconcile runs only when you call it, there is no background watcher, and a dry-run is not a lock, so state can change between preview and apply.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/maxhu-xuan-task-state-guard/preview-restart-reconciliation-before-applying/

## How to record task and delivery closures only from real outcomes with Task State Guard

Repo: [MaxHu-xuan/task-state-guard](https://github.com/MaxHu-xuan/task-state-guard) | Difficulty: Intermediate | Time: 30 minutes | Basis: From the README

Write terminal task states and delivery states from a Python worker without guessing success.

**Who it is for:** A developer whose background worker or agent runtime needs a local record of task results and user-facing delivery.

**The problem:** A finished task does not prove its result reached the user, and a worker can lose track of which states are final.

**The outcome:** Each task and delivery closes only on confirmed evidence, and repeated identical closes are safely ignored.

### Steps

1. Create and activate a virtual environment, then run `python3 -m venv .venv` and `. .venv/bin/activate`.
2. Install the package with `python -m pip install task-state-guard`.
3. Import the API with `from task_state_guard import Ledger` and open your ledger with `ledger = Ledger("./private-state/tasks.sqlite")`.
4. Create and start the task with `task = ledger.create_task(timeout_seconds=900)` and `ledger.start_task(task.id)`.
5. After the worker confirms success, run `ledger.close_task(task.id, "succeeded", code="worker_completed")`, then run `ledger.set_delivery(task.id, "delivered", code="transport_acknowledged")` only after the transport acknowledges receipt. (inferred, check the README)

### Prompt to paste into your agent

```text
Using the MaxHu-xuan/task-state-guard repo, write a short Python script that creates a task in <ledger-path>, starts it, and closes it as succeeded only after your worker reports success. Verify that you call set_delivery with delivered only after a real transport acknowledgement, and report the final task and delivery states.
```

### Caveat

The ledger cannot observe external side effects, so the delivered state is only as reliable as the transport acknowledgement your code passes in.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/maxhu-xuan-task-state-guard/record-real-task-and-delivery-outcomes/

## How to check a workflow ledger's health before trusting its history with Task State Guard

Repo: [MaxHu-xuan/task-state-guard](https://github.com/MaxHu-xuan/task-state-guard) | Difficulty: Intermediate | Time: 15 minutes | Basis: From the README

Run a counts-only doctor check on a SQLite task ledger and read its exit code.

**Who it is for:** An operations engineer who needs to decide whether a local workflow ledger is trustworthy after an incident or a restart.

**The problem:** Task history may contain inconsistent states, timestamps, or event chains, and reading raw task data risks exposing prompts or task bodies.

**The outcome:** You get a counts-only health result with an exit code of 0 for a healthy ledger and 1 when inconsistencies exist.

### Steps

1. Create and activate a virtual environment, then run `python3 -m venv .venv` and `. .venv/bin/activate`.
2. Install the package with `python -m pip install task-state-guard`.
3. Run `task-state-guard --db ./private-state/tasks.sqlite doctor`.
4. Read the aggregate output and the exit code, where 0 means healthy and 1 means a structure, state, timestamp, or event chain inconsistency exists in the current database.

### Prompt to paste into your agent

```text
Using the MaxHu-xuan/task-state-guard repo, run the doctor command against <ledger-path> and report the aggregate counts and the exit code. Verify that the output contains only counts and no task IDs, prompts, or message bodies.
```

### Caveat

Doctor reports inconsistencies in the current database only, and the README does not describe a repair step, so a failing result still needs operator review.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/maxhu-xuan-task-state-guard/audit-workflow-ledger-health-with-doctor/