fix(app): scheduled processes added via project update now register with the scheduler and respect run_on_start

[makingaipractical]

Summary

Three closely related bugs in UpdateProject (CLI: process-compose project update, REST: POST /project) cause scheduled processes to misbehave when added, modified, or compared as part of a running-project update:

1. A new scheduled process added via project update fires IMMEDIATELY, ignoring run_on_start: false.
2. The same new scheduled process is never registered with the scheduler — next_run_time stays nil and the cron is silently dropped forever.
3. Changing only a scheduled process's cron/interval/run_on_start/timezone is detected as no-change by ProcessConfig.Compare, so the new schedule is silently ignored.

Live evidence from my setup (Mac, 16 daemons supervised, v1.110.0): I appended one scheduled-cron entry to the project YAML and ran process-compose project update -f <yaml>. The new entry fired immediately and got "orphaned" — next_run_time: null — so its 0 8 * * * cron would never have fired again until a full supervisor restart.

The bug

(1) Immediate fire on add — src/app/project_runner.go

UpdateProject routes new entries to addProcessAndRun:

func (p *ProjectRunner) addProcessAndRun(proc types.ProcessConfig) {
    ...
    p.initProcessLog(proc.ReplicaName)
    if !proc.IsDeferred() {
        p.runProcess(&proc)   // <-- unconditional spawn
    }
}

IsDeferred() returns true only for IsForeground || Disabled — it does not consider Schedule. The startup loop has the correct guard (lines 186-189) — addProcessAndRun is just missing the same one.

(2) Schedule orphaned — src/scheduler/scheduler.go + src/app/project_runner.go

processScheduler.AddProcess is called in exactly one place — the startup Run() loop at line 169. Neither UpdateProject, UpdateProcess, addProcessAndRun, StartProcess, nor RestartProcess register new entries with the scheduler. A scheduled process added at runtime is permanently orphaned from gocron.

Symmetrically, removeProcess never deregisters from the scheduler — there's no Scheduler.RemoveProcess method at all (only PauseProcess, which keeps the entry in s.schedules so ResumeProcess can re-arm it).

(3) Compare omits Schedule — src/types/process.go

ProcessConfig.Compare (lines 107-149) walks ~25 fields by direct compare or reflect.DeepEqual. Schedule is literally absent from the field list. The function predates scheduled processes (introduced in v1.87.0); the maintenance was never done.

If only Schedule.Cron changes between the running config and the new YAML, Compare returns true (equal) → UpdateProject classifies the process as up-to-date → the cron change is silently ignored.

The fix

Three minimal source changes + one new scheduler method:

