feat(ruflo): govern ruflo memory on the ruvector-postgres sidecar (ADR-2123)

CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to agentbox are documented here. Format inspired by [Keep a
 
 ## [Unreleased]
 
+### Changed (2026-10-03 — ruflo memory governed on the sidecar, ADR-2123)
+
+- The image's `ruflo` / `claude-flow` bins are governed wrappers. `ruflo memory …` runs
+  `mcp/servers/ruflo-memory-cli.cjs`, which serves store/retrieve/search/list/delete/stats from
+  the ruvector-postgres sidecar through the governed memory library (Xinference bge-small
+  embeddings, the MCP server's entry ids) and emits ruflo 3.51.1's `--format json` shapes, so the
+  ruflo-console memory pane shows the sidecar corpus. `init`, `configure`, `export`, `import`,
+  `purge`, `distill`, `backup`, `compress`, `cleanup`, `classify`, `select-operator` and
+  `migrate` are refused (exit 2): ruflo's memory subsystem is local-only and would be a second
+  memory system. Every other subcommand runs with `RUFLO_DAEMON_AUTOSTART=0`,
+  `CLAUDE_FLOW_DISABLE_BRIDGE=1` and `CLAUDE_FLOW_MEMORY_PATH=~/.cache/ruflo/memory` as
+  overridable defaults (also exported at boot), so no invocation spawns a daemon or writes
+  `.swarm/`, `ruvector.db` or an ONNX model into the working directory.
+
 ### Changed (2026-10-03 — pod trails in the blocktrails git-mark §5.2 shape)
 
 - `nostr-pod-bridge` writes the pod's `blocktrails.json` in the blocktrails/spec git-mark

config/agentbox-aliases.sh

@@ -22,7 +22,7 @@ alias cf-hive="claude-flow hive-mind spawn"
 alias cf-spawn="claude-flow hive-mind spawn"
 alias cf-status="claude-flow hive-mind status"
 alias cf-help="claude-flow --help"
-alias cf-memory="claude-flow memory"  # read/debug only — writes MUST use MCP memory_* (CLI bypasses embeddings)
+alias cf-memory="claude-flow memory"  # governed (ADR-2123): serves the ruvector-postgres sidecar via Xinference; init/configure/export refused
 alias cf-hooks="claude-flow hooks"
 alias cf-doctor="claude-flow doctor --fix"
 alias cf-daemon="claude-flow daemon start"

config/custody/env-classes.json

@@ -596,6 +596,9 @@
         "RAW_BUS",
         "RES",
         "RUFLO_DAEMON_AI_WORKERS",
+        "RUFLO_DAEMON_AUTOSTART",
+        "CLAUDE_FLOW_DISABLE_BRIDGE",
+        "CLAUDE_FLOW_MEMORY_PATH",
         "RUNTIME_ENV_DURABLE",
         "RUNTIME_ENV_FILE",
         "RUSTUP_HOME",

config/entrypoint-unified.sh

@@ -3374,6 +3374,17 @@ export EMBEDDING_MODEL="${EMBEDDING_MODEL}"
 # explicitly so an enabled plugin — ruflo-loop-workers / ruflo-autopilot —
 # can never flip headless Claude launches on without an operator export).
 export RUFLO_DAEMON_AI_WORKERS="${RUFLO_DAEMON_AI_WORKERS:-0}"
+# ADR-2123 governed ruflo: the baked `ruflo`/`claude-flow` wrappers set these
+# per invocation; exporting them here covers anything that reaches
+# @claude-flow/cli directly (node …/cli.js, the console's subprocess env).
+# No daemon autostart (every CLI call, even --help, spawned one into the CWD),
+# no AgentDB bridge (its native engine writes ./ruvector.db wherever it runs
+# and downloads MiniLM into the read-only store path), and the sql.js
+# bookkeeping store under the cache dir instead of <cwd>/.swarm. Durable
+# memory is the ruvector-postgres sidecar via `ruflo memory …` / memory_* only.
+export RUFLO_DAEMON_AUTOSTART="${RUFLO_DAEMON_AUTOSTART:-0}"
+export CLAUDE_FLOW_DISABLE_BRIDGE="${CLAUDE_FLOW_DISABLE_BRIDGE:-1}"
+export CLAUDE_FLOW_MEMORY_PATH="\${CLAUDE_FLOW_MEMORY_PATH:-\${HOME:-/tmp}/.cache/ruflo/memory}"
 # ADR-2080 model-router console knobs (empty unless [model_routing.neural].enabled)
 $_MRN_EXPORTS
 # Interaction plane (PRD-021 / ADR-042): expose the AoE daemon + NIP-98 proxy

docs/adr/ADR-2002-aoe-token-auth-boundary.md

@@ -7,7 +7,7 @@ implementation_status: complete
 activation_status: live
 supersedes: []
 superseded_by: []
-verified_commit: 09e6271e9d00e2a657e18766172e4cc87355d17d
+verified_commit: 1fc26c78639e3ab1dfd81c9b4284ea95bb5d731c
 verified_paths: [config/nip98-proxy/proxy.mjs, scripts/aoe-curl.sh, flake.nix]
 owner: jjohare
 review_trigger: next image rebuild (activation), or any new consumer of :9095, or per-process isolation becoming available
@@ -266,3 +266,7 @@ Tripped by the W10 gap fixes on `custody/integration`. `flake.nix` (`dc91e092a`)
 ### Re-verification — 2026-10-03 (web-researcher hold note)
 
 `cff75f7ea..09e6271e9`: `flake.nix` changes only a comment in `webResearcherMcpPkg` (v1.49.4 held: needs Go 1.27.1, beyond the pinned nixpkgs); no pin, hash or gate changes (`09e6271e9`). Nothing this record governs (ADR-2002 — AoE interaction plane requires token auth — loopback is not a boundary) changes meaning. The decision holds. Re-verified by `git log cff75f7ea..09e6271e9 -- <verified_paths>`. Nix was not evaluated here; the image is unverified until the host rebuild.
+
+### Re-verification — 2026-10-03 (ruflo memory governed, 1fc26c786)
+
+`09e6271e9..1fc26c786`: `flake.nix`: `34f322740` projects `[sidechain].faucet_units`/`faucet_sats` into `[program:sidestr-faucet]`'s environment; `aeca58df6` passes `SIDESTR_PEG_SCRIPT` to the per-chain producer; `bde96a334` adds the `pokerCitizenSeats` map and bakes `[program:poker-citizen-<name>]` per `[poker_citizen.<name>]` (the package gate now counts a seat); `18a85577c` bakes `[program:poker-coach]` under `[poker_coach]`; `b83e0e5d7` adds `findutils` to both producer PATHs; `012bf98f5` adds `rufloGovernedPkg` — `ruflo`/`claude-flow` wrappers that exec `mcp/servers/ruflo-memory-cli.cjs` for `memory` and otherwise run `rufloPkg` with `RUFLO_DAEMON_AUTOSTART=0`, `CLAUDE_FLOW_DISABLE_BRIDGE=1` and `CLAUDE_FLOW_MEMORY_PATH` under `~/.cache` as overridable defaults, `claude-flow-mcp` symlinked through unchanged — and swaps it for `rufloPkg` in the gated package list (ADR-2123). Nothing this record decides (ADR-2002 — AoE interaction plane requires token auth — loopback is not a boundary) changed: the nip98-proxy, the AoE daemon and the token check are untouched, and none of the new programs opens a listener (the seats and the coach dial the forum relay and the loopback producer). The decision holds. Re-verified by `git diff 09e6271e9..1fc26c786 -- <verified_paths>`. Nix was not evaluated here; the image is unverified until the host rebuild.

docs/adr/ADR-2009-nip98-proxy-identity-boundary.md

@@ -7,7 +7,7 @@ implementation_status: complete
 activation_status: live
 supersedes: []
 superseded_by: []
-verified_commit: 09e6271e9d00e2a657e18766172e4cc87355d17d
+verified_commit: 1fc26c78639e3ab1dfd81c9b4284ea95bb5d731c
 verified_paths: [config/nip98-proxy/proxy.mjs, flake.nix, docs/INGRESS-identity.md]
 owner: jjohare
 review_trigger: A second identity ingress is proposed, or aoe serve stops binding loopback
@@ -274,3 +274,7 @@ Tripped by the W10 gap fixes on `custody/integration`. `flake.nix` (`dc91e092a`)
 ### Re-verification — 2026-10-03 (web-researcher hold note)
 
 `cff75f7ea..09e6271e9`: `flake.nix` changes only a comment in `webResearcherMcpPkg` (v1.49.4 held: needs Go 1.27.1, beyond the pinned nixpkgs); no pin, hash or gate changes (`09e6271e9`). Nothing this record governs (ADR-2009 — The nip98-proxy is the fail-closed AoE identity boundary) changes meaning. The decision holds. Re-verified by `git log cff75f7ea..09e6271e9 -- <verified_paths>`. Nix was not evaluated here; the image is unverified until the host rebuild.
+
+### Re-verification — 2026-10-03 (ruflo memory governed, 1fc26c786)
+
+`09e6271e9..1fc26c786`: `flake.nix`: `34f322740` projects `[sidechain].faucet_units`/`faucet_sats` into `[program:sidestr-faucet]`'s environment; `aeca58df6` passes `SIDESTR_PEG_SCRIPT` to the per-chain producer; `bde96a334` adds the `pokerCitizenSeats` map and bakes `[program:poker-citizen-<name>]` per `[poker_citizen.<name>]` (the package gate now counts a seat); `18a85577c` bakes `[program:poker-coach]` under `[poker_coach]`; `b83e0e5d7` adds `findutils` to both producer PATHs; `012bf98f5` adds `rufloGovernedPkg` — `ruflo`/`claude-flow` wrappers that exec `mcp/servers/ruflo-memory-cli.cjs` for `memory` and otherwise run `rufloPkg` with `RUFLO_DAEMON_AUTOSTART=0`, `CLAUDE_FLOW_DISABLE_BRIDGE=1` and `CLAUDE_FLOW_MEMORY_PATH` under `~/.cache` as overridable defaults, `claude-flow-mcp` symlinked through unchanged — and swaps it for `rufloPkg` in the gated package list (ADR-2123). Nothing this record decides (ADR-2009 — The nip98-proxy is the fail-closed AoE identity boundary) changed: `config/nip98-proxy/proxy.mjs` and `docs/INGRESS-identity.md` did not move and no change in `flake.nix` touches the proxy's package, program or environment. The decision holds. Re-verified by `git diff 09e6271e9..1fc26c786 -- <verified_paths>`. Nix was not evaluated here; the image is unverified until the host rebuild.

docs/adr/ADR-2012-relay-allowlist-only-ingress.md

@@ -7,7 +7,7 @@ implementation_status: partial
 activation_status: live
 supersedes: []
 superseded_by: []
-verified_commit: 09e6271e9d00e2a657e18766172e4cc87355d17d
+verified_commit: 1fc26c78639e3ab1dfd81c9b4284ea95bb5d731c
 verified_paths: [agentbox.toml, flake.nix]
 owner: jjohare
 review_trigger: ingress_policy changes from allowlist, or the ADR-040 D3 governance-publisher key-split lands
@@ -346,3 +346,7 @@ Tripped by `f93586b9e` (custody W2b and W4: the at-rest migrate/revert and the s
 ### Re-verification — 2026-10-03 (web-researcher hold note)
 
 `cff75f7ea..09e6271e9`: `flake.nix` changes only a comment in `webResearcherMcpPkg` (v1.49.4 held: needs Go 1.27.1, beyond the pinned nixpkgs); no pin, hash or gate changes (`09e6271e9`). Nothing this record governs (ADR-2012 — Relay ingress is allowlist-only with no fallback and no auto-add) changes meaning. The decision holds. Re-verified by `git log cff75f7ea..09e6271e9 -- <verified_paths>`. Nix was not evaluated here; the image is unverified until the host rebuild.
+
+### Re-verification — 2026-10-03 (ruflo memory governed, 1fc26c786)
+
+`09e6271e9..1fc26c786`: `agentbox.toml`: `34f322740` adds `[sidechain].faucet_units = 1000`/`faucet_sats = 2000`; `29bff6d94`, `5241b28e7` and `aeca58df6` switch `[sidechain.dreamlab-txbt4]` on (`enabled = true`, `interval = 60`, `peg_script`); `bde96a334`/`f2dfc5bfa` add `[poker_citizen.dreamlab-txbt4]` (the BLAKES7 seat on `:3451`, `asset_id`); `18a85577c` adds `[poker_coach]`; `a2ffa05eb` moves `[toolchains].ruflo_console` beside `ruflo` and sets it `true`. `flake.nix`: `34f322740` projects `[sidechain].faucet_units`/`faucet_sats` into `[program:sidestr-faucet]`'s environment; `aeca58df6` passes `SIDESTR_PEG_SCRIPT` to the per-chain producer; `bde96a334` adds the `pokerCitizenSeats` map and bakes `[program:poker-citizen-<name>]` per `[poker_citizen.<name>]` (the package gate now counts a seat); `18a85577c` bakes `[program:poker-coach]` under `[poker_coach]`; `b83e0e5d7` adds `findutils` to both producer PATHs; `012bf98f5` adds `rufloGovernedPkg` — `ruflo`/`claude-flow` wrappers that exec `mcp/servers/ruflo-memory-cli.cjs` for `memory` and otherwise run `rufloPkg` with `RUFLO_DAEMON_AUTOSTART=0`, `CLAUDE_FLOW_DISABLE_BRIDGE=1` and `CLAUDE_FLOW_MEMORY_PATH` under `~/.cache` as overridable defaults, `claude-flow-mcp` symlinked through unchanged — and swaps it for `rufloPkg` in the gated package list (ADR-2123). Nothing this record decides (ADR-2012 — Relay ingress is allowlist-only with no fallback and no auto-add) changed: the only relay URLs added (`[poker_citizen.dreamlab-txbt4].relay`, `[poker_coach].relay`) are the forum relay already named at `forum_relay_url` (`agentbox.toml:189`); no allowlist entry, fallback or auto-add appears. The decision holds. Re-verified by `git diff 09e6271e9..1fc26c786 -- <verified_paths>`. Nix was not evaluated here; the image is unverified until the host rebuild.

docs/adr/ADR-2013-loopback-publish-except-9096.md

@@ -7,7 +7,7 @@ implementation_status: partial
 activation_status: live
 supersedes: []
 superseded_by: []
-verified_commit: 09e6271e9d00e2a657e18766172e4cc87355d17d
+verified_commit: 1fc26c78639e3ab1dfd81c9b4284ea95bb5d731c
 verified_paths: [scripts/ci/check-ports-loopback.sh, .github/workflows/invariants.yml, flake.nix, docker-compose.yml]
 owner: jjohare
 review_trigger: Any new entry on the SANCTIONED list, or a new compose overlay file
@@ -347,3 +347,7 @@ Tripped by the W10 gap fixes on `custody/integration`. `.github/workflows/invari
 ### Re-verification — 2026-10-03 (web-researcher hold note)
 
 `cff75f7ea..09e6271e9`: `flake.nix` changes only a comment in `webResearcherMcpPkg` (v1.49.4 held: needs Go 1.27.1, beyond the pinned nixpkgs); no pin, hash or gate changes (`09e6271e9`). Nothing this record governs (ADR-2013 — Every compose publish binds 127.0.0.1 unless on the sanctioned-exposure list, CI-enforced across all overlays) changes meaning. The decision holds. Re-verified by `git log cff75f7ea..09e6271e9 -- <verified_paths>`. Nix was not evaluated here; the image is unverified until the host rebuild.
+
+### Re-verification — 2026-10-03 (ruflo memory governed, 1fc26c786)
+
+`09e6271e9..1fc26c786`: `flake.nix`: `34f322740` projects `[sidechain].faucet_units`/`faucet_sats` into `[program:sidestr-faucet]`'s environment; `aeca58df6` passes `SIDESTR_PEG_SCRIPT` to the per-chain producer; `bde96a334` adds the `pokerCitizenSeats` map and bakes `[program:poker-citizen-<name>]` per `[poker_citizen.<name>]` (the package gate now counts a seat); `18a85577c` bakes `[program:poker-coach]` under `[poker_coach]`; `b83e0e5d7` adds `findutils` to both producer PATHs; `012bf98f5` adds `rufloGovernedPkg` — `ruflo`/`claude-flow` wrappers that exec `mcp/servers/ruflo-memory-cli.cjs` for `memory` and otherwise run `rufloPkg` with `RUFLO_DAEMON_AUTOSTART=0`, `CLAUDE_FLOW_DISABLE_BRIDGE=1` and `CLAUDE_FLOW_MEMORY_PATH` under `~/.cache` as overridable defaults, `claude-flow-mcp` symlinked through unchanged — and swaps it for `rufloPkg` in the gated package list (ADR-2123). `docker-compose.yml`, `scripts/ci/check-ports-loopback.sh` and the invariants workflow did not move. Nothing this record decides (ADR-2013 — Every compose publish binds 127.0.0.1 unless on the sanctioned-exposure list, CI-enforced across all overlays) changed: the `flake.nix` changes add supervisor programs and a package wrapper, not compose publishes. The decision holds. Re-verified by `git diff 09e6271e9..1fc26c786 -- <verified_paths>`. Nix was not evaluated here; the image is unverified until the host rebuild.

docs/adr/ADR-2014-memory-mcp-only-fail-closed.md

@@ -118,3 +118,7 @@ structural rather than evidenced per row. Backup participation in TTL is still
 undefined: an expired row the sweep deletes may survive in a retained backup.
 `implementation_status` stays `partial` until a production repair run and a
 passing recall receipt exist together.
+
+## Re-affirmation — 2026-10-03 (ruflo 3.51.1 memory, ADR-2123)
+
+The `review_trigger` fired in substance: ruflo 3.51.1 (baked under the console gate) carries its own memory subsystem, and one `memory init` wrote three local stores into a repository. Tested, it is local-only (sql.js, AgentDB mirror, `./ruvector.db`, MiniLM) with no Postgres path, so it is not a new backend for this record to admit; it is a second system this record forbids. ADR-2123 closes the gap by routing `ruflo memory …` through `memStore`/`memSearch` of `lib/memory-tools.js` and refusing the local-store verbs, so the MCP-only, fail-closed mandate now also holds for the CLI and the ruflo-console memory pane. The upstream lineage (why ruvnet has an embedded line and a Postgres line, and why the Postgres line is current) is recorded in ADR-2123 so it is not re-derived. Nothing this record decides changed.

docs/adr/ADR-2019-model-lifecycle-384-dim-freeze.md

@@ -7,7 +7,7 @@ implementation_status: none
 activation_status: inactive
 supersedes: []
 superseded_by: []
-verified_commit: 451823ca8ec0b5452ceb8fdc52e777f77a2bbc43
+verified_commit: 1fc26c78639e3ab1dfd81c9b4284ea95bb5d731c
 verified_paths: [mcp/servers/lib/aggregate-effectiveness.js, scripts/ruvector-sona-feeder.mjs, agentbox.toml]
 owner: jjohare
 review_trigger: A SONA binary with configurable embedding_dim (384-capable) ships, or a dimension migration is planned
@@ -240,3 +240,7 @@ Tripped by `f93586b9e` (custody W2b and W4: the at-rest migrate/revert and the s
 ### Re-verification — 2026-10-03 (ruflo-console gate, `451823ca8`)
 
 `4ea3181b5..451823ca8`: `agentbox.toml` adds `[toolchains].ruflo_console = false`. Nothing this record governs (ADR-2019 — Model-lifecycle freeze — 384-dim bge is the active column, SONA and attention-rerank stay off) changes meaning. The decision holds. Re-verified by `git log 4ea3181b5..451823ca8 -- <verified_paths>`.
+
+### Re-verification — 2026-10-03 (ruflo memory governed, 1fc26c786)
+
+`451823ca8..1fc26c786` (nothing in the governed paths moved before `09e6271e9`): `agentbox.toml`: `34f322740` adds `[sidechain].faucet_units = 1000`/`faucet_sats = 2000`; `29bff6d94`, `5241b28e7` and `aeca58df6` switch `[sidechain.dreamlab-txbt4]` on (`enabled = true`, `interval = 60`, `peg_script`); `bde96a334`/`f2dfc5bfa` add `[poker_citizen.dreamlab-txbt4]` (the BLAKES7 seat on `:3451`, `asset_id`); `18a85577c` adds `[poker_coach]`; `a2ffa05eb` moves `[toolchains].ruflo_console` beside `ruflo` and sets it `true`. `mcp/servers/lib/aggregate-effectiveness.js` and `scripts/ruvector-sona-feeder.mjs` did not move. Nothing this record decides (ADR-2019 — Model-lifecycle freeze — 384-dim bge is the active column, SONA and attention-rerank stay off) changed: no embedding, SONA or rerank key changes. Outside the governed paths, `012bf98f5` routes `ruflo memory` to the ruvector-postgres sidecar and its 384-dim Xinference embedder instead of ruflo's own MiniLM store (ADR-2123), which is consistent with this freeze. The decision holds. Re-verified by `git diff 451823ca8..1fc26c786 -- <verified_paths>`.

docs/adr/ADR-2020-capability-gating.md

@@ -7,7 +7,7 @@ implementation_status: partial
 activation_status: live
 supersedes: []
 superseded_by: []
-verified_commit: 451823ca8ec0b5452ceb8fdc52e777f77a2bbc43
+verified_commit: 1fc26c78639e3ab1dfd81c9b4284ea95bb5d731c
 verified_paths: [agentbox.toml, skills/tree-search-coder/SKILL.md, services/agentbox-ops/src/bin/tree-search-cap.rs]
 owner: jjohare
 review_trigger: any new optional skill/feature block added to agentbox.toml, or any change to the tree-search-coder spend/route posture
@@ -247,3 +247,7 @@ Tripped by `f93586b9e` (custody W2b and W4: the at-rest migrate/revert and the s
 ### Re-verification — 2026-10-03 (ruflo-console gate, `451823ca8`)
 
 `4ea3181b5..451823ca8`: `agentbox.toml` adds `[toolchains].ruflo_console = false`. Nothing this record governs (ADR-2020 — Optional capabilities are manifest-gated and byte-identical-when-off; execution-gated tools are spend-capped and never auto-routed) changes meaning. This record's rule is exercised directly: the gate defaults off, flake.nix bakes nothing under it when off, and the boot projection leaves `settings.json` and `installed_plugins.json` byte-identical when none of the three ids is present (asserted in `tests/config/ruflo-console.test.mjs`). The decision holds. Re-verified by `git log 4ea3181b5..451823ca8 -- <verified_paths>`.
+
+### Re-verification — 2026-10-03 (ruflo memory governed, 1fc26c786)
+
+`451823ca8..1fc26c786` (nothing in the governed paths moved before `09e6271e9`): `agentbox.toml`: `34f322740` adds `[sidechain].faucet_units = 1000`/`faucet_sats = 2000`; `29bff6d94`, `5241b28e7` and `aeca58df6` switch `[sidechain.dreamlab-txbt4]` on (`enabled = true`, `interval = 60`, `peg_script`); `bde96a334`/`f2dfc5bfa` add `[poker_citizen.dreamlab-txbt4]` (the BLAKES7 seat on `:3451`, `asset_id`); `18a85577c` adds `[poker_coach]`; `a2ffa05eb` moves `[toolchains].ruflo_console` beside `ruflo` and sets it `true`. `skills/tree-search-coder/SKILL.md` and `tree-search-cap.rs` did not move. Each new table is a manifest gate in this record's shape: `[poker_citizen.<name>]` and `[poker_coach]` are schema-declared, catalogued rebuild-class, and bake nothing when off; the `[sidechain.dreamlab-txbt4]` and `ruflo_console` flips are gate *states* changing in the shipped manifest, not the rule. The previous note's "the gate defaults off" for `ruflo_console` describes the manifest at `451823ca8`; since `a2ffa05eb` it ships on, and `tests/config/ruflo-console.test.mjs` asserts byte-identity when off and the three ids when on (15/15 at HEAD). Nothing this record decides (ADR-2020 — Optional capabilities are manifest-gated and byte-identical-when-off; execution-gated tools are spend-capped and never auto-routed) changed. The decision holds. Re-verified by `git diff 451823ca8..1fc26c786 -- <verified_paths>`.