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

package/runtime/prime/bin/graph-projection.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# Explicit management boundary for the optional derived graph projection.
+# Usage: bash bin/graph-projection.sh {status|verify|rebuild} [--enable]
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+COMMAND="${1:-status}"
+shift || true
+ENABLED=false
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --enable) ENABLED=true ;;
+    --help|-h)
+      echo "Usage: graph-projection.sh {status|verify|rebuild} [--enable]"
+      exit 0
+      ;;
+    *) echo "Unknown option: $1" >&2; exit 2 ;;
+  esac
+  shift
+done
+
+case "$COMMAND" in
+  status|verify|rebuild) ;;
+  --help|-h)
+    echo "Usage: graph-projection.sh {status|verify|rebuild} [--enable]"
+    exit 0
+    ;;
+  *) echo "Usage: graph-projection.sh {status|verify|rebuild} [--enable]" >&2; exit 2 ;;
+esac
+
+RUNTIME_PYTHONPATH="$ROOT"
+if [ -n "${PYTHONPATH:-}" ]; then
+  RUNTIME_PYTHONPATH="$RUNTIME_PYTHONPATH:$PYTHONPATH"
+fi
+
+GRAPH_OVERRIDE=0
+[ "$ENABLED" = "true" ] && GRAPH_OVERRIDE=1
+ROOT="$ROOT" ENABLED="$ENABLED" COMMAND="$COMMAND" \
+EGREGORE_GRAPH_PROJECTION="$GRAPH_OVERRIDE" PYTHONPATH="$RUNTIME_PYTHONPATH" \
+python3 - <<'PY'
+import json
+import os
+from pathlib import Path
+
+from egregore_runtime.graph import graph_projection
+
+projection = graph_projection(
+    Path(os.environ["ROOT"]), enabled=os.environ["ENABLED"] == "true"
+)
+command = os.environ["COMMAND"]
+health = projection.rebuild() if command == "rebuild" else projection.verify()
+print(json.dumps(health.to_dict(), sort_keys=True))
+PY

package/runtime/prime/bin/graph-wal.sh

@@ -12,6 +12,7 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+CONFIG="$SCRIPT_DIR/egregore.json"
 
 if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
   echo "Usage: graph-wal.sh <command>"
@@ -25,6 +26,18 @@ if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
   exit 0
 fi
 
+# Do not accumulate a shadow write backlog while the optional projection is
+# quarantined. Canonical Markdown/Git remains the complete source of truth.
+# shellcheck source=bin/lib/config.sh
+source "$SCRIPT_DIR/bin/lib/config.sh"
+if ! _graph_projection_enabled; then
+  case "${1:-status}" in
+    status) echo '{"pending":0,"bytes":0,"status":"disabled","reason":"graph_projection_disabled"}' ;;
+    *) echo '{"status":"disabled","reason":"graph_projection_disabled"}' ;;
+  esac
+  exit 0
+fi
+
 WAL_DIR="$HOME/.egregore"
 # WAL file is per-instance to prevent cross-org data leakage on multi-instance machines
 PROJ_HASH=$(echo -n "$SCRIPT_DIR" | md5 2>/dev/null || echo -n "$SCRIPT_DIR" | md5sum 2>/dev/null | cut -d' ' -f1)

package/runtime/prime/bin/graph.sh

@@ -9,6 +9,50 @@ if [ ! -f "$CONFIG" ]; then
   exit 1
 fi
 
+# Optional compatibility projection. A dogfood instance can quarantine every
+# graph path without changing its Connected control-plane mode.
+# shellcheck source=bin/lib/config.sh
+source "$SCRIPT_DIR/bin/lib/config.sh"
+if ! _graph_projection_enabled; then
+  case "${1:-}" in
+    query)  echo '{"results":[],"status":"disabled","reason":"graph_projection_disabled"}' ;;
+    schema) echo '{}' ;;
+    test)   echo '{"status":"disabled","reason":"graph_projection_disabled"}' ;;
+    *)      echo '{"results":[],"status":"disabled","reason":"graph_projection_disabled"}' ;;
+  esac
+  exit 0
+fi
+
+# --- Runtime cutover gate --------------------------------------------------
+# Once the Runtime/QMD MVP is activated, graph retrieval is not used by this
+# Runtime: background callers (attendant cache warm, greeting enrichment,
+# search enrichment) get silence with no network and no telemetry — observed
+# live as a wall of graph_query telemetry events from the attendant on an
+# upgraded instance. An explicitly requested projection read passes through
+# by setting EGREGORE_GRAPH_EXPLICIT=1 (bin/graph-op.sh named reads do).
+if [ "${EGREGORE_GRAPH_EXPLICIT:-0}" != "1" ]; then
+  _CUT_ORG=$(jq -r '.org_id // empty' "$CONFIG" 2>/dev/null)
+  if [ -n "$_CUT_ORG" ]; then
+    _CUT_MAIN="$SCRIPT_DIR"
+    if [ -f "$SCRIPT_DIR/.git" ]; then
+      _CUT_GD=$(sed -n 's/^gitdir: //p' "$SCRIPT_DIR/.git" 2>/dev/null)
+      case "$_CUT_GD" in */.git/worktrees/*) _CUT_MAIN="${_CUT_GD%/.git/worktrees/*}" ;; esac
+    fi
+    _CUT_MAIN=$(cd "$_CUT_MAIN" 2>/dev/null && pwd -P || printf '%s' "$SCRIPT_DIR")
+    _CUT_KEY=$(printf '%s|%s' "$_CUT_ORG" "$_CUT_MAIN" | shasum -a 256 2>/dev/null | cut -c1-16)
+    _CUT_REC="${EGREGORE_UPGRADE_ROOT:-$HOME/.egregore/runtime/upgrade}/${_CUT_KEY}/active.json"
+    if [ -f "$_CUT_REC" ] && [ "$(jq -r '.retrieval // empty' "$_CUT_REC" 2>/dev/null)" = "runtime-qmd" ]; then
+      case "${1:-}" in
+        query)  echo '{"results":[],"status":"disabled","reason":"runtime_qmd_active"}' ;;
+        schema) echo '{}' ;;
+        test)   echo '{"status":"disabled","reason":"runtime_qmd_active"}' ;;
+        *)      echo '{"results":[],"status":"disabled","reason":"runtime_qmd_active"}' ;;
+      esac
+      exit 0
+    fi
+  fi
+fi
+
 # --- Local mode gate: bail immediately, no .env sourcing, no network ---
 _MODE=$(jq -r '.mode // "connected"' "$CONFIG" 2>/dev/null)
 if [ "$_MODE" = "local" ]; then

package/runtime/prime/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/prime/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)
+  }
+}'