Epic: approved schedules through the autonomous Queue #912

Outcome

A chat agent, or the user, can schedule agent work for later: a one-off ("on Monday at 08:00, re-check the forecast and update this note") or a recurring one ("every weekday at 07:00, triage the inbox"). Under approved Queue Execution A and bounded creation Authority A, with the remaining policy contracts settled through #913, the self-hosted server durably stores it, triggers due work under approved bounds, records the run in the activity record, and tells the user its actual result or failure. Storing, triggering, listing and cancelling schedules requires no vendor scheduling service or separate scheduler account. Executing a model-backed task still uses its configured agent backend and any ordinary inference authentication, network and billing requirements; offline inference is not promised. Scheduled work can be listed and cancelled from chat, the CLI and the PWA, and it runs the same on every chat backend.

Scope

Own Markdown schedule definitions, bounded creation authority, due-occurrence admission, correlation, chat tools and the approved Actions upcoming lens. Reuse #51’s execution path. #1658 journals changes to schedules; it does not implement scheduling or authorize altered definitions.

Why now

An agent in a chat session cannot defer work. When the user asks "check this again on Monday", the only options are:

• a session-only timer, which dies with the turn's process, or
• an external scheduler outside brain-kit's persisted state and operator controls. The local missing capability is sufficient evidence for this feature; no specific vendor scheduler availability or account requirement is asserted here.

The result is a passive fallback: setting next_review on a document so brain briefing lists it as overdue (packages/core/src/cli/commands/briefing.ts:255-263). Nothing runs. "Self-hosting is the model" (ROADMAP.md) means the deployment should be able to keep an appointment by itself.

Shared context

Most of the parts already exist. None of them is connected for this purpose:

