Patrol

Patrol runs a coding agent on a schedule. Each run follows tools/patrol/playbook.md:

1. It takes a lock, so that only one run works on the repository.
2. It scans one area for defects, each with evidence.
3. A council of models votes on each defect. Patrol files each confirmed defect as an issue with a severity.
4. The lead model writes a fix plan for the most severe issues. Each seat must score the plan at the threshold or more.
5. In full-stop mode, the lead fixes one issue with the full-stop skill and stops at a PR for the owner. In full-send mode, the full-send skill also merges.

A status card shows each step. The run edits it on a pinned log issue, and the T3 thread shows it too.

The playbook runs the skills council, sol-loop, full-stop, verify-pr and full-send without a change to them. A CI job, patrol-verify, tests each PR with an agent from another model family.

Adopt

1. Find an answer for each of these items in the repository. Do not stop to ask. The config starts in demo, so the user can change each answer in the PR before a run makes a fix:
   • The defect groups, each with impact points from 0 to 5 and two examples. Money, security and data loss usually get the most points.
   • The owner gates: the paths where a person must test before a merge, and the reason.
   • The commands that install, check and prove the code, for example make install, make check and make ci.
   • The CI checks that a merge needs, and the merge method.
   • The seat names of the lead and the council.
2. Copy scripts/patrol.mjs, playbook.md and prompts/ to tools/patrol/. Write tools/patrol/patrol.json from templates/patrol.json with the answers. Keep the mode demo.
3. To test each PR in CI, also copy the verify job of the forge. See Verify job.
4. Open one PR with these files. List each answer of step 1 in the PR, and say if you found it in the repository or took it from the template. Do not merge the PR unless the user asks.
5. Give the user the host steps for after the merge. Do not run them unless the user asks:
   1. Install the Sentinel skills of the core and ops profiles on the host. The playbook runs skills from both.
   2. Write ~/.config/sentinel/seats.json. It maps each seat name of patrol.json, the lead and each council seat, to a model, as in the example below. Write a family only for a model that you checked. The tester is the first seat with a family other than the lead.
   3. Run node tools/patrol/patrol.mjs init once. It makes the labels and the pinned log issue.
   4. Start one run by hand: open a new thread with the model of the lead in the repository, and give it the prompt Follow tools/patrol/playbook.md.
   5. Make a scheduled task with the same model and prompt, with a new worktree for each run.

{
  "models": {
    "opus": { "provider": "claude", "model": "claude-opus-5-5", "family": "claude", "effort": "high" },
    "fable": { "provider": "claude", "model": "claude-fable-5-1", "family": "claude", "effort": "high" },
    "astra": { "provider": "codex", "model": "gpt-6-astra", "family": "gpt", "effort": "high" },
    "muse": { "provider": "muse", "model": "muse-wonder-full-1.0", "family": "muse", "effort": "high" }
  }
}

Configuration

tools/patrol/patrol.json has no secrets. Change it in a PR to the default branch. A run uses the config of the default branch when it starts. A lower mode on the default branch also stops a run at its next gate.

A task prompt can change a limit for one run, for example Follow tools/patrol/playbook.md. Override: plans_per_run=3. It cannot raise the mode.

Labels

Add patrol:ready to an issue to send it back to the queue. The next run removes patrol:needs-owner and patrol:stuck and resets the count of tries. Close a patrol PR to stop its issue. Set a band label to change the severity.

Safety

• The council and patrol.mjs gate are quality checks. The security gates are the token scope, branch protection and the CI checks that a merge needs. Use full-send only behind branch protection.
• The run uses the forge login of the host. A scoped token has the rights of the current mode and no more, with no admin right.
• The engine reads a state or run record only from a comment of the patrol login. On a public repository, other people can comment, and the engine ignores their comments.
• The playbook treats issue, PR and seat text as data. gate refuses a diff that changes CI files, CODEOWNERS, agent instruction files or tools/patrol/.
• The lock works on one host, so each repository has one host.

