keystone-cli 0.7.2 → 1.0.0

package/src/cli.ts

@@ -1,17 +1,32 @@
 #!/usr/bin/env bun
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { Command } from 'commander';
 
 import exploreAgent from './templates/agents/explore.md' with { type: 'text' };
 import generalAgent from './templates/agents/general.md' with { type: 'text' };
 import architectAgent from './templates/agents/keystone-architect.md' with { type: 'text' };
+import softwareEngineerAgent from './templates/agents/software-engineer.md' with { type: 'text' };
+import summarizerAgent from './templates/agents/summarizer.md' with { type: 'text' };
+import testerAgent from './templates/agents/tester.md' with { type: 'text' };
+import decomposeImplementWorkflow from './templates/decompose-implement.yaml' with { type: 'text' };
+import decomposeWorkflow from './templates/decompose-problem.yaml' with { type: 'text' };
+import decomposeResearchWorkflow from './templates/decompose-research.yaml' with { type: 'text' };
+import decomposeReviewWorkflow from './templates/decompose-review.yaml' with { type: 'text' };
+import devWorkflow from './templates/dev.yaml' with { type: 'text' };
 // Default templates
 import scaffoldWorkflow from './templates/scaffold-feature.yaml' with { type: 'text' };
+import scaffoldGenerateWorkflow from './templates/scaffold-generate.yaml' with { type: 'text' };
+import scaffoldPlanWorkflow from './templates/scaffold-plan.yaml' with { type: 'text' };
 
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
 import { WorkflowDb, type WorkflowRun } from './db/workflow-db.ts';
+import type { TestDefinition } from './parser/test-schema.ts';
 import { WorkflowParser } from './parser/workflow-parser.ts';
+import { WorkflowSuspendedError, WorkflowWaitingError } from './runner/step-executor.ts';
+import { TestHarness } from './runner/test-harness.ts';
 import { ConfigLoader } from './utils/config-loader.ts';
+import { LIMITS } from './utils/constants.ts';
 import { ConsoleLogger } from './utils/logger.ts';
 import { generateMermaidGraph, renderWorkflowAsAscii } from './utils/mermaid.ts';
 import { WorkflowRegistry } from './utils/workflow-registry.ts';
@@ -19,12 +34,85 @@ import { WorkflowRegistry } from './utils/workflow-registry.ts';
 import pkg from '../package.json' with { type: 'json' };
 
 const program = new Command();
+const defaultRetentionDays = ConfigLoader.load().storage?.retention_days ?? 30;
+const MAX_INPUT_STRING_LENGTH = LIMITS.MAX_INPUT_STRING_LENGTH;
 
 program
   .name('keystone')
   .description('A local-first, declarative, agentic workflow orchestrator')
   .version(pkg.version);
 
+/**
+ * Parse CLI input pairs (key=value) into a record.
+ * Attempts JSON parsing for complex types, falls back to string for simple values.
+ *
+ * @param pairs Array of key=value strings
+ * @returns Record of parsed inputs
+ */
+const parseInputs = (pairs?: string[]): Record<string, unknown> => {
+  const inputs: Record<string, unknown> = Object.create(null);
+  const blockedKeys = new Set(['__proto__', 'prototype', 'constructor']);
+  if (!pairs) return inputs;
+  for (const pair of pairs) {
+    const index = pair.indexOf('=');
+    if (index <= 0) {
+      console.warn(`⚠️  Invalid input format: "${pair}" (expected key=value)`);
+      continue;
+    }
+    const key = pair.slice(0, index);
+    const value = pair.slice(index + 1);
+
+    // Validate key format (no special characters that could cause issues)
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(key)) {
+      console.warn(`⚠️  Invalid input key: "${key}" (use alphanumeric and underscores only)`);
+      continue;
+    }
+    if (blockedKeys.has(key)) {
+      console.warn(`⚠️  Invalid input key: "${key}" (reserved keyword)`);
+      continue;
+    }
+
+    try {
+      // Attempt JSON parse for objects, arrays, booleans, numbers
+      const parsed = JSON.parse(value);
+      if (typeof parsed === 'string') {
+        if (parsed.length > MAX_INPUT_STRING_LENGTH) {
+          console.warn(
+            `⚠️  Input "${key}" exceeds maximum length of ${MAX_INPUT_STRING_LENGTH} characters`
+          );
+          continue;
+        }
+        if (parsed.includes('\u0000')) {
+          console.warn(`⚠️  Input "${key}" contains invalid null characters`);
+          continue;
+        }
+      }
+      inputs[key] = parsed;
+    } catch {
+      if (value.length > MAX_INPUT_STRING_LENGTH) {
+        console.warn(
+          `⚠️  Input "${key}" exceeds maximum length of ${MAX_INPUT_STRING_LENGTH} characters`
+        );
+        continue;
+      }
+      if (value.includes('\u0000')) {
+        console.warn(`⚠️  Input "${key}" contains invalid null characters`);
+        continue;
+      }
+      // Check if it looks like malformed JSON (starts with { or [)
+      if ((value.startsWith('{') || value.startsWith('[')) && value.length > 1) {
+        console.warn(
+          `⚠️  Input "${key}" looks like JSON but failed to parse. Check for syntax errors.`
+        );
+        console.warn(`   Value: ${value.slice(0, 50)}${value.length > 50 ? '...' : ''}`);
+      }
+      // Fall back to string value
+      inputs[key] = value;
+    }
+  }
+  return inputs;
+};
+
 // ===== keystone init =====
 program
   .command('init')
