create-egregore 0.21.6 → 0.22.0

package/runtime/pi/bin/lib/health-footer.sh

@@ -22,6 +22,76 @@
 # Output: the footer lines on stdout, each already indented two spaces.
 # Returns 0 when nothing failed, 1 when at least one dimension failed.
 
+# Dated, release-delivered incident copy, not a live availability check. Keep
+# the launcher counterpart aligned; launcher-connected-status.test.js checks
+# the actual output of both implementations. No network or credential reads.
+_hosted_recovery_notice() {
+  [ "${LOCAL_MODE:-true}" != "true" ] || return 0
+  local origin now
+  [ -f "${CONFIG:-}" ] || return 0
+  origin=$(jq -r '.api_url // empty' "$CONFIG" 2>/dev/null) || return 0
+  case "$origin" in
+    https://api.egregore.xyz|https://api.egregore.xyz/|https://egregore-production-55f2.up.railway.app|https://egregore-production-55f2.up.railway.app/) ;;
+    *) return 0 ;;
+  esac
+  now=$(date -u +%s 2>/dev/null) || now=0
+  # A stale bundled notice never presents itself as current service status.
+  if [ "$now" -ge 1792627200 ] 2>/dev/null && [ "$now" -lt 1792800000 ] 2>/dev/null; then
+    printf '%s\n' '  ◐ Service recovery · 22 Oct 2026' \
+      '    Some connected services are temporarily unavailable' \
+      '    during security recovery.'
+  else
+    printf '%s\n' '  ◐ Service recovery · last update 22 Oct 2026' \
+      '    Some connected services were unavailable at this update.' \
+      '    Current hosted availability has not been checked.'
+  fi
+  printf '%s\n' '    Local memory and search remain available.' \
+    '    Keep your existing Egregore; you do not need to set it up again.'
+}
+
+# Recorded in .egregore-state.json by bin/runtime-identity.sh when it renews,
+# or cannot renew, an organization key retired in the October 2026 security
+# reset. Local state only; no network. The renewal shows once; the sign-in
+# line shows each session until a renewal works.
+_hosted_key_notice() {
+  [ "${LOCAL_MODE:-true}" != "true" ] || return 0
+  local state_file="${STATE_FILE:-}" file tmp
+  [ -n "$state_file" ] && [ -f "$state_file" ] || return 0
+  case "$(jq -r '.hosted_key_notice.state // empty' "$state_file" 2>/dev/null)" in
+    renewed)
+      printf '%s\n' "  ↻ Hosted services renewed this organization's key after" \
+        '    the October security reset. Your memory, files and' \
+        '    history are untouched.'
+      file=$(realpath "$state_file" 2>/dev/null) || file="$state_file"
+      tmp=$(mktemp "$file.XXXXXX" 2>/dev/null) || return 0
+      jq 'if .hosted_key_notice.state == "renewed" then del(.hosted_key_notice) else . end' \
+        "$file" > "$tmp" 2>/dev/null && [ -s "$tmp" ] && mv "$tmp" "$file" || rm -f "$tmp"
+      ;;
+    needs_sign_in)
+      printf '%s\n' '  ◐ Hosted services need a fresh key after the October' \
+        '    security reset. Your memory, files and history are' \
+        '    untouched. Run bash bin/github-auth.sh and start a new' \
+        '    session — it renews on its own.'
+      ;;
+  esac
+  return 0
+}
+
+# A Connected org whose saved api_url is not a plain web address sends nothing
+# to hosted services (bin/lib/config.sh refuses it), and /update rewrites only
+# a plain retired address. Say so each session until egregore.json is fixed.
+# Needs config.sh's resolver; reads local config only.
+_hosted_address_notice() {
+  [ "${LOCAL_MODE:-true}" != "true" ] || return 0
+  [ -f "${CONFIG:-}" ] || return 0
+  command -v _config_api_url >/dev/null 2>&1 || return 0
+  EGREGORE_ADDRESS_NOTICE=shown _config_api_url >/dev/null 2>&1 && return 0
+  printf '%s\n' "  ◐ Hosted services are off: api_url in egregore.json isn't" \
+    '    a plain web address, so nothing is sent to it. Correct it' \
+    "    (the hosted address is ${EGREGORE_HOSTED_API_ORIGIN:-https://api.egregore.xyz})" \
+    '    and start a new session. Local memory and search work.'
+}
+
 _health_footer_label() {
   case "$1" in
     github) printf 'github' ;;