Verify job

The verify job has two CI jobs:

1. agent gets the checkout of the PR and the key of the model provider, but no token that can write to the repository. patrol.mjs agent removes the forge tokens from its environment and stops it at the deadline.
2. publish gets the forge token. It runs patrol.mjs from the base branch and posts the report as a PR comment.

Copy the file of the forge:

• GitHub: templates/github/patrol-verify.yml to .github/workflows/. Add the secret OPENAI_API_KEY.
• GitLab: templates/gitlab/patrol-verify.yml to .gitlab/, and add it to include in .gitlab-ci.yml. Add the masked variable AZURE_OPENAI_API_KEY and a File variable CODEX_CONFIG with the Codex settings. Make a project access token with the Reporter role and the scope api. Put it in the masked variable PATROL_GITLAB_TOKEN with the environment scope patrol-verify. Do not protect it, because a merge request pipeline from an unprotected branch gets no protected variable.
• Azure Pipelines: templates/azure/patrol-verify.yml to .azure-pipelines/. Add it as an optional build validation policy on the default branch. Add a variable group patrol with AZURE_OPENAI_API_KEY, a secure file codex-config.toml, and a variable group patrol-write with the PAT PATROL_AZURE_PAT that can comment on PRs.

The agent can read the provider key, and code that the PR runs can read it too. Use a key with a spend limit, for patrol only. The templates skip PRs from forks.

Your own runners

The GitHub and Azure templates use hosted runners, and each hosted job gets a new machine. GitLab sends the jobs to each runner of the project that takes untagged jobs. The publish job holds the forge token. So the agent job must not change the files of the publish job or act as its runner.

• Do not give jobs the Docker socket, privileged mode, the cloud metadata service or a shared host folder.
• GitLab: use the Docker or Kubernetes executor, not the shell executor. Each job then gets a new container, and the publish job makes a new clone. If the project also has a runner that is not safe, add tags to the jobs.
• Azure: a self-hosted agent runs all its jobs as one user, and a job can read the credentials of the agent. So make a pool for patrol only, and set pool: <that pool> only on the agent job. Keep the publish job on vmImage: ubuntu-latest. Then PATROL_AZURE_PAT never gets to your machine. Start a new agent container with run.sh --once for each job. The templates need Azure DevOps Services, because the Azure DevOps CLI does not support Azure DevOps Server.
• GitHub: register each self-hosted runner with config.sh --ephemeral, and start it on a new VM or container.
• On a local runner, the agent can reach your network, and PR text can try to give it orders. Use a separate machine or VM, on a network that cannot reach your other services.

Commands

node tools/patrol/patrol.mjs init
node tools/patrol/patrol.mjs lock
node tools/patrol/patrol.mjs start --run ID --model MODEL [--override "plans_per_run=3"]
node tools/patrol/patrol.mjs queue|pick|card --run ID
node tools/patrol/patrol.mjs publish --run ID --mode issues --in DIR
node tools/patrol/patrol.mjs claim --run ID --id ISSUE
node tools/patrol/patrol.mjs mark --run ID --id ISSUE [--phase P] [--add L] [--remove L] [--note-file F] [--state JSON]
node tools/patrol/patrol.mjs gate --run ID --stage push|handoff|merge
node tools/patrol/patrol.mjs record --run ID [--step S --data JSON] [--pr N] [--calls 1] [--outcome O --reason R]
node tools/patrol/patrol.mjs agent --prompt FILE --out DIR [--minutes 45]
node tools/patrol/patrol.mjs publish --forge github|gitlab|azure --mode comment --in DIR --pr N

Exit code 3 means that the run ended, for example as Busy. Exit code 1 means that gate found a problem. Exit code 2 means an error.

Report

End with these facts:

• The files that you added, the PR, and the answers of step 1.
• The host steps of step 5, with the path of the seats file, the init command, how to start one run by hand, and the prompt of the scheduled task.
• The secrets that the user must set.
• Each step that you did not run.