therookie 0.4.3

package/templates/hook/lib/orphan-recovery.sh

@@ -0,0 +1,491 @@
+#!/bin/bash
+# lib/orphan-recovery.sh — 비정상 세션 종료 복구(orphan flush recovery).
+# spec docs/superpowers/specs/2026-06-18-crash-recovery-orphan-flush.md §3.
+# 비정상 종료로 Stop hook 이 못 돈 세션의 transcript 를 다음 SessionStart 에서 사후 회수.
+# 리뷰 3회 반영: marker lifecycle 3경로 / content-bearing success(chunks_inserted>0)
+#   / bootstrap "T창 안 최신 K개" / flushed·baseline·deferred 분리 / latency cap / 파일 allowlist.
+#
+# 의존: lib/transcript.sh (messages 추출), curl(flush 재전송).
+
+ROOKIE_ORPHAN_DIR="${ROOKIE_ORPHAN_DIR:-$HOME/.rookie/orphan-recovery}"
+ROOKIE_ORPHAN_AGE_HOLD="${ROOKIE_ORPHAN_AGE_HOLD:-60}"            # 최근 N초 수정 파일 보류
+ROOKIE_ORPHAN_BOOTSTRAP_T="${ROOKIE_ORPHAN_BOOTSTRAP_T:-172800}"  # 첫 도입 T창 (48h)
+ROOKIE_ORPHAN_CAP="${ROOKIE_ORPHAN_CAP:-3}"                       # latency cap = bootstrap K
+ROOKIE_ORPHAN_MAX_BYTES="${ROOKIE_ORPHAN_MAX_BYTES:-52428800}"    # 50MB
+ROOKIE_ORPHAN_DEFER_CAP="${ROOKIE_ORPHAN_DEFER_CAP:-3}"           # marker write 실패 보류 임계
+# pending tail 추출 TTL(일). prod 가 서버 fact 추출 off 라 orphan fact 는 차차 수동 처리뿐인데,
+# chunk 는 이미 recall 복구되므로 오래된 orphan fact 구조화는 비용 대비 가치 낮다. 미처리 N일+ 는
+# expired/ 로 감사 이동(삭제 아님)해 큐가 자동 수렴하게 한다(두목 결정 2026-06-23, 14→3).
+ROOKIE_ORPHAN_PENDING_TTL_DAYS="${ROOKIE_ORPHAN_PENDING_TTL_DAYS:-3}"
+
+# cwd → Claude Code transcript 디렉토리명. URL 인코딩 아님: 영숫자·hyphen 외 전부 '-'.
+# 예: /Volumes/HoOn/01_work/10_the-rookie → -Volumes-HoOn-01-work-10-the-rookie
+claude_project_dir_for_cwd() {
+  printf '%s' "$1" | sed 's/[^a-zA-Z0-9-]/-/g'
+}
+
+_orphan_flushed_dir()  { printf '%s/flushed'  "$ROOKIE_ORPHAN_DIR"; }
+_orphan_baseline_dir() { printf '%s/baseline' "$ROOKIE_ORPHAN_DIR"; }
+_orphan_deferred_dir() { printf '%s/deferred' "$ROOKIE_ORPHAN_DIR"; }
+# Phase 2 (client-assisted tail extraction): chunk 복구(flushed)와 별도로
+#   pending-extraction = 차차가 tail fact 를 추출해야 할 orphan 세션 큐
+#   client_extracted   = 차차가 추출 완료한 세션 (반복 저장 차단 idempotency marker)
+_orphan_pending_dir()          { printf '%s/pending-extraction' "$ROOKIE_ORPHAN_DIR"; }
+_orphan_client_extracted_dir() { printf '%s/client_extracted'   "$ROOKIE_ORPHAN_DIR"; }
+# P0.4: 적재 가드 — 짧고 내용 없는 세션은 low_value/, 14일+ 미처리 pending 은 expired/ 로 이동.
+#   둘 다 삭제 아닌 marker(감사) + scanner 재진입 방지(orphan_is_marked·marked() 제외 집합).
+_orphan_low_value_dir() { printf '%s/low_value' "$ROOKIE_ORPHAN_DIR"; }
+_orphan_expired_dir()   { printf '%s/expired'   "$ROOKIE_ORPHAN_DIR"; }
+_orphan_log()          { printf '%s/recovery.log' "$ROOKIE_ORPHAN_DIR"; }
+
+_orphan_dir_init() {
+  local d="$1"
+  [ -d "$d" ] || mkdir -m 700 -p "$d" 2>/dev/null
+  chmod 700 "$ROOKIE_ORPHAN_DIR" 2>/dev/null
+  chmod 700 "$d" 2>/dev/null
+}
+
+# session_id 가 UUID-like 인지 검증 (P2: marker path traversal 차단 — spec §3.4 "UUID-like filename만").
+_orphan_is_uuid() {
+  [[ "$1" =~ ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ ]]
+}
+
+# 원자적 marker write (tmp + mv). 실패 시 비-0. sid 비-UUID 면 거부(traversal 차단).
+_orphan_write_marker() {
+  local dir="$1" sid="$2" payload="$3"
+  _orphan_is_uuid "$sid" || return 1
+  _orphan_dir_init "$dir"
+  local tmp
+  tmp="$(mktemp "$dir/.tmp.XXXXXX" 2>/dev/null)" || return 1
+  printf '%s' "$payload" > "$tmp" 2>/dev/null || { rm -f "$tmp"; return 1; }
+  chmod 600 "$tmp" 2>/dev/null
+  mv -f "$tmp" "$dir/$sid.json" 2>/dev/null || { rm -f "$tmp"; return 1; }
+  return 0
+}
+
+orphan_mark_flushed() {
+  local sid="$1" source="${2:-stop}" mc="${3:-0}"
+  [ -n "$sid" ] || return 1
+  _orphan_write_marker "$(_orphan_flushed_dir)" "$sid" \
+    "$(printf '{"status":"flushed","source":"%s","message_count":%s}' "$source" "$mc")"
+}
+
+orphan_mark_baseline() {
+  local sid="$1"
+  [ -n "$sid" ] || return 1
+  _orphan_write_marker "$(_orphan_baseline_dir)" "$sid" \
+    '{"status":"baseline_skipped","reason":"bootstrap_old"}'
+}
+
+# P0.4 — 짧고 내용 없는(low_value) 세션 marker. record_pending 대신 호출 → 재적재 차단.
+orphan_mark_low_value() {
+  local sid="$1" reason="${2:-low_value}" mc="${3:-0}"
+  [ -n "$sid" ] || return 1
+  _orphan_write_marker "$(_orphan_low_value_dir)" "$sid" \
+    "$(printf '{"status":"low_value","reason":"%s","message_count":%s}' "$reason" "$mc")"
+}
+
+# P0.4 — pending 14일+ 미처리(expired) marker. orphan_prune_expired 가 pending 정리 시 호출.
+orphan_mark_expired() {
+  local sid="$1"
+  [ -n "$sid" ] || return 1
+  _orphan_write_marker "$(_orphan_expired_dir)" "$sid" \
+    '{"status":"expired","reason":"pending_ttl"}'
+}
+
+# flushed·baseline·low_value·expired marker 가 있으면 0 (scanner 후보 제외 기준).
+# P0.4: low_value·expired 추가 — 짧은 세션·만료 pending 의 sweep 재진입 차단(§9-#4).
+orphan_is_marked() {
+  local sid="$1"
+  [ -n "$sid" ] || return 1
+  [ -f "$(_orphan_flushed_dir)/$sid.json" ] && return 0
+  [ -f "$(_orphan_baseline_dir)/$sid.json" ] && return 0
+  [ -f "$(_orphan_low_value_dir)/$sid.json" ] && return 0
+  [ -f "$(_orphan_expired_dir)/$sid.json" ] && return 0
+  return 1
+}
+
+# ── Phase 2: client-assisted tail extraction marker (2026-06-18) ────
+# 차차가 추출 완료했는지.
+orphan_is_client_extracted() {
+  local sid="$1"
+  [ -n "$sid" ] || return 1
+  [ -f "$(_orphan_client_extracted_dir)/$sid.json" ]
+}
+
+# 복구된 orphan 세션을 client 추출 큐에 등록 (이미 추출 완료면 no-op — 반복 저장 차단).
+# P0.1(P2-5): message_count 를 payload 에 보존 → session-start 요약이 정렬·표시에 활용.
+orphan_record_pending() {
+  local sid="$1" tpath="$2" mc="${3:-0}"
+  _orphan_is_uuid "$sid" || return 1
+  orphan_is_client_extracted "$sid" && return 0
+  local payload
+  payload=$(node -e 'process.stdout.write(JSON.stringify({status:"pending_extraction",transcript_path:process.argv[1]||"",recovered_at:new Date().toISOString(),message_count:Number(process.argv[2]||0)}))' "$tpath" "$mc" 2>/dev/null) || return 1
+  _orphan_write_marker "$(_orphan_pending_dir)" "$sid" "$payload"
+}
+
+# B5 (spec 2026-07-11 §B5) — directive 준수율 계측 POST. fail-soft + 백그라운드(&) —
+# 계측이 marker·세션 시작 흐름을 절대 막지 않는다(리뷰 F3: batch 마킹 20건 × --max-time 5 =
+# 최대 100초 직렬 지연 차단). origin 은 서버가 local_hook 으로 고정하므로 body 는 directive/phase 만.
+# surface 헤더 필수 — served(session-start)와 acted(여기)가 같은 표면 버킷에 적재돼야
+# bySurface 분리 집계가 성립한다(리뷰 F2).
+# 자격증명은 config-resolve.sh 의 rookie_resolve_credentials(env > 로컬 상향 > 전역)로만 해석 —
+# 전역 config 경로 하드코딩은 B6-1 위반(계정 오염 재발 경로)이라 두지 않는다(리뷰 F4).
+_orphan_directive_metric() {
+  local phase="$1"
+  if ! command -v rookie_resolve_credentials >/dev/null 2>&1; then
+    # 단독 source 환경(차차 셸 등)이면 같은 디렉토리의 config-resolve.sh 지연 로드.
+    local _lib_dir; _lib_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd)"
+    # shellcheck source=/dev/null
+    [ -n "$_lib_dir" ] && [ -f "$_lib_dir/config-resolve.sh" ] && . "$_lib_dir/config-resolve.sh"
+  fi
+  command -v rookie_resolve_credentials >/dev/null 2>&1 || return 0
+  rookie_resolve_credentials "$PWD" 2>/dev/null || return 0
+  [ -n "$ROOKIE_RESOLVED_ENDPOINT" ] && [ -n "$ROOKIE_RESOLVED_TOKEN" ] || return 0
+  curl -sS --max-time 5 -X POST \
+    -H "Authorization: Bearer $ROOKIE_RESOLVED_TOKEN" -H "Content-Type: application/json" \
+    -H "x-rookie-hostname: $(hostname 2>/dev/null || echo unknown)" \
+    -H "x-rookie-surface: ${ROOKIE_SURFACE:-claude_code}" \
+    -d "{\"directive\":\"orphan_extract\",\"phase\":\"$phase\"}" \
+    -o /dev/null "$ROOKIE_RESOLVED_ENDPOINT/api/rookie/metric/directive" >/dev/null 2>&1 &
+  disown 2>/dev/null || true
+  return 0
+}
+
+# 차차가 tail 추출·저장 완료 표시. client_extracted marker + pending 큐에서 제거.
+orphan_mark_client_extracted() {
+  local sid="$1"
+  _orphan_is_uuid "$sid" || return 1
+  _orphan_write_marker "$(_orphan_client_extracted_dir)" "$sid" '{"status":"client_extracted"}' || return 1
+  rm -f "$(_orphan_pending_dir)/$sid.json" 2>/dev/null
+  _orphan_directive_metric "acted"   # B5 acted 계측 (fail-soft, 백그라운드)
+  return 0
+}
+
+# 처리 대기 목록(아직 client 추출 안 된 orphan 세션)을 1줄당 JSONL 로.
+# P0.1(P2-5): TSV 대신 JSONL `{sid,path,recovered_at,message_count}` — TSV 는 shell read 실수 유발.
+# client_extracted 된 stale pending 은 즉시 정리하고 skip. 깨진 marker 줄은 조용히 skip(fail-soft).
+orphan_pending_client_extraction() {
+  local d; d="$(_orphan_pending_dir)"
+  [ -d "$d" ] || return 0
+  local f sid
+  for f in "$d"/*.json; do
+    [ -f "$f" ] || continue
+    sid="${f##*/}"; sid="${sid%.json}"
+    _orphan_is_uuid "$sid" || continue
+    if orphan_is_client_extracted "$sid"; then rm -f "$f" 2>/dev/null; continue; fi
+    node -e 'try{const fs=require("fs");const j=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));process.stdout.write(JSON.stringify({sid:process.argv[2],path:j.transcript_path||"",recovered_at:j.recovered_at||"",message_count:j.message_count||0})+"\n");}catch{}' "$f" "$sid" 2>/dev/null
+  done
+}
+
+# P0.4 — tail 추출 큐(pending) 적재 가치 판정. 0=적재(record_pending), 1=low_value(skip).
+# 메시지 ≤3 그리고 본문에 운영사실 흔적(코드블록·SQL·URL·명령·포트·경로·tool)이 없을 때만 skip.
+# 짧아도 운영사실 있으면 적재. count-only 금지(doc P2-2). 파싱 실패는 보수적으로 적재(가치 간주).
+orphan_pending_is_worthwhile() {
+  local messages="$1" mc="${2:-0}"
+  [ "${mc:-0}" -gt 3 ] 2>/dev/null && return 0   # 메시지 많으면 무조건 가치
+  printf '%s' "$messages" | node -e '
+    let d=""; process.stdin.on("data",c=>d+=c).on("end",()=>{
+      try {
+        const a=JSON.parse(d);
+        const text=(Array.isArray(a)?a:[]).map(m=>typeof m.content==="string"?m.content:JSON.stringify(m.content||"")).join("\n");
+        // 운영사실 흔적 — 하나라도 있으면 적재 가치(exit 0).
+        const re=/```|\bSELECT\b|\bINSERT\b|\bUPDATE\b|\bCREATE\b|https?:\/\/|\bnpm\b|\bgit\b|\bcurl\b|\bssh\b|:\d{2,5}\b|\/[A-Za-z0-9_.\-]+\/[A-Za-z0-9_.\-]+|포트|배포|결정/i;
+        process.exit(re.test(text)?0:1);
+      } catch { process.exit(0); }   // 파싱 실패 → 보수적 적재
+    });
+  ' 2>/dev/null
+}
+
+# P0.4 — pending TTL(기본 3일)+ 미처리 → expired marker + pending 제거(삭제 아닌 감사 이동).
+# scanner 가 expired 를 제외하므로 만료 세션의 원본 transcript 재스캔도 막힌다.
+# TTL = ROOKIE_ORPHAN_PENDING_TTL_DAYS(기본 3). find -mtime +N 은 N*24h 초과 의미.
+orphan_prune_expired() {
+  local pdir; pdir="$(_orphan_pending_dir)"
+  [ -d "$pdir" ] || return 0
+  local ttl; ttl="${ROOKIE_ORPHAN_PENDING_TTL_DAYS:-3}"
+  local f sid
+  while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    sid="${f##*/}"; sid="${sid%.json}"
+    _orphan_is_uuid "$sid" || continue
+    orphan_mark_expired "$sid" && rm -f "$f" 2>/dev/null
+  done <<EOF
+$(find "$pdir" -maxdepth 1 -name '*.json' -type f -mtime +"$ttl" 2>/dev/null)
+EOF
+  return 0
+}
+
+# 현재 프로젝트 transcript 디렉토리에서 복구 후보 경로를 stdout 으로(1줄당 1개).
+# allowlist(regular·uuid·≤50MB·symlink제외) + marker 제외 + 현재 sid 제외 + 최근 보류
+#   + bootstrap(첫 도입: T창 안 최신 K개만, 나머지 baseline) / 정상(marker 없는 최신 K개).
+orphan_scan_candidates() {
+  local pdir="${ROOKIE_ORPHAN_PROJECT_DIR:-$HOME/.claude/projects/$(claude_project_dir_for_cwd "$PWD")}"
+  [ -d "$pdir" ] || return 0
+  local bootstrap=0
+  [ -d "$(_orphan_flushed_dir)" ] || bootstrap=1
+  node -e '
+    const fs=require("fs"), path=require("path");
+    const [pdir, orphanDir, holdS, Ts, Ks, maxBytes, cur, bootstrap, deferCapS] = process.argv.slice(1);
+    const now=Date.now()/1000, hold=+holdS, T=+Ts, K=+Ks, maxB=+maxBytes, isBoot=bootstrap==="1";
+    const flushedDir=path.join(orphanDir,"flushed"), baselineDir=path.join(orphanDir,"baseline");
+    const deferredDir=path.join(orphanDir,"deferred"), deferCap=+deferCapS;
+    // P0.4: low_value(짧은 세션)·expired(만료 pending) 도 후보 제외 — sweep 재진입 차단(§9-#4).
+    const lowValueDir=path.join(orphanDir,"low_value"), expiredDir=path.join(orphanDir,"expired");
+    // §3.2 scanner 는 flushed·baseline·유효 deferred 모두 후보 제외.
+    // 유효 deferred = fail_count≥cap(영구 보류) 또는 next_retry_at 미경과(backoff 창).
+    const deferBlocked=(sid)=>{ try{
+      const j=JSON.parse(fs.readFileSync(path.join(deferredDir,sid+".json"),"utf8"));
+      if((j.fail_count||0)>=deferCap) return true;
+      const nr=Date.parse(j.next_retry_at); return !isNaN(nr)&&nr/1000>now;
+    }catch{ return false; } };
+    const marked=(sid)=>fs.existsSync(path.join(flushedDir,sid+".json"))||fs.existsSync(path.join(baselineDir,sid+".json"))||fs.existsSync(path.join(lowValueDir,sid+".json"))||fs.existsSync(path.join(expiredDir,sid+".json"))||deferBlocked(sid);
+    const uuidRe=/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    const writeBaseline=(sid,reason)=>{ try{
+      fs.mkdirSync(baselineDir,{recursive:true,mode:0o700});
+      const tmp=path.join(baselineDir,"."+sid+".tmp");
+      fs.writeFileSync(tmp,JSON.stringify({status:"baseline_skipped",reason}),{mode:0o600});
+      fs.renameSync(tmp,path.join(baselineDir,sid+".json"));
+    }catch{} };
+    // self-reference(claude -p internal) transcript 는 진짜 세션이 아니다. cap 차지 전에
+    // scanner 단계에서 제외 + baseline 처리(P1) — 안 그러면 self-ref 최신 파일이 K개 cap 을
+    // 모두 먹어 실제 orphan 복구가 굶는다. 첫 user 메시지 선두 센티넬(신규) OR legacy 마커(하위호환).
+    // SSOT: src/lib/ai/internal-marker.ts. 전역 substring 폐기 — 본문 인용 false positive 차단(P1-4).
+    const SENT="[[ROOKIE_INTERNAL_INVOCATION::v1]]", LEG="the Rookie의 기억 정리 모듈";
+    const isSelfRef=(fp)=>{ try{
+      const raw=fs.readFileSync(fp,"utf8");
+      for(const l of raw.split("\n")){ if(!l.trim())continue;
+        let j; try{ j=JSON.parse(l); }catch{ continue; }
+        const m=j.message||j; if(m.role!=="user")continue;
+        const c=m.content;
+        const t=typeof c==="string"?c:Array.isArray(c)?((c.find(x=>x&&x.type==="text"&&typeof x.text==="string")||{}).text||""):"";
+        return t.replace(/^\s+/,"").startsWith(SENT)||t.includes(LEG);
+      }
+      return false;
+    }catch{ return false; } };
+    let entries=[];
+    let names=[]; try { names=fs.readdirSync(pdir); } catch { process.exit(0); }
+    for(const name of names){
+      if(!name.endsWith(".jsonl")) continue;
+      const sid=name.slice(0,-6);
+      if(!uuidRe.test(sid)) continue;
+      if(sid===cur) continue;
+      const fp=path.join(pdir,name);
+      let st; try{ st=fs.lstatSync(fp); }catch{ continue; }
+      if(!st.isFile()) continue;            // symlink/dir 제외
+      if(st.size>maxB) continue;
+      if((now-st.mtimeMs/1000)<hold) continue;  // 최근 수정 보류
+      if(marked(sid)) continue;
+      if(isSelfRef(fp)){ writeBaseline(sid,"self_reference"); continue; }  // P1: cap 차지 전 제외
+      entries.push({fp,sid,mtime:st.mtimeMs});
+    }
+    entries.sort((a,b)=>b.mtime-a.mtime);   // newest first
+    let pick;
+    if(isBoot){
+      const inWindow=entries.filter(e=>(now-e.mtime/1000)<=T);
+      pick=inWindow.slice(0,K);
+      const pickSet=new Set(pick.map(e=>e.sid));
+      for(const e of entries){
+        if(pickSet.has(e.sid)) continue;    // 자동 후보는 baseline 처리 안 함
+        writeBaseline(e.sid,"bootstrap_old");
+      }
+    } else {
+      pick=entries.slice(0,K);              // latency cap; 나머지는 다음 SessionStart 이월
+    }
+    for(const e of pick) process.stdout.write(e.fp+"\n");
+  ' "$pdir" "$ROOKIE_ORPHAN_DIR" "$ROOKIE_ORPHAN_AGE_HOLD" "$ROOKIE_ORPHAN_BOOTSTRAP_T" \
+    "$ROOKIE_ORPHAN_CAP" "$ROOKIE_ORPHAN_MAX_BYTES" "${ROOKIE_ORPHAN_CURRENT_SID:-}" "$bootstrap" \
+    "$ROOKIE_ORPHAN_DEFER_CAP" \
+    2>/dev/null
+}
+
+# ── telemetry / deferred backoff (§3.4) ─────────────────────────────
+# 모든 로그·deferred 는 stdout 미사용(§3.7) — recovery.log / deferred subdir 로만.
+_orphan_log_telemetry() {
+  local sid="$1" msg="$2"
+  _orphan_dir_init "$ROOKIE_ORPHAN_DIR"
+  printf '%s sid=%s %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$sid" "$msg" \
+    >> "$(_orphan_log)" 2>/dev/null || true
+  chmod 600 "$(_orphan_log)" 2>/dev/null || true
+}
+
+_orphan_deferred_path() { printf '%s/%s.json' "$(_orphan_deferred_dir)" "$1"; }
+
+# deferred 가 유효(영구 보류 or backoff 창)면 exit 0 → recovery 건너뜀.
+_orphan_deferred_blocked() {
+  local sid="$1" f
+  f="$(_orphan_deferred_path "$sid")"
+  [ -f "$f" ] || return 1
+  node -e '
+    const fs=require("fs");
+    try{
+      const j=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));
+      const cap=+process.argv[2], now=Date.now()/1000;
+      if((j.fail_count||0)>=cap) process.exit(0);
+      const nr=Date.parse(j.next_retry_at);
+      process.exit(!isNaN(nr)&&nr/1000>now ? 0 : 1);
+    }catch{ process.exit(1); }
+  ' "$f" "${ROOKIE_ORPHAN_DEFER_CAP:-3}" 2>/dev/null
+}
+
+# marker write 실패 시 fail_count++ + next_retry_at(6h*fail_count) 기록. 원자적 tmp+mv.
+_orphan_record_deferred() {
+  local sid="$1" err="$2" dir tmp f
+  _orphan_is_uuid "$sid" || return 1
+  dir="$(_orphan_deferred_dir)"
+  _orphan_dir_init "$dir"
+  f="$dir/$sid.json"
+  tmp="$(mktemp "$dir/.tmp.XXXXXX" 2>/dev/null)" || return 1
+  ROOKIE_DEFER_ERR="$err" node -e '
+    const fs=require("fs");
+    const f=process.argv[1], tmp=process.argv[2];
+    let prev={fail_count:0};
+    try{ prev=JSON.parse(fs.readFileSync(f,"utf8")); }catch{}
+    const fc=(prev.fail_count||0)+1;
+    const next=new Date(Date.now()+fc*21600*1000).toISOString();  // 6h * fail_count
+    fs.writeFileSync(tmp,JSON.stringify({fail_count:fc,next_retry_at:next,last_error:process.env.ROOKIE_DEFER_ERR||""}),{mode:0o600});
+  ' "$f" "$tmp" 2>/dev/null || { rm -f "$tmp"; return 1; }
+  chmod 600 "$tmp" 2>/dev/null
+  mv -f "$tmp" "$f" 2>/dev/null || { rm -f "$tmp"; return 1; }
+  return 0
+}
+
+_orphan_clear_deferred() {
+  local sid="$1"
+  _orphan_is_uuid "$sid" || return 0   # 비-UUID 면 rm 자체를 안 함 (traversal 차단)
+  rm -f "$(_orphan_deferred_path "$sid")" 2>/dev/null
+  return 0
+}
+
+# transcript messages JSON 의 배열 길이.
+_orphan_messages_count() {
+  printf '%s' "$1" | node -e '
+    let d=""; process.stdin.on("data",c=>d+=c).on("end",()=>{
+      try{ const a=JSON.parse(d); process.stdout.write(String(Array.isArray(a)?a.length:0)); }
+      catch{ process.stdout.write("0"); }
+    });
+  ' 2>/dev/null || printf '0'
+}
+
+# ── orphan_recover (§3.1·§3.6) ──────────────────────────────────────
+# scan → 각 candidate 를 기존 flush-session 으로 재전송 → content-bearing 성공 시 flushed marker.
+# stdout 미사용(§3.7). 복구 건수는 전역 ROOKIE_ORPHAN_RECOVERED_COUNT.
+# 의존: lib/transcript.sh (source 선행 필요).
+orphan_recover() {
+  local endpoint="$1" token="$2" user_id="$3"
+  ROOKIE_ORPHAN_RECOVERED_COUNT=0
+  [ -n "$endpoint" ] && [ -n "$token" ] || return 0
+  command -v transcript_messages_json >/dev/null 2>&1 || return 0
+
+  local deadline
+  deadline=$(( $(date +%s) + ${ROOKIE_ORPHAN_TIME_BUDGET:-8} ))
+
+  # 이슈② 재발 차단: repo 를 실행 셸 $PWD 로 고정하지 않는다. 후보 transcript 마다 실제 cwd 로
+  # 역산(while 루프 안). $PWD 폴백 절대 금지 — sweep_all 이 the-rookie 본진에서 전 프로젝트를
+  # 순회하므로 $PWD 고정이면 모든 회수분이 the-rookie 로 흡수된다(인시던트 §5.5).
+  local host repo_url repo_path
+  host="$(hostname)"
+
+  local candidates
+  candidates="$(orphan_scan_candidates)" || return 0
+  [ -n "$candidates" ] || return 0
+
+  local fp sid messages mc msg_file body_file code
+  while IFS= read -r fp; do
+    [ -n "$fp" ] || continue
+    [ "$(date +%s)" -ge "$deadline" ] && break          # §3.6 latency budget
+
+    sid="$(transcript_session_id_from_path "$fp")"
+    [ -n "$sid" ] || continue
+    _orphan_deferred_blocked "$sid" && continue          # backoff 보류 (scanner 이중 안전)
+
+    if transcript_has_self_reference "$fp"; then          # §3.4 self-ref 오판 차단
+      _orphan_log_telemetry "$sid" "skip_self_reference"; continue
+    fi
+
+    # 이슈② repo 역산 — 후보 transcript 의 실제 cwd. ⚠️ $PWD 폴백 절대 금지.
+    repo_path="$(transcript_claude_cwd "$fp")"
+
+    # B6-4 (spec 2026-07-11 §B6): cwd 불명 orphan 은 보류 — 어느 config 소속인지 판별 불가한
+    # 것을 현재 config 로 flush 하지 않는다(오귀속 방지). marker 를 안 남기므로 다음 기회에 재시도.
+    if [ -z "$repo_path" ]; then
+      _orphan_log_telemetry "$sid" "skip_unknown_cwd"; continue
+    fi
+    # B6-4 (codex R1 P1-2): cwd 디렉토리가 삭제·이동됐으면 판별 불가로 보류 — 로컬 config 를 못
+    # 찾는다는 이유로 전역 계정에 폴백 flush 하면 테스트 폴더 삭제 순간 본체로 오귀속된다.
+    if [ ! -d "$repo_path" ]; then
+      _orphan_log_telemetry "$sid" "skip_missing_cwd_dir"; continue
+    fi
+    # B6-4 partition: 후보 cwd 기준 유효 config(로컬>전역)가 현재 실행 config 와 다르면 skip —
+    # 그 config 의 sweep 몫으로 남긴다(테스트↔본체 계정 교차 전송 차단).
+    if command -v rookie_config_path_for_cwd >/dev/null 2>&1 && [ -n "${ROOKIE_ACTIVE_CONFIG:-}" ]; then
+      if [ "$(rookie_config_path_for_cwd "$repo_path")" != "$ROOKIE_ACTIVE_CONFIG" ]; then
+        _orphan_log_telemetry "$sid" "skip_other_config"; continue
+      fi
+    fi
+    # B6-3 (codex R1 P1-1): 세션 identity pin 이 있고 현재 토큰과 다르면 보류 — Stop flush 를
+    # 막아도 orphan/sweep 이 새 계정 토큰으로 재전송하면 같은 오귀속. pin 주인 계정으로 다시
+    # 로그인되면 그때 회수된다(pin TTL 14일 = pending prune 과 동일 감각).
+    if command -v identity_pin_check >/dev/null 2>&1 && ! identity_pin_check "$sid" "$token"; then
+      _orphan_log_telemetry "$sid" "skip_identity_mismatch"; continue
+    fi
+
+    repo_url="$(git -C "$repo_path" remote get-url origin 2>/dev/null || echo "")"
+
+    messages="$(transcript_messages_json "$fp")"
+    mc="$(_orphan_messages_count "$messages")"
+    if [ "${mc:-0}" -le 0 ] 2>/dev/null; then            # §3.2 messages 0 → POST 생략
+      _orphan_log_telemetry "$sid" "skip_empty_messages"; continue
+    fi
+
+    # P3: messages 를 env/argv 가 아닌 임시 파일로 전달 — 큰 transcript(긴 content)에서
+    # ARG_MAX/env 한계로 body build·POST 가 깨지는 것 방지. curl 도 -d @file 로 송신.
+    msg_file="$(mktemp 2>/dev/null)" || continue
+    printf '%s' "$messages" > "$msg_file" 2>/dev/null
+    body_file="$(mktemp 2>/dev/null)" || { rm -f "$msg_file"; continue; }
+    node -e '
+      const fs=require("fs");
+      const b={session_id:process.argv[1],hostname:process.argv[2],repo_path:process.argv[4],transcript_path:process.argv[5]};
+      if(process.argv[3]) b.repo_url=process.argv[3];
+      try{ const m=JSON.parse(fs.readFileSync(process.argv[6],"utf8")||"[]"); if(Array.isArray(m)&&m.length) b.messages=m; }catch{}
+      process.stdout.write(JSON.stringify(b));
+    ' "$sid" "$host" "$repo_url" "$repo_path" "$fp" "$msg_file" > "$body_file" 2>/dev/null
+    rm -f "$msg_file"
+    if [ ! -s "$body_file" ]; then
+      rm -f "$body_file"; _orphan_log_telemetry "$sid" "skip_body_build"; continue
+    fi
+
+    code="$(curl -sS --max-time 10 -X POST \
+      -H "Authorization: Bearer $token" -H "Content-Type: application/json" \
+      -H "x-rookie-user-id: $user_id" --data-binary @"$body_file" \
+      -o /dev/null -w "%{http_code}" \
+      "$endpoint/api/rookie/flush-session" 2>/dev/null)" || code="000"
+    rm -f "$body_file"
+
+    # P0.4 Step 4 (codex #10): marker 조건 = code 200 + message_count>0 (chunks_inserted 무관).
+    # mc 는 line "skip_empty_messages" 게이트로 이미 >0 보장. 멱등 재전송(chunks 0)도 marker 박아
+    # 복구 가능 세션이 영구 재시도되지 않게 한다. transcript 파싱 실패·빈 본문은 그 게이트가 차단.
+    if [ "$code" = "200" ] && [ "${mc:-0}" -gt 0 ] 2>/dev/null; then
+      if orphan_mark_flushed "$sid" "orphan" "$mc"; then
+        _orphan_clear_deferred "$sid"
+        # Phase 2: chunk 복구는 끝 — fact tail 큐 등록. 단 P0.4 Step 1: 짧고 내용 없는 세션은
+        # 큐에 안 올리고 low_value marker(차차 추출 작업 굶기지 않게). 운영사실 있으면 적재.
+        if orphan_pending_is_worthwhile "$messages" "$mc"; then
+          orphan_record_pending "$sid" "$fp" "$mc" || true
+        else
+          orphan_mark_low_value "$sid" "short_no_content" "$mc" || true
+        fi
+        ROOKIE_ORPHAN_RECOVERED_COUNT=$((ROOKIE_ORPHAN_RECOVERED_COUNT + 1))
+      else
+        # 전송은 멱등이라 데이터 안전 — marker write 실패만 backoff (§3.4).
+        _orphan_record_deferred "$sid" "marker_write_failed"
+        _orphan_log_telemetry "$sid" "marker_write_failed"
+      fi
+    else
+      _orphan_log_telemetry "$sid" "flush_failed code=$code mc=$mc"
+    fi
+  done <<EOF
+$candidates
+EOF
+  return 0
+}