create-egregore 0.21.6 → 0.22.0

package/runtime/pi/bin/lib/greeting.sh

@@ -18,6 +18,205 @@
 #          HEALTH_*, FRAMEWORK_VERSION, TIME_OF_DAY, EGREGORE_SESSION_ID,
 #          FIRST_SESSION, DISPLAY_NAME_STATE, DASHBOARD_URL
 
+# Session records reuse the index refreshed by the detached sweep.
+# No transcript is opened by a greeting.
+# Personal controls always win over the organization default.
+_print_session_records() {
+  [ -n "${HOME:-}" ] || return 0
+  command -v python3 >/dev/null 2>&1 || return 0
+  python3 - "${CONFIG:-$SCRIPT_DIR/egregore.json}" "$STATE_FILE" "$SCRIPT_DIR" \
+    "${EGREGORE_MEMORY_ROOT:-$SCRIPT_DIR/memory}" "${AUTHOR:-}" <<'RECORDS_PY' 2>/dev/null || true
+import datetime as dt
+import json
+import os
+from pathlib import Path
+import re
+import stat
+import sys
+
+config_path, state_path, project_root, memory_root, fallback_author = sys.argv[1:]
+def read_json(path):
+    try:
+        value = json.loads(Path(path).read_text())
+        return value if isinstance(value, dict) else {}
+    except (OSError, ValueError):
+        return {}
+
+config = read_json(config_path)
+policy = config.get("features", {}).get("session_records", {})
+if not isinstance(policy, dict) or policy.get("enabled") is not True:
+    raise SystemExit(0)
+state = read_json(state_path)
+author = state.get("github_username", fallback_author)
+sys.path.insert(0, str(Path(project_root) / "bin" / "lib"))
+try:
+    from session_trail import instance_prefix, valid_trail_folder
+    from session_record import collect_digest, metadata, sessions_directory, classify_record, Context, native_record_reader
+except ImportError:
+    raise SystemExit(0)
+prefix = instance_prefix(project_root)
+projects = Path(os.environ["HOME"]) / ".claude" / "projects"
+trail_root = Path(os.environ["HOME"]) / ".egregore" / "trails" / prefix
+cache = {}
+cache_path = trail_root / "index.json"
+try:
+    if (valid_trail_folder(trail_root, projects, prefix)
+            and stat.S_ISREG(cache_path.lstat().st_mode)
+            and cache_path.resolve().is_relative_to(trail_root.resolve())):
+        cache = read_json(cache_path)
+except OSError:
+    pass
+today = dt.datetime.now().astimezone().date()
+
+def clean(value):
+    return re.sub(r"[\x00-\x1f\x7f]", " ", str(value)).strip()
+
+def header(text, name):
+    match = re.search(r"^\*\*" + re.escape(name) + r"\*\*:\s*(.*)$", text, re.M)
+    return match.group(1).strip() if match else ""
+
+def frontmatter(text, name):
+    match = re.search(r"^" + re.escape(name) + r":\s*(.*)$", text.partition("\n---")[0], re.M)
+    return match.group(1).strip().strip('"\'') if match else ""
+
+def bullets(text, name):
+    match = re.search(r"^## " + re.escape(name) + r"\s*\n(.*?)(?=^## |\Z)", text, re.M | re.S)
+    return len(re.findall(r"^\s*[-*]\s+", match.group(1), re.M)) if match else 0
+
+records = []
+digest_records = []
+recorded_ids = set()
+scanned = 0
+# Month filenames sort chronologically; a bounded newest-first scan keeps the
+# greeting predictable even when an organization has years of sessions.
+sessions_root = sessions_directory(memory_root)
+try:
+    months = sorted((p for p in sessions_root.iterdir()
+                     if stat.S_ISDIR(p.lstat().st_mode)
+                     and p.resolve().is_relative_to(sessions_root)), reverse=True)[:120] if sessions_root else []
+except OSError:
+    months = []
+for month in months:
+    try:
+        paths = sorted(month.glob("*.md"), reverse=True)
+    except OSError:
+        continue
+    for path in paths[:2000 - scanned]:
+        scanned += 1
+        try:
+            if not stat.S_ISREG(path.lstat().st_mode) or not path.resolve().is_relative_to(sessions_root):
+                continue
+            with path.open() as source:
+                text = source.read(131072)
+        except (OSError, UnicodeError):
+            continue
+        if frontmatter(text, "kind") != "session-record":
+            continue
+        if state.get("session_records_noticed") is True:
+            digest_records.append((path, metadata(text), text))
+        if classify_record(metadata(text)) != "human-session":
+            continue
+        date = header(text, "Date") or frontmatter(text, "date")
+        owner = header(text, "Author") or frontmatter(text, "from")
+        session_id = header(text, "Session") or frontmatter(text, "session")
+        if session_id:
+            recorded_ids.add(session_id)
+        topic = frontmatter(text, "topic")
+        if not topic:
+            title = re.search(r"^# (?:Session: )?(.*)$", text, re.M)
+            topic = title.group(1) if title else "session"
+        commits = re.search(r"\b(\d+) commits\b", text)
+        records.append({"date": date, "author": owner, "topic": topic,
+                        "duration": header(text, "Duration") or frontmatter(text, "duration") or "unknown",
+                        "commits": int(commits.group(1)) if commits else 0,
+                        "decisions": bullets(text, "Decided"), "open": bullets(text, "Open")})
+    if scanned >= 2000:
+        break
+
+if state.get("session_records_noticed") is True:
+    # Open items are carried by the reflex line under this block
+    # (bin/reflexes/10-open-items.sh), so the digest skips the carry here.
+    has_native = any(classify_record(meta) != "human-session" for _, meta, _ in digest_records)
+    actor_id, reader = native_record_reader(Context(project_root)) if has_native else ("", None)
+    digest = collect_digest(memory_root, author=author, person=state.get("display_name", ""),
+                            days=1, today=today, records=digest_records, carry_days=0,
+                            actor_id=actor_id, native_reader=reader)
+    if digest["sessions"]:
+        print(f"  ◦ records · yesterday {digest['sessions']} ({digest['yours']} yours) · {len(digest['decided'])} decided · {len(digest['open'])} open · /records digest")
+        def short(value, limit):
+            value = clean(value)
+            return value if len(value) <= limit else value[:limit - 1] + "…"
+        def preview(line, who):
+            suffix = " — " + short(who, 40)
+            print("    - " + short(line, 120 - 6 - len(suffix)) + suffix)
+        for item in digest["decided"][:3]:
+            preview(item["line"], item["who"])
+    if digest["spirit_intents"]:
+        noun = "intent" if digest["spirit_intents"] == 1 else "intents"
+        print(f"  ◦ spirit records · {digest['spirit_intents']} {noun} ({digest['your_spirit_intents']} yours) · partial coverage · /records digest")
+    if digest["unsupported_native"]:
+        print(f"  ◦ {digest['unsupported_native']} unsupported spirit records · metadata unavailable")
+    if digest["held_records"]:
+        print(f"  ◦ {digest['held_records']} held records · details withheld")
+    if cache.get("waiting_push"):
+        print("  ◦ 1 records commit is waiting to push · /records status --push")
+    raise SystemExit(0)
+
+decider = clean(policy.get("decided_by", "your organization"))
+decided_on = clean(policy.get("decided_on", ""))
+personal_names = {str(value).casefold() for value in (author, state.get("display_name", "")) if value}
+if str(policy.get("decided_by", "")).casefold() in personal_names:
+    print(f"◇ Session records are on for {clean(config.get('github_org', ''))}/{clean(config.get('repo_name', 'egregore'))} · your decision, {decided_on}")
+else:
+    print(f"◇ Session records are new · {decider} turned them on for this egregore on {decided_on}")
+if state.get("session_records_enabled") is False:
+    print("  Your session records are off. /records on turns them back on.")
+else:
+    print("  Each session now leaves a record in memory/sessions: asked, decided, left open,")
+    print("  touched, cost. Asks are paraphrased, never quoted. The full trail stays on this")
+    model_on = policy.get("model", "haiku") != "none" and state.get("session_records_model_call") is not False
+    if model_on:
+        print("  machine as a file; your own Claude account reads it once to write the outline,")
+        print('  through the Claude service. Say "off the record" in any session to hold it.')
+    else:
+        print('  machine. Say "off the record" in any session to hold it.')
+    print("  /records changes yours.")
+    if "unrecorded_count" in cache:
+        count = int(cache.get("unrecorded_count", 0))
+        try:
+            days = max(0, (today - dt.date.fromisoformat(cache["oldest_date"][:10])).days)
+        except (KeyError, TypeError, ValueError):
+            days = int(cache.get("days", 0))
+    if records:
+        newest = max(records, key=lambda row: row["date"])
+        if newest["author"] != author:
+            print(f"  Here is one of {clean(newest['author'])}'s: {clean(newest['date'][:10])} · {clean(newest['topic'])} · {clean(newest['duration'])} · {newest['commits']} commits · {newest['decisions']} decisions · {newest['open']} open items")
+    if "unrecorded_count" in cache:
+        print(f"  {count} past sessions of yours are still on this machine ({days} days). Record them?")
+        print("  y · show one · no")
+    else:
+        print("  Past sessions are being counted. The count appears at your next start.")
+if cache.get("waiting_push"):
+    print("  ◦ 1 records commit is waiting to push · /records status --push")
+RECORDS_PY
+}
+
+# The reflexes: probes in bin/reflexes/ that each print a fact about
+# yesterday, or nothing. One runner, fail-soft, shared by every startup card.
+# See bin/reflexes/README.md.
+_print_reflexes() {
+  [ -f "$SCRIPT_DIR/bin/reflexes.sh" ] || return 0
+  bash "$SCRIPT_DIR/bin/reflexes.sh" \
+    --memory "${EGREGORE_MEMORY_ROOT:-$SCRIPT_DIR/memory}" \
+    --author "${AUTHOR:-}" --harness "${EGREGORE_HARNESS:-claude}" 2>/dev/null || true
+}
+
+# Other startup cards reuse this records block without rendering the Claude
+# greeting or running its surrounding notices and bookkeeping.
+if [ "${EGREGORE_GREETING_RECORDS_ONLY:-}" = "1" ]; then
+  return 0
+fi
+
 # --- Output greeting for Claude to display ---
 cat << 'GREETING'
 
