Overseers — the work, the settings and the internals (part 3)
Part 3 of the Overseers page: the kinds of work an Overseer can hand out and the jobs it may start on its own, what it notices without being told, how agents hand notes to each other, the spend circuit breaker and the settings that govern it all — plus the internals for anyone working on it.
On this page
What it is
This is part 3 of the Overseers page — what an Overseer actually does with its time, and how the system is put together.
Where to find it
The Overseers hub and its settings; the last section is agent- and developer-facing.
How it behaves
The kinds of work an Overseer can hand out
There's a fixed list of roles, each with its own trusted starting job description:
| Doing the work | Checking the work | Working out what to do |
|---|---|---|
| Builder — builds new features | Reviewer — reviews one change for bugs and quality | Planner — turns a vague goal into a sequenced plan |
| Fixer — root-causes and fixes bugs | Tester — writes tests that would catch a regression | Researcher — investigates and answers, changes nothing |
| Tool Builder — builds scripts and harnesses other agents use | Auditor — sweeps a whole area against a standard and reports | First-Principles Evaluator — re-derives what it should be, ignoring how it is done today |
| Documenter — writes the docs a change leaves behind | Red Teamer — attacks a claim or design to find where it breaks | Pattern Finder — finds every place a recurring shape appears |
| Optimizer — makes working code faster or cheaper | Triager — gives every item in a pile a disposition | Janitor — clears out dead code and tech debt |
An Overseer can propose one of those workers through the ordinary agent-session route by
including agentType. An Overseer's own proposal is applied on the spot — it never waits for
a click: the Overseer is only running because you stood it up and gave it a standing job, so
that deployment IS the approval, and a card it could never clear itself would only stall your
own decision. An ordinary caller's proposal still lands in your inbox for you to approve. Either
way Omniscio rejects roles outside that Overseer's allow-list before the spawn happens, the
spawn stays attributed to the Overseer, and it is still bound by the per-token rate limit and
the spawn's own dollar/turn caps. An Overseer you have switched off in Settings, or whose
session you paused, gets no exemption — its proposal queues like anyone else's.
The list is a closed set and is append-only — a stored allow-list holds these ids verbatim, so renaming or removing one would silently un-tick it everywhere it was chosen. Adding a role is free: an Overseer with no allow-list set is unrestricted, so it can use a new role immediately.
Example proposal body for POST /agent/sessions:
{ "projectId": "<project>", "initialPrompt": "Fix the failing checkout test", "agentType": "fixer" }
agentType is optional for ordinary callers. When the caller is an Overseer, it selects and
enforces the role and prepends the trusted stock instructions; the Overseer's prompt supplies
the specific assignment, not a replacement role definition.
A fixer runs on DeepSeek, and sending "provider": "claude" does not change that. Fix work is
pinned to the app's fix-work engine: DeepSeek, whenever the DeepSeek lane
is open to session spawning on that computer. A provider naming anything else beside
"agentType": "fixer" is replaced, the spawn is logged with both engines, and the response carries
fixWork: {"engine": "deepseek", "overriddenFrom": "claude"} so you can see what happened rather
than having to guess. Every OTHER worker type keeps the provider you sent — the rule is about fix
work, not about taking the engine choice away from an Overseer. Turning DeepSeek session spawning
off (Settings → the DeepSeek provider) is the off switch and the one way to send a fixer elsewhere,
and on a computer with Google connected the rule does not apply at all — DeepSeek cannot run a
session there, so the provider you sent stands. If DeepSeek cannot pay, the worker PARKS on that
account rather than quietly moving to Claude; restart it on Claude yourself if you want it running now.
What a spawned worker is actually told
The prompt a worker starts with is assembled by Omniscio in three parts, always in this order:
- The shared preamble — the same for every role. It explains where the worker is, that an agent (not a person) wrote its job, that a human approved the spend, the standard it is held to (fix causes not symptoms · label every claim confirmed or hypothesis · believe the report · do the smallest thing that works · never guess in silence), what it may not do (start other agents, push or merge, restart the app, touch another session's work), and how to sign off — its final message is the deliverable, read later by someone with none of its context.
- The role — the trusted per-type instructions above.
- The job — the only part the Overseer wrote, and deliberately last, so the trusted text is already in place before anything agent-authored is read.
Two things follow from that ordering and are worth knowing:
- A worker never produces a Plain Speak card or spoken narration. Its messages are read back by an Overseer, not watched by a person, so the spawn sets the session's overlay-suppression flag and the preamble says so — the flag removes the injected fragments, and the instruction covers any sub-agent the worker runs itself, which the flag cannot reach.
- A job that tries to restate the rules is read as the instruction it is, not as the standard the worker is held to.
From the command line
GET /overseer/agent-types reads the full list of roles and their starting instructions.
POST /overseer/agent-types sets which roles one Overseer may use:
{ "slotId": "custom:<id>", "allow": ["fixer", "tester"] }
Leave the setting alone and every role is allowed; send an empty list and none are. Like assigning sessions above, this applies immediately from inside Omniscio and is queued for your approval from anywhere else.
Doing it from the command line
POST /overseer/sessions moves one session in one call:
{ "sessionId": "<session>", "slotId": "custom:<id>" } // assign (or move it here)
{ "sessionId": "<session>", "slotId": null } // stop anyone watching it
The underlying setting (overseerSessionAssignments) is one whole map, so without this route
you would have to read it, edit it and write it back — and skipping the read would wipe every
other session's assignment. This route does that for you.
It is a convenience, not a second way in: it hands the result to the same approval step a raw settings change goes through, so a session running inside Omniscio applies immediately and any other caller is queued for you to approve. Nobody gains access they did not already have.
Two things it refuses rather than accepting quietly: a session that does not exist, and an Overseer that is not running (deleted, switched off, or a project with no Overseer). Both would be stored and then ignored forever, so the call would look like it worked and never do anything — the worst possible outcome for a script. Removing an assignment skips both checks, so a stale entry can always be cleaned up.
Work an Overseer starts on its own
An Overseer can hold standing rules: jobs it starts by itself, without a person asking each time. Each rule names three things — an agent type (from the roles list above), the job that worker is given, and what makes the rule fire:
- Every N minutes — a cadence, from 1 minute to 24 hours.
- When something happens — either a session finishing, or a worker failing.
A rule does nothing until you approve THAT rule. This is the whole safety story, so it is worth being blunt: writing a rule down is not approval, switching on the Overseer is not approval, and switching on the feature is not approval. A rule with no approval on it is stored, listed on the Settings tab, and completely inert — it never spawns, on a timer or on an event. Approving the rule is a separate act, and it is the one that authorises the spend.
Every rule also carries a required maximum runs per hour — there is no version of a rule without a ceiling, because a cadence with no cap is exactly the failure this feature exists to avoid. Two things follow from the ceiling and from how the schedule is kept:
- Repeated events fold into one run. A worker that fails five times between two sweeps leaves one trigger standing, not five, so a flapping worker becomes one run rather than a spend loop.
- A window the app slept through does not pile up. The next run is anchored to now, not to the cadence that came and went while Omniscio was closed, so an app down for a day wakes to one run per rule — never one for every interval it missed.
A run also crosses the same rails work started by hand does: it is held back when the spend breaker is tripped, and it is booked against that Overseer's interrupt budget. The rule's agent type must still be in the Overseer's allowed types at the moment it runs, so narrowing that list stops a rule written before the change rather than letting it keep spawning the type you removed.
Where you edit them. The Overseer's own Settings tab has the list, under Jobs it runs on
its own: each rule's type, job, trigger, hourly ceiling, and the Approved to run switch that
is the approval to spend. Headlessly, POST /overseer/auto-actions creates or changes one rule and
GET /overseer/auto-actions reads them back. That read reports each rule's approved state
explicitly, because that flag — not the rule's presence — is the answer to "why did nothing
happen?".
{
"slotId": "custom:<id>",
"action": {
"agentType": "fixer",
"job": "Re-run yesterday's failing checkout test and fix the cause.",
"maxPerHour": 2,
"trigger": { "kind": "every", "minutes": 60 } // or { "kind": "on", "event": "workerFailed" }
},
"approve": true // the approval to spend; omit to store it inert
}
What it notices on its own
Every few minutes each Overseer reviews your recent activity looking for patterns — repeated failures, wasted effort, things that look stuck. Anything it concludes now arrives in your inbox. (Until 2026-08-29 those findings only went to an internal log, so nobody ever saw them.)
The same finding recurring doesn't post a new card each time — it groups onto the existing one. And these go through the normal screening like any other alert, so if an Overseer's own observations get noisy, it can batch and quieten them itself.
Each Overseer can also be capped on how many of these it may push to your inbox in an hour —
No limit, Max 5/hr, Max 2/hr, or Only when blocked. A finding held back by the cap is never
lost: it is still recorded (you can see it as a "deferred" entry below), it just waits rather
than interrupting you immediately. Whatever the cap, something the Overseer genuinely can't get
past on its own always reaches you regardless. Set it on the Overseer's Settings tab (May
interrupt you) or in the wizard's Rhythm step; the stored key is interruptBudgetPerHour.
When a mission is stuck: the stall audit
A crew declares the number its mission is judged on, and the app reads it itself. When the same promise the crew declared has missed its own window twice, the app raises one card about it and asks the Review Service for one fresh independent audit of the mission, on another AI. That audit is the crew's own top-down look at what it is wasting, not a scheduled lens round.
It has a switch of its own — "Stall audits (run only when a mission is stuck)"
(crewLadderAuditEnabled, on by default). It exists so that a mission which is genuinely stuck is
still looked at when routine reviews are off. With Independent reviewer sessions on, the stall's
audit runs like any other round; with them off it is the only review that still starts. The switch
can start nothing by itself: it admits the stall's own request and nothing else — never a scheduled
round, never the daily audit; those answer to that other switch alone. Turn it off and a stuck
mission gets no audit at all while routine reviews are off.
Nothing else about a stall starts work: there is no incident, no re-plan deadline and no automatic replacement of the crew's lead. One audit per stall, never one per check, and every guard a review already passes still applies — one reviewer per crew at a time, the machine-wide limit, and a busy computer.
Notes one agent hands another
There is a second, quieter channel between sessions: a note. Any agent session can hand another
a short note, and it costs nothing — no turn is started, no model call is made, and the recipient
is never woken. POST /session/:id/aside sends one, and GET /session/:id/asides shows what is
still waiting to be read.
The honest trade is the whole design, so here it is plainly. Because a note never interrupts, it is read at the recipient's next turn — folded into the next prompt that session receives for some other reason, and never the reason that prompt exists. A session that never runs again never reads it. That is the price of a note costing nothing, and it is why a note is a courtesy and never a way to hand out work: anything needing an answer, a decision, or an action is a real turn.
It is also one-way. The sender gets nothing back — no reply, no acknowledgement, no inbox of its own. Every note is labelled with who sent it and framed to the recipient as untrusted information from another agent, never as your words: a note that tries to give an order is read as a claim it has merely read, not a command it should obey.
Every alert is copied to the Overseer that owns the session
Turn that channel around and it is also how an Overseer hears about your inbox. Every alert you get is mirrored to the Overseer assigned to the session that alert is about, as one of these notes. Two things make that safe to leave running:
- Only the ASSIGNED Overseer gets it. A session nobody assigned has no note to send, and there is no fallback to the project's or the global Overseer — putting an alert about a session in front of an agent that does not watch it would be worse than not passing it on at all.
- The note says what it is. It is labelled an automated copy of an inbox alert, and it states in words that it is not a person writing and not a request or an instruction — so it can never read as something you asked for.
The mirror adds nothing to the alert and can never delay it: it is a courtesy copy left beside the card, and every failure in it costs the copy, never the card. It is also capped per session, so one noisy session cannot flood its Overseer's notes.
Seeing what they did, and where things went
Each Overseer's Board tab in the hub is the record of what has actually happened, newest first: everything it did — each row says in plain words where the alert ended up (passed it through to you, you never saw this one, folded it into a similar alert) with its stated reason, and each wake-up's round report — alongside the questions agents asked it and what it answered, the boards of its swarms, the shared agent board, and the direct messages among its sessions. Filter by channel to read one stream at a time.
Since Stage 2 (2026-09-08) those are all ONE store. Every peer message, every question an agent asked its Overseer and every answer it gave is ALSO written as a post on a channel — overseer:<slot>, swarm:<id>, dm:<a>|<b>, group:<uuid> for a small group chat among picked agents, crew:<id> for one crew's private board, repo:<projectId> for every agent working one repository, and the bare name overseers for the one room every crew's lead shares. The Board tab looks exactly the same; it just reads one table instead of merging four.
Two things that follow from that, and are worth knowing before you change anything here. Recording never delays or blocks a message — the board is the record, the delivery guarantee belongs to agent-to-agent messaging, and a board write that fails costs a row and never a message. An empty Board is not the same as a broken one — because one mirror now feeds every message kind, the read reports when that mirror has failed rather than rendering an empty feed that looks like a quiet day.
The action name alone ("release", "silence") says what happened to the alert but not whether it ever reached you, which is the thing you actually want to know — so the outcome is spelled out.
An action recorded before Overseers became plural belongs to no Overseer's Board rather than being attributed to a guess.
Spend — what each one has cost today shows in the hub; the shared daily ceiling in the fleet settings shows the day's total against the cap.
Under the hood
Every action — hold, release, merge, silence, escalate, kill, spawn, guidance given, settings
change, circuit-breaker trip, scheduled restart, an inbox interrupt (or one held back by the
hourly cap) — is appended to overseer_action_ledger
with a timestamp, the target (alert dedupKey / session id / setting key), a stated reason, and
the slot id of the Overseer that acted. Ledger writes are fail-open — a DB error never
crashes the Overseer.
One thing worth knowing: judging is done by the global Overseer, even for a card a per-project Overseer caused to be held. The trail says so honestly rather than crediting the project's Overseer with a decision it did not make.
The spend circuit breaker
The Overseer tracks its own trailing-hour spend against your rolling baseline. If spend exceeds your configured multiplier (default 4×), the breaker trips: the Overseer pauses itself, stops holding new alerts, and raises a never-held inbox alert so you can investigate. While tripped, the inbox behaves exactly as it would with the Overseer disabled.
The breaker fails closed on unmeasurable spend — a DB outage is treated as tripped rather than zero, because that is exactly when a stuck loop might be accumulating real charges.
Giving each Overseer its own job
Where: the Overseers hub. New creates one through the wizard (purpose, scope, rhythm, review — Start watching is the approval to spend, Save without starting keeps it unstarted); the Settings tab of any Overseer edits its name, purpose and job, and its run switch starts or stops it. A custom Overseer can be deleted from its Settings tab (it asks first) or simply switched off, which keeps whatever you wrote for it. Every one of those edits goes through one writer in the main process — the app itself never writes an Overseer's settings directly.
An Overseer that is not going to start on its own says so, where you are looking. Its Chat tab reads "Not switched on — it will not start until you turn it on", with a Turn it on button that is the same approval to spend as the Settings tab's run switch. An Overseer that HAS been started and is simply between wake-ups still says "It starts on its next wake-up" — the two are different situations and must never read the same way, because only one of them is going to start on its own.
That first sentence covers two situations, and the app counts both as "not switched on". One is an Overseer you never approved. The other is an Overseer whose session you archived: the archive is the off switch, so the app holds the slot off and does not revive it — and that is what it says on screen, with the row reading Off and the same Turn it on button to bring it back. Before, that slot read "Starting" and promised a wake-up the app was deliberately holding back.
Only an Overseer you switched on asks for approval in the inbox. A per-project or custom Overseer you turned on but never approved raises one "An Overseer is waiting for your approval" card. The main Overseer never does: it appears whenever the Overseer feature is on, and its run switch being off is the normal "not running" state, not a pending question — so the card used to come back after every restart for something nobody had asked for.
Every Overseer has a name and a job description, both optional:
- Leave the job blank and it runs a built-in stock description — screen the inbox, answer agents, watch for patterns. Turning an Overseer on never requires writing a prompt first.
- Write your own and it replaces the stock text rather than being tacked onto it, so an instruction like "only watch billing, ignore everything else" is not contradicted by stock text telling it to do everything.
Don't want to come up with a name? Describe what it's for in the Purpose field instead — "Watch the billing pipeline and flag anomalies" — and Omniscio turns that into a short title for you automatically. Edit the Purpose later and the title updates to match, right up until you type a Name of your own; from then on your name always wins, and further Purpose edits never touch it. Already renamed it and want the generated title back? A Use the auto title button next to the Name field clears it for you.
Names show up in the session list, so you can tell them apart: Overseer, Overseer — Billing, or whatever you called your custom one. Without a name they would all read "Session 1", "Session 2".
Whatever you write, the safety half is always present and cannot be overridden by your instructions or by anything an agent says to it: the prompt-injection lock, the tool list, and the memory rules.
A custom Overseer can be paused without deleting it — it stops running and keeps the job description you wrote for it.
Settings
All of it lives in the Overseers hub, in two places:
- Each Overseer's Settings tab — what it is called, what it is told to do, the sessions it watches, its own cadence and interrupt cap, the agent types it may run, its AI engine (which provider and model it runs on; blank = the crew-lead default), its run switch, its Reporting switch (below), and Wakes up: the check-ins actually scheduled for it, whether each required one is covered, and the control that adds another.
- Fleet settings (the gear at the top of the list) — the settings that apply to every Overseer at once: whether they screen your inbox, how long they may hold an alert, how often they wake, how often they start fresh, the runaway-spending cut-off, the shared daily ceiling, the swarm defaults, and which projects get their own Overseer.
The hold window only appears while inbox screening is on, since it does nothing otherwise. The
master on/off (overseerEnabled) is the feature toggle and lives in Settings → Lab.
Changes take effect on the next keeper tick (within ~30 seconds) — nothing here needs a restart. The persisted keys behind those controls:
| Setting | Default | What it does |
|---|---|---|
overseerEnabled |
true |
Master on/off, on by default (the Lab toggle still switches it off). Also the unreleased-feature reveal key (overseer). |
overseerGatekeeperEnabled |
true |
Whether the Overseer holds new inbox items during the window. Can be off independently. |
overseerHoldWindowMinutes |
10 |
How many minutes a new alert is held before the Overseer must decide. Range 1–120 min. |
overseerRestartHours |
24 |
How many hours between automatic session restarts (to prevent context growth). Range 1–168 h. |
overseerSpendBreakerMultiplier |
4 |
Multiplier on rolling baseline before the spend breaker trips. Range 2–50×. |
overseerAutoPerProject |
false |
Give every project its own Overseer. Off by default — each one is a real running session. |
overseerProjectOverrides |
{} |
Per-project enable/disable map. Wins over overseerAutoPerProject in both directions. |
overseerSlots |
{} |
Per-Overseer name + instructions, keyed by slot. A custom: entry here is a custom Overseer. |
overseerSessionAssignments |
{} |
Which Overseer watches which session, keyed by session id. One owner per session; a value naming an Overseer that no longer exists is ignored and routing falls back. |
Reporting — the switch that decides who an Overseer answers to — only appears while a master
overseer is actually on the job. Off is the ordinary state: this Overseer's sessions go to your
master overseer like everything else. On keeps this one answering to you, and only this one;
every other Overseer is untouched. It is stored per slot as reportsToPerson inside overseerSlots,
and leaving it unset means the ordinary state. Nothing reports to itself, so the master's own row
never shows the switch, and nothing here changes while the master runs in inbox-only mode.
Fail-open design
Four independent fail-open paths ensure a broken Overseer can never silence your inbox:
- Dead / paused / breaker-tripped — the hold gate declines to hold; one deduped
overseer-offlinenotice fires. - Alive but silent — the release sweep clears the hold at the window expiry.
- Clock jumped backwards — the clock-jump floor force-releases any hold too far in the future.
- Alert storm — past the concurrently-held ceiling, nothing is held at all.
Related
- Overseers — part 1, what an Overseer is and the hub you reach it from.
- Overseers part 2 — running one, and steering what it watches.
- ai-spend-alerts.md — the wider spend-warning surface the circuit breaker sits beside.
Last verified 2026-10-05