Overseers — running one (part 2)
Part 2 of the Overseers page: keeping one working — how it wakes up, stays alive across restarts, and watches for stalls; how to copy one or run several; how to point one at specific sessions and where the answers it collects end up.
On this page
What it is
This is part 2 of the Overseers page — the operating half: keeping an Overseer running and steering what it watches.
Where to find it
The Overseers hub again — every control described here is on one of its tabs or in the Overseer's own settings.
How it behaves
How it wakes up (the check-ins)
Each Overseer is woken automatically on its own schedule to do the job you gave it — nothing to set up, no cron job, scheduled task or script.
- Two check-ins are seeded for every Overseer, and neither can be removed: a Heartbeat every 15 minutes (the regular look around) and a Review every 6 hours (a slower, wider pass over the standing picture).
- They are ordinary durable schedules on the Overseer's own session, so a check-in survives an app restart and the session being replaced; a wake-up still arrives as a real turn, so the Overseer remembers what it last looked at and did.
- The keeper restores a check-in that goes missing or runs out. Every schedule fires a finite number of times, so one that reaches the end of its budget is re-created on the next keeper tick — the failure this prevents is an Overseer that looks alive but is never woken again.
- Every wake-up is also SUBMITTED, not just delivered. The wake says only that the round is
due: the Overseer pulls its brief (
GET /overseer/heartbeat— the fleet digest, the board traffic, and the sessions it owns) and then sends the round withPOST /overseer/round. That submission is what reaches the audit list and the fleet board — one row perDID:orFINDING:line it carries; what reaches your inbox is the single tag on the Overseer's own final, and a round it does not send is a round nobody sees. - Change the cadence fleet-wide in the hub's Fleet settings, or per Overseer on its Settings tab (the wizard's Rhythm step names the fleet's live default).
- The Settings tab's Wakes up section shows what is actually scheduled — each check-in, the cadence it really fires on, how much of its fire budget is left, and a warning when a required one is missing, spent, or set to a cadence no schedule can express.
- Each check-in also reports what its last fire actually DID — the result of its own round, and
on the same
GET /overseer/heartbeatread: the last fire's outcome (delivered, or stood down with its reason — a check-in stands down when the session moved inside the last 30 minutes, or when a turn is already running), when a wake last arrived, and how many times it has fired. Those are two different numbers: a stood-down beat advances the fire count exactly like a delivered one, so the count alone is never proof a round happened. An Overseer reading its own wakes throughGET /wake-schedulesgets the same two facts; every individual fire, with its own output, is onGET /cron/jobs/<id>/runs, which is an owner/CLI read (a session's own token is refused there). - Add a check-in of your own from that same section: a Heartbeat or a Review at any cadence a schedule can express exactly (minutes dividing an hour, or whole hours). Adding one never replaces or disables the required pair.
- An Overseer can re-pace its own heartbeat, without asking you, by calling
POST /overseer/heartbeat {"everyMinutes": N}. Its briefing tells it so: an Overseer that notices it is checking too often, or not often enough, simply fixes it. - A check-in can carry data, so the Overseer wakes up already holding it. Each wake schedule
can carry up to three labelled add-ons: a standing note, or the latest output of a script
schedule that same Overseer created (and you approved). An add-on can ride every wake, or only
every N minutes. The Overseer sets them on its own schedules with
PATCH /wake-schedules/<id> {"injections": [{"label": "fleet", "kind": "script", "cronJobId": "<id>", "everyMinutes": 60}]}; an empty list clears them. The wake never runs a program itself, and what rode is shown in the Overseer's transcript, so you can always see what it was handed. - A cadence of
0means "never wake this one", and it is honoured where a check-in is created or restored. An explicit per-Overseer value wins in both directions, so "every Overseer except this one" works — a heartbeat already scheduled on a running session keeps firing until that session restarts or its own fire budget runs out. - A quiet wake-up leaves no trace. If it wakes, looks around, and finds nothing worth doing, nothing is recorded — so the audit list stays readable even at a fast cadence.
Each wake-up is a real paid turn. Every 15 minutes is 96 a day per Overseer, before the 6-hourly review adds four more.
Check-ins used to be a private timer. Until 2026-09-19 each Overseer was woken by a bespoke in-memory timer with its cadence in a settings number, and a round was read back out of the session's own transcript. Both are gone: the cadence lives on ordinary wake schedules, and the round is submitted by the Overseer itself.
Two things guard that spending:
The runaway-spending breaker is a runaway detector, not a spending cap — a permanently fast cadence simply becomes the normal it measures against. It watches for a sudden spike against what the Overseer normally costs, and pauses it until you restart.
The shared daily ceiling IS a hard cap, and it is off by default — there is no limit until you set one. Set a dollar figure and it covers the Overseer and every swarm it runs as one budget. When the day's total reaches it the Overseer stops waking and no new swarm workers start. It resets at local midnight and resumes on its own — unlike the breaker it never needs a restart, because being out of budget for today is not a fault.
The ceiling — and each Overseer's "spent today" figure in the hub — counts the sessions' own turns plus any charge billed to them; the runaway breaker still reads only the charge log, so it does not yet see session turns.
Swarm spending counts against the ceiling but is deliberately kept OUT of the breaker: a swarm running several workers costs far more than an Overseer alone, so counting it would trip the spike detector every ordinary hour and leave the Overseer paused for doing its job.
Only the global Overseer's wake-up carries the fleet digest and weekly summary as context, and only it can put a card in your inbox from a wake-up — it is the only one reading the fleet-wide digest that supports that kind of conclusion. Every other Overseer records what it did in the audit list and gets on with its own job; otherwise a fleet each waking four times an hour would turn your inbox into an activity log, the exact noise the Overseer exists to remove.
History worth knowing. Until the keeper existed, an Overseer was never woken — the service meant to do it was never switched on at startup — and the spend breaker could not trip, because nothing called it. Both are now live.
How it stays alive
A background service — the keeper — checks every 30 seconds whether a live Overseer session exists for each enabled slot (global + any per-project ones); if none exists it spawns a fresh one. It uses an exponential backoff when spawns fail and raises one inbox alert after five consecutive failures.
The 30-second check is the keeper's steady state, not a delay you wait through: switching an Overseer on runs the keeper straight away, so it starts within a couple of seconds rather than at whatever tick came next.
The keeper also holds the two spend gates — a tripped runaway-spending breaker pauses it until an app restart, a reached shared daily ceiling skips the tick (so it returns when the day rolls over) — and every healthy tick re-seeds a required check-in that has gone missing or run out of fires.
A brand-new Overseer is seeded with its check-ins as the new session is created, so there is no first interval of silence.
Archiving an Overseer's session switches that Overseer off. Archiving it by hand — close button, middle-click, shortcut, swipe or bulk archive — first asks "Archive this overseer?", so a stray click never switches one off. Once archived, the keeper stops replacing it, so the agent stops and stops costing anything until you start it again. This is the second way to turn one off, alongside the run switch on its Settings tab; the two agree.
Switching an Overseer off ends its running session, under either overseer system. Turning the
run switch off ends that Overseer's live session on the keeper's next pass, also while the system
is set to V3 (missions). Overseers still switched on keep their sessions, and turning off the
master Overseer switch (overseerEnabled) on its own stops nothing.
To bring it back, either reopen that session (which clears the archive) or switch the slot on again; a switch-on counts as the more recent instruction, so it wins. Nothing is lost either way — the notes file and the transcript stay exactly where they are.
The stuck-session sweeper (which recovers crashed sessions for normal agents) explicitly excludes Overseer sessions; only the keeper ever revives them. That keeps the sweeper's hard cap (12 consecutive failures → permanent terminal state) off a session designed to be permanent.
Memory and scheduled restarts
The Overseer's durable memory lives in NOTES.md in the app's own data directory
(<userData>/overseer/NOTES.md), for every kind of Overseer — global, per-project or custom.
Running one inside your repository therefore never touches it: no file is created, changed or
deleted, and its git status is exactly as you left it. You can read the notes or add to them
directly; the Overseer writes to them as it discovers patterns worth keeping.
When the Overseer starts (whether for the first time or after a scheduled restart), its standing instructions reach it as a system-level briefing the session carries every turn, never as a file dropped into the working directory:
- A base persona with an instruction-lock section (prompt-injection guard).
- Your custom Overseer instructions (from settings).
- Your own words to this Overseer, verbatim. Every message you sent this post, newest last and dated, read back by the app at spawn — so a standing rule you typed survives a restart, a fresh start and a successor even when the outgoing agent's notes did not keep it. A bare answer ("yes", "A") is shown with the question it answered, or marked as a reply when that question was never recorded, so a successor never reads a contextless "A" as an order. Older messages that do not fit are counted out loud, and the section opens by saying these are history rather than a message from you now. Secrets are removed on the way in.
- Its own notes, read from the notes file above.
- For a per-project Overseer only: the project's own
CLAUDE.mdand.claude/rules/files, loaded automatically because the session runs in the project folder — the same project context any session in that project gets. A global or custom Overseer does not receive these.
The briefing arrives through the system prompt rather than a generated CLAUDE.md, which makes "an
Overseer writes nothing into your repo" structural rather than a promise: a generated file would
collide with one the project may already own and dirty every repository that has an Overseer.
Upgrading from an older build deletes that file once, so no Overseer carries its instructions twice.
Notes carry forward across restarts, so the Overseer never loses what it has written down; context resets (fresh session, no accumulated context) while notes persist. Your own words ride every restart beside them, so what you told a previous holder is never left to that holder's summary.
A duty that has to keep running goes in the notes, never in the conversation. Anything an
Overseer starts inside its own session — a watcher, a command, a loop — ends when that session
does, and a fresh start does not bring it back. Put each duty under ## Standing duties: that block
is kept whole when the notes are trimmed, and the fresh-start request names the heading. A crew
lead's hand-off note must answer What must keep running; the successor's briefing says nothing
its predecessor started followed it, and names the file with the whole note if it had to cut it.
Scheduled restarts happen automatically at the interval you set (overseerRestartHours,
default 24 h). The keeper terminates the current session and immediately spawns a fresh one that
re-reads NOTES.md. The old session is filed away in that same pass, right after the fresh one is
started, so it never waits in your Interrupted list for a later tick; the one exception is an
old session still holding a card you have not read, which stays until you deal with the card. The
same goes for a fresh start when the conversation fills up. A restart is deferred while a turn is actually running, and while the session
is starting, stalled or terminating — the keeper waits for the next tick. An Overseer that
ended its turn on a hibernate marker, or is resting under a prose-wait hold, still reads running
between wakes but has no turn in flight, so it is restarted on time. A restart also
waits while the Overseer is holding a question, plan or permission request for you, because ending
the session would take that question out of your inbox. That wait is capped at 8 hours past the
restart interval; after that the restart goes ahead and the fresh Overseer has to ask again. Every
restart is recorded in the action ledger (see below).
How it screens the inbox (the hold mechanism)
When any alert is created — whichever part of the app or which agent raised it — the Overseer can place a hold on it:
- The hold is a nullable
held_untiltimestamp on theinbox_alert_itemsrow. - All three user-facing alert reads (
listActiveAlerts,listDripSourcedInboxItems,listAlertsByDrip) exclude held rows by default. A held card is invisible to you, to the phone, and to the badge count — but it is NOT deleted or suppressed at the push layer. - A release sweep runs on each cycle and clears expired holds, emitting
ALERT_CHANGEDso the renderer picks up the newly-visible card. - The global Overseer judges held cards in one batch shortly before the oldest one would show: it checks every 90 seconds, and once the soonest-expiring held card is within half the hold window (5 minutes at most) plus 90 seconds of its end, it judges the whole held pile, up to 25 cards, in a single turn. Urgent cards are never held, so they never wait. Each judgment is a real turn on its own session: release, silence (archive), merge, or escalate, one line per card. The verdict is applied when that turn ends — not when the prompt is sent, which returns in milliseconds — and the wait is capped at half the hold window (5 minutes at most). A turn that ends with no answer, or runs past the cap, releases every card in the batch.
- A clock-jump floor force-releases any hold sitting too far in the future (a multiple of the hold window), so a bad clock cannot hold a card forever.
- Past a storm ceiling (many cards held at once), new cards are not held at all — fail-open.
- Some cards are never held (
overseer-never-held.ts): anything that can page the phone (owner-critical alerts), auth/spend/security/data-loss/real-time-comms prefixes (including all team-chat notices), results you are waiting on (including every finished Nighty Tidy audit's result card, since the audit's own session is filed away once it finishes), and any card with an empty or unknown dedupKey. An unclassifiable card is always immediately visible. - If the Overseer is dead or unreachable, the hold step is skipped and the card goes straight through. The Overseer being broken can never silence your inbox.
- Only the global Overseer can cause a hold, because it is the only one that comes back to judge held cards. A per-project Overseer never holds anything: a card it withheld would be read by nobody and simply released later, which is delay without screening.
- Both ways an alert can be created now screen, including the one almost every agent-raised card comes through, and the judging step waits for the Overseer's answer before releasing a held card.
Having more than one Overseer
There are three kinds, and you can run as many as you like at once.
| Kind | What it watches | Project context | How you get one |
|---|---|---|---|
| Global | everything | none — runs in the app's data directory | on whenever the Overseer is on |
| Per-project | one project | full — loads CLAUDE.md and rules, can open memory and contracts | turn on "an Overseer for every project", or switch on the one project you want |
| Custom | only the sessions you assign it | none — runs in the app's data directory | you create it and give it a name |
Choose the right type for the job. A per-project Overseer runs in the project's own folder, so it loads that project's
CLAUDE.mdand.claude/rules/and can open its.claude/memory/docs and contracts — the context any session in that project gets; a global or custom one runs in the app's data directory and gets none of it. A job needing a project's processes, conventions, contracts or dev pipeline must be per-project: custom instructions cannot replace them.
Any of the three can also be handed specific sessions to watch — see below.
"An Overseer for every project" (overseerAutoPerProject) gives each project its own,
without switching them on one at a time. It is off by default — each Overseer is a real
running session that costs money, so switching them all on is your call, never a default.
You can still turn an individual project off while that is on. An explicit per-project choice always wins, in both directions, so "every project except this noisy one" works.
Each Overseer is a fully independent session: its own spawn claim, its own failure counter and retry backoff, and its own memory. A slow spawn for one never delays another, and one going down does not affect the rest.
A project-scoped alert goes to that project's Overseer if it has one, otherwise to the global.
Copying an Overseer
A running session can ask for a copy of itself in one call, and what it gets depends on what the
copy is FOR. POST /session/:id/clone takes a kind:
kind |
What you get |
|---|---|
one-off |
An ordinary session, started on the source session's own engine with the briefed opening below. It runs its job and finishes — it is not an Overseer, nothing keeps it alive, and no slot is created for it. |
standing-peer |
A HAND-OFF. The successor takes the SAME slot and the original stops, so the post has one live holder rather than two. It starts from the slot's own notes and instructions, which is what carries the mission and the memory across. Use it to replace yourself; use one-off to get a second pair of hands. |
A copy is never blind. A one-off copy opens with four things, in this order, mission last:
- Who it is — its own name, the session it copies, and the engine and model it was actually started on. That line outranks anything else the agent reads about itself, including the harness banner in its own terminal, because a copy that believed its banner over its brief refused the job it was copied for (measured 2026-10-04).
- The crew's memory, when the session it copies belongs to a crew — the same block that crew's lead is woken with.
- The conversation it is carrying — the source's visible messages, the same ones the export button gives you, scoped to the most recent compaction so a copy gets a working thread rather than an archive. A very long thread is trimmed in the middle with the amount dropped stated in band, so nothing is silently cut.
- A purpose brief, from one fixed template every copy shares: the single job it was made for, what to return (a one-line summary, then the finding and the evidence), that its actions are read-only, when to stop (including a 20-minute limit), and who it reports to.
The engine comes with the copy. Unless the caller asks otherwise, a copy runs on the source
session's own engine and model — the same instrument you started. provider and model in the body
override that, and a pair that engine cannot run is refused with a 400 rather than quietly swapped
for the box default. A source whose own model has since been retired is not refused: the copy
keeps that engine and uses its current default model.
The mission is recovered, never invented. The copy is given the mission the source session was
started with — its own first message, the exact text a person typed. Hand it a session with no
opening message and the call is refused with "there is nothing to copy", because a copy carrying a
made-up job would be worse than no copy at all. An optional job in the body is what the brief
names as the copy's one job — the instruction it reads before the mission, never instead of it, so
the copy knows what it is before it is told what this particular run adds.
A large copy is a choice, not an accident. Before a one-off copy is started, its brief is
measured. Over about 10,000 tokens, the call is refused with nothing started: the answer says how
big the brief is, which two parts make up most of it (usually the crew memory and the copied
conversation), and that an ordinary helper with a short brief is the lighter choice when the job
does not need the lead's full context. To make the copy anyway, send the same request again with
acceptLargeBrief: true. A refused copy does not count against the hourly copy limit.
A copy always reports to the session it was made for. Whether a copy simply finishes or signs off and files itself away, its final report goes to the session that made it (or that crew's lead when the maker is gone), not to your inbox.
A standing peer hands the post over — it adds no second Overseer. Only one Overseer of a given
role runs at a time, so standing-peer spawns a successor on the SAME slot, hands it the mission,
your notes and the reason for the takeover, then stops the original. The successor starts through
the keeper's ordinary revival — a scheduled restart's path — so the post has exactly one live holder
by construction. Everything it needs survives: the slot's notes are an Overseer's memory, and its
briefing is composed from them as after a restart. One thing a restart cannot carry is the caller's
job, so that is written into the notes before the source stops.
A standing peer does not ask you first. Creating an Overseer normally raises an approval card —
POST /overseer/slots still does, and so does switching one on — but you already approved this one
by standing it up with a standing job, so it may hand its post to a successor on its own authority.
Only an Overseer can ask (a plain session is refused), and every other creation route still asks.
Three things stop a hand-off, and each protects something real:
- A source that still owes you an answer. If the Overseer is holding a question, a plan or a permission request for you, the hand-off is refused outright. Ending that session would take the question out of your inbox and the successor would have to ask again — so you answer first, then hand over. (A scheduled restart is gentler: it waits, and eventually goes ahead anyway; a hand-off always has you on the other end, so it can simply refuse.)
- A source that is mid-turn. Refused, with a request to try again in a moment; ending a session mid-turn would throw away the work it is doing right now.
- A post with nothing running on it. Nothing to hand over — the keeper already owns starting one.
One brake remains, and it is not a cap you set. A hand-off may happen at most three times in any trailing hour across the whole box, always on and not a setting. Every hand-off starts a fresh paid session, so a looping Overseer would otherwise buy a new always-on session per iteration while the board still showed one — a runaway nothing else would catch.
The old overseerSelfCloneLimit ("Copies of itself") cap is removed: it counted extra
Overseers left behind, and a hand-off leaves none.
You can switch hand-offs off. overseerCloneHandoffEnabled is on by default. While it is
off, an Overseer asking to hand its post over is refused: it keeps running as it is, nothing is
ended or recorded, and none of the hourly allowance is used. It takes effect on the next request,
with no restart; one-off copies are unaffected. There is no row for it in the Overseer settings
panel — ask Omniscio to "turn off Overseer hand-offs" (or back on), or set it with
PATCH /settings/overseerCloneHandoffEnabled.
One-off copies carry a guard of their own, not a share of that one: a copy is far cheaper than handing over a post, so the two are counted separately. Across the whole box, one-off copies are capped at twelve in a trailing hour, a copy counting only once it actually starts. It is not a setting, and is deliberately far above ordinary use: twelve real investigations in one hour is a busy night, so a working Overseer never meets it while a runaway loop meets it at once.
Why copies are routine: an Overseer never reads code or logs itself; it sends a copy or its own subagent and takes back the summary.
The review round — where an Overseer buys fresh eyes
The review — the six-hourly slow, wide look woken beside the heartbeat — exists because an agent cannot see its own blind spots from the inside, so the round does not ask it to try.
Two switches on Overseers → How they behave control this. Scheduled reviews
(crewReviewWakesEnabled, on by default) is the master switch for every Overseer's review, crew leads
and the hub seat alike. Turn it off and no review runs at all: no app-run round, no retried round, no
"step back" wake; each review schedule stays in place and picks up again when switched back on.
Independent reviewer sessions (crewAppRunReviewsEnabled) decides who does the review, as below.
For a crew lead, the app runs the round itself (app-run side missions, on by default — the "crewAppRunReviewsEnabled" setting turns it off). When the review is due, the app:
- picks the next of fourteen written lenses — each runs once before any repeats, except
First-Principles Rethink, which every live crew gets at least once a day: if you started this
mission fresh today, what would you do, and is the crew patching where a strategy shift is due?
- Owner's Eyes, Claim and Done Audit, First-Principles Rethink, Blind-spot Scan, Toolsmith;
- Stop Doing, Speed, Owner's Time, Collision, Hand-off, Owner's Experience, Every Developer, Safety, Staffing;
- gathers the evidence itself, with secrets scrubbed before anything leaves the machine:
- the owner's own typed words to the mission, and what the lead told the owner;
- the crew's tasks with their proof, and its rules and decisions;
- spend, live machine load, and earlier rounds' findings;
- starts an independent reviewer through the Review Service, on a low-cost AI from a different vendor than the lead (DeepSeek, or GLM when the lead runs on DeepSeek) unless the owner named one in "crewReviewEngine". That setting takes a provider id, a model tier or a model id, and only an engine a reviewer can be locked on: Claude or a Claude-compatible vendor. Naming one that cannot (Codex, say) is refused when the setting is changed, with the list of engines that can; empty means automatic. A value saved before that check is kept, and each round is skipped with a plain reason naming why, instead of starting a reviewer that would be refused.
The lead is not woken to do the review. When the review finishes:
- its report is written as the final message of the reviewer's own session (named like "[Mission Review] DeepSeek: <crew> — <lens>"): the verdict in words, a short plain summary, and for each problem how serious it is, what is going wrong and what should happen — no raw evidence;
- the same report opens from the crew's dashboard: each finished review in the Review card has "Read report", which also shows how the lead has answered each finding so far, plus a link to the reviewer's session;
- each finding (at most five) is added to the crew's task list as a "Review finding" task the lead owns, due two hours later;
- the lead accepts a finding by closing its task as done, and the app refuses that unless the outcome names what makes the fix stick: a move made now, a check, a playbook change, or an owner card;
- the lead rejects a finding by closing its task as dropped, with its reason;
- a finding left open past its due time is flagged overdue;
- a review whose finding about the lead itself repeats an earlier one reaches the owner as one inbox card, sent by the reviewer's session (never the lead's), titled "<crew>: problem came back — <problem>". It carries the whole report with the returning problem first, and a "Talk to the overseer" link instead of a reply box;
- the morning "Overseer reviews about you" card links each finding to its reviewer's report.
A review card belongs to the mission. Its top line wears the mission's own crown and name, and the title carries the review's number in that mission's series ("Cloud Sessions - Review 12"). The card draws the review as a report rather than a wall of text: the verdict and how many problems it found, a two-sentence summary, then one block per problem with how serious it is, what is going wrong and what should happen. A reviewer's answer stays one tap away.
You choose the reviewers, and how often they run, from the card. "Review settings" offers one to six models - any model the app can run, picked with the same chips the multi-model council uses - and the cadence (30 minutes, 3, 6 or 12 hours). Both are the mission's own; another mission keeps its own choices. Leaving the models empty means Automatic, which is the app's own choice from the wide setting. A mission's review clock cannot be switched off from there - the app refuses that for a lead - so the app-wide scheduled-reviews switch is how every mission's reviews stop.
Two or more reviewers, and they talk it out. Pick two or more models and the review runs as a swarm: each model works the whole review on its own first, the shared board stays shut until each has reported, then they read each other, argue and merge until the group agrees, and one model the app appointed as chairman writes the answer for everyone. That chairman's answer is the review - what the card shows, what your digest line says, and what becomes proposals on the mission's task list. With one model, or Automatic, the app just merges the answers it gets: the majority verdict decides, a tie goes to the more serious verdict, and the same problem raised by three models counts once with "3 agree".
Addresses a reviewer writes (web, e-mail, app links) are shown as plain text, never as links — the reviewer reads raw mission evidence, so its text is treated as untrusted.
A round that cannot start is recorded with its plain reason. The reasons are:
- the lead is not running;
- the machine is busy;
- two mission reviews are already running;
- no reviewer AI can run.
That last reason names every engine the round tried, each with its own reason. When the only lanes left in a family's list are ones a reviewer can never use — Omniscio credits, or the company developer lane an enrolled developer's ordinary sessions run on — it says so, and says it is by design: a reviewer is never given a sign-in of its own, so neither lane can serve one, however built in it looks.
The first three postpone the round rather than cancelling it; the same lens comes round again on the next wake. The machine being busy and the review slots being full both clear on their own, so neither may hold a review up for ever: after a small number of deferrals the round runs anyway, and says on the record that it started late. A lead that is not running is the one reason that does not expire — a review nobody will read is waste, not service.
The rules are in the Overseer Side Missions contract.
The daily audit — the one look that ignores the backlog
Every live mission gets a second, slower piece of fresh eyes: one audit a day, beside the six-hourly round and on the same machinery. It exists because every lens round reads the crew's own history on the way in — earlier findings, tasks, decisions — so a mission can drift with a tidy backlog and no round will say so.
The daily audit is deliberately handed no backlog at all. Its brief is the opposite of a lens: start from the mission's goal and its declared number, work down to what the crew actually spends, and answer with the top ten wastes, worst first, each with what it costs. Ten is a shape, not a quota — a padded list costs the reader more than it tells them.
A mission that has declared a success number is audited before one that has not, longest-waiting first inside each group, so a mission with a number to move never sits behind one with none. The app owns the clock: the audit is the app's own check, not a schedule anyone keeps alive, and it never arms one.
The audit and mission reviews use one serialized admission check for reviewer capacity, a live lead and per-crew limits, while keeping separate records, deferrals and delivery retries. Because they compete for the same reviewer slots, the daily audit yields to a due mission review and waits when the box is busy.
An audit that cannot start does not go quiet. Once it has been owed and refused a few checks in a row, the crew gets one line on its own record saying what the app could not start and that nothing is needed by hand; it never reaches your inbox, because a crew's own review failing is the crew's business.
The daily audit is one app job, and its promises are in the Crew Daily Audit contract.
With app-run rounds switched off — and always for a slot Overseer — the round asks the Overseer to
spawn a reviewer: a fresh, read-only session that reads its notes and ledger and reports what it
finds. A crew lead uses POST /crew/reviewers — no body; the app reads the crew, works out the
project and the lens, and writes the brief itself. That is deliberately the only spawn a crew lead's
locked-down credential may make, so it buys fresh eyes without the run of the machine: it refuses
anything but the live lead, and starts no second reviewer while one is on the crew. A slot
Overseer spawns through POST /agent/sessions with an allowed agent type.
In that mode, successive reviews rotate through six lenses, so each round asks a genuinely different question instead of re-finding the last answer:
| Lens | What it asks |
|---|---|
| META | Which of my own rules would have prevented my last mistakes? |
| RED TEAM | Attack my findings and every "done" I accepted. |
| PATTERNS | What recurring shape am I still treating as separate instances? |
| FRESH EYES | Re-derive the approach from scratch, without my priors. |
| INTAKE AUDIT | What request never got a row, an answer, or a close? |
| SPEND | What did the period cost, and what was waste? |
The Overseer records which lens is next in its own notes — for a crew lead, a decision line on its crew log — because the reviewer is a fresh session that carries none of that memory. A reviewer is normally capped at ten ranked findings, each with its evidence.
Both abilities are named in the prompts an Overseer reads — the standing persona for a slot Overseer, and a crew lead's wake prompts. A refused spawn is reported, never quietly replaced by a self-review, which reads exactly like a completed one. Copies split the same way: a one-off copy works for any Overseer, a standing peer only from an Overseer slot.
Giving one specific sessions to watch
A whole project is often the wrong unit. Open any Overseer's Settings tab in the hub and you can name the exact sessions it is responsible for — the Sessions it watches field, with a chip per session and a search box to add another. The wizard's Scope step offers the same choice (Just these sessions) when you set one up.
This is also what makes a custom Overseer useful: before it, nothing routed to one at all — it woke up, read its job description, and had no work attached.
Three things change once a session is assigned:
- Its alerts go to that Overseer — not to its project's, and not to the global one.
- Its questions reach that Overseer when the agent asks for guidance.
- That Overseer is told about it — every wake-up lists the sessions it owns with their current status, project, and when they were last active.
- Its finished turns report to that Overseer, not to you — see Where a watched session's answers go below.
A session has exactly one Overseer. Add a session another Overseer already watches and it moves; the dropdown says who currently has it, so that is never a surprise. The most specific choice wins: an assigned session beats its project's Overseer, which beats the global one.
Assigning pins a session; it does not narrow the Overseer. Give the global Overseer three sessions and it still covers everything else — otherwise every un-routed alert would have nowhere to land. A per-project Overseer likewise keeps its whole project and simply picks up the extras.
A broken assignment quietly falls back. Delete or switch off an Overseer watching sessions and they revert to their project's Overseer, or the global one. Nothing is stranded.
The dropdown lists sessions that are still running — an Overseer watching a finished session has nothing to do — and the list it gets is capped, so a large assignment cannot multiply what every wake-up costs.
Giving a custom Overseer a whole project
Hand-picking sessions does not scale past a few dozen, and it cannot cover a session that does not exist yet. So a custom Overseer can also take one whole project: on its Settings tab, under What it watches, the field Also watch a whole project names it.
Pick a project there and everything in it is that Overseer's:
- Its sessions route there — questions and swarm work from any session in the project reach this Overseer instead of the project's own. Alert notes about a session are still mirrored only for the sessions you pin by hand, so pin any whose cards you want it to see.
- Sessions created later are covered too, with nothing to set up — routing follows the project, not a list written in advance.
- Its swarms come with it, so nothing paid is left showing under an Overseer that no longer answers for it.
A project has one owner. A project that already has its own Overseer hands it over rather than sharing: the two never both work on one session. Giving the same project to a second custom Overseer is refused, naming the project — that is what keeps routing predictable.
Choose "No project" to hand it back. The project returns to its own Overseer, or to the global one if it has none. Switching the custom Overseer off does the same, so a paused Overseer never quietly keeps a project it is not working on — though it does keep its place: no other custom Overseer can take that project while it is switched off.
What still wins. A session you pinned by hand stays pinned, wherever its project goes. The most specific choice wins, same as everywhere else: a session you assigned beats a project claim, which beats the project's own Overseer, which beats the global one.
Only a custom Overseer offers this field: a project Overseer already answers for its project and the global one for everything else, so there would be nothing left for them to claim.
Where a watched session's answers go
Once an Overseer watches a session, that session reports to it, not to you. The agent finishes its turn, its final message goes to the Overseer, and nothing appears in your inbox — no card, no badge, no chime. The Overseer reads it, and only what it genuinely cannot handle reaches you.
That is the point of an Overseer: before it, one could command a fleet of agents and every answer still landed on you.
Sessions an Overseer starts belong to it automatically. You do not have to assign them — if an Overseer spawned it, it owns it, and gets its reports back. An assignment you made by hand is never overwritten by this.
Questions go to it too. If the agent ends its turn asking something, the Overseer answers it when it can and passes it up when only you can decide.
A question nobody answers comes to you. If the Overseer received an agent's question and has not answered it within thirty minutes, the agent moves to your Needs You with its question intact and a note saying your Overseer has not answered it. It never sits under Live waiting on you. A routine report is different: it stays with a running Overseer, as described below.
Some things always come straight to you, whoever is watching. A request for permission and a plan waiting for approval are your call, not an Overseer's, and they are never handed off. Nor are the failure states an agent can get stuck in — a rate limit, a sign-in problem, an interrupted response — because something else is already working on those.
A watched agent can never be lost. Three routes bring it back, and only one has to work: the Overseer replies and the agent carries on or is passed up to you; the message fails to reach the Overseer and the agent comes straight to you as before; or the Overseer stops running and within thirty minutes the agent appears in your inbox with its message intact. While your Overseer IS running, leaving a message alone is its answer — a routine report needing nothing from you stays with it. A message goes to whichever Overseer replaced the one that received it. Hand-off is never "assume it worked": a session goes quiet only once the message has arrived, so an Overseer that is switched off, deleted or not running cannot swallow an agent.
You can turn this off with the Send their sessions’ replies to them, not you switch, under How they behave in Overseer settings. Off, every session reports to you as before.
Talking to the Overseer itself — asking it a question and telling it an alert should have reached you — is on part 4.
Related
- Overseers — part 1, what an Overseer is and how you create one.
- Overseers part 3 — the work it hands out, its settings and the internals.
- Overseers part 4 — talking to it: asking it a question, and telling it an alert should have reached you.
- agent-status-board.md — the board that shows what the fleet is doing right now.
Last verified 2026-10-22