• The Queue has a not-before state, but no generic scheduled-prompt creation path. The state machine has scheduled → ready | expired | dropped (packages/ui-server/src/inbox/state.ts:9). The lifecycle sweep promotes a due scheduled item to ready (packages/ui-server/src/inbox/actions.ts:188-189), and the table indexes wait_until (packages/ui-server/migrations/021_inbox.sql:46). But ingest() always creates type: "triage", status: "ready" (packages/ui-server/src/inbox/store.ts:548-549), and intake accepts only share | cli sources (packages/ui-server/src/inbox/intake.ts:16).
• An in-server tick already runs. The inbox runtime ticks every 60 s (packages/ui-server/src/inbox/runtime.ts:11), with leases, heartbeat and a loopback poke (ui-server: drain leased work with a recoverable internal poke #677).
• Production Queue dispatch is implemented but activation remains gated. feat(ui-server): wire the production Queue dispatcher behind the enablement gate #1539 (42296758) supplies createInboxDispatcher (packages/ui-server/src/inbox/dispatcher.ts:55) and test(ui-server): prove crash and restore recovery through the fixture host #1545 (edb97e1c) proves fixture-host crash/restore recovery. The runtime requires dispatch, budget and operation dependencies (dispatchEnabled, packages/ui-server/src/inbox/runtime.ts:56). createApp supplies them only through the unexported repository fixture symbol (const dispatchFixture, packages/ui-server/src/app.ts:448-460; createInboxDispatcher, same file:627-630); no config, environment variable or default enables autonomous dispatch. The headless-turn header now names the gated dispatcher (packages/ui-server/src/inbox/autonomous-turn.ts:1-5). This does not deliver scheduled-task dispatch: the schedule service still reports dispatch_disabled pending ui-server: run due scheduled tasks, record them as activity and notify the result #915/ui-server: enable autonomous dispatch in production behind a supported switch #1595 (createScheduleService, packages/ui-server/src/app.ts:658-669).
• Cron is static. The host crontab is generated at container start from hardcoded base jobs (packages/ui-server/src/cron/emit.ts:154-163) plus module-declared entries (packages/core/src/lib/module-types.ts:113-119). It has no runtime API. The crontab, not an in-process timer, owns scheduling (packages/ui-server/src/cron/scheduler.ts:8-12). One precedent matters: the nightly sync job already runs an agent headlessly from cron.
• Notifications only cover failure, completion or stuck runs (packages/ui-server/src/activity/notify.ts:29). Completion is opt-in per cron jobName (:162-165).
• Agent tools: the chat-UI tool set (mcp__brain-ui__*) is a stable contract (Chat-UI in-process tools, docs/integration-contract/mcp.md:222-236). New tools follow the query_activity path: the SDK contract (packages/ui-sdk/src/tool-contracts/bridge.ts:386), a BackendBridge handler, and registration in both backends (packages/ui-backend-claude/src/ask-user-tool.ts:138-140).

Constraints and non-goals

• No daemon (ROADMAP.md, "Deliberately not doing"), and no new transport seam (docs/decisions/async-collaboration.md:226-234). Use approved Execution A through the existing Queue runtime/tick and its recovery/backstop infrastructure; no independent cron/core-runner dispatcher owns the same occurrence. Template/operator integration belongs in the public hosting template when required, with no real deployment details in this repo.
• No vendor scheduler dependency for storing, triggering, listing or cancelling schedules. Ordinary inference dependencies remain those of the configured execution backend/runner.
• Every scheduled run is autonomous agent work. It must not open a side door around the containment, budget and admission gates of the async-collaboration design (Epic: restricted autonomous Queue execution and durable Actions #51, completed proof ui-server: verify the full async lifecycle before enabling autonomous dispatch #689 and activation gate ui-server: enable autonomous dispatch in production behind a supported switch #1595). Execution A and Budget A reuse those gates; neither ruling enables production dispatch.
• Not a general workflow engine: no task chains, no conditional triggers, no webhooks.
• Not reminders for unresolved Actions. ui-server: aggregate durable Action notices with explicit delivery policy #683 excludes those, and this epic doesn't revisit that.

Breakdown

1. ui-server: decide how a scheduled agent task runs while autonomous dispatch is gated #913 Decision record: approved Queue execution, bounded recurring authority, Budget A, Timing A and Delivery A, and Store B; deliver the durable record and matching technical contracts.
2. core: manage Markdown schedules through an authenticated host CLI #914 core/ui-server (delivered through CONTRACT: feat(core,ui-server): store scheduled tasks behind an authenticated host CLI #1009 and CONTRACT: feat(core,ui-server): admit schedule occurrences through the Queue and reconcile paused tasks #1045): a schedule store and brain schedule CLI (add | list | cancel | due, --json), one-off and cron-expression recurrence, time zone aware.
3. ui-server: run due scheduled tasks, record them as activity and notify the result #915 ui-server: run due schedules through the selected trigger/execution path, record them as activity, notify on result.
4. ui-sdk: give chat agents schedule_task, list and cancel tools on both backends #916 ui-sdk + backends: schedule_task, list_scheduled_tasks and cancel_scheduled_task chat tools on both backends.
5. ui-react: list and cancel scheduled tasks in the PWA #917 ui-react: list, inspect and cancel scheduled tasks in the PWA.

Approved policies and remaining deliverables

Execution A is selected: due occurrences use the existing Queue admission, authority, lifetime/budget and autonomous AgentBackend path. Existing runtime/tick and its recovery/backstop infrastructure own triggering; no direct core AgentRunner fallback or interim migration is approved. Production execution remains gated by #1595; #689 supplies completed system proof. See the recorded execution ruling on #913; it supplies the durable record after the remaining choices.

Authority A now also approves the exact recurring operation/tool/input/target/egress envelope at creation, with current revocation checks and durable checkpoint-and-unwind escalation for additional permission or answers. Creation is not an implicit blanket grant; changed scope requires a newly approved schedule. Budget A now selects a 10-minute host deadline per admitted attempt and at most three model-bearing operations per occurrence, counting retries/yields/compaction/continuations across restart or new Queue items. Scheduled work consumes existing shared operator-configured daily autonomous operation/spend caps; zero/absent remains disabled, with conservative reservation and unknown-usage accounting. Timing A now selects at most one outstanding/latest-missed catch-up within 24 hours, no overlap, due-based 24-hour occurrence freshness, future/unstarted-only schedule cancellation, distinct live-stop behavior and unknown-effect investigation. It also settles explicit/client/UTC zone precedence, offset-based future one-offs and DST skip-gap/first-fold-once rules. Delivery A now keeps success alerts opt-in per schedule, with authenticated Activity/schedule results, existing failure/stuck/Action paths, occurrence-correlated completion intents, origin autonomous, generic minimized push and existing suppression/retry/permission behavior. No unsolicited Chat insertion is approved. Store B now makes dedicated brain-root-contained Markdown files authoritative for definitions, with approved fingerprints, claims/occurrences/receipts/authority in the existing UI operational database. All supported CLI/chat/PWA consumers use the authenticated host, and edited/restored definitions require matching approval/reconciliation before dispatch. #913 delivers the durable record and technical consumer examples under these settled policies; the remaining UI judgment belongs to #917. #917 owns the list/cancel interaction design within existing D37 destinations. All six policy choices are settled; remove needs: decision. The epic remains open for its native children and is never coded directly. No creation-time blanket grant is approved. Bounded catch-up is approved under Timing A; Delivery A selects success alerts opt-in; no default-on success alerts are approved. The separate core-runner execution alternative is rejected. Preserve the full-v1 autonomous gate in docs/decisions/async-collaboration.md and #689. Completion evidence is the dated ruling/durable record plus reconciled children and the approved UI design; their implementation/system receipts are then required by the definition of done.

Definition of done

• A one-off task scheduled from chat, and a recurring task scheduled from the CLI, both run at their due time on a deployment with no network path to any vendor scheduler. This is proven by an integration test with a fake clock and by a manual check on a running host.
• Each run appears in query_activity with its schedule/occurrence identity and actual outcome. A durable result intent follows the chosen delivery policy; suppression, denied push permission or unavailable push never reads as successful delivery. The in-app record remains usable and push payloads minimize task data.
• docs/integration-contract.md documents the chosen CLI --json/exit shapes, tool names, list/cancel HTTP behavior and activity/notification correlation. Runtime tests cover both actual backend boundaries, admission/revocation, downtime, cancellation races, concurrency, DST and restart recovery without claiming exactly-once arbitrary external effects. No production autonomous execution is enabled before the existing required proof.

2026-10-03 triage: Source inspected at main 1d1fcc72a7e06352e8b5ee020b3910864babc5db, Bun 1.3.14. A bounded keyless probe of the real inbox runtime with one nonempty ready item, a configured budget and operation description, fake timers and no dispatcher returns claimed: 0, dispatchEnabled: false; the item remains ready with zero attempts and there are zero activity spans. Calling the real runAgent with a scripted runner forwards only cwd and onRuntime and completes the fictional prompt. These observations establish existing mechanics, not schedule execution or runtime containment proof. No vendor inference, account change or host action was performed. Baseline verification: bun run test packages/ui-server/tests/inbox-runtime.test.ts -t "unwired production runtime leaves nonempty ready work unclaimed" passed (1 test, 3 assertions, 17 filtered out). This is evidence for the current disabled-dispatch behavior only. Clarified local scheduling versus inference dependencies and the unselected trigger path; the five native children #913–#917 are already attached. priority: p2 denotes wanted unscheduled work; needs: decision keeps the architecture/authority choice explicit, with UI design owned by #917.

2026-10-04 maintainer execution reconciliation: selected Execution A on #912/#913 and folded the single Queue execution branch into this brief. Independent cron/core-runner execution and interim migration are rejected; production enablement still waits for #689. Authority, budgets, timing/recovery, delivery and store/consumer contracts remain unresolved; preserve needs: decision, existing blockers and any design need, without readiness or a release commitment.

2026-10-04 maintainer authority reconciliation: selected Authority A on #912/#913, including explicit operator approval of the recurring operation/tool/input/target/egress envelope, immutable scope with current revocation/expiry checks, authentic creator provenance and durable Action/checkpoint/unwind for additional needs. Folded that ruling into this brief and required negative/continuation controls where applicable. Budgets, timing/recovery, delivery and store/consumer contracts remain open; preserve needs: decision, blockers and any design need without readiness, enablement or a release commitment.

2026-10-04 maintainer budget reconciliation: selected Budget A on #912/#913, including 10-minute host deadlines per admitted attempt, three model-bearing operations per occurrence across retry/yield/compaction/continuation/new Queue items, persistent counters, shared configured daily autonomous caps and conservative accounting/unwind. This does not enable admission or promise a provider invoice ceiling. Timing/recovery, delivery and store/consumer contracts remain open; preserve needs: decision, blockers and design needs without readiness or a release commitment.

2026-10-04 maintainer timing reconciliation: selected Timing A on #912/#913 including latest/single catch-up within 24 hours, one outstanding occurrence/no overlap, original-due 24-hour freshness including human wait, future/unstarted-only schedule cancellation with distinct live-stop behavior, unknown-effect investigation and explicit/client/UTC zone, future offset one-off and skip-gap/first-fold-once DST rules. Folded these policies into the brief; delivery and store/consumer contracts remain open. Preserve needs: decision, blockers/design needs and #689 without readiness, enablement or a release commitment.

2026-10-04 maintainer delivery reconciliation: selected Delivery A on #912/#913: per-schedule success alerts opt-in, authenticated Activity/schedule results, existing failure/stuck/Actions/completion paths, origin autonomous plus occurrence correlation, generic minimized push and existing suppression/retry/permission honesty. No unsolicited Chat insertion/new service is approved. The final authoritative definition-store/CLI boundary remains open; preserve needs: decision, blockers/design needs and #689 without readiness, enablement or a release commitment.

2026-10-04 maintainer final storage reconciliation: selected Store B on #912/#913: root-contained Markdown definitions plus the existing UI approval/runtime ledger, canonical approved-fingerprint validation, durable file/DB compensation, one authenticated host-backed CLI/chat/PWA path, read-only due, idempotent retained create/cancel history and coordinated Git/operational restore. All six policy questions are settled; removed needs: decision. Keep actual record/implementation/design/proof dependencies without claiming completed work, production enablement or a release commitment.

Current record delivery and dependency state — 2026-10-04

#913 is complete: #980 merged as 38f3c10a3947b9b00574cc9123a0e64d1a1022ed, with thirteen executed current-head/live-base Depot checks, matching squash parent/tested tree/main ancestry and all twelve automatic main-push jobs verified. The durable record and future consumer contracts supply the selected specification. These are design/contract preparation, not shipped schedule commands or enabled execution.

The parent outcome remains open. #913’s record and #914’s authenticated store/CLI plus admission/reconciliation proof are delivered. #915–#917 retain production trigger/correlation, chat tools and PWA interaction/implementation. #689 is completed system proof; #1595 owns the independent production-execution gate and retains its public hosting-template prerequisite.

Earlier dated reconciliation notes record policy selection and dependency state at that time. The delivery state above supersedes their pending-record language; the original implementation scope and acceptance criteria are unchanged.

2026-10-07 delivery reconciliation: #914’s completion receipt records #1045 (7719bca8cf057cc485c1923cf5f075b273fcf091) delivering the remaining runtime admission fixture and operator reconciliation after #1009. The private admission helper is not production-wired; it does not complete #915 or lift production activation, now owned by #1595; #689 is completed proof. The fully paginated native list leaves #915–#917 open. Earlier pending-store/record language is historical. No enabled scheduler or running-host check is claimed.

2026-10-07 source reconciliation at main 86ca7f2408993113f3cba4287b7a01846a8b26ee: refreshed the named current-source anchors. Historical measurement/implementation receipts retain their original provenance; no new design or runtime completion is inferred.

2026-10-09 triage at main 9857f6f4c71151240e3c40fc88e4e3157477bcb7: verified and refreshed the moved Chat-UI in-process tool-contract anchor after the additive UI contract sections. Existing scheduling policies, native children and incomplete deliverables are unchanged.

2026-10-09 triage at main 23599e2207aceb4c795298d1d64dfe8b8eabc51c: refreshed the named Chat-UI in-process tools contract anchor after the additive UI-export section moved the document. Scheduled-task scope and existing child prerequisites remain unchanged.

2026-10-09 triage: #1409’s subsequently landed additive AppErrorBoundary contract section moves the named Chat-UI in-process tools anchor to 1330 at supplementary main 8327d47f76cd498b36c7533a77474f59051290f6. Refreshed that active pointer; the prior dated inspection and scheduled-task scope remain unchanged.

2026-10-10 triage at main aed59874d5c0bb7ab55928b904db8d2d0dc0e3e6: refreshed the named Chat-UI in-process tools anchor after travel contract additions moved it. Scheduled-task scope and child prerequisites are unchanged.

2026-10-10 citation reconciliation at main bae10edcf450a4b440cba3fdd2316d4724a75f90: refreshed the Chat-UI tool-contract and production-dispatch gate anchors after #1363 moved them. No scheduled-task policy or implementation completion changed.

2026-10-10 triage at main 7e398dc207f2c4725f6c364331c3cd5d3112954d: refreshed the named Chat-UI in-process tool-contract anchor after landed additive sections. Scheduling choices/native children and incomplete enablement proof are unchanged.

2026-10-10 citation review at main 2274b9e01df9e2de5438fd1c76571c9c8b059a72: refreshed the named Chat-UI in-process tool-contract range after the additive native-button section. No scheduling choice, child scope or readiness changed.

2026-10-10 citation review at main 17a6f84ad5b9029961c5225414b66e82edab3328: refreshed the named in-process tool-contract and activity registration anchors after hosted mask/worker additions. Scheduling specification, child scope and readiness are unchanged.

2026-10-10 triage at main a1e007c473cde021a472917a66fe56ec531a3cd8: refreshed named current-source pointers after the coordinator/control/demo deliveries. Original immutable failure receipts, unresolved prerequisites and approved behavior remain; source inspection supplies no new runtime or CI completion proof.

2026-10-10 triage at main e632b50b693448146dc26e92f8e2e7211b1e8e3d: refreshed the in-process-tool contract anchor after the Pi worker addition. Execution A and existing scheduling/authority boundaries are unchanged; this is source inspection, not a new dispatch or runtime result.

2026-10-10 source correction at main 810af03d6609e9c32762a6e352a9968adb614857: refreshed the named scheduled Queue promotion anchor after current merges. Source inspection only; existing prerequisites, runtime evidence and missing proof remain unchanged.

2026-10-10 source correction at main a9a3376fa68f98233931f6d963af99bb43db81e3: refreshed the named Chat-UI in-process tool contract anchor after the packaged-card/pack-job merges. Existing scope and prerequisite evidence remain unchanged; source inspection is not new runtime verification.

2026-10-10 triage at main 0fff240b6167390276e141ff9aaf06e927289ea2: Pointed the stable in-process tool contract at its authoritative split component; policy and schemas are unchanged.

2026-10-10 triage at main 0fff240b6167390276e141ff9aaf06e927289ea2: Refreshed the existing no-daemon/transport-seam paragraph after containment amendments; scheduled work gains no second dispatcher.

2026-10-10 source correction at main f1aa4c2c7a2d2fa87f669e6a8bdd9fdc71e0f41b: refreshed moved source anchors after the durable inbox bridge addition. Existing scope, prerequisites and immutable runtime receipts remain unchanged; source inspection supplies no new runtime proof.

2026-10-11 source reconciliation at main 8c4b2411df64a8cf8c2dfa05d7757c2509c74f13: replaced the stale no-dispatcher context with the delivered gated Queue engine and its fixture-only activation. Scheduling still requires its own integration and approved authority/budget/timing semantics. Recorded PR proof is attributed evidence; no new runtime, enabled dispatch or complete scheduling outcome is claimed.

2026-10-11 citation correction at main 9f0df4959887b2b549d628010a8e2af1e5c1bfff: refreshed the named runtime activation anchor after the internal cleanup-crash fixture hook. Scheduling integration and disabled production activation remain unchanged.

2026-10-11 citation correction at main b65b960e71d4e13f82f5cef98b21f6773459f3ad: refreshed the due scheduled-item promotion anchor after notification-policy changes. Scheduled-task integration and autonomous activation gates remain unchanged.

2026-10-11 citation reconciliation at main 62085604026ed3849aa818081185f17c9b0808ea: refreshed the no-new-daemon/transport paragraph after checkpoint-budget documentation moved it. Existing scheduling specification, dependencies and disabled execution are unchanged.

2026-10-12 current-source pointer reconciliation at 6f74aaa19d6707db95401649113e65c47787b27a: refreshed dispatchFixture after the governance additions. Production activation and scheduled-task authority/integration remain separate and unchanged.

Updated 2026-10-12: applied the approved epic scope/ownership clarification; preserved detailed outcomes, criteria, exclusions, decision links and recorded rulings.

Updated 2026-10-12: completed the active scheduling-specification correction: #689 is delivered proof and #1595 owns activation; historical rulings and approved schedule semantics remain intact.

2026-10-12 maintenance-delivery citation review: refreshed actual fixture/dispatcher/storage-only anchors at inspected main. Completed #689 proof remains distinct from #1595 production activation; no scheduled dispatch is enabled by these deliveries.

2026-10-13 source reconciliation at main 857ab01d1f9cb591f928755f5be516ab7f73338e: refreshed named current-source anchors after governed-flow integration. Historical receipts, scope and remaining prerequisites are unchanged; source inspection supplies no new runtime proof.

2026-10-14 source reconciliation at main 4af7b2f20a43d23260c2ee5e3bac3896aee971bd: verified and refreshed the active named source anchors after #1793. Historical receipts remain historical; native storage delivery does not complete the other child outcomes, enable autonomous/scheduled dispatch or establish new runtime proof in this triage.

2026-10-14 triage at main 27a368b6ed7c8e80b33613da0c33af6776d74f75: Refreshed the named chat-UI tools contract anchor. Scheduled-task authority, native children and activation prerequisites are unchanged; no scheduled dispatch is enabled.

2026-10-16 triage at main 8822aedeeac8b824bafe120c20a9b58c4cd1f4e6: refreshed the query_activity registration anchor. Interactive schema membership is now stable under #2048/#2073; permission and handler availability remain call-time checks. This supplies no scheduled dispatch or activation evidence.

2026-10-16 triage at main 80e028d84b7686d6cf864d8166029b1142de8756: corrected the module cron declaration anchor after renderer metadata additions. The fixture-only dispatcher and schedule activation gates remain; no scheduled execution is claimed.

2026-10-16 triage at main 7d1a31d09b96739a85bff5151cc2e1300c9ac4d0: refreshed the query_activity registration anchor after cache-evidence instrumentation. Dispatch/schedule activation remains gated; no new scheduled runtime proof is supplied.

2026-10-16 triage at main 4ba792473152c89eb74c286fc914e54ca1dae8fc: refreshed the fixture-only dispatcher anchor; scheduled/autonomous activation is still gated and no appointment execution is inferred.

2026-10-21 source reconciliation at main c2f080f20a31224a1eeccde321c574292eaedb02: refreshed the named Queue promotion/intake, fixture-only dispatcher and storage-only schedule-service anchors. All six scheduling rulings and native #915–#917 deliverables remain unchanged; inspected source still supplies no production activation or running-host qualification.

2026-10-22 triage at main ca8842828ed8634a84c4e8aa4a88e487238721b4: refreshed verified current-source pointers by their named anchors. Scope, recorded decisions and remaining prerequisites are unchanged; source inspection supplies no new runtime or epic-completion evidence.

2026-10-22 source audit at a310317: repaired the moved dispatchFixture (434-446), createInboxDispatcher (610-613) and storage-only schedule-service (638-653) anchors. The native list still leaves #915–#917 open, and #1595 remains the separate production-activation gate. All six recorded scheduling policies remain settled; no dispatch is enabled, new runtime is run or epic completion is inferred.

2026-10-22 source navigation at main 2ba99c607dec41f95be5901fc8f309611806ceb5: verified fixture-only autonomous dispatch and storage-only schedule construction and refreshed its moved active anchors after #2464. Historical source-bound receipts, scope, decisions, labels and remaining prerequisites are unchanged; no new execution or activation is claimed.

2026-10-22 source navigation at main aeaaf7794b6be41fde4e01bef78ce3f1a5828ac6: verified and refreshed the moved active app-construction citation(s) after #2397. Historical source-bound receipts, scope, decisions and prerequisites are unchanged; no new runtime, activation or epic-completion evidence is claimed.

2026-10-23 source navigation at main f3c6fdc9f9c6321fda5a384cf8cfd8bf2e4846da: verified and refreshed moved active app-construction anchors after reference-source composition. Historical source-bound receipts, scope, decisions and prerequisites remain unchanged; no new runtime, autonomous activation or epic completion is claimed.