agent-lib/docs/fleet-handoff.md

Fleet handoff — agent-lib v2 rollout

What az-fleet must roll out, and why. This document is written so the fleet team can implement their role from this file alone.

What the binary does (and does not do)

agent-lib is one static Go binary with two roles:

• Curator (maintainer machine): vendor add/update/diff/remove/list/inspect plus validate — manages external content inside the company work repository. Publication = git commit && git push by the maintainer.
• Client (employee machine): sync + status — pulls the work repository and deploys skills/commands/agents into the OpenCode paths. Deploys with three-state protection: user-modified managed items are skipped with a warning (never steamrolled), self-created items are never touched, unmodified items update/remove silently.

The binary handles all content transport itself. It never deploys or merges MCP fragments — mcp/ and external/*/mcp/ stay under controller-side merge and vault substitution (clone the work repository as before, now including the external areas).

Rollout components

1. Binary via pinned GitHub release

• Source of truth: GitHub releases of m3tam3re/agent-lib.
• Artifacts: agent-lib_{windows_amd64,linux_amd64,linux_arm64,darwin_amd64,darwin_arm64} plus checksums.txt (tar.gz archives; windows is a zip).
• Fleet pins an exact release tag (installer-pin pattern already used for other tools). No self-update exists in the binary — binary updates are exclusively fleet rollouts. Content updates are pulled by the binary itself.
• Verify the checksum during rollout; install to a fixed path (e.g. C:\Program Files\agent-lib\agent-lib.exe / /usr/local/bin/agent-lib).

2. Admin-protected client config

Path: C:\ProgramData\agent-lib\config.json (Windows, ACL restricted to Administrators + read for Users) or /etc/agent-lib/config.json (Linux, root-owned, mode 0644).

{
  "repo_url": "https://git.example.com/company/agent-content.git",
  "ref": "main",
  "token": "<read-only deploy token>",
  "token_user": "oauth2"
}

• The token is a shared read-only deploy token scoped to the work repository. It is used for HTTP basic auth only and never appears in the lockfile, the manifest, logs, or error output.
• Employees must be able to read the config (sync runs in their context) but must not be able to alter it.
• Per-run overrides for testing: --config <path> or AGENT_LIB_CONFIG.

Local state (manifest, cached bare repo, sync log) lives per-user: %LocalAppData%\agent-lib on Windows, ~/.local/state/agent-lib on Linux (override with AGENT_LIB_STATE_DIR).

3. Scheduled task — logged-in user context (required)

• Schedule agent-lib sync per user, running as the logged-in user, not SYSTEM. Two reasons:
  1. Deployment targets (~/.agents/skills, ~/.config/opencode/...) resolve against the user's profile.
  2. Windows toast notifications require an interactive user session. A task running as SYSTEM produces no visible toasts.
• Suggested cadence: every 1–4 hours plus/except at logon. Sync is idempotent and cheap when unchanged.
• Optional companion: a drift check running agent-lib status --json headless; its non-zero exit (problematic_drift: true) means a user's local modifications are blocking company updates — feed it into monitoring.

Token rotation procedure

1. Create/rotate the read-only deploy token on the git host.
2. Update token in the admin-protected config via the fleet (single run; config is fleet-managed, so this is one playbook task).
3. No client-side action: the next scheduled sync picks up the new token (config is read on every run). The old token can be revoked once the fleet run completed.
4. A failed sync never damages local state — a revoked token mid-rotation only means "no updates until the config arrives".

ADR draft — superseding the "exact mirror" doctrine

ADR-000X: agent-lib three-state sync supersedes exact-mirror deletion

Status

Proposed (supersedes ADR-0006 "exact mirror including deletion")

Context

The previous fleet doctrine required employee machines to be an exact mirror of the company content repository, including deletions. This steamrolled legitimate local work: employees' own skills and their local adjustments to company skills were destroyed by routine syncs.

agent-lib v2 replaces the mirror sync with a manifest-based three-state sync: a local manifest records every item agent-lib deployed (name, type, origin, revision, content hash), and the planner compares repository, manifest and on-disk content per item.

Decision

1. Managed items that the user modified locally are skipped — the local version wins, a warning is logged and (on Windows) toasted.
2. Items on disk that agent-lib never deployed are unmanaged — left untouched, reported by status as unrecognized.
3. Upstream deletions remove only the unmodified managed copies; modified copies are kept and warned about.
4. Everything else (new, changed-unmodified) updates silently; sync is idempotent and safe to schedule.

Consequences

• Employee machines are no longer exact mirrors by design; drift is visible (status, exit code) instead of silently destroyed.
• "What's in the repo is what I have" holds for everything the user never touched.
• Remediation for blocked updates is a human decision (restore the company version by deleting the local copy and re-syncing), not a forced overwrite.
• The controller-side MCP merge is unaffected: it clones the work repository (now including external/*/mcp/) and continues to own activation, merging and vault substitution.

Verification checklist for the fleet team

• Pinned binary installed, agent-lib version prints the release version.
• Config at the admin-protected path, readable by users, writable only by admins; token present.
• Scheduled task runs as the logged-in user; toast appears when a modified item is skipped (manual visual check on a Windows client).
• agent-lib status exits 0 on a clean machine, non-zero after editing a deployed file (self-test).
• Drift monitoring consumes status --json → problematic_drift.