Commit `109aad5d6b`

109aad5d6bc44031975f68a798e116214994e9d4

parent: b60200227d

Verified · cmc

cmc <hello@cleberg.net> · 2026-09-04 17:27 UTC

Document the menu-bar face

README: three faces built rather than two, a phase-plan entry, the workspace
layout, how to launch the app and add it to Login Items, and the pet's own
state path with why it is not beside the socket.

The design document is corrected to match what was built: state is a
line-based pet.state rather than pet.json, and the Swift side carries two tests
rather than none. A spec that disagrees with the code is worse than no spec.

Closes #19

CHANGELOG.org +14

		@@ -11,6 +11,20 @@ renumbered or removed.
11	11
12	12	* Unreleased
13	13
	14	** Added
	15	- =menubar-pet=, the third face: a menu-bar pet with one life. It ages, neglect
	16	kills it over a week through visible stages, and death is permanent for that
	17	pet. A new one arrives when you come back, and the dead are kept in a
	18	cemetery that is never pruned.
	19	- =pet-life=, the Rust crate behind it. Everything derives from timestamps
	20	rather than accumulating, so death happens at =last_activity + 7 days= and
	21	not when a program noticed — sleep, reboots, daemon restarts and the app not
	22	running change nothing. Birth requires activity, so a fortnight away leaves
	23	one grave rather than a chain of pets born, never fed and dead.
	24	- =History::open_read_only= and =History::last_activity_ms=. Read-only because
	25	the ordinary open prunes, and a face polling every five seconds must not
	26	delete the daemon's history as a side effect of reading it.
	27
14	28	** Fixed
15	29	- The privacy ship-gate's forbidden-symbol scan missed =${BUFFER}=. The braced
16	30	form is ordinary zsh and does not contain the substring =$BUFFER=, so the

README.md +38 −6

		@@ -20,10 +20,10 @@ the others.
20	20	▼ ▼ ▼ ▼ ▼
21	21	terminal-pet garden menubar-pet sonifier wallpaperd
22	22	(TUI) (TUI) (SwiftUI) (AVAudio) (image/window)
23		✅ built ✅ built planned planned planned
	23	✅ built ✅ built ✅ built planned planned
24	24	```
25	25
26		Two faces are built. The other three are the roadmap, not the product —
	26	Three faces are built. The other two are the roadmap, not the product —
27	27	see "Phase plan". Every face draws from the same signal bus: renderers
28	28	never poll hardware, never read the shell, they subscribe over a local Unix
29	29	socket (`$XDG_RUNTIME_DIR/signald.sock`). That buys one privacy boundary to
		@@ -134,12 +134,19 @@ ambient-companions/
134	134	│ ├── terminal-garden/ # first renderer: git aggregates as plots
135	135	│ │ ├── src/lib.rs # signals → plots → render (unit-tested)
136	136	│ │ └── src/main.rs # live subscribe + redraw loop
137		│ └── terminal-pet/ # second renderer: shell + machine + health
138		│ ├── src/lib.rs # signals → PetState → render (unit-tested)
139		│ └── src/main.rs # live subscribe + redraw loop
	137	│ ├── terminal-pet/ # second renderer: shell + machine + health
	138	│ │ ├── src/lib.rs # signals → PetState → render (unit-tested)
	139	│ │ └── src/main.rs # live subscribe + redraw loop
	140	│ └── pet-life/ # the one-life mechanic: ageing, death, cemetery
	141	│ ├── src/lib.rs # pure over timestamps (unit-tested)
	142	│ └── src/main.rs # one-shot: prints state as JSON
140	143	├── shell-hooks/ # zsh hooks: aggregate-only terminal collector
141	144	│ ├── signald-hooks.zsh
142	145	│ └── README.md
	146	├── menubar-pet/ # SwiftPM sibling: the third face
	147	│ ├── Sources/PetKit/ # the pet-life JSON contract (tested)
	148	│ ├── Sources/menubar-pet/ # status item + timer + menu
	149	│ └── scripts/bundle.sh # assembles the .app (LSUIElement)
143	150	└── macos-collector/ # SwiftPM sibling (NOT in the cargo workspace):
144	151	├── Package.swift # macOS IOKit hardware collector (Phase 3)
145	152	├── README.md # the Swift↔Rust wire contract (byte layout)
		@@ -238,7 +245,15 @@ and — for the differential test — `zpty` modules ship with zsh).
238	245	`SignalName::CollectorUp`, one per `Source` — the schema's `v5` addition —
239	246	so a dead collector reaches a face rather than a log file. `terminal-pet`
240	247	renders it: a pet that cannot feel its own hardware looks sick.
241		- Phase 3 renderer — menu-bar permadeath pet. Post-1.0.
	248	- Phase 3 renderer — menu-bar permadeath pet. ✅ Done.
	249	`menubar-pet/` is a sibling SwiftPM package: a status item, a timer and a
	250	menu. One life — it ages, neglect kills it over a week through visible
	251	stages, and death is permanent for that pet. A new one arrives when you come
	252	back, and the old one is remembered in a cemetery that is never pruned.
	253	The mechanic lives in the `pet-life` Rust crate, which the app runs on a
	254	timer; the app decodes no wire and opens no socket, so there is still one
	255	decoder and one privacy boundary. Everything derives from timestamps, so
	256	sleep, reboots and the app not running change nothing.
242	257	- Phase 4 — sonification (SSH-utility first, then continuous). Post-1.0.
243	258	- Phase 5 — live wallpaper (homelab, Path A) + e-ink/poster reuse.
244	259	Post-1.0.
		@@ -275,6 +290,17 @@ terminal-garden # your repos, as plants that grow and wilt
275	290	terminal-pet # the shell and the machine, as a mood
276	291	```
277	292
	293	The third face lives in the menu bar. Launch `menubar-pet.app` from the
	294	Homebrew prefix, and add it under System Settings → General → Login Items to
	295	have it there every day:
	296
	297	```sh
	298	open "$(brew --prefix)/opt/ambient-companions/menubar-pet.app"
	299	```
	300
	301	It has one life. Neglect it for a week — no typing, no commits — and it dies
	302	for good, and the next one starts when you come back.
	303
