@elyun/bylane 1.29.0 → 1.31.0

package/CLAUDE.md

@@ -11,7 +11,7 @@ byLane — Claude Code용 프론트엔드 개발 자동화 하네스.
 
 ```bash
 npm install          # 의존성 설치 + pre-commit 훅 자동 등록 (prepare 스크립트)
-npm test             # 테스트 실행 (19개)
+npm test             # 테스트 실행 (43개)
 npm run monitor      # 모니터 대시보드
 npm version minor    # 마이너 버전 올리기 (커밋 + 태그 자동 생성)
 npm run release      # npm 배포 (커밋/푸시 완료 후 실행)
@@ -38,16 +38,19 @@ npx @elyun/bylane memory read 123
 - `src/config.js` — `.bylane/bylane.json` 로드/저장/검증 (loadConfig, saveConfig, validateConfig, getAgentModel, DEFAULT_CONFIG)
 - `src/branch.js` — 브랜치명 패턴 엔진 (buildBranchName, buildBranchNameFromConfig)
 - `src/memory.js` — 이슈별 컨텍스트 메모리 유틸 (readIssueMemory, appendIssueMemory, listIssueMemories)
-- `src/cli.js` — npx 설치 CLI (install, loop, --symlink 옵션, 기존 파일 .bak 백업)
+- `src/cli.js` — npx 설치 CLI (install, loop, --symlink 옵션, 기존 파일 .bak 백업, Stop 훅 등록)
 - `src/loop-utils.js` — 루프 공통 유틸 (killExistingLoop, tmux 세션 관리, createAbsoluteTimer, resolveLoopMode)
-- `src/review-loop.js` — review 요청 PR 폴러 → `.bylane/state/review-queue.json` (절대시간 기반 폴링)
-- `src/respond-loop.js` — 내 PR 리뷰/코멘트 폴러 → `.bylane/state/respond-queue.json` (절대시간 기반 폴링)
+- `src/queue-utils.js` — 큐 상태 관리 유틸 (reconcileQueue, expireStaleItems, gcQueue, maintainQueue)
+- `src/pipeline.js` — 파이프라인 상태 추적 (startPipeline, updatePipelineStep, cancelStalePipeline, blockDownstreamOfFailed)
+- `src/review-loop.js` — review 요청 PR 폴러 → `.bylane/state/review-queue.json` (절대시간 기반 폴링, 큐 reconcile/GC 포함)
+- `src/respond-loop.js` — 내 PR 리뷰/코멘트 폴러 → `.bylane/state/respond-queue.json` (절대시간 기반 폴링, 큐 reconcile/GC 포함)
 - `src/monitor/` — blessed 기반 TUI 대시보드 (2열 그리드, 1초 폴링, fullUnicode)
 - `skills/` — Claude Code 에이전트 skill 파일들
 - `hooks/` — 외부 이벤트 자동 감지 훅
 - `commands/` — `/bylane` 슬래시 커맨드 정의
 - `templates/review-template.md` — 리뷰 코멘트 기본 템플릿
 - `scripts/release.sh` — npm 배포 스크립트 (dirty 체크 + 테스트 + publish)
+- `hooks/bylane-session-cleanup.js` — Stop 훅 (세션 종료 시 in_progress→cancelled, 루프/큐 상태 정리)
 - `.githooks/pre-commit` — 보안 검사 훅 (시크릿/민감파일/console.log)
 
 ## 에이전트 파이프라인
@@ -87,7 +90,7 @@ respond-loop  (독립: 설정 주기로 리뷰 코멘트 감지, 절대시간
 ```json
 {
   "agent": "code-agent",
-  "status": "in_progress | completed | failed | idle",
+  "status": "in_progress | completed | failed | cancelled | blocked | idle",
   "startedAt": "ISO8601",
   "progress": 0,
   "retries": 0,
@@ -95,6 +98,25 @@ respond-loop  (독립: 설정 주기로 리뷰 코멘트 감지, 절대시간
 }
 ```
 
+### 큐 항목 상태 값
+
+`pending` → `reviewing`/`responding` → `resolved` | `expired` (GC 후 제거)
+
+큐 reconcile: 매 poll마다 GitHub 상태와 대조하여 불필요한 pending 항목을 resolved로 전환.
+TTL: 24시간 초과 pending → expired. GC: resolved/expired 후 1시간 경과 시 큐에서 제거.
+
+### 파이프라인 상태 (`pipeline.json`)
+
+```json
+{
+  "agent": "pipeline",
+  "status": "in_progress | completed | failed | cancelled",
+  "pipelineType": "A | B | C_review | C_respond | D",
+  "currentStep": "code-agent",
+  "steps": [{ "agent": "code-agent", "status": "completed" }, ...]
+}
+```
+
 ## GitHub 접근 방법
 
 `github.method`: `"auto"` (기본, MCP→CLI→API 순) | `"mcp"` | `"cli"` | `"api"`
@@ -114,9 +136,11 @@ respond-loop  (독립: 설정 주기로 리뷰 코멘트 감지, 절대시간
 
 ```
 tests/
-├── state.test.js   — writeState, readState, clearState, listStates, appendLog
-├── config.test.js  — loadConfig, saveConfig, validateConfig, DEFAULT_CONFIG
-└── branch.test.js  — buildBranchName (6개 패턴 케이스, 슬래시 엣지케이스 포함)
+├── state.test.js        — writeState, readState, clearState, listStates, appendLog (6개)
+├── config.test.js       — loadConfig, saveConfig, validateConfig, DEFAULT_CONFIG (7개)
+├── branch.test.js       — buildBranchName (6개 패턴 케이스, 슬래시 엣지케이스 포함)
+├── queue-utils.test.js  — reconcileQueue, expireStaleItems, gcQueue, maintainQueue (10개)
+└── pipeline.test.js     — startPipeline, updatePipelineStep, cancelStalePipeline, blockDownstreamOfFailed (14개)
 ```
 
 ## 주의사항

package/commands/bylane-cleanup.md

@@ -25,11 +25,16 @@ npx @elyun/bylane cleanup
 
 | 항목 | 동작 |
 |------|------|
+| stale 파이프라인 | 30분 초과 파이프라인 cascade cancel (하위 에이전트 일괄 취소) |
+| upstream 실패 | 파이프라인 내 실패 에이전트 하류 → `blocked` 처리 |
 | `.bylane/state/` 권한 | 디렉토리 755, 파일 644로 수정 |
 | 죽은 루프 프로세스 | PID 확인 → 없으면 `stopped`로 전환 |
 | 30분 초과 `in_progress` | `failed`로 초기화 |
 | `subagents.json` active | PID 없는 항목 제거 |
 | 큐의 `reviewing`/`responding` | `pending`으로 복구 (재처리 대기) |
+| 큐 TTL 초과 pending | 24시간 초과 → `expired` 전환 |
+| 큐 GC | resolved/expired 후 1시간 경과 항목 제거 |
+| 루프-큐 상태 동기화 | 루프 미실행 시 큐 `stopped` 전환 |
 
 ## 완료
 

package/commands/bylane-code-agent.md

@@ -30,9 +30,27 @@ npx @elyun/bylane state write code-agent '{"status":"in_progress","startedAt":"'
 | `spec.figmaSpec` | Figma 컬러토큰·컴포넌트 구조 |
 | `issueType` | `new-feature` / `bug` / `improvement` / `chore` |
 | `issueNumber` | GitHub 이슈 번호 |
+| `branchName` | issue-agent가 생성한 브랜치명 |
+| `worktreePath` | 워크트리 경로 (없으면 `null`) |
 
 없으면 GitHub 이슈 본문을 직접 로드하여 파싱한다.
 
+### 브랜치/워크트리 확인
+
+issue-agent가 이미 브랜치를 생성했는지 확인한다:
+
+1. `branchName`이 있으면 → 해당 브랜치로 checkout
+2. `worktreePath`가 있으면 → 해당 워크트리 디렉토리에서 작업
+3. 둘 다 없으면 (`issue.autoCreateBranch: false`) → code-agent가 직접 브랜치 생성
+
+```bash
+# branchName이 있는 경우
+git checkout "$BRANCH_NAME"
+
+# worktreePath가 있는 경우 — 해당 디렉토리에서 모든 작업 수행
+cd "$WORKTREE_PATH"
+```
+
 issueMemory 로드:
 ```bash
 npx @elyun/bylane memory read ISSUE_NUMBER

package/commands/bylane-issue-agent.md

@@ -211,6 +211,49 @@ curl -s -X POST \
 
 ---
 
+### Phase 5 — 브랜치/워크트리 생성 (설정에 따라)
+
+이슈 생성 직후, `issue.autoCreateBranch`가 `true`이면 브랜치를 자동 생성한다.
+브랜치명은 `branch.pattern` 설정에 따라 결정된다.
+
+```bash
+# 브랜치명 생성 (src/branch.js 활용)
+BRANCH_NAME=$(node -e "
+import('./src/branch.js').then(({buildBranchNameFromConfig}) => {
+  import('./src/config.js').then(({loadConfig}) => {
+    const config = loadConfig()
+    const name = buildBranchNameFromConfig(config, {
+      issueNumber: ISSUE_NUMBER,
+      type: 'ISSUE_TYPE',
+      title: 'ISSUE_TITLE'
+    })
+    process.stdout.write(name)
+  })
+})
+")
+
+git checkout -b "$BRANCH_NAME"
+```
+
+#### 워크트리 생성 (`issue.autoCreateWorktree: true`인 경우)
+
+브랜치 대신 워크트리를 생성하여 독립된 작업 디렉토리를 만든다:
+
+```bash
+WORKTREE_DIR=".bylane/worktrees/$BRANCH_NAME"
+git worktree add "$WORKTREE_DIR" -b "$BRANCH_NAME"
+```
+
+이후 모든 에이전트(code-agent, test-agent, commit-agent 등)는 이 워크트리 경로에서 작업한다.
+state에 `branchName`과 `worktreePath`를 기록하여 후속 에이전트가 참조할 수 있게 한다.
+
+#### 설정이 꺼져 있는 경우
+
+`issue.autoCreateBranch: false`이면 이 단계를 건너뛴다.
+code-agent가 실행 시점에 브랜치를 직접 생성한다.
+
+---
+
 ## 출력
 
 `.bylane/state/issue-agent.json`:
@@ -230,7 +273,9 @@ curl -s -X POST \
     "affectedFiles": ["src/hooks/useTheme.ts", "src/components/Header/"],
     "checklist": ["ThemeToggle 컴포넌트 생성", "useTheme hook 수정", "테스트 작성"],
     "figmaSpec": { "enabled": false, "components": [], "colorTokens": {} }
-  }
+  },
+  "branchName": "issues-123-dark-mode-toggle",
+  "worktreePath": null
 }
 ```
 

package/commands/bylane-orchestrator.md

@@ -31,6 +31,41 @@ npx @elyun/bylane models
 
 ---
 
+## 파이프라인 상태 추적
+
+각 에이전트 호출 전후에 파이프라인 상태를 기록하여, 세션 종료나 에이전트 실패 시 자동 정리가 가능하게 한다.
+
+### 파이프라인 시작 (에이전트 호출 전)
+
+```bash
+npx @elyun/bylane state write pipeline '{"status":"in_progress","pipelineType":"A","issueNumber":null,"startedAt":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","currentStep":"issue-agent","steps":[{"agent":"issue-agent","status":"pending"},{"agent":"code-agent","status":"pending"},{"agent":"test-agent","status":"pending"},{"agent":"commit-agent","status":"pending"},{"agent":"pr-agent","status":"pending"},{"agent":"review-agent","status":"pending"},{"agent":"notify-agent","status":"pending"}]}'
+```
+
+### 각 에이전트 시작/완료 시
+
+```bash
+# 에이전트 시작 시 — 해당 step을 in_progress로
+npx @elyun/bylane state write pipeline '현재 pipeline state에서 해당 step.status를 "in_progress"로 변경'
+
+# 에이전트 완료 시 — 해당 step을 completed로, currentStep을 다음 단계로
+npx @elyun/bylane state write pipeline '현재 pipeline state에서 해당 step.status를 "completed"로 변경, currentStep 갱신'
+```
+
+### 파이프라인 완료/실패 시
+
+```bash
+# 성공
+npx @elyun/bylane state write pipeline '{"status":"completed","completedAt":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'",...}'
+
+# 실패 (maxRetries 초과 등)
+npx @elyun/bylane state write pipeline '{"status":"failed","failedAt":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","reason":"...",...}'
+```
+
+> **중요**: 파이프라인 상태가 30분간 업데이트되지 않으면 cleanup이 자동으로 cascade cancel한다.
+> 세션 종료 시 Stop 훅이 in_progress 파이프라인과 하위 에이전트를 즉시 cancelled로 전환한다.
+
+---
+
 ## 의도 파싱 규칙
 
 ### 파이프라인 A — 새 기능 / 이슈 없는 구현 요청
@@ -94,9 +129,13 @@ npx @elyun/bylane models
 
 ### 각 에이전트 호출 방법
 
-Agent 도구에 아래 형식으로 전달한다:
+Agent 도구에 아래 형식으로 전달한다. **호출 전후로 파이프라인 상태를 갱신**한다:
 
 ```
