Open Commons ObservatoryEnglish·Русский

Понятия и решения

Понятия проекта и принятые решения — с тем, что было отвергнуто.

One baseline per device

Every check that ever passed is held to; a check outside a run's scope is not asked, rather than kept in a second baseline.

The conveyor refuses what cannot work

Each mistake that cost a try becomes a refusal with a reason: a kernel that is not an EFI program, a listening test without the word that the microphone is placed.

devlab kernel install refuses a kernel that is not an EFI executable.

The bootloader starts EFI programs only; a gzip kernel was lost before it could log a line.

Отвергнуто: Documenting which file to pass.

2026-11-11

devlab health waits until the phone has been up 90 seconds before checking, saying so once.

Every job slept before a health check by hand (7 times); a check read too early fails for the wrong reason.

Отвергнуто: A fixed sleep in every script; checking at once and retrying failures.

2026-11-11

A listening test runs only with --placed, the word that the microphone is by the phone.

The first results came from a microphone being worn.

Отвергнуто: Un-naming the microphone's file as the safeguard: a trick only its author remembers.

2026-11-11

devlab kernel try waits for a new boot id and reports the outcome itself, judged from the running release, the entry's counter and the timeout log.

Booting a test kernel and reading what happened was the heaviest manual work (9 times, 54 effort-minutes), and guessing at it cost three reboots.

Отвергнуто: Waiting for the phone to go down and then up (it misfired twice: the try schedules its reboot); leaving the reading to a person.

2026-11-11

