@event4u/agent-config 9.16.0 → 9.17.0

package/src/scripts/_cli/handoff_sessions.ts

@@ -0,0 +1,435 @@
+/**
+ * Session enumeration for `agent-config handoff` (road-to-agent-handoff-
+ * resume Phase 1). Pure library — no CLI entry, no prompts, no writes.
+ *
+ * Sources, merged newest-first into one list:
+ *   - `chat-history`     — the cross-host JSONL log (primary; works for
+ *     every hook-capable host). Reuses `chat_history.list_sessions()`.
+ *   - `claude-transcript` — native Claude Code transcripts under
+ *     `~/.claude/projects/<slug>/*.jsonl` (fallback for sessions the log
+ *     missed; slug = cwd with `/` and `.` mapped to `-`).
+ *   - `codex-session`    — `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`
+ *     (Codex's ONLY source — a bundle host without hooks never writes
+ *     chat-history). Format verified 2026-08-04 against the live store:
+ *     line 0 is `{type:'session_meta', payload:{id, timestamp, cwd,
+ *     git:{branch}}}`; user prompts arrive as `event_msg` records with
+ *     `payload:{type:'user_message', message}` (fixture:
+ *     tests/scripts/fixtures/handoff/codex-session.jsonl).
+ *
+ * De-dup: native-store sessions whose platform id maps (via
+ * `derive_session_tag`) to a chat-history bucket are dropped — the
+ * chat-history entry wins.
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+import { derive_session_tag, list_sessions, read_entries } from '../chat_history.js';
+
+export const DEFAULT_CAP = 15;
+const SUMMARY_SNIPPET_CHARS = 120;
+
+export type HandoffSource = 'chat-history' | 'claude-transcript' | 'codex-session';
+
+export interface HandoffSession {
+    id: string;
+    source: HandoffSource;
+    startedAt: string | null;
+    endedAt: string | null;
+    branch?: string;
+    entryCount: number;
+    summary: string;
+    /** Absolute transcript path — set for the native-store sources. */
+    transcriptPath?: string;
+}
+
+export interface ListOptions {
+    /** Repo root the sessions must belong to. Default: process.cwd(). */
+    cwd?: string;
+    /** Chat-history JSONL override (else AGENT_CHAT_HISTORY_FILE / default). */
+    chatHistoryPath?: string | null;
+    /** Claude Code projects root. Default: ~/.claude/projects. */
+    claudeProjectsRoot?: string;
+    /** Codex sessions root. Default: ~/.codex/sessions. */
+    codexSessionsRoot?: string;
+    /** Max sessions per source AND in the merged result. Default 15. */
+    cap?: number;
+}
+
+/** Mirrors the Claude Code project-dir naming: `/` and `.` → `-`. */
+export function encode_project_path(cwd: string): string {
+    return cwd.replace(/[/.]/g, '-');
+}
+
+function _snippet(text: string, max: number = SUMMARY_SNIPPET_CHARS): string {
+    const oneLine = text.replace(/\s+/g, ' ').trim();
+    return oneLine.length <= max ? oneLine : oneLine.slice(0, max - 1) + '…';
+}
+
+/** first-prompt → last-prompt summary (Step 3 contract). */
+function _summarize(first: string | null, last: string | null): string {
+    const a = first ? _snippet(first) : '';
+    const b = last ? _snippet(last) : '';
+    if (a && b && a !== b) return `${a} → ${b}`;
+    return a || b || '(no user prompts)';
+}
+
+function _read_lines(file: string): string[] {
+    try {
+        return fs.readFileSync(file, 'utf-8').split('\n');
+    } catch {
+        return [];
+    }
+}
+
+function _parse_json(line: string): Record<string, unknown> | null {
+    const trimmed = line.trim();
+    if (!trimmed) return null;
+    try {
+        const parsed = JSON.parse(trimmed) as unknown;
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed as Record<string, unknown>;
+        }
+    } catch {
+        // fail-open — skip malformed lines
+    }
+    return null;
+}
+
+// ---------------------------------------------------------------------
+// chat-history (primary)
+// ---------------------------------------------------------------------
+
+const CHAT_HISTORY_REL = path.join('agents', 'runtime', '.agent-chat-history');
+
+/** Explicit option > AGENT_CHAT_HISTORY_FILE env > repo-root-relative default. */
+function _chat_history_path(opts: ListOptions): string {
+    if (opts.chatHistoryPath) return opts.chatHistoryPath;
+    return (
+        process.env.AGENT_CHAT_HISTORY_FILE ||
+        path.join(opts.cwd ?? process.cwd(), CHAT_HISTORY_REL)
+    );
+}
+
+/**
+ * Real-prompt summaries per session: hosts log system/task notifications as
+ * `t:'user'` entries, so the raw bucket summary can read like
+ * `<task-notification>…` — filtered here (council review 2026-08-04,
+ * claude-sonnet-4-5 + gpt-4o: picker noise is a UX defect; the log itself
+ * stays unfiltered).
+ */
+function _chat_history_summaries(histPath: string): Map<string, { first: string | null; last: string | null }> {
+    const bySession = new Map<string, { first: string | null; last: string | null }>();
+    let entries: Array<Record<string, unknown>>;
+    try {
+        entries = read_entries({ path: histPath, last: null });
+    } catch {
+        return bySession;
+    }
+    for (const e of entries) {
+        if (e.t !== 'user' || typeof e.text !== 'string') continue;
+        const text = e.text.trim();
+        if (!text || text.startsWith('<') || text.startsWith('Caveat:')) continue;
+        const sid = String(e.s ?? '<legacy>');
+        const slot = bySession.get(sid) ?? { first: null, last: null };
+        if (!slot.first) slot.first = text;
+        slot.last = text;
+        bySession.set(sid, slot);
+    }
+    return bySession;
+}
+
+function _chat_history_sessions(opts: ListOptions): HandoffSession[] {
+    const histPath = _chat_history_path(opts);
+    let buckets: Array<Record<string, unknown>>;
+    try {
+        buckets = list_sessions({ path: histPath, summary: true });
+    } catch {
+        return [];
+    }
+    const summaries = _chat_history_summaries(histPath);
+    return buckets
+        .filter((b) => Number(b.count ?? 0) > 0)
+        .map((b) => {
+            const id = String(b.id ?? '');
+            const prompts = summaries.get(id);
+            const summary = prompts
+                ? _summarize(prompts.first, prompts.last)
+                : '(no user prompts)';
+            return {
+                id,
+                source: 'chat-history' as const,
+                startedAt: b.first_ts ? String(b.first_ts) : null,
+                endedAt: b.last_ts ? String(b.last_ts) : null,
+                entryCount: Number(b.count ?? 0),
+                summary,
+            };
+        });
+}
+
+// ---------------------------------------------------------------------
+// claude-transcript (native fallback)
+// ---------------------------------------------------------------------
+
+interface TranscriptScan {
+    entryCount: number;
+    firstTs: string | null;
+    lastTs: string | null;
+    branch: string | null;
+    firstPrompt: string | null;
+    lastPrompt: string | null;
+}
+
+/** A real prompt has string content; tool_results arrive as block lists. */
+function _cc_prompt_text(rec: Record<string, unknown>): string | null {
+    if (rec.type !== 'user' || rec.isSidechain === true) return null;
+    const msg = rec.message;
+    if (!msg || typeof msg !== 'object' || Array.isArray(msg)) return null;
+    const content = (msg as Record<string, unknown>).content;
+    if (typeof content !== 'string') return null;
+    const trimmed = content.trim();
+    // skip host-injected meta blocks (caveats, command wrappers)
+    if (!trimmed || trimmed.startsWith('<') || trimmed.startsWith('Caveat:')) return null;
+    return trimmed;
+}
+
+function _scan_claude_transcript(file: string): TranscriptScan {
+    const scan: TranscriptScan = {
+        entryCount: 0,
+        firstTs: null,
+        lastTs: null,
+        branch: null,
+        firstPrompt: null,
+        lastPrompt: null,
+    };
+    for (const line of _read_lines(file)) {
+        const rec = _parse_json(line);
+        if (!rec) continue;
+        scan.entryCount += 1;
+        const ts = typeof rec.timestamp === 'string' ? rec.timestamp : null;
+        if (ts) {
+            if (!scan.firstTs) scan.firstTs = ts;
+            scan.lastTs = ts;
+        }
+        if (!scan.branch && typeof rec.gitBranch === 'string' && rec.gitBranch) {
+            scan.branch = rec.gitBranch;
+        }
+        const prompt = _cc_prompt_text(rec);
+        if (prompt) {
+            if (!scan.firstPrompt) scan.firstPrompt = prompt;
+            scan.lastPrompt = prompt;
+        }
+    }
+    return scan;
+}
+
+function _claude_transcript_sessions(opts: ListOptions, cap: number): HandoffSession[] {
+    const root = opts.claudeProjectsRoot ?? path.join(os.homedir(), '.claude', 'projects');
+    const cwd = opts.cwd ?? process.cwd();
+    const projectDir = path.join(root, encode_project_path(cwd));
+    let names: string[];
+    try {
+        names = fs.readdirSync(projectDir).filter((n) => n.endsWith('.jsonl'));
+    } catch {
+        return [];
+    }
+    const files = names
+        .map((n) => {
+            const full = path.join(projectDir, n);
+            try {
+                return { full, id: path.basename(n, '.jsonl'), mtime: fs.statSync(full).mtimeMs };
+            } catch {
+                return null;
+            }
+        })
+        .filter((f): f is { full: string; id: string; mtime: number } => f !== null)
+        .sort((a, b) => b.mtime - a.mtime)
+        .slice(0, cap);
+
+    const sessions: HandoffSession[] = [];
+    for (const f of files) {
+        const scan = _scan_claude_transcript(f.full);
+        if (scan.entryCount === 0) continue;
+        sessions.push({
+            id: f.id,
+            source: 'claude-transcript',
+            startedAt: scan.firstTs,
+            endedAt: scan.lastTs,
+            ...(scan.branch ? { branch: scan.branch } : {}),
+            entryCount: scan.entryCount,
+            summary: _summarize(scan.firstPrompt, scan.lastPrompt),
+            transcriptPath: f.full,
+        });
+    }
+    return sessions;
+}
+
+// ---------------------------------------------------------------------
+// codex-session (native adapter — Codex's only source)
+// ---------------------------------------------------------------------
+
+interface CodexMeta {
+    id: string;
+    timestamp: string | null;
+    cwd: string;
+    branch: string | null;
+}
+
+function _codex_meta(file: string): CodexMeta | null {
+    let firstLine = '';
+    try {
+        // metadata is always line 0 — never read the whole file here
+        const fd = fs.openSync(file, 'r');
+        try {
+            const buf = Buffer.alloc(8192);
+            const n = fs.readSync(fd, buf, 0, buf.length, 0);
+            firstLine = buf.toString('utf-8', 0, n).split('\n')[0] ?? '';
+        } finally {
+            fs.closeSync(fd);
+        }
+    } catch {
+        return null;
+    }
+    const rec = _parse_json(firstLine);
+    if (!rec || rec.type !== 'session_meta') return null;
+    const payload = rec.payload;
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return null;
+    const p = payload as Record<string, unknown>;
+    const git =
+        p.git && typeof p.git === 'object' && !Array.isArray(p.git)
+            ? (p.git as Record<string, unknown>)
+            : {};
+    return {
+        id: String(p.id ?? ''),
+        timestamp: typeof p.timestamp === 'string' ? p.timestamp : null,
+        cwd: String(p.cwd ?? ''),
+        branch: typeof git.branch === 'string' && git.branch ? git.branch : null,
+    };
+}
+
+function _codex_files(root: string): string[] {
+    const out: string[] = [];
+    const stack = [root];
+    while (stack.length > 0) {
+        const dir = stack.pop() as string;
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            continue;
+        }
+        for (const e of entries) {
+            const full = path.join(dir, e.name);
+            if (e.isDirectory()) stack.push(full);
+            else if (e.isFile() && e.name.endsWith('.jsonl')) out.push(full);
+        }
+    }
+    // rollout filenames embed the timestamp — lexicographic basename sort
+    // is chronological; newest first
+    return out.sort((a, b) => (path.basename(a) < path.basename(b) ? 1 : -1));
+}
+
+interface CodexScan {
+    entryCount: number;
+    lastTs: string | null;
+    firstPrompt: string | null;
+    lastPrompt: string | null;
+}
+
+function _codex_prompt_text(rec: Record<string, unknown>): string | null {
+    if (rec.type !== 'event_msg') return null;
+    const p = rec.payload;
+    if (!p || typeof p !== 'object' || Array.isArray(p)) return null;
+    const payload = p as Record<string, unknown>;
+    if (payload.type !== 'user_message') return null;
+    const msg = typeof payload.message === 'string' ? payload.message.trim() : '';
+    if (!msg || msg.startsWith('<')) return null; // skip injected meta blocks
+    return msg;
+}
+
+function _scan_codex_session(file: string): CodexScan {
+    const scan: CodexScan = { entryCount: 0, lastTs: null, firstPrompt: null, lastPrompt: null };
+    for (const line of _read_lines(file)) {
+        const rec = _parse_json(line);
+        if (!rec) continue;
+        scan.entryCount += 1;
+        if (typeof rec.timestamp === 'string') scan.lastTs = rec.timestamp;
+        const prompt = _codex_prompt_text(rec);
+        if (prompt) {
+            if (!scan.firstPrompt) scan.firstPrompt = prompt;
+            scan.lastPrompt = prompt;
+        }
+    }
+    return scan;
+}
+
+function _matches_repo(sessionCwd: string, repoCwd: string): boolean {
+    const norm = (p: string): string => path.resolve(p).replace(/\/+$/, '');
+    const a = norm(sessionCwd);
+    const b = norm(repoCwd);
+    return a === b || a.startsWith(b + path.sep);
+}
+
+function _codex_sessions(opts: ListOptions, cap: number): HandoffSession[] {
+    const root = opts.codexSessionsRoot ?? path.join(os.homedir(), '.codex', 'sessions');
+    const cwd = opts.cwd ?? process.cwd();
+    const matching: Array<{ file: string; meta: CodexMeta }> = [];
+    for (const file of _codex_files(root)) {
+        if (matching.length >= cap) break;
+        const meta = _codex_meta(file); // line-0 read only — cheap per file
+        if (!meta || !meta.id) continue;
+        if (!_matches_repo(meta.cwd, cwd)) continue;
+        matching.push({ file, meta });
+    }
+    const sessions: HandoffSession[] = [];
+    for (const { file, meta } of matching) {
+        const scan = _scan_codex_session(file);
+        if (scan.entryCount === 0) continue;
+        sessions.push({
+            id: meta.id,
+            source: 'codex-session',
+            startedAt: meta.timestamp,
+            endedAt: scan.lastTs ?? meta.timestamp,
+            ...(meta.branch ? { branch: meta.branch } : {}),
+            entryCount: scan.entryCount,
+            summary: _summarize(scan.firstPrompt, scan.lastPrompt),
+            transcriptPath: file,
+        });
+    }
+    return sessions;
+}
+
+// ---------------------------------------------------------------------
+// merge
+// ---------------------------------------------------------------------
+
+function _sort_key(s: HandoffSession): string {
+    return s.endedAt ?? s.startedAt ?? '';
+}
+
+/**
+ * Unified newest-first session list. Native-store sessions whose platform
+ * id maps to an existing chat-history bucket are dropped (chat-history is
+ * the primary source).
+ */
+export function list_handoff_sessions(opts: ListOptions = {}): HandoffSession[] {
+    const cap = opts.cap ?? DEFAULT_CAP;
+    const primary = _chat_history_sessions(opts);
+    const knownTags = new Set(primary.map((s) => s.id));
+
+    const native = [
+        ..._claude_transcript_sessions(opts, cap),
+        ..._codex_sessions(opts, cap),
+    ].filter((s) => {
+        try {
+            return !knownTags.has(derive_session_tag(s.id));
+        } catch {
+            return true;
+        }
+    });
+
+    return [...primary, ...native]
+        .sort((a, b) => (_sort_key(a) < _sort_key(b) ? 1 : _sort_key(a) > _sort_key(b) ? -1 : 0))
+        .slice(0, cap);
+}