+# 1. 호출 전: 파이프라인 step을 in_progress로 갱신
+npx @elyun/bylane state write pipeline '{...현재 state에서 해당 step.status → "in_progress"}'
+
+# 2. Agent 도구 호출
 subagent_type: "general-purpose"
 model: {models 명령으로 확인한 해당 에이전트 모델}
 prompt: |
@@ -109,6 +148,9 @@ prompt: |
 
   스킬 완료 후 .bylane/state/{에이전트명}.json 에 결과가 기록된다.
   결과 파일의 status, 핵심 출력 필드만 응답으로 돌려줘.
+
+# 3. 호출 후: 파이프라인 step을 completed/failed로 갱신, currentStep을 다음 에이전트로
+npx @elyun/bylane state write pipeline '{...현재 state에서 해당 step.status → "completed", currentStep → 다음}'
 ```
 
 ---

package/commands/bylane-setup.md

@@ -83,7 +83,25 @@ Linear API Key는 환경변수명(`LINEAR_API_KEY`)으로 저장. 실제 키값
 
 `permissions.scope`에 저장.
 
-## Step 5/9 — 리뷰 자동 Approve
+## Step 5/10 — 이슈 생성 시 브랜치/워크트리
+
+> 이슈 생성 후 자동으로 브랜치를 만들까요? (y/n, 기본: y)
+
+- `y` (기본) → `issue.autoCreateBranch = true` — 이슈 생성 직후 브랜치 네이밍 패턴에 따라 브랜치 자동 생성
+- `n` → `issue.autoCreateBranch = false` — code-agent 실행 시 수동 생성
+
+`y` 선택 시 추가 질문:
+
+> 브랜치와 함께 git worktree도 생성할까요? (y/n, 기본: n)
+> worktree를 사용하면 이슈별로 독립된 작업 디렉토리가 생성됩니다.
+> 여러 이슈를 동시에 작업할 때 유용합니다.
+
+- `y` → `issue.autoCreateWorktree = true` — `.bylane/worktrees/{branch-name}/`에 워크트리 생성
+- `n` (기본) → `issue.autoCreateWorktree = false` — 브랜치만 생성하고 checkout
+
+모든 후속 에이전트(code-agent, test-agent, commit-agent 등)는 이슈 번호 기준으로 해당 브랜치/워크트리에서 작업한다.
+
+## Step 6/10 — 리뷰 자동 Approve
 
 > AI 리뷰에서 지적사항이 없을 때 자동으로 Approve할까요? (y/n, 기본: n)
 
@@ -92,7 +110,7 @@ Linear API Key는 환경변수명(`LINEAR_API_KEY`)으로 저장. 실제 키값
 
 대부분의 팀에서는 사람이 최종 Approve하는 것을 권장한다.
 
-## Step 6/9 — Loop 실행 모드
+## Step 7/10 — Loop 실행 모드
 
 > Loop 실행 모드를 선택하세요:
 > 1. tmux  — tmux 세션에서 백그라운드 실행 (터미널 종료 후에도 유지, 권장)
@@ -117,7 +135,7 @@ bylane loop stop    # loop 종료
 bylane loop status  # 상태 확인
 ```
 
