open-research-protocol 0.4.27 → 0.4.29

package/CHANGELOG.md

@@ -6,6 +6,54 @@ There was no prior in-repo changelog file, so the first formal entry starts
 with the currently shipped `v0.4.4` release and summarizes the full release
 delta reflected in this repo.
 
+## v0.4.29 - 2026-04-25
+
+This release adds ORP-managed Codex session tracking so starting a Codex thread
+from a repo can automatically refresh the saved workspace session for that
+directory.
+
+### Added
+
+- Added `orp codex` as the default tracked Codex launcher: it resolves the repo
+  root, starts Codex there, watches local session metadata, and saves the new
+  Codex resume id into workspace `main`.
+- Added `orp codex status` and `orp codex reconcile` for checking stale saved
+  Codex sessions and refreshing tracked workspace tabs from recent local Codex
+  session metadata.
+- Added safeguards that ignore delegated/subagent sessions by default and refuse
+  broad roots or artifact-output repos unless explicitly overridden.
+
+### Changed
+
+- Documented the ORP/Codex compatibility workflow and exposed the new wrapper
+  command in the npm CLI help surface.
+
+## v0.4.28 - 2026-04-22
+
+This release tightens the ORP project-startup and research-spend loops, then
+refreshes the public README presentation with a mascot-led terminal animation.
+
+### Added
+
+- Added `orp init --project-startup` support for a fuller new-project ritual:
+  private GitHub remote setup, `main` workspace ledger tracking, Codex session
+  capture, bootstrap command storage, and optional Clawdad delegation setup.
+- Added local research spend guardrails for provider-backed research lanes:
+  per-secret daily spend cap metadata, dashboard limit notes, local spend
+  ledger records, and OpenAI preflight blocking when a lane would exceed the
+  configured cap.
+- Added a mascot-led ORP terminal animation that explains workspace ledgers,
+  secrets, research lanes, governance checkpoints, breakdown mode, and
+  agent-readable handoffs in simple language.
+
+### Changed
+
+- Promoted the refreshed terminal animation to the top of the README with a
+  short greeting and updated the walkthrough copy to match the current ORP
+  command surface.
+- Simplified generated animation scenes from a crowded command survey into a
+  cleaner seven-scene story with an expressive mascot and real CLI commands.
+
 ## v0.4.27 - 2026-04-18
 
 This release adds a staged OpenAI research profile and default-on worktree

package/README.md

