openlore 2.0.10 → 2.0.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openlore",
-  "version": "2.0.10",
+  "version": "2.0.12",
   "description": "Reverse-engineer OpenSpec specifications from existing codebases",
   "type": "module",
   "main": "dist/api/index.js",
@@ -50,8 +50,18 @@
     "documentation",
     "reverse-engineering",
     "specification",
-    "cli"
+    "cli",
+    "pi-package"
   ],
+  "pi": {
+    "extensions": [
+      "./dist/pi/extension.js"
+    ],
+    "skills": [
+      "./examples/opencode-skills",
+      "./skills/openlore-orient"
+    ]
+  },
   "author": "Clay Good",
   "license": "MIT",
   "repository": {
@@ -70,6 +80,7 @@
     "!dist/**/*.test.*",
     "src/viewer",
     "examples",
+    "skills/openlore-orient",
     "stubs",
     "schemas",
     "README.md",
@@ -126,6 +137,8 @@
     "tree-sitter-cli": "file:stubs/tree-sitter-cli-stub"
   },
   "devDependencies": {
+    "@earendil-works/pi-ai": "^0.78.1",
+    "@earendil-works/pi-coding-agent": "^0.78.1",
     "@eslint/js": "^9.17.0",
     "@types/node": "^22.10.5",
     "@vitest/coverage-v8": "^4.0.18",
@@ -133,6 +146,7 @@
     "globals": "^16.0.0",
     "memfs": "^4.15.0",
     "tsx": "^4.19.2",
+    "typebox": "1.1.38",
     "typescript": "^5.7.2",
     "typescript-eslint": "^8.19.1",
     "vitest": "^4.0.18"

package/skills/openlore-orient/README.md

@@ -0,0 +1,73 @@
+# openlore-orient — Claude Code Skill
+
+A drop-in Claude Code [Skill](https://docs.claude.com/en/docs/claude-code/skills) that teaches the model to call OpenLore's `orient()` at the start of every task in this repo, instead of grepping blind.
+
+## What it is
+
+OpenLore maintains a deterministic, graph-native model of your codebase — every function, every caller, every spec section, every file. The `orient` tool collapses what would otherwise be a chain of `analyze_codebase → search_code → search_specs → suggest_insertion_points` into a single call that returns the exact context the agent needs for the task at hand.
+
+This skill bundle ships the prompt and the wrappers Claude Code needs to know about `orient`. Once installed, Claude Code's system prompt picks it up automatically and the model invokes it when relevant — no `CLAUDE.md` editing required.
+
+## Install
+
+### Option 1 — user-scope (recommended)
+
+Available across every project on your machine. From the OpenLore repo root:
+
+```sh
+npm run skill:install-local
+```
+
+This copies `skills/openlore-orient/` into `~/.claude/skills/openlore-orient/`. Idempotent — re-run any time to upgrade.
+
+### Option 2 — project-scope
+
+Available only in the current project. From this OpenLore repo:
+
+```sh
+cp -R skills/openlore-orient /path/to/your-project/.claude/skills/
+```
+
+### Option 3 — via `openlore install` *(future)*
+
+Once OpenLore spec-01's `openlore install --agent claude-code` is shipped on npm, it will copy this skill into the target project's `.claude/skills/` automatically as part of the standard install flow. No separate step needed.
+
+## What's in the bundle
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | The manifest + instructions Claude Code reads. Frontmatter declares the skill; body sections describe when/how/what-not-to-do. |
+| `scripts/orient.sh` | POSIX wrapper. Prefers `npx openlore orient --json --task ...` (once shipped); falls back to the MCP path. |
+| `scripts/orient.ps1` | PowerShell equivalent for Windows. |
+| `scripts/orient-via-mcp.mjs` | Node helper that drives `openlore mcp` over stdio JSON-RPC. Used by the wrappers as a fallback. Pure Node built-ins, no deps. |
+| `examples/example-orient-output.json` | Real (redacted) output captured from this repo, so a reader can see the JSON shape without us writing a schema doc. |
+| `examples/example-task-prompt.md` | A short worked example of the full loop: task → orient call → output → next step. |
+
+## Performance & transparency (opt-in)
+
+`orient` is deterministic and local — no LLM, no API key, no network call. A typical call against a
+warm graph returns in well under a second; a cold first call may take a couple of seconds while the
+on-disk index loads, after which the in-memory cache serves the rest of the session.
+
+We deliberately keep these numbers **out of `SKILL.md`** so nothing is loaded into the agent's context
+unless you ask for it. If you want to measure on your own repo, the capability is built in as a flag:
+
+```sh
+openlore orient --metrics --task "your task"
+# wall time + output size are reported on stderr; the result on stdout is unchanged
+```
+
+The end-to-end, task-dependent benchmark numbers (wins *and* the small-repo loss cases) live in the
+main project README's [Value Scorecard](https://github.com/clay-good/OpenLore#value-scorecard--does-it-pay-for-itself).
+Links here use absolute URLs on purpose: copying this bundle into another project's `.claude/skills/`
+must never produce a broken relative link.
+
+## Known limitations
+
+The `openlore orient --json --task "..."` CLI subcommand is shipped, and `orient` is also exposed as an MCP tool. The shell wrappers prefer the CLI subcommand and transparently fall back to driving `openlore mcp` over stdio JSON-RPC via the bundled [`scripts/orient-via-mcp.mjs`](scripts/orient-via-mcp.mjs) helper on older openlore versions that predate the subcommand.
+
+See `TODO(spec-02-followup)` markers in `SKILL.md` and the wrappers.
+
+## License
+
+MIT, matching the [parent OpenLore repository](https://github.com/clay-good/OpenLore).

package/skills/openlore-orient/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: openlore-orient
+version: 2.1
+description: Persistent architectural memory for this codebase. Call `orient(task)` before reading source files to get the relevant functions, callers, spec sections, and insertion points for any task — one structural lookup instead of file-by-file rediscovery.
+---
+
+# OpenLore — orient before you read
+
+This project uses **OpenLore** to maintain a deterministic, graph-native model of the codebase: every function, every caller, every spec section, every file. The `orient` tool collapses what would otherwise be a chain of `analyze_codebase → search_code → search_specs → suggest_insertion_points` into a single call.
+
+The single most important habit when working in this repo: **call `orient` before opening source files for any non-trivial task.**
+
+## When to use this skill
+
+Call `orient` at the start of any of these:
+
+- **New task in the repo** — even ones that feel small. The graph knows things the file tree doesn't.
+- **Unknown function or symbol** — instead of grepping blind, ask `orient` and let it return the function, its callers, and the spec section that owns it.
+- **Planning a cross-module change** — `orient` returns insertion points ranked by structural fit, so you start at the right boundary instead of the most-recently-viewed file.
+- **After an Epistemic Lease prefix appears** — when a tool response says you're stale, re-orient before continuing. Acting on stale context is the most common failure mode.
+
+If you are reading source files without having called `orient` first, you are probably wasting tokens.
+
+## How to use it
+
+### Preferred: via the OpenLore MCP server
+
+If `openlore` is registered as an MCP server in this project (look for `.mcp.json` → `mcpServers.openlore` — the project-scope file Claude Code reads; **not** `.claude/settings.json`, which it ignores for MCP), call the `orient` tool directly through the MCP interface. This is the lowest-latency path and gives the model access to the full openlore tool surface (~50 tools), not just `orient`.
+
+### Fallback: via the shell wrapper
+
+```sh
+bash scripts/orient.sh "<task description>"
+```
+
+(On Windows: `powershell -File scripts/orient.ps1 "<task description>"`)
+
+The wrapper tries the direct CLI subcommand first (`npx --yes openlore orient --json --task "<task>"`) and falls back to driving the `openlore mcp` server over stdio JSON-RPC via the sibling `orient-via-mcp.mjs` helper on older openlore versions that predate the CLI subcommand. Either path produces real orient JSON on stdout. Parse these arrays from the result:
+
+The result fields are **camelCase** (matching `orient --json`):
+
+- **`relevantFunctions`** — top scored functions for the task, each with `name`/`file`/`line`, role classification, and a short reason.
+- **`callPaths`** — caller/callee neighbourhood for the top functions. This is where "who breaks if I change this" lives.
+- **`specDomains`** — OpenSpec domains that own the relevant files, including the requirements they encode. Read these before reading code.
+- **`insertionPoints`** — ranked candidate locations to make the change, with structural justification.
+- **`relevantFiles`**, **`provenance`**, **`changeCoupling`**, **`suggestedTools`**, **`nextSteps`** — supporting context. **`searchMode`** is `semantic` when embeddings are built or `bm25_fallback` otherwise.
+
+Always start by reading **`specDomains`**, then **`callPaths`**, then jump into source only at the **`insertionPoints`** you actually plan to edit.
+
+### Lean mode for shallow lookups (cheaper)
+
+For a quick "who calls X" / "where is Y defined" lookup, pass **`lean: true`** (or `orient --lean`): it returns just the navigation core (`relevantFunctions` with `expand` handles, `callPaths`, `specDomains`) — ~40% smaller — and drops the provenance / change-coupling / insertion-points / specs / decisions enrichment, each still one `expand` handle or dedicated tool call away. Omit `lean` when you actually need that enrichment (planning an edit, checking specs/decisions). Caveat (measured, Spec 27): on a *trivial* lookup in a small/familiar repo, even a lean orient call can cost more than just grepping — `orient` earns its keep on unfamiliar or multi-hop work, not one-line facts you could find in 2 reads.
+
+> **Note:** the `openlore orient --json --task` CLI subcommand is available, so the wrappers use it directly. The MCP fallback in the wrappers only kicks in on older openlore versions that predate the subcommand.
+
+> **Want to measure it on your own repo?** Pass `--metrics` (off by default) to have `orient` report its wall time and output size to stderr. Nothing is measured or printed unless you ask for it.
+
+## What NOT to do
+
+- **Do not open source files before `orient` has returned.** This is the single most expensive mistake — you'll re-derive what the graph already knows.
+- **Do not call `orient` on every edit.** It's a session-start and re-orient-on-staleness tool, not a per-call helper. Respect the Epistemic Lease signal — if no prefix appears, your context is still fresh.
+- **Do not paraphrase the task** when passing it to `orient`. Use the user's words. The semantic search matches better when the query language matches the eventual prompt.
+- **Do not ignore `specDomains`.** Reading specs first is faster and more accurate than reading code first, in this repo.
+
+## Failure modes
+
+If `orient` returns an empty result or errors:
+
+1. **Empty `relevantFunctions` array** — the task description didn't match the graph. Try rephrasing using a known module name, function name, or domain word from the spec. Do not fall back silently — tell the user that `orient` didn't match and you're going to grep.
+2. **Wrapper output contains `"error": "No analysis found"`** — the codebase hasn't been analyzed yet. Run `npx openlore analyze` once to seed the graph, then retry. The wrapper itself is healthy in this case; the underlying tool is telling you what's missing.
+3. **Graph is stale (mtime older than recent edits)** — the JSON output will still come back, but the insertion points may be wrong. Re-run `npx openlore analyze` to rebuild.
+
+In all failure cases, the correct fallback is a *targeted* `grep`/file read scoped to a single module — not opening the whole repo. And **always tell the user the skill silently degraded** so they can rebuild the graph if needed.

package/skills/openlore-orient/examples/example-orient-output.json

@@ -0,0 +1,103 @@
+{
+  "_meta": {
+    "captured_from": "this repository (OpenLore)",
+    "task_used": "add a rate limiter to the API client",
+    "note": "Function names, file paths, and line numbers below are real and verifiable in src/. The shape exactly matches the response produced by handleOrient() in src/core/services/mcp-handlers/orient.ts. To regenerate from a live run once the codebase has a vector index built: `bash skills/openlore-orient/scripts/orient.sh \"add a rate limiter to the API client\" > skills/openlore-orient/examples/example-orient-output.json`."
+  },
+  "task": "add a rate limiter to the API client",
+  "searchMode": "bm25_fallback",
+  "note": "Embedding server unavailable — results use keyword matching. Run \"openlore analyze --embed\" for semantic search.",
+  "relevantFiles": [
+    "src/core/services/llm-service.ts",
+    "src/core/services/chat-agent.ts",
+    "src/core/services/chat-tools.ts",
+    "src/cli/commands/doctor.ts",
+    "src/cli/commands/generate.ts"
+  ],
+  "relevantFunctions": [
+    {
+      "id": "src/core/services/llm-service.ts::createLLMService",
+      "name": "createLLMService",
+      "filePath": "src/core/services/llm-service.ts",
+      "lineStart": 1852,
+      "score": 0.61,
+      "role": "factory",
+      "isHub": true,
+      "reason": "Top match: factory for the LLM client used by every CLI command. Hub: 14 inbound callers."
+    },
+    {
+      "id": "src/core/services/chat-agent.ts::fetchWithRetry",
+      "name": "fetchWithRetry",
+      "filePath": "src/core/services/chat-agent.ts",
+      "lineStart": 196,
+      "score": 0.42,
+      "role": "boundary",
+      "isHub": false,
+      "reason": "Outbound HTTP entry with retry; rate-limit would wrap each request here."
+    },
+    {
+      "id": "src/core/services/chat-tools.ts::toChatToolDefinitions",
+      "name": "toChatToolDefinitions",
+      "filePath": "src/core/services/chat-tools.ts",
+      "lineStart": 607,
+      "score": 0.31,
+      "role": "schema",
+      "isHub": false,
+      "reason": "Tool dispatcher schema; per-tool rate budgets would attach here if needed."
+    }
+  ],
+  "specDomains": [
+    {
+      "domain": "services",
+      "specFile": "openspec/specs/services/spec.md",
+      "purpose": "Manages reading, writing, and merging configuration files for openlore and OpenSpec."
+    },
+    {
+      "domain": "chat",
+      "specFile": "openspec/specs/chat/spec.md",
+      "purpose": "Handles interactions with language model providers (Gemini, Anthropic, OpenAI-compatible) to process chat messages and tool calls."
+    }
+  ],
+  "callPaths": [
+    {
+      "function": "createLLMService",
+      "filePath": "src/core/services/llm-service.ts",
+      "callers": [
+        { "name": "doctorCommand", "filePath": "src/cli/commands/doctor.ts" },
+        { "name": "verifyCommand", "filePath": "src/cli/commands/verify.ts" },
+        { "name": "driftCommand", "filePath": "src/cli/commands/drift.ts" },
+        { "name": "generateCommand", "filePath": "src/cli/commands/generate.ts" }
+      ],
+      "callees": [
+        { "name": "fetchWithRetry", "filePath": "src/core/services/chat-agent.ts" }
+      ]
+    }
+  ],
+  "insertionPoints": [
+    {
+      "name": "createLLMService",
+      "filePath": "src/core/services/llm-service.ts",
+      "lineStart": 1852,
+      "rationale": "Highest-leverage point: every caller passes through this factory. Wrap the returned LLMService with a rate-limited proxy here."
+    },
+    {
+      "name": "fetchWithRetry",
+      "filePath": "src/core/services/chat-agent.ts",
+      "lineStart": 196,
+      "rationale": "Alternative: instrument at the HTTP boundary if rate-limit needs awareness of provider-specific tokens-per-minute rather than per-call counts."
+    }
+  ],
+  "suggestedTools": [
+    "record_decision",
+    "analyze_impact",
+    "get_subgraph",
+    "get_spec",
+    "check_spec_drift"
+  ],
+  "nextSteps": [
+    "Before making an architectural choice, call record_decision(title, rationale, consequences, affectedFiles) to document it",
+    "Call get_subgraph(\"createLLMService\") to trace the call neighbourhood",
+    "Call get_spec(\"services\") to read the full spec before writing code",
+    "After implementing, run check_spec_drift to verify the code matches the spec"
+  ]
+}

package/skills/openlore-orient/examples/example-task-prompt.md

@@ -0,0 +1,26 @@
+# Example: from task to first edit
+
+**User:** "Add a rate limiter to the API client."
+
+The agent picks up this skill and, before opening any source files, calls:
+
+```sh
+bash scripts/orient.sh "add a rate limiter to the API client"
+```
+
+The output (see `example-orient-output.json` for the actual shape) returns:
+
+- `relevantFunctions[]` — pointing at `createLLMService` in `src/core/services/llm-service.ts` (the factory every command flows through) and `fetchWithRetry` in `src/core/services/chat-agent.ts` (the HTTP boundary).
+- `callPaths[]` — every CLI command that calls into the LLM service (`doctor`, `verify`, `drift`, `generate`), so the agent knows the blast radius of a behavior change.
+- `specDomains[]` — surfacing the `services` and `chat` spec domains and the requirements about how request handling is documented.
+- `insertionPoints[]` — ranking the factory as the top candidate (wrap once, every caller benefits), with `fetchWithRetry` as a fallback if the rate limit needs token-bucket-per-provider awareness.
+
+The agent then proceeds in this order, *without* opening anything else first:
+
+1. Reads the two `spec_sections` to understand the documented contract.
+2. Reads the callers list to confirm which call paths must keep working.
+3. Opens `llm-service.ts` at the line from the top insertion point — not the top of the file.
+
+Total tokens consumed before the first edit: ~3k for the `orient` output + targeted reads. Without the skill, the same task typically costs 30k–50k tokens of file-by-file exploration before the agent finds the right place to edit.
+
+The Epistemic Lease keeps watch from this point on: if a tool response later carries a "stale" prefix (because some unrelated edit moved the graph forward), the agent re-orients before continuing.

package/skills/openlore-orient/scripts/orient-via-mcp.mjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+/**
+ * Drive the existing `openlore mcp` server over stdio JSON-RPC to call the
+ * `orient` tool, then print its JSON output to stdout. Used by orient.sh /
+ * orient.ps1 so the skill works today, against the currently shipped CLI
+ * surface (no new subcommand required — see TODO(spec-02-followup) in
+ * SKILL.md for context).
+ *
+ * Pure Node built-ins only. Spawns `npx --yes openlore mcp`, performs the
+ * MCP initialize handshake, calls tools/call("orient", {task, directory}),
+ * prints the result, and exits.
+ */
+
+import { spawn, spawnSync } from 'node:child_process';
+import { createInterface } from 'node:readline';
+
+const task = process.argv[2];
+const directory = process.argv[3] ?? process.cwd();
+
+if (!task) {
+  process.stderr.write('usage: orient-via-mcp.mjs "<task description>" [directory]\n');
+  process.exit(2);
+}
+
+// This is a one-shot call (initialize → orient → exit), so the MCP server must
+// NOT start its file watcher: auto-watch recursively watches the whole repo —
+// including huge build dirs like Rust's target/ — and EMFILEs before we ever
+// get a response. Pass --no-watch-auto, but only if this openlore build
+// supports it: older versions error on unknown options. Detect via `mcp --help`.
+const mcpArgs = ['--yes', 'openlore', 'mcp'];
+try {
+  const help = spawnSync('npx', ['--yes', 'openlore', 'mcp', '--help'], {
+    encoding: 'utf8',
+    timeout: 60_000,
+  });
+  if ((help.stdout ?? '').includes('--no-watch-auto')) {
+    mcpArgs.push('--no-watch-auto');
+  }
+} catch {
+  // If detection fails, fall through without the flag (safe default).
+}
+
+const child = spawn('npx', mcpArgs, {
+  stdio: ['pipe', 'pipe', 'inherit'],
+});
+
+const rl = createInterface({ input: child.stdout });
+
+let nextId = 1;
+const pending = new Map(); // id → { resolve, reject }
+
+rl.on('line', (line) => {
+  if (!line.trim()) return;
+  let msg;
+  try {
+    msg = JSON.parse(line);
+  } catch {
+    // MCP server occasionally logs non-JSON to stdout during boot; ignore.
+    return;
+  }
+  if (msg.id !== undefined && pending.has(msg.id)) {
+    const { resolve, reject } = pending.get(msg.id);
+    pending.delete(msg.id);
+    if (msg.error) reject(new Error(msg.error.message ?? 'MCP error'));
+    else resolve(msg.result);
+  }
+});
+
+function send(method, params) {
+  const id = nextId++;
+  const payload = { jsonrpc: '2.0', id, method, params };
+  child.stdin.write(JSON.stringify(payload) + '\n');
+  return new Promise((resolve, reject) => {
+    pending.set(id, { resolve, reject });
+  });
+}
+
+function notify(method, params) {
+  child.stdin.write(JSON.stringify({ jsonrpc: '2.0', method, params }) + '\n');
+}
+
+const SHUTDOWN_TIMEOUT_MS = 30_000;
+const timeout = setTimeout(() => {
+  process.stderr.write('orient-via-mcp: timed out waiting for MCP server\n');
+  child.kill('SIGTERM');
+  process.exit(124);
+}, SHUTDOWN_TIMEOUT_MS);
+
+try {
+  await send('initialize', {
+    protocolVersion: '2024-11-05',
+    capabilities: {},
+    clientInfo: { name: 'openlore-orient-skill', version: '1.0.0' },
+  });
+  notify('notifications/initialized', {});
+
+  const result = await send('tools/call', {
+    name: 'orient',
+    arguments: { directory, task },
+  });
+
+  clearTimeout(timeout);
+
+  // Tool responses come back as { content: [{ type: 'text', text: '<json>' }] }
+  const textBlock = result?.content?.find?.((c) => c.type === 'text');
+  if (textBlock?.text) {
+    // Try to parse + reformat; if not JSON, emit raw.
+    try {
+      const parsed = JSON.parse(textBlock.text);
+      process.stdout.write(JSON.stringify(parsed, null, 2) + '\n');
+    } catch {
+      process.stdout.write(textBlock.text + '\n');
+    }
+  } else {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  }
+} catch (err) {
+  clearTimeout(timeout);
+  process.stderr.write(`orient-via-mcp: ${err.message ?? err}\n`);
+  process.exitCode = 1;
+} finally {
+  child.stdin.end();
+  child.kill();
+}

package/skills/openlore-orient/scripts/orient.ps1

@@ -0,0 +1,36 @@
+# Wrapper: ask `openlore orient` for the relevant functions/callers/specs/
+# insertion-points for a task, and print the JSON to stdout.
+#
+# Strategy (in order):
+#   1. `npx --yes openlore orient --json --task "<task>"` — preferred path,
+#      uses the orient CLI subcommand.
+#   2. Drive the existing `openlore mcp` server over stdio JSON-RPC via the
+#      sibling orient-via-mcp.mjs helper — fallback for older openlore versions
+#      that predate the CLI subcommand.
+
+param(
+  [Parameter(Mandatory=$false, Position=0)]
+  [string]$Task
+)
+
+$ErrorActionPreference = 'Stop'
+
+if ([string]::IsNullOrWhiteSpace($Task)) {
+  [Console]::Error.WriteLine('usage: orient.ps1 "<task description>"')
+  exit 2
+}
+
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+
+# Preferred path: direct CLI subcommand (if/when it ships). Detect by
+# scanning `openlore --help` — commander returns exit 0 even for unknown
+# subcommands, so we can't rely on `orient --help`'s exit code.
+$help = & npx --yes openlore --help 2>$null
+if ($help -match '(?m)^  orient( |$|\[)') {
+  & npx --yes openlore orient --json --task $Task
+  exit $LASTEXITCODE
+}
+
+# Fallback path: drive the MCP server over stdio JSON-RPC.
+& node (Join-Path $ScriptDir 'orient-via-mcp.mjs') $Task
+exit $LASTEXITCODE

package/skills/openlore-orient/scripts/orient.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env sh
+# Wrapper: ask `openlore orient` for the relevant functions/callers/specs/
+# insertion-points for a task, and print the JSON to stdout.
+#
+# Strategy (in order):
+#   1. `npx --yes openlore orient --json --task "<task>"` — preferred path,
+#      uses the orient CLI subcommand.
+#   2. Drive the existing `openlore mcp` server over stdio JSON-RPC via the
+#      sibling orient-via-mcp.mjs helper — fallback for older openlore versions
+#      that predate the CLI subcommand.
+set -eu
+TASK="${1:-}"
+if [ -z "$TASK" ]; then
+  echo "usage: orient.sh \"<task description>\"" >&2
+  exit 2
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# Preferred path: direct CLI subcommand (if/when it ships). Detect by
+# inspecting `openlore --help` output — commander returns exit 0 even for
+# unknown subcommands, so we can't rely on `orient --help`'s exit code.
+if npx --yes openlore --help 2>/dev/null | grep -Eq '^  orient( |$|\[)'; then
+  exec npx --yes openlore orient --json --task "$TASK"
+fi
+
+# Fallback path: drive the MCP server over stdio JSON-RPC.
+exec node "$SCRIPT_DIR/orient-via-mcp.mjs" "$TASK"