@event4u/agent-config 16.4.0 → 17.0.0

package/src/scripts/_lib/self_repair.ts

@@ -118,8 +118,38 @@ export interface DefectFinding {
      * worse than free text — it looks joined and joins to nothing.
      */
     proposes?: string[];
+    /**
+     * The canonical claim, a stable slug (`drain/baseline-drift`). A retro
+     * writes its `Candidate.subject` here; two syntheses that agree on the
+     * claim spell it identically, which is what lets two installations meet.
+     *
+     * The upstream body carries it (`renderUpstreamBody`, D10); the key does
+     * not — whether it may identify a record across installations waits on a
+     * corpus showing one subject per mechanism.
+     */
+    principle?: string;
+    /** One bounded line naming how the defect happens. No producer field yet. Free text, so it never leaves. */
+    mechanism?: string;
+    /** One bounded line naming what would refute the claim; a retro's `Candidate.falsifier`. Never leaves. */
+    falsifier?: string;
+    /**
+     * The retro unit keys that named this record (`docs/contracts/retro-v1.md`).
+     * Local bookkeeping only, like `release_errors`: no renderer reads it and
+     * the fingerprint ignores it, so it joins a record to the finished work it
+     * came from without widening what can leave the machine.
+     */
+    unit_keys?: string[];
 }
 
+/** `principle` shape: non-empty lowercase segments joined by single `/`, `.`, `_` or `-`; at most 80 characters. */
+export const PRINCIPLE_RE = /^(?=.{1,80}$)[a-z0-9]+(?:[/._-][a-z0-9]+)*$/;
+
+/** Control characters, including the Unicode line and paragraph separators. */
+const CONTROL_RE = /[\u0000-\u001f\u007f\u2028\u2029]/;
+
+/** Length bound for `mechanism` and `falsifier`, the same as an evidence span. */
+export const MAX_CLAIM_LINE = 160;
+
 /** The four asset kinds a `target` entry may address. */
 export const TARGET_KINDS = ['rule', 'skill', 'command', 'hook'] as const;
 export type TargetKind = (typeof TARGET_KINDS)[number];
