souveraine/surfaces/quickshell/patches

patches/

Staged shell changes that are not applied to the tree.

Why this directory exists

~/.config/quickshell/souveraine/*.qml are symlinks into this repo, and quickshell reloads on write. So editing a file here edits the running shell, immediately. When the agent is the one editing, that means an edit can take down the process the agent's own turn is running inside — and a shell that fails to compile does not come back on its own (see 29ec9fe: one bad root type failed the whole qs.services module).

So the rule is: the agent writes patches, the human applies them. The reload happens on a human's beat, when nothing is in flight, with a known-good tree one git checkout away.

Applying

cd ~/Projects/souveraine
git am surfaces/quickshell/patches/0001-....patch
# then reload the shell yourself and watch it come up

Verify before trusting:

cd surfaces/quickshell
./deploy.sh
timeout 40 qs -c souveraine 2>&1 | grep -E "ERROR|Configuration Loaded"

If it does not come up, git reset --hard HEAD~1 and the patch is just a file again.

Discipline

• One patch, one behaviour. Reviewable in a sitting.
• The patch's commit message says what it changes and what it deliberately leaves alone.
• A patch is untested against a running shell unless its notes say otherwise. Say which: verified / reasoned / untested.
• Applied patches get deleted from this directory in the same commit that applies them. This directory is a queue, not an archive — git keeps history.

In the queue

0005 — mount the agent island (TASK-69 + TASK-70)

The four activating edits for the agent-session work. Everything the patch switches on already landed inert in 47ce2d1 / b211842: scripts/agent/agent-sessions.sh, services/AgentSessions.qml, modules/souveraine/island/.

Touches: services/qmldir (register the singleton), modules/common/Config.qml (bar.agentSessions block), modules/ii/bar/UtilButtons.qml (mount), deploy.sh (manifest).

Mounted in UtilButtons rather than BarContent on purpose: UtilButtons is already a Souveraine-owned override, so the island reaches both device bars without forking the 13.8K BarContent twice (ii-base and ii-phone) and carrying that divergence against the pin. The island narrows itself — dot on a cramped bar, pill where there is room — from the same threshold BarContent uses.

Status: verified / reasoned / untested — in that order, per piece.

• Verified: the collector. Run by hand against real data — 0.47 s, valid JSON, exit 0, correctly identifies this very conversation as a live session. Two bugs found and fixed by running it rather than reading it: jq's fromdateiso8601 rejects the fractional seconds all three providers emit (every session read "idle"), and the Codex id was the date prefix, not the uuid.
• Verified: syntax. qmllint exit 0 on all four QML files — using /usr/lib/qt6/bin/qmllint, not /usr/bin/qmllint, which is a Qt5 binary that prints nothing and cannot be trusted as a gate. Proven by feeding it a deliberately broken file first.
• Reasoned: the mount point, the device-form split, the degradation policy.
• Untested: nothing has rendered. No shell has loaded this. qmllint cannot resolve qs.* imports from the repo, so property-level mistakes (a wrong Appearance key, a missing StyledToolTip property) will only appear at load.

Lint the composed tree, not the repo, for a stronger check: ~/.config/quickshell/souveraine/ after deploy.sh.

If it does not come up: git reset --hard HEAD~1. The three inert commits are safe to keep either way — nothing imports them until this patch lands.