garrytan / garrytan/gstack

Codex design workflows report DESIGN_NOT_AVAILABLE due to broken fallback paths + missing design install surfaces

Open
#1,159 2 comments 1 reaction 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.