Why durability
An autonomous task should not exist only inside a model conversation
Multi-step coding work can outlive a provider connection, terminal session, process, or machine restart. If the only record is a chat transcript, recovery requires guessing which actions completed and which tool calls are safe to repeat. That is particularly dangerous for file writes, commands, database mutations, and external API calls.
A durable AI agent run stores its objective, phase, status, model steps, tool results, events, verification state, and completion report outside the active context window. It can then distinguish completed work from the next pending action after interruption.
Run state is written privately under ~/.uintell/runs with versioning and bounded serialized fields.
Structured tool results survive context changes and prevent completed calls from being replayed during resume.
Verification and independent review are explicit phases rather than optional prose in the final response.
Failed gates can schedule repair work, but the loop has a finite budget and reports unresolved defects when exhausted.
A run remains bounded by its turn limit, repair budget, permission policy, confirmation requests, cancellation signal, and quality gates.
Run pipeline
Each phase has a different tool and evidence profile
UIntellAgent models a coding run as six step kinds. The sequence makes implementation, verification, and review distinct, and it limits which tools are appropriate during read-oriented phases.
| Phase | Purpose | Typical evidence |
|---|---|---|
| Inspect and plan | Understand the objective, repository, relevant memory, and constraints before mutation. | Files read, search matches, graph context, and a scoped implementation plan. |
| Implement | Change real workspace files and perform the work required by the objective. | Before-and-after file bytes, commands, generated artifacts, and tool results. |
| Verify | Run focused and repository-wide checks appropriate to the change. | Exit codes, test output, compiler errors, lint results, and diagnostics. |
| Review | Examine behavior, regression risk, and missing coverage independently from implementation. | Findings tied to files, commands, output, and acceptance criteria. |
| Repair | Address actionable verification or review failures without expanding scope unnecessarily. | New diffs and repeated checks associated with a numbered repair round. |
| Finalize | Produce a result grounded in the run ledger and disclose unresolved risk. | Completion status, summary, checks run, changed files, and remaining issues. |
Planning, verification, and review restrict mutation-oriented tools. Implementation and repair can use the complete tool set, but they still pass through the shared permission engine. Finalization can read graph context and only write graph memory when the run was explicitly started with memory writes enabled.
Checkpoint model
Persist the control state, not just a generated summary
A useful checkpoint needs enough structure to continue deterministically. UIntellAgent stores the serialized Rig agent run, tool results keyed by call identity, task steps and attempts, status, events, context ledger, quality decisions, repair count, objective, workspace, and model configuration.
Bounded persistence protects recovery
- Objectives are bounded to 32,000 characters.
- A checkpoint file is bounded to 32 MiB.
- Stored tool output, context output, event detail, and total event count each have explicit limits.
- Run files use a format version so incompatible state can be detected.
- Only one process may drive a particular run at a time.
These limits prevent a single command or model response from turning checkpoint storage into an unbounded log. The run retains enough output for evidence and resume while truncating values that exceed the durable format's policy.
A partially written run file is worse than an older complete checkpoint. UIntellAgent writes checkpoints through a temporary path and replacement flow.
Quality gates
Verification and review can fail the run closed
An implementation phase completing without a tool error does not prove that the objective is satisfied. The run pipeline therefore interprets verification and review output as gates. Actionable failures schedule a repair round before finalization.
Run commands relevant to the repository and change, preserving their actual exit status and output.
Classify whether verification passed, failed, or produced an unresolved condition that needs attention.
Look for behavioral defects, regressions, missing tests, security issues, and unsupported completion claims.
Address actionable defects and repeat the relevant checks. The current runtime allows at most two scheduled repair rounds.
If the repair budget is exhausted, finalization must disclose the unresolved quality gate instead of claiming success.
A run can finish as completed or needs attention. The latter is a valid terminal result: it communicates that bounded work finished but the evidence does not support an unqualified success claim.
Cancellation and recovery
Resume from recorded results instead of replaying side effects
Run statuses include pending, running, paused, completed, needs attention, failed, and cancelled. Pending, running, paused, failed, and cancelled runs are resumable; completed and needs-attention runs are terminal records.
When UIntellAgent loads a checkpoint that was still marked running, it presents that run aspaused. This handles process crashes and abrupt terminal exits without pretending the previous worker is still active. Resume restores the serialized model run and the tool-result ledger, so already recorded tool calls are not issued again.
Cancellation remains cooperative and visible
Use c, Esc, or Ctrl+G to cancel active work from the TUI. The run records a cancellation event and saves its latest safe state. A later resume continues under the current provider readiness and permission policy rather than bypassing a confirmation that was previously pending.
The result ledger prevents UIntellAgent from replaying recorded tool calls. External services still need their own idempotency controls for network failures whose outcome was never observed.
Operate durable runs
Use Chat, the Runs workspace, or the CLI
Start from Chat with /task <objective>, open Runs with Alt+5 and press n, or use the command line for scripts and headless operation. Add --remember only when the task should be allowed to create or modify persistent graph knowledge.
./target/release/uintell-agent task start "implement the change and verify it"
./target/release/uintell-agent task start --remember "implement and record the design decision"
./target/release/uintell-agent task list
./target/release/uintell-agent task show <run-id>
./target/release/uintell-agent task resume <run-id>The Runs workspace displays the selected objective, current step, status, event timeline, tool results, repair rounds, and report. Agent-authored file changes remain available in Editor as independent review hunks after the run stops.