src/scheduler/scheduler.go — add RemoveProcess (full removal, distinct from PauseProcess's preserve-for-resume semantics). Tolerates gocron.ErrJobNotFound (the underlying gocron job table is eventually-consistent against NewJob and may have already wiped the job on shutdown) and always cleans up the local tracking map:

func (s *Scheduler) RemoveProcess(name string) error {
    s.mutex.Lock()
    defer s.mutex.Unlock()
    entry, ok := s.schedules[name]
    if !ok { return nil }
    var err error
    if entry.Job != nil {
        if rmErr := s.gocronScheduler.RemoveJob(entry.Job.ID()); rmErr != nil && !errors.Is(rmErr, gocron.ErrJobNotFound) {
            err = rmErr
        }
        entry.Job = nil
    }
    delete(s.schedules, name)
    return err
}

src/app/project_runner.go — patch addProcessAndRun to route scheduled processes to Scheduler.AddProcess and skip runProcess. Mirrors the startup-loop semantics. Patch removeProcess to call Scheduler.RemoveProcess for full deregistration.

src/types/process.go — add !reflect.DeepEqual(p.Schedule, another.Schedule) to Compare's DeepEqual chain.

Why patching addProcessAndRun (rather than branching in each call site): the helper is called from both UpdateProject (new procs) and UpdateProcess (the remove-then-re-add path). Both call sites should treat scheduled processes the same way. One change in the helper covers both, and means future call sites get the right behavior for free.

Minimal reproduction

mkdir -p /tmp/pc-bug-1801 && cd /tmp/pc-bug-1801
cat > project.yaml <<'EOF'
version: "0.5"
processes:
  ticker:
    command: echo "ticker would fire"
    namespace: scheduled-cron
    schedule:
      cron: "0 8 * * *"
      run_on_start: false
EOF

cat > project-after.yaml <<'EOF'
version: "0.5"
processes:
  ticker:
    command: echo "ticker would fire"
    namespace: scheduled-cron
    schedule:
      cron: "0 8 * * *"
      run_on_start: false
  newcomer:
    command: echo "this should NOT fire on update"
    namespace: scheduled-cron
    schedule:
      cron: "0 0 1 1 *"
      run_on_start: false
EOF

# Terminal 1: start supervisor with the smaller config
process-compose up -f project.yaml --tui=false &
SUPERVISOR=$!
sleep 2

# Terminal 1: append a new scheduled entry via project update
process-compose project update -f project-after.yaml

# Before fix: newcomer fired immediately ("this should NOT fire on update")
#             AND curl localhost:8080/process/newcomer | jq .next_run_time → null
# After fix:  newcomer is silent
#             AND curl localhost:8080/process/newcomer | jq .next_run_time → "2027-01-01T00:00:00Z"

curl -s localhost:8080/process/newcomer | python3 -c "import sys,json; p=json.load(sys.stdin); print(f\"next_run_time: {p.get('next_run_time')}\")"

kill $SUPERVISOR

Before / After (real environment)

I run a 16-process supervisor on macOS. I added one scheduled-cron entry to the YAML and ran project update. Captured curl localhost:8080/processes:

Before fix (v1.110.0):

test-entry: status=Completed, pid=69358, process_start_time=2026-05-23T00:53:54.907+02:00, next_run_time=null

→ Fired immediately at the update moment, orphaned from scheduler.

After fix (this PR):

test-entry: status=Scheduled, pid=0, process_start_time=null, next_run_time=2027-01-01T00:00:00+01:00

→ Quiet, scheduler-registered, will fire at the configured time.

Tests

Three test surfaces lock in the fix:

• src/scheduler/scheduler_test.go — 4 cases for the new RemoveProcess (found, unknown, already-paused, gocron-shutdown-tolerance).
• src/types/process_test.go — 4 cases extending the table-driven TestCompareProcessConfigs: different cron, different run_on_start, nil-vs-set Schedule, identical schedules equal.
• src/app/system_test.go — TestUpdateProject_ScheduledProcess end-to-end through UpdateProject: add → schedule-change → remove. Separate from the existing TestUpdateProject so the pre-fix behavior assertion in that test stays untouched.

make testrace passes locally. make lint clean. make ci's build-nix step skipped (non-Nix host).

There's one pre-existing failure in TestBuildProcessEnvironment/PC_PROC_NAME + PC_REPLICA_NUM on main (unrelated to this change — environment-variable test, no scheduler involvement). Confirmed by running go test ./src/app/ -run TestBuildProcessEnvironment against unmodified main.

Why this fix vs. alternatives

• Branch in each call site instead of the helper. Considered. Would require duplicating the same logic in UpdateProject's new-procs loop and UpdateProcess's add-after-remove path. The helper is the canonical "add a process to the runtime" entry point — putting the schedule guard there means the next caller (e.g. a future scaling path) gets it for free.
• Skip the Compare fix and just let UpdateProcess's second compare catch it. UpdateProcess does call AssignProcessExecutableAndArgs before its own Compare, but UpdateProject classifies entries via Compare before dispatching to UpdateProcess — and Schedule-only changes never make it past the first classification. Compare needs to know about Schedule directly.
• Reuse PauseProcess instead of adding RemoveProcess. Pause keeps the entry in s.schedules so ResumeProcess can re-arm it. For a process being deleted from the project entirely, that's a leak — and a name collision risk if a later AddProcess reuses the same name. The two operations have distinct contracts.

Related

• fix(loader): persist user-supplied FileNames, not the extends-mutated slice #487 — recent loader-path correctness fix (fix(loader): persist user-supplied FileNames, not the extends-mutated slice). Same family of bug: state leak across reload. Cross-referencing as precedent — not a dependency.
• No-downtime rollout #299 (open) — "No-downtime rollout" feature request. This PR is bug-fix scope, not the rollout feature; it doesn't close No-downtime rollout #299 but it does remove one class of "downtime cause" (scheduled-process orphaning).
• chore(api): project update in not in HTTP api #381 (closed) — the PR that added project update to the HTTP API. The current PR exposes that endpoint's scheduled-process path was never wired up correctly.

I have one more open question — a separate bouncing issue I observed on the live supervisor where two pre-existing scheduled processes were classified as "Updated" on a project update against a structurally-identical YAML, causing a full pulsar-postgres restart. The source-level explanation (UpdateProject calling Compare before AssignProcessExecutableAndArgs while the in-memory copy is already assigned) doesn't quite match the code in loader.Load which already runs assignExecutableAndArgs before returning. I'm filing that separately as an issue with debug-log evidence; happy to follow up with another PR if you confirm the diagnosis.

Thanks for process-compose — it's been a quiet workhorse for a 16-daemon Mac supervisor setup of mine for the past few weeks.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[makingaipractical]

Closing — withdrawing this PR. Apologies for the noise.