serve-live

Serve live — never hand over a stale process

<!-- agent-sync:start serve-live --> Vendor-neutral and machine-wide: this lives in ~/.agents/skills/, the cross-tool location Codex, Grok and Kilo read themselves; Claude Code gets a one-line pointer to it. It is written to be followed by any coding agent — Codex, Grok, Claude, Kilo, Cursor, Gemini, Copilot — or by a person.

The failure this exists to prevent

A service started before your last commit keeps answering. Every health check passes. The port is bound, requests return 200, logs look normal. And the person looking at it is looking at old code — reviewing work you did not do, reporting bugs you already fixed, or seeing none of the feature you just described to them.

This is not a rare edge case. It is the default outcome of committing while a server runs, and it is silent: nothing in the served response says "I am three commits behind" unless the application deliberately says so.

It wastes a person's attention, which is the most expensive thing you spend.

The rule

Committing code that a running service serves is not finished work until you have restarted that service and verified the restart.

Do it on your own initiative. Do not wait to be asked, do not ask permission for a dev service, and do not announce a page as ready, live, or working without doing it first.

Work ready for a person to test is live before you say so: read the push's svc deploy: serving <proj> at <sha> line, then the service's own reported build. A deploy or restart that did not happen (refused, failed, skipped) is yours to finish now with svc restart <service> — never handed back as "close your tabs" or "run this as max". An open page, sitting or job is not a reason to wait on a dev service: restart, then say what it cut off.

What "verified" means

Answering is not the check. A wedged or stale process answers.

Verify identity, in this order:

1. The running process reports the current commit. If the service exposes its build (many do: a /health field, a banner, a version endpoint), compare it to git rev-parse --short HEAD and require equality. This is the only check that actually proves freshness.
2. If it exposes no build, verify by behaviour: request something that only exists after your change and require the new answer. A status code is not enough — assert on content only the new code could produce.
3. Restart time is later than commit time. The weakest check; use it only when neither of the above is possible, and say that you used it.

A check that cannot distinguish the new code from the old proves nothing.

Drive the path you changed

Any path is not the check; the path is. A streaming request is a separate code path from a plain one, so a fix proven on one is unproven on the other — send both. A fix to a refusal is proven by a request that should be refused being refused, not by the allow path still working; a fix that only proves the allow path is half a fix.

Verifying a UI: sign in, do not infer

A change to a user interface is verified by loading the page, not by reading the source and reasoning that it must render. Source can be correct while the feature is unreachable — hidden behind a click with no affordance, rendered off-screen, or gated on an identity the viewer does not have. Those are real defects and no amount of re-reading the component finds them.

Two things block this, and both look like the app being broken:

• Credentials come from the environment, never from a read. Use the test credential the execution environment provides; never read .env or a keyfile to find one, and never print it or run with shell tracing on.
• An API key is not a login. Keys usually authenticate as nobody, while a management UI is a person's surface. Find the project's designated agent-usable account and sign in as it. Projects that expect agents to verify UI work provide one; look for it in the project's own docs before concluding you cannot log in. Check the sign-in route against the client code rather than guessing at /auth/signin or /login.
• A self-signed cert on a dev service. curl reads it as a hard failure without -k, and an http:// probe of an HTTPS port reports the service down while it is serving happily. A headless browser stops at an interstitial and never mounts the app — ERR_CERT_AUTHORITY_INVALID, a "Privacy error" title and a near-empty body, which reads exactly like a crash. Click through it (Advanced, then the proceed link) before judging anything.

When you assert on rendered text, match case-insensitively or read the accessibility tree. CSS routinely uppercases labels, so a literal test for Offered for fails on the OFFERED FOR that is plainly on screen — and that false negative sends you hunting a bug that does not exist.

If a surface stays locked after signing in as the agent account, check whether it is meant to be. An ordinary account being refused an operator-only page is correct behaviour, not a failed login.

Restart what you touched. Check the rest.

Two different obligations, and conflating them wastes time and takes down things that were fine.

Restart — only what your change actually reaches:

• The service whose code you edited.
• Anything that imported or vendored it, including sidecars and workers that load their own copy at spawn time and so keep running old code even after the parent restarts.
• Anything that cached it: a compiled bundle, a generated client, a template cache. A frontend served from a bundle needs its build step re-run, not just a server bounce.

Check, do not restart — everything else it depends on:

• Upstreams you did not change: confirm they answer and report their state.
• Services owned by another session or person: never bounce one to make yours look good. Report what you saw and let the owner decide.

If you are unsure whether your change reaches a service, ask what would have to be true for it to be stale — did its process load the code you changed? If no, leave it alone and say you left it alone. A change to docs or comments reaches no process: restart nothing, and say so.

Restarting safely

• Never restart onto code that does not pass. A live check against a broken build tells you nothing, and it takes down a working one to do it.
• Note work in flight, then restart. An open session, a running job, a live upload. Say what it cost. Do not wait and do not ask. Another session using the service is not a reason to leave stale code running.
• Kill by PID, and take the PID from something that cannot be you. pkill -f "<service>" can match the agent's own command line and kill the session. pgrep -f "<service>" first and then killing those PIDs is the same pattern with the same result: a shell that runs the restart and then greps for the service is killed along with it. Take the PID from the port (ss -ltnp 'sport = :<port>'), or anchor the pattern at the start of the server's own argv (^[^ ]*python[^ ]* [^ ]*/<entry> serve). No shell's command line starts that way.
• Escalate only when needed. Try a graceful stop; if the process is already wedged in shutdown (a held socket, a draining connection that never drains), a graceful signal cannot work and you escalate.
• Confirm the port is free before starting again, or you get a second process fighting for it, or a start that silently fails.
• Prefer no-reload in a shared tree. If several agents or a person edit the same checkout, a file-watch reloader can be triggered by someone else's save and wedge mid-restart. Autoreload is a convenience, not a substitute for this skill: it is exactly what produces "the port is bound but nothing answers".

Live is an end state

The restarted service must still be running when you hand back. Do not start it inside a test harness, behind a cleanup trap, or from a command whose environment reaps its children when it returns — a screenshot of a process that was then stopped is not a live verification. Make the final health request in a separate command, after the restart has returned; if the environment reaps background children, start the service under the user's service manager instead.

Warm-up is not readiness

Many services report empty or partial subsystems for seconds after start — models load lazily, engines warm on first use, caches fill on demand. Checking too early and reporting "the engine is empty, something is broken" is a wrong diagnosis that costs a person real time.

Wait for the subsystem to report ready before you judge it. Poll until it is populated or until a timeout you state. If it is still empty at the timeout, then it is a finding — and say how long you waited.

Write it down once

If you restart a service by hand more than once in a session, put the sequence in the project as a script — stop by PID, wait for the port, start, then block until the reported build equals HEAD, exiting non-zero if it does not. A script that returns success while serving the wrong commit is worse than no script. Make the freshness assertion the thing that gates its exit code.

What to say at the end

• The service, the port, and the commit it is now serving — with the checkout's commit beside it, so the match is visible rather than claimed.
• Any subsystem you waited for, and how long.
• Upstreams you checked but did not restart, and who owns them.
• Anything you could not verify — a page behind a login you cannot pass, a client you cannot drive. Name it plainly instead of implying you saw it work.

Never say "it is live" or "ready to look at" without the commit match behind it. If you could not verify, say what you actually did and what remains unproven. <!-- agent-sync:end -->