feat: add depends_on condition: completed for one-off programs

[ademidoff]

Closes #25.

started waits for the process, healthy waits for readiness. Neither expresses "wait for the work to finish", which is what a migration, an init task or a seed job is depended on for. This adds the third condition.

programs:
  migrate:
    command: /usr/bin/migrate --up
    autorestart: never

  api:
    command: /usr/bin/api
    depends_on:
      migrate:
        condition: completed

Semantics

As proposed in the issue:

• Satisfied by exit status 0, which is the same line autorestart: unexpected draws.
• Latched, for the daemon's lifetime. The condition stays satisfied while the task sits in EXITED, which is what the current behaviour gets wrong.
• Cleared when the program runs again, so sctl restart migrate re-runs the work and latches again on success. Dependents already up are left alone.
• A task that cannot complete drives its dependents to the existing "will never come up" path rather than an indefinite wait.
• Reload replacing the task clears the latch and runs the new definition; dependents already running stay running.

One decision the issue did not cover: sctl stop on a completed task does not clear the latch. Stopping a program that has already exited does not undo the work it did.

Implementation

The latch lives on Process (internal/process/process.go), set in the monitor when a run nobody asked to stop exits 0, cleared in Start(). It is set before the EXITED state change, because that change is what wakes the dependents — setting it afterwards would have them look and find nothing. Reload replaces the Process, so the latch clears there without any extra bookkeeping.

blockedByDependency (internal/server/reconcile.go) became condition-aware, which it could not be while it walked the dependency graph: the graph carries ordering, the config carries conditions. It now also treats an unsuccessful exit under autorestart: never as final, which is the second way a task fails to complete — FATAL was already covered.

Validation rejects autorestart: always on a program something waits to complete, naming both programs. autorestart: unexpected is the natural pairing and is accepted.

Two pre-existing waits this had to fix

Both are reachable today with any one-off, and sctl restart migrate — which the issue requires to re-run and re-latch — hits both:

• StopProcess waited for STOPPED specifically. The reconciler deliberately leaves EXITED alone, so stopping a program that had already exited timed out after 30s.
• StartProcess waited for RUNNING. A task that finishes inside startsecs never reaches it, so a successful run was reported as a failure after 30s.

StopProcess now accepts any settled state, and StartProcess accepts a completed run. Both are covered by tests that measure the elapsed time, so a regression shows up as a timeout rather than as a slow pass.

Tests

Unit tests cover the four cases the issue lists, plus the latch's placement relative to the state change, a failed exit not latching, and the two waits above.

probes/completed-latch.sh runs the whole shape in a container. --started is the control, and reproduces both of today's failures:

t=2s  migrate=RUNNING  api=RUNNING     <- ran alongside the task, not after it
t=5s  migrate=EXITED   api=RUNNING

  sctl stop api ... ok
  sctl start api ... REFUSED (30s)     <- and now it cannot come back

Why api is not running: dependency migrate is EXITED

against the same configuration with condition: completed:

t=4s  migrate=RUNNING  api=STOPPED     <- did not start alongside the work
t=5s  migrate=EXITED   api=RUNNING     <- started once the work was done

  sctl stop api ... ok
  sctl start api ... ok (1s)           <- the completion outlived the run

Documentation

README.md gains a Waiting for a one-off to finish subsection under Dependency Management, and the Best practices section from #10 is rewritten: it told people not to do this, and now points at the supported way of doing it.