openchamber/packages/web/server/lib/scheduled-tasks/DOCUMENTATION.md

Scheduled Tasks module

Server-owned scheduled task runtime and routes for OpenChamber-only automation.

Scope

• Per-project scheduled task persistence is owned by packages/web/server/lib/projects/project-config.js.
• Markdown loop discovery/parsing is owned by packages/web/server/lib/scheduled-tasks/loops.js.
• Runtime orchestration and execution is owned by packages/web/server/lib/scheduled-tasks/runtime.js.
• This module is OpenChamber feature logic; it is intentionally separate from OpenCode proxy/runtime internals.

Cross-instance occurrence claiming

Multiple OpenChamber server processes can share the same on-disk project config (for example CLI serve on port 3000 and the Electron desktop server on port 57123). Each process keeps its own timers, so without coordination a daily (or weekly / cron / once) slot would dispatch twice.

Before a scheduled run creates a session, the runtime claims the occurrence in shared project config under the project write lock:

• Writes state.lastScheduledFor to the armed nextRunAt timestamp and advances state.nextRunAt to the following occurrence.
• A second instance that loses the claim skips session creation and reschedules from the winner's persisted nextRunAt.
• Project config writes also take a cross-process .json.lock file so the read-modify-write is serialized across processes, not only within one process.
• The sharing processes may run different OpenChamber versions. Normalization keeps only the fields a build knows, so every writer persists tasks it did not change verbatim from disk and swaps only state onto a task whose state it updated; a task goes out normalized only when it was deliberately replaced (upsert, loop adoption). An older server touching the file after a run therefore cannot strip fields a newer build added, such as a task's goal or auto-accept settings.
• Lock timeout / filesystem errors on claim, manual-start, or completion state writes always release the in-process running slot (via finally) and best-effort re-arm the next future occurrence; they must not leave the task permanently "running" or reject unhandled from the queue pump.
• Project write locks release the in-process promise chain even when acquireProjectFileLock times out, so a later write for the same project can proceed after the on-disk lock is cleared (a hung chain would permanently wedge every mutating API and strand runTask before its finally).
• Re-arm helpers only schedule a persisted nextRunAt when it is still in the future. A past slot (common for once after claim, which cannot advance nextRunAt) falls back to computeNextRunAt — which returns null for a consumed/past once occurrence — so a losing instance stops instead of spinning delay-0 timers against the project lock.
• On claim lock/fs failure, best-effort persist lastStatus: error + lastError when nobody else claimed the occurrence, so a past once task is not left enabled-but-inert with only a warn log. Recurring schedules still re-arm the next slot.
• On completion-write failure after a session already ran, in-memory status is set to a terminal value and a single persist retry is attempted so lastStatus does not stay running. Manual runNow still returns the sessionID as a successful dispatch (ok follows run status, with persistError set) rather than a hard 500; the run API and Scheduled Tasks UI surface persistError as a warning toast.
• The claim predicate rejects a duplicate solely via lastScheduledFor within slack of this occurrence. It does not consult advanced on-disk nextRunAt (that field is routinely overwritten by a second instance syncing inside TASK_DUE_SLACK_MS, including on later days when lastScheduledFor is already set from a prior claim).
• Claiming always writes nextRunAt (including undefined) so a past once-slot is cleared when there is no following occurrence.

Manual runNow does not claim a schedule occurrence.

Files

• packages/web/server/lib/scheduled-tasks/runtime.js

  • Next-run computation (daily/weekly/cron compatibility)
  • Timer scheduling and queueing
  • Concurrency controls
  • Session create + prompt_async execution
  • Emits OpenChamber task-run events

