create-egregore 0.20.2 → 0.21.0-runtime-mvp.2

package/runtime/claude/bin/handoff-lifecycle-job.sh

@@ -0,0 +1,146 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Recurring handoff lifecycle runner.
+#
+# `scan` is read-only. `run` applies only lifecycle-v1, explicitly classified
+# handoffs, then creates approval-required notification proposals for eligible
+# seven-day nudges. It never dispatches. Legacy unclassified backfill is
+# deliberately outside this job.
+#
+# Usage:
+#   bash bin/handoff-lifecycle-job.sh scan
+#   bash bin/handoff-lifecycle-job.sh run
+
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+USE_LEGACY_GRAPH=false
+ARGS=()
+for argument in "$@"; do
+  if [[ "$argument" == "--graph" ]]; then
+    USE_LEGACY_GRAPH=true
+  else
+    ARGS+=("$argument")
+  fi
+done
+ACTION="${ARGS[0]:-scan}"
+case "$ACTION" in
+  scan|run) ;;
+  *) jq -n '{error:"action must be scan or run"}'; exit 2 ;;
+esac
+
+# Canonical Markdown and append-only lifecycle events are authoritative. The
+# default job never queries graph state and never sends notifications. It may
+# only apply typed, snapshot-bound attention expiry; age cannot complete work.
+if [[ "$USE_LEGACY_GRAPH" != true ]]; then
+  PLAN="$(bash "$SCRIPT_DIR/bin/handoff-lifecycle.sh" scan --managed-only)"
+  if [[ "$ACTION" == "scan" ]]; then
+    printf '%s\n' "$PLAN" | jq '{
+      schema:"egregore-handoff-lifecycle-job/v2",
+      mode:"scan",
+      authority:"canonical_markdown",
+      graph_dependency:false,
+      applied:false,
+      plan:.
+    }'
+    exit 0
+  fi
+  SNAPSHOT="$(printf '%s\n' "$PLAN" | jq -r '.snapshot_id')"
+  TRANSITIONS="$(bash "$SCRIPT_DIR/bin/handoff-lifecycle.sh" apply \
+    --managed-only \
+    --snapshot "$SNAPSHOT" \
+    --confirm APPLY_SAFE_HANDOFF_LIFECYCLE)"
+  jq -n \
+    --argjson transitions "$TRANSITIONS" \
+    --argjson review "$(printf '%s\n' "$PLAN" | jq '.review_candidates')" \
+    '{
+      schema:"egregore-handoff-lifecycle-job/v2",
+      mode:"run",
+      authority:"canonical_markdown",
+      graph_dependency:false,
+      applied:true,
+      transitions:$transitions.transitions,
+      review_candidates:$review,
+      notifications:[]
+    }'
+  exit 0
+fi
+
+MODE="$(jq -r '.mode // "connected"' "$SCRIPT_DIR/egregore.json" 2>/dev/null || echo connected)"
+if [[ "$MODE" != "connected" ]]; then
+  jq -n '{
+    schema:"egregore-handoff-lifecycle-job/v1",
+    availability:"unavailable_in_this_configuration",
+    applied:false
+  }'
+  exit 0
+fi
+
+PLAN="$(bash "$SCRIPT_DIR/bin/handoff-lifecycle.sh" scan --managed-only)"
+if [[ "$ACTION" == "scan" ]]; then
+  printf '%s\n' "$PLAN" | jq '{
+    schema:"egregore-handoff-lifecycle-job/v1",
+    mode:"scan",
+    applied:false,
+    plan:.
+  }'
+  exit 0
+fi
+
+SNAPSHOT="$(printf '%s\n' "$PLAN" | jq -r '.snapshot_id')"
+TRANSITIONS="$(bash "$SCRIPT_DIR/bin/handoff-lifecycle.sh" apply \
+  --managed-only \
+  --snapshot "$SNAPSHOT" \
+  --confirm APPLY_SAFE_HANDOFF_LIFECYCLE)"
+
+NUDGE_RESULTS='[]'
+while IFS= read -r ITEM; do
+  [[ -n "$ITEM" ]] || continue
+  SID="$(printf '%s\n' "$ITEM" | jq -r '.id')"
+  CLAIM="$(bash "$SCRIPT_DIR/bin/graph-op.sh" claim-handoff-nudge "$SID")"
+  if ! printf '%s\n' "$CLAIM" | jq -e '.values[0][0] != null' >/dev/null 2>&1; then
+    continue
+  fi
+
+  TOPIC="$(printf '%s\n' "$CLAIM" | jq -r '.values[0][1] // "handoff"')"
+  RECIPIENTS="$(printf '%s\n' "$CLAIM" | jq -c '.values[0][2] // []')"
+  PROPOSALS='[]'
+  FAILED=0
+  while IFS= read -r RECIPIENT; do
+    [[ -n "$RECIPIENT" ]] || continue
+    MESSAGE="Handoff waiting for you: ${TOPIC}. Open /activity to read, complete, or expire it."
+    NOTIFY_RESULT="$(bash "$SCRIPT_DIR/bin/notify.sh" plan send "$RECIPIENT" "$MESSAGE" 2>/dev/null || echo '{}')"
+    if printf '%s\n' "$NOTIFY_RESULT" | jq -e '.status == "approval_required"' >/dev/null 2>&1; then
+      PROPOSALS="$(printf '%s\n' "$PROPOSALS" | jq \
+        --argjson proposal "$NOTIFY_RESULT" '. + [$proposal]')"
+    else
+      FAILED=$((FAILED + 1))
+    fi
+  done < <(printf '%s\n' "$RECIPIENTS" | jq -r '.[]')
+
+  bash "$SCRIPT_DIR/bin/graph-op.sh" release-handoff-nudge "$SID" >/dev/null
+  if [[ "$(printf '%s\n' "$PROPOSALS" | jq 'length')" -gt 0 ]]; then
+    STATUS="approval_required"
+  else
+    STATUS="unavailable"
+  fi
+
+  NUDGE_RESULTS="$(printf '%s\n' "$NUDGE_RESULTS" | jq \
+    --arg id "$SID" \
+    --arg topic "$TOPIC" \
+    --arg status "$STATUS" \
+    --argjson proposals "$PROPOSALS" \
+    --argjson failed "$FAILED" \
+    '. + [{id:$id,topic:$topic,status:$status,proposals:$proposals,failed:$failed}]')"
+done < <(printf '%s\n' "$PLAN" | jq -c '.review_candidates[] | select(.action=="nudge")')
+
+jq -n \
+  --argjson transitions "$TRANSITIONS" \
+  --argjson nudges "$NUDGE_RESULTS" \
+  '{
+    schema:"egregore-handoff-lifecycle-job/v1",
+    mode:"run",
+    applied:true,
+    managed_only:true,
+    transitions:$transitions.transitions,
+    nudges:$nudges
+  }'

