v0.60.0

Added

• flair keys prune and flair doctor report node-shaped orphan candidates without removing them. (#2200, #1925)

• flair hook install --action-recall copies a version-matched Claude Code Bash recall hook to Flair-owned storage. (#2067)

• flair hook install --capture wires Claude Code PostToolUseFailure, PostToolUse and Stop hooks that stage command follow-ups and cue-matching sentences as candidate memories (flair#2068). (#2068)

  Heads-up: the hook is copied to ~/.flair/hooks/capture/<version>-<hash>/
  at install time. Re-run the installation after upgrading @tpsdev-ai/flair
  so the copy matches the running version.

• The MCP client-assertion signer can use the issuer audience (RFC 7523bis), behind a switch.

• flair principal disable and enable accept --instance (or FLAIR_URL) for a remote principal (#2114). (#2114)

• flair principal link maps one IdP login to a principal; unlink revokes a mapping; links lists current mappings.

• Retained skill payloads, _reindex, the seed lineage and org skill references now honour slice 2's history rules.

  Heads-up: an update that tightens a skill to private now also revokes
  read access to its predecessor's retained payload through Memory GET/search
  and the Feed replay, not only through the version read.

• InstructionVersion reads now authorize skill subjects under Memory's owner/non-private rule.

• Transactional skill versions for Memory and FeedMemories.

• Single-row Soul resource writes append history; Soul collection deletes are refused.

• Team directory lists active agents with published tps-mail contacts. (#2141)

• Flair seeds an org-wide using-flair skill (flair#2141). (#2141)

• flair integrity check alerts on unexplained loss of checkpointed durable Memory IDs or their nonempty tokens (Closes #2213). (#2213)

• Check declared direct root override keys matching workspace dependencies, devDependencies or optionalDependencies in CI and staged manifests in pre-commit. (#2301)

• Bridge plugin tests exercise the published Node CLI shim and Bun. (#2308)

Changed

• Updates harper from 5.2.8 to 5.3.1.

  Heads-up: A data directory upgraded to Harper 5.3 must not be served
  by an older flair. The only full rollback is restoring the pre-upgrade physical
  data-directory snapshot (flair snapshot restore <path>). flair backup/restore
  logically exports/imports only Agent, Memory and Soul rows through a running
  server; it can transfer those rows into a fresh compatible instance.

• Shard the shared unit lane across CI jobs.

• Team directory entries include a nullable homeInstanceId; Integration.patch answers 404 for an absent row. (#2322)

• Test pause points no longer share a union list.

• Updates @harperfast/oauth from 2.5.0 to 2.9.0, which can admit an interactive Client ID Metadata Document client that authenticates with private_key_jwt: that needs the client's host in mcp.clientIdMetadataDocuments.allowedHosts and, unless the headless client_credentials grant is enabled, mcp.clientIdMetadataDocuments.privateKeyJwt.enabled: true (the shipped config.yaml lists claude.ai and claude.com and leaves privateKeyJwt off).

Fixed

• CLI record paths encode IDs as one path segment (#1970). (#1970)

• Launchd stop verifies the recorded process exited before attempting stale-sidecar cleanup (#2075). (#2075)

• flair-session-start and flair-continuity-capture start from a path that contains a space, or from a symlinked bin, on Node before 22.18. (#2083)

• flair init validates the launchd plist it writes when there is no legacy job to migrate (Closes #2085). (#2085)

• flair bridge import now declares --user, --base-url and --api-key-file.

  Heads-up: set MEM0_API_KEY or pass --api-key-file <path> (no group/world permissions; chmod 600 recommended). An explicitly empty or invalid --base-url is refused before a request, and API failures do not print response bodies or pagination URLs.

• flair agent list/rotate-key warnings give a history-safe FLAIR_ADMIN_PASS remedy, and flair deploy's next step names agent add --target (#2123, #2124). (#2123, #2124)

• flair principal disable and enable refuse an id with no row by name before writing.

• The release workflow's stage-shell test cases run on macOS when GNU find (gfind) is on PATH. (#2136)

• Unit lane runs under a short, canonical temp root on macOS (#2137). (#2137)

• Downgrade refusal is conditional (flair#1047). (#1047)

• POST /MemoryPurge confirms pointer-row removal through its own transaction, so a purge on Harper 5.3 no longer returns a false 500.

• Use a consistent Linux process start second while boot time is unchanged and the host tick rate is known.

• flair mcp enable supports custom-domain Fabric targets with --fabric. (#2189)

• flair mcp enable stops before the restart when its local configuration update fails, exits non-zero, and says to fix the reported cause and re-run. (#2193)

• The shipped config.yaml leaves mcp.signingKeyPem unpinned.

• Local flair init --skip-start installs Harper without starting it.

• flair doctor --fix reports a direct Harper process not observed to exit during launchd adoption (Closes #2205). (#2205)

• Durability docs now state what each tier does and does not guarantee (flair#2217). (#2217)

• The unit lane's whole-lane time budget rises from 510 s to 780 s.

• Restore verifies a restored Memory or Soul row's preserved content, not only its ID and owner. (#2226)

• flair status: the expired-validTo warning is grouped by agent (#2231)

• Shard the root unit step by file.

• Skill creates at /Memory/<id> use that id when the body id is absent or null; the feed refuses reserved seed ids.

• Action-recall and learning-capture installation preserve shared group matchers when moving recognized commands into dedicated groups.

• Local upgrade can stage a missing GitHub OAuth redirect from configured MCP issuer and credentials.

• flair principal disable and enable treat a principal with no stored status as active. (#2272)

• Reading instruction-version history applies the read scope before Harper pages and projects. (#2273)

• Memory maintenance acts on the row it re-reads, not the scan-time copy (Closes #2275). (#2275)

• Successful Soul PUT/PATCH identity changes close the old history window; occupied destinations return 409 soul_subject_occupied.

• Refused migration-directory links now report their configured path, resolved target when available, and remedy. (#2277)

  Heads-up: for a link to a directory, only after verifying that the target is dedicated to this Flair instance and safe to relocate, stop Flair, remove the link, move its target to the configured path and start Flair. If ownership is uncertain, leave the target in place: for a linked data directory, set FLAIR_MIGRATION_DATA_DIR to the real directory path instead of the link and restart; for a linked .migrations child, configure a different data directory with an unlinked .migrations child. For a dangling link or a link to a file, replace the link with a writable directory.

• A stub Harper started by the launchd-2040 test now exits once the test process that started it is gone. (#2281)

• Failed adoption after a confirmed process exit attempts restoration and reports its outcome. (#2284)

• Unit-file discovery and the lane coverage gate share one predicate for the names Bun's runner discovers (#2288). (#2288)

• flair agent remove and flair memory hygiene --apply use the physical purge path for skill-tagged Memory rows (Closes #2290). (#2290)

• flair init re-pins a stale SessionStart hook, and flair hook status reports it.

• The bridge docs say plugin import options are a null-prototype record (flair#2293). (#2293, #2257)

• flair reembed changes only embedding, embeddingModel and updatedAt; other stored fields are kept (#2296). (#2296)

• An operator's collection DELETE on Integration now removes the matched rows.

• The process liveness probe reports an exited-but-unreaped process (a zombie) as exited.

• The Node CLI loads npm bridge plugins from their entry files. (#2315)

• The capture flush bounds its asynchronous setup and each write with one deadline (flair#2321). (#2321)

• flair reembed refuses before its first write when the server does not advertise the re-embed PATCH.

• The unit lane checks wholly omitted packages with recognized test filenames and missing matrix shard indices.

• flair start can recover an UNKNOWN state with an exited recorded owner (Refs #2350). (#2350)

• flair agent remove fails when the agent's Soul rows cannot be confirmed gone, instead of reporting a completed removal (Closes #2351). (#2351)

• Direct-process restarts probe through the stop deadline and refuse replacement after an unconfirmed stop.

• One agent-ID rule now guards the paths that create an Agent (#2359). (#2359)

• A Soul PATCH checks raw changes visible at its confirmation read.

• Human-readable flair principal show and principal list output reports a principal's status the way the auth gate reads it (flair#2378). (#2378)

• The hook-status probe ignores HUP/INT/QUIT/TERM in its group pin before forking it, so the probe's own SIGTERM cannot kill the pin. (#2385)

• The bake-time gate now age-checks non-exempt exact versions pinned through overrides (#2389)

• A re-embed PATCH now writes from the row it re-reads after the vector resolves (#2390). (#2390)

• Stop paths attempt sidecar cleanup using the PID their exit probe observed gone. (#2391)

• A failed-tool append waits up to 2 seconds for the capture lock. (#2395)

• The listed test fixtures publish content-read signals through a shared helper using a temp file and rename (#2397). (#2397)

• Memory writes redact recognized credential shapes server-side, and the write response reports how many values were replaced. (#2407)

• CLI-managed launchd starts write identity sidecars only for confirmed processes (flair#2411). (#2411)

• The isolated init admin-credential fixtures explicitly set the PID-file and open-mode saved-password permissions after creation. (#2412)

• REM nightly: a missing generative backend alone no longer fails the run (#924, #1503, #809)

• The action-recall deadline tests allow more setup time (#2303). (#2303)

• One v* release tag now starts the adk-flair PyPI workflow alongside npm staging. (#2206)

  Heads-up: Add v* to the adk-flair-publish environment's deployment tag policy, keeping adk-flair-v* and the required reviewer.

• flair backup rejects failed or non-array reads, missing, blank, non-string or duplicate IDs, and mismatched Memory or Soul ownership before publishing an archive. (#2214)

• Unfiltered flair backup includes Memory/Soul rows whose owner has no Agent row and checks received totals against exact whole-table storage counts. (#2228)

  Heads-up: Concurrent deletes can cause a count mismatch; pause writers and maintenance, then retry the backup.

• Feed-written ephemeral memories without an explicit expiry now get the tier TTL. (#2274)

• The feed replay test polls after expiring a successor (#2316). (#2316)

• Fix hook-status probe cleanup outside Windows (#2385)

• POST /MemoryArchive answers a refused basement or restore with the refusal's own HTTP status and named error, not HTTP 200.

• Restore fails on write errors or unconfirmed archived IDs. (#2215)

Security

• flair-client adds an asynchronous, size-bounded key loader; continuity capture redacts additional credential formats (#2086). (#2086)

• For npm-install vendor-pinned findings, the audit gate verifies locations and installed versions and refuses unverifiable evidence.

• Identity mapping honors the caller’s operations target, refuses noncanonical target origins before requests, and redacts target diagnostics. (#2102)

• OAuth authorization codes and refresh tokens are single-use across workers of one instance (flair#2145). (#2145)

• flair mcp enable refuses noncanonical targets before writes.

• flair mcp enable requires public discovery metadata to advertise the exact MCP token endpoint and refuses a mismatch.

• Memory, Feed, and bridge writes enforce the reserved content-property ID restriction.

• Init and doctor detect persisted Harper 5 admin users in RocksDB (Closes #2210). (#2210)

• Principal link, unlink, and provisioning re-read validated mapping state before writes and refuse detected changes (flair#2222). (#2222)

• The migration probe does not create candidate directories and rejects symlinked candidate or migration-state paths when probed (flair#2232). (#2232)

  Heads-up: a usable ~/.flair/data wins ahead of ROOTPATH regardless of which instance runs; an absent or unusable default loses.
  Set FLAIR_MIGRATION_DATA_DIR to separate custom migration state.

• Selected untrusted-record copies preserve special own keys as data; federation peers refuse affected signatures they cannot verify (flair#2235). (#2235)

• Plain local flair init refuses listeners without matching PID-file or spawned-child socket evidence before sending an admin credential.

• Without --reset-admin-pass, init verifies supplied administrator credentials before replacing an existing pass file (Closes #2271). (#2271)

• The dependency audit gate checks each audit stage's output, exit status and stderr (flair#2278). (#2278)

• flair keys prune leaves the key active when its path checks detect a nonregular ownership sidecar.

• Memory POST and ordinary PUT validate the shape of supplied supersedes references and canonicalize them (flair#2307). (#2307)

• Integration mutations retry when a stored row changes during validation; an explicit POST ID already in use is refused.

• Non-admin owner-scoped deletes recheck ownership before committing and refuse a detected change.

• A Basic-auth Agent lookup that fails refuses the request instead of admitting it. (#2403)

• @tpsdev-ai/adk-flair now requires Google ADK 2.x, a compatibility change.

• @tpsdev-ai/flair-mcp now depends on @modelcontextprotocol/sdk 1.31.0, outside the affected range of GHSA-6qxp-vccf-f47h (>=1.12.0 <1.31.0).

• The workspace lockfile resolves handlebars 4.7.10, outside the vulnerable range of GHSA-8r5x-fm3f-whwj, GHSA-p8wg-vrv2-v86f and GHSA-xw65-4hp5-5hc7 (>=4.0.0 <=4.7.9).

• The workspace lockfile resolves http-cache-semantics 4.3.0, outside the vulnerable range of GHSA-ch52-4w7c-c8xp (<=4.2.0).

• mariadb resolves to 3.5.4 in this repository's workspace install.

• The n8n nodes support Ed25519 signing with Agent Private Key; the admin password is deprecated (flair#1942). (#1942)

  Heads-up: base64-encode the raw key file from flair agent add <agent-id>
  (base64 < ~/.flair/keys/<agent-id>.key) for Agent Private Key.

• The workspace lockfile resolves proxy-addr 2.0.8, outside the vulnerable range of GHSA-jqcg-44mw-7w3h (>=1.1.0 <2.0.8).

---

Full record: CHANGELOG.md