AgentSkillsCN

warmup-sid-separator

当您需要在 `sse_lines.jsonl` 中区分 Claude Code 的预热 SID 与真实会话 SID（尤其是在 `--resume` 相关操作中），或需要实现可靠的 pid→sid 映射时，可使用此技能。

SKILL.md
--- frontmatter
name: warmup-sid-separator
description: This skill should be used when separating Claude Code warmup SIDs from real session SIDs in `sse_lines.jsonl` (especially around `--resume`), or when implementing reliable pid→sid mapping.

Warmup SID Separator

[Created by Codex: 019b74ad-1ac6-7261-962f-e3b9cd21ccb5]

Overview

Distinguish the ephemeral SID emitted by claude.warmup from the “real” session SID used by claude.user_prompt / claude.session_start. Use this to avoid false “resume forked to a new SID” conclusions when tailing sse_lines.jsonl.

When To Use

  • •Debug “resume created a new SID” reports where the first observed SID differs from the resumed SID.
  • •Implement pid→sid attribution for dashboards, tail bridges, or agent managers consuming ~/centralized-logs/claude/sse_lines.jsonl.
  • •Confirm whether a mismatch is a true fork (--fork-session) vs a warmup/telemetry artifact.

Rules (Separate Warmup SID vs Real SID)

To classify SIDs for a single pid:

  1. •Treat claude.warmup as pre-session telemetry; record its SID as warmupSid but do not treat it as the session identity.
  2. •Treat the first SID observed on any “session boundary” event as the real sessionSid. Prefer in this order:
    • •claude.session_start
    • •claude.user_prompt
    • •(fallback) claude.stop
  3. •If a resumeFromSid is known and later appears as the sessionSid, prefer it even if a different SID was seen earlier.
  4. •Do not freeze observedSid on “first SID seen for pid”; allow it to update once sessionSid is established.

Implementation Pattern

To implement robust pid→sid mapping:

  • •Track warmupSid?: string and sessionSid?: string separately per pid.
  • •Set warmupSid on claude.warmup.
  • •Set sessionSid only on claude.session_start / claude.user_prompt (or fallback events).
  • •Use sessionSid as the canonical sid for UI grouping; keep warmupSid only for debugging.

Verification Script (Repro + Interpretation)

Run scripts/verify_claude_resume_sid_artifact.mjs to reproduce the warmup-SID artifact and print a PASS/FAIL interpretation.

Bundled Resources

  • •scripts/verify_claude_resume_sid_artifact.mjs: Spawns Claude Code in stream-json mode, resumes SID_A, and confirms claude.user_prompt/claude.session_start preserve SID_A even if claude.warmup emits a fresh SID first.
  • •scripts/inspect_claude_pid_sids.mjs: Scans the tail of a Claude sse_lines.jsonl for a given pid and prints warmupSid vs derived sessionSid with an interpretation.