@made-by-moonlight/athene-core 0.9.1 → 0.10.0

package/dist/agent-workspace-hooks.d.ts

@@ -15,16 +15,16 @@ export declare function buildAgentPath(basePath: string | undefined): string;
  *   ao_cache_read <key>                — print cached stdout
  *   ao_cache_write <key>               — write stdin to cache atomically
  */
-export declare const AO_METADATA_HELPER = "#!/usr/bin/env bash\n# ao-metadata-helper \u2014 shared by gh/git wrappers\n# Provides: update_ao_metadata, read_ao_metadata, ao_cache_*\n\n# \u2500\u2500 Shared validation \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n_ao_validate_env() {\n  local ao_dir=\"${AO_DATA_DIR:-}\"\n  local ao_session=\"${AO_SESSION:-}\"\n  [[ -z \"$ao_dir\" || -z \"$ao_session\" ]] && return 1\n  case \"$ao_session\" in */* | *..*) return 1 ;; esac\n  case \"$ao_dir\" in\n    \"$HOME\"/.ao/* | \"$HOME\"/.agent-orchestrator/* | /tmp/*) ;;\n    *) return 1 ;;\n  esac\n  return 0\n}\n\n# \u2500\u2500 Metadata write \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nupdate_ao_metadata() {\n  local key=\"$1\" value=\"$2\"\n  local ao_dir=\"${AO_DATA_DIR:-}\"\n  local ao_session=\"${AO_SESSION:-}\"\n\n  [[ -z \"$ao_dir\" || -z \"$ao_session\" ]] && return 0\n\n  # Validate: session name must not contain path separators or traversal\n  case \"$ao_session\" in\n    */* | *..*) return 0 ;;\n  esac\n\n  # Validate: ao_dir must be an absolute path under known ao directories or /tmp\n  case \"$ao_dir\" in\n    \"$HOME\"/.ao/* | \"$HOME\"/.agent-orchestrator/* | /tmp/*) ;;\n    *) return 0 ;;\n  esac\n\n  # V2 storage uses .json extension; fallback to bare filename for pre-migration layouts\n  local metadata_file=\"$ao_dir/${ao_session}.json\"\n  if [[ ! -f \"$metadata_file\" ]]; then\n    metadata_file=\"$ao_dir/$ao_session\"\n  fi\n\n  # Resolve symlinks and verify canonicalized paths are still within trusted roots\n  local real_dir real_ao_dir\n  real_ao_dir=\"$(cd \"$ao_dir\" 2>/dev/null && pwd -P)\" || return 0\n  real_dir=\"$(cd \"$(dirname \"$metadata_file\")\" 2>/dev/null && pwd -P)\" || return 0\n\n  # Re-validate real_ao_dir against trusted roots after canonicalization\n  # (prevents /tmp/../../home/user from escaping the allowlist)\n  case \"$real_ao_dir\" in\n    \"$HOME\"/.ao/* | \"$HOME\"/.ao | \"$HOME\"/.agent-orchestrator/* | \"$HOME\"/.agent-orchestrator | /tmp/*) ;;\n    *) return 0 ;;\n  esac\n\n  [[ \"$real_dir\" == \"$real_ao_dir\"* ]] || return 0\n\n  [[ -f \"$metadata_file\" ]] || return 0\n\n  # Validate key \u2014 only allow alphanumeric, underscore, hyphen (prevents sed/jq injection)\n  [[ \"$key\" =~ ^[a-zA-Z0-9_-]+$ ]] || return 0\n\n  local temp_file=\"${metadata_file}.tmp.$$\"\n\n  # Strip newlines from value to prevent injection\n  local clean_value=\"$(printf '%s' \"$value\" | tr -d '\\n')\"\n\n  # Detect JSON vs key=value format\n  local first_char\n  first_char=\"$(head -c1 \"$metadata_file\" 2>/dev/null)\"\n\n  if [[ \"$first_char\" == \"{\" ]]; then\n    # JSON format\n    if command -v jq &>/dev/null; then\n      jq --arg k \"$key\" --arg v \"$clean_value\" '.[$k] = $v' \"$metadata_file\" > \"$temp_file\"\n      mv \"$temp_file\" \"$metadata_file\"\n    else\n      # jq unavailable \u2014 use node (hard dep) for safe nested JSON update\n      node -e \"\n        const fs = require('fs');\n        const d = JSON.parse(fs.readFileSync(process.argv[1], 'utf8'));\n        d[process.argv[2]] = process.argv[3];\n        fs.writeFileSync(process.argv[4], JSON.stringify(d, null, 2));\n      \" \"$metadata_file\" \"$key\" \"$clean_value\" \"$temp_file\"\n      mv \"$temp_file\" \"$metadata_file\"\n    fi\n  else\n    # Key=value format (legacy)\n    local escaped_value=\"$(printf '%s' \"$clean_value\" | sed 's/[&|\\\\]/\\\\&/g')\"\n    if grep -q \"^${key}=\" \"$metadata_file\" 2>/dev/null; then\n      sed \"s|^${key}=.*|${key}=${escaped_value}|\" \"$metadata_file\" > \"$temp_file\"\n    else\n      cp \"$metadata_file\" \"$temp_file\"\n      printf '%s=%s\\n' \"$key\" \"$clean_value\" >> \"$temp_file\"\n    fi\n    mv \"$temp_file\" \"$metadata_file\"\n  fi\n}\n\n# \u2500\u2500 Metadata read \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nread_ao_metadata() {\n  local key=\"$1\"\n  _ao_validate_env || return 1\n  local metadata_file=\"${AO_DATA_DIR}/${AO_SESSION}\"\n  [[ -f \"$metadata_file\" ]] || return 1\n  [[ \"$key\" =~ ^[a-zA-Z0-9_-]+$ ]] || return 1\n  local line\n  line=$(grep \"^${key}=\" \"$metadata_file\" 2>/dev/null | head -1) || return 1\n  printf '%s' \"${line#*=}\"\n}\n\n# \u2500\u2500 Cache helpers \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nao_cache_dir() {\n  _ao_validate_env || return 1\n  local d=\"${AO_DATA_DIR}/.ghcache/${AO_SESSION}\"\n  mkdir -p \"$d\" 2>/dev/null || return 1\n  printf '%s' \"$d\"\n}\n\nao_cache_fresh() {\n  local cache_key=\"$1\" max_age=\"$2\"\n  [[ \"$cache_key\" =~ ^[a-zA-Z0-9_.-]+$ ]] || return 1\n  local cache_dir\n  cache_dir=\"$(ao_cache_dir)\" || return 1\n  local ts_file=\"$cache_dir/${cache_key}.ts\"\n  local stdout_file=\"$cache_dir/${cache_key}.stdout\"\n  [[ -f \"$stdout_file\" && -f \"$ts_file\" ]] || return 1\n  local cached_ts now\n  cached_ts=$(cat \"$ts_file\" 2>/dev/null) || return 1\n  # Sanity check: cached_ts must be a positive integer (epoch seconds)\n  [[ \"$cached_ts\" =~ ^[0-9]+$ && \"$cached_ts\" -gt 0 ]] || return 1\n  # max_age=0 means infinite TTL\n  [[ \"$max_age\" -eq 0 ]] 2>/dev/null && return 0\n  now=$(date +%s)\n  (( now - cached_ts < max_age ))\n}\n\nao_cache_read() {\n  local cache_key=\"$1\"\n  [[ \"$cache_key\" =~ ^[a-zA-Z0-9_.-]+$ ]] || return 1\n  local cache_dir\n  cache_dir=\"$(ao_cache_dir)\" || return 1\n  cat \"$cache_dir/${cache_key}.stdout\"\n}\n\nao_cache_write() {\n  local cache_key=\"$1\"\n  [[ \"$cache_key\" =~ ^[a-zA-Z0-9_.-]+$ ]] || return 1\n  local cache_dir\n  cache_dir=\"$(ao_cache_dir)\" || return 1\n  local tmp=\"$cache_dir/${cache_key}.stdout.tmp.$$\"\n  cat > \"$tmp\" && mv \"$tmp\" \"$cache_dir/${cache_key}.stdout\"\n  date +%s > \"$cache_dir/${cache_key}.ts\"\n}\n";
+export declare const AO_METADATA_HELPER: string;
 /**
  * gh wrapper — intercepts agent-side gh calls for:
  * 1. Caching repeated read-only commands (PR discovery, issue context)
  * 2. Auto-updating session metadata on PR creation
  *
- * Cache storage: $AO_DATA_DIR/.ghcache/$AO_SESSION/{key}.stdout + {key}.ts
+ * Cache storage: $ATHENE_DATA_DIR/.ghcache/$ATHENE_SESSION/{key}.stdout + {key}.ts
  * See D4-wrapper-cache-plan.md for full design rationale.
  */