@@ -9,6 +9,12 @@ Maintained by SproutSeeds. Research stewardship: Fractal Research Group ([frg.ea
 [![license](https://img.shields.io/npm/l/open-research-protocol?color=111111&label=license)](./LICENSE)
 [![node](https://img.shields.io/node/v/open-research-protocol?color=111111&label=node)](https://www.npmjs.com/package/open-research-protocol)
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/SproutSeeds/orp/main/assets/terminal-demo.gif" alt="open-research-protocol mascot terminal demo">
+</p>
+
+<p align="center"><strong>Hello, researcher.</strong> Keep the loop open, recoverable, and kind.</p>
+
 > Agent-first CLI for workspace ledgers, operating agendas, local governance, secrets, scheduling, packets, reports, and research workflows.
 
 **Links:** [GitHub](https://github.com/SproutSeeds/orp) · [npm](https://www.npmjs.com/package/open-research-protocol) · [frg.earth](https://frg.earth)
@@ -38,24 +44,21 @@ checkpoint layer. See
 
 ## Watch It Run
 
-A short ORP command-family walkthrough:
-
-![open-research-protocol terminal demo](https://raw.githubusercontent.com/SproutSeeds/orp/main/assets/terminal-demo.gif)
+The current animation introduces a small protocol mascot for the ORP message:
+context before claims, saved threads before crashes, hidden keys before exposed
+secrets, dry-run research before spend, checkpoints before handoffs, and
+breakdowns before overwhelm. The terminal still uses real ORP command surfaces
+rather than a fabricated UI.
 
-The current animation intentionally uses the same human-facing command surfaces ORP prints in the terminal. It is not a fabricated UI layer. It currently shows ORP from multiple angles:
+It currently shows ORP from seven angles:
 
 - `home` for discovery and next actions
-- `hosted` for ideas, workspaces, runners, and the control plane
-- `secrets` for create-or-reuse plus local Keychain sync
-- `workspace` for the hosted + local saved workspace ledger and recovery commands
-- `agenda` for Codex-ranked actions and suggestions across current work
-- `connections` for service accounts, data sources, deploy targets, and research destinations
-- `opportunities` for contests, programs, grants, and other tracked openings
-- `schedule` for recurring Codex jobs
+- `workspace` for grouped project/session ledgers and recovery commands
+- `secrets` for local reusable credentials and spend policy metadata
+- `research` for dry-run-first research lanes with an OpenAI-ready provider path
 - `governance` for local checkpoints and repo safety
-- `planning` for frontier, compute, packet, and report surfaces
-- `synthesis` for discover, exchange, collaborate, and YouTube ingestion
-- `mode` for optional perspective-shift nudges
+- `breakdown` for broad-to-atomic comprehension loops
+- `publish` for agent-readable reports, handoffs, and open research messaging
 
 Maintainer asset generation:
 
@@ -451,10 +454,14 @@ Local desk and automation:
 orp workspace create mac-main --machine-label "Mac Studio"
 orp workspace list
 orp workspace tabs main
+orp init --project-startup --github-repo owner/repo --current-codex
 orp workspace add-tab main --path /absolute/path/to/project --remote-url git@github.com:org/project.git --bootstrap-command "npm install" --resume-command "codex resume <id>"
 orp workspace add-tab main --path /absolute/path/to/project --title "second active thread" --resume-tool claude --resume-session-id <id> --append
 orp workspace remove-tab main --path /absolute/path/to/project
 orp workspace sync main
+orp codex status
+orp codex reconcile --dry-run
+orp codex --search
 orp secrets list --json
 orp secrets ensure --alias openai-primary --provider openai --current-project --json
 orp secrets keychain-add --alias openai-primary --provider openai --env-var-name OPENAI_API_KEY --value-stdin --json
@@ -462,6 +469,19 @@ orp secrets sync-keychain openai-primary --json
 orp schedule add codex --name morning-summary --prompt "Summarize this repo" --json
 ```
 
+`orp codex` is a local compatibility layer for keeping workspace `main`
+aligned with Codex sessions. `status` compares the current repo against the
+latest local Codex session metadata, `reconcile` refreshes stale saved sessions,
+and bare `orp codex` launches Codex from the repo root while watching for the new
+session id. Delegated/subagent sessions are ignored by default, and
+artifact-output repos should be left untracked when a separate lab repo is the
+source of truth. Use `--` before Codex args that conflict with ORP wrapper
+options. The manual fallback from inside Codex is still:
+
+```bash
+orp workspace add-tab main --here --current-codex
+```
+
 For secrets, the simplest plain-English rule is:
 
 - `orp secrets ensure ...` = use the saved key if it already exists, or ask for it and create it if it does not
@@ -570,6 +590,7 @@ Stable artifact paths:
 1. Copy this folder into a new project directory.
 2. If you keep projects under one umbrella directory, run `orp agents root set /absolute/path/to/projects` once from anywhere.
 3. Run `orp init` immediately so the repo starts ORP-governed, scaffolds or updates `AGENTS.md` and `CLAUDE.md`, and creates `orp/project.json`.
+   For the fuller new-project ritual, run `orp init --project-startup --github-repo owner/repo --current-codex`; ORP will create a private GitHub remote through `gh`, save the path/session in workspace `main`, and register Clawdad delegation when `clawdad` is installed. Use `--startup-dry-run --json` first when you want to inspect the planned external commands.
 4. Edit `PROTOCOL.md` to define your canonical paths and claim labels.
 5. Run `orp project refresh --json` whenever the directory gains new roadmap, spec, docs, manifest, or command-surface files.
 6. Run `orp agents audit` to confirm the repo-level agent files are aligned and still preserving human notes.
@@ -769,3 +790,7 @@ python3 scripts/orp-pack-render.py --pack packs/erdos-open-problems --template s
 python3 scripts/orp-pack-render.py --pack packs/erdos-open-problems --template erdos_problems_catalog_sync \
   --var TARGET_REPO_ROOT=/path/to/repo --var ORP_REPO_ROOT=/path/to/orp --out /path/to/repo/orp.erdos-catalog-sync.yml
 ```
+
+## Support
+
+Everything here is released for public use. If ORP saved you time or you want to keep the work moving, you can [support public FRG releases](https://frg.earth/support?utm_source=readme&utm_medium=repo&utm_campaign=public_work_support&package=open-research-protocol).

package/bin/orp.js

@@ -9,6 +9,9 @@ const computeCliUrl = pathToFileURL(path.resolve(__dirname, "orp-compute.mjs")).
 const workspaceCliUrl = pathToFileURL(
   path.resolve(__dirname, "..", "packages", "orp-workspace-launcher", "src", "orp-command.js"),
 ).href;
+const codexCliUrl = pathToFileURL(
+  path.resolve(__dirname, "..", "packages", "orp-workspace-launcher", "src", "codex.js"),
+).href;
 const argv = process.argv.slice(2);
 
 const candidates = [];
@@ -36,6 +39,12 @@ async function runWorkspace(args) {
   process.exit(code == null ? 0 : code);
 }
 
+async function runCodex(args) {
+  const mod = await import(codexCliUrl);
+  const code = await mod.runOrpCodexCommand(args);
+  process.exit(code == null ? 0 : code);
+}
+
 function runPythonCli(args, { captureOutput }) {
   let lastErr = null;
 
@@ -58,7 +67,7 @@ function runPythonCli(args, { captureOutput }) {
           process.stderr.write(result.stderr);
         }
         if (result.status === 0) {
-          process.stdout.write("\nAdditional wrapper surface:\n  orp compute -h\n  orp workspace tabs -h\n  orp workspace hygiene --json\n");
+          process.stdout.write("\nAdditional wrapper surface:\n  orp compute -h\n  orp workspace tabs -h\n  orp workspace hygiene --json\n  orp codex status -h\n");
         }
       }
       process.exit(result.status == null ? 1 : result.status);
@@ -91,6 +100,10 @@ async function main() {
     await runWorkspace(argv.slice(1));
     return;
   }
+  if (argv[0] === "codex") {
+    await runCodex(argv.slice(1));
+    return;
+  }
 
   runPythonCli(argv, { captureOutput: isTopLevelHelp(argv) });
 }