[Feature] Unified automation & loop: one scheduled-task primitive

[Astro-Han]

What task are you trying to do?

I want PawWork to run a chat on its own, without me sitting and driving every run:

• On a schedule — "every morning at 9, summarize today's email into a brief."
• Repeatedly until something is true — "keep fixing the code until the tests pass."
• Once, later — "remind me / check back on this in 10 minutes."

Today none of this is possible. Every run is manual and in-session.

Which area would this change affect?

App flow or product behavior (primary). Also touches model harness / tools / session mechanics, since the same capability is exposed to the agent as a single tool and runs inside the engine.

What do you do today?

Nothing — there is no scheduling or looping. I have to be present, type the prompt, and watch each run. Confirmed in code: there is no scheduling/background infrastructure at all (packages/opencode/src/cli/cmd/serve.ts is a passive HTTP server that just waits forever; no cron, interval, or detached-run primitives anywhere).

What would a good result look like?

One unified "Automation" concept — not three separate tools (Loop / Schedule / Reminder). It is modeled in two layers: an Automation (the rule: a tagged union of one-shot vs recurring) and an AutomationRun (the record of each execution). The rule's orthogonal knobs:

• Trigger rhythm — one-shot time · interval-after-completion (loop) · cron (automation)
• Prompt — what to do
• Continue vs fresh — continue the automation's own ongoing session, or start a new empty one (never pollutes your main chat)
• Stop condition — count / condition / never (recurring only)
• Where it runs — which project (and, for fresh runs, optionally an isolated worktree)

The same object is created by the user (natural language, or a manual form) and by the agent itself (self-scheduling, e.g. "I'll check back in 10 minutes"). One tool, so the agent never has to choose between overlapping primitives.

It runs locally while PawWork is open. When an unattended run hits a permission prompt, it parks and shows the existing pending marker in the sidebar; I approve when I return.

What would count as done?

• I can say "every day at 9am, summarize today's email" in chat → an Automation is created and shown back on a confirmation card that echoes the parsed fields.
• I can create the same Automation via a manual form (title, prompt, project, schedule) and from a template.
• An "Automations" section in the sidebar lists my automations; I can view, edit, pause, delete, Run now, and review each run's history (including skipped runs and why).
• A recurring automation fires on schedule while the app is open; results land in a new empty session (fresh) or its own ongoing session (continue) — never in my main chat — following the continue/fresh knob.
• A loop-style automation ("keep doing X until Y") repeats and stops when its condition is met (with hard ceilings as a backstop).
• The agent can schedule its own follow-up run from within a conversation, using the same single tool.
• When an unattended run needs approval, the session parks, the sidebar shows the pending marker, and approving it resumes the run.
• Automations run under the existing permission framework (allow / deny / ask + autoAccept); the scheduler adds no separate permission system.

What should stay out of scope?

• No cloud execution / "runs while the app is closed" — local, app-open only in v1.
• No separate permission system inside the scheduler — reuse the existing one.
• No catch-up for missed runs — if the app/machine wasn't up at the trigger time, that fire is skipped (recorded with a reason); use Run now to trigger it manually.
• No auto-pause on repeated failure — failures are made visible (run history + consecutive-failure count + notification), not silently paused.
• No cross-restart persistence of pending approvals in v1 (in-memory; lost on app restart).

Which audience does this matter to most?

Both.

Extra context

Reference: OpenAI Codex Automations — adopt its UI shell (sidebar "Automations" entry, create-via-chat / create-manually toggle, templates such as Daily brief / Weekly review / Project monitor, a friendly schedule picker, an explicit project selector, and a per-task worktree toggle), and extend it with the two loop knobs Codex lacks: continue-vs-fresh context and a stop condition.

Full design doc, the architecture-review revisions, competitor comparison, and codebase grounding are in the first comment.

[Astro-Han]

Design: Unified Automation / Loop ("Automations")

This design has been through one architecture-review pass; the decisions below are the current, considered version (not an original + patch). Where we deliberately diverged from review suggestions, the rationale is recorded under Deliberate non-goals.

One primitive, deliberately merging what other tools split into "Loop", "Schedule", and "Reminder" — because they are the same primitive at different parameter settings.

---

1. The model: two layers

Naming: user-facing Automation; internally AutomationDefinition (the rule) + AutomationRun (one execution). We avoid the name "Task" — it collides with the legacy task permission key (now agent) and with todo semantics.

AutomationDefinition — the rule

A tagged union of one-shot vs recurring; the shape decides which knobs apply (keeps them MECE — no "only valid in mode X" flag soup):

One-shot: { fireAt, prompt, context, where }

Recurring: { rhythm, prompt, context, stop, where }

