Version lifecycle & roles
An im-cli push lands in the agent's draft version: it updates the open draft
when there is one, and creates a new version when there is not. A version moves
through a fixed set of states, and which ones you can run depends on your role.
States
| State | How it's reached |
|---|---|
draft | The default landing state of im-cli push. Iterate on it freely: each push updates it in place. |
pending_review | A draft submitted for review — via im-cli push --submit or a later submit. |
published | A pending-review version approved by a reviewer, or promoted by an admin. Publishing auto-archives the previously published version. |
archived | A previously published version, superseded by a newer publish. |
rejected | A pending-review version a reviewer declined. |
replaced | A draft superseded by im-cli push --new-version, or a pending-review version superseded by im-cli push --force (see below). |
push ──▶ draft ──submit──▶ pending_review ──approve/publish──▶ published
│ │
└── reject ──▶ rejected supersede ──▶ archived
Who can run what
im-cli run and the Portal playground apply the same rule, so you can test a
version before it's public:
| Role | Can run |
|---|---|
| Developer (agent participant) | Their draft versions |
| Reviewer (agent participant) | pending_review versions |
| Anyone with access | published versions |
| Org admin / owner (and superadmin) | Any state |
im-cli agent versions shows every version, its status, and a RUNNABLE column
telling you which ones you may run. With no version argument, im-cli run picks
the latest runnable version — so right after im-cli push you can im-cli run your
fresh draft immediately.
Runs started from the CLI are stamped with the cli trigger source (the Portal
playground uses playground; external PAT calls use external), which is
visible in the execution history.
Review
A pending_review version is approved or rejected by a reviewer. Approval
publishes it (and archives the old published version atomically); rejection
records a reason. A reviewer cannot approve their own submission — the
Portal blocks self-approval. An org admin can also publish a pending-review
version directly, without a separate reviewer.
Updating a draft, replacement & --force
- Pushing while the agent has an open draft updates that draft in place:
same id, number and label, new code, new
.im/io.jsoncontract. A run that was paused for input on the draft can't be continued, because its next step would run the new code: the push cancels it, or, if it can't, answering it does. Earlier runs keep pointing at the draft and show its current code. im-cli push --new-versioncreates a new draft instead and supersedes the old one into thereplacedstate, so the timeline stays a clean chain. Use it to keep a draft's code (and any run paused on it) as it is.- Pushing while a version is in pending_review requires
im-cli push --force, which preempts the version under review with a new draft. Without--forcethe push is rejected (HTTP 409, exit code1).
Only drafts are ever updated: a version under review, published, archived or rejected never changes after its push.
Use --replaces-version <label> to make the lineage explicit when you want to
chain a push to a specific prior version.
Getting the source back
Every push retains the uploaded archive, so a version's source can be downloaded
again with im-cli pull — the code a
portal is actually running, recoverable independently of whoever's laptop pushed
it. Pulling needs the same permission as pushing.
Retention started with the release that introduced im-cli pull; versions pushed
before it have no archive and report so rather than failing quietly. Deleting an
agent deletes its retained archives, and an operator can set a retention window
(AGENTS_ARTIFACT_ARCHIVE_TTL_DAYS) after which older archives are pruned — the
currently published version's archive is always kept, whatever its age.