elanous 0.2.0 → 0.2.5

package/scripts/backup/elanous-backup.sh

@@ -57,10 +57,11 @@ for a in "$@"; do
     #       ***「사본이 다르다」로 «거짓 양성»***을 낸다 — 사본은 main 과 같은데도 그렇다.
     #    🔑 운영 트리(tree-sync 가 20분마다 main 으로 당기는 곳)를 가리켜야
     #       「다르다」가 ***「사본이 main 보다 뒤처졌다」***라는 «쓸모 있는» 뜻이 된다.
+    #    🔁 2026-09-26: pilot 트리는 사라졌다 — 운영 출처는 이제 «설치본»이다(매일 04:33 main 으로 갱신).
     case "$SELF" in
-      */pilot/*) : ;;
-      *) echo "  ⚠️ ⛔ 출처가 «운영 트리가 아니다» — 이 트리를 편집하면 낡음 검사가 «거짓 양성»을 낸다."
-         echo "     ⇒ 운영 트리에서 다시 심어라:  bash <pilot 트리>/scripts/backup/elanous-backup.sh --install" ;;
+      */.local/share/elanous/*) : ;;
+      *) echo "  ⚠️ ⛔ 출처가 «설치본이 아니다» — 이 트리를 편집하면 낡음 검사가 «거짓 양성»을 낸다."
+         echo "     ⇒ 설치본에서 다시 심어라:  bash $HOME/.local/share/elanous/current/node_modules/elanous/scripts/backup/elanous-backup.sh --install" ;;
     esac
     exit 0
   fi
@@ -106,10 +107,11 @@ esac
 #    ⇒ 🔑 크론의 기본 PATH 는 /usr/bin:/bin:/usr/sbin:/sbin 이고 gcloud 는 /opt/homebrew/bin 에 있다.
 #    ⛔ 「내 셸에서 되니까 된다」가 그 병이다 — 로그인 셸의 PATH 는 크론에 «없다».
 GCLOUD=""
-for c in /opt/homebrew/bin/gcloud /usr/local/bin/gcloud "$HOME/google-cloud-sdk/bin/gcloud"; do
-  [ -x "$c" ] && { GCLOUD="$c"; break; }
+# 🔁 2026-09-26: PATH 를 «먼저» 본다 — crontab 찾기와 같은 꼴. 크론 PATH 엔 Homebrew 가 없어 결과는 같고,
+#    시험이 PATH 앞에 둔 스텁을 «건너뛰고» 진짜 gcloud 를 부르는 구멍(🅕 실측: 가짜 HOME 으로 진짜 cp 가 돌았다)을 막는다.
+for c in "$(command -v gcloud 2>/dev/null || true)" /opt/homebrew/bin/gcloud /usr/local/bin/gcloud "$HOME/google-cloud-sdk/bin/gcloud"; do
+  [ -n "$c" ] && [ -x "$c" ] && { GCLOUD="$c"; break; }
 done
-[ -z "$GCLOUD" ] && GCLOUD="$(command -v gcloud 2>/dev/null || true)"
 if [ -z "$GCLOUD" ]; then
   echo "⛔ gcloud 를 «못 찾았다» (PATH=$PATH) — 담기 전에 멈춘다(200M 을 만들고 버리지 않는다)"
   exit 1
@@ -125,6 +127,9 @@ for c in "$(command -v crontab 2>/dev/null || true)" /usr/bin/crontab /bin/cront
 done
 
 BUCKET="${ELANOUS_BACKUP_BUCKET:-gs://monad-backup-pearlplaygroud}"
+# 🔐 자격 묶음은 «다른» 곳으로 간다 — age 로 암호화한 파일 «하나»만, 비공개 S3 버킷으로(2026-09-26 · 대표).
+SECRETS_BUCKET="${ELANOUS_BACKUP_SECRETS_BUCKET:-s3://elanvital-ops-backup}"
+RECIPIENT_FILE="${ELANOUS_BACKUP_RECIPIENT_FILE:-$HOME/.elanous/backup-key/recipient.txt}"
 DRY=0
 # 🏷️ 「무인(cron)인가」 — ⛔ 안 주면 「미상」. 「손」으로 «가정하지 않는다».
 BACKUP_SOURCE=unknown
@@ -137,6 +142,7 @@ for a in "$@"; do
     --dry-run) DRY=1 ;;
     --bucket) shift; BUCKET="${1:-$BUCKET}" ;;
     gs://*) BUCKET="$a" ;;
+    s3://*) SECRETS_BUCKET="$a" ;;
   esac
   _prev="$a"
 done
@@ -147,9 +153,11 @@ DEST="$BUCKET/$HOST/$STAMP"
 STAGE="$(mktemp -d "${TMPDIR:-/tmp}/elanous-backup-XXXXXX")"
 # ⛔ 오류 파일을 staging «안»에 두면 그것까지 «올라간다»(첫 판에서 빈 .err 4개가 올라갔다).
 ERRDIR="$(mktemp -d "${TMPDIR:-/tmp}/elanous-backup-err-XXXXXX")"
-trap 'rm -rf "$STAGE" "$ERRDIR"' EXIT
+# 🔐 평문 자격이 닿는 «유일한» 자리 — 권한 700 · 종료 시 지운다. ⛔ 평문 tar 는 여기에도 만들지 않는다(파이프로 age 에 흘린다).
+SECDIR="$(mktemp -d "${TMPDIR:-/tmp}/elanous-backup-sec-XXXXXX")"; chmod 700 "$SECDIR"
+trap 'rm -rf "$STAGE" "$ERRDIR" "$SECDIR"' EXIT
 
-human() { du -h "$1" 2>/dev/null | cut -f1; }
+human() { du -sh "$1" 2>/dev/null | cut -f1; }
 note()  { printf "  %-42s %8s  %s\n" "$1" "$2" "${3:-}"; }
 
 echo "═══ 담을 것을 «세운다» (staging: $STAGE) ═══"
@@ -259,7 +267,9 @@ snap_crontab() {
   local hits
   hits="$(grep -niE "$CRED_RE" "$out" 2>/dev/null | cut -d: -f1 | tr '\n' ' ')"
   if [ -n "${hits// /}" ]; then
-    rm -f "$out"
+    # 🔐 데이터 백업(GCS)에는 «안» 담는다 — 대신 원문을 자격 묶음으로 넘겨 «암호화해서» 담는다(아래 🔐 단계).
+    #    ⛔ 판정은 그대로 둔다(FAILED+1): 「평문 크론에 자격이 있다」는 사실 자체를 계속 사람에게 보인다.
+    mv -f "$out" "$SECDIR/machine-crontab.raw" 2>/dev/null || rm -f "$out"
     note "$name" "-" "⛔ 자격처럼 보이는 값이 있어 «안 담았다» — 줄: ${hits}(⛔ 값은 안 낸다). 크론 밖으로 옮겨라"
     FAILED=$((FAILED+1))
     return 1
@@ -323,6 +333,89 @@ while IFS= read -r tdb; do
 done < <(find "$HOME/source" -maxdepth 5 -type f -path '*/.elanous-test/tasks/tasks.db' 2>/dev/null)
 echo "  (트리 태스크 $TREE_TASKS 개)"
 
