Fusebase Flow Health Check

Purpose

Verify the local Fusebase Flow overlay and the shared FuseBase CLI / Flow agent surfaces without writing to the repository. The health engine now separates failures by ownership layer:

Bounded execution + flags (v3.24.0+)

The verdict-affecting operations (preflight, conflict reporter, the upstream git fetch) are bounded so a network-impaired or large-repo host can't make the read-only diagnostic appear to hang. A timed-out/skipped critical check ⇒ PARTIAL_UNVERIFIED (never a false HEALTHY). (v4.2.0+) the hook-layer integrity critical is a fast single-pass manifest hash-compare (audit/hook-layer-manifest.json; seconds, OS-independent), so a full HEALTHY verdict is now reachable on Windows/Git-Bash without --fast — a mismatch names the exact drifted file (FLOW_LAYER_DRIFT, exit 1) and also catches local tampering. The upstream comparison is optional — its fetch timing out is a "upstream not verified" note only and never forces exit 4.

Env knobs (seconds; POSIX defaults in parentheses): FFHC_FETCH_TIMEOUT (15), FFHC_PREFLIGHT_TIMEOUT (30), FFHC_CONFLICT_TIMEOUT (30), FFHC_MANIFEST_TIMEOUT (30, the hook-layer integrity critical), FFHC_TESTS_TIMEOUT (60, the optional --run-hook-tests deep run only). An explicit env value always wins over the default on either platform. If neither timeout nor gtimeout exists, the bounded ops are skipped ⇒ PARTIAL_UNVERIFIED (install coreutils, or opt into unbounded runs with FFHC_ALLOW_UNBOUNDED=1). Worst-case bounded full run ≈ 155s.

Windows/MSYS under load (WS4, v3.30.3). Git-Bash/MSYS spawns each process in ~0.8–1.4s (vs ~1–3ms on Linux/macOS), so the flat 30/60s preflight/tests budgets routinely time out a healthy MSYS install under CPU load and surface a spurious PARTIAL_UNVERIFIED. On MINGW*/MSYS*/CYGWIN the engine auto-raises the defaults to FFHC_PREFLIGHT_TIMEOUT 60 / FFHC_TESTS_TIMEOUT 120 (fetch/conflict stay flat — network/git are platform-agnostic). When a run still lands PARTIAL_UNVERIFIED, the recommendation prints the exact knob name + its current effective value (e.g. FFHC_TESTS_TIMEOUT=120s) plus the detected platform, so raising the named budget and re-running is copy-ready. This is a timeout budget only — it never changes the verdict logic: a genuine FAIL: or an rc0-no-run crash still reads BROKEN regardless of platform (the fail-closed guard is untouched).

Installed-CLI version gate

hooks/local/lib/cli-version-check.sh probes fusebase --version at health-check time and compares it to the CLI snapshot this Flow edition's assets were vendored from.

Every outcome states three things: the version found, the bundled snapshot, and the next step.

Exactly one hard failure, and it is the only one backed by evidence. Below 0.29.0 the vendored documents are known-incompatible — verified at 0.25.16, where --app resolves by local path (not app id) and the commands Flow shipped were unrendered ETA templates.

Newer than the snapshot is an advisory, not a problem. After a full fusebase update the CLI rewrites the adopter's provider skills from its own current template, so their local documents are correct for their installed CLI. The only thing unknown is whether a Flow maintainer has reviewed that version — that is Flow's status, not the adopter's defect, and reporting it as a non-green verdict asks them to fix something that is not broken. (It also does not fit PARTIAL_UNVERIFIED, whose remediation is re-running an incomplete check; "supply an upstream CLI tree" is a different condition.)

fusebase absent is likewise exit 0. CI runners, containers and any machine that only edits the framework have nothing to fix. The advisory is verdict-neutral and, like the approval age warnings, is printed outside every count — it can move neither the verdict nor the exit code.

Nothing is trusted that was not established. The probe's exit code must be 0, and the version must be declared on a whole line in one of the two documented shapes (bare X.Y.Z, or FuseBase CLI X.Y.Z). A version embedded in a banner line, a pre-release/build suffix, a fourth component, trailing text, or two conflicting declarations all read as not determined — never as the nearest known version. Softening the outcome to an advisory does not soften this: an advisory reporting a version nobody established is a false claim with a gentler exit code. The incompatibility line is not env-overridable — it is the one remaining hard failure, so it is the one that must not be movable.

