Trust model
Agents break things. The system is built for that.
Every write AgentShell performs is either buffered, journalled, atomic, or audited — usually several of those. What follows is the honest account of which is which, including the operations that are deliberately not transactional.
Two kinds of change
The single most important thing to understand about AgentShell is that configuration and content are governed by different rules. Confusing the two is how sites get into trouble.
| Operation class | Inside a transaction | Guarantees |
|---|---|---|
| Configuration zones, design tokens, layout, widget registration, custom CSS |
Staged. Nothing reaches the live site until commit. | Atomic write, a recorded revision, a token-level diff and a doctor run before it lands. |
| Content pages, posts, drafts, publish transitions |
Refused, by name, unless the operation is journal-aware. | Each write runs inside its own SQL transaction, so a failed write leaves nothing behind. |
Journalled contentcreate_draft, update_draft |
Allowed. The operation is recorded before the write is attempted. | Durable intent, a recovery marker on the post, and verified compensation. |
Published-content editingedit_published, publish_edit |
Allowed, one original per transaction. | The original stays untouched until the publish step commits; the edit lives in a private shadow row. |
Navigationregister_navigation |
Refused, by name. | Writes immediately. A rollback will not undo it — the tool says so in its own result. |
Say it accurately. If an agent ran a configuration change inside a transaction and created pages outside one, the honest description is “the configuration was transactional; the content was immediate.” Not “the whole change was transactional.”
The lease
Transactions expire, so a crashed agent cannot wedge the site.
A transaction lives in one option row. It carries a sixty-minute inactivity lease that only its owner renews, and every write to that row is a compare-and-swap against the row's current bytes. Two agents cannot both believe they own it.
- Only the owner's activity renews the lease. A peer's preview does not, or any reader could pin a transaction open forever.
- An expired transaction is not a transaction: it stops staging, cannot be previewed, and a write arriving after expiry goes to the database rather than into a buffer nobody can commit.
- A transaction holding durable content work is never auto-reclaimed.
beginrefuses with an explicit unrecovered-work message instead.
The journal
Intent before action, evidence before deletion.
For the operations that support it, AgentShell records what it is about to do before it does it. The record carries a strong after-image — type, status, slug, timestamps and a SHA-256 of the content — captured in the same SQL transaction as the write.
create_draft → intended → applied → compensated
^ ^ ^
| | └─ verified delete: marker, type, status,
| | slug and content hash must all match
| └─ write succeeded, after-image captured
└─ durable intent recorded before any write was attempted
Narrow by design
Only create_draft and update_draft journal today. Updates to other content, taxonomy, status transitions and permanent deletion are refused by name rather than half-implemented.
Delete, do not trash
Recovery deletes the draft outright. Trashing would rewrite the slug and leave a row that is itself content, so the object would no longer be the one the journal described.
Claims, not hopes
Each operation is claimed by a compare-and-swap on the transaction row, and a MySQL advisory lock serialises the destructive part across processes. Two callers computing the same claim means exactly one lands.
Atomicity
A failed content write leaves nothing behind.
WordPress's own insert path is not all-or-nothing: it writes the row, the slug, the terms, the meta and the status transitions as separate steps, and one branch can return an error after some of them. AgentShell wraps every content write in a bounded SQL transaction that rolls back on a WP_Error, a false result or a thrown exception.
| Field in the result | What it tells you |
|---|---|
atomicity.database_transaction | Whether the write really ran inside a transaction on a transactional engine. |
atomicity.engine | Which engine is actually backing wp_posts. |
atomicity.on_failure | What happens if the write fails: rolled back, or honestly, not. |
atomicity.not_covered | The side effects a rollback cannot undo — email, files, outbound HTTP — disclosed rather than assumed away. |
Per write, not per workflow. A page created successfully followed by a failed menu registration is two outcomes, not one. The atomicity block is scoped to the single call, and says so.
Recovery
What happens after the agent dies.
agentshell_get_journal— read the durable record of a transaction's content work. Read-only, and the existence of another actor's transaction is not disclosed.agentshell_recover_transaction— settle the outstanding operations: verify the evidence, then delete.- Recovery refuses anything it cannot prove. A post edited by somebody else after the write is a conflict, and the post is left alone.
- A conflict keeps the row. Only a settled operation frees the slot, so the record of what a human still has to decide is never discarded to make room.
Inspection and destruction are different
Inspecting a journal needs manage_options and, for anyone but the transaction's owner, an explicit opt-in. Destroying needs authority re-checked at the moment of compensation: the per-post delete_post capability is verified again immediately before each delete.
An owner with manage_options but no delete_post on the target is refused for compensation — not for inspection. The two powers are not interchangeable.
Next
See the loop in practice.
The recipes page contains the actual sessions used to build this site, including a staged edit to published content and a rollback that left the original untouched.