open-research-protocol 0.4.25 → 0.4.27

package/docs/AGENT_LOOP.md

@@ -12,6 +12,11 @@ read:
 
 - Read `llms.txt`.
 - Run `orp about --json`.
+- Run `orp hygiene --json` before long delegation, after material writeback,
+  before API/remote/paid compute, and whenever dirty state grows unexpectedly.
+  If it reports `dirty_unclassified`, stop long-running expansion and classify
+  the paths, refresh generated surfaces, canonicalize useful scratch, or write a
+  blocker before continuing.
 - If the task benefits from fresh concepting, tasteful interface work, or
   exploratory reframing, run:
   - `orp mode nudge sleek-minimal-progressive --json`
@@ -32,6 +37,10 @@ read:
 ## 2. Select Work
 
 - Identify the target profile and canonical artifact paths.
+- Treat worktree hygiene as a default-on self-healing loop. Dirty state is okay
+  when it is owned; invisible or unclassified dirt is not. The command is
+  non-destructive, so never reset, checkout, or delete files merely to make the
+  report look clean.
 - If the task depends on the current highest-leverage action slice, refresh ORP's agenda first:
   - `orp agenda refresh --json`
   - `orp agenda refresh-status --json`

package/docs/RESEARCH_COUNCIL.md

@@ -0,0 +1,171 @@
+# ORP Research Council
+
+ORP research council runs turn one question into a durable, tool-callable research artifact. The default profile is OpenAI-only right now, so one saved ORP key can power the full loop:
+
+```bash
+orp research ask "Where should this system live?" --json
+```
+
+By default this is a dry run. ORP writes the decomposition, profile, lane plan, lane JSON files, synthesized planning answer, and summary under:
+
+```text
+orp/research/<run_id>/
+```
+
+Live provider calls require an explicit flag:
+
+```bash
+orp research ask "Where should this system live?" --execute --json
+```
+
+## Lanes
+
+The built-in `openai-council` profile defines three OpenAI API lanes:
+
+- `openai_reasoning_high`: `gpt-5.4` with `reasoning.effort=high` for the deliberate thinking pass.
+- `openai_web_synthesis`: `gpt-5.4` with high reasoning plus Responses API web search for current public evidence and citations.
+- `openai_deep_research`: `o3-deep-research-2025-06-26` with background execution and web search preview for Pro/Deep Research style investigation.
+
+This follows OpenAI's current model guidance: `gpt-5.4` is the default for general-purpose, coding, reasoning, and agentic workflows; web search is enabled through the Responses API `tools` array when current information is needed; and Deep Research is available through the Responses endpoint with `o3-deep-research-2025-06-26`.
+
+## Staged Deep Research Template
+
+ORP also includes a built-in `deep-think-web-think-deep` profile for a strict sequence:
+
+```text
+Deep Research -> think -> think/web search -> think -> Deep Research
+```
+
+Inspect the template before using it:
+
+```bash
+orp research profile show deep-think-web-think-deep --json
+```
+
+Run a dry plan with form-like fields filled by a human or an agent:
+
+```bash
+orp research ask "Should this product use a staged research loop?" \
+  --profile deep-think-web-think-deep \
+  --field goal="Decide whether to adopt the staged loop" \
+  --field audience="Platform team" \
+  --field decision_to_support="Choose the default research workflow" \
+  --field project_context="ORP owns durable artifacts and secret resolution" \
+  --field constraints="Use one OpenAI API key first" \
+  --field deliverable_format="Decision memo with risks and next steps" \
+  --json
+```
+
+The prompt form is intentionally general. It gives an agent a reusable customization surface, similar to filling out a product intake form for a company:
+
+- `goal`
+- `audience`
+- `decision_to_support`
+- `project_context`
+- `constraints`
+- `known_inputs`
+- `source_preferences`
+- `recency_requirements`
+- `excluded_assumptions`
+- `success_criteria`
+- `deliverable_format`
+
+Dry runs persist the generated prompt for every lane under `orp/research/<run_id>/lanes/`. Later lanes include earlier lane outputs when those outputs exist, whether they came from live calls or `--lane-fixture` files. This makes the sequence inspectable before spending live provider calls. In live mode, later staged lanes skip their provider call if an earlier required lane did not complete with text.
+
+The staged profile keeps Deep Research foreground by default so the next lane can receive actual output. Deep Research can take a long time; pass a larger `--timeout-sec` for live runs or provide a custom profile file that sets `background=true` if you want asynchronous Deep Research behavior.
+
+## API Call Moments
+
+ORP records when API keys are intended to be used:
+
+- `plan`: local decomposition only. No API key is resolved.
+- `thinking_reasoning_high`: resolve `openai-primary` immediately before the `openai_reasoning_high` lane.
+- `web_synthesis`: resolve `openai-primary` immediately before the `openai_web_synthesis` lane.
+- `pro_deep_research`: resolve `openai-primary` immediately before the `openai_deep_research` lane.
+
+Dry runs write every lane with `api_call.called=false`. Live runs require `--execute`; even then, secret values are read only at the lane call moment and are not written to artifacts.
+
+Secret values are read from environment variables first. If an env var is missing and a matching ORP Keychain secret is available, ORP can use it at execution time. Secret values are not persisted in artifacts.
+
+The default live profile expects this ORP secret alias or env var:
+
+- `openai-primary` / `OPENAI_API_KEY`
+
+Store a local machine copy without the hosted secret API like this:
+
+```bash
+printf '%s' '<openai-key>' | orp secrets keychain-add \
+  --alias openai-primary \
+  --label "OpenAI Primary" \
+  --provider openai \
+  --value-stdin \
+  --json
+```
+
+## Fixtures
+
+Provider outputs can be attached without spending live calls:
+
+```bash
+orp research ask "Where should this live?" \
+  --lane-fixture openai_reasoning_high=reports/reasoning.json \
+  --lane-fixture openai_web_synthesis=reports/web.txt \
+  --json
+```
+
+Fixtures are useful when an OpenAI run happened outside ORP, when you are comparing model settings manually, or when tests need deterministic lane outputs.
+
+## OpenAI API Notes
+
+ORP uses the Responses API for these lanes. Useful knobs in profile JSON:
+
+- `model`: for example `gpt-5.4` or `o3-deep-research-2025-06-26`.
+- `call_moment`: the named research-loop moment when this lane may resolve a key.
+- `reasoning_effort`: `none`, `low`, `medium`, `high`, or `xhigh` for supported models.
+- `reasoning_summary`: `auto` or `detailed` for Deep Research reasoning summaries.
+- `text_verbosity`: `low`, `medium`, or `high`.
+- `web_search`: `true` to add the Responses API web-search tool.
+- `search_context_size`: `low`, `medium`, or `high` for web search.
+- `background`: `true` for long-running Deep Research calls.
+- `max_output_tokens`: hard cap for a lane response.
+
+The default profile deliberately avoids Anthropic, xAI, and local-model lanes so a single OpenAI key is enough.
+
+## Project Context Timing
+
+`orp init` creates `orp/project.json`, a process-only project context lens for the current directory. It records the authority surfaces ORP can see, the directory signals it should route on, and the default research timing policy:
+
+- decompose locally first
+- use high-reasoning API calls when a decision gate or ambiguous next action needs outside reasoning
+- use web synthesis when current public facts, docs, papers, project status, or citations matter
+- use Deep Research only after reasoning/web lanes expose a research-heavy gap, disagreement, source-quality issue, or literature-scale synthesis need
+
+Run `orp project refresh --json` after adding or changing roadmap, spec, agent-guidance, docs, manifest, or command-surface files. Refreshing project context does not call a provider; live provider calls remain explicit through `orp research ask --execute`.
+
+## Follow-Up Commands
+
+```bash
+orp project show --json
+orp project refresh --json
+orp research status latest --json
+orp research show latest --json
+```
+
+## Codex MCP Tool
+
+ORP also ships a tiny stdio MCP wrapper for the research commands:
+
+```toml
+[mcp_servers.orp-research]
+command = "/path/to/orp/scripts/orp-mcp"
+```
+
+It exposes:
+
+- `orp_research_ask`
+- `orp_research_profile_list`
+- `orp_research_profile_show`
+- `orp_research_status`
+- `orp_research_show`
+
+Research council files are ORP process artifacts. They record decomposition, provider lane outputs, and synthesis. Canonical evidence still belongs in source repositories, linked reports, cited URLs, datasets, papers, or other primary artifacts.

