orca-agent-cleanup 1.5.0 → 1.5.1

package/README.ko.md

@@ -6,9 +6,9 @@
 
 남은 Orca 연결을 검사하고, 확인된 잔재를 복구 가능하게 격리합니다.
 
-[English](README.md) · **한국어**
+[English](https://github.com/wilgon456/orca-agent-cleanup/blob/main/README.md) · **한국어**
 
-![project: utility](https://img.shields.io/badge/project-utility-22d3ee?style=flat-square) ![stack: Node.js 18+](https://img.shields.io/badge/stack-Node.js%2018%2B-22d3ee?style=flat-square) [![License](https://img.shields.io/badge/license-MIT-22d3ee?style=flat-square)](LICENSE)
+![project: utility](https://img.shields.io/badge/project-utility-22d3ee?style=flat-square) ![stack: Node.js 18+](https://img.shields.io/badge/stack-Node.js%2018%2B-22d3ee?style=flat-square) [![License](https://img.shields.io/badge/license-MIT-22d3ee?style=flat-square)](https://github.com/wilgon456/orca-agent-cleanup/blob/main/LICENSE)
 
 [빠른 시작](#-빠른-시작) · [정리 범위](#-무엇을-정리하나요) · [복구](#-복구-방법)
 
@@ -427,7 +427,7 @@ Windows 전용 기존 도구의 회귀 테스트:
 .\tests\Invoke-SmokeTest.ps1
 ```
 
-보안 취약점 신고 방법은 [SECURITY.md](SECURITY.md)를 참고하세요.
+보안 취약점 신고 방법은 [SECURITY.md](https://github.com/wilgon456/orca-agent-cleanup/blob/main/SECURITY.md)를 참고하세요.
 
 ## 🙋 자주 묻는 질문
 
@@ -458,7 +458,7 @@ Orca가 `~/.orca`에 저장한 암호화 음성 토큰과 Bitbucket·Linear·Jir
 
 ## 📄 라이선스
 
-[MIT License](LICENSE)로 배포합니다.
+[MIT License](https://github.com/wilgon456/orca-agent-cleanup/blob/main/LICENSE)로 배포합니다.
 
 ---
 

package/README.md

@@ -6,9 +6,9 @@
 
 Inspect leftover Orca integrations, quarantine verified residue and restore it when needed.
 
-**English** · [한국어](README.ko.md)
+**English** · [한국어](https://github.com/wilgon456/orca-agent-cleanup/blob/main/README.ko.md)
 
-![project: utility](https://img.shields.io/badge/project-utility-22d3ee?style=flat-square) ![stack: Node.js 18+](https://img.shields.io/badge/stack-Node.js%2018%2B-22d3ee?style=flat-square) [![License](https://img.shields.io/badge/license-MIT-22d3ee?style=flat-square)](LICENSE)
+![project: utility](https://img.shields.io/badge/project-utility-22d3ee?style=flat-square) ![stack: Node.js 18+](https://img.shields.io/badge/stack-Node.js%2018%2B-22d3ee?style=flat-square) [![License](https://img.shields.io/badge/license-MIT-22d3ee?style=flat-square)](https://github.com/wilgon456/orca-agent-cleanup/blob/main/LICENSE)
 
 [Quick start](#quick-start) · [Coverage](#cleanup-coverage) · [Restore](#restore)
 
@@ -180,8 +180,8 @@ The legacy Windows interface remains available:
 .\tests\Invoke-SmokeTest.ps1
 ```
 
-See [SECURITY.md](SECURITY.md) for vulnerability reporting. For bug reports, include the OS, whether Orca was uninstalled, a redacted scan result and the expected versus observed behavior.
+See [SECURITY.md](https://github.com/wilgon456/orca-agent-cleanup/blob/main/SECURITY.md) for vulnerability reporting. For bug reports, include the OS, whether Orca was uninstalled, a redacted scan result and the expected versus observed behavior.
 
 ## License
 
-[MIT](LICENSE).
+[MIT](https://github.com/wilgon456/orca-agent-cleanup/blob/main/LICENSE).

package/package.json

@@ -1,42 +1,42 @@
-{
-  "name": "orca-agent-cleanup",
-  "version": "1.5.0",
-  "description": "Find and safely quarantine leftover Orca (stablyai/orca) skills, agent hooks, CLI launchers, credentials and app data after uninstalling Orca, with verified restore.",
-  "keywords": [
-    "orca",
-    "stablyai",
-    "uninstall",
-    "cleanup",
-    "claude-code",
-    "codex",
-    "agent-hooks",
-    "skills"
-  ],
-  "license": "MIT",
-  "author": "wilgon456",
-  "homepage": "https://github.com/wilgon456/orca-agent-cleanup#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/wilgon456/orca-agent-cleanup.git"
-  },
-  "bugs": {
-    "url": "https://github.com/wilgon456/orca-agent-cleanup/issues"
-  },
-  "type": "module",
-  "bin": {
-    "orca-agent-cleanup": "scripts/orca-agent-cleanup.mjs"
-  },
-  "files": [
-    "scripts/orca-agent-cleanup.mjs",
-    "scripts/orca-cleanup-core.mjs",
-    "README.md",
-    "README.ko.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "scripts": {
-    "test": "node --test tests/orca-agent-cleanup.test.mjs"
-  }
-}
+{
+  "name": "orca-agent-cleanup",
+  "version": "1.5.1",
+  "description": "Find and safely quarantine leftover Orca (stablyai/orca) skills, agent hooks, CLI launchers, credentials and app data after uninstalling Orca, with verified restore.",
+  "keywords": [
+    "orca",
+    "stablyai",
+    "uninstall",
+    "cleanup",
+    "claude-code",
+    "codex",
+    "agent-hooks",
+    "skills"
+  ],
+  "license": "MIT",
+  "author": "wilgon456",
+  "homepage": "https://github.com/wilgon456/orca-agent-cleanup#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wilgon456/orca-agent-cleanup.git"
+  },
+  "bugs": {
+    "url": "https://github.com/wilgon456/orca-agent-cleanup/issues"
+  },
+  "type": "module",
+  "bin": {
+    "orca-agent-cleanup": "scripts/orca-agent-cleanup.mjs"
+  },
+  "files": [
+    "scripts/orca-agent-cleanup.mjs",
+    "scripts/orca-cleanup-core.mjs",
+    "README.md",
+    "README.ko.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test tests/orca-agent-cleanup.test.mjs"
+  }
+}

package/scripts/orca-agent-cleanup.mjs

@@ -1,221 +1,221 @@
-#!/usr/bin/env node
-
-import fs from 'node:fs';
-import process from 'node:process';
-import {
-  buildContext,
-  cleanOrcaResidue,
-  OFFICIAL_ORCA_SKILLS,
-  restoreOrcaBackup,
-  scanOrcaResidue,
-  verifyOrcaBackup,
-} from './orca-cleanup-core.mjs';
-
-const VERSION = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
-
-const HELP = `
-Orca Agent Cleanup v${VERSION} : Windows·macOS·Linux 공통 정리 도구
-
-사용법:
-  npx orca-agent-cleanup scan [옵션]
-  npx orca-agent-cleanup clean [옵션]
-  npx orca-agent-cleanup restore --manifest <manifest.json> [옵션]
-  npx orca-agent-cleanup verify --manifest <manifest.json> [옵션]
-
-저장소에서 직접 실행할 때는 npx orca-agent-cleanup 대신 node scripts/orca-agent-cleanup.mjs를 씁니다.
-
-명령:
-  scan                         잔재를 검사합니다(기본 명령, 변경 없음).
-  clean                        확인된 잔재를 백업 폴더로 격리합니다.
-  restore                      manifest에 기록된 파일과 설정을 복원합니다.
-  verify                       manifest와 백업 내용의 무결성을 검사합니다.
-
-옵션:
-  --dry-run                    clean의 예정 작업만 표시합니다.
-  --stop-processes             앱 없이 남아 도는 Orca 백그라운드 프로세스를 끕니다.
-  --force                      Orca 앱이 설치·실행 중이어도 정리합니다(권장하지 않음).
-  --include-app-data           Orca 앱 데이터·캐시를 포함합니다.
-  --include-voice-data         별도 음성 모델 캐시를 포함합니다.
-  --include-user-state         ~/.orca 전체(자격증명·세션 포함)를 포함합니다.
-  --include-wsl                실행 중인 WSL 배포판의 Orca 잔재를 검사·정리합니다.
-  --wsl-home <경로>            WSL 홈 경로를 직접 추가합니다(반복 가능).
-  --include-remote             SSH 릴레이·원격 세션 잔재를 포함합니다.
-  --remote-home <경로>         접근 가능한 원격 홈 경로를 추가합니다(반복 가능).
-  --include-project-state      --project의 .orca·worktree 휴지통을 포함합니다.
-  --project <경로>             프로젝트 스킬 위치를 추가합니다(반복 가능).
-  --voice-model-path <경로>    사용자 지정 음성 모델 경로를 포함합니다(반복 가능).
-  --backup-root <경로>         격리·백업 폴더를 지정합니다.
-  --manifest <경로>            restore·verify에 사용할 manifest.json을 지정합니다.
-  --json                       결과를 JSON으로 출력합니다.
-  -v, --version                버전을 표시합니다.
-  -h, --help                   도움말을 표시합니다.
-
-예시:
-  npx orca-agent-cleanup scan
-  npx orca-agent-cleanup clean --dry-run --include-app-data --include-voice-data --stop-processes
-  npx orca-agent-cleanup clean --include-app-data --include-voice-data --stop-processes
-  npx orca-agent-cleanup restore --dry-run --manifest /path/to/manifest.json
-`;
-
-function parseArgs(argv) {
-  const result = {
-    command: 'scan', projects: [], customVoicePaths: [], wslHomes: [], remoteHomes: [], json: false,
-    dryRun: false, force: false, stopProcesses: false, includeAppData: false, includeVoiceData: false,
-    includeUserState: false, includeWsl: false, includeRemote: false, includeProjectState: false,
-  };
-  const args = [...argv];
-  if (args[0] && !args[0].startsWith('-')) result.command = args.shift();
-  while (args.length) {
-    const arg = args.shift();
-    if (arg === '--dry-run') result.dryRun = true;
-    else if (arg === '--force') result.force = true;
-    else if (arg === '--stop-processes') result.stopProcesses = true;
-    else if (arg === '--include-app-data') result.includeAppData = true;
-    else if (arg === '--include-voice-data') result.includeVoiceData = true;
-    else if (arg === '--include-user-state') result.includeUserState = true;
-    else if (arg === '--include-wsl') result.includeWsl = true;
-    else if (arg === '--include-remote') result.includeRemote = true;
-    else if (arg === '--include-project-state') result.includeProjectState = true;
-    else if (arg === '--json') result.json = true;
-    else if (arg === '-v' || arg === '--version') result.version = true;
-    else if (arg === '-h' || arg === '--help') result.help = true;
-    else if (arg === '--project') result.projects.push(requireValue(arg, args));
-    else if (arg === '--wsl-home') result.wslHomes.push(requireValue(arg, args));
-    else if (arg === '--remote-home') result.remoteHomes.push(requireValue(arg, args));
-    else if (arg === '--voice-model-path') result.customVoicePaths.push(requireValue(arg, args));
-    else if (arg === '--backup-root') result.backupRoot = requireValue(arg, args);
-    else if (arg === '--manifest') result.manifestPath = requireValue(arg, args);
-    else throw new Error(`알 수 없는 옵션입니다: ${arg}`);
-  }
-  if (!['scan', 'clean', 'restore', 'verify'].includes(result.command)) throw new Error(`알 수 없는 명령입니다: ${result.command}`);
-  if (['restore', 'verify'].includes(result.command) && !result.manifestPath && !result.help && !result.version) {
-    throw new Error(`${result.command}에는 --manifest <경로>가 필요합니다.`);
-  }
-  return result;
-}
-
-function requireValue(option, args) {
-  const value = args.shift();
-  if (!value || value.startsWith('--')) throw new Error(`${option} 뒤에 경로가 필요합니다.`);
-  return value;
-}
-
-function icon(kind) {
-  return ({ skill: '🧩', 'skill-lock': '🔒', hook: '🪝', 'shared-state': '🔗',
-    'skill-transaction': '🧹', extension: '🧱', 'app-data': '🗂️', 'voice-data': '🎙️',
-    'user-state': '🔐', 'wsl-state': '🐧', 'remote-state': '🌐', cli: '⌨️',
-    'project-state': '📁', 'app-installed': '⛔', 'app-running': '⛔', process: '⚙️',
-    'path-entry': '🛣️', unverified: '🛡️' })[kind] || '•';
-}
-
-function printScan(findings) {
-  console.log('\nOrca Agent Cleanup 검사 결과\n');
-  if (!findings.length) {
-    console.log('✅ 확인된 Orca 잔재가 없습니다.');
-    return;
-  }
-  for (const item of findings) {
-    const option = item.requires ? ` [정리 시 --${item.requires.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`)} 필요]` : '';
-    console.log(`${icon(item.kind)} ${item.path}`);
-    console.log(`   ${item.reason}${option}`);
-  }
-  console.log(`\n총 ${findings.length}개가 확인되었습니다. 검사만 수행했으며 변경 사항은 없습니다.`);
-  if (findings.some((item) => ['app-installed', 'app-running'].includes(item.kind))) {
-    console.log('\n⛔ Orca 앱이 아직 설치돼 있거나 실행 중입니다. 앱이 켜질 때 훅을 다시 설치하므로 먼저 앱을 제거하세요. 그 전까지 clean은 멈춥니다.');
-  }
-}
-
-function printClean(result) {
-  console.log(`\nOrca Agent Cleanup ${result.dryRun ? '미리보기' : '정리 결과'}\n`);
-  if (result.blocked && !result.dryRun) {
-    console.log(`⛔ ${result.errors[0].message}`);
-    return;
-  }
-  if (result.blocked) {
-    console.log('⛔ Orca 앱이 아직 설치돼 있거나 실행 중입니다. 실제 clean은 앱을 제거하기 전까지 멈춥니다.\n');
-  }
-  if (!result.actions.length) {
-    console.log('✅ 정리할 항목이 없습니다.');
-    return;
-  }
-  const labels = {
-    quarantined: '✅ 격리', edited: '✅ 수정', 'would-quarantine': '🔎 격리 예정',
-    'would-edit': '🔎 수정 예정', skipped: '⏭️ 옵션 제외', covered: '↳ 상위 상태에 포함',
-    unchanged: '➖ 변경 없음', error: '❌ 오류',
-    'pending-quarantine': '⚠️ 격리 상태 확인 필요', 'pending-edit': '⚠️ 수정 상태 확인 필요',
-    stopped: '✅ 프로세스 끔', 'would-stop': '🔎 프로세스 끌 예정',
-  };
-  for (const item of result.actions) console.log(`${labels[item.action] || item.action}  ${item.path}`);
-  if (!result.dryRun && result.actions.some((item) => ['quarantined', 'edited'].includes(item.action))) {
-    console.log(`\n복구용 백업: ${result.backupRoot}`);
-  }
-  if (result.errors.length) console.log(`\n⚠️ ${result.errors.length}개 항목은 자동 처리하지 못했습니다. 위 오류를 확인하세요.`);
-}
-
-function printRestore(result) {
-  console.log(`\nOrca Agent Cleanup ${result.dryRun ? '복원 미리보기' : '복원 결과'}\n`);
-  if (result.cleanupStatus === 'in-progress') {
-    console.log('⚠️ 중단된 정리 journal을 복구합니다. 해시 기록 전 중단된 항목은 백업 존재 여부로 판정합니다.\n');
-  }
-  if (!result.actions.length) {
-    console.log('✅ manifest에 복원할 완료 작업이 없습니다.');
-    return;
-  }
-  const labels = {
-    restored: '✅ 복원', 'would-restore': '🔎 복원 예정',
-    'already-restored': '➖ 이미 복원됨', error: '❌ 오류',
-  };
-  for (const item of result.actions) {
-    console.log(`${labels[item.action] || item.action}  ${item.path}`);
-    if (item.conflictBackup) console.log(`   현재 항목 보존: ${item.conflictBackup}`);
-  }
-  if (result.reportPath) console.log(`\n복원 보고서: ${result.reportPath}`);
-  if (result.errors.length) console.log(`\n⚠️ ${result.errors.length}개 항목은 복원하지 못했습니다.`);
-}
-
-function printVerify(result) {
-  console.log('\nOrca Agent Cleanup 백업 검증 결과\n');
-  const labels = {
-    verified: '✅ 검증됨', 'not-recorded': 'ℹ️ v1 해시 없음',
-    'not-applied': '➖ 미적용', 'recoverable-unverified': '⚠️ 중단 작업', error: '❌ 오류',
-  };
-  for (const item of result.actions) console.log(`${labels[item.status] || item.status}  ${item.backup || item.path}`);
-  console.log(result.valid ? '\n✅ manifest와 백업을 사용할 수 있습니다.' : `\n❌ ${result.errors.length}개 오류가 있습니다.`);
-}
-
-try {
-  const options = parseArgs(process.argv.slice(2));
-  if (options.version) {
-    console.log(VERSION);
-    process.exit(0);
-  } else if (options.help) {
-    console.log(HELP.trim());
-    process.exit(0);
-  }
-  if (options.command === 'verify') {
-    const result = verifyOrcaBackup(options.manifestPath, options);
-    if (options.json) console.log(JSON.stringify(result, null, 2));
-    else printVerify(result);
-    if (!result.valid) process.exitCode = 2;
-  } else if (options.command === 'restore') {
-    const result = restoreOrcaBackup(options.manifestPath, options);
-    if (options.json) console.log(JSON.stringify(result, null, 2));
-    else printRestore(result);
-    if (result.errors.length) process.exitCode = 2;
-  } else if (options.command === 'scan') {
-    const context = buildContext(options);
-    const findings = scanOrcaResidue(context);
-    if (options.json) console.log(JSON.stringify({ platform: context.platform, officialSkills: OFFICIAL_ORCA_SKILLS, findings }, null, 2));
-    else printScan(findings);
-  } else {
-    const context = buildContext(options);
-    const result = cleanOrcaResidue(context, options);
-    if (options.json) console.log(JSON.stringify(result, null, 2));
-    else printClean(result);
-    if (result.errors.length) process.exitCode = 2;
-  }
-} catch (error) {
-  console.error(`오류: ${error.message}`);
-  console.error('도움말: npx orca-agent-cleanup --help');
-  process.exitCode = 1;
-}
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import process from 'node:process';
+import {
+  buildContext,
+  cleanOrcaResidue,
+  OFFICIAL_ORCA_SKILLS,
+  restoreOrcaBackup,
+  scanOrcaResidue,
+  verifyOrcaBackup,
+} from './orca-cleanup-core.mjs';
+
+const VERSION = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+
+const HELP = `
+Orca Agent Cleanup v${VERSION} : Windows·macOS·Linux 공통 정리 도구
+
+사용법:
+  npx orca-agent-cleanup scan [옵션]
+  npx orca-agent-cleanup clean [옵션]
+  npx orca-agent-cleanup restore --manifest <manifest.json> [옵션]
+  npx orca-agent-cleanup verify --manifest <manifest.json> [옵션]
+
+저장소에서 직접 실행할 때는 npx orca-agent-cleanup 대신 node scripts/orca-agent-cleanup.mjs를 씁니다.
+
+명령:
+  scan                         잔재를 검사합니다(기본 명령, 변경 없음).
+  clean                        확인된 잔재를 백업 폴더로 격리합니다.
+  restore                      manifest에 기록된 파일과 설정을 복원합니다.
+  verify                       manifest와 백업 내용의 무결성을 검사합니다.
+
+옵션:
+  --dry-run                    clean의 예정 작업만 표시합니다.
+  --stop-processes             앱 없이 남아 도는 Orca 백그라운드 프로세스를 끕니다.
+  --force                      Orca 앱이 설치·실행 중이어도 정리합니다(권장하지 않음).
+  --include-app-data           Orca 앱 데이터·캐시를 포함합니다.
+  --include-voice-data         별도 음성 모델 캐시를 포함합니다.
+  --include-user-state         ~/.orca 전체(자격증명·세션 포함)를 포함합니다.
+  --include-wsl                실행 중인 WSL 배포판의 Orca 잔재를 검사·정리합니다.
+  --wsl-home <경로>            WSL 홈 경로를 직접 추가합니다(반복 가능).
+  --include-remote             SSH 릴레이·원격 세션 잔재를 포함합니다.
+  --remote-home <경로>         접근 가능한 원격 홈 경로를 추가합니다(반복 가능).
+  --include-project-state      --project의 .orca·worktree 휴지통을 포함합니다.
+  --project <경로>             프로젝트 스킬 위치를 추가합니다(반복 가능).
+  --voice-model-path <경로>    사용자 지정 음성 모델 경로를 포함합니다(반복 가능).
+  --backup-root <경로>         격리·백업 폴더를 지정합니다.
+  --manifest <경로>            restore·verify에 사용할 manifest.json을 지정합니다.
+  --json                       결과를 JSON으로 출력합니다.
+  -v, --version                버전을 표시합니다.
+  -h, --help                   도움말을 표시합니다.
+
+예시:
+  npx orca-agent-cleanup scan
+  npx orca-agent-cleanup clean --dry-run --include-app-data --include-voice-data --stop-processes
+  npx orca-agent-cleanup clean --include-app-data --include-voice-data --stop-processes
+  npx orca-agent-cleanup restore --dry-run --manifest /path/to/manifest.json
+`;
+
+function parseArgs(argv) {
+  const result = {
+    command: 'scan', projects: [], customVoicePaths: [], wslHomes: [], remoteHomes: [], json: false,
+    dryRun: false, force: false, stopProcesses: false, includeAppData: false, includeVoiceData: false,
+    includeUserState: false, includeWsl: false, includeRemote: false, includeProjectState: false,
+  };
+  const args = [...argv];
+  if (args[0] && !args[0].startsWith('-')) result.command = args.shift();
+  while (args.length) {
+    const arg = args.shift();
+    if (arg === '--dry-run') result.dryRun = true;
+    else if (arg === '--force') result.force = true;
+    else if (arg === '--stop-processes') result.stopProcesses = true;
+    else if (arg === '--include-app-data') result.includeAppData = true;
+    else if (arg === '--include-voice-data') result.includeVoiceData = true;
+    else if (arg === '--include-user-state') result.includeUserState = true;
+    else if (arg === '--include-wsl') result.includeWsl = true;
+    else if (arg === '--include-remote') result.includeRemote = true;
+    else if (arg === '--include-project-state') result.includeProjectState = true;
+    else if (arg === '--json') result.json = true;
+    else if (arg === '-v' || arg === '--version') result.version = true;
+    else if (arg === '-h' || arg === '--help') result.help = true;
+    else if (arg === '--project') result.projects.push(requireValue(arg, args));
+    else if (arg === '--wsl-home') result.wslHomes.push(requireValue(arg, args));
+    else if (arg === '--remote-home') result.remoteHomes.push(requireValue(arg, args));
+    else if (arg === '--voice-model-path') result.customVoicePaths.push(requireValue(arg, args));
+    else if (arg === '--backup-root') result.backupRoot = requireValue(arg, args);
+    else if (arg === '--manifest') result.manifestPath = requireValue(arg, args);
+    else throw new Error(`알 수 없는 옵션입니다: ${arg}`);
+  }
+  if (!['scan', 'clean', 'restore', 'verify'].includes(result.command)) throw new Error(`알 수 없는 명령입니다: ${result.command}`);
+  if (['restore', 'verify'].includes(result.command) && !result.manifestPath && !result.help && !result.version) {
+    throw new Error(`${result.command}에는 --manifest <경로>가 필요합니다.`);
+  }
+  return result;
+}
+
+function requireValue(option, args) {
+  const value = args.shift();
+  if (!value || value.startsWith('--')) throw new Error(`${option} 뒤에 경로가 필요합니다.`);
+  return value;
+}
+
+function icon(kind) {
+  return ({ skill: '🧩', 'skill-lock': '🔒', hook: '🪝', 'shared-state': '🔗',
+    'skill-transaction': '🧹', extension: '🧱', 'app-data': '🗂️', 'voice-data': '🎙️',
+    'user-state': '🔐', 'wsl-state': '🐧', 'remote-state': '🌐', cli: '⌨️',
+    'project-state': '📁', 'app-installed': '⛔', 'app-running': '⛔', process: '⚙️',
+    'path-entry': '🛣️', unverified: '🛡️' })[kind] || '•';
+}
+
+function printScan(findings) {
+  console.log('\nOrca Agent Cleanup 검사 결과\n');
+  if (!findings.length) {
+    console.log('✅ 확인된 Orca 잔재가 없습니다.');
+    return;
+  }
+  for (const item of findings) {
+    const option = item.requires ? ` [정리 시 --${item.requires.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`)} 필요]` : '';
+    console.log(`${icon(item.kind)} ${item.path}`);
+    console.log(`   ${item.reason}${option}`);
+  }
+  console.log(`\n총 ${findings.length}개가 확인되었습니다. 검사만 수행했으며 변경 사항은 없습니다.`);
+  if (findings.some((item) => ['app-installed', 'app-running'].includes(item.kind))) {
+    console.log('\n⛔ Orca 앱이 아직 설치돼 있거나 실행 중입니다. 앱이 켜질 때 훅을 다시 설치하므로 먼저 앱을 제거하세요. 그 전까지 clean은 멈춥니다.');
+  }
+}
+
+function printClean(result) {
+  console.log(`\nOrca Agent Cleanup ${result.dryRun ? '미리보기' : '정리 결과'}\n`);
+  if (result.blocked && !result.dryRun) {
+    console.log(`⛔ ${result.errors[0].message}`);
+    return;
+  }
+  if (result.blocked) {
+    console.log('⛔ Orca 앱이 아직 설치돼 있거나 실행 중입니다. 실제 clean은 앱을 제거하기 전까지 멈춥니다.\n');
+  }
+  if (!result.actions.length) {
+    console.log('✅ 정리할 항목이 없습니다.');
+    return;
+  }
+  const labels = {
+    quarantined: '✅ 격리', edited: '✅ 수정', 'would-quarantine': '🔎 격리 예정',
+    'would-edit': '🔎 수정 예정', skipped: '⏭️ 옵션 제외', covered: '↳ 상위 상태에 포함',
+    unchanged: '➖ 변경 없음', error: '❌ 오류',
+    'pending-quarantine': '⚠️ 격리 상태 확인 필요', 'pending-edit': '⚠️ 수정 상태 확인 필요',
+    stopped: '✅ 프로세스 끔', 'would-stop': '🔎 프로세스 끌 예정',
+  };
+  for (const item of result.actions) console.log(`${labels[item.action] || item.action}  ${item.path}`);
+  if (!result.dryRun && result.actions.some((item) => ['quarantined', 'edited'].includes(item.action))) {
+    console.log(`\n복구용 백업: ${result.backupRoot}`);
+  }
+  if (result.errors.length) console.log(`\n⚠️ ${result.errors.length}개 항목은 자동 처리하지 못했습니다. 위 오류를 확인하세요.`);
+}
+
+function printRestore(result) {
+  console.log(`\nOrca Agent Cleanup ${result.dryRun ? '복원 미리보기' : '복원 결과'}\n`);
+  if (result.cleanupStatus === 'in-progress') {
+    console.log('⚠️ 중단된 정리 journal을 복구합니다. 해시 기록 전 중단된 항목은 백업 존재 여부로 판정합니다.\n');
+  }
+  if (!result.actions.length) {
+    console.log('✅ manifest에 복원할 완료 작업이 없습니다.');
+    return;
+  }
+  const labels = {
+    restored: '✅ 복원', 'would-restore': '🔎 복원 예정',
+    'already-restored': '➖ 이미 복원됨', error: '❌ 오류',
+  };
+  for (const item of result.actions) {
+    console.log(`${labels[item.action] || item.action}  ${item.path}`);
+    if (item.conflictBackup) console.log(`   현재 항목 보존: ${item.conflictBackup}`);
+  }
+  if (result.reportPath) console.log(`\n복원 보고서: ${result.reportPath}`);
+  if (result.errors.length) console.log(`\n⚠️ ${result.errors.length}개 항목은 복원하지 못했습니다.`);
+}
+
+function printVerify(result) {
+  console.log('\nOrca Agent Cleanup 백업 검증 결과\n');
+  const labels = {
+    verified: '✅ 검증됨', 'not-recorded': 'ℹ️ v1 해시 없음',
+    'not-applied': '➖ 미적용', 'recoverable-unverified': '⚠️ 중단 작업', error: '❌ 오류',
+  };
+  for (const item of result.actions) console.log(`${labels[item.status] || item.status}  ${item.backup || item.path}`);
+  console.log(result.valid ? '\n✅ manifest와 백업을 사용할 수 있습니다.' : `\n❌ ${result.errors.length}개 오류가 있습니다.`);
+}
+
+try {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.version) {
+    console.log(VERSION);
+    process.exit(0);
+  } else if (options.help) {
+    console.log(HELP.trim());
+    process.exit(0);
+  }
+  if (options.command === 'verify') {
+    const result = verifyOrcaBackup(options.manifestPath, options);
+    if (options.json) console.log(JSON.stringify(result, null, 2));
+    else printVerify(result);
+    if (!result.valid) process.exitCode = 2;
+  } else if (options.command === 'restore') {
+    const result = restoreOrcaBackup(options.manifestPath, options);
+    if (options.json) console.log(JSON.stringify(result, null, 2));
+    else printRestore(result);
+    if (result.errors.length) process.exitCode = 2;
+  } else if (options.command === 'scan') {
+    const context = buildContext(options);
+    const findings = scanOrcaResidue(context);
+    if (options.json) console.log(JSON.stringify({ platform: context.platform, officialSkills: OFFICIAL_ORCA_SKILLS, findings }, null, 2));
+    else printScan(findings);
+  } else {
+    const context = buildContext(options);
+    const result = cleanOrcaResidue(context, options);
+    if (options.json) console.log(JSON.stringify(result, null, 2));
+    else printClean(result);
+    if (result.errors.length) process.exitCode = 2;
+  }
+} catch (error) {
+  console.error(`오류: ${error.message}`);
+  console.error('도움말: npx orca-agent-cleanup --help');
+  process.exitCode = 1;
+}