docs: update bot pairing + UnifiedSessionStore docs for PR #1892 bug fixes

[MervinPraison]

Summary

PraisonAI PR #1892 was merged on 2026-06-12. It fixes two high-severity correctness bugs in features that are already documented in PraisonAIDocs. Two existing docs pages need to be updated (no new pages needed), and one page also has pre-existing merge-conflict markers that should be cleaned up while we're there.

This is a content update task — folder rules are respected (all edits land in docs/features/ and docs/cli/, no docs/concepts/ changes).

---

Source Of Truth (SDK)

Area	SDK file	Change
Pairing approval	praisonai/bots/_unknown_user.py	send_approval_dm(..., channel=channel_type, ...) — was previously passing the chat ID instead of the platform type.
Unified session store	praisonai/cli/session/unified.py	_acquire_exclusive_lock / _release_exclusive_lock now lock the entire file on Windows (lock_length = max(file_size, 1)); save() reloads-under-lock and merges concurrent messages; load() always reads disk-fresh.

Verified against PR diff (4 files, +21 / -13):

• src/praisonai/praisonai/bots/_unknown_user.py (1 line)
• src/praisonai/praisonai/cli/session/unified.py (12 lines — Windows full-file locking)
• src/praisonai/tests/integration/bots/test_pairing_owner_dm.py (asserts channel == "telegram")
• src/praisonai/tests/integration/bots/test_pairing_agent_e2e.py (asserts channel == "discord")

---

Files To Update (existing — do NOT create new pages)

1. docs/features/bot-unknown-user-pairing.mdx

The page already documents the inline-button Approve / Deny flow. It does not mention that older releases had a bug where tapping Approve looked successful but never actually paired the user. Users on a pinned older version will hit this and search the docs.

Required edits:

• Add an <Info> callout near the top (alongside the existing PR docs(cli): document praisonai memory list subcommand and --limit flag (v4.6.141) #1791 Gateway Info block) noting:
  • "Before PR docs: cover named-agent subagent delegation (mode: subagent + --subagents + agent_resolver) #1892, the inline Approve button on Telegram / Discord / Slack incorrectly stored the chat ID as channel_type in PairingStore. The approval succeeded in the UI but is_paired() returned False on subsequent messages — the requester stayed blocked. Upgrade to pick up the fix."
• In the How It Works sequence diagram description, make explicit that the value embedded in the callback's channel field is the platform type (telegram / discord / slack), not the chat ID. Today the prose is silent on this.
• In Platform-specific UI accordions, the callback-data format already reads pair:{action}:{channel}:{user_id}:{code}:{sig} — add a one-line note clarifying that {channel} here is the platform identifier, since this is what PairingStore.is_paired() checks against.

Do not change the Quick Start code — the public API (unknown_user_policy="pair", owner_user_id="...") is unchanged. Bug was internal.

---

2. docs/features/session-persistence.mdx

Two issues on this page:

a) Pre-existing merge-conflict markers in the source. The current file on main contains live <<<<<<< HEAD / ======= / >>>>>>> origin/main markers around the "Multi-Process Safety" section, plus duplicated mermaid diagrams and an API Reference table that lists add_message twice. This is breaking the rendered page. Resolve in favour of the origin/main side (the version that describes reload-under-lock, fresh reads, and the praisonai session UnifiedSessionStore Note) and delete the duplicates. Keep exactly one of each of the three sequence diagrams.

b) Add the PR #1892 fix to the existing UnifiedSessionStore Note. The current Note says both stores "use the same cross-platform locking strategy as of PR #1837". Extend it (or add a follow-up Info) saying:

Updated in PR #1892: UnifiedSessionStore.save() now reloads under lock and merges concurrent writes (previously it overwrote with the in-process cache, dropping messages from a second process that wrote between load and save). UnifiedSessionStore.load() always reads from disk. The Windows code path now locks the entire file (max(file_size, 1) bytes via msvcrt.locking) instead of only the first byte, matching the Unix fcntl.flock semantics.

Cross-link to /docs/cli/session#cross-platform-support (already present).

---

3. docs/cli/session.mdx

The Cross-Platform Support section already documents msvcrt.locking on Windows and links to PR #1837. Update the same section for PR #1892:

• In the Windows row of the platform table, change the description from a generic mention of msvcrt.locking() to: "Whole-file lock (max(file_size, 1) bytes) — matches Unix fcntl.flock semantics".
• Add a new short subsection (or extend the Note) titled something like "Concurrent message safety" stating:
  • The CLI's UnifiedSessionStore is safe under two processes writing the same session file (e.g. praisonai --interactive while a TUI is open, or two praisonai shells sharing the same session).
  • Each save() reloads, merges new messages, deduplicates, and writes under the cross-platform lock.
  • Cross-link the end-paragraph PR docs: add pages for two new SDK evaluators — ContextEvaluator + HarnessEvaluator #1837 reference to also cite PR docs: cover named-agent subagent delegation (mode: subagent + --subagents + agent_resolver) #1892.

No changes to Commands, Use Cases, Auto-Save Sessions, History in Context, Workflow Checkpoints, or Storage Backend Options — those are unaffected.

---

What NOT To Do

