Problem

When a threaded conversation has already been split across reset transcripts, chat.history and the sessions_history tool only read the currently active transcript. The session store can already retain the family through usageFamilySessionIds, but history readers do not use that chain and do not discover archived *.jsonl.reset.<timestamp> topic transcripts.

That means an agent/tool can be looking at the correct logical Telegram/Slack/Discord thread and still miss earlier turns after session rollover.

Fix

Add an opt-in family history path:

• chat.history accepts includeFamily: true.
• sessions_history accepts includeFamily.
• Gateway and embedded chat.history now share the bounded/header-checked reset archive resolver instead of using separate prefix scans.
• The shared resolver can include owned topic-suffixed reset archives such as <sessionId>-topic-456.jsonl.reset.<timestamp> only when the archive header matches the requested session id.
• Same-prefix colliding topic archives and headerless topic archives are ignored.
• Family read targets are capped before transcript reads, and normal chat.history behavior remains opt-in: UI startup does not load ancestor history.

Validation

Current head: 1aa4e9cbb94f6841803bd55559aa0ea6de17dc67.

• CI=true node scripts/run-vitest.mjs run src/gateway/server.chat.gateway-server-chat-b.test.ts src/agents/tools/embedded-gateway-stub.test.ts
  • gateway shard: 84 tests passed
  • agents shard: 11 tests passed
• CI=true node scripts/run-vitest.mjs run src/agents/openclaw-tools.sessions.test.ts
  • 36 tests passed
• CI=true node --import tsx scripts/generate-prompt-snapshots.ts --check
  • Prompt snapshots are current (7 files).
• CI=true node scripts/run-tsgo.mjs -p test/tsconfig/tsconfig.core.test.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/core-test.tsbuildinfo
  • passed
• CI=true node scripts/run-tsgo.mjs -p test/tsconfig/tsconfig.extensions.test.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/extensions-test.tsbuildinfo
  • passed
• git diff --check
  • passed, no output

Real Behavior Proof

• Behavior or issue addressed: A logical thread whose active session has usageFamilySessionIds should be able to fetch earlier reset transcript turns when a caller explicitly requests family history, including owned topic-suffixed reset archives, without reading colliding or headerless topic archives. The current active transcript must also be preserved when a retained reset family has more entries than the bounded 32 read targets.
• Real environment tested: Local OpenClaw checkout on this PR branch at current head a12e1bbcf0, using temporary on-disk session directories, the real Gateway chat.history RPC integration harness, embedded-mode chat.history, and the same reset archive filename/header patterns that OpenClaw creates for topic transcripts.
• Exact steps or command run after this patch:
  1. Created temporary session directories and session-store entries with usageFamilySessionIds linking an ancestor session and the current session.
  2. Wrote an owned plain ancestor reset archive and an owned topic-suffixed ancestor archive with matching type: "session" headers.
  3. Wrote newer same-prefix colliding and headerless topic reset archives in the same sessions directory.
  4. Invoked the real Gateway chat.history RPC path with and without includeFamily: true.
  5. Created a second Gateway/RPC case with 40 ancestor session ids before the current id in usageFamilySessionIds.
  6. Invoked embedded-mode chat.history(includeFamily) through the sessions tool stub, including the same >32-family-target cap case.
• Evidence after fix: Terminal capture from current head:

  $ CI=true node scripts/run-vitest.mjs run src/gateway/server.chat.gateway-server-chat-b.test.ts src/agents/tools/embedded-gateway-stub.test.ts
  Test Files  2 passed (2)
  Tests  84 passed (84)
  Test Files  1 passed (1)
  Tests  11 passed (11)
  [test] passed 2 Vitest shards in 44.69s
  
  $ CI=true node scripts/run-vitest.mjs run src/agents/openclaw-tools.sessions.test.ts
  Test Files  1 passed (1)
  Tests  36 passed (36)
  [test] passed 1 Vitest shard in 30.16s
  
  $ CI=true node --import tsx scripts/generate-prompt-snapshots.ts --check
  Prompt snapshots are current (7 files).
  
  $ CI=true node scripts/run-tsgo.mjs -p test/tsconfig/tsconfig.core.test.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/core-test.tsbuildinfo
  # passed
  
  $ CI=true node scripts/run-tsgo.mjs -p test/tsconfig/tsconfig.extensions.test.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/extensions-test.tsbuildinfo
  # passed
  
  $ git diff --check
  # no output
  

