feat: scope worker names to stack slug and add --name-template

[kaiitunnz]

Purpose

flowmesh stack worker up cpu|gpu generated preset worker aliases from hardcoded, non-namespaced names (worker_cpu_0, worker_gpu_0, …). The server's DockerWorkerFactory uses the alias verbatim as the worker name and as the basis for the container name, but worker containers spawned by every stack share the host docker daemon namespace. Unlike the server / redis / volume names, which all carry the stack slug (flowmesh_node[_<suffix>]_*), these worker names were not stack-scoped, so two stacks differentiated by FLOWMESH_STACK_SUFFIX on the same host produced colliding worker containers.

This scopes preset worker names to the stack slug by default and adds a --name-template for custom naming.

Changes

• Alias construction — sdk/stack/src/flowmesh_stack/workers.py: create_workers / _payloads_for_worker_create gain name_template and slug params (both default None, so direct SDK callers and the --config paths keep today's behavior). New _worker_alias helper builds {slug}_worker_{kind}_{idx|gpu} by default, or renders a template over {slug} / {kind} / {idx} / {gpu} via a strict format dict that raises a clear FlowMeshError on an unknown placeholder. Generated aliases are deduped within one invocation.
• CLI wiring — cli/stack/src/flowmesh_cli_stack/worker.py: worker up gains --name-template, resolves the stack slug from env (reusing stack_resource_env_overrides / STACK_SLUG_ENV, which read the already-loaded FLOWMESH_STACK_SUFFIX), and passes both down. An invalid suffix exits cleanly.
• Docs — docs/CLI.md: document the slug-prefixed default naming and --name-template with its placeholders.
• Tests — tests/sdk/test_workers.py: cover slug-prefixed defaults, legacy bare names, template rendering, the unknown-placeholder error, the duplicate-name guard, and GPU single/multi cases.

Design

The default name is not expressed as a template string; it is the existing per-kind logic with a slug prefix, so GPU workers keep their informative _gpu_<id> / _gpu_all suffix. --name-template is a full override; when present it alone determines the alias. To prevent the obvious foot-gun (a template without {idx}/{gpu} for count > 1), all generated aliases are checked for uniqueness within a single up invocation and a missing-disambiguator template fails fast. The default prefix is the full stack slug (flowmesh_node + optional suffix), matching the convention every other stack-managed object already follows.

Test Plan

uv run pytest tests/sdk/test_workers.py tests/cli/test_stack_utils.py tests/server/test_command_listener.py
uv run pre-commit run --files sdk/stack/src/flowmesh_stack/workers.py cli/stack/src/flowmesh_cli_stack/worker.py tests/sdk/test_workers.py docs/CLI.md

End-to-end (flowmesh stack worker up / list / down): default and suffix-scoped naming, cross-stack isolation (two stacks, no collision), --name-template rendering, fail-fast on bad templates, and GPU naming (single / per-GPU / --targets all / template).

Test Result

$ uv run pytest tests/sdk/test_workers.py            # 9 passed
$ uv run pytest tests/cli/test_stack_utils.py \
                tests/server/test_command_listener.py # 39 passed (server alias path unaffected)
$ uv run pre-commit run --files ...                  # isort/black/ruff/mypy/codespell passed

End-to-end scenarios above all passed, including GPU workers on a 2-GPU host — every worker came up healthy with a correctly slug-prefixed name and no collisions.

---

Pre-submission Checklist

• I have read the contribution guidelines.
• I have run pre-commit run --all-files and fixed any issues.
• I have added or updated tests covering my changes (if applicable).
• I have verified that uv run pytest tests/ passes locally.
• If I changed shared schemas or proto definitions, I have checked downstream compatibility across Server and Worker. (No schema/proto changes.)
• If I changed the SDK or CLI, I have verified the affected packages work (uv sync --all-packages --group ci --frozen).
• If this is a breaking change, I have prefixed the PR title with [BREAKING] and described migration steps above.
• I have updated documentation or config examples if user-facing behavior changed.

[timzsu]

LGTM.