Omniscio

Cron job — Session spawn type

The Session job type in Omniscio's cron scheduler: instead of running a shell command or a recipe, it starts a brand-new Claude session in a project at the scheduled time, opening with a prompt you wrote, or wakes an existing session on a schedule. Covers setting one up, how each run is numbered, the live-session guard, the five-minute floor, and the heartbeat governor that nudges, cards and finally retires a wake schedule whose rounds keep finding nothing.

On this page

What it is

Omniscio's cron scheduler supports three job types: Script, Recipe, and Session. The Session type spawns a brand-new Claude session inside a project at the scheduled time, using a prompt you wrote when you created the job — exactly equivalent to clicking "+ Session" in that project and typing the prompt yourself, but on a recurring schedule.

This is useful when you want a recurring conversation rather than a recurring shell command (Script) or a recurring multi-step recipe. For example: "every weekday morning at 8:30 a.m., start a Claude session in my work project with the prompt 'summarize yesterday's git activity and draft today's plan'." Each fire creates a fresh session — past runs do not influence future runs because there is no shared memory between them.

Where to find it

Session jobs are created exactly like the other two kinds. Open the Cron Jobs view from the Cron row in the sidebar, click the new-job button, and pick Session on the job-type radios — the Project and Prompt fields appear in place of the script or recipe settings, and the schedule controls underneath are the same ones every job uses.

How it behaves

How to use it

  1. Open the Cron Jobs view. Click the Cron virtual project in the Omniscio sidebar, or open the Cron Jobs pane from the Settings → Cron Jobs section.

  2. Click "+ New Job" to open the job editor dialog.

  3. Set the job type to "Session". The form has three radio buttons: Script, Recipe, Session — pick Session. Two new fields appear:

    • Project (required) — pick the project the session should spawn in. Must be a real (non-virtual) project.
    • Prompt (required) — the initial message the new session opens with. This is identical to typing into the composer of a fresh session and hitting Enter.
    • Session Name (optional) — the label each spawned session carries. Leave it blank and the job's own name is used, so you never have to fill this in to get a sensible title; set it only when you want the sessions labelled differently from the job.

    Every spawned session is numbered, always. Whichever base name applies, each fire appends its run number — Performance watch review #10, overseer heartbeat #59 — so a job that has fired ten times leaves ten distinguishable sessions instead of ten look-alikes. The number is the job's own run count, so it matches the run history in the job panel, and a gap means a fire that errored before it could create a session.

    Because a numbered name is not a placeholder, the AI auto-titler stands down for these sessions (it only ever renames a session still called Session N). That is deliberate: an invented title differs on every run, which is the very thing the number is there to fix — one nightly job had accumulated seven near-identical variants of "Nightly PR cleanup". It also means a scheduled session costs no title-generation call.

  4. Set the schedule. Same controls as Script and Recipe jobs — pick a preset (daily at 9am, hourly, etc.) or type a 5-field cron expression. Pick a timezone. Choose run mode (recurring / one-off / limited).

  5. Save. Like every cron job, AI-created jobs land as Awaiting approval until you click Approve in the inbox; jobs you create yourself in the Omniscio UI arm immediately.

How it works

A session-spawn cron job stores its config in the cron_jobs.job_config JSON column with shape { projectId, prompt, sessionName, provider, model, thinkingLevel, location }. When the 60-second engine tick determines the job should fire, the engine routes the run to the SessionExecutor (cron-session-executor.ts) instead of the Script or Recipe executor. The executor validates the config (non-empty projectId, non-whitespace prompt) and calls the same createSessionWithPrompt path the Omniscio UI uses when you click "+ Session" — so spawn behavior matches manual session creation exactly: account auto-pick, worktree resolution, isolation, the works. A job that names location: "cloud" instead takes the cloud road (see below).

Failure detection covers two paths. If createSessionWithPrompt throws (project missing, processManager.launch crashed, etc.), the run is reported failed and the standard cron failure-alert pipeline kicks in (toast + inbox card + optional self-heal — see cron-failure-alerts.md). If createSessionWithPrompt returns successfully but the new session is already in status='error', the launch was refused without a throw. Two refusals do this: the API-key session-spawn guard (an API-key account is active but allowApiKeySessionSpawn is false, which never clears on its own) and a token refresh that failed on the network (common in the first minute after the app opens, which automatic recovery restarts a few minutes later). Both leave the same status, so the executor does not decide on that one read.