@@ -115,6 +314,10 @@ if [ -n "${SETTINGS_POSTURE_HELD:-}" ]; then
   echo "  ◇ boundary posture was set to ${SETTINGS_POSTURE_HELD} elsewhere — relaxing access needs your confirm: bash bin/settings.sh posture ${SETTINGS_POSTURE_HELD}"
 fi
 
+
+_print_session_records
+_print_reflexes
+
 # --- Footer: health + repos + memory (tertiary) ---
 echo "$SEPARATOR"
 
@@ -126,7 +329,7 @@ _render_health_footer || true
 # Runtime update summary — cached durable state only, never a live probe, so
 # session start stays fast. One compact line; silent when nothing is staged.
 # Keyed by stable org identity composed with the main installation path
-# (mirrors egregore_runtime.upgrade.instance_key); no org_id → no summary.
+# (mirrors egregore_runtime.installation.installation_key); no org_id → no summary.
 _UPGRADE_ORG=$(jq -r '.org_id // empty' "$SCRIPT_DIR/egregore.json" 2>/dev/null)
 _UPGRADE_MAIN=$(cd "${MAIN_PROJECT_DIR:-$SCRIPT_DIR}" 2>/dev/null && pwd -P || true)
 if [ -n "$_UPGRADE_ORG" ] && [ -n "$_UPGRADE_MAIN" ]; then