+# ── 🔐 자격 묶음: 명시 허용 목록 → tar | age → .age 한 파일 ──────────────────────────
+# 대표 2026-09-26: «재로그인 안내는 원하는 백업이 아니다 — 자격까지». 계기 = MCP 로그인값 유실.
+# ⛔ 불변식 셋: ① 평문은 $SECDIR(700) 밖에 안 쓴다 — tar 출력을 곧바로 age 로 흘려 평문 묶음 파일조차 안 만든다
+#              ② 올리는 것은 `.age` 한 파일뿐이다 ③ 출력에는 «이름과 바이트»만 — 내용은 한 줄도 안 낸다.
+# ⛔ 디렉터리를 통째로 담지 않는다 — `~/.codex` 는 4.8GB 대부분이 대화 기록이다(2026-09-26 실측).
+SECRET_ITEMS=()   # $HOME 기준 상대 경로
+add_secret() { [ -e "$HOME/$1" ] && SECRET_ITEMS+=("$1"); return 0; }
+for f in auth.json acp-token export-redactions.tsv config.json ssh-hosts.json; do add_secret ".elanous/$f"; done
+for d in "$HOME"/.codex "$HOME"/.codex-*; do
+  [ -d "$d" ] || continue; b="$(basename "$d")"
+  add_secret "$b/auth.json"; add_secret "$b/config.toml"
+done
+add_secret ".grok/auth.json"; add_secret ".grok/config.toml"
+for f in .config/gh/hosts.yml .aws/credentials .aws/config .npmrc .cargo/credentials.toml .ssh; do add_secret "$f"; done
+for f in credentials.db access_tokens.db application_default_credentials.json active_config configurations legacy_credentials; do
+  add_secret ".config/gcloud/$f"
+done
+add_secret "Library/Application Support/Higgsfield/Blender/auth.json"
+add_secret "Library/Application Support/Higgsfield/Blender/mcp"
+add_secret ".aside/accounts.json"
+for f in "$HOME"/Library/LaunchAgents/com.elanous.*.plist; do [ -f "$f" ] && add_secret "Library/LaunchAgents/$(basename "$f")"; done
+# API 키 캐시 — 이름은 `src/cli/doctor-fix.ts` defaultKeyNames() 와 같은 규칙: .env.example 의 `KEY=` 를 소문자로.
+KEY_CACHE_DIR="${ELANOUS_KEY_CACHE_DIR:-$HOME/.cache}"
+ENV_EXAMPLE="$(cd "$(dirname "$SELF")/../.." 2>/dev/null && pwd)/.env.example"
+case "$SRC_LINE" in '# ⛔ 이 파일은 «사본»이다. 출처: '*) ENV_EXAMPLE="$(cd "$(dirname "${SRC_LINE#*출처: }")/../.." 2>/dev/null && pwd)/.env.example" ;; esac
+KEY_CACHE_N=0; KEY_CACHE_OUTSIDE=0
+if [ -f "$ENV_EXAMPLE" ]; then
+  while IFS= read -r k; do
+    [ -f "$KEY_CACHE_DIR/$k" ] || continue
+    case "$KEY_CACHE_DIR/" in
+      "$HOME"/*) add_secret "${KEY_CACHE_DIR#"$HOME"/}/$k"; KEY_CACHE_N=$((KEY_CACHE_N+1)) ;;
+      # ⛔ 홈 밖 캐시는 «조용히 빼지 않는다» — 묶음은 홈 기준 경로라 못 담으니 실패로 센다(리뷰 must-fix).
+      *) KEY_CACHE_OUTSIDE=$((KEY_CACHE_OUTSIDE+1)) ;;
+    esac
+  done < <(sed -nE 's/^[[:space:]]*(#[[:space:]]*)?([A-Z][A-Z0-9_]*)=.*/\2/p' "$ENV_EXAMPLE" | tr 'A-Z' 'a-z' | sort -u)
+fi
+HAS_RAW_CRON=0; [ -s "$SECDIR/machine-crontab.raw" ] && HAS_RAW_CRON=1
+
+AGE=""
+for c in /opt/homebrew/bin/age /usr/local/bin/age "$(command -v age 2>/dev/null || true)"; do
+  [ -n "$c" ] && [ -x "$c" ] && { AGE="$c"; break; }
+done
+AWS=""
+for c in "$(command -v aws 2>/dev/null || true)" /opt/homebrew/bin/aws /usr/local/bin/aws; do
+  [ -n "$c" ] && [ -x "$c" ] && { AWS="$c"; break; }
+done
+SECRETS_STATE=skipped      # skipped | ok | failed
+SECRETS_REASON=""
+SECRETS_FILE="$SECDIR/secrets.tar.age"
+SECRETS_DEST="$SECRETS_BUCKET/$HOST/$STAMP/secrets.tar.age"
+echo
+echo "═══ 🔐 자격 묶음 (암호화 → $SECRETS_BUCKET) ═══"
+N_SECRETS=$(( ${#SECRET_ITEMS[@]} + HAS_RAW_CRON + KEY_CACHE_OUTSIDE ))
+if [ "$N_SECRETS" -eq 0 ]; then
+  echo "  담을 자격이 없다 — 건너뛴다"
+else
+  for it in ${SECRET_ITEMS[@]+"${SECRET_ITEMS[@]}"}; do note "secret:$it" "$(human "$HOME/$it")"; done
+  [ "$HAS_RAW_CRON" = 1 ] && note "secret:machine-crontab.raw" "$(human "$SECDIR/machine-crontab.raw")" "← 평문 백업에서 뺀 크론 원문"
+  echo "  (항목 $N_SECRETS · API 키 캐시 $KEY_CACHE_N$([ "$KEY_CACHE_OUTSIDE" -gt 0 ] && echo " · ⛔ 홈 밖 캐시 $KEY_CACHE_OUTSIDE"))"
+  if [ "$KEY_CACHE_OUTSIDE" -gt 0 ]; then
+    SECRETS_STATE=failed; SECRETS_REASON="API 키 캐시 $KEY_CACHE_OUTSIDE 개가 홈 밖($KEY_CACHE_DIR)이라 못 담는다 — ELANOUS_KEY_CACHE_DIR 를 홈 안으로"
+  elif [ -z "$AGE" ]; then
+    SECRETS_STATE=failed; SECRETS_REASON="age 를 못 찾았다 (brew install age)"
+  elif [ ! -s "$RECIPIENT_FILE" ]; then
+    SECRETS_STATE=failed; SECRETS_REASON="공개 열쇠 파일이 없다: $RECIPIENT_FILE"
+  else
+    TAR_ARGS=(-C "$HOME")
+    for it in ${SECRET_ITEMS[@]+"${SECRET_ITEMS[@]}"}; do TAR_ARGS+=("$it"); done
+    [ "$HAS_RAW_CRON" = 1 ] && TAR_ARGS+=(-C "$SECDIR" machine-crontab.raw)
+    # ⛔ pipefail 이 켜져 있으므로 tar 가 실패해도 여기서 잡힌다(파이프 뒤 rc 가 아니다).
+    if tar -cf - "${TAR_ARGS[@]}" 2>"$ERRDIR/secrets-tar.err" \
+         | "$AGE" -r "$(head -1 "$RECIPIENT_FILE" | tr -d '[:space:]')" -o "$SECRETS_FILE" 2>"$ERRDIR/secrets-age.err"; then
+      SECRETS_STATE=ok
+      note "secrets.tar.age" "$(human "$SECRETS_FILE")" "← tar | age -r (평문 묶음 파일 없음)"
+    else
+      rm -f "$SECRETS_FILE"
+      SECRETS_STATE=failed
+      SECRETS_REASON="묶기/암호화 실패: $(head -c 90 "$ERRDIR/secrets-tar.err" "$ERRDIR/secrets-age.err" 2>/dev/null | tr '\n' ' ')"
+    fi
+  fi
+  rm -f "$SECDIR/machine-crontab.raw"
+fi
+
 TOTAL="$(du -sh "$STAGE" 2>/dev/null | cut -f1)"
 echo
 STAGED=$(ls -1 "$STAGE" 2>/dev/null | wc -l | tr -d ' ')
@@ -331,11 +424,17 @@ echo "합계 $TOTAL → $DEST"
 printf "📋 계획 %s · 담김 %s · 실패 %s  %s\n" "$PLANNED" "$STAGED" "$FAILED" \
   "$([ "$PLANNED" = "$STAGED" ] && [ "$FAILED" = "0" ] && echo ✅ || echo '⛔ 구멍이 있다')"
 [ "$FAILED" -gt 0 ] && echo "⛔ 스냅샷 실패 $FAILED 건 — 위를 읽어라. 백업에 «구멍»이 있다."
+case "$SECRETS_STATE" in
+  ok)      echo "🔐 자격 묶음 ✅ 암호화됨 → $SECRETS_DEST" ;;
+  skipped) echo "🔐 자격 묶음 — 담을 자격이 없어 건너뛰었다" ;;
+  failed)  echo "🔐 자격 묶음 ⛔ 실패 — $SECRETS_REASON" ;;
+esac
 
 if [ "$DRY" = "1" ]; then
   echo "[dry-run] 올리지 않았다. 위 목록이 «올라갈 것»이다."
   # ⛔ 예행에서도 「구멍」을 «초록으로» 끝내지 않는다 — 예행의 뜻은 「이대로 올라간다」이므로.
   [ "$FAILED" -gt 0 ] || [ "$PLANNED" != "$STAGED" ] && exit 1
