stack/docs/scratchpads/fleet-standup-fixes.md

Fleet stand-up fixes — model_hint→--model + socket-default trap (#626)

• Issue: #626 · Branch: feat/fleet-standup-fixes (off main). PoC-blocking, before doctrine doc.

FIX 1 — model_hint consumed

• generateAgentEnv emits MOSAIC_AGENT_MODEL=<modelHint> (bare empty when unset).
• start-agent-session.sh default command → mosaic yolo $RUNTIME ${MOSAIC_AGENT_MODEL:+--model $MOSAIC_AGENT_MODEL}. → pi workers launch with --model openai-codex/gpt-5.5:high.

FIX 2 — socket default trap (absent ⇒ literal default socket, no -L everywhere)

• THE TRAP (3 sites): parseRosterText fallback was DEFAULT_SOCKET_NAME; systemd unit had Environment=MOSAIC_TMUX_SOCKET=mosaic-factory + ExecStop ${…:-mosaic-factory}; start-agent-session defaulted :-mosaic-factory. All fixed → absent socket = '' = default tmux socket (no -L).
• socketArgs(name) helper → name ? ['-L', name] : []; replaced all ~15 -L render sites in fleet.ts.
• shellEnvValue('') now emits a bare VAR= (not '') — unambiguous empty in systemd EnvironmentFile (a quoted '' could become a literal socket named "''").
• start-agent-session.sh: _tmux wrapper passes -L only when socket set; mosaic-agent@.service: dropped the socket default + conditional ExecStop. So spawn == observe == onboarding cheat-sheet.
• CONTAINMENT: all 6 shipped presets set socket_name: mosaic-factory explicitly → unaffected; only socket-less rosters (the PoC) get default-socket behavior. DEFAULT_SOCKET_NAME exported for explicit use.

Verification

• 158 fleet + 201 fleet-adjacent tests green; new: socketArgs none/named, model_hint→env, explicit-socket renders -L, socket-less env bare. tsc/eslint/prettier/sanitize clean. Shell bash -n + end-to-end sim (socket-less→no -L, model→--model).