@soleri/core 9.3.1 → 9.5.0

package/src/runtime/planning-extra-ops.ts

@@ -17,6 +17,7 @@ import { collectGitEvidence } from '../planning/evidence-collector.js';
 import { matchPlaybooks, type PlaybookMatchResult } from '../playbooks/index.js';
 import { entryToPlaybookDefinition } from '../playbooks/index.js';
 import { closeIssueWithComment } from './github-integration.js';
+import { recordPlanFeedback } from './plan-feedback-helper.js';
 
 /**
  * Create 22 extended planning operations for an agent runtime.
@@ -37,9 +38,9 @@ export function createPlanningExtraOps(runtime: AgentRuntime): OpDefinition[] {
     {
       name: 'plan_iterate',
       description:
-        'Revise a draft plan — change objective, scope, decisions, or add/remove tasks. Only works on draft plans.',
+        'Revise a draft plan — change objective, scope, decisions, alternatives, or add/remove tasks. Only works on draft plans.',
       auth: 'write',
-      schema: z.object({
+      schema: z.strictObject({
         planId: z.string().describe('ID of the draft plan to iterate on'),
         objective: z.string().optional().describe('New objective (replaces existing)'),
         scope: z.string().optional().describe('New scope (replaces existing)'),
@@ -49,21 +50,54 @@ export function createPlanningExtraOps(runtime: AgentRuntime): OpDefinition[] {
           .describe(
             'New decisions list (replaces existing) — strings or {decision, rationale} objects',
           ),
+        alternatives: z
+          .array(
+            z.object({
+              approach: z.string().describe('The alternative approach considered'),
+              pros: z.array(z.string()).describe('Advantages of this approach'),
+              cons: z.array(z.string()).describe('Disadvantages of this approach'),
+              rejected_reason: z.string().describe('Why this alternative was rejected'),
+            }),
+          )
+          .optional()
+          .describe('Rejected alternative approaches (replaces existing)'),
         addTasks: z
-          .array(z.object({ title: z.string(), description: z.string() }))
+          .array(
+            z.object({
+              title: z.string(),
+              description: z.string(),
+              phase: z
+                .string()
+                .optional()
+                .describe('Phase this task belongs to (e.g., "wave-1", "discovery")'),
+              milestone: z
+                .string()
+                .optional()
+                .describe('Milestone this task contributes to (e.g., "v1.0", "mvp")'),
+              parentTaskId: z.string().optional().describe('Parent task ID for sub-task hierarchy'),
+            }),
+          )
           .optional()
           .describe('Tasks to append'),
         removeTasks: z.array(z.string()).optional().describe('Task IDs to remove'),
       }),
       handler: async (params) => {
         try {
-          const plan = planner.iterate(params.planId as string, {
+          const { plan, mutated } = planner.iterate(params.planId as string, {
             objective: params.objective as string | undefined,
             scope: params.scope as string | undefined,
             decisions: params.decisions as string[] | undefined,
+            alternatives: params.alternatives as
+              | Array<{ approach: string; pros: string[]; cons: string[]; rejected_reason: string }>
+              | undefined,
             addTasks: params.addTasks as Array<{ title: string; description: string }> | undefined,
             removeTasks: params.removeTasks as string[] | undefined,
           });
+
+          if (mutated === 0) {
+            return { iterated: false, reason: 'no changes detected', plan };
+          }
+
           return { iterated: true, plan };
         } catch (err) {
           return { error: (err as Error).message };
@@ -85,6 +119,17 @@ export function createPlanningExtraOps(runtime: AgentRuntime): OpDefinition[] {
               title: z.string(),
               description: z.string(),
               dependsOn: z.array(z.string()).optional().describe('Task IDs this task depends on'),
+              phase: z
+                .string()
+                .optional()
+                .describe(
+                  'Phase this task belongs to (e.g., "wave-1", "discovery", "implementation")',
+                ),
+              milestone: z
+                .string()
+                .optional()
+                .describe('Milestone this task contributes to (e.g., "v1.0", "mvp", "beta")'),
+              parentTaskId: z.string().optional().describe('Parent task ID for sub-task hierarchy'),
             }),
           )
           .describe('New task list with optional dependency references (task-1, task-2, etc.)'),
@@ -93,7 +138,14 @@ export function createPlanningExtraOps(runtime: AgentRuntime): OpDefinition[] {
         try {
           const plan = planner.splitTasks(
             params.planId as string,
-            params.tasks as Array<{ title: string; description: string; dependsOn?: string[] }>,
+            params.tasks as Array<{
+              title: string;
+              description: string;
+              dependsOn?: string[];
+              phase?: string;
+              milestone?: string;
+              parentTaskId?: string;
+            }>,
           );
 
           // Auto-start brain session linked to the plan for learning pipeline
@@ -139,20 +191,16 @@ export function createPlanningExtraOps(runtime: AgentRuntime): OpDefinition[] {
           .describe('Specific drift items — differences between plan and reality'),
       }),
       handler: async (params) => {
-        try {
-          const plan = planner.reconcile(params.planId as string, {
-            actualOutcome: params.actualOutcome as string,
-            driftItems: params.driftItems as DriftItem[] | undefined,
-          });
-          return {
-            reconciled: true,
-            accuracy: plan.reconciliation!.accuracy,
-            driftCount: plan.reconciliation!.driftItems.length,
-            plan,
-          };
-        } catch (err) {
-          return { error: (err as Error).message };
-        }
+        const plan = planner.reconcile(params.planId as string, {
+          actualOutcome: params.actualOutcome as string,
+          driftItems: params.driftItems as DriftItem[] | undefined,
+        });
+        return {
+          reconciled: true,
+          accuracy: plan.reconciliation!.accuracy,
+          driftCount: plan.reconciliation!.driftItems.length,
+          plan,
+        };
       },
     },
 
@@ -228,20 +276,7 @@ export function createPlanningExtraOps(runtime: AgentRuntime): OpDefinition[] {
           }
 
           // Auto-record positive feedback for vault entries used as recommendations
-          let feedbackRecorded = 0;
-          const entryIdRegex = /\[entryId:([^\]]+)\]/;
-          for (const d of plan.decisions) {
-            const decisionStr = typeof d === 'string' ? d : d.decision;
-            const match = entryIdRegex.exec(decisionStr);
-            if (match) {
-              try {
-                brain.recordFeedback(plan.objective, match[1], 'accepted');
-                feedbackRecorded++;
-              } catch {
-                // Graceful degradation — skip if entry not found or already recorded
-              }
-            }
-          }
+          const feedbackRecorded = recordPlanFeedback(plan, brain, brainIntelligence);
 
           // Auto-close linked GitHub issue if plan has one
           let issueClosed = false;
@@ -818,6 +853,34 @@ export function createPlanningExtraOps(runtime: AgentRuntime): OpDefinition[] {
       },
     },
 
+    // ─── Plan Close Stale ───────────────────────────────────────
+    {
+      name: 'plan_close_stale',
+      description:
+        'Close stale plans stuck in non-terminal states. Draft/approved plans expire after 30 min. Executing/reconciling plans expire after the configured threshold (default 24h). Returns list of closed plans.',
+      auth: 'write',
+      schema: z.object({
+        olderThanMs: z
+          .number()
+          .optional()
+          .describe(
+            'Custom threshold in milliseconds for executing/reconciling plans (default: 24h). Set to 0 to close ALL non-terminal plans immediately.',
+          ),
+      }),
+      handler: async (params) => {
+        const olderThanMs = params.olderThanMs as number | undefined;
+        const result = planner.closeStale(olderThanMs);
+        return {
+          closed: result.closedPlans.length,
+          plans: result.closedPlans,
+          message:
+            result.closedPlans.length > 0
+              ? `Closed ${result.closedPlans.length} stale plan(s)`
+              : 'No stale plans found',
+        };
+      },
+    },
+
     // ─── Purge Plans (#215) ──────────────────────────────────────────
     {
       name: 'plan_purge',

package/src/runtime/runtime.test.ts

@@ -81,7 +81,10 @@ vi.mock('../governance/governance.js', () => ({
 }));
 
 vi.mock('../loop/loop-manager.js', () => ({
-  LoopManager: mockClass(),
+  LoopManager: vi.fn(function (this: Record<string, unknown>) {
+    this.isActive = vi.fn().mockReturnValue(false);
+    this.cancelLoop = vi.fn();
+  }),
 }));
 
 vi.mock('../control/identity-manager.js', () => ({
@@ -185,7 +188,9 @@ vi.mock('../context/context-engine.js', () => ({
 }));
 
 vi.mock('../agency/agency-manager.js', () => ({
-  AgencyManager: mockClass(),
+  AgencyManager: vi.fn(function (this: Record<string, unknown>) {
+    this.disable = vi.fn();
+  }),
 }));
 
 vi.mock('../vault/knowledge-review.js', () => ({
@@ -220,6 +225,7 @@ vi.mock('../queue/job-queue.js', () => ({
 vi.mock('../queue/pipeline-runner.js', () => ({
   PipelineRunner: vi.fn(function (this: Record<string, unknown>) {
     this.registerHandler = vi.fn();
+    this.stop = vi.fn();
   }),
 }));
 
@@ -261,6 +267,18 @@ vi.mock('./context-health.js', () => ({
   }),
 }));
 
+vi.mock('./shutdown-registry.js', () => ({
+  ShutdownRegistry: vi.fn(function (this: Record<string, unknown>) {
+    this.register = vi.fn();
+    this.closeAll = vi.fn().mockResolvedValue(undefined);
+    this.closeAllSync = vi.fn();
+    this.size = 0;
+    this.isClosed = false;
+    this.entries = [];
+    this.closed = false;
+  }),
+}));
+
 vi.mock('node:fs', () => ({
   existsSync: vi.fn().mockReturnValue(false),
   mkdirSync: vi.fn(),
@@ -360,4 +378,34 @@ describe('createAgentRuntime', () => {
   it('initializes context health monitor', () => {
     expect(runtime.contextHealth).toBeDefined();
   });
+
+  it('initializes shutdown registry', () => {
+    expect(runtime.shutdownRegistry).toBeDefined();
+    expect(runtime.shutdownRegistry.register).toBeDefined();
+  });
+
+  it('registers cleanup callbacks with shutdown registry', () => {
+    // vaultManager, pipelineRunner, agencyManager, loopManager
+    expect(runtime.shutdownRegistry.register).toHaveBeenCalledWith(
+      'vaultManager',
+      expect.any(Function),
+    );
+    expect(runtime.shutdownRegistry.register).toHaveBeenCalledWith(
+      'pipelineRunner',
+      expect.any(Function),
+    );
+    expect(runtime.shutdownRegistry.register).toHaveBeenCalledWith(
+      'agencyManager',
+      expect.any(Function),
+    );
+    expect(runtime.shutdownRegistry.register).toHaveBeenCalledWith(
+      'loopManager',
+      expect.any(Function),
+    );
+  });
+
+  it('close() calls shutdownRegistry.closeAllSync()', () => {
+    runtime.close();
+    expect(runtime.shutdownRegistry.closeAllSync).toHaveBeenCalled();
+  });
 });

package/src/runtime/runtime.ts

@@ -60,6 +60,7 @@ import { loadPersona } from '../persona/loader.js';
 import { generatePersonaInstructions } from '../persona/prompt-generator.js';
 import { OperatorProfileStore } from '../operator/operator-profile.js';
 import { ContextHealthMonitor } from './context-health.js';
+import { ShutdownRegistry } from './shutdown-registry.js';
 
 /**
  * Create a fully initialized agent runtime.
@@ -221,6 +222,117 @@ export function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime {
   learningRadar.setOperatorProfile(operatorProfile);
   brainIntelligence.setOperatorProfile(operatorProfile);
 
+  // ─── Shutdown Registry ────────────────────────────────────────────
+  const shutdownRegistry = new ShutdownRegistry();
+
+  // Build pipeline runner before the runtime object so we can reference it
+  const pipelineRunner = (() => {
+    const jq = new JobQueue(vault.getProvider());
+    const pr = new PipelineRunner(jq);
+    // Register default job handlers for curator pipeline
+    pr.registerHandler('tag-normalize', async (job) => {
+      const entry = vault.get(job.entryId ?? '');
+      if (!entry) return { skipped: true, reason: 'entry not found' };
+      const result = curator.normalizeTag(entry.tags[0] ?? '');
+      return result;
+    });
+    pr.registerHandler('dedup-check', async (job) => {
+      const entry = vault.get(job.entryId ?? '');
+      if (!entry) return { skipped: true, reason: 'entry not found' };
+      return curator.detectDuplicates(entry.id);
+    });
+    pr.registerHandler('auto-link', async (job) => {
+      if (linkManager) {
+        const suggestions = linkManager.suggestLinks(job.entryId ?? '', 3);
+        for (const s of suggestions) {
+          linkManager.addLink(
+            job.entryId ?? '',
+            s.entryId,
+            s.suggestedType,
+            `pipeline: ${s.reason}`,
+          );
+        }
+        return { linked: suggestions.length };
+      }
+      return { skipped: true, reason: 'link manager not available' };
+    });
+    pr.registerHandler('quality-gate', async (job) => {
+      const entry = vault.get(job.entryId ?? '');
+      if (!entry) return { skipped: true, reason: 'entry not found' };
+      return evaluateQuality(entry, llmClient);
+    });
+    pr.registerHandler('classify', async (job) => {
+      const entry = vault.get(job.entryId ?? '');
+      if (!entry) return { skipped: true, reason: 'entry not found' };
+      return classifyEntry(entry, llmClient);
+    });
+
+    // ─── 9 additional handlers for full Salvador parity (#216) ────
+    pr.registerHandler('enrich-frontmatter', async (job) => {
+      const entry = vault.get(job.entryId ?? '');
+      if (!entry) return { skipped: true, reason: 'entry not found' };
+      return curator.enrichMetadata(entry.id);
+    });
+    pr.registerHandler('detect-staleness', async (job) => {
+      const entry = vault.get(job.entryId ?? '');
+      if (!entry) return { skipped: true, reason: 'entry not found' };
+      // Check if entry is older than 90 days (using validFrom or fallback to 0)
+      const entryTimestamp = (entry.validFrom ?? 0) * 1000 || Date.now();
+      const ageMs = Date.now() - entryTimestamp;
+      const staleDays = 90;
+      const isStale = ageMs > staleDays * 86400000;
+      return { stale: isStale, ageDays: Math.floor(ageMs / 86400000), entryId: entry.id };
+    });
+    pr.registerHandler('detect-duplicate', async (job) => {
+      const entry = vault.get(job.entryId ?? '');
+      if (!entry) return { skipped: true, reason: 'entry not found' };
+      return curator.detectDuplicates(entry.id);
+    });
+    pr.registerHandler('detect-contradiction', async (job) => {
+      const entry = vault.get(job.entryId ?? '');
+      if (!entry) return { skipped: true, reason: 'entry not found' };
+      const contradictions = curator.detectContradictions(0.4);
+      const relevant = contradictions.filter(
+        (c) => c.patternId === job.entryId || c.antipatternId === job.entryId,
+      );
+      return { found: relevant.length, contradictions: relevant };
+    });
+    pr.registerHandler('consolidate-duplicates', async (_job) => {
+      return curator.consolidate({ dryRun: false, staleDaysThreshold: 90 });
+    });
+    pr.registerHandler('archive-stale', async (_job) => {
+      // Run consolidation with stale detection
+      const result = curator.consolidate({ dryRun: false, staleDaysThreshold: 90 });
+      return { archived: result.staleEntries.length, result };
+    });
+    pr.registerHandler('verify-searchable', async (job) => {
+      const entry = vault.get(job.entryId ?? '');
+      if (!entry) return { skipped: true, reason: 'entry not found' };
+      const searchResults = vault.search(entry.title, { limit: 1 });
+      const found = searchResults.some((r) => r.entry.id === entry.id);
+      return { searchable: found, entryId: entry.id };
+    });
+    return pr;
+  })();
+
+  // ─── Register cleanup callbacks (LIFO: first registered = last closed) ──
+  // Vault manager closes last (other modules may flush to vault during close)
+  shutdownRegistry.register('vaultManager', () => vaultManager.close());
+  // Pipeline runner — clear its polling interval
+  shutdownRegistry.register('pipelineRunner', () => pipelineRunner.stop());
+  // Agency manager — close FSWatchers and debounce timers
+  shutdownRegistry.register('agencyManager', () => agencyManager.disable());
+  // Loop manager — clear accumulated state
+  shutdownRegistry.register('loopManager', () => {
+    if (loop.isActive()) {
+      try {
+        loop.cancelLoop();
+      } catch {
+        // Loop may already be inactive
+      }
+    }
+  });
+
   return {
     config,
     logger,
@@ -256,94 +368,7 @@ export function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime {
     knowledgeSynthesizer: new KnowledgeSynthesizer(brain, llmClient),
     chainRunner: new ChainRunner(vault.getProvider()),
     jobQueue: new JobQueue(vault.getProvider()),
-    pipelineRunner: (() => {
-      const jq = new JobQueue(vault.getProvider());
-      const pr = new PipelineRunner(jq);
-      // Register default job handlers for curator pipeline
-      pr.registerHandler('tag-normalize', async (job) => {
-        const entry = vault.get(job.entryId ?? '');
-        if (!entry) return { skipped: true, reason: 'entry not found' };
-        const result = curator.normalizeTag(entry.tags[0] ?? '');
-        return result;
-      });
-      pr.registerHandler('dedup-check', async (job) => {
-        const entry = vault.get(job.entryId ?? '');
-        if (!entry) return { skipped: true, reason: 'entry not found' };
-        return curator.detectDuplicates(entry.id);
-      });
-      pr.registerHandler('auto-link', async (job) => {
-        if (linkManager) {
-          const suggestions = linkManager.suggestLinks(job.entryId ?? '', 3);
-          for (const s of suggestions) {
-            linkManager.addLink(
-              job.entryId ?? '',
-              s.entryId,
-              s.suggestedType,
-              `pipeline: ${s.reason}`,
-            );
-          }
-          return { linked: suggestions.length };
-        }
-        return { skipped: true, reason: 'link manager not available' };
-      });
-      pr.registerHandler('quality-gate', async (job) => {
-        const entry = vault.get(job.entryId ?? '');
-        if (!entry) return { skipped: true, reason: 'entry not found' };
-        return evaluateQuality(entry, llmClient);
-      });
-      pr.registerHandler('classify', async (job) => {
-        const entry = vault.get(job.entryId ?? '');
-        if (!entry) return { skipped: true, reason: 'entry not found' };
-        return classifyEntry(entry, llmClient);
-      });
-
-      // ─── 9 additional handlers for full Salvador parity (#216) ────
-      pr.registerHandler('enrich-frontmatter', async (job) => {
-        const entry = vault.get(job.entryId ?? '');
-        if (!entry) return { skipped: true, reason: 'entry not found' };
-        return curator.enrichMetadata(entry.id);
-      });
-      pr.registerHandler('detect-staleness', async (job) => {
-        const entry = vault.get(job.entryId ?? '');
-        if (!entry) return { skipped: true, reason: 'entry not found' };
-        // Check if entry is older than 90 days (using validFrom or fallback to 0)
-        const entryTimestamp = (entry.validFrom ?? 0) * 1000 || Date.now();
-        const ageMs = Date.now() - entryTimestamp;
-        const staleDays = 90;
-        const isStale = ageMs > staleDays * 86400000;
-        return { stale: isStale, ageDays: Math.floor(ageMs / 86400000), entryId: entry.id };
-      });
-      pr.registerHandler('detect-duplicate', async (job) => {
-        const entry = vault.get(job.entryId ?? '');
-        if (!entry) return { skipped: true, reason: 'entry not found' };
-        return curator.detectDuplicates(entry.id);
-      });
-      pr.registerHandler('detect-contradiction', async (job) => {
-        const entry = vault.get(job.entryId ?? '');
-        if (!entry) return { skipped: true, reason: 'entry not found' };
-        const contradictions = curator.detectContradictions(0.4);
-        const relevant = contradictions.filter(
-          (c) => c.patternId === job.entryId || c.antipatternId === job.entryId,
-        );
-        return { found: relevant.length, contradictions: relevant };
-      });
-      pr.registerHandler('consolidate-duplicates', async (_job) => {
-        return curator.consolidate({ dryRun: false, staleDaysThreshold: 90 });
-      });
-      pr.registerHandler('archive-stale', async (_job) => {
-        // Run consolidation with stale detection
-        const result = curator.consolidate({ dryRun: false, staleDaysThreshold: 90 });
-        return { archived: result.staleEntries.length, result };
-      });
-      pr.registerHandler('verify-searchable', async (job) => {
-        const entry = vault.get(job.entryId ?? '');
-        if (!entry) return { skipped: true, reason: 'entry not found' };
-        const searchResults = vault.search(entry.title, { limit: 1 });
-        const found = searchResults.some((r) => r.entry.id === entry.id);
-        return { searchable: found, entryId: entry.id };
-      });
-      return pr;
-    })(),
+    pipelineRunner,
     operatorProfile,
     persona: (() => {
       const p = loadPersona(agentId, config.persona ?? undefined);
@@ -355,9 +380,12 @@ export function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime {
       return generatePersonaInstructions(p);
     })(),
     contextHealth: new ContextHealthMonitor(),
+    shutdownRegistry,
     createdAt: Date.now(),
     close: () => {
-      vaultManager.close();
+      // Synchronous close — runs all registered callbacks in LIFO order,
+      // then closes the vault (registered first, so runs last).
+      shutdownRegistry.closeAllSync();
     },
   };
 }

package/src/runtime/session-briefing.test.ts

@@ -40,6 +40,7 @@ function makeRuntime(overrides?: {
     },
     planner: {
       list: () => o.plans ?? [],
+      closeStale: () => ({ closedIds: [], closedPlans: [] }),
     },
     vault: {
       stats: () => o.vaultStats ?? { totalEntries: 50, byType: { playbook: 5 } },

package/src/runtime/session-briefing.ts

@@ -78,8 +78,17 @@ export function createSessionBriefingOps(runtime: AgentRuntime): OpDefinition[]
           // Session data unavailable — skip
         }
 
-        // 2. Active plans
+        // 2. Active plans — auto-close ancient ones (>24h)
         try {
+          // Auto-close plans stuck in non-terminal states for more than 24h
+          const staleResult = planner.closeStale();
+          if (staleResult.closedPlans.length > 0) {
+            sections.push({
+              label: 'Plans auto-closed',
+              content: `${staleResult.closedPlans.length} stale plan(s) closed: ${staleResult.closedPlans.map((p) => `${p.id.slice(0, 25)}… (${p.reason})`).join(', ')}`,
+            });
+          }
+
           const plans = planner.list();
           const active = plans.filter(
             (p) =>