+  [ "$SECRETS_STATE" = failed ] && exit 1
   exit 0
 fi
 
@@ -349,6 +448,27 @@ if [ "$UPLOAD_RC" -ne 0 ]; then
   echo "⛔ 업로드 실패 (rc=$UPLOAD_RC)"; exit 1
 fi
 
+if [ "$SECRETS_STATE" = ok ]; then
+  if [ -z "$AWS" ]; then
+    SECRETS_STATE=failed; SECRETS_REASON="aws CLI 를 못 찾았다 (PATH=$PATH)"
+  else
+    S_LOG=$("$AWS" s3 cp "$SECRETS_FILE" "$SECRETS_DEST" --only-show-errors 2>&1); S_RC=$?
+    if [ "$S_RC" -ne 0 ]; then
+      SECRETS_STATE=failed; SECRETS_REASON="S3 업로드 실패 (rc=$S_RC): $(printf '%s' "$S_LOG" | head -c 120)"
+    else
+      # ⛔ 「올렸다」로 끝내지 않는다 — 저쪽 크기를 «다시» 잰다
+      R_SIZE=$("$AWS" s3 ls "$SECRETS_DEST" 2>/dev/null | awk '{print $3}' | head -1)
+      L_SIZE=$(wc -c < "$SECRETS_FILE" | tr -d ' ')
+      if [ "$R_SIZE" = "$L_SIZE" ]; then
+        echo "🔐 자격 묶음 업로드 ✅ ${L_SIZE} bytes → $SECRETS_DEST"
+      else
+        SECRETS_STATE=failed; SECRETS_REASON="원격 크기(${R_SIZE:-없음}) ≠ 로컬(${L_SIZE})"
+      fi
+    fi
+  fi
+  [ "$SECRETS_STATE" = failed ] && echo "🔐 자격 묶음 ⛔ 실패 — $SECRETS_REASON"
+fi
+
 # ── ⛔ 「올렸다」로 끝내지 않는다 — «저쪽에서» 세어 본다 ──────────────────────
 echo "═══ 판정 — 원격에서 «다시 센다» ═══"
 REMOTE=$("$GCLOUD" storage ls -l "$DEST/**" 2>/dev/null | grep -vE '^TOTAL' | wc -l | tr -d ' ')
