fix(relay): stream deploy logs and invalidate Docker placeholder cache

Docker rebuild left libbitfun_relay_service artifacts from the empty
placeholder crate, so relay-admin failed to find db/admin. Also make
detached deploy logs line-buffered and pollable so the wizard shows
progress while the remote build runs.

Author: bobleer

docs/superpowers/specs/2026-07-19-relay-deploy-log-and-docker-cache-design.md

@@ -0,0 +1,38 @@
+# Relay Deploy: Live Logs + Docker Cache Invalidation
+
+**Date:** 2026-07-19  
+**Status:** Approved for implementation
+
+## Problems
+
+1. Deploy wizard log pane stays empty until the remote task finishes or fails.
+2. Docker image rebuild fails with `cannot find db/admin in bitfun_relay_service`.
+
+## Root Causes
+
+1. Detached `nohup` redirects stdout to a file (full buffering); poll splitter is fragile on CRLF; frontend `setInterval` delays the first poll and can overlap.
+2. Dockerfile dependency-cache cleanup uses `deps/bitfun_relay_service*`, which does not match Cargo artifacts `libbitfun_relay_service-*`; the second build links the empty placeholder crate.
+
+## Design
+
+### Docker
+
+In `src/apps/relay-server/Dockerfile`, invalidate placeholder artifacts with globs `*bitfun_relay_service*`, `*bitfun_relay_server*`, `*relay_admin*`, remove matching `.fingerprint` dirs, and `touch` real sources before the second `cargo build`.
+
+### Live logs
+
+- Launch detached tasks with `stdbuf -oL -eL` when available.
+- Set `BUILDKIT_PROGRESS=plain` (and compose `--progress=plain` when supported).
+- Split poll stdout on `---\n`, `---\r\n`, or a trimmed `---` line.
+- Frontend: immediate first poll + serial `setTimeout` chain; seed a waiting line via i18n.
+
+### Out of scope
+
+- WebSocket log push / PTY
+- Configurable deploy git ref (default remains GitHub `main`)
+
+## Verification
+
+- Focused Rust check for `bitfun-services-integrations`
+- Web type-check
+- Local `docker compose build` for relay-server when feasible

src/apps/relay-server/Dockerfile

@@ -23,24 +23,35 @@ COPY src/apps/relay-server/Cargo.toml ./Cargo.toml
 COPY src/crates/services/relay-service/Cargo.toml ../../crates/services/relay-service/Cargo.toml
 
 # Build placeholders first so unchanged dependencies remain cached.
+# BuildKit exposes ARG as an env during RUN; cargo rejects CARGO_BUILD_JOBS="".
 RUN mkdir -p src/bin ../../crates/services/relay-service/src \
     && printf 'fn main() {}\n' > src/main.rs \
     && printf 'pub use bitfun_relay_service::*;\n' > src/lib.rs \
     && printf 'fn main() {}\n' > src/bin/relay_admin.rs \
     && printf '// placeholder\n' > ../../crates/services/relay-service/src/lib.rs \
+    && { [ -n "${CARGO_BUILD_JOBS:-}" ] || unset CARGO_BUILD_JOBS; } \
     && cargo build --release
 
+# Cargo emits libbitfun_relay_service-*.rlib/.rmeta — a bare bitfun_relay_service*
+# glob misses those and leaves the empty placeholder crate for the real rebuild.
 RUN rm -rf src ../../crates/services/relay-service/src \
     target/release/bitfun-relay-server \
     target/release/relay-admin \