• Observed result after fix: Default chat.history excludes ancestor reset archive content, while chat.history(includeFamily) includes the owned plain ancestor archive, includes the owned topic-suffixed ancestor archive, includes current-session content, and rejects the colliding/headerless topic reset archives. In the >32-target Gateway/RPC regression, chat.history(includeFamily) contains current survives family target cap, contains early ancestor content, and does not read the ancestor entries beyond the target cap. Embedded chat.history(includeFamily) now reads the current active transcript first, then current archives, then ancestor archives/active transcripts; its >32-target regression also keeps the current transcript and drops over-cap ancestors.
• What was not tested: I did not run a live Telegram topic end-to-end, and this PR does not add prompt-level carryover summaries or automatic prompt injection. It only adds explicit family history retrieval for gateway/tool callers.

Current head addendum: 8c164eeaa3

ClawSweeper's a12e1bbcf0 review finding is addressed in this head:

• Family target selection still reserves the current active transcript before the 32-target cap is reached.
• Family output order is now ancestor transcripts first, then current-session reset archives, then the current active transcript, so final limit trimming keeps the active session tail.
• Embedded chat.history(includeFamily) mirrors the Gateway order.
• Added over-limit regressions proving includeFamily with a small final limit keeps current active history.

Standalone redacted embedded chat.history smoke from current head 8c164eeaa3545a9f05dc507908f9dec0236d2c47:

$ node --import tsx --input-type=module <<'TS'
# Creates a temporary session.store, one ancestor transcript, and one current transcript;
# calls createEmbeddedCallGateway().chat.history with default, includeFamily, and includeFamily+limit.
TS
{
  "default": [
    "redacted current context"
  ],
  "includeFamily": [
    "redacted ancestor context",
    "redacted current context"
  ],
  "includeFamilyLimit1": [
    "redacted current context"
  ]
}

Validation on 8c164eeaa3545a9f05dc507908f9dec0236d2c47:

$ CI=true node scripts/run-vitest.mjs run src/gateway/server.chat.gateway-server-chat-b.test.ts src/agents/tools/embedded-gateway-stub.test.ts
Test Files  2 passed (2)
Tests  84 passed (84)
Test Files  1 passed (1)
Tests  11 passed (11)

$ CI=true node scripts/run-vitest.mjs run src/gateway/server.chat.gateway-server-chat-b.test.ts -t 'chat.history preserves current transcript when family targets hit the cap'
Test Files  1 passed (1)
Tests  1 passed | 41 skipped (42)

$ CI=true node scripts/run-vitest.mjs run src/agents/tools/embedded-gateway-stub.test.ts -t 'keeps embedded current chat history when family targets hit the cap'
Test Files  2 passed (2)
Tests  2 passed | 20 skipped (22)

$ CI=true node --import tsx scripts/generate-prompt-snapshots.ts --check
Prompt snapshots are current (7 files).

$ CI=true node scripts/run-tsgo.mjs -p test/tsconfig/tsconfig.core.test.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/core-test.tsbuildinfo
# passed

$ CI=true node scripts/run-tsgo.mjs -p test/tsconfig/tsconfig.extensions.test.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/extensions-test.tsbuildinfo
# passed

$ git diff --check
# no output

Current head addendum: 0d37b42702

Maintainer readiness note addressed on current head 0d37b42702688ac9c4bf0edf949f99b00f096cf6:

• Removed the resetAncestors sessions_history alias so the model-facing selector is only includeFamily.
• Kept Gateway chat.history and sessions_history aligned on the single includeFamily flag.
• The embedded history macOS path-normalization failure was already addressed by dropping the redundant path assertion in 6050d0bbfb.
• Exact-head CI has restarted for 0d37b42702; at refresh time there were no failed checks and the remaining required/security checks were still running.

Validation on 0d37b42702688ac9c4bf0edf949f99b00f096cf6:

$ CI=true node scripts/run-vitest.mjs run src/agents/openclaw-tools.sessions.test.ts
Test Files  1 passed (1)
Tests  36 passed (36)

