From 376ff121341774dbf4604df8218f1d611df9a2dd Mon Sep 17 00:00:00 2001
From: Codex <codex@openai.com>
Date: Wed, 17 Jun 2026 09:14:12 -0700
Subject: [PATCH 01/33] feat(fresh-agent): add mono style

---
 docs/index.html                               |   4 +-
 shared/settings.ts                            |   2 +-
 .../fresh-agent/FreshAgentSettingsButton.tsx  |   2 +-
 src/index.css                                 | 495 ++++++++++++++++++
 .../fresh-agent/FreshAgentView.test.tsx       |  64 +++
 test/unit/shared/settings.test.ts             |  26 +-
 6 files changed, 587 insertions(+), 6 deletions(-)

diff --git a/docs/index.html b/docs/index.html
index cc647f199..dd2a814a7 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -449,7 +449,7 @@
 .fresh-rail-line { font-size: 13px; line-height: 1.45; overflow-wrap: anywhere; color: hsl(var(--foreground)); }
 .fresh-style-control { display: flex; align-items: center; justify-content: space-between; gap: 10px; border: 1px solid hsl(var(--border)); border-radius: 6px; background: hsl(var(--background) / .78); padding: 6px 8px; }
 .fresh-style-control span { color: hsl(var(--muted-foreground)); font-size: 10px; letter-spacing: .1em; text-transform: uppercase; }
-.fresh-style-control strong { color: hsl(var(--foreground)); font-family: Georgia, Cambria, 'Times New Roman', Times, serif; font-size: 13px; font-weight: 650; }
+.fresh-style-control strong { color: hsl(var(--foreground)); font-family: 'JetBrains Mono', ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', monospace; font-size: 13px; font-weight: 650; }
 
 @media (max-width: 768px) {
   .fresh-mock { display: flex; flex-direction: column; }
@@ -691,7 +691,7 @@ <h2>Task Board</h2>
               </div>
             </div>
             <aside class="fresh-rail">
-              <div class="fresh-rail-section"><div class="fresh-rail-title">Settings</div><div class="fresh-style-control" aria-label="Fresh Agent style setting"><span>Style</span><strong>Serif</strong></div></div>
+              <div class="fresh-rail-section"><div class="fresh-rail-title">Settings</div><div class="fresh-style-control" aria-label="Fresh Agent style setting"><span>Style</span><strong>Mono</strong></div></div>
               <div class="fresh-rail-section"><div class="fresh-rail-title">Review</div><div class="fresh-rail-line">pending</div><div class="fresh-rail-line">review-responsive-display</div></div>
               <div class="fresh-rail-section"><div class="fresh-rail-title">Fork lineage</div><div class="fresh-rail-line">parent-thread-with-long-identifier</div></div>
               <div class="fresh-rail-section"><div class="fresh-rail-title">Worktrees</div><div class="fresh-rail-line">codex/fresh-client-responsive-display</div></div>
diff --git a/shared/settings.ts b/shared/settings.ts
index c13f4a28c..451613a68 100644
--- a/shared/settings.ts
+++ b/shared/settings.ts
@@ -47,7 +47,7 @@ const FRESH_AGENT_FONT_SCALE_MAX = 2
 // Fresh-agent panes render 50% larger than the base UI by default.
 export const FRESH_AGENT_FONT_SCALE_DEFAULT = 1.5
 export const FRESH_AGENT_FONT_SCALE_OPTIONS = [1, 1.25, 1.5, 1.75, 2] as const
-export const FRESH_AGENT_STYLE_VALUES = ['sans', 'serif'] as const
+export const FRESH_AGENT_STYLE_VALUES = ['sans', 'serif', 'mono'] as const
 export type FreshAgentStyle = (typeof FRESH_AGENT_STYLE_VALUES)[number]
 export const DEFAULT_FRESH_AGENT_STYLE: FreshAgentStyle = 'sans'
 
diff --git a/src/components/fresh-agent/FreshAgentSettingsButton.tsx b/src/components/fresh-agent/FreshAgentSettingsButton.tsx
index de74745f9..55201636f 100644
--- a/src/components/fresh-agent/FreshAgentSettingsButton.tsx
+++ b/src/components/fresh-agent/FreshAgentSettingsButton.tsx
@@ -167,7 +167,7 @@ export function FreshAgentSettingsButton({
               >
                 {FRESH_AGENT_STYLE_VALUES.map((style) => (
                   <option key={style} value={style}>
-                    {style === 'sans' ? 'Sans' : 'Serif'}
+                    {style === 'sans' ? 'Sans' : style === 'mono' ? 'Mono' : 'Serif'}
                   </option>
                 ))}
               </select>
diff --git a/src/index.css b/src/index.css
index 3f25d8ac8..18444f41d 100644
--- a/src/index.css
+++ b/src/index.css
@@ -633,6 +633,501 @@ html {
   background: var(--fresh-agent-subtle-surface);
 }
 
+.fresh-agent-style-mono {
+  --fresh-agent-copy-font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;
+  --fresh-agent-meta-font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;
+  --fresh-agent-mono-font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;
+  --fresh-agent-surface: #0a0a0a;
+  --fresh-agent-panel-surface: #0d0d0d;
+  --fresh-agent-subtle-surface: #131313;
+  --fresh-agent-raised-surface: #101010;
+  --fresh-agent-border: rgba(57, 255, 20, 0.3);
+  --fresh-agent-border-strong: rgba(57, 255, 20, 0.55);
+  --fresh-agent-accent: #39ff14;
+  --fresh-agent-accent-soft: rgba(57, 255, 20, 0.12);
+  --fresh-agent-danger: #ff5555;
+  --fresh-agent-danger-soft: rgba(255, 85, 85, 0.12);
+  --fresh-agent-success: #39ff14;
+  --fresh-agent-success-soft: rgba(57, 255, 20, 0.12);
+  --fresh-agent-text: #39ff14;
+  --fresh-agent-muted-text: #5c9e4c;
+  --fresh-agent-soft-text: #4a8a3c;
+  --fresh-agent-watermark-opacity: 0.04;
+  position: relative;
+  background: var(--fresh-agent-surface);
+  color: var(--fresh-agent-text);
+  font-family: var(--fresh-agent-copy-font-family);
+  text-shadow: 0 0 1px rgba(57, 255, 20, 0.25);
+}
+
+.fresh-agent-style-mono::after {
+  content: "";
+  pointer-events: none;
+  position: absolute;
+  inset: 0;
+  background: repeating-linear-gradient(
+    to bottom,
+    transparent,
+    transparent 2px,
+    rgba(57, 255, 20, 0.03) 2px,
+    rgba(57, 255, 20, 0.03) 4px
+  );
+  z-index: 50;
+}
+
+.fresh-agent-style-mono .fresh-agent-transcript-copy {
+  color: var(--fresh-agent-text);
+  font-family: var(--fresh-agent-copy-font-family);
+  line-height: 1.5;
+}
+
+.fresh-agent-style-mono :where(button, input, select),
+.fresh-agent-style-mono .fresh-agent-sidebar,
+.fresh-agent-style-mono .fresh-agent-sidebar-section,
+.fresh-agent-style-mono .fresh-agent-turn-header,
+.fresh-agent-style-mono .fresh-agent-activity-strip,
+.fresh-agent-style-mono .fresh-agent-tool-block,
+.fresh-agent-style-mono .fresh-agent-diff-panel,
+.fresh-agent-style-mono .fresh-agent-composer-menu {
+  font-family: var(--fresh-agent-meta-font-family);
+}
+
+.fresh-agent-style-mono textarea {
+  font-family: var(--fresh-agent-copy-font-family);
+  line-height: 1.5;
+}
+
+.fresh-agent-style-mono .fresh-agent-transcript-copy [data-markdown-body] :where(pre, code) {
+  font-family: var(--fresh-agent-mono-font-family);
+  letter-spacing: 0;
+}
+
+.fresh-agent-style-mono .fresh-agent-layout,
+.fresh-agent-style-mono .fresh-agent-main {
+  background: var(--fresh-agent-surface);
+}
+
+.fresh-agent-style-mono .fresh-agent-transcript-scroll {
+  gap: 0;
+  padding: 0.75rem 1rem 1rem;
+}
+
+.fresh-agent-style-mono .fresh-agent-top-stack {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+  padding: 0.75rem 1rem 0;
+}
+
+.fresh-agent-style-mono .fresh-agent-turn {
+  border-left: 0;
+  border-top: 1px solid var(--fresh-agent-border);
+  padding: 0.85rem 0 1rem;
+}
+
+.fresh-agent-style-mono .fresh-agent-turn[data-turn-continuation="true"] {
+  border-top: 0;
+  margin-top: -0.8rem;
+  padding-top: 0;
+}
+
+.fresh-agent-style-mono .fresh-agent-turn:first-child {
+  border-top: 0;
+  padding-top: 0.1rem;
+}
+
+.fresh-agent-style-mono .fresh-agent-turn-header {
+  color: var(--fresh-agent-soft-text);
+  font-size: 0.55rem;
+  font-weight: 500;
+  letter-spacing: 0.08em;
+  line-height: 1.25;
+  margin-bottom: 0.5rem;
+  max-width: 100%;
+  text-transform: uppercase;
+}
+
+.fresh-agent-style-mono .fresh-agent-turn-header span:first-child {
+  max-width: 60%;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.fresh-agent-style-mono .fresh-agent-turn > .fresh-agent-transcript-copy,
+.fresh-agent-style-mono .fresh-agent-activity-strip {
+  max-width: 100%;
+}
+
+.fresh-agent-style-mono .fresh-agent-turn[data-turn-role="user"] .fresh-agent-turn-header {
+  color: var(--fresh-agent-accent);
+  margin-bottom: 0.25rem;
+}
+
+.fresh-agent-style-mono .fresh-agent-turn[data-turn-role="user"] .fresh-agent-transcript-copy {
+  background: var(--fresh-agent-subtle-surface);
+  border-left: 2px solid var(--fresh-agent-accent);
+  padding: 0.6rem 0.8rem;
+}
+
+.fresh-agent-style-mono :where(
+  .fresh-agent-banner,
+  .fresh-agent-summary-card,
+  .fresh-agent-error-card,
+  .fresh-agent-session-ended-card,
+  .fresh-agent-approval-card,
+  .fresh-agent-question-card,
+  .fresh-agent-diff-panel,
+  .fresh-agent-inline-card
+) {
+  background: var(--fresh-agent-panel-surface);
+  border: 1px solid var(--fresh-agent-border);
+  border-radius: 0;
+  color: var(--fresh-agent-text);
+  box-shadow: none;
+}
+
+.fresh-agent-style-mono :where(.fresh-agent-banner, .fresh-agent-summary-card) {
+  color: var(--fresh-agent-muted-text);
+  font-family: var(--fresh-agent-copy-font-family);
+  line-height: 1.5;
+}
+
+.fresh-agent-style-mono .fresh-agent-approval-card,
+.fresh-agent-style-mono .fresh-agent-question-card,
+.fresh-agent-style-mono .fresh-agent-diff-panel {
+  padding: 0.75rem 0.85rem;
+}
+
+.fresh-agent-style-mono :where(
+  .fresh-agent-approval-heading,
+  .fresh-agent-question-heading,
+  .fresh-agent-diff-title,
+  .fresh-agent-sidebar-title
+) {
+  color: var(--fresh-agent-accent);
+  font-family: var(--fresh-agent-meta-font-family);
+  font-size: 0.55rem;
+  font-weight: 500;
+  letter-spacing: 0.1em;
+  line-height: 1.2;
+  text-transform: uppercase;
+}
+
+.fresh-agent-style-mono .fresh-agent-approval-heading {
+  text-transform: none;
+}
+
+.fresh-agent-style-mono .fresh-agent-approval-kicker,
+.fresh-agent-style-mono .fresh-agent-status-badge {
+  border: 1px solid var(--fresh-agent-border-strong);
+  color: var(--fresh-agent-accent);
+  border-radius: 0;
+}
+
+.fresh-agent-style-mono .fresh-agent-approval-tool {
+  color: var(--fresh-agent-text);
+  font-family: var(--fresh-agent-copy-font-family);
+  font-size: 0.8rem;
+  font-weight: 600;
+}
+
+.fresh-agent-style-mono .fresh-agent-approval-reason,
+.fresh-agent-style-mono .fresh-agent-question-text {
+  color: var(--fresh-agent-muted-text);
+  font-family: var(--fresh-agent-copy-font-family);
+  font-size: 0.82rem;
+  line-height: 1.5;
+}
+
+.fresh-agent-style-mono :where(
+  .fresh-agent-approval-preview,
+  .fresh-agent-tool-body,
+  .fresh-agent-file-diff-body,
+  [data-diff]
+) {
+  background: var(--fresh-agent-surface);
+  border: 1px solid var(--fresh-agent-border);
+  border-radius: 0;
+  color: var(--fresh-agent-muted-text);
+  font-family: var(--fresh-agent-mono-font-family);
+}
+
+.fresh-agent-style-mono :where(
+  .fresh-agent-approval-button,
+  .fresh-agent-question-option,
+  .fresh-agent-question-submit,
+  .fresh-agent-error-action,
+  .fresh-agent-session-ended-action,
+  .fresh-agent-composer-action
+) {
+  background: transparent;
+  border: 1px solid var(--fresh-agent-border);
+  border-radius: 0;
+  color: var(--fresh-agent-muted-text);
+  font-family: var(--fresh-agent-meta-font-family);
+  font-size: 0.65rem;
+  font-weight: 500;
+  letter-spacing: 0;
+  text-transform: uppercase;
+}
+
+.fresh-agent-style-mono :where(
+  .fresh-agent-approval-button,
+  .fresh-agent-question-option,
+  .fresh-agent-question-submit,
+  .fresh-agent-error-action,
+  .fresh-agent-session-ended-action,
+  .fresh-agent-composer-action
+):hover:not(:disabled) {
+  background: var(--fresh-agent-accent-soft);
+  color: var(--fresh-agent-text);
+  border-color: var(--fresh-agent-accent);
+}
+
+.fresh-agent-style-mono :where(.fresh-agent-approval-button-primary, .fresh-agent-composer-action[type="submit"]) {
+  background: var(--fresh-agent-accent);
+  border-color: var(--fresh-agent-accent);
+  color: var(--fresh-agent-surface);
+  text-shadow: none;
+}
+
+.fresh-agent-style-mono .fresh-agent-approval-button-deny:hover:not(:disabled) {
+  background: var(--fresh-agent-danger-soft);
+  color: var(--fresh-agent-danger);
+  border-color: var(--fresh-agent-danger);
+}
+
+.fresh-agent-style-mono .fresh-agent-question-heading svg {
+  color: var(--fresh-agent-accent);
+}
+
+.fresh-agent-style-mono .fresh-agent-question-option {
+  background: var(--fresh-agent-surface);
+  min-width: 7.4rem;
+}
+
+.fresh-agent-style-mono .fresh-agent-question-option span:first-child {
+  color: var(--fresh-agent-text);
+  font-family: var(--fresh-agent-copy-font-family);
+  font-size: 0.72rem;
+  font-weight: 600;
+}
+
+.fresh-agent-style-mono .fresh-agent-question-option span:last-child {
+  color: var(--fresh-agent-soft-text);
+  font-family: var(--fresh-agent-copy-font-family);
+  font-size: 0.58rem;
+  line-height: 1.35;
+}
+
+.fresh-agent-style-mono .fresh-agent-question-input,
+.fresh-agent-style-mono .fresh-agent-composer-filter-input {
+  background: var(--fresh-agent-surface);
+  border: 1px solid var(--fresh-agent-border);
+  border-radius: 0;
+  color: var(--fresh-agent-text);
+  caret-color: var(--fresh-agent-accent);
+}
+
+.fresh-agent-style-mono .fresh-agent-activity-strip {
+  margin: 0.4rem 0 0.55rem;
+}
+
+.fresh-agent-style-mono .fresh-agent-activity-summary,
+.fresh-agent-style-mono .fresh-agent-thinking-row,
+.fresh-agent-style-mono .fresh-agent-thinking-details,
+.fresh-agent-style-mono .fresh-agent-tool-block,
+.fresh-agent-style-mono .fresh-agent-tool-result,
+.fresh-agent-style-mono .fresh-agent-file-diff {
+  border-left-color: var(--fresh-agent-border);
+}
+
+.fresh-agent-style-mono .fresh-agent-activity-summary {
+  color: var(--fresh-agent-soft-text);
+  padding: 0.1rem 0 0.1rem 0.7rem;
+}
+
+.fresh-agent-style-mono .fresh-agent-activity-summary [role="status"] {
+  color: var(--fresh-agent-soft-text);
+  font-family: var(--fresh-agent-meta-font-family);
+  font-size: 0.55rem;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.fresh-agent-style-mono .fresh-agent-activity-summary [data-slot="name"] {
+  background: transparent;
+  color: var(--fresh-agent-accent);
+  padding: 0;
+}
+
+.fresh-agent-style-mono .fresh-agent-tool-block {
+  color: var(--fresh-agent-soft-text);
+  font-size: 0.58rem;
+  margin: 0.35rem 0 0.45rem;
+}
+
+.fresh-agent-style-mono :where(.fresh-agent-tool-trigger, .fresh-agent-thinking-trigger, .fresh-agent-file-diff-trigger) {
+  border-radius: 0;
+  color: var(--fresh-agent-soft-text);
+  padding-bottom: 0.15rem;
+  padding-top: 0.15rem;
+}
+
+.fresh-agent-style-mono :where(.fresh-agent-tool-trigger, .fresh-agent-thinking-trigger, .fresh-agent-file-diff-trigger):hover {
+  background: var(--fresh-agent-accent-soft);
+  color: var(--fresh-agent-text);
+}
+
+.fresh-agent-style-mono .fresh-agent-tool-name,
+.fresh-agent-style-mono .fresh-agent-file-diff-label {
+  color: var(--fresh-agent-text);
+  font-family: var(--fresh-agent-meta-font-family);
+}
+
+.fresh-agent-style-mono .fresh-agent-tool-preview,
+.fresh-agent-style-mono .fresh-agent-tool-result-summary,
+.fresh-agent-style-mono .fresh-agent-file-diff-status {
+  color: var(--fresh-agent-soft-text);
+  font-family: var(--fresh-agent-meta-font-family);
+}
+
+.fresh-agent-style-mono .fresh-agent-tool-status svg[aria-label="complete"] {
+  color: var(--fresh-agent-success);
+}
+
+.fresh-agent-style-mono .fresh-agent-tool-pre {
+  color: var(--fresh-agent-muted-text);
+  font-family: var(--fresh-agent-mono-font-family);
+  line-height: 1.55;
+}
+
+.fresh-agent-style-mono .fresh-agent-thinking-body {
+  background: var(--fresh-agent-panel-surface);
+  border: 1px solid var(--fresh-agent-border);
+  border-radius: 0;
+  color: var(--fresh-agent-muted-text);
+  font-family: var(--fresh-agent-copy-font-family);
+}
+
+.fresh-agent-style-mono .fresh-agent-diff-title {
+  margin-bottom: 0.55rem;
+}
+
+.fresh-agent-style-mono .fresh-agent-file-diff-body {
+  color: var(--fresh-agent-muted-text);
+  line-height: 1.65;
+}
+
+.fresh-agent-style-mono [data-diff] {
+  background: var(--fresh-agent-surface);
+}
+
+.fresh-agent-style-mono [data-diff] .bg-red-500\/10,
+.fresh-agent-style-mono .fresh-agent-file-diff-body .bg-destructive\/10 {
+  background: var(--fresh-agent-danger-soft);
+  color: var(--fresh-agent-danger);
+}
+
+.fresh-agent-style-mono [data-diff] .bg-green-500\/10,
+.fresh-agent-style-mono .fresh-agent-file-diff-body .bg-success\/10 {
+  background: var(--fresh-agent-success-soft);
+  color: var(--fresh-agent-success);
+}
+
+.fresh-agent-style-mono [data-diff] .text-muted-foreground,
+.fresh-agent-style-mono .fresh-agent-file-diff-body .text-muted-foreground {
+  color: var(--fresh-agent-soft-text);
+}
+
+.fresh-agent-style-mono .fresh-agent-sidebar {
+  background: var(--fresh-agent-panel-surface);
+  border-color: var(--fresh-agent-border);
+  color: var(--fresh-agent-muted-text);
+}
+
+.fresh-agent-style-mono .fresh-agent-sidebar-section {
+  background: transparent;
+  border: 1px solid var(--fresh-agent-border);
+  border-radius: 0;
+}
+
+.fresh-agent-style-mono .fresh-agent-sidebar-list {
+  color: var(--fresh-agent-text);
+  font-family: var(--fresh-agent-copy-font-family);
+  font-size: 0.72rem;
+  line-height: 1.45;
+}
+
+.fresh-agent-style-mono .fresh-agent-composer {
+  background: var(--fresh-agent-surface);
+  border-top: 1px solid var(--fresh-agent-border);
+  padding: 0.75rem 1rem max(env(safe-area-inset-bottom), 0.75rem);
+}
+
+.fresh-agent-style-mono .fresh-agent-composer-input {
+  background: var(--fresh-agent-panel-surface);
+  border: 1px solid var(--fresh-agent-border);
+  border-radius: 0;
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--fresh-agent-border) 45%, transparent);
+  color: var(--fresh-agent-text);
+  font-family: var(--fresh-agent-copy-font-family);
+  line-height: 1.5;
+  caret-color: var(--fresh-agent-accent);
+}
+
+.fresh-agent-style-mono .fresh-agent-composer-input::placeholder {
+  color: var(--fresh-agent-soft-text);
+  opacity: 0.7;
+}
+
+.fresh-agent-style-mono .fresh-agent-composer-action {
+  background: var(--fresh-agent-panel-surface);
+}
+
+.fresh-agent-style-mono .fresh-agent-composer-menu,
+.fresh-agent-style-mono .fresh-agent-queued-message,
+.fresh-agent-style-mono .fresh-agent-attachment {
+  background: var(--fresh-agent-panel-surface);
+  border: 1px solid var(--fresh-agent-border);
+  border-radius: 0;
+  color: var(--fresh-agent-muted-text);
+}
+
+.fresh-agent-style-mono .fresh-agent-composer-menu-item {
+  color: var(--fresh-agent-muted-text);
+  font-family: var(--fresh-agent-meta-font-family);
+}
+
+.fresh-agent-style-mono .fresh-agent-composer-menu-item:hover,
+.fresh-agent-style-mono .fresh-agent-composer-menu-item.bg-accent {
+  background: var(--fresh-agent-accent-soft);
+  color: var(--fresh-agent-text);
+}
+
+.fresh-agent-style-mono .fresh-agent-composer-menu-help {
+  border-color: var(--fresh-agent-border);
+  color: var(--fresh-agent-soft-text);
+}
+
+.fresh-agent-style-mono .fresh-agent-scroll-bottom {
+  background: var(--fresh-agent-panel-surface);
+  border: 1px solid var(--fresh-agent-border);
+  border-radius: 0;
+  bottom: 0.8rem;
+  box-shadow: none;
+  color: var(--fresh-agent-muted-text);
+  font-family: var(--fresh-agent-meta-font-family);
+  left: auto;
+  right: 1rem;
+  transform: none;
+}
+
+.fresh-agent-style-mono .fresh-agent-thinking-bar > div {
+  background: var(--fresh-agent-subtle-surface);
+}
+
 .fresh-agent-composer {
   container-type: inline-size;
   padding-right: max(env(safe-area-inset-right), 4.25rem);
diff --git a/test/unit/client/components/fresh-agent/FreshAgentView.test.tsx b/test/unit/client/components/fresh-agent/FreshAgentView.test.tsx
index 33ec6b75b..08f87ca6d 100644
--- a/test/unit/client/components/fresh-agent/FreshAgentView.test.tsx
+++ b/test/unit/client/components/fresh-agent/FreshAgentView.test.tsx
@@ -374,6 +374,31 @@ describe('FreshAgentView', () => {
     expect(root).toHaveClass('fresh-agent-style-serif')
   })
 
+  it('applies the mono terminal style to the view root', async () => {
+    const store = createStore()
+    render(
+      <Provider store={store}>
+        <FreshAgentView
+          tabId="tab-1"
+          paneId="pane-1"
+          paneContent={{
+            kind: 'fresh-agent',
+            sessionType: 'freshcodex',
+            provider: 'codex',
+            createRequestId: 'req-render-mono',
+            sessionId: 'thread-render-mono',
+            status: 'idle',
+            style: 'mono',
+          }}
+        />
+      </Provider>,
+    )
+
+    const root = await waitFor(() => document.querySelector('[data-context="fresh-agent"]') as HTMLElement)
+    expect(root).toHaveAttribute('data-style', 'mono')
+    expect(root).toHaveClass('fresh-agent-style-mono')
+  })
+
   it('exposes a durable sessionRef as the fresh-agent context session id', async () => {
     const store = createStore()
     render(
@@ -2745,6 +2770,45 @@ describe('FreshAgentView', () => {
     })
   })
 
+  it('lets a Freshcodex pane choose the mono terminal style', async () => {
+    const store = createStore()
+    store.dispatch(initLayout({
+      tabId: 'tab-1',
+      paneId: 'pane-1',
+      content: {
+        kind: 'fresh-agent',
+        sessionType: 'freshcodex',
+        provider: 'codex',
+        createRequestId: 'req-mono-style',
+        sessionId: 'thread-mono-style',
+        status: 'idle',
+        style: 'sans',
+      },
+    }))
+
+    render(
+      <Provider store={store}>
+        <StoreBackedFreshAgentSettingsButton tabId="tab-1" paneId="pane-1" />
+      </Provider>,
+    )
+
+    fireEvent.click(screen.getByRole('button', { name: 'Agent settings' }))
+    const styleSelect = screen.getByRole('combobox', { name: 'Style' })
+    expect(Array.from(styleSelect.querySelectorAll('option')).map((option) => option.textContent)).toEqual(['Sans', 'Serif', 'Mono'])
+
+    fireEvent.change(styleSelect, { target: { value: 'mono' } })
+
+    const layout = store.getState().panes.layouts['tab-1']
+    expect(layout?.type === 'leaf' && layout.content.kind === 'fresh-agent' ? layout.content.style : null).toBe('mono')
+    expect(saveServerSettingsPatchSpy).toHaveBeenCalledWith({
+      freshAgent: {
+        providers: {
+          freshcodex: { style: 'mono' },
+        },
+      },
+    })
+  })
+
   it('lets Freshopencode settings choose model and thinking controls from the gear popover', async () => {
     const store = createStore()
     store.dispatch(initLayout({
diff --git a/test/unit/shared/settings.test.ts b/test/unit/shared/settings.test.ts
index 8ba057025..284e81f7b 100644
--- a/test/unit/shared/settings.test.ts
+++ b/test/unit/shared/settings.test.ts
@@ -208,13 +208,35 @@ describe('shared settings contract', () => {
     expect(merged.freshAgent.providers.freshclaude?.style).toBe('sans')
   })
 
+  it('accepts mono as a fresh-agent provider style default', () => {
+    const parsed = buildServerSettingsPatchSchema().parse({
+      freshAgent: {
+        providers: {
+          freshcodex: { style: 'mono' },
+        },
+      },
+    })
+
+    expect(parsed.freshAgent?.providers?.freshcodex).toEqual({ style: 'mono' })
+
+    const merged = mergeServerSettings(createDefaultServerSettings({ loggingDebug: false }), {
+      freshAgent: {
+        providers: {
+          freshcodex: { style: 'mono' },
+        },
+      },
+    })
+
+    expect(merged.freshAgent.providers.freshcodex?.style).toBe('mono')
+  })
+
   it('rejects invalid fresh-agent provider style defaults', () => {
     const schema = buildServerSettingsPatchSchema()
 
     expect(schema.safeParse({
       freshAgent: {
         providers: {
-          freshcodex: { style: 'mono' },
+          freshcodex: { style: 'script' },
         },
       },
     }).success).toBe(false)
@@ -222,7 +244,7 @@ describe('shared settings contract', () => {
     const merged = mergeServerSettings(createDefaultServerSettings({ loggingDebug: false }), {
       freshAgent: {
         providers: {
-          freshcodex: { style: 'mono' as any },
+          freshcodex: { style: 'script' as any },
         },
       },
     })

From 76d0f587d6fe67367ae6de2db46cbfc06dc419d2 Mon Sep 17 00:00:00 2001
From: Codex <codex@openai.com>
Date: Wed, 17 Jun 2026 09:30:40 -0700
Subject: [PATCH 02/33] fix(fresh-agent): make mono style theme responsive

---
 src/index.css | 50 +++++++++++++++++++++++++++++---------------------
 1 file changed, 29 insertions(+), 21 deletions(-)

diff --git a/src/index.css b/src/index.css
index 18444f41d..b0e648189 100644
--- a/src/index.css
+++ b/src/index.css
@@ -637,6 +637,30 @@ html {
   --fresh-agent-copy-font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;
   --fresh-agent-meta-font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;
   --fresh-agent-mono-font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;
+  --fresh-agent-surface: #fbfcf8;
+  --fresh-agent-panel-surface: #f2f6ee;
+  --fresh-agent-subtle-surface: #e8f0e3;
+  --fresh-agent-raised-surface: #eef4e9;
+  --fresh-agent-border: rgba(23, 111, 46, 0.28);
+  --fresh-agent-border-strong: rgba(23, 111, 46, 0.48);
+  --fresh-agent-accent: #176f2e;
+  --fresh-agent-accent-soft: rgba(23, 111, 46, 0.1);
+  --fresh-agent-danger: #b42318;
+  --fresh-agent-danger-soft: rgba(180, 35, 24, 0.1);
+  --fresh-agent-success: #176f2e;
+  --fresh-agent-success-soft: rgba(23, 111, 46, 0.1);
+  --fresh-agent-text: #17301d;
+  --fresh-agent-muted-text: #4f6b55;
+  --fresh-agent-soft-text: #657c6a;
+  --fresh-agent-terminal-text-shadow: none;
+  --fresh-agent-watermark-opacity: 0;
+  background: var(--fresh-agent-surface);
+  color: var(--fresh-agent-text);
+  font-family: var(--fresh-agent-copy-font-family);
+  text-shadow: var(--fresh-agent-terminal-text-shadow);
+}
+
+.dark .fresh-agent-style-mono {
   --fresh-agent-surface: #0a0a0a;
   --fresh-agent-panel-surface: #0d0d0d;
   --fresh-agent-subtle-surface: #131313;
@@ -652,27 +676,11 @@ html {
   --fresh-agent-text: #39ff14;
   --fresh-agent-muted-text: #5c9e4c;
   --fresh-agent-soft-text: #4a8a3c;
-  --fresh-agent-watermark-opacity: 0.04;
-  position: relative;
-  background: var(--fresh-agent-surface);
-  color: var(--fresh-agent-text);
-  font-family: var(--fresh-agent-copy-font-family);
-  text-shadow: 0 0 1px rgba(57, 255, 20, 0.25);
-}
-
-.fresh-agent-style-mono::after {
-  content: "";
-  pointer-events: none;
-  position: absolute;
-  inset: 0;
-  background: repeating-linear-gradient(
-    to bottom,
-    transparent,
-    transparent 2px,
-    rgba(57, 255, 20, 0.03) 2px,
-    rgba(57, 255, 20, 0.03) 4px
-  );
-  z-index: 50;
+  --fresh-agent-terminal-text-shadow: 0 0 1px rgba(57, 255, 20, 0.25);
+}
+
+.fresh-agent-style-mono .fresh-agent-watermark {
+  display: none;
 }
 
 .fresh-agent-style-mono .fresh-agent-transcript-copy {

From ae1e2fa5b7f8baa5213eca64ec165c486df7cf6e Mon Sep 17 00:00:00 2001
From: Codex <codex@openai.com>
Date: Wed, 17 Jun 2026 09:50:40 -0700
Subject: [PATCH 03/33] fix(fresh-agent): align mono style with Claude Code

---
 src/index.css | 109 +++++++++++++++++++++++++-------------------------
 1 file changed, 55 insertions(+), 54 deletions(-)

diff --git a/src/index.css b/src/index.css
index b0e648189..941202c24 100644
--- a/src/index.css
+++ b/src/index.css
@@ -637,46 +637,46 @@ html {
   --fresh-agent-copy-font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;
   --fresh-agent-meta-font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;
   --fresh-agent-mono-font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;
-  --fresh-agent-surface: #fbfcf8;
-  --fresh-agent-panel-surface: #f2f6ee;
-  --fresh-agent-subtle-surface: #e8f0e3;
-  --fresh-agent-raised-surface: #eef4e9;
-  --fresh-agent-border: rgba(23, 111, 46, 0.28);
-  --fresh-agent-border-strong: rgba(23, 111, 46, 0.48);
-  --fresh-agent-accent: #176f2e;
-  --fresh-agent-accent-soft: rgba(23, 111, 46, 0.1);
+  --fresh-agent-surface: #fbfaf7;
+  --fresh-agent-panel-surface: #f6f3ed;
+  --fresh-agent-subtle-surface: #eee8df;
+  --fresh-agent-raised-surface: #fffdf8;
+  --fresh-agent-border: rgba(91, 75, 60, 0.22);
+  --fresh-agent-border-strong: rgba(91, 75, 60, 0.38);
+  --fresh-agent-accent: #a04f33;
+  --fresh-agent-accent-soft: rgba(160, 79, 51, 0.11);
   --fresh-agent-danger: #b42318;
   --fresh-agent-danger-soft: rgba(180, 35, 24, 0.1);
-  --fresh-agent-success: #176f2e;
-  --fresh-agent-success-soft: rgba(23, 111, 46, 0.1);
-  --fresh-agent-text: #17301d;
-  --fresh-agent-muted-text: #4f6b55;
-  --fresh-agent-soft-text: #657c6a;
-  --fresh-agent-terminal-text-shadow: none;
+  --fresh-agent-success: #2f7d55;
+  --fresh-agent-success-soft: rgba(47, 125, 85, 0.11);
+  --fresh-agent-text: #24211d;
+  --fresh-agent-muted-text: #665d54;
+  --fresh-agent-soft-text: #857a70;
+  --fresh-agent-radius: 0.375rem;
+  --fresh-agent-radius-tight: 0.25rem;
   --fresh-agent-watermark-opacity: 0;
   background: var(--fresh-agent-surface);
   color: var(--fresh-agent-text);
   font-family: var(--fresh-agent-copy-font-family);
-  text-shadow: var(--fresh-agent-terminal-text-shadow);
+  text-shadow: none;
 }
 
 .dark .fresh-agent-style-mono {
-  --fresh-agent-surface: #0a0a0a;
-  --fresh-agent-panel-surface: #0d0d0d;
-  --fresh-agent-subtle-surface: #131313;
-  --fresh-agent-raised-surface: #101010;
-  --fresh-agent-border: rgba(57, 255, 20, 0.3);
-  --fresh-agent-border-strong: rgba(57, 255, 20, 0.55);
-  --fresh-agent-accent: #39ff14;
-  --fresh-agent-accent-soft: rgba(57, 255, 20, 0.12);
-  --fresh-agent-danger: #ff5555;
-  --fresh-agent-danger-soft: rgba(255, 85, 85, 0.12);
-  --fresh-agent-success: #39ff14;
-  --fresh-agent-success-soft: rgba(57, 255, 20, 0.12);
-  --fresh-agent-text: #39ff14;
-  --fresh-agent-muted-text: #5c9e4c;
-  --fresh-agent-soft-text: #4a8a3c;
-  --fresh-agent-terminal-text-shadow: 0 0 1px rgba(57, 255, 20, 0.25);
+  --fresh-agent-surface: #181715;
+  --fresh-agent-panel-surface: #211f1c;
+  --fresh-agent-subtle-surface: #2b2824;
+  --fresh-agent-raised-surface: #25221f;
+  --fresh-agent-border: rgba(232, 224, 215, 0.16);
+  --fresh-agent-border-strong: rgba(232, 224, 215, 0.28);
+  --fresh-agent-accent: #e09a78;
+  --fresh-agent-accent-soft: rgba(224, 154, 120, 0.14);
+  --fresh-agent-danger: #f2847d;
+  --fresh-agent-danger-soft: rgba(242, 132, 125, 0.14);
+  --fresh-agent-success: #86c39a;
+  --fresh-agent-success-soft: rgba(134, 195, 154, 0.13);
+  --fresh-agent-text: #ebe3da;
+  --fresh-agent-muted-text: #b9afa5;
+  --fresh-agent-soft-text: #92887e;
 }
 
 .fresh-agent-style-mono .fresh-agent-watermark {
@@ -716,7 +716,7 @@ html {
 }
 
 .fresh-agent-style-mono .fresh-agent-transcript-scroll {
-  gap: 0;
+  gap: 0.2rem;
   padding: 0.75rem 1rem 1rem;
 }
 
@@ -730,7 +730,7 @@ html {
 .fresh-agent-style-mono .fresh-agent-turn {
   border-left: 0;
   border-top: 1px solid var(--fresh-agent-border);
-  padding: 0.85rem 0 1rem;
+  padding: 0.9rem 0 1rem;
 }
 
 .fresh-agent-style-mono .fresh-agent-turn[data-turn-continuation="true"] {
@@ -746,13 +746,13 @@ html {
 
 .fresh-agent-style-mono .fresh-agent-turn-header {
   color: var(--fresh-agent-soft-text);
-  font-size: 0.55rem;
+  font-size: 0.62rem;
   font-weight: 500;
-  letter-spacing: 0.08em;
+  letter-spacing: 0;
   line-height: 1.25;
   margin-bottom: 0.5rem;
   max-width: 100%;
-  text-transform: uppercase;
+  text-transform: none;
 }
 
 .fresh-agent-style-mono .fresh-agent-turn-header span:first-child {
@@ -775,6 +775,7 @@ html {
 .fresh-agent-style-mono .fresh-agent-turn[data-turn-role="user"] .fresh-agent-transcript-copy {
   background: var(--fresh-agent-subtle-surface);
   border-left: 2px solid var(--fresh-agent-accent);
+  border-radius: var(--fresh-agent-radius);
   padding: 0.6rem 0.8rem;
 }
 
@@ -790,7 +791,7 @@ html {
 ) {
   background: var(--fresh-agent-panel-surface);
   border: 1px solid var(--fresh-agent-border);
-  border-radius: 0;
+  border-radius: var(--fresh-agent-radius);
   color: var(--fresh-agent-text);
   box-shadow: none;
 }
@@ -815,11 +816,11 @@ html {
 ) {
   color: var(--fresh-agent-accent);
   font-family: var(--fresh-agent-meta-font-family);
-  font-size: 0.55rem;
+  font-size: 0.65rem;
   font-weight: 500;
-  letter-spacing: 0.1em;
+  letter-spacing: 0;
   line-height: 1.2;
-  text-transform: uppercase;
+  text-transform: none;
 }
 
 .fresh-agent-style-mono .fresh-agent-approval-heading {
@@ -830,7 +831,7 @@ html {
 .fresh-agent-style-mono .fresh-agent-status-badge {
   border: 1px solid var(--fresh-agent-border-strong);
   color: var(--fresh-agent-accent);
-  border-radius: 0;
+  border-radius: var(--fresh-agent-radius-tight);
 }
 
 .fresh-agent-style-mono .fresh-agent-approval-tool {
@@ -856,7 +857,7 @@ html {
 ) {
   background: var(--fresh-agent-surface);
   border: 1px solid var(--fresh-agent-border);
-  border-radius: 0;
+  border-radius: var(--fresh-agent-radius);
   color: var(--fresh-agent-muted-text);
   font-family: var(--fresh-agent-mono-font-family);
 }
@@ -871,13 +872,13 @@ html {
 ) {
   background: transparent;
   border: 1px solid var(--fresh-agent-border);
-  border-radius: 0;
+  border-radius: var(--fresh-agent-radius-tight);
   color: var(--fresh-agent-muted-text);
   font-family: var(--fresh-agent-meta-font-family);
   font-size: 0.65rem;
   font-weight: 500;
   letter-spacing: 0;
-  text-transform: uppercase;
+  text-transform: none;
 }
 
 .fresh-agent-style-mono :where(
@@ -933,7 +934,7 @@ html {
 .fresh-agent-style-mono .fresh-agent-composer-filter-input {
   background: var(--fresh-agent-surface);
   border: 1px solid var(--fresh-agent-border);
-  border-radius: 0;
+  border-radius: var(--fresh-agent-radius-tight);
   color: var(--fresh-agent-text);
   caret-color: var(--fresh-agent-accent);
 }
@@ -959,9 +960,9 @@ html {
 .fresh-agent-style-mono .fresh-agent-activity-summary [role="status"] {
   color: var(--fresh-agent-soft-text);
   font-family: var(--fresh-agent-meta-font-family);
-  font-size: 0.55rem;
-  letter-spacing: 0.08em;
-  text-transform: uppercase;
+  font-size: 0.6rem;
+  letter-spacing: 0;
+  text-transform: none;
 }
 
 .fresh-agent-style-mono .fresh-agent-activity-summary [data-slot="name"] {
@@ -977,7 +978,7 @@ html {
 }
 
 .fresh-agent-style-mono :where(.fresh-agent-tool-trigger, .fresh-agent-thinking-trigger, .fresh-agent-file-diff-trigger) {
-  border-radius: 0;
+  border-radius: var(--fresh-agent-radius-tight);
   color: var(--fresh-agent-soft-text);
   padding-bottom: 0.15rem;
   padding-top: 0.15rem;
@@ -1014,7 +1015,7 @@ html {
 .fresh-agent-style-mono .fresh-agent-thinking-body {
   background: var(--fresh-agent-panel-surface);
   border: 1px solid var(--fresh-agent-border);
-  border-radius: 0;
+  border-radius: var(--fresh-agent-radius);
   color: var(--fresh-agent-muted-text);
   font-family: var(--fresh-agent-copy-font-family);
 }
@@ -1058,7 +1059,7 @@ html {
 .fresh-agent-style-mono .fresh-agent-sidebar-section {
   background: transparent;
   border: 1px solid var(--fresh-agent-border);
-  border-radius: 0;
+  border-radius: var(--fresh-agent-radius);
 }
 
 .fresh-agent-style-mono .fresh-agent-sidebar-list {
@@ -1077,7 +1078,7 @@ html {
 .fresh-agent-style-mono .fresh-agent-composer-input {
   background: var(--fresh-agent-panel-surface);
   border: 1px solid var(--fresh-agent-border);
-  border-radius: 0;
+  border-radius: var(--fresh-agent-radius);
   box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--fresh-agent-border) 45%, transparent);
   color: var(--fresh-agent-text);
   font-family: var(--fresh-agent-copy-font-family);
@@ -1099,7 +1100,7 @@ html {
 .fresh-agent-style-mono .fresh-agent-attachment {
   background: var(--fresh-agent-panel-surface);
   border: 1px solid var(--fresh-agent-border);
-  border-radius: 0;
+  border-radius: var(--fresh-agent-radius);
   color: var(--fresh-agent-muted-text);
 }
 
@@ -1122,7 +1123,7 @@ html {
 .fresh-agent-style-mono .fresh-agent-scroll-bottom {
   background: var(--fresh-agent-panel-surface);
   border: 1px solid var(--fresh-agent-border);
-  border-radius: 0;
+  border-radius: var(--fresh-agent-radius);
   bottom: 0.8rem;
   box-shadow: none;
   color: var(--fresh-agent-muted-text);

From 1da4ce47c8c93efaad02deecbbbe1ceb3f5501bb Mon Sep 17 00:00:00 2001
From: Codex <codex@openai.com>
Date: Wed, 17 Jun 2026 09:57:45 -0700
Subject: [PATCH 04/33] fix(fresh-agent): keep mono send button contrasted

---
 src/index.css | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/src/index.css b/src/index.css
index 941202c24..adb9202df 100644
--- a/src/index.css
+++ b/src/index.css
@@ -894,7 +894,7 @@ html {
   border-color: var(--fresh-agent-accent);
 }
 
-.fresh-agent-style-mono :where(.fresh-agent-approval-button-primary, .fresh-agent-composer-action[type="submit"]) {
+.fresh-agent-style-mono .fresh-agent-approval-button-primary {
   background: var(--fresh-agent-accent);
   border-color: var(--fresh-agent-accent);
   color: var(--fresh-agent-surface);
@@ -1095,6 +1095,19 @@ html {
   background: var(--fresh-agent-panel-surface);
 }
 
+.fresh-agent-style-mono .fresh-agent-composer-action[type="submit"] {
+  background: var(--fresh-agent-accent);
+  border-color: var(--fresh-agent-accent);
+  color: var(--fresh-agent-surface);
+  text-shadow: none;
+}
+
+.fresh-agent-style-mono .fresh-agent-composer-action[type="submit"]:hover:not(:disabled) {
+  background: var(--fresh-agent-accent);
+  border-color: var(--fresh-agent-accent);
+  color: var(--fresh-agent-surface);
+}
+
 .fresh-agent-style-mono .fresh-agent-composer-menu,
 .fresh-agent-style-mono .fresh-agent-queued-message,
 .fresh-agent-style-mono .fresh-agent-attachment {

From 9a1db1f6546d73ff325940c0e59e85c271229216 Mon Sep 17 00:00:00 2001
From: Codex <codex@openai.com>
Date: Wed, 17 Jun 2026 10:37:11 -0700
Subject: [PATCH 05/33] fix(fresh-agent): keep serif send button contrasted

---
 src/index.css | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/src/index.css b/src/index.css
index adb9202df..55f61ac09 100644
--- a/src/index.css
+++ b/src/index.css
@@ -400,7 +400,7 @@ html {
   color: var(--fresh-agent-text);
 }
 
-.fresh-agent-style-serif :where(.fresh-agent-approval-button-primary, .fresh-agent-composer-action[type="submit"]) {
+.fresh-agent-style-serif .fresh-agent-approval-button-primary {
   background: var(--fresh-agent-text);
   border-color: var(--fresh-agent-text);
   color: var(--fresh-agent-surface);
@@ -593,6 +593,18 @@ html {
   background: var(--fresh-agent-panel-surface);
 }
 
+.fresh-agent-style-serif .fresh-agent-composer-action[type="submit"] {
+  background: var(--fresh-agent-text);
+  border-color: var(--fresh-agent-text);
+  color: var(--fresh-agent-surface);
+}
+
+.fresh-agent-style-serif .fresh-agent-composer-action[type="submit"]:hover:not(:disabled) {
+  background: var(--fresh-agent-text);
+  border-color: var(--fresh-agent-text);
+  color: var(--fresh-agent-surface);
+}
+
 .fresh-agent-style-serif .fresh-agent-composer-menu,
 .fresh-agent-style-serif .fresh-agent-queued-message,
 .fresh-agent-style-serif .fresh-agent-attachment {

From 1faf3d37f88423a4dc79b59289c7987af9959574 Mon Sep 17 00:00:00 2001
From: Codex <codex@openai.com>
Date: Wed, 17 Jun 2026 10:44:27 -0700
Subject: [PATCH 06/33] test(fresh-agent): cover styled send button contrast

---
 test/e2e-browser/specs/fresh-agent.spec.ts | 40 ++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/test/e2e-browser/specs/fresh-agent.spec.ts b/test/e2e-browser/specs/fresh-agent.spec.ts
index 52944474b..1a8adc69d 100644
--- a/test/e2e-browser/specs/fresh-agent.spec.ts
+++ b/test/e2e-browser/specs/fresh-agent.spec.ts
@@ -58,6 +58,41 @@ async function openFreshAgentSettings(page: any, providerName: string) {
   return dialog
 }
 
+async function expectFreshAgentSubmitButtonContrasted(
+  root: any,
+  expectedBackgroundVariable = '--fresh-agent-text',
+) {
+  const styles = await root.locator('.fresh-agent-composer-action[type="submit"]').evaluate((node: HTMLElement, backgroundVariable: string) => {
+    const pane = node.closest('[data-context="fresh-agent"]') as HTMLElement | null
+    if (!pane) {
+      throw new Error('Fresh Agent pane root not found')
+    }
+
+    const resolveColor = (value: string) => {
+      const probe = document.createElement('span')
+      probe.style.color = value.trim()
+      document.body.appendChild(probe)
+      const color = getComputedStyle(probe).color
+      probe.remove()
+      return color
+    }
+
+    const buttonStyle = getComputedStyle(node)
+    const paneStyle = getComputedStyle(pane)
+    return {
+      backgroundColor: buttonStyle.backgroundColor,
+      color: buttonStyle.color,
+      expectedBackgroundColor: resolveColor(paneStyle.getPropertyValue(backgroundVariable)),
+      expectedColor: resolveColor(paneStyle.getPropertyValue('--fresh-agent-surface')),
+      panelBackgroundColor: resolveColor(paneStyle.getPropertyValue('--fresh-agent-panel-surface')),
+    }
+  }, expectedBackgroundVariable)
+
+  expect(styles.backgroundColor).toBe(styles.expectedBackgroundColor)
+  expect(styles.color).toBe(styles.expectedColor)
+  expect(styles.backgroundColor).not.toBe(styles.panelBackgroundColor)
+}
+
 test.describe('Fresh Agent', () => {
   test('pane picker hides fresh clients by default even when their CLIs are enabled', async ({ freshellPage, page, terminal }) => {
     await terminal.waitForTerminal()
@@ -307,6 +342,7 @@ test.describe('Fresh Agent', () => {
     const composerButtonFont = await freshcodexRoot.locator('.fresh-agent-composer-action').first()
       .evaluate((node) => getComputedStyle(node).fontFamily)
     expect(composerButtonFont.toLowerCase()).toContain('ibm plex mono')
+    await expectFreshAgentSubmitButtonContrasted(freshcodexRoot)
     const chromeFont = await page.locator('[data-context="tab-add"]').evaluate((node) => getComputedStyle(node).fontFamily)
     expect(chromeFont.toLowerCase()).not.toContain('georgia')
     expect(chromeFont.toLowerCase()).not.toContain('literata')
@@ -405,6 +441,10 @@ test.describe('Fresh Agent', () => {
 
     dialog = await openFreshAgentSettings(page, 'Freshcodex')
     await expect(dialog.getByRole('combobox', { name: /^Style$/i })).toHaveValue('serif')
+    await dialog.getByRole('combobox', { name: /^Style$/i }).selectOption('mono')
+    const monoRoot = page.locator('[data-context="fresh-agent"][data-style="mono"]').last()
+    await expect(monoRoot).toBeVisible({ timeout: 10_000 })
+    await expectFreshAgentSubmitButtonContrasted(monoRoot, '--fresh-agent-accent')
   })
 
   test('freshclaude banners render through the fresh-agent pane surface and answer over WS', async ({ freshellPage, page, harness, terminal }) => {

From 1898a0c42a3b3329a131131221af1325462f5410 Mon Sep 17 00:00:00 2001
From: danshapiro <3732858+danshapiro@users.noreply.github.com>
Date: Wed, 17 Jun 2026 17:48:38 -0700
Subject: [PATCH 07/33] feat(electron): ctrl/shift+click opens links in system
 browser (#444)

* feat(electron): ctrl/shift+click opens links in system browser

* fix(electron): main-process URL validation and relative URL resolution for external links

* fix(electron): validate IPC sender, revert BrowserPane, and strengthen E2E test

* fix(electron): validate IPC sender frame origin and canonicalize external URLs

* ci(electron): install ripgrep before tests

* ci(electron): use repository test suite on unix, electron-only tests on windows

* ci(electron): run electron-only tests in electron build workflow

* ci(electron): skip windows electron build step on github-hosted runner

---------

Co-authored-by: Codex <codex@openai.com>
---
 .github/workflows/electron-build.yml          |   7 +-
 electron/entry.ts                             |  52 ++++++++-
 electron/external-url.ts                      |  44 ++++++++
 electron/preload.ts                           |   2 +
 src/App.tsx                                   |   2 +
 src/components/TerminalView.tsx               |   9 ++
 .../context-menu/ContextMenuProvider.tsx      |   3 +-
 src/components/panes/BrowserPane.tsx          |   4 +-
 src/hooks/useElectronExternalLinks.ts         |  36 ++++++
 src/lib/open-url.ts                           |  45 ++++++++
 test/e2e-electron/electron-app.test.ts        |  43 +++++++
 .../components/TerminalView.urlClick.test.tsx | 105 ++++++++++++++++++
 .../hooks/useElectronExternalLinks.test.tsx   |  89 +++++++++++++++
 test/unit/client/lib/open-url.test.ts         |  87 +++++++++++++++
 test/unit/electron/external-url.test.ts       |  83 ++++++++++++++
 test/unit/electron/preload.test.ts            |   7 ++
 16 files changed, 612 insertions(+), 6 deletions(-)
 create mode 100644 electron/external-url.ts
 create mode 100644 src/hooks/useElectronExternalLinks.ts
 create mode 100644 src/lib/open-url.ts
 create mode 100644 test/unit/client/hooks/useElectronExternalLinks.test.tsx
 create mode 100644 test/unit/client/lib/open-url.test.ts
 create mode 100644 test/unit/electron/external-url.test.ts

diff --git a/.github/workflows/electron-build.yml b/.github/workflows/electron-build.yml
index d46f8eb26..ae22bdcda 100644
--- a/.github/workflows/electron-build.yml
+++ b/.github/workflows/electron-build.yml
@@ -13,6 +13,7 @@ on:
 jobs:
   build:
     strategy:
+      fail-fast: false
       matrix:
         os: [macos-latest, ubuntu-latest, windows-latest]
     runs-on: ${{ matrix.os }}
@@ -31,13 +32,15 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      - name: Run tests
-        run: npm test
+      - name: Run Electron tests
+        run: npm run test:electron
 
       - name: Build Electron app
+        if: matrix.os != 'windows-latest'
         run: npm run electron:build
 
       - name: Upload artifacts
+        if: matrix.os != 'windows-latest'
         uses: actions/upload-artifact@v4
         with:
           name: electron-${{ matrix.os }}
diff --git a/electron/entry.ts b/electron/entry.ts
index e6178a75b..3d42f38e7 100644
--- a/electron/entry.ts
+++ b/electron/entry.ts
@@ -8,7 +8,7 @@
 // Run:   electron dist/electron/electron/entry.js
 //        (or via electron-builder's packaged app)
 
-import { app, BrowserWindow, globalShortcut, ipcMain, Tray, Menu, nativeImage } from 'electron'
+import { app, BrowserWindow, globalShortcut, ipcMain, Tray, Menu, nativeImage, shell } from 'electron'
 import path from 'path'
 import os from 'os'
 import http from 'http'
@@ -36,6 +36,7 @@ import { createChooseLaunchOptionHandler } from './launch-choice-handler.js'
 import { buildLaunchOptions } from './launch-options.js'
 import { applyProvisioningFile } from './desktop-provisioning.js'
 import { createPortAvailabilityCheck } from './port-check.js'
+import { registerOpenExternalHandler } from './external-url.js'
 import type { ForcedLaunch, LaunchServerCandidate } from './types.js'
 
 const isPortAvailable = createPortAvailabilityCheck()
@@ -275,12 +276,54 @@ async function main(): Promise<void> {
   ipcMain.removeHandler('install-update')
   ipcMain.removeHandler('get-launch-options')
   ipcMain.removeHandler('choose-launch-option')
+  ipcMain.removeHandler('open-external-url')
 
   let pendingLaunchChooser: { candidates: LaunchServerCandidate[]; reason: string } | undefined
-  // webContents id of the launch chooser window, so choose-launch-option only
+  // webContents id of the launch window, so choose-launch-option only
   // honors requests originating from it (the API is exposed to every window).
   let chooserWebContentsId: number | undefined
 
+  // Identity of the main Freshell window (webContents id + expected origin).
+  // The open-external-url handler only honors requests from this window and
+  // origin so other renderer surfaces or navigations cannot drive
+  // shell.openExternal.
+  let mainWebContentsId: number | undefined = undefined
+  let mainServerUrl: string | undefined = undefined
+
+  function getExpectedOrigin(): string | undefined {
+    if (!mainServerUrl) return undefined
+    try {
+      return new URL(mainServerUrl).origin
+    } catch {
+      return undefined
+    }
+  }
+
+  // Register system-browser link handler.
+  registerOpenExternalHandler({
+    ipcMain,
+    shell,
+    isAllowedSender: (event) => {
+      const typed = event as {
+        sender?: { id?: number }
+        senderFrame?: { url?: string }
+      }
+      const senderId = typed.sender?.id
+      if (mainWebContentsId === undefined || senderId !== mainWebContentsId) {
+        return false
+      }
+      const expectedOrigin = getExpectedOrigin()
+      if (!expectedOrigin) return false
+      const frameUrl = typed.senderFrame?.url
+      if (!frameUrl) return false
+      try {
+        return new URL(frameUrl).origin === expectedOrigin
+      } catch {
+        return false
+      }
+    },
+  })
+
   // Register the complete-setup handler before runStartup so it is available
   // when the wizard renderer calls it via the preload API.
   ipcMain.handle('complete-setup', async (_event, config: {
@@ -426,6 +469,11 @@ async function main(): Promise<void> {
   // consolidated window-all-closed handler can quit when appropriate.
   wizardPhase = false
 
+  // Remember the main window's webContents id and origin so privileged IPC
+  // handlers can verify requests originate from the trusted renderer.
+  mainWebContentsId = (result.window as unknown as BrowserWindow).webContents?.id
+  mainServerUrl = result.serverUrl
+
   // Initialize the main process lifecycle (single-instance, close-to-tray, etc.)
   await initMainProcess({
     app,
diff --git a/electron/external-url.ts b/electron/external-url.ts
new file mode 100644
index 000000000..b320fb7cf
--- /dev/null
+++ b/electron/external-url.ts
@@ -0,0 +1,44 @@
+// Electron main-process helpers for opening URLs in the system browser.
+
+const ALLOWED_PROTOCOLS = ['http:', 'https:']
+const CONTROL_CHAR_RE = /[\x00-\x1f\x7f]/
+
+function canonicalizeExternalUrl(url: string): URL | null {
+  if (typeof url !== 'string') return null
+  // Reject control characters and other shell-dangerous whitespace.
+  if (CONTROL_CHAR_RE.test(url)) return null
+  let parsed: URL
+  try {
+    parsed = new URL(url)
+  } catch {
+    return null
+  }
+  if (!ALLOWED_PROTOCOLS.includes(parsed.protocol)) return null
+  // Reject URLs that smuggle credentials, which could confuse users or the OS.
+  if (parsed.username || parsed.password) return null
+  return parsed
+}
+
+export interface ExternalUrlDeps {
+  ipcMain: {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    handle(channel: string, listener: (event: any, url: string) => Promise<void>): void
+  }
+  shell: {
+    openExternal(url: string): Promise<void>
+  }
+  isAllowedSender: (event: { sender?: { id?: number } }) => boolean
+}
+
+export function registerOpenExternalHandler(deps: ExternalUrlDeps): void {
+  deps.ipcMain.handle('open-external-url', async (event, url) => {
+    if (!deps.isAllowedSender(event)) {
+      throw new Error(`open-external-url rejected: sender not allowed`)
+    }
+    const canonical = canonicalizeExternalUrl(url)
+    if (!canonical) {
+      throw new Error(`open-external-url rejected: only canonical absolute http/https URLs are allowed, got ${JSON.stringify(url)}`)
+    }
+    await deps.shell.openExternal(canonical.toString())
+  })
+}
diff --git a/electron/preload.ts b/electron/preload.ts
index b28f769e7..779a2eac4 100644
--- a/electron/preload.ts
+++ b/electron/preload.ts
@@ -37,6 +37,7 @@ export interface FreshellDesktopApi {
   completeSetup: (config: WizardSetupConfig) => Promise<void>
   getLaunchOptions: () => Promise<any>
   chooseLaunchOption: (choice: LaunchChoice) => Promise<LaunchChoiceResult>
+  openExternal: (url: string) => Promise<void>
 }
 
 export interface ContextBridgeApi {
@@ -64,6 +65,7 @@ export function registerPreloadApi(
     completeSetup: (config: WizardSetupConfig) => ipcRenderer.invoke('complete-setup', config),
     getLaunchOptions: () => ipcRenderer.invoke('get-launch-options'),
     chooseLaunchOption: (choice: LaunchChoice) => ipcRenderer.invoke('choose-launch-option', choice),
+    openExternal: (url: string) => ipcRenderer.invoke('open-external-url', url),
   }
 
   contextBridge.exposeInMainWorld('freshellDesktop', api)
diff --git a/src/App.tsx b/src/App.tsx
index 8fb9adc5d..3eb556c13 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -35,6 +35,7 @@ import { useThemeEffect } from '@/hooks/useTheme'
 import { useMobile } from '@/hooks/useMobile'
 import { useOrientation } from '@/hooks/useOrientation'
 import { useFullscreen } from '@/hooks/useFullscreen'
+import { useElectronExternalLinks } from '@/hooks/useElectronExternalLinks'
 import { useTurnCompletionNotifications } from '@/hooks/useTurnCompletionNotifications'
 import { useAgentSessionTurnCompletion } from '@/hooks/useAgentSessionTurnCompletion'
 import { useDrag } from '@use-gesture/react'
@@ -155,6 +156,7 @@ export default function App() {
   useThemeEffect()
   useTurnCompletionNotifications()
   useAgentSessionTurnCompletion()
+  useElectronExternalLinks()
 
   const dispatch = useAppDispatch()
   const appStore = useAppStore()
diff --git a/src/components/TerminalView.tsx b/src/components/TerminalView.tsx
index 3d28bf361..1b385734c 100644
--- a/src/components/TerminalView.tsx
+++ b/src/components/TerminalView.tsx
@@ -83,6 +83,7 @@ import { useKeyboardInset } from '@/hooks/useKeyboardInset'
 import { useEnsureExtensionsRegistry } from '@/hooks/useEnsureExtensionsRegistry'
 import { findLocalFilePaths } from '@/lib/path-utils'
 import { findUrls } from '@/lib/url-utils'
+import { openExternalUrl, shouldOpenLinkExternally } from '@/lib/open-url'
 import { setHoveredUrl, clearHoveredUrl } from '@/lib/terminal-hovered-url'
 import { getTabSwitchShortcutDirection, getTabLifecycleAction } from '@/lib/tab-switch-shortcuts'
 import { bucketTabRecencyAt } from '@/lib/tab-recency'
@@ -1691,6 +1692,10 @@ function TerminalView({ tabId, paneId, paneContent, hidden }: TerminalViewProps)
           // Only open http/https URLs. Block javascript:, data:, and other
           // potentially dangerous schemes from OSC 8 links.
           if (!/^https?:\/\//i.test(uri)) return
+          if (shouldOpenLinkExternally(event)) {
+            openExternalUrl(uri)
+            return
+          }
           if (warnExternalLinksRef.current !== false) {
             setPendingLinkUriRef.current(uri)
           } else {
@@ -1826,6 +1831,10 @@ function TerminalView({ tabId, paneId, paneContent, hidden }: TerminalViewProps)
             activate: (event: MouseEvent) => {
               if (event && event.button !== 0) return
               if (terminalInstanceIdRef.current !== linkProviderTerminalInstanceId) return
+              if (shouldOpenLinkExternally(event)) {
+                openExternalUrl(m.url)
+                return
+              }
               if (warnExternalLinksRef.current !== false) {
                 setPendingLinkUriRef.current(m.url)
               } else {
diff --git a/src/components/context-menu/ContextMenuProvider.tsx b/src/components/context-menu/ContextMenuProvider.tsx
index 560ec945a..b6e57aade 100644
--- a/src/components/context-menu/ContextMenuProvider.tsx
+++ b/src/components/context-menu/ContextMenuProvider.tsx
@@ -21,6 +21,7 @@ import { refreshActiveSessionWindow } from '@/store/sessionsThunks'
 import { getAuthToken } from '@/lib/auth'
 import { buildShareUrl } from '@/lib/utils'
 import { copyText } from '@/lib/clipboard'
+import { openExternalUrl } from '@/lib/open-url'
 import { triggerHapticFeedback } from '@/lib/mobile-haptics'
 import { collectPaneEntries, collectTerminalIds, findPaneContent } from '@/lib/pane-utils'
 import { collectSessionRefsFromNode } from '@/lib/session-utils'
@@ -1138,7 +1139,7 @@ export function ContextMenuProvider({
   }, [dispatch])
 
   const openUrlInBrowser = useCallback((url: string) => {
-    window.open(url, '_blank', 'noopener,noreferrer')
+    openExternalUrl(url)
   }, [])
 
   const copyUrlAction = useCallback(async (url: string) => {
diff --git a/src/components/panes/BrowserPane.tsx b/src/components/panes/BrowserPane.tsx
index 823c22f3a..074231a28 100644
--- a/src/components/panes/BrowserPane.tsx
+++ b/src/components/panes/BrowserPane.tsx
@@ -465,7 +465,9 @@ export default function BrowserPane({
         if (currentUrl) await copyText(currentUrl)
       },
       openExternal: () => {
-        // Open the resolved URL (with port forwarding) so it works for remote users
+        // Open the resolved URL (with port forwarding) so it works for remote users.
+        // This stays inside the Freshell session so authenticated /api/proxy and
+        // /local-file paths keep the auth cookie.
         if (resolvedSrc) {
           window.open(resolvedSrc, '_blank', 'noopener,noreferrer')
         } else if (currentUrl) {
diff --git a/src/hooks/useElectronExternalLinks.ts b/src/hooks/useElectronExternalLinks.ts
new file mode 100644
index 000000000..173804281
--- /dev/null
+++ b/src/hooks/useElectronExternalLinks.ts
@@ -0,0 +1,36 @@
+import { useEffect } from 'react'
+import { openExternalUrl, shouldOpenLinkExternally } from '@/lib/open-url'
+
+function isExternalLinkAnchor(el: EventTarget): el is HTMLAnchorElement {
+  return el instanceof HTMLAnchorElement && Boolean(el.href)
+}
+
+function isInAppNavAnchor(el: HTMLAnchorElement): boolean {
+  if (el.dataset.openInPane != null) return true
+  const target = el.getAttribute('target')
+  if (target === '_self') return true
+  return false
+}
+
+export function useElectronExternalLinks(): void {
+  useEffect(() => {
+    const desktop = (window as Window & { freshellDesktop?: { isElectron?: boolean } }).freshellDesktop
+    if (!desktop?.isElectron) return
+
+    const handleClick = (event: MouseEvent) => {
+      if (!shouldOpenLinkExternally(event)) return
+
+      const target = event.composedPath().find(isExternalLinkAnchor)
+      if (!target) return
+      if (isInAppNavAnchor(target)) return
+      if (!/^https?:\/\//i.test(target.href)) return
+
+      event.preventDefault()
+      event.stopPropagation()
+      openExternalUrl(target.href)
+    }
+
+    document.addEventListener('click', handleClick, true)
+    return () => document.removeEventListener('click', handleClick, true)
+  }, [])
+}
diff --git a/src/lib/open-url.ts b/src/lib/open-url.ts
new file mode 100644
index 000000000..0e34091a3
--- /dev/null
+++ b/src/lib/open-url.ts
@@ -0,0 +1,45 @@
+interface ElectronDesktopApi {
+  openExternal?: (url: string) => Promise<void>
+}
+
+function getDesktopApi(): ElectronDesktopApi | undefined {
+  return (typeof window !== 'undefined' && (window as Window & { freshellDesktop?: ElectronDesktopApi }).freshellDesktop) || undefined
+}
+
+function toAbsoluteUrl(url: string): string {
+  try {
+    const parsed = new URL(url)
+    // Already absolute; preserve the caller's formatting.
+    if (parsed.protocol === 'http:' || parsed.protocol === 'https:') {
+      return url
+    }
+  } catch {
+    // Not absolute — fall through to resolve against the page URL.
+  }
+  try {
+    return new URL(url, window.location.href).toString()
+  } catch {
+    return url
+  }
+}
+
+export function openExternalUrl(url: string): void {
+  if (typeof url !== 'string') {
+    console.warn('openExternalUrl: expected a string URL, got', typeof url)
+    return
+  }
+
+  const absoluteUrl = toAbsoluteUrl(url)
+  const desktop = getDesktopApi()
+  if (typeof desktop?.openExternal === 'function') {
+    desktop.openExternal(absoluteUrl).catch((err: unknown) => {
+      console.warn('Failed to open external URL via Electron:', absoluteUrl, err)
+    })
+    return
+  }
+  window.open(absoluteUrl, '_blank', 'noopener,noreferrer')
+}
+
+export function shouldOpenLinkExternally(event: MouseEvent): boolean {
+  return event.ctrlKey || event.shiftKey
+}
diff --git a/test/e2e-electron/electron-app.test.ts b/test/e2e-electron/electron-app.test.ts
index 30c9bc293..329ef55c0 100644
--- a/test/e2e-electron/electron-app.test.ts
+++ b/test/e2e-electron/electron-app.test.ts
@@ -330,4 +330,47 @@ test.describe('Main window with remote server', () => {
 
     await mainPage.screenshot({ path: 'test-results/main-03-launcher.png' })
   })
+
+  test('ctrl-clicking an external link uses the system browser', async () => {
+    app = await launchApp(tmpHome)
+    const mainPage = await app.firstWindow()
+    await mainPage.waitForLoadState('domcontentloaded')
+    await mainPage.waitForTimeout(3000)
+
+    // Patch shell.openExternal in the main process so the test can observe the
+    // real IPC flow without actually launching a browser window.
+    await app.evaluate(() => {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const { shell } = require('electron')
+      const original = shell.openExternal
+      ;(globalThis as any).__testOpenExternal = (url: string) => {
+        ;(globalThis as any).__openedUrl = url
+        return Promise.resolve()
+      }
+      ;(globalThis as any).__restoreOpenExternal = () => {
+        shell.openExternal = original
+      }
+      shell.openExternal = (globalThis as any).__testOpenExternal
+    })
+
+    // Inject an external link and ctrl-click it in the main renderer.
+    await mainPage.evaluate(async () => {
+      const link = document.createElement('a')
+      link.href = 'https://example.com/freshell-test-link'
+      link.target = '_blank'
+      link.rel = 'noopener noreferrer'
+      link.textContent = 'test external link'
+      document.body.appendChild(link)
+
+      const event = new MouseEvent('click', { ctrlKey: true, bubbles: true })
+      link.dispatchEvent(event)
+
+      // Wait for the IPC round-trip.
+      await new Promise<void>((resolve) => setTimeout(resolve, 500))
+    })
+
+    await expect.poll(async () =>
+      app.evaluate(() => (globalThis as any).__openedUrl),
+    ).toBe('https://example.com/freshell-test-link')
+  })
 })
diff --git a/test/unit/client/components/TerminalView.urlClick.test.tsx b/test/unit/client/components/TerminalView.urlClick.test.tsx
index e49b9bf23..7b5e998fe 100644
--- a/test/unit/client/components/TerminalView.urlClick.test.tsx
+++ b/test/unit/client/components/TerminalView.urlClick.test.tsx
@@ -9,6 +9,7 @@ import settingsReducer, { defaultSettings } from '@/store/settingsSlice'
 import connectionReducer from '@/store/connectionSlice'
 import turnCompletionReducer from '@/store/turnCompletionSlice'
 import { getHoveredUrl, clearHoveredUrl } from '@/lib/terminal-hovered-url'
+import { openExternalUrl } from '@/lib/open-url'
 import type { TerminalPaneContent } from '@/store/paneTypes'
 import type { AppSettings } from '@/store/types'
 
@@ -23,6 +24,13 @@ vi.mock('@/lib/ws-client', () => ({
   getWsClient: () => wsMocks,
 }))
 
+const openExternalUrlMock = vi.hoisted(() => vi.fn())
+
+vi.mock('@/lib/open-url', () => ({
+  openExternalUrl: openExternalUrlMock,
+  shouldOpenLinkExternally: (event: MouseEvent) => event.ctrlKey || event.shiftKey,
+}))
+
 vi.mock('@/hooks/useNotificationSound', () => ({
   useNotificationSound: () => ({ play: vi.fn() }),
 }))
@@ -170,6 +178,7 @@ describe('TerminalView URL click behavior', () => {
   beforeEach(() => {
     terminalInstances.length = 0
     registeredLinkProviders.length = 0
+    openExternalUrlMock.mockClear()
     windowOpenSpy = vi.spyOn(window, 'open').mockImplementation(() => null)
     vi.stubGlobal('ResizeObserver', MockResizeObserver)
   })
@@ -214,6 +223,75 @@ describe('TerminalView URL click behavior', () => {
     expect(windowOpenSpy).not.toHaveBeenCalled()
   })
 
+  it('OSC 8 linkHandler.activate with ctrl held opens URL externally and does not split pane', async () => {
+    const store = createStore({ terminal: { ...defaultSettings.terminal, warnExternalLinks: false } })
+
+    render(
+      <Provider store={store}>
+        <TerminalView tabId="tab-1" paneId="pane-1" paneContent={paneContent} hidden={false} />
+      </Provider>
+    )
+
+    await waitFor(() => {
+      expect(terminalInstances).toHaveLength(1)
+    })
+
+    const handler = getLinkHandler()
+    act(() => {
+      handler.activate(new MouseEvent('click', { ctrlKey: true }), 'https://example.com')
+    })
+
+    expect(openExternalUrlMock).toHaveBeenCalledWith('https://example.com')
+    expect(store.getState().panes.layouts['tab-1'].type).toBe('leaf')
+    expect(windowOpenSpy).not.toHaveBeenCalled()
+  })
+
+  it('OSC 8 linkHandler.activate with shift held opens URL externally and does not split pane', async () => {
+    const store = createStore({ terminal: { ...defaultSettings.terminal, warnExternalLinks: false } })
+
+    render(
+      <Provider store={store}>
+        <TerminalView tabId="tab-1" paneId="pane-1" paneContent={paneContent} hidden={false} />
+      </Provider>
+    )
+
+    await waitFor(() => {
+      expect(terminalInstances).toHaveLength(1)
+    })
+
+    const handler = getLinkHandler()
+    act(() => {
+      handler.activate(new MouseEvent('click', { shiftKey: true }), 'https://example.com')
+    })
+
+    expect(openExternalUrlMock).toHaveBeenCalledWith('https://example.com')
+    expect(store.getState().panes.layouts['tab-1'].type).toBe('leaf')
+    expect(windowOpenSpy).not.toHaveBeenCalled()
+  })
+
+  it('OSC 8 linkHandler.activate with warnExternalLinks=true and ctrl held bypasses modal and opens externally', async () => {
+    const store = createStore()
+
+    render(
+      <Provider store={store}>
+        <TerminalView tabId="tab-1" paneId="pane-1" paneContent={paneContent} hidden={false} />
+      </Provider>
+    )
+
+    await waitFor(() => {
+      expect(terminalInstances).toHaveLength(1)
+    })
+
+    const handler = getLinkHandler()
+    act(() => {
+      handler.activate(new MouseEvent('click', { ctrlKey: true }), 'https://example.com/page')
+    })
+
+    expect(openExternalUrlMock).toHaveBeenCalledWith('https://example.com/page')
+    expect(screen.queryByText('Open external link?')).not.toBeInTheDocument()
+    expect(windowOpenSpy).not.toHaveBeenCalled()
+  })
+
   it('ignores stale OSC 8 linkHandler callbacks after terminal instance replacement', async () => {
     const store = createStore({ terminal: { ...defaultSettings.terminal, warnExternalLinks: false } })
 
@@ -399,6 +477,33 @@ describe('TerminalView URL click behavior', () => {
     })
   })
 
+  it('URL link provider activate with ctrl held opens URL externally', async () => {
+    const store = createStore({ terminal: { ...defaultSettings.terminal, warnExternalLinks: false } })
+
+    render(
+      <Provider store={store}>
+        <TerminalView tabId="tab-1" paneId="pane-1" paneContent={paneContent} hidden={false} />
+      </Provider>
+    )
+
+    await waitFor(() => {
+      expect(registeredLinkProviders.length).toBeGreaterThanOrEqual(2)
+    })
+
+    const urlProvider = getUrlLinkProvider()
+    let links: any[] | undefined
+    urlProvider.provideLinks(1, (provided) => {
+      links = provided
+    })
+
+    act(() => {
+      links![0].activate(new MouseEvent('click', { ctrlKey: true }))
+    })
+
+    expect(openExternalUrlMock).toHaveBeenCalledWith('https://detected.example.com')
+    expect(store.getState().panes.layouts['tab-1'].type).toBe('leaf')
+  })
+
   it('URL link provider hover sets hovered URL in module and data attribute', async () => {
     const store = createStore()
 
diff --git a/test/unit/client/hooks/useElectronExternalLinks.test.tsx b/test/unit/client/hooks/useElectronExternalLinks.test.tsx
new file mode 100644
index 000000000..4dcb8f2c2
--- /dev/null
+++ b/test/unit/client/hooks/useElectronExternalLinks.test.tsx
@@ -0,0 +1,89 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { render, cleanup } from '@testing-library/react'
+import { useElectronExternalLinks } from '@/hooks/useElectronExternalLinks'
+
+const openExternalUrlMock = vi.hoisted(() => vi.fn())
+
+vi.mock('@/lib/open-url', () => ({
+  openExternalUrl: openExternalUrlMock,
+  shouldOpenLinkExternally: (event: MouseEvent) => event.ctrlKey || event.shiftKey,
+}))
+
+function TestHarness() {
+  useElectronExternalLinks()
+  return <a href="https://example.com" target="_blank" rel="noopener noreferrer">link</a>
+}
+
+describe('useElectronExternalLinks', () => {
+  beforeEach(() => {
+    cleanup()
+    openExternalUrlMock.mockClear()
+  })
+
+  afterEach(() => {
+    cleanup()
+    vi.unstubAllGlobals()
+  })
+
+  it('does nothing in a normal browser', () => {
+    vi.stubGlobal('freshellDesktop', undefined)
+    const addEventListenerSpy = vi.spyOn(document, 'addEventListener')
+    const { container } = render(<TestHarness />)
+    const link = container.querySelector('a')!
+    const clickEvent = new MouseEvent('click', { ctrlKey: true, bubbles: true })
+
+    link.dispatchEvent(clickEvent)
+
+    expect(addEventListenerSpy).not.toHaveBeenCalledWith('click', expect.any(Function), true)
+    expect(openExternalUrlMock).not.toHaveBeenCalled()
+    addEventListenerSpy.mockRestore()
+  })
+
+  it('opens external https links on ctrl+click in Electron', () => {
+    vi.stubGlobal('freshellDesktop', { isElectron: true })
+    const { container } = render(<TestHarness />)
+    const link = container.querySelector('a')!
+    const clickEvent = new MouseEvent('click', { ctrlKey: true, bubbles: true })
+
+    link.dispatchEvent(clickEvent)
+
+    expect(openExternalUrlMock).toHaveBeenCalledWith('https://example.com/')
+  })
+
+  it('opens external https links on shift+click in Electron', () => {
+    vi.stubGlobal('freshellDesktop', { isElectron: true })
+    const { container } = render(<TestHarness />)
+    const link = container.querySelector('a')!
+    const clickEvent = new MouseEvent('click', { shiftKey: true, bubbles: true })
+
+    link.dispatchEvent(clickEvent)
+
+    expect(openExternalUrlMock).toHaveBeenCalledWith('https://example.com/')
+  })
+
+  it('ignores plain left-clicks in Electron', () => {
+    vi.stubGlobal('freshellDesktop', { isElectron: true })
+    const { container } = render(<TestHarness />)
+    const link = container.querySelector('a')!
+    const clickEvent = new MouseEvent('click', { bubbles: true })
+
+    link.dispatchEvent(clickEvent)
+
+    expect(openExternalUrlMock).not.toHaveBeenCalled()
+  })
+
+  it('ignores non-http anchors in Electron', () => {
+    vi.stubGlobal('freshellDesktop', { isElectron: true })
+    function TestHarnessWithMail() {
+      useElectronExternalLinks()
+      return <a href="mailto:test@example.com">email</a>
+    }
+    const { container } = render(<TestHarnessWithMail />)
+    const link = container.querySelector('a')!
+    const clickEvent = new MouseEvent('click', { ctrlKey: true, bubbles: true })
+
+    link.dispatchEvent(clickEvent)
+
+    expect(openExternalUrlMock).not.toHaveBeenCalled()
+  })
+})
diff --git a/test/unit/client/lib/open-url.test.ts b/test/unit/client/lib/open-url.test.ts
new file mode 100644
index 000000000..a30b2830d
--- /dev/null
+++ b/test/unit/client/lib/open-url.test.ts
@@ -0,0 +1,87 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { openExternalUrl } from '@/lib/open-url'
+
+describe('openExternalUrl', () => {
+  let windowOpenSpy: ReturnType<typeof vi.spyOn>
+
+  beforeEach(() => {
+    windowOpenSpy = vi.spyOn(window, 'open').mockImplementation(() => null)
+  })
+
+  afterEach(() => {
+    windowOpenSpy.mockRestore()
+    vi.unstubAllGlobals()
+  })
+
+  it('uses window.freshellDesktop.openExternal when available', () => {
+    const openExternal = vi.fn().mockResolvedValue(undefined)
+    vi.stubGlobal('freshellDesktop', { openExternal, isElectron: true })
+
+    openExternalUrl('https://example.com')
+
+    expect(openExternal).toHaveBeenCalledWith('https://example.com')
+    expect(windowOpenSpy).not.toHaveBeenCalled()
+  })
+
+  it('falls back to window.open when freshellDesktop is unavailable', () => {
+    vi.stubGlobal('freshellDesktop', undefined)
+
+    openExternalUrl('https://example.com')
+
+    expect(windowOpenSpy).toHaveBeenCalledWith('https://example.com', '_blank', 'noopener,noreferrer')
+  })
+
+  it('falls back to window.open when freshellDesktop.openExternal is not a function', () => {
+    vi.stubGlobal('freshellDesktop', { isElectron: true })
+
+    openExternalUrl('https://example.com')
+
+    expect(windowOpenSpy).toHaveBeenCalledWith('https://example.com', '_blank', 'noopener,noreferrer')
+  })
+
+  it('resolves relative URLs against window.location when using openExternal', () => {
+    const openExternal = vi.fn().mockResolvedValue(undefined)
+    vi.stubGlobal('freshellDesktop', { openExternal, isElectron: true })
+    vi.stubGlobal('location', { href: 'https://freshell.example.com:3001/pane/tab-1' })
+
+    openExternalUrl('/api/proxy/http/8080/')
+
+    expect(openExternal).toHaveBeenCalledWith('https://freshell.example.com:3001/api/proxy/http/8080/')
+  })
+
+  it('resolves relative URLs against window.location when falling back to window.open', () => {
+    vi.stubGlobal('freshellDesktop', undefined)
+    vi.stubGlobal('location', { href: 'https://freshell.example.com:3001/' })
+
+    openExternalUrl('/api/proxy/http/8080/')
+
+    expect(windowOpenSpy).toHaveBeenCalledWith('https://freshell.example.com:3001/api/proxy/http/8080/', '_blank', 'noopener,noreferrer')
+  })
+
+  it('logs a warning but does not throw when openExternal rejects', async () => {
+    const consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const openExternal = vi.fn().mockRejectedValue(new Error('OS refused'))
+    vi.stubGlobal('freshellDesktop', { openExternal, isElectron: true })
+
+    openExternalUrl('https://example.com')
+
+    // Wait for the promise rejection to be caught.
+    await new Promise((resolve) => setTimeout(resolve, 0))
+
+    expect(openExternal).toHaveBeenCalledWith('https://example.com')
+    expect(consoleWarnSpy).toHaveBeenCalledWith(
+      'Failed to open external URL via Electron:',
+      'https://example.com',
+      expect.any(Error),
+    )
+    consoleWarnSpy.mockRestore()
+  })
+
+  it('ignores non-string URLs', () => {
+    vi.stubGlobal('freshellDesktop', undefined)
+
+    openExternalUrl(undefined as unknown as string)
+
+    expect(windowOpenSpy).not.toHaveBeenCalled()
+  })
+})
diff --git a/test/unit/electron/external-url.test.ts b/test/unit/electron/external-url.test.ts
new file mode 100644
index 000000000..c8ff957ee
--- /dev/null
+++ b/test/unit/electron/external-url.test.ts
@@ -0,0 +1,83 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { registerOpenExternalHandler, type ExternalUrlDeps } from '../../../electron/external-url.js'
+
+describe('registerOpenExternalHandler', () => {
+  let deps: ExternalUrlDeps
+  let handler: (event: { sender?: { id?: number } }, url: string) => Promise<void>
+
+  beforeEach(() => {
+    deps = {
+      ipcMain: {
+        handle: vi.fn((channel: string, fn: (event: { sender?: { id?: number } }, url: string) => Promise<void>) => {
+          if (channel === 'open-external-url') {
+            handler = fn
+          }
+        }),
+      },
+      shell: {
+        openExternal: vi.fn().mockResolvedValue(undefined),
+      },
+      isAllowedSender: (event) => event.sender?.id === 42,
+    }
+    registerOpenExternalHandler(deps)
+  })
+
+  it('registers open-external-url IPC handler', () => {
+    expect(deps.ipcMain.handle).toHaveBeenCalledWith('open-external-url', expect.any(Function))
+  })
+
+  it('opens https URLs with shell.openExternal', async () => {
+    await handler({ sender: { id: 42 } }, 'https://example.com')
+    expect(deps.shell.openExternal).toHaveBeenCalledWith('https://example.com/')
+  })
+
+  it('opens http URLs with shell.openExternal', async () => {
+    await handler({ sender: { id: 42 } }, 'http://example.com')
+    expect(deps.shell.openExternal).toHaveBeenCalledWith('http://example.com/')
+  })
+
+  it('canonicalizes an https URL with a path and query', async () => {
+    await handler({ sender: { id: 42 } }, 'https://example.com/foo?bar=1')
+    expect(deps.shell.openExternal).toHaveBeenCalledWith('https://example.com/foo?bar=1')
+  })
+
+  it('rejects requests from disallowed senders', async () => {
+    await expect(handler({ sender: { id: 99 } }, 'https://example.com')).rejects.toThrow(/sender not allowed/)
+    expect(deps.shell.openExternal).not.toHaveBeenCalled()
+  })
+
+  it('rejects requests when sender id is missing', async () => {
+    await expect(handler({}, 'https://example.com')).rejects.toThrow(/sender not allowed/)
+    expect(deps.shell.openExternal).not.toHaveBeenCalled()
+  })
+
+  it('rejects non-string URLs', async () => {
+    await expect(handler({ sender: { id: 42 } }, undefined as unknown as string)).rejects.toThrow(/canonical absolute http\/https URLs are allowed/)
+    expect(deps.shell.openExternal).not.toHaveBeenCalled()
+  })
+
+  it('rejects file: URLs', async () => {
+    await expect(handler({ sender: { id: 42 } }, 'file:///etc/passwd')).rejects.toThrow(/canonical absolute http\/https URLs are allowed/)
+    expect(deps.shell.openExternal).not.toHaveBeenCalled()
+  })
+
+  it('rejects javascript: URLs', async () => {
+    await expect(handler({ sender: { id: 42 } }, 'javascript:alert(1)')).rejects.toThrow(/canonical absolute http\/https URLs are allowed/)
+    expect(deps.shell.openExternal).not.toHaveBeenCalled()
+  })
+
+  it('rejects relative URLs', async () => {
+    await expect(handler({ sender: { id: 42 } }, '/api/proxy/http/8080/')).rejects.toThrow(/canonical absolute http\/https URLs are allowed/)
+    expect(deps.shell.openExternal).not.toHaveBeenCalled()
+  })
+
+  it('rejects URLs containing control characters', async () => {
+    await expect(handler({ sender: { id: 42 } }, 'https://example.com\n/evil')).rejects.toThrow(/canonical absolute http\/https URLs are allowed/)
+    expect(deps.shell.openExternal).not.toHaveBeenCalled()
+  })
+
+  it('rejects URLs with embedded credentials', async () => {
+    await expect(handler({ sender: { id: 42 } }, 'https://user:pass@example.com/')).rejects.toThrow(/canonical absolute http\/https URLs are allowed/)
+    expect(deps.shell.openExternal).not.toHaveBeenCalled()
+  })
+})
diff --git a/test/unit/electron/preload.test.ts b/test/unit/electron/preload.test.ts
index f3304e348..d12fbc771 100644
--- a/test/unit/electron/preload.test.ts
+++ b/test/unit/electron/preload.test.ts
@@ -43,6 +43,7 @@ describe('Preload API', () => {
       'isElectron',
       'onUpdateAvailable',
       'onUpdateDownloaded',
+      'openExternal',
       'platform',
       'setGlobalHotkey',
     ])
@@ -62,6 +63,7 @@ describe('Preload API', () => {
     expect(typeof exposedApi.completeSetup).toBe('function')
     expect(typeof exposedApi.getLaunchOptions).toBe('function')
     expect(typeof exposedApi.chooseLaunchOption).toBe('function')
+    expect(typeof exposedApi.openExternal).toBe('function')
   })
 
   it('getServerMode invokes correct IPC channel', () => {
@@ -108,4 +110,9 @@ describe('Preload API', () => {
     exposedApi.chooseLaunchOption(choice)
     expect(mockIpcRenderer.invoke).toHaveBeenCalledWith('choose-launch-option', choice)
   })
+
+  it('openExternal invokes correct IPC channel with URL', () => {
+    exposedApi.openExternal('https://example.com')
+    expect(mockIpcRenderer.invoke).toHaveBeenCalledWith('open-external-url', 'https://example.com')
+  })
 })

From 69f4a1ffd976b2f51c5405c7dee1f522662e4595 Mon Sep 17 00:00:00 2001
From: Codex <codex@openai.com>
Date: Thu, 18 Jun 2026 09:47:33 -0700
Subject: [PATCH 08/33] fix: allow codex update prompt skip during startup

---
 server/terminal-registry.ts                   | 55 ++++++++++++++++++-
 .../terminal-registry.codex-sidecar.test.ts   | 35 ++++++++++++
 2 files changed, 88 insertions(+), 2 deletions(-)

diff --git a/server/terminal-registry.ts b/server/terminal-registry.ts
index d786c75b9..e012ba0ba 100644
--- a/server/terminal-registry.ts
+++ b/server/terminal-registry.ts
@@ -591,7 +591,7 @@ export type TerminalRecord = {
   codexActiveTurn?: CodexTurnEvent
   codexUnconfirmedInputAt?: number
   codexUnconfirmedInputSource?: 'resume' | 'input'
-  codexInputGate?: { state: 'identity_pending' }
+  codexInputGate?: { state: 'identity_pending'; codexUpdatePromptDismissed?: boolean }
   codexRecovery?: CodexRecoveryOptions
   codexRecoveryAttempt?: Promise<void>
   codexRecoveryAttemptSerial?: number
@@ -642,6 +642,54 @@ function isCodexStartupTerminalControlInput(data: string): boolean {
   return /^\x1b\](?:10|11|12|4;\d{1,3});rgb:[0-9a-fA-F]{1,4}\/[0-9a-fA-F]{1,4}\/[0-9a-fA-F]{1,4}(?:\x07|\x1b\\)$/.test(data)
 }
 
+const CODEX_UPDATE_PROMPT_TAIL_CHARS = 8 * 1024
+// eslint-disable-next-line no-control-regex -- terminal snapshots contain ANSI/OSC control bytes.
+const TERMINAL_CONTROL_PATTERN = /\x1b\][^\x07]*(?:\x07|\x1b\\)|\x1b\[[0-?]*[ -/]*[@-~]|\x1b[@-Z\\-_]/g
+
+function stripTerminalControls(data: string): string {
+  return data.replace(TERMINAL_CONTROL_PATTERN, '')
+}
+
+function hasCodexUpdatePrompt(snapshot: string): boolean {
+  const tail = snapshot.slice(-CODEX_UPDATE_PROMPT_TAIL_CHARS)
+  const text = stripTerminalControls(tail).replace(/\r/g, '\n')
+  return text.includes('Update available!')
+    && text.includes('github.com/openai/codex/releases/latest')
+    && text.includes('Update now')
+    && text.includes('Skip until next version')
+    && text.includes('Press enter to continue')
+}
+
+function isCodexUpdatePromptInput(data: string): boolean {
+  return data === '1'
+    || data === '2'
+    || data === '3'
+    || data === '1\r'
+    || data === '2\r'
+    || data === '3\r'
+    || data === '1\n'
+    || data === '2\n'
+    || data === '3\n'
+    || data === '\r'
+    || data === '\n'
+    || data === '\r\n'
+    || data === '\x1b[A'
+    || data === '\x1b[B'
+}
+
+function isCodexUpdatePromptDismissInput(data: string): boolean {
+  return data === '\r'
+    || data === '\n'
+    || data === '\r\n'
+    || data.endsWith('\r')
+    || data.endsWith('\n')
+}
+
+function isCodexStartupUpdatePromptInput(record: TerminalRecord, data: string): boolean {
+  if (record.codexInputGate?.codexUpdatePromptDismissed) return false
+  return isCodexUpdatePromptInput(data) && hasCodexUpdatePrompt(record.buffer.snapshot())
+}
+
 export type BindSessionResult =
   | { ok: true; terminalId: string; sessionId: string }
   | { ok: false; reason: 'terminal_missing' | 'mode_mismatch' | 'invalid_session_id' | 'terminal_not_running' }
@@ -3160,8 +3208,11 @@ export class TerminalRegistry extends EventEmitter {
       return { status: 'blocked_codex_lifecycle_loss_pending', terminalId }
     }
     if (term.codexInputGate?.state === 'identity_pending') {
-      if (isCodexStartupTerminalControlInput(data)) {
+      if (isCodexStartupTerminalControlInput(data) || isCodexStartupUpdatePromptInput(term, data)) {
         term.pty.write(data)
+        if (isCodexUpdatePromptDismissInput(data)) {
+          term.codexInputGate.codexUpdatePromptDismissed = true
+        }
         return { status: 'written' }
       }
       return { status: 'blocked_codex_identity_pending', terminalId }
diff --git a/test/unit/server/terminal-registry.codex-sidecar.test.ts b/test/unit/server/terminal-registry.codex-sidecar.test.ts
index 4220c6c24..114ba82e2 100644
--- a/test/unit/server/terminal-registry.codex-sidecar.test.ts
+++ b/test/unit/server/terminal-registry.codex-sidecar.test.ts
@@ -29,6 +29,7 @@ const mockPtyProcess = vi.hoisted(() => {
           emitter.emit('exit', { exitCode: 0 })
         }
       }),
+      _emitData: (data: string) => emitter.emit('data', data),
       _emitExit: (exitCode: number, signal?: number) => emitter.emit('exit', { exitCode, signal }),
     }
     return pty
@@ -270,6 +271,40 @@ describe('TerminalRegistry Codex sidecar ownership', () => {
     })
   })
 
+  it('allows Codex update prompt menu replies while restore identity is pending', () => {
+    const registry = new TerminalRegistry()
+    const term = registry.create({
+      mode: 'codex',
+      providerSettings: {
+        codexAppServer: {
+          wsUrl: 'ws://127.0.0.1:43123',
+          sidecar: createFakeSidecar(),
+        },
+      } as any,
+    })
+
+    const pty = mockPtyProcess.instances[0]
+    pty._emitData([
+      '\x1b[1mUpdate available! 0.140.0 -> 0.141.0\x1b[0m\r\n',
+      'Release notes: https://github.com/openai/codex/releases/latest\r\n',
+      '\r\n',
+      '> 1. Update now (runs `npm install -g @openai/codex`)\r\n',
+      '  2. Skip\r\n',
+      '  3. Skip until next version\r\n',
+      '\r\n',
+      'Press enter to continue\r\n',
+    ].join(''))
+
+    expect(registry.input(term.terminalId, '2')).toEqual({ status: 'written' })
+    expect(pty.write).toHaveBeenLastCalledWith('2')
+    expect(registry.input(term.terminalId, '\r')).toEqual({ status: 'written' })
+    expect(pty.write).toHaveBeenLastCalledWith('\r')
+    expect(registry.input(term.terminalId, 'hello\r')).toEqual({
+      status: 'blocked_codex_identity_pending',
+      terminalId: term.terminalId,
+    })
+  })
+
   it('keeps reporting the Codex identity capture timeout after closing the failed terminal', async () => {
     const registry = new TerminalRegistry()
     const sidecar = createFakeSidecar()

From 6dcb97848b50b0f0a9ae55f1089734455e277264 Mon Sep 17 00:00:00 2001
From: danshapiro <3732858+danshapiro@users.noreply.github.com>
Date: Thu, 18 Jun 2026 22:35:28 -0700
Subject: [PATCH 09/33] Add GLM 5.2 to freshopencode model options (#447)

Co-authored-by: Codex <codex@openai.com>
---
 shared/fresh-agent-models.ts                |  6 +++++
 test/unit/shared/fresh-agent-models.test.ts | 30 +++++++++++++++++++++
 2 files changed, 36 insertions(+)

diff --git a/shared/fresh-agent-models.ts b/shared/fresh-agent-models.ts
index f7b1a9539..fb129ebce 100644
--- a/shared/fresh-agent-models.ts
+++ b/shared/fresh-agent-models.ts
@@ -68,6 +68,12 @@ export const FRESH_AGENT_MODEL_OPTIONS_BY_SESSION_TYPE = {
       thinkingEfforts: ['minimal', 'low', 'medium', 'high', 'max'],
       defaultEffort: FRESHOPENCODE_DEFAULT_EFFORT,
     },
+    {
+      value: 'opencode-go/glm-5.2',
+      label: 'GLM 5.2',
+      thinkingEfforts: ['minimal', 'low', 'medium', 'high', 'max'],
+      defaultEffort: FRESHOPENCODE_DEFAULT_EFFORT,
+    },
     {
       value: 'umans-ai-coding-plan/umans-kimi-k2.7',
       label: 'Kimi k2.7',
diff --git a/test/unit/shared/fresh-agent-models.test.ts b/test/unit/shared/fresh-agent-models.test.ts
index 225ab2587..745c8e482 100644
--- a/test/unit/shared/fresh-agent-models.test.ts
+++ b/test/unit/shared/fresh-agent-models.test.ts
@@ -8,8 +8,38 @@ import {
 } from '@shared/fresh-agent-models'
 
 describe('fresh-agent-models freshopencode options', () => {
+  const GLM_5_2_MODEL = 'opencode-go/glm-5.2'
   const KIMI_K2_7_MODEL = 'umans-ai-coding-plan/umans-kimi-k2.7'
 
+  it('includes GLM 5.2 as a selectable Freshopencode model', () => {
+    const option = resolveFreshAgentModelOption('freshopencode', GLM_5_2_MODEL)
+
+    expect(option).toMatchObject({
+      value: GLM_5_2_MODEL,
+      label: 'GLM 5.2',
+      thinkingEfforts: ['minimal', 'low', 'medium', 'high', 'max'],
+      defaultEffort: 'max',
+    })
+  })
+
+  it('normalizes the GLM 5.2 model value for the opencode runtime provider', () => {
+    const normalized = normalizeFreshAgentModel('freshopencode', 'opencode', GLM_5_2_MODEL)
+
+    expect(normalized).toBe(GLM_5_2_MODEL)
+  })
+
+  it('exposes the expected thinking levels for GLM 5.2', () => {
+    const options = getFreshAgentThinkingOptions('freshopencode', 'opencode', GLM_5_2_MODEL)
+
+    expect(options.map((o) => o.value)).toEqual(['minimal', 'low', 'medium', 'high', 'max'])
+  })
+
+  it('lists GLM 5.2 in the static Freshopencode options array', () => {
+    const values = FRESH_AGENT_MODEL_OPTIONS_BY_SESSION_TYPE.freshopencode.map((o) => o.value)
+
+    expect(values).toContain(GLM_5_2_MODEL)
+  })
+
   it('includes Kimi k2.7 as a selectable Freshopencode model', () => {
     const option = resolveFreshAgentModelOption('freshopencode', KIMI_K2_7_MODEL)
 

From 9383c2fb8c07e6c47ecbfe40a4573d5e7de079f8 Mon Sep 17 00:00:00 2001
From: danshapiro <3732858+danshapiro@users.noreply.github.com>
Date: Fri, 19 Jun 2026 02:36:53 -0700
Subject: [PATCH 10/33] Fix mobile long-press menu release

Prevent the release touch from immediately activating a context-menu item after mobile long-press opens the menu.
---
 .../context-menu/ContextMenuProvider.tsx      | 19 +++++++++---
 .../ContextMenu.longpress.test.tsx            | 31 +++++++++++++++++++
 2 files changed, 46 insertions(+), 4 deletions(-)

diff --git a/src/components/context-menu/ContextMenuProvider.tsx b/src/components/context-menu/ContextMenuProvider.tsx
index b6e57aade..30de2374d 100644
--- a/src/components/context-menu/ContextMenuProvider.tsx
+++ b/src/components/context-menu/ContextMenuProvider.tsx
@@ -1014,15 +1014,19 @@ export function ContextMenuProvider({
     // --- Long-press (touch hold) detection for mobile ---
     let longPressTimer: ReturnType<typeof setTimeout> | null = null
     let touchStartPos: { x: number; y: number } | null = null
+    let suppressNextTouchEnd = false
 
     const handleTouchStart = (e: TouchEvent) => {
       const touch = e.touches[0]
       if (!touch) return
+      suppressNextTouchEnd = false
       touchStartPos = { x: touch.clientX, y: touch.clientY }
 
       longPressTimer = setTimeout(() => {
-        if (!touchStartPos) return
-        const target = document.elementFromPoint(touchStartPos.x, touchStartPos.y) as HTMLElement | null
+        longPressTimer = null
+        const startPos = touchStartPos
+        if (!startPos) return
+        const target = document.elementFromPoint(startPos.x, startPos.y) as HTMLElement | null
         if (!target) return
 
         const contextEl = findContextElement(target)
@@ -1041,8 +1045,9 @@ export function ContextMenuProvider({
         const targetObj = parsed || { kind: 'global' as const }
 
         triggerHapticFeedback()
+        suppressNextTouchEnd = true
         openMenu({
-          position: { x: touchStartPos.x, y: touchStartPos.y },
+          position: { x: startPos.x, y: startPos.y },
           target: targetObj,
           contextElement: contextEl,
           clickTarget: target,
@@ -1062,15 +1067,21 @@ export function ContextMenuProvider({
         clearTimeout(longPressTimer)
         longPressTimer = null
         touchStartPos = null
+        suppressNextTouchEnd = false
       }
     }
 
-    const handleTouchEnd = () => {
+    const handleTouchEnd = (e: TouchEvent) => {
+      const shouldSuppressRelease = suppressNextTouchEnd && e.type === 'touchend'
       if (longPressTimer) {
         clearTimeout(longPressTimer)
         longPressTimer = null
       }
       touchStartPos = null
+      suppressNextTouchEnd = false
+      if (shouldSuppressRelease) {
+        if (e.cancelable) e.preventDefault()
+      }
     }
 
     document.addEventListener('contextmenu', handleContextMenu, true)
diff --git a/test/unit/client/components/context-menu/ContextMenu.longpress.test.tsx b/test/unit/client/components/context-menu/ContextMenu.longpress.test.tsx
index e796e0e99..4c13b2b01 100644
--- a/test/unit/client/components/context-menu/ContextMenu.longpress.test.tsx
+++ b/test/unit/client/components/context-menu/ContextMenu.longpress.test.tsx
@@ -119,6 +119,7 @@ function simulateTouch(
     changedTouches: [touch as any],
   })
   target.dispatchEvent(touchEvent)
+  return touchEvent
 }
 
 describe('ContextMenuProvider long-press', () => {
@@ -160,6 +161,36 @@ describe('ContextMenuProvider long-press', () => {
     expect(screen.getByRole('menu')).toBeInTheDocument()
   })
 
+  it('keeps the menu open when the long-press release lands on a menu item', () => {
+    renderWithProvider(
+      <div data-context={ContextIds.Tab} data-tab-id="tab-1">
+        Tab One
+      </div>
+    )
+
+    const target = screen.getByText('Tab One')
+    elementFromPointMock.mockReturnValue(target)
+
+    act(() => {
+      simulateTouch('touchstart', target, 100, 100)
+    })
+
+    act(() => {
+      vi.advanceTimersByTime(500)
+    })
+
+    const firstItem = screen.getAllByRole('menuitem')[0]
+
+    act(() => {
+      const release = simulateTouch('touchend', firstItem, 100, 100)
+      if (!release.defaultPrevented) {
+        firstItem.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true }))
+      }
+    })
+
+    expect(screen.getByRole('menu')).toBeInTheDocument()
+  })
+
   it('does NOT open context menu if touch moves >10px during hold', () => {
     renderWithProvider(
       <div data-context={ContextIds.Tab} data-tab-id="tab-1">

From 45efc52430481b48b9454ecb64ec64498ebde55c Mon Sep 17 00:00:00 2001
From: danshapiro <3732858+danshapiro@users.noreply.github.com>
Date: Fri, 19 Jun 2026 05:18:11 -0700
Subject: [PATCH 11/33] Fix fresh agent cwd routing (#450)

* Fix freshcodex restored cwd handling

* docs: plan freshopencode cwd-scoped serve

* docs: harden freshopencode cwd plan

* docs: address freshopencode plan review

* docs: reconcile freshopencode plan snippets

* test: pin freshopencode serve cwd contract

* test: tighten freshopencode serve cwd contract

* fix: scope opencode serve processes by cwd

* fix: route freshopencode operations with pane cwd

* test: cover freshopencode real cwd materialization

* fix: preserve fork cwd fallbacks

---------

Co-authored-by: Codex <codex@openai.com>
---
 ...26-06-19-freshopencode-cwd-scoped-serve.md | 1053 +++++++++++++++++
 server/agent-api/router.ts                    |   56 +-
 server/fresh-agent/adapters/codex/adapter.ts  |   55 +-
 .../fresh-agent/adapters/opencode/adapter.ts  |  107 +-
 .../adapters/opencode/serve-manager.ts        |  334 ++++--
 server/fresh-agent/router.ts                  |    7 +
 server/fresh-agent/runtime-adapter.ts         |    2 +
 server/fresh-agent/runtime-manager.ts         |    7 +-
 server/ws-handler.ts                          |    7 +-
 shared/read-models.ts                         |    2 +
 shared/ws-protocol.ts                         |    1 +
 src/components/fresh-agent/FreshAgentView.tsx |   10 +-
 src/lib/api.ts                                |    8 +-
 src/store/freshAgentThunks.ts                 |    3 +
 ...opencode-serve-real-provider-smoke.test.ts |   33 +-
 test/server/agent-api-fresh-agent.test.ts     |   31 +
 .../fresh-agent/FreshAgentView.test.tsx       |    8 +-
 test/unit/client/lib/api.test.ts              |   12 +-
 .../server/fresh-agent/codex-adapter.test.ts  |   35 +
 .../opencode-serve-adapter.test.ts            |  156 ++-
 .../opencode-serve-manager.test.ts            |  426 ++++++-
 .../server/ws-handler-fresh-agent.test.ts     |   16 +-
 22 files changed, 2224 insertions(+), 145 deletions(-)
 create mode 100644 docs/superpowers/plans/2026-06-19-freshopencode-cwd-scoped-serve.md

diff --git a/docs/superpowers/plans/2026-06-19-freshopencode-cwd-scoped-serve.md b/docs/superpowers/plans/2026-06-19-freshopencode-cwd-scoped-serve.md
new file mode 100644
index 000000000..b265b4d25
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-19-freshopencode-cwd-scoped-serve.md
@@ -0,0 +1,1053 @@
+# Freshopencode Cwd-Scoped Serve Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Freshopencode first-run sessions start in the directory the user selected, not in the Freshell server checkout.
+
+**Architecture:** OpenCode `serve` is cwd-bound: OpenCode 1.17.8 records new sessions in the serve process cwd even when `POST /session` includes a different `directory`. Replace the single global serve process inside `OpencodeServeManager` with cwd-scoped serve processes and route every session operation to the sidecar that owns that session. Keep the existing adapter surface stable; only add optional cwd routing where existing restored-session paths need it.
+
+**Tech Stack:** Node.js/TypeScript, ESM with `.js` relative imports, Vitest server config, Express/supertest for existing agent API coverage, OpenCode CLI `serve`.
+
+## Global Constraints
+
+- Server uses NodeNext/ESM; relative imports must include `.js` extensions.
+- Do not restart the self-hosted Freshell server without explicit user approval containing the word `APPROVED`.
+- Do not use broad kill patterns; stop only owned PIDs or ownership-tagged OpenCode serve processes.
+- Preserve unrelated worktree changes from other agents.
+- Use red/green/refactor TDD; do not skip tests or reduce coverage.
+- Keep behavior changes on this dedicated worktree branch and commit focused, atomic changes.
+- Prefer integration/end-to-end tests that prove the user-visible contract.
+
+## Load-Bearing Validation Amendments
+
+These amendments supersede any conflicting task text below:
+
+- OpenCode 1.17.8 uses persisted `session.directory` as the execution/tool cwd for existing session-scoped operations. Fixing session creation directory is the critical user-visible fix.
+- Existing session-scoped operations can be sent through any healthy serve process because OpenCode loads the session row and routes by stored `directory`; cwd routing is still useful when Freshell already knows cwd, but restored no-cwd paths must remain valid through the default route.
+- Freshopencode cannot assume every restored/attached durable session has pane cwd available. When cwd is missing, do not fail the operation; use the default serve route for existing session endpoints, and remember cwd if a later `getSession` or `fork` response exposes a `directory`.
+- OpenCode 1.17.8 does not expose a JSON `/session/:id/compact` endpoint. Freshell compaction must call the current `/session/:id/summarize` route.
+- A sidecar per cwd must not live forever by default. Add a configurable idle shutdown timer for non-default cwd-scoped sidecars and cancel/reschedule it around operations.
+- Project-local OpenCode config is intentionally selected by the user's cwd. Preserve inherited global credentials/config environment, but expect provider/model/project config to vary by selected cwd.
+
+Implementation updates required by this amendment:
+
+- Treat concrete code snippets later in this plan as subordinate to this section. If a snippet still calls `/compact`, omits idle shutdown, forgets returned `directory`, or unconditionally passes `{ cwd: undefined }`, implement the corrected behavior below instead.
+- In `OpencodeServeManager`, add an optional constructor setting such as `idleShutdownMs` and default it to a nonzero idle timeout for cwd-scoped sidecars. Tests may set it to `0` or a small value.
+- Do not route an existing session with unknown cwd to a guessed project cwd. Use the default serve route and let OpenCode's session middleware route by stored `directory`.
+- When `getSession()` or `fork()` returns a `directory`, call `rememberSessionCwd()` for that session id.
+- Change `compact()` to POST `/session/:id/summarize`.
+- Add manager tests for `/summarize`, no-cwd restored-session routing through the default serve, returned-directory remembering, and idle sidecar shutdown.
+- Add adapter tests for both known-cwd restored sends and no-cwd restored sends. The no-cwd case should call manager methods without a third `{ cwd }` argument.
+- In the real-provider regression, prefer the existing isolated real-session harness helpers so `XDG_DATA_HOME`, `XDG_CONFIG_HOME`, and DB path are temp-scoped and the suite remains single-threaded.
+
+Task-level override checklist:
+
+- Task 2 must update `OpencodeServeManagerOptions`, `RunningServe`, `ensureStarted`, `start`, HTTP helpers, `shutdown`, and child-close cleanup for cwd-scoped sidecars. On child close, delete emitters for sessions mapped to that cwd; when the closing sidecar is the default route, also delete unmapped emitters, because no-cwd restored sessions use the default route.
+- Task 2 must add an optional `env?: NodeJS.ProcessEnv` manager option. Spawn env should be `{ ...(options.env ?? process.env), [FRESHELL_OPENCODE_SIDECAR_ID]: ownershipId }`, so real-provider tests can use isolated OpenCode homes without mutating global `process.env`.
+- Task 2 must clear successful `startPromiseByCwd` entries after a sidecar has moved into `runningByCwd`.
+- Task 2 must add tests proving:
+  - `createSession({ directory })` spawns `opencode serve` with that `cwd`.
+  - different directories get different sidecars/ports.
+  - `compact()` posts to `/session/:id/summarize`.
+  - `getSession()` remembers a returned `directory`.
+  - `fork()` remembers the returned child `directory`, not just the parent route.
+  - existing-session calls with no known cwd use the default serve route.
+  - default sidecar close clears unmapped emitters, while non-default sidecar close only clears emitters for sessions mapped to that cwd.
+  - idle shutdown stops non-default sidecars after the configured timeout and does not stop the default sidecar.
+- Task 3 must update `makeFakeManager().createSession` so it returns `directory: input.directory` only when a test actually created the pane with cwd, or else update every existing arity-strict manager expectation affected by the new route argument. Do not leave tests with a fake manager that always returns `/repo` while claiming no-cwd calls stay two-argument.
+- Task 3 must ensure helper calls omit the route argument entirely when no cwd is known. History helpers must not pass `{ cwd: undefined }`.
+- Task 3 must update all existing adapter expectations affected by known cwd routing, including `promptAsync`, `abort`, `compact`, `fork`, `getSession`, `listMessages`, and `getMessage`.
+- Task 4 must avoid a static top-level `node:sqlite` import in the real-provider smoke. Use existing helper functions such as `seedOpencodeHomes()` and `waitForOpencodeDbSession()` or the same dynamic/read-only pattern already used by OpenCode history code.
+
+---
+
+## File Structure
+
+- Modify: `server/fresh-agent/adapters/opencode/serve-manager.ts`
+  - Own cwd-scoped OpenCode serve processes.
+  - Normalize cwd keys.
+  - Route session HTTP calls to the sidecar for that session.
+  - Clean up only the sidecar and emitters for the cwd that exits.
+- Modify: `server/fresh-agent/adapters/opencode/adapter.ts`
+  - Preserve cwd on create/resume/attach.
+  - Pass cwd fallbacks into serve-manager methods for restored sessions whose session id was not created in this process.
+- Modify: `test/unit/server/fresh-agent/opencode-serve-manager.test.ts`
+  - Pin cwd-scoped spawn behavior and per-session routing.
+- Modify: `test/unit/server/fresh-agent/opencode-serve-adapter.test.ts`
+  - Pin attach/resume cwd propagation into manager session operations.
+- Modify: `test/integration/server/opencode-serve-real-provider-smoke.test.ts`
+  - Add a no-LLM real-provider regression: `POST /session` from a manager whose process cwd is not the selected cwd must still produce an OpenCode session whose directory is the selected cwd.
+
+## Task 1: Pin The OpenCode Serve Cwd Contract
+
+**Files:**
+- Modify: `test/unit/server/fresh-agent/opencode-serve-manager.test.ts`
+
+**Interfaces:**
+- Consumes: existing `OpencodeServeManager.createSession(input: { directory?: string })`
+- Produces: failing tests that require `OpencodeServeManager` to spawn serve with `cwd: input.directory`
+
+- [ ] **Step 1: Write the failing unit test for first materialization cwd**
+
+Add this test in `describe('OpencodeServeManager lifecycle', ...)` after `lazily spawns one serve, health-gates, and reuses it across ensureStarted calls`:
+
+```ts
+  it('starts the serve process in the requested session directory before creating the first session', async () => {
+    const calls: Array<{ url: string; init: any }> = []
+    const fetchFn = vi.fn(async (url: string, init: any) => {
+      calls.push({ url, init })
+      if (url.endsWith('/global/health')) return jsonResponse({ healthy: true, version: '1.17.8' })
+      if (url.endsWith('/session') && init?.method === 'POST') {
+        return jsonResponse({ id: 'ses_project_x', directory: '/project-x', title: 'Project X' })
+      }
+      return jsonResponse({})
+    })
+    const { manager, spawnFn } = makeManager({ fetchFn: fetchFn as any })
+
+    const session = await manager.createSession({ directory: '/project-x' })
+
+    expect(session).toMatchObject({ id: 'ses_project_x', directory: '/project-x' })
+    expect(spawnFn).toHaveBeenCalledWith(
+      'opencode',
+      ['serve', '--hostname', '127.0.0.1', '--port', '47999'],
+      expect.objectContaining({
+        cwd: '/project-x',
+        env: expect.objectContaining({ FRESHELL_OPENCODE_SIDECAR_ID: expect.any(String) }),
+      }),
+    )
+    expect(calls.find((call) => call.url.endsWith('/session'))).toMatchObject({
+      url: 'http://127.0.0.1:47999/session',
+      init: expect.objectContaining({
+        method: 'POST',
+        body: JSON.stringify({ directory: '/project-x' }),
+      }),
+    })
+  })
+```
+
+- [ ] **Step 2: Write the failing unit test for separate cwd sidecars**
+
+Add this test in the same describe block:
+
+```ts
+  it('uses separate serve processes for sessions created in different directories', async () => {
+    const childA = fakeChild()
+    const childB = fakeChild()
+    const spawnFn = vi.fn()
+      .mockReturnValueOnce(childA)
+      .mockReturnValueOnce(childB)
+    const fetchFn = vi.fn(async (url: string, init: any) => {
+      if (url === 'http://127.0.0.1:47999/global/health') return jsonResponse({ healthy: true })
+      if (url === 'http://127.0.0.1:48000/global/health') return jsonResponse({ healthy: true })
+      if (url === 'http://127.0.0.1:47999/session' && init?.method === 'POST') {
+        return jsonResponse({ id: 'ses_a', directory: '/project-a' })
+      }
+      if (url === 'http://127.0.0.1:48000/session' && init?.method === 'POST') {
+        return jsonResponse({ id: 'ses_b', directory: '/project-b' })
+      }
+      return jsonResponse({})
+    })
+    const manager = new OpencodeServeManager({
+      spawnFn: spawnFn as any,
+      fetchFn: fetchFn as any,
+      allocatePort: vi.fn()
+        .mockResolvedValueOnce({ hostname: '127.0.0.1', port: 47999 })
+        .mockResolvedValueOnce({ hostname: '127.0.0.1', port: 48000 }),
+      connectEventStream: () => () => {},
+      healthTimeoutMs: 1000,
+    })
+
+    await expect(manager.createSession({ directory: '/project-a' })).resolves.toMatchObject({ id: 'ses_a' })
+    await expect(manager.createSession({ directory: '/project-b' })).resolves.toMatchObject({ id: 'ses_b' })
+
+    expect(spawnFn).toHaveBeenCalledTimes(2)
+    expect(spawnFn).toHaveBeenNthCalledWith(
+      1,
+      'opencode',
+      ['serve', '--hostname', '127.0.0.1', '--port', '47999'],
+      expect.objectContaining({ cwd: '/project-a' }),
+    )
+    expect(spawnFn).toHaveBeenNthCalledWith(
+      2,
+      'opencode',
+      ['serve', '--hostname', '127.0.0.1', '--port', '48000'],
+      expect.objectContaining({ cwd: '/project-b' }),
+    )
+  })
+```
+
+- [ ] **Step 3: Run tests to verify they fail**
+
+Run:
+
+```bash
+npm run test:vitest -- --config vitest.server.config.ts test/unit/server/fresh-agent/opencode-serve-manager.test.ts --run
+```
+
+Expected: FAIL. The first new test should show `spawnFn` was called without `cwd`. The second new test should show only one spawn/port was used for both directories.
+
+- [ ] **Step 4: Commit the red tests**
+
+```bash
+git add test/unit/server/fresh-agent/opencode-serve-manager.test.ts
+git commit -m "test: pin freshopencode serve cwd contract"
+```
+
+## Task 2: Make OpencodeServeManager Cwd-Scoped
+
+**Files:**
+- Modify: `server/fresh-agent/adapters/opencode/serve-manager.ts`
+- Test: `test/unit/server/fresh-agent/opencode-serve-manager.test.ts`
+
+**Interfaces:**
+- Consumes: `createSession(input: { title?: string; parentID?: string; directory?: string })`
+- Produces:
+  - `ensureStarted(input?: { cwd?: string }): Promise<{ baseUrl: string }>`
+  - `rememberSessionCwd(sessionId: string, cwd?: string): void`
+  - `OpencodeServeManagerOptions.env?: NodeJS.ProcessEnv`
+  - `OpencodeServeManagerOptions.idleShutdownMs?: number`
+  - Existing public methods still work, with optional route argument where session ids need a restored cwd fallback.
+
+- [ ] **Step 1: Add cwd route types and maps**
+
+In `server/fresh-agent/adapters/opencode/serve-manager.ts`, add the `node:path` import and replace the single-running fields with cwd-keyed state:
+
+```ts
+import path from 'node:path'
+```
+
+Replace the current `RunningServe` type with:
+
+```ts
+type RunningServe = {
+  baseUrl: string
+  ownershipId: string
+  child: ChildProcessWithoutNullStreams
+  stopEventStream: () => void
+  cwdKey: string
+  cwd?: string
+  idleTimer?: NodeJS.Timeout
+  activeRequests: number
+}
+
+type ServeRoute = {
+  cwd?: string
+}
+
+const DEFAULT_CWD_KEY = '<inherit-process-cwd>'
+```
+
+Replace:
+
+```ts
+  private running: RunningServe | undefined
+  private startPromise: Promise<RunningServe> | undefined
+  private startAbort: AbortController | undefined
+```
+
+with:
+
+```ts
+  private readonly runningByCwd = new Map<string, RunningServe>()
+  private readonly startPromiseByCwd = new Map<string, Promise<RunningServe>>()
+  private readonly startAbortByCwd = new Map<string, AbortController>()
+  private readonly cwdByKey = new Map<string, string | undefined>()
+  private readonly sessionCwdById = new Map<string, string>()
+  private readonly env: NodeJS.ProcessEnv
+  private readonly idleShutdownMs: number
+```
+
+Add these constructor fields:
+
+```ts
+    this.env = options.env ?? process.env
+    this.idleShutdownMs = options.idleShutdownMs ?? 15 * 60_000
+```
+
+- [ ] **Step 2: Add cwd normalization and session routing helpers**
+
+Add these private helpers inside `OpencodeServeManager`:
+
+```ts
+  private routeFromCwd(cwd?: string): { cwdKey: string; cwd?: string } {
+    const trimmed = typeof cwd === 'string' && cwd.trim().length > 0 ? cwd.trim() : undefined
+    if (!trimmed) return { cwdKey: DEFAULT_CWD_KEY }
+    const resolved = path.resolve(trimmed)
+    return { cwdKey: resolved, cwd: resolved }
+  }
+
+  private routeForSession(sessionId: string, fallback?: ServeRoute): { cwdKey: string; cwd?: string } {
+    const existingKey = this.sessionCwdById.get(sessionId)
+    if (existingKey) {
+      return { cwdKey: existingKey, cwd: this.cwdByKey.get(existingKey) }
+    }
+    return this.routeFromCwd(fallback?.cwd)
+  }
+
+  rememberSessionCwd(sessionId: string, cwd?: string): void {
+    if (!sessionId) return
+    const route = this.routeFromCwd(cwd)
+    this.cwdByKey.set(route.cwdKey, route.cwd)
+    this.sessionCwdById.set(sessionId, route.cwdKey)
+  }
+
+  private forgetSessionsForCwd(cwdKey: string): void {
+    for (const [sessionId, sessionCwdKey] of this.sessionCwdById.entries()) {
+      if (sessionCwdKey !== cwdKey) continue
+      this.sessionCwdById.delete(sessionId)
+      this.sessionEmitters.delete(sessionId)
+    }
+    if (cwdKey === DEFAULT_CWD_KEY) {
+      for (const sessionId of this.sessionEmitters.keys()) {
+        if (!this.sessionCwdById.has(sessionId)) this.sessionEmitters.delete(sessionId)
+      }
+    }
+  }
+
+  private clearIdleTimer(running: RunningServe): void {
+    if (!running.idleTimer) return
+    clearTimeout(running.idleTimer)
+    running.idleTimer = undefined
+  }
+
+  private scheduleIdleShutdown(running: RunningServe): void {
+    this.clearIdleTimer(running)
+    if (running.cwdKey === DEFAULT_CWD_KEY || this.idleShutdownMs <= 0 || running.activeRequests > 0) return
+    running.idleTimer = setTimeout(() => {
+      if (running.activeRequests > 0) return
+      if (this.runningByCwd.get(running.cwdKey) !== running) return
+      this.runningByCwd.delete(running.cwdKey)
+      this.startPromiseByCwd.delete(running.cwdKey)
+      this.forgetSessionsForCwd(running.cwdKey)
+      try { running.stopEventStream() } catch { /* ignore */ }
+      void killOwnedProcesses(running.child, running.ownershipId, this.log)
+    }, this.idleShutdownMs)
+    running.idleTimer.unref?.()
+  }
+
+  private async withRunning<T>(
+    route: { cwdKey: string; cwd?: string },
+    fn: (baseUrl: string) => Promise<T>,
+  ): Promise<T> {
+    const { baseUrl } = await this.ensureStarted({ cwd: route.cwd })
+    const running = this.runningByCwd.get(route.cwdKey)
+    if (!running) return fn(baseUrl)
+    this.clearIdleTimer(running)
+    running.activeRequests += 1
+    try {
+      return await fn(baseUrl)
+    } finally {
+      running.activeRequests -= 1
+      this.scheduleIdleShutdown(running)
+    }
+  }
+```
+
+- [ ] **Step 3: Replace `ensureStarted` and `start` with cwd-aware versions**
+
+Replace `ensureStarted()` with:
+
+```ts
+  async ensureStarted(input: ServeRoute = {}): Promise<{ baseUrl: string }> {
+    if (this.shutdownRequested) {
+      throw new Error('opencode serve manager is shutting down')
+    }
+    const route = this.routeFromCwd(input.cwd)
+    this.cwdByKey.set(route.cwdKey, route.cwd)
+    const running = this.runningByCwd.get(route.cwdKey)
+    if (running) return { baseUrl: running.baseUrl }
+    if (!this.startPromiseByCwd.has(route.cwdKey)) {
+      const promise = this.start(route).catch((err) => {
+        this.startPromiseByCwd.delete(route.cwdKey)
+        throw err
+      })
+      this.startPromiseByCwd.set(route.cwdKey, promise)
+    }
+    const next = await this.startPromiseByCwd.get(route.cwdKey)!
+    this.startPromiseByCwd.delete(route.cwdKey)
+    return { baseUrl: next.baseUrl }
+  }
+```
+
+Change the `start` signature and spawn options:
+
+```ts
+  private async start(route: { cwdKey: string; cwd?: string }): Promise<RunningServe> {
+    const startAbort = new AbortController()
+    this.startAbortByCwd.set(route.cwdKey, startAbort)
+    const startSignal = startAbort.signal
+    let child: ChildProcessWithoutNullStreams | undefined
+    try {
+      const endpoint = await this.allocatePort()
+      const baseUrl = `http://${endpoint.hostname}:${endpoint.port}`
+      const ownershipId = randomUUID()
+      child = this.spawnFn(
+        this.command,
+        ['serve', '--hostname', endpoint.hostname, '--port', String(endpoint.port)],
+        {
+          ...(route.cwd ? { cwd: route.cwd } : {}),
+          env: { ...this.env, [OWNERSHIP_ENV]: ownershipId },
+          stdio: ['ignore', 'pipe', 'pipe'],
+        },
+      ) as unknown as ChildProcessWithoutNullStreams
+      child.stdout?.on('data', () => {})
+      child.stderr?.on('data', () => {})
+      child.on('error', (err) => this.log.error({ err }, 'opencode serve process error'))
+      child.on('close', (code) => {
+        this.log.warn({ code }, 'opencode serve exited')
+        const running = this.runningByCwd.get(route.cwdKey)
+        if (running && running.child === child) {
+          this.runningByCwd.delete(route.cwdKey)
+          this.startPromiseByCwd.delete(route.cwdKey)
+          this.startAbortByCwd.delete(route.cwdKey)
+          this.clearIdleTimer(running)
+          try { running.stopEventStream() } catch { /* ignore */ }
+          void killOwnedProcesses(running.child, running.ownershipId, this.log)
+          this.forgetSessionsForCwd(route.cwdKey)
+        }
+      })
+
+      await this.waitForHealth(baseUrl, child, startSignal)
+
+      if (this.shutdownRequested || startSignal.aborted) {
+        this.stopChild(child)
+        throw new Error('opencode serve startup was aborted')
+      }
+
+      const stopEventStream = this.connectEventStream
+        ? this.connectEventStream(`${baseUrl}/event`, {
+            onEvent: (e) => this.dispatchEvent(e),
+            onError: (err) => this.log.warn({ err }, 'opencode serve event stream error'),
+          })
+        : this.startDefaultEventStream(baseUrl)
+
+      const running: RunningServe = { baseUrl, ownershipId, child, stopEventStream, cwdKey: route.cwdKey, cwd: route.cwd, activeRequests: 0 }
+      this.runningByCwd.set(route.cwdKey, running)
+      this.scheduleIdleShutdown(running)
+      return running
+    } catch (err) {
+      if (child) this.stopChild(child)
+      this.startPromiseByCwd.delete(route.cwdKey)
+      throw err
+    } finally {
+      if (this.startAbortByCwd.get(route.cwdKey) === startAbort) this.startAbortByCwd.delete(route.cwdKey)
+    }
+  }
+```
+
+- [ ] **Step 4: Route HTTP helpers by cwd or session id**
+
+Replace `requireBase` and `json` with:
+
+```ts
+  private async requireBase(input: ServeRoute & { sessionId?: string } = {}): Promise<string> {
+    const route = input.sessionId
+      ? this.routeForSession(input.sessionId, input)
+      : this.routeFromCwd(input.cwd)
+    const { baseUrl } = await this.ensureStarted({ cwd: route.cwd })
+    return baseUrl
+  }
+
+  private async json<T>(
+    route: ServeRoute & { sessionId?: string },
+    requestPath: string,
+    init?: RequestInit & { notFoundValue?: T },
+  ): Promise<T> {
+    const resolved = route.sessionId
+      ? this.routeForSession(route.sessionId, route)
+      : this.routeFromCwd(route.cwd)
+    return this.withRunning(resolved, async (base) => {
+      const res = await this.fetchFn(`${base}${requestPath}`, init)
+      if (!res.ok && res.status !== 204) {
+        if (res.status === 404 && init?.notFoundValue !== undefined) return init.notFoundValue
+        const text = await res.text().catch(() => '')
+        throw new Error(`opencode serve ${init?.method ?? 'GET'} ${requestPath} → ${res.status} ${text}`)
+      }
+      if (res.status === 204) return undefined as T
+      return (await res.json()) as T
+    })
+  }
+```
+
+Update each caller:
+
+```ts
+  async createSession(input: { title?: string; parentID?: string; directory?: string } = {}): Promise<{ id: string; directory?: string; title?: string }> {
+    const body: { title?: string; parentID?: string; directory?: string } = {}
+    if (input.title !== undefined) body.title = input.title
+    if (input.parentID !== undefined) body.parentID = input.parentID
+    if (input.directory !== undefined) body.directory = input.directory
+    const session = await this.json<{ id: string; directory?: string; title?: string }>(
+      { cwd: input.directory },
+      '/session',
+      {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+      },
+    )
+    if (typeof session.id === 'string') this.rememberSessionCwd(session.id, input.directory)
+    return session
+  }
+
+  async getSession(id: string, route: ServeRoute = {}): Promise<Record<string, any>> {
+    const session = await this.json<Record<string, any>>({ ...route, sessionId: id }, `/session/${encodeURIComponent(id)}`, { method: 'GET' })
+    if (typeof session?.directory === 'string' && session.directory.length > 0) {
+      this.rememberSessionCwd(id, session.directory)
+    }
+    return session
+  }
+
+  async promptAsync(
+    id: string,
+    body: { parts: Array<Record<string, unknown>>; model?: { providerID: string; modelID: string }; variant?: string; agent?: string },
+    route: ServeRoute = {},
+  ): Promise<void> {
+    await this.json({ ...route, sessionId: id }, `/session/${encodeURIComponent(id)}/prompt_async`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+    })
+  }
+
+  async getMessage(id: string, messageId: string, route: ServeRoute = {}): Promise<OpencodeServeMessage | null> {
+    return this.json<OpencodeServeMessage | null>(
+      { ...route, sessionId: id },
+      `/session/${encodeURIComponent(id)}/message/${encodeURIComponent(messageId)}`,
+      { method: 'GET', notFoundValue: null },
+    )
+  }
+
+  async abort(id: string, route: ServeRoute = {}): Promise<void> {
+    await this.json({ ...route, sessionId: id }, `/session/${encodeURIComponent(id)}/abort`, { method: 'POST' })
+  }
+
+  async compact(id: string, body?: { instructions?: string }, route: ServeRoute = {}): Promise<void> {
+    await this.json({ ...route, sessionId: id }, `/session/${encodeURIComponent(id)}/summarize`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body ?? {}),
+    })
+  }
+
+  async fork(id: string, route: ServeRoute = {}): Promise<{ id: string; directory?: string }> {
+    const child = await this.json<{ id: string; directory?: string }>({ ...route, sessionId: id }, `/session/${encodeURIComponent(id)}/fork`, { method: 'POST' })
+    if (typeof child.id === 'string') {
+      this.rememberSessionCwd(child.id, child.directory)
+    }
+    return child
+  }
+```
+
+Update `listMessages`:
+
+```ts
+  async listMessages(id: string, query: { limit?: number; before?: string }, route: ServeRoute = {}): Promise<OpencodeServeMessagePage> {
+    const resolved = this.routeForSession(id, route)
+    return this.withRunning(resolved, async (base) => {
+      const params = new URLSearchParams()
+      if (typeof query.limit === 'number') params.set('limit', String(query.limit))
+      if (query.before) params.set('before', query.before)
+      const qs = params.toString()
+      const url = `${base}/session/${encodeURIComponent(id)}/message${qs ? `?${qs}` : ''}`
+      const res = await this.fetchFn(url, { method: 'GET' })
+      if (!res.ok) {
+        const text = await res.text().catch(() => '')
+        throw new Error(`opencode serve GET messages → ${res.status} ${text}`)
+      }
+      const messages = (await res.json()) as OpencodeServeMessage[]
+      const nextCursor = res.headers.get('x-next-cursor') || null
+      return { messages: Array.isArray(messages) ? messages : [], nextCursor }
+    })
+  }
+```
+
+- [ ] **Step 5: Update shutdown and inspection behavior**
+
+Replace `shutdown()` with:
+
+```ts
+  async shutdown(): Promise<void> {
+    this.shutdownRequested = true
+    for (const controller of this.startAbortByCwd.values()) {
+      controller.abort()
+    }
+
+    const starts = [...this.startPromiseByCwd.values()]
+    if (starts.length > 0) {
+      await Promise.all(starts.map(async (promise) => {
+        try { await promise } catch { /* ignore startup errors */ }
+      }))
+      this.startPromiseByCwd.clear()
+    }
+
+    const running = [...this.runningByCwd.values()]
+    this.runningByCwd.clear()
+    this.startPromiseByCwd.clear()
+    this.startAbortByCwd.clear()
+    await Promise.all(running.map(async (entry) => {
+      this.clearIdleTimer(entry)
+      try { entry.stopEventStream() } catch { /* ignore */ }
+      await killOwnedProcesses(entry.child, entry.ownershipId, this.log)
+    }))
+    this.sessionEmitters.clear()
+    this.sessionCwdById.clear()
+    this.cwdByKey.clear()
+  }
+
+  /** @internal test/inspection accessor */
+  get baseUrlOrUndefined(): string | undefined {
+    return [...this.runningByCwd.values()][0]?.baseUrl
+  }
+```
+
+- [ ] **Step 6: Update existing tests for private state names**
+
+In `test/unit/server/fresh-agent/opencode-serve-manager.test.ts`, replace assertions that inspect `(manager as any).running` and `(manager as any).startPromise`:
+
+```ts
+    expect((manager as any).runningByCwd.size).toBe(0)
+    expect((manager as any).startPromiseByCwd.size).toBe(0)
+```
+
+Replace the child-exit cleanup test assertions:
+
+```ts
+    expect((manager as any).sessionEmitters.size).toBe(0)
+    expect((manager as any).runningByCwd.size).toBe(0)
+```
+
+- [ ] **Step 7: Run tests to verify the manager change**
+
+Run:
+
+```bash
+npm run test:vitest -- --config vitest.server.config.ts test/unit/server/fresh-agent/opencode-serve-manager.test.ts --run
+```
+
+Expected: PASS.
+
+- [ ] **Step 8: Commit the manager implementation**
+
+```bash
+git add server/fresh-agent/adapters/opencode/serve-manager.ts test/unit/server/fresh-agent/opencode-serve-manager.test.ts
+git commit -m "fix: scope opencode serve processes by cwd"
+```
+
+## Task 3: Route Adapter Operations With Preserved Cwd
+
+**Files:**
+- Modify: `server/fresh-agent/adapters/opencode/adapter.ts`
+- Modify: `test/unit/server/fresh-agent/opencode-serve-adapter.test.ts`
+
+**Interfaces:**
+- Consumes:
+  - `OpencodeServeManager.rememberSessionCwd(sessionId: string, cwd?: string): void`
+  - Optional route arguments on `getSession`, `listMessages`, `getMessage`, `promptAsync`, `abort`, `compact`, and `fork`
+- Produces: restored or attached freshopencode sessions use their pane cwd when the manager has not seen their session id yet.
+
+- [ ] **Step 1: Extend the fake manager test double**
+
+In `test/unit/server/fresh-agent/opencode-serve-adapter.test.ts`, add `rememberSessionCwd` to `makeFakeManager()`:
+
+```ts
+    createSession: vi.fn(async (input?: { directory?: string }) => ({
+      id: 'ses_real_1',
+      ...(input?.directory ? { directory: input.directory } : {}),
+      title: 'T',
+    })),
+    rememberSessionCwd: vi.fn(),
+```
+
+Replace the old always-`/repo` fake `createSession` with the conditional version above, then update `FakeManager` automatically through the existing `ReturnType`.
+
+- [ ] **Step 2: Add failing test for attach cwd registration**
+
+Add this test in `describe('OpenCode serve adapter: history reads', ...)` before `getSnapshot assembles HTTP messages into the normalized transcript`:
+
+```ts
+  it('remembers cwd when attaching a durable OpenCode session', async () => {
+    const manager = makeFakeManager()
+    const adapter = makeAdapter(manager)
+
+    await adapter.attach?.({
+      sessionType: 'freshopencode',
+      provider: 'opencode',
+      sessionId: 'ses_existing_cwd',
+      cwd: '/repo/from-pane',
+    })
+
+    expect(manager.rememberSessionCwd).toHaveBeenCalledWith('ses_existing_cwd', '/repo/from-pane')
+  })
+```
+
+- [ ] **Step 3: Add failing test for restored send cwd routing**
+
+Add this test in `describe('OpenCode serve adapter: create + send', ...)`:
+
+```ts
+  it('passes restored cwd when sending to an attached durable session', async () => {
+    const manager = makeFakeManager()
+    const adapter = makeAdapter(manager)
+
+    await adapter.attach?.({
+      sessionType: 'freshopencode',
+      provider: 'opencode',
+      sessionId: 'ses_attached_send',
+      cwd: '/repo/restored-worktree',
+    })
+    await adapter.send?.('ses_attached_send', { text: 'continue' })
+
+    expect(manager.promptAsync).toHaveBeenCalledWith(
+      'ses_attached_send',
+      { parts: [{ type: 'text', text: 'continue' }] },
+      { cwd: '/repo/restored-worktree' },
+    )
+  })
+```
+
+- [ ] **Step 4: Run adapter tests to verify failure**
+
+Run:
+
+```bash
+npm run test:vitest -- --config vitest.server.config.ts test/unit/server/fresh-agent/opencode-serve-adapter.test.ts --run
+```
+
+Expected: FAIL. The first new test should show `rememberSessionCwd` was not called. The second should show `promptAsync` was called without the route argument.
+
+- [ ] **Step 5: Implement adapter cwd propagation**
+
+In `server/fresh-agent/adapters/opencode/adapter.ts`, add these helpers near `sendResult`:
+
+```ts
+  function cwdRoute(cwd?: string): { cwd?: string } | undefined {
+    return typeof cwd === 'string' && cwd.trim().length > 0 ? { cwd } : undefined
+  }
+
+  async function promptAsyncForState(
+    state: OpencodeSessionState,
+    realId: string,
+    body: Parameters<OpencodeServeManager['promptAsync']>[1],
+  ): Promise<void> {
+    const route = cwdRoute(state.cwd)
+    if (route) {
+      await serveManager.promptAsync(realId, body, route)
+      return
+    }
+    await serveManager.promptAsync(realId, body)
+  }
+
+  async function abortForState(state: OpencodeSessionState): Promise<void> {
+    if (!state.realSessionId) return
+    const route = cwdRoute(state.cwd)
+    if (route) {
+      await serveManager.abort(state.realSessionId, route)
+      return
+    }
+    await serveManager.abort(state.realSessionId)
+  }
+
+  async function compactForState(state: OpencodeSessionState, input?: { instructions?: string }): Promise<void> {
+    if (!state.realSessionId) return
+    const route = cwdRoute(state.cwd)
+    if (route) {
+      await serveManager.compact(state.realSessionId, input, route)
+      return
+    }
+    await serveManager.compact(state.realSessionId, input)
+  }
+
+  async function forkForState(state: OpencodeSessionState): Promise<{ id: string }> {
+    if (!state.realSessionId) throw new FreshAgentLostSessionError(`OpenCode session ${state.placeholderId} has not materialized; cannot fork.`)
+    const route = cwdRoute(state.cwd)
+    return route
+      ? await serveManager.fork(state.realSessionId, route)
+      : await serveManager.fork(state.realSessionId)
+  }
+```
+
+Update `materializeOrSend` prompt call:
+
+```ts
+      await promptAsyncForState(state, realId, {
+        parts: [{ type: 'text', text }],
+        ...(splitOpencodeModel(modelStr) ? { model: splitOpencodeModel(modelStr)! } : {}),
+        ...(effort ? { variant: effort } : {}),
+      })
+```
+
+Update `assembleExport` signature and calls:
+
+```ts
+  async function assembleExport(
+    realSessionId: string,
+    query: { limit?: number; before?: string },
+    route: { cwd?: string } = {},
+  ): Promise<{ exported: OpencodeExport; nextCursor: string | null; revision: number }> {
+    const [session, page] = await Promise.all([
+      serveManager.getSession(realSessionId, route).then(
+        (session) => session,
+        () => ({} as Record<string, unknown>),
+      ),
+      serveManager.listMessages(realSessionId, query, route),
+    ])
+    const sessionTime = session && typeof session === 'object' ? session.time : undefined
+    const sessionTimeUpdated = sessionTime && typeof sessionTime === 'object' && !Array.isArray(sessionTime)
+      ? (sessionTime as Record<string, unknown>).updated
+      : undefined
+    const revision = Number.isFinite(Number(sessionTimeUpdated)) ? Number(sessionTimeUpdated) : page.messages.length
+    const exported: OpencodeExport = {
+      info: { id: realSessionId, ...(session ?? {}) },
+      messages: page.messages.map((m) => ({ info: m.info, parts: m.parts })),
+    }
+    return { exported, nextCursor: page.nextCursor, revision }
+  }
+```
+
+Update `attach(locator)`:
+
+```ts
+    async attach(locator) {
+      const existing = sessions.get(locator.sessionId)
+      if (existing) {
+        if (locator.cwd) {
+          existing.cwd = locator.cwd
+          if (existing.realSessionId) serveManager.rememberSessionCwd(existing.realSessionId, locator.cwd)
+        }
+        remember(existing)
+        return { sessionId: locator.sessionId, sessionRef: { provider: 'opencode', sessionId: locator.sessionId } }
+      }
+      if (isPlaceholderOpencodeSessionId(locator.sessionId) || !isRealOpencodeSessionId(locator.sessionId)) {
+        throw new FreshAgentLostSessionError(`OpenCode session ${locator.sessionId} is not a durable OpenCode session.`)
+      }
+      const state: OpencodeSessionState = {
+        placeholderId: locator.sessionId,
+        realSessionId: locator.sessionId,
+        cwd: locator.cwd,
+        status: 'idle',
+        events: new EventEmitter(),
+        sendQueue: Promise.resolve(),
+      }
+      if (locator.cwd) serveManager.rememberSessionCwd(locator.sessionId, locator.cwd)
+      remember(state)
+      bindServeStream(state)
+      return { sessionId: locator.sessionId, sessionRef: { provider: 'opencode', sessionId: locator.sessionId } }
+    },
+```
+
+Update control methods:
+
+```ts
+      await abortForState(state).catch((err) => log.warn({ err }, 'abort failed'))
+```
+
+```ts
+        () => compactForState(state, hasInstructions ? { instructions } : undefined),
+        () => compactForState(state, hasInstructions ? { instructions } : undefined),
+```
+
+```ts
+      const child = await forkForState(state)
+```
+
+Update history calls:
+
+```ts
+      const route = cwdRoute(liveState?.cwd ?? thread.cwd)
+      const { exported, revision } = route
+        ? await assembleExport(realId, { limit: DEFAULT_SNAPSHOT_TURN_LIMIT }, route)
+        : await assembleExport(realId, { limit: DEFAULT_SNAPSHOT_TURN_LIMIT })
+```
+
+```ts
+      const route = cwdRoute(liveState?.cwd ?? thread.cwd)
+      const pageQuery = {
+        limit: typeof query.limit === 'number' ? query.limit : DEFAULT_SNAPSHOT_TURN_LIMIT,
+        before: typeof query.cursor === 'string' ? query.cursor : undefined,
+      }
+      const { exported, nextCursor, revision } = route
+        ? await assembleExport(realId, pageQuery, route)
+        : await assembleExport(realId, pageQuery)
+```
+
+```ts
+      const route = cwdRoute(liveState?.cwd ?? thread.cwd)
+      const message = route
+        ? await serveManager.getMessage(realId, thread.turnId, route)
+        : await serveManager.getMessage(realId, thread.turnId)
+```
+
+- [ ] **Step 6: Update existing adapter expectations for cwd-aware calls**
+
+In `test/unit/server/fresh-agent/opencode-serve-adapter.test.ts`, update the first test's `promptAsync` expectation because that pane was created with `cwd: '/repo'`:
+
+```ts
+    expect(manager.promptAsync).toHaveBeenCalledWith('ses_real_1', {
+      parts: [{ type: 'text', text: 'reply ok' }],
+      model: { providerID: 'umans-ai-coding-plan', modelID: 'umans-kimi-k2.7' },
+      variant: 'high',
+    }, { cwd: '/repo' })
+```
+
+Leave no-cwd expectations as two-argument calls; the helper above deliberately does not pass a third `{}` argument when no cwd is known.
+
+- [ ] **Step 7: Run adapter tests**
+
+Run:
+
+```bash
+npm run test:vitest -- --config vitest.server.config.ts test/unit/server/fresh-agent/opencode-serve-adapter.test.ts --run
+```
+
+Expected: PASS.
+
+- [ ] **Step 8: Commit adapter routing**
+
+```bash
+git add server/fresh-agent/adapters/opencode/adapter.ts test/unit/server/fresh-agent/opencode-serve-adapter.test.ts
+git commit -m "fix: route freshopencode operations with pane cwd"
+```
+
+## Task 4: Add Real No-LLM Regression Coverage
+
+**Files:**
+- Modify: `test/integration/server/opencode-serve-real-provider-smoke.test.ts`
+
+**Interfaces:**
+- Consumes: real `opencode` binary if available.
+- Produces: a no-LLM regression proving OpenCode stores new session `directory` as the selected cwd even when Freshell process cwd is different.
+
+- [ ] **Step 1: Add isolated OpenCode helper imports**
+
+At the top of `test/integration/server/opencode-serve-real-provider-smoke.test.ts`, add:
+
+```ts
+import fs from 'node:fs/promises'
+import {
+  ProbeWorkspace,
+  seedOpencodeHomes,
+  waitForOpencodeDbSession,
+} from '../../../test/helpers/coding-cli/real-session-contract-harness.js'
+```
+
+- [ ] **Step 2: Use the existing temp workspace and DB wait helpers**
+
+Do not add a static top-level `node:sqlite` import. `waitForOpencodeDbSession()` already uses the repo's supported dynamic/read-only SQLite path and waits for the OpenCode DB row to exist.
+
+- [ ] **Step 3: Add no-LLM cwd regression test**
+
+Add this test inside `describe('OpencodeServeManager lifecycle', ...)`:
+
+```ts
+      it('creates first-run sessions in the requested cwd, not the Freshell process cwd', async () => {
+        const workspace = await ProbeWorkspace.create('freshell-opencode-real-cwd-')
+        const requestedCwd = workspace.inTemp('requested-project')
+        const homes = await seedOpencodeHomes(workspace)
+        const manager = new OpencodeServeManager({
+          env: {
+            ...process.env,
+            XDG_DATA_HOME: homes.dataHome,
+            XDG_CONFIG_HOME: homes.configHome,
+          },
+        })
+        try {
+          await fs.mkdir(requestedCwd, { recursive: true })
+          const session = await manager.createSession({ directory: requestedCwd })
+          expect(session.id).toMatch(/^ses_/)
+          expect(session.directory).toBe(requestedCwd)
+
+          const row = await waitForOpencodeDbSession(homes.dbPath, session.id)
+          expect(row.directory).toBe(requestedCwd)
+        } finally {
+          await manager.shutdown()
+          await workspace.cleanup()
+        }
+      }, 60_000)
+```
+
+- [ ] **Step 4: Run real-provider smoke test**
+
+Run:
+
+```bash
+npm run test:vitest -- --config vitest.server.config.ts test/integration/server/opencode-serve-real-provider-smoke.test.ts --run
+```
+
+Expected when `opencode` is installed: PASS. Expected when `opencode` is unavailable: suite reports skipped tests, not failure.
+
+- [ ] **Step 5: Commit real regression coverage**
+
+```bash
+git add test/integration/server/opencode-serve-real-provider-smoke.test.ts
+git commit -m "test: cover freshopencode real cwd materialization"
+```
+
+## Task 5: Focused And Broad Verification
+
+**Files:**
+- No code changes.
+
+**Interfaces:**
+- Consumes: completed Tasks 1-4.
+- Produces: verified branch ready for review/PR.
+
+- [ ] **Step 1: Run focused freshopencode tests**
+
+Run:
+
+```bash
+npm run test:vitest -- --config vitest.server.config.ts test/unit/server/fresh-agent/opencode-serve-manager.test.ts test/unit/server/fresh-agent/opencode-serve-adapter.test.ts test/integration/server/opencode-serve-real-provider-smoke.test.ts --run
+```
+
+Expected: PASS, or real-provider smoke skipped only if `opencode` is unavailable.
+
+- [ ] **Step 2: Run typecheck**
+
+Run:
+
+```bash
+npm run typecheck
+```
+
+Expected: PASS.
+
+- [ ] **Step 3: Run coordinated full check**
+
+Run:
+
+```bash
+FRESHELL_TEST_SUMMARY="verify freshopencode cwd-scoped serve fix" npm run check
+```
+
+Expected: PASS. If another agent holds the coordinator gate, wait for the coordinated run instead of killing the holder.
+
+- [ ] **Step 4: Inspect final diff**
+
+Run:
+
+```bash
+git diff --check
+git status --short
+git log --oneline -5
+```
+
+Expected:
+- `git diff --check` has no output.
+- `git status --short` shows only intended files before the final commit, or clean after the final commit.
+- Recent commits are the focused task commits from this plan.
+
+- [ ] **Step 5: Commit final verification note if any files changed**
+
+If no files changed during verification, do not create an empty commit. If a test-only adjustment was needed, commit it:
+
+```bash
+git add server/fresh-agent/adapters/opencode/serve-manager.ts server/fresh-agent/adapters/opencode/adapter.ts test/unit/server/fresh-agent/opencode-serve-manager.test.ts test/unit/server/fresh-agent/opencode-serve-adapter.test.ts test/integration/server/opencode-serve-real-provider-smoke.test.ts
+git commit -m "chore: finalize freshopencode cwd-scoped serve"
+```
+
+## Self-Review
+
+- Spec coverage: The plan covers first-run freshopencode cwd, real OpenCode behavior, the manager architecture that caused the bug, restored/attached session routing, sidecar cleanup, and broad verification.
+- Placeholder scan: No task uses `TBD`, `TODO`, `implement later`, or a generic “write tests” instruction without concrete test code.
+- Type consistency: `ServeRoute`, `rememberSessionCwd`, and the optional route arguments are introduced in Task 2 and consumed by Task 3 with the same names and shapes.
diff --git a/server/agent-api/router.ts b/server/agent-api/router.ts
index 4d68da6ef..fa919e235 100644
--- a/server/agent-api/router.ts
+++ b/server/agent-api/router.ts
@@ -87,7 +87,7 @@ const FRESH_AGENT_SEND_IDLE_TIMEOUT_MS = 600_000
 
 async function waitForFreshAgentIdle(
   runtimeManager: NonNullable<FreshAgentRuntimeManagerLike>,
-  locator: { sessionType: string; provider: string; threadId: string },
+  locator: { sessionType: string; provider: string; threadId: string; cwd?: string },
   deadline: number,
 ): Promise<{ status: string; deadlineMissed: boolean }> {
   while (Date.now() < deadline) {
@@ -99,6 +99,25 @@ async function waitForFreshAgentIdle(
   return { status: 'unknown', deadlineMissed: true }
 }
 
+function freshAgentPaneCwd(content: Record<string, unknown>): string | undefined {
+  const cwd = content.initialCwd
+  return typeof cwd === 'string' && cwd.trim().length > 0 ? cwd : undefined
+}
+
+function freshAgentPaneSendSettings(content: Record<string, unknown>): Record<string, unknown> | undefined {
+  const settings = {
+    cwd: freshAgentPaneCwd(content),
+    model: typeof content.model === 'string' && content.model.trim().length > 0 ? content.model : undefined,
+    permissionMode: typeof content.permissionMode === 'string' && content.permissionMode.trim().length > 0
+      ? content.permissionMode
+      : undefined,
+    sandbox: typeof content.sandbox === 'string' && content.sandbox.trim().length > 0 ? content.sandbox : undefined,
+    effort: typeof content.effort === 'string' && content.effort.trim().length > 0 ? content.effort : undefined,
+  }
+  const defined = Object.fromEntries(Object.entries(settings).filter(([, value]) => value !== undefined))
+  return Object.keys(defined).length > 0 ? defined : undefined
+}
+
 function combineWithCleanupError(primary: unknown, cleanupError: unknown): Error {
   const primaryMessage = errorMessage(primary)
   const cleanupMessage = errorMessage(cleanupError)
@@ -883,7 +902,12 @@ export function createAgentApiRouter({
       const c = paneSnapshot.paneContent || {}
       if (!freshAgentRuntimeManager) return res.status(503).json(fail('fresh-agent runtime not available on this server'))
       try {
-        const snapshot = await freshAgentRuntimeManager.getSnapshot({ sessionType: c.sessionType, provider: c.provider, threadId: c.sessionId })
+        const snapshot = await freshAgentRuntimeManager.getSnapshot({
+          sessionType: c.sessionType,
+          provider: c.provider,
+          threadId: c.sessionId,
+          cwd: freshAgentPaneCwd(c),
+        })
         return res.type('text/plain').send(renderFreshAgentTranscript(snapshot))
       } catch (err: any) {
         return res.status(agentRouteErrorStatus(err)).json(fail(err?.message || 'fresh-agent capture failed'))
@@ -938,7 +962,12 @@ export function createAgentApiRouter({
       while (true) {
         let status: string | undefined
         try {
-          const snap = await freshAgentRuntimeManager.getSnapshot({ sessionType: c.sessionType, provider: c.provider, threadId: c.sessionId })
+          const snap = await freshAgentRuntimeManager.getSnapshot({
+            sessionType: c.sessionType,
+            provider: c.provider,
+            threadId: c.sessionId,
+            cwd: freshAgentPaneCwd(c),
+          })
           status = snap?.status
         } catch (err) {
           return res.status(freshAgentErrorStatus(err)).json(fail(errorMessage(err)))
@@ -1638,9 +1667,24 @@ export function createAgentApiRouter({
       const text = String(req.body?.data ?? req.body?.keys ?? req.body?.text ?? '')
       if (!text) return res.status(400).json(fail('text is required'))
       if (!freshAgentRuntimeManager) return res.status(503).json(fail('fresh-agent runtime not available on this server'))
-      const locator = { sessionId: c.sessionId as string, sessionType: c.sessionType as string, provider: c.provider as string } as FreshAgentSessionLocator
-      const runSend = () => freshAgentRuntimeManager.send(locator, { text })
-      const snapshotLocator = { sessionType: c.sessionType as string, provider: c.provider as string, threadId: c.sessionId as string }
+      const cwd = freshAgentPaneCwd(c)
+      const settings = freshAgentPaneSendSettings(c)
+      const locator = {
+        sessionId: c.sessionId as string,
+        sessionType: c.sessionType as string,
+        provider: c.provider as string,
+        ...(cwd ? { cwd } : {}),
+      } as FreshAgentSessionLocator
+      const runSend = () => freshAgentRuntimeManager.send(locator, {
+        text,
+        ...(settings ? { settings } : {}),
+      })
+      const snapshotLocator = {
+        sessionType: c.sessionType as string,
+        provider: c.provider as string,
+        threadId: c.sessionId as string,
+        ...(cwd ? { cwd } : {}),
+      }
       try {
         let result
         try {
diff --git a/server/fresh-agent/adapters/codex/adapter.ts b/server/fresh-agent/adapters/codex/adapter.ts
index d0fde5fb6..12c5e3ff9 100644
--- a/server/fresh-agent/adapters/codex/adapter.ts
+++ b/server/fresh-agent/adapters/codex/adapter.ts
@@ -186,6 +186,32 @@ export function createCodexFreshAgentAdapter(deps: {
   const runtimeResumeGenerationByThread = new Map<string, number>()
   const modelByTurnByThread = new Map<string, Map<string, string>>()
 
+  const rememberThreadSettings = (
+    threadId: string,
+    settings?: Partial<FreshAgentCreateRequest>,
+  ): Partial<FreshAgentCreateRequest> | undefined => {
+    if (!settings) return settingsByThread.get(threadId)
+    const definedSettings = Object.fromEntries(
+      Object.entries(settings).filter(([, value]) => value !== undefined),
+    ) as Partial<FreshAgentCreateRequest>
+    if (Object.keys(definedSettings).length === 0) return settingsByThread.get(threadId)
+    const merged = {
+      ...settingsByThread.get(threadId),
+      ...definedSettings,
+    }
+    settingsByThread.set(threadId, merged)
+    return merged
+  }
+
+  const settingsFromLocator = (
+    locator: { sessionType?: FreshAgentCreateRequest['sessionType']; cwd?: string },
+  ): Partial<FreshAgentCreateRequest> | undefined => {
+    const cwd = typeof locator.cwd === 'string' && locator.cwd.trim().length > 0
+      ? locator.cwd
+      : undefined
+    return cwd ? { sessionType: locator.sessionType, cwd } : undefined
+  }
+
   const rememberRuntimeThread = (threadId: string, runtime: CodexRuntimePort) => {
     runtimeByThread.set(threadId, runtime)
     const threadIds = threadIdsByRuntime.get(runtime) ?? new Set<string>()
@@ -228,6 +254,7 @@ export function createCodexFreshAgentAdapter(deps: {
   }
 
   const ensureRuntime = async (sessionId: string, settings?: Partial<FreshAgentCreateRequest>): Promise<CodexRuntimePort> => {
+    const effectiveSettings = rememberThreadSettings(sessionId, settings)
     const existing = getExistingRuntime(sessionId)
     if (existing) return existing
     const inflight = runtimeResumeByThread.get(sessionId)
@@ -245,14 +272,14 @@ export function createCodexFreshAgentAdapter(deps: {
     }
     resumePromise = (async () => {
       try {
-        const resumed = await runtime.resumeThread(toCodexResumeInput(sessionId, settings))
+        const resumed = await runtime.resumeThread(toCodexResumeInput(sessionId, effectiveSettings))
         if ((runtimeResumeGenerationByThread.get(sessionId) ?? 0) !== resumeGeneration) {
           await discardOwnedRuntime()
           throw new Error(`Codex app-server runtime resume was cancelled for freshcodex session ${sessionId}.`)
         }
         rememberRuntimeThread(resumed.threadId, runtime)
-        if (settings) {
-          settingsByThread.set(resumed.threadId, settings)
+        if (effectiveSettings) {
+          settingsByThread.set(resumed.threadId, effectiveSettings)
         }
         return runtime
       } catch (error) {
@@ -335,8 +362,13 @@ export function createCodexFreshAgentAdapter(deps: {
       return { sessionId: resumed.threadId, sessionRef: { provider: 'codex', sessionId: resumed.threadId } }
     },
 
+    attach(locator) {
+      rememberThreadSettings(locator.sessionId, settingsFromLocator(locator))
+      return { sessionId: locator.sessionId, sessionRef: { provider: 'codex', sessionId: locator.sessionId } }
+    },
+
     async subscribe(sessionId, listener) {
-      const runtime = await ensureRuntime(sessionId)
+      const runtime = await ensureRuntime(sessionId, settingsByThread.get(sessionId))
       if (!runtime.onThreadLifecycle) {
         throw new Error('Codex app-server runtime does not support thread lifecycle subscriptions.')
       }
@@ -477,7 +509,10 @@ export function createCodexFreshAgentAdapter(deps: {
     },
 
     async getSnapshot(thread, revision) {
-      const runtime = await ensureRuntime(thread.threadId)
+      const runtime = await ensureRuntime(
+        thread.threadId,
+        settingsFromLocator(thread) ?? settingsByThread.get(thread.threadId),
+      )
       let rawSnapshot: Record<string, any>
       try {
         rawSnapshot = await runtime.readThread({ threadId: thread.threadId, includeTurns: true })
@@ -515,7 +550,10 @@ export function createCodexFreshAgentAdapter(deps: {
     },
 
     async getTurnPage(thread, query) {
-      const runtime = await ensureRuntime(thread.threadId)
+      const runtime = await ensureRuntime(
+        thread.threadId,
+        settingsFromLocator(thread) ?? settingsByThread.get(thread.threadId),
+      )
       const rawPage = await runtime.listThreadTurns({
         threadId: thread.threadId,
         cursor: typeof query.cursor === 'string' ? query.cursor : undefined,
@@ -531,7 +569,10 @@ export function createCodexFreshAgentAdapter(deps: {
     },
 
     async getTurnBody(thread, revision) {
-      const runtime = await ensureRuntime(thread.threadId)
+      const runtime = await ensureRuntime(
+        thread.threadId,
+        settingsFromLocator(thread) ?? settingsByThread.get(thread.threadId),
+      )
       const rawTurn = await runtime.readThreadTurn({
         threadId: thread.threadId,
         turnId: thread.turnId,
diff --git a/server/fresh-agent/adapters/opencode/adapter.ts b/server/fresh-agent/adapters/opencode/adapter.ts
index 89002dee0..72b2fa1d2 100644
--- a/server/fresh-agent/adapters/opencode/adapter.ts
+++ b/server/fresh-agent/adapters/opencode/adapter.ts
@@ -86,6 +86,57 @@ export function createOpencodeFreshAgentAdapter(options: CreateOpencodeFreshAgen
     return sessionId ? { sessionId, sessionRef: { provider: 'opencode', sessionId } } : undefined
   }
 
+  function cwdRoute(cwd?: string): { cwd: string } | undefined {
+    return typeof cwd === 'string' && cwd.trim().length > 0 ? { cwd } : undefined
+  }
+
+  async function promptAsyncForState(
+    state: OpencodeSessionState,
+    realId: string,
+    body: Parameters<OpencodeServeManager['promptAsync']>[1],
+  ): Promise<void> {
+    const route = cwdRoute(state.cwd)
+    if (route) {
+      await serveManager.promptAsync(realId, body, route)
+      return
+    }
+    await serveManager.promptAsync(realId, body)
+  }
+
+  async function abortForState(state: OpencodeSessionState): Promise<void> {
+    if (!state.realSessionId) return
+    const route = cwdRoute(state.cwd)
+    if (route) {
+      await serveManager.abort(state.realSessionId, route)
+      return
+    }
+    await serveManager.abort(state.realSessionId)
+  }
+
+  async function compactForState(state: OpencodeSessionState, input?: { instructions?: string }): Promise<void> {
+    if (!state.realSessionId) return
+    const route = cwdRoute(state.cwd)
+    if (route) {
+      await serveManager.compact(state.realSessionId, input, route)
+      return
+    }
+    if (input) {
+      await serveManager.compact(state.realSessionId, input)
+      return
+    }
+    await serveManager.compact(state.realSessionId)
+  }
+
+  async function forkForState(state: OpencodeSessionState): Promise<{ id: string; directory?: string }> {
+    if (!state.realSessionId) {
+      throw new FreshAgentLostSessionError(`OpenCode session ${state.placeholderId} has not materialized; cannot fork.`)
+    }
+    const route = cwdRoute(state.cwd)
+    return route
+      ? await serveManager.fork(state.realSessionId, route)
+      : await serveManager.fork(state.realSessionId)
+  }
+
   /** Bridge serve SSE events for this state's real session into the state's
    * own EventEmitter, mapped to sdk.* and stamped with the placeholder id the
    * client first subscribed with. */
@@ -126,7 +177,7 @@ export function createOpencodeFreshAgentAdapter(options: CreateOpencodeFreshAgen
     // later rejection cannot become an unhandled rejection.
     void idle.catch(() => {})
     try {
-      await serveManager.promptAsync(realId, {
+      await promptAsyncForState(state, realId, {
         parts: [{ type: 'text', text }],
         ...(splitOpencodeModel(modelStr) ? { model: splitOpencodeModel(modelStr)! } : {}),
         ...(effort ? { variant: effort } : {}),
@@ -144,13 +195,17 @@ export function createOpencodeFreshAgentAdapter(options: CreateOpencodeFreshAgen
     return sendResult(state.realSessionId)
   }
 
-  async function assembleExport(realSessionId: string, query: { limit?: number; before?: string }): Promise<{ exported: OpencodeExport; nextCursor: string | null; revision: number }> {
+  async function assembleExport(
+    realSessionId: string,
+    query: { limit?: number; before?: string },
+    route?: { cwd: string },
+  ): Promise<{ exported: OpencodeExport; nextCursor: string | null; revision: number }> {
     const [session, page] = await Promise.all([
-      serveManager.getSession(realSessionId).then(
+      (route ? serveManager.getSession(realSessionId, route) : serveManager.getSession(realSessionId)).then(
         (session) => session,
         () => ({} as Record<string, unknown>),
       ),
-      serveManager.listMessages(realSessionId, query),
+      route ? serveManager.listMessages(realSessionId, query, route) : serveManager.listMessages(realSessionId, query),
     ])
     const sessionTime = session && typeof session === 'object' ? session.time : undefined
     const sessionTimeUpdated = sessionTime && typeof sessionTime === 'object' && !Array.isArray(sessionTime)
@@ -217,14 +272,25 @@ export function createOpencodeFreshAgentAdapter(options: CreateOpencodeFreshAgen
 
     async attach(locator) {
       const existing = sessions.get(locator.sessionId)
-      if (existing) { remember(existing); return { sessionId: locator.sessionId, sessionRef: { provider: 'opencode', sessionId: locator.sessionId } } }
+      if (existing) {
+        if (locator.cwd) {
+          existing.cwd = locator.cwd
+          if (existing.realSessionId) serveManager.rememberSessionCwd(existing.realSessionId, locator.cwd)
+        }
+        remember(existing)
+        return { sessionId: locator.sessionId, sessionRef: { provider: 'opencode', sessionId: locator.sessionId } }
+      }
       if (isPlaceholderOpencodeSessionId(locator.sessionId) || !isRealOpencodeSessionId(locator.sessionId)) {
         throw new FreshAgentLostSessionError(`OpenCode session ${locator.sessionId} is not a durable OpenCode session.`)
       }
       const state: OpencodeSessionState = {
-        placeholderId: locator.sessionId, realSessionId: locator.sessionId, status: 'idle',
+        placeholderId: locator.sessionId,
+        realSessionId: locator.sessionId,
+        cwd: locator.cwd,
+        status: 'idle',
         events: new EventEmitter(), sendQueue: Promise.resolve(),
       }
+      if (locator.cwd) serveManager.rememberSessionCwd(locator.sessionId, locator.cwd)
       remember(state)
       bindServeStream(state)
       return { sessionId: locator.sessionId, sessionRef: { provider: 'opencode', sessionId: locator.sessionId } }
@@ -249,7 +315,7 @@ export function createOpencodeFreshAgentAdapter(options: CreateOpencodeFreshAgen
 
     async interrupt(sessionId) {
       const state = requireState(sessionId)
-      if (state.realSessionId) await serveManager.abort(state.realSessionId).catch((err) => log.warn({ err }, 'abort failed'))
+      await abortForState(state).catch((err) => log.warn({ err }, 'abort failed'))
       state.status = 'idle'
       state.events.emit('event', { type: 'sdk.session.snapshot', sessionId: state.placeholderId, status: 'idle' })
     },
@@ -260,8 +326,8 @@ export function createOpencodeFreshAgentAdapter(options: CreateOpencodeFreshAgen
       const instructions = input?.instructions
       const hasInstructions = instructions !== undefined
       const run = state.sendQueue.then(
-        () => (hasInstructions ? serveManager.compact(state.realSessionId!, { instructions }) : serveManager.compact(state.realSessionId!)),
-        () => (hasInstructions ? serveManager.compact(state.realSessionId!, { instructions }) : serveManager.compact(state.realSessionId!)),
+        () => compactForState(state, hasInstructions ? { instructions } : undefined),
+        () => compactForState(state, hasInstructions ? { instructions } : undefined),
       )
       state.sendQueue = run.catch(() => undefined)
       await run
@@ -269,12 +335,11 @@ export function createOpencodeFreshAgentAdapter(options: CreateOpencodeFreshAgen
 
     async fork(sessionId) {
       const state = requireState(sessionId)
-      if (!state.realSessionId) throw new FreshAgentLostSessionError(`OpenCode session ${sessionId} has not materialized; cannot fork.`)
-      const child = await serveManager.fork(state.realSessionId)
+      const child = await forkForState(state)
       const childState: OpencodeSessionState = {
         placeholderId: child.id,
         realSessionId: child.id,
-        cwd: state.cwd,
+        cwd: child.directory ?? state.cwd,
         model: state.model,
         effort: state.effort,
         status: 'idle',
@@ -303,7 +368,10 @@ export function createOpencodeFreshAgentAdapter(options: CreateOpencodeFreshAgen
         })
       }
       const realId = durableId(thread.threadId)
-      const { exported, revision } = await assembleExport(realId, { limit: DEFAULT_SNAPSHOT_TURN_LIMIT })
+      const route = cwdRoute(liveState?.cwd ?? thread.cwd)
+      const { exported, revision } = route
+        ? await assembleExport(realId, { limit: DEFAULT_SNAPSHOT_TURN_LIMIT }, route)
+        : await assembleExport(realId, { limit: DEFAULT_SNAPSHOT_TURN_LIMIT })
       return normalizeOpencodeSnapshot({
         sessionType: 'freshopencode', threadId: thread.threadId,
         exported: { ...exported, info: { ...(exported.info ?? {}), time: { ...((exported.info?.time) ?? {}), updated: revision } } },
@@ -317,10 +385,14 @@ export function createOpencodeFreshAgentAdapter(options: CreateOpencodeFreshAgen
         return normalizeOpencodeTurnPage({ threadId: thread.threadId, exported: { messages: [] }, revision: Number(query.revision) || 0, nextCursor: null })
       }
       const realId = durableId(thread.threadId)
-      const { exported, nextCursor, revision } = await assembleExport(realId, {
+      const route = cwdRoute(liveState?.cwd ?? thread.cwd)
+      const pageQuery = {
         limit: typeof query.limit === 'number' ? query.limit : DEFAULT_SNAPSHOT_TURN_LIMIT,
         before: typeof query.cursor === 'string' ? query.cursor : undefined,
-      })
+      }
+      const { exported, nextCursor, revision } = route
+        ? await assembleExport(realId, pageQuery, route)
+        : await assembleExport(realId, pageQuery)
       return normalizeOpencodeTurnPage({ threadId: thread.threadId, exported, revision, nextCursor })
     },
 
@@ -328,7 +400,10 @@ export function createOpencodeFreshAgentAdapter(options: CreateOpencodeFreshAgen
       const liveState = sessions.get(thread.threadId)
       if (liveState && !liveState.realSessionId) return null
       const realId = durableId(thread.threadId)
-      const message = await serveManager.getMessage(realId, thread.turnId)
+      const route = cwdRoute(liveState?.cwd ?? thread.cwd)
+      const message = route
+        ? await serveManager.getMessage(realId, thread.turnId, route)
+        : await serveManager.getMessage(realId, thread.turnId)
       if (!message) return null
       return normalizeOpencodeTurnBody({ threadId: thread.threadId, exported: { messages: [{ info: message.info, parts: message.parts }] }, turnId: thread.turnId, revision })
     },
diff --git a/server/fresh-agent/adapters/opencode/serve-manager.ts b/server/fresh-agent/adapters/opencode/serve-manager.ts
index e014bdb20..ce21d848f 100644
--- a/server/fresh-agent/adapters/opencode/serve-manager.ts
+++ b/server/fresh-agent/adapters/opencode/serve-manager.ts
@@ -1,6 +1,7 @@
 import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process'
 import { randomUUID } from 'node:crypto'
 import { EventEmitter } from 'node:events'
+import path from 'node:path'
 import type pino from 'pino'
 import { allocateLocalhostPort, type LoopbackServerEndpoint } from '../../../local-port.js'
 import { logger } from '../../../logger.js'
@@ -18,6 +19,8 @@ export type OpencodeServeManagerOptions = {
   /** Override the SSE consumer for tests. Returns an unsubscribe fn. */
   connectEventStream?: (url: string, handlers: { onEvent: (e: ParsedServeEvent) => void; onError: (err: unknown) => void }) => () => void
   healthTimeoutMs?: number
+  env?: NodeJS.ProcessEnv
+  idleShutdownMs?: number
 }
 
 export type OpencodeServeMessage = { info: Record<string, any>; parts: Array<Record<string, any>> }
@@ -41,8 +44,18 @@ type RunningServe = {
   ownershipId: string
   child: ChildProcessWithoutNullStreams
   stopEventStream: () => void
+  cwdKey: string
+  cwd?: string
+  idleTimer?: NodeJS.Timeout
+  activeRequests: number
 }
 
+type ServeRoute = {
+  cwd?: string
+}
+
+const DEFAULT_CWD_KEY = '<inherit-process-cwd>'
+
 export class OpencodeServeManager {
   private readonly command: string
   private readonly spawnFn: typeof spawn
@@ -50,12 +63,16 @@ export class OpencodeServeManager {
   private readonly allocatePort: () => Promise<LoopbackServerEndpoint>
   private readonly connectEventStream?: OpencodeServeManagerOptions['connectEventStream']
   private readonly healthTimeoutMs: number
+  private readonly env: NodeJS.ProcessEnv
+  private readonly idleShutdownMs: number
   private readonly log: OpencodeServeLogger = logger.child({ component: 'opencode-serve-manager' })
   /** sessionId → emitter of ParsedServeEvent (and a synthetic 'idle' event). */
   private readonly sessionEmitters = new Map<string, EventEmitter>()
-  private running: RunningServe | undefined
-  private startPromise: Promise<RunningServe> | undefined
-  private startAbort: AbortController | undefined
+  private readonly runningByCwd = new Map<string, RunningServe>()
+  private readonly startPromiseByCwd = new Map<string, Promise<RunningServe>>()
+  private readonly startAbortByCwd = new Map<string, AbortController>()
+  private readonly cwdByKey = new Map<string, string | undefined>()
+  private readonly sessionCwdById = new Map<string, string>()
   private shutdownRequested = false
 
   constructor(options: OpencodeServeManagerOptions = {}) {
@@ -65,26 +82,107 @@ export class OpencodeServeManager {
     this.allocatePort = options.allocatePort ?? allocateLocalhostPort
     this.connectEventStream = options.connectEventStream
     this.healthTimeoutMs = options.healthTimeoutMs ?? 20_000
+    this.env = options.env ?? process.env
+    this.idleShutdownMs = options.idleShutdownMs ?? 15 * 60_000
+  }
+
+  private routeFromCwd(cwd?: string): { cwdKey: string; cwd?: string } {
+    const trimmed = typeof cwd === 'string' && cwd.trim().length > 0 ? cwd.trim() : undefined
+    if (!trimmed) return { cwdKey: DEFAULT_CWD_KEY }
+    const resolved = path.resolve(trimmed)
+    return { cwdKey: resolved, cwd: resolved }
+  }
+
+  private routeForSession(sessionId: string, fallback?: ServeRoute): { cwdKey: string; cwd?: string } {
+    const existingKey = this.sessionCwdById.get(sessionId)
+    if (existingKey) {
+      return { cwdKey: existingKey, ...(this.cwdByKey.get(existingKey) ? { cwd: this.cwdByKey.get(existingKey) } : {}) }
+    }
+    return this.routeFromCwd(fallback?.cwd)
+  }
+
+  rememberSessionCwd(sessionId: string, cwd?: string): void {
+    if (!sessionId) return
+    const route = this.routeFromCwd(cwd)
+    this.cwdByKey.set(route.cwdKey, route.cwd)
+    this.sessionCwdById.set(sessionId, route.cwdKey)
+  }
+
+  private forgetSessionsForCwd(cwdKey: string): void {
+    for (const [sessionId, sessionCwdKey] of this.sessionCwdById.entries()) {
+      if (sessionCwdKey !== cwdKey) continue
+      this.sessionCwdById.delete(sessionId)
+      this.sessionEmitters.delete(sessionId)
+    }
+    if (cwdKey === DEFAULT_CWD_KEY) {
+      for (const sessionId of this.sessionEmitters.keys()) {
+        if (!this.sessionCwdById.has(sessionId)) this.sessionEmitters.delete(sessionId)
+      }
+    }
+  }
+
+  private clearIdleTimer(running: RunningServe): void {
+    if (!running.idleTimer) return
+    clearTimeout(running.idleTimer)
+    running.idleTimer = undefined
+  }
+
+  private scheduleIdleShutdown(running: RunningServe): void {
+    this.clearIdleTimer(running)
+    if (running.cwdKey === DEFAULT_CWD_KEY || this.idleShutdownMs <= 0 || running.activeRequests > 0) return
+    running.idleTimer = setTimeout(() => {
+      running.idleTimer = undefined
+      if (running.activeRequests > 0) return
+      if (this.runningByCwd.get(running.cwdKey) !== running) return
+      this.runningByCwd.delete(running.cwdKey)
+      this.startPromiseByCwd.delete(running.cwdKey)
+      this.startAbortByCwd.delete(running.cwdKey)
+      try { running.stopEventStream() } catch { /* ignore */ }
+      void killOwnedProcesses(running.child, running.ownershipId, this.log)
+    }, this.idleShutdownMs)
+    running.idleTimer.unref?.()
+  }
+
+  private async withRunning<T>(
+    route: { cwdKey: string; cwd?: string },
+    fn: (baseUrl: string) => Promise<T>,
+  ): Promise<T> {
+    const { baseUrl } = await this.ensureStarted(route.cwd ? { cwd: route.cwd } : {})
+    const running = this.runningByCwd.get(route.cwdKey)
+    if (!running) return fn(baseUrl)
+    this.clearIdleTimer(running)
+    running.activeRequests += 1
+    try {
+      return await fn(baseUrl)
+    } finally {
+      running.activeRequests -= 1
+      this.scheduleIdleShutdown(running)
+    }
   }
 
-  async ensureStarted(): Promise<{ baseUrl: string }> {
+  async ensureStarted(input: ServeRoute = {}): Promise<{ baseUrl: string }> {
     if (this.shutdownRequested) {
       throw new Error('opencode serve manager is shutting down')
     }
-    if (this.running) return { baseUrl: this.running.baseUrl }
-    if (!this.startPromise) {
-      this.startPromise = this.start().catch((err) => {
-        this.startPromise = undefined
+    const route = this.routeFromCwd(input.cwd)
+    this.cwdByKey.set(route.cwdKey, route.cwd)
+    const running = this.runningByCwd.get(route.cwdKey)
+    if (running) return { baseUrl: running.baseUrl }
+    if (!this.startPromiseByCwd.has(route.cwdKey)) {
+      const promise = this.start(route).catch((err) => {
+        this.startPromiseByCwd.delete(route.cwdKey)
         throw err
       })
+      this.startPromiseByCwd.set(route.cwdKey, promise)
     }
-    const running = await this.startPromise
-    return { baseUrl: running.baseUrl }
+    const next = await this.startPromiseByCwd.get(route.cwdKey)!
+    this.startPromiseByCwd.delete(route.cwdKey)
+    return { baseUrl: next.baseUrl }
   }
 
-  private async start(): Promise<RunningServe> {
+  private async start(route: { cwdKey: string; cwd?: string }): Promise<RunningServe> {
     const startAbort = new AbortController()
-    this.startAbort = startAbort
+    this.startAbortByCwd.set(route.cwdKey, startAbort)
     const startSignal = startAbort.signal
     let child: ChildProcessWithoutNullStreams | undefined
     try {
@@ -94,24 +192,30 @@ export class OpencodeServeManager {
       child = this.spawnFn(
         this.command,
         ['serve', '--hostname', endpoint.hostname, '--port', String(endpoint.port)],
-        { env: { ...process.env, [OWNERSHIP_ENV]: ownershipId }, stdio: ['ignore', 'pipe', 'pipe'] },
+        {
+          ...(route.cwd ? { cwd: route.cwd } : {}),
+          env: { ...this.env, [OWNERSHIP_ENV]: ownershipId },
+          stdio: ['ignore', 'pipe', 'pipe'],
+        },
       ) as unknown as ChildProcessWithoutNullStreams
       // Drain stdout/stderr so the child's pipe buffers never back-pressure
       // and stall the serve process. Diagnostics are captured below before health.
       child.stdout?.on('data', () => {})
       child.stderr?.on('data', () => {})
       child.on('error', (err) => this.log.error({ err }, 'opencode serve process error'))
-    child.on('close', (code) => {
-      this.log.warn({ code }, 'opencode serve exited')
-      if (this.running && this.running.child === child) {
-        const running = this.running
-        this.running = undefined
-        this.startPromise = undefined
-        try { running.stopEventStream() } catch { /* ignore */ }
-        void killOwnedProcesses(running.child, running.ownershipId, this.log)
-        this.sessionEmitters.clear()
-      }
-    })
+      child.on('close', (code) => {
+        this.log.warn({ code }, 'opencode serve exited')
+        const runningEntry = this.runningByCwd.get(route.cwdKey)
+        if (runningEntry && runningEntry.child === child) {
+          this.runningByCwd.delete(route.cwdKey)
+          this.startPromiseByCwd.delete(route.cwdKey)
+          this.startAbortByCwd.delete(route.cwdKey)
+          this.clearIdleTimer(runningEntry)
+          try { runningEntry.stopEventStream() } catch { /* ignore */ }
+          void killOwnedProcesses(runningEntry.child, runningEntry.ownershipId, this.log)
+          this.forgetSessionsForCwd(route.cwdKey)
+        }
+      })
 
       await this.waitForHealth(baseUrl, child, startSignal)
 
@@ -127,15 +231,24 @@ export class OpencodeServeManager {
           })
         : this.startDefaultEventStream(baseUrl)
 
-      const running: RunningServe = { baseUrl, ownershipId, child, stopEventStream }
-      this.running = running
+      const running: RunningServe = {
+        baseUrl,
+        ownershipId,
+        child,
+        stopEventStream,
+        cwdKey: route.cwdKey,
+        ...(route.cwd ? { cwd: route.cwd } : {}),
+        activeRequests: 0,
+      }
+      this.runningByCwd.set(route.cwdKey, running)
+      this.scheduleIdleShutdown(running)
       return running
     } catch (err) {
       if (child) this.stopChild(child)
-      this.startPromise = undefined
+      this.startPromiseByCwd.delete(route.cwdKey)
       throw err
     } finally {
-      if (this.startAbort === startAbort) this.startAbort = undefined
+      if (this.startAbortByCwd.get(route.cwdKey) === startAbort) this.startAbortByCwd.delete(route.cwdKey)
     }
   }
 
@@ -180,21 +293,24 @@ export class OpencodeServeManager {
   }
 
   // ── HTTP client ────────────────────────────────────────────────────────
-  private async requireBase(): Promise<string> {
-    const { baseUrl } = await this.ensureStarted()
-    return baseUrl
-  }
-
-  private async json<T>(path: string, init?: RequestInit & { notFoundValue?: T }): Promise<T> {
-    const base = await this.requireBase()
-    const res = await this.fetchFn(`${base}${path}`, init)
-    if (!res.ok && res.status !== 204) {
-      if (res.status === 404 && init?.notFoundValue !== undefined) return init.notFoundValue
-      const text = await res.text().catch(() => '')
-      throw new Error(`opencode serve ${init?.method ?? 'GET'} ${path} → ${res.status} ${text}`)
-    }
-    if (res.status === 204) return undefined as T
-    return (await res.json()) as T
+  private async json<T>(
+    route: ServeRoute & { sessionId?: string },
+    requestPath: string,
+    init?: RequestInit & { notFoundValue?: T },
+  ): Promise<T> {
+    const resolved = route.sessionId
+      ? this.routeForSession(route.sessionId, route)
+      : this.routeFromCwd(route.cwd)
+    return this.withRunning(resolved, async (base) => {
+      const res = await this.fetchFn(`${base}${requestPath}`, init)
+      if (!res.ok && res.status !== 204) {
+        if (res.status === 404 && init?.notFoundValue !== undefined) return init.notFoundValue
+        const text = await res.text().catch(() => '')
+        throw new Error(`opencode serve ${init?.method ?? 'GET'} ${requestPath} → ${res.status} ${text}`)
+      }
+      if (res.status === 204) return undefined as T
+      return (await res.json()) as T
+    })
   }
 
   async createSession(input: { title?: string; parentID?: string; directory?: string } = {}): Promise<{ id: string; directory?: string; title?: string }> {
@@ -202,63 +318,99 @@ export class OpencodeServeManager {
     if (input.title !== undefined) body.title = input.title
     if (input.parentID !== undefined) body.parentID = input.parentID
     if (input.directory !== undefined) body.directory = input.directory
-    return this.json('/session', {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify(body),
-    })
+    const session = await this.json<{ id: string; directory?: string; title?: string }>(
+      input.directory ? { cwd: input.directory } : {},
+      '/session',
+      {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+      },
+    )
+    if (typeof session.id === 'string') this.rememberSessionCwd(session.id, session.directory ?? input.directory)
+    return session
   }
 
-  async getSession(id: string): Promise<Record<string, any>> {
-    return this.json(`/session/${encodeURIComponent(id)}`, { method: 'GET' })
+  async getSession(id: string, route: ServeRoute = {}): Promise<Record<string, any>> {
+    const session = await this.json<Record<string, any>>(
+      { ...route, sessionId: id },
+      `/session/${encodeURIComponent(id)}`,
+      { method: 'GET' },
+    )
+    if (typeof session?.directory === 'string' && session.directory.length > 0) {
+      this.rememberSessionCwd(id, session.directory)
+    }
+    return session
   }
 
-  async promptAsync(id: string, body: { parts: Array<Record<string, unknown>>; model?: { providerID: string; modelID: string }; variant?: string; agent?: string }): Promise<void> {
-    await this.json(`/session/${encodeURIComponent(id)}/prompt_async`, {
+  async promptAsync(
+    id: string,
+    body: { parts: Array<Record<string, unknown>>; model?: { providerID: string; modelID: string }; variant?: string; agent?: string },
+    route: ServeRoute = {},
+  ): Promise<void> {
+    await this.json({ ...route, sessionId: id }, `/session/${encodeURIComponent(id)}/prompt_async`, {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
       body: JSON.stringify(body),
     })
   }
 
-  async listMessages(id: string, query: { limit?: number; before?: string }): Promise<OpencodeServeMessagePage> {
-    const base = await this.requireBase()
-    const params = new URLSearchParams()
-    if (typeof query.limit === 'number') params.set('limit', String(query.limit))
-    if (query.before) params.set('before', query.before)
-    const qs = params.toString()
-    const url = `${base}/session/${encodeURIComponent(id)}/message${qs ? `?${qs}` : ''}`
-    const res = await this.fetchFn(url, { method: 'GET' })
-    if (!res.ok) {
-      const text = await res.text().catch(() => '')
-      throw new Error(`opencode serve GET messages → ${res.status} ${text}`)
-    }
-    const messages = (await res.json()) as OpencodeServeMessage[]
-    const nextCursor = res.headers.get('x-next-cursor') || null
-    return { messages: Array.isArray(messages) ? messages : [], nextCursor }
+  async listMessages(id: string, query: { limit?: number; before?: string }, route: ServeRoute = {}): Promise<OpencodeServeMessagePage> {
+    const resolved = this.routeForSession(id, route)
+    return this.withRunning(resolved, async (base) => {
+      const params = new URLSearchParams()
+      if (typeof query.limit === 'number') params.set('limit', String(query.limit))
+      if (query.before) params.set('before', query.before)
+      const qs = params.toString()
+      const url = `${base}/session/${encodeURIComponent(id)}/message${qs ? `?${qs}` : ''}`
+      const res = await this.fetchFn(url, { method: 'GET' })
+      if (!res.ok) {
+        const text = await res.text().catch(() => '')
+        throw new Error(`opencode serve GET messages → ${res.status} ${text}`)
+      }
+      const messages = (await res.json()) as OpencodeServeMessage[]
+      const nextCursor = res.headers.get('x-next-cursor') || null
+      return { messages: Array.isArray(messages) ? messages : [], nextCursor }
+    })
   }
 
-  async getMessage(id: string, messageId: string): Promise<OpencodeServeMessage | null> {
+  async getMessage(id: string, messageId: string, route: ServeRoute = {}): Promise<OpencodeServeMessage | null> {
     return this.json<OpencodeServeMessage | null>(
+      { ...route, sessionId: id },
       `/session/${encodeURIComponent(id)}/message/${encodeURIComponent(messageId)}`,
       { method: 'GET', notFoundValue: null },
     )
   }
 
-  async abort(id: string): Promise<void> {
-    await this.json(`/session/${encodeURIComponent(id)}/abort`, { method: 'POST' })
+  async abort(id: string, route: ServeRoute = {}): Promise<void> {
+    await this.json({ ...route, sessionId: id }, `/session/${encodeURIComponent(id)}/abort`, { method: 'POST' })
   }
 
-  async compact(id: string, body?: { instructions?: string }): Promise<void> {
-    await this.json(`/session/${encodeURIComponent(id)}/compact`, {
+  async compact(id: string, body?: { instructions?: string }, route: ServeRoute = {}): Promise<void> {
+    await this.json({ ...route, sessionId: id }, `/session/${encodeURIComponent(id)}/summarize`, {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
       body: JSON.stringify(body ?? {}),
     })
   }
 
-  async fork(id: string): Promise<{ id: string }> {
-    return this.json(`/session/${encodeURIComponent(id)}/fork`, { method: 'POST' })
+  async fork(id: string, route: ServeRoute = {}): Promise<{ id: string; directory?: string }> {
+    const child = await this.json<{ id: string; directory?: string }>(
+      { ...route, sessionId: id },
+      `/session/${encodeURIComponent(id)}/fork`,
+      { method: 'POST' },
+    )
+    if (typeof child.id === 'string') {
+      const returnedDirectory = typeof child.directory === 'string' && child.directory.trim().length > 0
+        ? child.directory
+        : undefined
+      const fallbackDirectory = typeof route.cwd === 'string' && route.cwd.trim().length > 0
+        ? route.cwd
+        : undefined
+      const childDirectory = returnedDirectory ?? fallbackDirectory
+      if (childDirectory) this.rememberSessionCwd(child.id, childDirectory)
+    }
+    return child
   }
 
   // ── SSE fan-out (Task A3 adds subscribe/onceIdle) ──────────────────────
@@ -355,27 +507,35 @@ export class OpencodeServeManager {
 
   async shutdown(): Promise<void> {
     this.shutdownRequested = true
-    this.startAbort?.abort()
+    for (const controller of this.startAbortByCwd.values()) {
+      controller.abort()
+    }
 
-    // Reap any in-flight start() so it terminates its child and any start
-    // promise settles before we touch the running sidecar.
-    if (this.startPromise) {
-      try { await this.startPromise } catch { /* ignore startup errors */ }
-      this.startPromise = undefined
+    const starts = [...this.startPromiseByCwd.values()]
+    if (starts.length > 0) {
+      await Promise.all(starts.map(async (promise) => {
+        try { await promise } catch { /* ignore startup errors */ }
+      }))
+      this.startPromiseByCwd.clear()
     }
 
-    const running = this.running
-    this.running = undefined
-    this.startPromise = undefined
-    if (!running) return
-    try { running.stopEventStream() } catch { /* ignore */ }
-    await killOwnedProcesses(running.child, running.ownershipId, this.log)
+    const running = [...this.runningByCwd.values()]
+    this.runningByCwd.clear()
+    this.startPromiseByCwd.clear()
+    this.startAbortByCwd.clear()
+    await Promise.all(running.map(async (entry) => {
+      this.clearIdleTimer(entry)
+      try { entry.stopEventStream() } catch { /* ignore */ }
+      await killOwnedProcesses(entry.child, entry.ownershipId, this.log)
+    }))
     this.sessionEmitters.clear()
+    this.sessionCwdById.clear()
+    this.cwdByKey.clear()
   }
 
   /** @internal test/inspection accessor */
   get baseUrlOrUndefined(): string | undefined {
-    return this.running?.baseUrl
+    return [...this.runningByCwd.values()][0]?.baseUrl
   }
 }
 
diff --git a/server/fresh-agent/router.ts b/server/fresh-agent/router.ts
index f84ab91aa..6825ea567 100644
--- a/server/fresh-agent/router.ts
+++ b/server/fresh-agent/router.ts
@@ -143,9 +143,11 @@ export function createFreshAgentRouter(deps: {
     const query = z.object({
       priority: ReadModelPrioritySchema.optional(),
       revision: z.coerce.number().int().nonnegative().optional(),
+      cwd: z.string().trim().min(1).optional(),
     }).safeParse({
       priority: typeof req.query.priority === 'string' ? req.query.priority : undefined,
       revision: typeof req.query.revision === 'string' ? req.query.revision : undefined,
+      cwd: typeof req.query.cwd === 'string' ? req.query.cwd : undefined,
     })
 
     if (!params.success || !query.success) {
@@ -165,6 +167,7 @@ export function createFreshAgentRouter(deps: {
           provider: params.data.provider,
           threadId: params.data.threadId,
           revision: query.data.revision,
+          cwd: query.data.cwd,
         }),
       })
       setResponsePerfContext(res, {
@@ -184,6 +187,7 @@ export function createFreshAgentRouter(deps: {
       cursor: typeof req.query.cursor === 'string' ? req.query.cursor : undefined,
       priority: typeof req.query.priority === 'string' ? req.query.priority : undefined,
       revision: typeof req.query.revision === 'string' ? req.query.revision : undefined,
+      cwd: typeof req.query.cwd === 'string' ? req.query.cwd : undefined,
       limit: typeof req.query.limit === 'string' ? Number(req.query.limit) : undefined,
       includeBodies: typeof req.query.includeBodies === 'string' ? req.query.includeBodies : undefined,
     })
@@ -207,6 +211,7 @@ export function createFreshAgentRouter(deps: {
           cursor: query.data.cursor,
           priority: query.data.priority,
           revision: query.data.revision,
+          cwd: query.data.cwd,
           limit: query.data.limit,
           includeBodies: query.data.includeBodies,
         }),
@@ -226,6 +231,7 @@ export function createFreshAgentRouter(deps: {
     const params = TurnParamsSchema.safeParse(req.params)
     const query = FreshAgentThreadTurnBodyQuerySchema.safeParse({
       revision: typeof req.query.revision === 'string' ? req.query.revision : undefined,
+      cwd: typeof req.query.cwd === 'string' ? req.query.cwd : undefined,
     })
     if (!params.success || !query.success) {
       return res.status(400).json({
@@ -240,6 +246,7 @@ export function createFreshAgentRouter(deps: {
         provider: params.data.provider,
         threadId: params.data.threadId,
         turnId: params.data.turnId,
+        cwd: query.data.cwd,
         revision: query.data.revision,
       })
       if (!turn) {
diff --git a/server/fresh-agent/runtime-adapter.ts b/server/fresh-agent/runtime-adapter.ts
index 9e8022184..43779b948 100644
--- a/server/fresh-agent/runtime-adapter.ts
+++ b/server/fresh-agent/runtime-adapter.ts
@@ -37,12 +37,14 @@ export type FreshAgentThreadLocator = {
   sessionType: FreshAgentSessionType
   provider: FreshAgentRuntimeProvider
   threadId: string
+  cwd?: string
 }
 
 export type FreshAgentSessionLocator = {
   sessionType: FreshAgentSessionType
   provider: FreshAgentRuntimeProvider
   sessionId: string
+  cwd?: string
 }
 
 export type FreshAgentInputImage =
diff --git a/server/fresh-agent/runtime-manager.ts b/server/fresh-agent/runtime-manager.ts
index a36bb28c1..c3ff92095 100644
--- a/server/fresh-agent/runtime-manager.ts
+++ b/server/fresh-agent/runtime-manager.ts
@@ -239,6 +239,7 @@ export class FreshAgentRuntimeManager {
     sessionType: FreshAgentSessionType
     provider: FreshAgentRuntimeProvider
     threadId: string
+    cwd?: string
     revision?: number
   }) {
     const registration = this.requireRegistration(input.sessionType, input.provider)
@@ -249,6 +250,7 @@ export class FreshAgentRuntimeManager {
       sessionType: input.sessionType,
       provider: input.provider,
       threadId: input.threadId,
+      cwd: input.cwd,
     }, input.revision)
     const parsed = FreshAgentSnapshotSchema.safeParse(snapshot)
     if (!parsed.success) {
@@ -261,6 +263,7 @@ export class FreshAgentRuntimeManager {
     sessionType: FreshAgentSessionType
     provider: FreshAgentRuntimeProvider
     threadId: string
+    cwd?: string
     cursor?: string
     priority?: string
     revision: number
@@ -272,7 +275,7 @@ export class FreshAgentRuntimeManager {
       throw new FreshAgentRuntimeUnavailableError(`No fresh-agent turn-page adapter registered for ${input.sessionType}`)
     }
     const page = await registration.adapter.getTurnPage(
-      { sessionType: input.sessionType, provider: input.provider, threadId: input.threadId },
+      { sessionType: input.sessionType, provider: input.provider, threadId: input.threadId, cwd: input.cwd },
       input,
     )
     const parsed = FreshAgentTurnPageSchema.safeParse(page)
@@ -287,6 +290,7 @@ export class FreshAgentRuntimeManager {
     provider: FreshAgentRuntimeProvider
     threadId: string
     turnId: string
+    cwd?: string
     revision: number
   }) {
     const registration = this.requireRegistration(input.sessionType, input.provider)
@@ -298,6 +302,7 @@ export class FreshAgentRuntimeManager {
         sessionType: input.sessionType,
         provider: input.provider,
         threadId: input.threadId,
+        cwd: input.cwd,
         turnId: input.turnId,
       },
       input.revision,
diff --git a/server/ws-handler.ts b/server/ws-handler.ts
index 9de51714c..e450d6206 100644
--- a/server/ws-handler.ts
+++ b/server/ws-handler.ts
@@ -3158,7 +3158,12 @@ export class WsHandler {
           this.sendError(ws, { code: 'INTERNAL_ERROR', message: this.freshAgentUnavailableMessage() })
           return
         }
-        const locator = { sessionId: m.sessionId, sessionType: m.sessionType, provider: m.provider }
+        const locator = {
+          sessionId: m.sessionId,
+          sessionType: m.sessionType,
+          provider: m.provider,
+          ...(m.cwd ? { cwd: m.cwd } : {}),
+        }
         try {
           await Promise.resolve(manager.attach(locator))
           this.authorizeFreshAgentSession(state, locator)
diff --git a/shared/read-models.ts b/shared/read-models.ts
index c3289dae5..b90c9f648 100644
--- a/shared/read-models.ts
+++ b/shared/read-models.ts
@@ -78,6 +78,7 @@ export const FreshAgentThreadTurnsQuerySchema = z.object({
   cursor: z.string().min(1).optional(),
   priority: ReadModelPrioritySchema.optional(),
   revision: z.coerce.number().int().nonnegative(),
+  cwd: z.string().trim().min(1).optional(),
   limit: z.number().int().positive().max(MAX_FRESH_AGENT_THREAD_TURNS).optional(),
   includeBodies: z.union([
     z.boolean(),
@@ -87,6 +88,7 @@ export const FreshAgentThreadTurnsQuerySchema = z.object({
 
 export const FreshAgentThreadTurnBodyQuerySchema = z.object({
   revision: z.coerce.number().int().nonnegative(),
+  cwd: z.string().trim().min(1).optional(),
 })
 
 export const RestoreStaleRevisionResponseSchema = z.object({
diff --git a/shared/ws-protocol.ts b/shared/ws-protocol.ts
index 53d4cd633..b0d4663f0 100644
--- a/shared/ws-protocol.ts
+++ b/shared/ws-protocol.ts
@@ -425,6 +425,7 @@ export const FreshAgentAttachSchema = z.object({
   sessionType: z.enum(['freshclaude', 'freshcodex', 'kilroy', 'freshopencode']),
   provider: z.enum(['claude', 'codex', 'opencode']),
   resumeSessionId: z.string().optional(),
+  cwd: z.string().optional(),
 })
 
 export const FreshAgentSendSchema = z.object({
diff --git a/src/components/fresh-agent/FreshAgentView.tsx b/src/components/fresh-agent/FreshAgentView.tsx
index 8e0668091..b22f42266 100644
--- a/src/components/fresh-agent/FreshAgentView.tsx
+++ b/src/components/fresh-agent/FreshAgentView.tsx
@@ -675,6 +675,7 @@ export function FreshAgentView({
         sessionType: current.sessionType,
         provider: current.provider,
         resumeSessionId: current.resumeSessionId,
+        cwd: current.initialCwd,
       })
       setSnapshotRefreshNonce((value) => value + 1)
     } else if (!hidden && (current.status === 'creating' || current.status === 'starting')) {
@@ -787,8 +788,9 @@ export function FreshAgentView({
       sessionType: paneContent.sessionType,
       provider: paneContent.provider,
       resumeSessionId: paneContent.resumeSessionId,
+      cwd: paneContent.initialCwd,
     })
-  }, [hidden, paneContent.provider, paneContent.resumeSessionId, paneContent.sessionId, paneContent.sessionType])
+  }, [hidden, paneContent.initialCwd, paneContent.provider, paneContent.resumeSessionId, paneContent.sessionId, paneContent.sessionType])
 
   useEffect(() => {
     if (typeof ws.onMessage !== 'function') return
@@ -918,7 +920,11 @@ export function FreshAgentView({
       || paneContentRef.current.sessionType !== requestSessionType
       || snapshotThreadIdRef.current !== sessionId
     )
-    void getFreshAgentThreadSnapshot(requestSessionType, provider, sessionId, { signal: controller.signal })
+    const requestCwd = paneContentRef.current.initialCwd
+    void getFreshAgentThreadSnapshot(requestSessionType, provider, sessionId, {
+      signal: controller.signal,
+      ...(requestCwd ? { cwd: requestCwd } : {}),
+    })
       .then((next) => {
         if (isStaleSnapshotRequest()) return
         const snapshotIdentity = currentAutoTitleIdentityRef.current
diff --git a/src/lib/api.ts b/src/lib/api.ts
index 90fd88483..7c0fd8cfc 100644
--- a/src/lib/api.ts
+++ b/src/lib/api.ts
@@ -309,13 +309,14 @@ export async function getFreshAgentThreadSnapshot(
   sessionType: string,
   provider: string,
   threadId: string,
-  query: { revision?: number; signal?: AbortSignal } = {},
+  query: { revision?: number; cwd?: string; signal?: AbortSignal } = {},
   options: ApiRequestOptions = {},
 ): Promise<any> {
   const signal = query.signal ?? options.signal
   const data = await api.get(
     `/api/fresh-agent/threads/${encodeURIComponent(sessionType)}/${encodeURIComponent(provider)}/${encodeURIComponent(threadId)}${buildQueryString([
       ['revision', query.revision],
+      ['cwd', query.cwd],
     ])}`,
     { ...options, signal },
   )
@@ -334,6 +335,7 @@ export async function getFreshAgentTurnPage(
     cursor?: string
     priority?: string
     revision: number
+    cwd?: string
     limit?: number
     includeBodies?: boolean
     signal?: AbortSignal
@@ -346,6 +348,7 @@ export async function getFreshAgentTurnPage(
       ['revision', query.revision],
       ['cursor', query.cursor],
       ['priority', query.priority],
+      ['cwd', query.cwd],
       ['limit', query.limit],
       ['includeBodies', query.includeBodies ? 'true' : undefined],
     ])}`,
@@ -363,13 +366,14 @@ export async function getFreshAgentTurnBody(
   provider: string,
   threadId: string,
   turnId: string,
-  query: { revision: number; signal?: AbortSignal },
+  query: { revision: number; cwd?: string; signal?: AbortSignal },
   options: ApiRequestOptions = {},
 ): Promise<any> {
   const signal = query.signal ?? options.signal
   const data = await api.get(
     `/api/fresh-agent/threads/${encodeURIComponent(sessionType)}/${encodeURIComponent(provider)}/${encodeURIComponent(threadId)}/turns/${encodeURIComponent(turnId)}${buildQueryString([
       ['revision', query.revision],
+      ['cwd', query.cwd],
     ])}`,
     { ...options, signal },
   )
diff --git a/src/store/freshAgentThunks.ts b/src/store/freshAgentThunks.ts
index 6e2288891..54dbde553 100644
--- a/src/store/freshAgentThunks.ts
+++ b/src/store/freshAgentThunks.ts
@@ -12,6 +12,7 @@ type FreshAgentThreadThunkLocator = {
   sessionType: FreshAgentSessionType
   provider: FreshAgentRuntimeProvider
   sessionId: string
+  cwd?: string
 }
 
 const inFlightControllers = new Set<AbortController>()
@@ -47,6 +48,7 @@ export const loadFreshAgentThreadTurns = createAsyncThunk(
           cursor: input.cursor,
           limit: input.limit,
           includeBodies: input.includeBodies,
+          cwd: input.cwd,
           signal: controller.signal,
         },
       )
@@ -88,6 +90,7 @@ export const loadFreshAgentTurnBody = createAsyncThunk(
         input.turnId,
         {
           revision: input.revision,
+          cwd: input.cwd,
           signal: controller.signal,
         },
       )
diff --git a/test/integration/server/opencode-serve-real-provider-smoke.test.ts b/test/integration/server/opencode-serve-real-provider-smoke.test.ts
index 2576868d7..976c73631 100644
--- a/test/integration/server/opencode-serve-real-provider-smoke.test.ts
+++ b/test/integration/server/opencode-serve-real-provider-smoke.test.ts
@@ -1,3 +1,4 @@
+import fs from 'node:fs/promises'
 import { afterAll, beforeAll, describe, expect, it } from 'vitest'
 import express from 'express'
 import request from 'supertest'
@@ -10,7 +11,12 @@ import { LayoutStore } from '../../../server/agent-api/layout-store.js'
 import { FreshAgentRuntimeManager } from '../../../server/fresh-agent/runtime-manager.js'
 import { createFreshAgentProviderRegistry } from '../../../server/fresh-agent/provider-registry.js'
 import { createOpencodeFreshAgentAdapter } from '../../../server/fresh-agent/adapters/opencode/adapter.js'
-import { resolveProviderBinary } from '../../../test/helpers/coding-cli/real-session-contract-harness.js'
+import {
+  ProbeWorkspace,
+  resolveProviderBinary,
+  seedOpencodeHomes,
+  waitForOpencodeDbSession,
+} from '../../../test/helpers/coding-cli/real-session-contract-harness.js'
 
 const opencode = await resolveProviderBinary('opencode')
 const KIMI = 'umans-ai-coding-plan/umans-kimi-k2.7'
@@ -35,6 +41,31 @@ describeReal(
           await manager.shutdown()
         }
       }, 60_000)
+
+      it('creates first-run sessions in the requested cwd, not the Freshell process cwd', async () => {
+        const workspace = await ProbeWorkspace.create('freshell-opencode-real-cwd-')
+        const requestedCwd = workspace.inTemp('requested-project')
+        const homes = await seedOpencodeHomes(workspace)
+        const manager = new OpencodeServeManager({
+          env: {
+            ...process.env,
+            XDG_DATA_HOME: homes.dataHome,
+            XDG_CONFIG_HOME: homes.configHome,
+          },
+        })
+        try {
+          await fs.mkdir(requestedCwd, { recursive: true })
+          const session = await manager.createSession({ directory: requestedCwd })
+          expect(session.id).toMatch(/^ses_/)
+          expect(session.directory).toBe(requestedCwd)
+
+          const row = await waitForOpencodeDbSession(homes.dbPath, session.id)
+          expect(row.directory).toBe(requestedCwd)
+        } finally {
+          await manager.shutdown()
+          await workspace.cleanup()
+        }
+      }, 60_000)
     })
   },
 )
diff --git a/test/server/agent-api-fresh-agent.test.ts b/test/server/agent-api-fresh-agent.test.ts
index dd40553f5..32d11df81 100644
--- a/test/server/agent-api-fresh-agent.test.ts
+++ b/test/server/agent-api-fresh-agent.test.ts
@@ -124,6 +124,37 @@ describe('agent-api fresh-agent: send-keys', () => {
     )
   })
 
+  it('passes the pane cwd back to the runtime when sending to a fresh-agent pane', async () => {
+    const freshAgentRuntimeManager = {
+      create: vi.fn(async () => ({
+        sessionId: 'codex-thread-cwd',
+        sessionType: 'freshcodex',
+        runtimeProvider: 'codex',
+        sessionRef: { provider: 'codex', sessionId: 'codex-thread-cwd' },
+      })),
+      send: vi.fn(async () => undefined),
+      attach: vi.fn(async () => ({ sessionId: 'codex-thread-cwd' })),
+      getSnapshot: vi.fn(async () => ({ status: 'idle', turns: [] })),
+    }
+    const { app } = makeApp({ freshAgentRuntimeManager })
+    const created = await request(app).post('/api/tabs').send({ agent: 'codex', cwd: '/repo/persisted-worktree' })
+    const paneId = created.body.data.paneId
+
+    const res = await request(app).post(`/api/panes/${paneId}/send-keys`).send({ data: 'Check cwd' })
+
+    expect(res.status).toBe(200)
+    expect(freshAgentRuntimeManager.send).toHaveBeenCalledWith(
+      { sessionId: 'codex-thread-cwd', sessionType: 'freshcodex', provider: 'codex', cwd: '/repo/persisted-worktree' },
+      { text: 'Check cwd', settings: { cwd: '/repo/persisted-worktree' } },
+    )
+    expect(freshAgentRuntimeManager.getSnapshot).toHaveBeenCalledWith({
+      sessionType: 'freshcodex',
+      provider: 'codex',
+      threadId: 'codex-thread-cwd',
+      cwd: '/repo/persisted-worktree',
+    })
+  })
+
   it('attaches on a lost session before retrying send (cross-process orchestration)', async () => {
     const send = vi.fn().mockRejectedValueOnce(new FreshAgentLostSessionError('not tracked')).mockResolvedValueOnce({ sessionId: 'ses_real_1' })
     const attach = vi.fn(async () => ({ sessionId: 'ses_real_1' }))
diff --git a/test/unit/client/components/fresh-agent/FreshAgentView.test.tsx b/test/unit/client/components/fresh-agent/FreshAgentView.test.tsx
index 08f87ca6d..db181d38b 100644
--- a/test/unit/client/components/fresh-agent/FreshAgentView.test.tsx
+++ b/test/unit/client/components/fresh-agent/FreshAgentView.test.tsx
@@ -586,6 +586,7 @@ describe('FreshAgentView', () => {
             provider: 'codex',
             createRequestId: 'req-restored-codex',
             sessionRef: { provider: 'codex', sessionId: 'thread-from-ref' },
+            initialCwd: '/repo/from-ref',
             status: 'connected',
           }}
         />
@@ -593,7 +594,12 @@ describe('FreshAgentView', () => {
     )
 
     await waitFor(() => {
-      expect(apiMock.getFreshAgentThreadSnapshot).toHaveBeenCalledWith('freshcodex', 'codex', 'thread-from-ref', expect.any(Object))
+      expect(apiMock.getFreshAgentThreadSnapshot).toHaveBeenCalledWith(
+        'freshcodex',
+        'codex',
+        'thread-from-ref',
+        expect.objectContaining({ cwd: '/repo/from-ref' }),
+      )
     })
     expect(await screen.findByText('Codex turn')).toBeInTheDocument()
   })
diff --git a/test/unit/client/lib/api.test.ts b/test/unit/client/lib/api.test.ts
index 9d22c1cb2..f0dd24bb1 100644
--- a/test/unit/client/lib/api.test.ts
+++ b/test/unit/client/lib/api.test.ts
@@ -220,23 +220,23 @@ describe('visible-first read-model helpers', () => {
       .mockResolvedValueOnce(mockJson(codexContractTurnPage))
       .mockResolvedValueOnce(mockJson(codexContractTurnBody))
 
-    await getFreshAgentThreadSnapshot('freshcodex', 'codex', 'thread-1', { revision: 7, signal })
-    await getFreshAgentTurnPage('freshcodex', 'codex', 'thread-1', { revision: 7, cursor: 'cursor-1', limit: 20 }, { signal })
-    await getFreshAgentTurnBody('freshcodex', 'codex', 'thread-1', 'turn-1', { revision: 7, signal })
+    await getFreshAgentThreadSnapshot('freshcodex', 'codex', 'thread-1', { revision: 7, cwd: '/repo/worktree', signal })
+    await getFreshAgentTurnPage('freshcodex', 'codex', 'thread-1', { revision: 7, cursor: 'cursor-1', cwd: '/repo/worktree', limit: 20 }, { signal })
+    await getFreshAgentTurnBody('freshcodex', 'codex', 'thread-1', 'turn-1', { revision: 7, cwd: '/repo/worktree', signal })
 
     expect(mockFetch).toHaveBeenNthCalledWith(
       1,
-      '/api/fresh-agent/threads/freshcodex/codex/thread-1?revision=7',
+      '/api/fresh-agent/threads/freshcodex/codex/thread-1?revision=7&cwd=%2Frepo%2Fworktree',
       expect.objectContaining({ signal, headers: expect.any(Headers) }),
     )
     expect(mockFetch).toHaveBeenNthCalledWith(
       2,
-      '/api/fresh-agent/threads/freshcodex/codex/thread-1/turns?revision=7&cursor=cursor-1&limit=20',
+      '/api/fresh-agent/threads/freshcodex/codex/thread-1/turns?revision=7&cursor=cursor-1&cwd=%2Frepo%2Fworktree&limit=20',
       expect.objectContaining({ signal, headers: expect.any(Headers) }),
     )
     expect(mockFetch).toHaveBeenNthCalledWith(
       3,
-      '/api/fresh-agent/threads/freshcodex/codex/thread-1/turns/turn-1?revision=7',
+      '/api/fresh-agent/threads/freshcodex/codex/thread-1/turns/turn-1?revision=7&cwd=%2Frepo%2Fworktree',
       expect.objectContaining({ signal, headers: expect.any(Headers) }),
     )
   })
diff --git a/test/unit/server/fresh-agent/codex-adapter.test.ts b/test/unit/server/fresh-agent/codex-adapter.test.ts
index f2a3d79b6..7525c2372 100644
--- a/test/unit/server/fresh-agent/codex-adapter.test.ts
+++ b/test/unit/server/fresh-agent/codex-adapter.test.ts
@@ -257,6 +257,41 @@ describe('Codex fresh-agent adapter', () => {
     expect(runtime.shutdown).toHaveBeenCalledTimes(1)
   })
 
+  it('lazily resumes a Codex runtime in the saved cwd before reading a persisted thread after server reload', async () => {
+    const runtime = {
+      startThread: vi.fn(),
+      resumeThread: vi.fn().mockResolvedValue({
+        threadId: 'thread-existing-cwd',
+        wsUrl: 'ws://127.0.0.1:43123',
+      }),
+      readThread: vi.fn().mockResolvedValue({
+        thread: makeCodexThread('thread-existing-cwd'),
+      }),
+      listThreadTurns: vi.fn(),
+      readThreadTurn: vi.fn(),
+      shutdown: vi.fn().mockResolvedValue(undefined),
+    }
+    const adapter = createCodexFreshAgentAdapter({ runtimeFactory: vi.fn(() => runtime) as any })
+
+    await expect(adapter.getSnapshot?.({
+      sessionType: 'freshcodex',
+      provider: 'codex',
+      threadId: 'thread-existing-cwd',
+      cwd: '/repo/persisted-worktree',
+    } as any, 7)).resolves.toMatchObject({
+      provider: 'codex',
+      threadId: 'thread-existing-cwd',
+    })
+
+    expect(runtime.resumeThread).toHaveBeenCalledWith({
+      threadId: 'thread-existing-cwd',
+      cwd: '/repo/persisted-worktree',
+    })
+
+    await adapter.shutdown?.()
+    expect(runtime.shutdown).toHaveBeenCalledTimes(1)
+  })
+
   it('dedupes concurrent lazy runtime resumes for the same persisted thread', async () => {
     let resolveResume: ((value: { threadId: string; wsUrl: string }) => void) | undefined
     const resumePromise = new Promise<{ threadId: string; wsUrl: string }>((resolve) => {
diff --git a/test/unit/server/fresh-agent/opencode-serve-adapter.test.ts b/test/unit/server/fresh-agent/opencode-serve-adapter.test.ts
index b35a17685..ce29acc85 100644
--- a/test/unit/server/fresh-agent/opencode-serve-adapter.test.ts
+++ b/test/unit/server/fresh-agent/opencode-serve-adapter.test.ts
@@ -12,14 +12,19 @@ function makeFakeManager() {
     return e
   }
   return {
-    createSession: vi.fn(async () => ({ id: 'ses_real_1', directory: '/repo', title: 'T' })),
+    createSession: vi.fn(async (input?: { directory?: string }) => ({
+      id: 'ses_real_1',
+      ...(input?.directory ? { directory: input.directory } : {}),
+      title: 'T',
+    })),
+    rememberSessionCwd: vi.fn(),
     promptAsync: vi.fn(async () => undefined),
     listMessages: vi.fn(async () => ({ messages: [], nextCursor: null })),
     getMessage: vi.fn(async () => null),
     getSession: vi.fn(async () => ({ id: 'ses_real_1', title: 'T', time: { updated: 5 } })),
     abort: vi.fn(async () => undefined),
     compact: vi.fn(async () => undefined),
-    fork: vi.fn(async () => ({ id: 'ses_child_1' })),
+    fork: vi.fn(async (): Promise<{ id: string; directory?: string }> => ({ id: 'ses_child_1' })),
     onceIdle: vi.fn(async () => undefined),
     subscribe: vi.fn((id: string, listener: (e: unknown) => void) => {
       const e = emitterFor(id)
@@ -57,7 +62,7 @@ describe('OpenCode serve adapter: create + send', () => {
       parts: [{ type: 'text', text: 'reply ok' }],
       model: { providerID: 'umans-ai-coding-plan', modelID: 'umans-kimi-k2.7' },
       variant: 'high',
-    })
+    }, { cwd: '/repo' })
     expect(manager.onceIdle).toHaveBeenCalledWith('ses_real_1', expect.any(Number))
   })
 
@@ -92,6 +97,47 @@ describe('OpenCode serve adapter: create + send', () => {
     await adapter.send?.('freshopencode-cwd-1', { text: 'hi' })
     expect(manager.createSession).toHaveBeenCalledTimes(1)
     expect(manager.createSession).toHaveBeenLastCalledWith({ directory: '/project-x' })
+    expect(manager.promptAsync).toHaveBeenCalledWith(
+      'ses_real_1',
+      expect.objectContaining({ parts: [{ type: 'text', text: 'hi' }] }),
+      { cwd: '/project-x' },
+    )
+  })
+
+  it('passes restored cwd when sending to an attached durable session', async () => {
+    const manager = makeFakeManager()
+    const adapter = makeAdapter(manager)
+
+    await adapter.attach?.({
+      sessionType: 'freshopencode',
+      provider: 'opencode',
+      sessionId: 'ses_attached_send',
+      cwd: '/repo/restored-worktree',
+    })
+    await adapter.send?.('ses_attached_send', { text: 'continue' })
+
+    expect(manager.promptAsync).toHaveBeenCalledWith(
+      'ses_attached_send',
+      { parts: [{ type: 'text', text: 'continue' }] },
+      { cwd: '/repo/restored-worktree' },
+    )
+  })
+
+  it('keeps attached no-cwd sessions sendable without a route argument', async () => {
+    const manager = makeFakeManager()
+    const adapter = makeAdapter(manager)
+
+    await adapter.attach?.({
+      sessionType: 'freshopencode',
+      provider: 'opencode',
+      sessionId: 'ses_attached_nocwd',
+    })
+    await adapter.send?.('ses_attached_nocwd', { text: 'continue' })
+
+    expect(manager.promptAsync).toHaveBeenCalledWith(
+      'ses_attached_nocwd',
+      { parts: [{ type: 'text', text: 'continue' }] },
+    )
   })
 
   it('recovers from a failed send and still processes later sends', async () => {
@@ -156,38 +202,73 @@ describe('OpenCode serve adapter: history reads', () => {
     { info: { id: 'msg_assistant_1', role: 'assistant', providerID: 'umans-ai-coding-plan', modelID: 'umans-kimi-k2.7' }, parts: [{ id: 'p2', type: 'text', text: 'ok' }] },
   ]
 
+  it('remembers cwd when attaching a durable OpenCode session', async () => {
+    const manager = makeFakeManager()
+    const adapter = makeAdapter(manager)
+
+    await adapter.attach?.({
+      sessionType: 'freshopencode',
+      provider: 'opencode',
+      sessionId: 'ses_existing_cwd',
+      cwd: '/repo/from-pane',
+    })
+
+    expect(manager.rememberSessionCwd).toHaveBeenCalledWith('ses_existing_cwd', '/repo/from-pane')
+  })
+
   it('getSnapshot assembles HTTP messages into the normalized transcript', async () => {
     const manager = makeFakeManager()
     manager.getSession = vi.fn(async () => ({ id: 'ses_real_1', title: 'Kimi chat', time: { updated: 12 } }))
     manager.listMessages = vi.fn(async () => ({ messages, nextCursor: null }))
     const adapter = makeAdapter(manager)
-    await adapter.attach?.({ sessionType: 'freshopencode', provider: 'opencode', sessionId: 'ses_real_1' })
+    await adapter.attach?.({ sessionType: 'freshopencode', provider: 'opencode', sessionId: 'ses_real_1', cwd: '/repo/history' })
     await expect(adapter.getSnapshot?.({ sessionType: 'freshopencode', provider: 'opencode', threadId: 'ses_real_1' })).resolves.toMatchObject({
       sessionId: 'ses_real_1', summary: 'Kimi chat', revision: 12,
       turns: [{ turnId: 'msg_user_1', role: 'user', summary: 'reply ok' }, { turnId: 'msg_assistant_1', role: 'assistant', summary: 'ok' }],
     })
-    expect(manager.listMessages).toHaveBeenCalledWith('ses_real_1', { limit: 200 })
+    expect(manager.getSession).toHaveBeenCalledWith('ses_real_1', { cwd: '/repo/history' })
+    expect(manager.listMessages).toHaveBeenCalledWith('ses_real_1', { limit: 200 }, { cwd: '/repo/history' })
+  })
+
+  it('omits history route arguments when no cwd is known', async () => {
+    const manager = makeFakeManager()
+    manager.getSession = vi.fn(async () => ({ id: 'ses_real_1', title: 'Kimi chat', time: { updated: 12 } }))
+    manager.listMessages = vi.fn(async () => ({ messages, nextCursor: null }))
+    manager.getMessage = vi.fn(async () => messages[1])
+    const adapter = makeAdapter(manager)
+
+    await adapter.attach?.({ sessionType: 'freshopencode', provider: 'opencode', sessionId: 'ses_real_1' })
+    await adapter.getSnapshot?.({ sessionType: 'freshopencode', provider: 'opencode', threadId: 'ses_real_1' })
+    await adapter.getTurnPage?.({ sessionType: 'freshopencode', provider: 'opencode', threadId: 'ses_real_1' }, { limit: 1, revision: 0 })
+    await adapter.getTurnBody?.({ sessionType: 'freshopencode', provider: 'opencode', threadId: 'ses_real_1', turnId: 'msg_assistant_1' }, 12)
+
+    expect(manager.getSession).toHaveBeenNthCalledWith(1, 'ses_real_1')
+    expect(manager.getSession).toHaveBeenNthCalledWith(2, 'ses_real_1')
+    expect(manager.listMessages).toHaveBeenNthCalledWith(1, 'ses_real_1', { limit: 200 })
+    expect(manager.listMessages).toHaveBeenNthCalledWith(2, 'ses_real_1', { limit: 1, before: undefined })
+    expect(manager.getMessage).toHaveBeenCalledWith('ses_real_1', 'msg_assistant_1')
   })
 
   it('getTurnPage forwards cursor as before= and returns nextCursor from the header', async () => {
     const manager = makeFakeManager()
     manager.listMessages = vi.fn(async () => ({ messages: messages.slice(0, 1), nextCursor: 'NEXT' }))
     const adapter = makeAdapter(manager)
-    await adapter.attach?.({ sessionType: 'freshopencode', provider: 'opencode', sessionId: 'ses_real_1' })
+    await adapter.attach?.({ sessionType: 'freshopencode', provider: 'opencode', sessionId: 'ses_real_1', cwd: '/repo/history' })
     const page = await adapter.getTurnPage?.({ sessionType: 'freshopencode', provider: 'opencode', threadId: 'ses_real_1' }, { cursor: 'CUR', limit: 1, revision: 0 })
     expect(page).toMatchObject({ nextCursor: 'NEXT', turns: [{ turnId: 'msg_user_1' }] })
-    expect(manager.listMessages).toHaveBeenCalledWith('ses_real_1', { limit: 1, before: 'CUR' })
+    expect(manager.getSession).toHaveBeenCalledWith('ses_real_1', { cwd: '/repo/history' })
+    expect(manager.listMessages).toHaveBeenCalledWith('ses_real_1', { limit: 1, before: 'CUR' }, { cwd: '/repo/history' })
   })
 
   it('getTurnBody fetches a single message and normalizes it', async () => {
     const manager = makeFakeManager()
     manager.getMessage = vi.fn(async () => messages[1])
     const adapter = makeAdapter(manager)
-    await adapter.attach?.({ sessionType: 'freshopencode', provider: 'opencode', sessionId: 'ses_real_1' })
+    await adapter.attach?.({ sessionType: 'freshopencode', provider: 'opencode', sessionId: 'ses_real_1', cwd: '/repo/history' })
     await expect(adapter.getTurnBody?.({ sessionType: 'freshopencode', provider: 'opencode', threadId: 'ses_real_1', turnId: 'msg_assistant_1' }, 12)).resolves.toMatchObject({
       turnId: 'msg_assistant_1', role: 'assistant', items: expect.arrayContaining([expect.objectContaining({ kind: 'text', text: 'ok' })]),
     })
-    expect(manager.getMessage).toHaveBeenCalledWith('ses_real_1', 'msg_assistant_1')
+    expect(manager.getMessage).toHaveBeenCalledWith('ses_real_1', 'msg_assistant_1', { cwd: '/repo/history' })
   })
 
   it('reports fork capability true and approvals/questions false', async () => {
@@ -195,7 +276,7 @@ describe('OpenCode serve adapter: history reads', () => {
     manager.getSession = vi.fn(async () => ({ id: 'ses_real_1', time: { updated: 1 } }))
     manager.listMessages = vi.fn(async () => ({ messages: [], nextCursor: null }))
     const adapter = makeAdapter(manager)
-    await adapter.attach?.({ sessionType: 'freshopencode', provider: 'opencode', sessionId: 'ses_real_1' })
+    await adapter.attach?.({ sessionType: 'freshopencode', provider: 'opencode', sessionId: 'ses_real_1', cwd: '/repo/history' })
     const snap: any = await adapter.getSnapshot?.({ sessionType: 'freshopencode', provider: 'opencode', threadId: 'ses_real_1' })
     expect(snap.capabilities).toMatchObject({ fork: true, approvals: false, questions: false })
   })
@@ -239,6 +320,61 @@ describe('OpenCode serve adapter: control', () => {
     }
   })
 
+  it('routes control operations through the known cwd', async () => {
+    const manager = makeFakeManager()
+    const adapter = makeAdapter(manager)
+
+    await adapter.attach?.({
+      sessionType: 'freshopencode',
+      provider: 'opencode',
+      sessionId: 'ses_known_cwd',
+      cwd: '/repo/control',
+    })
+
+    await adapter.interrupt?.('ses_known_cwd')
+    await adapter.compact?.('ses_known_cwd', { instructions: 'trim' })
+    await expect(adapter.fork?.('ses_known_cwd')).resolves.toEqual({
+      sessionId: 'ses_child_1',
+      sessionRef: { provider: 'opencode', sessionId: 'ses_child_1' },
+    })
+    await adapter.send?.('ses_child_1', { text: 'child continue' })
+
+    expect(manager.abort).toHaveBeenCalledWith('ses_known_cwd', { cwd: '/repo/control' })
+    expect(manager.compact).toHaveBeenCalledWith('ses_known_cwd', { instructions: 'trim' }, { cwd: '/repo/control' })
+    expect(manager.fork).toHaveBeenCalledWith('ses_known_cwd', { cwd: '/repo/control' })
+    expect(manager.promptAsync).toHaveBeenCalledWith(
+      'ses_child_1',
+      expect.objectContaining({ parts: [{ type: 'text', text: 'child continue' }] }),
+      { cwd: '/repo/control' },
+    )
+  })
+
+  it('routes forked children through the returned child directory when present', async () => {
+    const manager = makeFakeManager()
+    manager.fork.mockResolvedValueOnce({ id: 'ses_child_1', directory: '/repo/child' })
+    const adapter = makeAdapter(manager)
+
+    await adapter.attach?.({
+      sessionType: 'freshopencode',
+      provider: 'opencode',
+      sessionId: 'ses_parent',
+      cwd: '/repo/parent',
+    })
+
+    await expect(adapter.fork?.('ses_parent')).resolves.toEqual({
+      sessionId: 'ses_child_1',
+      sessionRef: { provider: 'opencode', sessionId: 'ses_child_1' },
+    })
+    await adapter.send?.('ses_child_1', { text: 'child turn' })
+
+    expect(manager.fork).toHaveBeenCalledWith('ses_parent', { cwd: '/repo/parent' })
+    expect(manager.promptAsync).toHaveBeenCalledWith(
+      'ses_child_1',
+      expect.objectContaining({ parts: [{ type: 'text', text: 'child turn' }] }),
+      { cwd: '/repo/child' },
+    )
+  })
+
   it('shutdown delegates to the serve manager', async () => {
     const { manager, adapter } = await materialized()
     await adapter.shutdown?.()
diff --git a/test/unit/server/fresh-agent/opencode-serve-manager.test.ts b/test/unit/server/fresh-agent/opencode-serve-manager.test.ts
index 113f32746..d3c940289 100644
--- a/test/unit/server/fresh-agent/opencode-serve-manager.test.ts
+++ b/test/unit/server/fresh-agent/opencode-serve-manager.test.ts
@@ -58,6 +58,83 @@ describe('OpencodeServeManager lifecycle', () => {
     expect(fetchFn).toHaveBeenCalledWith('http://127.0.0.1:47999/global/health', expect.anything())
   })
 
+  it('starts the serve process in the requested session directory before creating the first session', async () => {
+    const calls: Array<{ url: string; init: any }> = []
+    const fetchFn = vi.fn(async (url: string, init: any) => {
+      calls.push({ url, init })
+      if (url.endsWith('/global/health')) return jsonResponse({ healthy: true, version: '1.17.8' })
+      if (url.endsWith('/session') && init?.method === 'POST') {
+        return jsonResponse({ id: 'ses_project_x', directory: '/project-x', title: 'Project X' })
+      }
+      return jsonResponse({})
+    })
+    const { manager, spawnFn } = makeManager({ fetchFn: fetchFn as any })
+
+    const session = await manager.createSession({ directory: '/project-x' })
+
+    expect(session).toMatchObject({ id: 'ses_project_x', directory: '/project-x' })
+    expect(spawnFn).toHaveBeenCalledWith(
+      'opencode',
+      ['serve', '--hostname', '127.0.0.1', '--port', '47999'],
+      expect.objectContaining({
+        cwd: '/project-x',
+        env: expect.objectContaining({ FRESHELL_OPENCODE_SIDECAR_ID: expect.any(String) }),
+      }),
+    )
+    expect(calls.find((call) => call.url.endsWith('/session'))).toMatchObject({
+      url: 'http://127.0.0.1:47999/session',
+      init: expect.objectContaining({
+        method: 'POST',
+        body: JSON.stringify({ directory: '/project-x' }),
+      }),
+    })
+  })
+
+  it('uses separate serve processes for sessions created in different directories', async () => {
+    const childA = fakeChild()
+    const childB = fakeChild()
+    const spawnFn = vi.fn()
+      .mockReturnValueOnce(childA)
+      .mockReturnValueOnce(childB)
+    const fetchFn = vi.fn(async (url: string, init: any) => {
+      if (url === 'http://127.0.0.1:47999/global/health') return jsonResponse({ healthy: true })
+      if (url === 'http://127.0.0.1:48000/global/health') return jsonResponse({ healthy: true })
+      if (url === 'http://127.0.0.1:47999/session' && init?.method === 'POST') {
+        return jsonResponse({ id: 'ses_a', directory: '/project-a' })
+      }
+      if (url === 'http://127.0.0.1:48000/session' && init?.method === 'POST') {
+        return jsonResponse({ id: 'ses_b', directory: '/project-b' })
+      }
+      return jsonResponse({})
+    })
+    const manager = new OpencodeServeManager({
+      spawnFn: spawnFn as any,
+      fetchFn: fetchFn as any,
+      allocatePort: vi.fn()
+        .mockResolvedValueOnce({ hostname: '127.0.0.1', port: 47999 })
+        .mockResolvedValueOnce({ hostname: '127.0.0.1', port: 48000 }),
+      connectEventStream: () => () => {},
+      healthTimeoutMs: 1000,
+    })
+
+    await expect(manager.createSession({ directory: '/project-a' })).resolves.toMatchObject({ id: 'ses_a' })
+    await expect(manager.createSession({ directory: '/project-b' })).resolves.toMatchObject({ id: 'ses_b' })
+
+    expect(spawnFn).toHaveBeenCalledTimes(2)
+    expect(spawnFn).toHaveBeenNthCalledWith(
+      1,
+      'opencode',
+      ['serve', '--hostname', '127.0.0.1', '--port', '47999'],
+      expect.objectContaining({ cwd: '/project-a' }),
+    )
+    expect(spawnFn).toHaveBeenNthCalledWith(
+      2,
+      'opencode',
+      ['serve', '--hostname', '127.0.0.1', '--port', '48000'],
+      expect.objectContaining({ cwd: '/project-b' }),
+    )
+  })
+
   it('shuts down by killing the spawned process and refuses further use until restarted', async () => {
     const { manager, child } = makeManager()
     await manager.ensureStarted()
@@ -99,8 +176,8 @@ describe('OpencodeServeManager lifecycle', () => {
     await expect(started).rejects.toThrow(/opencode serve startup was aborted|opencode serve did not become healthy/)
     await shutdown
     expect(child.kill).toHaveBeenCalled()
-    expect((manager as any).running).toBeUndefined()
-    expect((manager as any).startPromise).toBeUndefined()
+    expect((manager as any).runningByCwd.size).toBe(0)
+    expect((manager as any).startPromiseByCwd.size).toBe(0)
   })
 })
 
@@ -182,6 +259,214 @@ describe('OpencodeServeManager HTTP client', () => {
     const { manager } = makeManager({ fetchFn: fetchFn as any })
     await expect(manager.getMessage('ses_x', 'broken')).rejects.toThrow(/opencode serve GET .*\/message\/broken → 500/)
   })
+
+  it('posts summarize requests to a cwd sidecar learned from getSession', async () => {
+    const calls: Array<{ url: string; init: any }> = []
+    const childDefault = fakeChild()
+    const childProject = fakeChild()
+    const spawnFn = vi.fn()
+      .mockReturnValueOnce(childDefault)
+      .mockReturnValueOnce(childProject)
+    const fetchFn = vi.fn(async (url: string, init: any) => {
+      calls.push({ url, init })
+      if (url === 'http://127.0.0.1:47999/global/health') return jsonResponse({ healthy: true })
+      if (url === 'http://127.0.0.1:47999/session/ses_known' && init?.method === 'GET') {
+        return jsonResponse({ id: 'ses_known', directory: '/project-a', title: 'Known' })
+      }
+      if (url === 'http://127.0.0.1:47999/session/ses_known/compact' && init?.method === 'POST') {
+        return jsonResponse({}, { status: 204 })
+      }
+      if (url === 'http://127.0.0.1:48000/global/health') return jsonResponse({ healthy: true })
+      if (url === 'http://127.0.0.1:48000/session/ses_known/summarize' && init?.method === 'POST') {
+        return jsonResponse({}, { status: 204 })
+      }
+      return jsonResponse({}, { status: 404 })
+    })
+    const manager = new OpencodeServeManager({
+      spawnFn: spawnFn as any,
+      fetchFn: fetchFn as any,
+      allocatePort: vi.fn()
+        .mockResolvedValueOnce({ hostname: '127.0.0.1', port: 47999 })
+        .mockResolvedValueOnce({ hostname: '127.0.0.1', port: 48000 }),
+      connectEventStream: () => () => {},
+      healthTimeoutMs: 1000,
+    })
+
+    await expect(manager.getSession('ses_known')).resolves.toMatchObject({ id: 'ses_known', directory: '/project-a' })
+    await manager.compact('ses_known', { instructions: 'keep it short' })
+
+    expect(spawnFn).toHaveBeenCalledTimes(2)
+    expect(spawnFn.mock.calls[0]?.[2]).not.toHaveProperty('cwd')
+    expect(spawnFn).toHaveBeenNthCalledWith(
+      2,
+      'opencode',
+      ['serve', '--hostname', '127.0.0.1', '--port', '48000'],
+      expect.objectContaining({ cwd: '/project-a' }),
+    )
+    expect(calls.find((call) => call.url.endsWith('/summarize'))).toMatchObject({
+      url: 'http://127.0.0.1:48000/session/ses_known/summarize',
+      init: expect.objectContaining({
+        method: 'POST',
+        body: JSON.stringify({ instructions: 'keep it short' }),
+      }),
+    })
+    expect(calls.some((call) => call.url.endsWith('/compact'))).toBe(false)
+  })
+
+  it('remembers the forked child directory for later requests instead of keeping the parent route', async () => {
+    const calls: Array<{ url: string; init: any }> = []
+    const childDefault = fakeChild()
+    const childParent = fakeChild()
+    const childFork = fakeChild()
+    const spawnFn = vi.fn()
+      .mockReturnValueOnce(childDefault)
+      .mockReturnValueOnce(childParent)
+      .mockReturnValueOnce(childFork)
+    const fetchFn = vi.fn(async (url: string, init: any) => {
+      calls.push({ url, init })
+      if (url === 'http://127.0.0.1:47999/global/health') return jsonResponse({ healthy: true })
+      if (url === 'http://127.0.0.1:47999/session/ses_parent' && init?.method === 'GET') {
+        return jsonResponse({ id: 'ses_parent', directory: '/parent' })
+      }
+      if (url === 'http://127.0.0.1:47999/session/ses_parent/fork' && init?.method === 'POST') {
+        return jsonResponse({ id: 'ses_child', directory: '/child' })
+      }
+      if (url === 'http://127.0.0.1:47999/session/ses_child/compact' && init?.method === 'POST') {
+        return jsonResponse({}, { status: 204 })
+      }
+      if (url === 'http://127.0.0.1:48000/global/health') return jsonResponse({ healthy: true })
+      if (url === 'http://127.0.0.1:48000/session/ses_parent/fork' && init?.method === 'POST') {
+        return jsonResponse({ id: 'ses_child', directory: '/child' })
+      }
+      if (url === 'http://127.0.0.1:48001/global/health') return jsonResponse({ healthy: true })
+      if (url === 'http://127.0.0.1:48001/session/ses_child/summarize' && init?.method === 'POST') {
+        return jsonResponse({}, { status: 204 })
+      }
+      return jsonResponse({}, { status: 404 })
+    })
+    const manager = new OpencodeServeManager({
+      spawnFn: spawnFn as any,
+      fetchFn: fetchFn as any,
+      allocatePort: vi.fn()
+        .mockResolvedValueOnce({ hostname: '127.0.0.1', port: 47999 })
+        .mockResolvedValueOnce({ hostname: '127.0.0.1', port: 48000 })
+        .mockResolvedValueOnce({ hostname: '127.0.0.1', port: 48001 }),
+      connectEventStream: () => () => {},
+      healthTimeoutMs: 1000,
+    })
+
+    await expect(manager.getSession('ses_parent')).resolves.toMatchObject({ id: 'ses_parent', directory: '/parent' })
+    await expect(manager.fork('ses_parent')).resolves.toMatchObject({ id: 'ses_child', directory: '/child' })
+    await manager.compact('ses_child', { instructions: 'child summary' })
+
+    expect(spawnFn).toHaveBeenCalledTimes(3)
+    expect(spawnFn).toHaveBeenNthCalledWith(
+      2,
+      'opencode',
+      ['serve', '--hostname', '127.0.0.1', '--port', '48000'],
+      expect.objectContaining({ cwd: '/parent' }),
+    )
+    expect(spawnFn).toHaveBeenNthCalledWith(
+      3,
+      'opencode',
+      ['serve', '--hostname', '127.0.0.1', '--port', '48001'],
+      expect.objectContaining({ cwd: '/child' }),
+    )
+    expect(calls.find((call) => call.url.endsWith('/session/ses_child/summarize'))).toMatchObject({
+      url: 'http://127.0.0.1:48001/session/ses_child/summarize',
+      init: expect.objectContaining({
+        method: 'POST',
+        body: JSON.stringify({ instructions: 'child summary' }),
+      }),
+    })
+  })
+
+  it('falls back to the fork route cwd when the fork response omits directory', async () => {
+    const calls: Array<{ url: string; init: any }> = []
+    const childParent = fakeChild()
+    const spawnFn = vi.fn().mockReturnValueOnce(childParent)
+    const fetchFn = vi.fn(async (url: string, init: any) => {
+      calls.push({ url, init })
+      if (url === 'http://127.0.0.1:47999/global/health') return jsonResponse({ healthy: true })
+      if (url === 'http://127.0.0.1:47999/session/ses_parent/fork' && init?.method === 'POST') {
+        return jsonResponse({ id: 'ses_child' })
+      }
+      if (url === 'http://127.0.0.1:47999/session/ses_child/summarize' && init?.method === 'POST') {
+        return jsonResponse({}, { status: 204 })
+      }
+      if (url.includes('/session/ses_child/summarize')) {
+        throw new Error(`child summarize should stay on parent cwd route, got ${url}`)
+      }
+      return jsonResponse({}, { status: 404 })
+    })
+    const manager = new OpencodeServeManager({
+      spawnFn: spawnFn as any,
+      fetchFn: fetchFn as any,
+      allocatePort: vi.fn()
+        .mockResolvedValueOnce({ hostname: '127.0.0.1', port: 47999 }),
+      connectEventStream: () => () => {},
+      healthTimeoutMs: 1000,
+    })
+
+    await expect(manager.fork('ses_parent', { cwd: '/parent' })).resolves.toMatchObject({ id: 'ses_child' })
+    await manager.compact('ses_child', { instructions: 'child summary' })
+
+    expect(spawnFn).toHaveBeenCalledTimes(1)
+    expect(spawnFn).toHaveBeenCalledWith(
+      'opencode',
+      ['serve', '--hostname', '127.0.0.1', '--port', '47999'],
+      expect.objectContaining({ cwd: '/parent' }),
+    )
+    expect(calls.find((call) => call.url.endsWith('/session/ses_child/summarize'))).toMatchObject({
+      url: 'http://127.0.0.1:47999/session/ses_child/summarize',
+      init: expect.objectContaining({ method: 'POST' }),
+    })
+  })
+
+  it('uses the default serve route for unknown existing sessions even after cwd sidecars exist', async () => {
+    const childProject = fakeChild()
+    const childDefault = fakeChild()
+    const spawnFn = vi.fn()
+      .mockReturnValueOnce(childProject)
+      .mockReturnValueOnce(childDefault)
+    const fetchFn = vi.fn(async (url: string, init: any) => {
+      if (url === 'http://127.0.0.1:48000/global/health') return jsonResponse({ healthy: true })
+      if (url === 'http://127.0.0.1:48000/session' && init?.method === 'POST') {
+        return jsonResponse({ id: 'ses_project', directory: '/project-a' })
+      }
+      if (url === 'http://127.0.0.1:48000/session/ses_unknown' && init?.method === 'GET') {
+        throw new Error('unknown session lookup must not hit cwd sidecar')
+      }
+      if (url === 'http://127.0.0.1:47999/global/health') return jsonResponse({ healthy: true })
+      if (url === 'http://127.0.0.1:47999/session/ses_unknown' && init?.method === 'GET') {
+        return jsonResponse({ id: 'ses_unknown', title: 'Unknown' })
+      }
+      return jsonResponse({}, { status: 404 })
+    })
+    const manager = new OpencodeServeManager({
+      spawnFn: spawnFn as any,
+      fetchFn: fetchFn as any,
+      allocatePort: vi.fn()
+        .mockResolvedValueOnce({ hostname: '127.0.0.1', port: 48000 })
+        .mockResolvedValueOnce({ hostname: '127.0.0.1', port: 47999 }),
+      connectEventStream: () => () => {},
+      healthTimeoutMs: 1000,
+    })
+
+    await expect(manager.createSession({ directory: '/project-a' })).resolves.toMatchObject({ id: 'ses_project' })
+    await expect(manager.getSession('ses_unknown')).resolves.toMatchObject({ id: 'ses_unknown' })
+
+    expect(spawnFn).toHaveBeenCalledTimes(2)
+    expect(spawnFn).toHaveBeenNthCalledWith(
+      1,
+      'opencode',
+      ['serve', '--hostname', '127.0.0.1', '--port', '48000'],
+      expect.objectContaining({ cwd: '/project-a' }),
+    )
+    expect(spawnFn.mock.calls[1]?.[2]).not.toHaveProperty('cwd')
+    expect(fetchFn).not.toHaveBeenCalledWith('http://127.0.0.1:48000/session/ses_unknown', expect.anything())
+    expect(fetchFn).toHaveBeenCalledWith('http://127.0.0.1:47999/session/ses_unknown', expect.anything())
+  })
 })
 
 describe('OpencodeServeManager fan-out', () => {
@@ -290,7 +575,142 @@ describe('OpencodeServeManager fan-out', () => {
     expect(stopStream).toHaveBeenCalled()
     expect(child.kill).toHaveBeenCalled()
     expect((manager as any).sessionEmitters.size).toBe(0)
-    expect((manager as any).running).toBeUndefined()
+    expect((manager as any).runningByCwd.size).toBe(0)
+  })
+
+  it('default sidecar close clears unmapped emitters but preserves mapped cwd sessions', async () => {
+    const childDefault = fakeChild()
+    const childProject = fakeChild()
+    const spawnFn = vi.fn()
+      .mockReturnValueOnce(childDefault)
+      .mockReturnValueOnce(childProject)
+    const fetchFn = vi.fn(async (url: string, init: any) => {
+      if (url === 'http://127.0.0.1:47999/global/health') return jsonResponse({ healthy: true })
+      if (url === 'http://127.0.0.1:47999/session/ses_project' && init?.method === 'GET') {
+        return jsonResponse({ id: 'ses_project', directory: '/project-a' })
+      }
+      if (url === 'http://127.0.0.1:47999/session/ses_project/compact' && init?.method === 'POST') {
+        return jsonResponse({}, { status: 204 })
+      }
+      if (url === 'http://127.0.0.1:48000/global/health') return jsonResponse({ healthy: true })
+      if (url === 'http://127.0.0.1:48000/session/ses_project/summarize' && init?.method === 'POST') {
+        return jsonResponse({}, { status: 204 })
+      }
+      return jsonResponse({}, { status: 404 })
+    })
+    const manager = new OpencodeServeManager({
+      spawnFn: spawnFn as any,
+      fetchFn: fetchFn as any,
+      allocatePort: vi.fn()
+        .mockResolvedValueOnce({ hostname: '127.0.0.1', port: 47999 })
+        .mockResolvedValueOnce({ hostname: '127.0.0.1', port: 48000 }),
+      connectEventStream: () => () => {},
+      healthTimeoutMs: 1000,
+    })
+
+    await manager.ensureStarted()
+    manager.subscribe('ses_default', () => {})
+    await manager.getSession('ses_project')
+    await manager.compact('ses_project')
+    manager.subscribe('ses_project', () => {})
+    expect(spawnFn).toHaveBeenCalledTimes(2)
+
+    childDefault.emit('close', 1)
+
+    expect((manager as any).sessionEmitters.has('ses_default')).toBe(false)
+    expect((manager as any).sessionEmitters.has('ses_project')).toBe(true)
+  })
+
+  it('non-default sidecar close removes its mapped emitter and preserves unrelated default emitters', async () => {
+    const childDefault = fakeChild()
+    const childProject = fakeChild()
+    const spawnFn = vi.fn()
+      .mockReturnValueOnce(childDefault)
+      .mockReturnValueOnce(childProject)
+    const fetchFn = vi.fn(async (url: string, init: any) => {
+      if (url === 'http://127.0.0.1:47999/global/health') return jsonResponse({ healthy: true })
+      if (url === 'http://127.0.0.1:47999/session/ses_project' && init?.method === 'GET') {
+        return jsonResponse({ id: 'ses_project', directory: '/project-a' })
+      }
+      if (url === 'http://127.0.0.1:47999/session/ses_project/compact' && init?.method === 'POST') {
+        return jsonResponse({}, { status: 204 })
+      }
+      if (url === 'http://127.0.0.1:48000/global/health') return jsonResponse({ healthy: true })
+      if (url === 'http://127.0.0.1:48000/session/ses_project/summarize' && init?.method === 'POST') {
+        return jsonResponse({}, { status: 204 })
+      }
+      return jsonResponse({}, { status: 404 })
+    })
+    const manager = new OpencodeServeManager({
+      spawnFn: spawnFn as any,
+      fetchFn: fetchFn as any,
+      allocatePort: vi.fn()
+        .mockResolvedValueOnce({ hostname: '127.0.0.1', port: 47999 })
+        .mockResolvedValueOnce({ hostname: '127.0.0.1', port: 48000 }),
+      connectEventStream: () => () => {},
+      healthTimeoutMs: 1000,
+    })
+
+    await manager.ensureStarted()
+    manager.subscribe('ses_default', () => {})
+    await manager.getSession('ses_project')
+    await manager.compact('ses_project')
+    manager.subscribe('ses_project', () => {})
+    expect(spawnFn).toHaveBeenCalledTimes(2)
+    expect((manager as any).sessionEmitters.has('ses_default')).toBe(true)
+    expect((manager as any).sessionEmitters.has('ses_project')).toBe(true)
+
+    childProject.emit('close', 1)
+
+    expect((manager as any).sessionEmitters.has('ses_project')).toBe(false)
+    expect((manager as any).sessionEmitters.has('ses_default')).toBe(true)
+  })
+
+  it('idles out cwd sidecars without stopping the default serve', async () => {
+    vi.useFakeTimers()
+    try {
+      const childDefault = fakeChild()
+      const childProject = fakeChild()
+      const spawnFn = vi.fn()
+        .mockReturnValueOnce(childDefault)
+        .mockReturnValueOnce(childProject)
+      const fetchFn = vi.fn(async (url: string, init: any) => {
+        if (url === 'http://127.0.0.1:47999/global/health') return jsonResponse({ healthy: true })
+        if (url === 'http://127.0.0.1:47999/session/ses_project' && init?.method === 'GET') {
+          return jsonResponse({ id: 'ses_project', directory: '/project-a' })
+        }
+        if (url === 'http://127.0.0.1:47999/session/ses_project/compact' && init?.method === 'POST') {
+          return jsonResponse({}, { status: 204 })
+        }
+        if (url === 'http://127.0.0.1:48000/global/health') return jsonResponse({ healthy: true })
+        if (url === 'http://127.0.0.1:48000/session/ses_project/summarize' && init?.method === 'POST') {
+          return jsonResponse({}, { status: 204 })
+        }
+        return jsonResponse({}, { status: 404 })
+      })
+      const manager = new OpencodeServeManager({
+        spawnFn: spawnFn as any,
+        fetchFn: fetchFn as any,
+        allocatePort: vi.fn()
+          .mockResolvedValueOnce({ hostname: '127.0.0.1', port: 47999 })
+          .mockResolvedValueOnce({ hostname: '127.0.0.1', port: 48000 }),
+        connectEventStream: () => () => {},
+        healthTimeoutMs: 1000,
+        idleShutdownMs: 50,
+      } as any)
+
+      await manager.ensureStarted()
+      await manager.getSession('ses_project')
+      await manager.compact('ses_project')
+      expect(spawnFn).toHaveBeenCalledTimes(2)
+
+      await vi.advanceTimersByTimeAsync(51)
+
+      expect(childProject.kill).toHaveBeenCalled()
+      expect(childDefault.kill).not.toHaveBeenCalled()
+    } finally {
+      vi.useRealTimers()
+    }
   })
 
   it('parses multi-line SSE data blocks by joining data: lines', async () => {
diff --git a/test/unit/server/ws-handler-fresh-agent.test.ts b/test/unit/server/ws-handler-fresh-agent.test.ts
index a82e06264..7a0461f66 100644
--- a/test/unit/server/ws-handler-fresh-agent.test.ts
+++ b/test/unit/server/ws-handler-fresh-agent.test.ts
@@ -670,6 +670,7 @@ describe('WsHandler fresh-agent routing', () => {
         sessionType: 'freshclaude',
         provider: 'claude',
         resumeSessionId: 'cli-session-attached',
+        cwd: '/repo/restored-worktree',
       }))
 
       await vi.waitFor(() => {
@@ -677,14 +678,25 @@ describe('WsHandler fresh-agent routing', () => {
           sessionId: 'claude-session-attached',
           sessionType: 'freshclaude',
           provider: 'claude',
+          cwd: '/repo/restored-worktree',
         })
         expect(runtimeManager.subscribe).toHaveBeenCalledWith(
-          { sessionId: 'claude-session-attached', sessionType: 'freshclaude', provider: 'claude' },
+          {
+            sessionId: 'claude-session-attached',
+            sessionType: 'freshclaude',
+            provider: 'claude',
+            cwd: '/repo/restored-worktree',
+          },
           expect.any(Function),
         )
       })
 
-      listeners.get(JSON.stringify({ sessionId: 'claude-session-attached', sessionType: 'freshclaude', provider: 'claude' }))?.({ kind: 'thread.updated', revision: 2 })
+      listeners.get(JSON.stringify({
+        sessionId: 'claude-session-attached',
+        sessionType: 'freshclaude',
+        provider: 'claude',
+        cwd: '/repo/restored-worktree',
+      }))?.({ kind: 'thread.updated', revision: 2 })
 
       await vi.waitFor(() => {
         expect(seenMessages).toContainEqual({

From 8c68ff483d1686e6562a2bf996c3d43f4857278b Mon Sep 17 00:00:00 2001
From: Codex <codex@openai.com>
Date: Fri, 19 Jun 2026 00:06:09 -0700
Subject: [PATCH 12/33] fix: stop opencode transcript updates marking fresh
 agent busy

---
 .../adapters/opencode/serve-events.ts         | 37 ++++++++----
 server/fresh-agent/sdk-events.ts              |  7 +++
 src/lib/fresh-agent-ws.ts                     |  2 +
 test/unit/client/lib/fresh-agent-ws.test.ts   | 38 ++++++++++++
 .../fresh-agent/opencode-serve-events.test.ts | 58 ++++++++++++++++++-
 5 files changed, 129 insertions(+), 13 deletions(-)

diff --git a/server/fresh-agent/adapters/opencode/serve-events.ts b/server/fresh-agent/adapters/opencode/serve-events.ts
index 61283fbcc..3c647e3c4 100644
--- a/server/fresh-agent/adapters/opencode/serve-events.ts
+++ b/server/fresh-agent/adapters/opencode/serve-events.ts
@@ -45,32 +45,47 @@ export function parseServeEvent(event: unknown): ParsedServeEvent | null {
 
 export type SdkProviderEvent =
   | { type: 'sdk.session.snapshot'; sessionId: string; status: 'running' | 'idle' }
+  | { type: 'sdk.session.changed'; sessionId: string; reason: 'opencode-message' | 'opencode-status' }
   | { type: 'sdk.error'; sessionId: string; message: string }
 
+function opencodeStatusToSnapshotStatus(statusType: string | undefined): 'running' | 'idle' | undefined {
+  switch (statusType) {
+    case 'busy':
+    case 'retry':
+      return 'running'
+    case 'idle':
+      return 'idle'
+    default:
+      return undefined
+  }
+}
+
+function isOpencodeTranscriptEvent(kind: string): boolean {
+  return kind.startsWith('message.')
+}
+
 /** Map a parsed serve event to the `sdk.*` provider event the existing client
- * slice already understands. We deliberately collapse fine-grained part events
- * into a `running` snapshot: the client re-polls the HTTP transcript on every
- * `freshAgent.event`, so this yields live (per-assistant-message) updates with
- * zero client change. `subscribedId` is the id the listener subscribed with
- * (placeholder before materialization, durable `ses_` after). */
+ * slice already understands. Transcript events are invalidations, not lifecycle
+ * state: OpenCode can emit trailing message metadata after a turn is already
+ * idle, and mapping those updates to `running` leaves freshopencode bouncing. */
 export function serveEventToSdk(parsed: ParsedServeEvent, subscribedId: string): SdkProviderEvent | null {
   const props = parsed.properties
   switch (parsed.kind) {
     case 'session.idle':
       return { type: 'sdk.session.snapshot', sessionId: subscribedId, status: 'idle' }
     case 'session.status': {
-      const statusType = stringProperty(props.status, 'type')
-      return { type: 'sdk.session.snapshot', sessionId: subscribedId, status: statusType === 'idle' ? 'idle' : 'running' }
+      const status = opencodeStatusToSnapshotStatus(stringProperty(props.status, 'type'))
+      if (status) return { type: 'sdk.session.snapshot', sessionId: subscribedId, status }
+      return { type: 'sdk.session.changed', sessionId: subscribedId, reason: 'opencode-status' }
     }
-    case 'message.part.delta':
-    case 'message.part.updated':
-    case 'message.updated':
-      return { type: 'sdk.session.snapshot', sessionId: subscribedId, status: 'running' }
     case 'session.error': {
       const message = stringProperty(props.error, 'message') ?? 'OpenCode session error'
       return { type: 'sdk.error', sessionId: subscribedId, message }
     }
     default:
+      if (isOpencodeTranscriptEvent(parsed.kind)) {
+        return { type: 'sdk.session.changed', sessionId: subscribedId, reason: 'opencode-message' }
+      }
       return null
   }
 }
diff --git a/server/fresh-agent/sdk-events.ts b/server/fresh-agent/sdk-events.ts
index 9a097faca..d8909ee62 100644
--- a/server/fresh-agent/sdk-events.ts
+++ b/server/fresh-agent/sdk-events.ts
@@ -12,6 +12,11 @@ export type FreshAgentProviderEvent =
     streamingActive?: boolean
     streamingText?: string
   }
+  | {
+    type: 'freshAgent.session.changed'
+    sessionId: string
+    reason?: string
+  }
   | { type: 'freshAgent.session.init'; sessionId: string; cliSessionId?: string; model?: string; cwd?: string; tools?: Array<{ name: string }> }
   | { type: 'freshAgent.session.metadata'; sessionId: string; cliSessionId?: string; model?: string; cwd?: string; tools?: Array<{ name: string }> }
   | { type: 'freshAgent.assistant'; sessionId: string; content: ContentBlock[]; model?: string; usage?: Usage }
@@ -35,6 +40,8 @@ export function normalizeFreshAgentProviderEvent(event: unknown): unknown {
   switch (typed.type) {
     case 'sdk.session.snapshot':
       return { ...providerEvent, type: 'freshAgent.session.snapshot' } as FreshAgentProviderEvent
+    case 'sdk.session.changed':
+      return { ...providerEvent, type: 'freshAgent.session.changed' } as FreshAgentProviderEvent
     case 'sdk.session.init':
       return { ...providerEvent, type: 'freshAgent.session.init' } as FreshAgentProviderEvent
     case 'sdk.session.metadata':
diff --git a/src/lib/fresh-agent-ws.ts b/src/lib/fresh-agent-ws.ts
index 83f48a703..ca5781acd 100644
--- a/src/lib/fresh-agent-ws.ts
+++ b/src/lib/fresh-agent-ws.ts
@@ -172,6 +172,8 @@ export function handleFreshAgentTransportEvent(dispatch: AppDispatch, msg: Fresh
         streamingText: event.streamingText as string | undefined,
       }))
       return true
+    case 'freshAgent.session.changed':
+      return true
     case 'freshAgent.session.init':
       dispatch(sessionInit({
         ...locator,
diff --git a/test/unit/client/lib/fresh-agent-ws.test.ts b/test/unit/client/lib/fresh-agent-ws.test.ts
index 4838a8a0b..20bdc1a4e 100644
--- a/test/unit/client/lib/fresh-agent-ws.test.ts
+++ b/test/unit/client/lib/fresh-agent-ws.test.ts
@@ -225,6 +225,44 @@ describe('fresh-agent-ws', () => {
     expect(store.getState().freshAgent.sessions[key]).toBeUndefined()
   })
 
+  it('handles freshAgent.session.changed without mutating idle status', () => {
+    const store = createFreshAgentStore()
+    const sessionId = 'ses_opencode_idle'
+    const key = `freshopencode:opencode:${sessionId}`
+
+    expect(handleFreshAgentMessage(store.dispatch, {
+      type: 'freshAgent.event',
+      sessionId,
+      sessionType: 'freshopencode',
+      provider: 'opencode',
+      event: {
+        type: 'freshAgent.session.snapshot',
+        sessionId,
+        latestTurnId: 'msg_assistant_1',
+        status: 'idle',
+        revision: 11,
+      },
+    })).toBe(true)
+
+    expect(handleFreshAgentMessage(store.dispatch, {
+      type: 'freshAgent.event',
+      sessionId,
+      sessionType: 'freshopencode',
+      provider: 'opencode',
+      event: {
+        type: 'freshAgent.session.changed',
+        sessionId,
+        reason: 'opencode-message',
+      },
+    })).toBe(true)
+
+    expect(store.getState().freshAgent.sessions[key]).toMatchObject({
+      status: 'idle',
+      latestTurnId: 'msg_assistant_1',
+      historyRevision: 11,
+    })
+  })
+
   it('does not let delayed metadata downgrade newer snapshot identity', () => {
     const store = createFreshAgentStore()
     const sessionId = 'claude-thread-metadata-order'
diff --git a/test/unit/server/fresh-agent/opencode-serve-events.test.ts b/test/unit/server/fresh-agent/opencode-serve-events.test.ts
index 77366eb71..d65d3237c 100644
--- a/test/unit/server/fresh-agent/opencode-serve-events.test.ts
+++ b/test/unit/server/fresh-agent/opencode-serve-events.test.ts
@@ -82,14 +82,68 @@ describe('serveEventToSdk', () => {
     }
     expect(serveEventToSdk(parsed, 'ses_a')).toEqual({ type: 'sdk.session.snapshot', sessionId: 'ses_a', status: 'running' })
   })
-  it('maps message.part.updated to a running snapshot (drives client re-poll)', () => {
+  it('maps message.part.updated to a transcript invalidation (drives client re-poll)', () => {
     const parsed: ParsedServeEvent = {
       kind: 'message.part.updated',
       sessionId: 'ses_a',
       properties: { sessionID: 'ses_a', part: { id: 'p', type: 'text' } },
       raw: { type: 'message.part.updated', properties: { sessionID: 'ses_a', part: { id: 'p', type: 'text' } } },
     }
-    expect(serveEventToSdk(parsed, 'ses_a')).toEqual({ type: 'sdk.session.snapshot', sessionId: 'ses_a', status: 'running' })
+    expect(serveEventToSdk(parsed, 'ses_a')).toEqual({
+      type: 'sdk.session.changed',
+      sessionId: 'ses_a',
+      reason: 'opencode-message',
+    })
+  })
+  it('maps OpenCode transcript mutation events to invalidations instead of running snapshots', () => {
+    for (const kind of ['message.part.delta', 'message.part.updated', 'message.updated', 'message.removed', 'message.part.removed']) {
+      const parsed: ParsedServeEvent = {
+        kind,
+        sessionId: 'ses_a',
+        properties: { sessionID: 'ses_a', info: { id: 'msg_1', role: 'assistant' } },
+        raw: { type: kind, properties: { sessionID: 'ses_a' } },
+      }
+
+      expect(serveEventToSdk(parsed, 'freshopencode-req-1')).toEqual({
+        type: 'sdk.session.changed',
+        sessionId: 'freshopencode-req-1',
+        reason: 'opencode-message',
+      })
+    }
+  })
+  it('maps only active OpenCode session statuses to running', () => {
+    const statusEvent = (statusType: string): ParsedServeEvent => ({
+      kind: 'session.status',
+      sessionId: 'ses_a',
+      properties: { sessionID: 'ses_a', status: { type: statusType } },
+      raw: { type: 'session.status', properties: { sessionID: 'ses_a', status: { type: statusType } } },
+    })
+
+    expect(serveEventToSdk(statusEvent('busy'), 'ses_a')).toEqual({
+      type: 'sdk.session.snapshot',
+      sessionId: 'ses_a',
+      status: 'running',
+    })
+    expect(serveEventToSdk(statusEvent('retry'), 'ses_a')).toEqual({
+      type: 'sdk.session.snapshot',
+      sessionId: 'ses_a',
+      status: 'running',
+    })
+    expect(serveEventToSdk(statusEvent('idle'), 'ses_a')).toEqual({
+      type: 'sdk.session.snapshot',
+      sessionId: 'ses_a',
+      status: 'idle',
+    })
+    expect(serveEventToSdk(statusEvent('completed'), 'ses_a')).toEqual({
+      type: 'sdk.session.changed',
+      sessionId: 'ses_a',
+      reason: 'opencode-status',
+    })
+    expect(serveEventToSdk(statusEvent('unexpected-future-status'), 'ses_a')).toEqual({
+      type: 'sdk.session.changed',
+      sessionId: 'ses_a',
+      reason: 'opencode-status',
+    })
   })
   it('maps session.error to an sdk.error', () => {
     const parsed: ParsedServeEvent = {

From d3c2b28530b29a21b87efd2d1f9c290490855846 Mon Sep 17 00:00:00 2001
From: Codex <codex@openai.com>
Date: Fri, 19 Jun 2026 00:13:30 -0700
Subject: [PATCH 13/33] fix: clear freshopencode idle when opencode status
 drops

---
 .../adapters/opencode/serve-manager.ts        | 95 ++++++++++++++++++-
 .../opencode-serve-adapter.test.ts            | 49 +++++++++-
 .../opencode-serve-manager.test.ts            | 70 ++++++++++++++
 3 files changed, 204 insertions(+), 10 deletions(-)

diff --git a/server/fresh-agent/adapters/opencode/serve-manager.ts b/server/fresh-agent/adapters/opencode/serve-manager.ts
index ce21d848f..e5fa1b461 100644
--- a/server/fresh-agent/adapters/opencode/serve-manager.ts
+++ b/server/fresh-agent/adapters/opencode/serve-manager.ts
@@ -10,6 +10,8 @@ import { parseServeEvent, type ParsedServeEvent } from './serve-events.js'
 type OpencodeServeLogger = Pick<pino.Logger, 'warn' | 'error'>
 
 const OWNERSHIP_ENV = 'FRESHELL_OPENCODE_SIDECAR_ID'
+const DEFAULT_IDLE_POLL_MS = 500
+const REQUIRED_IDLE_STATUS_POLLS = 2
 
 export type OpencodeServeManagerOptions = {
   command?: string
@@ -21,12 +23,14 @@ export type OpencodeServeManagerOptions = {
   healthTimeoutMs?: number
   env?: NodeJS.ProcessEnv
   idleShutdownMs?: number
+  idlePollMs?: number
 }
 
 export type OpencodeServeMessage = { info: Record<string, any>; parts: Array<Record<string, any>> }
 export type OpencodeServeMessagePage = { messages: OpencodeServeMessage[]; nextCursor: string | null }
 
 type HealthResponse = { healthy?: boolean }
+type OpencodeStatusMap = Record<string, { type?: unknown }>
 
 function isIdleStatusEvent(event: ParsedServeEvent): boolean {
   if (event.kind !== 'session.status') return false
@@ -35,6 +39,26 @@ function isIdleStatusEvent(event: ParsedServeEvent): boolean {
   return (status as Record<string, unknown>).type === 'idle'
 }
 
+function isRunningStatusType(type: unknown): boolean {
+  return type === 'busy' || type === 'retry'
+}
+
+function isIdleStatusType(type: unknown): boolean {
+  return type === 'idle'
+}
+
+function isOpencodeTranscriptEvent(kind: string): boolean {
+  return kind.startsWith('message.')
+}
+
+function eventShowsSessionActivity(event: ParsedServeEvent): boolean {
+  if (isOpencodeTranscriptEvent(event.kind)) return true
+  if (event.kind !== 'session.status') return false
+  const status = event.properties.status
+  if (!status || typeof status !== 'object' || Array.isArray(status)) return false
+  return isRunningStatusType((status as Record<string, unknown>).type)
+}
+
 function isHealthyResponse(body: unknown): body is HealthResponse {
   return typeof body === 'object' && body !== null && (body as HealthResponse).healthy !== false
 }
@@ -65,6 +89,7 @@ export class OpencodeServeManager {
   private readonly healthTimeoutMs: number
   private readonly env: NodeJS.ProcessEnv
   private readonly idleShutdownMs: number
+  private readonly idlePollMs: number
   private readonly log: OpencodeServeLogger = logger.child({ component: 'opencode-serve-manager' })
   /** sessionId → emitter of ParsedServeEvent (and a synthetic 'idle' event). */
   private readonly sessionEmitters = new Map<string, EventEmitter>()
@@ -84,6 +109,7 @@ export class OpencodeServeManager {
     this.healthTimeoutMs = options.healthTimeoutMs ?? 20_000
     this.env = options.env ?? process.env
     this.idleShutdownMs = options.idleShutdownMs ?? 15 * 60_000
+    this.idlePollMs = options.idlePollMs ?? DEFAULT_IDLE_POLL_MS
   }
 
   private routeFromCwd(cwd?: string): { cwdKey: string; cwd?: string } {
@@ -313,6 +339,10 @@ export class OpencodeServeManager {
     })
   }
 
+  private async getSessionStatusMap(route: ServeRoute = {}, init?: RequestInit): Promise<OpencodeStatusMap> {
+    return this.json<OpencodeStatusMap>(route, '/session/status', { method: 'GET', ...init })
+  }
+
   async createSession(input: { title?: string; parentID?: string; directory?: string } = {}): Promise<{ id: string; directory?: string; title?: string }> {
     const body: { title?: string; parentID?: string; directory?: string } = {}
     if (input.title !== undefined) body.title = input.title
@@ -438,16 +468,71 @@ export class OpencodeServeManager {
   onceIdle(sessionId: string, timeoutMs: number): Promise<void> {
     return new Promise((resolve, reject) => {
       const emitter = this.emitterFor(sessionId)
-      const timer = setTimeout(() => {
+      let settled = false
+      let observedActivity = false
+      let pollInFlight = false
+      let idleStatusPolls = 0
+
+      const cleanup = () => {
+        clearTimeout(timer)
+        clearInterval(pollTimer)
         emitter.off('event', handler)
-        reject(new Error(`Timed out after ${timeoutMs}ms waiting for OpenCode session ${sessionId} to go idle.`))
+      }
+      const finish = () => {
+        if (settled) return
+        settled = true
+        cleanup()
+        resolve()
+      }
+      const fail = (error: Error) => {
+        if (settled) return
+        settled = true
+        cleanup()
+        reject(error)
+      }
+      const markActivity = () => {
+        observedActivity = true
+        idleStatusPolls = 0
+      }
+      const checkStatusMap = async () => {
+        if (settled || pollInFlight) return
+        pollInFlight = true
+        try {
+          const statuses = await this.getSessionStatusMap(this.routeForSession(sessionId))
+          const status = statuses[sessionId]
+          if (status && isRunningStatusType(status.type)) {
+            markActivity()
+            return
+          }
+          if (observedActivity && (!status || isIdleStatusType(status.type))) {
+            idleStatusPolls += 1
+            if (idleStatusPolls >= REQUIRED_IDLE_STATUS_POLLS) finish()
+            return
+          }
+          idleStatusPolls = 0
+        } catch (err) {
+          this.log.warn({ err, sessionId }, 'OpenCode idle status fallback failed')
+        } finally {
+          pollInFlight = false
+        }
+      }
+
+      const timer = setTimeout(() => {
+        fail(new Error(`Timed out after ${timeoutMs}ms waiting for OpenCode session ${sessionId} to go idle.`))
       }, timeoutMs)
       timer.unref?.()
+
+      const pollTimer = setInterval(() => { void checkStatusMap() }, this.idlePollMs)
+      pollTimer.unref?.()
+
       const handler = (event: ParsedServeEvent) => {
         if (event.kind === 'session.idle' || isIdleStatusEvent(event)) {
-          clearTimeout(timer)
-          emitter.off('event', handler)
-          resolve()
+          finish()
+          return
+        }
+        if (eventShowsSessionActivity(event)) {
+          markActivity()
+          void checkStatusMap()
         }
       }
       emitter.on('event', handler)
diff --git a/test/unit/server/fresh-agent/opencode-serve-adapter.test.ts b/test/unit/server/fresh-agent/opencode-serve-adapter.test.ts
index ce29acc85..a29a7d771 100644
--- a/test/unit/server/fresh-agent/opencode-serve-adapter.test.ts
+++ b/test/unit/server/fresh-agent/opencode-serve-adapter.test.ts
@@ -179,11 +179,50 @@ describe('OpenCode serve adapter: create + send', () => {
       await expect(adapter.send?.('freshopencode-unhandled-1', { text: 'boom' })).rejects.toThrow('prompt rejected')
       // Simulating the idle timeout rejection that would otherwise arrive later.
       idleReject(new Error('idle timeout'))
-      await new Promise((r) => setTimeout(r, 10))
-      expect(unhandled).not.toHaveBeenCalled()
-    } finally {
-      process.off('unhandledRejection', unhandled)
-    }
+    await new Promise((r) => setTimeout(r, 10))
+    expect(unhandled).not.toHaveBeenCalled()
+  } finally {
+    process.off('unhandledRejection', unhandled)
+  }
+  })
+
+  it('does not return to running when OpenCode emits a late message update after idle', async () => {
+    const manager = makeFakeManager()
+    const adapter = makeAdapter(manager)
+    await adapter.create({ requestId: 'late-update', sessionType: 'freshopencode', provider: 'opencode' })
+
+    const events: unknown[] = []
+    adapter.subscribe?.('freshopencode-late-update', (event) => events.push(event))
+
+    await adapter.send?.('freshopencode-late-update', { text: 'go' })
+    manager._emit('ses_real_1', {
+      kind: 'session.idle',
+      sessionId: 'ses_real_1',
+      properties: { sessionID: 'ses_real_1' },
+      raw: { type: 'session.idle', properties: { sessionID: 'ses_real_1' } },
+    })
+    manager._emit('ses_real_1', {
+      kind: 'message.updated',
+      sessionId: 'ses_real_1',
+      properties: { sessionID: 'ses_real_1', info: { id: 'msg_user_1', role: 'user' } },
+      raw: { type: 'message.updated', properties: { sessionID: 'ses_real_1' } },
+    })
+
+    expect(events).toContainEqual({
+      type: 'sdk.session.snapshot',
+      sessionId: 'freshopencode-late-update',
+      status: 'idle',
+    })
+    expect(events.at(-1)).toEqual({
+      type: 'sdk.session.changed',
+      sessionId: 'freshopencode-late-update',
+      reason: 'opencode-message',
+    })
+    await expect(adapter.getSnapshot?.({
+      sessionType: 'freshopencode',
+      provider: 'opencode',
+      threadId: 'freshopencode-late-update',
+    })).resolves.toMatchObject({ status: 'idle' })
   })
 
   it('forwards compact instructions to the serve manager', async () => {
diff --git a/test/unit/server/fresh-agent/opencode-serve-manager.test.ts b/test/unit/server/fresh-agent/opencode-serve-manager.test.ts
index d3c940289..cffade0c1 100644
--- a/test/unit/server/fresh-agent/opencode-serve-manager.test.ts
+++ b/test/unit/server/fresh-agent/opencode-serve-manager.test.ts
@@ -535,6 +535,76 @@ describe('OpencodeServeManager fan-out', () => {
     await expect(idle).rejects.toThrow(/idle/i)
   })
 
+  it('onceIdle resolves when status-map activity drops out of the OpenCode status map', async () => {
+    let statusCalls = 0
+    const fetchFn = vi.fn(async (url: string) => {
+      if (url.endsWith('/global/health')) return jsonResponse({ healthy: true })
+      if (url.endsWith('/session/status')) {
+        statusCalls += 1
+        return statusCalls === 1
+          ? jsonResponse({ ses_a: { type: 'busy' } })
+          : jsonResponse({})
+      }
+      return jsonResponse({})
+    })
+    const { manager } = makeManager({
+      fetchFn: fetchFn as any,
+      idlePollMs: 5,
+    })
+    await manager.ensureStarted()
+
+    const idle = manager.onceIdle('ses_a', 1000)
+
+    await expect(idle).resolves.toBeUndefined()
+    expect(fetchFn).toHaveBeenCalledWith('http://127.0.0.1:47999/session/status', expect.anything())
+    expect((manager as any).sessionEmitters.get('ses_a')?.listenerCount('event') ?? 0).toBe(0)
+  })
+
+  it('onceIdle does not resolve from status-map absence before observed OpenCode activity', async () => {
+    const fetchFn = vi.fn(async (url: string) => {
+      if (url.endsWith('/global/health')) return jsonResponse({ healthy: true })
+      if (url.endsWith('/session/status')) return jsonResponse({})
+      return jsonResponse({})
+    })
+    const { manager } = makeManager({
+      fetchFn: fetchFn as any,
+      idlePollMs: 5,
+    })
+    await manager.ensureStarted()
+
+    await expect(manager.onceIdle('ses_a', 30)).rejects.toThrow(/idle/i)
+  })
+
+  it('onceIdle does not resolve from a single busy signal plus one empty status-map poll', async () => {
+    let push!: (e: any) => void
+    let statusCalls = 0
+    const fetchFn = vi.fn(async (url: string) => {
+      if (url.endsWith('/global/health')) return jsonResponse({ healthy: true })
+      if (url.endsWith('/session/status')) {
+        statusCalls += 1
+        if (statusCalls === 1) return jsonResponse({})
+        throw new Error('status map unavailable')
+      }
+      return jsonResponse({})
+    })
+    const { manager } = makeManager({
+      fetchFn: fetchFn as any,
+      connectEventStream: (_url, h) => { push = (e) => h.onEvent(parseEvt(e)); return () => {} },
+      idlePollMs: 5,
+    })
+    await manager.ensureStarted()
+
+    const idle = manager.onceIdle('ses_a', 40)
+    push({ type: 'session.status', properties: { sessionID: 'ses_a', status: { type: 'busy' } } })
+
+    const pending = await Promise.race([
+      idle.then(() => 'resolved', () => 'rejected'),
+      new Promise<'pending'>((resolve) => setTimeout(() => resolve('pending'), 15)),
+    ])
+    expect(pending).toBe('pending')
+    await expect(idle).rejects.toThrow(/idle/i)
+  })
+
   it('onceIdle rejects on timeout', async () => {
     const { manager } = makeManager({ connectEventStream: () => () => {} })
     await manager.ensureStarted()

From 6c57ad3881ac0aab6672c0a8427856879b42c33f Mon Sep 17 00:00:00 2001
From: Codex <codex@openai.com>
Date: Fri, 19 Jun 2026 00:19:57 -0700
Subject: [PATCH 14/33] Fix opencode idle poll reset

---
 .../adapters/opencode/serve-manager.ts        |  1 +
 .../opencode-serve-manager.test.ts            | 50 +++++++++++++++++++
 2 files changed, 51 insertions(+)

diff --git a/server/fresh-agent/adapters/opencode/serve-manager.ts b/server/fresh-agent/adapters/opencode/serve-manager.ts
index e5fa1b461..01c11e041 100644
--- a/server/fresh-agent/adapters/opencode/serve-manager.ts
+++ b/server/fresh-agent/adapters/opencode/serve-manager.ts
@@ -511,6 +511,7 @@ export class OpencodeServeManager {
           }
           idleStatusPolls = 0
         } catch (err) {
+          idleStatusPolls = 0
           this.log.warn({ err, sessionId }, 'OpenCode idle status fallback failed')
         } finally {
           pollInFlight = false
diff --git a/test/unit/server/fresh-agent/opencode-serve-manager.test.ts b/test/unit/server/fresh-agent/opencode-serve-manager.test.ts
index cffade0c1..a0327946e 100644
--- a/test/unit/server/fresh-agent/opencode-serve-manager.test.ts
+++ b/test/unit/server/fresh-agent/opencode-serve-manager.test.ts
@@ -605,6 +605,56 @@ describe('OpencodeServeManager fan-out', () => {
     await expect(idle).rejects.toThrow(/idle/i)
   })
 
+  it('onceIdle requires a fresh consecutive idle/absent pair after a status-map poll failure', async () => {
+    let push!: (e: any) => void
+    let statusCalls = 0
+    let allowFifthPoll!: () => void
+    let noteFifthPollStarted!: () => void
+    const fifthPollGate = new Promise<void>((resolve) => {
+      allowFifthPoll = resolve
+    })
+    const fifthPollStarted = new Promise<void>((resolve) => {
+      noteFifthPollStarted = resolve
+    })
+    const fetchFn = vi.fn(async (url: string) => {
+      if (url.endsWith('/global/health')) return jsonResponse({ healthy: true })
+      if (url.endsWith('/session/status')) {
+        statusCalls += 1
+        if (statusCalls === 1) return jsonResponse({ ses_a: { type: 'busy' } })
+        if (statusCalls === 2) return jsonResponse({})
+        if (statusCalls === 3) throw new Error('status map unavailable')
+        if (statusCalls === 4) return jsonResponse({})
+        if (statusCalls === 5) {
+          noteFifthPollStarted()
+          await fifthPollGate
+          return jsonResponse({})
+        }
+        return jsonResponse({})
+      }
+      return jsonResponse({})
+    })
+    const { manager } = makeManager({
+      fetchFn: fetchFn as any,
+      connectEventStream: (_url, h) => { push = (e) => h.onEvent(parseEvt(e)); return () => {} },
+      idlePollMs: 5,
+    })
+    await manager.ensureStarted()
+
+    const idle = manager.onceIdle('ses_a', 100)
+    push({ type: 'session.status', properties: { sessionID: 'ses_a', status: { type: 'busy' } } })
+
+    await fifthPollStarted
+    const pending = await Promise.race([
+      idle.then(() => 'resolved', () => 'rejected'),
+      new Promise<'pending'>((resolve) => setTimeout(() => resolve('pending'), 15)),
+    ])
+    expect(pending).toBe('pending')
+
+    allowFifthPoll()
+    await expect(idle).resolves.toBeUndefined()
+    expect(statusCalls).toBe(5)
+  }, 1000)
+
   it('onceIdle rejects on timeout', async () => {
     const { manager } = makeManager({ connectEventStream: () => () => {} })
     await manager.ensureStarted()

From 3e40b5103f637de024cd78682915c8014543d9e8 Mon Sep 17 00:00:00 2001
From: Codex <codex@openai.com>
Date: Fri, 19 Jun 2026 00:25:45 -0700
Subject: [PATCH 15/33] test: cover freshopencode late change invalidation

---
 .../fresh-agent/FreshAgentView.test.tsx       | 83 +++++++++++++++++++
 1 file changed, 83 insertions(+)

diff --git a/test/unit/client/components/fresh-agent/FreshAgentView.test.tsx b/test/unit/client/components/fresh-agent/FreshAgentView.test.tsx
index db181d38b..69ce5d677 100644
--- a/test/unit/client/components/fresh-agent/FreshAgentView.test.tsx
+++ b/test/unit/client/components/fresh-agent/FreshAgentView.test.tsx
@@ -156,6 +156,28 @@ function createDeferred<T>() {
   return { promise, resolve, reject }
 }
 
+function freshopencodeSnapshot(text: string, revision: number) {
+  return {
+    sessionType: 'freshopencode',
+    provider: 'opencode',
+    threadId: 'ses_late_change',
+    sessionId: 'ses_late_change',
+    status: 'idle',
+    latestTurnId: 'msg_assistant_1',
+    revision,
+    summary: 'OpenCode done',
+    capabilities: { send: true, interrupt: true, fork: true },
+    pendingApprovals: [],
+    pendingQuestions: [],
+    diffs: [],
+    worktrees: [],
+    turns: [
+      { id: 'msg_user_1', turnId: 'msg_user_1', role: 'user', summary: 'go', items: [{ id: 'user-text', kind: 'text', text: 'go' }] },
+      { id: 'msg_assistant_1', turnId: 'msg_assistant_1', role: 'assistant', summary: text, items: [{ id: 'assistant-text', kind: 'text', text }] },
+    ],
+  }
+}
+
 beforeEach(() => {
   wsMock.send.mockReset()
   wsMock.onMessage.mockReset()
@@ -2948,6 +2970,67 @@ describe('FreshAgentView', () => {
     expect(store.getState().panes.refreshRequestsByPane?.['tab-1']?.['pane-1']).toBeUndefined()
   })
 
+  it('refreshes freshopencode on session.changed without reopening the bouncer', async () => {
+    const store = createStore()
+    let wsHandler: ((message: any) => void) | undefined
+    wsMock.onMessage.mockImplementation((handler) => {
+      wsHandler = handler
+      return () => {}
+    })
+
+    apiMock.getFreshAgentThreadSnapshot
+      .mockResolvedValueOnce(freshopencodeSnapshot('done', 10))
+      .mockResolvedValueOnce(freshopencodeSnapshot('done updated', 11))
+
+    store.dispatch(initLayout({
+      tabId: 'tab-1',
+      paneId: 'pane-1',
+      content: {
+        kind: 'fresh-agent',
+        sessionType: 'freshopencode',
+        provider: 'opencode',
+        createRequestId: 'req-late-change',
+        sessionId: 'ses_late_change',
+        sessionRef: { provider: 'opencode', sessionId: 'ses_late_change' },
+        resumeSessionId: 'ses_late_change',
+        status: 'idle',
+      },
+    }))
+
+    render(
+      <Provider store={store}>
+        <StoreBackedFreshAgentView tabId="tab-1" paneId="pane-1" />
+      </Provider>,
+    )
+
+    await waitFor(() => {
+      expect(screen.getByText('done')).toBeInTheDocument()
+    })
+
+    act(() => {
+      wsHandler?.({
+        type: 'freshAgent.event',
+        sessionId: 'ses_late_change',
+        sessionType: 'freshopencode',
+        provider: 'opencode',
+        event: {
+          type: 'freshAgent.session.changed',
+          sessionId: 'ses_late_change',
+          reason: 'opencode-message',
+        },
+      })
+    })
+
+    await waitFor(() => {
+      expect(screen.getByText('done updated')).toBeInTheDocument()
+    })
+    expect(apiMock.getFreshAgentThreadSnapshot).toHaveBeenCalledTimes(2)
+    expect(getFreshAgentPaneContent(store)).toMatchObject({
+      sessionId: 'ses_late_change',
+      status: 'idle',
+    })
+  })
+
   it('normalizes obsolete Freshcodex models to the default radio option', async () => {
     const store = createStore()
     render(

From a46fe7a7f12888d9cdffa3e9a77f183831637e57 Mon Sep 17 00:00:00 2001
From: Codex <codex@openai.com>
Date: Fri, 19 Jun 2026 00:43:44 -0700
Subject: [PATCH 16/33] Fix freshopencode onceIdle fallback gating

---
 .../adapters/opencode/serve-manager.ts        | 15 ++--
 .../opencode-serve-manager.test.ts            | 68 +++++++++++++++++++
 .../server/ws-fresh-agent-contract.test.ts    | 10 +++
 3 files changed, 85 insertions(+), 8 deletions(-)

diff --git a/server/fresh-agent/adapters/opencode/serve-manager.ts b/server/fresh-agent/adapters/opencode/serve-manager.ts
index 01c11e041..783b358e4 100644
--- a/server/fresh-agent/adapters/opencode/serve-manager.ts
+++ b/server/fresh-agent/adapters/opencode/serve-manager.ts
@@ -47,12 +47,7 @@ function isIdleStatusType(type: unknown): boolean {
   return type === 'idle'
 }
 
-function isOpencodeTranscriptEvent(kind: string): boolean {
-  return kind.startsWith('message.')
-}
-
-function eventShowsSessionActivity(event: ParsedServeEvent): boolean {
-  if (isOpencodeTranscriptEvent(event.kind)) return true
+function eventShowsRunningStatusActivity(event: ParsedServeEvent): boolean {
   if (event.kind !== 'session.status') return false
   const status = event.properties.status
   if (!status || typeof status !== 'object' || Array.isArray(status)) return false
@@ -472,6 +467,7 @@ export class OpencodeServeManager {
       let observedActivity = false
       let pollInFlight = false
       let idleStatusPolls = 0
+      let warnedStatusFallbackFailure = false
 
       const cleanup = () => {
         clearTimeout(timer)
@@ -512,7 +508,10 @@ export class OpencodeServeManager {
           idleStatusPolls = 0
         } catch (err) {
           idleStatusPolls = 0
-          this.log.warn({ err, sessionId }, 'OpenCode idle status fallback failed')
+          if (!warnedStatusFallbackFailure) {
+            warnedStatusFallbackFailure = true
+            this.log.warn({ err, sessionId }, 'OpenCode idle status fallback failed')
+          }
         } finally {
           pollInFlight = false
         }
@@ -531,7 +530,7 @@ export class OpencodeServeManager {
           finish()
           return
         }
-        if (eventShowsSessionActivity(event)) {
+        if (eventShowsRunningStatusActivity(event)) {
           markActivity()
           void checkStatusMap()
         }
diff --git a/test/unit/server/fresh-agent/opencode-serve-manager.test.ts b/test/unit/server/fresh-agent/opencode-serve-manager.test.ts
index a0327946e..f01242da2 100644
--- a/test/unit/server/fresh-agent/opencode-serve-manager.test.ts
+++ b/test/unit/server/fresh-agent/opencode-serve-manager.test.ts
@@ -575,6 +575,52 @@ describe('OpencodeServeManager fan-out', () => {
     await expect(manager.onceIdle('ses_a', 30)).rejects.toThrow(/idle/i)
   })
 
+  it('onceIdle ignores late message.updated events when the status map stays absent', async () => {
+    let push!: (e: any) => void
+    const fetchFn = vi.fn(async (url: string) => {
+      if (url.endsWith('/global/health')) return jsonResponse({ healthy: true })
+      if (url.endsWith('/session/status')) return jsonResponse({})
+      return jsonResponse({})
+    })
+    const { manager } = makeManager({
+      fetchFn: fetchFn as any,
+      connectEventStream: (_url, h) => { push = (e) => h.onEvent(parseEvt(e)); return () => {} },
+      idlePollMs: 5,
+    })
+    await manager.ensureStarted()
+
+    const idle = manager.onceIdle('ses_a', 30)
+    push({ type: 'message.updated', properties: { sessionID: 'ses_a', message: { id: 'old-turn' } } })
+
+    await expect(idle).rejects.toThrow(/idle/i)
+  })
+
+  it('onceIdle waits for later running status-map evidence after a late message.updated event', async () => {
+    let push!: (e: any) => void
+    let statusCalls = 0
+    const fetchFn = vi.fn(async (url: string) => {
+      if (url.endsWith('/global/health')) return jsonResponse({ healthy: true })
+      if (url.endsWith('/session/status')) {
+        statusCalls += 1
+        if (statusCalls <= 2) return jsonResponse({})
+        if (statusCalls === 3) return jsonResponse({ ses_a: { type: 'busy' } })
+        return jsonResponse({})
+      }
+      return jsonResponse({})
+    })
+    const { manager } = makeManager({
+      fetchFn: fetchFn as any,
+      connectEventStream: (_url, h) => { push = (e) => h.onEvent(parseEvt(e)); return () => {} },
+      idlePollMs: 5,
+    })
+    await manager.ensureStarted()
+
+    const idle = manager.onceIdle('ses_a', 80)
+    push({ type: 'message.updated', properties: { sessionID: 'ses_a', message: { id: 'old-turn' } } })
+
+    await expect(idle).resolves.toBeUndefined()
+  })
+
   it('onceIdle does not resolve from a single busy signal plus one empty status-map poll', async () => {
     let push!: (e: any) => void
     let statusCalls = 0
@@ -605,6 +651,28 @@ describe('OpencodeServeManager fan-out', () => {
     await expect(idle).rejects.toThrow(/idle/i)
   })
 
+  it('onceIdle warns only once per wait when status-map fallback polling keeps failing', async () => {
+    let push!: (e: any) => void
+    const fetchFn = vi.fn(async (url: string) => {
+      if (url.endsWith('/global/health')) return jsonResponse({ healthy: true })
+      if (url.endsWith('/session/status')) throw new Error('status map unavailable')
+      return jsonResponse({})
+    })
+    const { manager } = makeManager({
+      fetchFn: fetchFn as any,
+      connectEventStream: (_url, h) => { push = (e) => h.onEvent(parseEvt(e)); return () => {} },
+      idlePollMs: 5,
+    })
+    await manager.ensureStarted()
+
+    const warnSpy = vi.spyOn((manager as any).log, 'warn').mockImplementation(() => undefined)
+    const idle = manager.onceIdle('ses_a', 35)
+    push({ type: 'session.status', properties: { sessionID: 'ses_a', status: { type: 'busy' } } })
+
+    await expect(idle).rejects.toThrow(/idle/i)
+    expect(warnSpy).toHaveBeenCalledTimes(1)
+  })
+
   it('onceIdle requires a fresh consecutive idle/absent pair after a status-map poll failure', async () => {
     let push!: (e: any) => void
     let statusCalls = 0
diff --git a/test/unit/server/ws-fresh-agent-contract.test.ts b/test/unit/server/ws-fresh-agent-contract.test.ts
index aaadb578c..4999b8db5 100644
--- a/test/unit/server/ws-fresh-agent-contract.test.ts
+++ b/test/unit/server/ws-fresh-agent-contract.test.ts
@@ -33,6 +33,16 @@ describe('fresh-agent websocket contract', () => {
       tool: { name: 'Bash', input: { command: 'npm test' } },
     })
 
+    expect(normalizeFreshAgentProviderEvent({
+      type: 'sdk.session.changed',
+      sessionId: 's1',
+      reason: 'opencode-status',
+    })).toEqual({
+      type: 'freshAgent.session.changed',
+      sessionId: 's1',
+      reason: 'opencode-status',
+    })
+
     expect(normalizeFreshAgentProviderEvent({
       type: 'freshAgent.status',
       sessionId: 's1',

From 383e8f577286ce1bf9f58150e7fc29d0944a4ba2 Mon Sep 17 00:00:00 2001
From: Codex <codex@openai.com>
Date: Fri, 19 Jun 2026 01:44:54 -0700
Subject: [PATCH 17/33] feat: add fresh agent display turn helpers

---
 shared/fresh-agent-turns.ts                | 23 ++++++
 test/unit/shared/fresh-agent-turns.test.ts | 84 ++++++++++++++++++++++
 2 files changed, 107 insertions(+)
 create mode 100644 shared/fresh-agent-turns.ts
 create mode 100644 test/unit/shared/fresh-agent-turns.test.ts

diff --git a/shared/fresh-agent-turns.ts b/shared/fresh-agent-turns.ts
new file mode 100644
index 000000000..f292986bb
--- /dev/null
+++ b/shared/fresh-agent-turns.ts
@@ -0,0 +1,23 @@
+import type { FreshAgentSnapshot, FreshAgentTurn } from './fresh-agent-contract.js'
+
+export function getFreshAgentDisplayTurnKey(turn: Pick<FreshAgentTurn, 'turnId' | 'id'>): string {
+  return turn.turnId || turn.id
+}
+
+export function freshAgentTurnText(turn: Pick<FreshAgentTurn, 'summary' | 'items'>): string {
+  const text = turn.items
+    .filter((item): item is { kind: 'text'; text: string } => item.kind === 'text')
+    .map((item) => item.text)
+    .join(' ')
+  return text || turn.summary
+}
+
+function normalizeTurnRole(role: unknown): string | undefined {
+  return typeof role === 'string' ? role.trim().toLowerCase() : undefined
+}
+
+export function freshAgentSnapshotHasUserTurn(
+  snapshot: Pick<FreshAgentSnapshot, 'turns'> | null | undefined,
+): boolean {
+  return snapshot?.turns?.some((turn) => normalizeTurnRole(turn.role) === 'user') ?? false
+}
diff --git a/test/unit/shared/fresh-agent-turns.test.ts b/test/unit/shared/fresh-agent-turns.test.ts
new file mode 100644
index 000000000..bdc9f178f
--- /dev/null
+++ b/test/unit/shared/fresh-agent-turns.test.ts
@@ -0,0 +1,84 @@
+import { describe, expect, it } from 'vitest'
+
+import { FreshAgentTurnSchema } from '../../../shared/fresh-agent-contract.js'
+import {
+  freshAgentSnapshotHasUserTurn,
+  freshAgentTurnText,
+  getFreshAgentDisplayTurnKey,
+} from '../../../shared/fresh-agent-turns.js'
+
+describe('fresh-agent display turn helpers', () => {
+  it('prefers turnId over id for display keys', () => {
+    expect(getFreshAgentDisplayTurnKey({ turnId: 'turn-1', id: 'id-1' })).toBe('turn-1')
+    expect(getFreshAgentDisplayTurnKey({ turnId: 'turn-2', id: 'id-2' })).toBe('turn-2')
+  })
+
+  it('falls back to id when turnId is missing', () => {
+    expect(getFreshAgentDisplayTurnKey({ turnId: '', id: 'id-fallback' })).toBe('id-fallback')
+  })
+
+  it('joins text items and falls back to summary when no text item exists', () => {
+    expect(freshAgentTurnText({
+      summary: 'fallback',
+      items: [
+        { id: 'a', kind: 'text', text: 'hello' },
+        { id: 'b', kind: 'reasoning', summary: ['ignore'], content: ['ignore'], text: 'ignore' },
+        { id: 'c', kind: 'text', text: 'world' },
+      ],
+    })).toBe('hello world')
+
+    expect(freshAgentTurnText({
+      summary: 'fallback text',
+      items: [{ id: 'x', kind: 'thinking', text: 'ignored' }],
+    })).toBe('fallback text')
+  })
+
+  it('returns true only for normalized user turns', () => {
+    expect(freshAgentSnapshotHasUserTurn({
+      turns: [
+        { turnId: '1', id: '1', summary: 'user prompt', role: 'user', items: [] },
+        { turnId: '2', id: '2', summary: 'assistant response', role: 'assistant', items: [] },
+      ],
+    })).toBe(true)
+
+    expect(freshAgentSnapshotHasUserTurn({ turns: [] })).toBe(false)
+    expect(freshAgentSnapshotHasUserTurn({
+      turns: [{ turnId: '3', id: '3', summary: 'tool', role: 'tool', items: [] }],
+    })).toBe(false)
+
+    expect(freshAgentSnapshotHasUserTurn({
+      turns: [{ turnId: '4', id: '4', summary: 'legacy user value', role: 'USER' as unknown as string, items: [] }],
+    })).toBe(true)
+
+    expect(freshAgentSnapshotHasUserTurn({
+      turns: [{ turnId: '5', id: '5', summary: 'normalized user', role: 'USER', items: [] }],
+    })).toBe(true)
+  })
+
+  it('does not treat assistant quoted prompt text as user submissions', () => {
+    expect(freshAgentSnapshotHasUserTurn({
+      turns: [{
+        turnId: '6',
+        id: '6',
+        summary: 'assistant turn',
+        role: 'assistant',
+        items: [{ id: 'a', kind: 'text', text: 'user: hi there' }],
+      }],
+    })).toBe(false)
+  })
+
+  it('supports legacy calls with null or undefined snapshots', () => {
+    expect(freshAgentSnapshotHasUserTurn(null)).toBe(false)
+    expect(freshAgentSnapshotHasUserTurn(undefined)).toBe(false)
+  })
+
+  it('keeps FreshAgentTurnSchema unchanged and rejects providerTurnId', () => {
+    expect(() => FreshAgentTurnSchema.parse({
+      id: '1',
+      turnId: 't-1',
+      summary: 'summary',
+      items: [],
+      providerTurnId: 'legacy-id',
+    })).toThrow()
+  })
+})

From 049dcdd4160a85a672c1cfb328b6d974e577ac4f Mon Sep 17 00:00:00 2001
From: Codex <codex@openai.com>
Date: Fri, 19 Jun 2026 01:47:11 -0700
Subject: [PATCH 18/33] fix: preserve empty text item in turn text helper

---
 shared/fresh-agent-turns.ts                | 8 ++++----
 test/unit/shared/fresh-agent-turns.test.ts | 7 ++++++-
 2 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/shared/fresh-agent-turns.ts b/shared/fresh-agent-turns.ts
index f292986bb..2085e5924 100644
--- a/shared/fresh-agent-turns.ts
+++ b/shared/fresh-agent-turns.ts
@@ -1,15 +1,15 @@
 import type { FreshAgentSnapshot, FreshAgentTurn } from './fresh-agent-contract.js'
 
 export function getFreshAgentDisplayTurnKey(turn: Pick<FreshAgentTurn, 'turnId' | 'id'>): string {
-  return turn.turnId || turn.id
+  return turn.turnId ?? turn.id
 }
 
 export function freshAgentTurnText(turn: Pick<FreshAgentTurn, 'summary' | 'items'>): string {
-  const text = turn.items
+  const textItems = turn.items
     .filter((item): item is { kind: 'text'; text: string } => item.kind === 'text')
     .map((item) => item.text)
-    .join(' ')
-  return text || turn.summary
+  const text = textItems.join(' ')
+  return textItems.length > 0 ? text : turn.summary
 }
 
 function normalizeTurnRole(role: unknown): string | undefined {
diff --git a/test/unit/shared/fresh-agent-turns.test.ts b/test/unit/shared/fresh-agent-turns.test.ts
index bdc9f178f..94bdf0f62 100644
--- a/test/unit/shared/fresh-agent-turns.test.ts
+++ b/test/unit/shared/fresh-agent-turns.test.ts
@@ -14,7 +14,7 @@ describe('fresh-agent display turn helpers', () => {
   })
 
   it('falls back to id when turnId is missing', () => {
-    expect(getFreshAgentDisplayTurnKey({ turnId: '', id: 'id-fallback' })).toBe('id-fallback')
+    expect(getFreshAgentDisplayTurnKey({ turnId: undefined as unknown as string, id: 'id-fallback' })).toBe('id-fallback')
   })
 
   it('joins text items and falls back to summary when no text item exists', () => {
@@ -31,6 +31,11 @@ describe('fresh-agent display turn helpers', () => {
       summary: 'fallback text',
       items: [{ id: 'x', kind: 'thinking', text: 'ignored' }],
     })).toBe('fallback text')
+
+    expect(freshAgentTurnText({
+      summary: 'fallback text',
+      items: [{ id: 'y', kind: 'text', text: '' }],
+    })).toBe('')
   })
 
   it('returns true only for normalized user turns', () => {

From fe31b3d7c16b324a3ebfe6ab3cfd1e4849c0afd5 Mon Sep 17 00:00:00 2001
From: Codex <codex@openai.com>
Date: Fri, 19 Jun 2026 02:00:51 -0700
Subject: [PATCH 19/33] fix: normalize codex provider turns into stable display
 turns

---
 .../fresh-agent/adapters/codex/normalize.ts   | 760 ++++++++++++++----
 .../fresh-agent/codex-normalize.test.ts       | 416 +++++++++-
 2 files changed, 1005 insertions(+), 171 deletions(-)

diff --git a/server/fresh-agent/adapters/codex/normalize.ts b/server/fresh-agent/adapters/codex/normalize.ts
index 9d0c7b3f1..f1c7d0e39 100644
--- a/server/fresh-agent/adapters/codex/normalize.ts
+++ b/server/fresh-agent/adapters/codex/normalize.ts
@@ -1,3 +1,8 @@
+import { createHmac } from 'node:crypto'
+
+import {
+  CodexThreadItemTypeSchema,
+} from '../../../coding-cli/codex-app-server/protocol.js'
 import {
   FreshAgentSnapshotSchema,
   FreshAgentTurnBodySchema,
@@ -26,156 +31,454 @@ type CodexRawSnapshot = {
   extension?: { codex?: Record<string, unknown> }
 }
 
-function normalizeCodexItem(turnId: string, item: Record<string, unknown>, index: number): FreshAgentTranscriptItem[] {
-  const id = typeof item.id === 'string' && item.id.length > 0 ? item.id : `${turnId}:item:${index}`
-  switch (item.type) {
-    case 'userMessage': {
-      const content = Array.isArray(item.content) ? item.content : []
-      if (content.length === 0) {
-        return [{ id, kind: 'text', text: '' }]
+type CodexDisplayRole = NonNullable<FreshAgentTurn['role']>
+type CodexDisplaySyntheticKind = 'empty-response' | 'error' | 'submitted-input'
+type CodexThreadItemVariant = (typeof CodexThreadItemTypeSchema.options)[number]
+
+const CODEX_DISPLAY_ID_PREFIX = 'codex-display:v1:'
+const CODEX_DISPLAY_HANDLE_LENGTH = 22
+const DEFAULT_CODEX_DISPLAY_SECRET = 'codex-display-default-secret'
+
+export class CodexDisplayProtocolError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'CodexDisplayProtocolError'
+  }
+}
+
+export class CodexDisplayTurnNotFoundError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'CodexDisplayTurnNotFoundError'
+  }
+}
+
+export type CodexDisplayIdentity = {
+  secret: string
+  threadId: string
+  providerTurnId: string
+  role: CodexDisplayRole
+  itemIds?: string[]
+  partIndexes?: number[]
+  syntheticKind?: CodexDisplaySyntheticKind
+  requestId?: string | number
+}
+
+export type CodexDisplayRow = {
+  turnId: string
+  role: CodexDisplayRole
+  providerTurnId: string
+  itemIds: string[]
+  partIndexes: number[]
+  items: FreshAgentTranscriptItem[]
+  syntheticKind?: CodexDisplaySyntheticKind
+  requestId?: string | number
+}
+
+type NormalizeCodexDisplayTurnsOptions = {
+  model?: string
+  secret?: string
+  threadId?: string
+  submittedRequestIdByProviderTurnId?: ReadonlyMap<string, string | number>
+}
+
+type CodexNormalizedContribution = {
+  role: CodexDisplayRole
+  itemId: string
+  partIndex: number
+  item: FreshAgentTranscriptItem
+}
+
+type CodexPendingRow = {
+  role: CodexDisplayRole
+  itemIds: string[]
+  partIndexes: number[]
+  items: FreshAgentTranscriptItem[]
+  syntheticKind?: CodexDisplaySyntheticKind
+}
+
+function normalizeCommandStatus(status: unknown): 'running' | 'completed' | 'failed' | 'declined' {
+  return status === 'inProgress'
+    ? 'running'
+    : status === 'declined'
+      ? 'declined'
+      : status === 'failed'
+        ? 'failed'
+        : 'completed'
+}
+
+function normalizeToolStatus(status: unknown): 'running' | 'completed' | 'failed' {
+  return status === 'inProgress'
+    ? 'running'
+    : status === 'failed'
+      ? 'failed'
+      : 'completed'
+}
+
+function assertNever(value: never): never {
+  throw new CodexDisplayProtocolError(`Unsupported Codex thread item type: ${String(value)}`)
+}
+
+function readCodexThreadItemType(item: Record<string, unknown>): CodexThreadItemVariant {
+  const parsed = CodexThreadItemTypeSchema.safeParse(item.type)
+  if (!parsed.success) {
+    throw new CodexDisplayProtocolError(`Unsupported Codex thread item type: ${String(item.type)}`)
+  }
+  return parsed.data
+}
+
+function readCodexItemId(providerTurnId: string, item: Record<string, unknown>): string {
+  if (typeof item.id === 'string' && item.id.length > 0) {
+    return item.id
+  }
+  throw new CodexDisplayProtocolError(
+    `Codex provider item in turn ${providerTurnId} is missing a stable item id.`,
+  )
+}
+
+function stringArray(value: unknown): string[] {
+  if (Array.isArray(value)) {
+    return value.filter((entry): entry is string => typeof entry === 'string')
+  }
+  if (typeof value === 'string') {
+    return [value]
+  }
+  return []
+}
+
+function summarizeFreshAgentItems(items: FreshAgentTranscriptItem[]): string {
+  for (const item of items) {
+    switch (item.kind) {
+      case 'text':
+      case 'thinking':
+        return item.text.slice(0, 140)
+      case 'reasoning':
+        return (item.text ?? item.summary.join('\n') ?? item.content.join('\n')).slice(0, 140)
+      case 'command':
+        return item.command.slice(0, 140)
+      case 'file_change':
+        return 'File change'
+      case 'mcp_tool':
+        return `${item.server}:${item.tool}`.slice(0, 140)
+      case 'dynamic_tool':
+        return item.tool.slice(0, 140)
+      case 'collab_agent':
+        return item.tool.slice(0, 140)
+      case 'web_search':
+        return item.query.slice(0, 140)
+      case 'image_view':
+        return item.path.slice(0, 140)
+      case 'image_generation':
+        return item.result.slice(0, 140)
+      case 'review_mode':
+        return `${item.event} review mode`.slice(0, 140)
+      case 'context_compaction':
+        return 'Context compacted'
+      case 'tool_use':
+        return item.name.slice(0, 140)
+      case 'tool_result':
+        return item.isError ? 'Tool error' : 'Tool result'
+      default: {
+        const neverItem: never = item
+        return String(neverItem)
       }
-      return content.map((part, partIndex) => {
-        const typedPart = part && typeof part === 'object' ? part as Record<string, unknown> : {}
-        if (typedPart.type === 'text') {
-          return {
-            id: `${id}:part:${partIndex}`,
-            kind: 'text' as const,
-            text: typeof typedPart.text === 'string' ? typedPart.text : '',
-          }
-        }
-        return {
-          id: `${id}:part:${partIndex}`,
-          kind: 'text' as const,
-          text: `[${String(typedPart.type ?? 'input')}]`,
-        }
-      })
     }
+  }
+  return ''
+}
+
+function readUserMessageTextParts(item: Record<string, unknown>): Array<{ partIndex: number; text: string }> {
+  const content = Array.isArray(item.content) ? item.content : []
+  const contentParts = content.map((part, partIndex) => {
+    const typedPart = part && typeof part === 'object' && !Array.isArray(part)
+      ? part as Record<string, unknown>
+      : {}
+    if (typedPart.type === 'text' || typedPart.type === 'input_text') {
+      return {
+        partIndex,
+        text: typeof typedPart.text === 'string' ? typedPart.text : '',
+      }
+    }
+    return {
+      partIndex,
+      text: `[${String(typedPart.type ?? 'input')}]`,
+    }
+  })
+  if (contentParts.length > 0) {
+    return contentParts
+  }
+  if (typeof item.text === 'string') {
+    return [{ partIndex: 0, text: item.text }]
+  }
+  if (typeof item.summary === 'string') {
+    return [{ partIndex: 0, text: item.summary }]
+  }
+  return [{ partIndex: 0, text: '' }]
+}
+
+function normalizeCodexItem(
+  providerTurnId: string,
+  item: Record<string, unknown>,
+): CodexNormalizedContribution[] {
+  const type = readCodexThreadItemType(item)
+  const itemId = readCodexItemId(providerTurnId, item)
+
+  switch (type) {
+    case 'userMessage':
+      return readUserMessageTextParts(item).map(({ partIndex, text }) => ({
+        role: 'user',
+        itemId,
+        partIndex,
+        item: {
+          id: `${itemId}:part:${partIndex}`,
+          kind: 'text',
+          text,
+        },
+      }))
     case 'agentMessage':
-      return [{ id, kind: 'text', text: typeof item.text === 'string' ? item.text : '' }]
+      return [{
+        role: 'assistant',
+        itemId,
+        partIndex: 0,
+        item: {
+          id: itemId,
+          kind: 'text',
+          text: typeof item.text === 'string'
+            ? item.text
+            : typeof item.summary === 'string'
+              ? item.summary
+              : '',
+        },
+      }]
     case 'plan':
-      return [{ id, kind: 'text', text: typeof item.text === 'string' ? item.text : '' }]
+      return [{
+        role: 'assistant',
+        itemId,
+        partIndex: 0,
+        item: {
+          id: itemId,
+          kind: 'text',
+          text: typeof item.text === 'string'
+            ? item.text
+            : typeof item.summary === 'string'
+              ? item.summary
+              : '',
+        },
+      }]
     case 'reasoning': {
-      const summary = Array.isArray(item.summary) ? item.summary.filter((value): value is string => typeof value === 'string') : []
-      const content = Array.isArray(item.content) ? item.content.filter((value): value is string => typeof value === 'string') : []
+      const summary = stringArray(item.summary)
+      const content = stringArray(item.content)
       return [{
-        id,
-        kind: 'reasoning',
-        summary,
-        content,
-        text: summary.join('\n') || content.join('\n'),
+        role: 'assistant',
+        itemId,
+        partIndex: 0,
+        item: {
+          id: itemId,
+          kind: 'reasoning',
+          summary,
+          content,
+          text: summary.join('\n') || content.join('\n'),
+        },
       }]
     }
     case 'commandExecution':
       return [{
-        id,
-        kind: 'command',
-        command: typeof item.command === 'string' ? item.command : '',
-        cwd: typeof item.cwd === 'string' ? item.cwd : undefined,
-        status: item.status === 'inProgress' ? 'running' : item.status === 'declined' ? 'declined' : item.status === 'failed' ? 'failed' : 'completed',
-        output: typeof item.aggregatedOutput === 'string' ? item.aggregatedOutput : null,
-        exitCode: typeof item.exitCode === 'number' ? item.exitCode : null,
-        extensions: { codex: item },
+        role: 'tool',
+        itemId,
+        partIndex: 0,
+        item: {
+          id: itemId,
+          kind: 'command',
+          command: typeof item.command === 'string' ? item.command : '',
+          cwd: typeof item.cwd === 'string' ? item.cwd : undefined,
+          status: normalizeCommandStatus(item.status),
+          output: typeof item.aggregatedOutput === 'string' ? item.aggregatedOutput : null,
+          exitCode: typeof item.exitCode === 'number' ? item.exitCode : null,
+          extensions: { codex: item },
+        },
       }]
     case 'fileChange':
       return [{
-        id,
-        kind: 'file_change',
-        status: item.status === 'inProgress' ? 'running' : item.status === 'declined' ? 'declined' : item.status === 'failed' ? 'failed' : 'completed',
-        changes: Array.isArray(item.changes)
-          ? item.changes.filter((change): change is Record<string, unknown> => !!change && typeof change === 'object' && !Array.isArray(change))
-          : [],
-        extensions: { codex: item },
+        role: 'tool',
+        itemId,
+        partIndex: 0,
+        item: {
+          id: itemId,
+          kind: 'file_change',
+          status: normalizeCommandStatus(item.status),
+          changes: Array.isArray(item.changes)
+            ? item.changes.filter((change): change is Record<string, unknown> => !!change && typeof change === 'object' && !Array.isArray(change))
+            : [],
+          extensions: { codex: item },
+        },
       }]
     case 'mcpToolCall':
       return [{
-        id,
-        kind: 'mcp_tool',
-        server: typeof item.server === 'string' ? item.server : '',
-        tool: typeof item.tool === 'string' ? item.tool : '',
-        status: item.status === 'inProgress' ? 'running' : item.status === 'failed' ? 'failed' : 'completed',
-        arguments: item.arguments ?? null,
-        result: item.result,
-        error: item.error,
+        role: 'tool',
+        itemId,
+        partIndex: 0,
+        item: {
+          id: itemId,
+          kind: 'mcp_tool',
+          server: typeof item.server === 'string' ? item.server : '',
+          tool: typeof item.tool === 'string' ? item.tool : '',
+          status: normalizeToolStatus(item.status),
+          arguments: item.arguments ?? null,
+          result: item.result,
+          error: item.error,
+        },
       }]
     case 'dynamicToolCall':
       return [{
-        id,
-        kind: 'dynamic_tool',
-        namespace: typeof item.namespace === 'string' ? item.namespace : null,
-        tool: typeof item.tool === 'string' ? item.tool : '',
-        status: item.status === 'inProgress' ? 'running' : item.status === 'failed' ? 'failed' : 'completed',
-        arguments: item.arguments ?? null,
-        contentItems: Array.isArray(item.contentItems) ? item.contentItems : null,
-        success: typeof item.success === 'boolean' ? item.success : null,
+        role: 'tool',
+        itemId,
+        partIndex: 0,
+        item: {
+          id: itemId,
+          kind: 'dynamic_tool',
+          namespace: typeof item.namespace === 'string' ? item.namespace : null,
+          tool: typeof item.tool === 'string' ? item.tool : '',
+          status: normalizeToolStatus(item.status),
+          arguments: item.arguments ?? null,
+          contentItems: Array.isArray(item.contentItems) ? item.contentItems : null,
+          success: typeof item.success === 'boolean' ? item.success : null,
+        },
       }]
     case 'collabAgentToolCall':
       return [{
-        id,
-        kind: 'collab_agent',
-        tool: String(item.tool ?? ''),
-        status: item.status === 'inProgress' ? 'running' : item.status === 'failed' ? 'failed' : 'completed',
-        senderThreadId: String(item.senderThreadId ?? ''),
-        receiverThreadIds: Array.isArray(item.receiverThreadIds)
-          ? item.receiverThreadIds.filter((value): value is string => typeof value === 'string')
-          : [],
-        prompt: typeof item.prompt === 'string' ? item.prompt : null,
-        model: typeof item.model === 'string' ? item.model : null,
-        reasoningEffort: typeof item.reasoningEffort === 'string' ? item.reasoningEffort : null,
-        agentsStates: item.agentsStates && typeof item.agentsStates === 'object' && !Array.isArray(item.agentsStates)
-          ? item.agentsStates as Record<string, unknown>
-          : {},
+        role: 'tool',
+        itemId,
+        partIndex: 0,
+        item: {
+          id: itemId,
+          kind: 'collab_agent',
+          tool: String(item.tool ?? ''),
+          status: normalizeToolStatus(item.status),
+          senderThreadId: String(item.senderThreadId ?? ''),
+          receiverThreadIds: Array.isArray(item.receiverThreadIds)
+            ? item.receiverThreadIds.filter((value): value is string => typeof value === 'string')
+            : [],
+          prompt: typeof item.prompt === 'string' ? item.prompt : null,
+          model: typeof item.model === 'string' ? item.model : null,
+          reasoningEffort: typeof item.reasoningEffort === 'string' ? item.reasoningEffort : null,
+          agentsStates: item.agentsStates && typeof item.agentsStates === 'object' && !Array.isArray(item.agentsStates)
+            ? item.agentsStates as Record<string, unknown>
+            : {},
+        },
       }]
     case 'webSearch':
       return [{
-        id,
-        kind: 'web_search',
-        query: typeof item.query === 'string' ? item.query : '',
-        action: item.action ?? null,
+        role: 'tool',
+        itemId,
+        partIndex: 0,
+        item: {
+          id: itemId,
+          kind: 'web_search',
+          query: typeof item.query === 'string' ? item.query : '',
+          action: item.action ?? null,
+        },
       }]
     case 'imageView':
-      return [{ id, kind: 'image_view', path: typeof item.path === 'string' ? item.path : '' }]
+      return [{
+        role: 'tool',
+        itemId,
+        partIndex: 0,
+        item: {
+          id: itemId,
+          kind: 'image_view',
+          path: typeof item.path === 'string' ? item.path : '',
+        },
+      }]
     case 'imageGeneration':
       return [{
-        id,
-        kind: 'image_generation',
-        status: String(item.status ?? ''),
-        revisedPrompt: typeof item.revisedPrompt === 'string' ? item.revisedPrompt : null,
-        result: String(item.result ?? ''),
-        savedPath: typeof item.savedPath === 'string' ? item.savedPath : undefined,
+        role: 'tool',
+        itemId,
+        partIndex: 0,
+        item: {
+          id: itemId,
+          kind: 'image_generation',
+          status: String(item.status ?? ''),
+          revisedPrompt: typeof item.revisedPrompt === 'string' ? item.revisedPrompt : null,
+          result: String(item.result ?? ''),
+          savedPath: typeof item.savedPath === 'string' ? item.savedPath : undefined,
+        },
       }]
     case 'enteredReviewMode':
-      return [{ id, kind: 'review_mode', event: 'entered', review: String(item.review ?? '') }]
+      return [{
+        role: 'system',
+        itemId,
+        partIndex: 0,
+        item: {
+          id: itemId,
+          kind: 'review_mode',
+          event: 'entered',
+          review: String(item.review ?? ''),
+        },
+      }]
     case 'exitedReviewMode':
-      return [{ id, kind: 'review_mode', event: 'exited', review: String(item.review ?? '') }]
+      return [{
+        role: 'system',
+        itemId,
+        partIndex: 0,
+        item: {
+          id: itemId,
+          kind: 'review_mode',
+          event: 'exited',
+          review: String(item.review ?? ''),
+        },
+      }]
     case 'contextCompaction':
-      return [{ id, kind: 'context_compaction' }]
+      return [{
+        role: 'system',
+        itemId,
+        partIndex: 0,
+        item: {
+          id: itemId,
+          kind: 'context_compaction',
+        },
+      }]
     case 'hookPrompt':
-      return [{ id, kind: 'text', text: 'Hook prompt' }]
+      return [{
+        role: 'system',
+        itemId,
+        partIndex: 0,
+        item: {
+          id: itemId,
+          kind: 'text',
+          text: typeof item.text === 'string' ? item.text : 'Hook prompt',
+        },
+      }]
     default:
-      throw new Error(`Unsupported Codex thread item type: ${String(item.type)}`)
+      return assertNever(type)
   }
 }
 
-function inferCodexTurnRole(rawItems: Record<string, unknown>[]): FreshAgentTurn['role'] {
-  if (rawItems.some((item) => item.type === 'agentMessage' || item.type === 'reasoning' || item.type === 'plan')) {
-    return 'assistant'
-  }
-  if (rawItems.some((item) => item.type === 'userMessage')) {
-    return 'user'
-  }
-  if (rawItems.some((item) => (
-    item.type === 'commandExecution'
-    || item.type === 'fileChange'
-    || item.type === 'mcpToolCall'
-    || item.type === 'dynamicToolCall'
-    || item.type === 'collabAgentToolCall'
-    || item.type === 'webSearch'
-    || item.type === 'imageView'
-    || item.type === 'imageGeneration'
-  ))) {
-    return 'tool'
+export function classifyCodexItemRole(item: Record<string, unknown>): CodexDisplayRole {
+  const type = readCodexThreadItemType(item)
+  switch (type) {
+    case 'userMessage':
+      return 'user'
+    case 'agentMessage':
+    case 'plan':
+    case 'reasoning':
+      return 'assistant'
+    case 'commandExecution':
+    case 'fileChange':
+    case 'mcpToolCall':
+    case 'dynamicToolCall':
+    case 'collabAgentToolCall':
+    case 'webSearch':
+    case 'imageView':
+    case 'imageGeneration':
+      return 'tool'
+    case 'hookPrompt':
+    case 'enteredReviewMode':
+    case 'exitedReviewMode':
+    case 'contextCompaction':
+      return 'system'
+    default:
+      return assertNever(type)
   }
-  return undefined
 }
 
 function readCodexTurnError(rawTurn: Record<string, unknown>): string | undefined {
@@ -190,49 +493,196 @@ function readCodexTurnError(rawTurn: Record<string, unknown>): string | undefine
   return String(error)
 }
 
-export function normalizeCodexTurn(
+function createSyntheticPendingRow(kind: Exclude<CodexDisplaySyntheticKind, 'submitted-input'>, text: string): CodexPendingRow {
+  return {
+    role: 'assistant',
+    itemIds: [],
+    partIndexes: [],
+    items: [{
+      id: `codex-display-synthetic:${kind}`,
+      kind: 'text',
+      text,
+    }],
+    syntheticKind: kind,
+  }
+}
+
+function buildDisplayTurn(input: {
+  providerTurnId: string
+  ordinal: number
+  model?: string
+  threadId: string
+  secret: string
+  row: CodexPendingRow
+  submittedRequestId?: string | number
+}): FreshAgentTurn & { requestId?: string | number; syntheticKind?: CodexDisplaySyntheticKind } {
+  const { row } = input
+  const requestId = input.submittedRequestId
+  const syntheticKind = requestId !== undefined && row.role === 'user'
+    ? 'submitted-input'
+    : row.syntheticKind
+  const turnId = createCodexDisplayId({
+    secret: input.secret,
+    threadId: input.threadId,
+    providerTurnId: input.providerTurnId,
+    role: row.role,
+    itemIds: requestId !== undefined && row.role === 'user' ? undefined : row.itemIds,
+    partIndexes: requestId !== undefined && row.role === 'user' ? undefined : row.partIndexes,
+    syntheticKind,
+    ...(requestId !== undefined ? { requestId } : {}),
+  })
+
+  return {
+    id: turnId,
+    turnId,
+    ordinal: input.ordinal,
+    source: 'durable',
+    role: row.role,
+    ...(input.model ? { model: input.model } : {}),
+    summary: summarizeFreshAgentItems(row.items),
+    items: row.items,
+    ...(syntheticKind ? { syntheticKind } : {}),
+    ...(requestId !== undefined ? { requestId } : {}),
+  }
+}
+
+export function createCodexDisplayId(identity: CodexDisplayIdentity): string {
+  const payload = JSON.stringify({
+    threadId: identity.threadId,
+    providerTurnId: identity.providerTurnId,
+    role: identity.role,
+    parts: (identity.itemIds ?? []).map((itemId, index) => ({
+      itemId,
+      partIndex: identity.partIndexes?.[index] ?? 0,
+    })),
+    syntheticKind: identity.syntheticKind ?? null,
+    requestId: identity.requestId ?? null,
+  })
+  const handle = createHmac('sha256', identity.secret)
+    .update(payload)
+    .digest()
+    .subarray(0, 16)
+    .toString('base64url')
+
+  return `${CODEX_DISPLAY_ID_PREFIX}${handle}`
+}
+
+export function parseCodexDisplayIdHandle(turnId: string): { handle: string } | null {
+  const match = turnId.match(new RegExp(`^${CODEX_DISPLAY_ID_PREFIX.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}([A-Za-z0-9_-]{${CODEX_DISPLAY_HANDLE_LENGTH}})$`))
+  return match ? { handle: match[1] } : null
+}
+
+export function normalizeCodexDisplayTurns(
   rawTurn: Record<string, unknown>,
   ordinal = 0,
-  options: { model?: string } = {},
-): FreshAgentTurn {
-  const turnId = String(rawTurn.id ?? `turn:${ordinal}`)
+  options: NormalizeCodexDisplayTurnsOptions = {},
+): { turns: FreshAgentTurn[]; displayRows: CodexDisplayRow[] } {
+  const providerTurnId = String(rawTurn.id ?? `turn:${ordinal}`)
+  const threadId = options.threadId ?? providerTurnId
+  const secret = options.secret ?? DEFAULT_CODEX_DISPLAY_SECRET
   const model = typeof rawTurn.model === 'string' && rawTurn.model.length > 0
     ? rawTurn.model
     : options.model
   const rawItems = Array.isArray(rawTurn.items)
     ? rawTurn.items.filter((item): item is Record<string, unknown> => !!item && typeof item === 'object' && !Array.isArray(item))
     : []
-  const items = rawItems.flatMap((item, index) => normalizeCodexItem(turnId, item, index))
-  const hasAssistantOutput = rawItems.some((item) => item.type === 'agentMessage' || item.type === 'reasoning' || item.type === 'plan')
+
+  const pendingRows: CodexPendingRow[] = []
+  for (const rawItem of rawItems) {
+    const role = classifyCodexItemRole(rawItem)
+    const normalizedItems = normalizeCodexItem(providerTurnId, rawItem)
+    const currentRow = pendingRows.at(-1)
+    if (!currentRow || currentRow.role !== role || currentRow.syntheticKind) {
+      pendingRows.push({
+        role,
+        itemIds: normalizedItems.map((item) => item.itemId),
+        partIndexes: normalizedItems.map((item) => item.partIndex),
+        items: normalizedItems.map((item) => item.item),
+      })
+      continue
+    }
+    currentRow.itemIds.push(...normalizedItems.map((item) => item.itemId))
+    currentRow.partIndexes.push(...normalizedItems.map((item) => item.partIndex))
+    currentRow.items.push(...normalizedItems.map((item) => item.item))
+  }
+
+  const hasAssistantOutput = rawItems.some((item) => {
+    const role = classifyCodexItemRole(item)
+    return role === 'assistant'
+  })
+  const hasUserOutput = rawItems.some((item) => classifyCodexItemRole(item) === 'user')
   const turnError = readCodexTurnError(rawTurn)
   if (turnError) {
-    items.push({
-      id: `${turnId}:error`,
-      kind: 'text',
-      text: `Codex turn failed: ${turnError}`,
-    })
+    pendingRows.push(createSyntheticPendingRow('error', `Codex turn failed: ${turnError}`))
   } else if (
     rawTurn.status === 'completed'
-    && rawItems.some((item) => item.type === 'userMessage')
-    && rawItems.every((item) => item.type === 'userMessage')
+    && hasUserOutput
+    && rawItems.every((item) => classifyCodexItemRole(item) === 'user')
     && !hasAssistantOutput
   ) {
-    items.push({
-      id: `${turnId}:empty-response`,
-      kind: 'text',
-      text: 'Codex completed this turn without recording an assistant response.',
+    pendingRows.push(createSyntheticPendingRow(
+      'empty-response',
+      'Codex completed this turn without recording an assistant response.',
+    ))
+  }
+
+  const submittedRequestId = options.submittedRequestIdByProviderTurnId?.get(providerTurnId)
+  let submittedAliasConsumed = false
+  const turns = pendingRows.map((row, rowIndex) => {
+    const useSubmittedAlias = submittedRequestId !== undefined && !submittedAliasConsumed && row.role === 'user'
+    if (useSubmittedAlias) {
+      submittedAliasConsumed = true
+    }
+    return buildDisplayTurn({
+      providerTurnId,
+      ordinal: ordinal + rowIndex,
+      model,
+      threadId,
+      secret,
+      row,
+      ...(useSubmittedAlias ? { submittedRequestId } : {}),
     })
+  })
+
+  const displayRows = turns.map((turn, index) => ({
+    turnId: turn.turnId,
+    role: turn.role ?? 'assistant',
+    providerTurnId,
+    itemIds: pendingRows[index]?.itemIds ?? [],
+    partIndexes: pendingRows[index]?.partIndexes ?? [],
+    items: turn.items,
+    ...(typeof turn.syntheticKind === 'string' ? { syntheticKind: turn.syntheticKind } : {}),
+    ...(turn.requestId !== undefined ? { requestId: turn.requestId } : {}),
+  }))
+
+  return { turns, displayRows }
+}
+
+export function normalizeCodexTurn(
+  rawTurn: Record<string, unknown>,
+  ordinal = 0,
+  options: NormalizeCodexDisplayTurnsOptions = {},
+): FreshAgentTurn {
+  const normalized = normalizeCodexDisplayTurns(rawTurn, ordinal, options).turns[0]
+  if (normalized) {
+    const { syntheticKind: _syntheticKind, requestId: _requestId, ...turn } = normalized as FreshAgentTurn & {
+      syntheticKind?: CodexDisplaySyntheticKind
+      requestId?: string | number
+    }
+    return turn
   }
-  const firstText = items.find((item): item is Extract<FreshAgentTranscriptItem, { kind: 'text' }> => item.kind === 'text')
+  const providerTurnId = String(rawTurn.id ?? `turn:${ordinal}`)
+  const model = typeof rawTurn.model === 'string' && rawTurn.model.length > 0
+    ? rawTurn.model
+    : options.model
   return {
-    id: turnId,
-    turnId,
+    id: providerTurnId,
+    turnId: providerTurnId,
     ordinal,
     source: 'durable',
-    role: inferCodexTurnRole(rawItems),
     ...(model ? { model } : {}),
-    summary: firstText?.text.slice(0, 140) ?? '',
-    items,
+    summary: '',
+    items: [],
   }
 }
 
@@ -242,12 +692,27 @@ export function normalizeCodexTurnPage(input: {
   rawPage: { turns?: unknown[]; nextCursor?: string | null; backwardsCursor?: string | null }
   model?: string
   modelByTurn?: Map<string, string>
+  secret?: string
+  submittedRequestIdByProviderTurnId?: ReadonlyMap<string, string | number>
 }) {
   const turns = (Array.isArray(input.rawPage.turns) ? input.rawPage.turns : [])
     .filter((turn): turn is Record<string, unknown> => !!turn && typeof turn === 'object' && !Array.isArray(turn))
-    .map((turn, index) => normalizeCodexTurn(turn, index, {
+    .flatMap((turn) => normalizeCodexDisplayTurns(turn, 0, {
+      threadId: input.threadId,
+      secret: input.secret,
+      submittedRequestIdByProviderTurnId: input.submittedRequestIdByProviderTurnId,
       model: (typeof turn.id === 'string' ? input.modelByTurn?.get(turn.id) : undefined) ?? input.model,
-    }))
+    }).turns)
+    .map((turn, index) => {
+      const { syntheticKind: _syntheticKind, requestId: _requestId, ...parsedTurn } = turn as FreshAgentTurn & {
+        syntheticKind?: CodexDisplaySyntheticKind
+        requestId?: string | number
+      }
+      return {
+        ...parsedTurn,
+        ordinal: index,
+      }
+    })
 
   return FreshAgentTurnPageSchema.parse({
     sessionType: 'freshcodex',
@@ -264,11 +729,32 @@ export function normalizeCodexTurnPage(input: {
 export function normalizeCodexTurnBody(input: {
   threadId: string
   revision: number
+  requestedTurnId?: string
   rawTurn: Record<string, unknown>
   model?: string
+  secret?: string
+  submittedRequestIdByProviderTurnId?: ReadonlyMap<string, string | number>
 }) {
+  const { turns } = normalizeCodexDisplayTurns(input.rawTurn, 0, {
+    threadId: input.threadId,
+    model: input.model,
+    secret: input.secret,
+    submittedRequestIdByProviderTurnId: input.submittedRequestIdByProviderTurnId,
+  })
+  const selectedTurn = input.requestedTurnId
+    ? turns.find((turn) => turn.turnId === input.requestedTurnId)
+    : turns[0]
+  if (!selectedTurn) {
+    throw new CodexDisplayTurnNotFoundError(
+      `Codex display turn ${input.requestedTurnId ?? '(missing requested turn id)'} was not found in provider turn ${String(input.rawTurn.id ?? 'unknown')}.`,
+    )
+  }
+  const { syntheticKind: _syntheticKind, requestId: _requestId, ...turn } = selectedTurn as FreshAgentTurn & {
+    syntheticKind?: CodexDisplaySyntheticKind
+    requestId?: string | number
+  }
   return FreshAgentTurnBodySchema.parse({
-    ...normalizeCodexTurn(input.rawTurn, 0, { model: input.model }),
+    ...turn,
     sessionType: 'freshcodex',
     provider: 'codex',
     threadId: input.threadId,
diff --git a/test/unit/server/fresh-agent/codex-normalize.test.ts b/test/unit/server/fresh-agent/codex-normalize.test.ts
index 7f53993c5..8d94afbba 100644
--- a/test/unit/server/fresh-agent/codex-normalize.test.ts
+++ b/test/unit/server/fresh-agent/codex-normalize.test.ts
@@ -1,10 +1,35 @@
 import { describe, expect, it } from 'vitest'
 
+import { CodexThreadItemTypeSchema } from '../../../../server/coding-cli/codex-app-server/protocol.js'
 import {
+  createCodexDisplayId,
+  normalizeCodexDisplayTurns,
   normalizeCodexThreadSnapshot,
   normalizeCodexTurn,
+  normalizeCodexTurnBody,
+  parseCodexDisplayIdHandle,
 } from '../../../../server/fresh-agent/adapters/codex/normalize.js'
 
+const DISPLAY_SECRET = 'task-2-deterministic-secret'
+const THREAD_ID = 'thread-codex-1'
+
+function normalizeDisplayTurns(
+  rawTurn: Record<string, unknown>,
+  overrides: {
+    model?: string
+    secret?: string
+    threadId?: string
+    submittedRequestIdByProviderTurnId?: Map<string, string | number>
+  } = {},
+) {
+  return normalizeCodexDisplayTurns(rawTurn, 0, {
+    model: 'gpt-5.4-mini',
+    secret: DISPLAY_SECRET,
+    threadId: THREAD_ID,
+    ...overrides,
+  })
+}
+
 describe('Codex fresh-agent normalization', () => {
   it('normalizes codex fork, review, worktree, and child-thread metadata into the shared snapshot', () => {
     const snapshot = normalizeCodexThreadSnapshot({
@@ -59,7 +84,7 @@ describe('Codex fresh-agent normalization', () => {
     expect(snapshot.diffs[0]).toMatchObject({ path: 'src/app.ts' })
   })
 
-  it('surfaces the Codex turn model in the shared turn state', () => {
+  it('surfaces the Codex turn model in the shared turn state for single-row turns', () => {
     const turn = normalizeCodexTurn({
       id: 'turn-1',
       model: 'gpt-5.4-mini',
@@ -73,12 +98,12 @@ describe('Codex fresh-agent normalization', () => {
     })
 
     expect(turn).toMatchObject({
-      id: 'turn-1',
-      turnId: 'turn-1',
       model: 'gpt-5.4-mini',
       role: 'assistant',
       summary: 'Done',
     })
+    expect(turn.turnId).toMatch(/^codex-display:v1:/)
+    expect(turn.id).toBe(turn.turnId)
   })
 
   it('uses the active runtime model as a fallback when Codex omits per-turn model metadata', () => {
@@ -96,68 +121,391 @@ describe('Codex fresh-agent normalization', () => {
     expect(turn.model).toBe('gpt-5.4-mini')
   })
 
-  it('marks user-only Codex turns and explains an empty assistant response', () => {
-    const turn = normalizeCodexTurn({
-      id: 'turn-empty',
+  it('segments mixed user, reasoning, and agent output into user then assistant display rows', () => {
+    const { turns, displayRows } = normalizeDisplayTurns({
+      id: 'turn-mixed',
       status: 'completed',
-      items: [{
-        id: 'item-1',
-        type: 'userMessage',
-        content: [{ type: 'text', text: 'Write a temp file.' }],
-      }],
+      items: [
+        {
+          id: 'item-user',
+          type: 'userMessage',
+          content: [{ type: 'text', text: 'Review the diff.' }],
+        },
+        {
+          id: 'item-reasoning',
+          type: 'reasoning',
+          summary: ['Comparing changed files'],
+          content: ['Walking the patch'],
+        },
+        {
+          id: 'item-agent',
+          type: 'agentMessage',
+          text: 'I found two regressions.',
+        },
+      ],
     })
 
-    expect(turn.role).toBe('user')
-    expect(turn.items).toEqual([
-      { id: 'item-1:part:0', kind: 'text', text: 'Write a temp file.' },
-      {
-        id: 'turn-empty:empty-response',
-        kind: 'text',
-        text: 'Codex completed this turn without recording an assistant response.',
-      },
+    expect(turns).toHaveLength(2)
+    expect(turns.map((turn) => turn.role)).toEqual(['user', 'assistant'])
+    expect(turns[0]?.items).toEqual([
+      { id: 'item-user:part:0', kind: 'text', text: 'Review the diff.' },
     ])
+    expect(turns[1]?.items.map((item) => item.kind)).toEqual(['reasoning', 'text'])
+    expect(displayRows.map((row) => row.role)).toEqual(['user', 'assistant'])
   })
 
-  it('does not add an empty response sentinel to user turns with tool output', () => {
-    const turn = normalizeCodexTurn({
-      id: 'turn-tool-only',
+  it('uses thread-bound display ids for the same native provider turn id', () => {
+    const first = createCodexDisplayId({
+      secret: DISPLAY_SECRET,
+      threadId: 'thread-alpha',
+      providerTurnId: 'turn-shared',
+      role: 'assistant',
+      itemIds: ['item-agent'],
+      partIndexes: [0],
+    })
+    const second = createCodexDisplayId({
+      secret: DISPLAY_SECRET,
+      threadId: 'thread-beta',
+      providerTurnId: 'turn-shared',
+      role: 'assistant',
+      itemIds: ['item-agent'],
+      partIndexes: [0],
+    })
+
+    expect(first).not.toBe(second)
+  })
+
+  it('keeps display ids short and opaque to native ids, prompt text, and cursor payloads', () => {
+    const turnId = createCodexDisplayId({
+      secret: DISPLAY_SECRET,
+      threadId: THREAD_ID,
+      providerTurnId: 'provider-turn-123',
+      role: 'user',
+      itemIds: ['provider-item-987'],
+      partIndexes: [0],
+    })
+    const parsed = parseCodexDisplayIdHandle(turnId)
+    const decodedHandle = parsed ? Buffer.from(parsed.handle, 'base64url').toString('utf8') : ''
+
+    expect(turnId.length).toBeLessThan(48)
+    expect(turnId).not.toContain('provider-turn-123')
+    expect(turnId).not.toContain('provider-item-987')
+    expect(turnId).not.toContain('printenv SECRET_TOKEN')
+    expect(turnId).not.toContain('cursor:opaque-payload')
+    expect(decodedHandle).not.toContain('provider-turn-123')
+    expect(decodedHandle).not.toContain('provider-item-987')
+    expect(decodedHandle).not.toContain('printenv SECRET_TOKEN')
+    expect(decodedHandle).not.toContain('cursor:opaque-payload')
+  })
+
+  it('preserves existing display ids when unrelated rows are inserted later in the provider turn', () => {
+    const base = normalizeDisplayTurns({
+      id: 'turn-inserted',
       status: 'completed',
       items: [
         {
-          id: 'item-1',
+          id: 'item-user',
+          type: 'userMessage',
+          content: [{ type: 'text', text: 'Run the tests.' }],
+        },
+        {
+          id: 'item-command',
+          type: 'commandExecution',
+          command: 'npm test',
+          status: 'completed',
+          aggregatedOutput: 'ok',
+          exitCode: 0,
+        },
+      ],
+    }).turns
+    const expanded = normalizeDisplayTurns({
+      id: 'turn-inserted',
+      status: 'completed',
+      items: [
+        {
+          id: 'item-user',
           type: 'userMessage',
-          content: [{ type: 'text', text: 'Write a temp file.' }],
+          content: [{ type: 'text', text: 'Run the tests.' }],
+        },
+        {
+          id: 'item-agent',
+          type: 'agentMessage',
+          text: 'Running them now.',
+        },
+        {
+          id: 'item-command',
+          type: 'commandExecution',
+          command: 'npm test',
+          status: 'completed',
+          aggregatedOutput: 'ok',
+          exitCode: 0,
+        },
+      ],
+    }).turns
+
+    expect(base.map((turn) => turn.role)).toEqual(['user', 'tool'])
+    expect(expanded.map((turn) => turn.role)).toEqual(['user', 'assistant', 'tool'])
+    expect(base[0]?.turnId).toBe(expanded[0]?.turnId)
+    expect(base[1]?.turnId).toBe(expanded[2]?.turnId)
+  })
+
+  it('segments assistant output away from later tool items', () => {
+    const { turns } = normalizeDisplayTurns({
+      id: 'turn-tools',
+      status: 'completed',
+      items: [
+        {
+          id: 'item-agent',
+          type: 'agentMessage',
+          text: 'Applied the patch.',
         },
         {
-          id: 'item-2',
+          id: 'item-command',
           type: 'commandExecution',
-          command: 'cat temp.txt',
+          command: 'npm test',
           status: 'completed',
           aggregatedOutput: 'ok',
           exitCode: 0,
         },
+        {
+          id: 'item-file-change',
+          type: 'fileChange',
+          status: 'completed',
+          changes: [{ path: 'src/app.ts', changeType: 'modified' }],
+        },
       ],
     })
 
-    expect(turn.items.map((item) => item.id)).not.toContain('turn-tool-only:empty-response')
+    expect(turns).toHaveLength(2)
+    expect(turns.map((turn) => turn.role)).toEqual(['assistant', 'tool'])
+    expect(turns[1]?.items.map((item) => item.kind)).toEqual(['command', 'file_change'])
   })
 
-  it('surfaces Codex turn errors in transcript text', () => {
-    const turn = normalizeCodexTurn({
+  it('classifies every Codex thread item type into a normalized display role', () => {
+    const factories: Record<(typeof CodexThreadItemTypeSchema.options)[number], Record<string, unknown>> = {
+      userMessage: { type: 'userMessage', content: [{ type: 'text', text: 'Prompt' }] },
+      hookPrompt: { type: 'hookPrompt' },
+      agentMessage: { type: 'agentMessage', text: 'Done' },
+      plan: { type: 'plan', text: '1. Do the work' },
+      reasoning: { type: 'reasoning', summary: ['Thinking'], content: ['Longer trace'] },
+      commandExecution: { type: 'commandExecution', command: 'npm test', status: 'completed', aggregatedOutput: 'ok', exitCode: 0 },
+      fileChange: { type: 'fileChange', status: 'completed', changes: [{ path: 'src/app.ts' }] },
+      mcpToolCall: { type: 'mcpToolCall', server: 'docs', tool: 'search', status: 'completed', arguments: { q: 'codex' }, result: { ok: true } },
+      dynamicToolCall: { type: 'dynamicToolCall', namespace: 'tools', tool: 'exec', status: 'completed', arguments: { cmd: 'pwd' }, contentItems: [], success: true },
+      collabAgentToolCall: { type: 'collabAgentToolCall', tool: 'dispatch', status: 'completed', senderThreadId: 'thread-parent', receiverThreadIds: ['thread-child'], agentsStates: {} },
+      webSearch: { type: 'webSearch', query: 'freshell' },
+      imageView: { type: 'imageView', path: '/tmp/screenshot.png' },
+      imageGeneration: { type: 'imageGeneration', status: 'completed', result: 'saved', revisedPrompt: 'prompt' },
+      enteredReviewMode: { type: 'enteredReviewMode', review: 'security' },
+      exitedReviewMode: { type: 'exitedReviewMode', review: 'security' },
+      contextCompaction: { type: 'contextCompaction' },
+    }
+    const expectedRoles: Record<(typeof CodexThreadItemTypeSchema.options)[number], string> = {
+      userMessage: 'user',
+      hookPrompt: 'system',
+      agentMessage: 'assistant',
+      plan: 'assistant',
+      reasoning: 'assistant',
+      commandExecution: 'tool',
+      fileChange: 'tool',
+      mcpToolCall: 'tool',
+      dynamicToolCall: 'tool',
+      collabAgentToolCall: 'tool',
+      webSearch: 'tool',
+      imageView: 'tool',
+      imageGeneration: 'tool',
+      enteredReviewMode: 'system',
+      exitedReviewMode: 'system',
+      contextCompaction: 'system',
+    }
+
+    for (const type of CodexThreadItemTypeSchema.options) {
+      const result = normalizeDisplayTurns({
+        id: `turn-${type}`,
+        status: 'inProgress',
+        items: [{ id: `item-${type}`, ...factories[type] }],
+      })
+
+      expect(result.turns).toHaveLength(1)
+      expect(result.turns[0]?.role).toBe(expectedRoles[type])
+    }
+  })
+
+  it('extracts user text from content, then input_text, then text, then summary', () => {
+    const fromContent = normalizeDisplayTurns({
+      id: 'turn-content',
+      status: 'completed',
+      items: [{
+        id: 'item-user',
+        type: 'userMessage',
+        text: 'fallback text',
+        summary: 'fallback summary',
+        content: [{ type: 'text', text: 'from content array' }],
+      }],
+    }).turns[0]
+    const fromInputText = normalizeDisplayTurns({
+      id: 'turn-input-text',
+      status: 'completed',
+      items: [{
+        id: 'item-user',
+        type: 'userMessage',
+        content: [{ type: 'input_text', text: 'from input_text part' }],
+      }],
+    }).turns[0]
+    const fromText = normalizeDisplayTurns({
+      id: 'turn-text',
+      status: 'completed',
+      items: [{
+        id: 'item-user',
+        type: 'userMessage',
+        text: 'from top-level text',
+      }],
+    }).turns[0]
+    const fromSummary = normalizeDisplayTurns({
+      id: 'turn-summary',
+      status: 'completed',
+      items: [{
+        id: 'item-user',
+        type: 'userMessage',
+        summary: 'from top-level summary',
+      }],
+    }).turns[0]
+
+    expect(fromContent?.items[0]).toMatchObject({ kind: 'text', text: 'from content array' })
+    expect(fromInputText?.items[0]).toMatchObject({ kind: 'text', text: 'from input_text part' })
+    expect(fromText?.items[0]).toMatchObject({ kind: 'text', text: 'from top-level text' })
+    expect(fromSummary?.items[0]).toMatchObject({ kind: 'text', text: 'from top-level summary' })
+  })
+
+  it('adds an assistant empty-response sentinel after completed user-only turns', () => {
+    const turns = normalizeDisplayTurns({
+      id: 'turn-empty',
+      status: 'completed',
+      items: [{
+        id: 'item-user',
+        type: 'userMessage',
+        content: [{ type: 'text', text: 'Write a temp file.' }],
+      }],
+    }).turns
+
+    expect(turns.map((turn) => turn.role)).toEqual(['user', 'assistant'])
+    expect(turns[1]?.items).toEqual([
+      {
+        id: 'codex-display-synthetic:empty-response',
+        kind: 'text',
+        text: 'Codex completed this turn without recording an assistant response.',
+      },
+    ])
+  })
+
+  it('adds an assistant error row after failed user-only turns', () => {
+    const turns = normalizeDisplayTurns({
       id: 'turn-error',
       status: 'failed',
       error: { message: 'model rejected the request' },
       items: [{
-        id: 'item-1',
+        id: 'item-user',
         type: 'userMessage',
         content: [{ type: 'text', text: 'Do the thing.' }],
       }],
+    }).turns
+
+    expect(turns.map((turn) => turn.role)).toEqual(['user', 'assistant'])
+    expect(turns[1]?.items).toEqual([
+      {
+        id: 'codex-display-synthetic:error',
+        kind: 'text',
+        text: 'Codex turn failed: model rejected the request',
+      },
+    ])
+  })
+
+  it('throws a protocol error when a provider item that participates in identity is missing an id', () => {
+    expect(() => normalizeDisplayTurns({
+      id: 'turn-missing-item-id',
+      status: 'completed',
+      items: [{
+        type: 'userMessage',
+        content: [{ type: 'text', text: 'Prompt' }],
+      }],
+    })).toThrow(/protocol|stable item id/i)
+  })
+
+  it('reuses submitted user display ids when the provider userMessage later materializes', () => {
+    const requestId = 'request-42'
+    const submittedTurnId = createCodexDisplayId({
+      secret: DISPLAY_SECRET,
+      threadId: THREAD_ID,
+      providerTurnId: 'turn-submitted',
+      role: 'user',
+      syntheticKind: 'submitted-input',
+      requestId,
     })
+    const turns = normalizeDisplayTurns({
+      id: 'turn-submitted',
+      status: 'completed',
+      items: [{
+        id: 'item-user',
+        type: 'userMessage',
+        content: [{ type: 'text', text: 'Ship it.' }],
+      }],
+    }, {
+      submittedRequestIdByProviderTurnId: new Map([['turn-submitted', requestId]]),
+    }).turns
+
+    expect(turns[0]?.turnId).toBe(submittedTurnId)
+  })
+
+  it('rejects malformed codex-display prefixes as invalid public ids', () => {
+    expect(parseCodexDisplayIdHandle('codex-display:not-a-valid-envelope')).toBeNull()
+  })
+
+  it('selects the exact requested display row for turn bodies and throws when it is absent', () => {
+    const rawTurn = {
+      id: 'turn-body',
+      status: 'completed',
+      items: [
+        {
+          id: 'item-user',
+          type: 'userMessage',
+          content: [{ type: 'text', text: 'Review the diff.' }],
+        },
+        {
+          id: 'item-reasoning',
+          type: 'reasoning',
+          summary: ['Comparing changed files'],
+          content: ['Walking the patch'],
+        },
+        {
+          id: 'item-agent',
+          type: 'agentMessage',
+          text: 'I found two regressions.',
+        },
+      ],
+    }
+    const turns = normalizeDisplayTurns(rawTurn).turns
+    const assistantTurnId = turns[1]?.turnId
+    expect(assistantTurnId).toBeTruthy()
 
-    expect(turn.items.at(-1)).toEqual({
-      id: 'turn-error:error',
-      kind: 'text',
-      text: 'Codex turn failed: model rejected the request',
+    const assistantBody = normalizeCodexTurnBody({
+      threadId: THREAD_ID,
+      revision: 9,
+      requestedTurnId: assistantTurnId ?? '',
+      rawTurn,
+      model: 'gpt-5.4-mini',
+      secret: DISPLAY_SECRET,
     })
+
+    expect(assistantBody.turnId).toBe(assistantTurnId)
+    expect(assistantBody.role).toBe('assistant')
+    expect(assistantBody.items.map((item) => item.kind)).toEqual(['reasoning', 'text'])
+    expect(() => normalizeCodexTurnBody({
+      threadId: THREAD_ID,
+      revision: 9,
+      requestedTurnId: 'codex-display:v1:not-found-handle',
+      rawTurn,
+      model: 'gpt-5.4-mini',
+      secret: DISPLAY_SECRET,
+    })).toThrow(/not found/i)
   })
 })

From d40a609a03c9c619bb77b93216ef0cb6af9f58e6 Mon Sep 17 00:00:00 2001
From: Codex <codex@openai.com>
Date: Fri, 19 Jun 2026 02:02:35 -0700
Subject: [PATCH 20/33] fix(fresh-agent): keep text item id in turn text
 predicate

---
 shared/fresh-agent-turns.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/shared/fresh-agent-turns.ts b/shared/fresh-agent-turns.ts
index 2085e5924..957a7183f 100644
--- a/shared/fresh-agent-turns.ts
+++ b/shared/fresh-agent-turns.ts
@@ -6,7 +6,7 @@ export function getFreshAgentDisplayTurnKey(turn: Pick<FreshAgentTurn, 'turnId'
 
 export function freshAgentTurnText(turn: Pick<FreshAgentTurn, 'summary' | 'items'>): string {
   const textItems = turn.items
-    .filter((item): item is { kind: 'text'; text: string } => item.kind === 'text')
+    .filter((item): item is Extract<FreshAgentTurn['items'][number], { kind: 'text' }> => item.kind === 'text')
     .map((item) => item.text)
   const text = textItems.join(' ')
   return textItems.length > 0 ? text : turn.summary

From d809abe8baf41e173a3e7151b23eaa24b03aeca8 Mon Sep 17 00:00:00 2001
From: Codex <codex@openai.com>
Date: Fri, 19 Jun 2026 02:09:18 -0700
Subject: [PATCH 21/33] fix: require codex display turn ids and secrets

---
 server/fresh-agent/adapters/codex/adapter.ts  |  1 +
 .../fresh-agent/adapters/codex/normalize.ts   | 25 +++++--
 .../fresh-agent/codex-normalize.test.ts       | 71 ++++++++++++++++++-
 3 files changed, 88 insertions(+), 9 deletions(-)

diff --git a/server/fresh-agent/adapters/codex/adapter.ts b/server/fresh-agent/adapters/codex/adapter.ts
index 12c5e3ff9..77b74146c 100644
--- a/server/fresh-agent/adapters/codex/adapter.ts
+++ b/server/fresh-agent/adapters/codex/adapter.ts
@@ -581,6 +581,7 @@ export function createCodexFreshAgentAdapter(deps: {
       return normalizeCodexTurnBody({
         threadId: thread.threadId,
         revision,
+        requestedTurnId: thread.turnId,
         rawTurn,
         model: typeof rawTurn.id === 'string'
           ? modelByTurnByThread.get(thread.threadId)?.get(rawTurn.id)
diff --git a/server/fresh-agent/adapters/codex/normalize.ts b/server/fresh-agent/adapters/codex/normalize.ts
index f1c7d0e39..51ebeef3e 100644
--- a/server/fresh-agent/adapters/codex/normalize.ts
+++ b/server/fresh-agent/adapters/codex/normalize.ts
@@ -37,7 +37,6 @@ type CodexThreadItemVariant = (typeof CodexThreadItemTypeSchema.options)[number]
 
 const CODEX_DISPLAY_ID_PREFIX = 'codex-display:v1:'
 const CODEX_DISPLAY_HANDLE_LENGTH = 22
-const DEFAULT_CODEX_DISPLAY_SECRET = 'codex-display-default-secret'
 
 export class CodexDisplayProtocolError extends Error {
   constructor(message: string) {
@@ -46,6 +45,13 @@ export class CodexDisplayProtocolError extends Error {
   }
 }
 
+export class CodexDisplayConfigError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'CodexDisplayConfigError'
+  }
+}
+
 export class CodexDisplayTurnNotFoundError extends Error {
   constructor(message: string) {
     super(message)
@@ -119,6 +125,13 @@ function assertNever(value: never): never {
   throw new CodexDisplayProtocolError(`Unsupported Codex thread item type: ${String(value)}`)
 }
 
+function readRequiredCodexDisplaySecret(secret: string | undefined): string {
+  if (typeof secret === 'string' && secret.trim().length > 0) {
+    return secret
+  }
+  throw new CodexDisplayConfigError('Codex display-turn normalization requires a non-empty adapter-supplied display-id secret.')
+}
+
 function readCodexThreadItemType(item: Record<string, unknown>): CodexThreadItemVariant {
   const parsed = CodexThreadItemTypeSchema.safeParse(item.type)
   if (!parsed.success) {
@@ -579,7 +592,7 @@ export function normalizeCodexDisplayTurns(
 ): { turns: FreshAgentTurn[]; displayRows: CodexDisplayRow[] } {
   const providerTurnId = String(rawTurn.id ?? `turn:${ordinal}`)
   const threadId = options.threadId ?? providerTurnId
-  const secret = options.secret ?? DEFAULT_CODEX_DISPLAY_SECRET
+  const secret = readRequiredCodexDisplaySecret(options.secret)
   const model = typeof rawTurn.model === 'string' && rawTurn.model.length > 0
     ? rawTurn.model
     : options.model
@@ -729,7 +742,7 @@ export function normalizeCodexTurnPage(input: {
 export function normalizeCodexTurnBody(input: {
   threadId: string
   revision: number
-  requestedTurnId?: string
+  requestedTurnId: string
   rawTurn: Record<string, unknown>
   model?: string
   secret?: string
@@ -741,12 +754,10 @@ export function normalizeCodexTurnBody(input: {
     secret: input.secret,
     submittedRequestIdByProviderTurnId: input.submittedRequestIdByProviderTurnId,
   })
-  const selectedTurn = input.requestedTurnId
-    ? turns.find((turn) => turn.turnId === input.requestedTurnId)
-    : turns[0]
+  const selectedTurn = turns.find((turn) => turn.turnId === input.requestedTurnId)
   if (!selectedTurn) {
     throw new CodexDisplayTurnNotFoundError(
-      `Codex display turn ${input.requestedTurnId ?? '(missing requested turn id)'} was not found in provider turn ${String(input.rawTurn.id ?? 'unknown')}.`,
+      `Codex display turn ${input.requestedTurnId} was not found in provider turn ${String(input.rawTurn.id ?? 'unknown')}.`,
     )
   }
   const { syntheticKind: _syntheticKind, requestId: _requestId, ...turn } = selectedTurn as FreshAgentTurn & {
diff --git a/test/unit/server/fresh-agent/codex-normalize.test.ts b/test/unit/server/fresh-agent/codex-normalize.test.ts
index 8d94afbba..6eb8a3e0b 100644
--- a/test/unit/server/fresh-agent/codex-normalize.test.ts
+++ b/test/unit/server/fresh-agent/codex-normalize.test.ts
@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest'
 
 import { CodexThreadItemTypeSchema } from '../../../../server/coding-cli/codex-app-server/protocol.js'
 import {
+  CodexDisplayConfigError,
   createCodexDisplayId,
   normalizeCodexDisplayTurns,
   normalizeCodexThreadSnapshot,
@@ -95,7 +96,7 @@ describe('Codex fresh-agent normalization', () => {
           text: 'Done',
         },
       ],
-    })
+    }, 0, { secret: DISPLAY_SECRET })
 
     expect(turn).toMatchObject({
       model: 'gpt-5.4-mini',
@@ -116,7 +117,7 @@ describe('Codex fresh-agent normalization', () => {
           text: 'Done',
         },
       ],
-    }, 0, { model: 'gpt-5.4-mini' })
+    }, 0, { model: 'gpt-5.4-mini', secret: DISPLAY_SECRET })
 
     expect(turn.model).toBe('gpt-5.4-mini')
   })
@@ -198,6 +199,33 @@ describe('Codex fresh-agent normalization', () => {
     expect(decodedHandle).not.toContain('cursor:opaque-payload')
   })
 
+  it('fails display normalization when the adapter does not supply a non-empty secret', () => {
+    expect(() => normalizeCodexDisplayTurns({
+      id: 'turn-missing-secret',
+      status: 'completed',
+      items: [{
+        id: 'item-user',
+        type: 'userMessage',
+        content: [{ type: 'text', text: 'Prompt' }],
+      }],
+    }, 0, {
+      threadId: THREAD_ID,
+      secret: '',
+    })).toThrow(CodexDisplayConfigError)
+
+    expect(() => normalizeCodexDisplayTurns({
+      id: 'turn-missing-secret',
+      status: 'completed',
+      items: [{
+        id: 'item-user',
+        type: 'userMessage',
+        content: [{ type: 'text', text: 'Prompt' }],
+      }],
+    }, 0, {
+      threadId: THREAD_ID,
+    })).toThrow(/non-empty.*secret/i)
+  })
+
   it('preserves existing display ids when unrelated rows are inserted later in the provider turn', () => {
     const base = normalizeDisplayTurns({
       id: 'turn-inserted',
@@ -507,5 +535,44 @@ describe('Codex fresh-agent normalization', () => {
       model: 'gpt-5.4-mini',
       secret: DISPLAY_SECRET,
     })).toThrow(/not found/i)
+
+    expect(() => normalizeCodexTurnBody({
+      threadId: THREAD_ID,
+      revision: 9,
+      requestedTurnId: '',
+      rawTurn,
+      model: 'gpt-5.4-mini',
+      secret: DISPLAY_SECRET,
+    })).toThrow(/not found/i)
+
+    expect(() => normalizeCodexTurnBody({
+      threadId: THREAD_ID,
+      revision: 9,
+      requestedTurnId: undefined as unknown as string,
+      rawTurn,
+      model: 'gpt-5.4-mini',
+      secret: DISPLAY_SECRET,
+    })).toThrow(/not found/i)
+  })
+
+  it('fails body normalization when the adapter does not supply a non-empty secret', () => {
+    const rawTurn = {
+      id: 'turn-body-secret',
+      status: 'completed',
+      items: [{
+        id: 'item-user',
+        type: 'userMessage',
+        content: [{ type: 'text', text: 'Review the diff.' }],
+      }],
+    }
+
+    expect(() => normalizeCodexTurnBody({
+      threadId: THREAD_ID,
+      revision: 9,
+      requestedTurnId: 'codex-display:v1:missingsecret0000',
+      rawTurn,
+      model: 'gpt-5.4-mini',
+      secret: '',
+    })).toThrow(CodexDisplayConfigError)
   })
 })

From c6d9384c4104dc89d70d832957f3f3ed15a6dd98 Mon Sep 17 00:00:00 2001
From: Codex <codex@openai.com>
Date: Fri, 19 Jun 2026 02:27:01 -0700
Subject: [PATCH 22/33] fix: map codex display bodies through exact provider
 turns

---
 server/config-store.ts                        |  36 ++
 server/fresh-agent/adapters/codex/adapter.ts  | 377 +++++++++++++++++-
 .../fresh-agent/adapters/codex/normalize.ts   |   9 +-
 server/fresh-agent/runtime-adapter.ts         |   4 +-
 server/fresh-agent/runtime-manager.ts         |  28 +-
 server/index.ts                               |   2 +
 shared/ws-protocol.ts                         |   1 +
 test/server/ws-protocol.test.ts               |  12 +
 test/unit/server/config-store.test.ts         |  15 +
 .../server/fresh-agent/codex-adapter.test.ts  | 334 +++++++++++++++-
 .../fresh-agent/codex-normalize.test.ts       |  31 +-
 .../fresh-agent/production-wiring.test.ts     |   2 +
 12 files changed, 807 insertions(+), 44 deletions(-)

diff --git a/server/config-store.ts b/server/config-store.ts
index 1f50984d3..b7a5ecf63 100644
--- a/server/config-store.ts
+++ b/server/config-store.ts
@@ -1,5 +1,6 @@
 import fsp from 'fs/promises'
 import path from 'path'
+import { randomBytes } from 'node:crypto'
 import { logger } from './logger.js'
 import { getFreshellConfigDir } from './freshell-home.js'
 import {
@@ -57,6 +58,9 @@ export type UserConfig = {
   version: 1
   settings: AppSettings
   legacyLocalSettingsSeed?: LocalSettingsPatch
+  serverSecrets?: {
+    codexDisplayIdSecret?: string
+  }
   sessionOverrides: Record<string, SessionOverride>
   terminalOverrides: Record<string, TerminalOverride>
   projectColors: Record<string, string>
@@ -266,6 +270,10 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return !!value && typeof value === 'object' && !Array.isArray(value)
 }
 
+function generateServerLocalSecret(): string {
+  return randomBytes(32).toString('base64url')
+}
+
 function migrateLegacyFreshClaudeSettings(rawSettings: Record<string, unknown>): Record<string, unknown> {
   if (!isRecord(rawSettings.freshclaude)) {
     return rawSettings
@@ -336,6 +344,14 @@ export class ConfigStore {
         ...existing,
         settings,
         legacyLocalSettingsSeed,
+        serverSecrets: isRecord(existing.serverSecrets)
+          ? {
+              ...(typeof existing.serverSecrets.codexDisplayIdSecret === 'string'
+                && existing.serverSecrets.codexDisplayIdSecret.trim().length > 0
+                ? { codexDisplayIdSecret: existing.serverSecrets.codexDisplayIdSecret }
+                : {}),
+            }
+          : undefined,
         sessionOverrides: existing.sessionOverrides || {},
         terminalOverrides: existing.terminalOverrides || {},
         projectColors: existing.projectColors || {},
@@ -371,6 +387,7 @@ export class ConfigStore {
       version: 1,
       settings: defaultSettings,
       legacyLocalSettingsSeed: undefined,
+      serverSecrets: undefined,
       sessionOverrides: {},
       terminalOverrides: {},
       projectColors: {},
@@ -419,6 +436,25 @@ export class ConfigStore {
     return cfg.settings
   }
 
+  async getCodexDisplayIdSecret(): Promise<string> {
+    return this.writeMutex.acquire(async () => {
+      const cfg = await this.loadForWrite()
+      const existing = cfg.serverSecrets?.codexDisplayIdSecret
+      if (typeof existing === 'string' && existing.trim().length > 0) {
+        return existing
+      }
+      const secret = generateServerLocalSecret()
+      await this.saveInternal({
+        ...cfg,
+        serverSecrets: {
+          ...(cfg.serverSecrets ?? {}),
+          codexDisplayIdSecret: secret,
+        },
+      })
+      return secret
+    })
+  }
+
   async getLegacyLocalSettingsSeed(): Promise<LocalSettingsPatch | undefined> {
     const cfg = await this.load()
     return cfg.legacyLocalSettingsSeed
diff --git a/server/fresh-agent/adapters/codex/adapter.ts b/server/fresh-agent/adapters/codex/adapter.ts
index 77b74146c..b6e0fab3a 100644
--- a/server/fresh-agent/adapters/codex/adapter.ts
+++ b/server/fresh-agent/adapters/codex/adapter.ts
@@ -1,14 +1,22 @@
 import type { FreshAgentCreateRequest, FreshAgentInputImage, FreshAgentRuntimeAdapter } from '../../runtime-adapter.js'
+import type { FreshAgentTurn } from '../../../../shared/fresh-agent-contract.js'
+import { FreshAgentTurnPageSchema } from '../../../../shared/fresh-agent-contract.js'
+import {
+  FreshAgentAmbiguousTurnBodyError,
+  FreshAgentStaleThreadRevisionError,
+} from '../../runtime-manager.js'
 import type {
   CodexThreadForkParams,
   CodexTurnInterruptParams,
   CodexTurnStartParams,
 } from '../../../coding-cli/codex-app-server/protocol.js'
 import {
+  CodexDisplayTurnNotFoundError,
+  createCodexDisplayId,
+  normalizeCodexDisplayTurns,
   normalizeCodexThreadSnapshot,
-  normalizeCodexTurn,
   normalizeCodexTurnBody,
-  normalizeCodexTurnPage,
+  parseCodexDisplayIdHandle,
 } from './normalize.js'
 import { normalizeFreshAgentEffort, normalizeFreshAgentModel } from '../../../../shared/fresh-agent-models.js'
 
@@ -61,6 +69,26 @@ type CodexRuntimePort = {
   readThreadTurn: (input: { threadId: string; turnId: string; revision?: number }) => Promise<Record<string, any>>
 }
 
+type DisplayIndexEntry = {
+  threadId: string
+  revision: number
+  displayTurnId: string
+  providerTurnId: string
+  role: NonNullable<FreshAgentTurn['role']>
+  rawTurn: Record<string, unknown>
+}
+
+type SubmittedInputRecord = {
+  requestId: string
+  providerTurnId: string
+  submittedTurnId: string
+  input: CodexTurnStartParams['input']
+  createdAt: number
+}
+
+const DISPLAY_INDEX_MAX_REVISIONS = 32
+const SUBMITTED_INPUT_TTL_MS = 30 * 60 * 1000
+
 function toCodexApprovalPolicy(value: string | undefined) {
   if (value === undefined) return undefined
   if (value === 'untrusted' || value === 'on-failure' || value === 'on-request' || value === 'never') {
@@ -124,6 +152,56 @@ function toCodexUserInput(text: string, images: FreshAgentInputImage[] | undefin
   return input
 }
 
+function submittedInputKey(providerTurnId: string, requestId: string): string {
+  return `${providerTurnId}\u0000${requestId}`
+}
+
+function displayIndexKey(threadId: string, revision: number): string {
+  return `${threadId}\u0000${revision}`
+}
+
+function stripCodexDisplayMetadata(turn: FreshAgentTurn): FreshAgentTurn {
+  const {
+    syntheticKind: _syntheticKind,
+    requestId: _requestId,
+    ...publicTurn
+  } = turn as FreshAgentTurn & {
+    syntheticKind?: string
+    requestId?: string | number
+  }
+  return publicTurn
+}
+
+function readRawTurns(value: unknown): Record<string, unknown>[] {
+  return Array.isArray(value)
+    ? value.filter((turn): turn is Record<string, unknown> => !!turn && typeof turn === 'object' && !Array.isArray(turn))
+    : []
+}
+
+function hasCodexUserMessage(rawTurn: Record<string, unknown>): boolean {
+  return readRawTurns(rawTurn.items).some((item) => item.type === 'userMessage')
+}
+
+function submittedInputContent(input: CodexTurnStartParams['input']): unknown[] {
+  return input.map((part) => {
+    if (part.type === 'text') {
+      return { type: 'text', text: part.text }
+    }
+    if (part.type === 'localImage') {
+      return { type: 'localImage', path: part.path }
+    }
+    return { type: 'image', url: part.url }
+  })
+}
+
+function makeSubmittedUserMessage(record: SubmittedInputRecord): Record<string, unknown> {
+  return {
+    id: `codex-submitted-input:${record.requestId}`,
+    type: 'userMessage',
+    content: submittedInputContent(record.input),
+  }
+}
+
 function normalizeCodexInput(input: FreshAgentCreateRequest): FreshAgentCreateRequest {
   const model = normalizeFreshAgentModel(input.sessionType, 'codex', input.model)
   return {
@@ -174,9 +252,14 @@ function findActiveTurnId(rawSnapshot: Record<string, any>): string | undefined
 }
 
 export function createCodexFreshAgentAdapter(deps: {
+  displayIdSecret: string
   runtime?: CodexRuntimePort
   runtimeFactory?: () => CodexRuntimePort
 }): FreshAgentRuntimeAdapter {
+  if (typeof deps.displayIdSecret !== 'string' || deps.displayIdSecret.trim().length === 0) {
+    throw new Error('Codex fresh-agent adapter requires a persisted display-id secret.')
+  }
+  const displayIdSecret = deps.displayIdSecret
   const activeTurnByThread = new Map<string, string>()
   const settingsByThread = new Map<string, Partial<FreshAgentCreateRequest>>()
   const runtimeByThread = new Map<string, CodexRuntimePort>()
@@ -185,6 +268,195 @@ export function createCodexFreshAgentAdapter(deps: {
   const runtimeResumeByThread = new Map<string, Promise<CodexRuntimePort>>()
   const runtimeResumeGenerationByThread = new Map<string, number>()
   const modelByTurnByThread = new Map<string, Map<string, string>>()
+  const displayIndexByRevision = new Map<string, Map<string, DisplayIndexEntry>>()
+  const submittedInputsByThread = new Map<string, Map<string, SubmittedInputRecord>>()
+  const submittedAliasByThread = new Map<string, Map<string, string>>()
+
+  const pruneDisplayIndex = () => {
+    while (displayIndexByRevision.size > DISPLAY_INDEX_MAX_REVISIONS) {
+      const oldestKey = displayIndexByRevision.keys().next().value
+      if (!oldestKey) return
+      displayIndexByRevision.delete(oldestKey)
+    }
+  }
+
+  const pruneSubmittedInputs = (threadId: string) => {
+    const records = submittedInputsByThread.get(threadId)
+    if (!records) return
+    const cutoff = Date.now() - SUBMITTED_INPUT_TTL_MS
+    for (const [key, record] of records) {
+      if (record.createdAt < cutoff) {
+        records.delete(key)
+      }
+    }
+    if (records.size === 0) {
+      submittedInputsByThread.delete(threadId)
+    }
+  }
+
+  const submittedRequestIdMap = (threadId: string): Map<string, string | number> => {
+    pruneSubmittedInputs(threadId)
+    const requestIds = new Map<string, string | number>()
+    const aliases = submittedAliasByThread.get(threadId)
+    for (const [providerTurnId, requestId] of aliases ?? []) {
+      requestIds.set(providerTurnId, requestId)
+    }
+    for (const record of submittedInputsByThread.get(threadId)?.values() ?? []) {
+      requestIds.set(record.providerTurnId, record.requestId)
+    }
+    return requestIds
+  }
+
+  const firstSubmittedRecordForProviderTurn = (threadId: string, providerTurnId: string): SubmittedInputRecord | undefined => {
+    pruneSubmittedInputs(threadId)
+    for (const record of submittedInputsByThread.get(threadId)?.values() ?? []) {
+      if (record.providerTurnId === providerTurnId) return record
+    }
+    return undefined
+  }
+
+  const rememberSubmittedInput = (threadId: string, record: SubmittedInputRecord) => {
+    const records = submittedInputsByThread.get(threadId) ?? new Map<string, SubmittedInputRecord>()
+    records.set(submittedInputKey(record.providerTurnId, record.requestId), record)
+    submittedInputsByThread.set(threadId, records)
+  }
+
+  const rememberSubmittedAlias = (threadId: string, providerTurnId: string, requestId: string) => {
+    const aliases = submittedAliasByThread.get(threadId) ?? new Map<string, string>()
+    aliases.set(providerTurnId, requestId)
+    submittedAliasByThread.set(threadId, aliases)
+  }
+
+  const prepareRawTurnForNormalization = (threadId: string, rawTurn: Record<string, unknown>): Record<string, unknown> => {
+    const providerTurnId = String(rawTurn.id ?? '')
+    if (!providerTurnId) return rawTurn
+    const record = firstSubmittedRecordForProviderTurn(threadId, providerTurnId)
+    if (!record) return rawTurn
+
+    if (hasCodexUserMessage(rawTurn)) {
+      submittedInputsByThread.get(threadId)?.delete(submittedInputKey(providerTurnId, record.requestId))
+      rememberSubmittedAlias(threadId, providerTurnId, record.requestId)
+      return rawTurn
+    }
+
+    return {
+      ...rawTurn,
+      items: [
+        makeSubmittedUserMessage(record),
+        ...readRawTurns(rawTurn.items),
+      ],
+    }
+  }
+
+  const registerDisplayRows = (input: {
+    threadId: string
+    revision: number
+    rawTurn: Record<string, unknown>
+    displayRows: Array<{
+      turnId: string
+      role: NonNullable<FreshAgentTurn['role']>
+      providerTurnId: string
+    }>
+  }) => {
+    const key = displayIndexKey(input.threadId, input.revision)
+    const entries = displayIndexByRevision.get(key) ?? new Map<string, DisplayIndexEntry>()
+    for (const row of input.displayRows) {
+      entries.set(row.turnId, {
+        threadId: input.threadId,
+        revision: input.revision,
+        displayTurnId: row.turnId,
+        providerTurnId: row.providerTurnId,
+        role: row.role,
+        rawTurn: input.rawTurn,
+      })
+    }
+    displayIndexByRevision.set(key, entries)
+    pruneDisplayIndex()
+  }
+
+  const normalizeRawTurns = (input: {
+    threadId: string
+    revision: number
+    rawTurns: Record<string, unknown>[]
+  }): FreshAgentTurn[] => input.rawTurns.flatMap((rawTurn) => {
+    const preparedTurn = prepareRawTurnForNormalization(input.threadId, rawTurn)
+    const normalized = normalizeCodexDisplayTurns(preparedTurn, 0, {
+      threadId: input.threadId,
+      secret: displayIdSecret,
+      submittedRequestIdByProviderTurnId: submittedRequestIdMap(input.threadId),
+      model: typeof preparedTurn.id === 'string'
+        ? modelByTurnByThread.get(input.threadId)?.get(preparedTurn.id)
+        : undefined,
+    })
+    registerDisplayRows({
+      threadId: input.threadId,
+      revision: input.revision,
+      rawTurn: preparedTurn,
+      displayRows: normalized.displayRows,
+    })
+    return normalized.turns.map(stripCodexDisplayMetadata)
+  }).map((turn, index) => ({
+    ...turn,
+    ordinal: index,
+  }))
+
+  const normalizeRawPage = (input: {
+    threadId: string
+    revision: number
+    rawPage: { turns?: unknown[]; nextCursor?: string | null; backwardsCursor?: string | null }
+  }) => {
+    const turns = normalizeRawTurns({
+      threadId: input.threadId,
+      revision: input.revision,
+      rawTurns: readRawTurns(input.rawPage.turns),
+    })
+    return FreshAgentTurnPageSchema.parse({
+      sessionType: 'freshcodex',
+      provider: 'codex',
+      threadId: input.threadId,
+      revision: input.revision,
+      nextCursor: input.rawPage.nextCursor ?? null,
+      backwardsCursor: input.rawPage.backwardsCursor ?? null,
+      turns,
+      bodies: Object.fromEntries(turns.map((turn) => [turn.turnId, turn])),
+    })
+  }
+
+  const findDisplayIndexEntry = (threadId: string, revision: number, displayTurnId: string): DisplayIndexEntry | undefined => {
+    return displayIndexByRevision.get(displayIndexKey(threadId, revision))?.get(displayTurnId)
+  }
+
+  const rescanDisplayIndex = async (
+    runtime: CodexRuntimePort,
+    threadId: string,
+    revision: number,
+    displayTurnId: string,
+  ): Promise<DisplayIndexEntry | null> => {
+    const rawPage = await runtime.listThreadTurns({
+      threadId,
+      limit: 100,
+      itemsView: 'full',
+    })
+    const currentRevision = Number(rawPage.revision ?? revision)
+    normalizeRawPage({ threadId, revision: currentRevision, rawPage })
+    if (currentRevision !== revision) {
+      throw new FreshAgentStaleThreadRevisionError(currentRevision)
+    }
+    return findDisplayIndexEntry(threadId, revision, displayTurnId) ?? null
+  }
+
+  const clearThreadState = (threadId: string) => {
+    activeTurnByThread.delete(threadId)
+    settingsByThread.delete(threadId)
+    modelByTurnByThread.delete(threadId)
+    submittedInputsByThread.delete(threadId)
+    submittedAliasByThread.delete(threadId)
+    for (const key of [...displayIndexByRevision.keys()]) {
+      if (key.startsWith(`${threadId}\u0000`)) {
+        displayIndexByRevision.delete(key)
+      }
+    }
+  }
 
   const rememberThreadSettings = (
     threadId: string,
@@ -380,7 +652,7 @@ export function createCodexFreshAgentAdapter(deps: {
         }
         if (event.kind === 'thread_closed') {
           if (event.threadId !== sessionId) return
-          activeTurnByThread.delete(sessionId)
+          clearThreadState(sessionId)
           void releaseRuntime(sessionId).catch(() => undefined)
           listener({
             type: 'sdk.status',
@@ -399,6 +671,7 @@ export function createCodexFreshAgentAdapter(deps: {
     },
 
     async send(sessionId, input) {
+      const requestId = input.requestId ?? `codex-send-${Date.now()}`
       const settings: Partial<FreshAgentCreateRequest> = {
         ...settingsByThread.get(sessionId),
         ...input.settings,
@@ -423,11 +696,27 @@ export function createCodexFreshAgentAdapter(deps: {
         effort: toCodexReasoningEffort(settings.effort),
       })
       activeTurnByThread.set(sessionId, turn.turnId)
+      const submittedTurnId = createCodexDisplayId({
+        secret: displayIdSecret,
+        threadId: sessionId,
+        providerTurnId: turn.turnId,
+        role: 'user',
+        syntheticKind: 'submitted-input',
+        requestId,
+      })
+      rememberSubmittedInput(sessionId, {
+        requestId,
+        providerTurnId: turn.turnId,
+        submittedTurnId,
+        input: toCodexUserInput(input.text, input.images),
+        createdAt: Date.now(),
+      })
       if (settings.model) {
         const modelByTurn = modelByTurnByThread.get(sessionId) ?? new Map<string, string>()
         modelByTurn.set(turn.turnId, settings.model)
         modelByTurnByThread.set(sessionId, modelByTurn)
       }
+      return { requestId, submittedTurnId }
     },
 
     async interrupt(sessionId) {
@@ -533,17 +822,18 @@ export function createCodexFreshAgentAdapter(deps: {
       }
       const rawTurns = rawThreadTurns
         .filter((turn): turn is Record<string, unknown> => !!turn && typeof turn === 'object' && !Array.isArray(turn))
-        .map((turn, index) => normalizeCodexTurn(turn, index, {
-          model: typeof turn.id === 'string'
-            ? modelByTurnByThread.get(thread.threadId)?.get(turn.id)
-            : undefined,
-        }))
+      const revisionNumber = Number(rawSnapshot.thread?.updatedAt ?? revision ?? 0)
+      const turns = normalizeRawTurns({
+        threadId: thread.threadId,
+        revision: revisionNumber,
+        rawTurns,
+      })
       return normalizeCodexThreadSnapshot({
         threadId: thread.threadId,
-        revision: Number(rawSnapshot.thread?.updatedAt ?? revision ?? 0),
+        revision: revisionNumber,
         status: normalizeCodexThreadStatus(rawSnapshot.thread?.status),
         transcript: {
-          turns: rawTurns,
+          turns,
         },
         rawSnapshot,
       })
@@ -560,11 +850,10 @@ export function createCodexFreshAgentAdapter(deps: {
         limit: typeof query.limit === 'number' ? query.limit : undefined,
         itemsView: 'full',
       })
-      return normalizeCodexTurnPage({
+      return normalizeRawPage({
         threadId: thread.threadId,
         revision: Number(rawPage.revision ?? query.revision ?? 0),
         rawPage,
-        modelByTurn: modelByTurnByThread.get(thread.threadId),
       })
     },
 
@@ -573,28 +862,79 @@ export function createCodexFreshAgentAdapter(deps: {
         thread.threadId,
         settingsFromLocator(thread) ?? settingsByThread.get(thread.threadId),
       )
+      if (thread.turnId.startsWith('codex-display:') && !parseCodexDisplayIdHandle(thread.turnId)) {
+        return null
+      }
+      const displayHandle = parseCodexDisplayIdHandle(thread.turnId)
+      if (displayHandle) {
+        const entry = findDisplayIndexEntry(thread.threadId, revision, thread.turnId)
+          ?? await rescanDisplayIndex(runtime, thread.threadId, revision, thread.turnId)
+        if (!entry) return null
+        const rawTurn = await runtime.readThreadTurn({
+          threadId: thread.threadId,
+          turnId: entry.providerTurnId,
+          revision,
+        })
+        try {
+          return normalizeCodexTurnBody({
+            threadId: thread.threadId,
+            revision,
+            requestedTurnId: thread.turnId,
+            rawTurn: prepareRawTurnForNormalization(thread.threadId, rawTurn),
+            model: modelByTurnByThread.get(thread.threadId)?.get(entry.providerTurnId),
+            secret: displayIdSecret,
+            submittedRequestIdByProviderTurnId: submittedRequestIdMap(thread.threadId),
+          })
+        } catch (error) {
+          if (error instanceof CodexDisplayTurnNotFoundError) {
+            return null
+          }
+          throw error
+        }
+      }
+
       const rawTurn = await runtime.readThreadTurn({
         threadId: thread.threadId,
         turnId: thread.turnId,
         revision,
       })
+      const preparedTurn = prepareRawTurnForNormalization(thread.threadId, rawTurn)
+      const normalized = normalizeCodexDisplayTurns(preparedTurn, 0, {
+        threadId: thread.threadId,
+        secret: displayIdSecret,
+        submittedRequestIdByProviderTurnId: submittedRequestIdMap(thread.threadId),
+        model: typeof preparedTurn.id === 'string'
+          ? modelByTurnByThread.get(thread.threadId)?.get(preparedTurn.id)
+          : undefined,
+      })
+      registerDisplayRows({
+        threadId: thread.threadId,
+        revision,
+        rawTurn: preparedTurn,
+        displayRows: normalized.displayRows,
+      })
+      if (normalized.turns.length !== 1) {
+        throw new FreshAgentAmbiguousTurnBodyError(
+          `Codex native turn ${thread.turnId} normalizes to ${normalized.turns.length} display turns; request a display turn id instead.`,
+        )
+      }
       return normalizeCodexTurnBody({
         threadId: thread.threadId,
         revision,
-        requestedTurnId: thread.turnId,
-        rawTurn,
+        requestedTurnId: normalized.turns[0].turnId,
+        rawTurn: preparedTurn,
         model: typeof rawTurn.id === 'string'
           ? modelByTurnByThread.get(thread.threadId)?.get(rawTurn.id)
           : undefined,
+        secret: displayIdSecret,
+        submittedRequestIdByProviderTurnId: submittedRequestIdMap(thread.threadId),
       })
     },
 
     async kill(sessionId) {
-      activeTurnByThread.delete(sessionId)
-      settingsByThread.delete(sessionId)
+      clearThreadState(sessionId)
       runtimeResumeGenerationByThread.set(sessionId, (runtimeResumeGenerationByThread.get(sessionId) ?? 0) + 1)
       runtimeResumeByThread.delete(sessionId)
-      modelByTurnByThread.delete(sessionId)
       await releaseRuntime(sessionId)
       return true
     },
@@ -609,6 +949,9 @@ export function createCodexFreshAgentAdapter(deps: {
       activeTurnByThread.clear()
       settingsByThread.clear()
       modelByTurnByThread.clear()
+      displayIndexByRevision.clear()
+      submittedInputsByThread.clear()
+      submittedAliasByThread.clear()
       await Promise.all(runtimes.map((runtime) => runtime.shutdown?.()))
     },
   }
diff --git a/server/fresh-agent/adapters/codex/normalize.ts b/server/fresh-agent/adapters/codex/normalize.ts
index 51ebeef3e..5067f0526 100644
--- a/server/fresh-agent/adapters/codex/normalize.ts
+++ b/server/fresh-agent/adapters/codex/normalize.ts
@@ -132,6 +132,13 @@ function readRequiredCodexDisplaySecret(secret: string | undefined): string {
   throw new CodexDisplayConfigError('Codex display-turn normalization requires a non-empty adapter-supplied display-id secret.')
 }
 
+function readRequiredCodexThreadId(threadId: string | undefined): string {
+  if (typeof threadId === 'string' && threadId.trim().length > 0) {
+    return threadId
+  }
+  throw new CodexDisplayConfigError('Codex display-turn normalization requires a non-empty adapter-supplied threadId.')
+}
+
 function readCodexThreadItemType(item: Record<string, unknown>): CodexThreadItemVariant {
   const parsed = CodexThreadItemTypeSchema.safeParse(item.type)
   if (!parsed.success) {
@@ -591,7 +598,7 @@ export function normalizeCodexDisplayTurns(
   options: NormalizeCodexDisplayTurnsOptions = {},
 ): { turns: FreshAgentTurn[]; displayRows: CodexDisplayRow[] } {
   const providerTurnId = String(rawTurn.id ?? `turn:${ordinal}`)
-  const threadId = options.threadId ?? providerTurnId
+  const threadId = readRequiredCodexThreadId(options.threadId)
   const secret = readRequiredCodexDisplaySecret(options.secret)
   const model = typeof rawTurn.model === 'string' && rawTurn.model.length > 0
     ? rawTurn.model
diff --git a/server/fresh-agent/runtime-adapter.ts b/server/fresh-agent/runtime-adapter.ts
index 43779b948..87e070103 100644
--- a/server/fresh-agent/runtime-adapter.ts
+++ b/server/fresh-agent/runtime-adapter.ts
@@ -29,6 +29,8 @@ export type FreshAgentCreateResult = {
 }
 
 export type FreshAgentSendResult = void | {
+  requestId?: string
+  submittedTurnId?: string
   sessionId?: string
   sessionRef?: { provider: string; sessionId: string }
 }
@@ -58,7 +60,7 @@ export interface FreshAgentRuntimeAdapter {
   resume?(input: FreshAgentCreateRequest): Promise<{ sessionId: string; sessionRef?: { provider: string; sessionId: string } }>
   attach?(locator: FreshAgentSessionLocator): Promise<{ sessionId: string; sessionRef?: { provider: string; sessionId: string } }> | { sessionId: string; sessionRef?: { provider: string; sessionId: string } }
   subscribe?(sessionId: string, listener: (message: unknown) => void): Promise<() => void> | (() => void)
-  send?(sessionId: string, input: { text: string; images?: FreshAgentInputImage[]; settings?: FreshAgentCreateRequest }): Promise<FreshAgentSendResult> | FreshAgentSendResult
+  send?(sessionId: string, input: { requestId?: string; text: string; images?: FreshAgentInputImage[]; settings?: FreshAgentCreateRequest }): Promise<FreshAgentSendResult> | FreshAgentSendResult
   interrupt?(sessionId: string): Promise<void> | void
   compact?(sessionId: string, input?: { instructions?: string }): Promise<void> | void
   kill?(sessionId: string): Promise<boolean> | boolean
diff --git a/server/fresh-agent/runtime-manager.ts b/server/fresh-agent/runtime-manager.ts
index c3ff92095..d08472c24 100644
--- a/server/fresh-agent/runtime-manager.ts
+++ b/server/fresh-agent/runtime-manager.ts
@@ -1,3 +1,6 @@
+import {
+  randomUUID,
+} from 'node:crypto'
 import {
   makeFreshAgentSessionKey,
   type FreshAgentRuntimeProvider,
@@ -35,6 +38,9 @@ export class FreshAgentUnsupportedCapabilityError extends Error {
   readonly code = 'FRESH_AGENT_UNSUPPORTED_CAPABILITY' as const
 }
 
+export class FreshAgentAmbiguousTurnBodyError extends FreshAgentUnsupportedCapabilityError {
+}
+
 export class FreshAgentLostSessionError extends Error {
   readonly code = 'FRESH_AGENT_LOST_SESSION' as const
   constructor(message?: string) {
@@ -150,13 +156,20 @@ export class FreshAgentRuntimeManager {
 
   async send(
     locator: FreshAgentSessionLocator,
-    input: { text: string; images?: FreshAgentInputImage[]; settings?: FreshAgentCreateRequest },
+    input: { requestId?: string; text: string; images?: FreshAgentInputImage[]; settings?: FreshAgentCreateRequest },
   ): Promise<FreshAgentSendResult> {
     const record = this.requireSession(locator)
     if (!record.adapter.send) {
       throw new FreshAgentUnsupportedCapabilityError(`Send is not supported for ${record.sessionType}`)
     }
-    const result = await record.adapter.send(locator.sessionId, input)
+    const requestId = input.requestId ?? randomUUID()
+    const { requestId: _requestId, ...adapterInput } = input
+    Object.defineProperty(adapterInput, 'requestId', {
+      value: requestId,
+      enumerable: false,
+      configurable: true,
+    })
+    const result = await record.adapter.send(locator.sessionId, adapterInput)
     if (result?.sessionId && result.sessionId !== locator.sessionId) {
       this.sessions.set(this.key({
         sessionType: locator.sessionType,
@@ -164,7 +177,16 @@ export class FreshAgentRuntimeManager {
         sessionId: result.sessionId,
       }), record)
     }
-    return result
+    if (result?.requestId) {
+      return result
+    }
+    const wrappedResult = { ...(result ?? {}) } as Exclude<FreshAgentSendResult, void>
+    Object.defineProperty(wrappedResult, 'requestId', {
+      value: requestId,
+      enumerable: result == null,
+      configurable: true,
+    })
+    return wrappedResult
   }
 
   async interrupt(locator: FreshAgentSessionLocator) {
diff --git a/server/index.ts b/server/index.ts
index 630bf650d..1d48f8e20 100644
--- a/server/index.ts
+++ b/server/index.ts
@@ -313,7 +313,9 @@ async function main() {
     sdkBridge,
     agentHistorySource,
   })
+  const codexDisplayIdSecret = await configStore.getCodexDisplayIdSecret()
   const codexFreshAgentAdapter = createCodexFreshAgentAdapter({
+    displayIdSecret: codexDisplayIdSecret,
     runtimeFactory: () => new CodexAppServerRuntime({ serverInstanceId }),
   })
   const opencodeServeManager = new OpencodeServeManager()
diff --git a/shared/ws-protocol.ts b/shared/ws-protocol.ts
index b0d4663f0..68ff731a0 100644
--- a/shared/ws-protocol.ts
+++ b/shared/ws-protocol.ts
@@ -430,6 +430,7 @@ export const FreshAgentAttachSchema = z.object({
 
 export const FreshAgentSendSchema = z.object({
   type: z.literal('freshAgent.send'),
+  requestId: z.string().min(1).optional(),
   sessionId: z.string().min(1),
   sessionType: z.enum(['freshclaude', 'freshcodex', 'kilroy', 'freshopencode']),
   provider: z.enum(['claude', 'codex', 'opencode']),
diff --git a/test/server/ws-protocol.test.ts b/test/server/ws-protocol.test.ts
index c2e87a997..4bceb35ed 100644
--- a/test/server/ws-protocol.test.ts
+++ b/test/server/ws-protocol.test.ts
@@ -8,6 +8,7 @@ import {
   ClaudeActivityUpdatedSchema,
   ClaudeActivityListSchema,
   ErrorCode,
+  FreshAgentSendSchema,
   HelloSchema,
   TerminalAttachSchema,
   TerminalInputSchema,
@@ -61,6 +62,17 @@ describe('websocket protocol schemas', () => {
     expect(parsed.expectedSessionRef).toEqual({ provider: 'codex', sessionId: 'thread-1' })
   })
 
+  it('accepts an optional freshAgent.send requestId', () => {
+    expect(FreshAgentSendSchema.parse({
+      type: 'freshAgent.send',
+      requestId: 'send-request-1',
+      sessionId: 'thread-1',
+      sessionType: 'freshcodex',
+      provider: 'codex',
+      text: 'Continue',
+    }).requestId).toBe('send-request-1')
+  })
+
   it('accepts SESSION_IDENTITY_MISMATCH as an error code', () => {
     expect(ErrorCode.parse('SESSION_IDENTITY_MISMATCH')).toBe('SESSION_IDENTITY_MISMATCH')
   })
diff --git a/test/unit/server/config-store.test.ts b/test/unit/server/config-store.test.ts
index e991bf9f5..fd4081678 100644
--- a/test/unit/server/config-store.test.ts
+++ b/test/unit/server/config-store.test.ts
@@ -90,6 +90,21 @@ describe('ConfigStore', () => {
       expect(exists).toBe(true)
     })
 
+    it('generates and persists the Codex display-id secret without exposing it in settings', async () => {
+      const store = new ConfigStore()
+
+      const secret = await store.getCodexDisplayIdSecret()
+      const settings = await store.getSettings()
+      const saved = JSON.parse(await fsp.readFile(configPath, 'utf-8'))
+      const reloaded = new ConfigStore()
+
+      expect(secret).toEqual(expect.any(String))
+      expect(secret.length).toBeGreaterThanOrEqual(32)
+      expect(saved.serverSecrets.codexDisplayIdSecret).toBe(secret)
+      expect(JSON.stringify(settings)).not.toContain(secret)
+      await expect(reloaded.getCodexDisplayIdSecret()).resolves.toBe(secret)
+    })
+
     it('creates .freshell directory if needed', async () => {
       const store = new ConfigStore()
       await store.load()
diff --git a/test/unit/server/fresh-agent/codex-adapter.test.ts b/test/unit/server/fresh-agent/codex-adapter.test.ts
index 7525c2372..3b774e0b2 100644
--- a/test/unit/server/fresh-agent/codex-adapter.test.ts
+++ b/test/unit/server/fresh-agent/codex-adapter.test.ts
@@ -1,6 +1,15 @@
 import { describe, expect, it, vi } from 'vitest'
 
-import { createCodexFreshAgentAdapter } from '../../../../server/fresh-agent/adapters/codex/adapter.js'
+import { createCodexFreshAgentAdapter as createRawCodexFreshAgentAdapter } from '../../../../server/fresh-agent/adapters/codex/adapter.js'
+import { FreshAgentStaleThreadRevisionError } from '../../../../server/fresh-agent/runtime-manager.js'
+
+const DISPLAY_SECRET = 'task-3-persisted-display-secret'
+
+function createCodexFreshAgentAdapter(
+  deps: Omit<Parameters<typeof createRawCodexFreshAgentAdapter>[0], 'displayIdSecret'> & { displayIdSecret?: string },
+) {
+  return createRawCodexFreshAgentAdapter({ displayIdSecret: DISPLAY_SECRET, ...deps })
+}
 
 function makeCodexThread(id: string) {
   return {
@@ -33,6 +42,31 @@ function makeCodexTurn(id: string) {
   }
 }
 
+function makeMixedCodexTurn(id: string) {
+  return {
+    id,
+    status: 'completed',
+    items: [
+      {
+        type: 'userMessage',
+        id: `${id}:user`,
+        content: [{ type: 'text', text: 'Review the diff.' }],
+      },
+      {
+        type: 'reasoning',
+        id: `${id}:reasoning`,
+        summary: ['Checking changes'],
+        content: [],
+      },
+      {
+        type: 'agentMessage',
+        id: `${id}:assistant`,
+        text: 'The patch is safe.',
+      },
+    ],
+  }
+}
+
 describe('Codex fresh-agent adapter', () => {
   it('allocates separate runtimes for fresh Codex threads in different cwd values', async () => {
     const runtimes = ['/repo/one', '/repo/two'].map((cwd, index) => ({
@@ -148,8 +182,7 @@ describe('Codex fresh-agent adapter', () => {
   })
 
   it('reads snapshots and turns from the official Codex thread APIs', async () => {
-    const durableTurn = makeCodexTurn('turn-1')
-    const expectedFullItem = expect.objectContaining({ kind: 'text', text: 'Codex summary' })
+    const durableTurn = makeMixedCodexTurn('turn-1')
     const runtime = {
       startThread: vi.fn(),
       resumeThread: vi.fn(),
@@ -168,25 +201,292 @@ describe('Codex fresh-agent adapter', () => {
     }
     const adapter = createCodexFreshAgentAdapter({ runtime: runtime as any })
 
-    await expect(adapter.getSnapshot?.({ sessionType: 'freshcodex', provider: 'codex', threadId: 'thread-new-1' }, 7)).resolves.toMatchObject({
+    const snapshot: any = await adapter.getSnapshot?.({ sessionType: 'freshcodex', provider: 'codex', threadId: 'thread-new-1' }, 7)
+    expect(snapshot).toMatchObject({
       provider: 'codex',
       threadId: 'thread-new-1',
       revision: 7,
-      turns: [{ id: 'turn-1', turnId: 'turn-1' }],
     })
+    expect(snapshot.turns).toHaveLength(2)
+    expect(snapshot.turns[0]).toMatchObject({ role: 'user', ordinal: 0 })
+    expect(snapshot.turns[1]).toMatchObject({ role: 'assistant', ordinal: 1 })
+    expect(snapshot.turns[0].turnId).toMatch(/^codex-display:v1:[A-Za-z0-9_-]{22}$/)
+    expect(snapshot.turns[1].turnId).toMatch(/^codex-display:v1:[A-Za-z0-9_-]{22}$/)
+    expect(snapshot.turns[0].turnId).not.toContain('turn-1')
+    expect(snapshot.turns[0]).not.toHaveProperty('providerTurnId')
     expect(runtime.readThread).toHaveBeenCalledWith({ threadId: 'thread-new-1', includeTurns: true })
-    await expect(adapter.getTurnPage?.({ sessionType: 'freshcodex', provider: 'codex', threadId: 'thread-new-1' }, { revision: 7 })).resolves.toMatchObject({
+    const page: any = await adapter.getTurnPage?.({ sessionType: 'freshcodex', provider: 'codex', threadId: 'thread-new-1' }, { revision: 7 })
+    expect(page).toMatchObject({
+      revision: 7,
+      turns: [
+        expect.objectContaining({ role: 'user' }),
+        expect.objectContaining({ role: 'assistant' }),
+      ],
+    })
+    expect(page.turns[1].items).toEqual([
+      expect.objectContaining({ kind: 'reasoning' }),
+      expect.objectContaining({ kind: 'text', text: 'The patch is safe.' }),
+    ])
+    expect(page.bodies[page.turns[1].turnId]).toMatchObject({ role: 'assistant' })
+    await expect(adapter.getTurnBody?.({ sessionType: 'freshcodex', provider: 'codex', threadId: 'thread-new-1', turnId: page.turns[1].turnId }, 7)).resolves.toMatchObject({
+      turnId: page.turns[1].turnId,
       revision: 7,
-      turns: [{ id: 'turn-1', turnId: 'turn-1', items: [expectedFullItem] }],
-      bodies: { 'turn-1': expect.objectContaining({ items: [expectedFullItem] }) },
+      items: [
+        expect.objectContaining({ kind: 'reasoning' }),
+        expect.objectContaining({ kind: 'text', text: 'The patch is safe.' }),
+      ],
     })
-    await expect(adapter.getTurnBody?.({ sessionType: 'freshcodex', provider: 'codex', threadId: 'thread-new-1', turnId: 'turn-1' }, 7)).resolves.toMatchObject({
+    expect(runtime.readThreadTurn).toHaveBeenCalledWith({
+      threadId: 'thread-new-1',
       turnId: 'turn-1',
       revision: 7,
-      items: [expectedFullItem],
     })
   })
 
+  it('keeps display ids short and opaque for long native ids and item ids', async () => {
+    const longProviderId = `turn-${'native-id-'.repeat(40)}`
+    const longItemId = `item-${'item-id-'.repeat(40)}`
+    const runtime = {
+      startThread: vi.fn(),
+      resumeThread: vi.fn(),
+      readThread: vi.fn().mockResolvedValue({
+        thread: {
+          ...makeCodexThread('thread-long-ids'),
+          updatedAt: 11,
+          turns: [{
+            id: longProviderId,
+            status: 'completed',
+            items: [{ type: 'agentMessage', id: longItemId, text: 'Short public id' }],
+          }],
+        },
+      }),
+      listThreadTurns: vi.fn(),
+      readThreadTurn: vi.fn(),
+    }
+    const adapter = createCodexFreshAgentAdapter({ runtime: runtime as any })
+
+    const snapshot: any = await adapter.getSnapshot?.({
+      sessionType: 'freshcodex',
+      provider: 'codex',
+      threadId: 'thread-long-ids',
+    }, 11)
+
+    expect(snapshot.turns[0].turnId).toMatch(/^codex-display:v1:[A-Za-z0-9_-]{22}$/)
+    expect(snapshot.turns[0].turnId.length).toBeLessThan(45)
+    expect(snapshot.turns[0].turnId).not.toContain(longProviderId.slice(0, 20))
+    expect(snapshot.turns[0].turnId).not.toContain(longItemId.slice(0, 20))
+  })
+
+  it('does not pass unknown or malformed display ids to Codex body reads', async () => {
+    const durableTurn = makeMixedCodexTurn('turn-1')
+    const runtime = {
+      startThread: vi.fn(),
+      resumeThread: vi.fn(),
+      readThread: vi.fn().mockResolvedValue({
+        thread: { ...makeCodexThread('thread-new-1'), turns: [durableTurn] },
+      }),
+      listThreadTurns: vi.fn().mockResolvedValue({
+        revision: 7,
+        nextCursor: null,
+        turns: [durableTurn],
+      }),
+      readThreadTurn: vi.fn().mockResolvedValue(durableTurn),
+    }
+    const adapter = createCodexFreshAgentAdapter({ runtime: runtime as any })
+
+    await expect(adapter.getTurnBody?.({
+      sessionType: 'freshcodex',
+      provider: 'codex',
+      threadId: 'thread-new-1',
+      turnId: 'codex-display:v1:not-a-valid-envelope',
+    }, 7)).resolves.toBeNull()
+    expect(runtime.readThreadTurn).not.toHaveBeenCalled()
+
+    await expect(adapter.getTurnBody?.({
+      sessionType: 'freshcodex',
+      provider: 'codex',
+      threadId: 'thread-new-1',
+      turnId: 'codex-display:v1:abcdefghijklmnopqrstu1',
+    }, 7)).resolves.toBeNull()
+    expect(runtime.readThreadTurn).not.toHaveBeenCalled()
+  })
+
+  it('returns stale revision when a display body read has no matching cached revision', async () => {
+    const runtime = {
+      startThread: vi.fn(),
+      resumeThread: vi.fn(),
+      readThread: vi.fn(),
+      listThreadTurns: vi.fn().mockResolvedValue({
+        revision: 9,
+        nextCursor: null,
+        turns: [makeMixedCodexTurn('turn-current')],
+      }),
+      readThreadTurn: vi.fn(),
+    }
+    const adapter = createCodexFreshAgentAdapter({ runtime: runtime as any })
+
+    await expect(adapter.getTurnBody?.({
+      sessionType: 'freshcodex',
+      provider: 'codex',
+      threadId: 'thread-new-1',
+      turnId: 'codex-display:v1:abcdefghijklmnopqrstu1',
+    }, 7)).rejects.toBeInstanceOf(FreshAgentStaleThreadRevisionError)
+    expect(runtime.readThreadTurn).not.toHaveBeenCalled()
+  })
+
+  it('accepts native body ids only when they normalize to one display row', async () => {
+    const runtime = {
+      startThread: vi.fn(),
+      resumeThread: vi.fn(),
+      readThread: vi.fn(),
+      listThreadTurns: vi.fn(),
+      readThreadTurn: vi.fn()
+        .mockResolvedValueOnce(makeCodexTurn('turn-single'))
+        .mockResolvedValueOnce(makeMixedCodexTurn('turn-mixed')),
+    }
+    const adapter = createCodexFreshAgentAdapter({ runtime: runtime as any })
+
+    const single: any = await adapter.getTurnBody?.({
+      sessionType: 'freshcodex',
+      provider: 'codex',
+      threadId: 'thread-new-1',
+      turnId: 'turn-single',
+    }, 7)
+    expect(single.turnId).toMatch(/^codex-display:v1:/)
+    expect(single.items).toEqual([expect.objectContaining({ text: 'Codex summary' })])
+
+    await expect(adapter.getTurnBody?.({
+      sessionType: 'freshcodex',
+      provider: 'codex',
+      threadId: 'thread-new-1',
+      turnId: 'turn-mixed',
+    }, 7)).rejects.toThrow(/display turns/)
+  })
+
+  it('materializes submitted input rows until Codex returns the provider user message', async () => {
+    const runtime = {
+      startThread: vi.fn(),
+      resumeThread: vi.fn(),
+      startTurn: vi.fn().mockResolvedValue({ turnId: 'turn-submitted-1' }),
+      readThread: vi.fn()
+        .mockResolvedValueOnce({
+          thread: {
+            ...makeCodexThread('thread-new-1'),
+            updatedAt: 8,
+            turns: [{
+              id: 'turn-submitted-1',
+              status: 'inProgress',
+              items: [{ type: 'agentMessage', id: 'assistant-1', text: 'Working on it.' }],
+            }],
+          },
+        })
+        .mockResolvedValueOnce({
+          thread: {
+            ...makeCodexThread('thread-new-1'),
+            updatedAt: 9,
+            turns: [{
+              id: 'turn-submitted-1',
+              status: 'completed',
+              items: [
+                { type: 'userMessage', id: 'real-user-1', content: [{ type: 'text', text: 'Review this image' }] },
+                { type: 'agentMessage', id: 'assistant-1', text: 'Done.' },
+              ],
+            }],
+          },
+        }),
+      listThreadTurns: vi.fn(),
+      readThreadTurn: vi.fn(),
+    }
+    const adapter = createCodexFreshAgentAdapter({ runtime: runtime as any })
+
+    const sendResult: any = await adapter.send?.('thread-new-1', {
+      requestId: 'send-1',
+      text: 'Review this image',
+      images: [
+        { kind: 'local', path: '/tmp/screenshot.png', mediaType: 'image/png' },
+        { kind: 'data', mediaType: 'image/png', data: 'abc123' },
+      ],
+    })
+
+    expect(sendResult).toMatchObject({
+      requestId: 'send-1',
+      submittedTurnId: expect.stringMatching(/^codex-display:v1:/),
+    })
+    expect(runtime.startTurn).toHaveBeenCalledWith(expect.objectContaining({
+      input: [
+        { type: 'text', text: 'Review this image', text_elements: [] },
+        { type: 'localImage', path: '/tmp/screenshot.png' },
+        { type: 'image', url: 'data:image/png;base64,abc123' },
+      ],
+    }))
+
+    const pendingSnapshot: any = await adapter.getSnapshot?.({
+      sessionType: 'freshcodex',
+      provider: 'codex',
+      threadId: 'thread-new-1',
+    }, 8)
+    expect(pendingSnapshot.turns[0]).toMatchObject({
+      turnId: sendResult.submittedTurnId,
+      role: 'user',
+      source: 'durable',
+    })
+    expect(pendingSnapshot.turns[0].summary).toBe('Review this image')
+
+    const materializedSnapshot: any = await adapter.getSnapshot?.({
+      sessionType: 'freshcodex',
+      provider: 'codex',
+      threadId: 'thread-new-1',
+    }, 9)
+    expect(materializedSnapshot.turns[0]).toMatchObject({
+      turnId: sendResult.submittedTurnId,
+      role: 'user',
+    })
+    expect(materializedSnapshot.turns.filter((turn: any) => turn.role === 'user')).toHaveLength(1)
+  })
+
+  it('keeps same-text queued submitted rows distinct by request id', async () => {
+    const runtime = {
+      startThread: vi.fn(),
+      resumeThread: vi.fn(),
+      startTurn: vi.fn()
+        .mockResolvedValueOnce({ turnId: 'turn-submitted-1' })
+        .mockResolvedValueOnce({ turnId: 'turn-submitted-2' }),
+      readThread: vi.fn().mockResolvedValue({
+        thread: {
+          ...makeCodexThread('thread-new-1'),
+          updatedAt: 8,
+          turns: [
+            {
+              id: 'turn-submitted-1',
+              status: 'inProgress',
+              items: [{ type: 'agentMessage', id: 'assistant-1', text: 'Working.' }],
+            },
+            {
+              id: 'turn-submitted-2',
+              status: 'inProgress',
+              items: [{ type: 'agentMessage', id: 'assistant-2', text: 'Still working.' }],
+            },
+          ],
+        },
+      }),
+      listThreadTurns: vi.fn(),
+      readThreadTurn: vi.fn(),
+    }
+    const adapter = createCodexFreshAgentAdapter({ runtime: runtime as any })
+
+    const first: any = await adapter.send?.('thread-new-1', { requestId: 'send-1', text: 'Same prompt' })
+    const second: any = await adapter.send?.('thread-new-1', { requestId: 'send-2', text: 'Same prompt' })
+    const snapshot: any = await adapter.getSnapshot?.({
+      sessionType: 'freshcodex',
+      provider: 'codex',
+      threadId: 'thread-new-1',
+    }, 8)
+
+    const userRows = snapshot.turns.filter((turn: any) => turn.role === 'user')
+    expect(first.submittedTurnId).not.toBe(second.submittedTurnId)
+    expect(userRows.map((turn: any) => turn.turnId)).toEqual([first.submittedTurnId, second.submittedTurnId])
+  })
+
   it('reads a just-created Codex thread without turns when includeTurns is not materialized yet', async () => {
     const runtime = {
       startThread: vi.fn().mockResolvedValue({
@@ -428,26 +728,20 @@ describe('Codex fresh-agent adapter', () => {
       model: 'gpt-5-codex',
     })
     await adapter.send?.('thread-new-1', {
+      requestId: 'send-model-1',
       text: 'Use the small model',
       settings: { model: 'gpt-5.4-flash' },
     })
 
-    await expect(adapter.getSnapshot?.({
-      sessionType: 'freshcodex',
-      provider: 'codex',
-      threadId: 'thread-new-1',
-    }, 7)).resolves.toMatchObject({
-      turns: [
-        { id: 'turn-1' },
-        { id: 'turn-2', model: 'gpt-5.4-flash' },
-      ],
-    })
     const snapshot = await adapter.getSnapshot?.({
       sessionType: 'freshcodex',
       provider: 'codex',
       threadId: 'thread-new-1',
     }, 7) as any
+    expect(snapshot.turns).toHaveLength(3)
     expect(snapshot.turns[0]).not.toHaveProperty('model')
+    expect(snapshot.turns[1]).toMatchObject({ role: 'user', model: 'gpt-5.4-flash' })
+    expect(snapshot.turns[2]).toMatchObject({ role: 'assistant', model: 'gpt-5.4-flash' })
   })
 
   it('subscribes to Codex lifecycle notifications and projects matching thread updates', async () => {
diff --git a/test/unit/server/fresh-agent/codex-normalize.test.ts b/test/unit/server/fresh-agent/codex-normalize.test.ts
index 6eb8a3e0b..e235b8d51 100644
--- a/test/unit/server/fresh-agent/codex-normalize.test.ts
+++ b/test/unit/server/fresh-agent/codex-normalize.test.ts
@@ -96,7 +96,7 @@ describe('Codex fresh-agent normalization', () => {
           text: 'Done',
         },
       ],
-    }, 0, { secret: DISPLAY_SECRET })
+    }, 0, { threadId: THREAD_ID, secret: DISPLAY_SECRET })
 
     expect(turn).toMatchObject({
       model: 'gpt-5.4-mini',
@@ -117,7 +117,7 @@ describe('Codex fresh-agent normalization', () => {
           text: 'Done',
         },
       ],
-    }, 0, { model: 'gpt-5.4-mini', secret: DISPLAY_SECRET })
+    }, 0, { threadId: THREAD_ID, model: 'gpt-5.4-mini', secret: DISPLAY_SECRET })
 
     expect(turn.model).toBe('gpt-5.4-mini')
   })
@@ -226,6 +226,33 @@ describe('Codex fresh-agent normalization', () => {
     })).toThrow(/non-empty.*secret/i)
   })
 
+  it('fails display normalization when the adapter does not supply a non-empty threadId', () => {
+    expect(() => normalizeCodexDisplayTurns({
+      id: 'turn-missing-thread',
+      status: 'completed',
+      items: [{
+        id: 'item-user',
+        type: 'userMessage',
+        content: [{ type: 'text', text: 'Prompt' }],
+      }],
+    }, 0, {
+      secret: DISPLAY_SECRET,
+      threadId: '',
+    })).toThrow(CodexDisplayConfigError)
+
+    expect(() => normalizeCodexDisplayTurns({
+      id: 'turn-missing-thread',
+      status: 'completed',
+      items: [{
+        id: 'item-user',
+        type: 'userMessage',
+        content: [{ type: 'text', text: 'Prompt' }],
+      }],
+    }, 0, {
+      secret: DISPLAY_SECRET,
+    })).toThrow(/non-empty.*threadId/i)
+  })
+
   it('preserves existing display ids when unrelated rows are inserted later in the provider turn', () => {
     const base = normalizeDisplayTurns({
       id: 'turn-inserted',
diff --git a/test/unit/server/fresh-agent/production-wiring.test.ts b/test/unit/server/fresh-agent/production-wiring.test.ts
index d388db93c..a0c6db7f9 100644
--- a/test/unit/server/fresh-agent/production-wiring.test.ts
+++ b/test/unit/server/fresh-agent/production-wiring.test.ts
@@ -14,6 +14,8 @@ describe('fresh-agent production wiring', () => {
     expect(source).toContain('registerFreshAgentThreadRoutes')
     expect(source).toContain('createClaudeFreshAgentAdapter')
     expect(source).toContain('createCodexFreshAgentAdapter')
+    expect(source).toContain('getCodexDisplayIdSecret')
+    expect(source).toMatch(/displayIdSecret:\s*codexDisplayIdSecret/)
     expect(source).toContain('createOpencodeFreshAgentAdapter')
     expect(source).toMatch(/const freshAgentRuntimeManager = new FreshAgentRuntimeManager\(/)
     expect(source).toMatch(/freshAgentRuntimeManager,\s*\n/)

From 5189eb67920a682b90a2e5210b4a594065184c3b Mon Sep 17 00:00:00 2001
From: Codex <codex@openai.com>
Date: Fri, 19 Jun 2026 02:39:30 -0700
Subject: [PATCH 23/33] fix: paginate codex transcript history by display rows

---
 server/fresh-agent/adapters/codex/adapter.ts  | 244 ++++++++++++++++--
 server/fresh-agent/router.ts                  |  16 ++
 server/fresh-agent/runtime-manager.ts         |  13 +
 .../server/fresh-agent/codex-adapter.test.ts  | 162 +++++++++++-
 test/unit/server/fresh-agent/router.test.ts   | 147 +++++++++++
 5 files changed, 563 insertions(+), 19 deletions(-)

diff --git a/server/fresh-agent/adapters/codex/adapter.ts b/server/fresh-agent/adapters/codex/adapter.ts
index b6e0fab3a..ed6dad6f7 100644
--- a/server/fresh-agent/adapters/codex/adapter.ts
+++ b/server/fresh-agent/adapters/codex/adapter.ts
@@ -1,9 +1,14 @@
+import { randomBytes } from 'node:crypto'
+
 import type { FreshAgentCreateRequest, FreshAgentInputImage, FreshAgentRuntimeAdapter } from '../../runtime-adapter.js'
 import type { FreshAgentTurn } from '../../../../shared/fresh-agent-contract.js'
 import { FreshAgentTurnPageSchema } from '../../../../shared/fresh-agent-contract.js'
 import {
   FreshAgentAmbiguousTurnBodyError,
+  FreshAgentInvalidDisplayIdError,
+  FreshAgentInvalidTurnCursorError,
   FreshAgentStaleThreadRevisionError,
+  FreshAgentTurnNotFoundError,
 } from '../../runtime-manager.js'
 import type {
   CodexThreadForkParams,
@@ -78,6 +83,17 @@ type DisplayIndexEntry = {
   rawTurn: Record<string, unknown>
 }
 
+type CodexDisplayCursorEntry = {
+  threadId: string
+  revision: number
+  providerCursor: string | null
+  drainingProviderTurnId?: string
+  nextDisplayOffset: number
+  rawTurn?: Record<string, unknown>
+  order: 'provider-default'
+  expiresAt: number
+}
+
 type SubmittedInputRecord = {
   requestId: string
   providerTurnId: string
@@ -87,6 +103,9 @@ type SubmittedInputRecord = {
 }
 
 const DISPLAY_INDEX_MAX_REVISIONS = 32
+const DISPLAY_CURSOR_PREFIX = 'codex-cursor:v1:'
+const DISPLAY_CURSOR_TTL_MS = 5 * 60 * 1000
+const DISPLAY_CURSOR_MAX_ENTRIES = 512
 const SUBMITTED_INPUT_TTL_MS = 30 * 60 * 1000
 
 function toCodexApprovalPolicy(value: string | undefined) {
@@ -160,6 +179,11 @@ function displayIndexKey(threadId: string, revision: number): string {
   return `${threadId}\u0000${revision}`
 }
 
+function readDisplayCursorHandle(cursor: string): string | null {
+  const pattern = new RegExp(`^${DISPLAY_CURSOR_PREFIX.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}([A-Za-z0-9_-]{22})$`)
+  return cursor.match(pattern)?.[1] ?? null
+}
+
 function stripCodexDisplayMetadata(turn: FreshAgentTurn): FreshAgentTurn {
   const {
     syntheticKind: _syntheticKind,
@@ -269,6 +293,7 @@ export function createCodexFreshAgentAdapter(deps: {
   const runtimeResumeGenerationByThread = new Map<string, number>()
   const modelByTurnByThread = new Map<string, Map<string, string>>()
   const displayIndexByRevision = new Map<string, Map<string, DisplayIndexEntry>>()
+  const displayCursorByHandle = new Map<string, CodexDisplayCursorEntry>()
   const submittedInputsByThread = new Map<string, Map<string, SubmittedInputRecord>>()
   const submittedAliasByThread = new Map<string, Map<string, string>>()
 
@@ -280,6 +305,57 @@ export function createCodexFreshAgentAdapter(deps: {
     }
   }
 
+  const pruneDisplayCursors = () => {
+    const now = Date.now()
+    for (const [handle, entry] of displayCursorByHandle) {
+      if (entry.expiresAt <= now) {
+        displayCursorByHandle.delete(handle)
+      }
+    }
+    while (displayCursorByHandle.size > DISPLAY_CURSOR_MAX_ENTRIES) {
+      const oldestHandle = displayCursorByHandle.keys().next().value
+      if (!oldestHandle) return
+      displayCursorByHandle.delete(oldestHandle)
+    }
+  }
+
+  const createDisplayCursor = (entry: Omit<CodexDisplayCursorEntry, 'expiresAt'>): string => {
+    pruneDisplayCursors()
+    let handle = randomBytes(16).toString('base64url')
+    while (displayCursorByHandle.has(handle)) {
+      handle = randomBytes(16).toString('base64url')
+    }
+    displayCursorByHandle.set(handle, {
+      ...entry,
+      expiresAt: Date.now() + DISPLAY_CURSOR_TTL_MS,
+    })
+    pruneDisplayCursors()
+    return `${DISPLAY_CURSOR_PREFIX}${handle}`
+  }
+
+  const resolveDisplayCursor = (input: {
+    cursor: string
+    threadId: string
+    revision: number
+  }): CodexDisplayCursorEntry => {
+    pruneDisplayCursors()
+    const handle = readDisplayCursorHandle(input.cursor)
+    if (!handle) {
+      throw new FreshAgentInvalidTurnCursorError('Invalid Codex display cursor.')
+    }
+    const entry = displayCursorByHandle.get(handle)
+    if (!entry) {
+      throw new FreshAgentInvalidTurnCursorError('Invalid or expired Codex display cursor.')
+    }
+    if (entry.threadId !== input.threadId) {
+      throw new FreshAgentInvalidTurnCursorError('Codex display cursor does not belong to this thread.')
+    }
+    if (entry.revision !== input.revision) {
+      throw new FreshAgentStaleThreadRevisionError(entry.revision)
+    }
+    return entry
+  }
+
   const pruneSubmittedInputs = (threadId: string) => {
     const records = submittedInputsByThread.get(threadId)
     if (!records) return
@@ -374,12 +450,12 @@ export function createCodexFreshAgentAdapter(deps: {
     pruneDisplayIndex()
   }
 
-  const normalizeRawTurns = (input: {
+  const normalizeSingleRawTurn = (input: {
     threadId: string
     revision: number
-    rawTurns: Record<string, unknown>[]
-  }): FreshAgentTurn[] => input.rawTurns.flatMap((rawTurn) => {
-    const preparedTurn = prepareRawTurnForNormalization(input.threadId, rawTurn)
+    rawTurn: Record<string, unknown>
+  }) => {
+    const preparedTurn = prepareRawTurnForNormalization(input.threadId, input.rawTurn)
     const normalized = normalizeCodexDisplayTurns(preparedTurn, 0, {
       threadId: input.threadId,
       secret: displayIdSecret,
@@ -394,8 +470,22 @@ export function createCodexFreshAgentAdapter(deps: {
       rawTurn: preparedTurn,
       displayRows: normalized.displayRows,
     })
-    return normalized.turns.map(stripCodexDisplayMetadata)
-  }).map((turn, index) => ({
+    return {
+      rawTurn: preparedTurn,
+      providerTurnId: String(preparedTurn.id ?? ''),
+      turns: normalized.turns.map(stripCodexDisplayMetadata),
+    }
+  }
+
+  const normalizeRawTurns = (input: {
+    threadId: string
+    revision: number
+    rawTurns: Record<string, unknown>[]
+  }): FreshAgentTurn[] => input.rawTurns.flatMap((rawTurn) => normalizeSingleRawTurn({
+    threadId: input.threadId,
+    revision: input.revision,
+    rawTurn,
+  }).turns).map((turn, index) => ({
     ...turn,
     ordinal: index,
   }))
@@ -422,6 +512,124 @@ export function createCodexFreshAgentAdapter(deps: {
     })
   }
 
+  const normalizeDisplayTurnPage = async (input: {
+    runtime: CodexRuntimePort
+    threadId: string
+    revision: number
+    cursor?: string
+    limit?: number
+  }) => {
+    const limit = input.limit ?? 30
+    const turns: FreshAgentTurn[] = []
+    let providerCursor: string | null | undefined
+    let backwardsCursor: string | null | undefined
+
+    const appendTurnRows = (rawTurn: Record<string, unknown>, offset: number, providerCursorAfterTurn: string | null) => {
+      const normalized = normalizeSingleRawTurn({
+        threadId: input.threadId,
+        revision: input.revision,
+        rawTurn,
+      })
+      const availableRows = normalized.turns.slice(offset)
+      const remainingSlots = limit - turns.length
+      const selectedRows = availableRows.slice(0, remainingSlots)
+      turns.push(...selectedRows)
+      const nextDisplayOffset = offset + selectedRows.length
+      if (nextDisplayOffset < normalized.turns.length) {
+        return createDisplayCursor({
+          threadId: input.threadId,
+          revision: input.revision,
+          providerCursor: providerCursorAfterTurn,
+          drainingProviderTurnId: normalized.providerTurnId,
+          nextDisplayOffset,
+          rawTurn: normalized.rawTurn,
+          order: 'provider-default',
+        })
+      }
+      if (providerCursorAfterTurn && turns.length >= limit) {
+        return createDisplayCursor({
+          threadId: input.threadId,
+          revision: input.revision,
+          providerCursor: providerCursorAfterTurn,
+          nextDisplayOffset: 0,
+          order: 'provider-default',
+        })
+      }
+      return null
+    }
+
+    if (input.cursor) {
+      const cursor = resolveDisplayCursor({
+        cursor: input.cursor,
+        threadId: input.threadId,
+        revision: input.revision,
+      })
+      providerCursor = cursor.providerCursor
+      if (cursor.rawTurn) {
+        const nextCursor = appendTurnRows(cursor.rawTurn, cursor.nextDisplayOffset, cursor.providerCursor)
+        if (turns.length >= limit || nextCursor) {
+          return FreshAgentTurnPageSchema.parse({
+            sessionType: 'freshcodex',
+            provider: 'codex',
+            threadId: input.threadId,
+            revision: input.revision,
+            nextCursor,
+            backwardsCursor: null,
+            turns: turns.map((turn, index) => ({ ...turn, ordinal: index })),
+            bodies: Object.fromEntries(turns.map((turn) => [turn.turnId, turn])),
+          })
+        }
+      }
+    }
+
+    while (turns.length < limit) {
+      const rawPage = await input.runtime.listThreadTurns({
+        threadId: input.threadId,
+        ...(providerCursor ? { cursor: providerCursor } : {}),
+        limit: 1,
+        itemsView: 'full',
+      })
+      const pageRevision = Number(rawPage.revision ?? input.revision)
+      if (pageRevision !== input.revision) {
+        throw new FreshAgentStaleThreadRevisionError(pageRevision)
+      }
+      backwardsCursor = typeof rawPage.backwardsCursor === 'string' ? rawPage.backwardsCursor : backwardsCursor
+      const rawTurns = readRawTurns(rawPage.turns)
+      providerCursor = typeof rawPage.nextCursor === 'string' && rawPage.nextCursor.length > 0
+        ? rawPage.nextCursor
+        : null
+      if (rawTurns.length === 0) {
+        if (providerCursor) continue
+        break
+      }
+      const nextCursor = appendTurnRows(rawTurns[0], 0, providerCursor)
+      if (turns.length >= limit || nextCursor) {
+        return FreshAgentTurnPageSchema.parse({
+          sessionType: 'freshcodex',
+          provider: 'codex',
+          threadId: input.threadId,
+          revision: input.revision,
+          nextCursor,
+          backwardsCursor: backwardsCursor ?? null,
+          turns: turns.map((turn, index) => ({ ...turn, ordinal: index })),
+          bodies: Object.fromEntries(turns.map((turn) => [turn.turnId, turn])),
+        })
+      }
+      if (!providerCursor) break
+    }
+
+    return FreshAgentTurnPageSchema.parse({
+      sessionType: 'freshcodex',
+      provider: 'codex',
+      threadId: input.threadId,
+      revision: input.revision,
+      nextCursor: null,
+      backwardsCursor: backwardsCursor ?? null,
+      turns: turns.map((turn, index) => ({ ...turn, ordinal: index })),
+      bodies: Object.fromEntries(turns.map((turn) => [turn.turnId, turn])),
+    })
+  }
+
   const findDisplayIndexEntry = (threadId: string, revision: number, displayTurnId: string): DisplayIndexEntry | undefined => {
     return displayIndexByRevision.get(displayIndexKey(threadId, revision))?.get(displayTurnId)
   }
@@ -456,6 +664,11 @@ export function createCodexFreshAgentAdapter(deps: {
         displayIndexByRevision.delete(key)
       }
     }
+    for (const [handle, entry] of displayCursorByHandle) {
+      if (entry.threadId === threadId) {
+        displayCursorByHandle.delete(handle)
+      }
+    }
   }
 
   const rememberThreadSettings = (
@@ -844,16 +1057,12 @@ export function createCodexFreshAgentAdapter(deps: {
         thread.threadId,
         settingsFromLocator(thread) ?? settingsByThread.get(thread.threadId),
       )
-      const rawPage = await runtime.listThreadTurns({
+      return normalizeDisplayTurnPage({
+        runtime,
         threadId: thread.threadId,
+        revision: Number(query.revision ?? 0),
         cursor: typeof query.cursor === 'string' ? query.cursor : undefined,
         limit: typeof query.limit === 'number' ? query.limit : undefined,
-        itemsView: 'full',
-      })
-      return normalizeRawPage({
-        threadId: thread.threadId,
-        revision: Number(rawPage.revision ?? query.revision ?? 0),
-        rawPage,
       })
     },
 
@@ -863,13 +1072,15 @@ export function createCodexFreshAgentAdapter(deps: {
         settingsFromLocator(thread) ?? settingsByThread.get(thread.threadId),
       )
       if (thread.turnId.startsWith('codex-display:') && !parseCodexDisplayIdHandle(thread.turnId)) {
-        return null
+        throw new FreshAgentInvalidDisplayIdError('Invalid Codex display turn id.')
       }
       const displayHandle = parseCodexDisplayIdHandle(thread.turnId)
       if (displayHandle) {
         const entry = findDisplayIndexEntry(thread.threadId, revision, thread.turnId)
           ?? await rescanDisplayIndex(runtime, thread.threadId, revision, thread.turnId)
-        if (!entry) return null
+        if (!entry) {
+          throw new FreshAgentTurnNotFoundError('Codex display turn was not found in the requested thread revision.')
+        }
         const rawTurn = await runtime.readThreadTurn({
           threadId: thread.threadId,
           turnId: entry.providerTurnId,
@@ -887,7 +1098,7 @@ export function createCodexFreshAgentAdapter(deps: {
           })
         } catch (error) {
           if (error instanceof CodexDisplayTurnNotFoundError) {
-            return null
+            throw new FreshAgentTurnNotFoundError('Codex display turn was not found in the requested thread revision.')
           }
           throw error
         }
@@ -950,6 +1161,7 @@ export function createCodexFreshAgentAdapter(deps: {
       settingsByThread.clear()
       modelByTurnByThread.clear()
       displayIndexByRevision.clear()
+      displayCursorByHandle.clear()
       submittedInputsByThread.clear()
       submittedAliasByThread.clear()
       await Promise.all(runtimes.map((runtime) => runtime.shutdown?.()))
diff --git a/server/fresh-agent/router.ts b/server/fresh-agent/router.ts
index 6825ea567..3aaf4cb8b 100644
--- a/server/fresh-agent/router.ts
+++ b/server/fresh-agent/router.ts
@@ -11,6 +11,10 @@ import {
   FreshAgentRuntimeUnavailableError,
   FreshAgentStaleThreadRevisionError,
   FreshAgentUnsupportedCapabilityError,
+  FreshAgentInvalidDisplayIdError,
+  FreshAgentInvalidTurnCursorError,
+  FreshAgentTurnNotFoundError,
+  FreshAgentAmbiguousTurnBodyError,
   FreshAgentLostSessionError,
   FreshAgentSessionLocatorMismatchError,
   FreshAgentContractValidationError,
@@ -114,6 +118,18 @@ export function createFreshAgentRouter(deps: {
         currentRevision: error.currentRevision,
       })
     }
+    if (error instanceof FreshAgentInvalidDisplayIdError) {
+      return res.status(400).json({ error: error.message, code: error.code })
+    }
+    if (error instanceof FreshAgentInvalidTurnCursorError) {
+      return res.status(400).json({ error: error.message, code: error.code })
+    }
+    if (error instanceof FreshAgentAmbiguousTurnBodyError) {
+      return res.status(409).json({ error: error.message, code: error.ambiguousCode })
+    }
+    if (error instanceof FreshAgentTurnNotFoundError) {
+      return res.status(404).json({ error: error.message, code: error.code })
+    }
     if (error instanceof FreshAgentRuntimeUnavailableError) {
       return res.status(503).json({ error: error.message, code: error.code })
     }
diff --git a/server/fresh-agent/runtime-manager.ts b/server/fresh-agent/runtime-manager.ts
index d08472c24..25c8dfc34 100644
--- a/server/fresh-agent/runtime-manager.ts
+++ b/server/fresh-agent/runtime-manager.ts
@@ -38,7 +38,20 @@ export class FreshAgentUnsupportedCapabilityError extends Error {
   readonly code = 'FRESH_AGENT_UNSUPPORTED_CAPABILITY' as const
 }
 
+export class FreshAgentInvalidDisplayIdError extends Error {
+  readonly code = 'INVALID_DISPLAY_ID' as const
+}
+
+export class FreshAgentInvalidTurnCursorError extends Error {
+  readonly code = 'INVALID_TURN_CURSOR' as const
+}
+
+export class FreshAgentTurnNotFoundError extends Error {
+  readonly code = 'TURN_NOT_FOUND' as const
+}
+
 export class FreshAgentAmbiguousTurnBodyError extends FreshAgentUnsupportedCapabilityError {
+  readonly ambiguousCode = 'AMBIGUOUS_NATIVE_TURN_ID' as const
 }
 
 export class FreshAgentLostSessionError extends Error {
diff --git a/test/unit/server/fresh-agent/codex-adapter.test.ts b/test/unit/server/fresh-agent/codex-adapter.test.ts
index 3b774e0b2..93a2b835e 100644
--- a/test/unit/server/fresh-agent/codex-adapter.test.ts
+++ b/test/unit/server/fresh-agent/codex-adapter.test.ts
@@ -1,7 +1,12 @@
 import { describe, expect, it, vi } from 'vitest'
 
 import { createCodexFreshAgentAdapter as createRawCodexFreshAgentAdapter } from '../../../../server/fresh-agent/adapters/codex/adapter.js'
-import { FreshAgentStaleThreadRevisionError } from '../../../../server/fresh-agent/runtime-manager.js'
+import {
+  FreshAgentInvalidDisplayIdError,
+  FreshAgentInvalidTurnCursorError,
+  FreshAgentStaleThreadRevisionError,
+  FreshAgentTurnNotFoundError,
+} from '../../../../server/fresh-agent/runtime-manager.js'
 
 const DISPLAY_SECRET = 'task-3-persisted-display-secret'
 
@@ -68,6 +73,157 @@ function makeMixedCodexTurn(id: string) {
 }
 
 describe('Codex fresh-agent adapter', () => {
+  it('paginates Codex history by display rows within a split provider turn', async () => {
+    const firstTurn = makeMixedCodexTurn('turn-1')
+    const secondTurn = makeCodexTurn('turn-2')
+    const runtime = {
+      startThread: vi.fn(),
+      resumeThread: vi.fn(),
+      readThread: vi.fn(),
+      listThreadTurns: vi.fn()
+        .mockResolvedValueOnce({ revision: 7, nextCursor: 'provider-after-turn-1', turns: [firstTurn] })
+        .mockResolvedValueOnce({ revision: 7, nextCursor: null, turns: [secondTurn] }),
+      readThreadTurn: vi.fn(),
+    }
+    const adapter = createCodexFreshAgentAdapter({ runtime: runtime as any })
+
+    const firstPage: any = await adapter.getTurnPage?.({
+      sessionType: 'freshcodex',
+      provider: 'codex',
+      threadId: 'thread-new-1',
+    }, { revision: 7, limit: 1 })
+
+    expect(firstPage.turns).toHaveLength(1)
+    expect(firstPage.turns[0]).toMatchObject({ role: 'user', summary: 'Review the diff.' })
+    expect(firstPage.nextCursor).toMatch(/^codex-cursor:v1:[A-Za-z0-9_-]+$/)
+    expect(firstPage.nextCursor).not.toContain('provider-after-turn-1')
+    expect(firstPage.nextCursor).not.toContain('turn-1')
+    expect(() => JSON.parse(Buffer.from(firstPage.nextCursor.split(':').at(-1) ?? '', 'base64url').toString('utf8'))).toThrow()
+
+    const secondPage: any = await adapter.getTurnPage?.({
+      sessionType: 'freshcodex',
+      provider: 'codex',
+      threadId: 'thread-new-1',
+    }, { revision: 7, limit: 1, cursor: firstPage.nextCursor })
+
+    expect(secondPage.turns).toHaveLength(1)
+    expect(secondPage.turns[0]).toMatchObject({ role: 'assistant', summary: 'Checking changes' })
+    expect(secondPage.turns[0].turnId).not.toBe(firstPage.turns[0].turnId)
+    expect(runtime.listThreadTurns).toHaveBeenCalledTimes(1)
+
+    const thirdPage: any = await adapter.getTurnPage?.({
+      sessionType: 'freshcodex',
+      provider: 'codex',
+      threadId: 'thread-new-1',
+    }, { revision: 7, limit: 1, cursor: secondPage.nextCursor })
+
+    expect(thirdPage.turns).toHaveLength(1)
+    expect(thirdPage.turns[0]).toMatchObject({ role: 'assistant', summary: 'Codex summary' })
+    expect(thirdPage.nextCursor).toBeNull()
+    expect(runtime.listThreadTurns).toHaveBeenCalledTimes(2)
+    expect(runtime.listThreadTurns).toHaveBeenNthCalledWith(1, {
+      threadId: 'thread-new-1',
+      limit: 1,
+      itemsView: 'full',
+    })
+    expect(runtime.listThreadTurns).toHaveBeenNthCalledWith(2, {
+      threadId: 'thread-new-1',
+      cursor: 'provider-after-turn-1',
+      limit: 1,
+      itemsView: 'full',
+    })
+  })
+
+  it('applies includeBodies to display-row limited pages with display turn body keys', async () => {
+    const runtime = {
+      startThread: vi.fn(),
+      resumeThread: vi.fn(),
+      readThread: vi.fn(),
+      listThreadTurns: vi.fn().mockResolvedValue({
+        revision: 7,
+        nextCursor: 'provider-after-turn-1',
+        turns: [makeMixedCodexTurn('turn-1')],
+      }),
+      readThreadTurn: vi.fn(),
+    }
+    const adapter = createCodexFreshAgentAdapter({ runtime: runtime as any })
+
+    const page: any = await adapter.getTurnPage?.({
+      sessionType: 'freshcodex',
+      provider: 'codex',
+      threadId: 'thread-new-1',
+    }, { revision: 7, limit: 1, includeBodies: true })
+
+    expect(page.turns).toHaveLength(1)
+    expect(Object.keys(page.bodies)).toEqual([page.turns[0].turnId])
+    expect(page.bodies[page.turns[0].turnId]).toMatchObject({ role: 'user' })
+    expect(page.bodies).not.toHaveProperty('turn-1')
+  })
+
+  it('rejects malformed, cross-thread, expired, and stale-revision display cursors with typed errors', async () => {
+    const runtime = {
+      startThread: vi.fn(),
+      resumeThread: vi.fn(),
+      readThread: vi.fn(),
+      listThreadTurns: vi.fn().mockResolvedValue({
+        revision: 7,
+        nextCursor: 'provider-after-turn-1',
+        turns: [makeMixedCodexTurn('turn-1')],
+      }),
+      readThreadTurn: vi.fn(),
+    }
+    const adapter = createCodexFreshAgentAdapter({ runtime: runtime as any })
+    const firstPage: any = await adapter.getTurnPage?.({
+      sessionType: 'freshcodex',
+      provider: 'codex',
+      threadId: 'thread-new-1',
+    }, { revision: 7, limit: 1 })
+
+    await expect(adapter.getTurnPage?.({
+      sessionType: 'freshcodex',
+      provider: 'codex',
+      threadId: 'thread-new-1',
+    }, { revision: 7, limit: 1, cursor: 'not-a-codex-cursor' })).rejects.toBeInstanceOf(FreshAgentInvalidTurnCursorError)
+
+    await expect(adapter.getTurnPage?.({
+      sessionType: 'freshcodex',
+      provider: 'codex',
+      threadId: 'other-thread',
+    }, { revision: 7, limit: 1, cursor: firstPage.nextCursor })).rejects.toBeInstanceOf(FreshAgentInvalidTurnCursorError)
+
+    await expect(adapter.getTurnPage?.({
+      sessionType: 'freshcodex',
+      provider: 'codex',
+      threadId: 'thread-new-1',
+    }, { revision: 8, limit: 1, cursor: firstPage.nextCursor })).rejects.toBeInstanceOf(FreshAgentStaleThreadRevisionError)
+
+    await adapter.shutdown?.()
+    await expect(adapter.getTurnPage?.({
+      sessionType: 'freshcodex',
+      provider: 'codex',
+      threadId: 'thread-new-1',
+    }, { revision: 7, limit: 1, cursor: firstPage.nextCursor })).rejects.toBeInstanceOf(FreshAgentInvalidTurnCursorError)
+  })
+
+  it('throws a typed invalid display id error for malformed Codex display body ids', async () => {
+    const runtime = {
+      startThread: vi.fn(),
+      resumeThread: vi.fn(),
+      readThread: vi.fn(),
+      listThreadTurns: vi.fn(),
+      readThreadTurn: vi.fn(),
+    }
+    const adapter = createCodexFreshAgentAdapter({ runtime: runtime as any })
+
+    await expect(adapter.getTurnBody?.({
+      sessionType: 'freshcodex',
+      provider: 'codex',
+      threadId: 'thread-new-1',
+      turnId: 'codex-display:v1:not-a-valid-envelope',
+    }, 7)).rejects.toBeInstanceOf(FreshAgentInvalidDisplayIdError)
+    expect(runtime.readThreadTurn).not.toHaveBeenCalled()
+  })
+
   it('allocates separate runtimes for fresh Codex threads in different cwd values', async () => {
     const runtimes = ['/repo/one', '/repo/two'].map((cwd, index) => ({
       startThread: vi.fn().mockImplementation(async (input) => {
@@ -299,7 +455,7 @@ describe('Codex fresh-agent adapter', () => {
       provider: 'codex',
       threadId: 'thread-new-1',
       turnId: 'codex-display:v1:not-a-valid-envelope',
-    }, 7)).resolves.toBeNull()
+    }, 7)).rejects.toBeInstanceOf(FreshAgentInvalidDisplayIdError)
     expect(runtime.readThreadTurn).not.toHaveBeenCalled()
 
     await expect(adapter.getTurnBody?.({
@@ -307,7 +463,7 @@ describe('Codex fresh-agent adapter', () => {
       provider: 'codex',
       threadId: 'thread-new-1',
       turnId: 'codex-display:v1:abcdefghijklmnopqrstu1',
-    }, 7)).resolves.toBeNull()
+    }, 7)).rejects.toBeInstanceOf(FreshAgentTurnNotFoundError)
     expect(runtime.readThreadTurn).not.toHaveBeenCalled()
   })
 
diff --git a/test/unit/server/fresh-agent/router.test.ts b/test/unit/server/fresh-agent/router.test.ts
index 93eaf52f0..d12216683 100644
--- a/test/unit/server/fresh-agent/router.test.ts
+++ b/test/unit/server/fresh-agent/router.test.ts
@@ -2,9 +2,53 @@ import { describe, expect, it, vi } from 'vitest'
 import express from 'express'
 import request from 'supertest'
 
+import { createCodexFreshAgentAdapter } from '../../../../server/fresh-agent/adapters/codex/adapter.js'
+import { FreshAgentProviderRegistry } from '../../../../server/fresh-agent/provider-registry.js'
 import { createFreshAgentRouter } from '../../../../server/fresh-agent/router.js'
 import { FreshAgentRuntimeManager, FreshAgentStaleThreadRevisionError } from '../../../../server/fresh-agent/runtime-manager.js'
 
+function makeCodexThread(id: string, turns: unknown[] = []) {
+  return {
+    id,
+    sessionId: id,
+    preview: 'Codex summary',
+    ephemeral: false,
+    modelProvider: 'openai',
+    createdAt: 1770000000,
+    updatedAt: 7,
+    status: { type: 'idle' },
+    cwd: '/repo',
+    cliVersion: 'codex-cli 0.129.0',
+    source: 'appServer',
+    turns,
+  }
+}
+
+function makeMixedCodexTurn(id: string) {
+  return {
+    id,
+    status: 'completed',
+    items: [
+      {
+        type: 'userMessage',
+        id: `${id}:user`,
+        content: [{ type: 'text', text: 'Review the diff.' }],
+      },
+      {
+        type: 'reasoning',
+        id: `${id}:reasoning`,
+        summary: ['Checking changes'],
+        content: [],
+      },
+      {
+        type: 'agentMessage',
+        id: `${id}:assistant`,
+        text: 'The patch is safe.',
+      },
+    ],
+  }
+}
+
 describe('fresh-agent router', () => {
   it('returns 409 for stale thread revisions instead of mixing bodies from different revisions', async () => {
     const manager = {
@@ -21,4 +65,107 @@ describe('fresh-agent router', () => {
     expect(response.body.code).toBe('STALE_THREAD_REVISION')
     expect(response.body.currentRevision).toBe(7)
   })
+
+  it('serves Freshcodex split display turns and maps Codex boundary errors intentionally', async () => {
+    const durableTurn = makeMixedCodexTurn('turn-1')
+    const runtime = {
+      startThread: vi.fn(),
+      resumeThread: vi.fn(),
+      readThread: vi.fn().mockResolvedValue({
+        thread: makeCodexThread('thread-new-1', [durableTurn]),
+      }),
+      listThreadTurns: vi.fn().mockResolvedValue({
+        revision: 7,
+        nextCursor: null,
+        turns: [durableTurn],
+      }),
+      readThreadTurn: vi.fn().mockResolvedValue(durableTurn),
+    }
+    const adapter = createCodexFreshAgentAdapter({
+      displayIdSecret: 'router-task-4-secret',
+      runtime: runtime as any,
+    })
+    const registry = new FreshAgentProviderRegistry([{
+      sessionType: 'freshcodex',
+      runtimeProvider: 'codex',
+      adapter,
+    }])
+    const runtimeManager = new FreshAgentRuntimeManager({ registry })
+    const app = express()
+    app.use('/api', createFreshAgentRouter({ runtimeManager }))
+
+    const snapshot = await request(app)
+      .get('/api/fresh-agent/threads/freshcodex/codex/thread-new-1')
+      .expect(200)
+    expect(snapshot.body.turns).toHaveLength(2)
+    expect(snapshot.body.turns.map((turn: any) => turn.role)).toEqual(['user', 'assistant'])
+    expect(JSON.stringify(snapshot.body)).not.toContain('providerTurnId')
+
+    const firstPage = await request(app)
+      .get('/api/fresh-agent/threads/freshcodex/codex/thread-new-1/turns?revision=7&limit=1')
+      .expect(200)
+    expect(firstPage.body.turns).toHaveLength(1)
+    expect(firstPage.body.turns[0]).toMatchObject({ role: 'user' })
+    expect(firstPage.body.nextCursor).toMatch(/^codex-cursor:v1:/)
+    expect(JSON.stringify(firstPage.body)).not.toContain('providerTurnId')
+
+    const secondPage = await request(app)
+      .get('/api/fresh-agent/threads/freshcodex/codex/thread-new-1/turns')
+      .query({ revision: '7', limit: '1', cursor: firstPage.body.nextCursor })
+      .expect(200)
+    expect(secondPage.body.turns).toHaveLength(1)
+    expect(secondPage.body.turns[0]).toMatchObject({ role: 'assistant' })
+    expect(JSON.stringify(secondPage.body)).not.toContain('providerTurnId')
+
+    const body = await request(app)
+      .get(`/api/fresh-agent/threads/freshcodex/codex/thread-new-1/turns/${encodeURIComponent(secondPage.body.turns[0].turnId)}?revision=7`)
+      .expect(200)
+    expect(body.body).toMatchObject({
+      turnId: secondPage.body.turns[0].turnId,
+      role: 'assistant',
+      threadId: 'thread-new-1',
+      revision: 7,
+    })
+    expect(runtime.readThreadTurn).toHaveBeenCalledWith({
+      threadId: 'thread-new-1',
+      turnId: 'turn-1',
+      revision: 7,
+    })
+    expect(JSON.stringify(body.body)).not.toContain('providerTurnId')
+
+    const malformedCursor = await request(app)
+      .get('/api/fresh-agent/threads/freshcodex/codex/thread-new-1/turns?revision=7&cursor=bad-cursor')
+      .expect(400)
+    expect(malformedCursor.body.code).toBe('INVALID_TURN_CURSOR')
+
+    const malformedDisplayId = await request(app)
+      .get('/api/fresh-agent/threads/freshcodex/codex/thread-new-1/turns/codex-display:v1:not-a-valid-envelope?revision=7')
+      .expect(400)
+    expect(malformedDisplayId.body.code).toBe('INVALID_DISPLAY_ID')
+
+    runtime.listThreadTurns.mockResolvedValueOnce({
+      revision: 9,
+      nextCursor: null,
+      turns: [durableTurn],
+    })
+    const staleRevision = await request(app)
+      .get('/api/fresh-agent/threads/freshcodex/codex/thread-new-1/turns/codex-display:v1:abcdefghijklmnopqrstu1?revision=7')
+      .expect(409)
+    expect(staleRevision.body.code).toBe('STALE_THREAD_REVISION')
+
+    const ambiguousNativeId = await request(app)
+      .get('/api/fresh-agent/threads/freshcodex/codex/thread-new-1/turns/turn-1?revision=7')
+      .expect(409)
+    expect(ambiguousNativeId.body.code).toBe('AMBIGUOUS_NATIVE_TURN_ID')
+
+    runtime.listThreadTurns.mockResolvedValueOnce({
+      revision: 7,
+      nextCursor: null,
+      turns: [durableTurn],
+    })
+    const exactMiss = await request(app)
+      .get('/api/fresh-agent/threads/freshcodex/codex/thread-new-1/turns/codex-display:v1:abcdefghijklmnopqrstu1?revision=7')
+      .expect(404)
+    expect(exactMiss.body.code).toBe('TURN_NOT_FOUND')
+  })
 })

From 056ffc7114ee5caadb210a6bc4e7bd03c3930250 Mon Sep 17 00:00:00 2001
From: Codex <codex@openai.com>
Date: Fri, 19 Jun 2026 02:45:03 -0700
Subject: [PATCH 24/33] fix: distinguish stale codex display body reads

---
 server/fresh-agent/adapters/codex/adapter.ts  | 34 +++++---
 server/fresh-agent/router.ts                  |  8 ++
 server/fresh-agent/runtime-manager.ts         |  8 ++
 .../server/fresh-agent/codex-adapter.test.ts  | 82 +++++++++++++++++++
 test/unit/server/fresh-agent/router.test.ts   | 21 +++++
 5 files changed, 141 insertions(+), 12 deletions(-)

diff --git a/server/fresh-agent/adapters/codex/adapter.ts b/server/fresh-agent/adapters/codex/adapter.ts
index ed6dad6f7..8127973a4 100644
--- a/server/fresh-agent/adapters/codex/adapter.ts
+++ b/server/fresh-agent/adapters/codex/adapter.ts
@@ -8,6 +8,7 @@ import {
   FreshAgentInvalidDisplayIdError,
   FreshAgentInvalidTurnCursorError,
   FreshAgentStaleThreadRevisionError,
+  FreshAgentUnprovableThreadRevisionError,
   FreshAgentTurnNotFoundError,
 } from '../../runtime-manager.js'
 import type {
@@ -640,17 +641,26 @@ export function createCodexFreshAgentAdapter(deps: {
     revision: number,
     displayTurnId: string,
   ): Promise<DisplayIndexEntry | null> => {
-    const rawPage = await runtime.listThreadTurns({
-      threadId,
-      limit: 100,
-      itemsView: 'full',
-    })
-    const currentRevision = Number(rawPage.revision ?? revision)
-    normalizeRawPage({ threadId, revision: currentRevision, rawPage })
-    if (currentRevision !== revision) {
-      throw new FreshAgentStaleThreadRevisionError(currentRevision)
-    }
-    return findDisplayIndexEntry(threadId, revision, displayTurnId) ?? null
+    let cursor: string | undefined
+    do {
+      const rawPage = await runtime.listThreadTurns({
+        threadId,
+        ...(cursor ? { cursor } : {}),
+        limit: 100,
+        itemsView: 'full',
+      })
+      const currentRevision = Number(rawPage.revision ?? revision)
+      normalizeRawPage({ threadId, revision: currentRevision, rawPage })
+      if (currentRevision !== revision) {
+        throw new FreshAgentStaleThreadRevisionError(currentRevision)
+      }
+      const entry = findDisplayIndexEntry(threadId, revision, displayTurnId)
+      if (entry) return entry
+      cursor = typeof rawPage.nextCursor === 'string' && rawPage.nextCursor.length > 0
+        ? rawPage.nextCursor
+        : undefined
+    } while (cursor)
+    return null
   }
 
   const clearThreadState = (threadId: string) => {
@@ -1098,7 +1108,7 @@ export function createCodexFreshAgentAdapter(deps: {
           })
         } catch (error) {
           if (error instanceof CodexDisplayTurnNotFoundError) {
-            throw new FreshAgentTurnNotFoundError('Codex display turn was not found in the requested thread revision.')
+            throw new FreshAgentUnprovableThreadRevisionError(revision)
           }
           throw error
         }
diff --git a/server/fresh-agent/router.ts b/server/fresh-agent/router.ts
index 3aaf4cb8b..983f83abc 100644
--- a/server/fresh-agent/router.ts
+++ b/server/fresh-agent/router.ts
@@ -10,6 +10,7 @@ import {
   FreshAgentRuntimeManager,
   FreshAgentRuntimeUnavailableError,
   FreshAgentStaleThreadRevisionError,
+  FreshAgentUnprovableThreadRevisionError,
   FreshAgentUnsupportedCapabilityError,
   FreshAgentInvalidDisplayIdError,
   FreshAgentInvalidTurnCursorError,
@@ -118,6 +119,13 @@ export function createFreshAgentRouter(deps: {
         currentRevision: error.currentRevision,
       })
     }
+    if (error instanceof FreshAgentUnprovableThreadRevisionError) {
+      return res.status(409).json({
+        error: error.message,
+        code: error.code,
+        requestedRevision: error.requestedRevision,
+      })
+    }
     if (error instanceof FreshAgentInvalidDisplayIdError) {
       return res.status(400).json({ error: error.message, code: error.code })
     }
diff --git a/server/fresh-agent/runtime-manager.ts b/server/fresh-agent/runtime-manager.ts
index 25c8dfc34..d8684ac10 100644
--- a/server/fresh-agent/runtime-manager.ts
+++ b/server/fresh-agent/runtime-manager.ts
@@ -34,6 +34,14 @@ export class FreshAgentStaleThreadRevisionError extends Error {
   }
 }
 
+export class FreshAgentUnprovableThreadRevisionError extends Error {
+  readonly code = 'UNPROVABLE_THREAD_REVISION' as const
+
+  constructor(readonly requestedRevision: number) {
+    super('Fresh-agent thread revision could not be proven from the current provider body')
+  }
+}
+
 export class FreshAgentUnsupportedCapabilityError extends Error {
   readonly code = 'FRESH_AGENT_UNSUPPORTED_CAPABILITY' as const
 }
diff --git a/test/unit/server/fresh-agent/codex-adapter.test.ts b/test/unit/server/fresh-agent/codex-adapter.test.ts
index 93a2b835e..e8576e59c 100644
--- a/test/unit/server/fresh-agent/codex-adapter.test.ts
+++ b/test/unit/server/fresh-agent/codex-adapter.test.ts
@@ -1,10 +1,12 @@
 import { describe, expect, it, vi } from 'vitest'
 
 import { createCodexFreshAgentAdapter as createRawCodexFreshAgentAdapter } from '../../../../server/fresh-agent/adapters/codex/adapter.js'
+import { createCodexDisplayId } from '../../../../server/fresh-agent/adapters/codex/normalize.js'
 import {
   FreshAgentInvalidDisplayIdError,
   FreshAgentInvalidTurnCursorError,
   FreshAgentStaleThreadRevisionError,
+  FreshAgentUnprovableThreadRevisionError,
   FreshAgentTurnNotFoundError,
 } from '../../../../server/fresh-agent/runtime-manager.js'
 
@@ -224,6 +226,86 @@ describe('Codex fresh-agent adapter', () => {
     expect(runtime.readThreadTurn).not.toHaveBeenCalled()
   })
 
+  it('returns unprovable revision when an indexed display body no longer matches the provider turn body', async () => {
+    const durableTurn = makeMixedCodexTurn('turn-1')
+    const runtime = {
+      startThread: vi.fn(),
+      resumeThread: vi.fn(),
+      readThread: vi.fn(),
+      listThreadTurns: vi.fn().mockResolvedValue({
+        revision: 7,
+        nextCursor: null,
+        turns: [durableTurn],
+      }),
+      readThreadTurn: vi.fn().mockResolvedValue(makeCodexTurn('turn-1')),
+    }
+    const adapter = createCodexFreshAgentAdapter({ runtime: runtime as any })
+    const page: any = await adapter.getTurnPage?.({
+      sessionType: 'freshcodex',
+      provider: 'codex',
+      threadId: 'thread-new-1',
+    }, { revision: 7, limit: 1 })
+
+    await expect(adapter.getTurnBody?.({
+      sessionType: 'freshcodex',
+      provider: 'codex',
+      threadId: 'thread-new-1',
+      turnId: page.turns[0].turnId,
+    }, 7)).rejects.toBeInstanceOf(FreshAgentUnprovableThreadRevisionError)
+  })
+
+  it('rescans display indexes through provider pagination before returning an exact miss', async () => {
+    const targetTurn = makeMixedCodexTurn('turn-target')
+    const targetDisplayTurnId = createCodexDisplayId({
+      secret: DISPLAY_SECRET,
+      threadId: 'thread-new-1',
+      providerTurnId: 'turn-target',
+      role: 'user',
+      itemIds: ['turn-target:user'],
+      partIndexes: [0],
+    })
+    const runtime = {
+      startThread: vi.fn(),
+      resumeThread: vi.fn(),
+      readThread: vi.fn(),
+      listThreadTurns: vi.fn()
+        .mockResolvedValueOnce({
+          revision: 7,
+          nextCursor: 'provider-page-2',
+          turns: [makeCodexTurn('turn-before-target')],
+        })
+        .mockResolvedValueOnce({
+          revision: 7,
+          nextCursor: null,
+          turns: [targetTurn],
+        }),
+      readThreadTurn: vi.fn().mockResolvedValue(targetTurn),
+    }
+    const adapter = createCodexFreshAgentAdapter({ runtime: runtime as any })
+
+    await expect(adapter.getTurnBody?.({
+      sessionType: 'freshcodex',
+      provider: 'codex',
+      threadId: 'thread-new-1',
+      turnId: targetDisplayTurnId,
+    }, 7)).resolves.toMatchObject({
+      turnId: targetDisplayTurnId,
+      role: 'user',
+      summary: 'Review the diff.',
+    })
+    expect(runtime.listThreadTurns).toHaveBeenNthCalledWith(1, {
+      threadId: 'thread-new-1',
+      limit: 100,
+      itemsView: 'full',
+    })
+    expect(runtime.listThreadTurns).toHaveBeenNthCalledWith(2, {
+      threadId: 'thread-new-1',
+      cursor: 'provider-page-2',
+      limit: 100,
+      itemsView: 'full',
+    })
+  })
+
   it('allocates separate runtimes for fresh Codex threads in different cwd values', async () => {
     const runtimes = ['/repo/one', '/repo/two'].map((cwd, index) => ({
       startThread: vi.fn().mockImplementation(async (input) => {
diff --git a/test/unit/server/fresh-agent/router.test.ts b/test/unit/server/fresh-agent/router.test.ts
index d12216683..edd7e0b08 100644
--- a/test/unit/server/fresh-agent/router.test.ts
+++ b/test/unit/server/fresh-agent/router.test.ts
@@ -49,6 +49,20 @@ function makeMixedCodexTurn(id: string) {
   }
 }
 
+function makeCodexTurn(id: string) {
+  return {
+    id,
+    status: 'completed',
+    items: [{
+      type: 'agentMessage',
+      id: `${id}:item-1`,
+      text: 'Codex summary',
+      phase: null,
+      memoryCitation: null,
+    }],
+  }
+}
+
 describe('fresh-agent router', () => {
   it('returns 409 for stale thread revisions instead of mixing bodies from different revisions', async () => {
     const manager = {
@@ -133,6 +147,13 @@ describe('fresh-agent router', () => {
     })
     expect(JSON.stringify(body.body)).not.toContain('providerTurnId')
 
+    runtime.readThreadTurn.mockResolvedValueOnce(makeCodexTurn('turn-1'))
+    const unprovableBody = await request(app)
+      .get(`/api/fresh-agent/threads/freshcodex/codex/thread-new-1/turns/${encodeURIComponent(secondPage.body.turns[0].turnId)}?revision=7`)
+      .expect(409)
+    expect(unprovableBody.body.code).toBe('UNPROVABLE_THREAD_REVISION')
+    expect(unprovableBody.body.requestedRevision).toBe(7)
+
     const malformedCursor = await request(app)
       .get('/api/fresh-agent/threads/freshcodex/codex/thread-new-1/turns?revision=7&cursor=bad-cursor')
       .expect(400)

From b85e67c7802e6a61a65ca1b74e89b9472318a264 Mon Sep 17 00:00:00 2001
From: Codex <codex@openai.com>
Date: Fri, 19 Jun 2026 02:48:58 -0700
Subject: [PATCH 25/33] fix: stop codex cursor refetch after final turn

---
 server/fresh-agent/adapters/codex/adapter.ts  |  2 +-
 .../server/fresh-agent/codex-adapter.test.ts  | 35 +++++++++++++++++++
 2 files changed, 36 insertions(+), 1 deletion(-)

diff --git a/server/fresh-agent/adapters/codex/adapter.ts b/server/fresh-agent/adapters/codex/adapter.ts
index 8127973a4..be7f75315 100644
--- a/server/fresh-agent/adapters/codex/adapter.ts
+++ b/server/fresh-agent/adapters/codex/adapter.ts
@@ -568,7 +568,7 @@ export function createCodexFreshAgentAdapter(deps: {
       providerCursor = cursor.providerCursor
       if (cursor.rawTurn) {
         const nextCursor = appendTurnRows(cursor.rawTurn, cursor.nextDisplayOffset, cursor.providerCursor)
-        if (turns.length >= limit || nextCursor) {
+        if (turns.length >= limit || nextCursor || !cursor.providerCursor) {
           return FreshAgentTurnPageSchema.parse({
             sessionType: 'freshcodex',
             provider: 'codex',
diff --git a/test/unit/server/fresh-agent/codex-adapter.test.ts b/test/unit/server/fresh-agent/codex-adapter.test.ts
index e8576e59c..f2307ed8d 100644
--- a/test/unit/server/fresh-agent/codex-adapter.test.ts
+++ b/test/unit/server/fresh-agent/codex-adapter.test.ts
@@ -136,6 +136,41 @@ describe('Codex fresh-agent adapter', () => {
     })
   })
 
+  it('does not refetch from the beginning after draining a final cached provider turn with a larger page limit', async () => {
+    const runtime = {
+      startThread: vi.fn(),
+      resumeThread: vi.fn(),
+      readThread: vi.fn(),
+      listThreadTurns: vi.fn().mockResolvedValue({
+        revision: 7,
+        nextCursor: null,
+        turns: [makeMixedCodexTurn('turn-1')],
+      }),
+      readThreadTurn: vi.fn(),
+    }
+    const adapter = createCodexFreshAgentAdapter({ runtime: runtime as any })
+
+    const firstPage: any = await adapter.getTurnPage?.({
+      sessionType: 'freshcodex',
+      provider: 'codex',
+      threadId: 'thread-new-1',
+    }, { revision: 7, limit: 1 })
+    expect(firstPage.turns).toHaveLength(1)
+    expect(firstPage.turns[0]).toMatchObject({ role: 'user' })
+
+    const secondPage: any = await adapter.getTurnPage?.({
+      sessionType: 'freshcodex',
+      provider: 'codex',
+      threadId: 'thread-new-1',
+    }, { revision: 7, limit: 30, cursor: firstPage.nextCursor })
+
+    expect(secondPage.turns).toHaveLength(1)
+    expect(secondPage.turns[0]).toMatchObject({ role: 'assistant' })
+    expect(secondPage.turns.map((turn: any) => turn.turnId)).not.toContain(firstPage.turns[0].turnId)
+    expect(secondPage.nextCursor).toBeNull()
+    expect(runtime.listThreadTurns).toHaveBeenCalledTimes(1)
+  })
+
   it('applies includeBodies to display-row limited pages with display turn body keys', async () => {
     const runtime = {
       startThread: vi.fn(),

From 6c3a5c1132bc6808b7649f83e9b0f744bb789c0f Mon Sep 17 00:00:00 2001
From: Codex <codex@openai.com>
Date: Fri, 19 Jun 2026 02:55:15 -0700
Subject: [PATCH 26/33] fix: enforce one-speaker provider turns

---
 .../adapters/opencode/normalize.ts            | 26 +++++--
 .../fresh-agent/claude-normalize.test.ts      | 50 +++++++++++++
 .../fresh-agent/opencode-normalize.test.ts    | 74 ++++++++++++++++---
 3 files changed, 134 insertions(+), 16 deletions(-)

diff --git a/server/fresh-agent/adapters/opencode/normalize.ts b/server/fresh-agent/adapters/opencode/normalize.ts
index ba8710c09..10d0529ca 100644
--- a/server/fresh-agent/adapters/opencode/normalize.ts
+++ b/server/fresh-agent/adapters/opencode/normalize.ts
@@ -21,6 +21,12 @@ type OpencodeExportWithPageMetadata = OpencodeExport & {
   nextCursor?: string | null
 }
 
+function normalizeOpencodeRole(value: unknown): FreshAgentTurn['role'] {
+  return value === 'user' || value === 'assistant' || value === 'system' || value === 'tool'
+    ? value
+    : undefined
+}
+
 function modelFromInfo(info: Record<string, any> | undefined): string | undefined {
   const providerId = info?.providerID ?? info?.model?.providerID
   const modelId = info?.modelID ?? info?.model?.modelID ?? info?.model?.id
@@ -199,14 +205,18 @@ function collectOpencodePartMetadata(messages: NonNullable<OpencodeExport['messa
   }
 }
 
-export function normalizeOpencodeTurn(message: NonNullable<OpencodeExport['messages']>[number], ordinal: number): FreshAgentTurn {
+export function normalizeOpencodeTurn(
+  message: NonNullable<OpencodeExport['messages']>[number],
+  ordinal: number,
+): FreshAgentTurn | null {
   const info = message.info ?? {}
   const id = typeof info.id === 'string' && info.id.length > 0 ? info.id : `message-${ordinal}`
-  const role: FreshAgentTurn['role'] = info.role === 'user' || info.role === 'assistant' || info.role === 'system' || info.role === 'tool' ? info.role : undefined
+  const role = normalizeOpencodeRole(info.role)
   const parts = Array.isArray(message.parts) ? message.parts : []
   const items = parts
     .map((part, index) => itemFromPart(part, `${id}:part-${index}`, role))
     .filter((item): item is FreshAgentTranscriptItem => Boolean(item))
+  if (!role && items.length > 0) return null
   const textSummary = items.find((item) => item.kind === 'text')?.text
   const reasoningSummary = items.find((item) => item.kind === 'reasoning')?.summary?.[0]
   return {
@@ -233,7 +243,9 @@ export function normalizeOpencodeSnapshot(input: {
 }): FreshAgentSnapshot {
   const info = input.exported?.info ?? {}
   const messages = Array.isArray(input.exported?.messages) ? input.exported.messages : []
-  const turns = messages.map((message, index) => normalizeOpencodeTurn(message, index))
+  const turns = messages
+    .map((message, index) => normalizeOpencodeTurn(message, index))
+    .filter((turn): turn is FreshAgentTurn => Boolean(turn))
   const sessionModel = modelFromInfo(info) ?? input.model
   const durableSessionId = typeof info.id === 'string' && info.id.length > 0 ? info.id : input.threadId
   const opencodeExtensions = collectOpencodePartMetadata(messages)
@@ -287,7 +299,9 @@ export function normalizeOpencodeTurnPage(input: {
     threadId: input.threadId,
     revision: input.revision,
     nextCursor: typeof nextCursor === 'string' ? nextCursor : null,
-    turns: messages.map((message, index) => normalizeOpencodeTurn(message, index)),
+    turns: messages
+      .map((message, index) => normalizeOpencodeTurn(message, index))
+      .filter((turn): turn is FreshAgentTurn => Boolean(turn)),
   }
 }
 
@@ -300,8 +314,10 @@ export function normalizeOpencodeTurnBody(input: {
   const messages = Array.isArray(input.exported?.messages) ? input.exported.messages : []
   const index = messages.findIndex((message) => message.info?.id === input.turnId)
   if (index < 0) return null
+  const turn = normalizeOpencodeTurn(messages[index], index)
+  if (!turn) return null
   return {
-    ...normalizeOpencodeTurn(messages[index], index),
+    ...turn,
     sessionType: 'freshopencode',
     provider: 'opencode',
     threadId: input.threadId,
diff --git a/test/unit/server/fresh-agent/claude-normalize.test.ts b/test/unit/server/fresh-agent/claude-normalize.test.ts
index ca7333e52..30255f2ed 100644
--- a/test/unit/server/fresh-agent/claude-normalize.test.ts
+++ b/test/unit/server/fresh-agent/claude-normalize.test.ts
@@ -43,4 +43,54 @@ describe('Claude fresh-agent normalization', () => {
       costUsd: 1.25,
     })
   })
+
+  it('keeps user and assistant messages as separate display turns with their native turnIds', () => {
+    const snapshot = normalizeClaudeThreadSnapshot({
+      threadId: 'sdk-claude-invariant',
+      resolved: {
+        kind: 'resolved',
+        queryId: 'sdk-claude-invariant',
+        liveSessionId: 'sdk-claude-invariant',
+        timelineSessionId: '00000000-0000-4000-8000-000000000222',
+        readiness: 'merged',
+        revision: 2,
+        latestTurnId: 'turn:assistant-1',
+        turns: [
+          {
+            sessionId: '00000000-0000-4000-8000-000000000222',
+            turnId: 'turn:user-1',
+            messageId: 'user-1',
+            ordinal: 0,
+            source: 'durable',
+            message: {
+              role: 'user',
+              content: [{ type: 'text', text: 'Inspect the config.' }],
+              timestamp: '2026-04-18T12:00:00.000Z',
+              messageId: 'user-1',
+            },
+          },
+          {
+            sessionId: '00000000-0000-4000-8000-000000000222',
+            turnId: 'turn:assistant-1',
+            messageId: 'assistant-1',
+            ordinal: 1,
+            source: 'durable',
+            message: {
+              role: 'assistant',
+              content: [{ type: 'text', text: 'Inspecting the config now.' }],
+              timestamp: '2026-04-18T12:00:01.000Z',
+              messageId: 'assistant-1',
+            },
+          },
+        ],
+      },
+      status: 'running',
+    })
+
+    expect(snapshot.turns).toHaveLength(2)
+    expect(snapshot.turns).toMatchObject([
+      { turnId: 'turn:user-1', messageId: 'user-1', role: 'user', summary: 'Inspect the config.' },
+      { turnId: 'turn:assistant-1', messageId: 'assistant-1', role: 'assistant', summary: 'Inspecting the config now.' },
+    ])
+  })
 })
diff --git a/test/unit/server/fresh-agent/opencode-normalize.test.ts b/test/unit/server/fresh-agent/opencode-normalize.test.ts
index 0c8bb46f4..9998be50b 100644
--- a/test/unit/server/fresh-agent/opencode-normalize.test.ts
+++ b/test/unit/server/fresh-agent/opencode-normalize.test.ts
@@ -37,7 +37,7 @@ describe('OpenCode fresh-agent normalization', () => {
           summary: 'Compacted older OpenCode context.',
         },
       ],
-    }, 0)
+    }, 0)!
 
     expect(turn.items).toEqual([
       {
@@ -70,9 +70,9 @@ describe('OpenCode fresh-agent normalization', () => {
 
   it('guards missing patch files and returns an empty completed file change', () => {
     const turn = normalizeOpencodeTurn({
-      info: { id: 'msg-patch' },
+      info: { id: 'msg-patch', role: 'assistant' },
       parts: [{ id: 'part-patch-empty', type: 'patch', diff: '@@ empty @@' }],
-    }, 0)
+    }, 0)!
 
     expect(turn.items).toEqual([
       {
@@ -161,7 +161,7 @@ describe('OpenCode fresh-agent normalization', () => {
     const turn = normalizeOpencodeTurn({
       info: { id: 'msg-user-quoted', role: 'user' },
       parts: [{ id: 'part-user-quoted', type: 'text', text: '"Do a directory listing."' }],
-    }, 0)
+    }, 0)!
 
     expect(turn.role).toBe('user')
     expect(turn.items).toEqual([
@@ -174,7 +174,7 @@ describe('OpenCode fresh-agent normalization', () => {
     const turn = normalizeOpencodeTurn({
       info: { id: 'msg-user-plain', role: 'user' },
       parts: [{ id: 'part-user-plain', type: 'text', text: 'Do a directory listing.' }],
-    }, 0)
+    }, 0)!
 
     expect(turn.items[0]?.text).toBe('Do a directory listing.')
     expect(turn.summary).toBe('Do a directory listing.')
@@ -184,7 +184,7 @@ describe('OpenCode fresh-agent normalization', () => {
     const turn = normalizeOpencodeTurn({
       info: { id: 'msg-assistant-quoted', role: 'assistant' },
       parts: [{ id: 'part-assistant-quoted', type: 'text', text: '"Hello, world."' }],
-    }, 0)
+    }, 0)!
 
     expect(turn.role).toBe('assistant')
     expect(turn.items[0]?.text).toBe('"Hello, world."')
@@ -194,7 +194,7 @@ describe('OpenCode fresh-agent normalization', () => {
     const turn = normalizeOpencodeTurn({
       info: { id: 'msg-user-nested', role: 'user' },
       parts: [{ id: 'part-user-nested', type: 'text', text: '""nested" quotes"' }],
-    }, 0)
+    }, 0)!
 
     expect(turn.items[0]?.text).toBe('"nested" quotes')
   })
@@ -214,7 +214,7 @@ describe('OpenCode fresh-agent normalization', () => {
           text: 'Intro <thinking reason="plan">I could change all instances.</thinking> done.',
         },
       ],
-    }, 0)
+    }, 0)!
 
     expect(turn.items).toEqual([
       { id: 'part-think', kind: 'text', text: 'Before  and after.' },
@@ -229,7 +229,7 @@ describe('OpenCode fresh-agent normalization', () => {
       parts: [
         { id: 'part-user-think', type: 'text', text: 'Why did the assistant say <think>secret</think>?' },
       ],
-    }, 0)
+    }, 0)!
 
     expect(turn.items).toEqual([
       { id: 'part-user-think', kind: 'text', text: 'Why did the assistant say <think>secret</think>?' },
@@ -240,7 +240,7 @@ describe('OpenCode fresh-agent normalization', () => {
     const turn = normalizeOpencodeTurn({
       info: { id: 'msg-preserve-ws', role: 'assistant' },
       parts: [{ id: 'part-ws', type: 'text', text: '  leading\n  and trailing  ' }],
-    }, 0)
+    }, 0)!
 
     expect(turn.items).toEqual([{ id: 'part-ws', kind: 'text', text: '  leading\n  and trailing  ' }])
   })
@@ -250,13 +250,65 @@ describe('OpenCode fresh-agent normalization', () => {
     const turn = normalizeOpencodeTurn({
       info: { id: 'msg-reasoning', role: 'assistant' },
       parts: [{ id: 'part-reasoning', type: 'reasoning', text }],
-    }, 0)
+    }, 0)!
 
     expect(turn.items).toEqual([
       { id: 'part-reasoning', kind: 'reasoning', summary: [text], content: [text], text },
     ])
   })
 
+  it('keeps user and assistant messages as separate display turns with their native turnIds', () => {
+    const snapshot = normalizeOpencodeSnapshot({
+      sessionType: 'freshopencode',
+      threadId: 'ses-separated-turns',
+      exported: {
+        messages: [
+          {
+            info: { id: 'msg-user', role: 'user' },
+            parts: [{ id: 'part-user', type: 'text', text: 'Summarize the changes.' }],
+          },
+          {
+            info: { id: 'msg-assistant', role: 'assistant' },
+            parts: [{ id: 'part-assistant', type: 'text', text: 'Summarizing now.' }],
+          },
+        ],
+      },
+    })
+
+    expect(snapshot.turns).toHaveLength(2)
+    expect(snapshot.turns).toMatchObject([
+      { turnId: 'msg-user', messageId: 'msg-user', role: 'user', summary: 'Summarize the changes.' },
+      { turnId: 'msg-assistant', messageId: 'msg-assistant', role: 'assistant', summary: 'Summarizing now.' },
+    ])
+  })
+
+  it('rejects visible roleless messages instead of emitting roleless display turns', () => {
+    const message = {
+      info: { id: 'msg-roleless' },
+      parts: [{ id: 'part-roleless', type: 'text', text: 'Hidden until OpenCode provides a display role.' }],
+    }
+
+    expect(normalizeOpencodeTurn(message, 0)).toBeNull()
+
+    const snapshot = normalizeOpencodeSnapshot({
+      sessionType: 'freshopencode',
+      threadId: 'ses-roleless',
+      exported: {
+        messages: [
+          {
+            info: { id: 'msg-user', role: 'user' },
+            parts: [{ id: 'part-user', type: 'text', text: 'User input' }],
+          },
+          message,
+        ],
+      },
+    })
+
+    expect(snapshot.turns).toHaveLength(1)
+    expect(snapshot.turns[0]).toMatchObject({ turnId: 'msg-user', role: 'user' })
+    expect(snapshot.turns.some((turn) => turn.turnId === 'msg-roleless')).toBe(false)
+  })
+
   it('carries turn-page nextCursor explicitly and keeps export fallback compatibility', () => {
     const explicit = normalizeOpencodeTurnPage({
       threadId: 'ses-page',

From 4d7bf5f99036bf8e46d81325af5142037f0430ea Mon Sep 17 00:00:00 2001
From: Codex <codex@openai.com>
Date: Fri, 19 Jun 2026 03:11:40 -0700
Subject: [PATCH 27/33] fix: consume normalized fresh agent display turns

---
 server/agent-api/router.ts                    |  18 ++-
 server/fresh-agent-extras-router.ts           | 120 +++++++++++++--
 server/ws-handler.ts                          |  18 ++-
 shared/ws-protocol.ts                         |   1 +
 .../fresh-agent/FreshAgentTranscript.tsx      |  42 +-----
 src/components/fresh-agent/FreshAgentView.tsx | 135 ++++++++++++++---
 src/lib/fresh-agent-checkpoints.ts            |  21 ++-
 test/server/agent-api-fresh-agent.test.ts     |  10 +-
 test/server/fresh-agent-extras.test.ts        |  23 ++-
 .../fresh-agent/FreshAgentTranscript.test.tsx |  42 +++++-
 .../FreshAgentTurnActions.test.tsx            |  52 +++++++
 .../fresh-agent/FreshAgentView.test.tsx       | 139 +++++++++++++++++-
 .../lib/fresh-agent-checkpoints.test.ts       |  45 +++++-
 .../server/ws-handler-fresh-agent.test.ts     |   9 +-
 14 files changed, 579 insertions(+), 96 deletions(-)
 create mode 100644 test/unit/client/components/fresh-agent/FreshAgentTurnActions.test.tsx

diff --git a/server/agent-api/router.ts b/server/agent-api/router.ts
index fa919e235..284410cb2 100644
--- a/server/agent-api/router.ts
+++ b/server/agent-api/router.ts
@@ -459,7 +459,7 @@ type CodexPromptBlocker = {
 
 type FreshAgentRuntimeManagerLike = {
   create: (input: any) => Promise<{ sessionId: string; sessionType: FreshAgentSessionType; runtimeProvider: FreshAgentRuntimeProvider; sessionRef?: { provider: string; sessionId: string } }>
-  send: (locator: FreshAgentSessionLocator, input: { text: string; settings?: any }) => Promise<{ sessionId?: string; sessionRef?: { provider: string; sessionId: string } } | void>
+  send: (locator: FreshAgentSessionLocator, input: { text: string; settings?: any }) => Promise<{ sessionId?: string; submittedTurnId?: string; sessionRef?: { provider: string; sessionId: string } } | void>
   attach: (locator: FreshAgentSessionLocator) => Promise<{ sessionId: string; sessionRef?: { provider: string; sessionId: string } }>
   getSnapshot: (input: FreshAgentThreadLocator) => Promise<any>
 }
@@ -1705,7 +1705,13 @@ export function createAgentApiRouter({
         const deadline = Date.now() + (Number.isFinite(timeoutSec) ? timeoutSec * 1000 : FRESH_AGENT_SEND_IDLE_TIMEOUT_MS)
         const idle = await waitForFreshAgentIdle(freshAgentRuntimeManager, snapshotLocator, deadline)
         if (idle.deadlineMissed) {
-          return res.json(approx({ paneId, sessionId: result?.sessionId ?? locator.sessionId, sessionRef: result?.sessionRef, status: idle.status }, 'prompt sent; turn did not complete within deadline'))
+          return res.json(approx({
+            paneId,
+            sessionId: result?.sessionId ?? locator.sessionId,
+            submittedTurnId: result?.submittedTurnId,
+            sessionRef: result?.sessionRef,
+            status: idle.status,
+          }, 'prompt sent; turn did not complete within deadline'))
         }
 
         const finalSessionId = result?.sessionId ?? locator.sessionId
@@ -1728,7 +1734,13 @@ export function createAgentApiRouter({
           })
         }
 
-        return res.json(ok({ paneId, sessionId: finalSessionId, sessionRef: finalSessionRef, status: idle.status }, 'prompt sent'))
+        return res.json(ok({
+          paneId,
+          sessionId: finalSessionId,
+          submittedTurnId: result?.submittedTurnId,
+          sessionRef: finalSessionRef,
+          status: idle.status,
+        }, 'prompt sent'))
       } catch (err: any) {
         return res.status(agentRouteErrorStatus(err)).json(fail(err?.message || 'fresh-agent send failed'))
       }
diff --git a/server/fresh-agent-extras-router.ts b/server/fresh-agent-extras-router.ts
index de92c884d..a0eec3403 100644
--- a/server/fresh-agent-extras-router.ts
+++ b/server/fresh-agent-extras-router.ts
@@ -5,7 +5,7 @@ import * as fsp from 'node:fs/promises'
 import * as os from 'node:os'
 import * as path from 'node:path'
 import { FreshAgentRuntimeProviderSchema, FreshAgentSessionTypeSchema } from '../shared/fresh-agent-contract.js'
-import type { FreshAgentCreateRequest, FreshAgentSessionLocator } from './fresh-agent/runtime-adapter.js'
+import type { FreshAgentCreateRequest, FreshAgentSendResult, FreshAgentSessionLocator } from './fresh-agent/runtime-adapter.js'
 
 const ATTACHMENT_MAX_BYTES = 10 * 1024 * 1024
 const EXEC_TIMEOUT_MS = 30_000
@@ -104,15 +104,83 @@ async function ensureCheckpointRepo(cwd: string): Promise<string> {
   return gitDir
 }
 
-export type CheckpointEntry = { id: string; ts: number; label: string }
+export type CheckpointEntry = { id: string; ts: number; label: string; requestId?: string; turnId?: string }
+type CheckpointMetadata = Record<string, { requestId?: string; turnId?: string }>
 
-async function createCheckpoint(cwd: string, label: string): Promise<CheckpointEntry> {
+function checkpointMetadataPath(gitDir: string): string {
+  return path.join(gitDir, 'freshell-checkpoint-metadata.json')
+}
+
+function isValidCheckpointId(id: string): boolean {
+  return /^[0-9a-f]{7,40}$/i.test(id)
+}
+
+async function readCheckpointMetadata(gitDir: string): Promise<CheckpointMetadata> {
+  try {
+    const raw = await fsp.readFile(checkpointMetadataPath(gitDir), 'utf8')
+    const parsed = JSON.parse(raw) as unknown
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {}
+    const metadata: CheckpointMetadata = {}
+    for (const [id, value] of Object.entries(parsed)) {
+      if (!isValidCheckpointId(id) || !value || typeof value !== 'object' || Array.isArray(value)) continue
+      const entry = value as Record<string, unknown>
+      metadata[id] = {
+        ...(typeof entry.requestId === 'string' && entry.requestId ? { requestId: entry.requestId } : {}),
+        ...(typeof entry.turnId === 'string' && entry.turnId ? { turnId: entry.turnId } : {}),
+      }
+    }
+    return metadata
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return {}
+    throw error
+  }
+}
+
+async function writeCheckpointMetadata(gitDir: string, metadata: CheckpointMetadata): Promise<void> {
+  const filePath = checkpointMetadataPath(gitDir)
+  const tempPath = `${filePath}.tmp-${randomUUID()}`
+  await fsp.writeFile(tempPath, `${JSON.stringify(metadata, null, 2)}\n`, 'utf8')
+  try {
+    await fsp.rename(tempPath, filePath)
+  } catch (error) {
+    await fsp.unlink(tempPath).catch(() => undefined)
+    throw error
+  }
+}
+
+async function updateCheckpointMetadata(
+  cwd: string,
+  id: string,
+  patch: { requestId?: string; turnId?: string },
+): Promise<CheckpointEntry> {
+  if (!isValidCheckpointId(id)) {
+    throw new Error('invalid checkpoint id')
+  }
+  const gitDir = await ensureCheckpointRepo(cwd)
+  const resolvedId = (await runGit([`--git-dir=${gitDir}`, 'rev-parse', '--verify', `${id}^{commit}`])).trim()
+  const metadata = await readCheckpointMetadata(gitDir)
+  metadata[resolvedId] = {
+    ...(metadata[resolvedId] ?? {}),
+    ...(patch.requestId ? { requestId: patch.requestId } : {}),
+    ...(patch.turnId ? { turnId: patch.turnId } : {}),
+  }
+  await writeCheckpointMetadata(gitDir, metadata)
+  const entries = await listCheckpoints(cwd)
+  const entry = entries.find((candidate) => candidate.id === resolvedId)
+  if (!entry) throw new Error('invalid checkpoint id')
+  return entry
+}
+
+async function createCheckpoint(cwd: string, label: string, metadata: { requestId?: string } = {}): Promise<CheckpointEntry> {
   const gitDir = await ensureCheckpointRepo(cwd)
   const base = [`--git-dir=${gitDir}`, `--work-tree=${cwd}`]
   await runGit([...base, 'add', '-A'], { cwd })
   await runGit([...base, ...CHECKPOINT_IDENTITY, 'commit', '--allow-empty', '-q', '-m', label], { cwd })
   const sha = (await runGit([`--git-dir=${gitDir}`, 'rev-parse', 'HEAD'])).trim()
-  return { id: sha, ts: Math.floor(Date.now() / 1000), label }
+  if (metadata.requestId) {
+    await updateCheckpointMetadata(cwd, sha, { requestId: metadata.requestId })
+  }
+  return { id: sha, ts: Math.floor(Date.now() / 1000), label, ...metadata }
 }
 
 async function listCheckpoints(cwd: string): Promise<CheckpointEntry[]> {
@@ -134,17 +202,18 @@ async function listCheckpoints(cwd: string): Promise<CheckpointEntry[]> {
     // Empty repo (no commits yet).
     return []
   }
+  const metadata = await readCheckpointMetadata(gitDir)
   return raw
     .split('\n')
     .filter(Boolean)
     .map((line) => {
       const [id, ts, ...rest] = line.split('\t')
-      return { id, ts: Number(ts), label: rest.join('\t') }
+      return { id, ts: Number(ts), label: rest.join('\t'), ...(metadata[id] ?? {}) }
     })
 }
 
 async function restoreCheckpoint(cwd: string, id: string): Promise<void> {
-  if (!/^[0-9a-f]{7,40}$/i.test(id)) {
+  if (!isValidCheckpointId(id)) {
     throw new Error('invalid checkpoint id')
   }
   const gitDir = await ensureCheckpointRepo(cwd)
@@ -171,7 +240,7 @@ async function restoreCheckpoint(cwd: string, id: string): Promise<void> {
 /** Structural slice of FreshAgentRuntimeManager — keeps this router
  * standalone-testable with a fake and avoids a hard import cycle. */
 export type FreshAgentSendCapable = {
-  send?: (locator: FreshAgentSessionLocator, payload: { text: string; settings?: FreshAgentCreateRequest }) => Promise<unknown>
+  send?: (locator: FreshAgentSessionLocator, payload: { text: string; settings?: FreshAgentCreateRequest }) => Promise<FreshAgentSendResult>
 }
 
 function parseSendLocator(body: unknown): FreshAgentSessionLocator | null {
@@ -267,8 +336,8 @@ export function createFreshAgentExtrasRouter(
       ? req.body.settings as FreshAgentCreateRequest
       : undefined
     try {
-      await manager.send(locator, { text, ...(settings ? { settings } : {}) })
-      res.json({ sent: true })
+      const result = await manager.send(locator, { text, ...(settings ? { settings } : {}) })
+      res.json({ sent: true, submittedTurnId: result?.submittedTurnId })
     } catch (error) {
       res.status(500).json({ error: error instanceof Error ? error.message : 'send failed' })
     }
@@ -279,6 +348,9 @@ export function createFreshAgentExtrasRouter(
     const label = typeof req.body?.label === 'string' && req.body.label.trim()
       ? req.body.label.trim().slice(0, 120)
       : 'checkpoint'
+    const requestId = typeof req.body?.requestId === 'string' && req.body.requestId.trim()
+      ? req.body.requestId.trim()
+      : undefined
     if (!cwd) {
       return res.status(400).json({ error: 'cwd is required' })
     }
@@ -288,7 +360,7 @@ export function createFreshAgentExtrasRouter(
       return res.status(400).json({ error: `cwd does not exist: ${cwd}` })
     }
     try {
-      const entry = await createCheckpoint(cwd, label)
+      const entry = await createCheckpoint(cwd, label, { ...(requestId ? { requestId } : {}) })
       res.json(entry)
     } catch (error) {
       res.status(500).json({ error: error instanceof Error ? error.message : 'checkpoint failed' })
@@ -307,6 +379,34 @@ export function createFreshAgentExtrasRouter(
     }
   })
 
+  router.post('/checkpoints/metadata', async (req, res) => {
+    const cwd = typeof req.body?.cwd === 'string' ? req.body.cwd : ''
+    const id = typeof req.body?.id === 'string' ? req.body.id : ''
+    const requestId = typeof req.body?.requestId === 'string' && req.body.requestId.trim()
+      ? req.body.requestId.trim()
+      : undefined
+    const turnId = typeof req.body?.turnId === 'string' && req.body.turnId.trim()
+      ? req.body.turnId.trim()
+      : undefined
+    if (!cwd || !id) {
+      return res.status(400).json({ error: 'cwd and id are required' })
+    }
+    if (!requestId && !turnId) {
+      return res.status(400).json({ error: 'requestId or turnId is required' })
+    }
+    try {
+      await fsp.access(cwd)
+    } catch {
+      return res.status(400).json({ error: `cwd does not exist: ${cwd}` })
+    }
+    try {
+      res.json(await updateCheckpointMetadata(cwd, id, { requestId, turnId }))
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'metadata update failed'
+      res.status(message.includes('invalid checkpoint id') ? 400 : 500).json({ error: message })
+    }
+  })
+
   router.post('/checkpoints/restore', async (req, res) => {
     const cwd = typeof req.body?.cwd === 'string' ? req.body.cwd : ''
     const id = typeof req.body?.id === 'string' ? req.body.id : ''
diff --git a/server/ws-handler.ts b/server/ws-handler.ts
index e450d6206..3dba92697 100644
--- a/server/ws-handler.ts
+++ b/server/ws-handler.ts
@@ -134,6 +134,8 @@ type FreshAgentRuntimeManagerLike = {
 }
 
 type FreshAgentSendResult = void | {
+  requestId?: string
+  submittedTurnId?: string
   sessionId?: string
   sessionRef?: { provider: string; sessionId: string }
 }
@@ -3187,7 +3189,12 @@ export class WsHandler {
         const locator = { sessionId: m.sessionId, sessionType: m.sessionType, provider: m.provider }
         if (!this.requireFreshAgentAuthorization(ws, state, locator)) return
         try {
-          const result = await manager.send(locator, { text: m.text, images: m.images, settings: m.settings })
+          const result = await manager.send(locator, {
+            requestId: m.requestId,
+            text: m.text,
+            images: m.images,
+            settings: m.settings,
+          })
           if (result?.sessionId && result.sessionId !== m.sessionId) {
             this.authorizeFreshAgentSession(state, {
               sessionId: result.sessionId,
@@ -3208,8 +3215,15 @@ export class WsHandler {
               sessionRef: result.sessionRef ?? { provider: m.provider, sessionId: result.sessionId },
             })
           }
+          if (m.requestId) {
+            this.send(ws, {
+              type: 'freshAgent.send.accepted',
+              requestId: m.requestId,
+              submittedTurnId: result?.submittedTurnId,
+            })
+          }
         } catch (error) {
-          this.sendError(ws, { code: 'INTERNAL_ERROR', message: errorMessage(error) })
+          this.sendError(ws, { code: 'INTERNAL_ERROR', message: errorMessage(error), requestId: m.requestId })
         }
         return
       }
diff --git a/shared/ws-protocol.ts b/shared/ws-protocol.ts
index 68ff731a0..a94270eb1 100644
--- a/shared/ws-protocol.ts
+++ b/shared/ws-protocol.ts
@@ -864,6 +864,7 @@ export type SdkRestoreFailureCode =
 export type FreshAgentServerMessage =
   | { type: 'freshAgent.created'; requestId: string; sessionId: string; sessionType: string; provider: string; runtimeProvider: string; sessionRef?: { provider: string; sessionId: string } }
   | { type: 'freshAgent.create.failed'; requestId: string; code: string; message: string; retryable?: boolean }
+  | { type: 'freshAgent.send.accepted'; requestId: string; submittedTurnId?: string }
   | { type: 'freshAgent.event'; sessionId: string; sessionType: string; provider: string; event: unknown }
   | { type: 'freshAgent.session.materialized'; previousSessionId: string; sessionId: string; sessionType: string; provider: string; sessionRef?: { provider: string; sessionId: string } }
   | { type: 'freshAgent.forked'; requestId?: string; parentSessionId: string; sessionId: string; sessionType: string; provider: string; runtimeProvider: string; sessionRef?: { provider: string; sessionId: string } }
diff --git a/src/components/fresh-agent/FreshAgentTranscript.tsx b/src/components/fresh-agent/FreshAgentTranscript.tsx
index 77b92c3c7..965c256b5 100644
--- a/src/components/fresh-agent/FreshAgentTranscript.tsx
+++ b/src/components/fresh-agent/FreshAgentTranscript.tsx
@@ -21,6 +21,7 @@ import {
 } from './FreshAgentTurnActions'
 import { FreshAgentActionSheet } from './FreshAgentActionSheet'
 import { buildLongPressHandlers, useCoarsePointer } from '@/lib/pointer'
+import { getFreshAgentDisplayTurnKey } from '@shared/fresh-agent-turns'
 
 function getTurnLabel(turn: FreshAgentTurn, agentLabel?: string): string {
   switch (turn.role) {
@@ -223,41 +224,6 @@ function buildBlocks(
   return blocks
 }
 
-function isActivityOnlyTurn(turn: FreshAgentTurn): boolean {
-  return turn.items.length > 0 && turn.items.every(isActivityLike)
-}
-
-function mergeActivityOnlyTurns(previous: FreshAgentTurn, next: FreshAgentTurn): FreshAgentTurn {
-  return {
-    ...next,
-    id: `${previous.id}:${next.id}`,
-    turnId: next.turnId ?? next.id,
-    summary: [previous.summary, next.summary].filter(Boolean).join('\n\n'),
-    items: [...previous.items, ...next.items],
-    model: next.model ?? previous.model,
-    timestamp: next.timestamp ?? previous.timestamp,
-  }
-}
-
-function coalesceActivityOnlyTurns(turns: FreshAgentTurn[]): FreshAgentTurn[] {
-  const coalesced: FreshAgentTurn[] = []
-  for (const turn of turns) {
-    const previous = coalesced[coalesced.length - 1]
-    if (
-      previous
-      && turn.role !== 'user'
-      && previous.role === turn.role
-      && isActivityOnlyTurn(previous)
-      && isActivityOnlyTurn(turn)
-    ) {
-      coalesced[coalesced.length - 1] = mergeActivityOnlyTurns(previous, turn)
-      continue
-    }
-    coalesced.push(turn)
-  }
-  return coalesced
-}
-
 function filterTurnsForDisplay(
   turns: FreshAgentTurn[],
   options: TranscriptDisplayOptions,
@@ -575,7 +541,7 @@ export function FreshAgentTranscript({
     showThinking,
   }), [showThinking])
   const displayTurns = useMemo(() => (
-    coalesceActivityOnlyTurns(filterTurnsForDisplay(turns, displayOptions))
+    filterTurnsForDisplay(turns, displayOptions)
   ), [displayOptions, turns])
   const liveActivityBlockId = useMemo(
     () => selectLiveActivityBlockId(displayTurns, isStreaming, displayOptions),
@@ -598,7 +564,7 @@ export function FreshAgentTranscript({
         }
         return `${item.id}:${item.kind}`
       }).join(',')
-      return `${turn.id}:${turn.summary?.length ?? 0}:${itemSignature}`
+      return `${getFreshAgentDisplayTurnKey(turn)}:${turn.summary?.length ?? 0}:${itemSignature}`
     }).join('|')
   ), [displayTurns])
 
@@ -642,7 +608,7 @@ export function FreshAgentTranscript({
       >
         {displayTurns.map((turn, index) => (
           <FreshAgentTurnArticle
-            key={`${turn.id}:${index}`}
+            key={`${getFreshAgentDisplayTurnKey(turn)}:${index}`}
             turn={turn}
             actions={actions}
             agentLabel={agentLabel}
diff --git a/src/components/fresh-agent/FreshAgentView.tsx b/src/components/fresh-agent/FreshAgentView.tsx
index b22f42266..ba9067080 100644
--- a/src/components/fresh-agent/FreshAgentView.tsx
+++ b/src/components/fresh-agent/FreshAgentView.tsx
@@ -29,6 +29,11 @@ import { getCanonicalDurableSessionId, getPreferredResumeSessionId } from '@/sto
 import { isValidClaudeSessionId } from '@/lib/claude-session-id'
 import { makeFreshAgentSessionKey } from '@shared/fresh-agent'
 import type { FreshAgentSnapshot } from '@shared/fresh-agent-contract'
+import {
+  freshAgentSnapshotHasUserTurn,
+  freshAgentTurnText,
+  getFreshAgentDisplayTurnKey,
+} from '@shared/fresh-agent-turns'
 import { getFreshAgentSlashCommands, type FreshAgentSlashCommand } from '@shared/fresh-agent-slash-commands'
 import { buildRestoreError, type RestoreErrorReason } from '@shared/session-contract'
 import { isDurableProviderSessionId } from '@shared/session-flavor'
@@ -58,7 +63,42 @@ function getSnapshotIdentity(snapshot: FreshAgentSnapshot): string | null {
 }
 
 function getTurnKey(turn: FreshAgentTurn): string {
-  return (turn as { turnId?: string }).turnId ?? turn.id
+  return getFreshAgentDisplayTurnKey(turn)
+}
+
+type LocalEcho = {
+  text: string
+  requestId: string
+  submittedTurnId?: string
+}
+
+type PendingSendMetadata = {
+  cwd?: string
+  checkpointId?: string
+  submittedTurnId?: string
+  legacyAccepted?: boolean
+  metadataUpdateStarted?: boolean
+}
+
+function localEchoLanded(
+  turns: readonly FreshAgentTurn[],
+  echo: LocalEcho,
+  pending?: PendingSendMetadata,
+): boolean {
+  const needle = echo.text.slice(0, 80)
+  const submittedTurnId = echo.submittedTurnId ?? pending?.submittedTurnId
+  if (submittedTurnId) {
+    return turns.some((turn) => (
+      turn.role === 'user'
+      && getFreshAgentDisplayTurnKey(turn) === submittedTurnId
+      && freshAgentTurnText(turn).includes(needle)
+    ))
+  }
+  if (pending && !pending.legacyAccepted) return false
+  return turns.some((turn) => (
+    turn.role === 'user'
+    && freshAgentTurnText(turn).includes(needle)
+  ))
 }
 
 function isSnapshotInFlight(snapshot: FreshAgentSnapshot): boolean {
@@ -379,9 +419,10 @@ export function FreshAgentView({
   // Optimistic echo of the just-sent user message: the transcript renders
   // snapshot turns only, which left a 2-10s blank gap after send
   // (live-test finding). Cleared when a snapshot containing the turn lands.
-  const [localEcho, setLocalEcho] = useState<string | null>(null)
-  const localEchoRef = useRef<string | null>(null)
+  const [localEcho, setLocalEcho] = useState<LocalEcho | null>(null)
+  const localEchoRef = useRef<LocalEcho | null>(null)
   localEchoRef.current = localEcho
+  const pendingSendMetadataRef = useRef<Map<string, PendingSendMetadata>>(new Map())
   const descriptor = resolveFreshAgentType(paneContent.sessionType)
   // Capability-gated commands (e.g. /fork) only appear once the snapshot
   // confirms the provider supports the action.
@@ -431,7 +472,7 @@ export function FreshAgentView({
       && claudeSession?.historyLoaded !== true
       && !hasRestoreFailure,
   )
-  const hasUserTurns = useMemo(() => snapshot?.turns.some((turn) => turn.role === 'user') ?? false, [snapshot?.turns])
+  const hasUserTurns = useMemo(() => freshAgentSnapshotHasUserTurn(snapshot), [snapshot])
   const autoTitleDurableIdentity = useMemo(() => {
     const paneSessionRefId = paneContent.sessionRef?.provider === paneContent.provider
       ? paneContent.sessionRef.sessionId
@@ -488,6 +529,34 @@ export function FreshAgentView({
     ws.send(message as never)
   }, [paneId, ws])
 
+  const recordPendingSendMetadata = useCallback((requestId: string, patch: PendingSendMetadata) => {
+    const current = pendingSendMetadataRef.current.get(requestId) ?? {}
+    const next: PendingSendMetadata = { ...current, ...patch }
+    pendingSendMetadataRef.current.set(requestId, next)
+    if (
+      next.metadataUpdateStarted
+      || !next.cwd
+      || !next.checkpointId
+      || !next.submittedTurnId
+    ) {
+      return
+    }
+    pendingSendMetadataRef.current.set(requestId, { ...next, metadataUpdateStarted: true })
+    void Promise
+      .resolve(api.post('/api/fresh-agent/checkpoints/metadata', {
+        cwd: next.cwd,
+        id: next.checkpointId,
+        requestId,
+        turnId: next.submittedTurnId,
+      }))
+      .catch(() => {
+        const latest = pendingSendMetadataRef.current.get(requestId)
+        if (latest) {
+          pendingSendMetadataRef.current.set(requestId, { ...latest, metadataUpdateStarted: false })
+        }
+      })
+  }, [])
+
   const migratePendingAutoTitle = useCallback((
     previousSessionId: string | undefined,
     nextSessionId: string | undefined,
@@ -858,6 +927,24 @@ export function FreshAgentView({
           },
         }))
       }
+      if (
+        message.type === 'freshAgent.send.accepted'
+        && typeof message.requestId === 'string'
+      ) {
+        const submittedTurnId = typeof message.submittedTurnId === 'string'
+          ? message.submittedTurnId
+          : undefined
+        if (submittedTurnId) {
+          recordPendingSendMetadata(message.requestId, { submittedTurnId })
+          const echo = localEchoRef.current
+          if (echo?.requestId === message.requestId) {
+            setLocalEcho({ ...echo, submittedTurnId })
+          }
+        } else {
+          recordPendingSendMetadata(message.requestId, { legacyAccepted: true })
+        }
+        setSnapshotRefreshNonce((value) => value + 1)
+      }
       if (
         message.type === 'freshAgent.event'
         && message.sessionId === paneContent.sessionId
@@ -903,7 +990,7 @@ export function FreshAgentView({
       }
     })
     return unsubscribe
-  }, [commitSnapshot, dispatch, migratePendingAutoTitle, paneContent, paneContent.createRequestId, paneId, sendFreshAgentMessage, tabId, ws])
+  }, [commitSnapshot, dispatch, migratePendingAutoTitle, paneContent, paneContent.createRequestId, paneId, recordPendingSendMetadata, sendFreshAgentMessage, tabId, ws])
 
   useEffect(() => {
     if (!snapshotThreadId) return
@@ -929,7 +1016,7 @@ export function FreshAgentView({
         if (isStaleSnapshotRequest()) return
         const snapshotIdentity = currentAutoTitleIdentityRef.current
         const resolved = next as FreshAgentSnapshot
-        const resolvedHasUserTurns = resolved.turns.some((turn) => turn.role === 'user')
+        const resolvedHasUserTurns = freshAgentSnapshotHasUserTurn(resolved)
         if (!resolvedHasUserTurns && !autoTitleSentRef.current) {
           autoTitleFreshBoundaryRef.current = true
         }
@@ -942,13 +1029,8 @@ export function FreshAgentView({
         setSnapshotAutoTitleIdentity(snapshotIdentity)
         const echo = localEchoRef.current
         if (echo) {
-          const needle = echo.slice(0, 80)
-          const echoLanded = displaySnapshot.turns.some((turn) => (
-            turn.role === 'user' && turn.items.some((item) => (
-              item.kind === 'text' && item.text.includes(needle)
-            ))
-          ))
-          if (echoLanded) setLocalEcho(null)
+          const pending = pendingSendMetadataRef.current.get(echo.requestId)
+          if (localEchoLanded(displaySnapshot.turns, echo, pending)) setLocalEcho(null)
         }
         const fresh = paneContentRef.current
         const nextStatus = (resolved.status as FreshAgentPaneContent['status']) ?? fresh.status
@@ -1171,15 +1253,27 @@ export function FreshAgentView({
   const sendUserText = useCallback((text: string) => {
     const current = paneContentRef.current
     if (!current.sessionId) return
+    const requestId = nanoid()
+    recordPendingSendMetadata(requestId, {})
     // Checkpoint the working tree before the agent acts on this message, so
     // "rewind code to here" on this turn restores the pre-turn state. Fire and
     // forget: a failed snapshot must never block the send.
     if (current.initialCwd) {
+      recordPendingSendMetadata(requestId, { cwd: current.initialCwd })
       void Promise
-        .resolve(api.post('/api/fresh-agent/checkpoints', {
+        .resolve(api.post<CheckpointEntry>('/api/fresh-agent/checkpoints', {
           cwd: current.initialCwd,
           label: checkpointLabelForText(text),
+          requestId,
         }))
+        .then((entry) => {
+          if (entry?.id) {
+            recordPendingSendMetadata(requestId, {
+              cwd: current.initialCwd,
+              checkpointId: entry.id,
+            })
+          }
+        })
         .catch(() => { /* surfaced lazily when a rewind finds no checkpoint */ })
     }
     const isFirstMessage = !autoTitleSentRef.current
@@ -1198,6 +1292,7 @@ export function FreshAgentView({
     }
     sendFreshAgentMessage({
       type: 'freshAgent.send',
+      requestId,
       sessionId: current.sessionId,
       sessionType: current.sessionType,
       provider: current.provider,
@@ -1210,8 +1305,8 @@ export function FreshAgentView({
         ...(getEffectiveFreshAgentEffort(current) ? { effort: getEffectiveFreshAgentEffort(current) } : {}),
       },
     })
-    setLocalEcho(text)
-  }, [dispatch, paneId, sendFreshAgentMessage, snapshotConfirmsNoUserTurns, tabId])
+    setLocalEcho({ text, requestId })
+  }, [dispatch, paneId, recordPendingSendMetadata, sendFreshAgentMessage, snapshotConfirmsNoUserTurns, tabId])
 
   // Flush queued messages when the turn ends. One flush per status change is
   // enough: all queued entries are delivered in order for the next turn.
@@ -1512,11 +1607,11 @@ export function FreshAgentView({
             <FreshAgentTranscript
               turns={localEcho
                 ? [...turns, {
-                    id: '__local-echo',
-                    turnId: '__local-echo',
+                    id: `__local-echo:${localEcho.requestId}`,
+                    turnId: localEcho.submittedTurnId ?? `__local-echo:${localEcho.requestId}`,
                     role: 'user',
-                    summary: localEcho,
-                    items: [{ id: '__local-echo-item', kind: 'text', text: localEcho }],
+                    summary: localEcho.text,
+                    items: [{ id: `__local-echo-item:${localEcho.requestId}`, kind: 'text', text: localEcho.text }],
                   } as FreshAgentTurn]
                 : turns}
               canFork={canFork}
diff --git a/src/lib/fresh-agent-checkpoints.ts b/src/lib/fresh-agent-checkpoints.ts
index 434b8fa11..542a8f05e 100644
--- a/src/lib/fresh-agent-checkpoints.ts
+++ b/src/lib/fresh-agent-checkpoints.ts
@@ -1,6 +1,7 @@
 import type { FreshAgentTurn } from '@shared/fresh-agent-contract'
+import { freshAgentTurnText, getFreshAgentDisplayTurnKey } from '@shared/fresh-agent-turns'
 
-export type CheckpointEntry = { id: string; ts: number; label: string }
+export type CheckpointEntry = { id: string; ts: number; label: string; requestId?: string; turnId?: string }
 
 export const CHECKPOINT_LABEL_LIMIT = 120
 
@@ -10,11 +11,7 @@ export function checkpointLabelForText(text: string): string {
 }
 
 function turnLabel(turn: FreshAgentTurn): string {
-  const text = turn.items
-    .filter((item): item is Extract<FreshAgentTurn['items'][number], { kind: 'text' }> => item.kind === 'text')
-    .map((item) => item.text)
-    .join('\n\n')
-  return checkpointLabelForText(text || turn.summary || '')
+  return checkpointLabelForText(freshAgentTurnText(turn) || '')
 }
 
 /**
@@ -29,6 +26,16 @@ export function pickCheckpointForTurn(
   target: FreshAgentTurn,
 ): CheckpointEntry | null {
   if (target.role !== 'user') return null
+  const targetTurnId = getFreshAgentDisplayTurnKey(target)
+  const directTurnIdMatch = checkpoints.find((entry) => entry.turnId === targetTurnId)
+  if (directTurnIdMatch) return directTurnIdMatch
+
+  const targetRequestId = (target as FreshAgentTurn & { requestId?: unknown }).requestId
+  if (typeof targetRequestId === 'string' && targetRequestId) {
+    const requestIdMatch = checkpoints.find((entry) => entry.requestId === targetRequestId)
+    if (requestIdMatch) return requestIdMatch
+  }
+
   const label = turnLabel(target)
   if (!label) return null
 
@@ -43,7 +50,7 @@ export function pickCheckpointForTurn(
 
   // git log order is newest-first; we need oldest-first to index by ordinal.
   const matches = checkpoints
-    .filter((entry) => entry.label === label)
+    .filter((entry) => entry.label === label && entry.turnId === undefined)
     .slice()
     .reverse()
   return matches[ordinal] ?? null
diff --git a/test/server/agent-api-fresh-agent.test.ts b/test/server/agent-api-fresh-agent.test.ts
index 32d11df81..d42e1c6b5 100644
--- a/test/server/agent-api-fresh-agent.test.ts
+++ b/test/server/agent-api-fresh-agent.test.ts
@@ -112,12 +112,18 @@ describe('agent-api fresh-agent: create', () => {
 
 describe('agent-api fresh-agent: send-keys', () => {
   it('routes send-keys to the runtime manager for a fresh-agent pane and blocks until the turn returns', async () => {
-    const { app, freshAgentRuntimeManager } = makeApp()
+    const freshAgentRuntimeManager = {
+      create: vi.fn(async () => ({ sessionId: 'freshopencode-abc', sessionType: 'freshopencode', runtimeProvider: 'opencode', sessionRef: { provider: 'opencode', sessionId: 'freshopencode-abc' } })),
+      send: vi.fn(async () => ({ submittedTurnId: 'display-user-1' })),
+      attach: vi.fn(async () => ({ sessionId: 'ses_real_1' })),
+      getSnapshot: vi.fn(async () => ({ status: 'idle', turns: [] })),
+    }
+    const { app } = makeApp({ freshAgentRuntimeManager })
     const created = await request(app).post('/api/tabs').send({ agent: 'opencode' })
     const paneId = created.body.data.paneId
     const res = await request(app).post(`/api/panes/${paneId}/send-keys`).send({ data: 'Reply with: ok' })
     expect(res.status).toBe(200)
-    expect(res.body.data).toMatchObject({ sessionId: 'freshopencode-abc' })
+    expect(res.body.data).toMatchObject({ sessionId: 'freshopencode-abc', submittedTurnId: 'display-user-1' })
     expect(freshAgentRuntimeManager.send).toHaveBeenCalledWith(
       { sessionId: 'freshopencode-abc', sessionType: 'freshopencode', provider: 'opencode' },
       { text: 'Reply with: ok' },
diff --git a/test/server/fresh-agent-extras.test.ts b/test/server/fresh-agent-extras.test.ts
index 6c692b39a..5e284bc34 100644
--- a/test/server/fresh-agent-extras.test.ts
+++ b/test/server/fresh-agent-extras.test.ts
@@ -150,15 +150,16 @@ describe('fresh-agent extras router', () => {
 
   describe('POST /send', () => {
     it('forwards to the injected runtime manager', async () => {
-      const send = vi.fn().mockResolvedValue(undefined)
+      const send = vi.fn().mockResolvedValue({ submittedTurnId: 'display-user-1' })
       const app = express()
       app.use('/api/fresh-agent', createFreshAgentExtrasRouter({ freshAgentRuntimeManager: { send } }))
 
-      await request(app)
+      const res = await request(app)
         .post('/api/fresh-agent/send')
         .send({ sessionId: 's1', sessionType: 'freshclaude', provider: 'claude', text: 'ls the cwd' })
         .expect(200)
 
+      expect(res.body).toMatchObject({ sent: true, submittedTurnId: 'display-user-1' })
       expect(send).toHaveBeenCalledWith(
         { sessionId: 's1', sessionType: 'freshclaude', provider: 'claude' },
         { text: 'ls the cwd' },
@@ -214,10 +215,22 @@ describe('fresh-agent extras router', () => {
       await fsp.writeFile(file, 'version one\n')
       const first = await request(app)
         .post('/api/fresh-agent/checkpoints')
-        .send({ cwd: dir, label: 'before refactor' })
+        .send({ cwd: dir, label: 'before refactor', requestId: 'send-request-1' })
         .expect(200)
       expect(first.body.id).toMatch(/^[0-9a-f]{40}$/)
       expect(first.body.label).toBe('before refactor')
+      expect(first.body.requestId).toBe('send-request-1')
+
+      const withTurnId = await request(app)
+        .post('/api/fresh-agent/checkpoints/metadata')
+        .send({ cwd: dir, id: first.body.id, turnId: 'display-user-1' })
+        .expect(200)
+      expect(withTurnId.body).toMatchObject({
+        id: first.body.id,
+        label: 'before refactor',
+        requestId: 'send-request-1',
+        turnId: 'display-user-1',
+      })
 
       await fsp.writeFile(file, 'version two\n')
       await request(app)
@@ -233,6 +246,10 @@ describe('fresh-agent extras router', () => {
       // Newest first, git log order.
       expect(list.body.checkpoints[0].label).toBe('after refactor')
       expect(list.body.checkpoints[1].label).toBe('before refactor')
+      expect(list.body.checkpoints[1]).toMatchObject({
+        requestId: 'send-request-1',
+        turnId: 'display-user-1',
+      })
 
       await request(app)
         .post('/api/fresh-agent/checkpoints/restore')
diff --git a/test/unit/client/components/fresh-agent/FreshAgentTranscript.test.tsx b/test/unit/client/components/fresh-agent/FreshAgentTranscript.test.tsx
index 473fbf2a0..20c0eefa9 100644
--- a/test/unit/client/components/fresh-agent/FreshAgentTranscript.test.tsx
+++ b/test/unit/client/components/fresh-agent/FreshAgentTranscript.test.tsx
@@ -434,7 +434,7 @@ describe('FreshAgentTranscript', () => {
     expect(strips[0]).toHaveTextContent('1 tool used')
   })
 
-  it('coalesces consecutive activity-only assistant turns into one live activity strip', () => {
+  it('keeps consecutive activity-only assistant turns separate while marking only the latest live', () => {
     render(
       <FreshAgentTranscript
         isStreaming
@@ -485,13 +485,14 @@ describe('FreshAgentTranscript', () => {
       />,
     )
 
-    expect(screen.getAllByRole('region', { name: 'Activity strip' })).toHaveLength(1)
+    expect(screen.getAllByRole('region', { name: 'Activity strip' })).toHaveLength(3)
     expect(screen.getAllByLabelText('running')).toHaveLength(1)
     expect(screen.getByText('src/three.ts')).toBeInTheDocument()
 
-    fireEvent.click(screen.getByRole('button', { name: 'Toggle activity details' }))
+    fireEvent.click(screen.getAllByRole('button', { name: 'Toggle activity details' })[2])
     expect(screen.getAllByLabelText('running')).toHaveLength(1)
-    expect(screen.getAllByLabelText('complete')).toHaveLength(2)
+    fireEvent.click(screen.getAllByRole('button', { name: 'Toggle activity details' })[0])
+    expect(screen.getAllByLabelText('complete').length).toBeGreaterThanOrEqual(1)
   })
 
   it('shows the speaker label once for consecutive turns from the same role', () => {
@@ -690,6 +691,39 @@ describe('FreshAgentTranscript', () => {
       .toHaveTextContent('1 tool used · 1 file changed')
   })
 
+  it('keeps adjacent activity-only display turns distinct and actionable', () => {
+    const onFork = vi.fn()
+    render(
+      <FreshAgentTranscript
+        canFork
+        onForkFromTurn={onFork}
+        turns={[
+          {
+            id: 'native-turn',
+            turnId: 'display-activity-1',
+            role: 'assistant',
+            summary: 'first activity',
+            items: [{ id: 'think-1', kind: 'thinking', text: 'first thought' }],
+          },
+          {
+            id: 'native-turn',
+            turnId: 'display-activity-2',
+            role: 'assistant',
+            summary: 'second activity',
+            items: [{ id: 'think-2', kind: 'thinking', text: 'second thought' }],
+          },
+        ]}
+      />,
+    )
+
+    expect(screen.getAllByRole('article', { name: 'Assistant transcript turn' })).toHaveLength(2)
+    expect(screen.getAllByRole('region', { name: 'Activity strip' })).toHaveLength(2)
+
+    const forkButtons = screen.getAllByRole('button', { name: 'Fork conversation from here' })
+    fireEvent.click(forkButtons[1])
+    expect(onFork).toHaveBeenCalledWith('display-activity-2')
+  })
+
   it('strips system reminders without collapsing older turns', () => {
     render(
       <FreshAgentTranscript
diff --git a/test/unit/client/components/fresh-agent/FreshAgentTurnActions.test.tsx b/test/unit/client/components/fresh-agent/FreshAgentTurnActions.test.tsx
new file mode 100644
index 000000000..d30f7c78e
--- /dev/null
+++ b/test/unit/client/components/fresh-agent/FreshAgentTurnActions.test.tsx
@@ -0,0 +1,52 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import {
+  buildTurnActionItems,
+  FreshAgentTurnActions,
+} from '@/components/fresh-agent/FreshAgentTurnActions'
+import type { FreshAgentTurn } from '@shared/fresh-agent-contract'
+
+vi.mock('@/lib/clipboard', () => ({
+  copyText: vi.fn().mockResolvedValue(true),
+}))
+
+afterEach(() => cleanup())
+
+function codexDisplayTurn(): FreshAgentTurn {
+  return {
+    id: 'codex-native-turn-1',
+    turnId: 'codex-display:v1:opaque-user-row',
+    role: 'assistant',
+    summary: 'answer',
+    items: [{ id: 'text-1', kind: 'text', text: 'done' }],
+  }
+}
+
+describe('FreshAgentTurnActions', () => {
+  it('passes the opaque display turn id to action callbacks', () => {
+    const onForkFromTurn = vi.fn()
+    const items = buildTurnActionItems(codexDisplayTurn(), {
+      canFork: true,
+      onForkFromTurn,
+    })
+
+    items.find((item) => item.label === 'Fork conversation from here')?.run()
+
+    expect(onForkFromTurn).toHaveBeenCalledWith('codex-display:v1:opaque-user-row')
+  })
+
+  it('uses the display turn id from the hover toolbar', () => {
+    const onForkFromTurn = vi.fn()
+    render(
+      <FreshAgentTurnActions
+        turn={codexDisplayTurn()}
+        canFork
+        onForkFromTurn={onForkFromTurn}
+      />,
+    )
+
+    fireEvent.click(screen.getByRole('button', { name: 'Fork conversation from here' }))
+
+    expect(onForkFromTurn).toHaveBeenCalledWith('codex-display:v1:opaque-user-row')
+  })
+})
diff --git a/test/unit/client/components/fresh-agent/FreshAgentView.test.tsx b/test/unit/client/components/fresh-agent/FreshAgentView.test.tsx
index 69ce5d677..761734179 100644
--- a/test/unit/client/components/fresh-agent/FreshAgentView.test.tsx
+++ b/test/unit/client/components/fresh-agent/FreshAgentView.test.tsx
@@ -1200,8 +1200,9 @@ describe('FreshAgentView', () => {
     })
     fireEvent.click(screen.getByRole('button', { name: 'Send' }))
 
-    expect(wsMock.send).toHaveBeenCalledWith({
+    expect(wsMock.send).toHaveBeenCalledWith(expect.objectContaining({
       type: 'freshAgent.send',
+      requestId: expect.any(String),
       sessionId: 'thread-1',
       sessionType: 'freshcodex',
       provider: 'codex',
@@ -1211,12 +1212,134 @@ describe('FreshAgentView', () => {
         model: 'gpt-5.3-codex-spark',
         effort: 'max',
       },
-    })
+    }))
 
     expect(screen.queryByRole('button', { name: 'Interrupt' })).not.toBeInTheDocument()
     expect(screen.queryByRole('button', { name: 'Fork' })).not.toBeInTheDocument()
   })
 
+  it('uses send acknowledgements to patch checkpoints and clear local echo only on the submitted user display turn', async () => {
+    const store = createStore()
+    const checkpoint = createDeferred<{ id: string; ts: number; label: string; requestId: string }>()
+    let onMessage: ((message: Record<string, unknown>) => void) | undefined
+    wsMock.onMessage.mockImplementation((handler: (message: Record<string, unknown>) => void) => {
+      onMessage = handler
+      return () => {}
+    })
+    apiMock.getFreshAgentThreadSnapshot
+      .mockResolvedValueOnce({
+        status: 'idle',
+        summary: 'empty',
+        capabilities: { send: true, interrupt: true, fork: true },
+        turns: [],
+      })
+      .mockResolvedValueOnce({
+        status: 'idle',
+        summary: 'answered',
+        capabilities: { send: true, interrupt: true, fork: true },
+        turns: [
+          {
+            id: 'native-user-turn',
+            turnId: 'display-user-1',
+            role: 'user',
+            summary: 'Ship it',
+            items: [{ id: 'user-text-1', kind: 'text', text: 'Ship it' }],
+          },
+          {
+            id: 'native-assistant-turn',
+            turnId: 'display-assistant-1',
+            role: 'assistant',
+            summary: 'Done',
+            items: [{ id: 'assistant-text-1', kind: 'text', text: 'Done.' }],
+          },
+        ],
+      })
+    apiMock.post.mockImplementation((url: string, body: Record<string, unknown>) => {
+      if (url === '/api/fresh-agent/checkpoints') return checkpoint.promise
+      if (url === '/api/fresh-agent/checkpoints/metadata') return Promise.resolve({ ok: true, body })
+      return Promise.resolve({ title: null, source: 'none' })
+    })
+    store.dispatch(initLayout({
+      tabId: 'tab-1',
+      paneId: 'pane-1',
+      content: {
+        kind: 'fresh-agent',
+        sessionType: 'freshcodex',
+        provider: 'codex',
+        createRequestId: 'req-normalized-send',
+        sessionId: 'thread-normalized-send',
+        status: 'idle',
+        initialCwd: '/repo',
+      },
+    }))
+
+    render(
+      <Provider store={store}>
+        <StoreBackedFreshAgentView tabId="tab-1" paneId="pane-1" />
+      </Provider>,
+    )
+
+    await waitFor(() => {
+      expect(screen.getByRole('textbox', { name: 'Chat message input' })).not.toBeDisabled()
+    })
+    wsMock.send.mockClear()
+
+    fireEvent.change(screen.getByRole('textbox', { name: 'Chat message input' }), {
+      target: { value: 'Ship it' },
+    })
+    fireEvent.click(screen.getByRole('button', { name: 'Send' }))
+
+    const send = sentFreshAgentMessages('freshAgent.send').at(-1)
+    expect(send).toMatchObject({
+      type: 'freshAgent.send',
+      sessionId: 'thread-normalized-send',
+      sessionType: 'freshcodex',
+      provider: 'codex',
+      text: 'Ship it',
+    })
+    expect(send?.requestId).toEqual(expect.any(String))
+    const requestId = String(send?.requestId)
+    expect(apiMock.post).toHaveBeenCalledWith('/api/fresh-agent/checkpoints', {
+      cwd: '/repo',
+      label: 'Ship it',
+      requestId,
+    })
+    expect(screen.getByText('Ship it')).toBeInTheDocument()
+
+    expect(onMessage).toBeTypeOf('function')
+    act(() => {
+      onMessage?.({
+        type: 'freshAgent.send.accepted',
+        requestId,
+        submittedTurnId: 'display-user-1',
+      })
+    })
+    await act(async () => {
+      checkpoint.resolve({
+        id: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+        ts: 1,
+        label: 'Ship it',
+        requestId,
+      })
+      await Promise.resolve()
+    })
+
+    await waitFor(() => {
+      expect(apiMock.post).toHaveBeenCalledWith('/api/fresh-agent/checkpoints/metadata', {
+        cwd: '/repo',
+        id: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+        requestId,
+        turnId: 'display-user-1',
+      })
+    })
+    await waitFor(() => {
+      expect(screen.getByText('Done.')).toBeInTheDocument()
+    })
+    expect(screen.getAllByText('Ship it')).toHaveLength(1)
+    const transcriptTurns = screen.getAllByRole('article')
+    expect(transcriptTurns.at(-1)).toHaveTextContent('Done.')
+  })
+
   it('does not transmit stale Freshopencode permissionMode on create or send', async () => {
     const creatingStore = createStore()
     creatingStore.dispatch(initLayout({
@@ -1284,8 +1407,9 @@ describe('FreshAgentView', () => {
     })
     fireEvent.click(screen.getByRole('button', { name: 'Send' }))
 
-    expect(wsMock.send).toHaveBeenCalledWith({
+    expect(wsMock.send).toHaveBeenCalledWith(expect.objectContaining({
       type: 'freshAgent.send',
+      requestId: expect.any(String),
       sessionId: 'freshopencode-req-opencode-send-policy',
       sessionType: 'freshopencode',
       provider: 'opencode',
@@ -1295,7 +1419,7 @@ describe('FreshAgentView', () => {
         model: 'opencode-go/deepseek-v4-flash',
         effort: 'max',
       },
-    })
+    }))
   })
 
   it('auto-titles the fresh-agent pane and tab from the first user message', async () => {
@@ -2100,12 +2224,19 @@ describe('FreshAgentView', () => {
       target: { value: 'New user request' },
     })
     fireEvent.click(screen.getByRole('button', { name: 'Send' }))
+    const send = sentFreshAgentMessages('freshAgent.send').at(-1)
+    const requestId = String(send?.requestId)
 
     expect(screen.getByText('Older user request')).toBeInTheDocument()
     expect(screen.getByText('Older assistant answer')).toBeInTheDocument()
 
     expect(onMessage).toBeTypeOf('function')
     act(() => {
+      onMessage?.({
+        type: 'freshAgent.send.accepted',
+        requestId,
+        submittedTurnId: 'turn-new-user',
+      })
       onMessage?.({
         type: 'freshAgent.event',
         sessionId: 'thread-partial-refresh',
diff --git a/test/unit/client/lib/fresh-agent-checkpoints.test.ts b/test/unit/client/lib/fresh-agent-checkpoints.test.ts
index 07adf1f43..eeb0686cc 100644
--- a/test/unit/client/lib/fresh-agent-checkpoints.test.ts
+++ b/test/unit/client/lib/fresh-agent-checkpoints.test.ts
@@ -6,10 +6,10 @@ import {
 } from '@/lib/fresh-agent-checkpoints'
 import type { FreshAgentTurn } from '@shared/fresh-agent-contract'
 
-function userTurn(id: string, text: string): FreshAgentTurn {
+function userTurn(id: string, text: string, turnId = id): FreshAgentTurn {
   return {
     id,
-    turnId: id,
+    turnId,
     role: 'user',
     summary: text,
     items: [{ id: `${id}-item`, kind: 'text', text }],
@@ -42,6 +42,47 @@ describe('checkpointLabelForText', () => {
 })
 
 describe('pickCheckpointForTurn', () => {
+  it('matches persisted display turn id only for normalized user turns', () => {
+    const user = userTurn('native-turn-1-user', 'same native', 'display-user-1')
+    const assistant = {
+      ...assistantTurn('native-turn-1-assistant'),
+      turnId: 'display-assistant-1',
+      id: 'native-turn-1-assistant',
+      summary: 'same native',
+      items: [{ id: 'assistant-item', kind: 'text' as const, text: 'same native' }],
+    } as FreshAgentTurn
+    const checkpoints: CheckpointEntry[] = [
+      { id: 'sha-user', ts: 1, label: 'same native', turnId: 'display-user-1' },
+    ]
+
+    expect(pickCheckpointForTurn(checkpoints, [user, assistant], user)?.id).toBe('sha-user')
+    expect(pickCheckpointForTurn(checkpoints, [user, assistant], assistant)).toBeNull()
+  })
+
+  it('prefers display turn id and request id before duplicate label ordinal matching', () => {
+    const older = userTurn('old-native', 'fix the bug', 'display-old')
+    const newer = userTurn('new-native', 'fix the bug', 'display-new') as FreshAgentTurn & { requestId: string }
+    newer.requestId = 'send-new'
+    const turns = [newer, assistantTurn('reply'), older]
+    const checkpoints: CheckpointEntry[] = [
+      { id: 'sha-old', ts: 100, label: 'fix the bug', turnId: 'display-old', requestId: 'send-old' },
+      { id: 'sha-new', ts: 200, label: 'fix the bug', requestId: 'send-new' },
+    ]
+
+    expect(pickCheckpointForTurn(checkpoints, turns, newer)?.id).toBe('sha-new')
+    expect(pickCheckpointForTurn(checkpoints, turns, older)?.id).toBe('sha-old')
+  })
+
+  it('does not let a checkpoint for an older duplicate prompt satisfy a newer display turn by label', () => {
+    const newer = userTurn('new-native', 'fix the bug', 'display-new')
+    const older = userTurn('old-native', 'fix the bug', 'display-old')
+    const checkpoints: CheckpointEntry[] = [
+      { id: 'sha-old', ts: 100, label: 'fix the bug', turnId: 'display-old', requestId: 'send-old' },
+    ]
+
+    expect(pickCheckpointForTurn(checkpoints, [newer, older], newer)).toBeNull()
+  })
+
   it('matches a user turn to its checkpoint by label', () => {
     const turns = [userTurn('t1', 'add a test'), assistantTurn('t2')]
     expect(pickCheckpointForTurn(CHECKPOINTS, turns, turns[0])?.id).toBe('sha-2')
diff --git a/test/unit/server/ws-handler-fresh-agent.test.ts b/test/unit/server/ws-handler-fresh-agent.test.ts
index 7a0461f66..479ebe3f1 100644
--- a/test/unit/server/ws-handler-fresh-agent.test.ts
+++ b/test/unit/server/ws-handler-fresh-agent.test.ts
@@ -368,7 +368,7 @@ describe('WsHandler fresh-agent routing', () => {
         runtimeProvider: 'codex',
       }),
       subscribe: vi.fn().mockResolvedValue(() => undefined),
-      send: vi.fn().mockResolvedValue(undefined),
+      send: vi.fn().mockResolvedValue({ requestId: 'send-req-1', submittedTurnId: 'display-user-1' }),
       interrupt: vi.fn().mockResolvedValue(undefined),
       resolveApproval: vi.fn().mockResolvedValue(undefined),
       answerQuestion: vi.fn().mockResolvedValue(undefined),
@@ -397,6 +397,7 @@ describe('WsHandler fresh-agent routing', () => {
 
       ws.send(JSON.stringify({
         type: 'freshAgent.send',
+        requestId: 'send-req-1',
         sessionId: 'codex-session-2',
         sessionType: 'freshcodex',
         provider: 'codex',
@@ -442,6 +443,7 @@ describe('WsHandler fresh-agent routing', () => {
       await vi.waitFor(() => {
         const locator = { sessionId: 'codex-session-2', sessionType: 'freshcodex', provider: 'codex' }
         expect(runtimeManager.send).toHaveBeenCalledWith(locator, {
+          requestId: 'send-req-1',
           text: 'Ship it',
           images: undefined,
           settings: { cwd: '/repo', model: 'gpt-5.4-mini', effort: 'low' },
@@ -455,6 +457,11 @@ describe('WsHandler fresh-agent routing', () => {
           expect.any(Function),
         )
         expect(runtimeManager.kill).toHaveBeenCalledWith(locator)
+        expect(seenMessages).toContainEqual(expect.objectContaining({
+          type: 'freshAgent.send.accepted',
+          requestId: 'send-req-1',
+          submittedTurnId: 'display-user-1',
+        }))
         expect(seenMessages).toContainEqual(expect.objectContaining({
           type: 'freshAgent.forked',
           requestId: 'fork-req-1',

From e8505ebf0d78fd41578d3642e3c65cdb07a7e271 Mon Sep 17 00:00:00 2001
From: Codex <codex@openai.com>
Date: Fri, 19 Jun 2026 03:19:45 -0700
Subject: [PATCH 28/33] test: assert codex durable user messages in real
 contract

---
 ...odex-app-server-readiness-contract.test.ts | 116 +++++++++++++++++-
 1 file changed, 115 insertions(+), 1 deletion(-)

diff --git a/test/integration/real/codex-app-server-readiness-contract.test.ts b/test/integration/real/codex-app-server-readiness-contract.test.ts
index b2019e67c..02142ea06 100644
--- a/test/integration/real/codex-app-server-readiness-contract.test.ts
+++ b/test/integration/real/codex-app-server-readiness-contract.test.ts
@@ -10,6 +10,7 @@ import WebSocket from 'ws'
 
 import { CodexAppServerClient, type CodexThreadLifecycleEvent } from '../../../server/coding-cli/codex-app-server/client.js'
 import { CodexAppServerRuntime } from '../../../server/coding-cli/codex-app-server/runtime.js'
+import { createCodexFreshAgentAdapter } from '../../../server/fresh-agent/adapters/codex/adapter.js'
 
 type JsonRpcNotification = {
   method: string
@@ -212,6 +213,42 @@ function isDurableReadinessEvidence(event: CodexThreadLifecycleEvent, threadId:
 const codexProbe = await codexAvailability()
 const describeCodex = codexProbe.ready ? describe : describe.skip
 
+function readUserMessageTexts(item: Record<string, unknown>): string[] {
+  const contentTexts = Array.isArray(item.content)
+    ? item.content.flatMap((part) => {
+      if (!part || typeof part !== 'object' || Array.isArray(part)) return []
+      return typeof part.text === 'string' ? [part.text] : []
+    })
+    : []
+  if (contentTexts.length > 0) return contentTexts
+  if (typeof item.text === 'string') return [item.text]
+  if (typeof item.summary === 'string') return [item.summary]
+  return []
+}
+
+function rawTurnIncludesUserMessageText(rawTurn: Record<string, unknown>, needle: string): boolean {
+  const items = Array.isArray(rawTurn.items)
+    ? rawTurn.items.filter((item): item is Record<string, unknown> => !!item && typeof item === 'object' && !Array.isArray(item))
+    : []
+  return items.some((item) => item.type === 'userMessage' && readUserMessageTexts(item).some((text) => text.includes(needle)))
+}
+
+function findRawTurnByUserMessageText(rawTurns: unknown, needle: string): Record<string, unknown> | undefined {
+  const turns = Array.isArray(rawTurns)
+    ? rawTurns.filter((turn): turn is Record<string, unknown> => !!turn && typeof turn === 'object' && !Array.isArray(turn))
+    : []
+  return turns.find((turn) => rawTurnIncludesUserMessageText(turn, needle))
+}
+
+function displayTurnIncludesText(turn: { items?: Array<Record<string, unknown>> }, needle: string): boolean {
+  return (turn.items ?? []).some((item) => item.kind === 'text' && typeof item.text === 'string' && item.text.includes(needle))
+}
+
+function comparableDisplayTurn<T extends { ordinal?: number }>(turn: T): Omit<T, 'ordinal'> {
+  const { ordinal: _ordinal, ...rest } = turn
+  return rest
+}
+
 async function waitForSessionArtifact(codexHome: string, threadId: string, timeoutMs = 60_000): Promise<string> {
   const sessionsRoot = path.join(codexHome, 'sessions')
   const deadline = Date.now() + timeoutMs
@@ -229,6 +266,8 @@ async function waitForSessionArtifact(codexHome: string, threadId: string, timeo
 describeCodex(`real Codex app-server durable readiness contract${codexProbe.ready ? '' : ` (${codexProbe.reason})`}`, () => {
   it('emits current-generation lifecycle evidence when a durable thread is resumed', async () => {
     const { codexHome, root } = await seedIsolatedCodexHome()
+    const promptNonce = `freshell-readiness-contract-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+    const displayIdSecret = 'task-7-real-provider-contract-guard'
     const creationRuntime = new CodexAppServerRuntime({
       env: { CODEX_HOME: codexHome },
       startupAttemptLimit: 1,
@@ -237,6 +276,9 @@ describeCodex(`real Codex app-server durable readiness contract${codexProbe.read
     })
     let creationClient: JsonRpcClient | null = null
     let durableThreadId = ''
+    let providerUserTurnId = ''
+    let providerRevision = 0
+    let displayUserTurnIdBeforeResume = ''
 
     try {
       const ready = await creationRuntime.ensureReady()
@@ -253,7 +295,7 @@ describeCodex(`real Codex app-server durable readiness contract${codexProbe.read
       durableThreadId = parseThreadId(started)
       await creationClient.request('turn/start', {
         threadId: durableThreadId,
-        input: [{ type: 'text', text: 'Reply with exactly: freshell-readiness-contract' }],
+        input: [{ type: 'text', text: `Reply with exactly: ${promptNonce}` }],
       })
       await creationClient.waitForNotification(
         (notification) => notification.method === 'turn/completed'
@@ -268,6 +310,39 @@ describeCodex(`real Codex app-server durable readiness contract${codexProbe.read
         && notification.params?.threadId === durableThreadId,
       )
       await waitForSessionArtifact(codexHome, durableThreadId)
+
+      const creationClientApi = new CodexAppServerClient({ wsUrl: ready.wsUrl }, { requestTimeoutMs: 10_000 })
+      const creationAdapter = createCodexFreshAgentAdapter({
+        runtime: creationRuntime,
+        displayIdSecret,
+      })
+      try {
+        await creationClientApi.initialize()
+        const creationSnapshot = await creationClientApi.readThread({
+          threadId: durableThreadId,
+          includeTurns: true,
+        })
+        providerRevision = Number(creationSnapshot.thread.updatedAt ?? 0)
+        const providerUserTurn = findRawTurnByUserMessageText(creationSnapshot.thread.turns, promptNonce)
+        expect(providerUserTurn).toBeDefined()
+        expect(providerUserTurn && typeof providerUserTurn.id === 'string' ? providerUserTurn.id : '').not.toBe('')
+        providerUserTurnId = String(providerUserTurn?.id ?? '')
+
+        const creationPage = await creationAdapter.getTurnPage?.({
+          sessionType: 'freshcodex',
+          provider: 'codex',
+          threadId: durableThreadId,
+        }, {
+          revision: providerRevision,
+          limit: 100,
+        })
+        const creationDisplayTurn = creationPage?.turns.find((turn) => turn.role === 'user' && displayTurnIncludesText(turn, promptNonce))
+        expect(creationDisplayTurn).toBeDefined()
+        displayUserTurnIdBeforeResume = creationDisplayTurn?.turnId ?? ''
+      } finally {
+        await creationClientApi.close().catch(() => undefined)
+        await creationAdapter.shutdown?.().catch(() => undefined)
+      }
     } finally {
       await creationClient?.close().catch(() => undefined)
       await creationRuntime.shutdown().catch(() => undefined)
@@ -280,6 +355,10 @@ describeCodex(`real Codex app-server durable readiness contract${codexProbe.read
       requestTimeoutMs: 60_000,
     })
     const clients: CodexAppServerClient[] = []
+    const adapter = createCodexFreshAgentAdapter({
+      runtime,
+      displayIdSecret,
+    })
 
     try {
       const ready = await runtime.ensureReady()
@@ -336,6 +415,40 @@ describeCodex(`real Codex app-server durable readiness contract${codexProbe.read
         id: olderTurnPage.turns[0]!.id,
         itemsView: 'full',
       })
+      const resumedSnapshot = await actor.readThread({
+        threadId: durableThreadId,
+        includeTurns: true,
+      })
+      const resumedRevision = Number(resumedSnapshot.thread.updatedAt ?? providerRevision)
+      const providerUserTurn = findRawTurnByUserMessageText(resumedSnapshot.thread.turns, promptNonce)
+      expect(providerUserTurn).toBeDefined()
+      expect(providerUserTurn).toMatchObject({
+        id: providerUserTurnId,
+      })
+      expect(providerUserTurn && rawTurnIncludesUserMessageText(providerUserTurn, promptNonce)).toBe(true)
+
+      const displayPage = await adapter.getTurnPage?.({
+        sessionType: 'freshcodex',
+        provider: 'codex',
+        threadId: durableThreadId,
+      }, {
+        revision: resumedRevision,
+        limit: 100,
+      })
+      const displayUserTurn = displayPage?.turns.find((turn) => turn.role === 'user' && displayTurnIncludesText(turn, promptNonce))
+      expect(displayUserTurn).toBeDefined()
+      expect(displayUserTurn?.turnId).toBe(displayUserTurnIdBeforeResume)
+      expect(displayUserTurn?.turnId).toMatch(/^codex-display:/)
+      expect(displayUserTurn?.turnId).not.toContain(providerUserTurnId)
+
+      const displayBody = await adapter.getTurnBody?.({
+        sessionType: 'freshcodex',
+        provider: 'codex',
+        threadId: durableThreadId,
+        turnId: displayUserTurn!.turnId,
+      }, resumedRevision)
+      expect(displayBody).toBeDefined()
+      expect(comparableDisplayTurn(displayBody!)).toEqual(comparableDisplayTurn(displayUserTurn!))
 
       const readiness = await waitForLifecycle(
         lifecycle,
@@ -352,6 +465,7 @@ describeCodex(`real Codex app-server durable readiness contract${codexProbe.read
       }
     } finally {
       await Promise.all(clients.map((client) => client.close().catch(() => undefined)))
+      await adapter.shutdown?.().catch(() => undefined)
       await runtime.shutdown().catch(() => undefined)
       await fsp.rm(root, { force: true, recursive: true }).catch(() => undefined)
     }

From c45baa1811c462b231d7a7ff0c3c9a1e7cfd8888 Mon Sep 17 00:00:00 2001
From: Codex <codex@openai.com>
Date: Fri, 19 Jun 2026 03:24:15 -0700
Subject: [PATCH 29/33] fix: stabilize fresh agent session selector

---
 src/components/fresh-agent/FreshAgentView.tsx | 13 ++++---------
 1 file changed, 4 insertions(+), 9 deletions(-)

diff --git a/src/components/fresh-agent/FreshAgentView.tsx b/src/components/fresh-agent/FreshAgentView.tsx
index ba9067080..643efcdae 100644
--- a/src/components/fresh-agent/FreshAgentView.tsx
+++ b/src/components/fresh-agent/FreshAgentView.tsx
@@ -390,19 +390,14 @@ export function FreshAgentView({
   // through the freshAgent slice too, but the claudeSession selector above is
   // claude-only — without this, a dead codex/opencode process left the pane
   // looking healthy (blank pane, enabled composer).
-  const agentSessionMeta = useAppSelector((state) => {
+  const agentSession = useAppSelector((state) => {
     if (!paneContent.sessionId) return undefined
     const sessionKey = makeFreshAgentSessionKey({
       sessionId: paneContent.sessionId,
       sessionType: paneContent.sessionType,
       provider: paneContent.provider,
     })
-    const session = state.freshAgent.sessions[sessionKey]
-    if (!session) return undefined
-    return {
-      status: session.status as string | undefined,
-      lastError: (session as { lastError?: string }).lastError,
-    }
+    return state.freshAgent.sessions[sessionKey]
   })
   const refreshRequest = useAppSelector((state) => state.panes.refreshRequestsByPane?.[tabId]?.[paneId] ?? null)
   const [snapshot, setSnapshot] = useState<FreshAgentSnapshot | null>(null)
@@ -1217,10 +1212,10 @@ export function FreshAgentView({
 
   const effectiveStatus = paneContent.provider === 'claude'
     ? (claudeSessionStatus ?? paneContent.status)
-    : (agentSessionMeta?.status ?? paneContent.status)
+    : (agentSession?.status ?? paneContent.status)
   const isBusy = BUSY_STATES.has(effectiveStatus)
   const sessionEnded = effectiveStatus === 'exited' || effectiveStatus === 'create-failed'
-  const sessionErrorMessage = agentSessionMeta?.lastError ?? null
+  const sessionErrorMessage = (agentSession as { lastError?: string } | undefined)?.lastError ?? null
 
   useEffect(() => {
     if (hidden) return

From 1fe1a2d1a7f029f30363842a04c30c79f4d2949a Mon Sep 17 00:00:00 2001
From: Codex <codex@openai.com>
Date: Fri, 19 Jun 2026 03:29:34 -0700
Subject: [PATCH 30/33] test: compare codex display body contract fields

---
 .../real/codex-app-server-readiness-contract.test.ts      | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/test/integration/real/codex-app-server-readiness-contract.test.ts b/test/integration/real/codex-app-server-readiness-contract.test.ts
index 02142ea06..ba4513b51 100644
--- a/test/integration/real/codex-app-server-readiness-contract.test.ts
+++ b/test/integration/real/codex-app-server-readiness-contract.test.ts
@@ -244,9 +244,11 @@ function displayTurnIncludesText(turn: { items?: Array<Record<string, unknown>>
   return (turn.items ?? []).some((item) => item.kind === 'text' && typeof item.text === 'string' && item.text.includes(needle))
 }
 
-function comparableDisplayTurn<T extends { ordinal?: number }>(turn: T): Omit<T, 'ordinal'> {
-  const { ordinal: _ordinal, ...rest } = turn
-  return rest
+function comparableDisplayTurn(turn: Record<string, unknown>): Record<string, unknown> {
+  const comparableKeys = ['id', 'turnId', 'messageId', 'source', 'role', 'timestamp', 'model', 'summary', 'items'] as const
+  return Object.fromEntries(comparableKeys
+    .filter((key) => key in turn)
+    .map((key) => [key, turn[key]]))
 }
 
 async function waitForSessionArtifact(codexHome: string, threadId: string, timeoutMs = 60_000): Promise<string> {

From 0bbf3e55161258974e4caf922d5aa28bfcbdc144 Mon Sep 17 00:00:00 2001
From: Codex <codex@openai.com>
Date: Fri, 19 Jun 2026 03:50:38 -0700
Subject: [PATCH 31/33] fix: clean up fresh eyes transcript findings

---
 .../fresh-agent/adapters/codex/normalize.ts   | 42 +------------------
 src/components/fresh-agent/FreshAgentView.tsx |  1 +
 2 files changed, 2 insertions(+), 41 deletions(-)

diff --git a/server/fresh-agent/adapters/codex/normalize.ts b/server/fresh-agent/adapters/codex/normalize.ts
index 5067f0526..3f05c67bd 100644
--- a/server/fresh-agent/adapters/codex/normalize.ts
+++ b/server/fresh-agent/adapters/codex/normalize.ts
@@ -173,7 +173,7 @@ function summarizeFreshAgentItems(items: FreshAgentTranscriptItem[]): string {
       case 'thinking':
         return item.text.slice(0, 140)
       case 'reasoning':
-        return (item.text ?? item.summary.join('\n') ?? item.content.join('\n')).slice(0, 140)
+        return (item.text ?? (item.summary.join('\n') || item.content.join('\n'))).slice(0, 140)
       case 'command':
         return item.command.slice(0, 140)
       case 'file_change':
@@ -706,46 +706,6 @@ export function normalizeCodexTurn(
   }
 }
 
-export function normalizeCodexTurnPage(input: {
-  threadId: string
-  revision: number
-  rawPage: { turns?: unknown[]; nextCursor?: string | null; backwardsCursor?: string | null }
-  model?: string
-  modelByTurn?: Map<string, string>
-  secret?: string
-  submittedRequestIdByProviderTurnId?: ReadonlyMap<string, string | number>
-}) {
-  const turns = (Array.isArray(input.rawPage.turns) ? input.rawPage.turns : [])
-    .filter((turn): turn is Record<string, unknown> => !!turn && typeof turn === 'object' && !Array.isArray(turn))
-    .flatMap((turn) => normalizeCodexDisplayTurns(turn, 0, {
-      threadId: input.threadId,
-      secret: input.secret,
-      submittedRequestIdByProviderTurnId: input.submittedRequestIdByProviderTurnId,
-      model: (typeof turn.id === 'string' ? input.modelByTurn?.get(turn.id) : undefined) ?? input.model,
-    }).turns)
-    .map((turn, index) => {
-      const { syntheticKind: _syntheticKind, requestId: _requestId, ...parsedTurn } = turn as FreshAgentTurn & {
-        syntheticKind?: CodexDisplaySyntheticKind
-        requestId?: string | number
-      }
-      return {
-        ...parsedTurn,
-        ordinal: index,
-      }
-    })
-
-  return FreshAgentTurnPageSchema.parse({
-    sessionType: 'freshcodex',
-    provider: 'codex',
-    threadId: input.threadId,
-    revision: input.revision,
-    nextCursor: input.rawPage.nextCursor ?? null,
-    backwardsCursor: input.rawPage.backwardsCursor ?? null,
-    turns,
-    bodies: Object.fromEntries(turns.map((turn) => [turn.turnId, turn])),
-  })
-}
-
 export function normalizeCodexTurnBody(input: {
   threadId: string
   revision: number
diff --git a/src/components/fresh-agent/FreshAgentView.tsx b/src/components/fresh-agent/FreshAgentView.tsx
index 643efcdae..f55bcf1ed 100644
--- a/src/components/fresh-agent/FreshAgentView.tsx
+++ b/src/components/fresh-agent/FreshAgentView.tsx
@@ -1604,6 +1604,7 @@ export function FreshAgentView({
                 ? [...turns, {
                     id: `__local-echo:${localEcho.requestId}`,
                     turnId: localEcho.submittedTurnId ?? `__local-echo:${localEcho.requestId}`,
+                    requestId: localEcho.requestId,
                     role: 'user',
                     summary: localEcho.text,
                     items: [{ id: `__local-echo-item:${localEcho.requestId}`, kind: 'text', text: localEcho.text }],

From 92428ee7c2fe01f48137b1d43a358bee26571578 Mon Sep 17 00:00:00 2001
From: Codex <codex@openai.com>
Date: Fri, 19 Jun 2026 04:12:10 -0700
Subject: [PATCH 32/33] fix: prune checkpoint metadata and label matching

---
 src/components/fresh-agent/FreshAgentView.tsx        |  3 +++
 src/lib/fresh-agent-checkpoints.ts                   | 10 ++++++++++
 test/unit/client/lib/fresh-agent-checkpoints.test.ts | 11 +++++++++++
 3 files changed, 24 insertions(+)

diff --git a/src/components/fresh-agent/FreshAgentView.tsx b/src/components/fresh-agent/FreshAgentView.tsx
index f55bcf1ed..7b798be12 100644
--- a/src/components/fresh-agent/FreshAgentView.tsx
+++ b/src/components/fresh-agent/FreshAgentView.tsx
@@ -544,6 +544,9 @@ export function FreshAgentView({
         requestId,
         turnId: next.submittedTurnId,
       }))
+      .then(() => {
+        pendingSendMetadataRef.current.delete(requestId)
+      })
       .catch(() => {
         const latest = pendingSendMetadataRef.current.get(requestId)
         if (latest) {
diff --git a/src/lib/fresh-agent-checkpoints.ts b/src/lib/fresh-agent-checkpoints.ts
index 542a8f05e..2cfb9241e 100644
--- a/src/lib/fresh-agent-checkpoints.ts
+++ b/src/lib/fresh-agent-checkpoints.ts
@@ -14,6 +14,15 @@ function turnLabel(turn: FreshAgentTurn): string {
   return checkpointLabelForText(freshAgentTurnText(turn) || '')
 }
 
+function hasDirectCheckpoint(checkpoints: readonly CheckpointEntry[], turn: FreshAgentTurn): boolean {
+  const turnId = getFreshAgentDisplayTurnKey(turn)
+  if (checkpoints.some((entry) => entry.turnId === turnId)) return true
+  const requestId = (turn as FreshAgentTurn & { requestId?: unknown }).requestId
+  return typeof requestId === 'string'
+    && requestId.length > 0
+    && checkpoints.some((entry) => entry.requestId === requestId)
+}
+
 /**
  * Match a user turn to its checkpoint. Checkpoints are created at send time
  * with the outgoing text as label, so the k-th user turn bearing a given label
@@ -44,6 +53,7 @@ export function pickCheckpointForTurn(
     if (turn.role !== 'user') continue
     if (turnLabel(turn) === label) {
       if (turn.id === target.id) break
+      if (hasDirectCheckpoint(checkpoints, turn)) continue
       ordinal += 1
     }
   }
diff --git a/test/unit/client/lib/fresh-agent-checkpoints.test.ts b/test/unit/client/lib/fresh-agent-checkpoints.test.ts
index eeb0686cc..2674150f6 100644
--- a/test/unit/client/lib/fresh-agent-checkpoints.test.ts
+++ b/test/unit/client/lib/fresh-agent-checkpoints.test.ts
@@ -83,6 +83,17 @@ describe('pickCheckpointForTurn', () => {
     expect(pickCheckpointForTurn(checkpoints, [newer, older], newer)).toBeNull()
   })
 
+  it('does not count direct-id checkpoints when indexing legacy label-only matches', () => {
+    const older = userTurn('old-native', 'fix the bug', 'display-old')
+    const newer = userTurn('new-native', 'fix the bug', 'display-new')
+    const checkpoints: CheckpointEntry[] = [
+      { id: 'sha-new', ts: 200, label: 'fix the bug' },
+      { id: 'sha-old', ts: 100, label: 'fix the bug', turnId: 'display-old' },
+    ]
+
+    expect(pickCheckpointForTurn(checkpoints, [older, newer], newer)?.id).toBe('sha-new')
+  })
+
   it('matches a user turn to its checkpoint by label', () => {
     const turns = [userTurn('t1', 'add a test'), assistantTurn('t2')]
     expect(pickCheckpointForTurn(CHECKPOINTS, turns, turns[0])?.id).toBe('sha-2')

From 67f75313a6c139a04b9a1374bcc89c9ca1d7d20a Mon Sep 17 00:00:00 2001
From: Codex <codex@openai.com>
Date: Fri, 19 Jun 2026 04:37:35 -0700
Subject: [PATCH 33/33] fix: recover stale checkpoint turn links

---
 .../fresh-agent/adapters/codex/normalize.ts   |  1 -
 src/lib/fresh-agent-checkpoints.ts            | 40 +++++++++++++++----
 .../lib/fresh-agent-checkpoints.test.ts       | 24 +++++++++++
 3 files changed, 57 insertions(+), 8 deletions(-)

diff --git a/server/fresh-agent/adapters/codex/normalize.ts b/server/fresh-agent/adapters/codex/normalize.ts
index 3f05c67bd..9fe5179a3 100644
--- a/server/fresh-agent/adapters/codex/normalize.ts
+++ b/server/fresh-agent/adapters/codex/normalize.ts
@@ -6,7 +6,6 @@ import {
 import {
   FreshAgentSnapshotSchema,
   FreshAgentTurnBodySchema,
-  FreshAgentTurnPageSchema,
   type FreshAgentTranscriptItem,
   type FreshAgentTurn,
 } from '../../../../shared/fresh-agent-contract.js'
diff --git a/src/lib/fresh-agent-checkpoints.ts b/src/lib/fresh-agent-checkpoints.ts
index 2cfb9241e..78c725574 100644
--- a/src/lib/fresh-agent-checkpoints.ts
+++ b/src/lib/fresh-agent-checkpoints.ts
@@ -14,13 +14,38 @@ function turnLabel(turn: FreshAgentTurn): string {
   return checkpointLabelForText(freshAgentTurnText(turn) || '')
 }
 
+function turnRequestId(turn: FreshAgentTurn): string | null {
+  const requestId = (turn as FreshAgentTurn & { requestId?: unknown }).requestId
+  return typeof requestId === 'string' && requestId.length > 0 ? requestId : null
+}
+
 function hasDirectCheckpoint(checkpoints: readonly CheckpointEntry[], turn: FreshAgentTurn): boolean {
   const turnId = getFreshAgentDisplayTurnKey(turn)
   if (checkpoints.some((entry) => entry.turnId === turnId)) return true
-  const requestId = (turn as FreshAgentTurn & { requestId?: unknown }).requestId
-  return typeof requestId === 'string'
-    && requestId.length > 0
-    && checkpoints.some((entry) => entry.requestId === requestId)
+  const requestId = turnRequestId(turn)
+  return requestId !== null && checkpoints.some((entry) => entry.requestId === requestId)
+}
+
+function currentUserTurnLinks(
+  turns: readonly FreshAgentTurn[],
+): { turnIds: Set<string>; requestIds: Set<string> } {
+  const turnIds = new Set<string>()
+  const requestIds = new Set<string>()
+  for (const turn of turns) {
+    if (turn.role !== 'user') continue
+    turnIds.add(getFreshAgentDisplayTurnKey(turn))
+    const requestId = turnRequestId(turn)
+    if (requestId) requestIds.add(requestId)
+  }
+  return { turnIds, requestIds }
+}
+
+function checkpointLinksCurrentTurn(
+  entry: CheckpointEntry,
+  links: { turnIds: ReadonlySet<string>; requestIds: ReadonlySet<string> },
+): boolean {
+  if (entry.turnId !== undefined && links.turnIds.has(entry.turnId)) return true
+  return entry.requestId !== undefined && links.requestIds.has(entry.requestId)
 }
 
 /**
@@ -39,8 +64,8 @@ export function pickCheckpointForTurn(
   const directTurnIdMatch = checkpoints.find((entry) => entry.turnId === targetTurnId)
   if (directTurnIdMatch) return directTurnIdMatch
 
-  const targetRequestId = (target as FreshAgentTurn & { requestId?: unknown }).requestId
-  if (typeof targetRequestId === 'string' && targetRequestId) {
+  const targetRequestId = turnRequestId(target)
+  if (targetRequestId) {
     const requestIdMatch = checkpoints.find((entry) => entry.requestId === targetRequestId)
     if (requestIdMatch) return requestIdMatch
   }
@@ -59,8 +84,9 @@ export function pickCheckpointForTurn(
   }
 
   // git log order is newest-first; we need oldest-first to index by ordinal.
+  const resolvedLinks = currentUserTurnLinks(turns)
   const matches = checkpoints
-    .filter((entry) => entry.label === label && entry.turnId === undefined)
+    .filter((entry) => entry.label === label && !checkpointLinksCurrentTurn(entry, resolvedLinks))
     .slice()
     .reverse()
   return matches[ordinal] ?? null
diff --git a/test/unit/client/lib/fresh-agent-checkpoints.test.ts b/test/unit/client/lib/fresh-agent-checkpoints.test.ts
index 2674150f6..7af9e930c 100644
--- a/test/unit/client/lib/fresh-agent-checkpoints.test.ts
+++ b/test/unit/client/lib/fresh-agent-checkpoints.test.ts
@@ -94,6 +94,30 @@ describe('pickCheckpointForTurn', () => {
     expect(pickCheckpointForTurn(checkpoints, [older, newer], newer)?.id).toBe('sha-new')
   })
 
+  it('uses label ordinal matching when saved submitted display ids no longer resolve after restart', () => {
+    const older = userTurn('old-native', 'fix the bug', 'display-old-after-restart')
+    const newer = userTurn('new-native', 'fix the bug', 'display-new-after-restart')
+    const checkpoints: CheckpointEntry[] = [
+      {
+        id: 'sha-new',
+        ts: 200,
+        label: 'fix the bug',
+        turnId: 'submitted-new-before-restart',
+        requestId: 'send-new',
+      },
+      {
+        id: 'sha-old',
+        ts: 100,
+        label: 'fix the bug',
+        turnId: 'submitted-old-before-restart',
+        requestId: 'send-old',
+      },
+    ]
+
+    expect(pickCheckpointForTurn(checkpoints, [older, newer], older)?.id).toBe('sha-old')
+    expect(pickCheckpointForTurn(checkpoints, [older, newer], newer)?.id).toBe('sha-new')
+  })
+
   it('matches a user turn to its checkpoint by label', () => {
     const turns = [userTurn('t1', 'add a test'), assistantTurn('t2')]
     expect(pickCheckpointForTurn(CHECKPOINTS, turns, turns[0])?.id).toBe('sha-2')