careermate 0.0.4 → 0.0.5

package/docs/MCP_TOOLS.md

@@ -2,7 +2,7 @@
 
 CareerMate는 **MCP-우선** 로컬 커리어 관리 도구입니다. 사용자는 자신의 ChatGPT/Claude/Gemini와 대화하고, 그 AI가 여기 정의된 MCP 도구를 호출해 로컬 커리어 DB(`~/.careermate/careermate.sqlite`)를 읽고 씁니다. **CareerMate 내부에는 LLM이 없습니다.** 적합도 분석·자기소개서 작성 같은 추론은 모두 사용자의 AI가 수행하고, CareerMate는 데이터를 저장하고 다시 돌려주는 역할만 합니다.
 
-이 문서는 `packages/mcp-tools/src/tools.ts`에 정의된 커리어 워크플로 **35개 도구**의 레퍼런스입니다. 도구의 입력 파라미터는 `packages/shared/src/schemas.ts`의 zod 스키마와 일치합니다.
+이 문서는 `packages/mcp-tools/src/tools.ts`에 정의된 커리어 워크플로 **37개 도구**의 레퍼런스입니다. 도구의 입력 파라미터는 `packages/shared/src/schemas.ts`의 zod 스키마와 일치합니다.
 
 > 설계 원칙: 이 도구들은 단순 CRUD 래퍼가 아닙니다. 각 도구는 AI가 사용자를 대신해 수행하는 실제 작업에 대응하며, 설명에 *언제* 그리고 *어떻게* 호출해야 하는지가 담겨 있습니다. 가장 중요한 도구는 [`get_application_context`](#get_application_context-) 입니다.
 
@@ -16,7 +16,7 @@ CareerMate는 **MCP-우선** 로컬 커리어 관리 도구입니다. 사용자
 
 | 읽기전용(✅) 도구 | 쓰기/부수효과(✏️) 도구 |
 | --- | --- |
-| `read_document`, `read_inbox`, `get_onboarding_status`, `get_profile`, `get_resumes`, `get_experiences`, `get_projects`, `get_skills`, `get_cover_letters`, `get_job_posting`, `list_jobs`, `get_application_context`, `list_recent_activity`, `get_workflow_guide`, `get_playbook`, `get_verifier`, `validate_cover_letter`, `get_writing_style_guide`, `check_for_update` | `open_inbox`, `save_profile`, `add_resume`, `add_experience`, `add_project`, `add_skill`, `save_cover_letter_version`, `set_verify_mode`, `save_job_posting`, `save_fit_analysis`, `update_application_status`, `save_interview_prep`, `export_cover_letter`, `open_dashboard`, `open_application`, `update_careermate` |
+| `read_document`, `read_inbox`, `get_onboarding_status`, `get_profile`, `get_resumes`, `get_experiences`, `get_projects`, `get_skills`, `get_cover_letters`, `get_job_posting`, `list_jobs`, `get_application_context`, `list_recent_activity`, `get_workflow_guide`, `get_playbook`, `get_verifier`, `validate_cover_letter`, `get_writing_style_guide`, `check_for_update` | `open_inbox`, `save_profile`, `add_resume`, `add_experience`, `add_project`, `add_skill`, `save_cover_letter_version`, `delete_cover_letter`, `set_verify_mode`, `save_job_posting`, `delete_job_posting`, `save_fit_analysis`, `update_application_status`, `save_interview_prep`, `export_cover_letter`, `open_dashboard`, `open_application`, `update_careermate` |
 
 ---
 
@@ -117,6 +117,7 @@ AI 클라이언트가 연결되면 이 도구를 가장 먼저 호출해 상태
 | --- | --- | --- | --- | --- | --- |
 | `get_cover_letters` | 저장된 자기소개서 조회(공고별 필터 가능). 각 항목은 현재 버전 내용·버전 수 포함 | `job_id?` | `CoverLetterRecord[]` | 자소서 목록/내용을 확인할 때 | ✅ |
 | `save_cover_letter_version` | 자기소개서의 새 버전 저장 — 자소서 작성 워크플로우의 핵심 저장 단계 | `content`(필수), `cover_letter_id?`, `title?`, `job_id?`, `note?`, `source?`, `set_current?` | `{ coverLetter, version }` | 새 공고용 자소서를 생성·갱신해 버전으로 남길 때 | ✏️ |
+| `delete_cover_letter` | 자기소개서 삭제(모든 버전 포함) | `cover_letter_id`, `confirm:"DELETE"` | 삭제 결과 | 사용자가 목록에서 삭제 대상을 확인한 뒤 | ✏️ |
 
 `save_cover_letter_version` 동작(`CoverLetterVersionInputSchema`):
 
@@ -127,6 +128,8 @@ AI 클라이언트가 연결되면 이 도구를 가장 먼저 호출해 상태
 
 > 기존 자소서를 학습용으로 보관하든 새 공고용 자소서를 새로 쓰든, 저장은 모두 `save_cover_letter_version`으로 합니다. `title`+`content`만 주면 새 자소서의 v1로 저장됩니다.
 
+`delete_cover_letter`는 되돌릴 수 없는 작업이므로, 먼저 `get_cover_letters`로 목록을 확인하고 사용자가 삭제할 항목을 명확히 고른 뒤 호출합니다. 삭제된 자기소개서의 버전은 함께 사라지며, 연결된 지원 기록은 자기소개서 연결만 비워집니다.
+
 ---
 
 ## 5. 채용공고 (Jobs)
@@ -136,10 +139,12 @@ AI 클라이언트가 연결되면 이 도구를 가장 먼저 호출해 상태
 | `save_job_posting` | 채용공고 저장(있으면 갱신). 저장 시 지원(application) 항목 자동 생성 | `company`, `position`(필수), `url?`, `location?`, `employment_type?`, `description?`, `requirements?`, `keywords?`, `deadline?`, `source?` | 저장된 `JobRecord`(`job_id` 포함) | 공고를 DB에 등록/갱신할 때 | ✏️ |
 | `get_job_posting` | 공고 1건 상세 조회 | `job_id` | `{ job, fit, application, cover_letters, interview }` | 한 공고의 분석·상태·자소서·면접 자료를 한 번에 볼 때 | ✅ |
 | `list_jobs` | 저장된 모든 공고를 지원 상태·적합도 점수와 함께 목록화 | 없음 | 공고 메타 포함 배열 | 전체 공고를 훑어볼 때 | ✅ |
+| `delete_job_posting` | 채용공고 삭제 | `job_id`, `confirm:"DELETE"` | 삭제 결과 | 사용자가 목록에서 삭제 대상을 확인한 뒤 | ✏️ |
 
 - `url`이 같으면 중복 생성 없이 갱신됩니다.
 - `requirements`에는 자격요건/우대사항 핵심, `keywords`에는 핵심 키워드를 정리해 넣으면 이후 적합도 분석·자소서 작성에 활용됩니다.
 - 붙여넣은 공고 원문의 구조화(회사명/직무/마감일/키워드 추출)는 AI가 직접 수행한 뒤 `save_job_posting`으로 저장합니다.
+- `delete_job_posting`은 연결된 지원 상태·적합도 분석·면접 준비를 함께 삭제합니다. 연결된 자기소개서는 삭제하지 않고 공고 연결만 해제합니다.
 
 ---
 
@@ -147,10 +152,11 @@ AI 클라이언트가 연결되면 이 도구를 가장 먼저 호출해 상태
 
 | 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
 | --- | --- | --- | --- | --- | --- |
-| `save_fit_analysis` | AI가 도출한 적합도 분석 결과 저장(같은 공고에 다시 저장하면 갱신) | `job_id`(필수), `score?`(0~100), `summary?`, `strengths?`, `gaps?`, `matched_keywords?`, `missing_keywords?`, `recommendations?` | 저장된 `FitAnalysisRecord` | 공고와 사용자 정보를 비교 분석한 결과를 저장할 때 | ✏️ |
+| `save_fit_analysis` | AI가 도출한 적합도 분석 결과 저장(같은 공고에 다시 저장하면 갱신) | `job_id`(필수), `score?`(0~100), `summary?`, `strengths?`, `gaps?`, `matched_keywords?`, `missing_keywords?`, `recommendations?` | 저장된 `FitAnalysisRecord` + `suggested_next_action` | 공고와 사용자 정보를 비교 분석한 결과를 저장할 때 | ✏️ |
 
 - `job_id`는 필수이며, 먼저 `save_job_posting`으로 공고가 저장되어 있어야 합니다.
 - 분석 자체는 AI가 수행하고, 이 도구는 결과만 저장합니다. 분석 전에는 반드시 [`get_application_context`](#get_application_context-)로 맥락을 가져오세요.
+- 저장 후 응답에는 "이 공고에 맞춘 자기소개서를 써드릴까요?" 선택지가 함께 제공됩니다. AI는 곧장 작성하지 말고 사용자가 "네"를 고른 경우에만 자기소개서 작성 흐름으로 이어갑니다.
 
 ---
 
@@ -283,6 +289,7 @@ CareerMate를 최신 버전으로 유지하기 위한 유지보수 도구입니
 | `update_careermate` | 설치 폴더에 `careermate@latest`를 npm으로 설치해 최신 버전으로 업데이트 | 없음 | 업데이트 결과(`{ ok, message, manual? }`) | 사용자가 명시적으로 "업데이트해줘"라고 할 때만 | ✏️ |
 
 - `check_for_update`는 확인만 하며 데이터를 변경하지 않습니다. 새 버전이 있으면 `update_careermate`로 적용하세요.
+- 사용자가 "업데이트해줘", "CareerMate 업데이트해줘", "최신으로 올려줘"처럼 적용을 명시하면 `update_careermate`를 바로 호출합니다. 이 도구가 최신 버전 확인도 함께 하므로 별도 확인 질문은 필요 없습니다.
 - `update_careermate` 성공 후에는 적용을 위해 AI 앱(또는 MCP 연결) **재시작**이 필요합니다. 재시작 시 데이터베이스는 자동 마이그레이션되어 기존 데이터가 보존됩니다.
 - 자동 설치가 막히면(개발 모드·비표준 설치) 직접 칠 명령(`manual`)을 안내합니다.
 

package/docs/WORKFLOWS.md

@@ -8,7 +8,7 @@ CareerMate는 내부에 LLM을 두지 않는다. 분석과 작성은 사용자
 
 - 연결 직후 AI가 따라가는 시작 런북은 [시작 런북](./START_WORKFLOW.md)을 참고한다.
 - 설치·연결 절차는 [설치 런북](../INSTALL.md)(또는 [지원 앱·설치 레퍼런스](./SUPPORTED_AI_APPS.md))을 참고한다.
-- MCP 도구 31종의 입출력 명세는 코드(`packages/mcp-tools/src/tools.ts`)에 정의되어 있으며, AI는 각 도구의 `inputSchema`로 직접 확인할 수 있다.
+- MCP 도구 37종의 입출력 명세는 코드(`packages/mcp-tools/src/tools.ts`)에 정의되어 있으며, AI는 각 도구의 `inputSchema`로 직접 확인할 수 있다.
 
 ## 워크플로우 5종 개요
 
@@ -74,8 +74,8 @@ get_onboarding_status
 4. **공고 저장** — 아직 저장되지 않은 공고라면 `save_job_posting`으로 공고를 저장하고 `job_id`를 확보한다.
 5. **분석 저장** — 도출한 분석 결과를 `save_fit_analysis`로 저장한다(`job_id`, `score`, `summary`, `strengths`, `gaps`, `matched_keywords`, `missing_keywords`, `recommendations`).
 6. **사용자 설명** — 분석 결과를 사용자에게 쉬운 한국어로 설명한다(잘 맞는 점, 보완할 점, 추천 전략). 기술 용어는 빼고 전달한다.
-7. **자소서 제안** — "이 공고에 맞춘 자기소개서를 써드릴까요?"라고 자기소개서 작성을 제안한다.
-8. **동의 시 자소서 저장** — 사용자가 동의하면 적합도 분석과 글쓰기 선호를 반영해 자기소개서를 작성하고 `save_cover_letter_version`으로 저장한다(`job_id` 연결, `note`에 작성 의도 요약).
+7. **자소서 선택 제안** — 분석 뒤 곧장 자기소개서를 쓰지 말고 "이 공고에 맞춘 자기소개서를 써드릴까요?"라고 묻고 선택지를 제시한다: ① "네, 이 공고에 맞춘 자기소개서를 써줘" ② "아니요, 분석만 저장해줘".
+8. **동의 시 자소서 저장** — 사용자가 ①을 선택하면 적합도 분석과 글쓰기 선호를 반영해 자기소개서를 작성하고 `save_cover_letter_version`으로 저장한다(`job_id` 연결, `note`에 작성 의도 요약). ②를 선택하면 자소서 작성 없이 멈추고 저장 결과와 대시보드 확인만 안내한다.
 9. **지원 건 열기** — `open_application`으로 해당 지원 건을 열어 사용자가 결과를 확인하게 하고, 지원 상태 변경(예: 지원 예정/지원 완료)을 제안한다.
 
 **도구 호출 순서 요약(정식 흐름):**
@@ -87,8 +87,8 @@ get_onboarding_status
   → save_job_posting                  # 미저장 공고일 때만, job_id 확보
   → save_fit_analysis                 # job_id 연결
   → (사용자에게 쉬운 한국어로 설명)
-  → (자기소개서 작성 제안)
-  → save_cover_letter_version         # 사용자 동의 시에만, job_id·note
+  → (자기소개서 작성 여부 선택지 제안)
+  → save_cover_letter_version         # 사용자가 "네"를 선택한 경우에만, job_id·note
   → open_application                  # 결과 확인 + 상태 변경 제안
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "careermate",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "type": "module",
   "description": "CareerMate — an MCP-first, local-first career workspace. Connect it to a local AI agent (Claude Desktop, Claude Code, Codex); CareerMate stores your career data locally on your machine and exposes it over MCP.",
   "license": "MIT",
@@ -66,7 +66,7 @@
     "shots:seed": "node --no-warnings --experimental-sqlite --import tsx scripts/shots-seed.ts",
     "shots": "node --no-warnings --experimental-sqlite --import tsx scripts/shots.ts",
     "doctor": "node --no-warnings --experimental-sqlite --import tsx scripts/doctor.ts",
-    "test": "node --no-warnings scripts/run.mjs scripts/test-init.ts \"INIT_TEST_VERDICT PASS\" && node --no-warnings scripts/run.mjs scripts/test.ts \"TEST_VERDICT PASS\"",
+    "test": "node --no-warnings scripts/run.mjs scripts/test-init.ts \"INIT_TEST_VERDICT PASS\" && node --no-warnings scripts/run.mjs scripts/test-bridge.ts \"BRIDGE_TEST_VERDICT PASS\" && node --no-warnings scripts/run.mjs scripts/test.ts \"TEST_VERDICT PASS\"",
     "test:ui": "node --no-warnings scripts/run.mjs scripts/ui-smoke.ts \"UI_VERDICT PASS\"",
     "typecheck": "tsc --noEmit"
   },

package/packages/core/src/services.ts

@@ -202,7 +202,7 @@ export function saveJobPosting(input: JobInput, id?: string): { job: JobRecord;
 
 export function saveFitAnalysis(input: FitAnalysisInput): FitAnalysisRecord {
   const job = jobRepo.get(input.job_id);
-  if (!job) throw notFound(`공고를 찾을 수 없습니다: ${input.job_id}. 먼저 save_job_posting으로 공고를 저장하세요.`);
+  if (!job) throw notFound('공고를 찾을 수 없습니다. 먼저 공고를 저장한 뒤 다시 시도하세요.');
   applicationRepo.ensure(job.id, 'draft');
   const fit = fitRepo.save(input);
   const scoreText = fit.score != null ? ` (적합도 ${fit.score}점)` : '';
@@ -269,7 +269,7 @@ export function updateApplicationStatus(
   note?: string,
 ): StatusChangeResult {
   const job = jobRepo.get(jobId);
-  if (!job) throw notFound(`공고를 찾을 수 없습니다: ${jobId}`);
+  if (!job) throw notFound('공고를 찾을 수 없습니다.');
   const application = applicationRepo.setStatus(jobId, status, note);
   activityRepo.log(
     'application_status_changed',
@@ -282,7 +282,7 @@ export function updateApplicationStatus(
   const hasPrep = !!interviewRepo.getByJob(jobId);
   const hint =
     interview_unlocked && !hasPrep
-      ? '서류 단계를 통과했어요. 이 공고 기준으로 예상 면접 질문과 1분 자기소개를 준비할까요? (save_interview_prep)'
+      ? '서류 단계를 통과했어요. 이 공고 기준으로 예상 면접 질문과 1분 자기소개를 준비할까요?'
       : null;
 
   return { application, job, interview_unlocked, hint };
@@ -292,14 +292,14 @@ export function updateApplicationStatus(
 
 export function saveInterviewPrep(input: InterviewPrepInput): InterviewPrepRecord {
   const job = jobRepo.get(input.job_id);
-  if (!job) throw notFound(`공고를 찾을 수 없습니다: ${input.job_id}`);
+  if (!job) throw notFound('공고를 찾을 수 없습니다.');
   // Spec gate: interview prep is only allowed once the application has reached
   // 서류 합격(document_passed) or beyond. Enforce it server-side, not just in prompts.
   const app = applicationRepo.getByJob(job.id);
   if (!app || !INTERVIEW_UNLOCK_STATUSES.includes(app.status)) {
     const current = app ? APPLICATION_STATUS_LABELS[app.status] : '미지원';
     throw conflict(
-      `면접 준비는 '서류 합격' 이상 상태에서만 저장할 수 있습니다. 현재 상태: '${current}'. 먼저 update_application_status로 상태를 올린 뒤 다시 시도하세요.`,
+      `면접 준비는 '서류 합격' 이상 상태에서만 저장할 수 있습니다. 현재 상태: '${current}'. 먼저 지원 상태를 '서류 합격' 이상으로 바꾼 뒤 다시 시도하세요.`,
     );
   }
   const prep = interviewRepo.save(input);

package/packages/mcp-tools/src/bridge.ts

@@ -3,12 +3,13 @@
  *
  * `open_dashboard` / `open_application` need the running web server's URL. The
  * web server publishes it to a runtime file (see @careermate/db runtime). If the
- * server isn't running we start it (detached) and wait for it to register.
+ * server isn't running we start it in the background and wait for it to register.
  */
-import { spawn, type SpawnOptions } from 'node:child_process';
+import { spawn, spawnSync, type SpawnOptions } from 'node:child_process';
+import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { readRuntimeInfo, isProcessAlive } from '@careermate/db';
+import { getDataDir, readRuntimeInfo, isProcessAlive, type RuntimeInfo } from '@careermate/db';
 import { BUNDLED } from '@careermate/shared';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -19,9 +20,103 @@ export function projectRoot(): string {
   return REPO_ROOT;
 }
 
-function liveServer() {
+const HEALTH_TIMEOUT_MS = 800;
+let pendingStart: Promise<{ url: string } | null> | null = null;
+
+function dashboardLogPath(): string {
+  return path.join(getDataDir(), 'server.log');
+}
+
+function launchdPlistPath(): string {
+  return path.join(getDataDir(), 'dashboard.launchd.plist');
+}
+
+function launchdLabel(): string {
+  let hash = 5381;
+  for (const ch of getDataDir()) hash = ((hash * 33) ^ ch.charCodeAt(0)) >>> 0;
+  return `life.careermate.dashboard.${hash.toString(16)}`;
+}
+
+function xmlEscape(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+function plistString(key: string, value: string): string {
+  return `  <key>${xmlEscape(key)}</key>\n  <string>${xmlEscape(value)}</string>`;
+}
+
+function renderLaunchdPlist(bin: string, args: string[], cwd: string, log: string): string {
+  const env: Record<string, string> = {
+    CAREERMATE_DATA_DIR: getDataDir(),
+    CAREERMATE_NO_OPEN: '1',
+  };
+  if (process.env.CAREERMATE_PORT) env.CAREERMATE_PORT = process.env.CAREERMATE_PORT;
+  if (process.env.PATH) env.PATH = process.env.PATH;
+
+  const programArgs = [bin, ...args].map((arg) => `    <string>${xmlEscape(arg)}</string>`).join('\n');
+  const envEntries = Object.entries(env).map(([key, value]) => `${plistString(key, value)}`).join('\n');
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${xmlEscape(launchdLabel())}</string>
+  <key>ProgramArguments</key>
+  <array>
+${programArgs}
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${xmlEscape(cwd)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+${envEntries}
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <false/>
+  <key>StandardOutPath</key>
+  <string>${xmlEscape(log)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xmlEscape(log)}</string>
+</dict>
+</plist>
+`;
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function pingDashboard(url: string, timeoutMs = HEALTH_TIMEOUT_MS): Promise<boolean> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  timer.unref?.();
+  try {
+    const healthUrl = new URL('/api/health', url);
+    const res = await fetch(healthUrl, {
+      signal: controller.signal,
+      headers: { accept: 'application/json' },
+    });
+    if (!res.ok) return false;
+    const body = (await res.json().catch(() => null)) as { ok?: unknown } | null;
+    return body?.ok === true;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function liveServer(): Promise<RuntimeInfo | null> {
   const info = readRuntimeInfo();
-  if (info && isProcessAlive(info.pid)) return info;
+  if (info && isProcessAlive(info.pid) && await pingDashboard(info.url)) return info;
   return null;
 }
 
@@ -33,36 +128,122 @@ function liveServer() {
  * guards the synchronous spawn() call, not the later event — so attach the
  * listener here. stdio defaults to 'ignore'; callers may override via opts.
  */
-function spawnDetached(cmd: string, args: string[], opts: SpawnOptions = {}): void {
+function spawnDetached(cmd: string, args: string[], opts: SpawnOptions = {}): number | null {
   try {
     const child = spawn(cmd, args, { stdio: 'ignore', detached: true, ...opts });
     child.on('error', () => {
       /* binary missing / spawn failed — best-effort, never crash */
     });
     child.unref();
+    return child.pid ?? null;
   } catch {
     /* best-effort */
+    return null;
   }
 }
 
-/** Start the dashboard server detached and wait until it publishes its address. */
+function spawnViaLaunchd(bin: string, args: string[], cwd: string, log: string): boolean {
+  if (process.platform !== 'darwin' || process.env.CAREERMATE_LAUNCHER === 'detached') return false;
+  if (typeof process.getuid !== 'function') return false;
+
+  const domain = `gui/${process.getuid()}`;
+  const label = launchdLabel();
+  const plist = launchdPlistPath();
+  try {
+    fs.writeFileSync(plist, renderLaunchdPlist(bin, args, cwd, log), 'utf8');
+    // Remove a stale loaded job for the same data dir. If it is not loaded,
+    // launchctl exits non-zero; that is fine and should not block bootstrap.
+    spawnSync('launchctl', ['bootout', `${domain}/${label}`], { stdio: 'ignore' });
+    const res = spawnSync('launchctl', ['bootstrap', domain, plist], {
+      encoding: 'utf8',
+      timeout: 5000,
+    });
+    if (res.status === 0) return true;
+    fs.appendFileSync(log, `[${new Date().toISOString()}] launchctl bootstrap failed: ${res.stderr || res.stdout || res.status}\n`);
+  } catch (e) {
+    try {
+      fs.appendFileSync(log, `[${new Date().toISOString()}] launchctl launch failed: ${e instanceof Error ? e.message : String(e)}\n`);
+    } catch {
+      /* ignore */
+    }
+  }
+  return false;
+}
+
+function spawnDashboardDetached(bin: string, args: string[], cwd: string, logFd: number | null): void {
+  spawnDetached(bin, args, {
+    cwd,
+    env: { ...process.env, CAREERMATE_NO_OPEN: '1' },
+    stdio: logFd === null ? 'ignore' : ['ignore', logFd, logFd],
+  });
+}
+
+/** Start the dashboard server in the background and wait until it publishes its address. */
 export async function ensureServer(timeoutMs = 12000): Promise<{ url: string } | null> {
-  const existing = liveServer();
+  const existing = await liveServer();
   if (existing) return { url: existing.url };
+  if (pendingStart) return pendingStart;
 
+  pendingStart = startServerBackground(timeoutMs);
+  try {
+    return await pendingStart;
+  } finally {
+    pendingStart = null;
+  }
+}
+
+async function startServerBackground(timeoutMs: number): Promise<{ url: string } | null> {
   // prod(번들): dist/web.mjs를 플레인 node로 실행. dev: tsx로 소스 실행.
   const [bin, args, cwd] = BUNDLED
     ? [process.execPath, ['--experimental-sqlite', path.join(__dirname, 'web.mjs')], __dirname]
-    : [process.execPath, ['--no-warnings', '--experimental-sqlite', '--import', 'tsx', 'apps/web/src/index.ts'], REPO_ROOT];
+    : [
+      process.execPath,
+      ['--no-warnings', '--experimental-sqlite', '--import', 'tsx', path.join(REPO_ROOT, 'apps/web/src/index.ts')],
+      REPO_ROOT,
+    ];
   // Spawn failures (sync or async) just leave the server down; the poll loop
   // below then times out and returns null — no crash.
-  spawnDetached(bin as string, args as string[], { cwd: cwd as string, env: { ...process.env, CAREERMATE_NO_OPEN: '1' } });
+  const log = dashboardLogPath();
+  let logFd: number | null = null;
+  try {
+    logFd = fs.openSync(log, 'a');
+    fs.writeSync(logFd, `\n[${new Date().toISOString()}] CareerMate dashboard background launch\n`);
+  } catch {
+    logFd = null;
+  }
+  let launchedViaLaunchd = false;
+  try {
+    launchedViaLaunchd = spawnViaLaunchd(bin as string, args as string[], cwd as string, log);
+    if (!launchedViaLaunchd) spawnDashboardDetached(bin as string, args as string[], cwd as string, logFd);
+  } finally {
+    if (logFd !== null) {
+      try { fs.closeSync(logFd); } catch { /* ignore */ }
+    }
+  }
 
   const start = Date.now();
   while (Date.now() - start < timeoutMs) {
-    const info = liveServer();
+    const info = await liveServer();
     if (info) return { url: info.url };
-    await new Promise((r) => setTimeout(r, 300));
+    await delay(300);
+  }
+
+  // If launchd accepted the job but the server never became healthy, give the
+  // simpler detached path one chance. This protects dev/source installs where
+  // launchd has a thinner environment than the invoking AI client.
+  if (launchedViaLaunchd) {
+    try {
+      fs.appendFileSync(log, `[${new Date().toISOString()}] launchd did not produce a healthy server; falling back to detached spawn\n`);
+    } catch {
+      /* ignore */
+    }
+    spawnDashboardDetached(bin as string, args as string[], cwd as string, null);
+    const fallbackStart = Date.now();
+    while (Date.now() - fallbackStart < Math.min(timeoutMs, 8000)) {
+      const info = await liveServer();
+      if (info) return { url: info.url };
+      await delay(300);
+    }
   }
   return null;
 }
@@ -98,7 +279,7 @@ export function openInFileManager(dir: string): void {
 
 /** Resolve the dashboard URL, starting the server if needed. */
 export async function resolveDashboardUrl(hash = ''): Promise<{ url: string; running: boolean }> {
-  const live = liveServer();
+  const live = await liveServer();
   if (live) return { url: live.url + hash, running: true };
   const started = await ensureServer();
   if (started) return { url: started.url + hash, running: true };