• packages/web/server/lib/scheduled-tasks/loops.js

  • Discovery of .agents/loops/*.md (project scope, ancestors up to the worktree root) and ~/.agents/loops/*.md (user scope)
  • Frontmatter parsing into scheduled-task definitions
  • syncProject reconciles discovered loops with the persisted task list on every project sync (startup, task list load, task save/delete)

• packages/web/server/lib/scheduled-tasks/routes.js

  • Scheduled task CRUD endpoints
  • Listing tasks reconciles loop files first, so opening the Scheduled Tasks UI discovers file additions, edits, and removals without a server restart
  • Loop-file endpoints toggle enabled in frontmatter or delete the authoritative markdown file, then reconcile the project
  • Manual run endpoint
  • OpenChamber events SSE stream endpoint

Loop file format

Portable, git-commit-able scheduled-task definitions:

---
name: daily-digest
schedule: "0 9 * * *"
enabled: true
model: anthropic/claude-sonnet-4-5
agent: plan
timezone: Europe/Kyiv
---
Summarize repository changes since yesterday.

Field mapping (model: packages/ui/src/lib/scheduledTasksApi.ts):

Frontmatter	Task field
name	name (required, max 80 characters — longer names are rejected as malformed)
schedule	schedule.kind: "cron" + schedule.cron (required, cron-only in the portable format)
enabled	enabled (default false — a loop only runs when the file explicitly enables it; add enabled: true to activate)
model	split on the first / into execution.providerID / execution.modelID (required)
agent	execution.agent (optional)
timezone	schedule.timezone (optional, IANA; defaults to the server zone)
body	execution.prompt (required)

thinking_level and goalEnabled/goalTokenBudget are not part of the portable format (UI/JSON-only today); daily/weekly/once schedules remain UI/JSON-only. Runtime state (lastRunAt, nextRunAt, lastStatus, lastError, lastSessionId, lastDurationMs) is never written to the markdown file — it continues to live in the project config state store.

Loop reconciliation rules

projectConfigRuntime.reconcileLoopTasks(projectID, loops) runs inside the project write lock on every syncProject when the project path is known:

• Identity. For loop-owned tasks (carrying the loopFile marker) identity is the loop file path: a loop takes its task over regardless of the task's current name, so renaming the loop (the name field, or a UI rename) renames the task in place instead of leaving a stale duplicate behind. A loop whose name matches a JSON task (no loopFile) takes that task over instead: its schedule/execution/enabled are overwritten from the file while the task's id and runtime state are preserved (markdown wins on conflict).
• UI-only fields survive adoption. Execution fields the file format does not define (goalEnabled, goalTokenBudget, permissionAutoAccept, variant) are preserved from the task when a loop adopts it; only fields the file defines are re-applied.
• Deletion. A task carrying the loopFile marker whose loop file is no longer discovered (removed or renamed) is unscheduled (removed from the config). The marker is persisted in the config file, so removal is detected across restarts. JSON-configured tasks without the marker are never removed. A task whose loop file still exists but is currently unparseable is KEPT with its last good definition — a transiently malformed file (mid-edit, bad merge) never deletes a task or its runtime state.
• Creation. Loops without a matching task are created under a deterministic loop:<scope>:<name> id so runtime state survives restarts. At most one task is driven per loop file; orphan duplicates of the same file are unscheduled.
• Scope precedence. Project-scope loops shadow user-scope loops with the same name; among project files the nearest ancestor wins.
• Malformed files (missing name/schedule/model/body, invalid cron, unreadable) are reported to the scheduler as definition: null entries and warned about; they never block valid loops in the same or other scopes.
• Loop-file mutations. The loop file remains authoritative. The scheduled- tasks UI opens it in the built-in file editor, updates its enabled frontmatter through the loop-file endpoint, and deletes the file through the loop-file endpoint after confirmation. Each mutation reconciles the project. The general task deletion API still rejects loop-sourced tasks while their file exists; once the file is gone, deleting an orphan task is allowed.

Public exports (runtime.js)

• createScheduledTasksRuntime(dependencies)
• Returned API:
  • start()
  • stop()
  • syncAllProjects()
  • syncProject(projectId)
  • runNow(projectId, taskId)

Public exports (routes.js)

• registerScheduledTaskRoutes(app, dependencies)
• Registers:
  • GET /api/projects/:projectId/scheduled-tasks
  • PUT /api/projects/:projectId/scheduled-tasks
  • DELETE /api/projects/:projectId/scheduled-tasks/:taskId
  • PATCH /api/projects/:projectId/scheduled-tasks/:taskId/loop-file
  • DELETE /api/projects/:projectId/scheduled-tasks/:taskId/loop-file
  • POST /api/projects/:projectId/scheduled-tasks/:taskId/run
  • GET /api/openchamber/scheduled-tasks/status
  • GET /api/openchamber/events