Merge pull request 'Revise the deployment model: an agent host and tool VMs' (#90) from deployment-model into main

docs/Development-Plan.md

@@ -309,3 +309,57 @@ All 19 open issues, as of 2026-09-30:
 | #79 ending projects and milestones | **Superseded** | M2.5 |
 | #80 build artifacts in PRs | Milestone | M1.4 |
 | #81 no-change milestones | **Superseded** | M2.5 |
+
+## 6. Implementation notes
+
+Mechanism detail moved out of `docs/Architecture.md` in PR #90, which keeps only
+decisions and their reasons. Keyed by the architecture section each note
+implements; a milestone touching that section uses the note, and changes it here
+if the implementation differs.
+
+- **L1 switching:** the grace period before switching away from an item waiting
+  on the operator defaults to 10 minutes. When the driver chooses the next ready
+  item and the choice fails or is invalid, fall back to the oldest.
+- **L3 revision stamping:** in Matrix, a reply is stamped with the revision whose
+  message had been sent when it arrived; on a Gitea issue, with the latest
+  proposal comment older than the reply.
+- **L5 transport:** the `Transport` interface is send, ask and receive. Intake
+  backoff is exponential, capped at a few minutes.
+- **L6 fitting order:** first shorten old tool results to their first and last
+  lines, then drop the oldest events with a note saying so; never the system
+  prompt, the current plan or the most recent turns. View labels:
+  `[orchestrator]`, `[operator, Matrix]`, `[operator, comment on PR #N]`,
+  `[helper report]`, `[executor]` narration.
+- **L7 rendering:** content is stored as bytes or local paths and uploaded or
+  inlined at render time, never as provider handles. Token budgeting and
+  prompt-cache breakpoints are render-time concerns, never stored. Compaction
+  summaries are first-class events so a model change never inherits opaquely
+  compacted history. A reasoning "session" is a delegation, including one resumed
+  after a crash.
+- **L8 state store:** SQLite in WAL mode, each change committed and fsynced before
+  the loop continues. A delegation's cut is clean when its last event is a
+  completed result, its branch is at the expected commit, its caps are unbreached
+  and external truth matches the log. "Anything else" offers continue, re-plan or
+  abandon.
+- **L9 local models:** request `tool_choice` only of models whose server declares
+  it can enforce it; otherwise the loop enforces the contract (an explicit
+  `finish`, prose treated as a violation). Briefings use the capability profile,
+  never a model name or "weaker model".
+- **L10 vault:** atomic writes are write-then-rename. Obsidian's settings folder
+  (and `.git`, if history is kept) are not synced. A failed write is retried, or
+  recorded and reconciled later.
+- **L12:** secrets reach a command by environment or stdin. Headless agents get an
+  Authelia single-factor exception scoped by source address, group and target.
+  Logs are shipped to the host journal, not kept in containers.
+- **D3 preflight:** a project's needs are read from its files (`Cargo.toml`,
+  `pyproject.toml`, `package.json`) or a declaration in the repository.
+- **D4 publishing:** standard excludes are configured in each clone, and only what
+  the work produced is committed. A push hands the key over stdin to a
+  short-lived `ssh-agent` on the build VM, for that one push.
+- **D7:** test services use ports 18000–18099, so opening access later is a
+  firewall change. The inference host is behind LiteLLM, so it is not a second
+  egress exception.
+- **X4:** the agent host's state dataset is ZFS, snapshotted on a schedule and on
+  each approval. Tool VM templates use Terraform's `bpg/proxmox` provider with
+  cloud-init. Containers restart unless stopped.
+- **X5:** the local inference host is llama-swap on an RTX 4090 machine.