세션 파일은 생겼지만 재시작 뒤 마지막 도구 호출이 사라지거나, 백업한 데이터베이스가 다시 열리지 않습니다. 개인 단일 실행이면 JSONL을 먼저 검증하고, 구조화된 검색이 필요할 때만 신뢰할 수 있는 로컬 디스크에서 SQLite를 평가하십시오. 네트워크 마운트에서는 WAL을 기본값처럼 적용하지 마십시오.
이 글은 다음 독자를 위한 실행 기준입니다.
- 세션을 오래 보관하면서 파일을 직접 확인하고 싶은 독립 개발자
- 클라우드 맥에서 여러 세션을 관리하고 검색해야 하는 운영팀
- 세션 감사, 복구, 저장소 교체 기준을 정해야 하는 플랫폼 담당자
먼저 저장소의 역할을 나누기
가장 먼저 구분할 것은 세 가지입니다.
- 세션 지속화 백엔드: 대화, 도구 호출, 실행 결과와 같은 원본 이벤트를 저장합니다.
- 파생 검색 색인: 여러 세션에서 조건 검색과 집계를 빠르게 만드는 보조 구조입니다.
- 일반 파일 백업: 원본을 다른 디스크나 보관 위치로 복사하는 절차입니다.
공식 설정에서 JSONL과 SQLite가 모두 선택지로 제시되더라도, 실제 기본 저장 위치는 현재 설정과 실행 버전에 따라 확인해야 합니다. 다음 명령을 실행하기 전에 설정 파일, 환경 변수, 세션 루트 디렉터리를 함께 기록하십시오.
dsh --help
find "$HOME" -iname '*session*' -o -iname '*.jsonl' -o -iname '*.sqlite'위 명령의 결과만으로 기본 경로를 확정해서는 안 됩니다. 파일이 생성되었다는 사실보다, 프로세스를 종료한 뒤 다시 열 수 있는지가 중요합니다.
단일 실행과 짧은 시험
개인 개발자가 한 대의 맥에서 잠시 테스트하고, 세션별 파일을 압축해 보관하려는 경우에는 JSONL이 먼저입니다. 사람이 직접 열어 레코드 흐름을 볼 수 있고, 세션별 파일을 분리하기 쉽기 때문입니다.
다만 JSONL 회선은 단순하다고 해서 자동으로 안전하지 않습니다. 다음 세 가지 제한을 확인해야 합니다.
- 프로세스가 파일 끝에 쓰는 도중 중단되면 마지막 줄이 불완전할 수 있습니다.
- 여러 프로세스가 같은 세션 파일에 동시에 쓰면 줄 순서와 중복 이벤트를 확인하기 어렵습니다.
- 백업 파일이 읽힌다고 해서 하네스가 정상적으로 재개된다는 뜻은 아닙니다.
- 새 세션을 만듭니다.
- 사용자 입력, 도구 호출, 도구 결과가 포함된 대표 작업을 한 번 실행합니다.
- 세션 루트와 실제 파일의 물리적 인코딩을 확인합니다.
- 하네스를 정상 종료합니다.
- 저장 파일을 다른 디렉터리에 복사합니다.
- 원본을 잠시 치운 뒤 복사본으로 세션을 다시 엽니다.
- 마지막 사용자 입력과 도구 결과가 동일한지 확인합니다.
장기 에이전트와 지속 기록
장시간 실행되는 에이전트는 파일 형식보다 중단 시점의 동작이 더 중요합니다. 정상 종료, 강제 종료, 운영 체제 재시작, 네트워크 일시 중단 뒤의 재개를 각각 나누어 시험해야 합니다.
JSONL은 지속 추가 기록에 자연스럽지만, 마지막 기록이 완전히 플러시되었는지와 재개 시 중복 이벤트를 어떻게 처리하는지는 하네스 구현에 달려 있습니다. SQLite는 트랜잭션 단위로 상태를 묶을 수 있지만, 데이터베이스 본체만 복사하는 방식으로는 일관된 백업을 보장하기 어렵습니다.
| 검증 항목 | JSONL | SQLite |
|---|---|---|
| 사람이 직접 읽기 | 쉬움 | 별도 질의 필요 |
| 세션별 파일 복사 | 단순함 | 본체와 관련 파일 확인 필요 |
| 중단 시 마지막 기록 | 끝부분 검사 필요 | 트랜잭션 복구 확인 필요 |
| 여러 세션 조건 검색 | 별도 색인 필요 | 질의 구조에 유리 |
| 장기 운영 판단 | 재개와 중복 검사 | 잠금과 백업 절차 검사 |
-wal과 -shm 파일을 사용할 수 있습니다. 공식 문서도 공유 메모리 파일이 같은 데이터베이스에 접근하는 프로세스 사이의 조정에 사용된다고 설명합니다. 따라서 데이터베이스 파일 하나만 저장소로 취급하면 안 됩니다. [SQLite WAL 동작 설명](https://www.sqlite.org/wal.html)과 [WAL 파일 형식 설명](https://sqlite.org/walformat.html)을 함께 확인하십시오. ([sqlite.org](https://www.sqlite.org/wal.html?utm_source=openai))
팀 조회와 감사 작업
세션 수가 늘어나면 “어떤 세션에서 특정 도구가 실패했는가”, “지난 기간에 중단된 실행은 무엇인가”, “특정 프로젝트의 모든 사용자 입력을 찾아라”와 같은 요구가 생깁니다. 이때 SQLite의 구조화된 질의와 별도 검색 색인이 가치가 있습니다.
그러나 여기서 원본과 색인을 섞으면 복구 책임이 흐려집니다.
- 원본 세션은 JSONL 또는 SQLite 중 하나로 보존합니다.
- 검색 색인은 다시 만들 수 있는 파생 데이터로 취급합니다.
- 색인이 깨져도 원본에서 재생성할 수 있어야 합니다.
- 감사 결과에는 원본 세션 식별자와 하네스 버전을 남깁니다.
| 판단 기준 | JSONL 점수 | SQLite 점수 | 선택 조건 |
|---|---|---|---|
| 단일 세션 백업 | 5점 | 3점 | 파일 단위 보관이 우선이면 JSONL |
| 대량 조건 검색 | 2점 | 5점 | 세션, 이벤트, 프로젝트 필터가 많으면 SQLite |
| 수동 장애 분석 | 5점 | 3점 | 원문을 바로 읽어야 하면 JSONL |
| 로컬 디스크의 동시 접근 | 3점 | 5점 | 잠금과 재개 시험을 통과한 경우에만 SQLite |
| 네트워크 마운트 | 2점 | 1점 | 먼저 로컬 저장 후 별도 백업 권장 |
| 백엔드 교체 | 4점 | 3점 | 원본 보존과 소량 변환을 전제로 판단 |
로컬 디스크와 네트워크 마운트
클라우드 맥의 로컬 내부 디스크에 저장하는 경우와 공유 디렉터리, 네트워크 마운트에 저장하는 경우는 같은 설정으로 비교하면 안 됩니다.
로컬 디스크에서는 다음 조건을 확인하십시오.
- 한 호스트에서만 데이터베이스를 엽니다.
- 동시에 실행되는 하네스 프로세스 수를 파악합니다.
-wal,-shm파일이 생기는지 확인합니다.- 강제 종료 뒤 재접속 시 복구되는지 확인합니다.
- 백업 시 데이터베이스 전용 백업 절차를 사용합니다.
- 한 호스트에서 세션을 쓰면서 다른 호스트에서 읽습니다.
- 쓰기 중 네트워크 연결을 끊습니다.
- 마운트를 다시 연결합니다.
- 하네스를 재시작합니다.
- 잠금 오류, 중복 이벤트, 마지막 커밋 누락을 확인합니다.
- 복구한 파일을 별도 로컬 디스크에서 다시 엽니다.
주의: 네트워크 드라이브가 빠르게 보인다는 이유만으로 데이터베이스 저장소로 적합하다고 판단하지 마십시오. 잠금, 공유 메모리, 재접속 뒤 복구가 모두 확인되지 않으면 백업 대상일 뿐 원본 저장소로 쓰지 않는 편이 안전합니다.
마이그레이션과 실패 회귀
개발자 미리 보기 단계에서는 JSONL에서 SQLite로 옮긴 뒤 다음 버전에서 스키마나 이벤트 표현이 바뀔 수 있습니다. 공식 저장소도 호환성 중단 가능성을 명시하므로, 직접 변환한 결과를 장기 호환 보증으로 해석해서는 안 됩니다. (github.com)
운영 순서는 다음과 같이 잡으십시오.
- 현재 하네스 버전과 저장 설정을 파일로 남깁니다.
- 기존 세션 루트를 읽기 전용으로 보존합니다.
- 대표 세션을 짧은 것, 도구 호출이 있는 것, 중단된 것으로 나눕니다.
- 새 백엔드에는 소량만 변환합니다.
- 세션 수, 마지막 이벤트, 도구 결과, 재개 결과를 원본과 대조합니다.
- 새 버전에서 정상 종료와 강제 종료를 각각 시험합니다.
- 실패하면 새 저장소를 제거하고 기존 백엔드로 회귀합니다.
클라우드 맥을 임시 실행 환경으로 사용할 계획이라면 MACGPU의 맥 미니 렌탈 환경을 먼저 확인하고, 저장소 원본은 실행 환경과 분리해 전달하는 방식이 관리하기 쉽습니다. 장기 실행 과정에서 세션 복구까지 책임져야 한다면 MACGPU의 원격 맥 환경 안내와 함께 저장 위치, 백업 주기, 복구 담당자를 문서화하십시오.
현재 사용하는 방식이 네트워크 공유 폴더, 수동 데이터베이스 복사, 세션 파일과 색인의 혼합 구조라면 세 가지 문제가 반복됩니다. 첫째, WAL 관련 파일을 빠뜨릴 수 있습니다. 둘째, 백업 시점의 일관성을 증명하기 어렵습니다. 셋째, 운영팀이 복구에 필요한 버전과 설정을 함께 전달하지 못할 수 있습니다. 이런 책임까지 직접 떠안아야 한다면, 단순히 저장소 형식만 바꾸기보다 로컬 디스크에서 검증된 세션 실행 환경을 임시로 확보하는 편이 현실적입니다. MACGPU의 맥 환경을 사용하면 최소한 실행 호스트와 전달 절차를 분리해 시험할 수 있습니다.
따라서 개인 시험과 단일 맥 실행에서는 JSONL을 먼저 채택하고, 여러 세션을 질의해야 하는 팀은 로컬 디스크에서 SQLite를 별도로 검증하십시오. 클라우드 맥에서 장기간 실행한다면 저장 형식보다 중단, 재시작, 백업 전달, 실패 회귀를 먼저 검증 기준에 넣어야 합니다.