@@ -234,7 +264,13 @@ export function sanitizeEvidence(raw: string): string {
  * of being scrubbed into publishable shape.
  */
 export function egressBlockedReason(record: DefectRecord, repoRoot?: string | null): string | null {
-    const result = redact_low_impact_entry(`${record.suggested_surface}\n${record.evidence}`, {
+    // Every free value the record carries, not only the two a report renders
+    // today — a field the floor never saw must not become sendable later by a
+    // renderer change alone.
+    const text = [record.suggested_surface, record.evidence, record.principle, record.mechanism, record.falsifier]
+        .filter((v): v is string => typeof v === 'string' && v.length > 0)
+        .join('\n');
+    const result = redact_low_impact_entry(text, {
         repoRoot: repoRoot ?? null,
     });
     if (result.ok) {
@@ -752,6 +788,15 @@ export function validateRecord(record: DefectRecord): string[] {
             out.push(`target '${value}' is not \`<rule|skill|command|hook>:<id>\``);
         }
     }
+    if (record.principle !== undefined && !PRINCIPLE_RE.test(record.principle)) {
+        out.push(`principle '${record.principle}' is not a lowercase slug of at most 80 characters`);
+    }
+    for (const field of ['mechanism', 'falsifier'] as const) {
+        const value = record[field];
+        if (value !== undefined && (value.trim() === '' || value.length > MAX_CLAIM_LINE || CONTROL_RE.test(value))) {
+            out.push(`${field} must be one non-empty line of at most ${MAX_CLAIM_LINE} characters`);
+        }
+    }
     return out;
 }
 
@@ -764,6 +809,20 @@ function _mergeIds(a: readonly string[] | undefined, b: readonly string[] | unde
     return out;
 }
 
+const CLAIM_FIELDS = ['principle', 'mechanism', 'falsifier'] as const;
+
+// The three fields are one claim: they are adopted together from one source,
+// never merged per field, so a falsifier is never paired with a claim it was
+// not written for.
+function claimFields(existing: DefectFinding, finding: DefectFinding): Partial<DefectFinding> {
+    const source = CLAIM_FIELDS.some((f) => existing[f] !== undefined) ? existing : finding;
+    const out: Partial<DefectFinding> = {};
+    for (const field of CLAIM_FIELDS) {
+        if (source[field] !== undefined) out[field] = source[field];
+    }
+    return out;
+}
+
 export function mergeRecord(
     existing: DefectRecord | null,
     finding: DefectFinding,
@@ -773,6 +832,7 @@ export function mergeRecord(
     if (existing !== null && existing.fingerprint === fp) {
         const target = _mergeIds(existing.target, finding.target);
         const proposes = _mergeIds(existing.proposes, finding.proposes);
+        const unitKeys = _mergeIds(existing.unit_keys, finding.unit_keys);
         const merged: DefectRecord = {
             ...existing,
             last_seen: now,
@@ -783,6 +843,9 @@ export function mergeRecord(
             status: 'open',
             ...(target.length > 0 ? { target } : {}),
             ...(proposes.length > 0 ? { proposes } : {}),
+            ...(unitKeys.length > 0 ? { unit_keys: unitKeys } : {}),
+            // A detector-opened record that a retro later names keeps the name.
+            ...claimFields(existing, finding),
         };
         // `open` carries no wake condition; a stale one would read as a park.
         delete merged.parked_until;
@@ -844,7 +907,11 @@ export function chooseEgress(cap: EgressCapability): EgressChoice {
     return { route: 'local-only', pushVia: null };
 }
 
-/** The PR / issue body. Deterministic — same record, same bytes. */
+/**
+ * The full local report, free-text fields included. Deterministic — same
+ * record, same bytes. Used for a local-only record and the Class-B case; what
+ * leaves the machine is `renderUpstreamBody` in `self_repair_outgoing.ts`.
+ */
 export function renderReport(record: DefectRecord, route: EgressRoute): string {
     const seen =
         record.occurrences === 1
@@ -879,40 +946,3 @@ export function renderReport(record: DefectRecord, route: EgressRoute): string {
         'construction — the record type has no field that can carry them.',
     ].join('\n');
 }
-
-/** The structured fields the upstream intake form collects. */
-export interface ParsedReport {
-    defect_class: string;
-    fingerprint: string;
-    occurrences: number;
-    evidence: string;
-    suggested_surface: string;
-}
-
-/**
- * Inverse of `renderReport` for the structured fields — the round-trip that
- * pins the rendered body to the upstream issue form: every field the form
- * collects is recoverable from a rendered report, so a `release` body and a
- * manually-filed form carry the same clustering keys (fingerprint above all).
- */
-export function parseReport(body: string): ParsedReport | null {
-    const cls = /^## Self-repair report — `([^`]+)`$/m.exec(body)?.[1];
-    const fp = /^- \*\*Fingerprint:\*\* `([^`]+)`$/m.exec(body)?.[1];
-    const seen = /^- \*\*Seen:\*\* (.+)$/m.exec(body)?.[1];
-    const evidence = /^### Evidence\n\n> (.*)$/m.exec(body)?.[1];
-    const surface = /### What the fix should address\n\n([\s\S]*?)\n\n---/.exec(body)?.[1];
-    if (!cls || !fp || !seen || evidence === undefined || !surface) {
-        return null;
-    }
-    const occurrences = seen.startsWith('once') ? 1 : Number(/^(\d+)×/.exec(seen)?.[1] ?? Number.NaN);
-    if (!Number.isFinite(occurrences)) {
-        return null;
-    }
-    return {
-        defect_class: cls,
-        fingerprint: fp,
-        occurrences,
-        evidence,
-        suggested_surface: surface.trim(),
-    };
-}

package/src/scripts/_lib/self_repair_outgoing.ts

@@ -0,0 +1,209 @@
+/**
+ * The exact bytes a release would send, rendered once for the person to read
+ * and digested once for the release to check.
+ *
+ * The dry run and the release build this from the same inputs, so an approval
+ * names the bytes that leave and where they go: the target repository, the
+ * account, the route and its fallback rungs, the push remote and the base
+ * commit; the branch name, the commit identity and message, the diff, the
+ * title and the body of the pull request; and the title and body of the issue
+ * the ladder degrades to. A change to any of them after the person read them
+ * changes the digest, and the release refuses. The comparison is `self_repair_class_b`'s `approve` — the one
+ * digest-bound approval in the tree — rather than a second one. The
+ * ratification `subjectDigest` was the other candidate and is not used: it
+ * digests the gated paths of a ratification subject at a revision, not an
+ * arbitrary outgoing payload.
+ *
+ * The commit date is not part of the digest. It is the moment of the release,
+ * stated in UTC so the local timezone offset does not leave with it.
+ */
+import { type DefectRecord, type EgressRoute } from './self_repair.js';
+import { approve, caseDigest } from './self_repair_class_b.js';
+
+/** A neutral branch: the fingerprint, never the author's branch name. */
+export function retroBranch(fingerprint: string): string {
+    return `retro/${fingerprint.slice(0, 8)}`;
+}
+
+/**
+ * The body of the pull request and the issue, built from closed fields only:
+ * the defect class, the intake source, the fingerprint, the occurrence count,
+ * the resolved targets and the principle slug — all shape-validated, none of
+ * them prose. The evidence span, the suggested surface, the mechanism and the
+ * falsifier are free text whatever their field name, so they stay on the
+ * machine (D10 of road-to-one-upstream-that-checks-what-leaves); `renderReport`
+ * still carries them for the local and Class-B case. No dates either: when a
+ * defect was seen is activity on the reporting machine, not part of the claim.
+ */
+export function renderUpstreamBody(record: DefectRecord, route: EgressRoute): string {
+    const targets = record.target !== undefined && record.target.length > 0 ? record.target.map((t) => `\`${t}\``).join(', ') : 'none identified';
+    const principle = record.principle !== undefined ? `\`${record.principle}\`` : 'not stated';
+    return [
+        `## Self-repair report — \`${record.defect_class}\``,
+        '',
+        `- **Source:** \`${record.source}\``,
+        `- **Fingerprint:** \`${record.fingerprint}\``,
+        `- **Occurrences:** ${record.occurrences}`,
+        `- **Route:** ${route}`,
+        `- **Targets:** ${targets}`,
+        `- **Principle:** ${principle}`,
+        '',
+        '### Package fixture',
+        '',
+        `Reproduce against this package's own \`${record.defect_class}\` detector in`,
+        '`src/scripts/_lib/self_repair.ts` and the targets named above.',
+        '',
+        '---',
+        '',
+        'Filed by the agent-config self-repair loop from closed fields only. The',
+        'evidence span, the suggested surface, the mechanism and the falsifier stayed',
+        'on the reporting machine; the person approved these exact bytes.',
+    ].join('\n');
+}
+
+/** The structured fields the upstream intake form collects. */
+export interface ParsedUpstreamBody {
+    defect_class: string;
+    source: string;
+    fingerprint: string;
+    occurrences: number;
+    targets: string;
+    principle: string;
+}
+
+/**
+ * Inverse of {@link renderUpstreamBody} — the round-trip that pins the body to
+ * the upstream issue form, so a released body and a hand-filed form carry the
+ * same clustering keys. `targets` and `principle` come back as rendered.
+ */
+export function parseUpstreamBody(body: string): ParsedUpstreamBody | null {
+    const field = (label: string): string | undefined => new RegExp(`^- \\*\\*${label}:\\*\\* (.+)$`, 'm').exec(body)?.[1];
+    const unquote = (v: string): string => v.replace(/`/g, '');
+    const cls = /^## Self-repair report — `([^`]+)`$/m.exec(body)?.[1];
+    const [source, fp, occ, targets, principle] = ['Source', 'Fingerprint', 'Occurrences', 'Targets', 'Principle'].map(field);
+    if (!cls || !source || !fp || !occ || !targets || !principle || !/^\d+$/.test(occ)) {
+        return null;
+    }
+    return {
+        defect_class: cls,
+        source: unquote(source),
+        fingerprint: unquote(fp),
+        occurrences: Number(occ),
+        targets: unquote(targets),
+        principle: unquote(principle),
+    };
+}
+
+export interface CommitIdentity {
+    name: string;
+    email: string;
+}
+
+const NOREPLY_DOMAIN = 'users.noreply.github.com';
+
+/**
+ * GitHub's noreply form for the account `gh` is signed in as. That account is
+ * already visible on the pull request; the configured git identity, which is
+ * often a company address, is not, and is never used.
+ */
+export function noreplyIdentity(login: string, id: string): CommitIdentity | null {
+    if (!/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/.test(login) || !/^\d+$/.test(id)) {
+        return null;
+    }
+    return { name: login, email: `${id}+${login}@${NOREPLY_DOMAIN}` };
+}
+
+export function isNoreplyEmail(email: string): boolean {
+    return email.toLowerCase().endsWith(`@${NOREPLY_DOMAIN}`);
+}
+
+/** Built from the title and the fingerprint only — both closed, both in the digest. */
+export function commitMessage(title: string, fingerprint: string): string {
+    return `${title}\n\nSelf-repair fingerprint: ${fingerprint}\n`;
+}
+
+export interface OutgoingPullRequest {
+    branch: string;
+    identity: CommitIdentity;
+    message: string;
+    /** The author branch's net change against the base, as `git diff --binary` prints it. */
+    patch: string;
+    title: string;
+    body: string;
+}
+
+export interface OutgoingIssue {
+    title: string;
+    body: string;
+}
+
+/** Where the bytes go — approved with them, because the same text sent elsewhere is another act. */
+export interface Destination {
+    /** `owner/name` the pull request or issue is opened against. */
+    repo: string;
+    /** The GitHub login the send carries, or null when it could not be resolved. */
+    account: string | null;
+    /** The planned route; `rungs` is the ladder it may degrade along. */
+    route: 'pull-request' | 'issue' | 'local-only';
+    rungs: Array<'upstream' | 'fork' | 'issue'>;
+    /** The URL the first push rung pushes to; null on the issue route. */
+    remote: string | null;
+    /** The commit the pull request's one commit sits on; null on the issue route. */
+    baseSha: string | null;
+}
+
+export interface Outgoing {
+    destination: Destination | null;
+    pullRequest: OutgoingPullRequest | null;
+    issue: OutgoingIssue | null;
+}
+
+function section(label: string, text: string): string {
+    // The byte count makes the concatenation unambiguous: no section's content
+    // can be shifted into its neighbour without the digest changing.
+    return `--- ${label} (${Buffer.byteLength(text, 'utf-8')} bytes) ---\n${text}\n`;
+}
+
+/** Every byte that may leave, in one deterministic text. */
+export function renderOutgoing(o: Outgoing): string {
+    let out = '';
+    if (o.destination !== null) {
+        const d = o.destination;
+        out += '=== destination ===\n';
+        out += section('repository', d.repo);
+        out += section('account', d.account ?? '(unresolved)');
+        out += section('route', `${d.route} (rungs: ${d.rungs.join(' -> ')})`);
+        out += section('push remote', d.remote ?? '(none)');
+        out += section('base commit', d.baseSha ?? '(none)');
+    }
+    if (o.pullRequest !== null) {
+        const pr = o.pullRequest;
+        out += '=== pull request ===\n';
+        out += section('branch', pr.branch);
+        out += section('author and committer', `${pr.identity.name} <${pr.identity.email}>`);
+        out += section('commit message', pr.message);
+        out += section('diff', pr.patch);
+        out += section('title', pr.title);
+        out += section('body', pr.body);
+    }
+    if (o.issue !== null) {
+        out += o.pullRequest !== null ? '=== issue, if the pull request fails ===\n' : '=== issue ===\n';
+        out += section('title', o.issue.title);
+        out += section('body', o.issue.body);
+    }
+    return out;
+}
+
+/** The digest the person approves: SHA-256 of {@link renderOutgoing}. */
+export function outgoingDigest(o: Outgoing): string {
+    return caseDigest(renderOutgoing(o));
+}
+
+/** Null when the approval names exactly these bytes; otherwise the reason it does not. */
+export function approvalRefusal(record: DefectRecord, o: Outgoing, approvedDigest: string | null | undefined): string | null {
+    if (approvedDigest === null || approvedDigest === undefined || approvedDigest.trim() === '') {
+        return 'no approval: run the dry run, read every byte, then release with --approve <digest>';
+    }
+    const verdict = approve(record, renderOutgoing(o), approvedDigest.trim());
+    return verdict.ok ? null : verdict.reason;
+}

package/src/scripts/_lib/self_repair_payload.ts

@@ -0,0 +1,86 @@
+/**
+ * The release's floor over the WHOLE outgoing payload — branch name, the
+ * synthesised commit (identity and message), every object the push adds to the
+ * base (paths and blob contents), title and body — where `egressBlockedReason`
+ * reads only the record's own text.
+ *
+ * Credentials come from the one detector table (`egress_rules`); no pattern is
+ * defined here. Identifiers are the consumer project's own, passed in as a deny
+ * list. A finding refuses and is named by WHERE it was found and which rule
+ * fired — never by the value, because the refusal is printed and stored.
+ */
+import { CREDENTIAL_RULES, detect } from './egress_rules.js';
+
+export type PayloadPart = 'branch' | 'commit' | 'object' | 'title' | 'body';
+
+export interface ReleasePayload {
+    branch: string;
+    /** Every commit object the push adds, raw: tree, parents, identities, message. */
+    commits: string;
+    /** Every tree and blob the push adds: its path and, for a blob, its whole content. */
+    objects: string;
+    title: string;
+    body: string;
+}
+
+export interface PayloadFinding {
+    part: PayloadPart;
+    rule: string;
+}
+
+function escapeRegExp(s: string): string {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * The consumer's identifiers minus every token of the target repository: a
+ * fix to this package names this package, and refusing on that would refuse
+ * every release made from the package's own checkout.
+ */
+export function consumerDenyList(identifiers: Iterable<string>, targetRepo: string): string[] {
+    const own = new Set<string>();
+    for (const part of targetRepo.toLowerCase().split('/')) {
+        own.add(part);
+        for (const sub of part.split('-')) {
+            own.add(sub);
+        }
+    }
+    return [...new Set([...identifiers].map((i) => i.trim()).filter((i) => i.length > 0))]
+        .filter((i) => !own.has(i.toLowerCase()))
+        .sort();
+}
+
+export function scanPayload(payload: ReleasePayload, deny: readonly string[]): PayloadFinding[] {
+    const denyRes = deny.map((ident) => ({
+        rule: 'consumer-identifier',
+        re: new RegExp(`(?<![A-Za-z0-9])${escapeRegExp(ident)}(?![A-Za-z0-9])`, 'i'),
+    }));
+    const findings: PayloadFinding[] = [];
+    const parts: Array<[PayloadPart, string]> = [
+        ['branch', payload.branch],
+        ['commit', payload.commits],
+        ['object', payload.objects],
+        ['title', payload.title],
+        ['body', payload.body],
+    ];
+    for (const [part, text] of parts) {
+        const rules = new Set<string>();
+        for (const span of detect(text, CREDENTIAL_RULES)) {
+            rules.add(span.rule);
+        }
+        for (const d of denyRes) {
+            if (d.re.test(text)) {
+                rules.add(d.rule);
+            }
+        }
+        for (const rule of [...rules].sort()) {
+            findings.push({ part, rule });
+        }
+    }
+    return findings;
+}
+
+export function describeFindings(findings: readonly PayloadFinding[]): string {
+    const named = findings.map((f) => `${f.rule} in ${f.part}`).join(', ');
+    return `payload floor refused the pull request (${named}) — nothing was pushed`;
+}

package/src/scripts/_lib/session_eol.ts

@@ -28,6 +28,9 @@
  * `scanEolSlice` accepts prior counters and only the newly appended complete
  * lines (`readNewCompleteLines`). A full rescan is only ever the bounded
  * 50 MB `isSafeTranscriptPath` cap away.
+ *
+ * loss_class: recoverable-lossy
+ * loss_recovery: the transcript JSONL itself — `readNewCompleteLines` returns only the bytes after `fromByte`, cut at the last complete line, and the rest stays in the file at its byte offsets.
  */
 
 import * as crypto from 'node:crypto';

package/src/scripts/_lib/session_pr_watch.ts

@@ -0,0 +1,207 @@
+/**
+ * The live state of the pull requests THIS session opened, carried into every
+ * prompt — so a session never reports a PR as waiting after it merged.
+ *
+ * Measured 2026-10-20: a session told the owner "#2534 waits for you" an hour
+ * after the owner had merged it. The state it reported was the one it saw when
+ * it opened the PR; nothing told a running session that a PR changed state, and
+ * the live-state rule that forbids answering from memory is model-carried. This
+ * module is the carrier: the `pr-url-reminder` concern records a PR the moment
+ * `gh pr create` prints its URL, and the `session-register` concern's
+ * `user_prompt_submit` beat re-reads the recorded PRs and injects their state.
+ *
+ * - **Store:** `<git-common-dir>/agent-session-prs/<session>.json`, one file per
+ *   session and one writer each, shared by every worktree of the repo.
+ * - **Throttle:** at most one `gh` call per {@link PROBE_INTERVAL_MS}, one GraphQL
+ *   query for every tracked PR at once, bounded by {@link PROBE_TIMEOUT_MS}.
+ *   Between probes the block repeats the last reading with its time, so a stale
+ *   reading is labelled stale rather than passed off as live.
+ * - **Lifetime:** a merged or closed PR is reported once more, as a change, and
+ *   then dropped; the block disappears when nothing open is tracked.
+ * - **Failure:** an unreachable `gh` keeps the last reading and says the probe
+ *   failed. Never throws, never blocks.
+ * - **What reaches the model from GitHub:** a state coerced to four enum values,
+ *   and a merge time that must read as an ISO timestamp after `sanitize_text`,
+ *   else it is dropped. No other remote byte is emitted.
+ */
+
+import { execFileSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { write_atomic } from './fs_atomic.js';
+import { git_common_dir } from './git_common_dir.js';
+import { sanitize_text } from './retrieval_sanitize.js';
+import { safe_stem } from './session_register.js';
+
+export const PROBE_INTERVAL_MS = 5 * 60 * 1000;
+export const PROBE_TIMEOUT_MS = 8_000;
+const MAX_TRACKED = 10;
+const STORE_DIRNAME = 'agent-session-prs';
+
+export type PrState = 'OPEN' | 'MERGED' | 'CLOSED' | 'UNKNOWN';
+
+export interface TrackedPr {
+    number: number;
+    url: string;
+    state: PrState;
+    /** Set when the last probe saw a state different from the one before it, until reported. */
+    changed_from?: PrState;
+    merged_at?: string | null;
+}
+
+export interface PrStore {
+    prs: TrackedPr[];
+    /** ISO time of the last probe attempt; absent before the first. */
+    probed_at?: string;
+    probe_failed?: boolean;
+}
+
+/** `{number: {state, mergedAt}}` for the asked numbers, or null when unreadable. */
+export type PrProbe = (cwd: string, numbers: readonly number[]) => Record<number, { state: PrState; merged_at: string | null }> | null;
+
+function store_file(root: string, session_id: string): string | null {
+    const common = git_common_dir(root);
+    return common === null ? null : path.join(common, STORE_DIRNAME, `${safe_stem(session_id)}.json`);
+}
+
+export function read_store(root: string, session_id: string): PrStore {
+    const file = store_file(root, session_id);
+    if (file === null) return { prs: [] };
+    try {
+        const o = JSON.parse(fs.readFileSync(file, 'utf-8')) as PrStore;
+        return Array.isArray(o.prs) ? o : { prs: [] };
+    } catch {
+        return { prs: [] };
+    }
+}
+
+function write_store(root: string, session_id: string, store: PrStore): void {
+    const file = store_file(root, session_id);
+    if (file === null) return;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    write_atomic(file, `${JSON.stringify(store, null, 2)}\n`);
+}
+
+/** Record a PR this session created. Idempotent per number. */
+/** `owner/repo` of the repository's `origin`, lower-cased, or null when it cannot be read. */
+function origin_slug(root: string): string | null {
+    try {
+        const url = execFileSync('git', ['-C', root, 'config', '--get', 'remote.origin.url'], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        const m = /[/:]([^/:]+)\/([^/]+?)(?:\.git)?\/?$/.exec(url);
+        return m === null ? null : `${m[1]}/${m[2]}`.toLowerCase();
+    } catch {
+        return null;
+    }
+}
+
+export function record_pr(root: string, session_id: string, url: string): void {
+    const m = /\/([^/]+)\/([^/]+)\/pull\/(\d+)/.exec(url);
+    if (m === null || session_id === '') return;
+    // The probe asks for a PR NUMBER in this repository: a PR of another repo
+    // or a fork would be read as whatever this repo's PR of that number is.
+    const here = origin_slug(root);
+    if (here !== null && `${m[1]}/${m[2]}`.toLowerCase() !== here) return;
+    const number = Number.parseInt(m[3] ?? '', 10);
+    const store = read_store(root, session_id);
+    if (store.prs.some((p) => p.number === number)) return;
+    store.prs = [...store.prs, { number, url, state: 'OPEN' as PrState }].slice(-MAX_TRACKED);
+    // A new PR should be read on the next prompt, not after the throttle window.
+    delete store.probed_at;
+    write_store(root, session_id, store);
+}
+
+const ISO_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;
+
+function iso_or_null(v: unknown): string | null {
+    if (typeof v !== 'string') return null;
+    const clean = sanitize_text(v);
+    return ISO_RE.test(clean) ? clean : null;
+}
+
+export const gh_probe: PrProbe = (cwd, numbers) => {
+    const fields = numbers.map((n) => `p${n}: pullRequest(number: ${n}) { state mergedAt }`).join(' ');
+    const query = `query($owner: String!, $repo: String!) { repository(owner: $owner, name: $repo) { ${fields} } }`;
+    try {
+        const out = execFileSync(
+            'gh',
+            ['api', 'graphql', '-f', `query=${query}`, '-F', 'owner={owner}', '-F', 'repo={repo}'],
+            { cwd, encoding: 'utf-8', timeout: PROBE_TIMEOUT_MS, stdio: ['ignore', 'pipe', 'ignore'] },
+        );
+        const repo = (JSON.parse(out) as { data?: { repository?: Record<string, { state?: string; mergedAt?: string | null } | null> } })
+            .data?.repository;
+        if (repo === undefined) return null;
+        const res: Record<number, { state: PrState; merged_at: string | null }> = {};
+        for (const n of numbers) {
+            const pr = repo[`p${n}`];
+            const s = pr?.state;
+            res[n] = {
+                state: s === 'OPEN' || s === 'MERGED' || s === 'CLOSED' ? s : 'UNKNOWN',
+                merged_at: iso_or_null(pr?.mergedAt),
+            };
+        }
+        return res;
+    } catch {
+        return null;
+    }
+};
+
+function hhmm(iso: string): string {
+    return iso.slice(11, 16);
+}
+
+/**
+ * Probe when the throttle allows, persist, and render the block. `null` when
+ * this session tracks no PR. Never throws.
+ */
+export function pr_watch_block(
+    root: string,
+    session_id: string,
+    now: Date = new Date(),
+    probe: PrProbe = gh_probe,
+): string | null {
+    try {
+        const store = read_store(root, session_id);
+        if (store.prs.length === 0) return null;
+        const last = store.probed_at === undefined ? Number.NaN : Date.parse(store.probed_at);
+        if (!(now.getTime() - last < PROBE_INTERVAL_MS)) {
+            const live = probe(root, store.prs.map((p) => p.number));
+            store.probed_at = now.toISOString();
+            store.probe_failed = live === null;
+            if (live !== null) {
+                for (const p of store.prs) {
+                    const got = live[p.number];
+                    if (got === undefined) continue;
+                    if (got.state !== p.state) p.changed_from = p.state;
+                    p.state = got.state;
+                    p.merged_at = got.merged_at;
+                }
+            }
+        }
+        const lines = store.prs.map((p) => {
+            const change = p.changed_from !== undefined ? `  ← CHANGED from ${p.changed_from}` : '';
+            const when = p.state === 'MERGED' && p.merged_at ? ` at ${p.merged_at}` : '';
+            return `- #${p.number} ${p.state}${when}${change}`;
+        });
+        const asOf = store.probed_at === undefined ? 'never read' : `read ${hhmm(store.probed_at)} UTC`;
+        const block = [
+            '<session-prs>',
+            `Pull requests this session opened (${asOf}${store.probe_failed ? ', the last read FAILED — state unverified' : ''}):`,
+            ...lines,
+            'State them from this block, or run `gh pr view <n>` first — never from memory.',
+            'A merged PR waits for nobody.',
+            '</session-prs>',
+        ].join('\n');
+        // Every change is in the block just rendered; keep only what can still change.
+        store.prs = store.prs
+            .filter((p) => p.state === 'OPEN' || p.state === 'UNKNOWN')
+            .map(({ changed_from: _reported, ...rest }) => rest);
+        write_store(root, session_id, store);
+        return block;
+    } catch {
+        return null;
+    }
+}