An errored launch waits for automatic recovery before the run is judged. The executor listens for the session's status changes (cron-launch-recovery.ts) and decides when the outcome is known:

  • Recovered — the session is running, waiting on you, ready or capacity-parked, and its pending action is not response_aborted. The run is success, and its output says launched after automatic recovery restarted its failed first launch.
  • Gave up — recovery marked the session terminal, handed it back to you with response_aborted, or it was archived, paused, ended or deleted. The run is failed.
  • Timed out — neither happened inside the wait budget. The run is failed, and its message says recovery had not restarted the session before the run ran out of time.

The budget is the smaller of four minutes and the time this run has left before the zombie-run reaper's deadline (resolveRunDeadlineMs), minus two minutes. Four minutes covers stuck-session recovery's first revive pass (a session must be stuck 120 s, and the sweep runs every 90 s); the measured revives came 146 s and 167 s after the error. Ending two minutes early keeps the run from being reaped as a zombie, which would hold the job's slot until a restart. A clean launch never waits. A failed run names the network, the active account and the "Allow API keys to run sessions" setting as the things to check. Measured 2026-11-13 and 2026-11-16: a daily job read failed on two mornings when its session had recovered and delivered its report.

Sessions are fire-and-forget — but the job will not stack a second one on top of a live one. Once the executor confirms the spawn succeeded, the cron run is success regardless of what the agent inside that session does next. The new session shows up in the project sidebar like any other session — you interact with it normally, archive it normally, etc. The run's success never depends on the agent's work.

The one coupling that does exist: while a session this job started can still make progress, the next fire skips its spawn and records the skip as a successful run naming that session. The guard clears the moment the session stops holding the job — once its turn is over and it is waiting on you, or it has ended, been archived, paused, or errored out. It does not wait for you to tidy your inbox, and a session you pause is not treated as a reason to stop the schedule.

This matters because a job's run is finished the moment the session is created — the schedule does not know the session is still working — so a job whose schedule is shorter than its sessions would otherwise stack one billable Claude session per fire. That is real: a 2-hourly evaluator job once had three of its sessions running at once, all doing the same work. Skipping is reported as success rather than failure on purpose: a failure would go to the retry and self-heal machinery, which would re-dispatch the executor and recreate the duplicate.

Because a skip is a success, a job that has stopped firing still looks healthy. If a scheduled session job quietly stops producing sessions, open its run history and read the output: a run whose output begins Skipped: was held by this guard, and the session id it names is the reason. The job's own last run timestamp and status stay green throughout — they answer "did the scheduler tick?", never "did a session get created?".

Archiving the session that set the job up does not stop it. You can ask an agent to schedule a daily session job for you, then archive that agent's session — the job keeps firing, because a job that starts a fresh session every time never needs the session that created it. Only a wake schedule — one that wakes an existing session instead of starting a new one — is switched off when the session it wakes is archived, and it comes back on if that session is un-archived. (Before 2026-10-14 a session job that started fresh sessions was switched off with its creator too, at every app start, so a job re-enabled by hand went off again at the next restart. Such a job stays off until you switch it on once; it then stays on.) Rules: cron-job-ownership-contract.md.

Run it hidden (force_silent). Set the job's Visibility radio to Force silent to spawn the session hidden — it stays out of the sidebar and inbox, auto-archives when it finishes, and only surfaces if it errors or stalls. Leave it on Use recipe default / Force visible for the normal visible behavior above. Details: silent-recipe-sessions.md.

Run it in the cloud (location). A session job can carry location: "cloud" instead of running on your own computer. The fire then provisions a real cloud machine and starts the session there — the same road a person-launched cloud session takes, including the cloud kill switch, the one-time spend consent, the billing check and the clock pre-flight. It is the way to schedule a heavy nightly job, or any job whose point is to leave your machine alone.

The approval card tells you which it is. A job waiting for approval carries a Run location row — "Runs in the cloud" for a job that asked for the cloud, "Runs on this computer" for every other job, including a session job that named nothing, and "Wakes an existing session" for one that re-uses a session instead of starting anything — so you are never asked to approve a cloud job believing it runs on your own machine.

A cloud job that cannot get to the cloud FAILS — it never quietly runs locally. If cloud sessions are switched off for this install, if the background cloud start is unavailable, or if the job's engine cannot run in the cloud, the run is recorded failed with a plain sentence saying why, and nothing is started. That is deliberate: an unattended job that asked for the cloud and ran in your own checkout instead is the one outcome you cannot detect from the outside, because a run that did the wrong thing is otherwise indistinguishable from one that did the right thing. Clearing the job's location makes it an ordinary local job again.

