# KHY vs qwen-code Gap Remediation Checklist (Execution Version)

Updated: 2026-05-14  
Scope: CLI AI runtime, gateway model selection, tool execution, timeout and status pipeline  
Reference baseline: `/home/kodehu03/Downloads/qwen-code-main.zip`

## 0. Target Outcomes (2 Weeks)

1. `/model` first-open result is stable and close to second-open result (cold start consistency).
2. No hard timeout kill for actively progressing long tasks; timeout must be activity-based.
3. App-launch intent (for example "open Feishu", "open a PDF editor") prefers `open_app` first, with reliable fallback.
4. Executor errors (for example `fork: retry: Resource temporarily unavailable`) are classified correctly, not misreported as host resource exhaustion.
5. Status output always follows `Action + Target + Progress` and no fixed "8s stuck" display.

## 1. Baseline Already Completed

- [x] Waiting status progression no longer freezes at a fixed `8s` in AI wait-line flow.
- [x] `ai-chat` watchdog timeout is aligned with request timeout budget in REPL path.
- [x] Large-task timeout budget was widened and propagated in gateway/codex adapter path.

Note: This checklist continues from the current baseline and focuses on remaining systematic gaps.

## 2. Week 1 (P0 Stability and Correctness)

### P0-1. `/model` First-Open Consistency

Objective:
- Solve "first `/model` incomplete, second `/model` complete" inconsistency.

Files to modify:
- `backend/src/cli/handlers/gateway.js`
- `backend/src/services/gateway/modelDiscovery.js`
- `backend/src/services/gateway/channelHealthBroadcaster.js`
- `backend/src/services/gateway/aiGateway.js`

Implementation:
1. Introduce a persisted probe snapshot (`lastStrictSnapshot`) with timestamp and confidence score.
2. Render first `/model` from `snapshot + fast delta` instead of fast probe only.
3. Move strict probe to background refresh and merge by epoch/version, not overwrite blindly.
4. Expose "snapshot time + confidence + probe phase" in diagnostics output.

Acceptance criteria:
1. Cold start: first and second `/model` model counts differ by no more than 1 transient item in normal network.
2. UI clearly marks items as `snapshot`, `fast-probe`, or `strict-verified`.
3. No hidden channel silently reappears without phase/source tag.

Validation:
```bash
khy gateway status
khy gateway model
```
Manual:
1. Start fresh session and run `/model` twice within 20 seconds.
2. Compare model set and confidence tags.

### P0-2. Provider/Model Identity Normalization

Objective:
- Fix "codex adapter shows `claude-*` as if codex native models".

Files to modify:
- `backend/src/services/gateway/modelDiscovery.js`
- `backend/src/services/gateway/modelRouter.js`
- `backend/src/services/gateway/protocolConverter/codex.js`
- `backend/src/cli/handlers/gateway.js`

Implementation:
1. Add provider-origin metadata (`originProvider`, `servedByAdapter`) to discovered models.
2. Split display groups: `Native`, `Routed`, `Relay`.
3. Default filter: hide cross-provider models in adapter-native list unless user enables "show routed/relay models".
4. If routed model is selected, show explicit execution route before confirm.

Acceptance criteria:
1. `codex` list defaults to codex-native IDs only.
2. Cross-provider models are visible only in routed/relay section with clear labels.
3. Selection confirmation includes `adapter + upstream provider + route mode`.

Validation:
```bash
cd backend && npm test -- modelRouter.test.js gatewayModelSelection.strictProbe.test.js
```

### P0-3. Executor Error Attribution and Recovery Path

Objective:
- Prevent false conclusion: "system resource exhausted" when executor/sandbox path fails.

Files to modify:
- `backend/src/services/toolCalling.js`
- `backend/src/services/toolUseLoop.js`
- `backend/src/services/errorClassifier.js`
- `backend/src/cli/repl.js`
- `backend/src/cli/liteRepl.js`

Implementation:
1. Promote `executor_unavailable` as first-class error category with structured fields (`scope`, `retryable`, `suggestedAction`).
2. On app-launch intent + shell executor unavailable: auto-recover via `open_app` before final failure.
3. Error output must explicitly separate:
   - executor/sandbox constraint
   - adapter timeout
   - confirmed host resource pressure
