@soleri/core 9.3.1 → 9.4.0

package/src/runtime/admin-ops.ts

@@ -1,5 +1,5 @@
 /**
- * Admin / infrastructure operations — 8 ops for agent self-management.
+ * Admin / infrastructure operations — 11 ops for agent self-management.
  *
  * These ops let agents introspect their own health, configuration, and
  * runtime state. No new modules needed — uses existing runtime parts.
@@ -11,6 +11,7 @@ import { fileURLToPath } from 'node:url';
 import type { OpDefinition } from '../facades/types.js';
 import type { AgentRuntime } from './types.js';
 import { ENGINE_MODULE_MANIFEST } from '../engine/module-manifest.js';
+import { discoverSkills } from '../skills/sync-skills.js';
 
 /**
  * Resolve the @soleri/core package.json version.
@@ -42,13 +43,13 @@ function getCoreVersion(): string {
  * Groups: health (1–2), introspection (4), diagnostics (2), mutation (1).
  */
 export function createAdminOps(runtime: AgentRuntime): OpDefinition[] {
-  const { vault, brain, brainIntelligence, llmClient, curator } = runtime;
+  const { vault, brain, brainIntelligence, llmClient, curator, packInstaller } = runtime;
 
   return [
     // ─── Health ──────────────────────────────────────────────────────
     {
       name: 'admin_health',
-      description: 'Comprehensive agent health check — vault, LLM, brain status.',
+      description: 'Comprehensive agent health check — vault, LLM, brain, skills, hooks status.',
       auth: 'read',
       handler: async () => {
         const vaultStats = vault.stats();
@@ -56,6 +57,24 @@ export function createAdminOps(runtime: AgentRuntime): OpDefinition[] {
         const brainStats = brain.getStats();
         const curatorStatus = curator.getStatus();
 
+        // Skills: agent-level + pack-level
+        const agentDir = runtime.config.agentDir;
+        const agentSkillsDirs = agentDir ? [join(agentDir, 'skills')] : [];
+        const agentSkills = discoverSkills(agentSkillsDirs);
+        const packs = packInstaller.list();
+        const packSkills = packs.flatMap((p) => p.skills);
+        const allSkillNames = [...agentSkills.map((s) => s.name), ...packSkills];
+
+        // Hooks: pack-level
+        const packHooks = packs.flatMap((p) => p.hooks);
+
+        // Tier breakdown
+        const tierCounts = { default: 0, community: 0, premium: 0 };
+        for (const pk of packs) {
+          const t = (pk.manifest as { tier?: string })?.tier ?? 'community';
+          if (t in tierCounts) tierCounts[t as keyof typeof tierCounts]++;
+        }
+
         return {
           status: 'ok',
           vault: { entries: vaultStats.totalEntries, domains: Object.keys(vaultStats.byDomain) },
@@ -65,6 +84,16 @@ export function createAdminOps(runtime: AgentRuntime): OpDefinition[] {
             feedbackCount: brainStats.feedbackCount,
           },
           curator: { initialized: curatorStatus.initialized },
+          skills: {
+            count: allSkillNames.length,
+            agent: agentSkills.map((s) => s.name),
+            packs: packSkills,
+          },
+          hooks: {
+            count: packHooks.length,
+            packs: packHooks,
+          },
+          packTiers: tierCounts,
         };
       },
     },
@@ -215,6 +244,39 @@ export function createAdminOps(runtime: AgentRuntime): OpDefinition[] {
       },
     },
 
+    // ─── Operator Context ───────────────────────────────────────────
+    {
+      name: 'operator_context_inspect',
+      description:
+        'Inspect the full operator context profile — expertise, corrections, interests, patterns.',
+      auth: 'read',
+      handler: async () => {
+        const store = runtime.operatorContextStore;
+        if (!store) {
+          return { available: false, message: 'Operator context not configured' };
+        }
+        return { available: true, ...store.inspect() };
+      },
+    },
+    {
+      name: 'operator_context_delete',
+      description: 'Delete a specific item from the operator context profile.',
+      auth: 'write',
+      handler: async (params) => {
+        const store = runtime.operatorContextStore;
+        if (!store) {
+          return { deleted: false, message: 'Operator context not configured' };
+        }
+        const type = params.type as string;
+        const id = params.id as string;
+        const deleted = store.deleteItem(type as Parameters<typeof store.deleteItem>[0], id);
+        if (deleted) {
+          return { deleted: true, type, id };
+        }
+        return { deleted: false, message: 'Item not found' };
+      },
+    },
+
     // ─── Diagnostics ─────────────────────────────────────────────────
     {
       name: 'admin_diagnostic',
@@ -301,6 +363,45 @@ export function createAdminOps(runtime: AgentRuntime): OpDefinition[] {
           });
         }
 
+        // 7. Skills
+        try {
+          const agentDir = runtime.config.agentDir;
+          const skillsDirs = agentDir ? [join(agentDir, 'skills')] : [];
+          const agentSkills = discoverSkills(skillsDirs);
+          const installedPacks = packInstaller.list();
+          const packSkillCount = installedPacks.reduce((sum, p) => sum + p.skills.length, 0);
+          const totalSkills = agentSkills.length + packSkillCount;
+          const skillStatus = totalSkills > 0 ? 'ok' : agentDir ? 'warn' : 'ok';
+          checks.push({
+            name: 'skills',
+            status: skillStatus,
+            detail: `${totalSkills} skills (${agentSkills.length} agent, ${packSkillCount} pack)`,
+          });
+        } catch (err) {
+          checks.push({
+            name: 'skills',
+            status: 'error',
+            detail: err instanceof Error ? err.message : String(err),
+          });
+        }
+
+        // 8. Hooks
+        try {
+          const installedPacks = packInstaller.list();
+          const packHookCount = installedPacks.reduce((sum, p) => sum + p.hooks.length, 0);
+          checks.push({
+            name: 'hooks',
+            status: 'ok',
+            detail: `${packHookCount} hooks from ${installedPacks.length} packs`,
+          });
+        } catch (err) {
+          checks.push({
+            name: 'hooks',
+            status: 'error',
+            detail: err instanceof Error ? err.message : String(err),
+          });
+        }
+
         const errorCount = checks.filter((c) => c.status === 'error').length;
         const warnCount = checks.filter((c) => c.status === 'warn').length;
         const overall = errorCount > 0 ? 'unhealthy' : warnCount > 0 ? 'degraded' : 'healthy';

package/src/runtime/admin-setup-ops.ts

@@ -99,7 +99,7 @@ function discoverHookifyFiles(dir: string): Array<{ name: string; path: string }
 // ─── Settings.json Hook Merging ───────────────────────────────────────
 
 interface SettingsHook {
-  type: 'prompt' | 'agent';
+  type: 'prompt' | 'agent' | 'command';
   prompt?: string;
   command?: string;
   timeout?: number;
@@ -110,6 +110,17 @@ interface SettingsHookGroup {
   hooks: SettingsHook[];
 }
 
+/**
+ * Build a shell command that checks if the agent's MCP server is configured
+ * in the current project's .mcp.json before emitting an instruction.
+ * This ensures hooks are globally safe — they no-op in projects without the agent.
+ */
+function buildConditionalHookCommand(agentId: string, instruction: string): string {
+  // Escape single quotes in instruction for safe shell embedding
+  const escaped = instruction.replace(/'/g, "'\\''");
+  return `root=$(git rev-parse --show-toplevel 2>/dev/null || echo "."); if grep -q '"${agentId}"' "$root/.mcp.json" 2>/dev/null; then echo '${escaped}'; fi`;
+}
+
 /** Default lifecycle hooks for any Soleri agent */
 function getDefaultLifecycleHooks(agentId: string): Record<string, SettingsHookGroup[]> {
   const marker = `mcp__${agentId}__${agentId}_`;
@@ -120,9 +131,12 @@ function getDefaultLifecycleHooks(agentId: string): Record<string, SettingsHookG
         matcher: '',
         hooks: [
           {
-            type: 'prompt',
-            prompt: `Call ${marker}admin op:admin_health to verify agent is ready. Do not show the result unless there are errors.`,
-            timeout: 15000,
+            type: 'command',
+            command: buildConditionalHookCommand(
+              agentId,
+              `Call ${marker}admin op:admin_health to verify agent is ready. Do not show the result unless there are errors.`,
+            ),
+            timeout: 5000,
           },
         ],
       },
@@ -132,9 +146,12 @@ function getDefaultLifecycleHooks(agentId: string): Record<string, SettingsHookG
         matcher: '',
         hooks: [
           {
-            type: 'agent',
-            prompt: `Call ${marker}memory op:session_capture with a brief summary of the current session before context is compacted.`,
-            timeout: 30000,
+            type: 'command',
+            command: buildConditionalHookCommand(
+              agentId,
+              `First, call ${marker}plan op:plan_close_stale params:{ olderThanMs: 0 } to auto-close any plans still in non-terminal states. Then call ${marker}memory op:session_capture with a brief summary of the current session before context is compacted. Include any auto-closed plan IDs in the summary.`,
+            ),
+            timeout: 10000,
           },
         ],
       },
@@ -144,9 +161,12 @@ function getDefaultLifecycleHooks(agentId: string): Record<string, SettingsHookG
         matcher: '',
         hooks: [
           {
-            type: 'agent',
-            prompt: `Call ${marker}memory op:session_capture with a structured summary of what was accomplished, then check ${marker}loop op:loop_status — if a loop is active, remind the user.`,
-            timeout: 30000,
+            type: 'command',
+            command: buildConditionalHookCommand(
+              agentId,
+              `First, call ${marker}plan op:plan_close_stale params:{ olderThanMs: 0 } to auto-close any plans still in non-terminal states. Then call ${marker}memory op:session_capture with a structured summary of what was accomplished, including any auto-closed plan IDs. Finally check ${marker}loop op:loop_status — if a loop is active, remind the user.`,
+            ),
+            timeout: 10000,
           },
         ],
       },

package/src/runtime/capture-ops.test.ts

@@ -37,6 +37,19 @@ function createMockRuntime(): AgentRuntime {
         entry: { id: 'captured-1' },
       })),
       intelligentSearch: vi.fn(async () => [{ id: 'r1', title: 'Result 1', score: 0.8 }]),
