fleet-maintenance

Files (18)

• SKILL.md
• openai.yaml · agents/
• fleet-schema.md · references/
• admin-membership.mjs · scripts/
• agent-cli-audit.sh · scripts/
• agent-skill-links-audit.sh · scripts/
• claude-attribution-audit.sh · scripts/
• fleet-profile.mjs · scripts/
• fleet-profile.test.mjs · scripts/
• global-gitignore-audit.sh · scripts/
• host-health-audit.sh · scripts/
• octopool-audit.sh · scripts/
• op-profile-audit.sh · scripts/
• repo-sync-audit.sh · scripts/
• repo-sync-update.sh · scripts/
• test-agent-cli-audit.sh · scripts/
• test-fleet-profile.sh · scripts/
• test-octopool-audit.sh · scripts/

SKILL.md (first lines)

# Fleet Maintenance

Maintain Peter's Macs while protecting ambiguous local work. Package updates are explicitly allowed during active sessions and may disrupt the software being upgraded. Use `$remote-mac` for inventory/SSH and `$xcode-sync` for all Xcode work.

## Desired state

- Read `~/Projects/manager/fleet/inventory.json` for desired software and local-account escrow references. Read `references/fleet-schema.md` before changing its schema or adopting packages.
- Keep exactly two profiles unless Peter explicitly changes the model:
  - `full`: daily-driver Macs with the complete development, communication, media, and agentic toolset.
  - `worker`: lean remote Macs that mainly run Codex, Claude, OpenClaw nodes, and supporting agent infrastructure.
- Treat profile policy as `minimum`: install required entries and report extras without removing them. Never silently turn observed software into desired state.
- Keep topology, SSH routing, and handed-off status in `~/Projects/manager/computers.yaml`. Do not duplicate live topology in this skill.
- Keep passwords, recovery keys, and private keys in 1Password. The inventory stores opaque item IDs only. Invoke `$one-password` before any `op` command; a `pending` reference is not an error during package maintenance.
- Require the classic OpenSSH mesh named by `ssh_mesh` on both profiles. The manager fleet setup document owns the canonical peer list and live proof. Use the symmetric Tailscale TCP 22 grant plus per-host `authorized_keys`; macOS GUI Tailscale clients cannot act as Tailscale SSH servers. Distribute public keys only, keep private keys host-local, verify both directions with `BatchMode=yes` and a finite timeout, and leave offline or provider-blocked directions pending.
- Require the stable 1Password CLI integrity baseline on every fleet Mac. Require the file-backed service-account profile block unless that host has a documented `requirement_exceptions` security boundary in inventory. Audit eligible hosts with `scripts/op-profile-audit.sh`; audit token-exempt hosts with `scripts/op-profile-audit.sh --cli-only`. Repair only after `$one-password` is loaded and the mode-0600 token file is provisioned; never print or store the token in inventory.
- Require the agent skill mirror on every fleet Mac. Audit it with `scripts/agent-skill-links-audit.sh`; its `--repair` invokes broad canonical sync only when both canonical repos exist. Sync preserves real directories and files, accepting same-directory local ownership and reporting other real destination conflicts. For `reason=nested-self-link`, invoke the reviewed sync owner directly by absolute path with `--repair-nested-self-links --dry-run -- NAME...`, then omit `--dry-run` to remove only validated nested leaves; preserve the real Claude skill directories and Codex backlinks. This narrow loop check is not an exhaustive graph validator. See `references/fleet-schema.md` for scope and `~/Projects/manager/docs/fleet-setup.md` for fleet setup.
- Require the shared global Git ignore on every fleet Mac. Audit it with `scripts/global-gitignore-audit.sh`; `--repair` creates `~/.config/git/ignore`, preserves unrelated entries, adds the inventory's macOS metadata patterns, and points `core.excludesFile` at it. An already-configured alternate excludes file requires manual review so existing rules are never discarded.
- Require Claude Code and Claude Desktop coding sessions to omit AI attribution. Audit `~/.claude/settings.json` with `scripts/claude-attribution-audit.sh`; `--repair` preserves unrelated settings while disabling commit trailers, pull-request footers, and remote-session links.
- Require the official Codex and Claude Code CLIs on both profiles. Package ownership comes from the profile's `codex` and `claude-code` Homebrew casks; the separate `claude` cask is Claude Desktop and does not satisfy the CLI requirement. Audit versions and non-interactive authentication with `scripts/agent-cli-audit.sh`; use `--live` for bounded, tool-free, non-persistent model turns. Never copy normal Claude OAuth credentials between Macs: refresh each host independently through `$anthropic` and leave locked-Keychain, account-selection, or offline cases pending.
- Require Octopool as the GitHub cache on both profiles with `requirements.github_cache: "octopool"`. Package presence alone is insufficient: `scripts/octopool-audit.sh` must prove that non-interactive and login zsh resolve `gh` through the Octopool shim, the client login has complete identity metadata, and every configured pool identity is healthy. Use `--repair` to log in through the existing authenticated stable-path GitHub CLI, install the zsh shim, and repair macOS login PATH ordering when needed; it never installs packages or prints credentials.

