run

The istok run command group provides direct access to task runs.

A run represents one attempt to work on a task. It carries the active lease used for managed execution and validation, and keeps the execution state associated with that attempt.

For normal coding-agent workflows, agents use these operations through MCP. The CLI is useful for inspection, troubleshooting, and direct control.

Commands

Run:

istok run --help

The main run commands are:

List runs

List runs in the current project:

istok run list

Runs can be filtered by task:

istok run list --task 12

You can also filter by status and limit the number of returned results.

Inspect the available values with:

istok run list --help

Show a run

Inspect a specific run:

istok run show RUN_ID

Use show when you need the current state of a run before performing an operation that depends on its lease or revision.

Leases

An active run uses a lease to identify the current owner of the attempt.

Commands that mutate or execute work inside the run require the current lease:

--lease LEASE

For example:

istok run heartbeat RUN_ID --lease LEASE

and:

istok run validate RUN_ID --lease LEASE -- go test ./...

A lease is specific to the current run attempt. If it changes, use the new lease returned by Istok for subsequent operations.

Heartbeat

Extend the lease of an active run:

istok run heartbeat RUN_ID --lease LEASE

A heartbeat extends the expiration of the active lease.

This is useful for long-running work where the agent needs to keep ownership of the current attempt while implementation continues.

Coding agents can perform heartbeats through MCP as part of their workflow.

Execute a command

Use exec to run a managed command associated with the current run:

istok run exec RUN_ID --lease LEASE -- COMMAND

For example:

istok run exec RUN_ID --lease LEASE -- pnpm test

Everything after -- belongs to the executed command and its arguments.

For example:

istok run exec RUN_ID --lease LEASE -- \
  go test ./internal/auth -run TestRefresh

Managed execution keeps the command and its output associated with the run instead of leaving the operation only in terminal history.

Working directory

A managed command can use an explicit working directory:

istok run exec RUN_ID \
  --lease LEASE \
  --cwd packages/api \
  -- pnpm test

Execution limits

Managed execution supports timeout and output limits.

The default timeout for exec is 30 minutes.

Each captured output stream stores up to 1 MiB.

Use:

istok run exec --help

to inspect the available timeout and output-limit flags.

Validate a run

Use validate for commands whose result should become validation evidence for the work:

istok run validate RUN_ID --lease LEASE -- COMMAND

For example:

istok run validate RUN_ID --lease LEASE -- go test ./...

or:

istok run validate RUN_ID --lease LEASE -- pnpm test

As with exec, everything after -- is passed to the command being executed.

The default timeout for validation is 10 minutes.

Validation preserves the result as part of the run so later task completion can refer to concrete evidence rather than only an agent’s report that the checks passed.

exec and validate

Both commands execute managed processes, but they serve different purposes.

Use exec for work performed as part of implementation:

istok run exec RUN_ID --lease LEASE -- pnpm lint

Use validate when the result should be recorded as evidence for completion:

istok run validate RUN_ID --lease LEASE -- pnpm test

A typical run can contain multiple executions before its final validation.

Run
 ├── exec
 ├── exec
 ├── exec
 └── validate
       ↓
 validation evidence

Managed environment

Commands started through managed execution receive an allowlisted environment.

This keeps execution associated with the controlled Istok run workflow rather than passing the entire parent process environment implicitly.

Use the installed command help when you need the exact execution options available in your version.

Dangerous commands

Commands classified as dangerous require an explicit override:

--allow-dangerous

together with a reason:

--override-reason REASON

For example, when an operation genuinely requires the override:

istok run exec RUN_ID \
  --lease LEASE \
  --allow-dangerous \
  --override-reason "Required for the requested migration" \
  -- COMMAND

The reason makes the exception explicit in the recorded workflow.

Do not use the override for normal execution when it is not required.

Artifacts

Runs can contain recorded artifacts.

List artifacts associated with a run:

istok run artifact list RUN_ID

Verify a specific artifact:

istok run artifact verify ARTIFACT_ID --run RUN_ID

Use:

istok run artifact --help

to inspect the available artifact selectors and options.

Artifacts allow files or other recorded outputs to remain associated with the run that produced them.

Finish a run

When the attempt is complete, finish the run:

istok run finish RUN_ID \
  --lease LEASE \
  --expected-revision REVISION \
  --status STATUS \
  --summary "Implemented and validated."

finish requires:

• the current lease;
• the expected revision;
• the final status;
• a summary.

A successful finish normally requires passed validation.

Conceptually:

Active run
   ↓
Implementation
   ↓
Validation
   ↓
Passed evidence
   ↓
Finish

After a successful run is finished, its validation evidence can be used when completing the task.

Finish without validation

There are cases where a run may need to be finished without passed validation.

Istok requires this to be explicit.

Use the unvalidated override together with an auditable reason rather than silently treating the run as normally validated.

Inspect the exact flags with:

istok run finish --help

This path should be treated as an exception. The normal workflow is to validate the result before successfully finishing the run.

Recover a run

Recover an existing run when work needs to continue with a refreshed lease:

istok run recover RUN_ID --reason "Continuing interrupted work"

Recovery changes the lease while keeping the same run.

Recovery is tied to the same current actor.

A forced recovery is also available for cases where the actor needs to replace its own still-active token:

istok run recover RUN_ID \
  --force \
  --reason "Replacing stale local session"

--force applies only to the current actor’s own active token.

Use the new lease returned by recovery for subsequent run operations.

Abandon a run

If an attempt should no longer continue, abandon it:

istok run abandon RUN_ID \
  --expected-revision REVISION \
  --reason "Implementation approach needs to be restarted"

Abandoning a run ends the attempt but leaves the task open.

This makes it possible to start another attempt later without losing the history of what happened in the abandoned run.

Task
 │
 ├── Run A
 │     ↓
 │  abandoned
 │
 └── remains open
       ↓
    later claim
       ↓
     Run B

The abandoned state remains part of the run history.

The equivalent MCP operation is restricted to supervisor or admin access.

Revisions

State-changing run operations can require an expected revision.

For example:

istok run finish RUN_ID \
  --lease LEASE \
  --expected-revision 5 \
  --status STATUS \
  --summary "Finished"

and:

istok run abandon RUN_ID \
  --expected-revision 5 \
  --reason "Restarting the attempt"

If the run changed since you last inspected it, read it again and use the current revision.

This prevents stale operations from overwriting newer run state.

JSON output

Run JSON results use:

{
  "schema_version": "2"
}

MCP run results use the same run schema version.

See JSON output for the general JSON conventions used by Istok.

Command help

Use built-in help for the exact flags supported by your installed version:

istok run list --help
istok run show --help
istok run exec --help
istok run validate --help
istok run finish --help
istok run recover --help
istok run abandon --help

Next

Continue with the context command reference to inspect and manage durable project context directly from the CLI.