@@ -372,6 +575,43 @@ if [ "$ALIAS_VERSION" -lt 2 ] 2>/dev/null; then
   fi
 fi
 
+# --- Card close: first-session welcome or tutorial tip (visible) ---
+# Everything the user should see renders before the hidden context below, so
+# a harness that displays the card directly (bin/lib/card-delivery.sh) shows
+# all of it. In that mode the card also asks the opening question itself,
+# the same way bin/codex-session-start.sh ends the Codex and Pi card.
+if [ -z "$FIRST_SESSION" ] && [ -f "$STATE_FILE" ]; then
+  FIRST_SESSION=$(jq -r '.first_session // false' "$STATE_FILE" 2>/dev/null)
+fi
+
+if [ "$FIRST_SESSION" = "true" ]; then
+  echo ""
+  echo "  Welcome! This is your first session."
+  if [ "${EGREGORE_CARD_DELIVERY:-text}" = "harness" ]; then
+    echo ""
+    echo "  Want a quick tour first (/onboarding), or jump straight in?"
+  fi
+  # Clear the flag so it only shows once
+  jq '.first_session = false' "$STATE_FILE" > "$STATE_FILE.tmp" && mv "$STATE_FILE.tmp" "$STATE_FILE"
+else
+  # --- Tutorial tip (if onboarding done but tutorial not) ---
+  TUTORIAL_COMPLETE="true"
+  if [ -f "$STATE_FILE" ]; then
+    TUTORIAL_COMPLETE=$(jq -r '.tutorial_complete // false' "$STATE_FILE" 2>/dev/null || echo "true")
+  fi
+
+  if [ "$TUTORIAL_COMPLETE" != "true" ]; then
+    # A tip that has not been acted on after a few sessions is noise; the
+    # ledger retires it after NOTICE_TIP_MAX showings.
+    _notice tutorial-tip tip "tutorial" "tutorial" "  Tip: Run /tutorial to learn the core loop."
+  fi
+  _notice_flush
+  if [ "${EGREGORE_CARD_DELIVERY:-text}" = "harness" ]; then
+    echo ""
+    echo "  What are you working on?"
+  fi
+fi
+
 echo ""
 
 # --- Session context (hidden, for Claude) ---