A job that names no location is completely unchanged — it runs locally exactly as every session job did before this option existed, so no existing schedule changes behavior.

In the Cron Jobs view, a session job shows its Type as "Session" and groups under the project it spawns into. That project comes from the job's spawn target (the Project you picked when creating it). Because a session job stores its project inside job_config rather than the job's top-level project field, Omniscio reads the spawn target for the By Project grouping, project search, and the detail panel's Project row — and mirrors it into the top-level field whenever the job is created or edited, so the grouping, search, and the ?project= REST filter all agree on where the job lives.

Cost protection: 5-minute minimum interval. The job-create Zod schema rejects session-spawn jobs whose cron expression fires more often than once per 5 minutes. (Recurring */4 * * * * would be blocked; */5 * * * * is the floor.) This is a guardrail against accidental account drain — every fire spawns a real Claude process, and a misconfigured per-minute schedule could burn through a rate-limit window in seconds. The Recipe and Script types do not have this floor because they are not guaranteed to spawn a Claude process per fire (a Script that runs git status costs nothing; a Recipe with no LLM steps costs nothing).

Telemetry. A successful spawn fires the cron_session_spawned feature event (index.ts) with projectId as the only allowed metadata key — prompt content and session names never leave the local DB. Failed spawns are not tracked under this event (they show up in the standard cron-run logs and the cron-failure-alert pipeline).

Waking a session instead of starting a new one (wake schedules)

The same machinery runs in a second direction. Instead of starting a fresh session on a timetable, a job can be pointed at a session that already exists and used to wake it — the scheduled run delivers its prompt into that session rather than creating a new one, cold-resuming the session's process first if it had ended. This is a wake schedule, and it is what lets a session put itself to sleep and come back later: an Overseer checking on a long job, or any agent that wants to look again in twenty minutes without holding a turn open.

The difference that matters is what it costs. A normal session job spawns a new session on every fire; a wake schedule never can — its whole purpose is to re-use the one it names — so waking a session does not add a session to your sidebar or bill a second one.

What a wake schedule cannot do (the two types share a table but not their full behaviour): it never asks for approval, never retries, never catches up a missed fire, and it is device-scoped. Those are deliberately fixed rather than configurable, because a wake is a nudge to a conversation that already exists — there is nothing to approve and nothing to spawn.

A crew's check-in stands duty

A crew lead's wake is normally skipped when the crew has no open task, no open ticket and nobody busy: nobody needs waking to lead nothing. That rule is wrong for a crew whose work IS watching something, because such a crew has an empty board exactly when nothing is wrong. So a check-in stands duty: its beat is delivered even with nothing to lead.

Duty is on by default for the two check-in types, heartbeat and review, and off for every other schedule. Any schedule can say otherwise: the Overseer's wake-schedules panel has one Check in when idle switch per row, and a schedule that declares standingDuty in its config takes that value instead of the default. A measured red Master Sync status wakes the lead whether or not the schedule stands duty.

