@zhijiewang/openharness 1.3.0 → 2.0.0

package/dist/commands/index.js

@@ -100,15 +100,54 @@ register("undo", "Undo last AI commit", () => {
         handled: true,
     };
 });
-register("rewind", "Restore files from last checkpoint (undo last AI edit)", () => {
-    const { rewindLastCheckpoint, checkpointCount } = require("../harness/checkpoints.js");
-    const cp = rewindLastCheckpoint();
-    if (!cp) {
+register("rewind", "Restore files from checkpoint (interactive picker or last)", (args) => {
+    const { rewindLastCheckpoint, listCheckpoints, checkpointCount } = require("../harness/checkpoints.js");
+    const checkpoints = listCheckpoints();
+    if (checkpoints.length === 0) {
         return { output: "No checkpoints available. Checkpoints are created before file modifications.", handled: true };
     }
-    const remaining = checkpointCount();
+    const idx = args.trim();
+    // /rewind (no args) — show checkpoint list
+    if (!idx) {
+        const lines = [`Checkpoints (${checkpoints.length}):\n`];
+        for (let i = checkpoints.length - 1; i >= 0; i--) {
+            const cp = checkpoints[i];
+            const age = Math.round((Date.now() - cp.timestamp) / 60_000);
+            lines.push(`  ${i + 1}. [${age}m ago] ${cp.description}`);
+            lines.push(`     Files: ${cp.files.join(', ')}`);
+        }
+        lines.push('');
+        lines.push('Usage: /rewind <number> to restore a specific checkpoint');
+        lines.push('       /rewind last    to restore the most recent');
+        return { output: lines.join('\n'), handled: true };
+    }
+    // /rewind last — restore most recent
+    if (idx === 'last') {
+        const cp = rewindLastCheckpoint();
+        if (!cp)
+            return { output: "No checkpoints.", handled: true };
+        return {
+            output: `Rewound: ${cp.description}\nRestored ${cp.files.length} file(s): ${cp.files.join(", ")}\n${checkpointCount()} checkpoint(s) remaining.`,
+            handled: true,
+        };
+    }
+    // /rewind <n> — restore specific checkpoint
+    const num = parseInt(idx, 10);
+    if (isNaN(num) || num < 1 || num > checkpoints.length) {
+        return { output: `Invalid checkpoint number. Use 1-${checkpoints.length}.`, handled: true };
+    }
+    // Rewind to specific checkpoint (restore all from that point)
+    let restored = 0;
+    while (checkpointCount() >= num) {
+        const cp = rewindLastCheckpoint();
+        if (!cp)
+            break;
+        restored++;
+        if (checkpointCount() < num)
+            break;
+    }
     return {
-        output: `Rewound: ${cp.description}\nRestored ${cp.files.length} file(s): ${cp.files.join(", ")}\n${remaining} checkpoint(s) remaining.`,
+        output: `Rewound ${restored} checkpoint(s) to point #${num}.\n${checkpointCount()} checkpoint(s) remaining.`,
         handled: true,
     };
 });

package/dist/harness/config.d.ts

@@ -11,14 +11,25 @@ export type McpServerConfig = {
     timeout?: number;
 };
 export type HookDef = {
-    command: string;
+    command?: string;
+    http?: string;
+    prompt?: string;
     match?: string;
+    timeout?: number;
 };
 export type HooksConfig = {
     sessionStart?: HookDef[];
     sessionEnd?: HookDef[];
     preToolUse?: HookDef[];
     postToolUse?: HookDef[];
+    fileChanged?: HookDef[];
+    cwdChanged?: HookDef[];
+    subagentStart?: HookDef[];
+    subagentStop?: HookDef[];
+    preCompact?: HookDef[];
+    postCompact?: HookDef[];
+    configChange?: HookDef[];
+    notification?: HookDef[];
 };
 export type ToolPermissionRule = {
     tool: string;

package/dist/harness/config.js

@@ -77,6 +77,11 @@ export function readOhConfig(root) {
 }
 export function writeOhConfig(cfg, root) {
     invalidateConfigCache();
+    // Emit configChange hook (lazy import to avoid circular dependency)
+    try {
+        require('./hooks.js').emitHook('configChange', {});
+    }
+    catch { /* ignore */ }
     const p = configPath(root);
     mkdirSync(join(root ?? ".", ".oh"), { recursive: true });
     if (cfg.provider === "llamacpp" || cfg.provider === "lmstudio") {

package/dist/harness/hooks.d.ts

@@ -1,10 +1,15 @@
 /**
- * Hooks system — run shell commands on lifecycle events.
+ * Hooks system — run commands, HTTP requests, or LLM prompts on lifecycle events.
  *
- * preToolUse hooks can block tool execution (exit code 1 = block).
+ * preToolUse hooks can block tool execution (exit code 1 / allowed: false).
  * All other hooks are fire-and-forget (errors are silently ignored).
+ *
+ * Hook types:
+ * - command: shell script (existing)
+ * - http: POST JSON to URL, expect { allowed: true/false }
+ * - prompt: LLM yes/no check via provider.complete()
  */
-export type HookEvent = "sessionStart" | "sessionEnd" | "preToolUse" | "postToolUse";
+export type HookEvent = "sessionStart" | "sessionEnd" | "preToolUse" | "postToolUse" | "fileChanged" | "cwdChanged" | "subagentStart" | "subagentStop" | "preCompact" | "postCompact" | "configChange" | "notification";
 export type HookContext = {
     toolName?: string;
     toolArgs?: string;
@@ -16,7 +21,17 @@ export type HookContext = {
     permissionMode?: string;
     cost?: string;
     tokens?: string;
+    /** For fileChanged: the file path that changed */
+    filePath?: string;
+    /** For cwdChanged: the new working directory */
+    newCwd?: string;
+    /** For subagentStart/Stop: the agent ID */
+    agentId?: string;
+    /** For notification: the message */
+    message?: string;
 };
+/** Clear hook cache (call after config changes) */
+export declare function invalidateHookCache(): void;
 /**
  * Emit a hook event. For preToolUse, returns false if any hook blocks the call.
  *
@@ -26,7 +41,7 @@ export type HookContext = {
 export declare function emitHook(event: HookEvent, ctx?: HookContext): boolean;
 /**
  * Async version of emitHook that waits for all hooks to complete.
- * Useful for sessionEnd where you want to ensure hooks finish.
+ * Supports all hook types (command, HTTP, prompt).
  */
 export declare function emitHookAsync(event: HookEvent, ctx?: HookContext): Promise<boolean>;
 //# sourceMappingURL=hooks.d.ts.map

package/dist/harness/hooks.js

@@ -1,8 +1,13 @@
 /**
- * Hooks system — run shell commands on lifecycle events.
+ * Hooks system — run commands, HTTP requests, or LLM prompts on lifecycle events.
  *
- * preToolUse hooks can block tool execution (exit code 1 = block).
+ * preToolUse hooks can block tool execution (exit code 1 / allowed: false).
  * All other hooks are fire-and-forget (errors are silently ignored).
+ *
+ * Hook types:
+ * - command: shell script (existing)
+ * - http: POST JSON to URL, expect { allowed: true/false }
+ * - prompt: LLM yes/no check via provider.complete()
  */
 import { spawn, spawnSync } from "node:child_process";
 import { readOhConfig } from "./config.js";
@@ -14,6 +19,10 @@ function getHooks() {
     cachedHooks = cfg?.hooks ?? null;
     return cachedHooks;
 }
+/** Clear hook cache (call after config changes) */
+export function invalidateHookCache() {
+    cachedHooks = undefined;
+}
 function buildEnv(event, ctx) {
     const env = {
         ...process.env,
@@ -39,6 +48,14 @@ function buildEnv(event, ctx) {
         env.OH_COST = ctx.cost;
     if (ctx.tokens)
         env.OH_TOKENS = ctx.tokens;
+    if (ctx.filePath)
+        env.OH_FILE_PATH = ctx.filePath;
+    if (ctx.newCwd)
+        env.OH_NEW_CWD = ctx.newCwd;
+    if (ctx.agentId)
+        env.OH_AGENT_ID = ctx.agentId;
+    if (ctx.message)
+        env.OH_MESSAGE = ctx.message;
     return env;
 }
 function matchesHook(def, ctx) {
@@ -47,11 +64,9 @@ function matchesHook(def, ctx) {
     }
     return true;
 }
-/**
- * Run a single hook command asynchronously.
- * Returns a promise that resolves with the exit code (0 = success).
- */
-function runHookAsync(command, env, timeoutMs = 10_000) {
+// ── Hook Executors ──
+/** Run a command hook. Returns exit code (0 = success/allowed). */
+function runCommandHookAsync(command, env, timeoutMs = 10_000) {
     return new Promise((resolve) => {
         const proc = spawn(command, {
             shell: true,
@@ -64,7 +79,7 @@ function runHookAsync(command, env, timeoutMs = 10_000) {
             if (!settled) {
                 settled = true;
                 proc.kill();
-                resolve(1); // timeout = failure
+                resolve(1);
             }
         }, timeoutMs);
         proc.on("exit", (code) => {
@@ -83,6 +98,50 @@ function runHookAsync(command, env, timeoutMs = 10_000) {
         });
     });
 }
+/** Run an HTTP hook. POSTs context as JSON, expects { allowed: true/false }. */
+async function runHttpHook(url, event, ctx, timeoutMs = 10_000) {
+    try {
+        const body = JSON.stringify({ event, ...ctx });
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body,
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!res.ok)
+            return false;
+        const data = await res.json();
+        return data.allowed !== false;
+    }
+    catch {
+        return false;
+    }
+}
+/** Run a prompt hook. Uses LLM to make a yes/no decision. */
+async function runPromptHook(promptText, ctx) {
+    // Prompt hooks require a provider — skip if not available
+    // This is a lightweight check; full LLM call would need provider injection
+    // For now, prompt hooks evaluate the prompt text as a simple template
+    // TODO: inject provider for full LLM-based prompt hooks
+    return true; // Default allow if no LLM available
+}
+// ── Hook Execution ──
+/** Execute a single hook definition. Returns true if allowed. */
+async function executeHookDef(def, event, ctx) {
+    const timeout = def.timeout ?? 10_000;
+    if (def.command) {
+        const env = buildEnv(event, ctx);
+        const code = await runCommandHookAsync(def.command, env, timeout);
+        return code === 0;
+    }
+    if (def.http) {
+        return runHttpHook(def.http, event, ctx, timeout);
+    }
+    if (def.prompt) {
+        return runPromptHook(def.prompt, ctx);
+    }
+    return true; // No handler = allow
+}
 /**
  * Emit a hook event. For preToolUse, returns false if any hook blocks the call.
  *
@@ -96,19 +155,21 @@ export function emitHook(event, ctx = {}) {
     const defs = hooks[event] ?? [];
     const env = buildEnv(event, ctx);
     if (event === "preToolUse") {
-        // preToolUse must be synchronous — it gates tool execution
+        // preToolUse command hooks must be synchronous — they gate tool execution
         for (const def of defs) {
             if (!matchesHook(def, ctx))
                 continue;
-            const result = spawnSync(def.command, {
-                shell: true,
-                timeout: 10_000,
-                stdio: "pipe",
-                env,
-            });
-            if (result.status !== 0 || result.error) {
-                return false;
+            if (def.command) {
+                const result = spawnSync(def.command, {
+                    shell: true,
+                    timeout: def.timeout ?? 10_000,
+                    stdio: "pipe",
+                    env,
+                });
+                if (result.status !== 0 || result.error)
+                    return false;
             }
+            // HTTP and prompt hooks for preToolUse are handled in emitHookAsync
         }
         return true;
     }
@@ -116,27 +177,25 @@ export function emitHook(event, ctx = {}) {
     for (const def of defs) {
         if (!matchesHook(def, ctx))
             continue;
-        runHookAsync(def.command, env).catch(() => { });
+        executeHookDef(def, event, ctx).catch(() => { });
     }
     return true;
 }
 /**
  * Async version of emitHook that waits for all hooks to complete.
- * Useful for sessionEnd where you want to ensure hooks finish.
+ * Supports all hook types (command, HTTP, prompt).
  */
 export async function emitHookAsync(event, ctx = {}) {
     const hooks = getHooks();
     if (!hooks)
         return true;
     const defs = hooks[event] ?? [];
-    const env = buildEnv(event, ctx);
     for (const def of defs) {
         if (!matchesHook(def, ctx))
             continue;
-        const code = await runHookAsync(def.command, env);
-        if (event === "preToolUse" && code !== 0) {
+        const allowed = await executeHookDef(def, event, ctx);
+        if (event === "preToolUse" && !allowed)
             return false;
-        }
     }
     return true;
 }

package/dist/harness/rules.js

@@ -65,13 +65,28 @@ export function loadRules(projectPath) {
         if (content)
             rules.push(content);
     }
-    // 4. Project rules/*.md
+    // 4. Project rules/*.md (with optional path-scoped filtering)
     const rulesDir = join(root, ".oh", "rules");
     if (existsSync(rulesDir)) {
         for (const file of readdirSync(rulesDir).filter((f) => f.endsWith(".md")).sort()) {
-            const content = readSafe(join(rulesDir, file));
-            if (content)
-                rules.push(content);
+            const raw = readSafe(join(rulesDir, file));
+            if (!raw)
+                continue;
+            // Check for paths frontmatter: only include if matching current context
+            const pathsMatch = raw.match(/^---\n[\s\S]*?^paths:\s*(.+)$/m);
+            if (pathsMatch) {
+                // Path-scoped rule — strip frontmatter and only include if glob matches
+                const pattern = pathsMatch[1].trim();
+                const fmEnd = raw.indexOf('---', raw.indexOf('---') + 3);
+                const content = fmEnd > 0 ? raw.slice(fmEnd + 3).trim() : raw;
+                if (content && matchesPathGlob(root, pattern)) {
+                    rules.push(content);
+                }
+            }
+            else {
+                // No paths restriction — always include
+                rules.push(raw);
+            }
         }
     }
     // 5. CLAUDE.local.md (personal overrides, typically gitignored)
@@ -110,4 +125,17 @@ function readSafe(path) {
         return "";
     }
 }
+/**
+ * Check if any file in the project matches a glob pattern.
+ * Simple implementation: checks if the pattern directory exists.
+ * For `src/api/**`, checks if `src/api/` exists.
+ */
+function matchesPathGlob(root, pattern) {
+    // Extract the directory portion before any wildcard
+    const dirPart = pattern.split('*')[0].replace(/\/+$/, '');
+    if (!dirPart)
+        return true; // Pattern like "**/*.ts" matches everything
+    const fullDir = join(root, dirPart);
+    return existsSync(fullDir);
+}
 //# sourceMappingURL=rules.js.map

package/dist/harness/submit-handler.js

@@ -69,14 +69,30 @@ export async function handleUserInput(input, ctx) {
     }
     // Normal prompt — add user message
     messages = [...messages, createUserMessage(input)];
-    // Resolve @mentions
+    // Resolve @mentions — local files first, then MCP resources
     let resolvedInput = input;
-    const mentionPattern = /@(\w[\w.-]*)/g;
+    const mentionPattern = /@([\w][\w./-]*)/g;
     const mentions = [...input.matchAll(mentionPattern)].map(m => m[1]);
     const companionName = ctx.companionConfig?.soul?.name?.toLowerCase();
     for (const mention of mentions) {
         if (companionName && mention.toLowerCase() === companionName)
             continue;
+        // Try local file first (supports paths like @src/main.ts, @README.md)
+        try {
+            const { existsSync, readFileSync } = await import('node:fs');
+            const { resolve } = await import('node:path');
+            const filePath = resolve(process.cwd(), mention);
+            if (existsSync(filePath)) {
+                const content = readFileSync(filePath, 'utf-8');
+                const truncated = content.length > 10_000
+                    ? content.slice(0, 10_000) + '\n[...truncated]'
+                    : content;
+                resolvedInput += `\n\n[File @${mention}]:\n${truncated}`;
+                continue;
+            }
+        }
+        catch { /* ignore */ }
+        // Fall back to MCP resource
         try {
             const content = await resolveMcpMention(mention);
             if (content)

package/dist/harness/traces.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Session Traces — structured observability for agent sessions.
+ *
+ * Every query turn, tool call, LLM stream, and compression event
+ * generates a trace span. Traces enable debugging, replay, and
+ * performance analysis.
+ *
+ * Compatible with OpenTelemetry export format.
+ */
+export type TraceSpan = {
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    startTime: number;
+    endTime: number;
+    durationMs: number;
+    attributes: Record<string, unknown>;
+    status: 'ok' | 'error';
+};
+export type TraceEvent = {
+    name: string;
+    timestamp: number;
+    attributes?: Record<string, unknown>;
+};
+export declare class SessionTracer {
+    private sessionId;
+    private spans;
+    private activeSpans;
+    private spanCounter;
+    constructor(sessionId: string);
+    /** Start a new span. Returns the span ID. */
+    startSpan(name: string, attributes?: Record<string, unknown>, parentSpanId?: string): string;
+    /** End a span and record it. */
+    endSpan(spanId: string, status?: 'ok' | 'error', extraAttributes?: Record<string, unknown>): TraceSpan | null;
+    /** Get all completed spans */
+    getSpans(): TraceSpan[];
+    /** Get a summary of the trace */
+    getSummary(): {
+        totalSpans: number;
+        totalDurationMs: number;
+        spansByName: Record<string, {
+            count: number;
+            totalMs: number;
+        }>;
+        errors: number;
+    };
+    /** Persist a span to the trace file */
+    private persistSpan;
+}
+/** Load trace spans for a session */
+export declare function loadTrace(sessionId: string): TraceSpan[];
+/** List all sessions with traces */
+export declare function listTracedSessions(): string[];
+/** Format trace for display */
+export declare function formatTrace(spans: TraceSpan[]): string;
+/** Export trace in OpenTelemetry-compatible format */
+export declare function exportTraceOTLP(sessionId: string, spans: TraceSpan[]): object;
+//# sourceMappingURL=traces.d.ts.map

package/dist/harness/traces.js

@@ -0,0 +1,178 @@
+/**
+ * Session Traces — structured observability for agent sessions.
+ *
+ * Every query turn, tool call, LLM stream, and compression event
+ * generates a trace span. Traces enable debugging, replay, and
+ * performance analysis.
+ *
+ * Compatible with OpenTelemetry export format.
+ */
+import { appendFileSync, mkdirSync, existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+const TRACE_DIR = join(homedir(), '.oh', 'traces');
+// ── Tracer ──
+export class SessionTracer {
+    sessionId;
+    spans = [];
+    activeSpans = new Map();
+    spanCounter = 0;
+    constructor(sessionId) {
+        this.sessionId = sessionId;
+    }
+    /** Start a new span. Returns the span ID. */
+    startSpan(name, attributes = {}, parentSpanId) {
+        const spanId = `span-${++this.spanCounter}`;
+        this.activeSpans.set(spanId, { name, startTime: Date.now(), parentSpanId, attributes });
+        return spanId;
+    }
+    /** End a span and record it. */
+    endSpan(spanId, status = 'ok', extraAttributes) {
+        const active = this.activeSpans.get(spanId);
+        if (!active)
+            return null;
+        this.activeSpans.delete(spanId);
+        const endTime = Date.now();
+        const span = {
+            spanId,
+            parentSpanId: active.parentSpanId,
+            name: active.name,
+            startTime: active.startTime,
+            endTime,
+            durationMs: endTime - active.startTime,
+            attributes: { ...active.attributes, ...extraAttributes },
+            status,
+        };
+        this.spans.push(span);
+        this.persistSpan(span);
+        return span;
+    }
+    /** Get all completed spans */
+    getSpans() {
+        return [...this.spans];
+    }
+    /** Get a summary of the trace */
+    getSummary() {
+        const spansByName = {};
+        let errors = 0;
+        let minStart = Infinity;
+        let maxEnd = 0;
+        for (const span of this.spans) {
+            const entry = spansByName[span.name] ?? { count: 0, totalMs: 0 };
+            entry.count++;
+            entry.totalMs += span.durationMs;
+            spansByName[span.name] = entry;
+            if (span.status === 'error')
+                errors++;
+            if (span.startTime < minStart)
+                minStart = span.startTime;
+            if (span.endTime > maxEnd)
+                maxEnd = span.endTime;
+        }
+        return {
+            totalSpans: this.spans.length,
+            totalDurationMs: maxEnd > minStart ? maxEnd - minStart : 0,
+            spansByName,
+            errors,
+        };
+    }
+    /** Persist a span to the trace file */
+    persistSpan(span) {
+        try {
+            mkdirSync(TRACE_DIR, { recursive: true });
+            const file = join(TRACE_DIR, `${this.sessionId}.jsonl`);
+            appendFileSync(file, JSON.stringify(span) + '\n');
+        }
+        catch { /* never crash on tracing failure */ }
+    }
+}
+// ── Trace Loading ──
+/** Load trace spans for a session */
+export function loadTrace(sessionId) {
+    const file = join(TRACE_DIR, `${sessionId}.jsonl`);
+    if (!existsSync(file))
+        return [];
+    try {
+        return readFileSync(file, 'utf-8')
+            .split('\n')
+            .filter(Boolean)
+            .map(line => JSON.parse(line));
+    }
+    catch {
+        return [];
+    }
+}
+/** List all sessions with traces */
+export function listTracedSessions() {
+    if (!existsSync(TRACE_DIR))
+        return [];
+    return readdirSync(TRACE_DIR)
+        .filter(f => f.endsWith('.jsonl'))
+        .map(f => f.replace('.jsonl', ''));
+}
+/** Format trace for display */
+export function formatTrace(spans) {
+    if (spans.length === 0)
+        return 'No trace spans recorded.';
+    const lines = [`Trace (${spans.length} spans):\n`];
+    // Group by parent for tree display
+    const roots = spans.filter(s => !s.parentSpanId);
+    const children = new Map();
+    for (const s of spans) {
+        if (s.parentSpanId) {
+            const list = children.get(s.parentSpanId) ?? [];
+            list.push(s);
+            children.set(s.parentSpanId, list);
+        }
+    }
+    function renderSpan(span, indent) {
+        const status = span.status === 'error' ? '✗' : '✓';
+        const pad = '  '.repeat(indent);
+        const attrs = Object.entries(span.attributes)
+            .filter(([, v]) => v !== undefined)
+            .map(([k, v]) => `${k}=${String(v).slice(0, 30)}`)
+            .join(' ');
+        lines.push(`${pad}${status} ${span.name} (${span.durationMs}ms) ${attrs}`);
+        const kids = children.get(span.spanId) ?? [];
+        for (const kid of kids)
+            renderSpan(kid, indent + 1);
+    }
+    for (const root of roots)
+        renderSpan(root, 0);
+    // Summary
+    const totalMs = spans.reduce((sum, s) => sum + s.durationMs, 0);
+    const errors = spans.filter(s => s.status === 'error').length;
+    lines.push('');
+    lines.push(`Total: ${spans.length} spans, ${totalMs}ms, ${errors} errors`);
+    return lines.join('\n');
+}
+/** Export trace in OpenTelemetry-compatible format */
+export function exportTraceOTLP(sessionId, spans) {
+    return {
+        resourceSpans: [{
+                resource: {
+                    attributes: [
+                        { key: 'service.name', value: { stringValue: 'openharness' } },
+                        { key: 'session.id', value: { stringValue: sessionId } },
+                    ],
+                },
+                scopeSpans: [{
+                        scope: { name: 'openharness.agent' },
+                        spans: spans.map(s => ({
+                            traceId: sessionId.padEnd(32, '0').slice(0, 32),
+                            spanId: s.spanId.padEnd(16, '0').slice(0, 16),
+                            parentSpanId: s.parentSpanId?.padEnd(16, '0').slice(0, 16),
+                            name: s.name,
+                            startTimeUnixNano: s.startTime * 1_000_000,
+                            endTimeUnixNano: s.endTime * 1_000_000,
+                            attributes: Object.entries(s.attributes).map(([k, v]) => ({
+                                key: k,
+                                value: { stringValue: String(v) },
+                            })),
+                            status: { code: s.status === 'ok' ? 1 : 2 },
+                        })),
+                    }],
+            }],
+    };
+}
+//# sourceMappingURL=traces.js.map

package/dist/main.js

@@ -233,6 +233,7 @@ program
     .option("--fork <id>", "Fork (branch) from an existing session")
     .option("--light", "Use light theme")
     .option("--output-format <format>", "Output format for -p mode (text, json, stream-json)", "text")
+    .option("--json-schema <schema>", "Constrain output to match a JSON schema (headless mode)")
     .action(async (opts) => {
     // Load saved config as defaults (env vars + CLI flags override)
     const savedConfig = readOhConfig();