[bug] `~/.superset/bin/superset` shim execs into a per-launch AppImage mount, so scripted callers break with exit 127 after every app restart

[maxence-lefebvre]

Summary

On Linux (AppImage), ~/.superset/bin/superset is a generated shim:

#!/bin/sh
# Superset bundled CLI shim v1
exec '/tmp/.mount_Superss<random>/resources/resources/bin/superset' "$@"

The mount point is per-launch: it changes every time the app starts and disappears
when the app exits, but the shim is only rewritten on the next app start. Any
non-interactive caller that runs between boot and the app's own startup (cron, a
systemd --user unit, a login script) dies with exit 127 (exec: ... not found)
rather than a diagnosable error.

Concretely: a systemd --user timer with Persistent=true replays a missed 07:00
automation about 40s after the user manager starts at boot. At that moment the shim
still points at the previous boot's mount, so the unit fails instantly with 127,
before it can reach any retry logic. And because systemd writes the persistence stamp
on the fire, the run is never replayed: the automation silently loses the day.

Repro

1. Linux, Superset desktop AppImage, CLI 1.24.2.
2. cat ~/.superset/bin/superset and note the /tmp/.mount_Superss<random> path.
3. Quit the app (or reboot) so that mount goes away; do not relaunch.
4. ~/.superset/bin/superset --version fails with exec: /tmp/.mount_.../superset: not found, exit 127.

Expected

Resolve the real binary at call time instead of baking in a launch-scoped path.
For example, exec a stable copy kept under ~/.superset/, or discover the mount from
the running host service. If it genuinely can't find a binary, exit with a distinct
code and a clear "Superset app is not running" message so wrappers can tell "app not
up yet" apart from "command is broken".

Environment

• CLI 1.24.2, Linux x86_64, AppImage (~/Desktop/Superset-x86_64.AppImage)

[github-actions]

Summary

The report is consistent with the code: on Linux the desktop app only ships as an AppImage, and the bundled-CLI shim it writes to ~/.superset/bin/superset hard-codes process.resourcesPath, which for an AppImage is a per-launch squashfs mount under /tmp/.mount_*. The shim is (re)written once per app start, so between the mount going away (app quit / reboot) and the next app start, the shim points at a path that no longer exists. Because the shim is a bare exec with no fallback and no diagnostics, /bin/sh fails with exec: ...: not found and exit 127 — the same signal as "command doesn't exist" — which is exactly what makes it undiagnosable for a non-interactive caller like a systemd --user timer firing at boot.

Affected code

• apps/desktop/src/main/lib/bundled-cli.ts:62-74 — getBundledCliCandidates(); the packaged branch (:65-67) resolves path.join(process.resourcesPath, "resources/bin", binaryName).
• apps/desktop/src/main/lib/bundled-cli.ts:46-60 — buildBundledCliShim() bakes that absolute path into exec '<path>' "$@" at write time.
• apps/desktop/src/main/lib/bundled-cli.ts:104-135 — installBundledCliShim() writes it to ~/.superset/bin/superset (getBinDir(), packages/agent-setup/src/paths.ts:18-20).
• apps/desktop/src/main/index.ts:512-516 — called exactly once, during app startup. Nothing rewrites the shim while the app is not running.
• apps/desktop/electron-builder.ts:149-155 — Linux target is ["AppImage"] only, so on Linux process.resourcesPath is always launch-scoped.

The double resources/resources/bin in the reported shim matches path.join(process.resourcesPath, "resources/bin") under an AppImage (resourcesPath = $APPDIR/resources, extraResources maps dist/resources/bin → resources/bin, electron-builder.ts:77-81), which is good evidence the paste is real rather than reconstructed.

Suspected root cause

Two distinct defects stacked:

