claude-controller 0.2.0 → 0.3.0

package/cognitive/prompts/analyst.md

@@ -0,0 +1,31 @@
+당신은 코드베이스 분석 전문 에이전트입니다. 코드를 읽기만 하고, 수정하지 않습니다.
+
+## 분석 관점
+
+1. **구조 파악**: 디렉토리 구조, 모듈 간 의존성, 진입점
+2. **영향 범위**: 특정 변경이 어떤 파일/함수에 영향을 미치는지
+3. **기술 부채**: 중복 코드, 미사용 코드, 과도한 복잡도
+4. **패턴 식별**: 프로젝트에서 사용하는 디자인 패턴, 코딩 관례
+
+## 출력 형식
+
+```json
+{
+  "summary": "분석 요약 (3문장 이내)",
+  "findings": [
+    {
+      "category": "structure|dependency|tech_debt|pattern|risk",
+      "description": "발견 내용",
+      "files": ["관련 파일"],
+      "impact": "high|medium|low"
+    }
+  ],
+  "recommendations": ["구체적 권고사항"]
+}
+```
+
+## 원칙
+
+- 추측하지 않는다 — 코드에서 확인된 사실만 보고한다
+- 파일 경로와 줄 번호를 포함한다
+- 코드를 수정하지 않는다 (읽기 전용)

package/cognitive/prompts/coder.md

@@ -0,0 +1,22 @@
+당신은 소프트웨어 개발 전문 에이전트입니다.
+
+## 원칙
+
+1. **최소 변경**: 요청된 부분만 정확히 수정. 관련 없는 코드를 건드리지 않는다.
+2. **테스트 포함**: 코드 변경 시 해당 변경을 검증하는 테스트를 함께 작성한다.
+3. **기존 관례 준수**: 프로젝트의 코딩 스타일, 네이밍, 구조를 따른다.
+4. **안전한 코드**: OWASP Top 10 취약점을 도입하지 않는다.
+
+## 작업 방식
+
+1. 먼저 관련 파일을 읽고 구조를 파악한다
+2. 영향 범위를 확인한다 (이 함수를 누가 호출하는지, 타입이 바뀌면 어디가 깨지는지)
+3. 변경을 수행한다
+4. 변경이 올바른지 테스트로 확인한다
+
+## 출력
+
+작업 완료 후 변경 요약을 간결하게 작성한다:
+- 변경한 파일 목록
+- 각 변경의 이유 (한 줄)
+- 주의사항 (있을 경우)

package/cognitive/prompts/reviewer.md

@@ -0,0 +1,33 @@
+당신은 시니어 코드 리뷰어입니다.
+
+## 리뷰 관점
+
+1. **정확성**: 로직이 의도대로 동작하는가?
+2. **보안**: 인젝션, XSS, 인증 우회 등 취약점은 없는가?
+3. **성능**: 불필요한 연산, N+1 쿼리, 메모리 누수는 없는가?
+4. **가독성**: 코드가 자명한가? 불필요한 복잡도는 없는가?
+5. **테스트**: 핵심 경로와 엣지 케이스가 테스트되었는가?
+
+## 출력 형식
+
+```json
+{
+  "verdict": "approve" | "request_changes",
+  "issues": [
+    {
+      "severity": "critical" | "major" | "minor" | "nit",
+      "file": "파일 경로",
+      "line": 42,
+      "description": "문제 설명",
+      "suggestion": "구체적 개선 제안"
+    }
+  ],
+  "summary": "전반적 평가 (2-3문장)"
+}
+```
+
+## 원칙
+
+- critical/major 이슈가 하나라도 있으면 반드시 request_changes
+- 구체적인 코드 제안을 포함한다 (추상적 조언 금지)
+- 잘된 부분도 언급한다

package/cognitive/prompts/tester.md

