Skip the Aside readiness probe on Linux and Windows and select the fallback browser directly
- Dominant language
- TypeScript
- Stars
- 133k
- Forks
- 19.9k
- Avg merge
- 18h 46m
- Merged PRs (30d)
- 26
Description
## Summary
Every browsing skill starts with the BROWSER SETUP block from `{{ASIDE_SETUP}}` and runs the Aside readiness probe before any browser step. Aside only ships for macOS 15+, so on Linux and Windows `command -v aside` always misses, the block always prints `NEEDS_ASIDE`, and the skill always continues into the Browser fallback section and drives `$B`.
That ending is correct, so this isn't a bug report. The ask is smaller: let the probe check the platform first, so a Linux or Windows host picks the fallback browser directly instead of getting there by way of a check that only makes sense on a Mac.
## What happens today
`scripts/resolvers/aside.ts:76-86` renders the probe with no platform condition:
```bash
if [ "${GSTACK_SKIP_ASIDE:-}" = "1" ] || ! command -v aside >/dev/null 2>&1; then
echo "NEEDS_ASIDE"
elif $_T aside repl 'console.log("ASIDE_READY " + pwd)' 2>&1 | grep -q '^ASIDE_READY'; then
echo "READY: aside $(aside --version 2>/dev/null)"
else
echo "ASIDE_NOT_RUNNING"
fi
```
The platform does get checked, just one step later. Line 88, handling the `NEEDS_ASIDE` result:
> `NEEDS_ASIDE`: if `uname -s` prints `Darwin`, tell the user once — "gstack works best with the Aside browser (macOS 15+) [...]". Off macOS, do not pitch it.
So `uname -s` decides whether to pitch the download, but not whether to run the probe in the first place.
`probeAside()` in `lib/aside-render.ts:74-92` has the same shape. It checks `GSTACK_SKIP_ASIDE`, spawns `aside --version`, then `aside repl`, with no `process.platform` check anywhere.
## What I see on Linux
gstack 1.84.1.0, the BROWSER SETUP snippet from `browse/SKILL.md` pasted verbatim:
```
$ uname -s
Linux
$
NEEDS_ASIDE
$ command -v aside
(nothing; Aside has no Linux build)
```
Same output on every run.
## Why bother
`command -v` fails fast, so there is no measurable time in this. What it costs is instruction budget and a transcript that reads wrong:
- The block is rendered into 20 skills: `benchmark browse canary cso design-consultation design-review devex-review investigate land-and-deploy office-hours plan-ceo-review plan-devex-review plan-eng-review qa qa-only review scrape setup-deploy ship spec`. Each browsing run on Linux or Windows spends a bash call on a question whose answer cannot change.
- The `ASIDE_NOT_RUNNING` branch tells the agent to ask the user to open the Aside app and re-run. That can never apply off macOS, but it sits in the context every time.
- `NEEDS_ASIDE` followed by a fallback reads as though something is missing from the machine. On Linux nothing is missing; the fallback is the only path there is.
`GSTACK_SKIP_ASIDE=1` already produces the behaviour I want, but you have to know it exists and set it in every environment. A platform check would cover the one case where skipping is never the wrong call.
## Proposal
Check the platform in both places and leave the macOS path alone.
`generateAsideSetup` in `scripts/resolvers/aside.ts`:
```bash
if [ "$(uname -s)" != "Darwin" ] || [ "${GSTACK_SKIP_ASIDE:-}" = "1" ] || ! command -v aside >/dev/null 2>&1; then
echo "NEEDS_ASIDE"
elif ...
```
`probeAside` in `lib/aside-render.ts`, before the first spawn:
```ts
if (process.platform !== 'darwin') {
return { ok: false, reason: 'NEEDS_ASIDE', detail: 'Aside is macOS 15+ only; using the bundled browser' };
}
```
On macOS nothing changes: Aside first, `READY` and `ASIDE_NOT_RUNNING` both still reachable, and the zsh fix in #2824 / #2854 lands on top of this without conflict. On Linux and Windows the skill goes to `$B` directly, with a reason the user can read. `GSTACK_SKIP_ASIDE=1` keeps working as the manual override on macOS.
The `NEEDS_ASIDE` result name and the fallback contract do not move, so `{{BROWSE_FALLBACK}}` stays as it is and the detection and never-install sentences pinned by `test/aside-driver.test.ts` are preserved.
Dropping the Aside contract text entirely from non-macOS renders would save more, since none of it is actionable there, but that is a much bigger change to the generator and I am not asking for it here.
## Not the zsh reports
#2842, and PRs #2824 / #2854, cover the opposite situation: Aside installed and running on macOS, probe reporting `ASIDE_NOT_RUNNING` because `$_T` is not word-split under zsh. That is a false negative worth fixing. This is about not asking the question on hosts where the answer is fixed. Both changes touch the same block and do not collide.
Happy to send a PR if this shape looks right.
## Environment
- gstack 1.84.1.0
- Linux, bash
- Aside not installed (no Linux build exists)
Contributor guide
Research direction
Start with the probe generation in scripts/resolvers/aside.ts:76-86 and the runtime probe in lib/aside-render.ts:74-92, then read test/aside-driver.test.ts for the preserved detection and fallback expectations. Verify that non-macOS hosts select the bundled browser directly while macOS retains the existing Aside paths and GSTACK_SKIP_ASIDE override.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- bash, typescript
- Domain
- cli, tooling
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 76/100