Skip to content

Make Codex and Claude Code subscriptions go further: a local model router that gives routine agent work to economical models and keeps your strongest model for the hard parts.

Explain Codex session visibility and supported recovery (#199)

澄潭70e8815610d4
diff --git a/apps/desktop/src/features/agents/CodexAccessPanel.tsx b/apps/desktop/src/features/agents/CodexAccessPanel.tsx
index 686021c9..3e962a9b 100644
--- a/apps/desktop/src/features/agents/CodexAccessPanel.tsx
+++ b/apps/desktop/src/features/agents/CodexAccessPanel.tsx
@@ -5,6 +5,25 @@ import { preferredCodexShell } from './codex-launch';
export type { CodexAccess } from './types';
import type { CodexAccess } from './types';
+export function CodexHistoryNotice({ language, mode }: { language: 'zh' | 'en'; mode: 'profile' | 'root' }) {
+ const text = (zh: string, en: string) => language === 'zh' ? zh : en;
+ const root = mode === 'root';
+ return <div className={`callout${root ? ' warn' : ''}`} role="note" data-codex-history-guidance data-codex-history-mode={mode}>
+ <UiIcon name={root ? 'warning' : 'info'} /><div>
+ <strong>{root
+ ? text('切换后如何找回原有会话', 'Finding earlier sessions after switching')
+ : text('原有会话仍可从原入口继续', 'Continue earlier sessions from the original entry')}</strong>
+ <p>{root
+ ? text('设为默认后,Codex 按模型服务商筛选 /resume。原有会话可能不再显示,即使选择全部目录;会话文件仍然保留。', 'After using HiRoute by default, Codex filters /resume by model provider. Earlier sessions may disappear, even with all directories selected; their files remain.')
+ : text('按需使用只影响 HiRoute profile,普通 Codex 的配置和会话历史不变。HiRoute profile 内的 /resume 可能不显示原服务商的会话。', 'On-demand access only affects the HiRoute profile. Ordinary Codex configuration and session history stay unchanged. Inside the HiRoute profile, /resume may hide sessions from the original provider.')}</p>
+ <p>{root
+ ? text('找回步骤:在 HiRoute 的“模型路由”点击“停用”,等待原配置恢复完成,再使用原 CODEX_HOME 和原 profile 运行 ', 'To recover: turn off Model routing in HiRoute and wait for configuration restoration to finish. Then use your original CODEX_HOME and profile to run ')
+ : text('无需停用 HiRoute。退出 HiRoute profile,用原 CODEX_HOME 和原 profile 运行 ', 'No need to disable HiRoute. Exit the HiRoute profile and use your original CODEX_HOME and profile to run ')}<code>codex resume --all</code>{text(',选择原有会话。', ' and select the earlier session.')}</p>
+ <p>{text('原入口使用原服务商,绕过 HiRoute,需要原账号或 API 凭据。', 'The original entry uses the original provider, bypasses HiRoute, and needs its original account or API credentials.')}</p>
+ </div>
+ </div>;
+}
+
export function CodexAccessSettings({ access, mode, language, disabled, onMode }: {
access: CodexAccess; mode: 'profile' | 'root'; language: 'zh' | 'en'; disabled: boolean;
onMode: (mode: 'profile' | 'root') => void;
@@ -22,7 +41,7 @@ export function CodexAccessSettings({ access, mode, language, disabled, onMode }
<dl><div><dt>CODEX_HOME</dt><dd><code className="configuration-path">{access.codex_home}</code></dd></div>
{access.slot_occupied && <div><dt>{text('目标文件', 'Target file')}</dt><dd><code className="configuration-path">{access.target_file}</code></dd></div>}
</dl>
- <p className="field-help">{text('不同入口的会话历史可能不同;不提供跨 provider 历史恢复。独立 profile 不支持启动 Desktop。', 'History may differ between entry points; cross-provider recovery is not provided. The separate profile cannot launch Desktop.')}</p>
+ <p className="field-help">{text('使用原有会话时需选择相同的 CODEX_HOME 和原 profile。独立 profile 不支持启动 Desktop。', 'Use the same CODEX_HOME and original profile for earlier sessions. The separate profile cannot launch Desktop.')}</p>
</Disclosure>
</div>;
}
@@ -40,6 +59,7 @@ export function CodexAccessPanel({ access, language, retryDisabled, onRetry }: {
<p className="field-help">{mode === 'profile'
? text('按需使用 · Codex CLI:复制命令到终端启动。普通 Codex 与 Desktop 保持原配置。', 'On demand · Codex CLI: copy the command to start in a terminal. Ordinary Codex and Desktop keep their settings.')
: text('默认接入 · Codex CLI 和 Desktop:共享此配置目录的入口使用 HiRoute。', 'Default connection · Codex CLI and Desktop: entry points sharing this directory use HiRoute.')}</p>
+ <CodexHistoryNotice language={language} mode={mode} />
{mode === 'profile' && access.slot_occupied && !access.pending_operation && !access.access_revoked && <div>
<div className="detail-section-head"><strong>{text('启动 Codex', 'Start Codex')}</strong><label className="field-label agent-launch-shell">Shell <select className="select" value={shell} onChange={e => { setShell(e.target.value); setCopyState(''); }}>{Object.keys(access.commands).map(name => <option key={name}>{name}</option>)}</select></label></div>
<pre className="agent-launch-command"><code>{command}</code></pre>
diff --git a/apps/desktop/src/features/agents/CodexModelEditor.tsx b/apps/desktop/src/features/agents/CodexModelEditor.tsx
index a38928b3..29803fd5 100644
--- a/apps/desktop/src/features/agents/CodexModelEditor.tsx
+++ b/apps/desktop/src/features/agents/CodexModelEditor.tsx
@@ -2,7 +2,7 @@ import { agentModelStatus } from './status';
import React from 'react';
import { Disclosure, UiIcon } from '../../ui';
import type { AgentModelEditorProps } from './AgentModelEditor';
-import { CodexAccessSettings } from './CodexAccessPanel';
+import { CodexAccessSettings, CodexHistoryNotice } from './CodexAccessPanel';
import { codexSurfaceFacts } from './codex-surfaces';
import { surfaceName } from './ecosystems';
import { codexDefaultChoiceValid } from './editor-state';
@@ -165,6 +165,7 @@ export function CodexModelEditor({
<p className="field-help" data-codex-shared-scope>{activeCodexMode === 'profile'
? text('按需使用 · 仅 Codex CLI。启用后将启动命令粘贴到终端,开启新会话。普通 Codex 和 Desktop 保持原配置。', 'On demand · Codex CLI only. After enabling, paste the launch command into a terminal to start a new session. Ordinary Codex and Desktop keep their settings.')
: text('设为默认 · 修改同一配置目录下 Codex CLI 和 Desktop 的模型接入。保存后重新启动对应客户端即可生效。', 'Use by default · changes model access for Codex CLI and Desktop sharing this directory. Restart the client after saving to apply the settings.')}</p>
+ <CodexHistoryNotice language={language} mode={activeCodexMode} />
<fieldset><legend className="field-label">{text('允许的智能路由', 'Allowed smart routes')}</legend>
{enabledPlans.length === 1 && creatingModelConnection && <p className="field-help">{text('唯一可用路由已选为默认,可直接启用。', 'The only available route is selected as the default. Enable to continue.')}</p>}
{enabledPlans.map(plan => <label className="check-row agent-route-choice" data-agent-plan-id={plan.agent_plan_id} key={plan.agent_plan_id}><input type="checkbox" checked={editorValues.allowedPlanIds.includes(plan.agent_plan_id)} onChange={() => toggleAllowedPlan(plan.agent_plan_id)} /><div><strong>{plan.desired.display_name}</strong></div></label>)}
@@ -199,7 +200,7 @@ export function CodexModelEditor({
: text('保存一次即作用于共享此配置作用域与 CODEX_HOME 的 Codex CLI 和 Desktop。', 'One save applies to Codex CLI and Desktop when they share this configuration scope and CODEX_HOME.')}</p>{codexSurfaces.map(({surface, detected, applicable}) => {
return <span className="field-help" key={surface} data-agent-surface-fact={surface} data-agent-surface-detected={detected ? 'true' : 'false'} data-agent-surface-applicable={applicable ? 'true' : 'false'}>{surfaceName(surface)} · {detected ? text('当前已发现可执行入口', 'currently detected as runnable') : text('当前未发现可执行入口', 'not currently detected as runnable')} · {applicable ? text('适用当前模式', 'applies to this mode') : text('不适用当前模式', 'does not apply to this mode')}</span>;
})}</div></div>
- <p className="field-help" data-agent-plan-compatibility>{text('保存时会核对路由的 Codex Responses 能力。不同入口的会话历史可能不同。', 'Saving checks the routes’ Codex Responses capabilities. History may differ between entry points.')}</p>
+ <p className="field-help" data-agent-plan-compatibility>{text('保存时会核对路由的 Codex Responses 能力。', 'Saving checks the routes’ Codex Responses capabilities.')}</p>
</Disclosure>
{modelFormInvalid && <span className="oc-inline-error">{text('请选择可用路由或固定模型,并修正不可用项。', 'Choose an available route or fixed model and resolve unavailable selections.')}</span>}
</div>;
diff --git a/apps/desktop/src/features/agents/README.md b/apps/desktop/src/features/agents/README.md
index 9bffd806..6cc09772 100644
--- a/apps/desktop/src/features/agents/README.md
+++ b/apps/desktop/src/features/agents/README.md
@@ -20,7 +20,7 @@ to their production owners and executable contracts.
| [AgentSettingsFeedback.tsx](AgentSettingsFeedback.tsx) | Presentation of authoritative Preview blockers. |
| [HermesModelEditor.tsx](HermesModelEditor.tsx), [HermesRootFields.tsx](HermesRootFields.tsx) | One Plan/protocol and explicit effective profile; root fields are shared with source scan. Automatic adapter preparation and unobserved native loading stay distinct. |
| [collaboration-check-feedback.ts](collaboration-check-feedback.ts) | Versioned collaboration-check failures become safe login, Skill recovery and retry guidance; native output is never display text. |
-| [CodexAccessPanel.tsx](CodexAccessPanel.tsx) | Profile/root facts, mode controls, launch commands, ordinary file-conflict diagnosis and an existing pending Operation's recovery entry. |
+| [CodexAccessPanel.tsx](CodexAccessPanel.tsx) | Profile/root facts, mode controls, launch commands, visible mode-specific session-history and original-entry guidance, ordinary file-conflict diagnosis and an existing pending Operation's recovery entry. |
| [codex-launch.ts](codex-launch.ts), [codex-surfaces.ts](codex-surfaces.ts) | Confirmed command-copy eligibility and the distinction between detected executables and mode applicability. |
| [mutation-feedback.ts](mutation-feedback.ts) | Submitted, pre-apply cancelled and uncertain outcomes; truthful disable/recovery messages. |
| [Agents page](../../agents.tsx) | Snapshot refresh, selected Agent/tab, in-memory draft and mode, discard guard, native calls, Operation handoff, confirmation-dependent copy effect and task-history composition. |
diff --git a/apps/desktop/src/occami/styles.css b/apps/desktop/src/occami/styles.css
index 63fd6073..7c4fc63a 100644
--- a/apps/desktop/src/occami/styles.css
+++ b/apps/desktop/src/occami/styles.css
@@ -65,6 +65,7 @@
.agent-form .agent-route-choice {padding:12px 14px;border:1px solid var(--border);border-radius:10px;background:var(--bg-soft);}
.agent-form .agent-route-choice:has(input:checked) {border-color:var(--accent);background:var(--accent-soft);}
.configuration-path {white-space:pre-wrap;overflow-wrap:anywhere;}
+[data-codex-history-guidance] code {white-space:nowrap;}
.agent-launch-command {white-space:pre-wrap;overflow-wrap:anywhere;padding:14px;border:1px solid var(--border);border-radius:10px;background:var(--bg-soft);font-size:calc(12px * var(--hr-text-scale));}
.agent-launch-shell {display:flex;align-items:center;gap:8px;}
.agent-launch-shell .select {width:auto;max-width:160px;}
diff --git a/apps/desktop/tests/v3/browser/agent-trust-scenarios.mjs b/apps/desktop/tests/v3/browser/agent-trust-scenarios.mjs
index beeecebf..adf1313c 100644
--- a/apps/desktop/tests/v3/browser/agent-trust-scenarios.mjs
+++ b/apps/desktop/tests/v3/browser/agent-trust-scenarios.mjs
@@ -318,12 +318,53 @@ const scenarios = [
const route = dialog().querySelector('[data-agent-plan-id] input');
assert(route?.checked && !submit().disabled, 'Sole route is not ready to submit');
assert(!dialog().querySelector('details').open, 'Advanced settings are open on first enable');
+ const history = dialog().querySelector('[data-codex-history-guidance]');
+ assert(visible(history) && !history.closest('details'), 'Session-history guidance is hidden before enabling');
+ assert(history.dataset.codexHistoryMode === 'profile' && !history.classList.contains('warn'), 'Default profile is presented as a root takeover warning');
+ assert(history.textContent.includes('普通 Codex 的配置和会话历史不变')
+ && history.textContent.includes('HiRoute profile 内的 /resume'), 'Default guidance does not limit provider filtering to the HiRoute profile');
+ assert(history.textContent.includes('无需停用 HiRoute') && !history.textContent.includes('恢复完成')
+ && history.textContent.includes('原 CODEX_HOME') && history.textContent.includes('原 profile')
+ && history.textContent.includes('codex resume --all') && history.textContent.includes('绕过 HiRoute')
+ && history.textContent.includes('凭据'), 'Default guidance requires disabling or omits the original entry and bypass semantics');
assert(!dialog().querySelector('[data-agent-capability-preview]') && calls('plan_editor_options').length === 0, 'Enable still loads a read-only capacity preview');
assert(dialog().textContent.includes('开启新会话'), 'Profile activation step is missing');
const cancel = [...dialog().querySelectorAll('button')].find(button => button.textContent.trim() === '取消');
cancel.click(); await tick();
assert(!dialog() && calls('preview_agent_settings').length === 0 && c().operations.length === 0, 'Cancel applied a draft');
}),
+ scenario('codex.history.root-and-configured-guidance', ['agent-model-routing'], 'Codex distinguishes original-entry return from root restoration in setup and saved settings', async () => {
+ await freshCodex('splitCodexStatus');
+ const saved = document.querySelector('[data-codex-history-guidance]');
+ assert(visible(saved) && saved.dataset.codexHistoryMode === 'root'
+ && saved.textContent.includes('停用') && saved.textContent.includes('恢复完成')
+ && saved.textContent.includes('codex resume --all')
+ && saved.textContent.includes('绕过 HiRoute'), 'Configured connection has no supported original-provider entry');
+ await openEditor('model', false);
+ const history = dialog().querySelector('[data-codex-history-guidance]');
+ assert(visible(history) && !history.closest('details'), 'Root takeover hides session-history warning in advanced settings');
+ assert(history.classList.contains('warn') && history.textContent.includes('全部目录')
+ && history.textContent.includes('会话文件仍然保留') && history.textContent.includes('恢复完成'), 'Root takeover omits provider filtering, preserved history or restoration');
+ assert(dialog().querySelector('[data-codex-shared-scope]').textContent.includes('设为默认'), 'The root configuration was not exercised');
+ assert(calls('preview_agent_settings').length === 0 && c().operations.length === 0, 'Reading history guidance changed configuration');
+ [...dialog().querySelectorAll('button')].find(button => button.textContent.trim() === '取消').click();
+ await tick();
+ assert(!dialog() && visible(saved), 'Cancelling lost the saved recovery instructions');
+ const access = c().agents.agents.find(agent => agent.agent_id === 'agent_codex_default').codex_access;
+ access.selected_mode = 'profile'; c().refresh(); await tick();
+ const profileSaved = document.querySelector('[data-codex-history-guidance]');
+ assert(profileSaved.dataset.codexHistoryMode === 'profile' && profileSaved.textContent.includes('无需停用 HiRoute')
+ && !profileSaved.classList.contains('warn'), 'Saved profile incorrectly requires restoration to use the ordinary entry');
+ access.slot_occupied = false; c().refresh(); await tick();
+ await openEditor('model');
+ const mode = dialog().querySelector('[data-codex-access-mode] select');
+ changeSelect(mode, 'root'); await tick();
+ assert(dialog().querySelector('[data-codex-history-guidance]').textContent.includes('恢复完成'), 'Switching to root keeps the profile return path');
+ changeSelect(mode, 'profile'); await tick();
+ assert(dialog().querySelector('[data-codex-history-guidance]').textContent.includes('无需停用 HiRoute'), 'Switching back to profile keeps root restoration instructions');
+ [...dialog().querySelectorAll('button')].find(button => button.textContent.trim() === '取消').click(); await tick();
+ assert(!dialog() && calls('preview_agent_settings').length === 0 && c().operations.length === 0, 'Reading or changing draft guidance applied settings');
+ }),
scenario('claude.enable.shared-presets', ['agent-model-routing'], 'Claude first enable shares one route while retaining independent advanced presets', async () => {
await fresh('notRunnable', true);
await openEditor('model', false);
diff --git a/apps/desktop/tests/v3/browser/scenario-requirements.mjs b/apps/desktop/tests/v3/browser/scenario-requirements.mjs
index 19451e48..ffbb8a25 100644
--- a/apps/desktop/tests/v3/browser/scenario-requirements.mjs
+++ b/apps/desktop/tests/v3/browser/scenario-requirements.mjs
@@ -12,6 +12,7 @@ export const agentTrustRequired = ['codex.restore.conflict-active',
'hermes.routing.unavailable-and-exact-recovery',
'claude.routing.blocker-guidance',
'codex.enable.draft-cancel',
+ 'codex.history.root-and-configured-guidance',
'claude.enable.shared-presets',
'codex.enable.confirmed-command',
'codex.routing.fixed-binding',
diff --git a/docs/code-map/worker-context.md b/docs/code-map/worker-context.md
index 8b13f923..dcdc4bc2 100644
--- a/docs/code-map/worker-context.md
+++ b/docs/code-map/worker-context.md
@@ -24,6 +24,12 @@ report the actual installed consumers; [safe conflict facts](../../crates/domain
retain rejection identity through compensation and client observation.
Native defaults and collaboration stay independent;
restoration must verify ownership rather than infer it from a provider name.
+
+Codex's [connection guidance](../../apps/desktop/src/features/agents/CodexAccessPanel.tsx)
+explains native provider-scoped session discovery before enabling routing. Default
+on-demand access preserves the ordinary entry for earlier sessions; advanced default
+takeover first requires configuration restoration. See [session recovery](../local-user-configuration.md#find-earlier-codex-sessions). Worker Continue below
+has its own exact-history binding and does not replace the native `/resume` picker.
OpenCode's [startup target binding](../../crates/daemon/src/control/runtime.rs) keeps
the physical JSON/JSONC file verified by existing recovery markers;
[effective model facts](../../crates/integrations/src/agents/opencode_scanner.rs)
diff --git a/docs/local-user-configuration.md b/docs/local-user-configuration.md
index e41bf686..53cf4d89 100644
--- a/docs/local-user-configuration.md
+++ b/docs/local-user-configuration.md
@@ -61,10 +61,10 @@ not adopt files by name or remove their authentication fields. Preserve your own
resolve the conflicting entry manually before a fresh preview.
Profile mode uses native `codex --profile hiroute`; it does not provide a Desktop profile
-launcher. History can differ between entry points. Cross-provider history restoration and
-session database changes are outside this feature. Gateway credentials authorize the selected
-models independently of the Codex client's OpenAI login; retaining original models still
-requires a usable upstream source configured in HiRoute.
+launcher. Session histories remain scoped to their native provider; HiRoute does not merge
+histories or modify the session database. Gateway credentials authorize the selected models
+independently of the Codex client's OpenAI login; retaining original models still requires a
+usable upstream source configured in HiRoute.
A pending operation reserves the home even if Gateway access is already revoked. The Agent
page shows the target and conflicting fields, and can recheck and resume the original Operation.
@@ -82,6 +82,50 @@ Local CLI callers can resume that same operation through `agents connect apply`
This retry accepts no new settings or grants. The daemon checks the stored operation and its
context before continuing. First-time creation and edits still require normal Preview/Apply.
+### Find earlier Codex sessions
+
+Default **On demand** mode preserves ordinary Codex configuration and session
+history. Use the ordinary Codex entry to find earlier sessions; the HiRoute profile
+can remain enabled.
+
+Inside the HiRoute profile, Codex filters its native `/resume` picker by HiRoute's
+model provider. Sessions created with another provider can disappear from that
+picker while their files remain in the same `CODEX_HOME`. Advanced **Use by default**
+mode applies this provider change to ordinary Codex and Desktop as well. Selecting
+all directories, or running `codex resume --all`, removes the directory filter;
+it does not remove the provider filter. The model-routing form and configured
+connection explain the selected mode's scope and return path.
+
+### Return to the original provider
+
+1. For default **On demand** mode, return to the ordinary Codex entry without
+ the HiRoute profile. **No disable or configuration restoration is needed.**
+ For advanced **Use by default** mode, open **Agents → Codex** in HiRoute and
+ turn off **Model routing** first. Wait for configuration restoration to complete;
+ resolve any reported file conflict or incomplete operation before continuing.
+2. Exit the Codex instance using HiRoute. Open a terminal using the original
+ `CODEX_HOME` shown in the connection's configuration details. Use the same
+ original profile and working environment as before enabling HiRoute.
+3. Run `codex resume --all` and select the earlier session. If the original entry
+ used an explicit profile, retain it: `codex --profile <original-profile> resume --all`.
+ The `hiroute` profile is the managed route, not the original entry.
+4. Continuing the session uses the original provider and its account or API
+ credentials. Those requests **bypass HiRoute**. The on-demand HiRoute profile
+ remains available for separate sessions. Advanced default takeover changes the
+ ordinary entry's provider again when re-enabled.
+
+Advanced-mode restoration uses the existing conditional transaction for
+HiRoute-owned configuration fields. Neither return path edits Codex's session files,
+provider labels or private session database. Keep a backup of important history;
+changing provider IDs or rewriting the database is not a supported migration.
+
+For sessions created under several different original providers, use each
+provider's original configuration and credentials. HiRoute cannot reconstruct a
+configuration or account that was already missing before it was enabled.
+
+The native commands are documented in the [official Codex CLI reference](https://developers.openai.com/codex/cli/reference/).
+The configuration contract belongs to [Agent connections](../issue-spec/specs/agent-connections/spec.md).
+
## OpenCode
In Agents, enable OpenCode model routing and select the published routes and each
diff --git a/issue-spec/specs/agent-connections/spec.md b/issue-spec/specs/agent-connections/spec.md
index 0082477f..075f60d1 100644
--- a/issue-spec/specs/agent-connections/spec.md
+++ b/issue-spec/specs/agent-connections/spec.md
@@ -247,8 +247,26 @@ DTO may expose only the exact codex_home/target_file/commands needed for this ac
other paths remain masked and no credential is included. This exception does not
apply to diagnostics or remote telemetry. Gateway validates token/model scope,
not directory hiding or launch argument filtering. Pure HiRoute needs no Codex
-OpenAI login and promises neither Desktop profile launch nor cross-provider history
-recovery. Native history labels/databases are not rewritten.
+OpenAI login and does not promise Desktop profile launch or migration of sessions
+between providers. Native history labels/databases are not rewritten.
+
+Before enabling model routing, the ordinary Codex form visibly explains session
+discovery for the selected mode; the configured connection retains this guidance.
+Default on-demand mode preserves ordinary Codex configuration and session history.
+Earlier-provider sessions can be hidden from `/resume` inside the HiRoute profile;
+returning to the original entry does not require disabling HiRoute. Advanced
+default takeover warns that the provider filter can hide earlier sessions even
+in the all-directories view, while retaining their files. Only this mode requires
+turning off model routing and completing native configuration restoration before
+returning to the original default entry. An incomplete or conflicting restore
+does not authorize claiming that entry is restored.
+
+Both modes direct users to their original CODEX_HOME and original profile with
+`codex resume --all` to select an earlier session. This original entry uses the
+original provider, bypasses HiRoute and needs that provider's credentials. Native
+acceptance proves earlier-session discovery and resume through the ordinary entry
+while the on-demand HiRoute profile remains configured; profile isolation alone
+does not establish resume success.
Restore preserves unrelated user fields and new content in a created profile.
Originally missing profile fields resume inheriting current root rather than writing