fix(sidecar): restore the seictl compatibility name in the image

[bdchatham]

Restores the compatibility shim that 531d7dc ("feat(sidecar)!: let the image own its entrypoint; drop the seictl name") deleted — the fourth commit of #504, after 8062799 had added it. That commit dropped the shim and both Command renderings together, before either half of the shim's own removal condition was met.

Reviewed by the kubernetes and systems specialists; corrections from both are folded in.

Why

The original condition was: remove only after the controller stops rendering Command and every cell has rolled past that controller. The first half happened at 186d65a. The second has not happened anywhere — all five overlays (harbor, dev, prod, prod-euw1, prod-use2) still point images.sidecar at ghcr.io/sei-protocol/seictl, and no cell's controller is past 186d65a.

What breaks without it

A pod spec's command replaces the image ENTRYPOINT (args replaces CMD); neither render site sets Args, so argv is exactly what the controller renders.

Controller renders	Image	Executes
["seictl","serve"]	old seictl	seictl serve	✅ today, all five cells
["seictl","serve"]	this image, no shim	exec seictl: not found	❌
(nothing)	this image	sei-sidecar serve	✅ target
(nothing)	old seictl	bare seictl → help, exit 0	❌

Controller-first does pass through a working state — no plan triggers on a Command-only change, so live pods keep the old template. But it is latently broken: the next apply-statefulset from any other cause (a seid image bump, a bootstrap plan, a re-init) renders old-image + no-Command and lands the quiet exit-0 pod. That is the real argument for the shim.

Row four is the quiet direction: exit 0 reads as Completed/success to a human and to any alert keyed on error reasons, where row two gives StartError. So the safe rollback is "revert the controller, leave the image" — never the reverse.

What it enables

Three steps per cell instead of one flip:

1. point images.sidecar at the ECR image, and restart the controller at its current version — images.sidecar is read once at startup (internal/platform/load.go:30-33), so the commit alone is inert. The restart rolls the cell, on the old controller, through the seictl name.
2. bump the controller — triggers no plan, so the Command leaves the StatefulSet at the next drift plan, atomically with whatever image that plan applies.
3. delete the shim, once no cell's controller can render Command.

Price: two cell rolls instead of one. That is the right trade and it should not be a surprise.

The shim covers both render sites — internal/noderesource/noderesource.go and internal/task/bootstrap_resources.go. The bootstrap Job renders fresh each time rather than through a StatefulSet, so an old controller creating a bootstrap Job against the new image needs seictl too.

Mechanism

A second COPY, not a symlink. A build-stage RUN ln -s plus a COPY of the link would work and would save the duplicate — but it makes the one thing unverifiable locally (the image build) carry a new BuildKit-behavior dependency, on a change whose whole purpose is to not fail. Cost is 83,037,797 bytes (linux/amd64), roughly doubling the image over a ~2 MB distroless base. Right trade for a few weeks.

Verification

argv[0] independence, empirically: built the binary, copied it to seictl, ran both names. seictl serve with SEI_HOME unset reaches serve's required-flag check; with a relative SEI_HOME it hits validateHome identically; output identical under either name. os.Args appears once, at sidecar/main.go:29, passed whole to urfave/cli; root Name is the literal "sei-sidecar" at :40.

PATH resolution — the stronger argument, and the one my local run did not exercise. The old controller renders a relative seictl, so this depends on PATH inside the container. Both images share the same base (gcr.io/distroless/static-debian12) and the same install path (/usr/bin/seictl), so resolution is byte-identical to what has run in prod for months.

serve serve cannot happen. Beyond the replace-not-append rule: every cell today runs Command: ["seictl","serve"] against an image whose ENTRYPOINT is ["/usr/bin/seictl"]. If Kubernetes appended, argv would be ["/usr/bin/seictl","seictl","serve"] and every sidecar in production would be dead. Replacement is already proven in prod on this exact pair.

Wire contract unchanged — old client ↔ new server verified compatible: seictl v0.0.68's sidecar/server differs only in the import path and four route literals hoisted to constants; wire.go byte-identical; all 24 task-type constants match.

Contract now pinned in code. Neither render site had any assertion that the sidecar renders no Command/Args — the invariant the whole cutover rests on. Both added and mutation-checked: re-adding Command fails each at the expected line, removing it passes again.

CLAUDE.md updated. It still stated the coordinated-deploy doctrine this PR dissolves. That doc outranks a Dockerfile comment, and the shim was deleted last time precisely because its rationale lived only in the Dockerfile.

The image build is not verified locally (no Docker daemon). The docker job in .github/workflows/ci.yml:78-109 builds sidecar/Dockerfile on every PR, so it is covered before merge — publish-sidecar runs only on push to main.

Not addressed here

Two open findings this PR does not touch, both raised as gates before the first cell:

• the executor treats a failed sidecar submit as retry-forever (internal/planner/executor.go:157-166) and never escalates to Failed, so a wedged plan is invisible and blocks later plans
• sharedDoer has no client timeout (cmd/main.go:153) and MaxConcurrentReconciles is unset, so one hung sidecar parks the single SeiNode worker for a whole cell

🤖 Generated with Claude Code

[cursor]

PR Summary

Medium Risk
Touches the sidecar image entrypoint used on every node; a wrong binary name or premature shim removal can leave sidecars looping exit-0 while seid never starts. Tests pin Command/Args empty, but the image itself is not exercised in unit tests.

Overview
Restores a temporary /usr/bin/seictl copy of sei-sidecar in the sidecar image so one image works under both the old controller (Command: ["seictl","serve"]) and the current one (no Command; ENTRYPOINT sei-sidecar serve). That turns a simultaneous image+controller flip into an ordered per-cell deploy: adopt the image first, bump the controller second, delete the shim last. Safe rollback is revert the controller and leave the image — the reverse still deadlocks (bare seictl exits 0, seid blocks on /v0/healthz).

Pins both sidecar render sites (StatefulSet and bootstrap Job) to empty Command/Args so the shim is not removed until those tests exist. Documents the order, rollback, and removal conditions in CLAUDE.md.

^{Reviewed by Cursor Bugbot for commit 80a678f. Bugbot is set up for automated code reviews on this repo. Configure here.}