@@ -364,8 +484,8 @@ printf "  로컬 %s개 · 원격 %s개  %s\n" "$LOCAL" "$REMOTE" "$([ "$LOCAL" =
 #    ⚠️ 이 줄은 ***판정 «앞»***에 둔다 — 실패한 회차일 때가 «가장 남겨야 할» 때다.
 BACKUP_LEDGER="${ELANOUS_STATE_DIR:-$HOME/.elanous}/botlab/backup-runs.jsonl"
 mkdir -p "$(dirname "$BACKUP_LEDGER")" 2>/dev/null
-printf '{"at":"%s","dest":"%s","planned":%s,"staged":%s,"failed":%s,"uploaded":%s}\n' \
-  "$(date -u +%FT%TZ)" "$DEST" "${PLANNED:-0}" "${LOCAL:-0}" "${FAILED:-0}" "${REMOTE:-0}" \
+printf '{"at":"%s","dest":"%s","planned":%s,"staged":%s,"failed":%s,"uploaded":%s,"secrets":"%s"}\n' \
+  "$(date -u +%FT%TZ)" "$DEST" "${PLANNED:-0}" "${LOCAL:-0}" "${FAILED:-0}" "${REMOTE:-0}" "${SECRETS_STATE:-skipped}" \
   >> "$BACKUP_LEDGER" 2>/dev/null \
   && echo "  🧾 회차 판정 기록 — $BACKUP_LEDGER" \
   || echo "  ⚠️⛔ 회차 판정을 «못 남겼다» — 카나리아가 이 회차의 «완전성»을 못 본다"
@@ -381,9 +501,14 @@ case "$SRC_LINE" in
   *) HB_REPO="$(cd "$(dirname "$SELF")/../.." 2>/dev/null && pwd)" ;;
 esac
 BACKUP_OK=1
-{ [ "$LOCAL" = "$REMOTE" ] && [ "$FAILED" = "0" ] && [ "$PLANNED" = "$LOCAL" ]; } && BACKUP_OK=0
-if [ -n "$HB_REPO" ] && [ -f "$HB_REPO/scripts/botlab/heartbeat-emit.sh" ]; then
-  bash "$HB_REPO/scripts/botlab/heartbeat-emit.sh" backup "$BACKUP_OK" "$HB_REPO" "$BACKUP_SOURCE"
+{ [ "$LOCAL" = "$REMOTE" ] && [ "$FAILED" = "0" ] && [ "$PLANNED" = "$LOCAL" ] && [ "$SECRETS_STATE" != failed ]; } && BACKUP_OK=0
+if [ "${ELANOUS_BACKUP_NO_HEARTBEAT:-0}" = "1" ]; then
+  echo "  (심박 끔 — ELANOUS_BACKUP_NO_HEARTBEAT=1 · 시험 전용)" >&2
+elif [ -n "$HB_REPO" ] && [ -f "$HB_REPO/scripts/botlab/heartbeat-emit.sh" ]; then
+  # 심박은 «운영» 우주로 — 백업이 뜨는 것이 운영 ~/.elanous 이다. 크론은 환경변수가 없고 소스 트리는
+  # 트리 파생 시험 우주로 풀려(`where` layer=tree-derived) 심박이 «격리라 안 밀었다»로 3일 멎었다(09-30).
+  ELANOUS_STATE_DIR="${ELANOUS_STATE_DIR:-$HOME/.elanous}" ELANOUS_CONFIG_DIR="${ELANOUS_CONFIG_DIR:-$HOME/.elanous}" \
+    bash "$HB_REPO/scripts/botlab/heartbeat-emit.sh" backup "$BACKUP_OK" "$HB_REPO" "$BACKUP_SOURCE"
 else
   echo "  ⚠️ 심박을 «못 보냈다» — 저장소 자리를 못 찾았다(HB_REPO=${HB_REPO:-없음})" >&2
 fi
@@ -395,3 +520,7 @@ if [ "$FAILED" -gt 0 ] || [ "$PLANNED" != "$LOCAL" ]; then
   echo "⛔ 올렸지만 «완전하지 않다» — 계획 $PLANNED · 담김 $LOCAL · 실패 $FAILED"
   exit 1
 fi
+if [ "$SECRETS_STATE" = failed ]; then
+  echo "⛔ 데이터는 올렸지만 «자격 묶음»이 실패했다 — $SECRETS_REASON"
+  exit 1
+fi