package/docs/START_HERE.md

@@ -43,6 +43,7 @@ orp home
 orp agents root set /absolute/path/to/projects
 orp init
 orp agents audit
+orp project show --json
 orp workspace create main-cody-1
 orp workspace tabs main
 orp agenda refresh --json
@@ -64,6 +65,7 @@ That gets you:
 - an optional umbrella projects root for parent/child agent guidance
 - repo governance initialized
 - repo-level AGENTS.md and CLAUDE.md scaffolded or refreshed
+- `orp/project.json` created as the local project context lens
 - a local workspace ledger
 - the main recovery surface
 - a local operating agenda
@@ -73,6 +75,8 @@ That gets you:
 - a clean repo-governance read
 - a first intentional checkpoint
 
+`orp/project.json` records the current directory's authority surfaces, directory signals, and default research call timing. It is refreshed by `orp init` and can evolve with the directory through `orp project refresh --json`, especially after adding or changing roadmap, spec, agent-guidance, docs, manifest, or command-surface files.
+
 ## Beginner Flow
 
 This is the zero-assumption path for a new user.
@@ -735,6 +739,7 @@ The guiding rule is simple:
 
 - recover the saved workspace
 - inspect repo safety
+- classify dirty state before expansion
 - resolve the right secret
 - inspect the current frontier
 - do the next honest move
