feat: add independent battery diagnostics

1bite

@@ -1,6 +1,18 @@
 #!/bin/bash
 set -euo pipefail
 ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+if [[ "${BASH_SOURCE[0]}" == "$0" && $# -gt 0 ]]; then
+  case "$1" in
+    --battery)
+      shift
+      exec /bin/bash "$ROOT/scripts/battery.sh" "$@"
+      ;;
+    --install-battery)
+      shift
+      exec /bin/bash "$ROOT/scripts/battery.sh" --install-tool "$@"
+      ;;
+  esac
+fi
 MODE=install
 UPDATE=false
 WITH_SOGOU=false
@@ -29,6 +41,8 @@ Powerlevel10k is installed after Oh My Zsh; existing explicit themes are preserv
 --plan            Print the plan; no writes or downloads.
 --welcome         Show the colorful One Bite system card; no writes or downloads.
 --lock-status     Show whether the selected log root is locked and list openers.
+--battery         Run battery diagnostics; supports --summary/--json/--tsv/--shell/--field.
+--install-battery Install ~/.local/bin/1bite-battery; add --update to replace an unchanged managed copy.
 --update          Update managed tools and refresh desktop DMGs (install mode only).
 --managed-desktop Automatically place desktop apps and configure Kiro hooks (explicit opt-in).
 --check-updates   Report available versions and configuration drift; never upgrade.