package/scripts/backup/elanous-restore.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+# elanous 운영 백업의 «자격 묶음»(secrets.tar.age)을 되돌린다 — elanous-backup.sh 의 짝.
+#
+#   bash scripts/backup/elanous-restore.sh --list                      묶음 안 항목 «이름»만 본다
+#   bash scripts/backup/elanous-restore.sh --to ~/restore-check        폴더에 풀기만 한다(기본 · 홈을 안 덮는다)
+#   bash scripts/backup/elanous-restore.sh --in-place                  원래 자리로 되돌린다(덮기 전 사본을 남긴다)
+#   옵션: --from <s3://…/secrets.tar.age | 로컬 파일>   (기본: 이 호스트의 가장 최근 묶음)
+#         --identity <identity.age>                    (기본: ~/.elanous/backup-key/identity.age · 없으면 S3 keys/ 에서 받는다)
+#
+# 🔑 여는 법: identity.age 는 passphrase 로 잠겨 있다 — age 가 tty 로 묻는다.
+#    passphrase 는 macOS 키체인 `elanous-backup-passphrase` · AWS Secrets Manager `elanous/ops-backup/age-key` 에 있다.
+#    ⚠️ 시험·무인 복원은 ELANOUS_BACKUP_IDENTITY_PLAIN=<평문 identity 파일> 로 passphrase 없이 연다(그 파일은 호출자가 지킨다).
+# ⛔ 불변식: 평문 묶음은 mktemp -d(700) 안에서만 풀고 끝나면 지운다 · 출력에는 «이름과 바이트»만 — 내용은 안 낸다.
+set -uo pipefail
+
+SECRETS_BUCKET="${ELANOUS_BACKUP_SECRETS_BUCKET:-s3://elanvital-ops-backup}"
+IDENTITY="${ELANOUS_BACKUP_IDENTITY:-$HOME/.elanous/backup-key/identity.age}"
+IDENTITY_PLAIN="${ELANOUS_BACKUP_IDENTITY_PLAIN:-}"
+FROM=""; TO=""; MODE=""
+_prev=""
+for a in "$@"; do
+  case "$_prev" in
+    --from) FROM="$a" ;;
+    --to) TO="$a"; MODE=to ;;
+    --identity) IDENTITY="$a" ;;
+  esac
+  case "$a" in
+    --list) MODE=list ;;
+    --in-place) MODE=inplace ;;
+  esac
+  _prev="$a"
+done
+[ -n "$MODE" ] || { echo "⛔ --list · --to <폴더> · --in-place 중 하나를 준다"; exit 2; }
+
+AGE=""; for c in /opt/homebrew/bin/age /usr/local/bin/age "$(command -v age 2>/dev/null || true)"; do [ -n "$c" ] && [ -x "$c" ] && { AGE="$c"; break; }; done
+[ -n "$AGE" ] || { echo "⛔ age 를 못 찾았다 (brew install age)"; exit 1; }
+AWS=""; for c in "$(command -v aws 2>/dev/null || true)" /opt/homebrew/bin/aws /usr/local/bin/aws; do [ -n "$c" ] && [ -x "$c" ] && { AWS="$c"; break; }; done
+
+WORK="$(mktemp -d "${TMPDIR:-/tmp}/elanous-restore-XXXXXX")"; chmod 700 "$WORK"
+trap 'rm -rf "$WORK"' EXIT
+
+# ── 묶음 가져오기 ────────────────────────────────────────────────────────────
+HOST="$(scutil --get LocalHostName 2>/dev/null || hostname -s)"
+BUNDLE="$WORK/secrets.tar.age"
+if [ -z "$FROM" ]; then
+  [ -n "$AWS" ] || { echo "⛔ aws CLI 가 없다 — --from <로컬 파일> 을 준다"; exit 1; }
+  LATEST="$("$AWS" s3 ls "$SECRETS_BUCKET/$HOST/" 2>/dev/null | awk '/PRE/{print $2}' | sort | tail -1)"
+  [ -n "$LATEST" ] || { echo "⛔ $SECRETS_BUCKET/$HOST/ 에 회차가 없다"; exit 1; }
+  FROM="$SECRETS_BUCKET/$HOST/${LATEST%/}/secrets.tar.age"
+fi
+case "$FROM" in
+  s3://*) "$AWS" s3 cp "$FROM" "$BUNDLE" --only-show-errors || { echo "⛔ 받기 실패: $FROM"; exit 1; } ;;
+  *) [ -f "$FROM" ] || { echo "⛔ 파일이 없다: $FROM"; exit 1; }; cp "$FROM" "$BUNDLE" ;;
+esac
+echo "📦 묶음: $FROM ($(wc -c < "$BUNDLE" | tr -d ' ') bytes)"
+
+# ── 여는 열쇠 ────────────────────────────────────────────────────────────────
+ID_ARGS=()
+if [ -n "$IDENTITY_PLAIN" ]; then
+  [ -f "$IDENTITY_PLAIN" ] || { echo "⛔ 평문 identity 가 없다: $IDENTITY_PLAIN"; exit 1; }
+  ID_ARGS=(-i "$IDENTITY_PLAIN")
+else
+  if [ ! -f "$IDENTITY" ]; then
+    [ -n "$AWS" ] || { echo "⛔ identity 도 aws 도 없다: $IDENTITY"; exit 1; }
+    IDENTITY="$WORK/identity.age"
+    "$AWS" s3 cp "$SECRETS_BUCKET/keys/identity.age" "$IDENTITY" --only-show-errors || { echo "⛔ identity 받기 실패"; exit 1; }
+  fi
+  ID_ARGS=(-i "$IDENTITY")
+  echo "🔑 passphrase 를 묻는다(키체인 elanous-backup-passphrase · Secrets Manager elanous/ops-backup/age-key)"
+fi
+
+# ── 풀기: 평문은 $WORK 안에서만 ─────────────────────────────────────────────
+PLAIN="$WORK/plain"; mkdir -p "$PLAIN"; chmod 700 "$PLAIN"
+if ! "$AGE" -d "${ID_ARGS[@]}" "$BUNDLE" | tar -xf - -C "$PLAIN"; then
+  echo "⛔ 복호화/풀기 실패 — passphrase·identity 를 확인한다"; exit 1
+fi
+N=0
+while IFS= read -r f; do
+  N=$((N+1)); printf "  %-64s %8s bytes\n" "${f#"$PLAIN"/}" "$(wc -c < "$f" | tr -d ' ')"
+done < <(find "$PLAIN" -type f | sort)
+echo "  (파일 $N 개)"
+
+case "$MODE" in
+  list) exit 0 ;;
+  to)
+    mkdir -p "$TO" || { echo "⛔ 폴더를 못 만든다: $TO"; exit 1; }
+    # ⛔ `--to` 는 «홈을 안 덮는다» — 홈(또는 홈을 품은 상위)을 주면 거부한다(리뷰 must-fix · 2026-09-26).
+    TO_REAL="$(cd "$TO" && pwd -P)"; HOME_REAL="$(cd "$HOME" && pwd -P)"
+    case "$HOME_REAL/" in
+      "$TO_REAL"/*) echo "⛔ --to 가 홈이거나 홈을 품는다($TO_REAL) — 홈에 되돌리려면 --in-place 를 쓴다"; exit 2 ;;
+    esac
+    chmod 700 "$TO" || { echo "⛔ 권한을 못 바꾼다: $TO"; exit 1; }
+    ( cd "$PLAIN" && tar -cf - . ) | ( cd "$TO" && tar -xpf - ) || { echo "⛔ 옮기기 실패"; exit 1; }
+    echo "✅ $TO 에 풀었다 — 홈은 건드리지 않았다. 확인 뒤 필요한 파일만 옮기거나 --in-place 를 쓴다."
+    ;;
+  inplace)
+    STAMP="$(date -u +%Y%m%dT%H%M%SZ)"; KEPT=0; DONE=0; SKIPPED=0
+    while IFS= read -r f; do
+      rel="${f#"$PLAIN"/}"
+      [ "$rel" = "machine-crontab.raw" ] && continue   # 크론은 사람이 보고 `crontab <파일>` 로 되돌린다
+      dst="$HOME/$rel"
+      # ⛔ 대상이 심볼릭 링크면(깨진 링크 포함) 건드리지 않는다 — cp 가 링크 «너머»를 사본 없이 덮을 수 있다(리뷰 must-fix).
+      if [ -L "$dst" ]; then echo "  ⛔ 대상이 심볼릭 링크라 건너뛴다(손으로 확인): $rel"; SKIPPED=$((SKIPPED+1)); continue; fi
+      if [ -e "$dst" ]; then
+        # ⛔ 사본을 못 만들면 «덮지 않는다» — 되돌릴 길 없이 덮는 것이 이 모드의 유일한 위험이다(리뷰 must-fix).
+        if cp -p "$dst" "$dst.pre-restore-$STAMP"; then KEPT=$((KEPT+1)); else
+          echo "  ⛔ 사본 실패 — 건너뛴다: $rel"; SKIPPED=$((SKIPPED+1)); continue
+        fi
+      fi
+      if mkdir -p "$(dirname "$dst")" && cp -p "$f" "$dst"; then DONE=$((DONE+1)); else
+        echo "  ⛔ 되돌리기 실패: $rel"; SKIPPED=$((SKIPPED+1))
+      fi
+    done < <(find "$PLAIN" -type f)
+    echo "원래 자리로 $DONE 개 되돌림 · 덮기 전 사본 $KEPT 개(*.pre-restore-$STAMP) · 실패 $SKIPPED 개"
+    [ "$SKIPPED" -eq 0 ] || { echo "⛔ 일부를 못 되돌렸다 — 위를 읽어라"; exit 1; }
+    echo "✅ 되돌렸다"
+    if [ -f "$PLAIN/machine-crontab.raw" ]; then
+      echo "  ⚠️ 크론 원문은 자동으로 안 되돌린다 — --to 로 풀어 보고 crontab <파일> 로 되돌린다"
+    fi
+    ;;
+esac
+exit 0

package/scripts/build-docs-site.ts

@@ -60,11 +60,12 @@ export const TRACK_SCRUBS: { pattern: RegExp; replace: string; why: string }[] =
 /** 잔여 표식 — 하나라도 남으면 rc=1 */
 const TRACK_REGISTRY = JSON.parse(
   readFileSync(join(import.meta.dir, 'coord-tracks.json'), 'utf8'),
-) as { tracks: { id: string; mark: string }[] };
+) as { tracks: { id: string; mark: string; alias?: string }[] };
 const TRACK_MARKS = TRACK_REGISTRY.tracks.map((t) => t.mark).join('');
