Sentinel

Inspiration

Every AI coding agent on the market right now asks for the same thing: shell access, your Git credentials, and free rein over a real repository. And in return, you get its word for what it did. "I ran the tests, they passed. I only touched three files." That's not evidence — that's a self-report, written by the exact same system you're supposed to be checking up on. It's like asking a suspect to write their own police report.

That gap, between what an agent says happened and what actually happened, is where real damage lives. A quietly force-pushed branch. A .env file read and never mentioned. A test suite that "passed" because three assertions got quietly deleted. By the time a human notices, the working tree, the commit history, or a pushed branch has already changed — and there's nothing independent to check the story against.

We didn't want a better prompt, a stricter system message, or an agent that promises to behave. We wanted something that doesn't have to trust the agent at all: a witness that sits outside it, watches with its own eyes, and writes down what happened whether the agent likes it or not.

What it does

Sentinel is a local-only change assurance runtime for Windows — it sits between an AI coding agent and your real Git repository like a flight recorder, and it never asks the agent to self-report anything.

Here's what actually happens on a run:

It launches the agent under real Windows process-tree supervision. Not a wrapper script that trusts the agent's own logs — genuine OS-level oversight of every process the agent spawns, so "what ran" is a fact, not a claim.
It fingerprints your repo, your environment, and your dependencies before the agent touches anything — and again the instant it's done. Diffing those two snapshots is how Sentinel knows exactly what changed, independent of anything the agent says.
Every mutation gets written to a hash-chained, tamper-evident journal, the same idea behind a blockchain's integrity guarantee — if even one entry is altered after the fact, the chain breaks and it's detectable.
It never hands the agent a raw secret. A credential broker issues short-lived, scoped grants instead — the agent gets exactly enough access to do the job, and nothing durable it can leak, log, or exfiltrate.
Git inspection is read-only, permanently. The only way a repository gets mutated is through a recovery action a human has previewed and explicitly approved — an agent, on its own, cannot rewrite your history no matter what it decides to do.
At the end of a run, Sentinel signs a Change Passport — a deterministic, independently generated, cryptographically verifiable report of exactly what happened. Not the agent's summary. Ours.

And it's not a proof-of-concept CLI script — it's a real product surface. A FastAPI backend, a scriptable CLI, a full Textual terminal UI, and an Electron desktop app, all four driven off one single frozen OpenAPI contract — 66 operations, 61 routes, 110 schemas — so whichever way you interact with Sentinel, you're getting the exact same guarantees, not a subset of them.

How we built it

We started from the contract instead of the code: a frozen set of Pydantic models and Protocol ports (GitInspectionPort, PolicyPort, CredentialBrokerPort, RecoveryPort, PassportPort, and others) that every module — Git, policy, credentials, providers, recovery, passport — implements independently against. That let the policy engine, the credential broker, and the Git evidence collector get built in parallel without any of them knowing about each other's internals, and let us swap real adapters for fakes in tests without touching a single call site.

On top of that we layered:

A deny-by-default policy engine that returns explainable decisions instead of throwing.
A SQLite-backed Change lifecycle with idempotent, replay-safe mutations.
A constrained, non-destructive Git recovery engine.
A GitHub provider layer that only ever acts through the credential broker's short-lived grants, never a raw token.

Challenges we ran into

Getting the Windows process supervision right was harder than expected. Launching an agent and actually tracking everything it spawns means dealing with job objects, token privileges, and process trees that Windows doesn't make easy to observe from the outside. Our first version of the launcher only lowered the agent's token privileges while it kept the same integrity level as the process that launched it — real, but not an actual sandbox. Getting from there to something closer to a true isolation boundary (Windows AppContainer) turned into its own research project, and we're still working through it.

We also had to be careful with the Git recovery engine. It's tempting to let a "helpful" recovery path just fix things automatically, but if a recovery routine can rewrite history on its own, the whole evidence chain stops being trustworthy. We ended up requiring every recovery action to go through a preview step before it's approved and applied, no exceptions, which took longer to build but was the only way to keep the non-destructive guarantee real instead of just documented.

Accomplishments that we're proud of

We didn't build a demo. We built a real system, end to end, in a weekend:

1,022+ passing tests — not smoke tests, a full suite including adversarial tests written to actively try to break our own safety claims.
A full threat-model review, 16 findings identified and all 16 closed, before we let ourselves call any part of it finished.
One frozen OpenAPI contract — 66 operations, 61 routes, 110 schemas — powering four completely different, fully working surfaces: a FastAPI backend, a scriptable CLI, a Textual terminal UI, and an Electron desktop app, all reading from the exact same contract with zero drift between them.
A complete Change lifecycle, live: create, list, get, update, transition, cancel — backed by SQLite with idempotent, replay-safe mutations, so retries never double-apply a change.
Real forensic evidence capture around every single agent run: Git state, environment, and dependencies snapshotted before and after, chained into a tamper-evident, hash-chained journal.
Actual Windows process-tree supervision for the launched agent — not a diagram, working code that watches what an agent spawns in real time.
A credential broker that is the only code path in the entire system allowed to touch a durable secret, issuing short-lived grants instead of ever handing an agent a raw token.
Live GitHub PR integration, running through that same broker, plus a full recovery engine with a hard preview-before-execute gate — nothing touches your repo without you seeing it first.
A working Change Passport builder that turns everything Sentinel observed into a signed, deterministic, exportable report — the actual proof this whole system exists to produce.
We held the line on zero safety theater: every single claim Sentinel makes about what it protects against is backed by a real test we wrote to try to disprove it — and where the code didn't back up a claim yet, we rewrote the claim instead of shipping the gap quietly.

What we learned

That the credibility of a safety tool comes from what it refuses to claim, not just what it does. It's easy to make an AI supervision tool sound airtight. It's much harder, and much more valuable, to draw the exact line between "we reduced this risk" and "we eliminated it," and then build the tests that keep that line honest as the code changes underneath it.

What's next for Sentinel

The next milestone is the big one: wrapping the agent launcher in a real Windows AppContainer, so lowered privilege stops being a mitigation and becomes an actual enforced boundary the agent can't step outside of, no matter what it's told or tricked into running. Job Objects and restricted tokens layer on top of that to lock down what a launched process — and everything it spawns — is allowed to touch on the machine at all.

Past that, we want to close the loop between the Change Passport and the outside world: pushing passports into CI so a PR can carry cryptographic proof of exactly what an agent did before a human ever has to take its word for it, and building out policy presets so teams can drop Sentinel in front of an agent and get a sane default posture on day one instead of hand-writing rules. Long term, the same evidence pipeline that watches a single agent run generalizes to watching a whole fleet of them — which is where this actually needs to go as more of the software we run starts being written by something that isn't us.