SouveraineOS/docs/tasks/README.md

# SouveraineOS — task files

Single-session-sized work units. Each file is self-contained: the goal, the
context a fresh session needs, the acceptance check, and where it connects.
Pick one, open a session, finish it. Don't pull in neighbours unless they're a
hard prerequisite.

**This index says what is left, not what happened.** History lives in the task
file. Closed work lives in [`archive/`](archive/README.md) with its full record
— nothing is deleted.

## Start here

Four that are cheap relative to what they unblock:

- **46 camera** — the drivers and CAMSS are already in our kernel; blueline's
  DT has no camera node at all. A same-sensor reference (Pocophone F1) sits in
  our own tree. Plausibly one session to a first frame.
- **31 dial contents** — the component and the squeeze that opens it are live;
  its entries are still a hand-written QML list. Wiring them to the verb tables
  is what stops a third capability enumeration existing.
- **19 settings health readout** — three separate tasks (08f, 42, 34) all owe
  their surfacing to this one page.
- **44 fingerprint, piece 1** — the vendor DT node and shim have sat unused in
  `staging/` since 2026-07-07. Wiring them buys a wake source; biometrics is a
  separate, harder question.

## Live — built, one check outstanding

| # | Task | What's left |
|---|------|-------------|
| 53 | [viewtop audit: what it left open](53-viewtop-audit-open.md) | All ten fixed and **packaged onto the phone** (`r74.g6c9614c20471`). The cold boot then exposed a *third*: a lost sessiond race had left the power button dead — discovery waits now. Hardware found two more the gates did not — `delivered` reported true for a withheld contact, and a drift warning that fired on every normal close. What is left needs the PIN. |
| 43 | [viewtop: the Souveraine compositor](43-viewtop-compositor.md) | Runs on the phone. Next lane is the ext-session-lock admission gate. The two-client lock handoff is the thing not to get wrong. |
| 29 | [SouveraineOS Updater](29-souveraine-updater.md) | Ships and installs by `pacman -Syu`. **Read-only on device** until something runs a polkit agent — that is the shell's job. Also owns TASK-42's layer 2. |

## In progress

| # | Task | What's left |
|---|------|-------------|
| 08 | [Device state manager / power profiles](08-device-state-manager.md) | Largest task; sub-divide before starting. (e) lease missing, (f) **surfaced 2026-07-31** — health, evidence and the decision trail render on the Device page; last-seen and grip still absent from `device_state`. (g) confidence gates need a decision before code. |
| 16 | [culver: messenger + contacts](16-culver-messenger-contacts.md) | A/B/D landed. C (contact card) builds and awaits phone acceptance. F is the folded-in TASK-01. |
| 19 | [First-party Settings control center](19-settings-control-center.md) | State-machine + source-health readout **built 2026-07-31**, unverified on glass. 34 and 42's layer 3 still surface here. |
| 31 | [The radial dial](31-radial-dial.md) | Component, gestures and squeeze invocation are live. **Entries are still a list in `DialHost.qml`** — they must come from the verb tables. |
| 30 | [Agent reach: verb tables](30-agent-reach-verb-tables.md) | sessiond has describe + refusal codes + intent. Dock, apps, shell and settings do not. One session per surface. |
| 42 | [Build outcomes are invisible](42-build-outcomes-are-invisible.md) | Layer 1 built (`tools/ci-status.sh` + push hook). Layer 2 is TASK-29's, layer 3 is TASK-19's. Pin-rot prevention unbuilt. |
| 02 | [Lockscreen-as-Rust-system](02-lockscreen-rust-system.md) | sessiond's fallback should render the glance, not a second PIN pad. Stopgap shipped 07-17. |
| 14 | [Overview → phone app grid](14-overview-appgrid.md) | Paged app grid replacing the desktop workspace pane; Auxo-style running cards; unconditional Home path. |

## Blocked or gated

