diff --git a/.agents/skills/upstream-status/SKILL.md b/.agents/skills/upstream-status/SKILL.md index 6370f491..46d3245a 100644 --- a/.agents/skills/upstream-status/SKILL.md +++ b/.agents/skills/upstream-status/SKILL.md @@ -41,7 +41,9 @@ dependency policies, constraints, and the `watch` list of upstream threads. For each item give the id, title, URL and a one-line reason: who replied and when, which release, or which ak change is pending. Give "Fixed upstream, not yet released", - "Waiting on upstream" and "Unmapped (no ak change recorded)" as counts only, unless asked. + "Released, waiting for the support window", "Waiting on upstream" and + "Unmapped (no ak change recorded)" as counts only, unless asked. A held item is not + dispatched: the oldest Ruflo in the support window (`supportWindow.floor`) predates its fix. 4. Offer the next actions that fit: - Draft a reply to an upstream thread. Show the draft; do not post it. - Dispatch a released item: branch `upstream/` from `main`, make the entry's `adjustment` diff --git a/.claude/skills/upstream-status/SKILL.md b/.claude/skills/upstream-status/SKILL.md index 6370f491..46d3245a 100644 --- a/.claude/skills/upstream-status/SKILL.md +++ b/.claude/skills/upstream-status/SKILL.md @@ -41,7 +41,9 @@ dependency policies, constraints, and the `watch` list of upstream threads. For each item give the id, title, URL and a one-line reason: who replied and when, which release, or which ak change is pending. Give "Fixed upstream, not yet released", - "Waiting on upstream" and "Unmapped (no ak change recorded)" as counts only, unless asked. + "Released, waiting for the support window", "Waiting on upstream" and + "Unmapped (no ak change recorded)" as counts only, unless asked. A held item is not + dispatched: the oldest Ruflo in the support window (`supportWindow.floor`) predates its fix. 4. Offer the next actions that fit: - Draft a reply to an upstream thread. Show the draft; do not post it. - Dispatch a released item: branch `upstream/` from `main`, make the entry's `adjustment` diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml index 9fc34d50..cc2e4a7a 100644 --- a/.github/workflows/nightly.yml +++ b/.github/workflows/nightly.yml @@ -78,7 +78,11 @@ jobs: } >> "$GITHUB_STEP_SUMMARY" # Non-blocking: a native libc++abi mutex abort on macos-latest poisons ruflo - # exit codes, tracked upstream at ruvnet/ruflo#2885 (open as of 2026-08-13). + # exit codes, tracked upstream at ruvnet/ruflo#2885 (open; the Aug 31 triage + # points at better-sqlite3 with onnxruntime-node on macOS arm64). A hosted + # probe on 2026-09-27 (Ruflo 3.46.1, run 36333572972) aborted 10/10 with the + # default settings and 10/10 with single-threaded ONNX Runtime sessions, so + # that mitigation does not help (issuecomment-5857781254). # Scope is NOT neural-train-specific: upstream evidence (2026-08-12) shows the # same teardown abort on store-touching commands (`memory search` โ†’ correct # output, rc 134), so an `x verify memory` step added here would need the same diff --git a/README.md b/README.md index 72563bb9..96d775a6 100644 --- a/README.md +++ b/README.md @@ -175,7 +175,8 @@ One of those is worth calling out: Projects set up by the kit get an append-only footer under ruflo's own status line, with segments reflecting their documented presence and metric checks: ๐Ÿง  SONA patterns/trajectories (+ -live micro-LoRA ฮ”โ€–Wโ€–), ๐Ÿ“ˆ route-RL metrics, ๐Ÿ›ก aidefence, ๐Ÿงฟ RuvNet Brain KB, +live micro-LoRA ฮ”โ€–Wโ€–), ๐Ÿ“ˆ route-RL metrics, a โš  aidefence OFF alarm (only when Ruflo has no +prompt-injection engine at all), ๐Ÿงฟ RuvNet Brain KB, โš™ machine-wide daemon count, and ๐ŸŽ“ Agentic-QE stats. That rich, command-backed footer is a Claude Code surface. Codex supports a diff --git a/docs/DASHBOARD.md b/docs/DASHBOARD.md index ca00fa6e..6bdd36ef 100644 --- a/docs/DASHBOARD.md +++ b/docs/DASHBOARD.md @@ -184,8 +184,8 @@ memory durability fix, and the funnel toggle โ€” get one card each in Overview > shows the state badge beside its plain-language meaning (and the action to take, when one applies), the current value and who controls it, an expandable "what it does" with its benefit, cost, and how to change it in `kit.json`, and the live evidence behind the state: which picker a -`hooks route` probe reported, MCP calls audited and refused in the last 24 hours (zero on ruflo -โ‰ค 3.44.0, which does not yet enforce the policy on stdio launches; see +`hooks route` probe reported, MCP calls audited and refused in the last 24 hours (zero on Ruflo +below 3.46.0, which does not enforce the policy on stdio launches; see [ADR-0058](adr/0058-managed-ruflo-components.md)), whether the learning engine is loaded, or the funnel's deciding source. The panel header repeats the same count and ruflo version `ak status` reports, so the two never disagree. Encryption at rest shows diff --git a/docs/HOST-SUPPORT.md b/docs/HOST-SUPPORT.md index e18c8042..cc245e0c 100644 --- a/docs/HOST-SUPPORT.md +++ b/docs/HOST-SUPPORT.md @@ -107,9 +107,9 @@ Official extension references: [Claude hooks](https://code.claude.com/docs/en/ho | Ruflo capability | Claude Code | Codex | OpenCode | | --- | --- | --- | --- | | Upstream host orientation | **Native:** primary/reference CLI surface | **Native + managed:** upstream backend/plugin pieces plus agentic-kit integration | **Managed:** no equivalent upstream backend flag | -| Ruflo MCP tools | Native registration | Managed Ruflo MCP registration | Connected managed MCP; compact lazy `ak_ruflo_*` provider projection | -| Ruflo browser executor | Process-scoped trusted agent-browser config | Same config inherited by `ak x ruflo-mcp` | Same config in the receipt-owned MCP environment | -| Shared Ruflo memory | Same project store | Same project store | Same project store when pointed at the same Ruflo server | +| Ruflo MCP tools | Managed user-scope registration through `ak x ruflo-mcp --host claude` | Managed Ruflo MCP registration through `ak x ruflo-mcp` | Connected managed MCP; compact lazy `ak_ruflo_*` provider projection | +| Ruflo browser executor | Process-scoped trusted agent-browser config, set by the launcher | Same config inherited by `ak x ruflo-mcp` | Same config in the receipt-owned MCP environment | +| Shared Ruflo memory | Same project store; the user-level store outside projects | Same project store; the user-level store outside projects | Same project store when pointed at the same Ruflo server | | Agents and skills | Upstream Claude assets | Codex-compatible skills/plugin assets and generated guidance | Receipt-owned lazy profile catalogue through one stock `ak-specialist`; stock skills loaded on demand | | Lifecycle hooks | Native Claude hooks | Codex hooks/plugin surfaces | OpenCode events translated by `ruflo-hooks.js` | | Inference-backend flag | `ENABLE_CLAUDE_CODE` | `ENABLE_CODEX` | None | @@ -132,8 +132,8 @@ The dated upstream risk inventory includes: ([#2638](https://github.com/ruvnet/ruflo/issues/2638)); - init and plugin installation can duplicate assets or hooks ([#2640](https://github.com/ruvnet/ruflo/issues/2640)); -- published 3.38.21 ignores its Codex/skills init opt-out flags - ([#3167](https://github.com/ruvnet/ruflo/issues/3167)); +- Ruflo below 3.46.0 ignores its Codex/skills init opt-out flags, so `ak setup` adds scripted + mode and `RUFLO_NO_SKILLS_SH=1` there ([#3167](https://github.com/ruvnet/ruflo/issues/3167)); - dual-host marketplace parity remains incomplete ([#2854](https://github.com/ruvnet/ruflo/issues/2854)); and - hierarchical AgentDB writes can report success without durable persistence diff --git a/docs/MANAGED-TOOLS.md b/docs/MANAGED-TOOLS.md index 995175ef..c2a95ce6 100644 --- a/docs/MANAGED-TOOLS.md +++ b/docs/MANAGED-TOOLS.md @@ -117,7 +117,7 @@ version supports; `ak status` reports the real state, never a bare label. | --- | --- | --- | --- | | Typesafe agent picker | on | 3.43.0 | global `@ruvector/typesafe` package + `CLAUDE_FLOW_ROUTER_TYPESAFE=1` | | MiniLM agent picker | on | 3.44.0 | `CLAUDE_FLOW_ROUTER_EMBEDDER=minilm` | -| MCP tool governance | on; 120 calls/min, audit on | 3.42.0 | project `.harness/mcp-policy.json` + project-scoped `RUFLO_MCP_ENFORCE_POLICY=1` (not yet enforced on stdio launches by ruflo โ‰ค 3.44.0) | +| MCP tool governance | on; 120 calls/min, audit on | 3.42.0 | project `.harness/mcp-policy.json` + project-scoped `RUFLO_MCP_ENFORCE_POLICY=1` (enforced on stdio launches from Ruflo 3.46.0) | | Learning profile | `balanced` | 3.42.1 | `RUFLO_INTELLIGENCE_MODE=balanced` | | MetaHarness turn-credit | on | 3.36.0 | nothing to apply; ak confirms ruflo's bundled dependency resolves | | Memory durability fix (#2887) | on | 3.36.0 | nothing to apply; ak confirms `@claude-flow/memory` โ‰ฅ 3.0.0-alpha.22 | @@ -144,10 +144,12 @@ components in the same settings file. If you delete a value ak set, `ak status` The governance policy file is enforced only when it carries ak's own `_about` marker; a project's own pre-existing `.harness/mcp-policy.json` is left alone and reported `user-managed`. -Ruflo 3.44.0 and earlier do not apply the policy on the stdio MCP launches Claude Code, Codex and -OpenCode use (ADR-0058 upstream request 6): ak writes the file and the variable so they are ready -when ruflo wires enforcement, and the component reports `unknown` until then, because no audit -records appear. +Ruflo 3.46.0 and newer apply the policy on the stdio MCP launches Claude Code, Codex and OpenCode +use: calls beyond the cap are refused and every call is audited. Older Ruflo does not apply it on +those launches, so there the component reports `unknown`, because no audit records appear. ak +keeps its own policy file out of git with one line in the repository's `.git/info/exclude` +(never `.gitignore`, and never the whole `.harness/` folder, which other tools use for files they +commit); removing the policy removes that line. Every state `ak status`, `ak setup`, and the dashboard show carries its meaning and, where one applies, the fix: diff --git a/docs/SETUP.md b/docs/SETUP.md index f9bd9ce2..b4642360 100644 --- a/docs/SETUP.md +++ b/docs/SETUP.md @@ -122,13 +122,14 @@ versions. The table below describes the current contract. | Path or state | Existing project | New/empty project | | --- | --- | --- | | Application source, `package.json`, and arbitrary project files | Not intentionally changed by agentic-kit. | No application is scaffolded. | -| `.claude/settings.json` | Regenerated by `ruflo init --full --force`; agentic-kit then disables `claudeFlow.daemon.autoStart` if it is `true`, and AQE may merge its hooks/settings. Ruflo also reads that `false` as "do not start the daemon when a `ruflo` command runs", so the daemon, and with it memory backup and distillation, runs only when started ([details](TROUBLESHOOTING.md#memory-backup-and-distillation)). Custom content can be at risk. | Created with Ruflo settings, then normalized and optionally extended by AQE. | +| `.claude/settings.json` | Regenerated by `ruflo init --full --force`, which writes `claudeFlow.daemon.autoStart: false`. Agentic-kit turns that `false` into `true`, so Ruflo starts the project daemon (and with it memory backup and distillation) on the next `ruflo` command, and keeps the old value to restore on `ak uninstall`. To keep it off, set `rufloDaemon.autoStart` to `false` in `kit.json` ([details](TROUBLESHOOTING.md#memory-backup-and-distillation)). AQE may merge its hooks/settings. Custom content can be at risk. | Created with Ruflo settings, then normalized and optionally extended by AQE. | | `.claude/settings.local.json` | Valid existing JSON is preserved and merged with an absolute `env.CLAUDE_FLOW_DB_PATH`. A one-time `.bak` is created before agentic-kit writes it. Invalid JSON is treated as empty. | Created with the absolute memory path. | | `.claude/skills/`, `.claude/commands/`, `.claude/agents/`, `.claude/helpers/` | Ruflo's matching generated assets are overwritten; AQE assets are then added or refreshed. Unrelated extra files are generally not swept. | Generated and populated. | | `CLAUDE.md` | Agentic-kit captures the pre-init bytes before Ruflo runs, restores user-authored prose outside its own sentinels, and reconciles the bounded managed projection before and after AQE. An exact old unsentineled lean stub is migrated; a near-match is preserved. In an AGENTS-only repository, the created file is the one-line `@AGENTS.md` reference. | Created only when required: bounded managed guidance, or a one-line `@AGENTS.md` reference when that is the existing project guidance source. | | `.mcp.json` | Ruflo force-init regenerates this file before agentic-kit removes project-local `ruflo`, `claude-flow`, `ruv-swarm`, and `flow-nexus` entries. The file is deleted if those are the only remaining content. AQE may subsequently add its own server. Because regeneration happens first, pre-existing custom MCP entries can be lost; preserve them separately and restore them after setup. | Temporarily generated and sanitized; it may be absent afterward unless AQE or another retained entry needs it. | | Claude's project-local `ruflo` MCP registration | Removed with `claude mcp remove ruflo -s local`; agentic-kit offers user-scope registration instead. | Same behavior. | | `.claude-flow/` generated config and runtime support files | Ruflo-generated files are refreshed. Agentic-kit initializes memory and swarm state, starts the local-only daemon (it ends itself after 12 hours), and injects/heals the status-line footer. | Created and initialized. | +| `.claude-flow/config.json` | Before starting the daemon, agentic-kit adds only the flat keys the installed Ruflo needs: `"daemon.idleSecs": 0` below Ruflo 3.46.0, and `"daemon.resourceThresholds.minFreeMemoryPercent": 0` on macOS. Other keys are kept. A file that is not a readable JSON object, or a key that holds your own value, is left alone, and `ak status` names the key to set yourself. `ak sync` removes a key once the installed Ruflo no longer needs it, and `ak uninstall` removes them all. | Created only when a key is needed (always on macOS). | | `.swarm/memory.db` and adjacent memory stores | Initialized or migrated in place. Agentic-kit writes a disposable verification record, confirms the on-disk row, and removes only that probe. | Created/initialized and verified. | | `.agentic-qe/` and AQE integration assets | With AQE enabled, `aqe init --auto` migrates or refreshes its database, configuration, workers, skills, agents, hooks, and platform integrations. Generated assets can change with the installed AQE version. | Created and initialized when AQE is enabled. | | Oversized `.agentic-qe/*.rvf` stores | An RVF file over 2 GiB and its `.lock`, `.idmap.json`, and `.manifest.json` sidecars are removed before AQE initialization. Normal-sized stores are left to AQE. | Normally not applicable. | @@ -145,8 +146,9 @@ their supported initializer arguments. AQE owns and updates its guidance block. Setup with Codex enabled inventories the effective user Codex MCP configuration even in machine-only mode. When project setup is active it inventories that project's Codex MCP configuration too. An exact recursive -`[mcp_servers.codex]` entry and the exact deprecated `claude-flow` Ruflo -transport are listed in the setup trust manifest, backed up, corrected only after +`[mcp_servers.codex]` entry and an exact `claude-flow` Ruflo alias (the deprecated +`ruflo mcp start` transport, or a copy of Claude Code's `ak x ruflo-mcp --host claude` +registration that Codex's Claude import added) are listed in the setup trust manifest, backed up, corrected only after the setup confirmation (or `--yes`), and re-probed before setup may report success. The recursive entry is removed; the `claude-flow` alias is replaced by a disabled placeholder so Codex's Claude config import cannot add it back. A fresh recovery copy captures the immediate pre-repair bytes; symlinked @@ -175,10 +177,11 @@ The project guidance result is defined by ownership, not by which initializer ra Agentic-QE's `BEGIN AGENTIC-QE CODEX` block is owned by Agentic-QE, not by this merge engine. Setup uses a bounded compatibility guard and reconciles around AQE initialization, but does not claim arbitrary AQE content. Ruflo is called with `--no-global`, `--no-codex-detect`, and -`--no-skills-sh` to declare the machine/Codex ownership boundary. Published Ruflo 3.38.21 does not -honor the two hyphenated skill flags ([ruflo #3167](https://github.com/ruvnet/ruflo/issues/3167)), -so agentic-kit additionally uses scripted `--format json` mode and `RUFLO_NO_SKILLS_SH=1`; both -independently suppress the optional projections in that release. Existing unreceipted skills +`--no-skills-sh` to declare the machine/Codex ownership boundary. Ruflo below 3.46.0 does not +honor the two hyphenated flags ([ruflo #3167](https://github.com/ruvnet/ruflo/issues/3167)), so +on those versions agentic-kit also uses scripted `--format json` mode and `RUFLO_NO_SKILLS_SH=1`; +both independently suppress the optional projections. On Ruflo 3.46.0 and newer the flags alone +are passed. Existing unreceipted skills remain review-only. A future upgrade may remove a stale projection only when its path and last-written digest are receipt-owned and the file is still unchanged. Generated settings, skills, agents and hooks remain subject to the upstream ownership and overwrite warnings in the table above. @@ -246,13 +249,19 @@ never touches the plugin cache or Claude Code's plugin state. `ak status` reads enabled bundles to report known placement, hook, and skill portability problems. All enabled hosts converge on the same project-scoped Ruflo memory contract. -Claude receives the absolute `CLAUDE_FLOW_DB_PATH` in project settings. Codex's -user-scoped Ruflo MCP registration launches `ak x ruflo-mcp`, which derives the -pin from the workspace at process start: the Git repository, else the folder -itself. When Codex starts at the filesystem root, in the home folder itself, in a -temporary root or inside a tool's own folder (`~/.codex`, `~/.claude`, `~/.config`, -and similar), the launcher uses one user-level store, `~/.claude-flow/memory`, -instead of creating `.swarm` there. OpenCode's managed MCP gateway and +Claude receives the absolute `CLAUDE_FLOW_DB_PATH` in project settings. The +user-scoped Ruflo MCP registrations of Claude Code (`ak x ruflo-mcp --host claude`) +and Codex (`ak x ruflo-mcp`) start ak's launcher, which derives the pin from the +workspace at process start: the Git repository, else the folder itself. Ruflo +starts at that root, so a session opened in a subfolder uses the repository's +store and MCP policy file. When a session starts at the filesystem root, in the +home folder itself, in a temporary root or inside a tool's own folder (`~/.codex`, +`~/.claude`, `~/.config`, and similar), the launcher uses one user-level store, +`~/.claude-flow/memory`, instead of creating `.swarm` there. `ak x harvest` +follows the same rule, and `ak setup --project` refuses in such a folder. The +Claude registration needs `ak` on the `PATH` Claude Code starts with, at a version whose +launcher takes `--host` (ak checks `ak x ruflo-mcp --help`); otherwise setup and sync leave +the existing registration in place and say so. OpenCode's managed MCP gateway and lifecycle bridge receive its project directory and set the same absolute pin. Ruflo's MCP tools use `.swarm/agentdb-memory.db` beside the pinned `.swarm/memory.db`; that sibling is the native store, not configuration drift. diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index b7fd01cb..8ef41ca9 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -37,22 +37,28 @@ ak sync # apply it | Codex receives automatic deja-vu recall while Agentic Kit says MCP mode | A user-owned Codex deja-vu plugin can contribute session/per-prompt/precompaction hooks independently of Agentic Kit's mode | disable/remove that plugin through Codex if MCP-only behavior is required. `ak sync` preserves external plugins and reports the effective auto surface without claiming a fix | | `--purge-deja-vu-data` refuses the index path | The observed path is broad, relative, outside an approved data root, overlaps config/transcript sources, or crosses a symlink | move/reconfigure the derived index safely, run `deja doctor --offline`, then retry. Never bypass the guard by deleting a host transcript root | | Just upgraded ruflo/agentic-qe (`npm i -g โ€ฆ`) and things feel off | Upgrades re-resolve dependencies: native SQLite bindings and the aidefence package get dropped, and ruflo's helper auto-refresh regenerates the statusline without the footer | `ak sync` (this is its main job) | +| `status` says `Ruflo โ€ฆ is unsupported: below the support window` | ak supports the newest six Ruflo minors, never fewer than those released in the last 30 days. Workarounds for Ruflo defects fixed before the window's floor have been removed, so an older Ruflo may misbehave | `ak sync` upgrades Ruflo. See [Ruflo support window](UPGRADING.md#2026-09-27-ruflo-support-window) | +| `status` says `Ruflo support window not yet known` | ak has not read Ruflo's release dates yet; `ak status` never looks them up itself | Run `ak sync` (not `--dry-run` or `--no-upgrade`): it reads and remembers them | | `status` shows a host `installed but not executable` | npm exits 0 even when an optional dependency fails, so a package can be recorded without its platform binary. Codex ships its binary as per-platform versions (for example `@openai/codex-darwin-arm64`) published minutes after the main version, so an upgrade in that window can leave `codex` unable to start | `ak sync` reinstalls an npm-owned host and verifies it starts; upgrades and installs already retry once with `--prefer-online`. An external (mise/native/brew) install is reinstalled with its own tool | | `status` shows `natives โ€ฆ WASM fallback` | agentdb resolved a non-native better-sqlite3 โ€” on this path **memory writes can silently vanish**. Common causes are npm โ‰ฅ11.17 blocking install scripts during upgrades, or a stale better-sqlite3 โ‰ค12.9 pin on Node 26 | `ak sync` selects a Node-compatible release and installs the native binding | | `status` says `ak applied Ruflo's native SQLite pin (ruvnet/ruflo#2219)` | To install a native better-sqlite3 where a bundled package could not find one, `ak sync` changed that package's own better-sqlite3 line (npm refuses the install otherwise). Ruflo pins better-sqlite3 to 12.8.0 or later for the same reason, but `npm install -g` does not apply Ruflo's pin. The row names each file, field, original value and ak's value | Nothing to do. `ak uninstall` puts each original value back where the file still holds ak's value. A Ruflo upgrade or reinstall replaces the file; `status` then says the edit is no longer there. Edits made before ak kept receipts are not listed and cannot be restored by ak; reinstall Ruflo if you want its shipped files back | | `status` shows `ruflo memory runtime on WASM fallback (โ€ฆ): no native binding` | The better-sqlite3 that Ruflo's memory runtime loads has no compiled binding; the row ends with the load error | `ak sync` builds the native binding | | `status` shows `ruflo memory runtime on WASM fallback (โ€ฆ): its native binding is present but will not load` | The binding file exists but was built for another Node.js version or platform, or is damaged; the row ends with the load error (for example `compiled against a different Node.js version`) | `ak sync` removes the binding that will not load, rebuilds it in place, and load-tests the result | | `status` shows `ruflo memory runtime backend unverified` | The load probe timed out twice or ended without a diagnostic, so native versus WASM is unknown. Sync does not act on an unverified probe | Re-run `ak status` when the machine is less busy. If it persists, `npx ruflo doctor` shows the runtime's own view | -| `status` shows `aidefence missing` | ruflo โ‰ฅ3.28 stopped shipping `@claude-flow/aidefence` but `ruflo security defend` still imports it โ€” injection defense is silently non-functional ([ruvnet/ruflo#2670](https://github.com/ruvnet/ruflo/issues/2670)) | `ak sync` reinstalls it; `ak x verify security` proves defend works (exit 1=threat / 0=clean) | +| `status` says `security defend uses Ruflo's built-in engine; @claude-flow/aidefence โ€ฆ is missing` | Ruflo does not declare `@claude-flow/aidefence` as a dependency, so an upgrade can drop it. `ruflo security defend` still screens prompts with Ruflo's built-in engine ([ruvnet/ruflo#2670](https://github.com/ruvnet/ruflo/issues/2670)); only adaptive learning and the `aidefence_*` MCP tools are missing | `ak sync` reinstalls it. `ak x verify security` reads defend's JSON verdict: it passes when defend flags an injection sample and passes a clean one | +| `ak x verify security` says `defend crashed before reporting a verdict (ruvnet/ruflo#3473)` | Ruflo's text-mode `security defend` crashes after it prints a detection. ak asks for `-o json`, which does not crash, so this means defend failed before giving any verdict | Re-run `ak x verify security`; if it repeats, run `ruflo security defend -i "ignore previous instructions" -o json` to see Ruflo's own output | | `status` shows oversized RVF store(s) | A runaway append after a hard exit grew a `.rvf` past the 2 GB cap (seen at ~277 GB once) | `ak sync` quarantines the oversized store; agentic-qe rebuilds it | | Statusline footer (๐Ÿง /๐Ÿ›ก/๐ŸŽ“ lines) disappeared | `@claude-flow/cli`'s version-stamped helper auto-refresh pristine-copies `statusline.cjs` on the **first ruflo command after an upgrade** โ€” including the statusline render itself | `ak sync` โ€” it now triggers that refresh *first*, then re-injects, so the footer survives; `ak status` flags an armed wipe before it fires | | Statusline footer is blank or stale with no visible error | Footer probes are intentionally silent during normal rendering | Set `AK_STATUSLINE_DEBUG=1` for one reproduction. Redacted stage/error metadata goes to `$XDG_STATE_HOME/agentic-kit/statusline-debug.log` (default `~/.local/state/agentic-kit/statusline-debug.log`, mode 0600, bounded at 64 KiB); set `AK_STATUSLINE_DEBUG_FILE` to redirect it, then unset debug | +| Statusline security line shows Ruflo's own scan status | ak no longer overlays Ruflo's security count: Ruflo fixed its fabricated CVE count in 3.32.2, below the support window. `ak sync` removes the overlay an older ak injected | Nothing to do. For a current result run `ruflo security scan`; use `npm audit` for dependency CVEs | | Statusline shows a Ruflo version you do not have installed (for example `RuFlo V9.9.9`) | Ruflo's helper bakes a version into `.claude/helpers/statusline.cjs` as a floor and shows the highest version it finds. A baked value above every install never corrects itself. `ak status` flags it on the `statusline` row | `ak sync`: it clears the helper stamp so Ruflo's own refresh regenerates the helper, then re-injects the footer. `ak` never writes the version. If Ruflo's refresh cannot run (`.claude/helpers/.LOCKED` or `RUFLO_HELPERS_LOCKED`), edit `let ver` in that file to the installed version or lower. A version newer than `ak status` can also come from a newer Ruflo copy the helper finds, such as the Claude plugin marketplace checkout. That is Ruflo's own choice and `ak` leaves it alone | | Codex's native status line did not change | Codex reads the user-wide setting when a session starts; an existing TUI may not hot-reload it | Exit and start a new Codex session; inspect ownership with `ak x statusline status` and drift with `ak status` | | The right side of Codex's status line is missing | Codex has one width-constrained native line | Widen the terminal or choose the compact preset with `ak x statusline codex native` | | Want the rich Ruflo/SONA/AQE display inside Codex | Codex currently accepts built-in status-line fields only, not a command-backed renderer | Keep the rich footer in Claude Code; see [Managed Codex status line](CODEX-STATUSLINE.md) for the current boundary | | Too many `โš™` daemons / stale daemons | One daemon per active project is normal (local-only workers, $0). Stale = workspace deleted or past the 12h TTL | `ak x daemon-gc --kill`; `sync` also reaps (and verifies the pid really is a ruflo daemon before killing) | -| `status` warns that the memory backup is old, or `daemons` says none runs for this project | Ruflo backs up and distills project memory only inside the project's daemon, which ends itself after 12 hours. Ruflo's start-on-use is off when `.claude/settings.json` has `claudeFlow.daemon.autoStart: false` (`ruflo init` writes it; `ak setup` keeps it) | Run `ruflo daemon start` in the project root, or `ruflo memory backup` for a one-off copy; see [Memory backup and distillation](#memory-backup-and-distillation) | +| `status` warns that the memory backup is old, or `daemons` says none runs for this project | Ruflo backs up and distills project memory only inside the project's daemon, which ends itself after 12 hours. Ruflo starts it again on the next `ruflo` command unless start-on-use is off (`claudeFlow.daemon.autoStart: false` in `.claude/settings.json`, which `ruflo init` writes) | `ak sync` turns start-on-use on unless `kit.json` has `rufloDaemon.autoStart: false`. Otherwise run `ruflo daemon start` in the project root, or `ruflo memory backup` for a one-off copy; see [Memory backup and distillation](#memory-backup-and-distillation) | +| `daemons` warns that the daemon is running but deferred distillation or backup | The daemon skips a job while CPU load or free memory is past its threshold. On macOS it undercounts free memory ([ruvnet/ruflo#2935](https://github.com/ruvnet/ruflo/issues/2935)) | On macOS in a Ruflo repository, `ak sync` sets the threshold in `.claude-flow/config.json` and restarts the daemon. When that file is unreadable or holds your own value, or on other systems, the row is a manual step: set the flat key it names in that file, then run `ruflo daemon stop` and `ruflo daemon start` | +| `daemons` warns that ak-managed daemon settings differ | The installed Ruflo needs different keys in `.claude-flow/config.json` (after an upgrade, or on a new project), or `ruflo init` turned start-on-use off again | `ak sync` | | `status` warns that `claude-flow.config.json` (or `.claude-flow/config.json`) points Ruflo memory away from the entries in `.swarm` | A command that saves Ruflo settings (`ruflo providers configure`, `ruflo config set`) created that file from Ruflo's defaults, whose `memory.persistPath` is `./data/memory` ([ruvnet/ruflo#3193](https://github.com/ruvnet/ruflo/issues/3193)). The MCP store and any `ruflo` command without ak's pin now look there | Set `memory.persistPath` to `".swarm"` in the file `status` names, or remove the key. `ak` does not edit a Ruflo configuration it did not write. `ak setup` and `ak sync` pin `.swarm` before registering providers, so they do not cause this | | Want to change which MCP tool families are callable | Exclusions are `permissions.deny` rules, persisted in kit.json | `ak x mcp pick` (re-runnable); `x mcp status` shows the inventory; `x mcp off` unregisters | | `status` says a legacy `ruflo`-keyed MCP registration is preserved | The entry is not the `ruflo mcp start` registration agentic-kit wrote (another path, `ruflo mcp`, a custom env key, or a project/local scope), so `ak sync` leaves it alone. With `claude-flow` also registered, Claude loads the Ruflo tools twice | Inspect it with `claude mcp get ruflo`, then run the command `status` prints (for example `claude mcp remove ruflo -s user`) if you don't need it | @@ -66,7 +72,7 @@ ak sync # apply it | `status` says an external `agent-browser` is outside Ruflo's range | You installed a newer `agent-browser` yourself. ak never replaces a user-managed install, so `sync` cannot clear this, and Ruflo's browser tools may not work with that version | Install a Ruflo-compatible `agent-browser` 0.27.x yourself, or set `agentBrowser: false` in `~/.config/agentic-kit/kit.json` to stop ak managing the executor (Ruflo MCP then no longer gets ak's trusted browser config or readiness checks) | | `status` lists a stray memory store | A tool wrote a store where this project's hosts do not read it, usually because it ran in another folder. ak only reports it | Nothing breaks. To keep its rows, inspect it read-only first; see [Stray memory stores](#stray-memory-stores) | | `status` shows a `memory-pin` warning | `CLAUDE_FLOW_DB_PATH` is pinned to a dead or foreign path, so every memory op targets the wrong DB ("Database not initialized" beside a healthy in-repo DB). The pin may be deliberate, so `sync` never touches it | repoint (or remove) the pin in `.claude/settings.local.json` `env` | -| MCP tool governance stays `unknown` | Ruflo 3.44.0 and earlier do not route stdio MCP tool calls through their policy enforcer, so no audit records are written even though ak wrote the policy file and set `RUFLO_MCP_ENFORCE_POLICY=1` | Nothing to fix on your side; the component confirms once ruflo wires enforcement (ADR-0058 upstream request 6). A project whose `.harness/mcp-policy.json` is invalid shows `mcpGovernance: blocked` instead: restore a valid, ak-written file and run `ak sync`, which also removes the enforcement variable for that project until the file is fixed | +| MCP tool governance stays `unknown` | No Ruflo MCP tool call was audited in the last 24 hours. Ruflo below 3.46.0 does not route stdio MCP tool calls through its policy enforcer, so no audit records are written there even though ak wrote the policy file and set `RUFLO_MCP_ENFORCE_POLICY=1` | Use a Ruflo MCP tool in the project; on Ruflo below 3.46.0 run `ak sync` to upgrade. A project whose `.harness/mcp-policy.json` is invalid shows `mcpGovernance: blocked` instead: restore a valid, ak-written file and run `ak sync`, which also removes the enforcement variable for that project until the file is fixed | | A [ruflo component](MANAGED-TOOLS.md#managed-ruflo-components) stays `applied, not verified` | Claude Code, Codex, and OpenCode read their environment only at process start-up, so a change setup or sync just made has not reached a running session yet | Restart Claude Code, Codex, and OpenCode, then run `ak status --refresh` to re-collect evidence with the new environment in effect | | Want to run `ak sync` but Claude/Codex/OpenCode sessions are open in other terminals | Upgrade-bearing syncs stop **all** ruflo daemons machine-wide and swap the global npm trees live sessions execute hooks/statusline/MCP calls from; even a no-upgrade sync can repair configuration or missing dependencies | `ak sync --dry-run` first; a `versions` row means idle the other sessions or use `ak sync --no-upgrade` (or `ak sync --skip versions` to hold back only the package upgrades); see [Running `ak sync` while sessions are live](UPGRADING.md#running-ak-sync-while-sessions-are-live) | | Suspicious token burn | Background automation vs interactive usage | ask Claude to run the **ruflo-token-audit** skill (deployed by `setup`) | @@ -320,11 +326,23 @@ reason a store gets large. A file with no memory table yet is reported as empty. Some folders never get a store: the filesystem root, your home folder itself, a temporary root such as `/tmp`, and folders that belong to a tool (`~/.codex`, `~/.claude`, `~/.config`, `~/.local`, `~/.cache`, `~/Library/Application Support`, -`%APPDATA%`). Codex often starts in one of these. Its Ruflo launcher (`ak x ruflo-mcp`) -then uses one user-level store, `~/.claude-flow/memory`. Run from such a folder, -`ak status` names that store instead of a project store. From anywhere, it reports -the user-level store once it exists. Claude's own Ruflo registration does not use -the launcher and is unchanged. +`%APPDATA%`). Codex often starts in one of these. The Ruflo launcher that Claude Code +and Codex both start (`ak x ruflo-mcp`) then uses one user-level store, +`~/.claude-flow/memory`. Run from such a folder, `ak status` names that store instead +of a project store. From anywhere, it reports the user-level store once it exists. + +### Old setup probe rows + +Earlier `ak setup` runs could leave rows with keys like `_setup/verify-12345-1700000000000` +(namespace `_setup`, content `setup-verify`) in a store. Ruflo copies each write into +`agentdb-memory.db` as well, and its own `memory delete` leaves that copy +([ruvnet/ruflo#3450](https://github.com/ruvnet/ruflo/issues/3450)). `ak status` warns +with the count per store, for the current project and the user-level store. `ak sync` +backs up each affected file under `~/.local/state/agentic-kit/memory-probe-cleanup/backups/` +(`%LOCALAPPDATA%\agentic-kit\memory-probe-cleanup\backups\` on Windows; with `VACUUM INTO`), deletes exactly those rows from both files, writes a receipt beside +the backups, and records the store in `kit.json` so it never cleans it twice. +`ak sync --dry-run` shows the counts first. Rows in other projects are cleaned when you +run `ak sync` there. ### Stray memory stores @@ -338,7 +356,7 @@ each one by owner, for information only. ak never moves, merges or deletes them. | `./agentdb.rvf` | AgentDB's RVF backend, which defaults to the working directory | | `./ruvector.db` | RuVector's default store (`ruvector mcp start`; `ruflo memory init` also creates one) | | A `.agentic-qe/` below the project root | AQE resolves a relative `AQE_MEMORY_PATH` against the folder a command or hook ran in | -| `~/.swarm`, or `.swarm` folders under `~/.codex/.chatgpt-projects/` (reported from any project) | Ruflo ran with your home folder or a Codex ChatGPT project folder as its working directory, before Codex's launcher used the user-level store there | +| `~/.swarm`, or `.swarm` folders under `~/.codex/.chatgpt-projects/` (reported from any project) | Ruflo ran with your home folder or a Codex ChatGPT project folder as its working directory, before ak's launcher used the user-level store there | Ruflo's rotated backups in `.swarm/backups/` are not strays. The search skips `node_modules`, `.git` and the contents of dot folders such as `.claude/worktrees`, @@ -358,12 +376,30 @@ from the files Ruflo writes in `.claude-flow/metrics/` and the newest snapshot i runs for the project. A failed attempt is always a warning. - An old distillation is information only. A failed or corrupt run is a warning. - The `daemons` row is information, not ok, when the project has memory and no - daemon, and it names the setting that stops Ruflo starting one on use. - -The daemon ends itself after 12 hours, sooner if its workers stop running. `ak setup` -starts one, but Ruflo's start-on-use is off in a project set up by `ruflo init` or -`ak setup` (`claudeFlow.daemon.autoStart: false` in `.claude/settings.json`). Backups -therefore stop within a day of setup unless you start the daemon again: + daemon. It says Ruflo starts one on the next `ruflo` command, or names the + setting that stops it. +- The `daemons` row warns when a running daemon deferred backup or distillation + and has not run it since. + +The daemon ends itself after 12 hours. Ruflo starts a new one on the next `ruflo` +command in the project unless start-on-use is off. `ruflo init` turns it off +(`claudeFlow.daemon.autoStart: false` in `.claude/settings.json`); `ak setup` and +`ak sync` turn it back on and keep the old value for `ak uninstall`. They also +write the flat keys Ruflo's daemon needs in `.claude-flow/config.json`: a free-memory +floor of 0 on macOS, where Ruflo undercounts free memory +([ruvnet/ruflo#2935](https://github.com/ruvnet/ruflo/issues/2935)), and +`daemon.idleSecs: 0` on Ruflo older than 3.46.0, whose daemon ended itself early +([ruvnet/ruflo#3194](https://github.com/ruvnet/ruflo/issues/3194)). ak never uses +`ruflo config set` for these. A file that is not a JSON object, or a key that holds your +own value, is left alone, and `ak status` names the key to set yourself. ak writes these keys +only in a repository Ruflo already treats as a project (it has `.swarm/memory.db`, a Ruflo +config file, a `claudeFlow` block in `.claude/settings.json`, or a Ruflo server in `.mcp.json`), +never in one that has just an empty `.claude-flow/` folder, since the file would make Ruflo +start a daemon there. + +To leave start-on-use as Ruflo set it, add `"rufloDaemon": { "autoStart": false }` +to `kit.json` and run `ak sync`; it puts back a value it changed. You can always +start the daemon or take a backup yourself: ```bash ruflo daemon start # in the project root; runs both workers until it ends diff --git a/docs/UPGRADING.md b/docs/UPGRADING.md index 56bc7c77..d2ca15fb 100644 --- a/docs/UPGRADING.md +++ b/docs/UPGRADING.md @@ -48,6 +48,32 @@ old hosts and origins, so the Footprint snapshot schema advances to v8. This bui snapshot as unreadable until you run **Full scan** in System or `ak system --deep`. It is never shown under the new rule. See [ADR-0060](adr/0060-session-surface-initiator-and-product-names.md) ยง3. +## 2026-09-27: Ruflo support window + +ak supports the newest six Ruflo minor versions, and never fewer than the minors released in the +last 30 days. The oldest supported minor is the window's floor (for example `3.39.0`). `ak status` +shows a `versions` row for it: + +- **inside the support window**: your Ruflo is supported; the row names the floor and when ak last + read Ruflo's release dates. +- **unsupported**: your Ruflo is below the floor. ak's workarounds for Ruflo defects fixed before + the floor are gone, so an older Ruflo may misbehave. Run `ak sync` to upgrade it. +- **not yet known**: ak has not read Ruflo's release dates yet. Run `ak sync`. + +`ak status` never looks the dates up itself. A plain `ak sync` reads them from npm and remembers them +in `kit.json` (`versionCheck.rufloMinors`); `ak sync --dry-run` and `ak sync --no-upgrade` do not. + +## 2026-09-27: ak keeps its MCP policy file out of git + +In a Ruflo repository where MCP tool governance is on, the next `ak sync` or `ak setup --project` +adds two lines to the repository's `.git/info/exclude`: `# agentic-kit` and +`/.harness/mcp-policy.json`. git then ignores the policy file ak writes. No tracked file changes: +ak never edits `.gitignore` and never ignores the rest of `.harness/`. If you already committed +ak's policy file, the line does not untrack it; run `git rm --cached .harness/mcp-policy.json` if +you want it out. When ak removes its policy file (governance turned off, or `ak uninstall`), it +removes the two lines too; a policy file you edited is yours, so ak leaves it and the lines. On Ruflo 3.46.0 +and newer the policy is enforced on the stdio MCP launches, so calls beyond the cap are refused. + ## 2026-09-26: `ak sync`'s exit code ignores fixes you do by hand `ak sync` now exits 0 when everything it can repair has converged, even if a row whose fix you @@ -73,6 +99,23 @@ rest. A Ruflo upgrade or reinstall replaces the edited files, and ak then forget made by earlier releases have no receipt: ak cannot show or restore them. Reinstall Ruflo if you want its shipped files back, then run `ak sync`. +## 2026-09-27: Claude Code's Ruflo MCP starts through ak's launcher + +The next `ak sync` (or `ak setup`) replaces ak's user-scope `claude-flow` registration +(`ruflo mcp start`) with `ak x ruflo-mcp --host claude`, the launcher Codex already uses. Claude +Code sessions then use the same store as Codex: the repository's `.swarm` from any subfolder, and +the user-level store `~/.claude-flow/memory` from your home folder, a temporary root or a tool's +own folder. Ruflo also reads the repository's MCP policy file from a subfolder. A registration you +wrote yourself (another command, scope or environment key) is left alone. The launcher must be on +the `PATH` Claude Code starts with, and that `ak` must be a build whose launcher takes `--host` +(ak checks `ak x ruflo-mcp --help`). If `ak` is not found, or it is an older install whose launcher +has no `--host` option, sync keeps the old registration and says so, and `ak status` lists the step as yours: put `ak` on `PATH` (or update +it), then run `ak sync`. Restart Claude Code to pick up the new registration. + +The same sync removes ak's old setup probe rows (`_setup/verify-โ€ฆ`) once, from both memory files of +the current project and of the user-level store, after backing each file up (see +[TROUBLESHOOTING](TROUBLESHOOTING.md#old-setup-probe-rows)). + ## 2026-09-26: Codex's Ruflo memory outside a project Codex's Ruflo launcher (`ak x ruflo-mcp`) no longer creates a `.swarm` store at the filesystem @@ -82,7 +125,7 @@ Sessions started there share one user-level store, `~/.claude-flow/memory`. Repo work folders keep their own `.swarm` as before. Earlier sessions may have left `~/.swarm` or `.swarm` folders under `~/.codex/.chatgpt-projects/`. `ak status` lists them for information and never moves or deletes them; inspect one read-only before you remove it. Restart Codex for a -running Ruflo server to pick up the new location. Claude's own Ruflo registration is unchanged. +running Ruflo server to pick up the new location. ## 2026-09-26: Registering a provider keeps Ruflo memory in `.swarm` diff --git a/docs/UPSTREAM-WATCH.md b/docs/UPSTREAM-WATCH.md index 6b6f59a4..abff28ab 100644 --- a/docs/UPSTREAM-WATCH.md +++ b/docs/UPSTREAM-WATCH.md @@ -33,7 +33,7 @@ A watch entry records: |---|---| | `id`, `url`, `kind`, `title` | The thread (`owner/repo#n`, issue or pr). | | `relation` | `filed`, `commented`, `referenced` (cited, not ours) or `tracking` (our own issue that waits on upstream threads; lists them in `tracks`). | -| `dependency` | The dependency policy that governs it. AgentDB threads use `ruflo`: ak gets AgentDB through Ruflo, so an AgentDB fix counts as released only when the newest Ruflo (npm `latest`, the newest version in the support window) installs a fixed agentdb (`doneWhen.release.bundledBy`). AgentDB publishes no tags, so a fix is confirmed by hand and recorded as `minVersion` until then. | +| `dependency` | The dependency policy that governs it. AgentDB threads use `ruflo`: ak gets AgentDB through Ruflo, so an AgentDB fix counts as released only when the newest Ruflo (npm `latest`) installs a fixed agentdb (`doneWhen.release.bundledBy`), and it waits for the support window until the oldest supported Ruflo does too. AgentDB publishes no tags, so a fix is confirmed by hand and recorded as `minVersion` until then. | | `doneWhen` | `closed-completed` or `merged`, plus the release channel, the first fixed version when known, the upstream tag spelling (`tagPattern`) when it is not `v`, and the carrier chain (`bundledBy`) when ak gets the package through another. | | `mapping`, `kitImpact`, `adjustment` | Whether ak carries something for it, which files and plan or decision refs, and the change ak makes when it lands. | | `status`, `history` | Lifecycle status and dated events. A `reviewed` event (with a `note`) records that every comment up to the end of that UTC day was read and needs no reply. History carries dates, not times, so a comment posted later on the day of the review is covered too: record a review only after the day's comments are read, or on a later day. | @@ -85,6 +85,11 @@ node scripts/upstream-watch.mjs report [--json] node scripts/upstream-watch.mjs check --since [--ledger ] [--json] ``` +The Ruflo support window (the newest six minors, never fewer than those released in the last +30 days; `supportWindow` on the Ruflo dependency policy, ADR-0041 ยง7) comes from the npm release +dates the check reads. When they cannot be read, or `gh` is signed out, nothing is held for the +window. + `report` gives counts, then these groups (a thread can be in more than one): | Group | Rule | @@ -93,6 +98,7 @@ node scripts/upstream-watch.mjs check --since [--ledger ] [--js | Released and actionable | Upstream fixed, and a published release contains the merged fixing pull request (or closing commit), checked against the repository's tag for that version, or the registry records the first fixed version (`minVersion`). The entry is `watching` or `fixed-unreleased` and ak has an adjustment. Carries the dispatch branch and removal proof. | | Released, fix not confirmed | A release came out after the fix, but ak could not prove it contains the fixing change (no merged pull request closed the thread, or no tag for that version). Confirm by hand and record `minVersion`. Never dispatched. | | Fixed upstream, ak still carries the workaround | The entry is `released` or `dispatched` and ak has an adjustment. | +| Released, waiting for the support window | A Ruflo entry that would be in one of the two groups above, but its first fixed version is above the Ruflo support window's floor (`supportWindow.floor` in the JSON report), or an AgentDB entry whose fixed agentdb the floor Ruflo does not yet bundle. No dispatch: the workaround stays until the oldest supported Ruflo has the fix. | | Fixed upstream, not yet released | Upstream fixed, no release contains it, the entry is `watching` or `fixed-unreleased`, and ak has an adjustment. | | Reopened upstream | Open upstream while the entry says fixed, released, dispatched or adopted. | | Waiting on upstream | Open, not stale, and nobody is waiting on us. | @@ -122,7 +128,8 @@ fixing change when the release was confirmed from it), `reopened`, `stale`, `retire-proposed`, `retest-due` (constraint id) and `idle` (id `registry`, nothing left to watch). `check --since` limits replies, acknowledgements, closures and merges to activity after `--since`. The other events repeat while their condition holds, dated by the upstream fact, so -the same fact always gives the same line. `--ledger ` drops any line already in that file, +the same fact always gives the same line. A `released` line for a fix held for the support +window has no `branch=` field; the line with one appears once the window's floor contains the fix. `--ledger ` drops any line already in that file, so an exact line the routine recorded is never acted on twice. The file holds only the routine's own comments: a line someone else posted would suppress a real event. Each posted comment ends with `checked-at