package/src/scripts/_dispatch.bash

@@ -257,6 +257,7 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
   telemetry:status           Print artefact-engagement telemetry status (read-only)
   telemetry:report           Aggregate the engagement log into a quartile report
   analyze-session            Read-only post-session report from on-disk runtime state
+  handoff                    Pick a recent session, generate a handoff, seed a fresh session
 EOF
   fi
 
@@ -1182,6 +1183,13 @@ cmd_analyze_session() {
   exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_analyze_session.ts" "$@"
 }
 
+# `agent-config handoff` — pick a recent session, generate a deterministic
+# handoff into agents/runtime/state/handoff-context.md, optionally --launch a
+# fresh host session. See scripts/_cli/cmd_handoff.ts.
+cmd_handoff() {
+  exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_handoff.ts" "$@"
+}
+
 main() {
   local cmd="${1-}"
   [[ $# -gt 0 ]] && shift || true
@@ -1255,6 +1263,7 @@ main() {
     versions)                cmd_versions "$@" ;;
     explain)                 cmd_explain "$@" ;;
     analyze-session)         cmd_analyze_session "$@" ;;
+    handoff)                 cmd_handoff "$@" ;;
     help|--help|-h|"")
       # Optional `--tier=0|1|all` filter (default 0).
       local tier_arg="0"