Use the deterministic profile tool:

```bash
node skills/fleet-maintenance/scripts/fleet-profile.mjs collect
node skills/fleet-maintenance/scripts/fleet-profile.mjs \
  plan --fleet ~/Projects/manager/fleet/inventory.json \
  --host mac-studio-sf --snapshot /path/to/mac-studio-sf.json
node skills/fleet-maintenance/scripts/fleet-profile.mjs \
  diff --source /path/to/macbook-pro.json --target /path/to/mac-studio-sf.json
node skills/fleet-maintenance/scripts/fleet-profile.mjs \
  brewfile --fleet ~/Projects/manager/fleet/inventory.json --host mac-studio-sf
node skills/fleet-maintenance/scripts/fleet-profile.mjs \
  validate --fleet ~/Projects/manager/fleet/inventory.json
skills/fleet-maintenance/scripts/agent-skill-links-audit.sh
skills/fleet-maintenance/scripts/global-gitignore-audit.sh --host mac-studio-sf
skills/fleet-maintenance/scripts/claude-attribution-audit.sh
skills/fleet-maintenance/scripts/agent-cli-audit.sh
skills/fleet-maintenance/scripts/octopool-audit.sh
skills/fleet-maintenance/scripts/op-profile-audit.sh
```

Collector snapshots are observed evidence, not configuration. Store reviewed snapshots under `~/Projects/manager/fleet/snapshots/<host-id>.json`. `diff` reports source-only candidates; Peter chooses which enter `full`.

## Safety contract

- Read `~/Projects/manager/computers.yaml`; use live Tailscale state and deduplicate hosts by hardware UUID. Exclude handed-off and unknown machines.
- Audit hosts in parallel; mutate one host at a time. Recheck agent activity immediately before every repo or Xcode mutation.
- Skip repositories with a user process cwd inside them or a Git lock. Recent files are audit signal, not a blocker. Permit dirty worktrees only through the conflict-free fast-forward procedure below.
- Homebrew and global npm updates are allowed while agents/services are running. This can mix old in-memory code with replaced files, break later imports or child processes, and let Homebrew terminate/reopen cask GUI apps. Accept that package-update risk; never manually terminate or restart services. Verify health and report interruptions or pending restarts.
- Never reset, clean, stash, rebase, switch branches, delete local work, push, install macOS updates, or reboot during routine maintenance.
- Snapshot role-critical services before package updates. Do not restart OpenClaw gateways or other services unless explicitly authorized; verify them afterward using their owning skill.
- Keep a per-host action log. An unreachable host is pending, never current.

## Run order