+      scanSearch: vi.fn(async () => [
+        {
+          id: 'r1',
+          title: 'Result 1',
+          score: 0.8,
+          snippet: 'Short desc...',
+          tokenEstimate: 50,
+          type: 'pattern',
+          domain: 'test',
+          severity: 'suggestion',
+          tags: ['test'],
+        },
+      ]),
       recordFeedback: vi.fn(),
     },
     governance: {
@@ -365,6 +378,77 @@ describe('createCaptureOps', () => {
       })) as Array<Record<string, unknown>>;
       expect((result[0].score as number) >= (result[1].score as number)).toBe(true);
     });
+
+    it('scan mode calls brain.scanSearch instead of intelligentSearch', async () => {
+      const result = (await findOp(ops, 'search_intelligent').handler({
+        query: 'test patterns',
+        mode: 'scan',
+      })) as Array<Record<string, unknown>>;
+      expect(runtime.brain.scanSearch).toHaveBeenCalledWith(
+        'test patterns',
+        expect.objectContaining({ limit: 10 }),
+      );
+      expect(runtime.brain.intelligentSearch).not.toHaveBeenCalled();
+      expect(Array.isArray(result)).toBe(true);
+      expect(result[0].source).toBe('vault');
+      expect(result[0].snippet).toBeDefined();
+    });
+
+    it('scan mode defaults limit to 10', async () => {
+      await findOp(ops, 'search_intelligent').handler({
+        query: 'test',
+        mode: 'scan',
+      });
+      expect(runtime.brain.scanSearch).toHaveBeenCalledWith(
+        'test',
+        expect.objectContaining({ limit: 10 }),
+      );
+    });
+
+    it('full mode (default) still uses intelligentSearch with limit 20', async () => {
+      await findOp(ops, 'search_intelligent').handler({
+        query: 'test',
+      });
+      expect(runtime.brain.intelligentSearch).toHaveBeenCalledWith(
+        'test',
+        expect.objectContaining({ limit: 20 }),
+      );
+      expect(runtime.brain.scanSearch).not.toHaveBeenCalled();
+    });
+
+    it('scan mode with includeMemories returns lightweight memory results', async () => {
+      vi.mocked(runtime.vault.searchMemories).mockReturnValue([
+        {
+          id: 'm1',
+          summary:
+            'A long memory summary that should be truncated to 120 chars for scan mode lightweight results test',
+          context: 'Auth context',
+        },
+      ] as unknown);
+      const result = (await findOp(ops, 'search_intelligent').handler({
+        query: 'auth',
+        mode: 'scan',
+        includeMemories: true,
+      })) as Array<Record<string, unknown>>;
+      const memResult = result.find((r) => r.source === 'memory');
+      expect(memResult).toBeDefined();
+      expect(memResult!.id).toBe('m1');
+      expect(memResult!.snippet).toBeDefined();
+      expect(typeof memResult!.snippet).toBe('string');
+      // Should NOT have full memory fields
+      expect(memResult!.filesModified).toBeUndefined();
+      expect(memResult!.toolsUsed).toBeUndefined();
+    });
+
+    it('scan mode handles search failure gracefully', async () => {
+      vi.mocked(runtime.brain.scanSearch).mockRejectedValue(new Error('Scan failed'));
+      const result = (await findOp(ops, 'search_intelligent').handler({
+        query: 'anything',
+        mode: 'scan',
+      })) as Array<Record<string, unknown>>;
+      expect(Array.isArray(result)).toBe(true);
+      expect(result).toHaveLength(0);
+    });
   });
 
   describe('search_feedback', () => {

package/src/runtime/capture-ops.ts

@@ -484,28 +484,42 @@ export function createCaptureOps(runtime: AgentRuntime): OpDefinition[] {
     {
       name: 'search_intelligent',
       description:
-        'Project-scoped intelligent search combining vault FTS, brain TF-IDF ranking, and optional memory search.',
+        'Project-scoped intelligent search combining vault FTS, brain TF-IDF ranking, and optional memory search. mode:"scan" returns lightweight results (titles + scores + snippets) for two-pass retrieval. mode:"full" (default) returns complete entries.',
       auth: 'read',
       schema: z.object({
         query: z.string(),
         projectPath: z.string().optional(),
         domain: z.string().optional(),
         type: z.string().optional(),
-        limit: z.number().optional().default(20),
+        limit: z.number().optional(),
         includeMemories: z.boolean().optional().default(false),
+        mode: z
+          .enum(['full', 'scan'])
+          .optional()
+          .default('full')
+          .describe(
+            'full = complete entries with scoring breakdowns, scan = lightweight titles + scores for two-pass retrieval',
+          ),
       }),
       handler: async (params) => {
         const query = params.query as string;
         const domain = params.domain as string | undefined;
         const type = params.type as string | undefined;
-        const limit = (params.limit as number | undefined) ?? 20;
+        const mode = (params.mode as string | undefined) ?? 'full';
+        const isScan = mode === 'scan';
+        const limit = (params.limit as number | undefined) ?? (isScan ? 10 : 20);
         const includeMemories = (params.includeMemories as boolean | undefined) ?? false;
 
-        // Search vault via brain's intelligent search (TF-IDF ranked)
+        // Search vault — scan mode returns lightweight results, full returns complete entries
         let vaultResults: Array<{ source: string; [key: string]: unknown }> = [];
         try {
-          const ranked = await brain.intelligentSearch(query, { domain, type, limit });
-          vaultResults = ranked.map((r) => ({ ...r, source: 'vault' }));
+          if (isScan) {
+            const scanned = await brain.scanSearch(query, { domain, type, limit });
+            vaultResults = scanned.map((r) => ({ ...r, source: 'vault' }));
+          } else {
+            const ranked = await brain.intelligentSearch(query, { domain, type, limit });
+            vaultResults = ranked.map((r) => ({ ...r, source: 'vault' }));
+          }
         } catch {
           // Graceful degradation — return empty vault results
         }
@@ -515,7 +529,21 @@ export function createCaptureOps(runtime: AgentRuntime): OpDefinition[] {
         if (includeMemories) {
           try {
             const memories = vault.searchMemories(query, { limit });
-            memoryResults = memories.map((m) => ({ ...m, source: 'memory', score: 0.5 }));
+            if (isScan) {
+              // Lightweight memory results for scan mode
+              memoryResults = memories.map((m) => {
+                const desc = m.summary ?? '';
+                return {
+                  id: m.id,
+                  title: m.context ?? '',
+                  snippet: desc.slice(0, 120) + (desc.length > 120 ? '...' : ''),
+                  score: 0.5,
+                  source: 'memory',
+                };
+              });
+            } else {
+              memoryResults = memories.map((m) => ({ ...m, source: 'memory', score: 0.5 }));
+            }
           } catch {
             // Graceful degradation — return empty memory results
           }

package/src/runtime/facades/admin-facade.test.ts

@@ -84,7 +84,7 @@ function mockRuntime(): AgentRuntime {
     pluginRegistry: {
       get: vi.fn(),
     },
-    packInstaller: {},
+    packInstaller: { list: vi.fn(() => []) },
     createdAt: Date.now() - 60000,
     persona: { name: 'TestAgent' },
   } as unknown as AgentRuntime;

package/src/runtime/facades/brain-facade.ts

@@ -466,13 +466,16 @@ export function createBrainFacadeOps(runtime: AgentRuntime): OpDefinition[] {
     },
     {
       name: 'radar_dismiss',
-      description: 'Dismiss a pending radar candidate — marks it as not worth capturing.',
+      description:
+        'Dismiss one or more pending radar candidates — marks them as not worth capturing. Accepts a single ID or an array.',
       auth: 'write',
       schema: z.object({
-        candidateId: z.number().describe('Radar candidate ID to dismiss'),
+        candidateId: z
+          .union([z.number(), z.array(z.number())])
+          .describe('Radar candidate ID(s) to dismiss — single number or array'),
       }),
       handler: async (params) => {
-        return learningRadar.dismiss(params.candidateId as number);
+        return learningRadar.dismiss(params.candidateId as number | number[]);
       },
     },
     {

package/src/runtime/facades/control-facade.ts

@@ -118,11 +118,19 @@ export function createControlFacadeOps(runtime: AgentRuntime): OpDefinition[] {
         mode: z
           .string()
           .describe(
-            'The operational mode to switch to. Valid modes: BUILD-MODE, FIX-MODE, VALIDATE-MODE, DESIGN-MODE, IMPROVE-MODE, DELIVER-MODE, EXPLORE-MODE, PLAN-MODE, REVIEW-MODE, GENERAL-MODE. Use "reset" to return to GENERAL-MODE.',
+            'The operational mode to switch to. Valid modes: BUILD-MODE, FIX-MODE, VALIDATE-MODE, DESIGN-MODE, IMPROVE-MODE, DELIVER-MODE, EXPLORE-MODE, PLAN-MODE, REVIEW-MODE, GENERAL-MODE, YOLO-MODE. Use "reset" to return to GENERAL-MODE.',
+          ),
+        hookPackInstalled: z
+          .boolean()
+          .optional()
+          .describe(
+            'Whether the yolo-safety hook pack is installed. Required for YOLO-MODE activation. The CLI layer should check for the hook pack before calling morph.',
           ),
       }),
       handler: async (params) => {
-        return intentRouter.morph(params.mode as OperationalMode);
+        return intentRouter.morph(params.mode as OperationalMode, {
+          hookPackInstalled: params.hookPackInstalled as boolean | undefined,
+        });
       },
     },
     {

package/src/runtime/facades/curator-facade.ts

@@ -36,6 +36,24 @@ export function createCuratorFacadeOps(runtime: AgentRuntime): OpDefinition[] {
         );
       },
     },
+    {
+      name: 'curator_dismiss_duplicate',
+      description:
+        'Dismiss a flagged duplicate pair — marks two entries as reviewed and intentionally distinct. They will no longer appear in curator_detect_duplicates results.',
+      auth: 'write',
+      schema: z.object({
+        entryIdA: z.string().describe('First entry ID'),
+        entryIdB: z.string().describe('Second entry ID'),
+        reason: z.string().optional().describe('Why these are not duplicates'),
+      }),
+      handler: async (params) => {
+        return curator.dismissDuplicate(
+          params.entryIdA as string,
+          params.entryIdB as string,
+          params.reason as string | undefined,
+        );
+      },
+    },
     {
       name: 'curator_contradictions',
       description: 'List or detect contradictions between patterns and anti-patterns.',

package/src/runtime/facades/memory-facade.test.ts

@@ -67,7 +67,8 @@ describe('memory-facade', () => {
   it('memory_search returns empty for no matches', async () => {
     const result = await executeOp(ops, 'memory_search', { query: 'nonexistent' });
     expect(result.success).toBe(true);
-    expect((result.data as Record<string, unknown>).total).toBe(0);
+    const data = result.data as unknown[];
+    expect(data.length).toBe(0);
   });
 
   it('memory_search finds captured memories', async () => {
@@ -79,7 +80,8 @@ describe('memory-facade', () => {
     });
     const result = await executeOp(ops, 'memory_search', { query: 'token migration' });
     expect(result.success).toBe(true);
-    expect((result.data as Record<string, unknown>).total).toBeGreaterThanOrEqual(1);
+    const data = result.data as unknown[];
+    expect(data.length).toBeGreaterThanOrEqual(1);
   });
 
   it('memory_search returns summaries by default', async () => {
@@ -91,9 +93,9 @@ describe('memory-facade', () => {
     });
     const result = await executeOp(ops, 'memory_search', { query: 'short summary' });
     expect(result.success).toBe(true);
-    const data = result.data as { results: Array<{ summary: string }> };
-    expect(data.results[0]).toHaveProperty('summary');
-    expect(data.results[0]).not.toHaveProperty('context');
+    const data = result.data as Array<{ summary: string }>;
+    expect(data[0]).toHaveProperty('summary');
+    expect(data[0]).not.toHaveProperty('context');
   });
 
   it('memory_search returns full objects with verbose:true', async () => {
@@ -105,8 +107,8 @@ describe('memory-facade', () => {
     });
     const result = await executeOp(ops, 'memory_search', { query: 'verbose test', verbose: true });
     expect(result.success).toBe(true);
-    const data = result.data as { results: Array<Record<string, unknown>> };
-    expect(data.results[0]).toHaveProperty('context');
+    const data = result.data as Array<Record<string, unknown>>;
+    expect(data[0]).toHaveProperty('context');
   });
 
   // ─── memory_list ───────────────────────────────────────────────
@@ -120,9 +122,9 @@ describe('memory-facade', () => {
     });
     const result = await executeOp(ops, 'memory_list', {});
     expect(result.success).toBe(true);
-    const data = result.data as { entries: unknown[]; total: number };
-    expect(data.total).toBeGreaterThanOrEqual(1);
-    expect(data.entries.length).toBeGreaterThanOrEqual(1);
+    const data = result.data as { memories: unknown[]; stats: { total: number } };
+    expect(data.stats.total).toBeGreaterThanOrEqual(1);
+    expect(data.memories.length).toBeGreaterThanOrEqual(1);
   });
 
   it('memory_list filters by type', async () => {
@@ -140,8 +142,8 @@ describe('memory-facade', () => {
     });
     const result = await executeOp(ops, 'memory_list', { type: 'lesson' });
     expect(result.success).toBe(true);
-    const data = result.data as { entries: unknown[]; total: number };
-    expect(data.entries.length).toBe(1);
+    const data = result.data as { memories: unknown[]; stats: Record<string, unknown> };
+    expect(data.memories.length).toBe(1);
   });
 
   it('memory_list verbose returns full objects', async () => {

package/src/runtime/facades/memory-facade.ts

@@ -45,17 +45,15 @@ export function createMemoryFacadeOps(runtime: AgentRuntime): OpDefinition[] {
           limit: (params.limit as number) ?? 10,
         });
         if (params.verbose) {
-          return { results: memories, total: memories.length };
+          return memories;
         }
-        return {
-          results: memories.map((m) => ({
-            id: m.id,
-            summary: truncateSummary(m.summary || m.context),
-            score: null,
-            project: m.projectPath,
-          })),
-          total: memories.length,
-        };
+        return memories.map((m) => ({
+          id: m.id,
+          type: m.type,
+          summary: truncateSummary(m.summary || m.context),
+          score: null,
+          project: m.projectPath,
+        }));
       },
     },
     {
@@ -117,13 +115,13 @@ export function createMemoryFacadeOps(runtime: AgentRuntime): OpDefinition[] {
           return { memories, stats };
         }
         return {
-          entries: memories.map((m) => ({
+          memories: memories.map((m) => ({
             id: m.id,
             summary: truncateSummary(m.summary || m.context),
             project: m.projectPath,
             createdAt: m.createdAt,
           })),
-          total: stats.total,
+          stats,
         };
       },
     },

package/src/runtime/facades/orchestrate-facade.ts

@@ -25,7 +25,9 @@ export function createOrchestrateFacadeOps(runtime: AgentRuntime): OpDefinition[
         name: z.string().optional().describe('Project display name (derived from path if omitted)'),
       }),
       handler: async (params) => {
-        const { resolve } = await import('node:path');
+        const { resolve, join } = await import('node:path');
+        const { homedir } = await import('node:os');
+        const { existsSync, readdirSync, statSync } = await import('node:fs');
         const projectPath = resolve((params.projectPath as string) ?? '.');
         const project = vault.registerProject(projectPath, params.name as string | undefined);
         // Also track in project registry for cross-project features
@@ -40,6 +42,35 @@ export function createOrchestrateFacadeOps(runtime: AgentRuntime): OpDefinition[
         const proposalStats = governance.getProposalStats(projectPath);
         const quotaStatus = governance.getQuotaStatus(projectPath);
 
+        // Check for stale staging backups (lightweight — stat only, no tree walk)
+        let stagingWarning: { count: number; message: string } | undefined;
+        try {
+          const stagingRoot = join(homedir(), '.soleri', 'staging');
+          if (existsSync(stagingRoot)) {
+            const maxAgeMs = 7 * 24 * 60 * 60 * 1000; // 7 days
+            const cutoff = Date.now() - maxAgeMs;
+            const dirs = readdirSync(stagingRoot, { withFileTypes: true });
+            let staleCount = 0;
+            for (const dir of dirs) {
+              if (!dir.isDirectory()) continue;
+              try {
+                const st = statSync(join(stagingRoot, dir.name));
+                if (st.mtimeMs < cutoff) staleCount++;
+              } catch {
+                // skip unreadable entries
+              }
+            }
+            if (staleCount > 0) {
+              stagingWarning = {
+                count: staleCount,
+                message: `${staleCount} staging backup(s) older than 7 days. Run: soleri staging cleanup --yes`,
+              };
+            }
+          }
+        } catch {
+          // Non-critical — don't fail session start over staging check
+        }
+
         return {
           project,
           is_new: isNew,
@@ -56,6 +87,7 @@ export function createOrchestrateFacadeOps(runtime: AgentRuntime): OpDefinition[
             isQuotaWarning: quotaStatus.isWarning,
             expiredThisSession: expired,
           },
+          ...(stagingWarning ? { stagingWarning } : {}),
         };
       },
     },