@@ -752,16 +757,20 @@ If you only want the irreducible ORP loop, it is this:
    ```bash
    orp status --json
    ```
-3. resolve the right secret
+3. classify dirty worktree state before expansion
+   ```bash
+   orp hygiene --json
+   ```
+4. resolve the right secret
    ```bash
    orp secrets ensure --alias <alias> --provider <provider> --current-project --json
    ```
-4. inspect the current frontier
+5. inspect the current frontier
    ```bash
    orp frontier state --json
    ```
-5. do the next honest move
-6. checkpoint it
+6. do the next honest move
+7. checkpoint it
    ```bash
    orp checkpoint create -m "describe completed unit" --json
    ```
@@ -770,6 +779,7 @@ That is the shortest version of the protocol:
 
 - recover continuity
 - inspect safety
+- classify dirty state
 - resolve access
 - inspect context
 - do the work
@@ -782,6 +792,7 @@ If you want the agent to stay aligned with ORP, the default check sequence shoul
 ```bash
 orp workspace tabs main
 orp status --json
+orp hygiene --json
 orp secrets ensure --alias <alias> --provider <provider> --current-project --json
 orp frontier state --json
 ```
@@ -796,17 +807,18 @@ That is the practical ORP loop:
 
 1. recover the workspace ledger
 2. inspect repo safety
-3. resolve the right key
-4. inspect the current frontier
-5. do the work
-6. checkpoint it honestly
+3. classify dirty state and stop if anything is unowned
+4. resolve the right key
+5. inspect the current frontier
+6. do the work
+7. checkpoint it honestly
 
 The key point is that ORP should become the lens:
 
 - not "something we remember to use sometimes"
 - but the operating frame the agent checks before and after meaningful work
 