Split @fusebase/* installs are a CLI advisory too. With fusebase.json at the repo root, hooks/local/lib/fusebase_package_split.py resolves each @fusebase/* dependency of every package.json (skipping node_modules/ and dot-directories) the way Node does, and prints one line per package installed at more than one version, naming each version's roots — separate SDK copies break instanceof checks such as ApiError. Verdict, counts and exit code are unchanged. Owner: FuseBase CLI version management; fix: align those package.json entries, then npm install in each root — never fusebase update, which rewrites only the root and SPA package.json and is how the split arises. Bounded by FFHC_CLI_PACKAGES_TIMEOUT (10 s); a scan that does not complete says so in one advisory line.

Advisory signals (informational — never change the verdict or exit code)

The conflict reporter (check-cli-flow-conflicts.sh) also emits advisory findings for vendored CLI-owned assets. These are info-only: they do NOT flip the verdict away from HEALTHY and do NOT change the exit code. Restoration of CLI-owned content always stays with the FuseBase CLI; Flow only diagnoses.

Procedure

1. Confirm the engine exists:

   test -f hooks/local/fusebase-flow-health-check.sh

2. Run the read-only engine:

   bash hooks/local/fusebase-flow-health-check.sh

3. Optionally run the no-write ownership report for more detail:

   bash hooks/local/check-cli-flow-conflicts.sh

   This report also surfaces the advisory findings CLI_SNAPSHOT_STALE (a present CLI asset differs from the bundled provenance sha256), CLI_CUSTOM_AT_RISK (a drifted CLI skill carries a CUSTOM:SKILL block), CLI_STOP_UNVERIFIED (a Flow-merged project with no state/audit/cli-stop-baseline.json receipt), and CLI_STOP_BASELINE_DRIFT (a baselined CLI Stop hook is gone). All are informational only — they do not change the verdict or exit code. Provenance lives in audit/cli-vendor-manifest.json (re-stamp: bash hooks/local/stamp-cli-provenance.sh); the Stop receipt is written by bash hooks/local/post-fusebase-update.sh --wire-hooks.

4. Interpret exit code:

   Exit	Verdicts
   0	HEALTHY (every critical check ran clean)
   1	CLI_LAYER_DRIFT, CLI_VERSION_UNSUPPORTED, FLOW_LAYER_DRIFT, SHARED_MERGE_DRIFT, PARTIAL_UPGRADE, PUBLISHER_PACKAGING_DRIFT
   2	BROKEN
   3	EXCEPTION_IN_EFFECT
   4	PARTIAL_UNVERIFIED (a critical check did not run — partial/unverified; not full health, not a hard failure)

   Callers that branch on the exit code must treat 4 as partial/unverified — re-run or raise a timeout knob; never read it as healthy and never hard-fail a pipeline on it without distinguishing it from drift/breakage.

5. If verdict is FLOW_LAYER_DRIFT or SHARED_MERGE_DRIFT, ask in chat before writing:

   Run Flow recovery now? Reply yes, run it, fix it, or proceed and I will execute bash hooks/local/post-fusebase-update.sh, then re-run the health check.

6. If the operator already gave an affirmative in the same turn, that counts as confirmation for this recovery action. Execute:

   bash hooks/local/post-fusebase-update.sh
   bash hooks/local/fusebase-flow-health-check.sh

7. If verdict is CLI_LAYER_DRIFT, do not run Flow recovery as the first step. Say:

   CLI-owned files need the current FuseBase CLI to restore them. Run the current FuseBase CLI refresh/update for this project first, then run bash hooks/local/post-fusebase-update.sh.

Recovery Boundary

post-fusebase-update.sh restores only Flow-owned assets and shared Flow additions:

• Flow skills into .claude/skills/ and .agents/skills/
• Flow agents into .claude/agents/ and .codex/agents/
• Flow overlay blocks in AGENTS.md and CLAUDE.md
• Flow lifecycle hooks merged into .claude/settings.json
• fusebase-flow-health-check skill mirrors
• .claude/commands/fusebase-health.md

It does not patch or restore .claude/hooks/**, FuseBase CLI provider skills, MCP configs, fusebase.json, skills-lock.json, or active .codex/config.toml content. Those are CLI-owned or project-owned surfaces.

The advisory signals (CLI_SNAPSHOT_STALE, CLI_CUSTOM_AT_RISK, CLI_STOP_UNVERIFIED, CLI_STOP_BASELINE_DRIFT) never trigger Flow recovery: a present-but-changed CLI asset is the CLI's to manage, a CUSTOM:SKILL block is a user edit Flow must not clobber, and a missing/unverified CLI Stop hook is a non-Flow edit (the preserve-only merge never drops one). Flow only reports them so the operator can act (re-stamp provenance, back up CUSTOM blocks, or re-run --wire-hooks to re-baseline the Stop receipt).

Output Shape

Report:

• Verdict
• Layer that drifted
• Concrete next action
• Whether recovery was offered, declined, or executed
• Re-check result when recovery runs

Keep chat output brief and concrete. Do not paste the full engine transcript unless the operator asks.