• Do not create a new "Bot pairing channel_type fix" page or a new "UnifiedSessionStore" page. The features are already documented; only the existing pages need touch-ups.
• Do not edit anything under docs/concepts/ (docs/concepts/session-management.mdx references session CLI but does not need changes — it's not the SDK truth for these stores).
• Do not edit docs/js/ or docs/rust/ — these are auto-generated.
• Do not modify docs.json — these are existing pages, no sidebar changes.
• Do not change public Python API signatures in code examples — BotConfig, Agent(memory={"session_id": ...}), praisonai session start/list/resume all still work the same way. Bug fixes only.

---

Suggested Structure For The Pairing Info Callout

For the user-facing Info on bot-unknown-user-pairing.mdx, prefer a positive framing (what works now) over a defect-list, in keeping with the project style. Example:

<Info>
**Inline approvals (PR #1892)**: When the owner taps **Approve** on the Telegram / Discord / Slack DM, the requester is paired immediately on the platform type (`telegram` / `discord` / `slack`) so all of their later messages flow straight through. If you saw "approve looked successful but the next message was still blocked" on an older release, upgrade to pick up this fix.
</Info>

---

Suggested Mermaid Addition (optional)

If a small visual helps on session-persistence.mdx, a single sequence diagram (replacing the duplicated ones currently in the file) for two CLI processes writing the same session:

sequenceDiagram
    participant CLI_A as Process A (save)
    participant Disk as session-1.json
    participant CLI_B as Process B (save)

    CLI_A->>Disk: FileLock acquire
    CLI_A->>Disk: reload, merge ["hi from A"]
    CLI_A->>Disk: atomic write
    CLI_A->>Disk: FileLock release
    CLI_B->>Disk: FileLock acquire
    CLI_B->>Disk: reload (sees "hi from A"), merge ["hi from B"]
    CLI_B->>Disk: atomic write
    CLI_B->>Disk: FileLock release
    Note over Disk: Final file contains both messages

Loading

Use the standard color scheme from AGENTS.md §3.1 (#8B0000 for processes, #189AB4 for the file).

---

Acceptance Checklist (for the implementing agent)

• docs/features/bot-unknown-user-pairing.mdx: Info callout about PR docs: cover named-agent subagent delegation (mode: subagent + --subagents + agent_resolver) #1892 added; sequence-diagram prose clarifies channel = platform type; HMAC callback-format note clarifies {channel} field.
• docs/features/session-persistence.mdx: All <<<<<<< / ======= / >>>>>>> conflict markers removed; duplicate diagrams and duplicate API Reference rows removed; UnifiedSessionStore Note extended with PR docs: cover named-agent subagent delegation (mode: subagent + --subagents + agent_resolver) #1892 details (reload-under-lock, dedup, Windows full-file lock).
• docs/cli/session.mdx: Windows row of cross-platform table updated to mention whole-file lock; concurrent-write safety paragraph added; PR docs: cover named-agent subagent delegation (mode: subagent + --subagents + agent_resolver) #1892 cross-link added next to existing PR docs: add pages for two new SDK evaluators — ContextEvaluator + HarnessEvaluator #1837 reference.
• All edited pages still validate as MDX (no broken JSX, frontmatter intact).
• Color scheme on any new mermaid diagrams matches AGENTS.md §3.1.
• No new files created; no docs/concepts/ changes; no docs.json edits.
• PR opened against the docs repo and linked back to this issue and to PraisonAI PR docs: cover named-agent subagent delegation (mode: subagent + --subagents + agent_resolver) #1892.

---

Source PR: MervinPraison/PraisonAI#1892
Related earlier PRs already cited in docs: #1709, #1724, #1745, #1781, #1791, #1837

[MervinPraison]

🤖 Auto-triaging with Claude. Analyzing issue and implementing a fix...

Claude will:

1. Classify this issue
2. Search codebase for root cause
3. Implement a minimal fix following AGENTS.md
4. Create a PR with the changes

[MervinPraison]

Claude finished @MervinPraison's task —— View job • claude/issue-542-20260612-1750 • [Create PR ➔](https://github.com/MervinPraison/PraisonAIDocs/compare/main...claude/issue-542-20260612-1750?quick_pull=1&title=Issue%20%23542%3A%20Changes%20from%20Claude&body=This%20PR%20addresses%20issue%20%23542%0A%0AGenerated%20with%20%5BClaude%20Code%5D(https%3A%2F%2Fclaude.ai%2Fcode)

---

Documentation Update for PR #1892 Bug Fixes ✅

Successfully implemented documentation updates for bot pairing and UnifiedSessionStore bug fixes from PraisonAI PR #1892.

Completed Tasks:

• Setup git identity and read AGENTS.md documentation standards
• Examine current state of target documentation files
• Update docs/features/bot-unknown-user-pairing.mdx with PR docs: cover named-agent subagent delegation (mode: subagent + --subagents + agent_resolver) #1892 Info callout
• Fix merge conflicts in docs/features/session-persistence.mdx and add PR docs: cover named-agent subagent delegation (mode: subagent + --subagents + agent_resolver) #1892 details
• Update docs/cli/session.mdx with cross-platform locking improvements
• Verify MDX validity and commit changes
• Create pull request

Summary of Changes

docs/features/bot-unknown-user-pairing.mdx

• Added Info callout explaining the PR docs: cover named-agent subagent delegation (mode: subagent + --subagents + agent_resolver) #1892 fix for inline approval bug
• Clarified that callback {channel} field contains platform type (telegram/discord/slack), not chat ID
• Updated sequence diagram and platform-specific UI sections

docs/features/session-persistence.mdx

• Resolved all merge conflict markers, keeping origin/main version
• Removed duplicated mermaid diagrams and API reference entries
• Enhanced UnifiedSessionStore Note with PR docs: cover named-agent subagent delegation (mode: subagent + --subagents + agent_resolver) #1892 details about reload-under-lock and Windows whole-file locking

docs/cli/session.mdx

• Updated cross-platform table to specify Windows whole-file locking semantics
• Added "Concurrent Message Safety" subsection
• Updated PR references to include both docs: add pages for two new SDK evaluators — ContextEvaluator + HarnessEvaluator #1837 and docs: cover named-agent subagent delegation (mode: subagent + --subagents + agent_resolver) #1892

Pull Request Created

View PR #550

---