RFC: daemon auto-reload when CLI binaries change

[tangyuanjc]

Context

This is a discussion-first RFC; I am not proposing a code PR until maintainers confirm the desired behavior.

Our team hit a daemon sharp edge while dogfooding Multica with local agent CLIs: after upgrading Codex/Hermes/other agent CLIs, the long-lived multica daemon can keep advertising stale runtime capability/version information until the user manually restarts it. In one real case, upgrading Codex without restarting the daemon left a task stuck / new model capability invisible until a manual daemon restart.

There is nearby maintainer signal in #2410: Bohan clarified that CLI/daemon update behavior is a separate design space from Desktop, where relaunch semantics are unavoidable. This RFC is narrower than "silent updates": it is about detecting that relevant CLI binaries changed outside the daemon and safely reloading the local runtime.

Related prior work:

• Daemon restart after self-update fails on Linux: os.Executable() returns deleted Cellar path #1624 / fix(daemon): use brew prefix symlink for self-restart so Linux Cellar deletion does not orphan runtimes #2076 fixed self-restart after a server-triggered Multica CLI update, including the Linuxbrew os.Executable() / deleted Cellar path issue.
• Current daemon startup detects agent CLIs in LoadConfig once:

  multica/server/internal/daemon/config.go

  Lines 98 to 179 in fb8ad8c

  	// Probe available agent CLIs
  	agents := map[string]AgentEntry{}
  	claudePath := envOrDefault("MULTICA_CLAUDE_PATH", "claude")
  	if _, err := exec.LookPath(claudePath); err == nil {
  	agents["claude"] = AgentEntry{
  	Path: claudePath,
  	Model: strings.TrimSpace(os.Getenv("MULTICA_CLAUDE_MODEL")),
  	}
  	}
  	codexPath := envOrDefault("MULTICA_CODEX_PATH", "codex")
  	if _, err := exec.LookPath(codexPath); err == nil {
  	agents["codex"] = AgentEntry{
  	Path: codexPath,
  	Model: strings.TrimSpace(os.Getenv("MULTICA_CODEX_MODEL")),
  	}
  	}
  	opencodePath := envOrDefault("MULTICA_OPENCODE_PATH", "opencode")
  	if _, err := exec.LookPath(opencodePath); err == nil {
  	agents["opencode"] = AgentEntry{
  	Path: opencodePath,
  	Model: strings.TrimSpace(os.Getenv("MULTICA_OPENCODE_MODEL")),
  	}
  	}
  	openclawPath := envOrDefault("MULTICA_OPENCLAW_PATH", "openclaw")
  	if _, err := exec.LookPath(openclawPath); err == nil {
  	agents["openclaw"] = AgentEntry{
  	Path: openclawPath,
  	Model: strings.TrimSpace(os.Getenv("MULTICA_OPENCLAW_MODEL")),
  	}
  	}
  	hermesPath := envOrDefault("MULTICA_HERMES_PATH", "hermes")
  	if _, err := exec.LookPath(hermesPath); err == nil {
  	agents["hermes"] = AgentEntry{
  	Path: hermesPath,
  	Model: strings.TrimSpace(os.Getenv("MULTICA_HERMES_MODEL")),
  	}
  	}
  	geminiPath := envOrDefault("MULTICA_GEMINI_PATH", "gemini")
  	if _, err := exec.LookPath(geminiPath); err == nil {
  	agents["gemini"] = AgentEntry{
  	Path: geminiPath,
  	Model: strings.TrimSpace(os.Getenv("MULTICA_GEMINI_MODEL")),
  	}
  	}
  	piPath := envOrDefault("MULTICA_PI_PATH", "pi")
  	if _, err := exec.LookPath(piPath); err == nil {
  	agents["pi"] = AgentEntry{
  	Path: piPath,
  	Model: strings.TrimSpace(os.Getenv("MULTICA_PI_MODEL")),
  	}
  	}
  	cursorPath := envOrDefault("MULTICA_CURSOR_PATH", "cursor-agent")
  	if _, err := exec.LookPath(cursorPath); err == nil {
  	agents["cursor"] = AgentEntry{
  	Path: cursorPath,
  	Model: strings.TrimSpace(os.Getenv("MULTICA_CURSOR_MODEL")),
  	}
  	}
  	copilotPath := envOrDefault("MULTICA_COPILOT_PATH", "copilot")
  	if _, err := exec.LookPath(copilotPath); err == nil {
  	agents["copilot"] = AgentEntry{
  	Path: copilotPath,
  	Model: strings.TrimSpace(os.Getenv("MULTICA_COPILOT_MODEL")),
  	}
  	}
  	kimiPath := envOrDefault("MULTICA_KIMI_PATH", "kimi")
  	if _, err := exec.LookPath(kimiPath); err == nil {
  	agents["kimi"] = AgentEntry{
  	Path: kimiPath,
  	Model: strings.TrimSpace(os.Getenv("MULTICA_KIMI_MODEL")),
  	}
  	}
  	kiroPath := envOrDefault("MULTICA_KIRO_PATH", "kiro-cli")
  	if _, err := exec.LookPath(kiroPath); err == nil {
  	agents["kiro"] = AgentEntry{
  	Path: kiroPath,
  	Model: strings.TrimSpace(os.Getenv("MULTICA_KIRO_MODEL")),
  	}
  	}
  	if len(agents) == 0 {
  	return Config{}, fmt.Errorf("no agent CLI found: install claude, codex, copilot, opencode, openclaw, hermes, gemini, pi, cursor-agent, kimi, or kiro-cli and ensure it is on PATH")
  	}