lpoco-bringup image pack/info/unpack/check use abootimg-oxide for the v0 header (parse and write); our code adds the v0 id (SHA-1 over kernel, ramdisk, second with sizes) and the page padding. mkbootimg stays the oracle: the test bringup-pack-matches-mkbootimg builds the same image with it (plain header and with os words) and compares bytes; it skips as 'not measured: no mkbootimg'. The header facts come from device.toml [boot] (deviceinfo words), read by the bringup library (devlab's reader ignores the table until it needs it). check prints one ok/FAIL/not-measured line per fact and exits 1 on a miss; info and unpack.boot.toml print the header as a [boot] table (offsets from base 0), so unpack then pack round-trips.

The research measured the crate's header bytes equal to mkbootimg's; the two gaps are small and proven by test. Native Rust pack means no Python or android-tools needed at run time, and the oracle test guards it.

Отвергнуто: Wrapping mkbootimg for pack: only needed if the crate were not byte-exact, and it would put a python tool in every run. Writing the 1632-byte header by hand: the crate already does it and also parses v1-v4 for later items.

2026-11-17

WHERE: one place for tools that bring a device up - linux-phone-oco/lab-tools, which already says it holds "tools for bringing up and testing Linux phones, not tied to one device". A new workspace member `bringup` (a library with a binary), beside devlab, health and tone. Not a new repository (lab-tools has the CI, the release-plz and the package conveyor; the device template already points there), and not devlab subcommands (devlab is the phone-facing tool - fastboot, ssh, keeper lease, MCP, tokio and rmcp - and building an image needs no phone, no lease and no network; the boundary stays: bringup makes files on the host, devlab puts them on the phone). devlab may call bringup's library later (kernel try building its own image); it does not grow image code. NAME AND ONE ROOF (the author: all tools of lpoco under one roof): one command, `lpoco`, with the family as subcommands - `lpoco bringup ...`, `lpoco health ...`, `lpoco lab ...` (today's devlab), `lpoco tone ...`, `lpoco mcp` - as git and cargo do: `lpoco` is a small dispatcher (argenv) that finds the program lpoco-NAME beside itself or on PATH and runs it, so every tool is still its own crate and binary in lab-tools (lpoco-bringup, lpoco-health, lpoco-lab, lpoco-tone) and can be run alone. One roof buys one install, one pin (device.toml [tools] lpoco = "X.Y" names the whole family), one completion and man page, one MCP server (`lpoco mcp`, the tools of every subcommand under their subcommand's name), one place agents look (`lpoco list`). The family is released together: one version, and the dispatcher stops with a line naming both versions when a subcommand's version differs from its own (nothing half-upgraded runs). The phone's lpoco-health stays its own small static binary - the dispatcher is not shipped there and the phone carries none of devlab's tokio or rmcp. Old names stay as other names for a while - devlab = lpoco lab, devlab-health, the MCP tool names - so the ~450 references are swept over time and nothing breaks at once (as lpoco-health kept devlab-health). The new tool is born under the roof: the crate and binary are lpoco-bringup from its first commit, the dispatcher first or in the same change. The plain word is the method's own (bring-up-a-part); no acronym. SHAPE: Rust, command line declared once with argenv (as lpoco-health), wrapping and not reinventing: mkbootimg, unpack_bootimg and avbtool (android-tools, found on PATH, the oracles) for what only they do well - the AVB footer first - and crates for the rest (a header layer such as abootimg-oxide if its v0 write is byte-exact; cpio, flate2, lz4_flex, xz for the initramfs and kernel container; dtoolkit or fdt to read the appended dtb). Our own code is the part nobody has: the checks against the device's expected fields, the swap of one part against a control image, and the reproducible initramfs. The packer is proven against mkbootimg byte for byte by test, so a later Rust writer replaces the wrapped call without changing a result. FIRST COMMANDS: bringup image info|unpack|pack|swap|check (header v0 first; the swap takes a control image and one part - ramdisk, kernel, dtb, cmdline or a header field - and says what differs; check counts the fields the device's [boot] expects and stops the job on a miss); bringup initramfs build (a newc cpio with fixed times, a template variable for the USB-gadget address instead of the sed rewrite, xz or gzip by the device); bringup bisect FILE (a declared series of swaps against stock). AVB hash footer with algorithm NONE and the control's size and properties is part of pack and swap. Not first: vendor_boot and header v3/v4 (read-only at first), a native AVB, QEMU selftest. STAYS SHELL, stupid simple: build-kernel (a make call with the config) and build-busybox are a few lines each over a strong tool (make); they stay in the device repository, as thin as they are, shellchecked. rust-script is for one-off analysis of a boot image or a log (decision 2026-11-17-health-checks-shell-and-rust); a rust-script that is used a second time becomes a bringup subcommand. tests/host/gadget-up.sh, a host-side check that the phone's gadget answers, belongs with devlab (it is about the phone) and is a later item. HOW DEVICES CALL IT: the device's facts move out of the scripts into device.toml, a [boot] table in pmOS deviceinfo's words (header_version, base, kernel_offset, ramdisk_offset, tags_offset, second_offset, pagesize, os_version, os_patch_level, cmdline, dtb = appended, kernel_compression, ramdisk_compression, avb_footer, partition_size). The device's build scripts become one line each (bringup image pack, bringup initramfs build, bringup bisect), then go away where one command says it; the device template names bringup in its AGENTS.md and ships the [boot] table with every value marked CHANGE, like [flash] and [fastboot]. BUILD: queued as backlog for a builder with the first failing test (bringup-image-v0, proof bringup-pack-matches-mkbootimg); this session builds nothing. HOW A DEVICE USES, EXTENDS, SENDS BACK AND PULLS (the author's rule: side by side, no rebase each time): the tool is followed by a version pin, never copied. Pin: device.toml [tools] lpoco = "X.Y", the family's one pin; lpoco refuses a different version with a clear line (an explicit stop), and installs from a released host binary or cargo install --git --tag bringup-vX.Y.Z (bringup-release settles which is simpler). Extension, never an edit of the tool, in three levels: data ([boot] and the files it names), hooks (executables the manifest names for a step; shell where stupid simple; a nonzero exit stops the job), logic (a rust-script file or small crate in the device repository that depends on bringup's library at the pinned tag). The device's parts are its own files, so a pin bump touches none of them. Sending back: a generic improvement is a pull request to lab-tools from the device's branch, recorded in the device base as an upstream item (form patch, ready on the author's word) against a lab-tools upstream row seeded in device-template beside idealkb and device-template. Pulling in: the weekly pin bump (idealkb's update-pins learns the [tools] line), one pull request per source, the device's CI answering. Same rule for devlab and lpoco-health: lab-tools tools are followed by pin. The files that go with the tool (the [boot] skeleton, hook examples, an initramfs skeleton) travel in device-template's slice by follow.sh as today. RHIZOID: it carries two cases and lacks three things, none worked around. Its cases: a slice (slice-consumption, the template files) and a cutting (a device that must patch bringup itself before upstream takes it: a cutting of lab-tools, tracking branch pristine, patch branch merged, consumed as a cargo git dependency with [patch]; rare, because the three levels cover most). What it lacks, filed on its own backlog (git-rhizoid.github.io PR 28): cutting-as-cargo-dependency, followers-one-pin-bump, send-back-writes-the-upstream-item. Until it has them: follow.sh and update-pins for slices, a plain fork and a [patch] line for the rare cutting.

Walleye wrote eight shell scripts (~520 lines) in a day, the bisect one alone 87 lines of sed, od and grep over unpack_bootimg's output, and surya's was done by hand: every new device would write them again, and their checks (a count that exits 1) are exactly what a typed tool does better with tests. The author's rule is shell only where stupid simple and a strong tool stands behind it; these scripts are logic (header fields, offsets, a dtb found by magic bytes, a footer copied from a control), so they become Rust, and the two that are only make calls stay shell. Earlier decisions already point here: backlog rust-toolset (one Rust toolset in lab-tools, surya is the test subject and not the mould) and 2026-11-17-health-checks-shell-and-rust (Rust for logic, shell for readings, rust-script for one-offs). The landscape (research bringup-tools-landscape) shows nothing covers the job - pmbootstrap does not build the image and is ~24k lines of Python, magiskboot is GPL and aimed at rooting, abootimg-oxide has the header but no checks, no swap, no footer - so wrapping the oracles and the crates is cheaper and safer than writing a packer first. The name: the author offered linux-phone-oco-bootstrap-helpers (lp-oco-bh); "bootstrap" is pmbootstrap's word and the compiler world's, and means something else to every reader; "helpers" says nothing; five words and an unpronounceable shorthand do not suit a command; lab-tools' names are one plain word each. A tool's logic is compiled and versioned, so the follow problem for it is a pin, not files laid into the follower; keeping the device's own parts in its own repository beside the tool makes the rebase question vanish rather than solved (research bringup-home-follow-and-rhizoid). It reuses the one pin-and-follow mechanism decided in idealkb's chain-follow-by-slice and the upstream-item flow already used, and keeps rhizoid for what it was made for. The name was weighed again as a family (research bringup-family-names): git-*, cargo-* and pm* (pmbootstrap, pmaports) are prefixes of tools others install, and a prefix is what makes them findable by completion; a bare plain word is safe only inside one machine. The author asked for a distinctive family.

Отвергнуто: A new repository (a second CI, release and package conveyor for one crate; lab-tools is already where the device template sends people). Devlab subcommands (devlab would take build-time crates and a second job, and its 5.4k lines already carry the phone's whole life; an offline tool should not need a phone manifest's fastboot section to run - it reads only [boot]). Growing the shell scripts into a shared shell library (the pmbootstrap path: more shell, hand-parsed text, no tests, nothing a second device can share by name). Python (refused). Porting mkbootimg and avbtool into Rust first (cost before need; the byte-for-byte test lets it come later). Taking magiskboot or pmbootstrap as a dependency (GPL and rooting-aimed; Python sprawl). Names: linux-phone-oco-bootstrap-helpers and lp-oco-bh (bootstrap means pmbootstrap or a compiler's; helpers has no meaning; too long and unpronounceable), bootstrap, bootkit (a malware word), bootimg (a crate's name and only half the job), imgtool (mcuboot's), mkboot, forge, kit. Shorthand: none - bringup is the short form. For the home: tools as a slice of files followed into each device repository (compiled logic copied everywhere; every device edit becomes a rebase); every device a cutting (fork) of lab-tools (drags the whole workspace into each device repository, and a device cannot follow two forks); git subtree or submodule (a prefix and a second checkout the device never needs); a plugin loader that runs device code inside the tool (a second language boundary; the hooks and the library cover it); waiting for rhizoid to be implemented (its CLI is stubbed and its consumption side open; the need is now). Family question: no prefix at all (bringup, devlab, tone: three plain words, but tone and bringup are ordinary words that collide on crates.io and on other people's PATH, and nothing says whose they are); a prefix on everything now (renaming devlab touches ~450 files, the installed path and the MCP tool names, and the name lpoco-devlab stutters; renaming tone buys nothing while it is not installed); a suffix family like systemd's *ctl (lpoco-ctl names nothing); a short prefix lp- (lp is the printer). Words: lpoco-bootstrap, lpoco-bh, lpoco-bootkit, lpoco-images (see the first list), and a short alias `bringup` beside lpoco-bringup (two names for one tool, which is what the family is meant to end). One roof, the forms weighed (research bringup-one-roof): prefix only, lpoco-* each on its own, devlab and tone deferred (the 2026-11-17 first amendment: findable by completion, but no one install, one pin, one MCP server or one place to look); all tools renamed lpoco-* now and released together with no dispatcher (the same missing roof, and a pin per tool); one fat binary holding every tool (the phone's lpoco-health must stay small and static - it would carry devlab's tokio and rmcp - and a crate per tool is what lets each be tested and run alone; a feature-gated single binary can come later if the dispatcher proves too thin); a hard rename with no old names (breaks ~450 references and the MCP names in one change).

2026-11-17

Install lpoco and lpoco-bringup on a lab host with cargo install --locked --git URL --tag lpoco-vX.Y.Z lpoco, and --tag lpoco-bringup-vX.Y.Z lpoco-bringup (README, Install on a lab host). release-plz tags every package of a release on the one release commit, so the tags agree and the versions match.

Proof bringup-installs-from-tag (lpoco/tests/install_from_tag.rs): into a clean root, from GitHub's tags, lpoco --version is the tag's version, lpoco list shows bringup, and bringup refuses a wrong pin (exit 2). It passed in CI. Cargo already resolves the tag, the lockfile and the toolchain; nothing new to maintain. Found on the way: tags of 0.1.7 sat on different commits, so only a version released after the pin (0.2.0) installs a family that works; and the release made the old wrong pin 0.2 right, so the wrong-pin tests now use 99.0.

Отвергнуто: Host binaries as release assets (x86_64 linux, checksum): a build job, a checksum step and a download script for a lab that already has cargo; revisit when a host without a toolchain needs it. One shared family tag: the conveyor reads lpoco-health-v*, see 2026-11-17-lpoco-family-version.

2026-11-17

[boot.hooks] parts = EXE (relative to the manifest) is called with the kernel and ramdisk paths in a scratch folder; what they hold afterwards is packed. A missing or non-zero hook stops the job (exit 2, nothing written). The pin [tools] lpoco = "X.Y" is a version prefix checked before any verb that finds a manifest.

Test-first: bringup-refuses-wrong-pin and hook tests in bringup/tests/pin_and_hooks.rs; the ramdisk is the part device repositories change.

Отвергнуто: Hooks editing the user's own files in place: a failed hook would leave them changed. A hook per image field: no device asked for one yet. Skipping the rust-script test when rust-script is absent: a skipped check is not a check; CI installs it instead.

2026-11-17

devlab-health reaches phones as an Alpine package: release-plz tags devlab-health-vX.Y.Z, and the package conveyor's alpine.yml builds it from the tag's APKBUILD, signs it with lab-tools' own RSA key, verifies it and publishes an apk repository on lab-tools' pages for postmarketOS v26.06 (Alpine 3.24), then installs it in a clean container.

One way for code to reach a phone, measured, instead of devlab copying files: the phone updates the suite with the rest of its system, and any postmarketOS phone can take it without the lab. The conveyor already did this for pacman; the Alpine path was its open cv-apk.

Отвергнуто: Keeping devlab suite put as the only way (files no package manager knows, nothing for a phone outside the lab); building in lab-tools' own CI (copying what the conveyor keeps once); a key shared across the commons (keys stay per project for now); publishing as release assets (apk needs an index under a stable path).

2026-11-17

A change devlab makes to the phone ends with its health: after a reboot (phone reboot, kernel try) devlab waits for the report that boot writes by itself, rather than running the suite again; after a change without a reboot (provision) it runs the suite now. Either way the report is brought to the lab and an unhealthy phone fails the command.

Nobody has to remember to check; and waiting for the boot's own report measures exactly what every boot of the phone measures - the lab adds no second way of checking.

Отвергнуто: Running the suite from the lab after each reboot (two runs per boot, and the lab's run would be the one that differs from an unattended boot); leaving the health check as a separate step to remember.

2026-11-17

device.toml [fastboot] serial (as fastboot devices lists it) and writes (default false). Every fastboot call devlab makes passes -s SERIAL; devlab flash refuses a phone without writes = true; devlab fastboot offers only reading, boot from memory and reboot - no flash, erase or set_active verb. The guard refuses raw fastboot other than devices, getvar and help.

A second phone (google-walleye) sits in fastboot on the lab beside surya: devlab flash checked any phone in fastboot and flashed without -s, so a surya flash would have written to walleye. walleye's slots must stay as they are until a recorded decision (walleye-fastboot-first); a default of no writing makes that the phone's state, not a rule to remember.

Отвергнуто: writes defaulting to true (a manifest that forgets the line would let walleye be flashed); a flash that takes the only phone in fastboot when there is one (true today, false the moment two are); a separate fastboot tool beside devlab (the lease, hold and guard are devlab's, one way per phone); writing surya's serial from its soc0 serial (3693150539 = dc21014b) unread from fastboot: not known yet is said as not known, so surya's flash refuses until a keeper reads it.

2026-11-17

devlab files the phone's reports into the picture through tad (one tad sql statement per run: its rows read from the report, its counts from those rows; tad keeps it only if every rule holds, then canonical form and the rendered pages), and devlab watch, after every boot, waits for the phone's own report, says its verdict on the board, and gathers with --land: in devlab's own clones of the lab and the picture, each landed through land, signed devlab. The face is drawn again by the picture's CI on that landing.

The author, 2026-11-17: tad is the open database shared by the whole linux-phone project; devlab reports the suites' results into it by itself and the pages reflect them - not an agent doing it by hand each time. devlab's own clones keep its landings out of the clones people and agents work in (two hands in one clone once merged each other's changes).

Отвергнуто: devlab appending JSON lines itself (rows tad never checked); the watch running the lab-side checks over SSH (a second way of measuring beside the phone's own); landing from ~/Projects (collides with work in progress there).

2026-11-17

devlab gather now brings every report the phone keeps that the lab lacks into the device lab's tests/results (RUN.jsonl, as written on the phone), and files every run not yet filed into linux-phone-oco/docs' test_results and test_runs, the rows made from the report's lines. A run is filed once, by its id.

Filing was by hand (tests/to-docs.sh, through tad's Python) and had fallen a week behind: docs held 7 runs from 2026-11-10 while the lab had made many since. Rust carries it now, and the tables stay where they are declared and observed today.

Отвергнуто: Declaring test_runs and test_results again in each device lab (one nature, two declarations - entered as the sign a-test-run-has-no-shared-shape in ocoeco, to be answered in the language); keeping to-docs.sh (new filing through Python).

2026-11-17

devlab guard keeps only the phone's way: ssh, scp, sftp, rsync and sshpass to a phone outside devlab are refused (devlab guard tool, PreToolUse). The ways every project shares - no git push to main, no Python, the practices and the inbox at session start - moved to the ideal-agent plugin's hooks (grenudi/ideal-agent), installed on the lab; devlab guard start is gone and the lab's settings keep only the PreToolUse hook (lab-tools #65).

The author, 2026-11-17: general agent know-how has one home, grenudi/ideal-agent (its decision 2026-11-17-one-home-for-agent-know-how). Held in devlab, the shared rules held only on the lab. Before devlab's rules were removed, both guards were given the same 19 events: they agreed on every push and Python case; the one difference was the phone's, which stays here.

Отвергнуто: Both guards holding the shared rules (two guards saying one thing drift apart). Moving the phone's rule to the plugin too (it is this lab's device: its addresses come from devlab's state).

2026-11-17

devlab-health takes analysis as subcommands of its own binary: tone make|find (lab-tools' tone crate, linked with only its wav feature) and data plan|spent (the month's mobile-data ledger, a JSON file in /var/lib/devlab/health-data that pruning never touches). Their arguments are parsed by hand, and each prints one JSON line with exit 0/1/2. A check reads that line with lib.sh's json_field. mobile-data runs every boot in the telephony layer and is bounded by the month's budget, not by once_a_day. It measures the connected bearer that carries a default route and is not IMS. The week's 5 MB run counts as made only when its download came whole.

The tone crate already had tests, and the checks' awk Goertzel had none. Linking the crate costs 64 KiB on the phone, against two copies of the arithmetic. hound was already the lab's WAV reader, so one read_mono now serves tone, devlab hear and the runner instead of three. The research (mobile-data-check-budget) measures data every boot and bounds it by a monthly ledger; a byte count kept across runs is state, which the shell-and-Rust decision puts in Rust. On surya an IMS bearer (APN ims, IPv6, no route) sits beside the data bearer, and the first-connected rule measured it as 0 of 5 pings.

Отвергнуто: clap in devlab-health (size on the phone; argenv is the commons' parser, and moving the runner onto it is its own change). A WAV reader written again by hand (hound is there and tested). Ledger arithmetic in shell (state and numbers, against the shell-and-Rust decision). once_a_day for mobile data (the research measures every boot; the budget already bounds the cost). The first connected bearer (picked IMS on surya). Marking the weekly run as made when it failed (a broken run would hide throughput for a week).

2026-11-17

The phones' health suites keep one contract - a check prints 'pass|fail|skip TEST COMPONENT detail', and docs' tests table says what a pass proves - and two languages by kind of work: shell for readings (sysfs, a command's output, a few readable lines on BusyBox), and Rust for anything with numbers, timing or states (tones, echoes, calls, sleep counters), as subcommands of one static multi-call binary shipped with devlab-health (devlab-health tone make|find, later call echo), unit-tested on the lab with recorded fixtures and cross-built by health/build.sh. rust-script is the lab's tool for prototypes and one-off analysis of recordings fetched from the phone; a prototype that is kept becomes a subcommand. Checks are layered by cost: base, shell, telephony (calls and data, budgeted, at most daily), witnessed (a person). Coverage is a query over docs: every device's components with no test proving works.

The shell contract is what makes a check quick to write and read, and it already runs everywhere; what goes wrong in shell is arithmetic - three of surya's checks carry an awk Goertzel and a printf-built tone that nobody unit-tests, while lab-tools' tone crate has tests and never reaches the phone. The phone has no Rust toolchain, so Rust must arrive compiled; one binary already goes there (devlab-health), so analysis joins it at no new cost. rust-script works today on the lab; Cargo's own scripts are still nightly-only (Cargo 1.99 asks for -Zscript) and can replace rust-script when they are stable.

Отвергнуто: Python checks (refused on the lab; the phone's python3 is the image's, not ours). rust-script or cargo script on the phone (a toolchain and network on the phone, minutes of compiling at boot). Every check in Rust (a ten-line sysfs reading becomes a cross-build per change). bats or another shell test framework (bash, not BusyBox ash; the contract already does its work). LAVA or a KTAP-native harness now (a lab of many boards; our lines map onto KTAP if ever needed). One binary per check (many cross-builds and files to ship).

2026-11-17

The phone measures its own health after every boot: devlab-health, a static Rust runner, runs small check files (base layer, then shell layer) and writes one report per run in test_results' shape, keeping the evidence when unhealthy. The checks are POSIX shell in postmarketOS's test shape and print plain words (pass|fail|skip TEST COMPONENT detail); the runner makes the JSON, the verdict and the evidence. Generic checks live in lab-tools; what a phone is expected to have is its manifest's [health], and a phone's own checks sit beside the generic ones.

Health measured only from the lab is health only while the lab is connected and remembers to ask; a phone that checks itself after every boot leaves a record for every change. Shipped code is Rust (2026-11-11-rust-for-what-ships): strings and structure - JSON escaping, the report - are where shell is fragile. The probes themselves only read sysfs and the system's own tools, which is what postmarketOS's tests and bootrr do in shell, so they can be contributed there.

Отвергнуто: A shell runner (JSON escaping and report shaping in sh - the fragility the Rust decision answers); checks written in Rust (a probe of sysfs gains nothing, and upstream would not take it); keeping the checks run only from the lab over SSH (no record when the lab is not asking); one check file per device (surya's checks.sh: nothing reusable for the next phone).

2026-11-17

The health suite reaches phones as an Alpine package (devlab-health: the runner, the checks, the unit and the timer) published through the package conveyor once it publishes Alpine repositories (cv-apk); until then devlab puts the same files on the phone itself, as the development path.

The commons has one packaging conveyor that every project calls (linux-package-distribution-oco/conveyor) and it already builds aarch64-musl binaries; a package is how postmarketOS installs and updates anything, and it gives the phone updates the way the lab machine already gets them.

Отвергнуто: devlab copying files onto the phone for good (a second delivery route beside the conveyor; nothing updates it); building the package in lab-tools' own CI (copying what the conveyor exists to do once).

2026-11-17

lpoco and lpoco-health (and every later lpoco-*) share one version through release-plz's version_group, starting at 0.1.7 (lpoco-health's). The dispatcher refuses a program whose --version differs, so every lpoco-* program must answer --version with 'NAME X.Y.Z' (lpoco-health now does). Tags stay one per package: lpoco-v{version} for the dispatcher (lab-side only, no phone package) and lpoco-health-v{version} for the conveyor's phone package.

Decision 2026-11-17-bringup-in-lab-tools asks for one version pin for the family and one release; version_group gives it without moving the conveyor's tag prefix. Proof: lpoco-refuses-mixed-versions.

Отвергнуто: One shared git tag for the whole family: the conveyor reads lpoco-health-v* for the phone package, a shared tag would break it. Independent versions per program: the dispatcher could not tell a compatible program from a stale one.

2026-11-17

linux-phone-oco has one health suite, lpoco-health (devlab-health renamed; same checks, same test_results shape, same report on the phone). It keeps the shape decision 2026-11-17-health-on-the-phone chose: small shell checks printing 'pass|fail|skip TEST COMPONENT detail' (postmarketOS's test shape, so a check can later become a postmarketos-test-* subpackage by a merge request), gathered by our static Rust runner. New: (1) detected conditions - conditions/*.sh work out no-sim, no-modem, no-network at every run; checks say skip_on NAME and report 'skip: no SIM card'; nothing is written down. (2) chosen switches - lpoco-health off TEST --reason WORDS [--by], on TEST, list, kept in /etc/lpoco-health/switches (test, reason, who, when), reported as 'skip: switched off: reason (by who, when)'; never without a reason; from the lab devlab suite off|on|list and the MCP tools health_switch_off/on, health_switches. (3) the command line is declared with argenv (health/src/cli.rs). (4) docs hold only facts about the hardware and the results; the phone's state (SIM in or out) is never recorded there; backlog sim-removed-skips closed as superseded, its log entry stays. (5) provisioning: the Alpine package lpoco-health (published by the conveyor since 0.1.6) is what devlab suite put now takes; --runner builds the runner on the lab for what is unreleased; put migrates the old devlab-health reports, month data ledger and once-a-day marks with nothing lost, and the package keeps devlab-health and /usr/lib/devlab/health as other names until the phone's own checks call the new ones. (6) upstream: we do not fork postmarketOS' test pieces now; we write our checks so they could be sent upstream, and revisit when their system-level tests or farm admission exist.

The SIM removal showed that a state of the phone cannot live in docs: it is true for minutes and the phone knows it better. Every mature phone CI (bootrr, LAVA, postmarketOS's test package, CI-tron) keeps tests as small executables with one result line each and a thin runner, device facts as data and an explicit skip; nobody compiles on the device. Upstream postmarketOS (checked 2026-11-17) runs on-device tests only from the initramfs, halting the boot; boot and system tests - the modem, audio, sensors, sleep and budgets we need - are not built, and their farm is one phone behind a token gate. Our checks and runner already have the shape, so it is kept and extended, not replaced (decision 2026-11-17-health-on-the-phone weighed first).

Отвергнуто: A. Building fully on postmarketOS upstream (fork their test pieces into a rhizcut-synced subfolder, send improvements back as merge requests): the right long-term friend - open GitLab, clear review rules, Python only host-side so it does not weigh against it - but today it gives us only the initramfs hook, which halts the boot and covers kernel tests, not the after-boot system tests we run; their farm has one OnePlus 6T and registration is token-gated; whether rhizcuts handle a GitLab upstream and a subfolder is not known; licence/CLA and fork-sync cost not known. Revisit when upstream gets system tests or admits other phones. C. A different shape of our own: nothing to gain over B. rust-script tests with a bundle crate (the author's lean, weighed fairly): the dependency direction is right (bundle depends on tests, not the reverse) and nextest shows it works, but rust-script needs rust+cargo on the phone (Alpine aarch64 72 MiB download, 206 MiB installed plus gcc, musl-dev, llvm-libs, network for crates), a registry (inventory/linkme) is unproven on aarch64 musl and links everything into one binary; kept instead: the same direction by discovery - the runner finds tests in directories, tests depend on nothing of it - and Rust for logic (runner, ledger, tone) built on the lab as a static binary; revisit as prebuilt per-test binaries when a check needs more than shell. Building each test on the lab as its own binary now: cross-build work for 13 small shell checks that need none. A settings store in docs or in devlab's lab-side files: wrong place for the phone's state, goes stale. Keeping the name devlab-health: the suite is linux-phone-oco's, not devlab's; the old name stays only as an alias. Lab-built runner by default: the package is published, so the package is the default.

2026-11-17

WHAT: a new program under the lpoco roof, lpoco-host (`lpoco host`), its own crate host/ in lab-tools, Rust, command line declared with argenv. It prepares the lab host for the devices it serves and keeps the host's own tools at their pins, from declarations only: no manual step stays outside it. Bringing a phone up on a fresh host is then: the one bootstrap line (cargo install --locked --git https://github.com/linux-phone-oco/lab-tools --tag lpoco-vX lpoco lpoco-host), clone the lab and device repositories, `lpoco host prepare now`. VERBS: `lpoco host plan` (the default, read-only: a content diff per file, the tools to install with pinned and found versions, and the exact root commands); `lpoco host prepare now` (the only state change: writes, reloads, triggers change only where it touched; `prepare` without `now` refuses); `lpoco host check` (the lab user opens each declared node present; each tool at its pin; fastboot by the device's serial as the lab user). Only plan and check are offered through `lpoco mcp`. TWO DECLARATIONS, one owner each. What a device needs of any host lives in its own device.toml, a [host] table read by lpoco-host alone (devlab ignores it): `modules = [...]`, `[[host.gadget]] serial = "...", access = ["block", "tty"]` (walleye's shape from lab PR 54, kept; deny_unknown_fields inside [host]); later `targets` and `commands`. What one machine is lives in the lab's own declaration, lab.toml at the root of grenudi/lab-machine (that repository already is "how the lab machine is set up"; --lab PATH or LPOCO_LAB elsewhere): where its devices are (default ~/Projects/linux-phone-oco/*/device.toml), its root prefix, and [tools] - each host tool with its source and pin. WHERE THE TOOL PINS LIVE: in the lab's declaration, not in device.toml. A host has one ~/.local/bin, so one version of each tool; land, oco-work and agent-env are the lab's and the agents', no device's concern. device.toml [tools] lpoco = "X.Y" stays what it is - the device's requirement of the family - and the plan checks the lab's lpoco pin meets every device's: a device it does not meet is named and nothing is installed for it. Tools: land (grenudi/lab-machine bin/land at a commit), oco-work (its only tracked home is creation-guidelines/lab-agent oco-agent/tools/oco-work, a retiring place: it needs a living home before it can be pinned), agent-env (grenudi/ideal-agent scripts/agent-env at a commit), the lpoco family from its release tag (cargo install --locked --git ... --tag lpoco-vX for lpoco, lpoco-lab, lpoco-bringup and lpoco-host itself; a self-upgrade installs and stops, the next run is the new one). User-level, into ~/.local/bin, no root; hand copies (devlab.before-*) are not the tool's to keep. ACCESS: per device one file /etc/udev/rules.d/70-lpoco-CODENAME.rules (below 73-seat-late, as uaccess needs), one line per access kind: ACTION!="remove" (systemd 258+ re-applies on change), SUBSYSTEM=="block"|"tty", ATTRS{serial}=="SERIAL" (our own gadget's serial, never a vendor-wide match), TAG+="uaccess". uaccess reaches the lab user while it holds the active seat0 session - true on the lab today, and enough for the acceptance; a lab group with MODE 0660 for a headless host and services is the next item (lpoco-host-rest). Nothing by vendor for adb and fastboot: systemd 262's hwdb tags them; `check` proves it. Applied by `udevadm control --reload` and `udevadm trigger --action=change --attr-match=serial=S`: no replug. MODULES: /etc/modules-load.d/lpoco.conf from the declared modules, `modprobe` each now; when /lib/modules/$(uname -r) is gone the plan says the host must reboot into its installed kernel (what stopped usb_storage and cdc_acm today). ROOT: the tool runs as the lab user and asks root only through one prefix, LPOCO_ROOT, falling back to DEVLAB_ROOT, then `sudo -n lab-agent root-exec --`; it runs only a fixed list of commands the plan prints (install -D -m 0644 into the two paths above, udevadm control --reload, udevadm trigger --action=change --attr-match=serial=S, modprobe M). That list is what lab-agent's retirement part 6 (ideal-agent 2026-11-17-lab-agent-retires-by-parts; lab-agent-6-root-exec-grant) can write a narrow grant or the lab-root wrapper from; the grant stays the author's and root's. LAB-MACHINE keeps what is only this machine's (locale, nix, plasma) and its lab.toml; setup/devlab-watch.sh retires when watchers move into the tool; its README names the bootstrap line. The device template gains a commented [host] table. PROOF: first the failing fixture test plan_grants_gadget_serial_and_changes_nothing, then plan_lists_host_tools_at_pins_and_installs_nothing; acceptance is the tool's first real use (the author: "ill wait for the tool, so its use would be its test"): `lpoco host prepare now` grants walleye-first-boot, and the walleye keeper reads /dev/sda and /dev/ttyACM0 as the lab user. No udev rule is written by hand meanwhile. Backlog lpoco-host (rank 1), lpoco-host-rest. AMENDED 2026-11-17 (the author, through the coordinator: "Keep it for now"): /etc/udev/rules.d/51-android.rules, the wide rule left by lab-agent's connect.sh, stays. lpoco-host leaves it alone: plan and check may name it as a known wide rule, and prepare now neither removes nor edits it.

Principles no-manual-steps and rust-with-argenv. The author, 2026-11-17: "this needs to be on lpoco tools, for preparing the lab, and device repos should have it from the one roof. something like lpoco-labprep or something ... we dont keep manual steps outside tools, so that the process of bringing up linux phones could be fully automatic"; and "ye, ill wait for the tool, so its use would be its test". The coordinator, the same night: the host's own tools (land, oco-work, agent-env, the lpoco family) installed by the tool at pinned versions, nothing copied by hand - ~/.local/bin/land was a hand copy and nothing in lab-machine installs it. Measured (research lab-host-prepare-landscape): after the reboot walleye's gadget bound but /dev/sda (root:disk) and /dev/ttyACM0 (root:uucp) were closed to the lab user, and the fix was handed to the author as a manual rule; 51-android.rules, the cross toolchain, the watcher units, the host tools and the host reboot for missing modules were all hand work. Nobody outside derives host rules from per-device declarations: LAVA comes closest (serials in data, one static rule and a root helper), labgrid leaves rules to the administrator, pmbootstrap runs as root. systemd's source settles the mechanism: uaccess in a rule below 73, not add-only, applied to present nodes by a change trigger; adb and fastboot already covered on 258+. Under the roof (decision 2026-11-17-bringup-in-lab-tools): a crate per tool, run alone or as `lpoco NAME`, one pin, one release; the boundary that lpoco-lab is the phone-facing tool (fastboot, ssh, the keeper's lease, tokio and rmcp) holds - preparing a host needs no phone and must run first on a fresh machine, small. The device says what it needs, the lab says what it is: each declaration with the owner that knows it, as [boot] is bringup's and [health] the suite's. The name is plain and names its object, as health and bringup do: `lpoco host prepare now` reads as what it does.

Отвергнуто: Names: lpoco-labprep, the author's starting word (a clipped compound, the shorthand the roof refused with lp-oco-bh; and `lpoco labprep` beside `lpoco lab` reads as part of lpoco-lab, the phone tool); lpoco-hostprep (the same clipping); lpoco-setup (says nothing of what is set up; setup/ is lab-machine's folder word); lpoco-provision (devlab provision is the phone's); lpoco-bootstrap (refused for bringup: pmbootstrap's and the compilers' word); lpoco-prepare (a verb as a name - prepare what? the verb belongs after the object); lpoco-machine (lab-machine's name); lpoco-env (agent-env's word). Forms: a `lpoco lab host ...` subcommand of lpoco-lab (lpoco-lab carries the phone's life, tokio and rmcp, and a lease; the host must be prepared before any phone and from a fresh machine; the roof keeps one crate per job); lab-machine's job, fed by the declarations (shell parsing TOML and diffing files is logic in shell, which the author's rule refuses; lab-machine describes one private machine, so a second lab would copy it; it keeps the lab's own declaration instead); LAVA's way, one static rule calling a root helper on every uevent (root on every event, rules matching at run time cannot be planned or diffed); a package or a systemd confext image built from the declarations (a rebuild per device change, tied to the host's distribution, while the conveyor builds Alpine packages; possible later as an output); systemd's built-ins alone (cover adb and fastboot, not our gadget's block and tty); NixOS modules or Ansible roles (a second system to adopt on a CachyOS host; Ansible is Python); vendor-wide rules in the shape of 51-android.rules (MODE 0666 to every Google or Qualcomm device on the bus; ours match only our own gadget's serial); adding the lab user to disk and uucp (disk opens every disk on the host); a dedicated group in the first build (needs usermod and a new login before it works; uaccess serves the acceptance now; the group follows in lpoco-host-rest); a udev rule written by hand meanwhile (the author: the tool's use is its test). Where pins live: in each device.toml [tools] (one ~/.local/bin cannot hold two devices' different versions, and land, oco-work, agent-env belong to no device; the device's lpoco pin stays as its requirement, checked against the lab's); in the tool's own code (it would pin what it was built with, so moving land meant releasing lab-tools); a lockfile beside ~/.local/bin (state, not a declaration in a repository; nothing reviews it); following main without pins (a tool changing under a running lane, which the family's one-version stop exists to prevent). Root: running the whole tool as root (whole-command root, as pmbootstrap; the plan and the tool installs need none); editing sudoers from the tool (the grant is the author's and root's, lab-agent-6).

2026-11-17

lpoco mcp runs lpoco-lab mcp. One server lists lab_run/put/get/kernel_*/reboot (the bare names run, put, ... answer the same function), health_* and bringup_image_info/check (which run lpoco-bringup beside it). A new program joins by adding its prefixed tools to that router.

Agents look in one place; the rmcp router already held the lab tools, and prefixes by program name need no second protocol layer. Proof lpoco-mcp-lists-every-family-tool lists them over real stdio.

Отвергнуто: A proxy that starts each lpoco-NAME mcp and merges their tools: a child process per program and an MCP client for no gain while only the lab holds a phone. A separate lpoco-mcp crate: a second copy of the door and its device loading. Renaming the tools with no aliases: breaks every agent's saved config (lpoco-names-sweep keeps aliases until it ends).

2026-11-17

Every test sound is quiet unless the phone's manifest says otherwise: [hear] level_dbfs (default -40 dBFS) and volume (default 25%), capped at full scale and 100%, used by devlab hear and given to every check through the phone's health.env (TEST_TONE_DBFS, TEST_VOLUME).

The author, 2026-11-17, urgently: a full-scale test sine played at night; test sounds must be quiet, with a setting for it in the suite. devlab hear had -12 dBFS at 60% volume hard-coded.

Отвергнуто: Lowering the hard-coded numbers (no setting, and other checks would choose their own); a level per check (a phone in a home has one acceptable loudness).

2026-11-17

fastboot boot now and set-active read current-slot and the slot-unbootable/successful/retry-count flags of both slots before and after, and say the difference; the verdict of a boot is where the phone went, not fastboot's exit. set-active (metadata) is refused unless the manifest says [fastboot] slot_switch = true, separate from writes.

walleye's try b: devlab wrote nothing, yet the bootloader's A/B logic ended on slot b with slot a unbootable, and devlab, reading fastboot's failing exit, called the try refused.

Отвергнуто: keeping 'nothing written, slots as they were' (true of devlab, false of the phone); folding the switch into writes = true (a flag change is not a partition write, and walleye may need one without the other); restoring slot a by devlab on its own after a try (a write that needs the author's word).

2026-11-17

devlab holds the phone for every change it makes - flash, provision, reboot, root commands, put, kernel install, try and remove, suite put - by an exclusive lock on STATE/phone.lock, from the command line and the MCP door alike; a second change waits for the first and says so. Reading needs no hold.

Two sessions now work with one phone (the bring-up session beside the conveyor's): a reboot under a kernel try would strand a test or misreport it. A lock each session must remember to take is a rule kept by care; devlab taking it itself is kept by the tool.

Отвергнуто: flock around devlab by convention (forgotten once is enough; and wrapped around a devlab that also locks, it would wait on itself); a lock only in the MCP door.

2026-11-17

devlab offers its structured door over MCP (devlab mcp, stdio, with rmcp): run, put and get a file, the health report, kernel install, try and status, reboot and wait - each the same function the command line calls.

Agent access plans every tool's structured door over MCP in Rust with rmcp, devlab among the first (aa-two-doors); an agent then works with the phone without a person and without a shell's quoting layer.

Отвергнуто: A separate MCP server project beside devlab (two doors to keep in step); MCP through a generic shell tool (every call a quoting puzzle).

2026-11-17

The ways an agent must keep on the lab (land, not a push to main; no Python; the phone only through devlab) are held by Claude Code command hooks that call devlab guard, a subcommand of devlab in Rust, with its cases tested.

A way that must be remembered is forgotten; the hook refuses when it is tried and says why, to the agent that tried. devlab already knows the phones (their manifests and learned addresses), so the guard knows what reaching the phone means.

Отвергнуто: Hook scripts in shell with jq (logic in shell, untested; the guide says Rust for logic); a separate guard tool beside devlab (a second place that must learn the phones addresses); permission deny rules in settings (match command prefixes only: miss sudo, env, sh -c and $(...), and cannot tell a branch push from a push to main).

2026-11-17

image bisect frames a swapped-in kernel with the lz4 program (level 9, independent 4 MiB blocks, content checksum, the stock kernel's frame flags); an entry may also leave the AVB footer off. The count compares ramdisk, kernel, dtb and command line to the control and verifies the footer; it does not compare the second stage or other header fields.

walleye's build-bisect.sh used lz4 -9 -BI -B7, whose frame the stock bootloader path reads; the oracle is the lz4 program, as avbtool is for the footer (research bringup-tools-landscape).

Отвергнуто: a Rust lz4 crate (lz4_flex): no level-9 high compression and the frame flags would differ from the stock frame, so the bisect would change two things at once; comparing every header field: not needed for the walleye series, narrowed the claim instead

2026-11-18

check-changelog.sh (run by the commit-kind workflow): per package, a changed CHANGELOG.md passes if the [package] version changed since the merge-base, or if it adds the heading for the current version that the merge-base lacked. A lone edit or a repeated version is refused.

Release #111 left lpoco-host without an entry; release-plz put it in a follow-up PR #113 that only changes a changelog, which the first check (#112) would refuse. That PR completes the version, tags host-v0.3.5, and so tags something.

Отвергнуто: Reconfiguring release-plz so unchanged version_group members get an entry in the first PR: no setting for it confirmed. Accepting any changelog-only PR: reopens the changelog-only release #112 forbids.

2026-11-18

pr-title.yml checks the PR title and every commit title against .github/commit-kind.regex, and refuses a changed CHANGELOG.md with no changed Cargo.toml version; lpoco/tests/release_family.rs keeps release-plz.toml, versions and changelog headings whole.

#110 landed titled 'bringup: ...', so release-plz saw nothing to bump and #109 was a changelog-only release under v0.3.4; the code sat under no tag. land squash-merges a one-commit branch under its commit title, so commits are checked, not only the PR title (review).

Отвергнуто: Checking only the PR title: the commit title is what lands. Comparing the changelog with the version's tag in a Rust test: release-plz tags the commit before the changelog is written, so it always differs. release_commits regex in release-plz.toml: does not make an untyped commit bump.

2026-11-18

release-plz.toml gives each package changelog_include = every other member; a fixture-workspace test runs release-plz update and requires every member's CHANGELOG at the new version; CI installs release-plz@0.4.3.

Seen on v0.3.5-v0.3.7: a package changed only by the version_group bump got no entry, so main was red until a follow-up PR (#113, #117, #120). Reproduced with release-plz 0.4.3: without the key fam-b has no entry, with it all three do.

Отвергнуто: Writing missing entries in a release hook: more code than one config key. Loosening the release_family test: hides the red instead of removing it. A fixture with no prior changelogs: passes without the fix, so proves nothing.

2026-11-18

In a git clone, plan/prepare/check fetch origin (no prompts, low-speed bound) and read device.toml from origin/main; a read: line names the commit, the checkout's lag, a differing working file, or why the file as it lies was read.

A stale detached google-walleye-lab clone without [host] planned no udev rule; a stale checkout must not hide the declaration.

Отвергнуто: Reading the working file only (the bug). Following origin/HEAD: main is the lab's only truth, so origin/main is fixed. Fetching only in plan: prepare would then act on a different commit than plan showed.

2026-11-18

devlab/src/cli.rs holds contract! inputs (positionals scoped to the command, flags, the env it reads) and a TREE of commands and actions with their arguments and flags; --help, argument counts and per-action flag checks read it. suite put's --runner [FILE] becomes --runner FILE or --built-runner. Usage mistakes exit 2 with the usage; help wins over a mistake.

argenv scopes inputs to the first word only and has no optional-value flag; the tree restores per-action scoping. Programmer review found sibling-action flags silently accepted and exit codes split 1/2: both fixed.

Отвергнуто: Generic ARG0..ARG4 inputs (help says nothing); keeping clap beside argenv (two declarations of one surface); a hand parser for the optional-value flag (practice 43)

2026-11-18

tone/src/cli.rs holds the contract; main.rs scopes flags per command from TREE, refuses extra positionals and out-of-range or zero rate and channels with the usage (exit 2). Rate and channels are read as u64 and narrowed at the edge; defaults come from the declaration.

The last clap in the family (backlog lpoco-tone-argenv); the practice that every program declares its invocation surface once with argenv; same shape as lpoco-lab so one reader knows both.

Отвергнуто: Reading rate/channels as u32/u16 in the contract: a value that does not fit becomes None and fell back to the default silently (programmer review). Keeping clap beside argenv: two parsers for one program.

2026-11-18