System Online

Sentinel

Watches production. Attributes errors. Spawns fixers. Tightens contracts. Closes the loop between runtime and specification.

$ pip install sentinel-monitor click to copy

How It Works

Error to fix in five steps

◉

Detect

Tail logs, watch processes, receive webhooks for error signals

⎔

Attribute

Extract PACT keys, look up component in manifest, compute severity

⚙

Fix

LLM generates reproducer test + source fix, validates in temp dir

↻

Tighten

Push updated contract to Pact so this class of error cannot recur

✓

Report

Trust events to Arbiter, signals to Stigmergy, webhook notifications

Capabilities

Built for production feedback loops

Attribution

PACT Key Extraction

Parses PACT:component:method from log lines. Registered keys route to the manifest. Unregistered keys are logged, never dropped.

Remediation

LLM Fixer Agents

Per-error fixer reads contract, tests, and source. Produces a reproducer test that proves the bug, then fixes the source. Validates in a temp directory before applying.

Contracts

Contract Tightening

When a fixer proposes a contract change, Sentinel pushes it to Pact via CLI. The contract gets tighter with every production error.

Severity

Ledger Integration

Loads field-level severity mappings at startup. Errors on gdpr_erasable fields auto-escalate to HIGH. Audit field deletions go to COMPLIANCE.

Trust

Arbiter Events

Reports trust events after every fix outcome. Successful fixes boost trust. Failed fixes and production errors reduce it.

Safety

Git-Aware Fixes

Pre-fix snapshot commit before touching files. Post-fix commit on success. Automatic revert on failure. Silent no-op outside git repos.

Quick Start

Running in four commands

CLI

# Initialize Sentinel
$ sentinel init

# Register a Pact project
$ sentinel register ~/Code/my-project
  Registered: auth_module
  Registered: payment_processor
  Registered: user_service

# Start watching
$ sentinel watch

# Or trigger a fix manually
$ sentinel fix "PACT:auth:validate" \
  "Token signature invalid"

sentinel.yaml

version: "1.0"

sources:
  - type: file
    path: "/var/log/app/*.log"

auto_remediate: true

llm:
  model: claude-sonnet-4-20250514
  budget_per_fix: 2.00

pact:
  project_dir: ~/Code/my-project

arbiter:
  api_endpoint: http://localhost:7700

CLI Commands

Full command reference

Command	Description
sentinel init	Initialize `.sentinel/` directory and `sentinel.yaml`
sentinel watch	Start watching configured log sources (long-running)
sentinel register <dir>	Register all components from a Pact project directory
sentinel manifest show	Show all registered components
sentinel manifest add <id>	Manually add a component to the manifest
sentinel triage <error>	Triage an error to find the responsible component
sentinel fix <key> <error>	Manually trigger a fix for a PACT key + error text
sentinel report	Show recent incidents and fix history
sentinel status	Show configuration and integration connectivity
sentinel serve	Start the HTTP API server (default port 8484)

HTTP API

Programmatic access

Method	Endpoint	Description
GET	/status	Health and integration connectivity
GET	/manifest	All registered components
GET	/fixes	Recent fix history
GET	/fixes/:id	Single fix detail
POST	/fix	Manually trigger a fix (`pact_key` + `error`)
POST	/register	Register a component via JSON body
GET	/metrics	Operational metrics (incidents, fixes, spend)

Attribution

The PACT key standard

Format

PACT:<component_id>:<method_name>

# Examples
PACT:auth_module:validate_token
PACT:payment_processor:charge_card
PACT:user_service:create_user

# Rules
component_id: alphanumeric + underscore
method_name:  alphanumeric + underscore
prefix:       "PACT:" (uppercase, literal)
regex:        PACT:[a-zA-Z0-9_]+:[a-zA-Z0-9_]+

How It Works

# Pact embeds keys during code generation
logger.error(
  "[PACT:auth:validate] Token invalid"
)

# Sentinel extracts at error time
$ sentinel triage "[PACT:auth:validate] Token invalid"
component_id: auth
confidence:   1.0
reasoning:    PACT key found, matched to
              registered component

Integration

Pact → Sentinel → Arbiter

Data Flow

  Pact                    Sentinel                    Arbiter
  ┌──────────┐            ┌──────────────────┐          ┌──────────┐
  │ Generate │            │ Detect           │          │  Trust   │
  │ code w/  │───embed───>│   Log tailing    │          │  Ledger  │
  │ PACT keys│            │   CloudWatch     │          │          │
  └──────────┘            │   Webhooks       │          └──────────┘
                          │                  │               ^
  ┌──────────┐            │ Attribute        │               │
  │ Contracts│<──push────│   PACT key parse │      trust events
  │ (tighten)│            │   Manifest lookup│               │
  └──────────┘            │   LLM triage     │               │
                          │                  │          ┌──────────┐
  ┌──────────┐            │ Remediate        │          │Stigmergy │
  │ Tests +  │<──read────│   LLM fixer      │──signal─>│ (signals)│
  │ Source   │            │   Git snapshot   │          └──────────┘
  └──────────┘            │   Test + verify  │
                          └──────────────────┘