| # | Task | Blocked by |
|---|------|------------|
| 15 | [Idle coordinator](15-idle-coordinator.md) | Freezing `app.slice` would freeze sessiond, shell and secrets. Needs slice separation first (measured 07-25). |
| 28 | [Handover on upgrade](28-upgrade-handover.md) | TASK-27's packaging. Also owns TASK-13's outstanding cold-boot handshake check. |
| 25 | [One repo, all packages](25-one-repo-all-packages.md) | Parked 07-25 — four blockers before `repo-add --sign`. See TASK-27. |
| 40 | [Inference tiering for the sensors](40-inference-tiering-sensors.md) | Nothing — **it is the gate.** P1 applied to sensord/grip/dial; gates the grip raw stream and TASK-31's IPC. Decisions first, then small code. |

## Open

| # | Task | What's left |
|---|------|-------------|
| 60 | [Multitasking is a place, not a transition](60-the-multitasking-view.md) | Written after building the wrong thing. The rail scales the active zone's windows on swipe — a *transition* mistaken for the *destination*. It scales the wrong windows (2 s poll, and the shell has no "focused window" fact at all), and scaling one zone can never show what is backgrounded. `WindowOverview` draws one column of window cards and has no concept of zones; its own header admits the gap. Needs deciding before code: card = window or zone, `ScreencopyView` pictures vs posed real windows, where focus comes from, and whether the poll gets replaced by a push. |
| 59 | [Her face on the glass: a Live2D presence](59-her-face-on-the-glass.md) | **Phase 1 passed on hardware 2026-08-05: ~58 fps, rig verified drawing (`painted_px` 23.6k/24k), 283 MB WebKit RSS.** Scoped from a Live2D board-girl found in a cloned blog. The reference streams its chat over **SSE terminated by `[DONE]`** — the contract souveraine's server already speaks, so the integration is accidentally done. Base layer is **wry**, not the Chromium already on the phone; the first deliverable is a measured frame rate for the Cubism runtime in WebKit on freedreno, and if that fails the task stops there. Replaces ani-avatar's 2.5 GB of sprite states with one rig. Reference rig ships as the working placeholder and gets edited toward Annie — it just stays out of any public repo. Summoned by app launch and/or the radial dial, not always-on. |
| 58 | [Host power: the SMB2 OTG boost](58-host-power-smb2-boost.md) | Host data works; the boost isn't. The SMB2 5 V boost exists in silicon and mainline's `qcom-smbx-charger` never registers it. Investigation first (which tree builds the running kernel, does smb2 touch the boost, does `qcom_pmic_typec` bind pmi8998), then vbus-supply + regulator + typec. Unlocks host-mode power, power-bank mode, and the Pi without a wall wart. |
| 57 | [The Pi dock head](57-pi-dock-head.md) | Phone stays a gadget; the Pi 4 drives the monitor + dock. NCM link is default, Venus encoder is present, compositor capture landed — the unproven seams are `zwlr_screencopy` vs our own capture IPC, and the Pi's own bring-up ("major malfunctions TBD"). Four phases: Pi bring-up, static chain, real capture + udev trigger, input injection. |
| 56 | [The island, and the bar's honest face](56-island-and-the-bars-honest-face.md) | Bar clears a region for sprawling notification banners, agent-controlled (Part A: design questions). Part B is buildable now: drop the LTE suffix, tap-to-cycle the carrier name (Fido → Casey → Fimeg), and a network-type indicator that shows the live connection instead of a wifi glyph that never reflects cellular. |
| 55 | [The hand's verbs: a window action sheet](55-hand-verbs-on-the-glass.md) | **Sheet built and deployed 2026-08-05.** The tap carries its window now (the centroid was being dropped, which is why it could only reach the overview); `Kill` added because `Close` is a request a hung client never reads; `ViewtopControl.qml` is the shell's one path to the scene verbs. Split's chooser, Home-via-compositor, and Move-as-a-mode (`grab`/`drop`) all landed the same day; the three-finger **drag was deleted outright** — it beat the tap to nearly every gesture, and zones now move only when something says so. Left: a real resize handle, widgets on the cleared home zone, and shipping the drag-removal package (viewtop CI 1165 failed in checkout). Also surfaced a runtime-lock paint gap — black until the lockscreen draws, because only boot has a splash→glance→lockscreen chain. |
| 52 | [Atmosphere](52-atmosphere.md) | Attention as a compositor capability — the fifteen-technique vocabulary. Two are **already landed** (`expose` is negative space, `pose` is gravity wells), and `compile_custom_pixel_shader` + `PixelShaderElement` are already in our smithay, so most of the rest needs no new machinery. Build the attention model and one clock **first**; fifteen uncoordinated animators is §1's blind actors in the render path. |
| 50 | [Her hand on the glass](50-agent-hand-on-the-glass.md) | Every scene intent reaches the compositor now **except touch** — so she can move, scale, dim and close a window and cannot press anything inside one. The receiving end is built (`Origin::Agent`, the disjoint slot namespace, the evidence predicate); nothing calls it, so she still reaches touch through uinput, which is the exact conflation `input.rs` exists to prevent. Also owns the inverse mapping `pose` owes the hit test. |
| 51 | [viewtop to daily driver](51-viewtop-to-daily-driver.md) | The punch list between *runs* and *stable*, all of it found by using the phone: windows stack with nothing to tell them apart, screen capture is written and unmerged (so no UI change can be verified), volume buttons are recognised and dropped, and five named holes that are one decision each. |
| 48 | [Shell dies on any reload that owes a lock](48-lock-surface-reload-fatal.md) | Fully diagnosed 07-29, 11 crashes since 07-17. A reload re-requests ext-session-lock while the outgoing instance still holds it → `FATAL: Tried to show lockscreen surfaces without active lock`. **Sync with TASK-43 before touching the lock path.** |
| 47 | [Auto-brightness: anchors, none of it built](47-auto-brightness-anchors.md) | §12 reads as settled and has **zero** code behind its actuation half — no brightness `Action`, no anchors, `grep anchor src/` is empty. The evidence half (lux in, health tracked) is live. |
| 46 | [Camera: **the front camera works**](46-camera-imx363.md) | **First frame captured 2026-07-29** on the running kernel — no reboot, no DT change. Both front IMX355 were already bound; nobody had tried streaming. Recipe + the stride/packing gotchas are in the task. Next: exposure controls, then libcamera. Rear IMX363 DT (`c7784b716`) still unbuilt but no longer the blocker. |
| 44 | [Fingerprint (FPC1020)](44-fingerprint-fpc1020.md) | Piece 1 (wake source / input) is a session — DT + shim already extracted. Piece 2 (biometrics) is a TrustZone question, answer it before scheduling it. |
| 45 | [Haptics (CS40L20)](45-haptics-cs40l20.md) | **First: which chip actually drives the motor** — `pmi8998_haptics` is what the dial's detents use today. Then port `cs40l2x` from Kirisakura; firmware blobs are committed. |
| 41 | [Producers must be attested](41-attested-producers.md) | Design first. Demonstrated live 07-28 — a squeeze and a dial-open both accepted from an SSH shell. |
| 36 | [CHRE nanoapp host for the SLPI](36-chre-nanoapp-host.md) | Three methods to add; method table recovered 07-27. No longer on grip's critical path — wanted for DozeDeep detection and `elmyra_haptics_control`. |
| 34 | [SLPI FastRPC session wedge](34-slpi-bringup-sequencing.md) | Re-diagnose. The real symptom: a DSP session survives its host daemon's death and only a cold boot clears it. **No longer blocks grip.** |
| 03 | [Boot timing: splash → lock](03-boot-timing-splash-to-lock.md) | The EBUSY handoff race is the last timing bug. Splash text killed, holder added. |
| 07 | [WCD9340 mic](07-mic-wcd9340-slim-tx.md) | Functional since 07-20. One defect: the power pin that makes it work. Kernel branch `mic-race-fix`. |
| 09 | [Suspend-resume FTS calibration race](09-suspend-resume-fts.md) | Kernel-side real fix; interim fix shipped. Cold-boot only. |
| 12 | [Face auth as a capability factor](12-gaze-reference-face-auth.md) | Per-target. Phone needs front-camera bring-up — **that is TASK-46's IMX355 half.** |
| 17 | [Keyboard + dictation polish](17-keyboard-stevia-dictation.md) | No word completion (stevia asks hunspell for `en-us`, the dict is `en_US`); no recording indicator on the mic key. The layout half moved to TASK-24. **TTS now exists** (`10.10.20.123:7863`) — the settings field can be filled. |
| 18 | [Selection/highlight action menu](18-selection-menu.md) | Component first, fluid before functional. **Read Aloud is unblocked** — TTS is live. |
| 20 | [Player: video + agent control](20-player-video-agent.md) | Video, snapshot, manifest. Preserve the music path. |
| 21 | [Reboot-to-Android confirmation](21-reboot-android-confirmation.md) | Scoped 07-22. A one-tap irreversible slot flip still sits bare in app search. |
| 23 | [culver locked-notification nudge](23-culver-locked-notification-nudge.md) | Needs `SyncBurst()` + an IdleCoordinator schedule (TASK-15). |
| 24 | [Keyboard layout rethink](24-keyboard-layout-rethink.md) | Redesign from scratch, not more patches. Start from squeekboard `us+apple`. Casey decides where the mic key goes. |
| 27 | [Gitea pipeline audit](27-gitea-pipeline-audit.md) | The fixes. Overlay is not a package; no `primary` branch; poisoned build sysroot. |
| 32 | [Pill and keyboard as owned apps](32-pill-and-osk-as-apps.md) | Both erroneous daily; neither has an owner or a shipping story. |
| 33 | [Battery belongs to the state machine](33-battery-as-device-state.md) | Last raw feed going straight to the glass. The charge ceiling is writable today. |
| 37 | ["Back" as a first-class verb](37-navigation-back-verb.md) | Our `Gestures.qml` is already the compositor half; `can_go_back` is the dial's enabled/reason. |
| 38 | [Pill swipe-to-max swaps the keyboard](38-pill-swipe-osk-swap.md) | Micro. The only route to a terminal keyboard since stevia dropped its layout. |
| 39 | [Audio levels as tracked state](39-audio-levels-as-state.md) | Defaults + roles, **not** a save bug — WirePlumber persistence measured working 07-28. Do not add a second writer. |
| — | [Unify the shell trees](unify-shell-trees-laptop-phone.md) | **DONE 2026-07-31** — verified by md5 across both devices: 918 differing files → 7, all 7 declared in the `ii-phone` overlay, laptop-only **0**, zero stranded. The KEEP list was promoted to repo overrides, not lost. Blocks nothing; archive it. |

## Conventions

- **Repo of record:** `~/Projects/souveraine` (substrate + QML shell),
  `~/Projects/Pixel3Arch` (phone rootfs/overlays/kernel),
  `~/Projects/SouveraineOS/docs` (this tree).
- **Builds:** on archdev (`10.10.20.123`, ssh key `~/.ssh/ani`). Never the
  laptop (93% disk).
- **Phone:** ssh aliases `pixel` / `pixel-root` at `172.16.42.1`. COLD boots
  only — a warm reboot poisons TZ/remoteproc.
- **CI:** `SouveraineOS/tools/ci-status.sh <repo>` reads outcomes from the
  Gitea API. The runner journal is not a status source.
- **Commits:** no Co-Authored-By, no Claude attribution, terse sysadmin prose,
  no caveats in public messages.