-export declare const GH_WRAPPER = "#!/usr/bin/env bash\n# ao gh wrapper \u2014 caches reads + auto-updates metadata on writes\n\n# Find real gh by removing our wrapper directory from PATH\nao_bin_dir=\"$(cd \"$(dirname \"$0\")\" && pwd)\"\nclean_path=\"$(echo \"$PATH\" | tr ':' '\\n' | grep -Fxv \"$ao_bin_dir\" | grep . | tr '\\n' ':')\"\nclean_path=\"${clean_path%:}\"\nreal_gh=\"\"\n\n# Prefer explicit gh path when provided by AO environment.\n# Guard against recursive self-reference to the wrapper in ~/.ao/bin.\nif [[ -n \"${GH_PATH:-}\" && -x \"$GH_PATH\" ]]; then\n  gh_dir=\"$(cd \"$(dirname \"$GH_PATH\")\" 2>/dev/null && pwd)\"\n  if [[ \"$gh_dir\" != \"$ao_bin_dir\" ]]; then\n    real_gh=\"$GH_PATH\"\n  fi\nfi\n\nif [[ -z \"$real_gh\" ]]; then\n  real_gh=\"$(PATH=\"$clean_path\" command -v gh 2>/dev/null)\"\nfi\n\nif [[ -z \"$real_gh\" ]]; then\n  echo \"ao-wrapper: gh not found in PATH\" >&2\n  exit 127\nfi\n\n# Source the metadata helper (provides update/read_ao_metadata, ao_cache_*)\nsource \"$ao_bin_dir/ao-metadata-helper.sh\" 2>/dev/null || true\n\n# Redact sensitive values from args before tracing.\n# Handles: -H \"Authorization: ...\", token=..., password=..., secret=...\n_ao_redact_args() {\n  local prev=\"\"\n  local out=()\n  for arg in \"$@\"; do\n    if [[ \"$prev\" == \"-H\" || \"$prev\" == \"--header\" ]] && [[ \"$arg\" =~ ^[Aa]uthorization: ]]; then\n      out+=(\"Authorization: [REDACTED]\")\n    elif [[ \"$arg\" =~ ^-H[Aa]uthorization: ]]; then\n      out+=(\"-HAuthorization: [REDACTED]\")\n    elif [[ \"$arg\" =~ ^[Tt]oken= ]]; then\n      out+=(\"token=[REDACTED]\")\n    elif [[ \"$arg\" =~ ^[Pp]assword= ]]; then\n      out+=(\"password=[REDACTED]\")\n    elif [[ \"$arg\" =~ ^[Ss]ecret= ]]; then\n      out+=(\"secret=[REDACTED]\")\n    else\n      out+=(\"$arg\")\n    fi\n    prev=\"$arg\"\n  done\n  printf '%s\n' \"${out[@]}\"\n}\n\n# Best-effort JSONL tracing for agent-side gh invocations.\nlog_gh_invocation() {\n  local trace_file=\"${AO_AGENT_GH_TRACE:-}\"\n  [[ -z \"$trace_file\" ]] && return 0\n  command -v jq >/dev/null 2>&1 || return 0\n\n  mkdir -p \"$(dirname \"$trace_file\")\" 2>/dev/null || return 0\n\n  local args_json\n  args_json=\"$(_ao_redact_args \"$@\" | jq -Rsc 'split(\"\n\")[:-1]')\" || return 0\n\n  # Compute operation: gh.{arg1}.{arg2} (mirrors AO-side extractOperation)\n  local _ao_op=\"gh\"\n  [[ $# -ge 1 ]] && _ao_op=\"gh.$1\"\n  [[ $# -ge 2 && \"$2\" != -* ]] && _ao_op=\"gh.$1.$2\"\n\n  jq -nc     --arg timestamp \"$(date -u +\"%Y-%m-%dT%H:%M:%SZ\")\"     --arg cwd \"$PWD\"     --arg operation \"$_ao_op\"     --arg aoSession \"${AO_SESSION:-}\"     --arg aoSessionName \"${AO_SESSION_NAME:-}\"     --arg aoProjectId \"${AO_PROJECT_ID:-}\"     --arg aoIssueId \"${AO_ISSUE_ID:-}\"     --arg aoCallerType \"${AO_CALLER_TYPE:-}\"     --arg pid \"$$\"     --arg wrapperVersion \"0.8.0\"     --argjson args \"$args_json\"     '{\n      timestamp: $timestamp,\n      cwd: $cwd,\n      args: $args,\n      operation: $operation,\n      aoSession: (if $aoSession == \"\" then null else $aoSession end),\n      aoSessionName: (if $aoSessionName == \"\" then null else $aoSessionName end),\n      aoProjectId: (if $aoProjectId == \"\" then null else $aoProjectId end),\n      aoIssueId: (if $aoIssueId == \"\" then null else $aoIssueId end),\n      aoCallerType: (if $aoCallerType == \"\" then null else $aoCallerType end),\n      pid: ($pid | tonumber),\n      wrapperVersion: $wrapperVersion\n    }' >> \"$trace_file\" 2>/dev/null || true\n}\n\nlog_gh_invocation \"$@\"\n\n# Best-effort cache-outcome tracing (appends to same JSONL trace file).\n# result: hit | miss-stored | miss-write-failed | miss-negative | miss-error | passthrough\nlog_ao_cache() {\n  local result=\"$1\" cache_key=\"$2\" duration_ms=\"${3:-0}\" exit_code=\"${4:-0}\" ok=\"${5:-true}\"\n  local trace_file=\"${AO_AGENT_GH_TRACE:-}\"\n  [[ -z \"$trace_file\" ]] && return 0\n  printf '{\"timestamp\":\"%s\",\"cacheResult\":\"%s\",\"cacheKey\":\"%s\",\"pid\":%s,\"durationMs\":%s,\"exitCode\":%s,\"ok\":%s}\\n'     \"$(date -u +\"%Y-%m-%dT%H:%M:%SZ\")\" \"$result\" \"$cache_key\" \"$$\"     \"$duration_ms\" \"$exit_code\" \"$ok\"     >> \"$trace_file\" 2>/dev/null || true\n}\n\n# =============================================================================\n# Cacheable reads\n# =============================================================================\n\n# \u2500\u2500 1. PR discovery: gh pr list --head <B> --limit 1 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n# 120s TTL for positive results (non-empty array). Never caches [].\nif [[ \"$1\" == \"pr\" && \"$2\" == \"list\" ]]; then\n  _ao_head=\"\" _ao_limit=\"\" _ao_json=\"\" _ao_repo=\"\" _ao_cacheable=true\n  _ao_saved_args=(\"$@\")\n  shift 2\n  while [[ $# -gt 0 ]]; do\n    case \"$1\" in\n      --head)     _ao_head=\"$2\"; shift 2 ;;\n      --head=*)   _ao_head=\"${1#--head=}\"; shift ;;\n      --limit)    _ao_limit=\"$2\"; shift 2 ;;\n      --limit=*)  _ao_limit=\"${1#--limit=}\"; shift ;;\n      --json)     _ao_json=\"$2\"; shift 2 ;;\n      --json=*)   _ao_json=\"${1#--json=}\"; shift ;;\n      --repo)     _ao_repo=\"$2\"; shift 2 ;;\n      --repo=*)   _ao_repo=\"${1#--repo=}\"; shift ;;\n      --search|--state|--assignee|--label|--jq|--template)\n        _ao_cacheable=false; break ;;\n      --search=*|--state=*|--assignee=*|--label=*|--jq=*|--template=*)\n        _ao_cacheable=false; break ;;\n      -*)         shift ;;  # skip unknown flags\n      *)          shift ;;  # skip positional\n    esac\n  done\n  set -- \"${_ao_saved_args[@]}\"\n\n  if [[ \"$_ao_cacheable\" == true && \"$_ao_limit\" == \"1\" && -n \"$_ao_head\" ]]; then\n    # Use sha256 hash suffix to avoid collisions from tr-based sanitization\n    # (e.g. feat/foo, feat-foo, feat_foo would otherwise map to the same key)\n    _ao_raw_key=\"pr-discovery-${_ao_repo}-${_ao_head}\"\n    if [[ -n \"$_ao_json\" ]]; then\n      _ao_raw_key=\"${_ao_raw_key}-j-${_ao_json}\"\n    fi\n    _ao_cache_key=$(printf '%s' \"$_ao_raw_key\" | shasum -a 256 | cut -c1-16)\n    _ao_cache_key=\"pr-disc-${_ao_cache_key}\"\n\n    if ao_cache_fresh \"$_ao_cache_key\" 120 2>/dev/null; then\n      log_ao_cache \"hit\" \"$_ao_cache_key\" 0 0 true\n      ao_cache_read \"$_ao_cache_key\"\n      exit 0\n    fi\n\n    # Cache miss \u2014 call real gh, cache positive results (stderr passes through)\n    _ao_tmpout=\"$(mktemp)\"\n    trap 'rm -f \"$_ao_tmpout\"' EXIT\n    _ao_start_s=$(date +%s)\n    \"$real_gh\" \"$@\" > \"$_ao_tmpout\"\n    _ao_exit=$?\n    _ao_duration_ms=$(( ($(date +%s) - _ao_start_s) * 1000 ))\n    _ao_ok=true; [[ $_ao_exit -ne 0 ]] && _ao_ok=false\n    cat \"$_ao_tmpout\"\n    if [[ $_ao_exit -eq 0 ]]; then\n      _ao_trimmed=$(tr -d '[:space:]' < \"$_ao_tmpout\")\n      # Only cache non-empty positive results\n      if [[ -n \"$_ao_trimmed\" && \"$_ao_trimmed\" != \"[]\" ]]; then\n        if ao_cache_write \"$_ao_cache_key\" < \"$_ao_tmpout\" 2>/dev/null; then\n          log_ao_cache \"miss-stored\" \"$_ao_cache_key\" \"$_ao_duration_ms\" \"$_ao_exit\" \"$_ao_ok\"\n        else\n          log_ao_cache \"miss-write-failed\" \"$_ao_cache_key\" \"$_ao_duration_ms\" \"$_ao_exit\" \"$_ao_ok\"\n        fi\n      else\n        log_ao_cache \"miss-negative\" \"$_ao_cache_key\" \"$_ao_duration_ms\" \"$_ao_exit\" \"$_ao_ok\"\n      fi\n    else\n      log_ao_cache \"miss-error\" \"$_ao_cache_key\" \"$_ao_duration_ms\" \"$_ao_exit\" \"$_ao_ok\"\n    fi\n    exit $_ao_exit\n  fi\nfi\n\n# \u2500\u2500 2. Issue context: gh issue view <N> \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n# 300-second TTL. Caches any successful response.\nif [[ \"$1\" == \"issue\" && \"$2\" == \"view\" ]]; then\n  _ao_issue_id=\"\" _ao_json=\"\" _ao_repo=\"\" _ao_cacheable=true\n  _ao_saved_args=(\"$@\")\n  shift 2\n  # First non-flag arg is the issue identifier\n  while [[ $# -gt 0 ]]; do\n    case \"$1\" in\n      --web|--comments|--jq|--template)\n        _ao_cacheable=false; break ;;\n      --jq=*|--template=*)\n        _ao_cacheable=false; break ;;\n      --json)     _ao_json=\"$2\"; shift 2 ;;\n      --json=*)   _ao_json=\"${1#--json=}\"; shift ;;\n      --repo)     _ao_repo=\"$2\"; shift 2 ;;\n      --repo=*)   _ao_repo=\"${1#--repo=}\"; shift ;;\n      -*)         shift ;;\n      *)\n        if [[ -z \"$_ao_issue_id\" && \"$1\" =~ ^[0-9]+$ ]]; then\n          _ao_issue_id=\"$1\"\n        fi\n        shift ;;\n    esac\n  done\n  set -- \"${_ao_saved_args[@]}\"\n\n  if [[ \"$_ao_cacheable\" == true && -n \"$_ao_issue_id\" ]]; then\n    _ao_raw_key=\"issue-ctx-${_ao_repo}-${_ao_issue_id}\"\n    if [[ -n \"$_ao_json\" ]]; then\n      _ao_raw_key=\"${_ao_raw_key}-j-${_ao_json}\"\n    fi\n    _ao_cache_key=$(printf '%s' \"$_ao_raw_key\" | shasum -a 256 | cut -c1-16)\n    _ao_cache_key=\"issue-${_ao_cache_key}\"\n\n    if ao_cache_fresh \"$_ao_cache_key\" 300 2>/dev/null; then\n      log_ao_cache \"hit\" \"$_ao_cache_key\" 0 0 true\n      ao_cache_read \"$_ao_cache_key\"\n      exit 0\n    fi\n\n    _ao_tmpout=\"$(mktemp)\"\n    trap 'rm -f \"$_ao_tmpout\"' EXIT\n    _ao_start_s=$(date +%s)\n    \"$real_gh\" \"$@\" > \"$_ao_tmpout\"\n    _ao_exit=$?\n    _ao_duration_ms=$(( ($(date +%s) - _ao_start_s) * 1000 ))\n    _ao_ok=true; [[ $_ao_exit -ne 0 ]] && _ao_ok=false\n    cat \"$_ao_tmpout\"\n    if [[ $_ao_exit -eq 0 ]]; then\n      if ao_cache_write \"$_ao_cache_key\" < \"$_ao_tmpout\" 2>/dev/null; then\n        log_ao_cache \"miss-stored\" \"$_ao_cache_key\" \"$_ao_duration_ms\" \"$_ao_exit\" \"$_ao_ok\"\n      else\n        log_ao_cache \"miss-write-failed\" \"$_ao_cache_key\" \"$_ao_duration_ms\" \"$_ao_exit\" \"$_ao_ok\"\n      fi\n    else\n      log_ao_cache \"miss-error\" \"$_ao_cache_key\" \"$_ao_duration_ms\" \"$_ao_exit\" \"$_ao_ok\"\n    fi\n    exit $_ao_exit\n  fi\nfi\n\n# =============================================================================\n# Write intercepts\n# =============================================================================\n\ncase \"$1/$2\" in\n  pr/create)\n    tmpout=\"$(mktemp)\"\n    trap 'rm -f \"$tmpout\"' EXIT\n\n    _ao_start_s=$(date +%s)\n    \"$real_gh\" \"$@\" 2>&1 | tee \"$tmpout\"\n    exit_code=${PIPESTATUS[0]}\n    _ao_duration_ms=$(( ($(date +%s) - _ao_start_s) * 1000 ))\n    _ao_ok=true; [[ $exit_code -ne 0 ]] && _ao_ok=false\n\n    if [[ $exit_code -eq 0 ]]; then\n      output=\"$(cat \"$tmpout\")\"\n      pr_url=\"$(echo \"$output\" | grep -Eo 'https?://[^/]+/[^/]+/[^/]+/pull/[0-9]+' | head -1)\"\n      report_state=\"pr_created\"\n      report_draft=\"false\"\n      for arg in \"$@\"; do\n        if [[ \"$arg\" == \"--draft\" || \"$arg\" == \"-d\" ]]; then\n          report_state=\"draft_pr_created\"\n          report_draft=\"true\"\n          break\n        fi\n      done\n      if [[ -n \"$pr_url\" ]]; then\n        update_ao_metadata pr \"$pr_url\"\n        update_ao_metadata agentReportedPrUrl \"$pr_url\"\n        # Append to prs field (comma-separated list of all PR URLs for this session).\n        # Supports multiple PRs per session \u2014 same repo or different repos.\n        _ao_meta_f=\"${AO_DATA_DIR}/${AO_SESSION}.json\"\n        [[ -f \"$_ao_meta_f\" ]] || _ao_meta_f=\"${AO_DATA_DIR}/${AO_SESSION}\"\n        if head -c1 \"$_ao_meta_f\" 2>/dev/null | grep -q '{'; then\n          existing_prs=\"$(jq -r '.prs // empty' \"$_ao_meta_f\" 2>/dev/null || echo \"\")\"\n        else\n          existing_prs=\"$(grep '^prs=' \"$_ao_meta_f\" 2>/dev/null | cut -d'=' -f2- || echo \"\")\"\n        fi\n        if [[ -z \"$existing_prs\" ]]; then\n          new_prs=\"$pr_url\"\n        else\n          if ! echo \",$existing_prs,\" | grep -qF \",$pr_url,\"; then\n            new_prs=\"$existing_prs,$pr_url\"\n          else\n            new_prs=\"$existing_prs\"\n          fi\n        fi\n        update_ao_metadata prs \"$new_prs\"\n      fi\n      pr_number=\"$(printf '%s' \"$pr_url\" | grep -Eo '[0-9]+$' | head -1)\"\n      if [[ -n \"$pr_number\" ]]; then\n        update_ao_metadata agentReportedPrNumber \"$pr_number\"\n      fi\n      update_ao_metadata agentReportedState \"$report_state\"\n      update_ao_metadata agentReportedAt \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"\n      update_ao_metadata agentReportedPrIsDraft \"$report_draft\"\n    fi\n\n    log_ao_cache \"passthrough\" \"\" \"$_ao_duration_ms\" \"$exit_code\" \"$_ao_ok\"\n    exit $exit_code\n    ;;\n  *)\n    _ao_start_s=$(date +%s)\n    \"$real_gh\" \"$@\"\n    _ao_exit=$?\n    _ao_duration_ms=$(( ($(date +%s) - _ao_start_s) * 1000 ))\n    _ao_ok=true; [[ $_ao_exit -ne 0 ]] && _ao_ok=false\n    log_ao_cache \"passthrough\" \"\" \"$_ao_duration_ms\" \"$_ao_exit\" \"$_ao_ok\"\n    exit $_ao_exit\n    ;;\nesac\n";
+export declare const GH_WRAPPER: string;
 /**
  * git wrapper — intercepts branch operations to auto-update metadata.
  * All other commands pass through transparently.

package/dist/agent-workspace-hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-workspace-hooks.d.ts","sourceRoot":"","sources":["../src/agent-workspace-hooks.ts"],"names":[],"mappings":"AAwBA,mDAAmD;AACnD,eAAO,MAAM,iBAAiB,sBAA+B,CAAC;AAkB9D;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAsBnE;AAQD;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,+vNA6J9B,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,wrZA+TtB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,o6CA4CvB,CAAC;AAMF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,KAAK,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,CAKnF;AAkQD;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,4UAWhC,CAAC;AAkBF;;;;;;;;;GASG;AACH,wBAAsB,yBAAyB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAmDpF"}
+{"version":3,"file":"agent-workspace-hooks.d.ts","sourceRoot":"","sources":["../src/agent-workspace-hooks.ts"],"names":[],"mappings":"AAyBA,mDAAmD;AACnD,eAAO,MAAM,iBAAiB,sBAA+B,CAAC;AAkB9D;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAsBnE;AAQD;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,QA6J9B,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,QA+TtB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,o6CA4CvB,CAAC;AAMF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,KAAK,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,CAKnF;AAkQD;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,4UAWhC,CAAC;AAkBF;;;;;;;;;GASG;AACH,wBAAsB,yBAAyB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAmDpF"}

package/dist/agent-workspace-hooks.js

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { randomBytes } from 'node:crypto';
 import { isWindows } from './platform.js';
+import { bashEnvRead, nodeEnvRead, ENV } from './env.js';
 
 /**
  * Shared PATH-based workspace hooks for all agent plugins.
@@ -81,8 +82,8 @@ const AO_METADATA_HELPER = `#!/usr/bin/env bash
 # ── Shared validation ────────────────────────────────────────────────────────
 
 _ao_validate_env() {
-  local ao_dir="\${AO_DATA_DIR:-}"
-  local ao_session="\${AO_SESSION:-}"
+  local ao_dir="${bashEnvRead(ENV.DATA_DIR)}"
+  local ao_session="${bashEnvRead(ENV.SESSION)}"
   [[ -z "\$ao_dir" || -z "\$ao_session" ]] && return 1
   case "\$ao_session" in */* | *..*) return 1 ;; esac
   case "\$ao_dir" in