$ CI=true node scripts/run-vitest.mjs run src/agents/tools/embedded-gateway-stub.test.ts -t 'reads embedded chat history from reset ancestor transcripts when includeFamily is set|keeps embedded current chat history when family targets hit the cap'
Test Files  2 passed (2)
Tests  4 passed | 18 skipped (22)

$ CI=true node scripts/run-vitest.mjs run src/gateway/server.chat.gateway-server-chat-b.test.ts -t 'chat.history includes owned topic reset archives when includeFamily is set|chat.history preserves current transcript when family targets hit the cap'
Test Files  1 passed (1)
Tests  1 passed | 41 skipped (42)

$ git diff --check
# no output

Current head addendum: 1aa4e9cbb9

ClawSweeper's generated-snapshot blocker is addressed on current head 1aa4e9cbb94f6841803bd55559aa0ea6de17dc67:

• Refreshed the Codex dynamic-tool prompt snapshots after removing resetAncestors.
• resetAncestors no longer appears in source, docs, protocol/tool snapshots, or prompt snapshot counters.
• Kept includeFamily as the only model-facing family-history selector.

Validation on 1aa4e9cbb94f6841803bd55559aa0ea6de17dc67:

$ CI=true pnpm prompt:snapshots:gen
Wrote 7 prompt snapshot files.

$ CI=true node --import tsx scripts/generate-prompt-snapshots.ts --check
Prompt snapshots are current (7 files).

$ CI=true node scripts/run-vitest.mjs run src/agents/openclaw-tools.sessions.test.ts
Test Files  1 passed (1)
Tests  36 passed (36)

$ git diff --check
# no output

Current head addendum: 64281c2720

ClawSweeper's latest exact-head proof and offset-semantics request is addressed on 64281c2720dce8a9dbe35bf2db7c37f5c64f8f6e.

The supported contract is now explicit:

• default chat.history / sessions_history reads active history
• includeFamily: true reads the newest bounded reset-family tail
• offset reads active-history pages
• includeFamily: true with offset is rejected at protocol/tool/Gateway/embedded validation instead of silently returning active-only pages

Exact-head protocol proof:

$ git rev-parse HEAD
64281c2720dce8a9dbe35bf2db7c37f5c64f8f6e

$ node --import tsx --input-type=module <<'TS'
# Imports current-branch packages/gateway-protocol/src/index.ts
# Validates default history, includeFamily tail, offset page, and includeFamily+offset.
TS
{
  "head": "64281c2720dce8a9dbe35bf2db7c37f5c64f8f6e",
  "defaultHistoryValid": true,
  "includeFamilyHistoryValid": true,
  "offsetPageValid": true,
  "includeFamilyOffsetValid": false,
  "includeFamilyOffsetErrors": [
    "must not be valid"
  ]
}

Exact-head validation:

$ CI=true node scripts/run-vitest.mjs run packages/gateway-protocol/src/index.test.ts
Test Files  1 passed (1)
Tests  45 passed (45)

$ CI=true node scripts/run-vitest.mjs run src/agents/tools/sessions-history-tool.test.ts src/agents/openclaw-tools.sessions.test.ts -t 'includeFamily|offset'
Test Files  4 passed (4)
Tests  12 passed | 84 skipped (96)

$ CI=true node scripts/run-vitest.mjs run src/agents/tools/embedded-gateway-stub.test.ts src/gateway/server.chat.gateway-server-chat-b.test.ts -t 'family|includeFamily|subagent_announce|sessionStartedAt|offset|cap'
Test Files  3 passed (3)
Tests  30 passed | 58 skipped (88)

$ pnpm lint --threads=8
# passed

$ CI=true pnpm check:test-types
# passed

$ CI=true node --import tsx scripts/generate-prompt-snapshots.ts --check
Prompt snapshots are current (7 files).

$ git diff --check
# no output

Current head addendum: 578af36109

Follow-up head 578af36109ebdd666d0159fc5287cdfda69d9ea1 keeps the explicit includeFamily + offset rejection while preserving generated protocol compatibility.

Important correction to the previous addendum: protocol schema generation currently needs ChatHistoryParams to remain a simple generated model, so the public schema still describes the fields. The unsupported combination is rejected consistently at the executable request boundaries instead of silently returning active-only pages:

