feat: backfill check + recovery for unanalyzed sessions

[melagiri]

Context

Part of the Native Analysis via Claude Code Hooks feature (Phase 12, v4.8.0).
Plan: docs/plans/2026-03-28-native-analysis-hooks.md

Issue 5 of 6 — Depends on #240 (insights command).

Problem

When the analysis hook fails, or a user installs Code Insights after having existing sessions, unanalyzed sessions accumulate. We need a recovery mechanism.

Solution

code-insights insights check subcommand

code-insights insights check [options]
  --days <n>       Lookback window (default: 7)
  --quiet, -q      Machine-readable output (just count)

Behavior by Count

Unanalyzed (last 7d)	Behavior
0	Silent exit
1-2	Auto-analyze silently (calls insights <id> --native for each)
3-10	Print count + suggest: "Run code-insights insights check --analyze to process them"
11+	Print count + time estimate + suggest command

Query

SELECT s.id, s.title, s.started_at
FROM sessions s
LEFT JOIN analysis_usage au ON au.session_id = s.id AND au.analysis_type = 'session'
WHERE s.started_at > datetime('now', '-7 days')
  AND s.deleted_at IS NULL
  AND au.session_id IS NULL
ORDER BY s.started_at DESC

Optional SessionStart Hook

For automatic detection, users can add a SessionStart hook:

{
  "SessionStart": [{
    "hooks": [{ "type": "command", "command": "node <cli> insights check -q" }]
  }]
}

This is informational only (prints a notice), not installed by default.

Acceptance Criteria

• insights check queries unanalyzed sessions in last 7 days
• 1-2 sessions: auto-analyzes with --native
• 3+ sessions: prints suggestion message with count
• --days <n> overrides lookback window
• --quiet outputs just the count (for scripting)
• --analyze flag processes all found sessions
• Progress output during batch processing: [1/8] session-title ... done (12s)
• Non-blocking — single notice, no nag on repeat invocations

[melagiri]

Dev Handoff — insights check (PM)

What's already there

cli/src/commands/insights.ts lines 323-362 has a working stub for insightsCheckCommand. It already:

• Queries unanalyzed sessions via LEFT JOIN on analysis_usage
• Computes the cutoff from --days
• Handles --quiet (prints count only)
• Prints a generic yellow notice + dim suggestion line

This is not a from-scratch task. Expand the stub — don't replace it.

CLI wiring is already in cli/src/index.ts lines 136-143. You need to add the --analyze flag there.

What's missing (the actual work)

The stub prints a generic message for any count > 0. The full spec requires tiered behavior:

Count	Required behavior
0	Silent exit (already works)
1-2	Auto-analyze silently with --native (no flag needed)
3-10	Print count + suggest code-insights insights check --analyze
11+	Print count + time estimate (~15s/session) + suggest command

Plus:

1. --analyze flag — batch-process all found sessions calling runInsightsCommand for each
2. Progress line per session: [1/8] session-title ... done (12s)
3. The query needs s.title in addition to s.id (title exists in sessions table)
4. --days override already wired in CLI, just needs to flow correctly into the function

File pointers

File	Lines	Purpose
cli/src/commands/insights.ts	323-362	Stub to expand
cli/src/commands/__tests__/insights.test.ts	entire file	Add insightsCheckCommand describe block here
cli/src/index.ts	136-143	Add --analyze option to check subcommand

Key import already available in insights.ts: runInsightsCommand — use it directly for the auto-analyze and --analyze paths.

TDD requirements

Write tests before implementing. Add a new describe('insightsCheckCommand', ...) block to cli/src/commands/__tests__/insights.test.ts. The existing mock setup (mockDb, seedSession, etc.) is reusable.

Testable acceptance criteria:

Test	Input	Expected
0 unanalyzed	0 sessions in window	No output, no error, returns cleanly
quiet + 0	0 sessions, --quiet	No output
quiet + N	3 sessions, --quiet	Writes "3\n" to stdout
1-2 auto-analyze	1 session in DB, no --analyze	Calls runInsightsCommand once with { native: true }
2 auto-analyze	2 sessions in DB, no --analyze	Calls runInsightsCommand twice
3+ suggest	5 sessions	Does NOT call runInsightsCommand, prints suggestion
11+ time estimate	12 sessions	Prints estimate (~3 min), prints suggestion
--analyze	5 sessions + flag	Calls runInsightsCommand 5 times, prints progress
progress format	3 sessions + --analyze	Each line matches [N/3] title ... done (Xs)
--days override	14-day cutoff	Query uses 14-day window

Implementation notes

• The auto-analyze path (1-2 sessions) should call runInsightsCommand({ sessionId, native: true, quiet: true }) — use native runner, always quiet in auto mode
• Time estimate for 11+: Math.round(count * 15 / 60) minutes, or show seconds if < 60s total
• The --analyze path can reuse the same runInsightsCommand import
• For testing runInsightsCommand calls, mock the module: vi.mock('../insights.js', async (importOriginal) => ...) — but insightsCheckCommand is in the same file. Instead extract runInsightsCommand to a separate import or pass it as a dependency, OR mock at the test level using vi.spyOn. Check how other tests in the file mock things.
• Actually simpler: make insightsCheckCommand async and call runInsightsCommand which is already in scope. For tests, mock runInsightsCommand by exporting a ref or via module mock. Look at how mockProviderRunAnalysis is set up — same pattern.

Scope constraints

• NOT_API_CHANGE — no server changes
• NOT_NEW_DEPS — no new packages
• Tier 1 verification: pnpm build (zero errors) + pnpm test in cli/ (zero failures)

Worktree

All work in: /Users/melagiri/Workspace/codeInsights/code-insights-backfill-check-recovery/
Branch: feature/backfill-check-recovery