Codex design workflows report DESIGN_NOT_AVAILABLE due to broken fallback paths + missing design install surfaces
- Dominant language
- TypeScript
- Stars
- 133k
- Forks
- 19.9k
- Avg merge
- 18h 46m
- Merged PRs (30d)
- 26
Description
## Summary
Codex-hosted design skills can incorrectly report `DESIGN_NOT_AVAILABLE` even when the design binary exists. The failure comes from a combination of broken fallback path generation and missing `design` install surfaces in the Codex runtime.
## What breaks
There are three linked problems:
1. Generated fallback paths in Codex setup blocks prepend `$HOME` to env-var-backed paths like `$GSTACK_DESIGN` and `$GSTACK_BROWSE`, producing invalid doubled-home paths.
2. The Codex global runtime root does not expose `design/dist`, so even a correct fallback path has no global design binary to execute.
3. The repo-local `.agents/skills/gstack` sidecar also omits `design`, so the local-first resolution path fails in repos that have a sidecar install.
## Reproduction
Environment:
- gstack current `main`
- Codex host install
Observed from generated Codex design skill setup:
- fallback for `D` becomes `$HOME$GSTACK_DESIGN/design`
- fallback for `B` becomes `$HOME$GSTACK_BROWSE/browse`
In Codex, those env vars already resolve to absolute paths, so the resulting lookup becomes effectively:
- `/home/user/home/user/.codex/skills/gstack/design/dist/design`
- `/home/user/home/user/.codex/skills/gstack/browse/dist/browse`
That causes `DESIGN_NOT_AVAILABLE` / browse-unavailable behavior even when the underlying binary exists elsewhere.
## Root cause
Verified against current source:
- `scripts/resolvers/design.ts`
- `generateDesignSetup()` builds fallback with `$HOME${ctx.paths.designDir...}` and `$HOME${ctx.paths.browseDir...}`
- `generateDesignMockup()` builds fallback with `$HOME${ctx.paths.designDir...}`
- `scripts/resolvers/browse.ts`
- `generateBrowseSetup()` builds fallback with `$HOME${ctx.paths.browseDir...}`
- `hosts/codex.ts`
- Codex runtime assets include `bin`, `browse/dist`, `browse/bin`, `gstack-upgrade`, `ETHOS.md`, but not `design/dist`
- `setup`
- `create_codex_runtime_root()` does not link `design/dist`
- `create_agents_sidecar()` does not link `design`
So this is not just a generated text bug. It is generation drift plus install-surface drift.
## Expected behavior
For Codex installs:
- generated setup blocks should resolve valid fallback paths for both design and browse binaries
- `~/.codex/skills/gstack/design/dist/design` should exist after setup when design workflows are advertised
- repo-local `.agents/skills/gstack/design/dist/design` should exist when the sidecar is present
- `design-shotgun` preflight should return `DESIGN_READY` when the binary is installed
## Proposed fix
1. Fix shared resolver generation for env-var-backed host paths
- update `scripts/resolvers/design.ts`
- update `scripts/resolvers/browse.ts`
- do not prepend `$HOME` when the host path is already `$GSTACK_*`
2. Add `design/dist` to Codex runtime assets
- update `hosts/codex.ts`
3. Patch the actual install helpers in `setup`
- `create_codex_runtime_root()` should link `design/dist`
- `create_agents_sidecar()` should link `design`
4. Add regression coverage for:
- Codex host asset manifest includes `design/dist`
- generated Codex design setup has valid `D` and `B` fallbacks
- generated Codex browse setup does not emit `$HOME$GSTACK_BROWSE`
- setup helper coverage for both global runtime root and repo-local sidecar
## Why this matters
Right now Codex design workflows degrade into fallback not because the feature is optional, but because the generated/install paths are broken. That makes the host integration look unreliable even when the underlying binary exists.
I can send a PR for this from a fork if the maintainers want the fix bundled with regression tests.
Contributor guide
Assessment
This issue has not been assessed yet.