4. For timeout exits, include "completed steps vs pending steps" summary.

Acceptance criteria:
1. `fork` failure no longer emits generic host resource exhaustion conclusion.
2. App-launch requests attempt `open_app` recovery automatically when shell probing fails.
3. Final failure text includes unfinished work disclosure.

Validation:
```bash
cd backend && npm test -- toolCalling.shellForkClassify.test.js toolUseLoop.appLaunchRecovery.test.js
```

### P0-4. Activity-Based Timeout Unification (No Hard Kill)

Objective:
- Remove fixed wall-clock kill logic for active long tasks.

Files to modify:
- `backend/src/services/resourceGuard.js`
- `backend/src/cli/ai.js`
- `backend/src/cli/repl.js`
- `backend/src/cli/liteRepl.js`
- `backend/src/services/gateway/aiGateway.js`
- `backend/src/services/gateway/adapters/codexAdapter.js`

Implementation:
1. Add unified activity heartbeat contract (`onChunk`, `onToolResult`, `onStatus`, `onLoopAdvance`).
2. Replace hard wall timeout with sliding idle timeout + optional max lifetime for deadlock safety.
3. Make timeout budget profile-aware (`small`, `normal`, `large`) and user-overridable.
4. Timeout messages must report:
   - last activity timestamp
   - steps completed
   - last successful tool/model event

Acceptance criteria:
1. Long active tasks are not killed only because wall-clock exceeded.
2. Idle timeout only triggers when no progress event within configured idle window.
3. Logs include activity evidence for timeout decisions.

Validation:
```bash
cd backend && npm test -- aiGateway.stability.test.js aiGateway.stability.regressions.test.js aiCli.concurrentPreferredIsolation.test.js
```

### P0-5. Status Pipeline: Action + Target + Progress

Objective:
- Make runtime status transparent and dynamic, no vague/opaque wait text.

Files to modify:
- `backend/src/cli/repl.js`
- `backend/src/cli/liteRepl.js`
- `backend/src/cli/aiRenderer.js`
- `backend/src/cli/agentRenderer.js`

Implementation:
1. Define status schema: `{action, target, progress, elapsedMs, source}`.
2. Replace generic text with structured lines, for example:
   - `Adapter claude probing connectivity (attempt 2/3, 6s)`
   - `Codex adapter waiting for first token (elapsed 14s)`
3. Debounce by semantic key, not only raw text.
4. Keep live line update stable for terminals with/without carriage-return support.

Acceptance criteria:
1. No standalone vague status lines in AI runtime path.
2. Progress number/time updates continue while waiting.
3. Mixed adapters produce source-labeled status lines.

Validation:
```bash
node scripts/check-agent-rules.js --changed
```
Manual:
1. Trigger one short task and one long task; verify status clarity and progression.

## 3. Week 2 (P1 Capability and Operability)

### P1-1. Program-Level Fuzzy Intent Routing (Not Model-Only)

Objective:
- Add deterministic pre-routing for fuzzy user language, instead of relying only on model inference.

Files to modify:
- `backend/src/cli/router.js`
- `backend/src/cli/aliases.js`
- `backend/src/services/toolUseLoop.js`
- `backend/src/services/toolCalling.js`
- `backend/src/services/shellToToolMapper.js`

Implementation:
1. Add lightweight intent classifier before tool loop: `app_launch`, `file_edit`, `diagnosis`, `web_lookup`.
2. For `app_launch`, force tool priority: `open_app` first, then shell fallback.
3. Expand fuzzy lexicon for Chinese typos, pinyin variants, duplicated characters.
4. Record intent decision trace for postmortem.

Acceptance criteria:
1. Ambiguous requests still map to expected tool path with high consistency.
2. Reduced first-tool misfire rate in app-launch scenarios.
3. Intent trace available in debug logs.

Validation:
```bash
cd backend && npm test -- toolUseLoop.guardrails.test.js toolUseLoop.appLaunchRewrite.test.js toolCalling.openAppAlias.test.js
```

