Summary

Describe the problem and fix in 2-5 bullets:

• Problem: sessions_list could compute transcriptPath from a non-concrete sessions.list.path (for example "(multiple)", missing, non-string, relative, or template values), causing transcript paths to resolve under process.cwd() (often the workspace) instead of an agent sessions directory.
• Why it matters: Users see incorrect transcriptPath values and missing transcripts even though the actual .jsonl files exist under the agent sessions directory.
• What changed: sessions_list now resolves transcript paths via resolveSessionFilePathOptions(...) + resolveSessionFilePath(...), and only uses the gateway path when it can be made concrete. Supported template paths ({agentId}, ~) are resolved per session agent via resolveStorePath(...); non-concrete values fall back to agent defaults.
• What did NOT change (scope boundary): No changes to transcript storage format, gateway payload contract, session store layout, or visibility/auth policy logic. This only affects how sessions_list computes and reports transcriptPath.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• 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 transcriptPath in session metadata points to workspace instead of agent sessions directory #20320
• Related: N/A

User-visible / Behavior Changes

• sessions_list now returns correct transcriptPath values even when gateway sessions.list.path is:
  • "(multiple)"
  • missing
  • non-string
  • relative
  • absolute template path ({agentId} / ~)
• Returned paths now resolve to agent sessions directories (or correctly resolved custom template roots), rather than workspace-derived paths.

Security Impact (required)

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

Repro + Verification

Environment

• OS: Debian GNU/Linux 12 (bookworm), kernel 6.1.x
• Runtime/container: OpenClaw 2026.02.22-2 installed through the "One-liner"
• Model/provider: openai-codex/gpt-5.3-codex (Codex 5.3) for assistant/subagent work
• Integration/channel (if any): sessions tooling (sessions_list)
• Relevant config (redacted):
  • default session.store unset (gateway returns sessions.list.path as "(multiple)")
  • transcripts stored under ~/.openclaw/agents/main/sessions/

Steps

1. On a running gateway instance where sessions.list.path is "(multiple)", open the chat
2. Send this exact prompt to OpenClaw:

   Please spawn a subagent with task "reply with exactly: ok". After it starts, check sessions_list and reply with only:
   - newest subagent sessionId
   - transcriptPath reported by sessions_list
   - whether that transcriptPath exists
   

Expected (after deploying this PR locally)

- newest subagent sessionId: a4e755df-27e5-4c2b-9093-f037009fd467
- transcriptPath reported by sessions_list: ~/.openclaw/agents/main/sessions/a4e755df-27e5-4c2b-9093-f037009fd467.jsonl
- transcriptPath exists: yes

(sessionId can vary)

Actual (deployed instance with 2026.02.22-2)

- newest subagent sessionId: 81bd98b9-1336-4a73-96d1-6ce5447baa47
- transcriptPath reported by sessions_list: ~/.openclaw/workspace/81bd98b9-1336-4a73-96d1-6ce5447baa47.jsonl
- whether that transcriptPath exists: no

(sessionId can vary)

Evidence

Attach at least one:

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

pnpm vitest src/agents/tools/sessions.test.ts src/config/sessions.test.ts

✓ src/config/sessions.test.ts (35 tests)
✓ src/agents/tools/sessions.test.ts (14 tests)

Test Files  2 passed (2)
Tests       49 passed (49)
Duration    2.78s

✓ src/config/sessions.test.ts (35 tests)
❯ src/agents/tools/sessions.test.ts (14 tests | 5 failed)

Failed tests:
- resolves cross-agent transcript paths from agent defaults when gateway store path is relative
- resolves transcriptPath even when sessions.list does not return a store path
- falls back to agent defaults when gateway path is non-string
- falls back to agent defaults when gateway path is '(multiple)'
- resolves absolute {agentId} template paths per session agent

Test Files  1 failed | 1 passed (2)
Tests       5 failed | 44 passed (49)
Duration    2.65s

Notes:

• Added regression tests for "(multiple)", missing/non-string/relative path, and {agentId} template resolution.
• Verified failure by temporarily reverting the fix locally (tests fail), then restoring (tests pass).

Human Verification (required)

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

• Verified scenarios:
  • Reproduced transcriptPath in session metadata points to workspace instead of agent sessions directory #20320 on a live gateway instance (2026.02.22-2) using real session IDs where sessions_list returned a workspace path that did not exist, while the agent sessions transcript existed (see "Actual" example from above).
  • After deploying and restarting gateway with this fix, confirmed sessions_list returns canonical agent sessions transcript paths that exist on disk for existing sessions and for a freshly spawned session/subagent (see "Expected" example from above).
• Edge cases checked: sessions.list.path == "(multiple)" in a live gateway instance; other variants (missing/non-string/relative/template) covered by unit tests.
• What you did not verify:
  • Manual Windows runtime behavior (path semantics), other situations that could trigger this behavior, like multi-agent setups.

Compatibility / Migration

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

Failure Recovery (if this breaks)

• How to disable/revert this change quickly:
  • Revert this commit to restore prior sessions_list behavior.
• Files/config to restore:
  • src/agents/tools/sessions-list-tool.ts
  • src/agents/tools/sessions.test.ts
  • src/config/sessions.test.ts
• Known bad symptoms reviewers should watch for:
  • sessions_list.transcriptPath points under the workspace directory
  • transcriptPath is undefined when sessions.list.path is absent
  • incorrect transcript paths under templated store setups

Risks and Mitigations

• Risk: Unusual gateway path values could still be misinterpreted as concrete, leading to incorrect transcript roots.
  • Mitigation: Non-concrete values are ignored with a safe fallback; supported templates ({agentId}, ~) are explicitly resolved via resolveStorePath(..., { agentId }); targeted regression tests cover observed variants ("(multiple)", missing/non-string/relative/template paths).

Greptile Summary

Fixed sessions_list to compute correct transcriptPath values when the gateway returns non-concrete sessions.list.path values (like "(multiple)", missing, non-string, or relative paths). Previously, these edge cases caused transcript paths to incorrectly resolve under process.cwd() instead of the agent sessions directory.

• The fix now resolves transcript paths via resolveSessionFilePathOptions(...) and resolveSessionFilePath(...), and supports template paths like {agentId} and ~ through resolveStorePath(...)
• Five new regression tests cover all edge cases: relative paths, missing paths, non-string paths, "(multiple)", and {agentId} template paths
• Two additional unit tests validate resolveSessionFilePathOptions behavior with explicit agentId and store paths
• No changes to storage format, gateway contracts, or visibility policies

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The fix is well-scoped, backward compatible, and addresses a clear bug with comprehensive test coverage. The implementation correctly handles all edge cases (missing/relative/non-string/template paths) and falls back to agent defaults. All existing usages of resolveSessionFilePathOptions remain compatible. The PR includes targeted regression tests that demonstrate the failure before the fix and success after.
• No files require special attention

_{Last reviewed commit: dda7f0c}

_{(2/5) Greptile learns from your feedback when you react with thumbs up/down!}