-## Step 7/9 — 고급 설정
+## Step 8/10 — 고급 설정
 
 > 고급 설정을 변경하시겠습니까? (Enter = 기본값 사용)
 
@@ -126,7 +144,7 @@ bylane loop status  # 상태 확인
 - `loopTimeoutMinutes` (기본: 30): 루프 타임아웃 (분)
 - Figma MCP 활성화? (y/n, 기본: n)
 
-## Step 8/9 — 브랜치 네이밍
+## Step 9/10 — 브랜치 네이밍
 
 > 브랜치 네이밍 패턴을 선택하세요:
 > 1. {tracker}-{issue-number}              예) issues-32
@@ -141,7 +159,7 @@ bylane loop status  # 상태 확인
 직접 입력 시 사용 가능한 토큰 목록 안내:
 `{tracker}`, `{type}`, `{issue-number}`, `{custom-id}`, `{title-slug}`, `{date}`, `{username}`
 
-## Step 9/9 — 에이전트 모델 설정
+## Step 10/10 — 에이전트 모델 설정
 
 > 각 에이전트에 사용할 AI 모델을 설정하시겠습니까? (Enter = 기본값 사용)
 

package/hooks/bylane-session-cleanup.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+/**
+ * bylane-session-cleanup.js
+ * Stop 훅 — Claude Code 세션 종료 시 상태 파일 자동 정리
+ *
+ * 처리 항목:
+ * - in_progress 에이전트 → cancelled (세션 종료)
+ * - running 루프 (PID 죽은 경우) → stopped
+ * - running 큐 (루프 죽은 경우) → stopped
+ * - pipeline in_progress → cancelled
+ */
+import { readFileSync, readdirSync, writeFileSync, existsSync } from 'fs'
+
+// stdin 읽기 (훅 프로토콜)
+try { readFileSync('/dev/stdin', 'utf8') } catch {}
+
+const STATE_DIR = '.bylane/state'
+if (!existsSync(STATE_DIR)) process.exit(0)
+
+const now = new Date().toISOString()
+
+function isPidAlive(pid) {
+  try { process.kill(Number(pid), 0); return true } catch { return false }
+}
+
+function readJson(path) {
+  try { return JSON.parse(readFileSync(path, 'utf8')) } catch { return null }
+}
+
+function writeJson(path, data) {
+  writeFileSync(path, JSON.stringify({ ...data, updatedAt: now }, null, 2))
+}
+
+try {
+  const files = readdirSync(STATE_DIR).filter(f => f.endsWith('.json'))
+  const { join } = await import('path')
+
+  for (const file of files) {
+    const name = file.replace('.json', '')
+    if (name === 'cancel' || name === 'subagents') continue
+
+    const path = join(STATE_DIR, file)
+    const state = readJson(path)
+    if (!state) continue
+
+    // 파이프라인: in_progress → cancelled + 하위 step도 cancelled
+    if (name === 'pipeline' && state.status === 'in_progress') {
+      writeJson(path, {
+        ...state,
+        status: 'cancelled',
+        cancelledAt: now,
+        reason: 'session_ended',
+        steps: (state.steps ?? []).map(step =>
+          step.status === 'in_progress' || step.status === 'pending'
+            ? { ...step, status: 'cancelled', cancelledAt: now }
+            : step
+        )
+      })
+      continue
+    }
+
+    // in_progress 에이전트 → cancelled
+    if (state.status === 'in_progress' && !name.endsWith('-loop') && !name.endsWith('-queue')) {
+      writeJson(path, {
+        ...state,
+        status: 'cancelled',
+        cancelledAt: now,
+        reason: 'session_ended'
+      })
+      continue
+    }
+
+    // running 루프: PID 죽었으면 stopped
+    if (name.endsWith('-loop') && state.status === 'running' && state.pid) {
+      if (!isPidAlive(state.pid)) {
+        writeJson(path, { ...state, status: 'stopped', stoppedAt: now })
+      }
+      continue
+    }
+
+    // running 큐: 대응 루프가 죽었으면 stopped
+    if (name.endsWith('-queue') && state.status === 'running') {
+      const loopName = name.replace('-queue', '-loop')
+      const loopPath = join(STATE_DIR, `${loopName}.json`)
+      const loopState = readJson(loopPath)
+      const loopAlive = loopState?.status === 'running' && loopState?.pid && isPidAlive(loopState.pid)
+      if (!loopAlive) {
+        writeJson(path, { ...state, status: 'stopped' })
+      }
+    }
+  }
+} catch {}
+
+process.exit(0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elyun/bylane",
-  "version": "1.29.0",
+  "version": "1.31.0",
   "description": "Frontend development harness for Claude Code",
   "type": "module",
   "bin": {

package/src/cleanup.js

@@ -6,6 +6,8 @@
 import { readdirSync, chmodSync, existsSync, unlinkSync, readFileSync, writeFileSync, mkdirSync } from 'fs'
 import { join } from 'path'
 import { readState, writeState } from './state.js'
+import { gcQueue, expireStaleItems } from './queue-utils.js'
+import { cancelStalePipeline, blockDownstreamOfFailed } from './pipeline.js'
 
 const STATE_DIR = '.bylane/state'
 const STALE_MS = 30 * 60 * 1000   // 30분 이상 in_progress → 초기화
@@ -73,6 +75,18 @@ export function runCleanup() {
     return result
   }
 
+  // 0. 파이프라인 cascade cancel — stale 파이프라인 감지 시 하위 에이전트 일괄 취소
+  const stalePipeline = cancelStalePipeline()
+  if (stalePipeline.pipelineCancelled) {
+    result.reset.push(`pipeline: stale → cancelled (${stalePipeline.cancelled.length}개 에이전트 취소: ${stalePipeline.cancelled.join(', ')})`)
+  }
+
+  // 0-1. 파이프라인 내 실패 에이전트 하류 → blocked
+  const downstream = blockDownstreamOfFailed()
+  if (downstream.blocked.length > 0) {
+    result.reset.push(`pipeline: upstream 실패 → ${downstream.blocked.length}개 에이전트 blocked (${downstream.blocked.join(', ')})`)
+  }
+
   // 1. 파일 권한 수정
   result.fixed.push(...fixPermissions())
 
@@ -82,8 +96,8 @@ export function runCleanup() {
   for (const file of files) {
     const name = file.replace('.json', '')
 
-    // 특수 파일 건너뜀
-    if (name === 'cancel') continue
+    // 특수 파일 건너뜀 (pipeline은 pipeline.js에서 별도 처리)
+    if (name === 'cancel' || name === 'pipeline') continue
 
     // subagents 별도 처리
     if (name === 'subagents') {
@@ -115,17 +129,53 @@ export function runCleanup() {
       }
     }
 
-    // 큐 파일: responding/reviewing 상태가 남아있으면 pending으로 복구
+    // 큐 파일 종합 정리
     if ((name === 'review-queue' || name === 'respond-queue') && Array.isArray(state.queue)) {
-      const fixed = state.queue.map(item =>
+      let queue = state.queue
+      let changed = false
+
+      // 1) responding/reviewing 상태 → pending 복구
+      const recovered = queue.map(item =>
         item.status === 'reviewing' || item.status === 'responding'
           ? { ...item, status: 'pending', recoveredAt: new Date().toISOString() }
           : item
       )
-      const changedCount = fixed.filter((item, i) => item.status !== state.queue[i].status).length
-      if (changedCount > 0) {
-        writeState(name, { ...state, queue: fixed }, STATE_DIR)
-        result.reset.push(`${name}: ${changedCount}개 진행중 항목 → pending 복구`)
+      const recoveredCount = recovered.filter((item, i) => item.status !== queue[i].status).length
+      if (recoveredCount > 0) {
+        queue = recovered
+        changed = true
+        result.reset.push(`${name}: ${recoveredCount}개 진행중 항목 → pending 복구`)
+      }
+
+      // 2) stale pending → expired (TTL 초과)
+      const expired = expireStaleItems(queue)
+      if (expired.expiredCount > 0) {
+        queue = expired.queue
+        changed = true
+        result.reset.push(`${name}: ${expired.expiredCount}개 pending 항목 → expired (TTL 초과)`)
+      }
+
+      // 3) resolved/expired 항목 GC (1시간 경과)
+      const gc = gcQueue(queue)
+      if (gc.removedCount > 0) {
+        queue = gc.queue
+        changed = true
+        result.cleared.push(`${name}: ${gc.removedCount}개 완료/만료 항목 GC 제거`)
+      }
+
+      // 4) 루프-큐 상태 동기화: 루프가 stopped인데 큐가 running이면 stopped로
+      const loopName = name.replace('-queue', '-loop')
+      const loopState = readState(loopName, STATE_DIR)
+      const loopDead = !loopState || loopState.status !== 'running' ||
+        (loopState.pid && !isPidAlive(loopState.pid))
+      if (state.status === 'running' && loopDead) {
+        changed = true
+        result.reset.push(`${name}: 루프 미실행 → 큐 상태 stopped`)
+      }
+
+      if (changed) {
+        const newStatus = (state.status === 'running' && loopDead) ? 'stopped' : state.status
+        writeState(name, { ...state, status: newStatus, queue }, STATE_DIR)
       }
     }
   }

package/src/cli.js

@@ -49,11 +49,14 @@ function registerHooks() {
   }
 
   const hookScript = join(CLAUDE_DIR, 'hooks', 'bylane-agent-tracker.js')
+  const cleanupHookScript = join(CLAUDE_DIR, 'hooks', 'bylane-session-cleanup.js')
   settings.hooks = settings.hooks ?? {}
 
   // 기존 bylane 훅 제거 후 재등록 (버전 업 시 경로 변경 대응)
   const stripBylane = (arr) =>
-    (arr ?? []).filter(h => !h.hooks?.some(hh => hh.command?.includes('bylane-agent-tracker')))
+    (arr ?? []).filter(h => !h.hooks?.some(hh =>
+      hh.command?.includes('bylane-agent-tracker') || hh.command?.includes('bylane-session-cleanup')
+    ))
 
   settings.hooks.PreToolUse = [
     ...stripBylane(settings.hooks.PreToolUse),
@@ -63,9 +66,14 @@ function registerHooks() {
     ...stripBylane(settings.hooks.PostToolUse),
     { matcher: 'Agent', hooks: [{ type: 'command', command: `node ${hookScript} post` }] }
   ]
+  settings.hooks.Stop = [
+    ...stripBylane(settings.hooks.Stop),
+    { matcher: '', hooks: [{ type: 'command', command: `node ${cleanupHookScript}` }] }
+  ]
 
   writeFileSync(settingsPath, JSON.stringify(settings, null, 2))
-  console.log('  ~ Hook: bylane-agent-tracker 등록 (최신 경로로 갱신)')
+  console.log('  ~ Hook: bylane-agent-tracker 등록 (PreToolUse + PostToolUse)')
+  console.log('  ~ Hook: bylane-session-cleanup 등록 (Stop — 세션 종료 시 상태 정리)')
 }
 
 function preservedConfigs() {
@@ -158,10 +166,13 @@ function uninstall() {
     try {
       const settings = JSON.parse(readFileSync(settingsPath, 'utf8'))
       const stripBylane = (arr) =>
-        (arr ?? []).filter(h => !h.hooks?.some(hh => hh.command?.includes('bylane-agent-tracker')))
+        (arr ?? []).filter(h => !h.hooks?.some(hh =>
+          hh.command?.includes('bylane-agent-tracker') || hh.command?.includes('bylane-session-cleanup')
+        ))
       settings.hooks = settings.hooks ?? {}
       settings.hooks.PreToolUse = stripBylane(settings.hooks.PreToolUse)
       settings.hooks.PostToolUse = stripBylane(settings.hooks.PostToolUse)
+      settings.hooks.Stop = stripBylane(settings.hooks.Stop)
       writeFileSync(settingsPath, JSON.stringify(settings, null, 2))
       console.log('  - Hook: bylane-agent-tracker 제거')
     } catch {}
@@ -267,6 +278,10 @@ if (command === 'install') {
   const sessionName = config.loop?.sessionName ?? 'bylane-loops'
 
   if (subCmd === 'start') {
+    // 시작 전 상태 정리
+    const { runCleanup } = await import('./cleanup.js')
+    runCleanup()
+
     const mode = resolveLoopMode()
 
     if (mode === 'tmux') {
@@ -330,6 +345,10 @@ if (command === 'install') {
       }
     }
 
+    // 종료 후 상태 정리 (큐 상태 동기화 포함)
+    const { runCleanup } = await import('./cleanup.js')
+    runCleanup()
+
     if (!stopped) {
       console.log('  실행 중인 루프가 없습니다.')
     }

package/src/config.js

@@ -40,6 +40,10 @@ export const DEFAULT_CONFIG = {
     owner: '',
     repo: ''
   },
+  issue: {
+    autoCreateBranch: true,
+    autoCreateWorktree: false
+  },
   memory: {
     enabled: true,
     dir: '.bylane/memory'