The limits, all of which a caller hits rather than configures:

  • Cadence is bounded on both ends — at least 5 minutes apart, at most 24 hours.
  • At most 3 wake schedules per session at a time, or 12 for an Overseer session, which needs more of them because it supervises other work.
  • A schedule ends by running out, not by a date. Each wake schedule carries a maximum number of fires (288 by default — a day's worth at the five-minute floor) and simply stops when it has used them. There is no "expires at" time to set; if you want it gone sooner, delete it.
  • A last fire that cannot be delivered waits — then ends, instead of retrying for ever. If a schedule's FINAL fire is refused (its session is ended, paused, archived, handed off to the cloud, or busy), the wake is held and retried every 15 minutes rather than thrown away, and it delivers the moment that state clears. The wait is capped at 24 hours: after that the schedule finishes, records the reason, and stops costing anything. Nothing is deleted — a finished schedule is listed under the removed ones and switching it back on starts it fresh.
  • A wake held behind a busy turn still counts as arriving. A wake that fires while its session is mid-turn — an Overseer's six-hourly review landing seconds after its heartbeat, say — waits for that turn and is handed over then. The hand-over is what counts as the wake reaching the session, so a held wake never makes its schedule look silent or raises the inbox card about a wake that has stopped reaching its session.
  • Another schedule reaching the same session also counts. If a review reaches the session while its heartbeat keeps finding that review's turn running, the session has been reached. The latest actual arrival from either schedule resets the silence clock and clears an older false alarm. An arrival at a different session does not count, and the alert still appears when every arrival is older than the schedule's allowed gap.
  • A wake the app deliberately stands down is not silence. A schedule whose fire finds the session recently active (or already holding one of that schedule's wakes), waiting on an unread inbox card, with scheduled reviews switched off, with nothing to lead, or whose review round the app deferred, records a skip and stays armed — none of those raises the "stopped reaching its session" card. A wake that genuinely fails to arrive still does. "Recently active" is checked, not taken on trust: the session must have moved inside the last half hour, so a session that stopped moving behind a stand-down of that kind does raise the card rather than hide behind it.
  • That card is about the session, not one schedule. It appears only when no schedule has reached the session for longer than the schedule's own gap (at least two hours). If two schedules share one cadence — an Overseer's heartbeat and review, say — and one keeps finding the other's turn already running, the session is still being reached, so no card appears. Each skipped fire still shows in that schedule's run history.
  • A schedule moved to a new session starts a fresh clock. When a session hands over to a successor, its schedules move with it, and the silence clock starts at the moment of the move — not when the schedule was first made. A long-standing schedule never cards its brand-new successor minutes after a healthy hand-over; it cards only if nothing reaches the new session for the schedule's full allowed gap.
  • The "stopped reaching its session" card belongs to the computer that runs the schedule. A wake schedule lives on the computer hosting the session it wakes, and only that computer reports it silent — a schedule one computer runs never raises a card on another, even when both share the same synced account. A one-off is not judged before its own fire time either, so a wake set days ahead does not card in the minutes after it comes due.

A session manages only its own wake schedules: it can create, list, edit or delete the ones bound to it and can neither see nor touch another session's.

A heartbeat that keeps finding nothing is handled for you. A wake round that comes back perfectly healthy but declares it found nothing new is counted against that schedule, and three consecutive quiet rounds are treated as a heartbeat nobody needs. Omniscio then escalates:

  • At 3 the agent is told on its own next wake — how many rounds in a row found nothing, what they cost, and its options (slow the cadence, retire the schedule, hibernate, or close itself out).
  • At 12 you get one inbox card naming that schedule, its count and its cost. It links the session it keeps waking — tap the name to jump to what the agent is actually doing — and offers three controls: Open this job (the schedule, where the cadence and the switch live), Turn off this wake (switch that one schedule off on the spot; reversible from the Cron Jobs panel), and Stop the session (end the running agent itself — it confirms first, because unlike the other two it cannot be undone).
  • At 25 the schedule is switched off. The fire before that announces itself as the last one, so the agent can re-arm the heartbeat if the guard is still wanted, and nothing is deleted — the row, its prompt and its history survive, and turning it back on through the normal control clears the retirement.

Either way out starts the count again. Re-arming a switched-off heartbeat, and giving a live one a new cadence, both end the current run of quiet rounds — so the schedule is judged on what it does from that point, rather than carrying the count that condemned it. That is what makes the two things the escalation asks for (slow the cadence, or turn it back on) actually take effect.

A re-arm is allowed once a day, and a refusal says so. One switch-on out of a retirement per schedule per rolling 24 hours, whichever control made it, so a defeated heartbeat cannot be kept firing on a paid cadence by flipping the switch again and again. Ask a second time inside that day and the switch stays off and tells you why — it was already re-armed today, and a fresh schedule is the way forward if the cadence is genuinely still wanted. Switching a heartbeat you turned off yourself is not a re-arm and is not counted.

Two rules keep it from firing on a heartbeat that is working. A round is counted quiet by what it moved, never by how it was worded: any record the app wrote during that round — a crew task, a status line, a deliverable, a log entry, a message sent to another session, a commit, or a round an Overseer recorded through POST /overseer/round — makes it productive and starts the count again. What the agent said is deliberately not consulted, in either direction: a summary that reads like work is not work, and neither the no-op sentence nor the quiet or hibernate marker can switch the record off. And a round whose verdict could not be observed counts as productive, so a streak only ever advances on evidence. AMC_DISABLE_HEARTBEAT_GOVERNOR=1 turns the whole governor off.

The manual version of what this type does on a schedule — starting a session by hand and what happens as it comes up — is on the start a new session page, and how Omniscio picks which Claude account a spawned session runs on is on account pool. The other per-job switches a cron job can carry are on run if missed and cron self-healing.

Last verified 2026-11-12