git:20260816.4cb676c to git:20260904.05174fb

+ # Infinitus — project rules

+

+ Native macOS menu bar app for the claude-swap engine. Split out of

+ `~/death/claude-swap/swift/CswapBar` on 2026-08-29 with history.

+

+ ## Non-negotiables

+ - **Everything is Swift; the engine is fully isolated.** Every engine

+ touchpoint is a `cswap … --json` subprocess (InfinitusCore/Engines/Cswap/CswapCLI.swift).

+ Never read engine internals (`~/.claude-swap-backup/*`). Reading

+ Claude Code's own files is fine: `~/.claude/settings.json`,

+ `~/.claude/sessions/*.json` (+ `.key`), `~/.claude/projects/*/*.jsonl`.

+ - **The resume-nudge mechanism lives HERE, not in the engine** (user

+ 2026-08-30; upstream never merged PR #250's copy). InfinitusCore

+ ClaudeSessions/Transcript/PeerSocket/PtyHosts/PtyNudge/SessionResume

+ + ResumeService. Never rebuild it engine-side.

+ - **Bundle id is `com.huuloc.infinitus`** (user-approved explicit ask,

+ 2026-09-03; before it `com.huuloc.limitless` from 2026-08-30, before

+ that the CswapBar g2 id). Prefs copy-migrate from the previous id's

+ domain on first launch (AppModel.migrateLegacyDefaults). App Support

+ is `Infinitus/` (copy-migrated from `Limitless/`, which came from

+ `CswapBar/`; legacy dirs left for rollback). The local checkout may

+ still live at `~/death/limitless`. Notification Center and login-item

+ grants key on the id and must be re-granted once under it; keychain

+ items prompt once. Never change the id casually again — the

+ 2026-08-29 casual change cost a day of ControlCenter-ban debugging.

+ - **Push nothing to any remote** unless explicitly asked. Commit locally.

+ - **main takes commits only through pull requests** (GitHub ruleset

+ "main via pull requests", user 2026-09-04): no direct push, no

+ force-push, no deletion; 0 required approvals (solo repo). Work on a

+ branch, `gh pr create`, merge with `gh pr merge --squash` (or

+ `--merge` when the branch history matters) once tests pass.

+ - **Every commit carries `Co-Authored-By: Claude Code

+ <noreply@anthropic.com>`** (user 2026-09-04: "some commits still

+ missing Claude in author"). `tools/githooks/prepare-commit-msg`

+ appends it; each clone/worktree owner runs `git config core.hooksPath

+ tools/githooks` once (shared across worktrees of one clone). Subagent

+ briefs still say it explicitly.

+ - Secrets (webhook URLs, bot tokens) travel over stdin, never argv; shown

+ masked only. Usage-cost figures are estimates, never billing truth.

+ - Surgical changes; match existing style; no speculative abstractions.

+ - **Account policy lives in the engines** (user 2026-09-03). Auto-swap,

+ pick-first, ordering come from each engine's own knobs (cswap

+ `autoswitch.*`, the proxy's priority); the app only sets those and

+ never runs a second policy on top (the app-side auto-order writer was

+ removed for this). Missing knob → upstream PR, never a fork.

+ - **Keep performance in check with every feature** (user 2026-09-03):

+ idle CPU with the pop-out open must stay near 0% (`infinitusctl perf`

+ twice, 15s apart; `tools/e2e.sh` gates it in CI). Any continuous

+ motion goes through Core Animation (`LayerEffect`), never a

+ TimelineView / repeatForever `.animation` — see the hard-won fact.

+

+ ## Hard-won facts

+ - NSPopover measures content once; wholesale content-shape swaps must go

+ through `withAnimation` so it re-measures live. Never close/reopen.

+ - macOS ignores Dynamic Type — popup scaling is `PopupScale`

+ (fixedSize → measure → scaleEffect + matching frame). Measuring without

+ `fixedSize` feeds the scaled width back in and runs away ×scale.

+ - The pop-out window must NOT let NSHostingView size it (crash on

+ unbounded ideal width); PinnedRoot reports its fixedSize geometry and

+ `fitPinned` applies it.

+ - Never `cp` over the RUNNING unbundled binary — overwriting a signed

+ executable in place gets the process killed on its next page-in

+ (the dev instance "mysteriously died" 2026-08-30). pkill first.

+ - macOS 26 ControlCenter can stop adopting new bundled apps' status items

+ after rapid relaunch churn — only a logout clears it; `run-unbundled.sh`

+ is the workaround. Don't run the dev loop's kill/reopen cycle for hours.

+ - NSPopover windows refuse CABackdropLayer at every level (renders a

+ black slab; probed 2026-08-30) — the anchored popup is therefore a

+ borderless non-activating NSPanel. CABackdropLayer + CAFilter

+ gaussianBlur in a plain window is the only tunable-blur glass.

+ - NSGlassEffectView does NOT deactivate when its window resigns key —

+ the "goes solid unfocused" repro was the probe window being occluded.

+ Never reintroduce a focus-swap around it; glass runs in all states.

+ - usernoted refuses dev-cert builds without a provisioning profile;

+ notifications fall back to osascript (working mode, not an error).

+ - SwiftUI Grid: spanning cells span the widest row's real column count;

+ placeholders need `.frame(maxWidth: .infinity)` +

+ `.gridCellUnsizedAxes(.horizontal)`.

+ - macOS 26: a VStack of mixed text+gauge rows under-reports its ideal

+ HEIGHT under two-axis fixedSize (last row clips to slivers) — give

+ every such row its own `.fixedSize()`.

+ - A GridRow can't wear a modifier (collapses to one cell), but a Group

+ INSIDE it distributes the modifier to every cell — that's how the

+ rows intro slides a whole grid row.

+ - Multi-engine (#8): every engine is an `AccountEngine` yielding

+ `EngineFleet`s; the popup stacks one `FleetState` per fleet and

+ `AppModel` is only a FleetModel FACADE over the primary Claude fleet.

+ Gate UI on `capabilities`, never on engine identity.

+ - The CLIProxyAPI key lives in the keychain (`com.huuloc.infinitus.cliproxy`,

+ account = base URL). Unsigned debug binaries trip an ACL prompt on

+ every rebuild — reads skip UI, and the dev loop codesigns the debug

+ binary with the Apple Development identity so the grant sticks.

+ - Every SwiftUI-driven frame (TimelineView tick, repeatForever

+ `.animation`) commits a CA transaction: display-list diff, AppKit

+ drag-region + tracking-area rebuild, a WindowServer fence — ~7 ms

+ each, the same whether one leaf or the whole grid changed. Five RPG

+ effects at 20 fps idled the pop-out at 43% CPU (#18, 2026-09-03);

+ as CAAnimations on a LayerEffect host they idle at 0.4%, burn

+ overlays included (CAEmitterLayer sparks; a `.line` emitter's

+ emissionLongitude is a quarter turn off a `.point` one's: 0 = up).

+ A per-second `.contentTransition(.numericText)` grows the CG glyph

+ cache ~2 MB/min for as long as it ticks (macOS 26) — never on a

+ countdown; the e2e gate checks idle heap growth via `perf.heapBytes`.

+ An ordered-out window keeps its SwiftUI content ticking (the wall's

+ 15 fps TimelineView cost ~8% idle after every visit): detach the

+ hosting controller on close, and reuse the NSWindow — a closed

+ borderless one lingers in AppKit's list regardless.

+ - Dev instances: sign the debug binary `--identifier

+ com.huuloc.infinitus` (tools/e2e.sh does) or the keychain ACL prompt

+ blocks AppModel.init forever (no socket, SecurityAgent spawns).

+ `swift build --target X` may not relink — use `--product`, ONE per

+ invocation: with two `--product` flags SwiftPM builds only the last

+ (CI's e2e ran a stale app binary for a day, 2026-09-03).

+ - Two Claude sessions work this repo (since 2026-09-02 evening): the

+ second one lives in its OWN worktree `../limitless-e2` on branch `e2`

+ (one `cd` there; separate `.build`). Main (`~/death/limitless`) is

+ merge-only and owned by the first session, which also owns

+ `Infinitus.app` rebuild/relaunch (always from a clean worktree at a

+ main sha) and the PRs. Ship flow: e2 commits → "merge e2 at <sha>" →

+ push `e2` → `gh pr create --base main --head e2` → tests → `gh pr

+ merge --merge` → `git pull` main → rebuild → relaunch. Never edit the

+ other session's tree; in either tree stage by explicit path.

+

+ ## Release

+ - Every release updates **site/** (infinitus.run) and the **GitHub

+ README** with the new features so app, site and README stay in sync

+ (user 2026-09-03). Do it in the release commit, not after.

+

+ - Any dev/smoke instance of the app (debug binary, `-mock_mode`, a

+ second bundle) MUST run with `INFINITUS_CONTROL_SOCKET=/tmp/<short>.sock`

+ — without it, ControlServer.start() unlinks the real app's control

+ socket and `infinitusctl`/the phone get "connection refused" until

+ the bundle relaunches (bit us 2026-09-03 08:21). Short path: unix

+ sockets cap at ~104 bytes, so never the scratchpad dir.

+

+ ## Build / run / test

+ `./make-app.sh && open Infinitus.app` · `swift test` · `./dev.sh` (entr)

+ · `./run-unbundled.sh` (menu bar wedge workaround).