test(docs): clarify and cover multi-session semantics

- Document in-pane CQ_SESSION behavior vs ask --session targeting\n- Add tests for env vs explicit session precedence and fallback semantics

Author: stefanc-ai2

.beads/issues.jsonl

@@ -7,7 +7,7 @@
 {"id":"claude_code_bridge-4.5","title":"ask: add --session and route using session-scoped session files","description":"Make `ask` able to target a specific session.\n\n## Scope\n- Add `--session \u003cname\u003e` to `bin/ask` (default from `CQ_SESSION`, else `default`).\n- Load the provider session for the selected session.\n\n## Acceptance\n- `ask --session A codex ...` routes to A.\n- Running `ask codex ...` inside session A routes to A (via `CQ_SESSION`).\n","status":"closed","priority":1,"issue_type":"task","owner":"stefanc@allenai.org","created_at":"2026-02-03T18:50:39.371587-08:00","created_by":"stefanc-ai2","updated_at":"2026-02-03T21:52:53.90757-08:00","closed_at":"2026-02-03T21:52:53.90757-08:00","close_reason":"Added ask --session \u003cname\u003e to target a specific CQ session; validates names via session_scope, passes session/env through to provider session loaders, and improves error hints to include the selected session and the correct cq --session command. Updated README and added tests for explicit --session, CQ_SESSION env defaulting, and invalid session rejection.","labels":["sessions","cli","routing"],"dependencies":[{"issue_id":"claude_code_bridge-4.5","depends_on_id":"claude_code_bridge-4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"claude_code_bridge-4.5","depends_on_id":"claude_code_bridge-4.1","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"claude_code_bridge-4.5","depends_on_id":"claude_code_bridge-4.6","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"claude_code_bridge-4.6","title":"Make codex/claude session loaders + registry session-aware","description":"Update session resolution so multiple sessions can coexist.\n\n## Scope\n- Update `lib/codex_session.py` + `lib/claude_session.py` to accept a `session` parameter (or read `CQ_SESSION`).\n- Update `lib/claude_session_resolver.py` so it prefers session-scoped files/registry records and avoids cross-session collisions.\n- Consider adding `cq_session_name` to registry records for additional disambiguation.\n\n## Acceptance\n- With two active sessions, `ask --session A claude ...` never resolves B's pane.\n","status":"closed","priority":1,"issue_type":"task","owner":"stefanc@allenai.org","created_at":"2026-02-03T18:50:39.542717-08:00","created_by":"stefanc-ai2","updated_at":"2026-02-03T21:31:27.028941-08:00","closed_at":"2026-02-03T21:31:27.028941-08:00","close_reason":"Session-aware loaders/resolution: added cq_session_name to registry records, filtered registry lookups by session, and threaded session/env through codex/claude loaders + claude_session_resolver to avoid cross-session pane collisions. Added tests for registry+resolver session filtering (named + default).","labels":["sessions","registry"],"dependencies":[{"issue_id":"claude_code_bridge-4.6","depends_on_id":"claude_code_bridge-4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"claude_code_bridge-4.6","depends_on_id":"claude_code_bridge-4.1","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"claude_code_bridge-4.6","depends_on_id":"claude_code_bridge-4.3","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"claude_code_bridge-4.7","title":"cq-mounted: add --session and list all sessions","description":"Teach `cq-mounted` about multiple sessions.\n\n## Scope\n- Support `cq-mounted --session \u003cname\u003e` (or `CQ_SESSION`) to answer \"is this session mounted?\"\n- Add `cq-mounted --all-sessions` to enumerate `.cq_config/sessions/*` plus the default session.\n\n## Acceptance\n- Skills using `cq-mounted` from inside a session see the right providers.\n","status":"closed","priority":2,"issue_type":"task","owner":"stefanc@allenai.org","created_at":"2026-02-03T18:50:39.728948-08:00","created_by":"stefanc-ai2","updated_at":"2026-02-03T22:13:01.902213-08:00","closed_at":"2026-02-03T22:13:01.902213-08:00","close_reason":"Added multi-session support to cq-mounted: --session (default from CQ_SESSION) performs strict session-scoped lookups, and --all-sessions enumerates default plus .cq_config/sessions/* with deterministic ordering. JSON output includes selected session or sessions list. Updated README and expanded tests (env/flag selection, strictness, all-sessions, invalid session).","labels":["sessions","cli"],"dependencies":[{"issue_id":"claude_code_bridge-4.7","depends_on_id":"claude_code_bridge-4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"claude_code_bridge-4.7","depends_on_id":"claude_code_bridge-4.1","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"claude_code_bridge-4.7","depends_on_id":"claude_code_bridge-4.3","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
-{"id":"claude_code_bridge-4.8","title":"Tests + README docs for multi-session","description":"Add coverage and documentation for multi-session workflow.\n\n## Scope\n- Unit tests for session path selection and routing precedence.\n- Update README with examples:\n  - Start two sessions\n  - Target via `ask --session`\n  - In-pane default behavior via `CQ_SESSION`\n\n## Acceptance\n- Tests cover session selection rules and no collisions.\n- README documents multi-session usage succinctly.\n","status":"open","priority":2,"issue_type":"task","owner":"stefanc@allenai.org","created_at":"2026-02-03T18:50:39.914963-08:00","created_by":"stefanc-ai2","updated_at":"2026-02-03T18:50:39.914963-08:00","labels":["sessions","tests","docs"],"dependencies":[{"issue_id":"claude_code_bridge-4.8","depends_on_id":"claude_code_bridge-4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"claude_code_bridge-4.8","depends_on_id":"claude_code_bridge-4.5","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"claude_code_bridge-4.8","depends_on_id":"claude_code_bridge-4.7","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
+{"id":"claude_code_bridge-4.8","title":"Tests + README docs for multi-session","description":"Add coverage and documentation for multi-session workflow.\n\n## Scope\n- Unit tests for session path selection and routing precedence.\n- Update README with examples:\n  - Start two sessions\n  - Target via `ask --session`\n  - In-pane default behavior via `CQ_SESSION`\n\n## Acceptance\n- Tests cover session selection rules and no collisions.\n- README documents multi-session usage succinctly.\n","status":"closed","priority":2,"issue_type":"task","owner":"stefanc@allenai.org","created_at":"2026-02-03T18:50:39.914963-08:00","created_by":"stefanc-ai2","updated_at":"2026-02-03T22:20:48.683323-08:00","closed_at":"2026-02-03T22:20:48.683323-08:00","close_reason":"Added multi-session docs and test coverage: README now explains in-pane CQ_SESSION scoping vs out-of-pane ask --session targeting; tests cover env vs explicit precedence (explicit overrides env), explicit named-session strictness, and env-based fallback behavior.","labels":["sessions","tests","docs"],"dependencies":[{"issue_id":"claude_code_bridge-4.8","depends_on_id":"claude_code_bridge-4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"claude_code_bridge-4.8","depends_on_id":"claude_code_bridge-4.5","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"claude_code_bridge-4.8","depends_on_id":"claude_code_bridge-4.7","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"claude_code_bridge-4.9","title":"Update all-plan/pair/poll skills to include session targeting","description":"Ensure the `all-plan`, `pair`, and `poll` skills work correctly with multi-session support.\n\n## Problem\nWhen multiple sessions exist in the same repo, skills that instruct users to run `ask codex ...` / `cq-mounted` need to either:\n- pass `--session \u003cname\u003e` explicitly, or\n- rely on inherited `CQ_SESSION` env var and ensure any *driver-side* invocations preserve it.\n\n## Scope\n- Update skill docs/templates so:\n  - Any `ask ...` command examples include `--session \"$CQ_SESSION\"` when appropriate, or explicitly mention relying on `CQ_SESSION`.\n  - Any `cq-mounted` usage includes `--session` or respects `CQ_SESSION`.\n- Ensure reply-via-ask instructions keep responses routed to the correct session.\n\n## Files\n- `/Users/stefanc/.codex/skills/all-plan/**`\n- `/Users/stefanc/.codex/skills/pair/**`\n- `/Users/stefanc/.codex/skills/poll/**`\n\n## Dependencies\n- Should block on core multi-session routing being implemented (`ask --session`, `cq-mounted --session`).\n\n## Acceptance\n- With two sessions running, invoking `/all-plan`, `/pair`, or `/poll` inside session A results in all `ask` traffic staying within session A.\n- Skill prompts/templates mention session explicitly (or document `CQ_SESSION` inheritance clearly).\n","status":"open","priority":2,"issue_type":"task","owner":"stefanc@allenai.org","created_at":"2026-02-03T18:53:39.084064-08:00","created_by":"stefanc-ai2","updated_at":"2026-02-03T18:53:39.084064-08:00","labels":["sessions","skills","docs"],"dependencies":[{"issue_id":"claude_code_bridge-4.9","depends_on_id":"claude_code_bridge-4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"claude_code_bridge-4.9","depends_on_id":"claude_code_bridge-4.5","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"claude_code_bridge-4.9","depends_on_id":"claude_code_bridge-4.7","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"claude_code_bridge-qkw","title":"Remove CHANGELOG.md and CHANGELOG_4.0.md","description":"Remove changelog files that are outdated/unnecessary:\n\n- CHANGELOG.md: Minimal content (12 lines), just lists unreleased breaking changes\n- CHANGELOG_4.0.md: Chinese language documentation from v4.0 release, outdated\n\nThese files add maintenance burden without providing value in the simplified codebase. Version history is tracked in git.\n\nVerify: files deleted, no references remain","status":"closed","priority":2,"issue_type":"task","assignee":"stefanc-ai2","owner":"stefanc@allenai.org","created_at":"2026-01-30T20:12:42.396944-08:00","created_by":"stefanc-ai2","updated_at":"2026-01-30T21:34:53.691347-08:00","closed_at":"2026-01-30T21:34:53.691347-08:00","close_reason":"Deleted CHANGELOG.md and CHANGELOG_4.0.md; removed references","labels":["s7t"]}
 {"id":"claude_code_bridge-s7t","title":"Simplify CCB to Claude+Codex Only","description":"Simplify Claude Code Bridge from a 5-provider, multi-platform system to a minimal 2-provider (Claude + Codex) solution for **macOS + Linux only** (no Windows, no WSL).\n\n## Goals\n- Providers: keep **codex** + **claude** only; remove **gemini/opencode/droid**\n- Platform: remove Windows/WSL compatibility and Windows-specific artifacts\n- UX: replace `pend` with **reply-via-ask**; `ask` becomes **pure async** (submit-only)\n- Remove MCP delegation integration (`mcp/ccb-delegation`, `ccb droid setup-delegation`)\n- Keep both tmux + WezTerm backends\n\n## Notes\n- Keep repo green per-layer: `python -m compileall -q lib bin ccb` + targeted `pytest`.\n- No “read results from logs” UX (no `pend`, no completion hook prompting `pend`).\n\n## Estimated reduction\n~4,500+ lines of code, 20+ files deleted (likely more once docs/tests/installers are pruned).\n","status":"open","priority":1,"issue_type":"epic","owner":"stefanc@allenai.org","created_at":"2026-01-30T12:38:16.250679-08:00","created_by":"stefanc-ai2","updated_at":"2026-01-30T13:21:39.237439-08:00","labels":["simplification"]}

README.md

@@ -134,6 +134,14 @@ cq --session feature-b codex,claude
 
 This namespaces the launcher lock per (cwd,session) and exports `CQ_SESSION` in managed panes.
 
+Inside a managed pane, `ask` and `cq-mounted` automatically scope to that session via `CQ_SESSION` (no `--session` needed):
+
+```bash
+# From within the codex pane of feature-a:
+ask claude "Any concerns with this approach?"
+cq-mounted --json
+```
+
 To send to a specific session from outside a managed pane:
 
 ```bash

test/test_ask_session_flag.py

@@ -21,6 +21,7 @@ def test_ask_passes_session_flag_to_loader(tmp_path: Path, monkeypatch: pytest.M
     ask = _load_ask_module(repo_root)
 
     monkeypatch.chdir(tmp_path)
+    monkeypatch.setenv("CQ_SESSION", "other-session")
 
     sent: dict[str, str] = {}
 
@@ -40,6 +41,7 @@ def _fake_load_codex_session(work_dir: Path, *, session=None, env=None):
         assert work_dir.resolve() == tmp_path.resolve()
         assert session == "feature-x"
         assert env is not None
+        assert env.get("CQ_SESSION") == "other-session"
         return _Session()
 
     monkeypatch.setattr(ask, "load_codex_session", _fake_load_codex_session)

test/test_session_scope.py

@@ -98,6 +98,19 @@ def test_session_utils_explicit_named_session_is_strict(tmp_path: Path) -> None:
     )
 
 
+def test_session_utils_env_named_session_allows_fallback(tmp_path: Path) -> None:
+    cfg = tmp_path / ".cq_config"
+    cfg.mkdir()
+    default = cfg / ".codex-session"
+    default.write_text("default", encoding="utf-8")
+
+    # Named session missing: fall back to default when resolved via env (non-explicit).
+    assert (
+        session_utils.find_project_session_file(tmp_path, ".codex-session", env={"CQ_SESSION": "feature-x"})
+        == default
+    )
+
+
 def test_find_project_session_file_strict_mode(tmp_path: Path) -> None:
     cfg = tmp_path / ".cq_config"
     cfg.mkdir()