@@ -77,9 +165,15 @@ model_mappings:
 #     command: npx
 #     args: ["-y", "@modelcontextprotocol/server-filesystem", "."]
 
+# engines:
+#   allowlist:
+#     codex:
+#       command: codex
+#       version: "1.2.3"
+#       versionArgs: ["--version"]
+
 storage:
   retention_days: 30
-workflows_directory: workflows
 `;
       writeFileSync(configPath, defaultConfig);
       console.log(`✓ Created ${configPath}`);
@@ -106,6 +200,30 @@ workflows_directory: workflows
         path: '.keystone/workflows/scaffold-feature.yaml',
         content: scaffoldWorkflow,
       },
+      {
+        path: '.keystone/workflows/scaffold-plan.yaml',
+        content: scaffoldPlanWorkflow,
+      },
+      {
+        path: '.keystone/workflows/scaffold-generate.yaml',
+        content: scaffoldGenerateWorkflow,
+      },
+      {
+        path: '.keystone/workflows/decompose-problem.yaml',
+        content: decomposeWorkflow,
+      },
+      {
+        path: '.keystone/workflows/decompose-research.yaml',
+        content: decomposeResearchWorkflow,
+      },
+      {
+        path: '.keystone/workflows/decompose-implement.yaml',
+        content: decomposeImplementWorkflow,
+      },
+      {
+        path: '.keystone/workflows/decompose-review.yaml',
+        content: decomposeReviewWorkflow,
+      },
       {
         path: '.keystone/workflows/agents/keystone-architect.md',
         content: architectAgent,
@@ -118,6 +236,22 @@ workflows_directory: workflows
         path: '.keystone/workflows/agents/explore.md',
         content: exploreAgent,
       },
+      {
+        path: '.keystone/workflows/agents/software-engineer.md',
+        content: softwareEngineerAgent,
+      },
+      {
+        path: '.keystone/workflows/agents/summarizer.md',
+        content: summarizerAgent,
+      },
+      {
+        path: '.keystone/workflows/dev.yaml',
+        content: devWorkflow,
+      },
+      {
+        path: '.keystone/workflows/agents/tester.md',
+        content: testerAgent,
+      },
     ];
 
     for (const seed of seeds) {
@@ -141,7 +275,9 @@ program
   .command('validate')
   .description('Validate workflow files')
   .argument('[path]', 'Workflow file or directory to validate (default: .keystone/workflows/)')
-  .action(async (pathArg) => {
+  .option('--strict', 'Enable strict validation (schemas, enums)')
+  .option('--explain', 'Show detailed error context with suggestions')
+  .action(async (pathArg, options) => {
     const path = pathArg || '.keystone/workflows/';
 
     try {
@@ -176,12 +312,35 @@ program
       for (const file of files) {
         try {
           const workflow = WorkflowParser.loadWorkflow(file);
+          if (options.strict) {
+            const source = readFileSync(file, 'utf-8');
+            WorkflowParser.validateStrict(workflow, source);
+          }
           console.log(`  ✓ ${file.padEnd(40)} ${workflow.name} (${workflow.steps.length} steps)`);
           successCount++;
         } catch (error) {
-          console.error(
-            `  ✗ ${file.padEnd(40)} ${error instanceof Error ? error.message : String(error)}`
-          );
+          if (options.explain) {
+            const { readFileSync } = await import('node:fs');
+            const { formatYamlError, renderError, formatError } = await import(
+              './utils/error-renderer.ts'
+            );
+            try {
+              const source = readFileSync(file, 'utf-8');
+              const formatted = formatYamlError(error as Error, source, file);
+              console.error(renderError({ message: formatted.summary, source, filePath: file }));
+            } catch {
+              console.error(
+                renderError({
+                  message: error instanceof Error ? error.message : String(error),
+                  filePath: file,
+                })
+              );
+            }
+          } else {
+            console.error(
+              `  ✗ ${file.padEnd(40)} ${error instanceof Error ? error.message : String(error)}`
+            );
+          }
           failCount++;
         }
       }
@@ -228,38 +387,58 @@ program
   .option('-i, --input <key=value...>', 'Input values')
   .option('--dry-run', 'Show what would be executed without actually running it')
   .option('--debug', 'Enable interactive debug mode on failure')
-  .action(async (workflowPath, options) => {
-    // Parse inputs
-    const inputs: Record<string, unknown> = {};
-    if (options.input) {
-      for (const pair of options.input) {
-        const index = pair.indexOf('=');
-        if (index > 0) {
-          const key = pair.slice(0, index);
-          const value = pair.slice(index + 1);
-          // Try to parse as JSON, otherwise use as string
-          try {
-            inputs[key] = JSON.parse(value);
-          } catch {
-            inputs[key] = value;
-          }
-        }
-      }
-    }
+  .option('--no-dedup', 'Disable idempotency/deduplication')
+  .option('--resume', 'Resume the last run of this workflow if it failed or was paused')
+  .option('--explain', 'Show detailed error context with suggestions on failure')
+  .action(async (workflowPathArg, options) => {
+    const inputs = parseInputs(options.input);
+    let resolvedPath: string | undefined;
 
     // Load and validate workflow
     try {
-      const resolvedPath = WorkflowRegistry.resolvePath(workflowPath);
+      resolvedPath = WorkflowRegistry.resolvePath(workflowPathArg);
       const workflow = WorkflowParser.loadWorkflow(resolvedPath);
 
       // Import WorkflowRunner dynamically
       const { WorkflowRunner } = await import('./runner/workflow-runner.ts');
       const logger = new ConsoleLogger();
+
+      let resumeRunId: string | undefined;
+
+      // Handle auto-resume
+      if (options.resume) {
+        const db = new WorkflowDb();
+        const lastRun = await db.getLastRun(workflow.name);
+        db.close();
+
+        if (lastRun) {
+          if (
+            lastRun.status === 'failed' ||
+            lastRun.status === 'paused' ||
+            lastRun.status === 'running'
+          ) {
+            resumeRunId = lastRun.id;
+            console.log(
+              `Resuming run ${lastRun.id} (status: ${lastRun.status}) from ${new Date(
+                lastRun.started_at
+              ).toLocaleString()}`
+            );
+          } else {
+            console.log(`Last run ${lastRun.id} completed successfully. Starting new run.`);
+          }
+        } else {
+          console.log('No previous run found. Starting new run.');
+        }
+      }
+
       const runner = new WorkflowRunner(workflow, {
-        inputs,
+        inputs: resumeRunId ? undefined : inputs,
+        resumeInputs: resumeRunId ? inputs : undefined,
         workflowDir: dirname(resolvedPath),
         dryRun: !!options.dryRun,
         debug: !!options.debug,
+        dedup: options.dedup,
+        resumeRunId,
         logger,
       });
 
@@ -271,10 +450,108 @@ program
       }
       process.exit(0);
     } catch (error) {
-      console.error(
-        '✗ Failed to execute workflow:',
-        error instanceof Error ? error.message : error
-      );
+      if (options.explain) {
+        const message = error instanceof Error ? error.message : String(error);
+        try {
+          const { readFileSync } = await import('node:fs');
+          const { renderError } = await import('./utils/error-renderer.ts');
+          const source = resolvedPath ? readFileSync(resolvedPath, 'utf-8') : undefined;
+          console.error(
+            renderError({
+              message,
+              source,
+              filePath: resolvedPath,
+            })
+          );
+        } catch {
+          console.error('✗ Failed to execute workflow:', message);
+        }
+      } else {
+        console.error(
+          '✗ Failed to execute workflow:',
+          error instanceof Error ? error.message : error
+        );
+      }
+      process.exit(1);
+    }
+  });
+
+// ===== keystone test =====
+program
+  .command('test')
+  .description('Run workflow tests with fixtures and snapshots')
+  .argument('[path]', 'Test file or directory to run (default: .keystone/tests/)')
+  .option('-u, --update', 'Update snapshots on mismatch or failure')
+  .action(async (pathArg, options) => {
+    const testPath = pathArg || '.keystone/tests/';
+
+    try {
+      let files: string[] = [];
+      if (existsSync(testPath) && (testPath.endsWith('.yaml') || testPath.endsWith('.yml'))) {
+        files = [testPath];
+      } else if (existsSync(testPath)) {
+        const glob = new Bun.Glob('**/*.test.{yaml,yml}');
+        for await (const file of glob.scan(testPath)) {
+          files.push(join(testPath, file));
+        }
+      }
+
+      if (files.length === 0) {
+        console.log('⊘ No test files found.');
+        return;
+      }
+
+      console.log(`🧪 Running ${files.length} test(s)...\n`);
+
+      let totalPassed = 0;
+      let totalFailed = 0;
+
+      for (const file of files) {
+        try {
+          const content = readFileSync(file, 'utf-8');
+          const testDef = parseYaml(content) as TestDefinition;
+
+          console.log(`  ▶ ${testDef.name} (${file})`);
+
+          const workflowPath = WorkflowRegistry.resolvePath(testDef.workflow);
+          const workflow = WorkflowParser.loadWorkflow(workflowPath);
+
+          const harness = new TestHarness(workflow, testDef.fixture);
+          const result = await harness.run();
+
+          if (!testDef.snapshot || options.update) {
+            testDef.snapshot = result;
+            writeFileSync(file, stringifyYaml(testDef));
+            console.log(`    ✓ Snapshot ${options.update ? 'updated' : 'initialized'}`);
+            totalPassed++;
+            continue;
+          }
+
+          // Compare snapshot (simple JSON stringify for now)
+          const expected = JSON.stringify(testDef.snapshot);
+          const actual = JSON.stringify(result);
+
+          if (expected !== actual) {
+            console.error(`    ✗ Snapshot mismatch in ${file}`);
+            totalFailed++;
+          } else {
+            console.log('    ✓ Passed');
+            totalPassed++;
+          }
+        } catch (error) {
+          console.error(
+            `    ✗ Test failed: ${error instanceof Error ? error.message : String(error)}`
+          );
+          totalFailed++;
+        }
+      }
+
+      console.log(`\nSummary: ${totalPassed} passed, ${totalFailed} failed.`);
+      if (totalFailed > 0) {
+        process.exit(1);
+      }
+    } catch (error) {
+      console.error('✗ Test execution failed:', error instanceof Error ? error.message : error);
       process.exit(1);
     }
   });
@@ -314,22 +591,7 @@ program
       const resolvedPath = WorkflowRegistry.resolvePath(workflowPath);
       const workflow = WorkflowParser.loadWorkflow(resolvedPath);
 
-      // Parse inputs
-      const inputs: Record<string, unknown> = {};
-      if (options.input) {
-        for (const pair of options.input) {
-          const index = pair.indexOf('=');
-          if (index > 0) {
-            const key = pair.slice(0, index);
-            const value = pair.slice(index + 1);
-            try {
-              inputs[key] = JSON.parse(value);
-            } catch {
-              inputs[key] = value;
-            }
-          }
-        }
-      }
+      const inputs = parseInputs(options.input);
 
       const runner = new OptimizationRunner(workflow, {
         workflowPath: resolvedPath,
@@ -359,6 +621,7 @@ program
   .description('Resume a paused or failed workflow run')
   .argument('<run_id>', 'Run ID to resume')
   .option('-w, --workflow <path>', 'Path to workflow file (auto-detected if not specified)')
+  .option('-i, --input <key=value...>', 'Input values for resume')
   .action(async (runId, options) => {
     try {
       const db = new WorkflowDb();
@@ -400,8 +663,10 @@ program
       // Import WorkflowRunner dynamically
       const { WorkflowRunner } = await import('./runner/workflow-runner.ts');
       const logger = new ConsoleLogger();
+      const inputs = parseInputs(options.input);
       const runner = new WorkflowRunner(workflow, {
         resumeRunId: runId,
+        resumeInputs: inputs,
         workflowDir: dirname(workflowPath),
         logger,
       });
@@ -500,6 +765,124 @@ program
     }
   });
 
+// ===== keystone compile =====
+program
+  .command('compile')
+  .description('Compile a project into a single executable with embedded assets')
+  .option('-o, --outfile <path>', 'Output executable path', 'keystone-app')
+  .option('--project <path>', 'Project directory (default: .)', '.')
+  .action(async (options) => {
+    const { spawnSync } = await import('node:child_process');
+    const { resolve, join } = await import('node:path');
+    const { existsSync } = await import('node:fs');
+
+    const projectDir = resolve(options.project);
+    const keystoneDir = join(projectDir, '.keystone');
+
+    if (!existsSync(keystoneDir)) {
+      console.error(`✗ No .keystone directory found at ${projectDir}`);
+      process.exit(1);
+    }
+
+    console.log(`🏗️  Compiling project at ${projectDir}...`);
+    console.log(`📂 Embedding assets from ${keystoneDir}`);
+
+    // Find the CLI source path
+    const cliSource = resolve(import.meta.dir, 'cli.ts');
+
+    const buildArgs = ['build', cliSource, '--compile', '--outfile', options.outfile];
+
+    console.log(`🚀 Running: ASSETS_DIR=${keystoneDir} bun ${buildArgs.join(' ')}`);
+
+    const result = spawnSync('bun', buildArgs, {
+      env: {
+        ...process.env,
+        ASSETS_DIR: keystoneDir,
+      },
+      stdio: 'inherit',
+    });
+
+    if (result.status === 0) {
+      console.log(`\n✨ Successfully compiled to ${options.outfile}`);
+      console.log(`   You can now run ./${options.outfile} anywhere!`);
+    } else {
+      console.error(`\n✗ Compilation failed with exit code ${result.status}`);
+      process.exit(1);
+    }
+  });
+
+// ===== keystone dev =====
+program
+  .command('dev')
+  .description('Run the self-bootstrapping DevMode workflow')
+  .argument('<task>', 'The development task to perform')
+  .option('--auto-approve', 'Skip the plan approval step', false)
+  .action(async (task, options) => {
+    try {
+      // Find the dev workflow path
+      // Priority:
+      // 1. Local .keystone/workflows/dev.yaml
+      // 2. Embedded resource
+      let devPath: string;
+      try {
+        devPath = WorkflowRegistry.resolvePath('dev');
+      } catch {
+        // Fallback to searching in templates if not indexed yet
+        devPath = join(process.cwd(), '.keystone/workflows/dev.yaml');
+        if (!existsSync(devPath)) {
+          console.error('✗ Dev workflow not found. Run "keystone init" to seed it.');
+          process.exit(1);
+        }
+      }
+
+      console.log(`🏗️  Starting DevMode for task: ${task}\n`);
+
+      // Import WorkflowRunner dynamically
+      const { WorkflowRunner } = await import('./runner/workflow-runner.ts');
+      const { WorkflowParser } = await import('./parser/workflow-parser.ts');
+      const logger = new ConsoleLogger();
+
+      const workflow = WorkflowParser.loadWorkflow(devPath);
+      const runner = new WorkflowRunner(workflow, {
+        inputs: { task, auto_approve: options.auto_approve },
+        workflowDir: dirname(devPath),
+        logger,
+        allowInsecure: true, // Trusted internal workflow
+      });
+
+      const outputs = await runner.run();
+      if (Object.keys(outputs).length > 0) {
+        console.log('\nDevMode Summary:');
+        console.log(JSON.stringify(runner.redact(outputs), null, 2));
+      }
+      process.exit(0);
+    } catch (error) {
+      console.error('\n✗ DevMode failed:', error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
+// ===== keystone manifest =====
+program
+  .command('manifest')
+  .description('Show embedded assets manifest')
+  .action(async () => {
+    const { ResourceLoader } = await import('./utils/resource-loader.ts');
+    const assets = ResourceLoader.getEmbeddedAssets();
+    const keys = Object.keys(assets);
+
+    if (keys.length === 0) {
+      console.log('No embedded assets found.');
+      return;
+    }
+
+    console.log(`\n📦 Embedded Assets (${keys.length}):`);
+    for (const key of keys.sort()) {
+      console.log(`  - ${key} (${assets[key].length} bytes)`);
+    }
+    console.log('');
+  });
+
 async function showRunLogs(run: WorkflowRun, db: WorkflowDb, verbose: boolean) {
   console.log(`\n🏛️  Run: ${run.workflow_name} (${run.id})`);
   console.log(`   Status: ${run.status}`);
@@ -578,7 +961,7 @@ async function performMaintenance(days: number) {
 program
   .command('prune')
   .description('Delete old workflow runs from the database (alias for maintenance)')
-  .option('--days <number>', 'Days to keep', '30')
+  .option('--days <number>', 'Days to keep', String(defaultRetentionDays))
   .action(async (options) => {
     const days = Number.parseInt(options.days, 10);
     await performMaintenance(days);
@@ -587,12 +970,236 @@ program
 program
   .command('maintenance')
   .description('Perform database maintenance (prune old runs and vacuum)')
-  .option('--days <days>', 'Delete runs older than this many days', '30')
+  .option('--days <days>', 'Delete runs older than this many days', String(defaultRetentionDays))
   .action(async (options) => {
     const days = Number.parseInt(options.days, 10);
     await performMaintenance(days);
   });
 
+// ===== keystone dedup =====
+const dedup = program.command('dedup').description('Manage idempotency/deduplication records');
+
+dedup
+  .command('list')
+  .description('List idempotency records')
+  .argument('[run_id]', 'Filter by run ID (optional)')
+  .action(async (runId) => {
+    try {
+      const db = new WorkflowDb();
+      const records = await db.listIdempotencyRecords(runId);
+      db.close();
+
+      if (records.length === 0) {
+        console.log('No idempotency records found.');
+        return;
+      }
+
+      console.log('\n🔑 Idempotency Records:');
+      console.log(''.padEnd(100, '-'));
+      console.log(
+        `${'Key'.padEnd(30)} ${'Step'.padEnd(15)} ${'Status'.padEnd(10)} ${'Created At'}`
+      );
+      console.log(''.padEnd(100, '-'));
+
+      for (const record of records) {
+        const key = record.idempotency_key.slice(0, 28);
+        console.log(
+          `${key.padEnd(30)} ${record.step_id.padEnd(15)} ${record.status.padEnd(10)} ${record.created_at}`
+        );
+      }
+      console.log(`\nTotal: ${records.length} record(s)`);
+    } catch (error) {
+      console.error('✗ Failed to list records:', error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
+dedup
+  .command('clear')
+  .description('Clear idempotency records')
+  .argument('<target>', 'Run ID to clear, or "--all" to clear all records')
+  .action(async (target) => {
+    try {
+      const db = new WorkflowDb();
+      let count: number;
+
+      if (target === '--all') {
+        count = await db.clearAllIdempotencyRecords();
+        console.log(`✓ Cleared ${count} idempotency record(s)`);
+      } else {
+        count = await db.clearIdempotencyRecords(target);
+        console.log(`✓ Cleared ${count} idempotency record(s) for run ${target.slice(0, 8)}`);
+      }
+
+      db.close();
+    } catch (error) {
+      console.error('✗ Failed to clear records:', error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
+dedup
+  .command('prune')
+  .description('Remove expired idempotency records')
+  .action(async () => {
+    try {
+      const db = new WorkflowDb();
+      const count = await db.pruneIdempotencyRecords();
+      db.close();
+      console.log(`✓ Pruned ${count} expired idempotency record(s)`);
+    } catch (error) {
+      console.error('✗ Failed to prune records:', error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
+// ===== keystone scheduler =====
+program
+  .command('scheduler')
+  .description('Run the durable timer scheduler (polls for ready timers)')
+  .option('-i, --interval <seconds>', 'Poll interval in seconds', '30')
+  .option('--once', "Run once and exit (don't poll)")
+  .action(async (options) => {
+    const interval = Number.parseInt(options.interval, 10) * 1000;
+    const db = new WorkflowDb();
+
+    console.log('🏛️  Keystone Durable Timer Scheduler');
+    console.log(`📡 Polling every ${options.interval}s for ready timers...`);
+
+    const poll = async () => {
+      try {
+        const pending = await db.getPendingTimers(undefined, 'sleep');
+        if (pending.length > 0) {
+          console.log(`\n⏰ Found ${pending.length} ready timer(s)`);
+
+          for (const timer of pending) {
+            console.log(`   - Resuming run ${timer.run_id.slice(0, 8)} (step: ${timer.step_id})`);
+
+            // Load run to get workflow name
+            const run = await db.getRun(timer.run_id);
+            if (!run) {
+              console.warn(`     ⚠️ Run ${timer.run_id} not found in DB`);
+              continue;
+            }
+
+            try {
+              const workflowPath = WorkflowRegistry.resolvePath(run.workflow_name);
+              const workflow = WorkflowParser.loadWorkflow(workflowPath);
+
+              const { WorkflowRunner } = await import('./runner/workflow-runner.ts');
+              const runner = new WorkflowRunner(workflow, {
+                resumeRunId: timer.run_id,
+                workflowDir: dirname(workflowPath),
+                logger: new ConsoleLogger(),
+              });
+
+              // Running this in current process iteration
+              // The runner will handle checking the timer status in restoreState
+              await runner.run();
+              console.log(`     ✓ Run ${timer.run_id.slice(0, 8)} resumed and finished/paused`);
+            } catch (err) {
+              if (err instanceof WorkflowWaitingError || err instanceof WorkflowSuspendedError) {
+                // This is expected if it hits another wait/human step
+                console.log(`     ⏸ Run ${timer.run_id.slice(0, 8)} paused/waiting again`);
+              } else {
+                console.error(
+                  `     ✗ Failed to resume run ${timer.run_id.slice(0, 8)}:`,
+                  err instanceof Error ? err.message : String(err)
+                );
+              }
+            }
+          }
+        }
+      } catch (err) {
+        console.error('✗ Scheduler error:', err instanceof Error ? err.message : String(err));
+      }
+    };
+
+    if (options.once) {
+      await poll();
+      db.close();
+      process.exit(0);
+    }
+
+    // Polling loop
+    await poll();
+    setInterval(poll, interval);
+
+    // Keep process alive
+    process.on('SIGINT', () => {
+      console.log('\n👋 Scheduler stopping...');
+      db.close();
+      process.exit(0);
+    });
+  });
+
+// ===== keystone timers =====
+const timersCmd = program.command('timers').description('Manage durable timers');
+
+timersCmd
+  .command('list')
+  .description('List pending timers')
+  .option('-r, --run <run_id>', 'Filter by run ID')
+  .action(async (options) => {
+    try {
+      const db = new WorkflowDb();
+      const timers = await db.listTimers(options.run);
+      db.close();
+
+      if (timers.length === 0) {
+        console.log('No durable timers found.');
+        return;
+      }
+
+      console.log('\n⏰ Durable Timers:');
+      console.log(''.padEnd(100, '-'));
+      console.log(
+        `${'ID'.padEnd(10)} ${'Run'.padEnd(15)} ${'Step'.padEnd(20)} ${'Type'.padEnd(10)} ${'Wake At'}`
+      );
+      console.log(''.padEnd(100, '-'));
+
+      for (const timer of timers) {
+        const id = timer.id.slice(0, 8);
+        const run = timer.run_id.slice(0, 8);
+        const wakeAt = timer.wake_at ? new Date(timer.wake_at).toLocaleString() : 'N/A';
+        const statusStr = timer.completed_at
+          ? ` (DONE at ${new Date(timer.completed_at).toLocaleTimeString()})`
+          : '';
+
+        console.log(
+          `${id.padEnd(10)} ${run.padEnd(15)} ${timer.step_id.padEnd(20)} ${timer.timer_type.padEnd(
+            10
+          )} ${wakeAt}${statusStr}`
+        );
+      }
+      console.log(`\nTotal: ${timers.length} timer(s)`);
+    } catch (error) {
+      console.error('✗ Failed to list timers:', error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
+timersCmd
+  .command('clear')
+  .description('Clear pending timers')
+  .option('-r, --run <run_id>', 'Clear timers for a specific run')
+  .option('--all', 'Clear all timers')
+  .action(async (options) => {
+    try {
+      if (!options.all && !options.run) {
+        console.error('✗ Please specify --run <id> or --all');
+        process.exit(1);
+      }
+      const db = new WorkflowDb();
+      const count = await db.clearTimers(options.run);
+      db.close();
+      console.log(`✓ Cleared ${count} timer(s)`);
+    } catch (error) {
+      console.error('✗ Failed to clear timers:', error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
 // ===== keystone ui =====
 program
   .command('ui')
@@ -706,15 +1313,26 @@ mcp
   });
 
 // ===== keystone config =====
-program
-  .command('config')
-  .description('Show current configuration')
+const configCmd = program.command('config').description('Configuration management');
+
+configCmd
+  .command('show')
+  .alias('list')
+  .description('Show current configuration and discovery paths')
   .action(async () => {
     const { ConfigLoader } = await import('./utils/config-loader.ts');
+    const { PathResolver } = await import('./utils/paths.ts');
     try {
       const config = ConfigLoader.load();
       console.log('\n🏛️  Keystone Configuration:');
       console.log(JSON.stringify(config, null, 2));
+
+      console.log('\n🔍 Configuration Search Paths (in precedence order):');
+      const paths = PathResolver.getConfigPaths();
+      for (const [i, p] of paths.entries()) {
+        const exists = existsSync(p) ? '✓' : '⊘';
+        console.log(`  ${i + 1}. ${exists} ${p}`);
+      }
     } catch (error) {
       console.error('✗ Failed to load config:', error instanceof Error ? error.message : error);
     }
@@ -727,16 +1345,13 @@ auth
   .command('login')
   .description('Login to an authentication provider')
   .argument('[provider]', 'Authentication provider', 'github')
-  .option(
-    '-p, --provider <provider>',
-    'Authentication provider (deprecated, use positional argument)'
-  )
   .option('-t, --token <token>', 'Personal Access Token (if not using interactive mode)')
-  .action(async (providerArg, options) => {
+  .option('--project <project_id>', 'Google Cloud project ID (Gemini OAuth)')
+  .action(async (provider, options) => {
     const { AuthManager } = await import('./utils/auth-manager.ts');
-    const provider = (options.provider || providerArg).toLowerCase();
+    const providerName = provider.toLowerCase();
 
-    if (provider === 'github') {
+    if (providerName === 'github') {
       let token = options.token;
 
       if (!token) {
@@ -791,12 +1406,87 @@ auth
         console.error('✗ No token provided.');
         process.exit(1);
       }
-    } else if (provider === 'openai' || provider === 'anthropic') {
+    } else if (providerName === 'openai-chatgpt') {
+      try {
+        await AuthManager.loginOpenAIChatGPT();
+        console.log('\n✓ Successfully logged in to OpenAI ChatGPT.');
+        return;
+      } catch (error) {
+        console.error(
+          '\n✗ Failed to login with OpenAI ChatGPT:',
+          error instanceof Error ? error.message : error
+        );
+        process.exit(1);
+      }
+    } else if (providerName === 'anthropic-claude') {
+      try {
+        const { url, verifier } = AuthManager.createAnthropicClaudeAuth();
+
+        console.log('\nTo login with Anthropic Claude (Pro/Max):');
+        console.log('1. Visit the following URL in your browser:');
+        console.log(`   ${url}\n`);
+        console.log('2. Copy the authorization code and paste it below:\n');
+
+        try {
+          const { platform } = process;
+          const command =
+            platform === 'win32' ? 'start' : platform === 'darwin' ? 'open' : 'xdg-open';
+          const { spawn } = require('node:child_process');
+          spawn(command, [url]);
+        } catch (e) {
+          // Ignore if we can't open the browser automatically
+        }
+
+        let code = options.token;
+        if (!code) {
+          const prompt = 'Authorization Code: ';
+          process.stdout.write(prompt);
+          for await (const line of console) {
+            code = line.trim();
+            break;
+          }
+        }
+
+        if (!code) {
+          console.error('✗ No authorization code provided.');
+          process.exit(1);
+        }
+
+        const data = await AuthManager.exchangeAnthropicClaudeCode(code, verifier);
+        AuthManager.save({
+          anthropic_claude: {
+            access_token: data.access_token,
+            refresh_token: data.refresh_token,
+            expires_at: Math.floor(Date.now() / 1000) + data.expires_in,
+          },
+        });
+        console.log('\n✓ Successfully logged in to Anthropic Claude.');
+        return;
+      } catch (error) {
+        console.error(
+          '\n✗ Failed to login with Anthropic Claude:',
+          error instanceof Error ? error.message : error
+        );
+        process.exit(1);
+      }
+    } else if (providerName === 'gemini' || providerName === 'google-gemini') {
+      try {
+        await AuthManager.loginGoogleGemini(options.project);
+        console.log('\n✓ Successfully logged in to Google Gemini.');
+        return;
+      } catch (error) {
+        console.error(
+          '\n✗ Failed to login with Google Gemini:',
+          error instanceof Error ? error.message : error
+        );
+        process.exit(1);
+      }
+    } else if (providerName === 'openai' || providerName === 'anthropic') {
       let key = options.token; // Use --token if provided as the API key
 
       if (!key) {
-        console.log(`\n🔑 Login to ${provider.toUpperCase()}`);
-        console.log(`   Please provide your ${provider.toUpperCase()} API key.\n`);
+        console.log(`\n🔑 Login to ${providerName.toUpperCase()}`);
+        console.log(`   Please provide your ${providerName.toUpperCase()} API key.\n`);
         const prompt = 'API Key: ';
         process.stdout.write(prompt);
         for await (const line of console) {
@@ -806,18 +1496,18 @@ auth
       }
 
       if (key) {
-        if (provider === 'openai') {
+        if (providerName === 'openai') {
           AuthManager.save({ openai_api_key: key });
         } else {
           AuthManager.save({ anthropic_api_key: key });
         }
-        console.log(`\n✓ Successfully saved ${provider.toUpperCase()} API key.`);
+        console.log(`\n✓ Successfully saved ${providerName.toUpperCase()} API key.`);
       } else {
         console.error('✗ No API key provided.');
         process.exit(1);
       }
     } else {
-      console.error(`✗ Unsupported provider: ${provider}`);
+      console.error(`✗ Unsupported provider: ${providerName}`);
       process.exit(1);
     }
   });
@@ -826,49 +1516,91 @@ auth
   .command('status')
   .description('Show authentication status')
   .argument('[provider]', 'Authentication provider')
-  .option('-p, --provider <provider>', 'Authentication provider')
-  .action(async (providerArg, options) => {
+  .action(async (provider) => {
     const { AuthManager } = await import('./utils/auth-manager.ts');
     const auth = AuthManager.load();
-    const provider = (options.provider || providerArg)?.toLowerCase();
+    const providerName = provider?.toLowerCase();
 
     console.log('\n🏛️  Authentication Status:');
 
-    if (!provider || provider === 'github' || provider === 'copilot') {
+    if (!providerName || providerName === 'github' || providerName === 'copilot') {
       if (auth.github_token) {
         console.log('  ✓ Logged into GitHub');
         if (auth.copilot_expires_at) {
           const expires = new Date(auth.copilot_expires_at * 1000);
           console.log(`  ✓ Copilot session expires: ${expires.toLocaleString()}`);
         }
-      } else if (provider) {
+      } else if (providerName) {
         console.log(
           `  ⊘ Not logged into GitHub. Run "keystone auth login github" to authenticate.`
         );
       }
     }
 
-    if (!provider || provider === 'openai') {
+    if (!providerName || providerName === 'openai' || providerName === 'openai-chatgpt') {
       if (auth.openai_api_key) {
         console.log('  ✓ OpenAI API key configured');
-      } else if (provider) {
+      }
+      if (auth.openai_chatgpt) {
+        console.log('  ✓ OpenAI ChatGPT subscription (OAuth) authenticated');
+        if (auth.openai_chatgpt.expires_at) {
+          const expires = new Date(auth.openai_chatgpt.expires_at * 1000);
+          console.log(`    Session expires: ${expires.toLocaleString()}`);
+        }
+      }
+
+      if (providerName && !auth.openai_api_key && !auth.openai_chatgpt) {
         console.log(
-          `  ⊘ OpenAI API key not configured. Run "keystone auth login openai" to authenticate.`
+          `  ⊘ OpenAI authentication not configured. Run "keystone auth login openai" or "keystone auth login openai-chatgpt" to authenticate.`
         );
       }
     }
 
-    if (!provider || provider === 'anthropic') {
+    if (!providerName || providerName === 'anthropic' || providerName === 'anthropic-claude') {
       if (auth.anthropic_api_key) {
         console.log('  ✓ Anthropic API key configured');
-      } else if (provider) {
+      }
+      if (auth.anthropic_claude) {
+        console.log('  ✓ Anthropic Claude subscription (OAuth) authenticated');
+        if (auth.anthropic_claude.expires_at) {
+          const expires = new Date(auth.anthropic_claude.expires_at * 1000);
+          console.log(`    Session expires: ${expires.toLocaleString()}`);
+        }
+      }
+
+      if (providerName && !auth.anthropic_api_key && !auth.anthropic_claude) {
+        console.log(
+          `  ⊘ Anthropic authentication not configured. Run "keystone auth login anthropic" or "keystone auth login anthropic-claude" to authenticate.`
+        );
+      }
+    }
+
+    if (!providerName || providerName === 'gemini' || providerName === 'google-gemini') {
+      if (auth.google_gemini) {
+        console.log('  ✓ Google Gemini subscription (OAuth) authenticated');
+        if (auth.google_gemini.email) {
+          console.log(`    Account: ${auth.google_gemini.email}`);
+        }
+        if (auth.google_gemini.expires_at) {
+          const expires = new Date(auth.google_gemini.expires_at * 1000);
+          console.log(`    Session expires: ${expires.toLocaleString()}`);
+        }
+      } else if (providerName) {
         console.log(
-          `  ⊘ Anthropic API key not configured. Run "keystone auth login anthropic" to authenticate.`
+          `  ⊘ Google Gemini authentication not configured. Run "keystone auth login gemini" to authenticate.`
         );
       }
     }
 
-    if (!auth.github_token && !auth.openai_api_key && !auth.anthropic_api_key && !provider) {
+    if (
+      !auth.github_token &&
+      !auth.openai_api_key &&
+      !auth.openai_chatgpt &&
+      !auth.anthropic_api_key &&
+      !auth.anthropic_claude &&
+      !auth.google_gemini &&
+      !providerName
+    ) {
       console.log('  ⊘ No providers configured. Run "keystone auth login" to authenticate.');
     }
   });
@@ -877,29 +1609,42 @@ auth
   .command('logout')
   .description('Logout and clear authentication tokens')
   .argument('[provider]', 'Authentication provider')
-  .option(
-    '-p, --provider <provider>',
-    'Authentication provider (deprecated, use positional argument)'
-  )
-  .action(async (providerArg, options) => {
+  .action(async (provider) => {
     const { AuthManager } = await import('./utils/auth-manager.ts');
-    const provider = (options.provider || providerArg)?.toLowerCase();
+    const providerName = provider?.toLowerCase();
 
-    if (!provider || provider === 'github' || provider === 'copilot') {
+    const auth = AuthManager.load();
+
+    if (!providerName || providerName === 'github' || providerName === 'copilot') {
       AuthManager.save({
         github_token: undefined,
         copilot_token: undefined,
         copilot_expires_at: undefined,
       });
       console.log('✓ Successfully logged out of GitHub.');
-    } else if (provider === 'openai') {
-      AuthManager.save({ openai_api_key: undefined });
-      console.log('✓ Successfully cleared OpenAI API key.');
-    } else if (provider === 'anthropic') {
-      AuthManager.save({ anthropic_api_key: undefined });
-      console.log('✓ Successfully cleared Anthropic API key.');
+    } else if (providerName === 'openai' || providerName === 'openai-chatgpt') {
+      AuthManager.save({
+        openai_api_key: providerName === 'openai' ? undefined : auth.openai_api_key,
+        openai_chatgpt: undefined,
+      });
+      console.log(
+        `✓ Successfully cleared ${providerName === 'openai' ? 'OpenAI API key and ' : ''}ChatGPT session.`
+      );
+    } else if (providerName === 'anthropic' || providerName === 'anthropic-claude') {
+      AuthManager.save({
+        anthropic_api_key: providerName === 'anthropic' ? undefined : auth.anthropic_api_key,
+        anthropic_claude: undefined,
+      });
+      console.log(
+        `✓ Successfully cleared ${providerName === 'anthropic' ? 'Anthropic API key and ' : ''}Claude session.`
+      );
+    } else if (providerName === 'gemini' || providerName === 'google-gemini') {
+      AuthManager.save({
+        google_gemini: undefined,
+      });
+      console.log('✓ Successfully cleared Google Gemini session.');
     } else {
-      console.error(`✗ Unknown provider: ${provider}`);
+      console.error(`✗ Unknown provider: ${providerName}`);
       process.exit(1);
     }
   });
@@ -979,7 +1724,12 @@ _keystone() {
         validate)
           _arguments ':path:_files'
           ;;
-        resume|logs)
+        resume)
+          _arguments \\
+            '(-i --input)'{-i,--input}'[Input values]:key=value' \\
+            ':run_id:__keystone_runs'
+          ;;
+        logs)
           _arguments ':run_id:__keystone_runs'
           ;;
         auth)