@gkoreli/ghx 2.3.2 → 2.4.1

package/README.md

@@ -67,6 +67,7 @@ you can `ls` and `jq`:
     traces.jsonl              # OTel spans: session → turn → each tool call
     logs.jsonl                # GenAI-convention message-content records
     metrics.jsonl             # duration, token, report-size metrics
+    tier-decisions.jsonl      # escalation policy evaluation per turn (which tier, why)
 ```
 
 Sessions persist, so follow-up questions on the same repo are cheaper and
@@ -168,7 +169,8 @@ diff and refuses to overwrite without `--force`.
 ### 3. Verify
 
 ```bash
-ghx sidecar doctor    # checks token, network, ghx binary, and the ACP handshake
+ghx sidecar doctor           # token, network, ghx binary, ACP handshake, report sink
+ghx sidecar doctor --live    # also run a REAL one-prompt turn through the agent
 ```
 
 `doctor` fails fast with an actionable message if the configured agent cannot
@@ -178,6 +180,13 @@ matches the running ghx version — a stale sink binary would silently degrade
 structured reports to a text fallback, so doctor fails loudly with fix-it text
 instead.
 
+`--live` goes one step further: the plain handshake stops at ACP *initialize*,
+which passes even on setups where a real turn then fails (auth typically
+resolves lazily at prompt time). `--live` runs a full `session/new` + one tiny
+prompt turn through the configured agent and, on failure, prints the failing
+**stage** and the agent's **stderr tail** — the deterministic way to diagnose a
+machine where `ask` produces nothing (see [ADR-0033](docs/adr/0033-sidecar-out-of-box-agent-config.md)).
+
 ### 4. Ask
 
 ```bash
@@ -188,9 +197,13 @@ ghx sidecar ask --repo hono/hono "How does Hono implement middleware chaining, a
   Without it: **discovery** — "which repos/libraries do X" — the sidecar sweeps
   GitHub for candidates and reads into the top ones before claiming anything
   (see [ADR-0019.1](docs/adr/0019.1-discovery-tier.md)).
-- `--session <name>` is optional (defaults to a repo slug like `hono-hono`, or a
-  question-derived slug for discovery asks — printed so you can resume it); use
-  it to keep parallel investigation threads apart.
+- `--session <name>` is advanced: pin a specific session; normally omit — ghx
+  routes each question to the right session for you
+  ([ADR-0030.1](docs/adr/0030.1-session-routing.md)). With `--repo` the
+  repo-slug session (like `hono-hono`) still stands; with neither flag the
+  daemon runs a deterministic cascade (explicit → repo mention in the question
+  → warm continuation → ledger overlap → new session) and reports the route it
+  chose: `session: hono-hono (routed: overlap 0.62, next 0.21)`.
 - `--json` prints an envelope — `{"report": {...}, "artifacts": {"sessionDir":
   "...", "traceId": "..."}}` — the validated report plus a pointer to the
   session's audit trail. Without it you get the answer plus compact verified /
@@ -207,6 +220,7 @@ session automatically and answer faster. A fresh question takes tens of seconds.
 ghx sidecar sessions list                 # all sessions
 ghx sidecar sessions show <session>       # details + report history
 ghx sidecar sessions ledger <session>     # the accumulated evidence ledger
+ghx sidecar sessions reroute <s> <turn> <dest>  # move a mis-routed turn; both ledgers rebuilt by replay
 ghx sidecar view [session]                # spawn a local trace UI over the session's artifacts
 ghx sidecar view --list                   # sessions with turn/report counts
 ghx sidecar view --port 9000              # viewer UI port (default 8000)
@@ -220,6 +234,33 @@ most recent session. Everything it shows is the same file you can read by hand.
 Requires the viewer on PATH:
 `go install github.com/CtrlSpice/otel-desktop-viewer@latest`.
 
+### Troubleshooting
+
+If an `ask` returns nothing useful, the failure is recorded, not lost
+([ADR-0033](docs/adr/0033-sidecar-out-of-box-agent-config.md)):
+
+- **Per-session agent stderr.** The spawned agent's stderr is captured to
+  `~/.ghx/sessions/<session>/agent-stderr.log`. Under the always-on daemon it
+  no longer disappears into the daemon's own log. A failed turn also splices the
+  tail of that log — and its path — into the error the CLI prints.
+- **Reproduce it deterministically.** `ghx sidecar doctor --live` runs a real
+  prompt turn and prints the failing stage plus the agent's stderr, even when the
+  plain handshake passes.
+- **`this workspace has not been trusted`.** ghx already runs the agent in a
+  neutral, ghx-owned session directory (outside any git repo, no `.claude`
+  settings), so this warning should not appear. If it still does, the agent
+  picked up a git-repo workspace: trust it once (run the agent interactively
+  there and accept the dialog) or set
+  `projects["<dir>"].hasTrustDialogAccepted: true` in `~/.claude.json`. ghx will
+  never write that file for you.
+- **"works from shell A, fails from shell B".** The daemon auto-spawns from the
+  **first** caller's environment, so a missing auth/proxy env var is a common
+  cause. `ghx sidecar sessions show <session>` lists the agent command, the
+  session's spawn cwd, and the **names** (never values) of the agent-relevant
+  environment variables present when it was created. If the wrong env was
+  inherited, `ghx sidecar daemon --stop` and re-run `ask` from a shell that has
+  the right variables.
+
 ### Delegating from a main agent (MCP)
 
 A main agent talks to the sidecar through a single MCP tool — one tool it cannot
@@ -343,6 +384,14 @@ before any clone; answers fall back to remote Tier-1 evidence — never a
 silent or faked Tier-2 result. `astgrep` follows grep parity: exit `1` with
 `[]` means the search ran and found nothing.
 
+When the sidecar answers a question, escalation is never vibes: every turn
+gets a declarative policy evaluation
+([ADR-0024.2](docs/adr/0024.2-escalation-policy.md)) over named observables
+(question shape, exhausted searches, low-confidence remote-only reports),
+recorded as a `ghx.tier.decision` span in `traces.jsonl`, a line in the
+session's `tier-decisions.jsonl`, and `tierUsed` provenance on the report —
+so "which tier answered and why" is always recomputable from the artifacts.
+
 ### Codemode
 
 Write JS programs that compose multiple operations in one round-trip. All

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gkoreli/ghx",
-  "version": "2.3.2",
+  "version": "2.4.1",
   "description": "Agent-first GitHub code exploration. GraphQL batching, code maps, codemode TypeScript sandbox, MCP server.",
   "bin": {
     "ghx": "npm/bin/ghx"
@@ -28,11 +28,11 @@
     "node": ">=16"
   },
   "optionalDependencies": {
-    "@gkoreli/ghx-darwin-arm64": "2.3.2",
-    "@gkoreli/ghx-darwin-x64": "2.3.2",
-    "@gkoreli/ghx-linux-arm64": "2.3.2",
-    "@gkoreli/ghx-linux-x64": "2.3.2",
-    "@gkoreli/ghx-win32-arm64": "2.3.2",
-    "@gkoreli/ghx-win32-x64": "2.3.2"
+    "@gkoreli/ghx-darwin-arm64": "2.4.1",
+    "@gkoreli/ghx-darwin-x64": "2.4.1",
+    "@gkoreli/ghx-linux-arm64": "2.4.1",
+    "@gkoreli/ghx-linux-x64": "2.4.1",
+    "@gkoreli/ghx-win32-arm64": "2.4.1",
+    "@gkoreli/ghx-win32-x64": "2.4.1"
   }
 }