### P1-2. Approval/Permission UX Convergence

Objective:
- Align permission workflow with clear mode semantics and persistent trust rules.

Files to modify:
- `backend/src/services/execApproval.js`
- `backend/src/services/permissionStore.js`
- `backend/src/cli/ui/permissionDialog.js`
- `backend/src/permissions/rules.js`

Implementation:
1. Consolidate approval modes (`strict`, `on-failure`, `never`, etc.) into one canonical enum.
2. Persist per-command and prefix trust decisions with scope (`session`, `workspace`, `global`).
3. Improve permission prompt content: action, target path/command, risk level, reuse rule.

Acceptance criteria:
1. Same command path does not repeatedly ask when rule already exists in scope.
2. Prompt text is explicit and auditable.
3. Rule conflict resolution is deterministic.

Validation:
```bash
cd backend && npm test -- toolRegistryMcp.test.js hook-lifecycle.test.js
```

### P1-3. Config Layering + Schema Migration

Objective:
- Make behavior reproducible across env/profile/session overrides.

Files to modify:
- `backend/src/config/env.js`
- `backend/src/config/settingsWhitelist.js`
- `backend/src/routes/settings.js`
- `backend/src/services/gateway/aiGateway.js`

Implementation:
1. Enforce config precedence: default < user < workspace < env < CLI override.
2. Add schema validation and migration for gateway/timeouts/model filters.
3. Provide `khy doctor` diagnostics for effective config source per key.

Acceptance criteria:
1. Effective config value always includes source trace.
2. Old config formats migrate automatically with warning.
3. No silent fallback to implicit hardcoded values.

Validation:
```bash
cd backend && npm test -- proxyConfig.routing.test.js proxyConfigService.socks5Compatibility.test.js
```

### P1-4. Memory/Session Lifecycle Alignment

Objective:
- Improve long-session stability and recoverability.

Files to modify:
- `backend/src/services/memoryDreaming.js`
- `backend/src/services/sessionFileRepair.js`
- `backend/src/services/sessionTraceSummary.js`
- `backend/src/services/compact/index.js`
- `backend/src/services/query/compactPipeline.js`

Implementation:
1. Unify session compaction trigger and summarization thresholds.
2. Make memory writes crash-safe (atomic replace + integrity marker).
3. Add recovery path for partial/corrupted session files.

Acceptance criteria:
1. Long conversation keeps response quality after compaction.
2. Session corruption can be auto-repaired or clearly isolated.
3. Compaction events are visible in status logs.

Validation:
```bash
cd backend && npm test -- agent-context.test.js aiCli.feedback.stability.test.js
```

### P1-5. Test Matrix and Regression Gate

Objective:
- Convert recent incident patterns into mandatory regression checks.

Files to modify:
- `backend/tests/gatewayModelSelection.strictProbe.test.js`
- `backend/tests/toolUseLoop.appLaunchRecovery.test.js`
- `backend/tests/toolCalling.shellForkClassify.test.js`
- `backend/tests/aiGateway.stability.regressions.test.js`
- `scripts/check-agent-rules.js`

Implementation:
1. Add first-run `/model` consistency scenario.
2. Add executor-unavailable + open_app auto-recovery scenario.
3. Add long-running active task timeout non-kill scenario.
4. Enforce check script in CI for changed files.

Acceptance criteria:
1. New regressions are reproducible locally and caught in CI.
2. P0 scenarios become release gate.

Validation:
```bash
cd backend && npm test -- gatewayModelSelection.strictProbe.test.js toolUseLoop.appLaunchRecovery.test.js toolCalling.shellForkClassify.test.js aiGateway.stability.regressions.test.js
node scripts/check-agent-rules.js --changed
```

## 4. Delivery and Sign-off

Release gate:
1. P0 items all pass acceptance criteria and validation commands.
2. No new hardcoded endpoint/path violation from changed files.
3. Timeout behavior verified on at least one long active task and one true idle-stall task.

Tracking rule:
1. For each item, attach PR link + test evidence + before/after CLI transcript.
2. Any failed acceptance check must reopen the checklist item.
