@tpsdev-ai/flair 0.29.0 → 0.31.0

package/docs/supply-chain-policy.md

@@ -19,13 +19,13 @@ We don't pull in any newly-published dep version for **at least 7 days** after i
 
 #### 1a. Keep-current allow-list
 
-Some deps are tightly coupled to Flair's runtime correctness — Harper bug fixes and security patches land in `@harperfast/harper`, embedding-pipeline fixes land in `harper-fabric-embeddings`. We accept the bake-time risk and pull these eagerly. Current allow-list:
+Some deps are tightly coupled to Flair's runtime correctness — Harper bug fixes and security patches land in `harper`, embedding-pipeline fixes land in `harper-fabric-embeddings`. We accept the bake-time risk and pull these eagerly. Current allow-list:
 
 | Package | Why kept current |
 |---------|------------------|
-| `@harperfast/harper` | Foundational. Vector-index and HNSW correctness fixes land here; we want them ASAP. High-volume upstream, fast detection if compromised. |
+| `harper` | Foundational. Vector-index and HNSW correctness fixes land here; we want them ASAP. High-volume upstream, fast detection if compromised. **Bare name, not `@harperfast/harper`** — the two are permanent lockstep publishes of the same source, and depending on the scoped one made every install materialise both copies (~213 MB), because `@harperfast/oauth` peers on the bare name and npm cannot dedupe across two names. Aligned in flair#870. |
 | `harper-fabric-embeddings` | Embedding model loader. Coupled to Harper version. Same trust-and-volume reasoning. |
-| `@harperfast/oauth` | Same high-trust `@harperfast/*` owner as `@harperfast/harper`. Used ONLY by the **default-OFF** native-MCP OAuth surface (`FLAIR_MCP_OAUTH`), which dynamically imports it only when the flag is on — it is **not loaded in the shipped default build**, so bake-time exposure is zero until an operator explicitly opts in. Pinned to the exact version whose `withMCPAuth` API the surface was built against; the API surface (not a floating range) is what we depend on. |
+| `@harperfast/oauth` | Same high-trust upstream owner as `harper`. Used ONLY by the **default-OFF** native-MCP OAuth surface (`FLAIR_MCP_OAUTH`), which dynamically imports it only when the flag is on — it is **not loaded in the shipped default build**, so bake-time exposure is zero until an operator explicitly opts in. Pinned to the exact version whose `withMCPAuth` API the surface was built against; the API surface (not a floating range) is what we depend on. |
 
 Adding to this list is a deliberate decision. The bar:
 - The upstream is well-known and high-volume (gets eyeballs fast).