-const TRACK_IDS = TRACK_REGISTRY.tracks.map((t) => t.id).join('');
+/** 2글자 신원(OP·MK·TC·UX) ⊕ 옛 한 글자 별칭(S·T·O·F) — 둘 다 공개 문서에 남으면 안 된다. */
+const TRACK_NAMES = [...new Set(TRACK_REGISTRY.tracks.flatMap((t) => [t.id, t.alias ?? '']).filter(Boolean))].join('|');
 /** 잔여 표식 — 트랙 정본(`coord-tracks.json`)에서 파생한다. 트랙을 더해도 여기는 고치지 않는다. */
-export const TRACK_RESIDUE = new RegExp(`[${TRACK_MARKS}]|(?<![\\w\\]])\\[[${TRACK_IDS}]\\](?!\\()`, 'gu');
+export const TRACK_RESIDUE = new RegExp(`[${TRACK_MARKS}]|(?<![\\w\\]])\\[(?:${TRACK_NAMES})\\](?!\\()`, 'gu');
 
 export function scrubTrackMarks(md: string): { text: string; applied: string[] } {
   let text = md;

package/scripts/ci-daemon-port-gate.ts

@@ -0,0 +1,164 @@
+/** Ratchet for daemon port literals in non-test TypeScript source. */
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+const ROOT = join(import.meta.dir, '..');
+const BASELINE_FILE = 'scripts/daemon-port-baseline.txt';
+const PORT = '31415';
+
+type Hit = { lineNumber: number; line: string };
+type DaemonPortGateIo = {
+  args?: readonly string[];
+  cwd?: string;
+  scan?: () => Map<string, Hit[]>;
+  loadBaseline?: () => Map<string, number>;
+  writeBaseline?: (entries: Map<string, number>) => void;
+  log?: (message: string) => void;
+  error?: (message: string) => void;
+};
+
+/** Only comment-only lines are ignored; executable code with trailing comments is counted. */
+export function scanDaemonPortSource(source: string): Hit[] {
+  let inBlockComment = false;
+  let quote: "'" | '"' | null = null;
+  const frames: Array<{ kind: 'template' } | { kind: 'expression'; depth: number }> = [];
+  return source.split('\n').flatMap((line, index) => {
+    let code = '';
+    for (let offset = 0; offset < line.length;) {
+      const char = line[offset]!;
+      const next = line[offset + 1];
+      const frame = frames.at(-1);
+      if (frame?.kind === 'template') {
+        if (char === '\\' && next !== undefined) {
+          code += char + next;
+          offset += 2;
+        } else if (char === '$' && next === '{') {
+          code += '${';
+          frames.push({ kind: 'expression', depth: 0 });
+          offset += 2;
+        } else {
+          code += char;
+          if (char === '`') frames.pop();
+          offset++;
+        }
+      } else if (inBlockComment) {
+        if (char === '*' && next === '/') {
+          inBlockComment = false;
+          offset += 2;
+        } else offset++;
+      } else if (quote) {
+        code += char;
+        if (char === '\\' && next !== undefined) {
+          code += next;
+          offset += 2;
+        } else {
+          if (char === quote) quote = null;
+          offset++;
+        }
+      } else if (char === '/' && next === '*') {
+        inBlockComment = true;
+        offset += 2;
+      } else if (char === '/' && next === '/') {
+        break;
+      } else {
+        code += char;
+        if (char === "'" || char === '"') quote = char;
+        else if (char === '`') frames.push({ kind: 'template' });
+        else if (frame?.kind === 'expression') {
+          if (char === '{') frame.depth++;
+          else if (char === '}' && --frame.depth < 0) frames.pop();
+        }
+        offset++;
+      }
+    }
+    quote = null;
+    const trimmed = line.trim();
+    return code.trim() && code.includes(PORT)
+      ? [{ lineNumber: index + 1, line: trimmed }]
+      : [];
+  });
+}
+
+export function scanDaemonPorts(root = ROOT): Map<string, Hit[]> {
+  const entries = new Map<string, Hit[]>();
+  const src = join(root, 'src');
+  if (!existsSync(src)) return entries;
+  const walk = (dir: string): void => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+      const path = join(dir, entry.name);
+      if (entry.isDirectory()) walk(path);
+      else if (entry.isFile() && entry.name.endsWith('.ts') && !entry.name.endsWith('.test.ts') && !entry.name.endsWith('.spec.ts')) {
+        const hits = scanDaemonPortSource(readFileSync(path, 'utf8'));
+        if (hits.length) entries.set(relative(root, path), hits);
+      }
+    }
+  };
+  walk(src);
+  return entries;
+}
+
+export function readDaemonPortBaseline(text: string): Map<string, number> {
+  const baseline = new Map<string, number>();
+  for (const line of text.split('\n')) {
+    if (!line.trim() || line.startsWith('#')) continue;
+    const match = /^(\d+)\t(src\/[^\t]+\.ts)$/.exec(line);
+    if (!match) throw new Error(`Invalid daemon port baseline row: ${line}`);
+    baseline.set(match[2]!, Number(match[1]));
+  }
+  return baseline;
+}
+
+export function renderDaemonPortBaseline(entries: Map<string, number>): string {
+  const lines = [...entries].sort(([a], [b]) => a.localeCompare(b)).map(([file, count]) => `${count}\t${file}`);
+  const total = [...entries.values()].reduce((sum, count) => sum + count, 0);
+  return [
+    '# Daemon port literal baseline: non-comment lines in non-test src/**/*.ts, per file.',
+    '# New files and increases fail. Migrate callers to the daemon endpoint resolver, then --update.',
+    `# total=${total} files=${entries.size}`,
+    ...lines,
+    '',
+  ].join('\n');
+}
+
+export function runDaemonPortGate(io: DaemonPortGateIo = {}): number {
+  const args = io.args ?? process.argv.slice(2);
+  const log = io.log ?? console.log;
+  const error = io.error ?? console.error;
+  const root = io.cwd ?? ROOT;
+  if (args.some(arg => arg !== '--update')) {
+    error('[daemon-port-gate] FAIL — only --update is supported; the gate always scans all source files.');
+    return 1;
+  }
+  const current = io.scan ? io.scan() : scanDaemonPorts(root);
+  const count = [...current.values()].reduce((sum, hits) => sum + hits.length, 0);
+  log(`[daemon-port-gate] observed ${count} line(s) in ${current.size} file(s).`);
+  const baselinePath = join(root, BASELINE_FILE);
+  if (args.includes('--update')) {
+    const counts = new Map([...current].map(([file, hits]) => [file, hits.length]));
+    (io.writeBaseline ?? ((entries) => writeFileSync(baselinePath, renderDaemonPortBaseline(entries))))(counts);
+    log(`[daemon-port-gate] baseline updated: ${count} line(s) in ${current.size} file(s).`);
+    return 0;
+  }
+  if (!io.loadBaseline && !existsSync(baselinePath)) {
+    error(`[daemon-port-gate] FAIL — missing baseline: ${baselinePath}; run --update to measure it.`);
+    return 1;
+  }
+  const baseline = io.loadBaseline ? io.loadBaseline() : readDaemonPortBaseline(readFileSync(baselinePath, 'utf8'));
+  let violations = 0;
+  for (const [file, hits] of current) {
+    const allowed = baseline.get(file) ?? 0;
+    if (hits.length <= allowed) continue;
+    violations++;
+    error(`  ${file}: ${allowed} → ${hits.length} (+${hits.length - allowed} daemon port line(s))`);
+    for (const hit of hits) error(`    ${file}:${hit.lineNumber}: ${hit.line.slice(0, 160)}`);
+  }
+  if (violations) {
+    error('[daemon-port-gate] FAIL — replace new daemon port literals with resolveDaemonEndpoint (src/nexus/daemon-endpoint.ts).');
+    return 1;
+  }
+  log('[daemon-port-gate] PASS — no new daemon port literals.');
+  return 0;
+}
+
+if (import.meta.main) process.exit(runDaemonPortGate());