• Runtime registration detects agent CLI versions during workspace registration:

  multica/server/internal/daemon/daemon.go

  Lines 598 to 620 in fb8ad8c

  	func (d *Daemon) registerRuntimesForWorkspace(ctx context.Context, workspaceID string) (*RegisterResponse, error) {
  	var runtimes []map[string]string
  	for name, entry := range d.cfg.Agents {
  	version, err := detectAgentVersion(ctx, entry.Path)
  	if err != nil {
  	d.logger.Warn("skip registering runtime", "name", name, "error", err)
  	continue
  	}
  	if err := checkAgentMinVersion(name, version); err != nil {
  	d.logger.Warn("skip registering runtime: version too old", "name", name, "version", version, "error", err)
  	continue
  	}
  	d.setAgentVersion(name, version)
  	displayName := strings.ToUpper(name[:1]) + name[1:]
  	if d.cfg.DeviceName != "" {
  	displayName = fmt.Sprintf("%s (%s)", displayName, d.cfg.DeviceName)
  	}
  	runtimes = append(runtimes, map[string]string{
  	"name": displayName,
  	"type": name,
  	"version": version,
  	"status": "online",
  	})

• The existing restart path is only reached from server-triggered PendingUpdate:

  multica/server/internal/daemon/daemon.go

  Lines 1158 to 1164 in fb8ad8c

  	if resp.PendingUpdate != nil {
  	go d.handleUpdate(ctx, runtimeID, resp.PendingUpdate)
  	}
  	if resp.PendingModelList != nil {
  	if rt := d.findRuntime(runtimeID); rt != nil {
  	go d.handleModelList(ctx, *rt, resp.PendingModelList.ID)
  	}

  and

  multica/server/internal/daemon/daemon.go

  Lines 1362 to 1427 in fb8ad8c

  	// handleUpdate performs the CLI update when triggered by the server via heartbeat.
  	func (d *Daemon) handleUpdate(ctx context.Context, runtimeID string, update *PendingUpdate) {
  	// Desktop-managed daemons share their CLI binary with the Electron app,
  	// which is responsible for shipping and replacing it. Letting the daemon
  	// self-update would just get overwritten on the next Desktop launch and
  	// could brick the embedded binary mid-update. Refuse cleanly.
  	if d.cfg.LaunchedBy == "desktop" {
  	d.logger.Info("refusing CLI self-update: daemon is managed by Desktop", "runtime_id", runtimeID, "update_id", update.ID)
  	d.reportUpdateResult(ctx, runtimeID, update.ID, map[string]any{
  	"status": "failed",
  	"error": "CLI is managed by Multica Desktop — update the Desktop app to upgrade the CLI",
  	})
  	return
  	}
  	// Prevent concurrent update attempts.
  	if !d.updating.CompareAndSwap(false, true) {
  	d.logger.Warn("update already in progress, ignoring", "runtime_id", runtimeID, "update_id", update.ID)
  	return
  	}
  	defer d.updating.Store(false)
  	d.logger.Info("CLI update requested", "runtime_id", runtimeID, "update_id", update.ID, "target_version", update.TargetVersion)
  	// Report running status.
  	d.reportUpdateResult(ctx, runtimeID, update.ID, map[string]any{
  	"status": "running",
  	})
  	// Try Homebrew first, fall back to direct download.
  	var output string
  	if cli.IsBrewInstall() {
  	d.logger.Info("updating CLI via Homebrew...")
  	var err error
  	output, err = cli.UpdateViaBrew()
  	if err != nil {
  	d.logger.Error("CLI update failed", "error", err, "output", output)
  	d.reportUpdateResult(ctx, runtimeID, update.ID, map[string]any{
  	"status": "failed",
  	"error": fmt.Sprintf("brew upgrade failed: %v", err),
  	})
  	return
  	}
  	} else {
  	d.logger.Info("updating CLI via direct download...", "target_version", update.TargetVersion)
  	var err error
  	output, err = cli.UpdateViaDownload(update.TargetVersion)
  	if err != nil {
  	d.logger.Error("CLI update failed", "error", err)
  	d.reportUpdateResult(ctx, runtimeID, update.ID, map[string]any{
  	"status": "failed",
  	"error": fmt.Sprintf("download update failed: %v", err),
  	})
  	return
  	}
  	}
  	d.logger.Info("CLI update completed successfully", "output", output)
  	d.reportUpdateResult(ctx, runtimeID, update.ID, map[string]any{
  	"status": "completed",
  	"output": fmt.Sprintf("Updated to %s", update.TargetVersion),
  	})
  	// Trigger daemon restart with the new binary.
  	d.triggerRestart()
  	}

• The daemon already has a graceful restart handoff after updates:

  multica/server/internal/daemon/daemon.go

  Lines 1485 to 1520 in fb8ad8c

  	// triggerRestart initiates a graceful daemon restart after a successful CLI update.
  	// For brew installs, it keeps the symlink path (e.g. /opt/homebrew/bin/multica)
  	// so the restarted daemon picks up the new Cellar version automatically.
  	// For non-brew installs, it resolves to the absolute path of the replaced binary.
  	// The caller (cmd_daemon.go) checks RestartBinary() and launches the new process.
  	func (d *Daemon) triggerRestart() {
  	newBin, err := os.Executable()
  	if err != nil {
  	d.logger.Error("could not resolve executable path for restart", "error", err)
  	return
  	}
  	// On Linux, os.Executable() reads /proc/self/exe, which the kernel resolves
  	// to the Cellar path. brew cleanup deletes that path after upgrade, so we
  	// must use the stable <brew-prefix>/bin/multica symlink instead.
  	if isBrewInstall() {
  	if brewPrefix := getBrewPrefix(); brewPrefix != "" {
  	newBin = filepath.Join(brewPrefix, "bin", "multica")
  	} else if prefix := matchKnownBrewPrefix(newBin); prefix != "" {
  	newBin = filepath.Join(prefix, "bin", "multica")
  	} else {
  	d.logger.Warn("brew install detected but prefix could not be resolved; restart may fail",
  	"executable", newBin)
  	}
  	} else {
  	if resolved, err := filepath.EvalSymlinks(newBin); err == nil {
  	newBin = resolved
  	}
  	}
  	d.logger.Info("scheduling daemon restart", "new_binary", newBin)
  	d.restartBinary = newBin
  	// Cancel the main context to trigger graceful shutdown.
  	if d.cancelFunc != nil {
  	d.cancelFunc()
  	}

  and

  multica/server/cmd/multica/cmd_daemon.go

  Lines 365 to 409 in fb8ad8c

  	// Check if the daemon needs to restart after a CLI update.
  	if restartBin := d.RestartBinary(); restartBin != "" {
  	logger.Info("restarting daemon with updated binary", "path", restartBin)
  	args := buildDaemonStartArgs(cmd)
  	child := exec.Command(restartBin, args...)
  	logPath := daemonLogPathForProfile(profile)
  	logFile, err := os.OpenFile(logPath, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0o644)
  	if err != nil {
  	logger.Error("failed to open log file for restart", "error", err)
  	return nil
  	}
  	child.Stdout = logFile
  	child.Stderr = logFile
  	// Break out of the parent's Job Object on Windows; see the
  	// runDaemonBackground call site for rationale.
  	child.SysProcAttr = daemonSysProcAttr(true)
  	if err := child.Start(); err != nil {
  	if isAccessDeniedSpawnErr(err) {
  	child = exec.Command(restartBin, args...)
  	child.Stdout = logFile
  	child.Stderr = logFile
  	child.SysProcAttr = daemonSysProcAttr(false)
  	if err := child.Start(); err != nil {
  	logFile.Close()
  	logger.Error("failed to start new daemon (no breakaway)", "error", err)
  	return nil
  	}
  	} else {
  	logFile.Close()
  	logger.Error("failed to start new daemon", "error", err)
  	return nil
  	}
  	}
  	logFile.Close()
  	child.Process.Release()
  	// Write new PID file.
  	pidPath := daemonPIDPathForProfile(profile)
  	os.WriteFile(pidPath, []byte(strconv.Itoa(child.Process.Pid)), 0o644)
  	logger.Info("new daemon started", "pid", child.Process.Pid)
  	}

Goals

1. Let a long-running CLI daemon notice when relevant binaries change without requiring users to remember multica daemon restart.
2. Cover both the Multica daemon binary itself and configured agent runtime binaries such as codex, claude, hermes, gemini, openclaw, etc.
3. Preserve current behavior by default unless maintainers want this on-by-default later.
4. Avoid interrupting active tasks in the default mode.
5. Keep the design cross-platform enough for macOS/Linux/Windows, including symlink-based installs such as Homebrew.

Non-goals

• No fully silent Desktop app update. Desktop should keep its own download/relaunch UX.
• No automatic installation of new agent CLIs.
• No server-side model catalog redesign.
• No immediate change to cloud runtimes.
• No forced interruption of active agent tasks unless explicitly opted into later.

Proposed model

Add an opt-in daemon flag/env, for example:

multica daemon start --auto-reload-binaries
# or
MULTICA_DAEMON_AUTO_RELOAD_BINARIES=1 multica daemon start

When enabled, the daemon records a lightweight fingerprint for:

• The running Multica binary / restart target.
• Each configured agent CLI binary from Config.Agents after exec.LookPath / symlink resolution.

A fingerprint can be:

• Resolved path.
• Device/inode where available.
• Size and mtime as portable fallback, especially on Windows.
• Optional symlink target string so Homebrew/npm-style pointer swaps are detected even when the stable launcher path stays constant.

The daemon then checks fingerprints on a low-frequency interval, likely aligned with heartbeat or a dedicated 30-60s ticker. I would prefer polling over fsnotify for v1 because package managers often replace symlink targets atomically, and polling is simpler to make portable.

When a change is detected, v1 should schedule a graceful full daemon restart:

1. Log which binary changed and mark reload_pending in memory / health output.
2. Stop claiming new tasks.
3. If activeTasks == 0, reuse the existing restart handoff immediately.
4. If tasks are running, wait for them to finish, then restart.
5. On restart, normal startup re-runs LoadConfig, re-detects CLI availability/versions, and re-registers runtimes.

This deliberately favors a full process restart for v1 rather than an in-process runtime registry reload. It is less elegant, but it reuses the existing deregister/register/restart machinery and reduces the risk of partial state bugs.

Alternatives

A. Graceful restart after drain (recommended)

Best default. It fixes stale runtime metadata, avoids task loss, and mostly reuses current daemon restart flow.

Trade-off: if a task runs for hours, users wait for the new runtime metadata until it completes.

B. Immediate restart and retry active tasks

Fastest to freshness. On binary change, cancel active tasks, restart, and rely on task retry/requeue behavior.

Trade-off: risky for long-running coding tasks and surprising as an opt-in default.

C. Notify only, reload on next idle/manual restart

Safest operationally. Daemon detects the change and tells the user / UI that restart is recommended.

Trade-off: it only improves observability; it does not remove the manual restart sharp edge.

Migration / compatibility

• Ship as opt-in at first.
• Keep existing daemon start, daemon restart, and server-triggered update behavior unchanged.
• Desktop-managed daemons can ignore the flag initially or surface a Desktop-specific relaunch recommendation.
• If telemetry / community feedback is positive, maintainers could later enable idle-only graceful reload by default for CLI daemons.

Tests

Suggested coverage:

• Unit-test fingerprinting for regular files, symlinks, replaced symlink targets, and missing binaries.
• Unit-test that a changed Multica binary schedules restart without starting a second concurrent restart.
• Unit-test that a changed agent CLI binary schedules graceful restart / reload pending.
• Integration-style daemon test with a fake codex binary on PATH: start daemon, replace the fake binary, verify restart is scheduled only after active task count drains.
• Regression test that unchanged mtimes/inodes do not trigger restart loops.
• Linuxbrew/Homebrew path test that keeps the fix(daemon): use brew prefix symlink for self-restart so Linux Cellar deletion does not orphan runtimes #2076 symlink behavior intact.
• Windows fallback test using mtime/size where inode is unavailable.

Open questions

1. Should v1 watch both the Multica binary and agent runtime binaries, or start with agent runtime binaries only?
2. Should --auto-reload-binaries be one flag, or split into --auto-reload-daemon-binary and --auto-reload-agent-binaries?
3. Is a full daemon restart acceptable for v1, or would maintainers prefer an in-process runtime re-registration path?
4. Should the daemon expose reload_pending in /health so Desktop/UI can show a precise status?
5. Should long-running active tasks block reload indefinitely, or should there be an optional max grace period?
6. How should this interact with runtime/model list cache invalidation so a refreshed CLI's new model set becomes visible promptly?

@Bohan-J curious if this direction matches your mental model for the CLI/daemon half of #2410. If you already have a preferred design, happy to adjust or withdraw and follow that direction.

AI disclosure: drafted with help from a Multica Codex agent based on our company dogfooding notes and source-code review.

[Bohan-J]

Thanks for the careful write-up — the problem framing and the prior-art links are spot-on, and the recommended Alternative A is the right default. A few pieces of feedback before this turns into a PR, with concrete answers to your open questions at the end.

Scope: agent CLIs only for v1, not the multica binary

The strongest piece of advice I'd give: drop the multica binary from the v1 watch set. Two reasons:

1. Server-triggered self-update already handles that case end-to-end (handleUpdate → triggerRestart), and the os.Executable() sharp edge that Daemon restart after self-update fails on Linux: os.Executable() returns deleted Cellar path #1624 / fix(daemon): use brew prefix symlink for self-restart so Linux Cellar deletion does not orphan runtimes #2076 fixed is non-trivial to replicate correctly in a polling watcher. A bug here would be much worse than the bug it's trying to fix: a watcher that restarts on the wrong path would brick the daemon, not just leave it stale.
2. There's a real restart-storm risk: while handleUpdate is mid-flight, the binary on disk is being replaced. The watcher needs to know not to fire concurrently. We have d.updating atomic.Bool for exactly this, but the simpler answer is "don't watch the thing we already self-update."

The actual user-facing pain you describe — Codex upgraded out-of-band, daemon keeps advertising the old version — is purely about agent CLIs. Scope v1 to those and you avoid the entire coordination problem with handleUpdate. A future PR can add multica-binary watching if there's demand, with the benefit of dogfooding on the simpler case first.

That answers your open questions 1 and 2: agent runtime binaries only, single flag (--auto-reload-agent-binaries or similar — the name should make the scope obvious).

Fingerprinting: prefer a content hash over the inode/mtime/size triple

The proposed triple is portable in theory but has known failure modes:

• mtime can be preserved by cp -p or rewound by package managers that restore timestamps; on Windows, FAT-family filesystems round mtime to 2-second granularity, so two upgrades within 2s look identical.
• size is unchanged by in-place patches (dd ... conv=notrunc, prelinking, codesign re-stamp on macOS).
• Inode swap catches atomic-rename installs (Homebrew, npm, mise) but Windows doesn't expose a stable inode equivalent through os.Stat.

For a binary that's typically tens of MB, a SHA-256 of the resolved path on a 30–60s tick is microseconds once it's in the page cache, requires no platform-specific code, and is robust against every replacement strategy I've seen. The fingerprint becomes: (resolved_path, sha256). If you want to keep the cost predictable, hash the first 64KB + last 64KB + size — that's enough to detect any real upgrade and runs in ~10µs from cache.

The symlink-target check is still worth keeping as a cheap pre-filter — if the symlink target hasn't changed, you can skip the hash entirely. But the hash should be the authoritative signal.

Required interlocks

These are non-negotiable for the implementation, not optional polish:

• Desktop-managed daemons must be a hard no-op. LaunchedBy == "desktop" already disables server-triggered self-update for the same reason — Electron owns the binary lifecycle. The watcher should refuse to start when LaunchedBy == "desktop", ideally with a single log line so users debugging stale-runtime issues know why the flag is ignored.
• Coordinate with d.updating. Even though the multica binary is out of scope, an agent-only watcher tick that fires during a server-triggered multica update could race with the restart handoff. Check d.updating.Load() and skip the tick.
• Debounce stable changes. Brew installs finish in milliseconds, but during make build or an active CI run, the binary can be rewritten repeatedly over several seconds. Require N consecutive ticks (or M seconds of fingerprint stability) before scheduling restart. 30s is plenty and avoids thrashing.

"Graceful" needs a definition

Your Alternative A says "wait for tasks to finish, then restart." Today activeTasks is decremented per task in handleTask — so for a long-running coding task this can mean hours. That's almost certainly the right v1 behavior since the flag is opt-in, but I'd be explicit in the docs that "graceful" can mean "indefinitely deferred." Once this goes default-on (your migration plan), you'll want a configurable max grace with a clearly logged warning before forcing.

Also: while waiting to drain, the daemon should stop claiming new tasks, as you noted. That's already structurally possible — pollLoop checks ctx — but it needs to be a deliberate state change ("reload pending → drain mode"), not just "we'll restart whenever active hits zero." Otherwise a constantly-busy daemon never drains.

Open questions — direct answers

1. Multica binary + agent CLIs, or agent only? Agent only for v1. (See above.)
2. One flag or two? One — --auto-reload-agent-binaries (or env equivalent). The two-flag split is premature until someone asks for multica-binary watching.
3. Full restart vs in-process re-register? Full restart for v1. The in-process path means rebuilding the runtime registry, re-issuing register/deregister to the server, invalidating agentVersions, and re-doing model-list catalog lookups — every one of those is a separate footgun. Full restart reuses code that's already been through the Daemon restart after self-update fails on Linux: os.Executable() returns deleted Cellar path #1624/fix(daemon): use brew prefix symlink for self-restart so Linux Cellar deletion does not orphan runtimes #2076 wringer.
4. Expose reload_pending in /health? Yes. Two fields: reload_pending: bool and reload_pending_reason: "agent CLI 'codex' changed". Cheap to add, makes the Desktop "restart recommended" UI trivial, and gives oncall a clear signal during incidents.
5. Max grace period for long-running tasks? For opt-in v1, no max — match the current daemon's "we never kill a task" contract. Add --auto-reload-grace=<duration> only when this becomes default-on, and default it to something forgiving (6h+).
6. Model list cache invalidation? No extra work needed if we go with full restart. handleModelList already shells out per request rather than caching, and agentVersions is rebuilt on registration. Worth a regression test, but no design change.

Suggested additions to the test plan

In addition to your list:

• updating interlock — while handleUpdate is mid-replace, a fake "agent CLI changed" signal must not schedule a competing restart.
• LaunchedBy=="desktop" no-op — flag set, binary fingerprint changes, no restart scheduled, log line emitted.
• Disappearing binary — agent CLI removed from PATH → fingerprint becomes "gone" → scheduled restart drops the runtime on next registration. (Without this, a brew uninstall codex followed by a daemon restart would still advertise codex.)
• Reappearing binary — agent CLI not present at startup → installed later → restart picks it up. Today LoadConfig only runs once.
• Debounce — N rapid fingerprint changes inside the debounce window schedule exactly one restart.
• macOS os.Executable() vs Linux /proc/self/exe — moot for v1 if multica binary is out of scope, but the test plan currently lists "Linuxbrew/Homebrew path test that keeps the fix(daemon): use brew prefix symlink for self-restart so Linux Cellar deletion does not orphan runtimes #2076 symlink behavior intact" which only applies to the multica binary. Drop it from the v1 plan and revisit when multica-binary watching lands.

Naming

--auto-reload-binaries is fine semantically but reads like a webdev hot-reload thing. Something like --reload-on-agent-cli-change or --watch-agent-cli is more honest about scope. Minor — bikeshed at PR time.

Net

The direction matches the right mental model. Narrow v1 to agent CLIs, use a content hash with a symlink pre-filter, respect LaunchedBy==desktop and d.updating, debounce, and surface reload_pending in /health. With that scoping I think this is a small, low-blast-radius PR that lands the real user value without re-litigating the #1624 territory.

[Bohan-J]

Quick decision update after thinking this through further.

Direction approved, with the following agreed shape for v1:

• Flag name: --auto-reload-on-version-change (env: MULTICA_DAEMON_AUTO_RELOAD=0 to disable).
• Default: on for CLI-launched daemons, hard no-op when LaunchedBy == "desktop".
• Scope: both the multica binary itself and every configured agent CLI. (Revising my earlier comment — once you factor in that CLI-launched daemons have no out-of-band update path at all, dropping the multica binary from v1 leaves half the actual user pain unsolved.)
• Fingerprint: poll --version output, not file stat. Reuses existing detectAgentVersion for agent CLIs; for the multica binary, run <restart_target> --version (where <restart_target> is the path triggerRestart() would exec — that's the Linuxbrew-safe path from fix(daemon): use brew prefix symlink for self-restart so Linux Cellar deletion does not orphan runtimes #2076, so we sidestep the os.Executable() Cellar problem entirely). Version-string comparison ignores harmless rebuilds and needs no debounce.
• Cadence: piggyback on the heartbeat loop, every N heartbeats (≈5 min). No new ticker goroutine.
• Action on change: set reload_pending → stop claiming new tasks → wait for activeTasks == 0 → reuse existing triggerRestart().
• Interlock: skip the tick while d.updating.Load() == true, so the new path never races a server-triggered handleUpdate.
• /health: add reload_pending bool and reload_pending_reason string (e.g. "codex version changed: 0.1.4 → 0.1.5").
• Out of scope for v1: daemon self-downloading a new version when upstream has one. That's a separate concern — it crosses the trust line of "daemon writes to user's filesystem" and needs signature/checksum/rollback work that this PR doesn't need. Worth tracking as a fast-follow that reuses this PR's drain+restart machinery.

Rough estimate: single file under server/internal/daemon/, ~150 LOC + 4-5 unit tests. Drain semantics make the default-on posture safe — in-flight tasks aren't interrupted; only new task claims pause until the restart completes.

@tangyuanjc — your RFC body says you weren't proposing a PR until maintainers confirmed the direction. Direction's confirmed. If you'd like to drive the PR, please go ahead — you've done all the discovery work and your trade-off analysis is already pointing the right way. If you'd rather hand it off, just say so and we'll pick it up. Either way, drop a note here so we don't double up.

[beastpu]

Hi @tangyuanjc — circling back since @Bohan-J handed off PR ownership to you on 2026-05-12 and I want to make sure we don't double up.

If you've stepped back from driving the v1 implementation, I'm happy to pick it up and follow the locked shape verbatim:

• --auto-reload-on-version-change flag (env MULTICA_DAEMON_AUTO_RELOAD=0 to disable)
• default-on for CLI-launched daemons; hard no-op when LaunchedBy == "desktop"
• both the multica binary and configured agent CLIs in scope, --version polling as the fingerprint
• piggyback on the heartbeat loop (~5 min cadence), no new ticker goroutine
• interlock: skip the tick while d.updating.Load() == true
• drain semantics: set reload_pending → stop claiming new tasks → wait for activeTasks == 0 → reuse existing triggerRestart()
• expose reload_pending and reload_pending_reason in /health

If you'd rather still drive it, totally fine — just drop a quick note here. Otherwise I'll start implementation in ~3 days (around 2026-06-12) and post the branch link back here when the PR is ready for review.