@@ -65,7 +135,16 @@ _health_footer_check() {
 }
 
 _render_health_footer() {
-  local width="${LINE_WIDTH:-65}" failed=0
+  local width="${LINE_WIDTH:-65}" failed=0 recovery_notice key_notice address_notice local_only=""
+  address_notice=$(_hosted_address_notice)
+  [ -z "$address_notice" ] || { printf '%s\n' "$address_notice"; local_only=1; }
+  recovery_notice=$(_hosted_recovery_notice)
+  [ -z "$recovery_notice" ] || printf '%s\n' "$recovery_notice"
+  key_notice=$(_hosted_key_notice)
+  [ -z "$key_notice" ] || printf '%s\n' "$key_notice"
+  # Hosted services stay out of reach for this person until the key renews.
+  [ -z "$recovery_notice" ] || local_only=1
+  case "$key_notice" in *"need a fresh key"*) local_only=1 ;; esac
   _health_footer_check github "${HEALTH_GITHUB:-skip}" || failed=1
   _health_footer_check git "${HEALTH_GIT:-skip}" || failed=1
   _health_footer_check memory "${HEALTH_MEMORY:-skip}" || failed=1
@@ -87,7 +166,9 @@ _render_health_footer() {
   fi
 
   local left right pad
-  if [ "${FRAMEWORK_UPDATED:-false}" = "true" ]; then
+  if [ -n "$local_only" ]; then
+    left="  ✓ local checks ready"
+  elif [ "${FRAMEWORK_UPDATED:-false}" = "true" ]; then
     left="  ◆ updated"
   else
     left="  ✓ ready"

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

@@ -7,10 +7,12 @@
 #   3. Graph person lookup (existing team member on new machine)
 #   4. Global git config user.name (last resort)
 #
-# Inputs:  STATE_FILE, ENV_FILE, SCRIPT_DIR, HEALTH_GITHUB
+# Inputs:  STATE_FILE, ENV_FILE, SCRIPT_DIR, HEALTH_GITHUB; optionally
+#          EGREGORE_START_HARNESS with EGREGORE_NATIVE_SESSION_ID/_HARNESS
 # Outputs: AUTHOR, DISPLAY_NAME_STATE, FIRST_SESSION, HEALTH_GITHUB,
 #          EGREGORE_USER, EGREGORE_ORG, EGREGORE_SESSION_ID
-#          Writes .egregore-session-id and ~/.egregore/session-*.id
+#          Writes .egregore-session-id and ~/.egregore/session-*.id, and
+#          maps the native session id via bin/session-id.sh
 
 STORED_USERNAME=""
 FIRST_SESSION=""
@@ -192,16 +194,35 @@ fi
 # --- Export telemetry identity env vars ---
 export EGREGORE_USER="$AUTHOR"
 export EGREGORE_ORG="$(jq -r '.slug // .github_org // empty' "$SCRIPT_DIR/egregore.json" 2>/dev/null || true)"
-export EGREGORE_SESSION_ID="$(date -u +%Y%m%dT%H%M%S)-${AUTHOR}-$$"
-
-# Persist session ID to file so telemetry.sh can read it
-# (env vars from hooks don't propagate into the Claude Code agent)
 SESSION_ID_DIR="$HOME/.egregore"
 mkdir -p "$SESSION_ID_DIR"
-PROJ_HASH=$(echo -n "$SCRIPT_DIR" | md5 2>/dev/null || echo -n "$SCRIPT_DIR" | md5sum 2>/dev/null | cut -d' ' -f1)
-echo "$EGREGORE_SESSION_ID" > "$SESSION_ID_DIR/session-${PROJ_HASH}.id"
-# Also write project-local file (CLAUDE.md reads this — no glob needed)
-echo "$EGREGORE_SESSION_ID" > "$SCRIPT_DIR/.egregore-session-id"
+if [ -n "${_EGREGORE_REUSE_SESSION_ID:-}" ]; then
+  # Background refresh of a session the quick startup pass already identified
+  # (bin/lib/card-delivery.sh): keep its id, and leave the id files and the
+  # native mapping as that pass wrote them; a newer session may own them now.
+  export EGREGORE_SESSION_ID="$_EGREGORE_REUSE_SESSION_ID"
+  unset _EGREGORE_REUSE_SESSION_ID
+else
+  export EGREGORE_SESSION_ID="$(date -u +%Y%m%dT%H%M%S)-${AUTHOR}-$$"
+
+  # Persist session ID to file so telemetry.sh can read it
+  # (env vars from hooks don't propagate into the Claude Code agent)
+  PROJ_HASH=$(echo -n "$SCRIPT_DIR" | md5 2>/dev/null || echo -n "$SCRIPT_DIR" | md5sum 2>/dev/null | cut -d' ' -f1)
+  echo "$EGREGORE_SESSION_ID" > "$SESSION_ID_DIR/session-${PROJ_HASH}.id"
+  # Also write project-local file (CLAUDE.md reads this — no glob needed)
+  echo "$EGREGORE_SESSION_ID" > "$SCRIPT_DIR/.egregore-session-id"
+fi
+# Every worktree links that file, so a parallel session start rewrites it
+# under this session. Map the starting harness session's own id to this id
+# (bin/session-id.sh) so its commits keep their own Egregore-Session trailer.
+# Each entry point names the harness it starts; a native id inherited from
+# another session's shell never matches that name.
+if [ -n "${EGREGORE_START_HARNESS:-}" ] && [ -n "${EGREGORE_NATIVE_SESSION_ID:-}" ] \
+  && [ "${EGREGORE_NATIVE_HARNESS:-}" = "$EGREGORE_START_HARNESS" ] \
+  && [ -f "$SCRIPT_DIR/bin/session-id.sh" ]; then
+  bash "$SCRIPT_DIR/bin/session-id.sh" record "$EGREGORE_START_HARNESS" \
+    "$EGREGORE_NATIVE_SESSION_ID" "$EGREGORE_SESSION_ID" --root "$SCRIPT_DIR" >/dev/null 2>&1 || true
+fi
 
 # Model stamp hashes the git common-dir root because telemetry.sh resolves it that way.
 MODEL_REPO_ROOT=$(git -C "$SCRIPT_DIR" rev-parse --path-format=absolute --git-common-dir 2>/dev/null | sed 's|/\.git$||') || MODEL_REPO_ROOT="$SCRIPT_DIR"

package/runtime/pi/bin/lib/instance-registry.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# instance-registry.sh — session start's maintenance of the instance registry
+# (~/.egregore/instances.json). Sourced by bin/session-start.sh (register +
+# prune) and bin/codex-session-start.sh (prune). Requires jq.
+#
+#   egregore_registry_prune <registry>
+#       Drop entries that can never be an instance: a checkout inside another
+#       registered instance's .egregore/ runtime directory (an evaluation
+#       sandbox) is runtime state of that instance.
+#   egregore_registry_register <registry> <dir> <slug> <name> [org_id]
+#       Register <dir> unless it is already registered or is such runtime
+#       state; patch a legacy entry with its org_id.
+#
+# Every write goes through a temporary file and a rename: the boundary check
+# reads an empty or half-written registry as damage and fails closed.
+
+# True when $p sits inside another listed path's .egregore/ directory.
+_EGREGORE_REGISTRY_JQ_DEFS='
+def runtime_state($all): . as $p | any($all[]; . as $root | $root != $p and ($p | startswith($root + "/.egregore/")));
+def registered_paths: [.[] | objects | .path | strings];
+def runtime_entry($all): type == "object" and (.path | type) == "string" and (.path | runtime_state($all));
+'
+
+_egregore_registry_write() {
+  local registry="$1" tmp="$1.tmp.$$"
+  shift
+  if jq "$@" "$registry" > "$tmp" 2>/dev/null && [ -s "$tmp" ]; then
+    mv "$tmp" "$registry"
+  else
+    rm -f "$tmp"
+    return 1
+  fi
+}
+
+egregore_registry_prune() {
+  local registry="$1" pruned
+  [ -f "$registry" ] || return 0
+  pruned=$(jq "$_EGREGORE_REGISTRY_JQ_DEFS"'
+    if type == "array" then registered_paths as $all | [.[] | select(runtime_entry($all))] | length else 0 end' \
+    "$registry" 2>/dev/null) || return 0
+  [ "${pruned:-0}" -gt 0 ] 2>/dev/null || return 0
+  _egregore_registry_write "$registry" "$_EGREGORE_REGISTRY_JQ_DEFS"'
+    registered_paths as $all | map(select(runtime_entry($all) | not))'
+}
+
+egregore_registry_register() {
+  local registry="$1" dir="$2" slug="$3" name="$4" org="${5:-}" entry
+  [ -n "$dir" ] && [ -n "$slug" ] && [ -n "$name" ] || return 0
+  mkdir -p "$(dirname "$registry")" || return 0
+  if [ ! -f "$registry" ]; then
+    echo "[]" > "$registry.tmp.$$" && mv "$registry.tmp.$$" "$registry"
+  fi
+  # Runtime state of another registered instance never registers itself.
+  if jq -e --arg p "$dir" "$_EGREGORE_REGISTRY_JQ_DEFS"'registered_paths as $all | $p | runtime_state($all)' \
+    "$registry" >/dev/null 2>&1; then
+    return 0
+  fi
+  if [ "$(jq --arg p "$dir" '[.[] | objects | select(.path == $p)] | length' "$registry" 2>/dev/null)" = "0" ]; then
+    # org_id is the stable identity other sessions use to prove this
+    # checkout is same-organization rather than foreign
+    entry=$(jq -n --arg s "$slug" --arg n "$name" --arg p "$dir" --arg o "$org" \
+      '{slug: $s, name: $n, path: $p} + (if $o == "" then {} else {org_id: $o} end)')
+    _egregore_registry_write "$registry" --argjson e "$entry" '. + [$e]'
+  elif [ -n "$org" ]; then
+    # Backward compatibility: patch this checkout's own legacy entry with its
+    # org_id so other sessions can prove identity instead of failing closed
+    # against it
+    _egregore_registry_write "$registry" --arg p "$dir" --arg o "$org" \
+      'map(if type == "object" and .path == $p and ((.org_id // "") == "") then . + {org_id: $o} else . end)'
+  fi
+}

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

@@ -0,0 +1,249 @@
+#!/usr/bin/env python3
+"""Bind caller-recorded local checks to a PR commit while hosted CI is unavailable.
+
+generate --records FILE accepts a JSON array of {suite, command, exit_code, log}.
+It copies logs beside the receipt and hashes them. validate checks identity,
+Git trees and retained log integrity; it does not execute commands or certify
+that the caller actually ran them. Authorization belongs to the merge caller.
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import stat
+import subprocess
+import sys
+
+SCHEMA = "local-ci/v1"
+REASON = "GitHub Actions credits exhausted"
+MAX_JSON = 1024 * 1024
+MAX_LOG = 64 * 1024 * 1024
+SHA = re.compile(r"[0-9a-f]{40}")
+DIGEST = re.compile(r"[0-9a-f]{64}")
+
+
+class Invalid(ValueError):
+    pass
+
+
+def require(condition, message):
+    if not condition:
+        raise Invalid(message)
+
+
+def read_file(path, limit):
+    """Read a bounded regular file without following its final symlink."""
+    fd = os.open(path, os.O_RDONLY | os.O_NONBLOCK | getattr(os, "O_NOFOLLOW", 0))
+    with os.fdopen(fd, "rb") as stream:
+        info = os.fstat(stream.fileno())
+        require(stat.S_ISREG(info.st_mode) and info.st_size <= limit, "invalid evidence file")
+        value = stream.read(limit + 1)
+        require(len(value) <= limit, "evidence file exceeds limit")
+        return value
+
+
+def read_log(root, relative):
+    """A receipt can read regular log descendants only, without symlink hops."""
+    require(isinstance(relative, str) and relative, "missing retained log path")
+    path = Path(relative)
+    require(path.parts and not path.is_absolute() and all(p not in (".", "..") for p in path.parts),
+            "retained log must stay beside the receipt")
+    fd = os.open(root, os.O_RDONLY | os.O_DIRECTORY)
+    try:
+        for part in path.parts[:-1]:
+            child = os.open(part, os.O_RDONLY | os.O_DIRECTORY | getattr(os, "O_NOFOLLOW", 0), dir_fd=fd)
+            os.close(fd)
+            fd = child
+        leaf = os.open(path.parts[-1], os.O_RDONLY | os.O_NONBLOCK | getattr(os, "O_NOFOLLOW", 0), dir_fd=fd)
+        with os.fdopen(leaf, "rb") as stream:
+            info = os.fstat(stream.fileno())
+            require(stat.S_ISREG(info.st_mode) and info.st_size <= MAX_LOG, "invalid retained log")
+            content = stream.read(MAX_LOG + 1)
+            require(len(content) <= MAX_LOG, "retained log exceeds limit")
+            return content
+    finally:
+        os.close(fd)
+
+
+def document(path):
+    value = json.loads(read_file(path, MAX_JSON))
+    require(isinstance(value, dict), "receipt must be an object")
+    return value
+
+
+def git(checkout, *args, failure="Git identity is unavailable"):
+    env = {k: v for k, v in os.environ.items() if not k.startswith("GIT_")}
+    env.update(GIT_OPTIONAL_LOCKS="0", GIT_CONFIG_NOSYSTEM="1", GIT_NO_REPLACE_OBJECTS="1")
+    result = subprocess.run(["git", "-c", "core.fsmonitor=false", "-C", str(checkout), *args], env=env,
+                            capture_output=True, text=True, timeout=15)
+    require(result.returncode == 0, failure)
+    return result.stdout.strip()
+
+
+def text(value, label, limit=4096):
+    require(isinstance(value, str) and 0 < len(value) <= limit
+            and all(ord(c) >= 32 or c in "\n\t" for c in value), f"invalid {label}")
+    return value
+
+
+def identity(row):
+    require(row.get("schema") == SCHEMA, "unsupported local CI receipt schema")
+    require(isinstance(row.get("repo"), str) and
+            re.fullmatch(r"[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+", row["repo"]), "invalid repository")
+    require(type(row.get("pr")) is int and row["pr"] > 0, "invalid PR number")
+    for key in ("head", "base_sha", "tree_sha"):
+        require(isinstance(row.get(key), str) and SHA.fullmatch(row[key]), f"invalid {key}")
+    text(row.get("base"), "base ref", 200)
+    require("\n" not in row["base"] and "\t" not in row["base"] and not row["base"].startswith("-"),
+            "invalid base ref")
+    text(row.get("checkout"), "checkout")
+    require(Path(row["checkout"]).is_absolute(), "checkout must be absolute")
+    require(row.get("unavailable_reason") == REASON, "unsupported hosted CI exception")
+
+
+def validate(path, *, repo, pr, head, base, base_sha):
+    row = document(path)
+    identity(row)
+    for key, wanted in (("repo", repo), ("pr", pr), ("head", head), ("base", base), ("base_sha", base_sha)):
+        require(row[key] == wanted, f"receipt {key} does not match current PR")
+    require(git(row["checkout"], "rev-parse", "--verify", row["head"] + "^{tree}") == row["tree_sha"],
+            "tested tree does not match PR head")
+    require(git(row["checkout"], "rev-parse", "--verify", row["base_sha"] + "^{commit}") == row["base_sha"],
+            "base commit is unavailable")
+    git(row["checkout"], "merge-base", "--is-ancestor", row["base_sha"], row["head"],
+        failure="tested head does not contain the current base")
+    suites = row.get("required_suites")
+    require(isinstance(suites, list) and 0 < len(suites) <= 100, "required suites are missing")
+    for suite in suites:
+        text(suite, "suite name", 200)
+    require(len(set(suites)) == len(suites), "required suites are duplicated")
+    results = row.get("results")
+    require(isinstance(results, list) and len(results) == len(suites), "required suite results are incomplete")
+    seen = set()
+    for result in results:
+        require(isinstance(result, dict), "invalid suite result")
+        suite = result.get("suite")
+        require(isinstance(suite, str) and suite in suites and suite not in seen,
+                "unexpected or duplicate suite result")
+        seen.add(suite)
+        text(result.get("command"), "recorded command", 16384)
+        require(type(result.get("exit_code")) is int and result["exit_code"] == 0,
+                f"required suite did not pass: {suite}")
+        require(isinstance(result.get("sha256"), str) and DIGEST.fullmatch(result["sha256"]),
+                "invalid log digest")
+        log = read_log(Path(path).resolve().parent, result.get("log"))
+        require(hashlib.sha256(log).hexdigest() == result["sha256"], f"log changed: {suite}")
+    failed = row.get("failed_checks")
+    require(isinstance(failed, list) and len(failed) <= 100, "failed_checks must be a list")
+    named = set()
+    for check in failed:
+        require(isinstance(check, dict), "invalid hosted check explanation")
+        name = text(check.get("name"), "hosted check name", 300)
+        text(check.get("reason"), "hosted check reason")
+        require(name not in named, "duplicate hosted check explanation")
+        named.add(name)
+    return row
+
+
+def quoted(value):
+    """Single-line Markdown code, including hostile backticks, without HTML."""
+    value = " ".join(str(value).split())
+    runs = re.findall(r"`+", value)
+    fence = "`" * (1 + max(map(len, runs), default=0))
+    return f"{fence} {value} {fence}"
+
+
+def markdown(row):
+    lines = ["## Local CI receipt", "",
+             f"Repository {quoted(row['repo'])}, PR #{row['pr']}.",
+             f"Head {quoted(row['head'])}; base {quoted(row['base'])} at {quoted(row['base_sha'])}.",
+             f"Tested tree {quoted(row['tree_sha'])}.",
+             f"Caller-reported hosted CI exception: {REASON}.", "",
+             "The caller recorded these checks. Validation verified commit identity and retained log hashes; "
+             "it did not independently execute or attest the commands. The receipt does not grant merge authorization.",
+             ""]
+    for result in row["results"]:
+        lines.append(f"- {quoted(result['suite'])}: recorded exit 0; {quoted(result['command'])}; "
+                     f"log SHA256 {quoted(result['sha256'])}.")
+    if row["failed_checks"]:
+        lines.extend(["", "Hosted checks covered by this local exception:", ""])
+        for check in row["failed_checks"]:
+            lines.append(f"- {quoted(check['name'])}: {quoted(check['reason'])}.")
+    return "\n".join(lines) + "\n"
+
+
+def generate(args):
+    checkout = Path(args.checkout).resolve()
+    tree = args.tree
+    if tree is None:
+        require(git(checkout, "rev-parse", "HEAD") == args.head, "checkout is not at the tested head")
+        require(not git(checkout, "status", "--porcelain", "--untracked-files=no"), "tracked checkout is dirty")
+        tree = git(checkout, "rev-parse", "HEAD^{tree}")
+    row = {"schema": SCHEMA, "repo": args.repo, "pr": args.pr, "head": args.head,
+           "base": args.base, "base_sha": args.base_sha, "tree_sha": tree,
+           "checkout": str(checkout), "unavailable_reason": args.unavailable_reason,
+           "required_suites": args.required_suite, "results": [],
+           "failed_checks": json.loads(read_file(args.failed_checks, MAX_JSON)) if args.failed_checks else []}
+    identity(row)
+    records = json.loads(read_file(args.records, MAX_JSON))
+    require(isinstance(records, list), "records must be a JSON array")
+    output = Path(args.output).absolute()
+    require(not output.exists(), "receipt output already exists")
+    output.parent.mkdir(parents=True, exist_ok=True)
+    log_root = output.parent / (output.name + ".logs")
+    log_root.mkdir(mode=0o700)
+    for index, result in enumerate(records):
+        require(isinstance(result, dict), "invalid caller record")
+        content = read_file(Path(args.records).resolve().parent / result["log"], MAX_LOG)
+        target = log_root / f"{index + 1:03d}.log"
+        with target.open("xb") as stream:
+            stream.write(content)
+        target.chmod(0o600)
+        row["results"].append({key: result.get(key) for key in ("suite", "command", "exit_code")} |
+                              {"log": str(target.relative_to(output.parent)),
+                               "sha256": hashlib.sha256(content).hexdigest()})
+    with output.open("x", encoding="utf-8") as stream:
+        json.dump(row, stream, indent=2)
+        stream.write("\n")
+    output.chmod(0o600)
+    validate(output, repo=args.repo, pr=args.pr, head=args.head, base=args.base, base_sha=args.base_sha)
+    return output
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__)
+    sub = parser.add_subparsers(dest="action", required=True)
+    for action in ("generate", "validate"):
+        command = sub.add_parser(action)
+        for flag in ("repo", "head", "base", "base-sha"):
+            command.add_argument("--" + flag, required=True)
+        command.add_argument("--pr", type=int, required=True)
+        if action == "validate":
+            command.add_argument("--receipt", type=Path, required=True)
+        else:
+            command.add_argument("--output", type=Path, required=True)
+            command.add_argument("--checkout", type=Path, required=True)
+            command.add_argument("--records", type=Path, required=True)
+            command.add_argument("--required-suite", action="append", required=True)
+            command.add_argument("--unavailable-reason", required=True)
+            command.add_argument("--failed-checks", type=Path, help="JSON array of hosted {name, reason} explanations")
+            command.add_argument("--tree", help="explicit tested Git tree, for checks run before committing that tree")
+    args = parser.parse_args(argv)
+    try:
+        if args.action == "generate":
+            print(generate(args))
+        else:
+            print(markdown(validate(args.receipt, repo=args.repo, pr=args.pr, head=args.head,
+                                    base=args.base, base_sha=args.base_sha)), end="")
+    except (Invalid, OSError, ValueError, KeyError, TypeError, subprocess.SubprocessError) as error:
+        print(f"local-ci: {error}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())