@@ -69,6 +83,17 @@ check_install_target() {
   [[ "${version%%.*}" -ge 26 ]] || fail 'Full installation targets macOS Tahoe 26 or newer.'
   [[ $(id -u) -ne 0 ]] || fail 'Run as your normal user; Homebrew requests sudo when needed.'
   echo "Target: Apple Silicon, macOS $version"
+  if ! startup_battery_summary; then echo 'Battery: unavailable; setup will continue.'; fi
+}
+
+startup_battery_summary() {
+  # Called inside run_session; RUN_DIR belongs to that same subshell.
+  # shellcheck disable=SC2031
+  local summary work_root=${RUN_DIR:-${TMPDIR:-/tmp}}
+  summary=$(without_session_lock /usr/bin/env TMPDIR="$work_root" /bin/bash "$ROOT/scripts/battery.sh" --summary --no-cache 2>/dev/null || :)
+  summary=${summary//$'\n'/ }
+  [[ -n "$summary" ]] || return 1
+  printf '%s\n' "$summary"
 }
 
 installer_url() {

AGENTS.md

@@ -24,6 +24,7 @@ Read `README.md` and `docs/automation.md` first. This directory is an independen
 - Load fzf widgets whenever Zsh is interactive. Do not require stdin, stdout, or stderr to be a TTY: Powerlevel10k instant prompt redirects all three while cached startup runs. Support both current `fzf --zsh` output and the shell files shipped by older healthy Homebrew releases; force an interactive shell with all three descriptors redirected and verify the function, ZLE widget, and Ctrl+R binding. Preserve later personal bindings.
 - Treat the Homebrew `node` formula as the complete baseline Node.js development/runtime environment. Require `node`, `npm`, and `npx`, and exercise an offline local npm build/start lifecycle during disposable-machine verification.
 - Keep `hexyl` in the default Homebrew formula set as the terminal hex viewer. It must follow the standard install, executable health, inventory, strict verification, and update-check contracts.
+- Keep the full battery diagnostic explicit and independent. `--battery` must dispatch before UI/session creation and never affect verification, inventory, maintenance, locks, or result files. A normal install may print only its cache-free `--summary` after the platform checks; close the session-lock descriptor for that read-only probe tree, omit history, and treat missing, partial, or failed probes as non-blocking display information. Use only system Bash 3.2 and built-in macOS probes; immediately reduce their output to the documented allowlist. Cache only normalized timestamps, source, numeric percentages, and derived intervals in a 0700 private directory with 0600 atomic files and symlink refusal. Preserve unknown/modified installed commands; only an explicit battery-tool update may replace bytes still proven by its private receipt.
 - Give a fresh shell the reviewed built-in Oh My Zsh plugins `git`, `macos`, `vscode`, `web-search`, `extract`, and `tmux`, plus `docker` only when its client is available. Preserve any existing `plugins` array exactly. Keep fzf, AutoJump, and zoxide on their separately verified native integrations so they are not initialized twice by Oh My Zsh plugins.
 - Keep SSH helpers identity-neutral. `sshkey` may print a selected existing Ed25519, ECDSA or RSA public key and may create a passphrase-free Ed25519 default only when the user explicitly invokes it; it must never overwrite a key. `pubkey` may copy that public key, but neither helper may read SSH config, agents, known hosts, account names or private key contents into setup output.
 - At the end of an install, explain every remaining DMG task with the current session's exact package path, a safely quoted `open` command, numbered copy/eject/launch steps, application-specific first-launch work, and the matching strict verification command. Save the same guide in the run directory. Derive it only from current-session receipts; do not surface stale downloads or unselected applications. If a later stage fails, still explain packages successfully prepared in that run.

Makefile

@@ -1,5 +1,5 @@
 PYTHON ?= python3
-SHELL_FILES := 1bite scripts/verify.sh scripts/docker-smoke.sh scripts/session.sh scripts/welcome.sh scripts/editor.sh scripts/quality.sh apps/qbittorrent/qbt.sh
+SHELL_FILES := 1bite scripts/verify.sh scripts/docker-smoke.sh scripts/session.sh scripts/welcome.sh scripts/editor.sh scripts/battery.sh scripts/quality.sh apps/qbittorrent/qbt.sh
 
 .PHONY: build test format-check quality check
 build:

README.md

@@ -31,6 +31,7 @@ Run the installer as your normal administrator account, without `sudo`. If `gh`
 | AI command-line tools | Installs Codex CLI and Kiro CLI from their official installers. Claude Code is opt-in. |
 | Desktop applications | Downloads official DMGs for Chrome, ChatGPT, and Kiro IDE when the apps are missing. Docker Desktop is opt-in. |
 | Optional Docker apps | Provides separate, opt-in launchers for useful local services. These apps never start as part of the main installer. |
+| Battery diagnostics | Shows a best-effort charge, power, maximum-capacity, and cycle summary beside the initial macOS check. The independent dashboard also provides JSON, TSV, Shell, and single-field output. Probe failure never changes installation success. |
 
 Docker Desktop is disabled by default because its terms may not fit every workplace. Review the current vendor terms, then add `--with-docker` whenever you install, update, or verify it. Claude Desktop and Claude Code are also disabled by default and use `--with-claude`.
 
@@ -58,6 +59,10 @@ The default run checks Doubao Input Method independently after the managed Pytho
 ./1bite --update                     # Update managed tools and refresh DMGs
 ./1bite --welcome                    # Show the colorful One Bite system card
 ./1bite --lock-status                # Inspect the session lock and its open processes
+./1bite --battery                    # Show the independent battery dashboard
+./1bite --battery --summary          # Print the cache-free startup summary
+./1bite --battery --json             # Emit the stable battery report schema
+./1bite --install-battery            # Optionally install the 1bite-battery command
 ./1bite --verify                     # Strictly verify actual installations
 ./1bite --check-updates              # Report available updates without changing them
 ./1bite --configure-only             # Apply managed configuration templates only
@@ -98,6 +103,7 @@ One Bite installs both `neofetch` and `fastfetch`. Because Neofetch was archived
 - [Installation policy](docs/installation.md)
 - [Shell, editor, Git, aliases, and terminal configuration](docs/shell-editor.md)
 - [Obsidian installation and vault starter](docs/obsidian.md)
+- [Read-only battery diagnostics](docs/battery.md)
 - [Troubleshooting](docs/troubleshooting.md)
 - [Updates and maintenance](docs/maintenance.md)
 - [Official software sources](docs/sources.md)

VERSION

@@ -1 +1 @@
-0.0.6
+0.0.7

config/repository-files.txt

@@ -52,6 +52,8 @@ config/zsh/terminal.zsh
 config/zsh/tools.zsh
 config/zsh/utilities.zsh
 docs/automation.md
+docs/battery.md
+docs/battery.schema.json
 docs/development.md
 docs/installation.md
 docs/maintenance.md
@@ -61,6 +63,7 @@ docs/shell-editor.md
 docs/sources.md
 docs/troubleshooting.md
 docs/updates.schema.json
+scripts/battery.sh
 scripts/check-change.py
 scripts/check-format.py
 scripts/check-repository.py
@@ -82,7 +85,10 @@ scripts/runtime-smoke.py
 scripts/session.sh
 scripts/welcome.sh
 scripts/verify.sh
+tests/fixtures/battery/pmset-log-batt-uppercase.txt
+tests/fixtures/battery/pmset-log-batt.txt
 tests/fixtures/config-golden.json
+tests/test_battery.py
 tests/test_desktop.py
 tests/test_doubao.py
 tests/test_editor.py

docs/automation.md

@@ -8,6 +8,8 @@ Run Bash 3.2-compatible `./1bite`. Source checkout: `https://github.com/1set/1bi
 | --- | --- | --- |
 | `--help`, `--plan` | None, no log directory created | Help/plan printed, exit 0 |
 | `--lock-status` | None; reads the selected log root and kernel lock | Reports available, held, or lock-helper error; a held lock returns 75 |
+| `--battery [OUTPUT]` | Reads allowlisted macOS battery fields; optionally writes only sanitized private history | Produces the requested dashboard, one-line summary, JSON v1, TSV, Shell, or single-field report without entering an install session |
+| `--install-battery [--update]` | Explicitly installs or updates the separately owned `1bite-battery` command | Missing target is installed; current managed bytes are skipped; replacement requires an unchanged receipt plus explicit update |
 | no mode | Install development tools/AI CLIs; prepare missing desktop DMGs and the Doubao Input Method ZIP; apply templates | Automated tools and prepared packages verify; manual_steps lists remaining user work |
 | `--managed-desktop` | Also place desktop apps and configure managed Kiro Zsh integration | All declared packages/runtime probes pass; GUI/login remain manual |
 | `--with-docker` | Include Docker Desktop in the selected install, update, verification, inventory, and maintenance scope | Same mode-specific requirements, now including Docker Desktop; engine execution remains a separate smoke check |
@@ -22,6 +24,8 @@ Run Bash 3.2-compatible `./1bite`. Source checkout: `https://github.com/1set/1bi
 
 `--config-dir DIR` selects the configuration templates, including all eight `zsh/` modules and the complete `obsidian-vault/` starter; it never changes installer URLs or the package manifest. `--log-dir DIR` selects a local, private log root. All invocations using that root share its lock; do not use different roots to bypass concurrency protection. `--update` and `--with-sogou` can be combined only with install or `--plan`, including both flags together.
 
+Explicit battery dispatch occurs before the normal UI, session directory, fd 9 lock, environment report, inventory, and result handling. A normal install also runs the cache-free, history-free battery summary after its architecture, macOS-version, and user checks. That read-only subprocess closes fd 9. Missing hardware prints `Battery: not present.` and succeeds; partial fields are labeled unavailable in place; command failure or empty output degrades to `Battery: unavailable; setup will continue.` None of these cases can fail the target step or stop later installation work. The summary is display output only: it is not a separate step and does not enter `result.json`. Neither the full diagnostic nor its optional command installation participates in `--verify`, inventory, maintenance, or installation success. The diagnostic uses system Bash 3.2 and built-in macOS commands, filters raw output immediately to an exact field allowlist, and writes only sanitized timestamps, power source, numeric percentages, and derived intervals to its mode-0600 cache. Cache directories are mode 0700; replacements are same-directory atomic renames, and symbolic links are never followed. Unknown files are preserved. See [battery.md](battery.md) and the [JSON schema](battery.schema.json).
+
 Default downloadable desktops are Chrome, ChatGPT and Kiro IDE. Docker Desktop is excluded unless `--with-docker` is explicitly supplied; Claude Desktop and Claude Code CLI use `--with-claude`. `--managed-desktop` alone does not select either optional group. Unselected software is not downloaded, installed, read, repaired, updated, inventoried, or required for verification. Pass the same flag again for reruns, `--verify`, `--configure-only`, and `--check-updates`. Each selected app is inspected independently: a healthy copy of one app suppresses only its own download and never another app's. Missing selected apps get their official DMGs in `~/Downloads/1bite` and a final manual-install reminder. The default install applies the same independent check to Doubao Input Method before preparing its official ZIP; Sogou remains selected only by `--with-sogou` and has a separate check. iTerm2/VS Code remain qualified official casks. Default Kiro CLI invokes its official installer and leaves onboarding/integration to the vendor. See installation.md for the per-app policy.
 
 The default stage count is derived from the current package and extension manifests plus the pinned Neofetch and default Doubao check/preparation stage; `--with-docker` adds one stage, `--with-claude` adds two stages, and `--with-sogou` adds one check/preparation stage. Install mode prepares Python first, then independently preserves an installed Doubao or prepares its ZIP; selected Sogou follows the same separate rule before the remaining package, configuration, onboarding, and final-verification stages. A later failure therefore retains any current-session receipts and prints actionable manual steps. Prepared packages are not installed apps or enabled input sources. `result.json` includes `desktop_mode`, `with_docker`, `with_claude`, and `manual_steps`. During default install only, verification may accept a freshly validated prepared DMG for an absent selected desktop; inventory records `null` plus `pending_applications`. Standalone `--verify` remains strict and fails for absent selected apps. `--managed-desktop --verify` additionally validates managed Kiro hooks. Doubao and optional Sogou always remain manual installations in either desktop policy.