package/src/scripts/_lib/agent_src.ts

@@ -179,6 +179,27 @@ function _iterdirSorted(p: string): string[] {
 function _rglobSorted(root: string, pattern: string): string[] {
     const out: string[] = [];
     const suffix = pattern === '*' ? null : pattern.slice(1); // drop leading '*'
+    // Symlink confinement: every symlink (leaf or directory) must resolve
+    // inside the walk root, or it is ignored. A visited-realpath set bounds
+    // symlink cycles, and a broken symlink (realpath throws) is skipped
+    // explicitly. Without this, a directory symlink planted under a source
+    // root walks arbitrary paths outside the package and a cycle recurses
+    // until stack exhaustion (release-truth Phase 3).
+    let rootReal: string;
+    try {
+        rootReal = fs.realpathSync(root);
+    } catch {
+        return out;
+    }
+    const _confined = (p: string): string | null => {
+        try {
+            const real = fs.realpathSync(p);
+            return real === rootReal || _isUnder(real, rootReal) ? real : null;
+        } catch {
+            return null; // broken symlink → handled explicitly as "not yielded"
+        }
+    };
+    const visited = new Set<string>([rootReal]);
     const walk = (dir: string): void => {
         let entries: fs.Dirent[];
         try {
@@ -189,14 +210,21 @@ function _rglobSorted(root: string, pattern: string): string[] {
         for (const ent of entries) {
             const full = path.join(dir, ent.name);
             const matches = suffix === null ? true : ent.name.endsWith(suffix);
-            if (matches) {
+            if (matches && (!ent.isSymbolicLink() || _confined(full) !== null)) {
                 out.push(full);
             }
             // Recurse into directories. `isDirectory()` on a Dirent does not
-            // follow symlinks; pathlib.rglob follows directory symlinks. Use a
-            // stat-based dir check to match Python's traversal, but guard
-            // against unreadable entries.
-            if (ent.isDirectory() || (ent.isSymbolicLink() && _isDir(full))) {
+            // follow symlinks; pathlib.rglob follows directory symlinks. Follow
+            // a directory symlink only when its target stays inside the walk
+            // root and has not been visited yet (cycle guard).
+            if (ent.isDirectory()) {
+                walk(full);
+            } else if (ent.isSymbolicLink() && _isDir(full)) {
+                const real = _confined(full);
+                if (real === null || visited.has(real)) {
+                    continue;
+                }
+                visited.add(real);
                 walk(full);
             }
         }
@@ -432,7 +460,9 @@ export function artefact_roots(): string[] {
  *
  * Walks `_root_specs` (the leaf view). Deterministic order; deduplicated on
  * logical path so a file present in two roots during the move window is
- * yielded once. Symlinks and non-files are skipped. Mirrors `iter_artefacts`.
+ * yielded once. Non-files are skipped; symlinks are followed only when they
+ * resolve inside their walk root (external targets, broken links, and cycles
+ * are ignored). Mirrors `iter_artefacts`.
  */
 export function* iter_artefacts(suffix = '.md'): Generator<string> {
     const seen: Set<string> = new Set();

package/src/scripts/_lib/release_material.ts

@@ -0,0 +1,156 @@
+/**
+ * Single-source release material (release-truth Phase 1).
+ *
+ * The recorded 9.14.0 failure: PR body, CHANGELOG entry, GitHub release
+ * body, and tag metadata were generated at different times from different
+ * scopes — the PR body said 10,054 tests while the merged changelog carried
+ * 10,056 and more items. The fix is structural: the CHANGELOG section at the
+ * relevant head is the ONE final source, and every other surface is a pure
+ * derivation of it (release.ts re-derives on branch update / resume / merge,
+ * so late commits cannot desynchronize the surfaces).
+ *
+ * Everything here is a pure function of strings so the equality gate
+ * (`check_release_surface_equality.ts`) and the fixture tests exercise the
+ * exact production code paths.
+ */
+
+export interface ChangelogSection {
+    /** The `## …` heading line, verbatim. */
+    heading: string;
+    /** Section content below the heading, outer blank lines stripped. */
+    body: string;
+}
+
+const _NEXT_HEADING_RE = /^##\s+\[?\d+\.\d+\.\d+/m;
+
+function _reEscape(s: string): string {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Extract the CHANGELOG section for `version` — heading plus body up to the
+ * next version heading (or end of file). Returns null when no heading for
+ * `version` exists. Matches both heading shapes the generator emits
+ * (`## X.Y.Z (date)` and `## [X.Y.Z](compare-url) (date)`).
+ */
+export function extract_changelog_section(text: string, version: string): ChangelogSection | null {
+    const headingRe = new RegExp(`^##\\s+\\[?${_reEscape(version)}\\b.*$`, 'm');
+    const m = headingRe.exec(text);
+    if (!m) {
+        return null;
+    }
+    const bodyStart = m.index + m[0].length;
+    const rest = text.slice(bodyStart);
+    const next = _NEXT_HEADING_RE.exec(rest);
+    const sectionEnd = bodyStart + (next ? next.index : rest.length);
+    const body = text
+        .slice(bodyStart, sectionEnd)
+        .replace(/^\n+/u, '')
+        .replace(/\s+$/u, '');
+    return { heading: m[0], body };
+}
+
+/** Footer appended to the release-PR body; the strip helper accepts legacy variants. */
+export const PR_BODY_FOOTER = 'Created by `src/scripts/release.ts`.';
+const _LEGACY_PR_FOOTERS = ['Created by `scripts/release.py`.', PR_BODY_FOOTER];
+
+/** Marker `_cap_body` embeds when a surface was truncated to a GitHub limit. */
+export const TRUNCATION_MARKER = '_Changelog truncated to fit GitHub';
+
+/** Release-PR body derived from the (possibly capped) changelog-section body. */
+export function pr_body_from_section(cappedBody: string, version: string): string {
+    return `Release ${version}.\n\n${cappedBody}\n\n${PR_BODY_FOOTER}`;
+}
+
+/** GitHub-release notes derived from the (possibly capped) changelog-section body. */
+export function release_notes_from_section(cappedBody: string, version: string): string {
+    return cappedBody || `Release ${version}`;
+}
+
+/** Annotated-tag message derived from the merged changelog-section body. */
+export function tag_message_from_section(body: string, version: string): string {
+    const trailer = body ? `\n\n${body}` : '';
+    return `release: ${version}${trailer}\n`;
+}
+
+/**
+ * Inverse of `pr_body_from_section`: return the changelog-derived middle of a
+ * release-PR body, or null when the body does not carry the canonical
+ * `Release X.Y.Z.` prefix (then it was not generated by this pipeline).
+ */
+export function strip_pr_wrapper(prBody: string, version: string): string | null {
+    const prefix = `Release ${version}.`;
+    let s = prBody.replace(/\r\n/gu, '\n').trim();
+    if (!s.startsWith(prefix)) {
+        return null;
+    }
+    s = s.slice(prefix.length);
+    for (const footer of _LEGACY_PR_FOOTERS) {
+        if (s.trimEnd().endsWith(footer)) {
+            s = s.trimEnd();
+            s = s.slice(0, s.length - footer.length);
+            break;
+        }
+    }
+    return s.replace(/^\n+/u, '').replace(/\s+$/u, '');
+}
+
+/**
+ * Whitespace/anchor normalization — deliberately nothing stronger, per the
+ * roadmap lock ("not 'similar', equal"): CRLF → LF, trailing whitespace per
+ * line dropped, runs of blank lines collapsed to one, outer blank lines
+ * trimmed. Content differences always survive normalization.
+ */
+export function normalize_release_text(s: string): string {
+    return s
+        .replace(/\r\n/gu, '\n')
+        .split('\n')
+        .map((line) => line.replace(/[ \t]+$/u, ''))
+        .join('\n')
+        .replace(/\n{3,}/gu, '\n\n')
+        .replace(/^\n+/u, '')
+        .replace(/\n+$/u, '');
+}
+
+/**
+ * Compare a derived release surface against the changelog-section body it
+ * must equal. Returns null when equal (after normalization), else a
+ * human-readable first-divergence report. A truncated surface (carrying the
+ * `_cap_body` notice) is compared as a prefix of the changelog side — the
+ * truncation itself is not a divergence.
+ */
+export function surface_divergence(surfaceText: string, changelogBody: string): string | null {
+    const a = normalize_release_text(surfaceText);
+    const b = normalize_release_text(changelogBody);
+    if (a.includes(TRUNCATION_MARKER)) {
+        const cut = a.indexOf(TRUNCATION_MARKER);
+        const prefix = a
+            .slice(0, cut)
+            .replace(/>\s*$/u, '')
+            .replace(/\n+$/u, '');
+        if (b.startsWith(prefix)) {
+            return null;
+        }
+        return _first_diff(prefix, b.slice(0, prefix.length));
+    }
+    if (a === b) {
+        return null;
+    }
+    return _first_diff(a, b);
+}
+
+function _first_diff(a: string, b: string): string {
+    const al = a.split('\n');
+    const bl = b.split('\n');
+    const n = Math.max(al.length, bl.length);
+    for (let i = 0; i < n; i++) {
+        if (al[i] !== bl[i]) {
+            return (
+                `first divergence at line ${i + 1}: ` +
+                `surface=${JSON.stringify(al[i] ?? '<missing>')} ` +
+                `changelog=${JSON.stringify(bl[i] ?? '<missing>')}`
+            );
+        }
+    }
+    return 'surfaces differ only in normalization-invisible content';
+}