@@ -0,0 +1,21 @@
+당신은 QA/테스트 전문 에이전트입니다.
+
+## 원칙
+
+1. **엣지 케이스 우선**: 정상 경로보다 경계값, 빈 입력, 동시성 문제를 집중 테스트
+2. **독립성**: 각 테스트는 다른 테스트에 의존하지 않아야 한다
+3. **빠른 실행**: 불필요한 I/O, sleep, 네트워크 호출을 피한다
+4. **명확한 실패 메시지**: 테스트 실패 시 원인을 바로 알 수 있는 assert 메시지
+
+## 작업 방식
+
+1. 대상 코드를 읽고 입/출력, 사이드이펙트를 파악
+2. 테스트 케이스 목록을 설계 (정상, 경계, 에러, 동시성)
+3. 테스트를 작성하고 실행
+4. 실패하는 테스트가 있으면 원인을 분석하여 보고
+
+## 출력
+
+- 작성한 테스트 파일 경로
+- 테스트 실행 결과 요약
+- 커버리지 정보 (측정 가능한 경우)

package/cognitive/prompts/writer.md

@@ -0,0 +1,25 @@
+당신은 기술 문서 작성 전문 에이전트입니다.
+
+## 원칙
+
+1. **코드 기반 정확성**: 코드를 직접 읽고 동작을 확인한 내용만 문서화
+2. **실행 가능한 예제**: 모든 코드 예제는 실제로 동작해야 한다
+3. **대상 독자 고려**: 문서의 대상 독자 수준에 맞춰 작성
+4. **최신성**: 현재 코드 상태를 반영하여 작성
+
+## 문서 유형별 구조
+
+### API 문서
+- 엔드포인트, 메서드, 요청/응답 스키마, 에러 코드, 예제
+
+### 가이드
+- 개요, 사전 요구사항, 단계별 설명, 문제 해결(FAQ)
+
+### 아키텍처 문서
+- 전체 구조, 컴포넌트 역할, 데이터 흐름, 설계 결정과 이유
+
+## 원칙
+
+- 존재하지 않는 기능이나 파라미터를 만들어내지 않는다
+- 코드를 먼저 읽고 문서를 작성한다
+- 마크다운 형식을 사용한다

package/config.sh

@@ -33,6 +33,9 @@ PID_FILE="${CONTROLLER_DIR}/service/controller.pid"
 # 최대 동시 백그라운드 작업 수
 MAX_BACKGROUND_JOBS="${MAX_BACKGROUND_JOBS:-10}"
 
+# 완료/실패 작업 파일 보존 기간 (일) — 이 기간이 지난 job_*.out/.meta 자동 삭제
+LOG_RETENTION_DAYS="${LOG_RETENTION_DAYS:-30}"
+
 # 시스템 프롬프트 추가
 APPEND_SYSTEM_PROMPT="${APPEND_SYSTEM_PROMPT:-}"
 
@@ -51,7 +54,8 @@ WORKTREES_DIR="${CONTROLLER_DIR}/worktrees"
 
 # ── 권한 설정 ──────────────────────────────────────────────
 # true로 설정 시 --dangerously-skip-permissions 사용 (모든 도구 무제한 허용)
-SKIP_PERMISSIONS="${SKIP_PERMISSIONS:-true}"
+# 보안상 기본값은 false — 필요 시 환경변수 또는 settings.json에서 명시적으로 활성화
+SKIP_PERMISSIONS="${SKIP_PERMISSIONS:-false}"
 
 # ── Checkpoint 설정 ────────────────────────────────────────
 # 체크포인트 감시 주기 (초) — 이 간격으로 worktree 변경을 확인
@@ -70,5 +74,6 @@ if [[ -f "$SETTINGS_FILE" ]] && command -v jq &>/dev/null; then
   _v=$(_s '.target_repo');            [[ -n "$_v" ]] && TARGET_REPO="$_v"
   _v=$(_s '.base_branch');            [[ -n "$_v" ]] && BASE_BRANCH="$_v"
   _v=$(_s '.checkpoint_interval');    [[ -n "$_v" ]] && CHECKPOINT_INTERVAL="$_v"