@@ -96,8 +97,8 @@ _ao_validate_env() {
 
 update_ao_metadata() {
   local key="\$1" value="\$2"
-  local ao_dir="\${AO_DATA_DIR:-}"
-  local ao_session="\${AO_SESSION:-}"
+  local ao_dir="${bashEnvRead(ENV.DATA_DIR)}"
+  local ao_session="${bashEnvRead(ENV.SESSION)}"
 
   [[ -z "\$ao_dir" || -z "\$ao_session" ]] && return 0
 
@@ -179,7 +180,7 @@ update_ao_metadata() {
 read_ao_metadata() {
   local key="\$1"
   _ao_validate_env || return 1
-  local metadata_file="\${AO_DATA_DIR}/\${AO_SESSION}"
+  local metadata_file="${bashEnvRead(ENV.DATA_DIR)}/${bashEnvRead(ENV.SESSION)}"
   [[ -f "\$metadata_file" ]] || return 1
   [[ "\$key" =~ ^[a-zA-Z0-9_-]+$ ]] || return 1
   local line
@@ -191,7 +192,7 @@ read_ao_metadata() {
 
 ao_cache_dir() {
   _ao_validate_env || return 1
-  local d="\${AO_DATA_DIR}/.ghcache/\${AO_SESSION}"
+  local d="${bashEnvRead(ENV.DATA_DIR)}/.ghcache/${bashEnvRead(ENV.SESSION)}"
   mkdir -p "\$d" 2>/dev/null || return 1
   printf '%s' "\$d"
 }
@@ -237,7 +238,7 @@ ao_cache_write() {
  * 1. Caching repeated read-only commands (PR discovery, issue context)
  * 2. Auto-updating session metadata on PR creation
  *
- * Cache storage: $AO_DATA_DIR/.ghcache/$AO_SESSION/{key}.stdout + {key}.ts
+ * Cache storage: $ATHENE_DATA_DIR/.ghcache/$ATHENE_SESSION/{key}.stdout + {key}.ts
  * See D4-wrapper-cache-plan.md for full design rationale.
  */
 const GH_WRAPPER = `#!/usr/bin/env bash
@@ -296,7 +297,7 @@ _ao_redact_args() {
 
 # Best-effort JSONL tracing for agent-side gh invocations.
 log_gh_invocation() {
-  local trace_file="\${AO_AGENT_GH_TRACE:-}"
+  local trace_file="${bashEnvRead(ENV.AGENT_GH_TRACE)}"
   [[ -z "\$trace_file" ]] && return 0
   command -v jq >/dev/null 2>&1 || return 0
 
@@ -314,11 +315,11 @@ log_gh_invocation() {
     --arg timestamp "\$(date -u +"%Y-%m-%dT%H:%M:%SZ")" \
     --arg cwd "\$PWD" \
     --arg operation "\$_ao_op" \
-    --arg aoSession "\${AO_SESSION:-}" \
-    --arg aoSessionName "\${AO_SESSION_NAME:-}" \
-    --arg aoProjectId "\${AO_PROJECT_ID:-}" \
-    --arg aoIssueId "\${AO_ISSUE_ID:-}" \
-    --arg aoCallerType "\${AO_CALLER_TYPE:-}" \
+    --arg aoSession "${bashEnvRead(ENV.SESSION)}" \
+    --arg aoSessionName "${bashEnvRead(ENV.SESSION_NAME)}" \
+    --arg aoProjectId "${bashEnvRead(ENV.PROJECT_ID)}" \
+    --arg aoIssueId "${bashEnvRead(ENV.ISSUE_ID)}" \
+    --arg aoCallerType "${bashEnvRead(ENV.CALLER_TYPE)}" \
     --arg pid "\$\$" \
     --arg wrapperVersion "${WRAPPER_VERSION}" \
     --argjson args "\$args_json" \
@@ -343,7 +344,7 @@ log_gh_invocation "\$@"
 # result: hit | miss-stored | miss-write-failed | miss-negative | miss-error | passthrough
 log_ao_cache() {
   local result="\$1" cache_key="\$2" duration_ms="\${3:-0}" exit_code="\${4:-0}" ok="\${5:-true}"
-  local trace_file="\${AO_AGENT_GH_TRACE:-}"
+  local trace_file="${bashEnvRead(ENV.AGENT_GH_TRACE)}"
   [[ -z "\$trace_file" ]] && return 0
   printf '{"timestamp":"%s","cacheResult":"%s","cacheKey":"%s","pid":%s,"durationMs":%s,"exitCode":%s,"ok":%s}\\n' \
     "\$(date -u +"%Y-%m-%dT%H:%M:%SZ")" "\$result" "\$cache_key" "\$\$" \
@@ -519,8 +520,8 @@ case "\$1/\$2" in
         update_ao_metadata agentReportedPrUrl "\$pr_url"
         # Append to prs field (comma-separated list of all PR URLs for this session).
         # Supports multiple PRs per session — same repo or different repos.
-        _ao_meta_f="\${AO_DATA_DIR}/\${AO_SESSION}.json"
-        [[ -f "\$_ao_meta_f" ]] || _ao_meta_f="\${AO_DATA_DIR}/\${AO_SESSION}"
+        _ao_meta_f="${bashEnvRead(ENV.DATA_DIR)}/${bashEnvRead(ENV.SESSION)}.json"
+        [[ -f "\$_ao_meta_f" ]] || _ao_meta_f="${bashEnvRead(ENV.DATA_DIR)}/${bashEnvRead(ENV.SESSION)}"
         if head -c1 "\$_ao_meta_f" 2>/dev/null | grep -q '{'; then
           existing_prs="\$(jq -r '.prs // empty' "\$_ao_meta_f" 2>/dev/null || echo "")"
         else
@@ -643,15 +644,15 @@ function buildNodeWrapper(name, realBinaryPath) {
 }
 /**
  * Shared Node.js snippet: updateAoMetadata function used by both gh and git wrappers.
- * Validates session, key, and AO_DATA_DIR before writing metadata.
+ * Validates session, key, and ATHENE_DATA_DIR before writing metadata.
  */
 const NODE_UPDATE_AO_METADATA = `\
 // ---------------------------------------------------------------------------
 // Metadata update (shared by gh/git wrappers)
 // ---------------------------------------------------------------------------
 function updateAoMetadata(key, value) {
-  const aoDir = process.env["AO_DATA_DIR"] || "";
-  const aoSession = process.env["AO_SESSION"] || "";
+  const aoDir = ${nodeEnvRead(ENV.DATA_DIR)} || "";
+  const aoSession = ${nodeEnvRead(ENV.SESSION)} || "";
   if (!aoDir || !aoSession) return;
 
   // Validate session — no path separators or traversal
@@ -785,8 +786,8 @@ if (key === "pr/create" || key === "pr/merge") {
         // Append to prs field — supports multiple PRs per session
         let existingPrs = "";
         try {
-          const aoDir = process.env["AO_DATA_DIR"] || "";
-          const aoSession = process.env["AO_SESSION"] || "";
+          const aoDir = ${nodeEnvRead(ENV.DATA_DIR)} || "";
+          const aoSession = ${nodeEnvRead(ENV.SESSION)} || "";
           if (aoDir && aoSession && /^[a-zA-Z0-9_-]+$/.test(aoSession)) {
             let metaFile = path.join(aoDir, aoSession + ".json");
             if (!fs.existsSync(metaFile)) metaFile = path.join(aoDir, aoSession);

package/dist/agent-workspace-hooks.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-workspace-hooks.js","sources":["../src/agent-workspace-hooks.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}
+{"version":3,"file":"agent-workspace-hooks.js","sources":["../src/agent-workspace-hooks.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -10,6 +10,15 @@
  * Everything else has sensible defaults.
  */
 import { type ExternalPluginEntryRef, type LoadedConfig, type OrchestratorConfig } from "./types.js";
+/**
+ * Fail loudly when a meta orchestrator's explicit scope references a project ID
+ * that is not in the registered set. Evaluated against the FULL global project
+ * registry (not a partial effective projection), so valid multi-project scopes
+ * load while genuine typos are rejected. Throws on the first unknown reference.
+ */
+export declare function assertMetaScopeProjectsExist(metaOrchestrators: Record<string, {
+    scope?: unknown;
+}> | undefined, knownProjectIds: string[]): void;
 /**
  * Collect external plugin configs from tracker, scm, and notifier inline configs.
  * These will be auto-added to config.plugins for loading.
@@ -33,7 +42,7 @@ export declare const DEFAULT_BUGBOT_COMMENTS_MESSAGE = "Automated review comment
  * Search for config file in standard locations.
  *
  * Search order:
- * 1. AO_CONFIG_PATH environment variable (if set)
+ * 1. ATHENE_CONFIG_PATH environment variable (if set)
  * 2. Search up directory tree from CWD (like git)
  * 3. Explicit startDir (if provided)
  * 4. Home directory locations
@@ -41,6 +50,15 @@ export declare const DEFAULT_BUGBOT_COMMENTS_MESSAGE = "Automated review comment
 export declare function findConfigFile(startDir?: string): string | null;
 /** Find config file path (exported for use in hash generation) */
 export declare function findConfig(startDir?: string): string | null;
+/**
+ * Validate a WRAPPED config (one that carries its full `projects` map inline).
+ * Mirrors the global/flat-local builders by failing loud on a meta scope that
+ * references an unregistered project — validated against this config's own
+ * complete projects set. NOT folded into the shared `validateConfig`, because the
+ * flat-local builder calls validateConfig with a SINGLE-PROJECT projection where
+ * such a check would spuriously reject valid multi-project scopes (round-15).
+ */
+export declare function validateWrappedConfig(raw: unknown): OrchestratorConfig;
 /** Load and validate config from a YAML file */
 export declare function loadConfig(configPath?: string): LoadedConfig;
 /** Load config and return both config and resolved path */

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,OAAO,EAIL,KAAK,sBAAsB,EAC3B,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACxB,MAAM,YAAY,CAAC;AA6cpB;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,kBAAkB,GAAG,sBAAsB,EAAE,CAwCjG;AA2HD;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B,mFACsC,CAAC;AAiFnF;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAkE/D;AAoGD,kEAAkE;AAClE,wBAAgB,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE3D;AAED,gDAAgD;AAChD,wBAAgB,UAAU,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,YAAY,CA+B5D;AAED,2DAA2D;AAC3D,wBAAgB,kBAAkB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG;IACvD,MAAM,EAAE,YAAY,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;CACd,CA6BA;AAED,mCAAmC;AACnC,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,kBAAkB,CAqB/D;AAED,0DAA0D;AAC1D,wBAAgB,gBAAgB,IAAI,kBAAkB,CAIrD"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AASH,OAAO,EAIL,KAAK,sBAAsB,EAC3B,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACxB,MAAM,YAAY,CAAC;AA2ZpB;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC,GAAG,SAAS,EAClE,eAAe,EAAE,MAAM,EAAE,GACxB,IAAI,CAgBN;AA0GD;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,kBAAkB,GAAG,sBAAsB,EAAE,CAwCjG;AA2HD;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B,mFACsC,CAAC;AAiFnF;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAmE/D;AAgHD,kEAAkE;AAClE,wBAAgB,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE3D;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,kBAAkB,CAItE;AAED,gDAAgD;AAChD,wBAAgB,UAAU,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,YAAY,CAmC5D;AAED,2DAA2D;AAC3D,wBAAgB,kBAAkB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG;IACvD,MAAM,EAAE,YAAY,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;CACd,CAiCA;AAED,mCAAmC;AACnC,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,kBAAkB,CAqB/D;AAED,0DAA0D;AAC1D,wBAAgB,gBAAgB,IAAI,kBAAkB,CAIrD"}

package/dist/config.js

@@ -4,6 +4,7 @@ import { resolve, dirname, basename, join } from 'node:path';
 import { homedir } from 'node:os';
 import { parse } from 'yaml';
 import { z } from 'zod';
+import { getEnvString, ENV } from './env.js';
 import { ConfigNotFoundError, ProjectResolveError } from './types.js';
 import { generateSessionPrefix } from './paths.js';
 import { getDefaultRuntime } from './platform.js';
@@ -197,6 +198,8 @@ const RoleAgentConfigSchema = z
 const ProjectConfigSchema = z.object({
     name: z.string().optional(),
     repo: z.string().optional(),
+    /** Short routing hint surfaced in the meta orchestrator catalog. */
+    description: z.string().optional(),
     path: z.string(),
     defaultBranch: z.string().default("main"),
     sessionPrefix: z
@@ -296,7 +299,26 @@ const LifecycleConfigSchema = z
         .default(300_000),
 })
     .default({});
-const OrchestratorConfigSchema = z.object({
+const MetaScopeSchema = z.union([
+    z.literal("all"),
+    z.object({ projects: z.array(z.string()).min(1) }),
+]);
+const MetaOrchestratorConfigSchema = z.object({
+    scope: MetaScopeSchema,
+    // Include newly-registered projects in this meta orchestrator's scope.
+    // NOTE (current behavior): scope is resolved live by `meta-status` and the
+    // dashboard, so new projects show there immediately; the running orchestrator's
+    // prompt catalog is a snapshot from `meta-start`, so it only refreshes on
+    // restart. (`reconcileMetaScopeIds` is the building block for future live
+    // prompt-refresh wiring.) With scope:'all' new projects are naturally in scope.
+    discover: z.boolean().default(false),
+    // Optional agent plugin override; defaults to the global default agent.
+    agent: z.string().optional(),
+    // Optional extra instructions appended to the meta orchestrator prompt.
+    rules: z.string().optional(),
+});
+const OrchestratorConfigSchema = z
+    .object({
     $schema: z.string().optional(),
     port: z.number().int().default(3000),
     terminalPort: z.number().int().optional(),
@@ -314,7 +336,58 @@ const OrchestratorConfigSchema = z.object({
     notifiers: z.record(NotifierConfigSchema).default({}),
     notificationRouting: z.record(z.array(z.string())).default({}),
     reactions: z.record(ReactionConfigSchema).default({}),
+    metaOrchestrators: z
+        .record(z
+        .string()
+        .regex(/^[a-zA-Z0-9_-]+$/, "meta orchestrator name must match [a-zA-Z0-9_-]+"), MetaOrchestratorConfigSchema)
+        .optional(),
+})
+    .superRefine((value, ctx) => {
+    // `_meta` is the reserved on-disk parent for meta orchestrator sessions
+    // (projects/_meta/<name>/sessions/<name>.json). A real project keyed `_meta`
+    // would collide with that storage scope. `projects` is required but Zod runs
+    // object refinements even when a required key is absent, so guard against
+    // `undefined` — otherwise an omitted `projects:` would crash with a TypeError
+    // instead of surfacing Zod's clean "Required" error.
+    const projects = value.projects ?? {};
+    if (Object.prototype.hasOwnProperty.call(projects, "_meta")) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["projects", "_meta"],
+            message: "'_meta' is a reserved project ID used for meta orchestrator storage; rename this project.",
+        });
+    }
+    // NOTE: meta-orchestrator explicit-scope project existence is intentionally
+    // NOT checked here — `value.projects` may be a partial projection (the
+    // flat-local path narrows to the single cwd project; the global path drops
+    // degraded projects), which would spuriously reject valid multi-project
+    // scopes. That check runs against the FULL registered project set via
+    // `assertMetaScopeProjectsExist` in the global-config load path.
 });
+/**
+ * Fail loudly when a meta orchestrator's explicit scope references a project ID
+ * that is not in the registered set. Evaluated against the FULL global project
+ * registry (not a partial effective projection), so valid multi-project scopes
+ * load while genuine typos are rejected. Throws on the first unknown reference.
+ */
+function assertMetaScopeProjectsExist(metaOrchestrators, knownProjectIds) {
+    if (!metaOrchestrators)
+        return;
+    const known = new Set(knownProjectIds);
+    for (const [metaName, meta] of Object.entries(metaOrchestrators)) {
+        const scope = meta?.scope;
+        if (!scope || scope === "all" || typeof scope !== "object")
+            continue;
+        const scoped = scope.projects;
+        if (!Array.isArray(scoped))
+            continue;
+        for (const projectId of scoped) {
+            if (typeof projectId === "string" && !known.has(projectId)) {
+                throw new Error(`Meta orchestrator '${metaName}' references unknown project '${projectId}'. Known projects: ${knownProjectIds.join(", ") || "(none)"}.`);
+            }
+        }
+    }
+}
 // =============================================================================
 // CONFIG LOADING
 // =============================================================================
@@ -606,15 +679,16 @@ function applyDefaultReactions(config) {
  * Search for config file in standard locations.
  *
  * Search order:
- * 1. AO_CONFIG_PATH environment variable (if set)
+ * 1. ATHENE_CONFIG_PATH environment variable (if set)
  * 2. Search up directory tree from CWD (like git)
  * 3. Explicit startDir (if provided)
  * 4. Home directory locations
  */
 function findConfigFile(startDir) {
     // 1. Check environment variable override
-    if (process.env["AO_CONFIG_PATH"]) {
-        const envPath = resolve(process.env["AO_CONFIG_PATH"]);
+    const configPathOverride = getEnvString(ENV.CONFIG_PATH);
+    if (configPathOverride) {
+        const envPath = resolve(configPathOverride);
         if (existsSync(envPath)) {
             return envPath;
         }
@@ -675,6 +749,10 @@ function buildEffectiveConfigFromFlatLocalPath(configPath, _localParsed) {
     const globalConfig = loadGlobalConfig(globalConfigPath);
     if (!globalConfig)
         return null;
+    // Validate meta scopes against the FULL registry before projecting down to the
+    // single cwd project below (otherwise valid multi-project scopes would be
+    // rejected by validateConfig against the partial projects map).
+    assertMetaScopeProjectsExist(globalConfig.metaOrchestrators, Object.keys(globalConfig.projects));
     const canonicalProjectDir = (() => {
         try {
             return realpathSync(resolve(dirname(configPath)));
@@ -707,6 +785,7 @@ function buildEffectiveConfigFromFlatLocalPath(configPath, _localParsed) {
         notifiers: globalConfig.notifiers,
         notificationRouting: globalConfig.notificationRouting,
         reactions: globalConfig.reactions,
+        metaOrchestrators: globalConfig.metaOrchestrators,
         projects: {
             [projectId]: {
                 ...project,
@@ -719,6 +798,10 @@ function buildEffectiveConfigFromGlobalConfigPath(configPath) {
     const globalConfig = loadGlobalConfig(configPath);
     if (!globalConfig)
         return null;
+    // Validate meta scopes against the FULL registry — including projects that may
+    // degrade (and thus be excluded from the effective `projects` map below) — so a
+    // scope referencing a temporarily-degraded but registered project still loads.
+    assertMetaScopeProjectsExist(globalConfig.metaOrchestrators, Object.keys(globalConfig.projects));
     const projects = {};
     const degradedProjects = {};
     for (const [projectId, entry] of Object.entries(globalConfig.projects)) {
@@ -757,6 +840,7 @@ function buildEffectiveConfigFromGlobalConfigPath(configPath) {
         notifiers: globalConfig.notifiers,
         notificationRouting: globalConfig.notificationRouting,
         reactions: globalConfig.reactions,
+        metaOrchestrators: globalConfig.metaOrchestrators,
         projects,
     });
     return { ...config, degradedProjects };
@@ -768,10 +852,23 @@ function buildEffectiveConfigFromGlobalConfigPath(configPath) {
 function findConfig(startDir) {
     return findConfigFile(startDir);
 }
+/**
+ * Validate a WRAPPED config (one that carries its full `projects` map inline).
+ * Mirrors the global/flat-local builders by failing loud on a meta scope that
+ * references an unregistered project — validated against this config's own
+ * complete projects set. NOT folded into the shared `validateConfig`, because the
+ * flat-local builder calls validateConfig with a SINGLE-PROJECT projection where
+ * such a check would spuriously reject valid multi-project scopes (round-15).
+ */
+function validateWrappedConfig(raw) {
+    const config = validateConfig(raw);
+    assertMetaScopeProjectsExist(config.metaOrchestrators, Object.keys(config.projects));
+    return config;
+}
 /** Load and validate config from a YAML file */
 function loadConfig(configPath) {
-    // Priority: 1. Explicit param, 2. Search (including AO_CONFIG_PATH env var)
-    // findConfigFile treats AO_CONFIG_PATH as authoritative when present.
+    // Priority: 1. Explicit param, 2. Search (including ATHENE_CONFIG_PATH env var)
+    // findConfigFile treats ATHENE_CONFIG_PATH as authoritative when present.
     const path = configPath ?? findConfigFile();
     if (!path) {
         throw new ConfigNotFoundError();
@@ -784,9 +881,13 @@ function loadConfig(configPath) {
         ? applyWrappedLocalStorageKeys(path, parsed)
         : parsed;
     const config = isCanonicalGlobalConfig
-        ? (buildEffectiveConfigFromGlobalConfigPath(path) ?? validateConfig(normalizedParsed))
+        ? // The canonical-global `normalizedParsed` carries the full registry, so the
+            // fallback must mirror the builder's "fail loudly on unknown meta scope"
+            // rule (validateConfig alone skips it). validateWrappedConfig validates
+            // scopes against the complete `projects` map — no flat-local projection.
+            (buildEffectiveConfigFromGlobalConfigPath(path) ?? validateWrappedConfig(normalizedParsed))
         : shape === "wrapped"
-            ? validateConfig(normalizedParsed)
+            ? validateWrappedConfig(normalizedParsed)
             : (buildEffectiveConfigFromFlatLocalPath(path) ??
                 validateConfig(normalizedParsed));
     // Set the config path in the config object for hash generation
@@ -810,9 +911,13 @@ function loadConfigWithPath(configPath) {
         ? applyWrappedLocalStorageKeys(path, parsed)
         : parsed;
     const config = isCanonicalGlobalConfig
-        ? (buildEffectiveConfigFromGlobalConfigPath(path) ?? validateConfig(normalizedParsed))
+        ? // The canonical-global `normalizedParsed` carries the full registry, so the
+            // fallback must mirror the builder's "fail loudly on unknown meta scope"
+            // rule (validateConfig alone skips it). validateWrappedConfig validates
+            // scopes against the complete `projects` map — no flat-local projection.
+            (buildEffectiveConfigFromGlobalConfigPath(path) ?? validateWrappedConfig(normalizedParsed))
         : shape === "wrapped"
-            ? validateConfig(normalizedParsed)
+            ? validateWrappedConfig(normalizedParsed)
             : (buildEffectiveConfigFromFlatLocalPath(path) ??
                 validateConfig(normalizedParsed));
     // Set the config path in the config object for hash generation
@@ -848,5 +953,5 @@ function getDefaultConfig() {
     });
 }
 
-export { collectExternalPluginConfigs, findConfig, findConfigFile, getDefaultConfig, loadConfig, loadConfigWithPath, validateConfig };
+export { assertMetaScopeProjectsExist, collectExternalPluginConfigs, findConfig, findConfigFile, getDefaultConfig, loadConfig, loadConfigWithPath, validateConfig, validateWrappedConfig };
 //# sourceMappingURL=config.js.map