KeyTurn — makes “done” a result you can check

Why editing the files is not enough

Apps read .env.production when they start. Running apps keep the old password until they are recreated.

Connection pool (PgBouncer) has its own config and auth file, and keeps open sessions that logged in with the old password.

Database stores the role's password. Until it changes, the old password still works — and nothing looks broken.

In our lab, under a short request, plain IBM Bob edited every copy of the password in the files and listed the live steps as next steps — three times out of three the old password still worked. With the outcome spelled out, plain Bob succeeded. The gap is the definition of “done”; KeyTurn makes it a reusable check.

How it works inside IBM Bob

Three custom modes
KeyTurn Inventory (read-only: every copy and who reads it) → KeyTurn Plan (ordered handover, either method) → KeyTurn Execute (checks after every step).

A skill
credential-handover: what “complete” means, both valid methods (same user, new user), and never printing a secret.

A gate hook (PreToolUse)
Refuses covered unsafe steps with the reason, e.g. restarting the apps onto a password the database would reject.

A done-check hook (Stop)
Records VERIFIED, FAILED or UNVERIFIED next to the work. It records; Bob's Stop hook cannot block “done”.

A 12-tool MCP checker, no AI
Login tests, running config, sessions, customer probes, a transition watch, restart / reconnect / migration / delayed-job tests, the three proofs, the record.

The three proofs
1 customers on the new credential · 2 old credential refused, no old sessions · 3 recreate, reconnect, restart, migration and a queued job all pass. VERIFIED only on the current state.

Installed in Bob (real screenshots)

Bob Settings, Modes: KeyTurn Inventory, Plan and Execute listed as workspace modes — Modes: the three KeyTurn modes (workspace).

Bob Settings, Hooks: three active workspace hooks — Hooks: UserPromptSubmit, PreToolUse, Stop — active.

Bob Settings, MCP: keyturn server connected — MCP: the `keyturn` server, connected.

IBM Bob using KeyTurn

Genuine IBM Bob session · P2, 26 Sep · KeyTurn v0.1 · 35.07 Bobcoins

Same short request as the failing runs. Bob used the KeyTurn modes and tools, traced the credential copies, planned the change and ran the checks; every final check passed (n = 1).

Bob task: the short request and the credential-handover skill loading — The short request; Bob loads the `credential-handover` skill.

Bob switches to keyturn-plan mode — Bob switches to KeyTurn Plan mode.

Bob's handover plan as a sequence diagram — Bob's plan: files, password change, pool reload, app recreate.

KeyTurn v0.1 gate refuses ALTER ROLE — v0.1's gate refuses a step. This v0.1 gate was over-strict (it allowed only the new-login method); v0.2 accepts both methods. Lab password masked.

Bob's final message: all three proofs pass — End of the task: all three proofs pass.

Latest: a read-only check with KeyTurn 0.2.1

Genuine IBM Bob session · P3, 27 Sep · KeyTurn 0.2.1 · Ask mode · 0.121 Bobcoins

A script left the lab half-changed (files on the new password, database unchanged). Asked to check without changing anything, Bob called KeyTurn’s checks (five tool calls) and answered: “The handover is not complete — all three required proofs fail.” It changed nothing; KeyTurn's done-check recorded FAILED. One of Bob's eight next steps was based on a misread hash (it said the pool's auth file held the old hash; it held the new one).

Bob P3 verdict: not complete — Bob's verdict. Lab password masked.

Bob P3: proof results all fail — Proof results, from KeyTurn's checks.

Bob P3: ordered next steps — What is still needed, in order (step 3 is unnecessary — see above).

A real handover record

Scripted lab demonstration · KeyTurn 0.2.1 (code 3e742248) · synthetic data · not Bob

This is the record KeyTurn wrote at the end of demo run 5. It opens with the current verdict, lists the three checks, what the transition watch saw (3 of 10 sampled journeys failed during the change), the steps the gate refused, and KeyTurn's known limits. Open it full-page.

Replay the real lab run

Scripted operator, not Bob · real terminal output · idle pauses shortened

Demo run 5 on real Mastodon + PgBouncer + Postgres: files changed but not the live password (FAILED) → unsafe restart refused with the reason → ordered change with the watch running → restart and migration tests → VERIFIED → a file edit and a restart make it UNVERIFIED until the proofs run again.

Every run, nothing left out

Small lab trials; prompts differ

Run	Who	Request	Result
P2a 1–3	Plain IBM Bob	short	0 of 3 — files edited, live password unchanged
P2	Bob + KeyTurn v0.1	same short request	1 of 1 — all final checks passed (35.07 Bobcoins; over-strict gate and a timeout bug added cost)
P2b	Plain IBM Bob	outcome spelled out	1 of 1 — all final checks passed (2.42 Bobcoins; cap raised mid-run)
P3	Bob + KeyTurn 0.2.1	read-only check	found the half-changed handover not complete; changed nothing (0.121 Bobcoins)
Lab tests	KeyTurn 0.2.1, scripted, not Bob	—	unit 81/81 · same user 69/69 · new user 55/55

Judged by the same fixed checker (no AI) for P2a, P2 and P2b. No speed, cost or cause-and-effect claim. Full reports, Bob's messages, KeyTurn logs and task-cost screenshots: evidence/ and bob_sessions/.

Run it yourself

git clone https://github.com/pvgirish/keyturn && cd keyturn/lab/harness
./setup_stack.sh && ./before_p2a.sh        # Docker; builds the lab in ~/mastodon-ops
./install_keyturn.sh                       # installs KeyTurn into that Bob workspace
python3 -m unittest discover -s ../../keyturn/tests   # 81 tests, Python 3.9+ standard library

Open ~/mastodon-ops in IBM Bob, check Settings → Modes, Skills, Hooks and MCP, and ask Bob to rotate the database password. Synthetic lab data only.

Limits

One deployment shape today: apps → PgBouncer (auth_file) → Postgres, in Docker.
Covered commands only: script files, Python/Ruby file writes, podman and interactive psql are not gated (the proofs still judge the end state).
Customer checks are sampled about every 5 s. No zero-downtime promise.
Bob's Stop hook cannot block “done”; KeyTurn records a verdict instead.

KeyTurn makes “done” a result you can check.

The video