1. Launch-scoped path baked at write time. The shim records where the binary was this launch instead of resolving it at call time. On macOS/Windows the baked path happens to be stable across restarts (/Applications/..., install dir), so the bug is effectively Linux/AppImage-specific — though the same shim also goes stale on macOS if the user moves or renames the .app bundle, until the next launch.
2. No failure diagnostics. exec on a missing target yields a shell-level 127 with no Superset-attributable message. Worth noting the repo already has the pattern the issue asks for, one package over: buildWrapperScript() in packages/agent-setup/src/agent-wrappers-common.ts:154-175 resolves the real binary at call time via find_real_binary and, on failure, prints Superset: <name> not found in PATH... to stderr before exit 127. The bundled-CLI shim just never adopted it.

I'd push back on part of the suggested fix: "discover the mount from the running host service" doesn't address the reported scenario. When cron or a boot-time timer fires and the app isn't running, there is no mount to discover — the binary genuinely doesn't exist on disk anywhere outside the AppImage. Only a copy kept outside the mount makes the CLI callable when the app is down.

A trap for the obvious fix: shouldReplaceShim() (bundled-cli.ts:86-102) only returns true when BUNDLED_CLI_SHIM_MARKER appears in the first 2048 bytes, and returns false for anything that isn't a regular file. So if a fix copies the real Bun-compiled binary to ~/.superset/bin/superset, or symlinks it there, the app will thereafter classify its own artifact as unmanaged and return "skipped" (:118-123) — the CLI would never be updated again. The marker-bearing shim needs to stay at that path; the stable copy belongs elsewhere.

Reproduction

Manual, matching the report: launch the AppImage, cat ~/.superset/bin/superset to note the /tmp/.mount_* path, quit the app, then ~/.superset/bin/superset --version; echo $? → 127.

As a regression test in apps/desktop/src/main/lib/bundled-cli.test.ts (the existing suite already builds a fake binary in a temp dir, so this drops in):

it("keeps working after the launch-scoped resources dir disappears", () => {
  const mount = mkdtempSync(path.join(tmpdir(), ".mount_Superss"));
  const cli = path.join(mount, "resources/resources/bin/superset");
  mkdirSync(path.dirname(cli), { recursive: true });
  writeFileSync(cli, "#!/bin/sh\necho 1.24.2\n", { mode: 0o755 });

  installBundledCliShim({ binDir, bundledCliPath: cli, platform: "linux" });
  rmSync(mount, { recursive: true, force: true }); // app quit → AppImage unmounted

  const result = spawnSync(path.join(binDir, "superset"), ["--version"]);
  expect(result.status).toBe(0); // today: 127, stderr "exec: ...: not found"
});

A cheaper unit-level assertion for the same thing: buildBundledCliShim("/tmp/.mount_x/resources/resources/bin/superset", "linux") should not contain /tmp/.mount_.

Suggested fix direction

1. On app start, copy the bundled binary to a version-keyed stable location under the Superset home, e.g. ~/.superset/cli/<app-version>/superset, written to a temp name and renameSyncd into place so a concurrent caller never sees a partial file. Skip the copy when the target already exists (keeps startup cheap), and prune older version dirs — the Bun-compiled binary is tens of MB, so unbounded accumulation matters.
2. Change the shim body to resolve at call time, in priority order: $SUPERSET_CLI_BIN (escape hatch), the stable copy, then the baked in-bundle path as a last resort. If none is executable, write a distinct message to stderr (Superset CLI binary not found — the Superset app may not be installed or has not been launched since install.) and exit with a reserved code distinguishable from 127 so wrappers can branch on it. Mirror this in the win32 .cmd branch of buildBundledCliShim().
3. Scoping the copy step to platform === "linux" first is defensible: packages/cli/src/lib/env.ts:14-22 notes the bundled CLI "lives inside the signed .app", and copying a signed Mach-O out of the bundle deserves its own thought about codesigning/quarantine before shipping. The call-time resolution and the clear error message can land for all platforms regardless, since they're pure shim-content changes.
4. If the copy lands, shouldReplaceShim() stays correct as-is — but any patch that instead points ~/.superset/bin/superset at a non-shim file needs to update that function in the same change, or CLI updates silently stop.