• sessions_history tool rejects before calling chat.history
• embedded chat.history rejects before reading session files
• Gateway chat.history rejects with includeFamily cannot be combined with offset
• docs state that family history is available only through the newest bounded tail view

Exact-head validation:

$ git rev-parse HEAD
578af36109ebdd666d0159fc5287cdfda69d9ea1

$ pnpm protocol:check
# passed; generated protocol schema and Swift models are current

$ CI=true node scripts/run-vitest.mjs run packages/gateway-protocol/src/index.test.ts
Test Files  1 passed (1)
Tests  45 passed (45)

$ CI=true node scripts/run-vitest.mjs run src/agents/tools/sessions-history-tool.test.ts src/agents/openclaw-tools.sessions.test.ts -t 'includeFamily|offset'
Test Files  4 passed (4)
Tests  12 passed | 84 skipped (96)

$ CI=true node scripts/run-vitest.mjs run src/agents/tools/embedded-gateway-stub.test.ts src/gateway/server.chat.gateway-server-chat-b.test.ts -t 'family|includeFamily|subagent_announce|sessionStartedAt|offset|cap'
Test Files  3 passed (3)
Tests  30 passed | 58 skipped (88)

$ git diff --check
# no output

The broader exact-head validation from 64281c2720 remains applicable for lint, test-types, and prompt snapshots; this head only restores generated protocol compatibility while keeping runtime rejection behavior.

Current head addendum: `99106083df`

ClawSweeper's latest review items are addressed on current head `99106083dfc91bd188d2b4abd2d5aced2c7981ae`:

• Family-history target capping now keeps the newest bounded ancestor tail instead of the oldest ancestors, while reserving current-session slots.
• Gateway and embedded `chat.history(includeFamily)` both keep the current active transcript after family target capping.
• The executable protocol validator now rejects `includeFamily: true` with `offset` while keeping `ChatHistoryParamsSchema` generator-compatible for protocol schema and Swift model generation.

Exact-head validation:

```text
$ git rev-parse HEAD
9910608

$ CI=true node scripts/run-vitest.mjs run packages/gateway-protocol/src/index.test.ts
Test Files 1 passed (1)
Tests 45 passed (45)

$ CI=true node scripts/run-vitest.mjs run src/agents/tools/sessions-history-tool.test.ts src/agents/openclaw-tools.sessions.test.ts -t 'includeFamily|offset'
Test Files 4 passed (4)
Tests 12 passed | 84 skipped (96)

$ CI=true node scripts/run-vitest.mjs run src/agents/tools/embedded-gateway-stub.test.ts src/gateway/server.chat.gateway-server-chat-b.test.ts -t 'family|includeFamily|subagent_announce|sessionStartedAt|offset|cap'
Test Files 3 passed (3)
Tests 30 passed | 58 skipped (88)

$ pnpm protocol:check

passed; generated protocol schema and Swift models are current

$ pnpm lint --threads=8

passed

$ CI=true pnpm check:test-types

passed

$ git diff --check

no output

```

Current head addendum: e9b75be554

Current head e9b75be554c409dbf49769417bd6ca5b3b2b7b30 keeps the runtime family-history behavior from 99106083df and only adds the latest origin/main merge, a docs note for sessions_history(includeFamily), and the generated docs map refresh.

Compatibility / migration proof for the persistent-state surfaces ClawSweeper flagged:

• No existing transcript, session-store, proxy-capture, or serialized session-history records are rewritten or migrated by this PR.
• The new includeFamily selector is opt-in; omitted or false keeps the existing active-transcript-only behavior for chat.history and sessions_history.
• Reset-family archive discovery is bounded and header-checked before reading topic-suffixed reset archives, so colliding/headerless archives are ignored.
• includeFamily: true with offset is rejected at the executable Gateway/embedded/tool validation boundaries instead of changing existing offset pagination semantics.
• CI on exact head e9b75be554c4 is green: watchdog saw 105 checks, 94 evaluated required/relevant checks, 0 failed, 0 running; GitHub check runs include successful Real behavior proof, docs, lint, test-types, protocol/bundled checks, gateway/channel/agent critical quality, and security-high shards.