Reviewing and approving changes

Sudo cannot apply anything. He can only ask, and what he asks with is a diff.

The rule

No silent writes

Edits live in the session's own copy of /workspace until commit stages them and stops. Only an administrator's approval applies anything, and what you approve is the diff you were shown.

Three things follow from that, and each is enforced rather than merely intended:

Build before commit. commit parses every changed file back through the workspace's own importer and compiles its body against the scope it will run in — and against the workspace as the whole change set leaves it, so a file naming a definition the same commit adds compiles, and one naming a definition it removes does not. It refuses the whole set if anything fails. --force exists, says so loudly in the output, and still needs your approval.
One way in. An approved commit is an ordinary definitions import of the files that differ, routed by exactly the same code that reads an uploaded definitions bundle. There is no parallel set of per-surface writers that could drift out of step with it.
One tracked change per approval. The import runs inside the workspace's tracked configuration change, so an approved commit is one commit in the configuration git history, attributed to the administrator who approved it, landing in the same history as a change you made by hand.

What you see

When Sudo runs commit, the chat renders that turn as an approval card instead of an ordinary tool chip, and the pending-changes panel in the chat toolbar picks up a badge. Opening it gives you the change in two shapes, both reading the same diff:

File list

A list of the changed files with a side-by-side diff for the one you select. Best for checking one file closely.

Pull request

Every file's diff one after the other, down one page, with a comment box under each. Best for forming an opinion about a change that spans several files.

The diff is read-only on purpose. Editing Sudo's draft in the review screen would put your change somewhere he cannot see it, and the file still sitting in his shell would silently disagree with what was applied. If something is wrong, say so in the chat: he edits the file, builds it, and commits again.

The three buttons


Approve	Applies every file in the commit. The apply streams its progress, so you see each file as it is imported along with any warnings the importer raises, rather than a spinner. It runs on the server: closing the tab or losing the connection costs you the log, not the change.
Discard	Throws the commit away and keeps the edits. Sudo still has the files; tell him what to change.
Reset	Throws away every uncommitted edit, putting his shell back to the live configuration.

A card left open while Sudo staged a newer commit refuses to apply: the id you were shown and the id he is holding differ, so approving would apply something nobody read. Ask him to show you the current one.

What approving does

flowchart TD A[You press Approve] --> B[Deletions applied first] B --> C[Each remaining file imported<br/>through the definitions importer] C --> D{Every file applied?} D -->|Yes| E[One tracked git commit,<br/>attributed to you] E --> F[Sudo's session reloads<br/>from the live configuration] D -->|No| G[Errors reported;<br/>the edits stay in his shell]

Deletions go first, so a change set that removes an endpoint and adds one on the same route removes before it adds rather than deleting what it just created. Search-index halves and package declarations are collected and handled together, because a search index is two files that only mean something as a pair.

On success his session is reloaded so his next command reads what was actually applied, which is what you want him looking at from there. On a partial failure the edits are kept and the errors are reported: whatever did not import is still work someone did, and throwing it away is the worst possible answer to "some of this did not apply".

Approving also says so in the conversation. Once the workspace has taken the commit, a message in your voice names it and how many files are live, and carries any notes you typed while reviewing in the same message rather than as a second one. Sudo is told to stop at a commit and wait, and the apply has just reset the shell he was working in — without that message the session would go on offering a change that is already live, and re-committing it would be wrong. Discarding says nothing, so silence is not approval; a failed apply says nothing either, because the progress sheet has already reported what went wrong.

Deleting things

A definitions file can also say something should be removed. Deleting a file from /workspace and committing resolves to the same deletion an imported bundle would express, so there is one meaning rather than two.

Three behaviours are worth knowing:

A built-in is refused for what it is, before the existence check. A workspace that has not seeded a built-in yet does not make deleting it reasonable.
A UID naming the wrong kind of node is left alone, with an error, because acting on it would delete an unrelated part of the workspace.
Naming something that is already absent is a warning, not an error, so the same change is safe to apply twice.

An index, a schema, a package or a configuration document is not one node that can be taken away, and says so rather than appearing to succeed.

What your account may do

Every session works the same way — Sudo drafts, you approve — Sudo is never allowed to change something without yoour approval. What still varies is your own permission, and it is the narrower of the two.

For a read-only administrator — and for any administrator while administrator write protection is on — commit and run refuse. Everything else works: Sudo reads the whole workspace, drafts in his own copy, and tells you what is ready, and the draft is kept for whoever can hand it over. The shell itself is not taken away, because taking it away would leave him unable to read the workspace either. See Security.

Accountability

Every shell call is metered into the workspace's own metrics under an Admin Agent bucket, separately from ordinary chat tools.
Every applied commit is one entry in the configuration history, attributed to the administrator who approved it, visible under Manage / Access / Audit log and readable from the sandbox at /proc/audit.
Every code surface additionally carries its own code history, so an endpoint, AI tool, task, index or entity post-processing script changed through Sudo can be reviewed and rolled back exactly like one changed by hand.