orchestration sometimes picks the wrong tab

[danshapiro]

Summary

freshell orchestration can create/split panes in the wrong tab when commands target the wrong Freshell instance and rely on implicit active-tab behavior.

In my run, I asked the agent to open AGENTS.md in "this tab". The command succeeded, but the pane appeared in a different tab than the one the user was looking at.

User Scenario

A user is working in one Freshell tab and asks an agent to open a file in the current tab. The user expects the file to appear beside their current terminal pane.

The agent issues a valid CLI split/open command, but the pane appears in another tab (or another Freshell window/instance), causing confusion and follow-up debugging.

Impact

• User-facing behavior is surprising and feels flaky.
• Agent appears unreliable even though command responses are status: ok.
• Can lead to accidental edits or navigation in the wrong context.

Reproduction

I could reproduce this with two concurrent Freshell instances.

1. Have one terminal session running with inherited runtime env:
   • FRESHELL_URL=http://localhost:3002
   • FRESHELL_TAB_ID=<current-tab-id>
   • FRESHELL_PANE_ID=<current-pane-id>
2. In orchestration, export URL/token from repo .env (this pointed to http://localhost:3001 in my case).
3. Run a pane mutation without explicit target, e.g.:
   • split-pane --editor /home/user/code/freshell/AGENTS.md
4. Observe command returns success and a new pane id.
5. Observe pane was created in whichever tab is active in the 3001 instance, not in the user’s current tab in 3002.

Expected

When a user asks for "open in this tab", orchestration should mutate the tab/pane associated with the current terminal session.

Actual

Command succeeded against another Freshell instance and used implicit active-tab routing there, so pane landed in the wrong tab.

Technical Root Cause

Two issues combine:

1. Instance selection mismatch

   • Orchestration setup often exports FRESHELL_URL/FRESHELL_TOKEN from repo .env.
   • In multi-instance setups, runtime env for the current pane can point elsewhere (e.g., :3002), while .env points to a different server (e.g., :3001).

2. Implicit tab targeting

   • Commands like split-pane without -t use server-side active tab.
   • If you are connected to the wrong instance, active tab is the wrong UI context.

What We Learned

• "Active tab" is instance-local; it is not globally "the tab I am looking at".
• For pane mutations, explicit targeting is required for reliability.
• Runtime env (FRESHELL_URL, FRESHELL_TAB_ID, FRESHELL_PANE_ID) is the best source of truth for "here".

Proposed Fixes

Orchestration skill/docs

• Prefer inherited runtime FRESHELL_URL/FRESHELL_TOKEN if present.
• Fall back to repo .env only when runtime env is absent.
• For pane mutations (split-pane, send-keys, capture-pane, etc.), require explicit -t, preferring FRESHELL_PANE_ID.
• Add a preflight check:
  • if FRESHELL_TAB_ID exists, verify target with list-panes -t "$FRESHELL_TAB_ID" --json before mutating.

CLI ergonomics (optional)

• Add a --here/--current-pane mode that automatically targets FRESHELL_PANE_ID when available.
• Warn when command uses implicit active tab and runtime FRESHELL_PANE_ID exists.

Concrete Recovery That Worked

Using runtime env and explicit pane target resolved it immediately:

split-pane -t "$FRESHELL_PANE_ID" --editor /home/user/code/freshell/AGENTS.md

This created the pane in the actual current tab.