feat: self-update of master and agents (#15)

README.md

@@ -18,7 +18,8 @@ Clicking *Update* on a service re-pulls the service's **current tag** (`repo:tag
 agent asks its Docker daemon for the tag's digest and deploys `repo:tag@digest`, so what
 runs is exactly what was pulled. The log streams to the browser while it runs; job
 history is kept in Postgres. A service without a tag (`repo@digest`), a plain container,
-and the updater's own services cannot be updated, and the UI says why. A bare image
+and a Swarm agent's own service cannot be updated, and the UI says why (see
+[Self-update](#self-update) for the master and Compose agents). A bare image
 (`image: postgres`, no tag and no digest) counts as `postgres:latest`; only a reference
 with a digest and no tag (`repo@sha256:...`) "follows no tag". Compose services with a
 `build:` section are shown but never updated ("built from source (build:)"). One update at
@@ -73,8 +74,8 @@ one that has been pushed. Compose services get pinned to it through
 already follows (a bare image counts as `:latest`); a service that follows no tag
 (`repo@digest`) is then not touched and is reported as `refused` ("no tag given and the
 service follows no tag"), manual or auto.
-With a `tag`, the "follows no tag" refusal does not apply; the other refusals (the
-updater's own services, `build:` services, plain containers) still do.
+With a `tag`, the "follows no tag" refusal does not apply; the other refusals (`build:`
+services, plain containers, a Swarm agent's own service) still do.
 
 Response (`200` or `500`):
 
@@ -111,8 +112,8 @@ is refused with its reason, in auto mode too, until someone restores or accepts
 
 The webhook never creates services: the first deployment of a stack is done by hand. A
 new service always starts in **manual** mode; switch it with the *Make auto* button on the
-overview or the service page. Auto is refused for the updater's own services, `build:`
-services and plain containers.
+overview or the service page. Auto is refused for `build:` services, plain containers and
+a Swarm agent's own service.
 
 > **Warning:** auto mode deploys whatever CI pushes, without anyone looking at it. Using
 > it on critical services is your own risk.
@@ -145,8 +146,7 @@ multi-arch image the digest is the index digest, the same one `docker inspect` s
   digest was found, the next cycle tries again.
 - **What is not polled.** Services that follow no tag (`repo@digest`), `build:` services, and
   services without a registry digest (locally built images). The service page says which.
-  The updater's own services and plain containers are polled, so their badge works, but
-  jobs for them are still refused.
+  Plain containers are polled, so their badge works, but jobs for them are refused.
 - **Errors.** A failed lookup is stored for the services that follow that tag and shown as a
   "poll failed" badge on the overview and in the "Polling" row of the service page; other
   tags continue. A later success clears it.
@@ -276,6 +276,33 @@ Read-only mounts and mounts whose source differs from the destination are refuse
 clear message. On Docker Desktop and OrbStack bind sources are translated host paths, so
 Compose jobs fail there; that is a development-only limitation.
 
+## Self-update
+
+The master's own Compose service and each Compose agent's own service are updated like
+any other service; the overview marks the agent's row "This agent".
+
+- **Master.** The agent on the master's host runs the job. The `up -d` recreates the
+  master, which ends the connection and any webhook request that waits for the job. The
+  agent keeps the result and sends it again when the new master is up, so the job is
+  recorded as finished. A client that waited gets an error and has to look at the job
+  afterwards.
+- **Agent.** `up -d` would stop the agent that runs it, so the agent starts a short-lived
+  helper container from its own image (same mounts) and the helper runs `docker compose
+  up -d <service>`. The helper carries `se.shcizo.package-updater.self-update.*` labels
+  with the job ID, the pinned ref and the output so far. When the new agent starts it
+  finds the helper by those labels, waits for it, adds its logs to the job output, removes
+  it and reports the result under the old job ID. The old agent reports nothing after it
+  is stopped.
+- **Requirements.** The agent's own stack directory has to be mounted read-write at the
+  same path (see below), like any stack it updates, and the agent must speak protocol 4
+  (`agent too old to update itself` otherwise). The master and the agent need to be
+  upgraded to a version with protocol 4 by hand once.
+- **Order.** A job for an agent's own service runs after every other queued job on that
+  agent. A master and an agent on the same host share an image, so one push starts both
+  jobs, and the master's job has to finish before the agent replaces itself.
+- **Swarm.** An agent's own Swarm service is refused: the agent cannot update the service
+  it runs in.
+
 ## How Compose updates work, and their limits
 
 The agent never edits your files. It writes one file next to the stack's base file,