@@ -487,34 +727,21 @@ bash "$SCRIPT_DIR/bin/startup-check.sh" >/dev/null 2>&1 &
 # Clean up temp files
 rm -rf "$CTX_DIR"
 
-# --- First session welcome ---
-if [ -z "$FIRST_SESSION" ] && [ -f "$STATE_FILE" ]; then
-  FIRST_SESSION=$(jq -r '.first_session // false' "$STATE_FILE" 2>/dev/null)
-fi
-
-if [ "$FIRST_SESSION" = "true" ]; then
-  echo ""
-  echo "  Welcome! This is your first session."
-  echo ""
+# --- Instruction for the model ---
+# Harness delivery: the user already sees the scripted card, question
+# included, so the model must not retype it. Text delivery (a harness that
+# cannot display hook output directly) keeps the display instruction. The
+# branch rule that used to follow is gone: CLAUDE.md's "Before Project
+# Changes" section is the one branching contract.
+echo ""
+if [ "${EGREGORE_CARD_DELIVERY:-text}" = "harness" ]; then
+  if [ "$FIRST_SESSION" = "true" ]; then
+    echo "STARTUP CARD: The harness has already shown the user the startup card above, ending with an offer of a quick tour (/onboarding). Do not reprint, summarize, or narrate it. Treat the user's first message as their answer."
+  else
+    echo "STARTUP CARD: The harness has already shown the user the startup card above, ending with \"What are you working on?\". Do not reprint, summarize, or narrate it. Treat the user's first message as the answer. If it carries no request (the launcher submits \`start\` automatically), reply with one short line and no tool calls."
+  fi
+elif [ "$FIRST_SESSION" = "true" ]; then
   echo "IMPORTANT: Display the above greeting exactly as-is (ASCII art + ornamented status). Then ask the user if they'd like a quick onboarding tour (run /onboarding), or if they want to jump straight in."
