# Troubleshooting execution readiness

Use this page when RCS appears installed but real Codex execution still fails.

## Install success vs real execution success

`rcs setup` and `rcs doctor` validate RCS's local install surface: prompts, skills, AGENTS scaffolding, config files, hooks, and runtime prerequisites. They do not guarantee that the active Codex profile can authenticate and complete a model request.

After `rcs doctor`, run a real smoke test from the same shell, HOME, and project directory you will use for RCS:

```bash
codex login status
rcs exec --skip-git-repo-check -C . "Reply with exactly RCS-EXEC-OK"
```

Treat the boundary this way:

- Codex plugin install/discovery may cache `roblox-ai-os-creator-skills` under `${CODEX_HOME:-~/.codex}/plugins/cache/$MARKETPLACE_NAME/roblox-ai-os-creator-skills/$VERSION/` (with `local` possible as a version identifier for local installs). That confirms a marketplace/plugin artifact; the packaged plugin includes plugin-scoped companion metadata for MCP servers and apps, while native/runtime hooks remain setup-owned, so it is still not the full RCS runtime setup.
- Plugin install/discovery is not a replacement for `npm install -g @jstn-sdk/rcs` plus `rcs setup`; legacy setup mode installs native agents and prompts, while plugin setup mode relies on plugin discovery for bundled skills and archives/removes legacy RCS-managed prompts/native-agent TOMLs so stale role files cannot shadow plugin behavior.
- `rcs doctor` green: install and local runtime wiring look sane.
- `codex login status` green: the active Codex profile can see login state.
- `rcs exec ...` returns `RCS-EXEC-OK`: real execution, auth, provider routing, and current working-directory assumptions are working together.

## Green doctor, but `rcs exec` fails with auth errors

Common failure strings include `401 Unauthorized`, `Missing bearer or basic authentication in header`, or `Incorrect API key provided`.

Check the active runtime profile, not only your normal login shell:

1. Print `HOME` and `CODEX_HOME` in the shell that launches RCS.
2. Confirm that the active `~/.codex` or `CODEX_HOME` contains the expected auth and `config.toml`.
3. Re-run `codex login status` from that same shell.

Custom HOME, container, profile, CI, and service-user environments often have a different `~/.codex` from the machine's main user. A working Codex setup in one home does not automatically make another home ready.

## Local proxy or `openai_base_url` mismatch

If your setup depends on an OpenAI-compatible local proxy or gateway, verify that the active runtime config contains the matching base URL:

```toml
openai_base_url = "http://localhost:8317/v1"
```

Use your actual proxy URL. If the profile-local `~/.codex/config.toml` is missing `openai_base_url`, Codex may send the proxy-issued key to the default endpoint. That can make setup and doctor look fine while real execution fails with 401-style auth errors.

## Stale `doctor --team` or dead tmux session state

`rcs doctor --team`, `rcs team resume`, or startup diagnostics can fail when a previous team state references a tmux session that no longer exists. The state may mention `resume_blocker`, or the dead session may be recorded under `.rcs/state/team/<team-name>/config.json` or `manifest.v2.json`.

If the team is intentionally abandoned and no live tmux session remains, clean it up with:

```bash
rcs team shutdown <team-name> --force --confirm-issues
rcs cancel
rcs doctor --team
```

Do not force-shutdown a team that may still have useful live panes or worker state. Prefer `rcs team status <team-name>` and `tmux ls` first when unsure.

## Shift+Enter submits instead of inserting a newline in tmux-backed RCS sessions

This is usually **not** a net-new RCS feature gap.

RCS already carries the tmux-side preservation work from issue `#1271` / PR `#1273` (`4405f582`, “Preserve Shift+Enter inside tmux-backed RCS launches”), and current `dev` still enables tmux `extended-keys=always` around RCS-owned Codex launch paths:

- in-tmux launches wrap Codex with `withTmuxExtendedKeys(...)` in `src/cli/index.ts`
- detached tmux launches acquire the same protection through the detached leader bootstrap/cleanup path in `src/cli/index.ts`
- regression tests still cover the enable/restore/lease behavior in `src/cli/__tests__/index.test.ts`

So if `Shift+Enter` still behaves like plain `Enter`, the narrowest likely causes are:

1. **tmux is not actually forwarding extended keys for the reporter's terminal path**
   - tmux only forwards the richer key event when the attached terminal is detected as supporting extended keys
   - `tmux show -gv extended-keys` can say `always`, but forwarding can still fail if the terminal capability is missing or not detected
2. **the reporter is not in the RCS-owned tmux launch path**
   - for example, reproducing in a different pane/session than the one RCS launched or after attaching through a different client path
3. **terminal-specific capability mismatch**
   - some terminals need an explicit tmux `terminal-features` hint for `extkeys`

### Operator checks

Run these from the same tmux client/session where the failure happens:

```bash
tmux show -gv extended-keys
tmux info | grep extkeys
tmux show -gv terminal-features
printf '%s\n' "$TERM" "$TERM_PROGRAM"
```

Expected first check: `always` while RCS is actively running Codex in that tmux-managed path.

If `extended-keys` is **not** `always` during the failing session, that points to an RCS launch-path bug/regression.

If `extended-keys` **is** `always`, but `Shift+Enter` still submits, the likely problem is terminal capability discovery or upstream Codex terminal-input interpretation rather than RCS submission logic.

### Typical environment fix

If your terminal supports extended keys but tmux does not detect it automatically, add an `extkeys` feature hint in `~/.tmux.conf` and restart tmux:

```tmux
set -as terminal-features ',xterm-256color:extkeys'
```

Adjust the terminal pattern if your client advertises a different terminfo name.

### Maintainer triage guidance

- **Open a code fix** only if you can show current `dev` fails to set `extended-keys=always` on the live RCS-owned tmux launch path.
- **Close as environment limitation** if current `dev` sets the tmux option correctly but the reporter's terminal path still does not forward the richer key event.
- **Prefer a docs follow-up** when the root problem is discoverability/operator guidance rather than a broken RCS codepath.

## `rcs explore` fallback boundaries

`rcs explore` has two intentionally bounded fallback paths:

- **Sparkshell backend fallback**: qualifying shell-native prompts (for example `git log --oneline`) try `rcs sparkshell` first. If that backend is unavailable or incompatible, stderr reports `sparkshell backend unavailable ... Falling back to the explore harness` before the harness runs.
- **Model fallback inside the explore harness**: the harness tries the configured spark model first and then the configured fallback/standard model only if spark fails. This changes the cost/behavior boundary, so stderr emits structured attempt metadata such as `fallback-attempt=model from=... to=... reason=spark_attempt_failed exit=...`. The stdout notice `## RCS Explore fallback` is emitted only after successful fallback output.

A harness limitation is different from fallback. If the harness cannot answer safely (unsupported platform, missing native binary for a packaged install, missing Rust toolchain in a checkout, or a non-shell-only task), it should report the limitation and stop or ask the caller to use the richer normal path; it should not silently broaden tools or model behavior.