fix(skills): unblock startup on snapshot errors

[zerob13]

Summary

• keep DeepChat startup available when Agent Skill snapshot migration fails
• log the migration error and preserve the incomplete migration for retry on the next launch
• document the non-blocking startup contract and add regression coverage for symbolic-link failures

Root cause

Agent Skill migration ran inside the critical SkillService initialization path. Any snapshot copy or validation error, including a nested symbolic link, rejected SkillService.initialize() and prevented normal application startup.

Impact

Snapshot safety rules remain unchanged: unsafe snapshots are still rejected. The failure is now isolated from application startup, committed Agent scopes remain available, and missing scopes stay empty until migration succeeds on a later launch.

Validation

• pnpm exec vitest run test/main/skill/skillService.test.ts test/main/skill/skillServiceAgentScopes.test.ts (139 tests)
• pnpm run format
• pnpm run i18n
• pnpm run lint
• pnpm run typecheck:node

Summary by CodeRabbit

• Bug Fixes

  • Startup now continues when Agent Skill migration fails.
  • Migration failures are logged and retried during the next launch.
  • Existing Agent roots remain available, while missing roots stay empty instead of using another root.
  • macOS activation is ignored until startup completes.
  • Shutdown continues to wait for Skill initialization and background scans before cleanup.

• Documentation

  • Clarified migration, startup, retry, and shutdown behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 46e21f50-7036-4aea-aa76-941c9faabaa8

📥 Commits

Reviewing files that changed from the base of the PR and between 13f0c6c and 68c658b.

📒 Files selected for processing (4)

• docs/architecture/independent-agent-skills/plan.md
• docs/architecture/independent-agent-skills/spec.md
• src/main/skill/index.ts
• test/main/skill/skillService.test.ts

---

📝 Walkthrough

Walkthrough

SkillService now logs legacy Agent Skill migration failures and continues startup. Documentation describes retryable migration attempts, preserved or empty Agent roots, and shutdown draining, while tests verify the continued initialization path.

Changes

Skill migration startup

Layer / File(s)	Summary
Non-blocking migration startup behavior docs/architecture/independent-agent-skills/{plan.md,spec.md}, src/main/skill/index.ts, test/main/skill/skillService.test.ts	SkillService catches and logs migration failures while continuing initialization; documentation records retry and root-handling semantics, and tests verify subsequent startup steps and initialization state.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• ThinkInAIXYZ/deepchat#2007: Introduces related legacy Agent Skill scope migration behavior used by this startup handling.

Suggested reviewers: zhangmo8

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: startup now continues when snapshot migration errors occur.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/fix-skill-snapshot-symlinks

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}