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

docs/superpowers/specs/2026-10-12-master-agent-design.md

@@ -229,13 +229,40 @@ Online/offline is held in memory only.
 | Master restarts mid-job | Jobs in `running` are reconciled when the agent reconnects; jobs the agent does not know are marked `failed` ("lost"). |
 | New trigger while a job for the same service is queued or running | No new job; only `available_*` is updated. Two jobs never race on one service. |
 | Job exceeds `UPDATE_TIMEOUT` | The agent cancels it, as today. |
+| Agent updates itself | The old agent runs `up -d` in a helper container and waits. When the helper recreates the agent, the old agent is stopped and records nothing. The new agent finds the helper by its labels before it connects, so its hello lists the job; it reports the helper's outcome as the job's result. If the helper fails or the new agent never starts, the job stays `running` until the agent reconnects without it ("lost") or `UPDATE_TIMEOUT` ends the wait. |
 | Polling fails for one image | Error stored in `last_poll_error` and shown; other images continue. |
 
-### Self-protection
+### Self-update
 
-The agent reports its own container and the master knows its own service. Both are shown
-as "updated manually outside the system", and the master refuses to create jobs for
-them. An agent recreating itself would kill the job it is running.
+The agent reports its own container with `self`; the overview shows "This agent". The
+master's own Compose service and every Compose agent's own service are normal update
+targets. A Swarm agent's own service is refused ("an agent's own Swarm service cannot
+update itself").
+
+- **Master.** No special execution. The agent on the master's host runs the job; the
+  recreate drops its connection, and it sends the result again after the new master is up
+  (unacknowledged results are resent).
+- **Agent.** The old agent does the usual checks, writes the override and pulls. Only
+  `up -d <service>` runs in a helper container made from the agent's own image, with the
+  agent's own bind and volume mounts and no Compose labels. The helper's labels
+  (`se.shcizo.package-updater.self-update.` plus `job`, `ref`, `started`, `project`,
+  `service`, `output`) hold what the new agent needs: the job ID, the pinned ref, the
+  start time and the output so far (tail, 32 KiB). If the helper exits while the old agent
+  still runs, the old agent copies its logs into the job output, removes it and reports
+  the outcome itself.
+- **Resume.** At startup, before the runner and the connection start, the agent lists
+  helpers whose project and service labels match its own container and registers each as
+  a job at the front of its queue. The job is then in `known_jobs` of the first hello.
+  Its result is a normal `job.result`: output, helper logs, pinned ref on exit 0,
+  otherwise an error. A helper with unusable labels fails the job with a message saying so.
+- **Stopping.** When the agent is stopped (SIGTERM) while a job runs, the runner drops the
+  job and records no result, so a "context canceled" result cannot overtake the new
+  agent's.
+- **Order.** `job.start` carries `self`; the agent runs a self job only when no other job
+  is queued (the master's job on a shared host has to finish first). Whether to use a
+  helper is decided by the agent from its own container ID, not from the flag.
+- **Protocol 4.** The master routes a self job only to an agent speaking protocol 4
+  (`agent too old to update itself`).
 
 ## Registry polling
 
@@ -355,7 +382,7 @@ Each phase ends with something that works on its own.
    snapshot and live events, Postgres storage, OIDC login, Overview and Agents pages.
    The overview works; nothing can be updated yet.
 2. **Jobs and manual update.** Job protocol, agent queue and executors (Compose override
-   file, Swarm with digest), job history, Service and Jobs pages, self-protection.
+   file, Swarm with digest), job history, Service and Jobs pages.
 3. **Webhook and auto mode.** `POST /update` on the master, matching, waiting for
    auto jobs, mode toggle.
 4. **Polling and version history.** `image_versions`, registry polling, version picker
@@ -372,6 +399,5 @@ Each phase ends with something that works on its own.
 - Export/import of a fleet configuration to restore a setup. The `services` table
   already holds what an export needs.
 - Writing version bumps back to git.
-- Self-update of master and agents (`internal/selfupdate` is the starting point).
 - Updating plain (non-Compose, non-Swarm) containers.
 - Credential management UI for registries.