@@ -41,6 +41,9 @@ Override per-run via `FLAIR_DEP_KEEP_CURRENT="pkg1,pkg2,@scope/pkg3"` env (addit
 Every `dependencies` entry in any `package.json` must be a single concrete version (`"5.0.9"`), not a range (`"^5.0"`, `"~5.0.9"`, `">=5"`). Range specifiers expose us to silent supply-chain swaps every install — exactly the surface attackers exploit.
 
 - `peerDependencies` may use ranges (host-provided; never installed by us). `devDependencies` are also exact-pinned for build reproducibility, though they don't ship in our published tarballs.
+- **Flair declares no optional peers today**, and no `optionalDependencies` at all. If either is ever proposed as an install-weight fix, the mechanism has now been measured twice (`@harperfast/oauth` flair#750, `node-llama-cpp` flair#887) and the result is counter-intuitive enough to be worth stating: **only `peerDependencies` + `peerDependenciesMeta.optional` is skipped by a default install** (npm and bun alike). A plain `optionalDependencies` entry *is* still installed by default — "optional" there means "a failed install is non-fatal", not "skipped" — so it buys no install-weight reduction whatsoever. Exact-pinning an optional peer (rather than ranging it) is also legitimate where the consuming code path is version-sensitive, so that an operator who installs a different version gets told the version they have is not the version that was tested.
+
+  Note the corollary, measured during flair#893: an optional peer that is simply *absent* installs silently — npm prints no warning at all — so it cannot be relied on to prompt anyone to install it. Anything a user must install for a feature to work needs to be documented, or detected and reported at runtime.
 - `bun.lock` is committed and frozen-lockfile installed in CI. Any unintended dep drift fails the workspace-deps consistency gate.
 - Pin updates happen via deliberate, test-gated PRs — never auto-merged. **Renovate is enabled** (`.github/renovate.json`) to *propose* these updates on a schedule, but it respects the bake-time cooldown (`minimumReleaseAge: "7 days"`, matching `FLAIR_DEP_MIN_AGE_DAYS`) and opens PRs only — `automerge` is off, so every bump flows through the full test suite + K&S review. Renovate uses `rangeStrategy: "pin"` so it proposes exact-version bumps (never re-widens to ranges) and shares the keep-current allow-list with `check-dep-ages.mjs`. Vulnerability alerts bypass the cooldown so security fixes aren't delayed.
 
@@ -69,13 +72,46 @@ Only Nathan publishes to npm (per the existing MFA boundary). Flint preps the re
 - The build host is not logged into npm by design.
 - A planned post-publish smoke job will add an automated round-trip check after each publish to ensure cross-package resolution works on the actually-published artifacts.
 
+### 7. Dependency audit gate: blocking, with dated exceptions
+
+`bun audit` runs on every PR via the `audit` job and **blocks merge**. Every advisory it reports must either be fixed or appear in `.github/audit-allowlist.json`. There is no third option and no global escape hatch.
+
+This replaced a step that could not fail:
+
+```yaml
+run: bun audit || echo "::warning::Audit found vulnerabilities — all in harper transitive deps (unreleased v5 build)"
+continue-on-error: true
+```
+
+Both mechanisms independently forced a pass (`|| echo` made the shell exit 0, so `continue-on-error` was dead config that never even fired). The justification was accurate the day it was written. It carried **no expiry**, so it outlived its reason — by the time it was removed, "all in harper transitive deps" was false, and a critical advisory was reaching users through a first-party workspace package while the gate reported green.
+
+**The defect was the unexpirable exception, not the exception.** Some advisories genuinely cannot be fixed from this repo. So each one is now enumerated with:
+
+| field | meaning |
+|---|---|
+| `ghsa` | the published advisory id |
+| `package`, `severity` | re-verified against `bun audit` on every run; drift fails the gate |
+| `class` | `no-patch-published`, `vendor-pinned`, or `remediation-available` |
+| `introducedBy` | the dependency edge that pulls it in |
+| `reason` | why it cannot be fixed here, specifically |
+| `added`, `expires` | hard dates; lifetime is capped by severity |
+| `removeWhen` | the concrete condition that retires the entry |
+
+`scripts/audit-gate.mjs` fails the build on: an unlisted advisory, a malformed entry, an entry parked beyond its severity cap (critical 30 days, high 60, moderate/low 180), an **expired** entry, a **stale** entry whose advisory no longer appears, or a `no-patch-published` entry for which a patched version has since shipped. That last pair matters — an allowlist that only ever grows is the same failure with more ceremony.
+
+When an entry expires the build fails and a human re-decides. **That is the mechanism working, not a flaw.** Re-dating an entry without re-reading its reason is how this file rots back into the thing it replaced.
+
+Run it locally with `node scripts/audit-gate.mjs --explain`.
+
+**Standing rule for every check in this repo:** any check that is advisory-only must carry, in a comment at its own definition, what would make it blocking and when that gets re-evaluated. Advisory is a terminating state with a defined promotion event, never a resting place.
+
 ---
 
 ## Automation
 
 ### `.github/renovate.json` — deliberate, cooldown-gated update proposals
 
-Renovate opens PRs to propose dependency updates so we don't drift behind upstream indefinitely — but on our terms, not the registry's. It is configured to never auto-merge (`automerge: false`), to pin (`rangeStrategy: "pin"`, consistent with §2), and to respect the bake-time cooldown (`minimumReleaseAge: "7 days"`, matching `FLAIR_DEP_MIN_AGE_DAYS` in `check-dep-ages.mjs`) so it only proposes versions that have already cleared the detection window. Non-major updates are grouped; majors land as isolated PRs. The keep-current allow-list (`@harperfast/harper`, `harper-fabric-embeddings`, `@harperfast/oauth`) mirrors the script's `DEFAULT_KEEP_CURRENT` — keep the two in lockstep when either changes. Vulnerability alerts bypass the cooldown. Every Renovate PR still runs the full CI suite (including the bake-time and workspace-deps gates) and is K&S-reviewed before merge.
+Renovate opens PRs to propose dependency updates so we don't drift behind upstream indefinitely — but on our terms, not the registry's. It is configured to never auto-merge (`automerge: false`), to pin (`rangeStrategy: "pin"`, consistent with §2), and to respect the bake-time cooldown (`minimumReleaseAge: "7 days"`, matching `FLAIR_DEP_MIN_AGE_DAYS` in `check-dep-ages.mjs`) so it only proposes versions that have already cleared the detection window. Non-major updates are grouped; majors land as isolated PRs. The keep-current allow-list (`harper`, `harper-fabric-embeddings`, `@harperfast/oauth`) mirrors the script's `DEFAULT_KEEP_CURRENT` — keep the two in lockstep when either changes. Vulnerability alerts bypass the cooldown. Every Renovate PR still runs the full CI suite (including the bake-time and workspace-deps gates) and is K&S-reviewed before merge.
 
 ### `scripts/check-workspace-deps.mjs` (already shipped, PR #368)
 

package/docs/troubleshooting.md

@@ -173,6 +173,30 @@ flair doctor    # check for issues
 
 **Fix:** Either rephrase the content to avoid injection patterns, or switch to default mode (remove `FLAIR_CONTENT_SAFETY=strict` from environment). In default mode, flagged content is stored but tagged — not rejected.
 
+### "no writable migration data directory" / migrations reported failed
+
+**Symptoms:** `flair doctor` reports every migration `failed` with a "no writable migration data directory" reason, and the instance log carries a matching `[flair-migrations]` line naming each path it tried.
+
+**Cause:** flair keeps its migration bookkeeping (`.migrations/state.json`, the single-flight lock, and risk-scoped snapshots) in a directory alongside the instance's data — by default `~/.flair/data`, falling back to Harper's root path. On a provisioned install (a service-managed unit, a container, a component deployment) the account the process runs as may have a home directory it cannot write to, and if none of the candidates is usable there is nowhere safe to snapshot before a migration writes.
+
+**Fix:** point `FLAIR_MIGRATION_DATA_DIR` at a writable directory and restart, or make one of the paths named in the error writable by the account the instance runs as:
+
+```bash
+export FLAIR_MIGRATION_DATA_DIR=/var/lib/flair   # add to the service unit / launch script to persist
+flair restart
+flair doctor                                     # migrations should now report completed
+```
+
+Migrations are boot-keyed, so the next start runs the cycle and clears the finding. Nothing is lost while this is unresolved — a migration that cannot snapshot refuses to run rather than writing unprotected.
+
+### "Migration boot cycle never fired on this instance"
+
+**Symptoms:** `flair doctor` reports the boot cycle never fired, and `/HealthDetail` shows `migrations.cyclePhase: "idle"`.
+
+**Cause:** the trigger that schedules the migration cycle registers itself at boot, so `idle` means the running build's `dist/resources/migration-boot.js` never loaded — usually a partial or interrupted install rather than a runtime failure.
+
+**Fix:** reinstall flair (`npm install -g @tpsdev-ai/flair`) and restart, then check the instance log for `[flair-migrations]` lines, which name any error raised while the trigger was loading.
+
 ## Getting Help
 
 ```bash

package/docs/upgrade.md

@@ -50,13 +50,25 @@ actually running:
   stage the new packages without bouncing the process yet (the old
   opt-in `--restart` flag still parses but is now a no-op — restart is the
   default).
+- **The restart runs through the newly installed CLI** (flair#905), not the
+  process that did the installing. Only version N's own code knows how version
+  N starts — spawn arguments, required environment, config templates and the
+  Harper dependency's own package name are all things a release may change, and
+  the pre-swap process would get every one of them wrong the same silent way.
+  The output names the CLI it handed the restart to. If that CLI can't be found
+  or its version can't be confirmed, the upgrade says so and restarts in-process
+  rather than refusing to start anything.
 - **Post-restart verification** (skip with `--no-verify`) confirms the
   restarted instance answers `/Health`, that an authenticated request
   round-trips, and that the reported running version matches what was just
   installed.
-- **On verification failure**, `flair upgrade` automatically reinstalls the
-  previously-running `@tpsdev-ai/flair` version, restarts again, and
-  re-verifies — then exits nonzero with a clear report of what failed. If the
+- **On a failed restart OR a failed verification**, `flair upgrade`
+  automatically reinstalls the previously-running `@tpsdev-ai/flair` version,
+  restarts again, and re-verifies — then exits nonzero with a clear report of
+  what failed. Until flair#905 the rollback was wired to the *verification* leg
+  only: an upgrade that installed new packages and then failed to start them
+  exited 1 and left the operator on the new version with nothing running, which
+  is the single outcome this transaction exists to prevent. If the
   rollback itself fails verification, it says so loudly and points at the
   concrete pre-upgrade snapshot path (see "Pre-upgrade snapshot" below)
   instead of retrying in a loop — see [Downgrade](#downgrade) for the
@@ -177,7 +189,7 @@ FABRIC_USER=<admin> FABRIC_PASSWORD=<pass> \
 (or `--fabric-password-file <path>` instead of the `FABRIC_PASSWORD` env var — reads the
 password from a file, chmod 600). This resolves the target version (latest published
 `@tpsdev-ai/flair`, or pin one with `--version`), stages a clean deployable with the
-required `@harperfast/harper` version pin applied (`--harper-version` to override),
+required `harper` version pin applied (`--harper-version` to override),
 confirms the staged Harper build before deploying, then reuses `flair deploy` to push it
 and verifies the result. `--check` shows the version diff and plan without deploying
 anything; `--yes` skips the confirmation prompt for scripted use.
@@ -223,7 +235,7 @@ Exit codes:
 *Flair's own* federation peer table, not Harper Fabric's own cluster-replication
 nodes. Harper's `cluster_status` operation (the one that would answer "what nodes are
 in this cluster and are they in sync") is harper-pro-only and unavailable in the OSS
-`@harperfast/harper` build this CLI ships — there is no way for this CLI to enumerate
+`harper` build this CLI ships — there is no way for this CLI to enumerate
 Fabric's own replication topology, on the origin or anywhere else. A Fabric replica
 that was never separately paired as a Flair federation peer (`flair federation pair`)
 is invisible to this sweep: `0 peers known` means "0 peers on file," never "0 peers
@@ -233,6 +245,56 @@ dropped, never shown green. The sweep also needs Basic-auth credentials
 `--fabric-user`/`--fabric-password`) to authenticate each peer probe; a token-only
 (`--fabric-token`) deploy skips it with a note instead of a silent no-op.
 
+### Peer-replication errors are not verdicts
+
+Harper replicates a deployed component to its cluster peers **asynchronously**, so
+`harper deploy` can exit non-zero with
+
+```
+Component 'flair' was deployed on the origin node but failed to replicate to 1 of 1
+peer node(s): <peer> (Error: Connection closed 1006)
+```
+
+for a deploy that then converges on its own moments later. That error describes one
+instant, not an outcome.
+
+Both `flair deploy` and `flair upgrade --target` therefore **check before they
+declare**. On that error the CLI reads the peer node names out of Harper's own
+message, polls each node's component file tree (`get_components` — path, size and
+mtime), and compares it against the origin's. If every named peer converged, the
+deploy is reported as a **success**, with a line saying that Harper's error resolved:
+
+```
+⚠ harper reported a peer-replication failure, but every named peer node's component
+  tree matched the origin when checked afterwards — replication converged on its own.
+```
+
+Convergence is only ever claimed on positive evidence. A peer whose name is not an
+addressable host, whose hostname does not resolve, which cannot be reached, which
+reports no such component, or which currently resolves to the *same address as the
+deploy target* (a Fabric cluster endpoint is steered to one member node, so that
+comparison would be a node against itself) is reported as unverified — never as
+converged.
+
+| Flag | Effect |
+|------|--------|
+| `--convergence-timeout <ms>` | How long to wait for replication to converge before reporting failure (default `180000`) |
+| `--no-convergence-check` | Skip the poll and fail on Harper's error verbatim |
+| `--ignore-replication-errors` | Accept an origin-only deploy when replication has not converged; the peer catches up via federation sync or a later deploy |
+| `--deploy-retries <n>` | Retry the full deploy when replication is *observed* not to have converged (default `0`) |
+
+**`--deploy-retries` defaults to `0`, deliberately.** A retry re-runs the whole
+deploy, including Harper's own `npm install` into the component directory on every
+node, and a real upgrade died that way — `ENOTEMPTY` on a native module, on the
+*retry*, for a deploy whose peers had already converged. Retrying was compensating
+for the absence of a convergence check; the poll above covers that window without
+touching the cluster. When retries are enabled they are gated twice: only on
+positively observed non-convergence, and only once the origin's component tree has
+stopped changing across consecutive reads. If a retry does still fail differently
+from the original error, the CLI reports the **original** failure as the headline and
+labels the later one as a consequence of retrying — a retry can never change what the
+failure is reported to be.
+
 ## Re-embedding after an upgrade
 
 Two situations require a re-embed pass, and `flair doctor` will flag both:
@@ -345,6 +407,39 @@ reason as above: the restart is performed by the *old*, already-installed CLI.
 - If you already hit it (upgrade "finished" but the server is down): run
   `flair start` — not `restart` — and you're on the new version. Nothing was lost.
 
+### Known issue — upgrading *from* 0.29.0 stops with a false "Harper binary not found"
+
+0.30.0 renamed its Harper dependency from `@harperfast/harper` to the bare
+`harper` package (flair#870, a real ~104 MB saving — the two names are the same
+engine and no package manager can dedupe across them). `flair upgrade` replaces
+the package tree *while the CLI is executing out of it*, and 0.29.0's restart
+step only ever probes the old name — so once the swap lands, the name it is
+looking for is genuinely gone:
+
+```
+Restarting Flair...
+Stopping...
+Starting...
+❌ restart failed: Harper binary not found. Run 'flair init' first.
+   Flair may be partially down. Check: flair doctor
+```
+
+The error is false twice over. The install is complete and Harper is present
+under its new name; and `flair init` is the wrong remedy — on an initialised
+instance it is not what you want to reach for, and it could not have fixed a
+missing binary anyway.
+
+**Workaround when upgrading from 0.29.0:** run `flair start`. The new version is
+installed and correct; only the old CLI's restart step failed. `flair status`
+should then report 0.30.0 and healthy. Nothing was lost — the upgrade never
+touches `~/.flair/data`.
+
+Forward-only, for the same reason as the two issues above: the code that
+performs the restart is the version you are upgrading *from*. From flair#905
+onward the restart is handed to the newly installed CLI and the Harper package
+name is read from the post-swap `package.json` instead of being compiled in, so
+a future dependency rename cannot reproduce it.
+
 ## Downgrade
 
 Rolling back the **package** (above) assumes the data on disk is fine — only the new

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.29.0",
+  "version": "0.31.0",
   "packageManager": "bun@1.3.10",
   "description": "Identity, memory, and soul for AI agents. Cryptographic identity (Ed25519), semantic memory with local embeddings, and persistent personality — all in a single process.",
   "type": "module",
@@ -56,26 +56,16 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@harperfast/harper": "5.1.22",
     "@harperfast/oauth": "2.4.0",
     "@types/js-yaml": "4.0.9",
     "commander": "14.0.3",
+    "harper": "5.1.22",
     "harper-fabric-embeddings": "^0.5.0",
     "jose": "6.2.2",
-    "js-yaml": "4.1.1",
-    "node-llama-cpp": "3.18.1",
-    "tar": "7.5.13",
+    "js-yaml": "4.3.0",
+    "tar": "7.5.20",
     "tweetnacl": "1.0.3"
   },
-  "optionalDependencies": {
-    "@node-llama-cpp/linux-arm64": "3.18.1",
-    "@node-llama-cpp/linux-armv7l": "3.18.1",
-    "@node-llama-cpp/linux-x64": "3.18.1",
-    "@node-llama-cpp/mac-arm64-metal": "3.18.1",
-    "@node-llama-cpp/mac-x64": "3.18.1",
-    "@node-llama-cpp/win-arm64": "3.18.1",
-    "@node-llama-cpp/win-x64": "3.18.1"
-  },
   "overrides": {
     "react-native-fs": "npm:empty-npm-package@1.0.0"
   },

package/schemas/memory.graphql

@@ -188,7 +188,15 @@ type MemoryUsage @table(database: "flair") {
 # that requires both --rationale and --to (soul|memory). Rejected candidates
 # retain their decision history so recurring false-positives become visible
 # via the `supersedes` chain.
-type MemoryCandidate @table(database: "flair") {
+#
+# flair#849: this type shipped WITHOUT @export, so it had no REST surface at
+# all — `flair rem candidates`/`promote`/`reject` 404'd on every call, a
+# clean-room dogfood blocker. @export alone would have reopened the exact P0
+# leak the memory-soul-read-gate family fix closed for every other
+# agent-facing table (anonymous read/write of every row); see
+# resources/MemoryCandidate.ts for the paired identity-gated, owner-scoped
+# resource class that makes @export here safe.
+type MemoryCandidate @table(database: "flair") @export {
   id: ID @primaryKey
   agentId: String! @indexed
   claim: String!                   # distilled lesson text

package/templates/bin/flair-federation-sync.sh.tmpl

@@ -0,0 +1,28 @@
+#!/bin/sh
+# Flair federation sync driver shim.
+# Deployed by `flair federation sync enable` to {{SHIM_PATH}}.
+# Invoked by launchd (macOS) or systemd (Linux) every {{INTERVAL_SECONDS}}s.
+#
+# One-shot by design: every run is a fresh, fully bounded process. See
+# src/federation/scheduler.ts for why this is a periodic one-shot rather than
+# a supervised long-lived watcher.
+#
+# The admin password is NEVER written into the scheduler unit. The unit
+# carries FLAIR_ADMIN_PASS_FILE — a PATH — and the CLI reads the file itself
+# through readAdminPassFileSecure(), which refuses anything not owner-only.
+# Passing the path (not the value) also keeps it out of `ps`.
+#
+# Logs land in {{HOME}}/.flair/logs/federation-sync.{stdout,stderr}.log.
+set -e
+
+if [ -n "${FLAIR_TARGET:-}" ]; then
+  set -- --target "${FLAIR_TARGET}"
+else
+  set --
+fi
+
+if [ -n "${FLAIR_ADMIN_PASS_FILE:-}" ] && [ -f "${FLAIR_ADMIN_PASS_FILE}" ]; then
+  set -- "$@" --admin-pass-file "${FLAIR_ADMIN_PASS_FILE}"
+fi
+
+exec "{{FLAIR_BIN}}" federation sync "$@"

package/templates/launchd/dev.flair.federation.sync.plist.tmpl

@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>dev.flair.federation.sync</string>
+
+  <key>ProgramArguments</key>
+  <array>
+    <string>{{SHIM_PATH}}</string>
+  </array>
+
+  <!-- Periodic one-shot. NOT KeepAlive: the sync carries no state between
+       runs, and KeepAlive restarts a process that exits while doing nothing
+       for one that hangs. See src/federation/scheduler.ts. -->
+  <key>StartInterval</key>
+  <integer>{{INTERVAL_SECONDS}}</integer>
+
+  <!-- Sync once as soon as the job is loaded, so `enable` visibly works
+       instead of leaving the operator waiting out a whole interval. -->
+  <key>RunAtLoad</key>
+  <true/>
+
+  <key>StandardOutPath</key>
+  <string>{{HOME}}/.flair/logs/federation-sync.stdout.log</string>
+
+  <key>StandardErrorPath</key>
+  <string>{{HOME}}/.flair/logs/federation-sync.stderr.log</string>
+
+  <key>WorkingDirectory</key>
+  <string>{{HOME}}</string>
+
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>HOME</key>
+    <string>{{HOME}}</string>
+    <key>PATH</key>
+    <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
+    <!-- A PATH to the password file, never the password. -->
+    <key>FLAIR_ADMIN_PASS_FILE</key>
+    <string>{{ADMIN_PASS_FILE}}</string>
+    <key>FLAIR_TARGET</key>
+    <string>{{FLAIR_TARGET}}</string>
+  </dict>
+</dict>
+</plist>

package/templates/systemd/flair-federation-sync.service.tmpl

@@ -0,0 +1,21 @@
+[Unit]
+Description=Flair federation sync (one-shot, driven by flair-federation-sync.timer)
+After=network-online.target
+
+[Service]
+# Type=oneshot, not a Restart=always long-lived watcher: the sync carries no
+# state between runs, and every network call inside it is bounded by its own
+# timeout, so a run always terminates and the timer always gets to fire the
+# next one. See src/federation/scheduler.ts.
+Type=oneshot
+ExecStart={{SHIM_PATH}}
+# A PATH to the password file, never the password.
+Environment=FLAIR_ADMIN_PASS_FILE={{ADMIN_PASS_FILE}}
+Environment=FLAIR_TARGET={{FLAIR_TARGET}}
+StandardOutput=append:{{HOME}}/.flair/logs/federation-sync.stdout.log
+StandardError=append:{{HOME}}/.flair/logs/federation-sync.stderr.log
+
+# No [Install] section: this unit is started by flair-federation-sync.timer,
+# which is what `flair federation sync enable` enables. A WantedBy here would
+# only invite someone to enable the service directly and get exactly one sync
+# per boot.

package/templates/systemd/flair-federation-sync.timer.tmpl

@@ -0,0 +1,16 @@
+[Unit]
+Description=Flair federation sync timer (every {{INTERVAL_SECONDS}}s)
+
+[Timer]
+# Sync shortly after the timer starts (enable, and every boot thereafter), so
+# `enable` visibly works instead of leaving the operator waiting out a whole
+# interval. The launchd side gets this from RunAtLoad.
+OnActiveSec=10s
+# Then repeat, measured from the END of the previous run — a slow sync delays
+# the next one rather than overlapping with it.
+OnUnitActiveSec={{INTERVAL_SECONDS}}s
+AccuracySec=30s
+Unit=flair-federation-sync.service
+
+[Install]
+WantedBy=timers.target