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

package/runtime/pi/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

package/runtime/pi/bin/handoff-run.sh

@@ -37,7 +37,9 @@ set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
 # shellcheck source=bin/lib/git-message.sh
-. "$SCRIPT_DIR/bin/lib/git-message.sh" 2>/dev/null || true
+if [ -f "$SCRIPT_DIR/bin/lib/git-message.sh" ]; then
+  . "$SCRIPT_DIR/bin/lib/git-message.sh"
+fi
 type egregore_commit >/dev/null 2>&1 || egregore_commit() {
   local gd="$1" m="$3"; shift 3; git -C "$gd" commit -m "$m" "$@"
 }
@@ -57,6 +59,7 @@ INTENT="action"
 NO_PUSH=0
 NO_NOTIFY=0
 NO_PUBLISH=0
+NO_INDEX=0
 COMPOSED=""    # optional house-kit JSON — the agent-composed render spec
 CONTENT_MODE="generated"
 INCLUDE_SESSION_ARTIFACTS=0
@@ -74,6 +77,7 @@ while [ $# -gt 0 ]; do
     --no-push)    NO_PUSH=1;          shift ;;
     --no-notify)  NO_NOTIFY=1;        shift ;;
     --no-publish) NO_PUBLISH=1;       shift ;;
+    --no-index)   NO_INDEX=1;         shift ;;
     *) echo "Unknown arg: $1" >&2; exit 1 ;;
   esac
 done
@@ -104,6 +108,7 @@ if [ "$CONTENT_MODE" = "supplied" ] && [ -n "$COMPOSED" ]; then
 fi
 
 MODE=$(jq -r '.mode // "connected"' "$CONFIG" 2>/dev/null || echo "connected")
+GRAPH_ENABLED="${EGREGORE_GRAPH_PROJECTION:-0}"
 TODAY=$(date +%Y-%m-%d)
 YYYY_MM=$(date +%Y-%m)
 DD=$(date +%d)
@@ -212,25 +217,30 @@ if [ -n "$REPO_STATE" ]; then
   printf '\n%s\n' "$REPO_STATE" >> "$ABS_FILE"
 fi
 
-# --- Prepend memory/handoffs/index.md -----------------------------------
-INDEX="$SCRIPT_DIR/memory/handoffs/index.md"
-mkdir -p "$(dirname "$INDEX")"
-[ -f "$INDEX" ] || printf '# Handoffs\n\n' > "$INDEX"
+# --- Legacy handoff ledger ----------------------------------------------
+# Runtime-owned capture skips this compatibility index. The canonical handoff
+# file is independently discoverable and QMD is a rebuildable projection;
+# mutating a second Markdown file would create a second canonical write that
+# the Runtime transaction did not authorize or include in provenance.
+if [ "$NO_INDEX" = "0" ]; then
+  INDEX="$SCRIPT_DIR/memory/handoffs/index.md"
+  mkdir -p "$(dirname "$INDEX")"
+  [ -f "$INDEX" ] || printf '# Handoffs\n\n' > "$INDEX"
+
+  if [ -n "$RECIPIENT" ]; then
+    IDX_LINE="- **${TODAY}** — ${AUTHOR}: ${TOPIC} (handoff to ${RECIPIENT})"
+  else
+    IDX_LINE="- **${TODAY}** — ${AUTHOR}: ${TOPIC} (handoff)"
+  fi
 
-if [ -n "$RECIPIENT" ]; then
-  IDX_LINE="- **${TODAY}** — ${AUTHOR}: ${TOPIC} (handoff to ${RECIPIENT})"
-else
-  IDX_LINE="- **${TODAY}** — ${AUTHOR}: ${TOPIC} (handoff)"
+  awk -v line="$IDX_LINE" '
+    BEGIN { inserted = 0 }
+    /^$/ && !inserted { print; print line; inserted = 1; next }
+    { print }
+    END { if (!inserted) print line }
+  ' "$INDEX" > "$INDEX.new" && mv "$INDEX.new" "$INDEX"
 fi
 
-# Insert after the first blank line (keeping the # header intact)
-awk -v line="$IDX_LINE" '
-  BEGIN { inserted = 0 }
-  /^$/ && !inserted { print; print line; inserted = 1; next }
-  { print }
-  END { if (!inserted) print line }
-' "$INDEX" > "$INDEX.new" && mv "$INDEX.new" "$INDEX"
-
 # --- Parallel stage: graph + memory + (publish → notification proposal) -
 #
 # Three independent branches fork here and join before we emit the result:
@@ -260,7 +270,7 @@ BRIEFING_SHORT=$(awk '/^## Briefing/{found=1; next} found && /^##/{exit} found &
 
 # --- Branch A: Graph index ---
 (
-  if [ "$MODE" = "connected" ]; then
+  if [ "$MODE" = "connected" ] && [ "$GRAPH_ENABLED" = "1" ]; then
     GJ=$(bash "$SCRIPT_DIR/bin/index-handoff.sh" "$ABS_FILE" 2>/dev/null || echo '{}')
     SID=$(echo "$GJ" | jq -r '.sessionId // ""' 2>/dev/null || echo "")
     RES=$(echo "$GJ" | jq -r '.resolved // 0' 2>/dev/null || echo 0)
@@ -273,7 +283,7 @@ BRIEFING_SHORT=$(awk '/^## Briefing/{found=1; next} found && /^##/{exit} found &
     fi
   else
     echo "null" > "$TMPD/subgraph"
-    printf '\n0\nskipped\n' > "$TMPD/graph"
+    printf '\n0\ndisabled\n' > "$TMPD/graph"
   fi
 ) &
 PID_GRAPH=$!
@@ -285,7 +295,7 @@ PID_GRAPH=$!
 # this before committing so the file always has the section.
 (
   ARTIFACTS_JSON="[]"
-  if [ "$MODE" = "connected" ]; then
+  if [ "$MODE" = "connected" ] && [ "$GRAPH_ENABLED" = "1" ]; then
     YY=$(date +%Y); MM=$(date +%-m); DD_NUM=$(date +%-d)
     RAW=$(bash "$SCRIPT_DIR/bin/graph.sh" query "
       MATCH (a:Artifact)-[:CONTRIBUTED_BY]->(p:Person {github: \$gh})
@@ -328,7 +338,11 @@ PID_ARTIFACTS=$!
     fi
 
     cd "$MEMORY_DIR"
-    git add "$REL_FILE" handoffs/index.md >/dev/null 2>&1
+    if [ "$NO_INDEX" = "1" ]; then
+      git add "$REL_FILE" >/dev/null 2>&1
+    else
+      git add "$REL_FILE" handoffs/index.md >/dev/null 2>&1
+    fi
 
     if [ -n "$RECIPIENT" ]; then
       MSG_COMMIT="chore(handoff): record ${TOPIC} (to ${RECIPIENT})"
@@ -405,14 +419,16 @@ PID_MEMORY=$!
       if [ "$RENDER_TYPE" = "composed" ]; then
         FIDELITY_ARGS+=(--source "$ABS_FILE")
       fi
-      if [ "${EGREGORE_USE_PUBLISHED:-0}" != "1" ] && [ -f "$LOCAL_CLI" ] && [ -d "$SCRIPT_DIR/packages/egregore-artifacts/node_modules/react" ]; then
-        if node "$LOCAL_CLI" "$RENDER_TYPE" "${RENDER_SRC:-$ABS_FILE}" "${FIDELITY_ARGS[@]}" --output "$RENDERED_HTML" >/dev/null 2>"$TMPD/render-error"; then
+      # Node always runs through the adapter (broken Volta/NVM shims are a
+      # live hazard in harness shells), and there is no npx/@latest fallback:
+      # a hidden registry fetch of a floating version is never an acceptable
+      # renderer. Missing local renderer → structured-only handoff.
+      if [ -f "$LOCAL_CLI" ] && [ -d "$SCRIPT_DIR/packages/egregore-artifacts/node_modules/react" ]; then
+        if bash "$SCRIPT_DIR/bin/node-run.sh" "$LOCAL_CLI" "$RENDER_TYPE" "${RENDER_SRC:-$ABS_FILE}" "${FIDELITY_ARGS[@]}" --output "$RENDERED_HTML" >/dev/null 2>"$TMPD/render-error"; then
           RENDER_OK=1
         fi
       else
-        if npx -y egregore-artifacts@latest "$RENDER_TYPE" "${RENDER_SRC:-$ABS_FILE}" "${FIDELITY_ARGS[@]}" --output "$RENDERED_HTML" >/dev/null 2>"$TMPD/render-error"; then
-          RENDER_OK=1
-        fi
+        echo "local egregore-artifacts renderer unavailable; sending structured handoff without custom HTML" > "$TMPD/render-error"
       fi
 
       # Step 2: build the emissary payload. If rendering succeeded AND the

package/runtime/pi/bin/ingest-graph.sh

@@ -31,6 +31,12 @@ case "$mode" in
   *) usage ;;
 esac
 
+if ! _graph_projection_enabled; then
+  jq -cn \
+    '{status:"stored",graph:"disabled",reason:"graph_projection_disabled",queries:0,batches:0,failed:0,replayable:true}'
+  exit 0
+fi
+
 plan="$(python3 "$PLANNER" plan "$manifest")"
 manifest_id="$(printf '%s' "$plan" | jq -r '.manifest_id')"
 query_count="$(printf '%s' "$plan" | jq -r '.query_count')"

package/runtime/pi/bin/ingest-item.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# Runtime-neutral adapter for one external source's staged admission lifecycle.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+export EGREGORE_ROOT="${EGREGORE_ROOT:-$ROOT}"
+export EGREGORE_SESSION_ID="${EGREGORE_SESSION_ID:-$(cat "$ROOT/.egregore-session-id" 2>/dev/null || true)}"
+export PYTHONPATH="$ROOT${PYTHONPATH:+:$PYTHONPATH}"
+
+exec python3 -m egregore_runtime.ingest_cli "$@"

package/runtime/pi/bin/ingest.sh

@@ -2,38 +2,56 @@
 set -euo pipefail
 
 # Org-scoped intake plane. Shared manifests live in memory/; normalized bodies
-# stay in this checkout's gitignored cache; qmd uses a separate per-org index.
+# stay in this checkout's gitignored cache. Indexing is routed through the
+# Egregore Local Retriever; this compatibility shell contains no QMD details.
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 export NODE_NO_WARNINGS=1
 PY="$ROOT/bin/ingest.py"
 SURFACE="$ROOT/bin/ingest_surface.py"
 SLUG="$(jq -r '.slug // "egregore"' "$ROOT/egregore.json")"
-INDEX="${SLUG}-ingest"
-COLLECTION="${SLUG}-ingest"
 INGEST_ROOT="${EGREGORE_INGEST_ROOT:-$ROOT/.egregore/ingest}"
 INGEST_META_ROOT="${EGREGORE_INGEST_META_ROOT:-$ROOT/memory/ingest}"
-QMD_VERSION="2.5.3"
 GRAPH_PROJECTOR="${EGREGORE_INGEST_GRAPH_PROJECTOR:-$ROOT/bin/ingest-graph.sh}"
 
-_qmd() {
-  if command -v qmd >/dev/null 2>&1; then
-    qmd --index "$INDEX" "$@"
-  else
-    npx -y "@tobilu/qmd@${QMD_VERSION}" --index "$INDEX" "$@"
-  fi
+_retriever() {
+  EGREGORE_ROOT="$ROOT" \
+    EGREGORE_INGEST_ROOT="$INGEST_ROOT" \
+    PYTHONPATH="$ROOT${PYTHONPATH:+:$PYTHONPATH}" \
+    python3 -m egregore_runtime.ingest_index_cli "$@"
 }
 
 _ensure_index() {
   mkdir -p "$INGEST_ROOT"
-  if ! _qmd collection list 2>/dev/null | grep -q "^${COLLECTION} "; then
-    _qmd collection add "$INGEST_ROOT" --name "$COLLECTION" >/dev/null
-  fi
-  _qmd update >/dev/null
+  _retriever update --background-embed >/dev/null
+}
+
+_register_manifest() {
+  local source="$1" source_root manifest source_record
+  source_root="$INGEST_META_ROOT/sources/$source"
+  manifest="$source_root/manifest.json"
+  source_record="$source_root/source.json"
+  case "$(cd "$INGEST_META_ROOT" 2>/dev/null && pwd -P)/" in
+    "$(cd "$ROOT/memory" 2>/dev/null && pwd -P)/"*) ;;
+    *)
+      # Explicit test/custom metadata roots are not canonical organizational
+      # state and therefore cannot be committed by the Runtime.
+      printf '%s\n' '{"status":"external-metadata-root","warnings":["manifest was not registered as canonical state"]}'
+      return 0
+      ;;
+  esac
+  EGREGORE_ROOT="$ROOT" \
+    PYTHONPATH="$ROOT${PYTHONPATH:+:$PYTHONPATH}" \
+    python3 -m egregore_runtime.ingest_cli register \
+      --source "$source" --manifest "$manifest" --source-record "$source_record"
 }
 
 _graph_sync() {
-  local source="${1:-}" manifest result status
+  local source="${1:-}" force="${2:-0}" manifest result status
+  if [ "${EGREGORE_GRAPH_PROJECTION:-0}" != "1" ] && [ "$force" != "1" ]; then
+    printf '%s\n' '{"status":"disabled","enabled":false,"reason":"canonical Markdown is authoritative; graph projection requires explicit opt-in","replayable":true}'
+    return 0
+  fi
   local total=0 succeeded=0 failed=0 stored=0 queries=0
   local manifests=()
   if [ -n "$source" ]; then
@@ -98,38 +116,44 @@ PY
 }
 
 cmd_add() {
-  local source="" summary graph final qmd_status
+  local source="" summary graph final qmd_status canonical_status
   local args=("$@")
   local i
   for ((i=0; i<${#args[@]}; i++)); do
     if [ "${args[$i]}" = "--source" ] && [ $((i+1)) -lt ${#args[@]} ]; then source="${args[$((i+1))]}"; fi
   done
   summary="$(python3 "$PY" add "$@")"
+  source="$(printf '%s' "$summary" | jq -r '.source')"
   _journal "$source" "normalized" "$(printf '%s' "$summary" | jq -c '{ingested,unchanged,metadata_updated,skipped,pruned}')"
+  if ! canonical_status="$(_register_manifest "$source")"; then
+    _journal "$source" "canonical_failed" '{"status":"failed"}'
+    printf '%s\n' "$summary" | jq '. + {status:"failed",canonical:{status:"failed"},qmd:{status:"not-attempted"},graph:{status:"not-attempted"}}'
+    return 1
+  fi
   if ! _ensure_index; then
     qmd_status='{"status":"failed"}'
     _journal "$source" "index_failed" "$qmd_status"
-    printf '%s\n' "$summary" | jq --argjson qmd "$qmd_status" '. + {status:"failed",qmd:$qmd,graph:{status:"not-attempted"}}'
+    printf '%s\n' "$summary" | jq --argjson canonical "$canonical_status" --argjson qmd "$qmd_status" '. + {status:"failed",canonical:$canonical,qmd:$qmd,graph:{status:"not-attempted"}}'
     return 1
   fi
   qmd_status='{"status":"indexed"}'
   if graph="$(_graph_sync "$source")"; then :; else :; fi
   if [ "$(printf '%s' "$summary" | jq -r .skipped)" -gt 0 ]; then
     _journal "$source" "extraction_attention" "$(printf '%s' "$summary" | jq -c '{skipped}')"
-    final="$(printf '%s' "$summary" | jq --argjson qmd "$qmd_status" --argjson graph "$graph" '. + {status:"attention",qmd:$qmd,graph:$graph}')"
+    final="$(printf '%s' "$summary" | jq --argjson canonical "$canonical_status" --argjson qmd "$qmd_status" --argjson graph "$graph" '. + {status:"attention",canonical:$canonical,qmd:$qmd,graph:$graph}')"
   elif [ "$(printf '%s' "$graph" | jq -r .status)" = "partial" ]; then
     _journal "$source" "graph_pending" "$graph"
-    final="$(printf '%s' "$summary" | jq --argjson qmd "$qmd_status" --argjson graph "$graph" '. + {status:"attention",qmd:$qmd,graph:$graph}')"
+    final="$(printf '%s' "$summary" | jq --argjson canonical "$canonical_status" --argjson qmd "$qmd_status" --argjson graph "$graph" '. + {status:"attention",canonical:$canonical,qmd:$qmd,graph:$graph}')"
   else
     _journal_clear "$source"
-    final="$(printf '%s' "$summary" | jq --argjson qmd "$qmd_status" --argjson graph "$graph" '. + {status:"complete",qmd:$qmd,graph:$graph}')"
+    final="$(printf '%s' "$summary" | jq --argjson canonical "$canonical_status" --argjson qmd "$qmd_status" --argjson graph "$graph" '. + {status:"complete",canonical:$canonical,qmd:$qmd,graph:$graph}')"
   fi
   printf '%s\n' "$final"
 }
 
 cmd_add_selection() {
   local manifest="${1:?usage: bin/ingest.sh add-selection MANIFEST}"
-  local source receipt_url receipt_token summary graph qmd_status outcome final message contract
+  local source receipt_url receipt_token summary graph qmd_status canonical_status outcome final message contract
   contract="$(python3 - "$manifest" <<'PY'
 import json, sys
 value = json.load(open(sys.argv[1], encoding="utf-8"))
@@ -144,8 +168,13 @@ PY
     _notify_receipt "$receipt_url" "$receipt_token" "$final"
     return 2
   fi
+  source="$(printf '%s' "$summary" | jq -r '.source')"
   _journal "$source" "normalized" "$(printf '%s' "$summary" | jq -c '{ingested,unchanged,metadata_updated,skipped,pruned}')"
-  if _ensure_index; then
+  if ! canonical_status="$(_register_manifest "$source")"; then
+    canonical_status='{"status":"failed"}'
+    qmd_status='{"status":"not-attempted"}'
+    _journal "$source" "canonical_failed" "$canonical_status"
+  elif _ensure_index; then
     qmd_status='{"status":"indexed"}'
   else
     qmd_status='{"status":"failed"}'
@@ -158,23 +187,23 @@ PY
   fi
   if [ "$(printf '%s' "$qmd_status" | jq -r .status)" != "indexed" ]; then
     outcome="index failed"
-    message="The normalized source was retained, but QMD did not finish indexing it. Run bin/ingest.sh reindex to repair it."
-    final="$(printf '%s' "$summary" | jq --argjson qmd "$qmd_status" --argjson graph "$graph" --arg outcome "$outcome" --arg message "$message" '. + {status:"failed",outcome:$outcome,message:$message,qmd:$qmd,graph:$graph}')"
+    message="The normalized source was retained, but the Local retrieval index did not finish updating. Run bin/ingest.sh reindex to repair it."
+    final="$(printf '%s' "$summary" | jq --argjson canonical "$canonical_status" --argjson qmd "$qmd_status" --argjson graph "$graph" --arg outcome "$outcome" --arg message "$message" '. + {status:"failed",outcome:$outcome,message:$message,canonical:$canonical,qmd:$qmd,graph:$graph}')"
   elif [ "$(printf '%s' "$summary" | jq -r '.skipped')" -gt 0 ]; then
     outcome="indexed with skipped files"
     message="Searchable files were indexed, but one or more files still need a compatible extractor. Their staging bytes were retained."
     _journal "$source" "extraction_attention" "$(printf '%s' "$summary" | jq -c '{skipped,selection_path}')"
-    final="$(printf '%s' "$summary" | jq --argjson qmd "$qmd_status" --argjson graph "$graph" --arg outcome "$outcome" --arg message "$message" '. + {status:"attention",outcome:$outcome,message:$message,qmd:$qmd,graph:$graph}')"
+    final="$(printf '%s' "$summary" | jq --argjson canonical "$canonical_status" --argjson qmd "$qmd_status" --argjson graph "$graph" --arg outcome "$outcome" --arg message "$message" '. + {status:"attention",outcome:$outcome,message:$message,canonical:$canonical,qmd:$qmd,graph:$graph}')"
   elif [ "$(printf '%s' "$graph" | jq -r .status)" = "partial" ]; then
     outcome="indexed · graph pending"
     message="The source is searchable now. Graph projection was incomplete and is recorded for retry."
     _journal "$source" "graph_pending" "$graph"
-    final="$(printf '%s' "$summary" | jq --argjson qmd "$qmd_status" --argjson graph "$graph" --arg outcome "$outcome" --arg message "$message" '. + {status:"attention",outcome:$outcome,message:$message,qmd:$qmd,graph:$graph}')"
+    final="$(printf '%s' "$summary" | jq --argjson canonical "$canonical_status" --argjson qmd "$qmd_status" --argjson graph "$graph" --arg outcome "$outcome" --arg message "$message" '. + {status:"attention",outcome:$outcome,message:$message,canonical:$canonical,qmd:$qmd,graph:$graph}')"
   else
     outcome="indexed · org-scoped · unverified"
     message="The files were validated, normalized, and added to this organization’s retrieval index."
     _journal_clear "$source"
-    final="$(printf '%s' "$summary" | jq --argjson qmd "$qmd_status" --argjson graph "$graph" --arg outcome "$outcome" --arg message "$message" '. + {status:"complete",outcome:$outcome,message:$message,qmd:$qmd,graph:$graph}')"
+    final="$(printf '%s' "$summary" | jq --argjson canonical "$canonical_status" --argjson qmd "$qmd_status" --argjson graph "$graph" --arg outcome "$outcome" --arg message "$message" '. + {status:"complete",outcome:$outcome,message:$message,canonical:$canonical,qmd:$qmd,graph:$graph}')"
   fi
   _notify_receipt "$receipt_url" "$receipt_token" "$final"
   printf '%s\n' "$final"
@@ -193,7 +222,7 @@ cmd_search() {
     esac
   done
   _ensure_index
-  raw="$(_qmd search "$query" -c "$COLLECTION" -n "$qmd_n" --all --json 2>/dev/null || echo '[]')"
+  raw="$(_retriever query --query "$query" --limit "$qmd_n" 2>/dev/null || echo '[]')"
   if [ ${#filter_args[@]} -gt 0 ]; then
     filtered="$(printf '%s' "$raw" | python3 "$PY" filter-results "${filter_args[@]}" --limit "$limit")"
   else
@@ -265,8 +294,8 @@ case "${1:-}" in
     fi
     printf '%s\n' "$graph"
     ;;
-  graph-sync) shift; _graph_sync "${1:-}" ;;
-  status) python3 "$PY" status; _qmd status 2>/dev/null || true ;;
+  graph-sync) shift; _graph_sync "${1:-}" 1 ;;
+  status) python3 "$PY" status; _retriever status 2>/dev/null || true ;;
   *)
     echo 'usage: bash bin/ingest.sh {select|add|add-selection|register-extraction|search|reindex|graph-sync|status}' >&2
     echo '  select [--no-open] [--timeout SECONDS]' >&2

package/runtime/pi/bin/invite.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+export EGREGORE_ROOT="${EGREGORE_ROOT:-$ROOT}"
+exec python3 -m egregore_runtime.invitation_cli "$@"

package/runtime/pi/bin/issue.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# Runtime-neutral adapter for canonical internal issues.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+export EGREGORE_ROOT="${EGREGORE_ROOT:-$ROOT}"
+export EGREGORE_SESSION_ID="${EGREGORE_SESSION_ID:-$(cat "$ROOT/.egregore-session-id" 2>/dev/null || true)}"
+export PYTHONPATH="$ROOT${PYTHONPATH:+:$PYTHONPATH}"
+
+exec python3 -m egregore_runtime.issue_cli "$@"

package/runtime/pi/bin/knowledge.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# Stable harness adapter for shared knowledge capture and private notes.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+export EGREGORE_ROOT="${EGREGORE_ROOT:-$ROOT}"
+export EGREGORE_SESSION_ID="${EGREGORE_SESSION_ID:-$(cat "$ROOT/.egregore-session-id" 2>/dev/null || true)}"
+export PYTHONPATH="$ROOT${PYTHONPATH:+:$PYTHONPATH}"
+
+exec python3 -m egregore_runtime.knowledge_cli "$@"

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

@@ -104,6 +104,26 @@ _detect_mode() {
   fi
 }
 
+# Whether the optional derived graph projection may be used by compatibility
+# commands. An explicit environment value wins for bounded maintenance/tests.
+# Existing instances that have not declared the feature retain compatibility;
+# new dogfood can set features.graph_projection=false to quarantine every
+# graph read/write while canonical Runtime paths are evaluated.
+_graph_projection_enabled() {
+  case "${EGREGORE_GRAPH_PROJECTION:-}" in
+    1|true|enabled) return 0 ;;
+    0|false|disabled) return 1 ;;
+  esac
+
+  local config="${CONFIG:-$SCRIPT_DIR/egregore.json}"
+  [ -r "$config" ] || return 1
+  if jq -e '.features | type == "object" and .graph_projection == false' \
+    "$config" >/dev/null 2>&1; then
+    return 1
+  fi
+  return 0
+}
+
 # Compact runtime identity shared by terminal surfaces. The sigils deliberately
 # distinguish an active hosted connection from the self-contained local mode
 # without implying that local Egregore is unhealthy.