pub fn drain(paths: &MissionPaths) -> Result<Vec<(PathBuf, ControlCommand)>>Expand description
Drain the inbox: parse every queued .json file, oldest first,
NON-destructively.
Each parsed command is returned together with the file it came from; the caller deletes each file only AFTER the command has been durably applied (e.g. appended to the event log). Deleting up front would lose commands if the process crashed between the drain and the apply — re-processing a file on the next drain is the safe failure mode (duplicates are tolerated downstream).
A file that fails to parse, or fails to authenticate, is renamed to
<name>.bad (with a warning) and skipped so neither a corrupt file nor a
forged one can block the queue. Non-.json files (tmp files, .bad
quarantines) are ignored. Returns the commands in filename (==
chronological) order.
§Trust model
The authority key lives under the operator’s ~/.kranz, never in the
repository, and never inside a session’s working tree. Under an enforced
sandbox it sits in authority_read_deny_paths, so a contained session
cannot read it and therefore cannot produce a sig this function accepts.
Under the default sandbox.enforce = off there is no OS boundary, and the
barrier is the agent CLI’s own deny rules (permissions::AUTHORITY_DENY
denies Read/Edit/Write on ~/.kranz/** and on every mission’s
control/**). That is a weaker barrier than the sandbox and is stated as
such: a session that escapes its own CLI’s permission layer can still read
the key. What no longer works is the one-file forgery this closes, where
merely being able to write inside the repo was enough.