-  # Clear the flag so it only shows once
-  jq '.first_session = false' "$STATE_FILE" > "$STATE_FILE.tmp" && mv "$STATE_FILE.tmp" "$STATE_FILE"
 else
-  # --- Tutorial tip (if onboarding done but tutorial not) ---
-  TUTORIAL_COMPLETE="true"
-  if [ -f "$STATE_FILE" ]; then
-    TUTORIAL_COMPLETE=$(jq -r '.tutorial_complete // false' "$STATE_FILE" 2>/dev/null || echo "true")
-  fi
-
-  if [ "$TUTORIAL_COMPLETE" != "true" ]; then
-    # A tip that has not been acted on after a few sessions is noise; the
-    # ledger retires it after NOTICE_TIP_MAX showings.
-    _notice tutorial-tip tip "tutorial" "tutorial" "  Tip: Run /tutorial to learn the core loop."
-  fi
-  _notice_flush
-
-  echo ""
   echo "IMPORTANT: Display the above greeting to the user exactly as-is (preserve the ASCII art formatting and ornamented status) on their first message. Then ask: What are you working on?"
-  echo ""
-  echo "BRANCH RULE: When the user responds with what they're working on, your FIRST action is to create a working branch: git fetch origin $BASE_BRANCH --quiet && git checkout --no-track -b dev/{author}/{topic-slug} origin/$BASE_BRANCH. Do this BEFORE any other work. Derive the topic slug from their description. If they ask a pure question with no work intent, skip branching."
 fi

package/runtime/pi/bin/lib/handoff_meta.py

