Eight Architectural Decisions for Sovereign Agent

Pain point: twelve users running an agent simultaneously and User A's memory shows up in User B's conversation, two users' tool outputs overwrite the same ./workspace/output.txt, a crash loses half of everyone's in-progress work. These aren't separate bugs — they're one bug: no boundary between what belongs to whom.

Naive approach: a global database, conversations in one table, tool results in another, memory in a third, joined by user_id and session_id. Every feature needs a migration; a bug in a query filter leaks one tenant's data into another's; crash recovery means replaying an event log that has to be perfectly correct.

Decision: every run gets its own directory, sessions/sess_<12hex>/, and everything for that run lives inside it — session.json, workspace/, memory/, ipc/, tickets/, logs/trace.jsonl.

Tradeoff: no cross-session queries without writing code — you can't SELECT across all sessions for a keyword in one statement. In exchange, isolation is physical: User A's data is in a different path, not a different row a bug can leak across.

Pain point: a task fails halfway through, after it's already written files, called a paid API, sent an email. A retry that resets state to planning and reruns doesn't undo any of that — it runs on top of it. The second API call is a duplicate charge.

Naive approach: reset the state field and rerun in place.

Decision: state only ever moves forward — created → planning → executing → halved → complete (or failed/escalated), never backward. A retry is a new session that references the old one, create_session(retries_from=old_session.id).

Tradeoff: more session directories accumulate over time (a housekeeping cost, not a correctness one). In exchange, every session has exactly one history, and you can always tell how many times something was attempted by counting sessions instead of guessing from mutated state.

Pain point: the agent misbehaved in production and your manager asks what it actually did. Your logs say INFO: tool call succeeded — no tool name, no arguments, no result, no order.

Naive approach: regular text logs, written for a human skimming, not for reconstructing a sequence of operations.

Decision: every operation — planner call, executor turn, tool invocation, handoff — writes an append-only ticket to tickets/, with a ticket ID, timestamps, a summary, and (for file-producing operations) a manifest. Tickets are never edited or deleted; a correction is a new ticket.

Tradeoff: more files, more disk. In exchange, "what happened in this session?" always has one answer: read the tickets in order.

Pain point: a colleague asks, a week later, whether workspace/report.md is still the agent's original output or whether someone edited it. The file's modification time proves nothing — touch -d forges it in one command, and an absent-minded editor save bumps it by accident.

Naive approach: trust the modification time.

Decision: when a ticket records that files were produced, it records the SHA-256 hash of each file's content:

ticket.manifest = Manifest(
    files=["workspace/report.md"],
    sha256={"workspace/report.md": "c891f7a2b...  (64 hex chars)"}
)
# Later: ticket.manifest.verify() — True only if content still
# hashes to the recorded value, False if even one byte changed

Tradeoff, stated honestly: this catches accidental edits and disk corruption — it does not catch a determined attacker who rewrites both the file and the manifest on the same disk. That's not cryptographic security, it's an integrity check against accidents. Signed manifests with external keys are a v0.2 concern if the threat model changes.

Pain point: the loop half and the structured half need to talk — when the loop half finishes, it has to tell the structured half "your turn, here's the context." The standard tutorial answer is a message broker: RabbitMQ, Redis, Kafka. Now you're installing and running the broker, wiring its config and credentials, and debugging why it won't connect on a student's laptop.

Naive approach: stand up a message broker for two processes on the same machine.

Decision: the two halves communicate by writing files to a shared directory, using an atomic rename:

tmp = ipc_dir / "handoff_to_structured.json.tmp"
tmp.write_text(json.dumps(payload))
tmp.rename(ipc_dir / "handoff_to_structured.json")  # ← the magic line

rename() is atomic under POSIX — it either fully happens or fully doesn't — and that guarantee holds across ext4, APFS, and NTFS. A reader never observes a half-written file; there's no in-between state to race against.

Tradeoff: reading a file costs roughly 1ms versus roughly 0.1ms for a broker message. Invisible for an agent making an LLM call every few seconds; would matter for high-frequency trading. Atomic rename is the only IPC primitive you need until you've measured a reason otherwise.

Pain point: the executor is mid-write on three related memory facts. It's written two of three when the planner, running in parallel, reads memory to prepare the next subgoal — and sees an incomplete, inconsistent view. Worse: if the executor crashes after two of three writes, the inconsistency is permanent.

Naive approach: lock each file individually. This gives per-file atomicity but not "all three together or none" — and locking multiple files in different orders invites deadlock, which is a worse problem to debug than the one you started with.

Decision: lock at the session level, not the file level — at most one operation touches a given session at a time; different sessions run in parallel freely.

Tradeoff: the planner and executor of the same session can't run concurrently. That's the point, not a bug — the cost is a small amount of latency within one session, and the benefit is that "what's happening right now in this session" always has exactly one answer.

Pain point: the planner is told, explicitly, "respond with ONLY a JSON array, no prose, no markdown fences." It responds with prose, wrapped around JSON, wrapped in markdown fences anyway. json.loads() crashes. This isn't rare or model-specific — in Rod's own sovereign-agent test runs, logged while building this framework rather than pulled from a published benchmark, MiniMax-M2.5 wrapped its JSON in fences roughly 40% of the time, Qwen3 about 15%, GPT-4 about 5%, despite the explicit instruction in every case.

Naive approach: add "no markdown fences" to the prompt and hope. It works for a while, until a model update changes the failure rate and your alerts fire at 2 AM.

Decision: assume the model is going to violate the format, and parse defensively — strip fences if present, fall back to extracting the first [...] block if json.loads still fails, and validate the shape before trusting it.

Tradeoff: more parsing code to maintain, and it never fully eliminates edge cases. In exchange, the pipeline survives the roughly 5-to-40% of responses that don't match the instruction, instead of crashing on them.

Pain point: the code-review scenario is given exactly the task "analyze this Python source, write findings to review.md" — and the LLM calls list_files, calls it again, calls read_file on a path that doesn't exist, and gives up. It never calls the analyzer tool it actually needed. Two hours of adding "do not call list_files" to the prompt didn't stop it — the model has seen millions of training trajectories where "first, see what's on disk" is step one, and no instruction reliably overrides that reflex.

Naive approach: register every available tool "for flexibility" and prompt the model away from the ones you don't want used.

Decision: register tools explicitly, per scenario — the code-reviewer scenario gets exactly three: write_file, complete_task, analyze_workspace_file. No list_files, no read_file. The LLM cannot call a tool that isn't in its registry; the option doesn't exist to be reached for.

After this change, in Rod's own retest of that same code-reviewer scenario: the agent succeeded on the first try, every time.