package/scripts/ci-typecheck-changed.ts

@@ -791,7 +791,7 @@ export function formatOutsideChangedWarning(outsideChanged: readonly { file: str
   return `[tsc-gate] ⚠ 변경 파일 밖 진단 ${total}건이 파일 ${fileCount}개에서 버려짐: ${nameText}`;
 }
 
-function inspectTscResult(tsc: TscRun, changed: ReadonlySet<string>, baseline: ReadonlyMap<string, number>, error: (message: string) => void, warn: (message: string) => void, wholeRepository = false, excludedPrefixes: readonly string[] = [], includedPrefixes: readonly string[] = [], promotionBaseline?: BaselineDiagnostics): boolean {
+function inspectTscResult(tsc: TscRun, changed: ReadonlySet<string>, baseline: ReadonlyMap<string, number>, error: (message: string) => void, warn: (message: string) => void, wholeRepository = false, excludedPrefixes: readonly string[] = [], includedPrefixes: readonly string[] = [], promotionBaseline?: BaselineDiagnostics, excludeTests = false): boolean {
   if (!tsc.ran) {
     error(`[tsc-gate] ⛔ 실행 판정 실패 — ${tsc.why}`);
     if (tsc.out.trim()) error(tsc.out.trim().slice(0, 2000));
@@ -800,11 +800,13 @@ function inspectTscResult(tsc: TscRun, changed: ReadonlySet<string>, baseline: R
   }
   const diagnostics = parseTypecheckErrors(tsc.out).filter((diagnostic) =>
     !excludedPrefixes.some((prefix) => diagnostic.file.startsWith(prefix))
+      && (!excludeTests || (!isTestTypeScriptFile(diagnostic.file)))
       && (includedPrefixes.length === 0 || includedPrefixes.some((prefix) => diagnostic.file.startsWith(prefix))),
   );
   const baselineDiagnostics = promotionBaseline && 'diagnostics' in promotionBaseline
     ? promotionBaseline.diagnostics.filter((diagnostic) =>
       !excludedPrefixes.some((prefix) => diagnostic.file.startsWith(prefix))
+        && (!excludeTests || (!isTestTypeScriptFile(diagnostic.file)))
         && (includedPrefixes.length === 0 || includedPrefixes.some((prefix) => diagnostic.file.startsWith(prefix))),
     )
     : undefined;
@@ -904,6 +906,9 @@ export function runGate(io: Partial<GateIo> = {}): void {
   // PWA 설정은 언제나 자기 소유 범위만 판정해 진단이 중복 귀속되지 않게 한다.
   const rootScope = wholeRepository ? new Set(['**']) : rootChanged;
   const pwaScope = wholeRepository ? new Set(['apps/pwa/**']) : pwaChanged;
+  const nonTestRootChanged = new Set([...rootChanged].filter((file) => !isTestTypeScriptFile(file)));
+  const pwaEnvScope = wholeRepository ? new Set(['**']) : nonTestRootChanged;
+  const runsPwaEnv = nonTestRootChanged.size > 0;
   if (requiredFields.length > 0) log(`[tsc-gate] 필수 export 필드 추가 감지 — 저장소 전체 검사로 승격: ${requiredFields.map(({ typeName, fieldName }) => `${typeName}.${fieldName}`).join(', ')}.`);
   if (removedSymbols.length > 0) log(`[tsc-gate] exported 심볼 사라짐 감지 — 저장소 전체 검사로 승격: ${removedSymbols.map(({ name }) => name).join(', ')}.`);
   if (parameterIncreases.length > 0) log(`[tsc-gate] exported 함수 매개변수 증가 감지 — 저장소 전체 검사로 승격: ${parameterIncreases.map(({ name, from, to }) => `${name}(${from}→${to})`).join(', ')}.`);
@@ -912,6 +917,7 @@ export function runGate(io: Partial<GateIo> = {}): void {
   const observedScopes = [
     { config: TYPECHECK_GATE_CONFIG, checkedFiles: [...rootScope], excludes: ['apps/pwa/**'] },
     ...(runsPwa ? [{ config: 'apps/pwa/tsconfig.json', checkedFiles: [...pwaScope], excludes: [] as string[] }] : []),
+    ...(runsPwaEnv ? [{ config: 'tsconfig.pwa-env.json', checkedFiles: [...pwaEnvScope], excludes: ['apps/pwa/**', 'docs/**', '**/*.test.ts', 'test/**'] }] : []),
   ];
   const promotionTriggers = [
     ...(requiredFields.length > 0 ? ['required-export-field'] : []),
@@ -932,8 +938,10 @@ export function runGate(io: Partial<GateIo> = {}): void {
   const baseline = readTestTypecheckBaseline(process.cwd());
   const rootCommand = `${tscBin} --noEmit -p ${TYPECHECK_GATE_CONFIG}`;
   const pwaCommand = `${tscBin} --noEmit -p apps/pwa/tsconfig.json`;
+  const pwaEnvCommand = `${tscBin} --noEmit -p tsconfig.pwa-env.json`;
   const rootPromotionBaseline = wholeRepository ? readBaselineDiagnostics(base, rootCommand) : undefined;
   const pwaPromotionBaseline = wholeRepository && runsPwa ? readBaselineDiagnostics(base, pwaCommand) : undefined;
+  const pwaEnvPromotionBaseline = wholeRepository && runsPwaEnv ? readBaselineDiagnostics(base, pwaEnvCommand) : undefined;
   const rootTsc = runTscCmd(rootCommand);
   let unmeasured = !rootTsc.ran;
   let passed = inspectTscResult(rootTsc, rootScope, baseline, error, warn, wholeRepository, ['apps/pwa/'], [], rootPromotionBaseline);
@@ -943,6 +951,12 @@ export function runGate(io: Partial<GateIo> = {}): void {
     unmeasured = unmeasured || !pwaTsc.ran;
     passed = inspectTscResult(pwaTsc, pwaScope, baseline, error, warn, wholeRepository, [], ['apps/pwa/'], pwaPromotionBaseline) && passed;
   }
+  if (runsPwaEnv) {
+    log(`[tsc-gate] PWA env 패스 — 루트 비시험 ${nonTestRootChanged.size}개 (Next ProcessEnv 선언 포함).`);
+    const pwaEnvTsc = runTscCmd(pwaEnvCommand);
+    unmeasured = unmeasured || !pwaEnvTsc.ran;
+    passed = inspectTscResult(pwaEnvTsc, pwaEnvScope, baseline, error, warn, wholeRepository, ['apps/pwa/'], [], pwaEnvPromotionBaseline, true) && passed;
+  }
   if (passed) { log('[tsc-gate] PASS — 변경 파일에 신규 타입 에러 없음.'); return; }
   // ⛔⭐⭐ T67 — ***마지막 줄은 언제나 「판정」이어야 한다.*** 사람도 도구도 마지막 줄을 읽는다.
   //   🩸 2026-09-11 실측(🅕 보고): 타입 에러 3건이 있는데 `tail -1` 이 «경고»를 집어