create-egregore 0.21.6 → 0.22.0

package/runtime/claude/bin/reflexes/20-sandbox.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# Reflex (show): a session inside a sandbox says what runs degraded and
+# what will not work.
+#
+# Positive markers only, the predicate bin/lib/secret_entry.py and
+# egregore_runtime/sandbox.py use: CODEX_SANDBOX set to anything but empty,
+# none, false or 0, or APP_SANDBOX_CONTAINER_ID set. No marker, no line, on
+# every harness; a missing DISPLAY or a failing write never names a sandbox.
+# With a marker, one file is created and removed where the runtime keeps its
+# per-user state (search and telemetry, resolved as egregore_runtime does).
+# The line follows the result: writable state, and search and browser checks
+# will not work; refused state, and search runs degraded on the workspace
+# copy, with a second line saying that state is read-only here.
+set -u
+
+marker="$(printf '%s' "${CODEX_SANDBOX:-}" | tr '[:upper:]' '[:lower:]')"
+case "$marker" in
+  ""|none|false|0) [ -n "${APP_SANDBOX_CONTAINER_ID:-}" ] || exit 0 ;;
+esac
+
+# Create and remove one file in the nearest existing ancestor of a directory;
+# fails when that location refuses the write or keeps the file. A probe file
+# that outlives its test is removed again on the way out, and that retry
+# never fails the probe, even under an inherited errexit.
+probe_file=""
+trap 'if [ -n "$probe_file" ]; then rm -f "$probe_file" 2>/dev/null || true; fi' EXIT
+writable() {
+  local dir="$1" parent
+  case "$dir" in \~/*) dir="${HOME:-}/${dir#\~/}" ;; esac
+  # A relative override is relative to the current directory, as the runtime
+  # resolves it; the walk must reach that directory, never stop short of it.
+  case "$dir" in /*) ;; *) dir="$PWD/$dir" ;; esac
+  while [ ! -e "$dir" ]; do
+    parent="${dir%/*}"
+    [ -n "$parent" ] || parent=/
+    [ "$parent" != "$dir" ] || break
+    dir="$parent"
+  done
+  [ -d "$dir" ] || return 0
+  probe_file="$(mktemp "$dir/.egregore-write-probe.XXXXXX" 2>/dev/null)" || { probe_file=""; return 1; }
+  rm -f "$probe_file" 2>/dev/null || return 1
+  probe_file=""
+}
+
+# Both stores key their per-user directory by the resolved memory checkout
+# (QmdLocalRetriever._instance_hash, LocalTelemetrySink's namespace).
+root="${EGREGORE_ROOT:-.}"
+memory="$(cd "$root/memory" 2>/dev/null && pwd -P)" \
+  || memory="$(cd "$root" 2>/dev/null && pwd -P)/memory"
+digest=""
+if command -v shasum >/dev/null 2>&1; then
+  digest="$(printf '%s' "$memory" | LC_ALL=C shasum -a 256 2>/dev/null)"
+elif command -v sha256sum >/dev/null 2>&1; then
+  digest="$(printf '%s' "$memory" | sha256sum 2>/dev/null)"
+fi
+digest="${digest%% *}"
+
+search_state="${EGREGORE_QMD_RUNTIME_DIR:-}"
+telemetry_state="${EGREGORE_TELEMETRY_DIR:-}"
+if [ -n "${HOME:-}" ]; then
+  [ -n "$search_state" ] || search_state="$HOME/.egregore/runtime/qmd${digest:+/${digest:0:16}}"
+  [ -n "$telemetry_state" ] || telemetry_state="$HOME/.egregore/telemetry${digest:+/${digest:0:20}}"
+fi
+
+refused=""
+for state in "$search_state" "$telemetry_state"; do
+  [ -n "$state" ] || continue
+  if ! writable "$state"; then
+    refused=1
+    break
+  fi
+done
+
+# shellcheck disable=SC2016  # the backticks are part of each line
+if [ -n "$refused" ]; then
+  # The runtime falls back to the workspace copy: lexical search, telemetry
+  # kept there. The read-only fact gets its own line, because this one uses
+  # 157 of the runner's 160 characters.
+  printf '%s\n' 'this session runs in a sandbox: search runs degraded, telemetry stays in the workspace and browser checks will not work · start through `egregore` to lift it'
+  printf '%s\n' 'per-user state is read-only here'
+else
+  # Per-user state stays in use, but the sandbox refuses the loopback port
+  # of the query worker, so search fails instead of degrading.
+  printf '%s\n' 'this session runs in a sandbox: search and browser checks will not work · start through `egregore` to lift it'
+fi

package/runtime/claude/bin/reflexes/30-cost.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""Reflex: your session cost over seven days. Show tier.
+
+Reads the current person's session records from the last seven days, today
+included, and only the files whose names fall in that window. A priced record
+counts under its harness (a record priced at list price is a Codex session);
+an unpriced record counts apart, with the input tokens from its Cost section.
+Prints one line, leaving out the parts that are zero, and nothing without
+records. Numbers only: no topic, branch or prompt text.
+"""
+import datetime
+import json
+import math
+import os
+import re
+import sys
+from pathlib import Path
+
+DAYS = 7
+READ_LIMIT = 256 * 1024
+PRICED = ("ledger", "estimate", "list price")
+LABELS = {"claude": "Claude", "codex": "Codex", "pi": "Pi", "prime": "Prime", "other": "Other"}
+TOKENS = re.compile(r"^- tokens: (\d+) input\b", re.M)
+
+
+def front_matter(text):
+    if not text.startswith("---\n"):
+        return {}
+    block = text[4:].partition("\n---")[0]
+    fields = {}
+    for line in block.splitlines():
+        key, sep, value = line.partition(":")
+        if not sep:
+            continue
+        value = value.strip()
+        try:
+            value = json.loads(value)
+        except ValueError:
+            pass
+        fields[key.strip()] = value
+    return fields
+
+
+def amount(value):
+    try:
+        number = float(value)
+    except (TypeError, ValueError):
+        return 0.0
+    return number if math.isfinite(number) and number > 0 else 0.0
+
+
+def compact(count):
+    value, unit = float(count), ""
+    for name in ("K", "M", "B"):
+        if round(value, 1) < 1000:
+            break
+        value, unit = value / 1000, name
+    return (f"{value:.1f}".removesuffix(".0") if unit else str(count)) + unit
+
+
+def main():
+    memory = os.environ.get("EGREGORE_MEMORY", "")
+    author = re.sub(r"[^a-z0-9_-]", "", os.environ.get("EGREGORE_AUTHOR", "").strip().lower())
+    sessions = Path(memory) / "sessions" if memory else None
+    if not author or sessions is None or not sessions.is_dir():
+        return 0
+    today = datetime.date.today()
+    priced = dict.fromkeys(LABELS.values(), 0.0)
+    unpriced, tokens, seen = 0, 0, set()
+    for offset in range(DAYS):
+        day = today - datetime.timedelta(days=offset)
+        try:
+            paths = sorted((sessions / day.strftime("%Y-%m")).glob(day.strftime("%d-") + author + "-*.md"))
+        except OSError:
+            continue
+        for path in paths:
+            try:
+                with path.open("rb") as stream:
+                    text = stream.read(READ_LIMIT).decode("utf-8", errors="replace")
+            except OSError:
+                continue
+            meta = front_matter(text)
+            owner = str(meta.get("from", "")).strip().lower()
+            # Producer-bearing records are never a person's session, including
+            # malformed metadata and records copied without a private adapter.
+            if any(key.strip().strip("\"'").casefold() in
+                   {"producer", "producer_principal_id", "producer_identity", "record_owner_actor_id", "subject_kind"}
+                   and (key != "subject_kind" or value != "human-session") for key, value in meta.items()):
+                continue
+            session = str(meta.get("session", path.name))
+            if meta.get("kind") != "session-record" or owner != author or session in seen:
+                continue
+            seen.add(session)
+            source = meta.get("cost_source", "estimate")
+            if source in PRICED:
+                harness = "codex" if source == "list price" else str(meta.get("harness") or "claude").lower()
+                priced[LABELS.get(harness, "Other")] += amount(meta.get("cost_usd"))
+                continue
+            unpriced += 1
+            match = TOKENS.search(text.partition("\n## Cost\n")[2])
+            tokens += int(match.group(1)) if match else 0
+    parts = []
+    total = sum(priced.values())
+    if round(total, 2) > 0:
+        split = ", ".join(f"{label} ${value:,.2f}" for label, value in priced.items() if round(value, 2) > 0)
+        parts.append(f"${total:,.2f} priced ({split})")
+    if unpriced:
+        part = f"{unpriced} unpriced session" + ("" if unpriced == 1 else "s")
+        parts.append(part + (f", {compact(tokens)} input tokens" if tokens else ""))
+    if parts:
+        print("7 days: " + " · ".join(parts))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/runtime/claude/bin/reflexes/40-shells.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""Reflex: refused shell shapes. Show tier.
+
+Reads yesterday's session records of the current person and sums the
+`worktree-guard refusals` counter from their Friction sections. Three or
+more prints one line with the count and the pointer to the plain forms.
+"""
+import datetime
+import os
+import re
+import sys
+from pathlib import Path
+
+COUNTER = re.compile(r"^- worktree-guard refusals: (\d+)\s*$", re.M)
+FROM = re.compile(r"^from:\s*(.+?)\s*$", re.M)
+
+
+def main():
+    memory = os.environ.get("EGREGORE_MEMORY", "")
+    author = os.environ.get("EGREGORE_AUTHOR", "").strip().casefold()
+    sessions = Path(memory) / "sessions" if memory else None
+    if sessions is None or not sessions.is_dir():
+        return 0
+    yesterday = datetime.date.today() - datetime.timedelta(days=1)
+    folder = sessions / yesterday.strftime("%Y-%m")
+    total, files = 0, 0
+    try:
+        paths = sorted(folder.glob(yesterday.strftime("%d-") + "*.md"))
+    except OSError:
+        return 0
+    for path in paths:
+        try:
+            text = path.read_text(encoding="utf-8", errors="replace")[:200000]
+        except OSError:
+            continue
+        head = text.partition("\n---")[0]
+        owner = FROM.search(head)
+        if author and owner and owner.group(1).strip("\"'").casefold() != author:
+            continue
+        match = COUNTER.search(text)
+        if match:
+            total += int(match.group(1))
+            files += 1
+    if total >= 3:
+        noun = "session" if files == 1 else "sessions"
+        print(f"{total} refused shell commands yesterday across {files} {noun} · plain forms: .claude/context/plain-shell.md")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/runtime/claude/bin/reflexes/README.md

@@ -0,0 +1,61 @@
+# Reflexes
+
+A reflex is a probe with a tier. The probe states a fact about yesterday; the
+tier says how far the egregore may go on its own: say it (show), end the line
+with the command to run (propose), or do it and leave a receipt (act). The
+startup card is where the probes speak, on every harness. The act tier never
+prints from here; it lives in the path it governs, such as the merge gate in
+the save path.
+
+## A probe
+
+One file in this directory: a `.sh` or `.py` file, or any executable. The
+runner (`bin/reflexes.sh`, `bin/lib/reflexes.py`) runs them in name order,
+one at a time, and prints each line a probe writes to stdout with the card's
+sigil in front. A probe prints nothing when there is nothing to say, one line
+for a fact, two at most. Lines are cut at 160 characters.
+
+The runner never fails the card. A probe that exits non-zero, prints nothing,
+or runs past one second is silent; the runner stops launching probes once
+three seconds have passed in total. `bash bin/reflexes.sh --debug` names
+every silent probe and the reason.
+
+Sessions started minutes apart print the same card, so the runner keeps the
+last card for each harness in `.egregore/runtime/reflexes/` and prints it
+again, for up to ten minutes, while what the probes read is unchanged: the
+probe and `bin/lib` files, everything under `memory/sessions` (records and
+ledgers), the features in `egregore.json`, the person's names and records
+switch in the state file, the local date and nightly's cache (`cache_key` in
+`bin/lib/reflexes.py`). Anything else, such as the memory lookups the
+retrieval line counts, can be up to ten minutes old on the card. `--debug`, a
+sandbox marker, or a run in which a probe ran past its budget or never
+started skips the cache.
+
+Every probe gets, on top of the caller's environment:
+
+- `EGREGORE_ROOT` the project root
+- `EGREGORE_MEMORY` the memory directory, which may not exist
+- `EGREGORE_STATE` the per-instance state file (`.egregore-state.json`)
+- `EGREGORE_AUTHOR` the person's GitHub username, when known
+- `EGREGORE_HARNESS` `claude`, `codex`, `pi` or `prime`
+
+A probe reads records, state and local files; it never reaches the network
+without a cache and a budget, never writes outside `tmp/` (beyond one file
+created and removed to test a directory, as `20-sandbox.sh` does), and never
+prints anything a record would withhold.
+
+## Adding one
+
+Add a file here with a two-digit prefix for order (`20-nightly.sh`), make it
+print its line only when its predicate holds, and give it a case in
+`tests/test-reflexes.sh` or a test of its own. A probe that reads a file the
+cache key does not cover shows its change up to ten minutes late; add the
+file to `cache_key` when that matters. The runtime bundle ships this
+directory whole (`BIN_DIRS` in the bundle builder), so a tracked probe needs
+no allowlist entry. An organisation adds its own probes the same way.
+
+## Wording
+
+A show line states the fact: `3 open items are older than three days and
+have no owner`. A propose line ends with the command: `... · /records file
+a1b2c3`. No exclamation marks, no advice, no explanation of the mechanism.

package/runtime/claude/bin/reflexes.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# The reflexes: one runner, a directory of probes. See bin/reflexes/README.md.
+# Prints the probes' lines for the startup card; never fails the card.
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)" || exit 0
+command -v python3 >/dev/null 2>&1 || exit 0
+exec python3 "$SCRIPT_DIR/bin/lib/reflexes.py" --root "$SCRIPT_DIR" "$@"

package/runtime/claude/bin/runtime-identity.sh

@@ -14,6 +14,8 @@ ROOT="${EGREGORE_INSTANCE_ROOT:-$RUNTIME_ROOT}"
 ROOT="$(cd "$ROOT" && pwd)"
 CONFIG="$ROOT/egregore.json"
 STATE="$ROOT/.egregore-state.json"
+# shellcheck source=bin/lib/config.sh
+source "$RUNTIME_ROOT/bin/lib/config.sh"
 
 resolved() {
   [ -f "$CONFIG" ] && [ -f "$STATE" ] || return 1
@@ -26,6 +28,114 @@ resolved() {
   ' "$STATE" >/dev/null 2>&1
 }
 
+# The saved address is resolved: an egregore.json saved before the October
+# 2026 move still names the retired origin, which never receives a token.
+connected_config() {
+  api_url="$(_config_api_url)" || api_url=""
+  slug="$(jq -r '.slug // empty' "$CONFIG" 2>/dev/null)"
+  api_key="$(grep '^EGREGORE_API_KEY=' "$ROOT/.env" 2>/dev/null | cut -d= -f2- || true)"
+  [ -n "$api_url" ] && [ -n "$slug" ]
+}
+
+# The greeting's one note about the organization key (bin/lib/health-footer.sh
+# renders it): "renewed" shows once; "needs_sign_in" shows until renewal works.
+key_notice_state() {
+  jq -r '.hosted_key_notice.state // empty' "$STATE" 2>/dev/null || true
+}
+
+key_notice() {
+  local file tmp
+  [ -f "$STATE" ] || return 0
+  # A worktree links the checkout's state file: rename onto its target.
+  file="$(realpath "$STATE" 2>/dev/null)" || file="$STATE"
+  tmp="$(mktemp "$file.XXXXXX" 2>/dev/null)" || return 0
+  if [ "$1" = clear ]; then
+    jq 'if .hosted_key_notice.state == "needs_sign_in" then del(.hosted_key_notice) else . end' \
+      "$file" >"$tmp" 2>/dev/null
+  else
+    jq --arg state "$1" --arg at "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+      '.hosted_key_notice = {state: $state, at: $at}' "$file" >"$tmp" 2>/dev/null
+  fi && [ -s "$tmp" ] && mv "$tmp" "$file" || rm -f "$tmp"
+}
+
+# One authenticated status read; sets status_code and status_body.
+probe_status() {
+  local response=""
+  status_code=""
+  status_body=""
+  [ -n "$api_key" ] || return 0
+  response="$(curl -s "$api_url/api/org/status" \
+    -H "Authorization: Bearer $api_key" --connect-timeout 2 --max-time 4 \
+    -w '\n%{http_code}' 2>/dev/null || true)"
+  status_code="${response##*$'\n'}"
+  status_body="${response%$'\n'*}"
+}
+
+status_ok() {
+  [ "$status_code" = 200 ] && printf '%s' "$status_body" | jq -e --arg slug "$slug" '
+    (.org_id | type == "string" and length > 0) and .slug == $slug
+  ' >/dev/null 2>&1
+}
+
+rejection_code() {
+  [ "$status_code" = 401 ] || return 0
+  printf '%s' "$status_body" | jq -r '.code // empty' 2>/dev/null || true
+}
+
+# Recover the configured org's key only through the membership-verifying
+# endpoint, which renews a key retired in the October 2026 security reset.
+# A historic path/namespace collision could also leave this checkout with
+# another Egregore's key. Install it atomically, then verify it. No
+# credential bytes are printed. $1 is the API's code for the rejected key.
+recover_key() {
+  local rejected="${1:-}" github_token encoded_slug response code recovered renewed previous_key
+  github_token="$(grep '^GITHUB_TOKEN=' "$ROOT/.env" 2>/dev/null | cut -d= -f2- || true)"
+  if [ -z "$github_token" ]; then
+    [ "$rejected" != key_retired ] || key_notice needs_sign_in
+    return 1
+  fi
+  encoded_slug="$(printf '%s' "$slug" | jq -sRr @uri)"
+  response="$(curl -s "$api_url/api/org/$encoded_slug/key" \
+    -H "Authorization: Bearer $github_token" --connect-timeout 2 --max-time 12 \
+    -w '\n%{http_code}' 2>/dev/null || true)"
+  code="${response##*$'\n'}"
+  recovered="${response%$'\n'*}"
+  if [ "$code" = 401 ]; then
+    # The GitHub sign-in was rejected; a fresh one renews the key.
+    [ "$rejected" != key_retired ] || key_notice needs_sign_in
+    return 1
+  fi
+  [ "$code" = 200 ] || return 1
+  # The key itself must name this org (ek_<slug>_<secret>), not just the reply.
+  printf '%s' "$recovered" | jq -e --arg slug "$slug" '
+    (.api_key | type == "string" and startswith("ek_" + $slug + "_")
+      and length > ($slug | length) + 4)
+    and .org_slug == $slug
+  ' >/dev/null 2>&1 || return 1
+  renewed="$(printf '%s' "$recovered" | jq -r '.renewed == true' 2>/dev/null || echo false)"
+  # Prove the candidate works before it replaces the saved key.
+  previous_key="$api_key"
+  api_key="$(printf '%s' "$recovered" | jq -r '.api_key')"
+  probe_status
+  if ! status_ok; then
+    api_key="$previous_key"
+    return 1
+  fi
+  if ! printf '%s' "$recovered" | \
+    EGREGORE_ROOT="$ROOT" \
+    PYTHONSAFEPATH=1 PYTHONPATH="$RUNTIME_ROOT${PYTHONPATH:+:$PYTHONPATH}" \
+    python3 -m egregore_runtime.identity_cli install-connected-key >/dev/null; then
+    api_key="$previous_key"
+    return 1
+  fi
+  api_key="$(grep '^EGREGORE_API_KEY=' "$ROOT/.env" 2>/dev/null | cut -d= -f2- || true)"
+  if [ "$rejected" = key_retired ] || [ "$renewed" = true ]; then
+    key_notice renewed
+  else
+    key_notice clear
+  fi
+}
+
 case "${1:-ensure}" in
   status)
     if resolved; then
@@ -35,56 +145,44 @@ case "${1:-ensure}" in
     printf '{"status":"unresolved"}\n'
     exit 1
     ;;
+  recover)
+    # A hosted request just rejected the organization key ($2 is the API's
+    # code). Once a fresh sign-in is known to be needed, only session start
+    # retries, so the notice and the retry stay one per session.
+    [ "$(key_notice_state)" != needs_sign_in ] || exit 1
+    connected_config || exit 1
+    recover_key "${2:-}"
+    ;;
   ensure)
-    resolved && exit 0
+    if resolved; then
+      # Healthy starts stop here, with no network call. After a recorded
+      # need for a fresh sign-in, retry so the greeting shows the outcome.
+      [ "$(key_notice_state)" = needs_sign_in ] || exit 0
+      connected_config || exit 0
+      probe_status
+      if status_ok; then
+        key_notice clear
+      else
+        recover_key "$(rejection_code)" || true
+      fi
+      exit 0
+    fi
     mode="$(jq -r 'if (.mode // "local") == "connected" or (.api_url // "") != "" then "connected" else "local" end' "$CONFIG" 2>/dev/null || echo local)"
     if [ "$mode" = "local" ]; then
       EGREGORE_ROOT="$ROOT" \
         PYTHONSAFEPATH=1 PYTHONPATH="$RUNTIME_ROOT${PYTHONPATH:+:$PYTHONPATH}" \
         python3 -m egregore_runtime.identity_cli initialize-local >/dev/null
     else
-      api_url="$(jq -r '.api_url // empty' "$CONFIG" 2>/dev/null)"
-      slug="$(jq -r '.slug // empty' "$CONFIG" 2>/dev/null)"
-      api_key="$(grep '^EGREGORE_API_KEY=' "$ROOT/.env" 2>/dev/null | cut -d= -f2-)"
-      [ -n "$api_url" ] && [ -n "$slug" ] || exit 1
+      connected_config || exit 1
       # Identity repair selects already-existing account and membership
-      # records, then adopts their opaque IDs locally. If a stale credential
-      # belongs to another org, recover only the configured org's existing key
-      # through verified GitHub membership. No control-plane records are made.
-      control_plane=""
-      if [ -n "$api_key" ]; then
-        control_plane="$(curl -sf "$api_url/api/org/status" \
-          -H "Authorization: Bearer $api_key" --connect-timeout 2 --max-time 4 \
-          2>/dev/null || true)"
-      fi
-      if ! printf '%s' "$control_plane" | jq -e --arg slug "$slug" '
-        (.org_id | type == "string" and length > 0) and .slug == $slug
-      ' >/dev/null 2>&1; then
-        # A historic path/namespace collision could leave this checkout with
-        # another Egregore's API key. Recover the configured org's existing key
-        # only through the membership-verifying endpoint, install it atomically,
-        # and retry. No credential bytes are printed.
-        github_token="$(grep '^GITHUB_TOKEN=' "$ROOT/.env" 2>/dev/null | cut -d= -f2-)"
-        [ -n "$github_token" ] || exit 1
-        encoded_slug="$(printf '%s' "$slug" | jq -sRr @uri)"
-        recovered="$(curl -sf "$api_url/api/org/$encoded_slug/key" \
-          -H "Authorization: Bearer $github_token" --connect-timeout 2 --max-time 12 \
-          2>/dev/null || true)"
-        printf '%s' "$recovered" | jq -e --arg slug "$slug" '
-          (.api_key | type == "string" and length > 0) and .org_slug == $slug
-        ' >/dev/null 2>&1 || exit 1
-        printf '%s' "$recovered" | \
-          EGREGORE_ROOT="$ROOT" \
-          PYTHONSAFEPATH=1 PYTHONPATH="$RUNTIME_ROOT${PYTHONPATH:+:$PYTHONPATH}" \
-          python3 -m egregore_runtime.identity_cli install-connected-key >/dev/null
-        api_key="$(grep '^EGREGORE_API_KEY=' "$ROOT/.env" 2>/dev/null | cut -d= -f2-)"
-        control_plane="$(curl -sf "$api_url/api/org/status" \
-          -H "Authorization: Bearer $api_key" --connect-timeout 2 --max-time 4 \
-          2>/dev/null || true)"
-        printf '%s' "$control_plane" | jq -e --arg slug "$slug" '
-          (.org_id | type == "string" and length > 0) and .slug == $slug
-        ' >/dev/null 2>&1 || exit 1
+      # records, then adopts their opaque IDs locally. A rejected key is
+      # recovered for the configured org only, through verified GitHub
+      # membership. No control-plane records are made.
+      probe_status
+      if ! status_ok; then
+        recover_key "$(rejection_code)" || exit 1
       fi
+      control_plane="$status_body"
       roster="$(curl -sf "$api_url/api/org/$slug/members?include_removed=true" \
         -H "Authorization: Bearer $api_key" --connect-timeout 2 --max-time 4 \
         2>/dev/null || true)"
@@ -102,7 +200,7 @@ case "${1:-ensure}" in
     resolved
     ;;
   *)
-    echo 'usage: bash bin/runtime-identity.sh {ensure|status}' >&2
+    echo 'usage: bash bin/runtime-identity.sh {ensure|status|recover [code]}' >&2
     exit 2
     ;;
 esac

package/runtime/claude/bin/screenshot.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# Render an HTML file or a URL to a PNG with headless Chrome.
+#   bin/screenshot.sh <file.html|url> <out.png> [width] [height]   (1440 x 2400)
+# Chrome: $EGREGORE_CHROME when set, with no fallback when it is wrong; else
+# the macOS Google Chrome app; else google-chrome or chromium on PATH. An
+# aborted render (no file, or zero bytes) is retried once; each try is capped
+# at 30 s. Prints "<out>: <bytes> bytes"; a failure prints one line naming the
+# cause and exits non-zero.
+# Headless Chrome enforces a minimum window width near 500 px, so phone checks
+# use 600. Heights above about 5400 px yield no file. Run one headless Chrome
+# at a time. Chrome dies at launch under the Codex sandbox, so in a minion run
+# the driver renders (.claude/skills/minion/SKILL.md, LAND).
+set -u
+
+die() { printf 'screenshot: %s\n' "$1" >&2; exit "${2:-1}"; }
+whole() { for n in "$@"; do case $n in '' | 0* | *[!0-9]*) return 1 ;; esac; done; }
+
+[ $# -ge 2 ] && [ $# -le 4 ] || die "usage: bin/screenshot.sh <file.html|url> <out.png> [width] [height]" 2
+input=$1 out=$2 width=${3:-1440} height=${4:-2400}
+whole "$width" "$height" || die "width and height must be whole pixels, got $width x $height" 2
+
+if [[ $input =~ ^[A-Za-z][A-Za-z0-9+.-]*:// ]] || [[ $input == data:* ]] || [[ $input == about:* ]]; then
+  url=$input
+else
+  [ -f "$input" ] && [ -r "$input" ] || die "input file missing: $input"
+  case $input in */*) dir=${input%/*} ;; *) dir=. ;; esac
+  dir=$(cd -- "${dir:-/}" && pwd -P) || die "input file missing: $input"
+  url=file://
+  # Percent-encode every byte outside the unreserved set, so a space, "#", "?",
+  # "%", a control character or a non-UTF-8 name reaches Chrome intact.
+  # shellcheck disable=SC2046 # the words are od's hex pairs; splitting them is the point
+  for byte in $(printf '%s' "${dir%/}/${input##*/}" | od -An -v -tx1); do
+    case $byte in
+      2[d-f] | 3[0-9] | 4[1-9a-f] | 5[0-9a] | 5f | 6[1-9a-f] | 7[0-9a] | 7e)
+        printf -v char '%b' "\\x$byte"; url+=$char ;;
+      *) url+=%$byte ;;
+    esac
+  done
+fi
+
+case $out in */*) outdir=${out%/*} ;; *) outdir=. ;; esac
+[ -d "${outdir:-/}" ] && [ -w "${outdir:-/}" ] || die "output directory missing or not writable: ${outdir:-/}"
+[ ! -d "$out" ] || die "output path is a directory: $out"
+
+if [ -n "${EGREGORE_CHROME:-}" ]; then
+  chrome=$EGREGORE_CHROME
+  [ -f "$chrome" ] && [ -x "$chrome" ] || die "no Chrome found: EGREGORE_CHROME=$chrome is not an executable file"
+else
+  chrome="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+  [ -x "$chrome" ] || chrome=$(command -v google-chrome || command -v chromium) \
+    || die "no Chrome found: set EGREGORE_CHROME, or install Google Chrome or Chromium"
+fi
+
+pid=
+trap '[ -z "$pid" ] || kill "$pid" 2>/dev/null' EXIT
+trap 'exit 130' INT TERM HUP
+
+render() { # one try; true when Chrome left a non-empty file at $out
+  rm -f -- "$out"; timed_out=0 ticks=0
+  "$chrome" --headless=new --disable-gpu --hide-scrollbars --window-size="$width,$height" \
+    --virtual-time-budget=4000 --screenshot="$out" "$url" >/dev/null 2>&1 &
+  pid=$!
+  while kill -0 "$pid" 2>/dev/null; do
+    [ "$ticks" -lt 150 ] || { kill -9 "$pid" 2>/dev/null; timed_out=1; break; }
+    sleep 0.2; ticks=$((ticks + 1))
+  done
+  wait "$pid" 2>/dev/null; pid=
+  [ -f "$out" ] && [ -s "$out" ]
+}
+
+if ! render && ! render; then
+  cause="no file at $out"
+  [ "$timed_out" = 0 ] || cause="the last try timed out after 30 s"
+  [ "$height" -le 5400 ] || cause="$cause; heights above about 5400 px yield no file"
+  die "render aborted twice ($cause)"
+fi
+printf '%s: %s bytes\n' "$out" "$(wc -c < "$out" | tr -d ' ')"

package/runtime/claude/bin/scroll.sh

@@ -3,7 +3,7 @@ set -euo pipefail
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 export EGREGORE_ROOT="$ROOT"
-export EGREGORE_SESSION_ID="${EGREGORE_SESSION_ID:-$(cat "$ROOT/.egregore-session-id" 2>/dev/null || true)}"
+export EGREGORE_SESSION_ID="${EGREGORE_SESSION_ID:-$(bash "$ROOT/bin/session-id.sh" --root "$ROOT" 2>/dev/null || cat "$ROOT/.egregore-session-id" 2>/dev/null || true)}"
 export PYTHONSAFEPATH=1 PYTHONPATH="$ROOT${PYTHONPATH:+:$PYTHONPATH}"
 
 exec python3 -m egregore_runtime.scroll_cli "$@"