task 72: plan owned agent surface

docs/tasks/72-surfacing-pane-tool-primitives.md

@@ -1,8 +1,10 @@
 # TASK 72 — the surfacing pane: tool primitives, status, and an honest bottom bar
 
-**Status:** first shell patch queued, 2026-08-11; not applied or run. Patch
-`surfaces/quickshell/patches/0003-typed-chat-segments-tool-cards.patch` follows
-the queued think-fence stopgap (0002) and remains for Casey to apply and reload.
+**Status:** interim bridge composed and QuickShell restarted, 2026-08-11.
+Patches 0002 and 0003 are applied on `souveraine/primary`; 0004 fixes their
+QML compatibility. The running instance logged `Configuration Loaded`. This
+proves composition and startup only: a live agent turn containing a tool call
+has not yet exercised the new cards.
 **Source:** Casey, this morning. **Adjacent:** TASK-70 (the island — same
 renderer, different surface), TASK-65 (subconscious stall wedges the surface),
 TASK-59 (her face).
@@ -55,13 +57,84 @@ markdown blob. Once segments are first-class:
 Patch 0002 is a **correct stopgap on the wrong layer**. Do not treat it as the
 fix; treat it as the thing that keeps the surface readable until the layer moves.
 
-**Queued implementation (reasoned, not live-tested):** patch 0003 carries the
-wire's assistant/reasoning/tool-call/tool-return kinds in a per-message segment
-list. The sidebar dispatches those segments directly; tool returns bind to calls
-by wire id (with a fallback for old id-less frames), and the new cards give bash,
-file, sensor, and memory calls compact summaries, folded output, and explicit
-running/done/failed state. It applies cleanly after 0002 in a disposable
-worktree. The composed shell has not been touched.
+## Current bridge — useful now, deliberately not the destination
+
+Patch 0003 carries the wire's assistant/reasoning/tool-call/tool-return kinds
+in a per-message segment list. The sidebar dispatches those segments directly;
+tool returns bind to calls by wire id (with a fallback for old id-less frames),
+and the new cards give bash, file, sensor, and memory calls compact summaries,
+folded output, and explicit running/done/failed state. Patch 0004 removes
+object-spread expressions which the installed QML runtime rejected at load.
+
+That bridge is live because Casey needed the panel usable before a larger
+rewrite. It is architectural debt, not permission to keep building there:
+0003 modifies `ii-base`, while `surfaces/quickshell/II-BASE.md` and the shell
+decision say Souveraine work belongs in original modules, not in the ii vendor
+snapshot. No further agent-surface feature should land in `ii-base`.
+
+## Owned destination — a reloadable agent-surface package
+
+**Reasoned design; implement and prove it in this order.** The chat surface
+becomes an original Souveraine module, for example
+`surfaces/quickshell/modules/souveraine/agent/`, with a small, legible split:
+
+- `AgentPaneHost` owns lifecycle and the stable pane boundary.
+- `AgentChat` and `AgentMessage` render typed segments only.
+- `ThinkingCard`, `ToolCallCard`, `PasteIndicator`, and `InProgressIndicator`
+  are explicit primitives; tool cards own their collapsed state and status.
+- `services/Ai.qml` remains the data/substrate boundary. It preserves wire
+  segment type and call identity, but it does not choose pixels. The old flat
+  `content` projection exists only for compatibility consumers such as copy and
+  speech; no renderer may re-parse it.
+
+This is the path away from ii: first host the owned module inside the existing
+Souveraine compose, then replace the borrowed `AiChat` host, then remove this
+bridge and its ii-base changes. TASK-70 remains a separate surface which may
+reuse the renderer but does not own the sidebar's lifecycle.
+
+### Pane-local update and recovery
+
+The desired operation is *not* "edit a live QML file and hope QuickShell
+notices." An installed candidate version loads beside the active pane. Only
+after its ready signal and basic data binding succeed does `AgentPaneHost` swap
+the visible loader; a failed candidate leaves the previous pane intact. Expose
+that as a narrow IPC action such as `agentPane.reload`, with status and the
+active version visible in the host. The first implementation must be proven in
+an isolated config before it is offered as a daily control. This is reasoned,
+not yet hardware-proven.
+
+### Package boundary
+
+The Rust substrate package stays a substrate package. Add a surface package
+family which installs immutable, versioned QML/assets under
+`/usr/share/souveraine/surfaces/`, with a small common package and explicit
+desktop/phone profile packages as needed. A user-level launcher starts
+QuickShell by explicit `qs --path`, rather than treating a mutable
+`~/.config/quickshell` compose as the product. Package upgrade stages a new
+candidate; it does **not** silently restart, swap, or claim the UI adopted it.
+Activation is explicit, reversible, and leaves the last working candidate
+available.
+
+The existing `deploy.sh` composer is a development bridge: it copies `ii-base`
+to `~/.config/quickshell/ii`, symlinks Souveraine-owned manifest files into
+`~/.config/quickshell/souveraine`, and does not restart QuickShell. It is not a
+surface package manager.
+
+### Delivery sequence and proof
+
+1. Transcribe the TUI's tool semantics into the owned module, including the
+   paste flag and honest in-progress state; exercise one real tool turn of each
+   major kind.
+2. Replace the sidebar's borrowed chat host without changing the wire/data
+   boundary; delete the 0003 ii-base modifications once parity is proven.
+3. Add the candidate pane loader and prove a bad candidate leaves the old pane
+   drawn and usable.
+4. Package the owned assets, build them in Gitea Actions, and prove package
+   install plus explicit activation on the target display.
+
+Label the evidence separately at each step: source committed, package built,
+package installed, candidate activated, and real tool round rendered. Do not
+call the last item complete from a clean QML startup alone.
 
 ## Candidate tabs (Casey)
 
@@ -88,9 +161,15 @@ worktree. The composed shell has not been touched.
 
 ## Discipline (non-negotiable, learned the hard way)
 
-The composed config at `~/.config/quickshell/souveraine` is **symlinks into the
-repo**, and quickshell reloads on write — an agent edit lands live in the
-process the agent is thinking inside. Work goes through
-`surfaces/quickshell/patches/`: **the agent stages, the human applies.** Load
-test before trusting: `deploy.sh`, then `timeout 40 qs -c souveraine`, grep
-ERROR, confirm `Configuration Loaded`.
+Do not edit the composed config. Souveraine-owned manifest files there are
+symlinks into the repo, while `ii-base` is a copied vendor snapshot; both are
+wrong places to develop. Stage changes in a detached worktree and keep patch
+queue order explicit. The 2026-08-11 deployment was a Casey-authorised bridge
+deployment, not a new normal.
+
+There is no laptop build claim here. Gitea Actions owns reproducible builds.
+For a deliberate compose/restart, inspect the exact QuickShell instance, run
+`deploy.sh`, restart only that instance, inspect its fresh log for `ERROR`, and
+require `Configuration Loaded`. Never use an empty search result as proof that
+the source is absent; resolve symlinks and use `grep -R` where the composed
+tree is involved.