fix: decouple session resume from isFirstVisit guard #140

2026-06-07T01:50:32Z

xiaoju commented

2026-06-07 01:50:32 +00:00

What

Remove the isFirstVisit guard from session cache lookup in both agent-claude-code and agent-hermes.

Why

When frontmatter validation fails, the step is never written to CAS → isFirstVisit stays true on the next run → session cache is skipped → agent starts a fresh session (new worktree) → all previous work is wasted.

This burned ~30 min of Claude Code time and 1603 lines of working code on ocas #83 — the agent wrote everything, committed it, but the frontmatter did not parse, so the next run ignored the cached session and started from scratch.

Changes

packages/agent-claude-code/src/claude-code.ts — remove if (!ctx.isFirstVisit) guard around session cache check. Now always checks cache; falls back to fresh session if no cache entry exists.
packages/agent-hermes/src/hermes.ts — remove ctx.isFirstVisit || from prepareSession guard. Same logic: only resumeDisabled can skip cache lookup.

Ref

Fixes #139

## What Remove the `isFirstVisit` guard from session cache lookup in both `agent-claude-code` and `agent-hermes`. ## Why When frontmatter validation fails, the step is never written to CAS → `isFirstVisit` stays `true` on the next run → session cache is skipped → agent starts a fresh session (new worktree) → all previous work is wasted. This burned ~30 min of Claude Code time and 1603 lines of working code on ocas #83 — the agent wrote everything, committed it, but the frontmatter did not parse, so the next run ignored the cached session and started from scratch. ## Changes - **`packages/agent-claude-code/src/claude-code.ts`** — remove `if (!ctx.isFirstVisit)` guard around session cache check. Now always checks cache; falls back to fresh session if no cache entry exists. - **`packages/agent-hermes/src/hermes.ts`** — remove `ctx.isFirstVisit ||` from prepareSession guard. Same logic: only `resumeDisabled` can skip cache lookup. ## Ref Fixes #139

xiaoju added 1 commit 2026-06-07 02:36:19 +00:00

fix: decouple session resume from isFirstVisit guard

CI / check (pull_request) Successful in 1m58s

Details

aaadab4445

When frontmatter validation fails, the step is never written to CAS, so
isFirstVisit remains true on the next run.  Both agent-claude-code and
agent-hermes gated session cache lookup behind !isFirstVisit, which
caused them to start a fresh session (and a new worktree) instead of
resuming the one that already has all the work done.

Changes:
- Remove the isFirstVisit guard from both adapters so they always check
  the session cache.
- When isFirstVisit + cache hit (frontmatter-only failure), send a
  minimal correction prompt via buildFrontmatterRetryPrompt() instead
  of re-sending the full initial prompt — the session already has full
  context, we just need the agent to re-output correctly formatted
  frontmatter.
- Add buildFrontmatterRetryPrompt to util-agent with tests.

Fixes #139

xiaoju force-pushed fix/139-session-resume-on-frontmatter-fail from 32bbea0f32 to aaadab4445

2026-06-07 02:36:19 +00:00

Compare

xiaomo approved these changes 2026-06-07 02:40:07 +00:00

xiaomo left a comment

LGTM ✅

Bug 分析准确： frontmatter 验证失败 → step 不写 CAS → isFirstVisit 永远 true → session cache 被跳过 → 上一轮所有工作白费。30 min + 1603 行代码的教训。

修复逻辑清晰：

去掉 isFirstVisit 对 session cache lookup 的守卫，改为始终检查 cache
isFirstVisit + cache hit = frontmatter retry，发 minimal prompt 让 agent 只重新输出格式
!isFirstVisit + cache hit = 正常 re-entry，走 continuation prompt
两个 adapter（claude-code / hermes）处理一致

buildFrontmatterRetryPrompt 设计合理：

"不需要重做任何工作，只输出正确的 frontmatter" — 简洁明确
带上 outputFormatInstruction 让 agent 知道正确格式
独立模块 + 3 个测试覆盖

hermes 的 PromptAttempt 扩展干净： 新增 frontmatterRetry 字段，useContinuation 和 frontmatterRetry 互斥逻辑正确（isFirstVisit 时 useContinuation: false, frontmatterRetry: true）。

可以合。

LGTM ✅ **Bug 分析准确：** frontmatter 验证失败 → step 不写 CAS → isFirstVisit 永远 true → session cache 被跳过 → 上一轮所有工作白费。30 min + 1603 行代码的教训。 **修复逻辑清晰：** - 去掉 `isFirstVisit` 对 session cache lookup 的守卫，改为始终检查 cache - `isFirstVisit + cache hit` = frontmatter retry，发 minimal prompt 让 agent 只重新输出格式 - `!isFirstVisit + cache hit` = 正常 re-entry，走 continuation prompt - 两个 adapter（claude-code / hermes）处理一致 **`buildFrontmatterRetryPrompt` 设计合理：** - "不需要重做任何工作，只输出正确的 frontmatter" — 简洁明确 - 带上 `outputFormatInstruction` 让 agent 知道正确格式 - 独立模块 + 3 个测试覆盖 **hermes 的 `PromptAttempt` 扩展干净：** 新增 `frontmatterRetry` 字段，`useContinuation` 和 `frontmatterRetry` 互斥逻辑正确（`isFirstVisit` 时 `useContinuation: false, frontmatterRetry: true`）。可以合。

xiaoju added 1 commit 2026-06-07 02:41:27 +00:00

docs: add efficiency guidelines to CLAUDE.md

CI / check (pull_request) Successful in 2m3s

Details

88c077d439

Three rules to reduce wasted Claude Code turns:
1. Don't comment on whether code is malware (trusted codebase)
2. Stop re-reading/re-verifying after tests pass
3. Don't rebuild/retest after adding a changeset (it's just markdown)

xiaomo merged commit 2e7e5f6ec4 into main

2026-06-07 02:43:37 +00:00

xiaomo deleted branch fix/139-session-resume-on-frontmatter-fail

2026-06-07 02:43:37 +00:00

xiaoju referenced this pull request

2026-06-07 03:04:05 +00:00

chore: add changeset for session resume fix (#139) #141

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: shazhou/united-workforce#140