@@ -0,0 +1,294 @@
+#!/usr/bin/env python3
+"""Handoff metadata for many files in one process.
+
+bin/lib/handoff-meta.sh extracts a handoff's author, topic and date with a
+grep | sed | xargs pipeline per field, and the startup gather of handoffs
+addressed to the user added an awk, a read loop and a jq per file: over a
+hundred processes for five handoffs. This module reads each file once and
+reproduces those pipelines' results, including xargs' quote and whitespace
+handling and the echo it runs, so the files the gather writes are
+unchanged.
+
+    handoff_meta.py addressed NAMES_OUT RICH_OUT [FILE...]
+
+writes the gather's two files: NAMES_OUT holds the handoff names, RICH_OUT
+their author, topic, date and Repo State table rows. bin/tests/
+test-handoff-metadata.sh holds this module to the shell functions.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+
+# POSIX [[:space:]]. On macOS, sed in a UTF-8 locale also counts Unicode
+# spaces (a no-break space after "**Author**:" is stripped there).
+_ASCII_SPACE = frozenset(" \t\n\v\f\r")
+_DARWIN = sys.platform == "darwin"
+
+
+def _is_space(character: str) -> bool:
+    return character in _ASCII_SPACE or (_DARWIN and character.isspace())
+
+
+def _lstrip_space(text: str) -> str:
+    position = 0
+    while position < len(text) and _is_space(text[position]):
+        position += 1
+    return text[position:]
+
+
+def _echo_operands(arguments: list[str]) -> list[str]:
+    """What /bin/echo prints of its arguments, as xargs runs it."""
+    if _DARWIN:
+        # FreeBSD echo: only an exact first "-n" is an option, and a "\c"
+        # ending the last argument is dropped with the newline.
+        if arguments and arguments[0] == "-n":
+            arguments = arguments[1:]
+        if arguments and arguments[-1].endswith("\\c"):
+            arguments = [*arguments[:-1], arguments[-1][:-2]]
+        return arguments
+    # GNU echo: leading arguments made only of n, e and E are options.
+    while arguments and re.fullmatch(r"-[neE]+", arguments[0]):
+        arguments = arguments[1:]
+    return arguments
+
+
+def _xargs(text: str) -> str:
+    """`printf '%s\\n' "$text" | xargs`, as captured by $(...).
+
+    Blanks and newlines separate arguments, quotes group them, a backslash
+    outside quotes escapes the next character, and an unterminated quote
+    makes xargs fail before running echo.
+    """
+    arguments: list[str] = []
+    argument: list[str] = []
+    started = False
+    quote = ""
+    characters = iter(text + "\n")
+    for character in characters:
+        if quote:
+            if character == quote:
+                quote = ""
+            elif character == "\n":
+                return ""
+            else:
+                argument.append(character)
+            continue
+        if character in " \t\n":
+            if started:
+                arguments.append("".join(argument))
+                argument, started = [], False
+            continue
+        started = True
+        if character in "'\"":
+            quote = character
+        elif character == "\\":
+            escaped = next(characters, None)
+            if escaped is None:
+                break
+            argument.append(escaped)
+        else:
+            argument.append(character)
+    if quote:
+        return ""
+    if started:
+        arguments.append("".join(argument))
+    return " ".join(_echo_operands(arguments)).rstrip("\n")
+
+
+def _bash_echo(value: str) -> str:
+    """`echo "$value"` in bash: an argument of only n, e and E is an option."""
+    return "" if re.fullmatch(r"-[neE]+", value) else value
+
+
+def _first(lines: list[str], prefix: str) -> str | None:
+    return next((line for line in lines if line.startswith(prefix)), None)
+
+
+def _after(lines: list[str], prefix: str) -> str:
+    """grep -m1 "^prefix" | sed "s/^prefix[[:space:]]*//" | xargs"""
+    line = _first(lines, prefix)
+    return "" if line is None else _xargs(_lstrip_space(line[len(prefix):]))
+
+
+def _markdown_field(lines: list[str], key: str) -> str:
+    return _after(lines, f"**{key}**:") or _after(lines, f"**{key}:**")
+
+
+def _yaml_field(lines: list[str], key: str) -> str:
+    # sed -n '/^---$/,/^---$/p' prints every such range, not only the first.
+    inside = False
+    ranged: list[str] = []
+    for line in lines:
+        if inside:
+            ranged.append(line)
+            inside = line != "---"
+        elif line == "---":
+            ranged.append(line)
+            inside = True
+    line = _first(ranged, f"{key}:")
+    if line is None:
+        return ""
+    value = _lstrip_space(line[len(key) + 1:])
+    for mark in ('"', "'"):
+        value = value[1:] if value.startswith(mark) else value
+        value = value[:-1] if value.endswith(mark) else value
+    return _xargs(value)
+
+
+def _name(path: str) -> str:
+    name = os.path.basename(path)
+    return name[:-3] if name.endswith(".md") and name != ".md" else name
+
+
+def _author_from_filename(path: str) -> str:
+    match = re.match(r"[0-9]{2}-([^-]+)-", _name(path)) or re.match(
+        r"[0-9]{4}-[0-9]{2}-[0-9]{2}-([^-]+)-", _name(path)
+    )
+    return match.group(1) if match else ""
+
+
+def _date_from_filename(path: str) -> str:
+    name = _name(path)
+    directory = os.path.basename(os.path.dirname(path))
+    day = re.match(r"([0-9]{2})-", name)
+    if re.fullmatch(r"[0-9]{4}-[0-9]{2}", directory) and day:
+        return f"{directory}-{day.group(1)}"
+    dated = re.match(r"([0-9]{4}-[0-9]{2}-[0-9]{2})-", name)
+    return dated.group(1) if dated else ""
+
+
+def author(lines: list[str], path: str) -> str:
+    found = (
+        _markdown_field(lines, "Author")
+        or _markdown_field(lines, "From")
+        or _after(lines, "From:")
+        or _yaml_field(lines, "author")
+        or _yaml_field(lines, "from")
+        or _author_from_filename(path)
+    )
+    # sed 's/[[:space:]]*→.*//'
+    arrow = found.find("→")
+    if arrow >= 0:
+        while arrow > 0 and _is_space(found[arrow - 1]):
+            arrow -= 1
+        found = found[:arrow]
+    return _xargs(found)
+
+
+def topic(lines: list[str]) -> str:
+    heading = _first(lines, "# ")
+    found = ""
+    if heading is not None:
+        text = heading[2:]
+        if text.startswith("Handoff:"):
+            text = _lstrip_space(text[len("Handoff:"):])
+        found = _xargs(text)
+    return found or _yaml_field(lines, "topic")
+
+
+def date(lines: list[str], path: str) -> str:
+    return (
+        _markdown_field(lines, "Date")
+        or _after(lines, "Date:")
+        or _yaml_field(lines, "date")
+        or _date_from_filename(path)
+    )
+
+
+def _json_string(value: str) -> str:
+    # jq's compact output: raw UTF-8, with DEL escaped as well.
+    return json.dumps(value, ensure_ascii=False).replace("\x7f", "\\u007f")
+
+
+def _cell(fields: list[str], position: int) -> str:
+    return _xargs(_bash_echo(fields[position] if position < len(fields) else ""))
+
+
+def repo_state(lines: list[str]) -> str:
+    """The `## Repo State` table as the JSON array the gather builds.
+
+    Each row was printed into JSON text and parsed with `jq -s`, so a cell
+    jq could not parse empties the whole table, as it did there.
+    """
+    rows: list[str] = []
+    found = False
+    for line in lines:
+        if line.startswith("## Repo State"):
+            found = True
+            continue
+        if not found:
+            continue
+        if line.startswith("#"):
+            break
+        if len(line) > 1 and line[0] == "|" and line[1] != "-" and not line.startswith("| Repo"):
+            rows.append(line)
+    entries: list[str] = []
+    for row in rows:
+        fields = row.split("|")
+        repository, branch, base = _cell(fields, 1), _cell(fields, 2), _cell(fields, 4)
+        pull = _cell(fields, 3)
+        pull = (pull[1:] if pull.startswith("#") else pull).replace("—", "", 1)
+        if not repository:
+            continue
+        number = "null"
+        if re.fullmatch(r"[+-]?[0-9]+", pull) and -(2**63) <= int(pull) < 2**63:
+            number = ("-" if pull.startswith("-") else "") + (pull.lstrip("+-").lstrip("0") or "0")
+        try:
+            text = [json.loads(f'"{value}"') for value in (repository, branch, base)]
+        except ValueError:
+            return "[]"
+        entries.append(
+            f'{{"repo":{_json_string(text[0])},"branch":{_json_string(text[1])},'
+            f'"pr":{number},"base":{_json_string(text[2])}}}'
+        )
+    return "[" + ",".join(entries) + "]"
+
+
+def _lines(path: str) -> list[str]:
+    try:
+        with open(path, "rb") as handle:
+            content = handle.read().decode("utf-8", errors="replace")
+    except OSError:
+        return []
+    lines = content.split("\n")
+    if lines and lines[-1] == "":
+        lines.pop()
+    return lines
+
+
+def addressed(paths: list[str]) -> tuple[str, str]:
+    names: list[str] = []
+    rich: list[str] = []
+    for path in paths:
+        lines = _lines(path)
+        name = _name(path)
+        names.append(f'"{name}"')
+        try:
+            entry = (
+                f'{{"name":{_json_string(name)},"author":{_json_string(author(lines, path))},'
+                f'"topic":{_json_string(topic(lines))},"date":{_json_string(date(lines, path))},'
+                f'"repoState":{repo_state(lines)}}}'
+            )
+        except Exception:  # one unreadable handoff keeps its place, not the list's
+            entry = f'{{"name":{_json_string(name)},"author":"","topic":"","date":"","repoState":[]}}'
+        rich.append(entry)
+    return "[" + ",".join(names) + "]", "[" + ",".join(rich) + "]"
+
+
+def main(arguments: list[str]) -> int:
+    if len(arguments) < 3 or arguments[0] != "addressed":
+        print("usage: handoff_meta.py addressed NAMES_OUT RICH_OUT [FILE...]", file=sys.stderr)
+        return 2
+    names, rich = addressed(arguments[3:])
+    for path, content in ((arguments[1], names), (arguments[2], rich)):
+        with open(path, "w", encoding="utf-8") as handle:
+            handle.write(content + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))