• rhythm — interval-after-completion (wait N after each run finishes; completion-anchored so a slow run never overlaps itself — the loop rhythm) · cron (wall-clock, e.g. 0 9 * * * — the automation rhythm)
• context — continue (same session) · fresh (new empty session). See §3.
• stop — count(n) · condition (agent's "done" judgment, a soft early-stop only) · never
• where — which project, and (fresh runs only) live directory vs isolated worktree. See §3/§5.

Loop / Automation / Reminder are settings of this one object:

Intent	shape	rhythm	context	stop
Loop until tests pass	recurring	interval-after-completion	continue	condition
Daily email brief	recurring	cron	fresh	never
Remind in 10 min	one-shot	—	continue	(fires once)

Discipline: knobs stay orthogonal. A param becoming "only valid in mode X" is the signal a merge is forced — reconsider then.

AutomationRun — the ledger

Every execution is its own record: state (scheduled / running / awaiting_permission / succeeded / failed / skipped / expired), triggeredAt / startedAt / completedAt, the sessionID it ran in, result / error, cost. This is what makes "how many times did it run", "last result", "why was it skipped", and the management panel possible. It is also what the panel reads from — invisible plumbing now, but the foundation the visible UI sits on.

Model-readable validation (hard requirement, the agent calls this tool): errors name the wrong field + correct shape + an example ("one-shot takes no stop rule; drop it or use a recurring rhythm"; "invalid cron …, expected 0 9 * * * = daily 9am"). On success the tool echoes the resolved definition back so both the agent and the confirmation card can verify interpretation.

---

2. Who creates one, and how

Two entry points, same object, same single tool, same validation:

• Natural language — "every day at 9am, summarize today's email" → the agent calls the scheduling tool, parses it, and renders a confirmation card echoing the parsed fields (a usability check that it understood you, not a security gate).
• Manual form — title + prompt + project + schedule (+ templates like Daily brief / Weekly review / Project monitor, to kill the blank page for non-technical users).

Agent self-scheduling uses the same tool, directly — no special gate. "I'll check back in 10 minutes" = a one-shot, +10min, continue current conversation. We do not add a propose-then-confirm gate for agent-created automations: prompt-injection is a base-layer problem, and an injected automation is still bounded by the same permission/park layer (§4) and is plainly visible in the Automations panel (reviewable, deletable). A gate on top of that base defense is redundant.

Management lives in a sidebar Automations panel: list, edit, pause/resume, delete, Run now, review history (including skipped runs and why), review/revoke saved approvals.

UI shell mirrors Codex Automations; the two extra knobs (continue-vs-fresh, stop) are our additions.

---

3. Runtime and session placement

• Where: local, runs while the app is open (incl. tray) and the machine is awake. No cloud in v1. Precedent: Claude Code Desktop scheduled tasks, Codex local automations.
• How it fires: at trigger time a forked Effect fiber starts/continues a session and runs the prompt. Interval-after-completion is run → sleep → run on that fiber.
• Session placement follows the context knob — and never pollutes the user's main chat:
  • continue → the automation's own ongoing session; length is handled by the engine's existing compaction, we add no trimming/summarization logic (the "what is clean / who summarizes" rabbit hole is explicitly avoided).
  • fresh → a brand-new empty session each run (nothing carried, so no trimming needed).
  • Defaults: loop → continue, cron → fresh (changeable). The only time an automation continues the user's actual chat is the ephemeral AI self-schedule ("check back in 10 min").
• Execution context (where) is per-automation: default live directory; an isolated worktree is an optional toggle, offered only for fresh runs (a continue run inherits the location it already lives in). Same-project runs are single-writer to avoid clobbering. Non-git / non-code projects never see the worktree option.

---

4. Permissions and unattended handling

• The scheduler owns no permission logic. Runs use the existing allow / deny / ask + per-session/per-directory autoAccept framework (packages/opencode/src/permission/).
• Unattended ask reuses existing mechanism, builds nothing new: the run parks (engine already blocks on a Deferred with no timeout); the sidebar already shows a pending marker on non-focused sessions (sidebar-items.tsx, isAsking); you return, approve, the run resumes. This park-by-default is the real safety line — consequential actions don't happen unattended unless you've granted allow.
• Autonomy is opted into via the existing allow rules, not a scheduler knob.
• No per-automation permission scope in v1 (reuse session/directory grants). The known trade-off: autoAccept set for interactive convenience also grants unattended runs the same bypass — a wider blast radius. Accepted as a revisitable risk; park-by-default contains the default case. (Noted: Claude Code does scope saved approvals per-task; we are choosing the simpler shared model for now.)

---

5. Guardrails — reuse, don't invent

• Per-run ceiling: reuse the engine's existing step cap (agent.steps, today defaults to Infinity) by giving automation runs a real default value; reuse the existing abort path to stop a run (cancel / expiry / panel "cancel run"). No new "kill switch" subsystem. There is no single-run cost/time cap — there isn't one for normal interactive use either; the human-in-the-loop was the cap, and for automations the panel + abort stand in.
• Repetition ceiling: the stop = count knob + task auto-expiry (stops after N days unattended) + minimum-interval floor + concurrency cap.
• Failures are made visible, not auto-paused: record in the run ledger, show a consecutive-failure count in the panel, notify after N consecutive failures. We do not auto-pause (no competitor does; it would "stop on the agent's behalf" and surprise the user). The differentiation vs competitors is not hiding failures (Claude Code Routines docs warn that "green" ≠ success).
• Missed runs = skip, no catch-up. If the app/machine wasn't up at the trigger time, that fire is skipped. We keep three cheap, orthogonal bits: skipped runs recorded with reason in history; cron stores its creation timezone (for correct trigger computation); the UI previews the next few fire times. "I want today's run" is covered by manual Run now. (This is simpler than Claude Code, which does one catch-up on wake; we avoid catch-up's "9am brief runs at 11pm, stale" foot-gun.)

---

6. Scheduler as a supervised backend service

A backend singleton (Effect Layer, same shape as Permission.Service): on startup, scan due/missed definitions; hold a durable lock; dedup across multiple windows / serve + desktop so a fire happens once; on shutdown, mark in-flight runs interrupted. Use Schedule / forked fibers / Effect.repeat, typed (tagged) errors — no raw setInterval / bare Promises, no tech debt. There is no scheduling infrastructure today (serve is a passive HTTP server), so this is greenfield.

---

7. Why merge (the core bet)

Loop, ScheduleWakeup, and Cron elsewhere are one primitive at different counts/anchors — "Loop can implement ScheduleWakeup" proves they implement each other. Overlapping, mutually-implementable tools are exactly what make a model hesitate. Merging removes the choice; §1's orthogonal knobs keep the single tool from re-introducing confusion.

---

Deliberate non-goals

Scope decisions, including where we diverged from the architecture review:

• No cloud / "runs while app closed" — local, app-open only in v1.
• cron is kept (review suggested cutting it). "Daily at 9am" is the flagship use case and cron is cheap; the complexity lives in permissions/sessions/runtime, which we build regardless.
• No per-automation permission scope (review suggested adding it) — reuse the existing framework; park-by-default contains the default case.
• No auto-pause on repeated failure — make failures visible instead.
• No gate on agent self-scheduling (review suggested propose-then-confirm) — the base permission/park layer + panel visibility already bound the risk.
• No catch-up for missed runs — skip + manual Run now.
• No cross-restart persistence of pending approvals in v1 (in-memory; a parked run is lost on app restart and must be re-triggered).

---

Competitor landscape (verified against official docs)

Product	Variant	Where it runs	Needs you present	Runs with app closed	Result delivery
Claude Code	/loop	local, in session	yes (terminal open)	no	printed into the live conversation
Claude Code	Desktop scheduled tasks	local, in app	no, app open + machine awake	no	desktop notification + new session; one catch-up on wake
Claude Code	Routines	cloud	no	yes	task pushes (Slack/PR); min 1h; daily caps; failures silent by design
Codex	local project automation	local, in app	no, app open	no	sidebar Triage inbox
Codex	cloud worktree automation	cloud	no	yes	inbox / Slack / PR diff
Cursor	Automations	cloud	no	yes	Slack / GitHub PR, etc.

Takeaways: local scheduled automation is mainstream (no cloud backend required); nobody runs locally with the machine off (physically impossible) — the real fork is local-app-open vs cloud, and we chose local-app-open; nobody auto-pauses on repeated failure, and failures tend to be silent — a gap we close with visibility.

Sources: code.claude.com/docs (scheduled-tasks, desktop-scheduled-tasks, routines), developers.openai.com/codex/app/automations, cursor.com/docs/cloud-agent/automations.

---

Codebase grounding (verified)

• Permission framework is clean: allow / deny / ask (default ask), rule matching by tool/pattern, last-match-wins; config in pawwork.json permission; session- & directory-level autoAccept in the frontend. packages/opencode/src/permission/{index,evaluate}.ts, config/permission.ts, packages/app/src/context/permission.tsx.
• Unattended ask currently hangs — Deferred.await, no timeout (permission/index.ts); pending is in-memory, rejected by the finalizer on process exit (lost on restart).
• Session archive is manual-only — no auto-archive/idle-eviction; a parked background session is not auto-killed (server/instance/session.ts).
• Sidebar pending marker already exists for non-focused sessions (sidebar-items.tsx, sidebar-status-kind.ts).
• Per-run step cap exists but defaults to Infinity (session/prompt.ts, config/agent.ts); abort path is well established (session/processor.ts).
• No scheduling infrastructure exists — greenfield; serve is a passive HTTP server.

---

Open assumptions

• Guardrail numbers (step-cap default, interval floor, expiry window, concurrency cap, consecutive-failure-notify threshold) — TBD.
• Run-record retention (how long to keep AutomationRun history / linked sessions; what "delete automation" does to history) — TBD.
• Initial template set — TBD.

[Astro-Han]

Build plan — converged. This comment is the canonical PR-decomposition / execution plan for this issue, settled after several independent model-review passes (including parallel multi-model crosscheck) with no open P0/P1. The product design above is unchanged; this is purely how we ship it.

For anyone (or any agent) picking this up: you do not need to write a new execution plan. Implement the PRs strictly in order against the frozen §3 contract, follow each PR's scope + verify lines, and keep the §2 blocking decisions intact. Ownership: backend (PR1–PR5) → Codex, frontend (PR6–PR7) → Claude. Execution is serial: each PR merges before the next opens.

Issue #950 — Unified Automation / Loop: PR decomposition & build plan

Status: converged build plan (reviewed across multiple independent model passes, including parallel multi-model crosscheck; no open P0/P1). The design in #950 (first comment) is locked and architecture-reviewed. This doc does not re-litigate the design; it decides how to ship it — PR slicing, the backend/frontend seam, the blocking decisions, and ownership. It is the execution plan: implement the PRs strictly in order against the frozen §3 contract — no need to re-plan.

Ownership: backend (PR1–PR5) → Codex, frontend (PR6–PR7) → Claude. Execution is strictly serial: each PR merges before the next opens. The seam (§3) is the contract everything else builds against; it is locked in PR1.

---

1. Grounding (verified 2026-05-27, against dev)

Codebase facts the plan depends on:

• Permission: allow/deny/ask, default ask, last-match-wins. deny rejects immediately (DeniedError, permission/index.ts:183-212); only ask parks on a no-timeout Deferred.await (index.ts:223-231). Pending is in-memory; the exit finalizer rejects it (index.ts:161-166) and emits no replied event. Permission does publish asked/replied bus events during normal flow.
• question is allow for the default agent (base ruleset question: "deny", agent/agent.ts:85, but build overrides to allow, agent/agent.ts:123 — note this is src/agent/agent.ts, not src/config/agent.ts), and the tool waits on an external-result Deferred (question.ts:120). External-result has no symmetric bus event — it is a module-level registry with route-based hydrate (server/instance/external-result.ts) and surfaces to the UI via message.part.updated (externalResultReady). So you cannot assemble blocker state for question by listening to a bus the way you can for permission.
• An active within-turn loop gate already runs: SessionPrompt.applyLoopGate (prompt.ts:134, :833, :906) executes before every tool call and can block/stop repeated calls. It keys off processor.message.parentID, which is the assistant message's parent user-message id (MessageV2.Assistant.parentID, set to lastUser.id, prompt.ts:1033/1996/2046) — not a sub-agent session id. Every normal assistant turn has it, so the gate does fire on top-level automation runs (it only no-ops on a parent-less synthetic message). (The doom_loop config key is separate and unwired.) This is not the user-facing automation rhythm; do not reuse it for that (D2).
• Step cap is soft. agent.steps ?? Infinity (prompt.ts:2023) only appends a MAX_STEPS assistant message at step >= maxSteps and still passes tools to the processor (prompt.ts:2178) — the model can ignore it. The abort path (session/run-state.ts, prompt.ts:327) is the real stop.
• Sidebar pending marker is a session-level isAsking OR (permission OR a running external-result question, sidebar-items.tsx:92-111) — not a per-automation run ledger.
• SDK is generated from OpenAPI (packages/sdk/js/script/build.ts) and consumed by the app's global-sync event reducer. New types reach the frontend only after routes + schemas + SDK regeneration.
• Event replay is a whitelist. EventReplayStore.append only stores envelopes that pass isReplayableGlobalEvent (server/event-replay.ts:93-94); a client reconnecting with a lastEventID replays only those. New automation.* events that are not added to that predicate are lost on reconnect/gap.
• No scheduler exists. serve.ts ends in await new Promise(() => {}) — an empty event loop — but the real service layer is AppLayer (effect/app-runtime.ts), which desktop also runs. Where the scheduler lives is a real decision (§4 PR3).
• Service shape: Truncate.Service / Permission.Service are style references for Layer.effect + InstanceState + forkScoped + finalizers; neither models per-definition timers / reschedule / cancel / test clock / next-fire computation.
• Session archive is manual-only; clearSession has a "dangling_session" reason reusable for orphan cleanup.

---

2. Blocking decisions

D1 — Blocking is tracked at the run-context seam; park policy depends on attendance

An automation run can block on (1) an ask permission and (2) a question tool call (default agent allows it). These have asymmetric plumbing — permission has bus events, external-result does not — so the correct mechanism is not "listen on a bus beside the scheduler". Instead, thread an AutomationRunContext (Effect service) through the run so that SessionPrompt's common blocking seam (ctx.ask / ctx.externalResult) writes the run's blocked state directly. One seam, both block kinds, no event-reassembly.

Blocked run state: awaiting_input with blocker: { kind: "permission" | "question", sessionID, requestID?, callID? }.

The two block kinds are not symmetric, and ctx.ask is not a plain wrapper. ctx.externalResult always registers then awaits, so the run context records the blocker on entry and clears it on the question's resolve/dismiss/abort transition (those exits, not just success, must return the run out of awaiting_input). Permission.ask instead returns immediately for allow, throws for deny, and only parks for ask — and the caller gets no signal that it actually parked before Deferred.await. Writing awaiting_input before calling it would mislabel allow. So PR2 adds a narrow Permission API — Permission.ask takes an onPending(request) callback (or split evaluate/enqueue) — and ctx.ask writes the blocker only when onPending fires. Crucially, ctx.ask is wrapped in Effect.orDie today (prompt.ts:742), so a deny/reject is a defect, not a typed failure — the blocker must be cleared in ensuring/onExit, never catchAll (which cannot see a defect), or a denied run stays stuck awaiting_input.

These two block kinds are gated by one explicit attendance field on AutomationRunContext (attended | unattended), read at both seams — and the two kinds are treated differently, deliberately:

• ctx.ask permission: parks in both cases (matches the design's park-by-default). For unattended the only difference is it parks slot-free and is recorded (see policy below). It is not terminalized — permission approval is exactly what park-and-resume is for.
• ctx.externalResult (question): for unattended, fails fast as needs_user_input before ExternalResult.register (the native question tool calls ctx.externalResult unconditionally, question.ts:140); a question has no resume-after-restart story.

The engine touch this requires is named explicitly: a small edit to permission/index.ts adding an onPending(request) hook to Permission.ask (today it parks via Effect.ensuring(Deferred.await,…) with no pre-park hook, index.ts:226), plus the AutomationRunContext attendance read at the two prompt.ts seams. Both land in PR2 as one gate; PR3 only sets attendance = unattended and adds no second engine touch. Because the exit finalizer emits no replied event (§1), the badge-clearing path depends entirely on the PR2 ensuring/onExit writing the run's terminal/cleared state — call that dependency out in PR2 acceptance. The native question tool can also Effect.die on its duplicate-label guard before reaching the seam, so the run loop must terminalize defect exits too, not only the gated ones.

Park policy is split by who is present, because an unattended, indefinitely-parked, non-durable run can deadlock:

• Attended (Run now, PR2): the user triggered it and is present → normal park is fine; they approve and it resumes.
• Unattended (scheduled, PR3): a parked run releases the global concurrency slot (so it can't starve other automations) but still holds its own automation's active/blocked token — so the same automation cannot pile up overlapping parked runs. The next due fire while one is parked is recorded skipped with reason previous_run_awaiting_input (or waits for expiry). The block is recorded in the ledger. Via the attendance gate above, question fails fast (needs_user_input) for unattended runs and permission ask parks (matches design).
• Durable park + resume + restart reconciliation (PR4): only once runs persist can a parked run survive UI/restart and be reconciled. On restart a still-awaiting_input run is terminalized (expired, reason "blocker lost on restart"), per the design non-goal (no cross-restart persistence of pending approvals).

Rejected alternative: a schedule-side pre-check that only lets allow-resolving runs go unattended. Contradicts park-by-default; silently skips useful runs. Revisitable.

D2 — Do not reuse the existing loop gate; the automation's own knobs are the ceiling

applyLoopGate is a within-turn repeated-call guard, not the user-facing rhythm. The loop ceiling is the design's knobs: stop = count(n) + auto-expiry + min-interval floor + concurrency cap + the hard step cap (D3). The gate does fire on top-level automation runs (§1: its parentID is the per-turn user-message id, always present), so when it stops a run the ledger records stopReason: "loop_gate" (it is in the frozen enum). Just don't conflate the gate with the rhythm — the gate guards a single turn; the rhythm is the schedule between runs.

D3 — Hard stop is a real gate in the run loop, not a ledger flag

Because the step cap is soft (§1), automation runs need a hard gate in the run loop / runner: at the ceiling, withhold further tool execution and cancel/terminate the session fiber via the abort path, then write the terminal state (stopReason: "step_cap") only after the run is durably recorded. Reuse the abort path for cancel/expiry too. Tests must cover "model ignores MAX_STEPS and keeps calling tools" → run is still hard-stopped.

---

3. The backend/frontend seam — frozen as concrete OpenAPI + SDK + events in PR1

The SDK is generated from OpenAPI and events flow through global-sync + the replay whitelist (§1), so the seam is concrete, not illustrative. Frontend (PR6-7) builds against the generated SDK types/client and event fixtures. PR1 ships routes + Effect schemas + regenerated SDK + the events (added to isReplayableGlobalEvent) + fixtures. Some route impls are stubbed until later PRs, but signatures, enums, error shapes, ordering/cursor, and event payloads are final at PR1.

Naming contract (frozen at PR1 — verb tool, noun resource): the agent-facing tool is the verb automate (a single verb, like edit / read / plan); the resource it produces — product name, schemas, events, routes — is the noun Automation (AutomationDefinition, AutomationRun, automation.* events, automation.list/get/create/... routes, sidebar "Automations"). Mnemonic: you automate something and it produces an Automation. The verb/noun split is deliberate (a verb tool reads as an action, a noun type reads as data → higher tool-call selection accuracy), not an inconsistency — confirmed against independent Codex + DeepSeek passes. Do not name the tool automation (a noun reads as a resource/getter and lowers tool-call selection accuracy), and do not introduce heartbeat (already the file-lock heartbeat in flock.ts; it is also merely OpenAI Codex's nickname for the continue mode, which we already express via the continue/fresh knob), loop (the within-turn applyLoopGate, and only one rhythm), cron / job (too technical/narrow for non-technical users), schedule (collides with Claude Code's cloud /schedule and loses the loop-until-condition rhythm), or routine (reads as recurring-only and is a different root from the product name).

Types (in packages/opencode, surfaced through the generated SDK):

• AutomationDefinition — tagged union oneshot | recurring. id, title, prompt, revision (monotonic, see below), updatedAt, single paused: boolean (not enabled+paused), context: continue|fresh, where (projectID; worktree accepted but rejected as unsupported_where_worktree until PR5), createdAt, timezone; one-shot adds fireAt; recurring adds rhythm (interval | cron), stop (count|condition|never), nextFireAt / nextFires preview. Session refs are explicit and distinct: sourceSessionID? (the chat a self-schedule was created from, if any) vs automationSessionID? (the automation's own ongoing session for continue). The per-run session is AutomationRun.sessionID.
• AutomationRun — id, automationID, revision (monotonic), state (scheduled|running|awaiting_input|succeeded|failed|skipped|expired), blocker (when awaiting_input: kind, sessionID, requestID?, callID?), triggeredAt/startedAt/completedAt (epoch ms), sessionID, result (bounded summary, not the full long output — fetch detail via sessionID), error (enum incl. needs_user_input + message), skipReason? (enum incl. previous_run_awaiting_input), stopReason?, cost. Definition-level failureStreak for the consecutive-failure notify.
• Terminal-reason vocabulary + state mapping (frozen now, not just step_cap): the run history (PR6) needs to show why a run ended, so freeze the full enum at PR1 even though some impls land later — stopReason ∈ { step_cap, loop_gate, cancelled, expired, blocker_lost } — and freeze which state each co-occurs with, so count accounting and PR6 rendering can't diverge: state = failed ← genuine attempts force-stopped (step_cap, loop_gate) → consume count; state = expired ← externally terminated / not a genuine attempt (cancelled, expired, blocker_lost) → do not consume count. This avoids a mid-stack contract reopen when cancel (D3), expiry/reconcile (PR4) each need a distinct cause.
• revision resolves the response-vs-event race (frozen now): an HTTP mutation response and the *.updated event carry the same monotonic revision for that object; the frontend reducer ignores any snapshot whose revision is older than what it holds. Without this, runNow returning scheduled can clobber a newer running event that already arrived over SSE. The monotonic-revision compare-and-ignore-stale reducer already exists (global-sync.tsx:47) but only for session_todo today — so extending it to automation.*.updated is explicit PR6 frontend work, not a free reuse. Fixtures must cover "route response arrives after the event".
• Count accounting (frozen now): only succeeded/failed consume stop = count; skipped/awaiting_input/expired do not. Same rule for condition. Combined with the no-overlap rule (§2 D1) and expiry, a perpetually-parking automation terminates via expiry rather than spinning forever.

Operations (final operationId/path at PR1; some impls stubbed):

• automation.list / get / create / update / pause / resume / delete / runNow
• automation.runs(automationID) — defined ordering + limit/cursor/nextCursor.
• mutations return the full definition (with revision); runNow returns the created run (with revision); delete returns a tombstone for optimistic apply.
• create is the same path the agent tool uses; create echoes the resolved definition. Echo carries normalizationWarnings if anything was adjusted; there is no silent coercion (the min-interval floor rejects with 422, §5).

Initial load + scoping (contract frozen now; app-side wiring is PR6): the design is that automation state joins global-sync — bootstrapDirectory calls automation.list on first load and after server.connected (replay gap / invalid cursor), so the panel is not live-event-only and survives reconnect (bootstrap.ts:300, global.ts:125). PR1 (backend) only freezes the contract + ships fixtures; the actual app-side store/reducer/bootstrap wiring is frontend work in PR6, not PR1. Automations are scoped to the current Instance: PR1-4 accept only where.projectID === current Instance.project.id. This is a new validation PR1 adds — the existing WorkspaceRouterMiddleware (middleware.ts:52) scopes requests by directory/workspace but does not enforce this equality, so PR1 adds it on the automation routes. The event envelope's directory is the owner directory and project is that projectID.

Events (existing bus, added to isReplayableGlobalEvent): automation.definition.updated, automation.definition.deleted (tombstone), automation.run.updated — each a full snapshot (with revision) of the affected object, matching how global-sync consumes session/permission events. The bounded-result rule above keeps snapshots small enough for the replay buffer (2048 records / 5 min). Ship event fixtures so frontend builds before firing is real.

---

4. PR breakdown

Flat PRs from latest dev, executed strictly in order — each merges before the next opens (no parallel frontend track). The backend firing core is two PRs — PR2 (manual Run now) then PR3 (background timers) — so execution/guardrails/blocker are proven while a user is present, before the unattended/ownership complexity arrives.

PR1 — Contract + in-memory store + hidden tool + SDK/events (Codex, backend)

Freezes §3; does not make automations execute, so the automate tool stays hidden / feature-flagged (no user can create a never-firing automation yet).

• AutomationDefinition + AutomationRun Effect schemas; the frozen §3 contract.
• The automate tool (hidden; verb — see the naming contract in §3): model-readable validation (names the wrong field + correct shape + example) and echoes the resolved definition.
• In-memory store + CRUD/list/runs routes (real where cheap, stubbed where they need a runner), regenerated OpenAPI + SDK, event payloads added to isReplayableGlobalEvent, and fixtures.
• Verify: headless — validation errors name the right field; create echoes; SDK types compile; events pass the replay predicate; fixtures match schema.

PR2 — Run now execution + hard guardrails + blocker tracking (Codex, backend)

Makes a run actually execute, triggered manually (runNow) — user present, so park is safe and ownership/timers are not yet in play. The agent tool stays hidden (it is unhidden in PR6, once automations are persisted and manageable); runNow is exercised via the SDK/API headlessly here.

• Run execution wrapper: fork a fiber that continues (automationSessionID) or starts a fresh session and runs the prompt; never the user's main chat.
• AutomationRunContext (with an explicit attendance field) threaded into SessionPrompt so ctx.ask/ctx.externalResult write awaiting_input + blocker directly and enforce attendance at one seam (D1). Includes the narrow Permission.ask onPending API — the one engine touch; risk + acceptance called out here. This engine seam is deliberately kept inside PR2, not split into its own PR — it is one small hook plus an attendance check, and the plan keeps the PR count minimal. ctx.externalResult records on entry, clears on resolve/dismiss/abort, and fails fast for unattended before ExternalResult.register; ctx.ask records only on onPending and clears in ensuring/onExit (not catchAll — ctx.ask is orDie).
• Hard guardrails (D3): real hard step-cap gate in the run loop; reuse abort for cancel; min-interval floor validation (reject 422, no coerce); per-automation single-writer.
• Verify: headless — runNow executes and records a run; a question-blocked and an ask-blocked run both show awaiting_input with the right blocker.kind; an allow permission is not mislabeled awaiting_input; a run whose model ignores MAX_STEPS is hard-stopped; abort stops a run; a question tool that Effect.dies on its duplicate-label guard (question.ts:118-141) before reaching the seam still terminalizes the run cleanly (the defect path is caught by the run loop, not left dangling).

PR3 — Scheduler timers + ownership + unattended policy (Codex, backend)

Background firing: one-shot + interval-after-completion. First unattended execution, so it owns the ownership + park-policy decisions. The agent tool stays hidden (unhidden in PR6); scheduled firing is exercised here via the SDK/API and the test clock — the agent self-schedule "check back in 10 min" (one-shot, continue, fires once) is the same path but only reachable by the model once the tool is unhidden in PR6.

• Scheduler.Service (Effect Layer) with per-definition timers, reschedule, cancel, a test clock, and next-fire computation.
• Single owner: the scheduler is not placed in the shared AppLayer where both serve and desktop would run it; it is started by one explicit owner (durable cross-window lock arrives in PR4). Do not let "fork into serve" become implicit.
• Unattended block policy (D1): PR3 only sets attendance = unattended on scheduled runs — the gate itself already lives in PR2's AutomationRunContext, so no new engine touch here. A parked run releases the global slot but keeps its automation's token, so the same automation can't overlap — the next due fire is skipped(previous_run_awaiting_input). question then fails fast (needs_user_input); permission ask parks.
• Rhythms: one-shot (fireAt) + interval-after-completion (run → sleep → run).
• Verify: headless (test clock) — one-shot fires once; interval is completion-anchored and never overlaps; while one run is parked, the next due fire is skipped with reason, not a second concurrent run.

PR4 — Persistence + cron + missed-skip + durable lock (Codex, backend)

Makes "daily 9am brief" survive restart; enables true durable park.

• Persist definitions + runs; scan due/missed on startup.
• cron rhythm; store the definition's creation timezone; nextFires preview.
• Missed = skip, no catch-up: record skipped with reason; "Run now" covers today.
• Reconcile stale awaiting_input runs on restart (D1): terminalize as expired.
• Durable cross-window lock enforcing the single owner across windows / serve + desktop so a fire happens once.
• Persisted implementations + restart behavior for update/pause/resume/delete (and the durable side of runNow, whose live execution already landed in PR2) against the PR1-frozen signatures; run-record retention (§5).
• Verify: headless — restart reloads definitions; cron next-fire correct across a tz boundary; missed window records skipped; a persisted parked run reconciles on restart.

PR5 — Execution location where + worktree (Codex, backend)

• Default live directory; isolated worktree for fresh runs only; non-git/non-code projects never offered it; same-project runs single-writer. Flip the contract's unsupported_where_worktree to supported.
• Verify: headless — fresh+worktree run executes isolated and cleans up; single-writer serializes two same-project runs.

PR6 — Sidebar "Automations" panel (Claude, frontend)

The first frontend PR; it builds against the SDK + fixtures PR1 froze and the backend PR2-5 shipped. It unhides the agent tool — safe now because automations are persisted (PR4), visible, and manageable, so a created automation can never silently vanish or sit unmanageable. It also does the app-side global-sync wiring (store/reducer + bootstrapDirectory automation.list) that §3 specifies as frontend work, including extending the monotonic-revision ignore-stale reducer (today session_todo only) to automation.*.updated.

• Sidebar "Automations" section: list, view, pause/resume, delete, Run now, per-run history (incl. skipped + why), failureStreak + notify-after-N.
• The awaiting_input badge is driven from the run ledger (AutomationRun.state + blocker), not the existing session-level pending marker (which reads sessionStore for current-directory chats and won't see an automation's own session) — reuse only the visual treatment.
• Follow docs/DESIGN.md (warm neutrals, orange accent only, dense, no emoji/gradient).
• Verify: E2E user-path (open panel → run now → see run in history → pause → delete) + bun run snap on a new/covering target; bun run dev:desktop if any platform.* / window.api / notification path is touched.

PR7 — Create-via-form + templates + NL confirmation card (Claude, frontend)

• Manual create form (title, prompt, project, schedule, context, stop); templates (Daily brief / Weekly review / Project monitor — kills the blank page).
• Confirmation card for NL creation: renders the resolved definition the tool returns as structured metadata.automationDefinition (frozen in PR1 with a typed fixture, not parsed from prose), plus any normalizationWarnings.
• Verify: E2E (form create → appears in panel; NL create → card echoes parsed fields; template → prefilled form) + snap; dev:desktop if Electron paths involved.

---

5. Open assumptions — proposed defaults

Numbers are tunable later, but the enums, return semantics, and accounting they imply are frozen in the PR1 contract.

Knob	Proposed default	Frozen at	Note
Hard step cap	finite (e.g. 50); hard gate, not soft	PR1 enum / PR2 impl	stopReason: "step_cap"
Min interval floor	e.g. 30s; reject (422 + field error), no silent coerce	PR1	agent self-schedule below the floor is rejected, not quietly bumped
Concurrency cap	1 per automation; small global (e.g. 3); parked run releases the global slot but keeps its automation token (no overlap)	PR1 / PR3	next due fire while parked → skipped(previous_run_awaiting_input)
stop = count accounting	only succeeded/failed consume count	PR1	same rule for condition
Unattended question	fails fast (needs_user_input) via the attendance gate	PR2 seam / PR3 sets flag	revisit when durable park + UI exist
Auto-expiry	e.g. 30 days unattended	PR4
Consecutive-failure notify	after 3 (failureStreak)	PR6	visible, never auto-pause
Run-record retention	keep last N (e.g. 50) or N days per automation	PR4
Delete-automation → runs/sessions	delete run ledger (tombstone); unlink, keep chat sessions	PR1 semantics / PR4 impl	affects PR6 delete UI
Initial templates	Daily brief / Weekly review / Project monitor	PR7

---

6. Sequencing

Strictly serial — merge each before opening the next:

PR1 → PR2 → PR3 → PR4 → PR5 → PR6 → PR7
└──────── Codex (backend) ───────┘   └─ Claude (frontend) ─┘

• PR1 is the foundation: it freezes the §3 contract, regenerates the SDK, and ships event fixtures. Everything downstream (including the frontend PRs, when their turn comes) builds against those stable types.
• PR2 vs PR3 split is deliberate: manual Run now (attended) proves execution + guardrails + blocker tracking before unattended firing introduces ownership and the park-deadlock risk.
• Each PR: targeted local verification (backend headless / frontend E2E + visual), broader suites left to CI. PR titles Conventional Commits; labels per AGENTS.md.

---

7. Explicit non-goals (carried from design)

No cloud / app-closed runs; no per-automation permission scope; no auto-pause on failure; no missed-run catch-up; no cross-restart persistence of pending approvals.

Known accepted risk (v1, YAGNI): with no per-automation permission scope and no creation gate, an agent-created automation inherits the project's existing allow/autoAccept rules and runs unattended on a schedule, so a prompt-injected create can amplify a one-time injection into recurring background actions. Accepted for now: unattended ask still parks (no silent approval), so the residual exposure is only project-level allow — the same permission model sub-agents/loops already inherit today. Revisit a creation gate (e.g. the create tool defaulting to ask) or per-automation scope only if this surfaces in practice; do not re-raise it as a new finding.