-## If You Only Remember 8 Commands
+## If You Only Remember 9 Commands
 
 ```bash
 orp home
@@ -814,6 +826,7 @@ orp init
 orp workspace create main-cody-1
 orp workspace tabs main
 orp workspace add-tab main --path /absolute/path/to/project --resume-command "codex resume <id>"
+orp hygiene --json
 orp secrets ensure --alias openai-primary --provider openai --current-project --json
 orp status --json
 orp checkpoint create -m "capture loop state" --json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-research-protocol",
-  "version": "0.4.25",
+  "version": "0.4.27",
   "description": "ORP CLI (Open Research Protocol): workspace ledgers, secrets, scheduling, governed execution, and agent-friendly research workflows.",
   "license": "MIT",
   "author": "Fractal Research Group <cody@frg.earth>",

package/packages/orp-workspace-launcher/src/orp-command.js

@@ -1,9 +1,55 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
 import { runWorkspaceAddTab, runWorkspaceCreate, runWorkspaceRemoveTab } from "./ledger.js";
 import { runWorkspaceList } from "./list.js";
 import { runWorkspaceSlot } from "./slot.js";
 import { runWorkspaceSync } from "./sync.js";
 import { runWorkspaceTabs } from "./tabs.js";
 
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pythonCliPath = path.resolve(__dirname, "..", "..", "..", "cli", "orp.py");
+
+function pythonCandidates() {
+  const candidates = [];
+  if (process.env.ORP_PYTHON && process.env.ORP_PYTHON.trim() !== "") {
+    candidates.push(process.env.ORP_PYTHON.trim());
+  }
+  if (process.platform === "win32") {
+    candidates.push("py");
+  }
+  candidates.push("python3", "python");
+  return candidates;
+}
+
+function runWorkspaceHygiene(args = []) {
+  let lastErr = null;
+  for (const py of pythonCandidates()) {
+    const pyArgs = py === "py" ? ["-3", pythonCliPath, "hygiene", ...args] : [pythonCliPath, "hygiene", ...args];
+    const result = spawnSync(py, pyArgs, { encoding: "utf8" });
+    if (!result.error) {
+      if (result.stdout) {
+        process.stdout.write(result.stdout);
+      }
+      if (result.stderr) {
+        process.stderr.write(result.stderr);
+      }
+      return result.status == null ? 1 : result.status;
+    }
+    if (result.error && result.error.code === "ENOENT") {
+      continue;
+    }
+    lastErr = result.error;
+  }
+  process.stderr.write("ORP workspace hygiene requires Python 3 on PATH.\n");
+  process.stderr.write("Tried: " + pythonCandidates().join(", ") + "\n");
+  if (lastErr) {
+    process.stderr.write(String(lastErr) + "\n");
+  }
+  return 1;
+}
+
 function printWorkspaceHelp() {
   console.log(`ORP workspace
 
@@ -18,6 +64,7 @@ Usage:
   orp workspace remove-tab <name-or-id> (--index <n> | --path <absolute-path> | --title <title> | --resume-session-id <id> | --resume-command <text>) [--all] [--json]
   orp workspace slot <list|set|clear> ...
   orp workspace sync <name-or-id> [--workspace-file <path> | --notes-file <path>] [--dry-run] [--json]
+  orp workspace hygiene [--json]
   orp workspace ledger <name-or-id> [--json]
   orp workspace ledger add <name-or-id> (--path <absolute-path> | --here) [--title <title>] [--remote-url <git-url>] [--remote-branch <branch>] [--bootstrap-command <text>] [--resume-command <text> | --resume-tool <codex|claude> --resume-session-id <id> | --current-codex] [--append] [--json]
   orp workspace ledger remove <name-or-id> (--index <n> | --path <absolute-path> | --title <title> | --resume-session-id <id> | --resume-command <text>) [--all] [--json]
@@ -31,6 +78,7 @@ Commands:
   remove-tab Remove one or more saved tabs from the workspace ledger directly
   slot    Assign and inspect named workspace slots like main and offhand
   sync    Post a CLI-authored workspace manifest back to the hosted ORP idea
+  hygiene Classify dirty worktree paths before long agent expansion
   ledger  Compatibility alias for the same tabs/add/remove ledger flow
 
 Notes:
@@ -41,6 +89,7 @@ Notes:
   - Use \`orp workspace add-tab ... --remote-url ... --bootstrap-command ...\` when you want ORP to remember how to recreate the repo on another machine.
   - Use \`orp workspace add-tab ...\` and \`orp workspace remove-tab ...\` when you want to edit the saved workspace ledger explicitly from Terminal.app or any other shell.
   - If you prefer the older ledger-prefixed wording, \`orp workspace ledger\`, \`orp workspace ledger add\`, and \`orp workspace ledger remove\` stay available as aliases.
+  - \`orp workspace hygiene --json\` is a wrapper alias for \`orp hygiene --json\`; it reports dirty path categories without resetting, checking out, or deleting files.
   - \`main\` and \`offhand\` are reserved slot selectors; use \`orp workspace slot set ...\` to assign them.
   - Syncing or editing a hosted workspace writes a managed local cache on this Mac.
   - \`<name-or-id>\` can be a saved workspace title, workspace id, idea id, or local tracked workspace title/id.
@@ -51,6 +100,7 @@ Examples:
   orp workspace create mac-main --machine-label "Mac Studio" --path /absolute/path/to/orp --remote-url git@github.com:SproutSeeds/orp.git --bootstrap-command "npm install"
   orp workspace list
   orp workspace tabs main-cody-1
+  orp workspace hygiene --json
   orp workspace add-tab main --here --current-codex
   orp workspace add-tab main --path /absolute/path/to/new-project --resume-command "codex resume 019d..."
   orp workspace add-tab main --path /absolute/path/to/new-project --remote-url git@github.com:org/new-project.git --bootstrap-command "npm install"
@@ -126,5 +176,9 @@ export async function runOrpWorkspaceCommand(argv = []) {
     return runWorkspaceSync(rest);
   }
 
+  if (subcommand === "hygiene") {
+    return runWorkspaceHygiene(rest);
+  }
+
   throw new Error(`unknown workspace subcommand: ${subcommand}`);
 }

package/packages/orp-workspace-launcher/test/orp-command.test.js

@@ -38,6 +38,7 @@ test("runOrpWorkspaceCommand shows the ledger-first help surface", async () => {
   assert.match(stdout, /orp workspace ledger add <name-or-id>/);
   assert.match(stdout, /orp workspace ledger remove <name-or-id>/);
   assert.match(stdout, /orp workspace tabs <name-or-id>/);
+  assert.match(stdout, /orp workspace hygiene \[--json\]/);
   assert.match(stdout, /Compatibility alias for the same tabs\/add\/remove ledger flow/);
 });
 

package/scripts/orp-mcp

@@ -0,0 +1,256 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import json
+from pathlib import Path
+import subprocess
+import sys
+from typing import Any
+
+
+ROOT = Path(__file__).resolve().parents[1]
+CLI = ROOT / "cli" / "orp.py"
+
+
+TOOLS: list[dict[str, Any]] = [
+    {
+        "name": "orp_research_ask",
+        "description": "Create an ORP OpenAI research-loop run with high-reasoning, web-synthesis, and deep-research call moments. Dry-run by default; set execute=true for live provider lanes.",
+        "inputSchema": {
+            "type": "object",
+            "required": ["question"],
+            "properties": {
+                "question": {"type": "string", "minLength": 1},
+                "repo_root": {"type": "string", "description": "Repository root. Defaults to current directory."},
+                "run_id": {"type": "string"},
+                "profile": {"type": "string", "default": "openai-council"},
+                "profile_file": {"type": "string"},
+                "fields": {
+                    "type": "object",
+                    "description": "Prompt-template fields passed as key/value pairs.",
+                    "additionalProperties": {"type": "string"},
+                },
+                "execute": {"type": "boolean", "default": False},
+                "lane_fixtures": {
+                    "type": "object",
+                    "description": "Mapping of lane_id to fixture path.",
+                    "additionalProperties": {"type": "string"},
+                },
+                "chimera_bin": {"type": "string", "default": "chimera"},
+                "timeout_sec": {"type": "integer", "minimum": 1, "description": "Override the profile per-lane timeout policy."},
+            },
+        },
+    },
+    {
+        "name": "orp_research_profile_list",
+        "description": "List built-in ORP research profiles and prompt-template surfaces.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "repo_root": {"type": "string", "description": "Repository root. Defaults to current directory."},
+            },
+        },
+    },
+    {
+        "name": "orp_research_profile_show",
+        "description": "Show a built-in ORP research profile, including its lane sequence and prompt form.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "repo_root": {"type": "string", "description": "Repository root. Defaults to current directory."},
+                "profile_id": {"type": "string", "default": "openai-council"},
+            },
+        },
+    },
+    {
+        "name": "orp_research_status",
+        "description": "Show status and lane summary for an ORP research council run.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "repo_root": {"type": "string", "description": "Repository root. Defaults to current directory."},
+                "run_id": {"type": "string", "default": "latest"},
+            },
+        },
+    },
+    {
+        "name": "orp_research_show",
+        "description": "Show an ORP research council answer payload.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "repo_root": {"type": "string", "description": "Repository root. Defaults to current directory."},
+                "run_id": {"type": "string", "default": "latest"},
+            },
+        },
+    },
+]
+
+
+def _json_response(request_id: Any, result: Any | None = None, error: Any | None = None) -> dict[str, Any]:
+    response: dict[str, Any] = {"jsonrpc": "2.0", "id": request_id}
+    if error is not None:
+        response["error"] = error
+    else:
+        response["result"] = result if result is not None else {}
+    return response
+
+
+def _write(payload: dict[str, Any]) -> None:
+    sys.stdout.write(json.dumps(payload, separators=(",", ":")) + "\n")
+    sys.stdout.flush()
+
+
+def _text_result(text: str, *, is_error: bool = False) -> dict[str, Any]:
+    return {
+        "content": [{"type": "text", "text": text}],
+        "isError": is_error,
+    }
+
+
+def _repo_root(args: dict[str, Any]) -> str:
+    raw = str(args.get("repo_root", "") or "").strip()
+    return raw or "."
+
+
+def _run_orp(args: list[str]) -> tuple[int, str, str]:
+    proc = subprocess.run(
+        [sys.executable, str(CLI), *args],
+        capture_output=True,
+        text=True,
+        cwd=str(ROOT),
+    )
+    return proc.returncode, proc.stdout, proc.stderr
+
+
+def _call_research_ask(args: dict[str, Any]) -> dict[str, Any]:
+    question = str(args.get("question", "") or "").strip()
+    if not question:
+        return _text_result("question is required", is_error=True)
+    cmd = ["--repo-root", _repo_root(args), "research", "ask", question]
+    profile = str(args.get("profile", "") or "").strip()
+    if profile:
+        cmd.extend(["--profile", profile])
+    profile_file = str(args.get("profile_file", "") or "").strip()
+    if profile_file:
+        cmd.extend(["--profile-file", profile_file])
+    run_id = str(args.get("run_id", "") or "").strip()
+    if run_id:
+        cmd.extend(["--run-id", run_id])
+    fields = args.get("fields")
+    if isinstance(fields, dict):
+        for key, value in fields.items():
+            cmd.extend(["--field", f"{key}={value}"])
+    if bool(args.get("execute", False)):
+        cmd.append("--execute")
+    lane_fixtures = args.get("lane_fixtures")
+    if isinstance(lane_fixtures, dict):
+        for lane_id, path in lane_fixtures.items():
+            cmd.extend(["--lane-fixture", f"{lane_id}={path}"])
+    chimera_bin = str(args.get("chimera_bin", "") or "").strip()
+    if chimera_bin:
+        cmd.extend(["--chimera-bin", chimera_bin])
+    timeout_sec = args.get("timeout_sec")
+    if timeout_sec is not None:
+        cmd.extend(["--timeout-sec", str(timeout_sec)])
+    cmd.append("--json")
+    code, stdout, stderr = _run_orp(cmd)
+    if code != 0:
+        return _text_result((stderr or stdout or f"orp exited {code}").strip(), is_error=True)
+    return _text_result(stdout.strip())
+
+
+def _call_research_profile_list(args: dict[str, Any]) -> dict[str, Any]:
+    cmd = ["--repo-root", _repo_root(args), "research", "profile", "list", "--json"]
+    code, stdout, stderr = _run_orp(cmd)
+    if code != 0:
+        return _text_result((stderr or stdout or f"orp exited {code}").strip(), is_error=True)
+    return _text_result(stdout.strip())
+
+
+def _call_research_profile_show(args: dict[str, Any]) -> dict[str, Any]:
+    profile_id = str(args.get("profile_id", "") or "openai-council").strip() or "openai-council"
+    cmd = ["--repo-root", _repo_root(args), "research", "profile", "show", profile_id, "--json"]
+    code, stdout, stderr = _run_orp(cmd)
+    if code != 0:
+        return _text_result((stderr or stdout or f"orp exited {code}").strip(), is_error=True)
+    return _text_result(stdout.strip())
+
+
+def _call_research_status(args: dict[str, Any]) -> dict[str, Any]:
+    run_id = str(args.get("run_id", "") or "latest").strip() or "latest"
+    cmd = ["--repo-root", _repo_root(args), "research", "status", run_id, "--json"]
+    code, stdout, stderr = _run_orp(cmd)
+    if code != 0:
+        return _text_result((stderr or stdout or f"orp exited {code}").strip(), is_error=True)
+    return _text_result(stdout.strip())
+
+
+def _call_research_show(args: dict[str, Any]) -> dict[str, Any]:
+    run_id = str(args.get("run_id", "") or "latest").strip() or "latest"
+    cmd = ["--repo-root", _repo_root(args), "research", "show", run_id, "--json"]
+    code, stdout, stderr = _run_orp(cmd)
+    if code != 0:
+        return _text_result((stderr or stdout or f"orp exited {code}").strip(), is_error=True)
+    return _text_result(stdout.strip())
+
+
+def _handle(request: dict[str, Any]) -> dict[str, Any] | None:
+    request_id = request.get("id")
+    method = str(request.get("method", "") or "")
+    if method.startswith("notifications/"):
+        return None
+    if method == "initialize":
+        return _json_response(
+            request_id,
+            {
+                "protocolVersion": str(request.get("params", {}).get("protocolVersion", "2024-11-05")),
+                "capabilities": {"tools": {}},
+                "serverInfo": {"name": "orp-research", "version": "0.1.0"},
+            },
+        )
+    if method == "tools/list":
+        return _json_response(request_id, {"tools": TOOLS})
+    if method == "tools/call":
+        params = request.get("params")
+        if not isinstance(params, dict):
+            return _json_response(request_id, error={"code": -32602, "message": "params must be an object"})
+        name = str(params.get("name", "") or "")
+        arguments = params.get("arguments")
+        if not isinstance(arguments, dict):
+            arguments = {}
+        if name == "orp_research_ask":
+            return _json_response(request_id, _call_research_ask(arguments))
+        if name == "orp_research_profile_list":
+            return _json_response(request_id, _call_research_profile_list(arguments))
+        if name == "orp_research_profile_show":
+            return _json_response(request_id, _call_research_profile_show(arguments))
+        if name == "orp_research_status":
+            return _json_response(request_id, _call_research_status(arguments))
+        if name == "orp_research_show":
+            return _json_response(request_id, _call_research_show(arguments))
+        return _json_response(request_id, error={"code": -32601, "message": f"unknown tool: {name}"})
+    return _json_response(request_id, error={"code": -32601, "message": f"unknown method: {method}"})
+
+
+def main() -> int:
+    for line in sys.stdin:
+        text = line.strip()
+        if not text:
+            continue
+        try:
+            request = json.loads(text)
+        except Exception as exc:
+            _write(_json_response(None, error={"code": -32700, "message": str(exc)}))
+            continue
+        if not isinstance(request, dict):
+            _write(_json_response(None, error={"code": -32600, "message": "request must be an object"}))
+            continue
+        response = _handle(request)
+        if response is not None:
+            _write(response)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())