PR #77772: fix(gateway): rotate reset transcript paths

• Repository: openclaw/openclaw
• Author: ddupg
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/77772

Description (problem / solution / changelog)

Summary

• Problem: TUI /reset created a new logical session but continued reusing the previous generated transcript path in some cases.
• Why it matters: The active transcript filename could appear to belong to an old session, making session files, reset archives, and trajectory-related artifacts harder to reason about.
• What changed: Reset now rotates generated transcript paths to the new session id, while preserving explicitly custom transcript paths.
• What did NOT change (scope boundary): This does not add migration or automatic repair for already-stale historical session entries created by older behavior.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #77770
• Related #
• This PR fixes a bug or regression

Real behavior proof (required for external PRs)

External contributors must show after-fix evidence from a real OpenClaw setup. Unit tests, mocks, lint, typechecks, snapshots, and CI are supplemental only.

• Behavior or issue addressed: TUI /reset should create a fresh session whose generated transcript path is based on the new session id.
• Real environment tested: Local macOS development checkout, Gateway mode TUI.
• Exact steps or command run after this patch:
  1. Start the Gateway with pnpm openclaw gateway run.
  2. Start the TUI with pnpm openclaw tui.
  3. Send a normal message.
  4. Run /reset.
  5. Inspect the agent sessions directory.
• Evidence after fix: In a clean session state, /reset produced a new active transcript named after the new session id, while the old transcript was archived as .jsonl.reset.<timestamp>.
• Observed result after fix: The new active transcript path changed from <old-session-id>.jsonl to <new-session-id>.jsonl.
• What was not tested: Automatic repair of already-stale historical session entries where sessionFile had already diverged from the current logical sessionId.
• Before evidence: Existing affected state showed reset archive files and the active transcript sharing the same stale basename, for example <old-session-id>.jsonl.reset.<timestamp> and <old-session-id>.jsonl.

Root Cause (if applicable)

• Root cause: The reset path generated a fresh logical sessionId, but passed the previous sessionFile back into session file resolution. For generated transcript paths, that preserved the old filename instead of deriving a path from the new session id.
• Missing detection / guardrail: Tests covered reset metadata behavior but did not assert that generated transcript filenames rotate with the new session id.
• Contributing context (if known): Earlier reset behavior appears to have changed over time between always generating fresh transcript paths and preserving explicit transcript paths. The implementation did not distinguish generated transcript paths from custom explicit paths.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/gateway/server.sessions.reset-models.test.ts, plus shared helper coverage in src/config/sessions/session-file-rotation.test.ts.
• Scenario the test should lock in: Given a session entry with a generated transcript path matching the old session id, sessions.reset creates a new session id and stores a transcript path using the new session id.
• Why this is the smallest reliable guardrail: The bug lives at the Gateway reset/session-store boundary, so a focused sessions.reset test verifies the actual persisted entry without requiring a full TUI run.
• Existing test that already covers this (if any): None before this change.
• If no new test is added, why not: N/A.

User-visible / Behavior Changes

TUI /reset now uses a new generated transcript filename for the new session instead of continuing to write to the old generated filename.

Diagram (if applicable)

Before:
/reset -> new sessionId -> old generated sessionFile basename reused

After:
/reset -> new sessionId -> generated sessionFile basename rewritten -> new transcript path

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: macOS
• Runtime/container: Local Node/pnpm development checkout
• Model/provider: Not provider-specific
• Integration/channel (if any): TUI via Gateway WebSocket
• Relevant config (redacted): Default main agent session store under the local OpenClaw state directory

Steps

1. Start the Gateway with pnpm openclaw gateway run.
2. Start the TUI with pnpm openclaw tui.
3. Send a normal message, then run /reset.
4. Inspect the active transcript file in the agent sessions directory.

Expected

• The old transcript is archived as <old-session-id>.jsonl.reset.<timestamp>.
• The new active transcript is written to <new-session-id>.jsonl.

Actual

• Before this fix, the new active transcript could continue using the old generated filename.
• After this fix, clean session state resets use a new transcript filename based on the new session id.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: Clean TUI/Gateway reset flow creates a new session and rotates the generated transcript filename.
• Edge cases checked: Generated default transcript paths, relative generated transcript paths, and custom subdirectory transcript paths.
• What you did not verify: Automatic migration or repair of historical session entries already polluted by older reset behavior.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: Custom transcript paths could be accidentally rewritten.
  • Mitigation: The rewrite only applies to recognized generated transcript filename patterns, and custom subdirectory transcript paths are covered by tests.

Changed files

• src/auto-reply/reply/session-updates.ts (modified, +1/-32)
• src/config/sessions.ts (modified, +1/-0)
• src/config/sessions/session-file-rotation.test.ts (added, +97/-0)
• src/config/sessions/session-file-rotation.ts (added, +44/-0)
• src/gateway/server.sessions.reset-models.test.ts (modified, +131/-0)
• src/gateway/session-reset-service.ts (modified, +29/-1)