-    target/release/deps/bitfun_relay_service* \
-    target/release/deps/bitfun_relay_server* \
-    target/release/deps/relay_admin*
+    target/release/deps/*bitfun_relay_service* \
+    target/release/deps/*bitfun_relay_server* \
+    target/release/deps/*relay_admin* \
+    target/release/.fingerprint/bitfun-relay-service-* \
+    target/release/.fingerprint/bitfun-relay-server-* \
+    target/release/.fingerprint/relay-admin-*
 
 COPY src/apps/relay-server/src/ ./src/
 COPY src/crates/services/relay-service/src/ ../../crates/services/relay-service/src/
 
-RUN if [ -n "${CARGO_BUILD_JOBS}" ]; then export CARGO_BUILD_JOBS; fi \
+RUN touch ../../crates/services/relay-service/src/lib.rs \
+        src/lib.rs \
+        src/main.rs \
+        src/bin/relay_admin.rs \
+    && { [ -n "${CARGO_BUILD_JOBS:-}" ] || unset CARGO_BUILD_JOBS; } \
     && cargo build --release \
     && (strip target/release/bitfun-relay-server target/release/relay-admin || true)
 

src/apps/relay-server/deploy.sh

@@ -87,9 +87,16 @@ else
     BUILD_ARGS+=(--build-arg "CARGO_BUILD_JOBS=${RELAY_CARGO_BUILD_JOBS}")
     echo "  Using CARGO_BUILD_JOBS=${RELAY_CARGO_BUILD_JOBS}"
   fi
+  # Plain progress so nohup/file-redirected deploys still stream build lines.
+  export BUILDKIT_PROGRESS="${BUILDKIT_PROGRESS:-plain}"
   # Do not pass --platform unless the user explicitly set DOCKER_DEFAULT_PLATFORM;
   # native builds on amd64/arm64 servers are the supported path.
-  compose build "${BUILD_ARGS[@]}"
+  # Compose V2 wants --progress as a global flag; legacy docker-compose has none.
+  if [ "${#COMPOSE[@]}" -ge 2 ] && [ "${COMPOSE[0]}" = "docker" ] && [ "${COMPOSE[1]}" = "compose" ]; then
+    docker compose --progress=plain build "${BUILD_ARGS[@]}"
+  else
+    compose build "${BUILD_ARGS[@]}"
+  fi
 fi
 
 echo "[2/2] Starting / recreating services..."

src/crates/services/services-integrations/src/remote_ssh/relay_deploy.rs

@@ -197,9 +197,12 @@ pub async fn start_task(
 
     // Detach fully: stdio redirected, stdin from /dev/null, so the SSH exec
     // channel closes immediately and the task survives disconnects.
+    // Prefer stdbuf line buffering so docker/cargo output reaches the log file
+    // while the task is still running (file redirects otherwise fully buffer).
     let launch = format!(
         "cd {dir} && chmod 700 {stem}.sh && rm -f {stem}.log {stem}.pid \
-         && nohup bash {stem}.sh > {stem}.log 2>&1 < /dev/null & echo $! > {stem}.pid"
+         && (command -v stdbuf >/dev/null 2>&1 && RUNNER='stdbuf -oL -eL bash' || RUNNER=bash) \
+         && nohup $RUNNER ./{stem}.sh > {stem}.log 2>&1 < /dev/null & echo $! > {stem}.pid"
     );
     exec_ok(manager, connection_id, &launch).await?;
     Ok(())
@@ -236,10 +239,7 @@ if [ -f "$LOG" ]; then tail -c +{from} "$LOG"; fi
     if code != 0 {
         return Err(anyhow!("poll failed (exit {code})"));
     }
-    let (head, output) = match stdout.split_once("---\n") {
-        Some((h, o)) => (h, o.to_string()),
-        None => (stdout.as_str(), String::new()),
-    };
+    let (head, output) = split_poll_stdout(&stdout);
     let get = |key: &str| -> String {
         head.lines()
             .find_map(|l| l.strip_prefix(key).and_then(|v| v.strip_prefix('=')))
@@ -259,11 +259,32 @@ if [ -f "$LOG" ]; then tail -c +{from} "$LOG"; fi
     };
     Ok(RelayTaskPoll {
         cursor: size,
-        output,
+        output: output.to_string(),
         status,
     })
 }
 
+/// Split poll script stdout into the metadata head and incremental log body.
+///
+/// Accepts LF, CRLF, or a standalone `---` line so SSH/OS line endings cannot
+/// drop the entire log payload.
+fn split_poll_stdout(stdout: &str) -> (&str, &str) {
+    if let Some((head, output)) = stdout.split_once("---\r\n") {
+        return (head, output);
+    }
+    if let Some((head, output)) = stdout.split_once("---\n") {
+        return (head, output);
+    }
+    let mut offset = 0usize;
+    for line in stdout.split_inclusive('\n') {
+        if line.trim_end_matches(['\r', '\n']) == "---" {
+            return (&stdout[..offset], &stdout[offset + line.len()..]);
+        }
+        offset += line.len();
+    }
+    (stdout, "")
+}
+
 /// Import a locally-provisioned account into the running relay container.
 ///
 /// `account_json` is the serialized `ImportableAccount` produced client-side
@@ -415,13 +436,42 @@ if [ "${{RELAY_CARGO_BUILD_JOBS:-}}" = "" ] && [ "$MEM_KB" -lt 2097152 ]; then
   export RELAY_CARGO_BUILD_JOBS=1
   echo ">>> Low memory detected; using RELAY_CARGO_BUILD_JOBS=1"
 fi
+# Stream BuildKit lines into the detached log file (avoid fancy TTY progress).
+export BUILDKIT_PROGRESS=plain
 echo ">>> Building and starting the relay container (this can take a while)..."
 if [ "$DOCKER" = "sudo docker" ]; then
-  sudo -E env RELAY_CARGO_BUILD_JOBS="${{RELAY_CARGO_BUILD_JOBS:-}}" bash deploy.sh
+  sudo -E env RELAY_CARGO_BUILD_JOBS="${{RELAY_CARGO_BUILD_JOBS:-}}" \
+    BUILDKIT_PROGRESS=plain bash deploy.sh
 else
   bash deploy.sh
 fi
 echo {TASK_DONE_MARKER}
 "#
     )
 }
+
+#[cfg(test)]
+mod tests {
+    use super::split_poll_stdout;
+
+    #[test]
+    fn split_poll_stdout_accepts_lf() {
+        let (head, out) = split_poll_stdout("running=1\nsize=12\nmarker=0\n---\nhello\n");
+        assert!(head.contains("running=1"));
+        assert_eq!(out, "hello\n");
+    }
+
+    #[test]
+    fn split_poll_stdout_accepts_crlf() {
+        let (head, out) = split_poll_stdout("running=1\r\nsize=12\r\nmarker=0\r\n---\r\nworld\r\n");
+        assert!(head.contains("running=1"));
+        assert_eq!(out, "world\r\n");
+    }
+
+    #[test]
+    fn split_poll_stdout_missing_marker_yields_empty_body() {
+        let (head, out) = split_poll_stdout("running=0\nsize=0\nmarker=0\n");
+        assert!(head.contains("running=0"));
+        assert_eq!(out, "");
+    }
+}

src/web-ui/src/features/relay-deploy/RelayDeployWizard.tsx

@@ -113,7 +113,8 @@ export const RelayDeployWizard: React.FC<RelayDeployWizardProps> = ({
   const [activeTask, setActiveTask] = useState<RelayDeployTask | null>(null);
   const [taskLog, setTaskLog] = useState('');
   const [taskStatus, setTaskStatus] = useState<RelayTaskStatus | null>(null);
-  const pollRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  const pollRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const pollActiveRef = useRef(false);
   const cursorRef = useRef(0);
   const pollFailuresRef = useRef(0);
   const logViewRef = useRef<HTMLPreElement>(null);
@@ -131,8 +132,9 @@ export const RelayDeployWizard: React.FC<RelayDeployWizardProps> = ({
   const relayUrl = `http://${serverHost}:${RELAY_PORT}`;
 
   const stopPolling = useCallback(() => {
+    pollActiveRef.current = false;
     if (pollRef.current) {
-      clearInterval(pollRef.current);
+      clearTimeout(pollRef.current);
       pollRef.current = null;
     }
   }, []);
@@ -352,17 +354,34 @@ export const RelayDeployWizard: React.FC<RelayDeployWizardProps> = ({
   }, [t]);
 
   // ── task polling ─────────────────────────────────────────────────────────
+  // Serial setTimeout chain (not setInterval): immediate first poll, no overlap
+  // when an SSH round-trip takes longer than POLL_INTERVAL_MS.
   const startTaskPolling = useCallback((task: RelayDeployTask, connId: string) => {
     stopPolling();
     cursorRef.current = 0;
     pollFailuresRef.current = 0;
-    pollRef.current = setInterval(async () => {
+    pollActiveRef.current = true;
+
+    const scheduleNext = () => {
+      if (!pollActiveRef.current) return;
+      pollRef.current = setTimeout(() => {
+        void tick();
+      }, POLL_INTERVAL_MS);
+    };
+
+    const tick = async () => {
+      if (!pollActiveRef.current) return;
       try {
         const res = await relayDeployApi.poll(connId, task, cursorRef.current);
+        if (!pollActiveRef.current) return;
         cursorRef.current = res.cursor;
         pollFailuresRef.current = 0;
         if (res.output) {
-          setTaskLog((prev) => (prev + res.output).slice(-MAX_LOG_CHARS));
+          setTaskLog((prev) => {
+            const waiting = t('relayDeploy.waitingRemoteOutput');
+            const base = prev === waiting ? '' : prev;
+            return (base + res.output).slice(-MAX_LOG_CHARS);
+          });
         }
         if (res.status !== 'running') {
           stopPolling();
@@ -375,25 +394,31 @@ export const RelayDeployWizard: React.FC<RelayDeployWizardProps> = ({
               window.setTimeout(() => setStep('register'), 800);
             }
           }
+          return;
         }
       } catch (e) {
         // Transient SSH blips are expected (the manager auto-reconnects);
         // only give up after repeated failures.
+        if (!pollActiveRef.current) return;
         pollFailuresRef.current += 1;
         log.warn('task poll failed', e);
         if (pollFailuresRef.current >= MAX_POLL_FAILURES) {
           stopPolling();
           setTaskStatus('failed');
           setTaskLog((prev) => `${prev}\n[poll] ${errMsg(e)}`);
+          return;
         }
       }
-    }, POLL_INTERVAL_MS);
-  }, [runPreflight, stopPolling]);
+      scheduleNext();
+    };
+
+    void tick();
+  }, [runPreflight, stopPolling, t]);
 
   const handleInstallDocker = async () => {
     if (!connectionId) return;
     setError(null);
-    setTaskLog('');
+    setTaskLog(t('relayDeploy.waitingRemoteOutput'));
     setTaskStatus('running');
     setActiveTask('install_docker');
     try {
@@ -409,7 +434,7 @@ export const RelayDeployWizard: React.FC<RelayDeployWizardProps> = ({
     if (!connectionId) return;
     setError(null);
     setStep('deploy');
-    setTaskLog('');
+    setTaskLog(t('relayDeploy.waitingRemoteOutput'));
     setTaskStatus('running');
     setActiveTask('deploy');
     try {

src/web-ui/src/locales/en-US/common.json

@@ -590,6 +590,7 @@
     "startDeploy": "Start Deployment",
     "deployingTitle": "Deploying relay server…",
     "deployingHint": "The first build compiles Rust in Docker and can take several minutes. The deployment continues on the server even if you close this window.",
+    "waitingRemoteOutput": "Waiting for remote output…",
     "deploySucceeded": "Deployment succeeded",
     "deployFailed": "Deployment failed",
     "retry": "Retry",

src/web-ui/src/locales/zh-CN/common.json

@@ -590,6 +590,7 @@
     "startDeploy": "开始部署",
     "deployingTitle": "正在部署 relay server…",
     "deployingHint": "首次构建需要在 Docker 中编译 Rust，可能持续几分钟。即使关闭本窗口，部署也会在服务器上继续进行。",
+    "waitingRemoteOutput": "正在等待远端输出…",
     "deploySucceeded": "部署成功",
     "deployFailed": "部署失败",
     "retry": "重试",

src/web-ui/src/locales/zh-TW/common.json

@@ -590,6 +590,7 @@
     "startDeploy": "開始部署",
     "deployingTitle": "正在部署 relay server…",
     "deployingHint": "首次建構需要在 Docker 中編譯 Rust，可能持續幾分鐘。即使關閉本視窗，部署也會在伺服器上繼續進行。",
+    "waitingRemoteOutput": "正在等待遠端輸出…",
     "deploySucceeded": "部署成功",
     "deployFailed": "部署失敗",
     "retry": "重試",