278	304	`brew services` logs to `$(brew --prefix)/var/log/`. To run the agent by hand
279	305	instead, `packaging/net.krz.signald.plist` is a launchd template; its header
280	306	comment carries the `sed` line that fills in the paths and the `launchctl load`
		@@ -292,6 +318,12 @@ and every renderer, and its test pins the values below;
292	318	\| history db \| `$XDG_RUNTIME_DIR/signald.sqlite` \| `~/.local/state/signald/signald.sqlite` \|
293	319	\| terminal spool \| `$XDG_RUNTIME_DIR/terminal.spool` \| `~/.local/state/signald/terminal.spool` \|
294	320
	321	The menu-bar pet keeps its own state at
	322	`$XDG_DATA_HOME/ambient-companions/pet.state`, else
	323	`~/.local/share/ambient-companions/pet.state`. Deliberately not beside the
	324	socket: those paths follow `$XDG_RUNTIME_DIR` where it is set, which is a tmpfs
	325	wiped every reboot, and a graveyard a reboot can erase is not a graveyard.
	326
295	327	The db and the spool are derived from the socket's directory, so `--socket`
296	328	moves all three together. Override individually with `--db` and `--spool`, and
297	329	the spool from the shell side with `$SIGNALD_SPOOL` — it must match whatever

docs/superpowers/specs/2026-09-04-menubar-pet-design.md +19 −7

		@@ -125,8 +125,14 @@ not mutate the daemon's store.
125	125
126	126	### Persistence
127	127
128		`$XDG_DATA_HOME/ambient-companions/pet.json`, else
129		`~/.local/share/ambient-companions/pet.json`.
	128	`$XDG_DATA_HOME/ambient-companions/pet.state`, else
	129	`~/.local/share/ambient-companions/pet.state`.
	130
	131	Implemented as a line-based format rather than the JSON this design first
	132	called for. Only `pet-life` reads it, so a hand-rolled JSON parser would have
	133	been all risk and no benefit; the terminal spool already stores plain
	134	whitespace-separated records for the same reason. JSON remains the contract
	135	handed to the app, and that direction only needs emitting.
130	136
131	137	Deliberately not under the daemon's state directory. That path derives from
132	138	the socket, which follows `$XDG_RUNTIME_DIR` when set — a tmpfs on systems that
		@@ -187,15 +193,21 @@ are deterministic and instant — no sleeping, no clock mocking.
187	193	- `last_activity_ms` against an in-memory history fixture, including the case
188	194	where retention has pruned everything.
189	195
190		The Swift side stays untested: it is a status item, a timer and a menu, and the
191		logic lives in Rust. What is checked is that the bundle assembles — the `.app`
192		exists and its `Info.plist` carries `LSUIElement`. Claiming UI coverage that
193		does not exist would be worse than saying this plainly.
	196	The Swift side is almost untested: it is a status item, a timer and a menu, and
	197	the logic lives in Rust. Two things are checked. The bundle assembles — the
	198	`.app` exists and its `Info.plist` carries `LSUIElement`. And `PetKit` decodes
	199	the exact bytes `pet-life` pins, including the dead-pet case where `name` is
	200	null, which a plain `String` would reject. That second one departs from this
	201	design deliberately: the Rust-to-Swift contract has drifted twice in this
	202	project and a pinned fixture caught it both times.
	203
	204	The menu bar's actual appearance is not verified by anything, and cannot be
	205	without a human looking at it.
194	206
195	207	## Documentation
196	208
197	209	- README: the faces diagram gains a third built face; a phase-plan entry;
198		workspace layout; launch instructions; the Paths table gains `pet.json` with
	210	workspace layout; launch instructions; the Paths table gains `pet.state` with
199	211	a note on why it is not under the runtime directory.
200	212	- CHANGELOG: an Unreleased entry.
201	213

Commit 109aad5d6b

Commit `109aad5d6b`