1. Resolve the host's `full` or `worker` profile, collect observed inventory, and run package-ownership preflight.
2. Sync eligible repos using the existing Git/toolchain.
3. Update Homebrew and global npm packages on every eligible, reachable host regardless of active agents/services.
4. Verify each host's macOS stable/beta track.
5. Sync Xcode through `$xcode-sync`.
6. Empty Trash only when explicitly requested for this run; perform approved package cleanup.
7. Re-audit disk, tools, package ownership, repos, memory, and role-critical services.

## Preflight

Record hostname, hardware UUID, macOS, architecture, uptime, Tailscale state, selected Xcode, free bytes/percent, Trash size, Homebrew prefix/version, Node/npm versions, running Brew services, active coding-agent processes, and resident-memory outliers:

```bash
node skills/fleet-maintenance/scripts/fleet-profile.mjs collect
skills/fleet-maintenance/scripts/host-health-audit.sh 30
ssh -o RequestTTY=no -o RemoteCommand=none HOST 'node --input-type=module - collect' \
  < skills/fleet-maintenance/scripts/fleet-profile.mjs
ssh -o RequestTTY=no -o RemoteCommand=none HOST 'bash -s -- 30' \
  < skills/fleet-maintenance/scripts/host-health-audit.sh
```

Report every process above 30 GiB resident memory. Do not alert on virtual size alone, sum related processes, or terminate a process automatically. Record PID, resident GiB, user, executable, role, and whether memory remains above the threshold on a second sample.

Classify startup-disk space using both absolute and relative capacity:

- healthy: at least 100 GiB and 15% free
- warning: 50–100 GiB or 10–15% free
- critical: below 50 GiB or 10% free

Do not start Xcode expansion on warning/critical space. Never delete outside Trash, superseded package-manager artifacts, or Xcode paths governed by `$xcode-sync` without explicit approval.

## Repository sync

Run the read-only candidate audit on each host:

```bash
skills/fleet-maintenance/scripts/repo-sync-audit.sh ~/Projects 3
ssh -o RequestTTY=no -o RemoteCommand=none HOST 'bash -s -- "$HOME/Projects" 3' \
  < skills/fleet-maintenance/scripts/repo-sync-audit.sh
```

Apply the audited policy with the bundled updater. It rechecks safety, fetches noninteractively, fast-forwards clean or conflict-free dirty worktrees, and isolates refusals:

```bash
skills/fleet-maintenance/scripts/repo-sync-update.sh ~/Projects 3
ssh -o RequestTTY=no -o RemoteCommand=none HOST \
  '"$HOME/Projects/agent-scripts/skills/fleet-maintenance/scripts/repo-sync-update.sh" "$HOME/Projects" 3'
```

Only process rows marked `candidate`. Recheck branch, upstream, Git locks, and active process cwd immediately before mutation, then:

```bash
git -C "$repo" fetch --prune
git -C "$repo" rev-list --left-right --count HEAD...@{upstream}
```

Run fetches noninteractively and bound each one (for example five minutes). On timeout, authentication failure, or network failure, terminate that fetch, mark the repo pending, and continue. Never let one stale/private mirror stall the host, rewrite its remote, or prompt for credentials during fleet maintenance.

Interpret counts as `ahead behind`:

- `0 0`: current; no action.
- `0 N`: inspect `git log --oneline HEAD..@{upstream}` and `git diff --stat HEAD..@{upstream}`. Record `HEAD` and worktree status. Run `git merge --ff-only --no-autostash --no-overwrite-ignore @{upstream}`. A clean worktree should advance. A dirty worktree may advance only when Git can preserve every local change without overlap; Git refusal means `skip-local-overlap`, not an error to repair. After success, require no unmerged entries, the expected upstream commit at `HEAD`, and all prior local modifications still present. After refusal, require unchanged `HEAD`, no unmerged entries, and unchanged worktree status.
- `N 0` or `N M`: inspect local commit subjects/authors and `git diff --stat @{upstream}...HEAD`; explain likely intent and escalate. Never push or rewrite.

From steipete/agent-scripts, MIT.

More from steipete/agent-scripts