+  _v=$(_s '.log_retention_days');     [[ -n "$_v" ]] && LOG_RETENTION_DAYS="$_v"
   unset -f _s; unset _v
 fi

package/dag/__init__.py

@@ -0,0 +1,5 @@
+"""DAG — 태스크 의존성 그래프 엔진."""
+
+from dag.graph import TaskDAG, TaskNode
+
+__all__ = ["TaskDAG", "TaskNode"]

package/dag/graph.py

@@ -0,0 +1,222 @@
+"""
+DAG (Directed Acyclic Graph) — 태스크 의존성 그래프
+Planner가 생성한 태스크들의 선행/후행 관계를 관리하고,
+토폴로지 정렬 기반으로 실행 순서를 결정한다.
+"""
+
+from collections import defaultdict, deque
+from typing import Optional
+
+
+class TaskNode:
+    """DAG 내 개별 태스크 노드."""
+
+    __slots__ = (
+        "id", "name", "worker_type", "prompt", "depends_on",
+        "status", "cost_usd", "duration_ms", "result", "retries",
+    )
+
+    def __init__(
+        self,
+        task_id: str,
+        name: str,
+        worker_type: str,
+        prompt: str,
+        depends_on: Optional[list[str]] = None,
+    ):
+        self.id = task_id
+        self.name = name
+        self.worker_type = worker_type  # coder, reviewer, tester, analyst, writer
+        self.prompt = prompt
+        self.depends_on = depends_on or []
+        self.status = "pending"         # pending, running, completed, failed
+        self.cost_usd = 0.0
+        self.duration_ms = 0
+        self.result = None
+        self.retries = 0
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "worker_type": self.worker_type,
+            "prompt": self.prompt,
+            "depends_on": self.depends_on,
+            "status": self.status,
+            "cost_usd": self.cost_usd,
+            "duration_ms": self.duration_ms,
+            "retries": self.retries,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "TaskNode":
+        node = cls(
+            task_id=d["id"],
+            name=d["name"],
+            worker_type=d["worker_type"],
+            prompt=d["prompt"],
+            depends_on=d.get("depends_on", []),
+        )
+        node.status = d.get("status", "pending")
+        node.cost_usd = d.get("cost_usd", 0.0)
+        node.duration_ms = d.get("duration_ms", 0)
+        node.retries = d.get("retries", 0)
+        return node
+
+
+class TaskDAG:
+    """태스크 방향성 비순환 그래프.
+
+    핵심 기능:
+    - 토폴로지 정렬: 실행 순서 결정
+    - 실행 가능 태스크: 의존성이 모두 완료된 태스크 반환
+    - 병렬 그룹: 동시 실행 가능한 태스크 집합 반환
+    - 순환 감지: DAG 유효성 검증
+    """
+
+    def __init__(self):
+        self.nodes: dict[str, TaskNode] = {}
+        self._adj: dict[str, list[str]] = defaultdict(list)    # 정방향 간선
+        self._rev: dict[str, list[str]] = defaultdict(list)    # 역방향 간선
+
+    def add_task(self, node: TaskNode):
+        """태스크를 DAG에 추가한다."""
+        self.nodes[node.id] = node
+        for dep in node.depends_on:
+            self._adj[dep].append(node.id)
+            self._rev[node.id].append(dep)
+
+    def validate(self) -> tuple[bool, str]:
+        """DAG의 유효성을 검증한다 (순환 감지, 누락 의존성)."""
+        # 누락된 의존성 확인
+        for node in self.nodes.values():
+            for dep in node.depends_on:
+                if dep not in self.nodes:
+                    return False, f"Task '{node.id}' depends on unknown task '{dep}'"
+
+        # 순환 감지 (Kahn's algorithm)
+        in_degree = {nid: 0 for nid in self.nodes}
+        for nid, node in self.nodes.items():
+            for dep in node.depends_on:
+                in_degree[nid] += 1  # 아닌, 이미 위에서 계산
+
+        # 재계산
+        in_degree = {nid: len(self._rev.get(nid, [])) for nid in self.nodes}
+        queue = deque(nid for nid, deg in in_degree.items() if deg == 0)
+        visited = 0
+
+        while queue:
+            nid = queue.popleft()
+            visited += 1
+            for child in self._adj.get(nid, []):
+                in_degree[child] -= 1
+                if in_degree[child] == 0:
+                    queue.append(child)
+
+        if visited != len(self.nodes):
+            return False, "Cycle detected in task DAG"
+        return True, "OK"
+
+    def topological_sort(self) -> list[str]:
+        """토폴로지 정렬 순서를 반환한다."""
+        in_degree = {nid: len(self._rev.get(nid, [])) for nid in self.nodes}
+        queue = deque(
+            sorted(nid for nid, deg in in_degree.items() if deg == 0)
+        )
+        order = []
+
+        while queue:
+            nid = queue.popleft()
+            order.append(nid)
+            for child in sorted(self._adj.get(nid, [])):
+                in_degree[child] -= 1
+                if in_degree[child] == 0:
+                    queue.append(child)
+
+        return order
+
+    def get_ready_tasks(self) -> list[TaskNode]:
+        """현재 실행 가능한 태스크들을 반환한다 (의존성 충족 + pending 상태)."""
+        ready = []
+        for node in self.nodes.values():
+            if node.status != "pending":
+                continue
+            deps_met = all(
+                self.nodes[d].status == "completed"
+                for d in node.depends_on
+                if d in self.nodes
+            )
+            if deps_met:
+                ready.append(node)
+        return ready
+
+    def get_parallel_groups(self) -> list[list[str]]:
+        """병렬 실행 가능한 태스크 그룹을 계층별로 반환한다.
+
+        Returns:
+            [[t1, t2], [t3, t4, t5], [t6]] — 같은 리스트 내 태스크는 동시 실행 가능
+        """
+        in_degree = {nid: len(self._rev.get(nid, [])) for nid in self.nodes}
+        groups = []
+        remaining = set(self.nodes.keys())
+
+        while remaining:
+            # in-degree가 0인 노드 = 현재 레벨에서 실행 가능
+            level = [nid for nid in remaining if in_degree.get(nid, 0) == 0]
+            if not level:
+                break  # 순환이 있으면 중단 (validate에서 이미 검사)
+            groups.append(sorted(level))
+            for nid in level:
+                remaining.discard(nid)
+                for child in self._adj.get(nid, []):
+                    in_degree[child] -= 1
+
+        return groups
+
+    def is_complete(self) -> bool:
+        """모든 태스크가 완료되었는지 확인한다."""
+        return all(n.status == "completed" for n in self.nodes.values())
+
+    def has_failures(self) -> bool:
+        """실패한 태스크가 있는지 확인한다."""
+        return any(n.status == "failed" for n in self.nodes.values())
+
+    def to_dict(self) -> dict:
+        """DAG를 직렬화한다."""
+        return {
+            "tasks": [node.to_dict() for node in self.nodes.values()],
+            "parallel_groups": self.get_parallel_groups(),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "TaskDAG":
+        """직렬화된 DAG를 복원한다."""
+        dag = cls()
+        for td in data.get("tasks", []):
+            dag.add_task(TaskNode.from_dict(td))
+        return dag
+
+    def to_mermaid(self) -> str:
+        """DAG를 Mermaid 다이어그램 문법으로 변환한다 (UI 시각화용)."""
+        lines = ["graph TD"]
+        status_style = {
+            "pending": ":::pending",
+            "running": ":::running",
+            "completed": ":::completed",
+            "failed": ":::failed",
+        }
+        for node in self.nodes.values():
+            label = f'{node.id}["{node.name}<br/>{node.worker_type}"]'
+            style = status_style.get(node.status, "")
+            lines.append(f"    {label}{style}")
+        for node in self.nodes.values():
+            for dep in node.depends_on:
+                lines.append(f"    {dep} --> {node.id}")
+        # 스타일 정의
+        lines.extend([
+            "    classDef pending fill:#e2e8f0,stroke:#94a3b8",
+            "    classDef running fill:#bfdbfe,stroke:#3b82f6",
+            "    classDef completed fill:#bbf7d0,stroke:#22c55e",
+            "    classDef failed fill:#fecaca,stroke:#ef4444",
+        ])
+        return "\n".join(lines)

package/lib/jobs.sh

@@ -66,7 +66,7 @@ job_register() {
   local meta_file="${LOGS_DIR}/job_${job_id}.meta"
   # 프롬프트 내의 특수문자를 이스케이프하여 안전하게 저장
   local safe_prompt
-  safe_prompt=$(printf '%s' "$prompt" | head -c 500 | sed "s/'/'\\\\''/g")
+  safe_prompt=$(printf '%s' "$prompt" | head -c 500 | tr -d '\000-\037\177' | sed "s/'/'\\\\''/g")
   cat > "$meta_file" <<EOF
 JOB_ID=${job_id}
 STATUS=running
@@ -105,12 +105,23 @@ job_mark_done() {
   local job_id="$1"
   local meta_file="${LOGS_DIR}/job_${job_id}.meta"
   _meta_set_field "$meta_file" "STATUS" "done"
+  _fire_webhook "$job_id" "done"
 }
 
 job_mark_failed() {
   local job_id="$1"
   local meta_file="${LOGS_DIR}/job_${job_id}.meta"
   _meta_set_field "$meta_file" "STATUS" "failed"
+  _fire_webhook "$job_id" "failed"
+}
+
+# ── 웹훅 전달 (백그라운드) ─────────────────────────────────
+_fire_webhook() {
+  local job_id="$1" status="$2"
+  local webhook_script="${CONTROLLER_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/web/webhook.py"
+  [[ -f "$webhook_script" ]] || return 0
+  # 백그라운드에서 실행 — 작업 완료 흐름을 차단하지 않는다
+  python3 "$webhook_script" "$job_id" "$status" &>/dev/null &
 }
 
 # ── 상태 조회 ──────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-controller",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Claude Code headless daemon controller — FIFO-based async task dispatch, Git Worktree isolation, auto-checkpointing, and a web dashboard",
   "license": "MIT",
   "author": "choiwon",
@@ -29,8 +29,12 @@
     "bin/app-launcher.sh",
     "bin/ctl",
     "bin/native-app.py",
+    "bin/autoloop.sh",
+    "bin/watchdog.sh",
     "lib/",
     "service/controller.sh",
+    "cognitive/",
+    "dag/",
     "web/*.py",
     "web/static/*.html",
     "web/static/*.js",

package/postinstall.sh

@@ -66,7 +66,7 @@ SETTINGS_FILE="${CONTROLLER_DIR}/data/settings.json"
 if [[ ! -f "$SETTINGS_FILE" ]]; then
   cat > "$SETTINGS_FILE" << 'SETTINGS'
 {
-  "skip_permissions": true,
+  "skip_permissions": false,
   "allowed_tools": "Bash,Read,Write,Edit,Glob,Grep,Agent,NotebookEdit,WebFetch,WebSearch",
   "model": "",
   "max_jobs": 10,

package/service/controller.sh

@@ -86,6 +86,13 @@ _on_signal() {
 
 trap _on_signal SIGTERM SIGINT SIGHUP
 
+# ── meta 파일 인젝션 방지 ─────────────────────────────────────
+# 개행·제어문자를 제거하여 KEY=VALUE 라인 인젝션을 방지한다.
+# Python 측 _sanitize_meta_value()와 동일한 역할.
+_sanitize_meta_val() {
+  printf '%s' "$1" | tr -d '\000-\037\177'
+}
+
 # ── 중복 디스패치 방지 ────────────────────────────────────────
 # 최근 디스패치된 프롬프트 해시와 타임스탬프를 기록
 _LAST_DISPATCH_HASH=""
@@ -161,16 +168,40 @@ dispatch_job() {
     return 1
   fi
 
-  # Job 등록
-  local job_id
-  job_id=$(job_register "$prompt")
+  # ── pending 작업 재사용 (DAG 의존성 디스패치) ──
+  local pending_jid
+  pending_jid=$(echo "$json_line" | jq -r '.pending_job_id // empty')
+
+  local job_id meta_file out_file
+  # 사용자 입력값 새니타이즈 (meta 파일 인젝션 방지)
+  job_uuid=$(_sanitize_meta_val "$job_uuid")
+  cwd=$(_sanitize_meta_val "$cwd")
+
+  if [[ -n "$pending_jid" ]]; then
+    local pending_meta="${LOGS_DIR}/job_${pending_jid}.meta"
+    if [[ -f "$pending_meta" ]]; then
+      job_id="$pending_jid"
+      meta_file="$pending_meta"
+      _meta_set_field "$meta_file" "STATUS" "running"
+      rm -f "${LOGS_DIR}/job_${pending_jid}.pending"
+      _log_info "Pending Job #${job_id} 디스패치 (DAG 의존성 충족)"
+    else
+      job_id=$(job_register "$prompt")
+      meta_file="${LOGS_DIR}/job_${job_id}.meta"
+      local _tmp="${meta_file}.tmp.$$"
+      { cat "$meta_file"; echo "UUID=${job_uuid}"; } > "$_tmp" && mv -f "$_tmp" "$meta_file"
+    fi
+  else
+    # Job 등록
+    job_id=$(job_register "$prompt")
+    meta_file="${LOGS_DIR}/job_${job_id}.meta"
 
-  local out_file="${LOGS_DIR}/job_${job_id}.out"
-  local meta_file="${LOGS_DIR}/job_${job_id}.meta"
+    # .meta 파일에 UUID 기록 (원자적 append: temp → rename)
+    local _tmp="${meta_file}.tmp.$$"
+    { cat "$meta_file"; echo "UUID=${job_uuid}"; } > "$_tmp" && mv -f "$_tmp" "$meta_file"
+  fi
 
-  # .meta 파일에 UUID 기록 (원자적 append: temp → rename)
-  local _tmp="${meta_file}.tmp.$$"
-  { cat "$meta_file"; echo "UUID=${job_uuid}"; } > "$_tmp" && mv -f "$_tmp" "$meta_file"
+  out_file="${LOGS_DIR}/job_${job_id}.out"
 
   # ── Worktree 결정: 재사용(rewind) > 새로 생성 ──
   local wt_path=""
@@ -406,11 +437,12 @@ start_service() {
 
   # FIFO 생성
   if [[ -p "$FIFO_PATH" ]]; then
-    _log_warn "기존 FIFO 파이프 발견. 재사용합니다: ${FIFO_PATH}"
+    chmod 600 "$FIFO_PATH"
+    _log_warn "기존 FIFO 파이프 발견. 권한 확인 후 재사용합니다: ${FIFO_PATH}"
   else
     rm -f "$FIFO_PATH"
-    mkfifo "$FIFO_PATH"
-    _log_info "FIFO 파이프 생성됨: ${FIFO_PATH}"
+    mkfifo -m 600 "$FIFO_PATH"
+    _log_info "FIFO 파이프 생성됨 (mode 600): ${FIFO_PATH}"
   fi
 
   # PID 기록

package/web/audit.py

@@ -0,0 +1,122 @@
+"""
+감사 로그 — 모든 API 호출을 타임스탬프·IP와 함께 기록하고 조회 API를 제공한다.
+
+저장 형식: JSONL (한 줄에 하나의 JSON 객체)
+저장 위치: data/audit.log
+필드: ts, time, method, path, ip, status, duration_ms
+"""
+
+import json
+import time
+from config import DATA_DIR
+
+AUDIT_LOG_FILE = DATA_DIR / "audit.log"
+_ROTATED_FILE = DATA_DIR / "audit.log.1"
+
+# 최대 로그 파일 크기 (10 MB) — 초과 시 .1로 로테이션
+MAX_AUDIT_SIZE = 10 * 1024 * 1024
+
+# 기록 제외 경로 (정적 파일, 페이지 요청)
+_EXCLUDE_PREFIXES = ("/static/", "/uploads/")
+_EXCLUDE_PATHS = {"/", "/index.html", "/favicon.ico"}
+
+
+def log_api_call(method, path, client_ip, status, duration_ms):
+    """API 호출 한 건을 감사 로그에 기록한다.
+
+    정적 파일 요청과 페이지 로드는 제외되며, /api/ 경로만 기록된다.
+    POSIX O_APPEND 모드의 원자적 쓰기를 활용하여 ThreadingHTTPServer에서 안전하다.
+    """
+    if path in _EXCLUDE_PATHS:
+        return
+    for prefix in _EXCLUDE_PREFIXES:
+        if path.startswith(prefix):
+            return
+
+    entry = {
+        "ts": time.time(),
+        "time": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+        "method": method,
+        "path": path,
+        "ip": client_ip,
+        "status": status,
+        "duration_ms": round(duration_ms, 1),
+    }
+
+    try:
+        DATA_DIR.mkdir(parents=True, exist_ok=True)
+        # 크기 기반 로테이션: 최대 1세대만 유지
+        if AUDIT_LOG_FILE.exists():
+            try:
+                if AUDIT_LOG_FILE.stat().st_size > MAX_AUDIT_SIZE:
+                    AUDIT_LOG_FILE.rename(_ROTATED_FILE)
+            except OSError:
+                pass
+        with open(AUDIT_LOG_FILE, "a", encoding="utf-8") as f:
+            f.write(json.dumps(entry, ensure_ascii=False) + "\n")
+    except OSError:
+        pass
+
+
+def search_audit(from_ts=None, to_ts=None, method=None, path_contains=None,
+                 ip=None, status=None, limit=100, offset=0):
+    """감사 로그를 조건에 맞게 검색한다.
+
+    Args:
+        from_ts: 시작 시간 (Unix timestamp)
+        to_ts: 끝 시간 (Unix timestamp)
+        method: HTTP 메서드 필터 (GET, POST, DELETE)
+        path_contains: 경로 부분 문자열 필터
+        ip: IP 주소 필터
+        status: HTTP 상태 코드 필터
+        limit: 반환 최대 건수 (기본 100)
+        offset: 건너뛸 건수
+
+    Returns:
+        dict: {"entries": [...], "total": int, "limit": int, "offset": int}
+    """
+    if not AUDIT_LOG_FILE.exists():
+        return {"entries": [], "total": 0, "limit": limit, "offset": offset}
+
+    results = []
+    with open(AUDIT_LOG_FILE, "r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                entry = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+
+            ts = entry.get("ts", 0)
+            if from_ts is not None and ts < from_ts:
+                continue
+            if to_ts is not None and ts > to_ts:
+                continue
+            if method and entry.get("method") != method.upper():
+                continue
+            if path_contains and path_contains not in entry.get("path", ""):
+                continue
+            if ip and entry.get("ip") != ip:
+                continue
+            if status is not None:
+                try:
+                    if entry.get("status") != int(status):
+                        continue
+                except (ValueError, TypeError):
+                    continue
+
+            results.append(entry)
+
+    # 최신 순으로 정렬
+    results.sort(key=lambda e: e.get("ts", 0), reverse=True)
+    total = len(results)
+    entries = results[offset:offset + limit]
+
+    return {
+        "entries": entries,
+        "total": total,
+        "limit": limit,
+        "offset": offset,
+    }