package/runtime/claude/bin/handoff-lifecycle.sh

@@ -0,0 +1,280 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Deterministic handoff lifecycle reconciliation.
+#
+# `scan` is read-only and produces a versioned, hash-bound plan. `apply` can
+# execute only high-confidence transitions from an unchanged plan:
+#   - read/claimed -> done when one recipient has a completed IMPLEMENTS session
+#   - open FYI -> expired after the configured age floor
+#   - untouched pending -> expired after the configured lifecycle TTL
+#
+# Age never marks a handoff done. Read/claimed action and feedback handoffs
+# without implementation evidence stay open for human review.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+USE_LEGACY_GRAPH=false
+RUNTIME_ARGS=()
+for argument in "$@"; do
+  if [ "$argument" = "--graph" ]; then
+    USE_LEGACY_GRAPH=true
+  else
+    RUNTIME_ARGS+=("$argument")
+  fi
+done
+
+# Canonical Markdown is authoritative in every mode. The preserved graph
+# implementation is an explicit compatibility/projection adapter only.
+if [ "$USE_LEGACY_GRAPH" != true ]; then
+  export PYTHONPATH="$SCRIPT_DIR${PYTHONPATH:+:$PYTHONPATH}"
+  exec python3 -m egregore_runtime.lifecycle_cli "${RUNTIME_ARGS[@]}"
+fi
+set -- "${RUNTIME_ARGS[@]}"
+
+GS="$SCRIPT_DIR/bin/graph.sh"
+ACTION="${1:-scan}"
+shift || true
+
+usage() {
+  cat <<'EOF'
+Usage:
+  handoff-lifecycle.sh scan [--days N] [--user HANDLE] [--managed-only]
+  handoff-lifecycle.sh action <read|claim|done|expire|reopen|review> ARTIFACT_ID
+                              [--expected-revision REV]
+  handoff-lifecycle.sh apply --snapshot SHA256 --confirm APPLY_SAFE_HANDOFF_LIFECYCLE
+                             [--days N] [--user HANDLE] [--managed-only]
+
+scan is read-only. apply fails closed when canonical state changed after scan.
+--managed-only limits the plan to lifecycle-v1 handoffs with explicit intent;
+it is the safe boundary for unattended recurring execution.
+Add --graph to use the preserved legacy graph projection explicitly.
+EOF
+}
+
+if [[ "$ACTION" == "--help" || "$ACTION" == "-h" ]]; then
+  usage
+  exit 0
+fi
+if [[ "$ACTION" != "scan" && "$ACTION" != "apply" ]]; then
+  echo '{"error":"action must be scan or apply"}'
+  exit 2
+fi
+
+DAYS=14
+USER_REF=""
+EXPECTED_SNAPSHOT=""
+CONFIRM=""
+MANAGED_ONLY=false
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --days) DAYS="${2:?missing days}"; shift 2 ;;
+    --user) USER_REF="${2:?missing user}"; shift 2 ;;
+    --managed-only) MANAGED_ONLY=true; shift ;;
+    --snapshot) EXPECTED_SNAPSHOT="${2:?missing snapshot}"; shift 2 ;;
+    --confirm) CONFIRM="${2:?missing confirmation}"; shift 2 ;;
+    *) echo '{"error":"unknown option","option":"'"$1"'"}'; exit 2 ;;
+  esac
+done
+
+if ! [[ "$DAYS" =~ ^[0-9]+$ ]] || [[ "$DAYS" -lt 1 || "$DAYS" -gt 365 ]]; then
+  echo '{"error":"days must be between 1 and 365"}'
+  exit 2
+fi
+
+MODE="$(jq -r '.mode // "connected"' "$SCRIPT_DIR/egregore.json" 2>/dev/null || echo connected)"
+if [[ "$MODE" == "local" ]]; then
+  echo '{"schema":"egregore-handoff-lifecycle-plan/v1","availability":"unavailable_in_this_configuration","must_abstain":true}'
+  exit 0
+fi
+
+build_plan() {
+  local raw rows snapshot
+  raw="$(bash "$GS" query "
+    MATCH (s:Session)-[:HANDED_TO]->(recipient:Person)
+    WHERE (\$user = ''
+           OR toLower(recipient.name) = toLower(\$user)
+           OR toLower(coalesce(recipient.github, '')) = toLower(\$user))
+      AND coalesce(s.handoffStatus, 'pending') IN ['pending','read','claimed']
+      AND (NOT \$managedOnly
+           OR (coalesce(s.handoffLifecycleVersion, 0) >= 1
+               AND coalesce(s.handoffIntent, 'unclassified') IN ['action','feedback','fyi']))
+    WITH DISTINCT s, recipient
+    OPTIONAL MATCH (s)-[:BY]->(author:Person)
+    WITH s, recipient, author,
+         size([(s)-[:HANDED_TO]->(:Person) | 1]) AS recipientCount
+    OPTIONAL MATCH (impl:Session)-[:IMPLEMENTS]->(s)
+    OPTIONAL MATCH (impl)-[:BY]->(implAuthor:Person)
+    WITH s, recipient, author, recipientCount,
+         head([candidate IN collect(DISTINCT
+           CASE
+             WHEN implAuthor = recipient
+              AND (impl.wrappedAt IS NOT NULL
+                   OR impl.status IN ['completed','handed_off','wrapped'])
+             THEN {id: impl.id, status: impl.status}
+             ELSE null
+           END) WHERE candidate IS NOT NULL]) AS implementation
+    WITH s, recipient, author, recipientCount, implementation,
+         CASE WHEN s.date IS NULL THEN null
+              ELSE duration.inDays(date(s.date), date()).days END AS ageDays
+    RETURN s.id AS id,
+           s.topic AS topic,
+           coalesce(author.name, s.author, 'unknown') AS author,
+           recipient.name AS recipient,
+           toString(s.date) AS date,
+           coalesce(s.handoffStatus, 'pending') AS status,
+           coalesce(s.handoffIntent, 'unclassified') AS intent,
+           ageDays,
+           recipientCount,
+           implementation.id AS implementationId,
+           implementation.status AS implementationStatus,
+           s.handoffLifecycleVersion AS lifecycleVersion,
+           toString(s.handoffNudgedAt) AS nudgedAt
+    ORDER BY s.date DESC, recipient.name
+  " "$(jq -n --arg user "$USER_REF" --argjson managedOnly "$MANAGED_ONLY" \
+    '{user:$user,managedOnly:$managedOnly}')")"
+
+  if ! rows="$(printf '%s' "$raw" | jq -c '
+    (.values // []) | map({
+      id:.[0], topic:.[1], author:.[2], recipient:.[3], date:.[4],
+      status:.[5], intent:.[6], age_days:.[7], recipient_count:.[8],
+      implementation_id:.[9], implementation_status:.[10],
+      lifecycle_version:.[11], nudged_at:.[12]
+    }) | sort_by(.id, .recipient)
+  ' 2>/dev/null)"; then
+    echo '{"error":"invalid graph response"}'
+    return 1
+  fi
+
+  snapshot="$(printf '%s' "$rows" | openssl dgst -sha256 | awk '{print $NF}')"
+  jq -n \
+    --arg snapshot "$snapshot" \
+    --arg user "$USER_REF" \
+    --argjson days "$DAYS" \
+    --argjson managed_only "$MANAGED_ONLY" \
+    --argjson rows "$rows" '
+    def recommendation:
+      if ((.status == "read" or .status == "claimed")
+          and .recipient_count == 1
+          and .implementation_id != null)
+      then {action:"close", reason:"single_recipient_implemented", confidence:"high"}
+      elif (.intent == "fyi" and (.age_days // 0) >= $days)
+      then {action:"expire", reason:"fyi_age_floor", confidence:"high"}
+      elif (.status == "pending" and (.age_days // 0) >= $days)
+      then {action:"expire", reason:"pending_ttl_elapsed", confidence:"policy"}
+      elif ((.age_days // 0) >= $days)
+      then {action:"review", reason:
+              (if .intent == "unclassified"
+               then "stale_unclassified"
+               else "stale_requires_human" end),
+            confidence:"none"}
+      elif ((.age_days // 0) >= 7 and .recipient_count > 1)
+      then {action:"review", reason:"multi_recipient_requires_human", confidence:"none"}
+      elif ((.age_days // 0) >= 7 and .nudged_at == null)
+      then {action:"nudge", reason:"open_seven_days", confidence:"none"}
+      elif ((.age_days // 0) >= 7)
+      then {action:"keep", reason:"awaiting_after_nudge", confidence:"none"}
+      else {action:"keep", reason:"recent_open", confidence:"none"}
+      end;
+    ($rows | map(. + recommendation)) as $items
+    | {
+        schema:"egregore-handoff-lifecycle-plan/v1",
+        snapshot_id:$snapshot,
+        subject:(if $user == "" then "all" else $user end),
+        threshold_days:$days,
+        managed_only:$managed_only,
+        state_scope:"session",
+        state_scope_warning:"Status is stored on Session, so automatic close requires exactly one recipient.",
+        counts:{
+          open_rows:($items|length),
+          unique_handoffs:([$items[].id]|unique|length),
+          duplicate_recipient_rows:(($items|length)-([$items[].id]|unique|length)),
+          close:([$items[]|select(.action=="close")]|unique_by(.id)|length),
+          expire:([$items[]|select(.action=="expire")]|unique_by(.id)|length),
+          review:([$items[]|select(.action=="review")]|unique_by(.id)|length),
+          nudge:([$items[]|select(.action=="nudge")]|unique_by(.id)|length),
+          keep:([$items[]|select(.action=="keep")]|unique_by(.id)|length),
+          unclassified:([$items[]|select(.intent=="unclassified")]|unique_by(.id)|length)
+        },
+        safe_candidates:([$items[]|select(.action=="close" or .action=="expire")]|unique_by(.id)),
+        review_candidates:([$items[]|select(.action=="review" or .action=="nudge")]|unique_by(.id)),
+        items:$items,
+        apply_contract:{
+          requires_snapshot:true,
+          confirmation:"APPLY_SAFE_HANDOFF_LIFECYCLE",
+          age_alone_never_marks_done:true,
+          pending_ttl_may_expire_unacknowledged_work:true
+        }
+      }
+  '
+}
+
+PLAN="$(build_plan)"
+if [[ "$ACTION" == "scan" ]]; then
+  printf '%s\n' "$PLAN"
+  exit 0
+fi
+
+if [[ -z "$EXPECTED_SNAPSHOT" || "$CONFIRM" != "APPLY_SAFE_HANDOFF_LIFECYCLE" ]]; then
+  printf '%s\n' "$PLAN" | jq '. + {
+    applied:false,
+    error:"apply requires the current --snapshot and --confirm APPLY_SAFE_HANDOFF_LIFECYCLE"
+  }'
+  exit 3
+fi
+
+CURRENT_SNAPSHOT="$(printf '%s' "$PLAN" | jq -r '.snapshot_id')"
+if [[ "$CURRENT_SNAPSHOT" != "$EXPECTED_SNAPSHOT" ]]; then
+  printf '%s\n' "$PLAN" | jq --arg expected "$EXPECTED_SNAPSHOT" '. + {
+    applied:false,
+    error:"snapshot_changed",
+    expected_snapshot:$expected
+  }'
+  exit 4
+fi
+
+CLOSE_IDS="$(printf '%s' "$PLAN" | jq -c '[.safe_candidates[]|select(.action=="close")|.id]|unique')"
+EXPIRE_IDS="$(printf '%s' "$PLAN" | jq -c '[.safe_candidates[]|select(.action=="expire")|.id]|unique')"
+
+if [[ "$CLOSE_IDS" == "[]" && "$EXPIRE_IDS" == "[]" ]]; then
+  printf '%s\n' "$PLAN" | jq '. + {applied:true,transitions:{closed:0,expired:0}}'
+  exit 0
+fi
+
+RESULT="$(bash "$GS" query "
+  UNWIND \$closeIds AS closeId
+  MATCH (closed:Session {id: closeId})
+  WHERE coalesce(closed.handoffStatus, 'pending') IN ['read','claimed']
+  SET closed.handoffStatus = 'done',
+      closed.handoffDoneAt = coalesce(closed.handoffDoneAt, datetime()),
+      closed.handoffUpdatedAt = datetime(),
+      closed.handoffLifecycleReason = 'single_recipient_implemented',
+      closed.handoffLifecycleVersion = 1
+  WITH count(closed) AS closedCount
+  CALL {
+    WITH \$expireIds AS expireIds
+    UNWIND expireIds AS expireId
+    MATCH (expired:Session {id: expireId})
+    WHERE coalesce(expired.handoffStatus, 'pending') IN ['pending','read','claimed']
+      AND (expired.handoffIntent = 'fyi'
+           OR coalesce(expired.handoffStatus, 'pending') = 'pending')
+    SET expired.handoffStatus = 'expired',
+        expired.handoffExpiredAt = coalesce(expired.handoffExpiredAt, datetime()),
+        expired.handoffUpdatedAt = datetime(),
+        expired.handoffLifecycleReason =
+          CASE WHEN expired.handoffIntent = 'fyi'
+               THEN 'fyi_age_floor'
+               ELSE 'pending_ttl_elapsed' END,
+        expired.handoffLifecycleVersion = 1
+    RETURN count(expired) AS expiredCount
+  }
+  RETURN closedCount, expiredCount
+" "$(jq -n --argjson closeIds "$CLOSE_IDS" --argjson expireIds "$EXPIRE_IDS" \
+  '{closeIds:$closeIds,expireIds:$expireIds}')")"
+
+printf '%s\n' "$PLAN" | jq --argjson result "$RESULT" '. + {
+  applied:true,
+  transitions:{
+    closed:($result.values[0][0] // 0),
+    expired:($result.values[0][1] // 0)
+  }
+}'

package/runtime/claude/bin/handoff-pr-backfill.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+# handoff-pr-backfill.sh — fill in PR numbers in a handoff file's ## Repo State
+# table, then re-commit + push the memory repo. Detached fire-and-forget from
+# /handoff's hot path so user-visible latency doesn't include N × `gh pr list`.
+#
+# Usage:
+#   handoff-pr-backfill.sh <abs-handoff-file> <topic>
+#
+# Reads the ## Repo State table, looks up each (repo, branch)'s open PR via
+# `gh pr list`, rewrites the PR column from `—` to `#N`, commits the memory
+# repo, pushes to main. Silent on all failures — this is cosmetic.
+#
+# Detached usage (the skill / orchestrator call it this way):
+#   ( bash bin/handoff-pr-backfill.sh "$ABS_FILE" "$TOPIC" >/dev/null 2>&1 & ) >/dev/null 2>&1
+
+set -uo pipefail
+
+ABS_FILE="${1:-}"
+TOPIC="${2:-handoff}"
+
+[ -n "$ABS_FILE" ] && [ -f "$ABS_FILE" ] || exit 0
+
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+CONFIG="$SCRIPT_DIR/egregore.json"
+
+command -v gh >/dev/null 2>&1 || exit 0
+command -v jq >/dev/null 2>&1 || exit 0
+
+GITHUB_ORG=$(jq -r '.github_org // empty' "$CONFIG" 2>/dev/null)
+[ -n "$GITHUB_ORG" ] || exit 0
+
+# Extract the ## Repo State table rows: format is `| repo | branch | — | base |`.
+# Skip header and separator lines (first two rows of the markdown table).
+ROWS=$(awk '
+  /^## Repo State/ { in_section=1; next }
+  in_section && /^## / { in_section=0 }
+  in_section && /^\|/ && !/^\|[-\s]/ && !/^\| Repo/ { print }
+' "$ABS_FILE" 2>/dev/null)
+
+[ -n "$ROWS" ] || exit 0
+
+UPDATED=0
+while IFS= read -r row; do
+  [ -z "$row" ] && continue
+  # Parse: | repo | branch | pr | base |
+  repo=$(echo "$row" | awk -F'|' '{gsub(/^ +| +$/,"",$2); print $2}')
+  branch=$(echo "$row" | awk -F'|' '{gsub(/^ +| +$/,"",$3); print $3}')
+  pr_col=$(echo "$row" | awk -F'|' '{gsub(/^ +| +$/,"",$4); print $4}')
+
+  # Only backfill `—` cells (leave `#N` alone)
+  [ "$pr_col" = "—" ] || continue
+  [ -n "$repo" ] && [ -n "$branch" ] || continue
+
+  pr_num=$(gh pr list --repo "$GITHUB_ORG/$repo" --head "$branch" --json number --jq '.[0].number // empty' 2>/dev/null || echo "")
+  [ -n "$pr_num" ] || continue
+
+  # Rewrite the `—` in this branch's row to `#N`. Match by branch name to
+  # avoid cross-repo collisions when repos share branch names.
+  awk -v branch="$branch" -v pr="#$pr_num" '
+    BEGIN { in_section=0 }
+    /^## Repo State/ { in_section=1; print; next }
+    in_section && /^## / { in_section=0 }
+    in_section && $0 ~ "\\| " branch " " && /—/ {
+      sub(/—/, pr)
+      print; next
+    }
+    { print }
+  ' "$ABS_FILE" > "$ABS_FILE.tmp" && mv "$ABS_FILE.tmp" "$ABS_FILE"
+  UPDATED=1
+done <<< "$ROWS"
+
+[ "$UPDATED" = "1" ] || exit 0
+
+# Re-commit + push the memory repo with the backfilled PR numbers.
+MEMORY_DIR="$SCRIPT_DIR/memory"
+if [ -d "$MEMORY_DIR" ]; then
+  (
+    cd "$MEMORY_DIR" || exit 0
+    git add -A >/dev/null 2>&1
+    git commit -m "chore(handoff): backfill PR numbers for $TOPIC" >/dev/null 2>&1 || exit 0
+    git pull --rebase origin main --quiet >/dev/null 2>&1
+    git push origin main --quiet >/dev/null 2>&1
+  ) || true
+fi
+
+exit 0

package/runtime/claude/bin/handoff-preview.sh

@@ -0,0 +1,169 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Private preview/approval bridge for internal handoffs. Canonical Markdown is
+# supplied once during preview; approval references an opaque, single-use token.
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+STORE_ROOT="${EGREGORE_HANDOFF_PREVIEW_DIR:-${TMPDIR:-/tmp}/egregore-handoff-previews}"
+MAX_AGE_SECONDS="${EGREGORE_HANDOFF_PREVIEW_MAX_AGE:-21600}"
+
+usage() {
+  cat >&2 <<'EOF'
+usage:
+  bash bin/handoff-preview.sh preview --author HANDLE --recipient HANDLE \
+    --topic TOPIC --intent action|feedback|fyi \
+    --content-mode supplied|generated < handoff.md
+  bash bin/handoff-preview.sh approve TOKEN
+EOF
+}
+
+sha256_file() {
+  if command -v openssl >/dev/null 2>&1; then
+    openssl dgst -sha256 "$1" | awk '{print $NF}'
+  elif command -v shasum >/dev/null 2>&1; then
+    shasum -a 256 "$1" | awk '{print $1}'
+  else
+    sha256sum "$1" | awk '{print $1}'
+  fi
+}
+
+new_token() {
+  if command -v openssl >/dev/null 2>&1; then
+    openssl rand -hex 16
+  else
+    printf '%s' "$(date +%s)-$$-${RANDOM:-0}" | sha256sum | awk '{print substr($1,1,32)}'
+  fi
+}
+
+validate_token() {
+  [[ "$1" =~ ^[a-f0-9]{32}$ ]] || {
+    echo "handoff preview token is invalid" >&2
+    exit 2
+  }
+}
+
+preview() {
+  local author="" recipient="" topic="" intent="" content_mode=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --author) author="${2:-}"; shift 2 ;;
+      --recipient) recipient="${2:-}"; shift 2 ;;
+      --topic) topic="${2:-}"; shift 2 ;;
+      --intent) intent="${2:-}"; shift 2 ;;
+      --content-mode) content_mode="${2:-}"; shift 2 ;;
+      *) echo "unknown preview option: $1" >&2; usage; exit 2 ;;
+    esac
+  done
+
+  [ -n "$author" ] || { echo "handoff preview requires --author" >&2; exit 2; }
+  [ -n "$topic" ] || { echo "handoff preview requires --topic" >&2; exit 2; }
+  case "$intent" in action|feedback|fyi) ;; *) echo "invalid handoff intent" >&2; exit 2 ;; esac
+  case "$content_mode" in supplied|generated) ;; *) echo "invalid handoff content mode" >&2; exit 2 ;; esac
+
+  umask 077
+  mkdir -p "$STORE_ROOT"
+  chmod 700 "$STORE_ROOT"
+
+  local token content_file metadata_file digest
+  token="$(new_token)"
+  validate_token "$token"
+  content_file="$STORE_ROOT/$token.md"
+  metadata_file="$STORE_ROOT/$token.json"
+  cat > "$content_file"
+  [ -s "$content_file" ] || {
+    rm -f "$content_file"
+    echo "handoff preview input is empty" >&2
+    exit 2
+  }
+  digest="$(sha256_file "$content_file")"
+  jq -n \
+    --arg author "$author" \
+    --arg recipient "$recipient" \
+    --arg topic "$topic" \
+    --arg intent "$intent" \
+    --arg contentMode "$content_mode" \
+    --arg digest "$digest" \
+    --argjson createdAt "$(date +%s)" \
+    '{author:$author,recipient:$recipient,topic:$topic,intent:$intent,contentMode:$contentMode,digest:$digest,createdAt:$createdAt}' \
+    > "$metadata_file"
+
+  if ! bash "$ROOT/bin/node-run.sh" \
+    "$ROOT/packages/egregore-artifacts/bin/cli.js" handoff "$content_file" \
+    --verify-fidelity; then
+    rm -f "$content_file" "$metadata_file"
+    exit 1
+  fi
+
+  printf 'HANDOFF_PREVIEW_TOKEN=%s\n' "$token"
+}
+
+approve() {
+  [ $# -eq 1 ] || { usage; exit 2; }
+  local token="$1"
+  validate_token "$token"
+
+  local content_file="$STORE_ROOT/$token.md"
+  local metadata_file="$STORE_ROOT/$token.json"
+  local lock_dir="$STORE_ROOT/$token.approving"
+  [ -f "$content_file" ] && [ -f "$metadata_file" ] || {
+    echo "handoff preview is missing, expired, or already used" >&2
+    exit 1
+  }
+  if ! mkdir "$lock_dir" 2>/dev/null; then
+    echo "handoff preview approval is already running" >&2
+    exit 1
+  fi
+
+  local expected_digest actual_digest created_at now age
+  expected_digest="$(jq -er '.digest' "$metadata_file")"
+  actual_digest="$(sha256_file "$content_file")"
+  if [ "$expected_digest" != "$actual_digest" ]; then
+    rmdir "$lock_dir" 2>/dev/null || true
+    echo "handoff preview content changed after approval was requested" >&2
+    exit 1
+  fi
+  created_at="$(jq -er '.createdAt' "$metadata_file")"
+  now="$(date +%s)"
+  age=$((now - created_at))
+  if [ "$age" -lt 0 ] || [ "$age" -gt "$MAX_AGE_SECONDS" ]; then
+    rmdir "$lock_dir" 2>/dev/null || true
+    echo "handoff preview expired; render a fresh preview" >&2
+    exit 1
+  fi
+
+  local author recipient topic intent content_mode
+  author="$(jq -er '.author' "$metadata_file")"
+  recipient="$(jq -er '.recipient' "$metadata_file")"
+  topic="$(jq -er '.topic' "$metadata_file")"
+  intent="$(jq -er '.intent' "$metadata_file")"
+  content_mode="$(jq -er '.contentMode' "$metadata_file")"
+
+  local result_tmp
+  result_tmp="$(mktemp -d -t egregore-handoff-result-XXXXXX)"
+  local args=(
+    capture --mode addressed --author "$author" --topic "$topic"
+    --intent "$intent" --content-mode "$content_mode"
+  )
+  [ -z "$recipient" ] || args+=(--recipient "$recipient")
+
+  if ! TMPDIR="$result_tmp" bash "$ROOT/bin/artifact-writeback.sh" "${args[@]}" \
+    < "$content_file"; then
+    rmdir "$lock_dir" 2>/dev/null || true
+    exit 1
+  fi
+
+  # Consume the approved token before rendering. A renderer failure must not
+  # make a successful canonical write eligible for accidental replay.
+  mv "$content_file" "$result_tmp/approved-handoff.md"
+  mv "$metadata_file" "$result_tmp/approved-handoff.json"
+  rmdir "$lock_dir" 2>/dev/null || true
+  bash "$ROOT/bin/render-card.sh" \
+    --result "$result_tmp/capture-run-result.json"
+}
+
+case "${1:-}" in
+  preview) shift; preview "$@" ;;
+  approve) shift; approve "$@" ;;
+  *) usage; exit 2 ;;
+esac