@smartergpt/lexrunner

LexRunner (lexrunner)

LexRunner turns a changing set of pull requests into a reviewable integration program: discover the work, freeze a dependency plan, run bounded gates, preserve evidence, and merge only with explicit authority.

It is useful when a repository has concurrent PRs, dependencies between changes, repeated local and CI checks, or agent-assisted implementation that needs a durable handoff. It is usually not a fit for a repository with one occasional PR and no integration-order problem.

Ask your agent: “Read docs/agent-evaluation.md, evaluate this repository without installing or changing anything, and return adopt, pilot, defer, or not a fit with the smallest reversible trial.”

That evaluation is deliberately read-only. Installing the package, writing a plan, creating a branch, pushing, opening a PR, or merging requires separate approval.

Start here

For your first trial, install LexRunner only in a GitHub repository with open PRs. Node.js 24+ and Git are required. npm installs LexRunner's dependencies; you do not need to install Lex, AXF, LexSona, a policy-host service, or an MCP server separately for this CLI workflow. These examples use the published 2.2.0 release.

npm install --save-dev @smartergpt/lexrunner@2.2.0
npx lexrunner --version
npx lexrunner weave discover --json

Installation changes your package manifest, lockfile and dependencies. Discovery reads GitHub; private repositories need an authorized GITHUB_TOKEN supplied to the process. See the merge-weave quickstart for setup, authentication and the complete first-use journey:

Discover → freeze a plan → inspect dependencies → preview gates.

The first useful result is an inspected plan and gate preview. A dry run neither executes gates nor proves merge eligibility. The quickstart separates local writes, command execution, independent review and the explicit merge boundary. Single-repository GitHub plans bind explicit refs and commits for local integration. The walkthrough explains clean-checkout preparation, exact-input checks and separately authorized execution.

Start the walkthrough · Choose another SmarterGPT workflow

Add capabilities when needed

LexRunner’s supported workflow has grown in layers. A normal user can stop at any layer.

Layer	Current capability	First surface
Deterministic plan	Freeze PRs and declared dependencies into schema-versioned plan.json	lexrunner weave plan
Merge-weave	Compute merge order, preview integration, run gates, and apply authorized merges	lexrunner weave *, lexrunner gate run
Run and evidence	Persist bounded receipts, independent verification, acceptance, and artifacts	lexrunner attempt *
Fanout	Harvest and analyze issue/PR evidence for parallel work planning	lexrunner fanout *
Assisted agent work	Prepare an immutable packet and workspace envelope, attach a foreground-owned worker, then verify its claims	CLI/MCP Attempt lifecycle

The ADR-010 coordination model is accepted and its assisted Attempt lifecycle is implemented. LexRunner also has a tested headless reconciliation application boundary, but it is not a general production supervisor: there is no approved public headless launch surface, native host/reboot recovery remains release evidence, and Stage 5 fault-injection and authority expansion remain unproven. See ADR-010 and the headless proof boundary.

Architecture boundary

LexRunner has two contracts that must not be blurred:

• Stateless integration core: plan, gate, status, and weave services consume frozen inputs. At integration time, plan.json is the sole authority for dependency order and merge intent. The integration core never reads coordination state or .smartergpt/ as hidden truth.
• Explicitly stateful coordination service: ADR-010 WorkItems, Runs, Attempts, controller leases, workspace leases, receipts, and verification live behind CoordinationStore and workspace lifecycle adapters. That state coordinates implementation work; it does not authorize the integration core or silently alter a frozen plan.

.smartergpt/ is a portable example profile, not a runtime dependency. User/work artifacts belong in explicit stores, ignored local deliverables, CI artifacts, or PR comments—not in the package source tree. Canonical terms live in docs/TERMS.md.

Authority and safety

• Discovery, status, planning, schema validation, merge-order calculation, and dry runs are non-merging operations.
• Gate commands execute the commands declared by the reviewed plan; inspect them before running.
• Git/GitHub writes, delivery, release, and merge are separate authority lanes.
• Worker receipts are claims. LexRunner-owned verification and acceptance are the evidence used by the coordinator.
• Assisted and headless control share durable nouns and fencing rules; neither mode gains implicit merge, credential, release, or external-service authority.

Install and authenticate

Ecosystem 3.1 requires Node.js 24 or newer. The npm package is publicly readable without an npm login. Current source uses Apache-2.0; 2.1.0 is the first public npm release under those terms. Earlier published versions retain their applicable licenses.

npm install --save-dev @smartergpt/lexrunner
npx lexrunner --version

Global installation is also supported:

npm install --global @smartergpt/lexrunner
lexrunner --version

Do not place npm tokens in the repository or a chat transcript. Windows/private-package validation is documented in the Node 24 migration guide.

lexrunner is the canonical CLI name. The existing lex-pr executable remains an additive compatibility alias and invokes the same program, so existing automation does not need to change.

The checked-in package version is the single source for lexrunner --version and lex-pr --version.

Current repository package version: 2.3.0. npm availability and dist-tags are separate release evidence; inspect the registry rather than inferring publication from source metadata.

See the 2.3.0 selected-work candidate, the 2.2.0 frozen-input release, the 2.1.0 open-source release, the 2.0.2 generated timeout correction, the 2.0.1 MCP identity correction, the 2.0.0 plan-bound evidence release, the 1.5.2 exact Lex alignment release, the 1.5.1 release correction, the 1.4.1 canonical CLI release, the 1.4.0 native-host boundary release, the 1.3.0 dogfood release, the 1.2.1 publication repair, and the underlying 1.2.0 compatibility decision for package disposition, semver rationale, supported assisted behavior, and deferred guarantees.

Choose a surface

• Human CLI: follow the first-use walkthrough.
• Agent/MCP: LexRunner ships lexrunner-mcp; use it for plans, gates and integration. No MCP setup is needed for the CLI trial. Tool calls can write artifacts or run commands even when merge mutations are disabled. See the compatibility and setup guide, plus docs/AX.md and README.mcp.md.
• Assisted agent work: run attempt preflight before packet construction. When it reports broker_required, use attempt projection status|prepare to bind the exact committed base into native WSL, then continue with attempt prepare, attempt start, worker attachment/heartbeat, receipt submission, verification, and acceptance. The foreground host still owns worker launch. Follow the native Windows-to-WSL projection workflow for recovery and cleanup.
• Advanced operators: read the orchestration primitives, headless supervisor boundary, and security guidance.

The normative CLI/MCP inventory is generated from live registrations and stored in docs/architecture/cli-mcp-surface.json. Deprecated top-level aliases remain migration aids, not recommended entry points.

Reading order

• Agent fit evaluation — decide whether to adopt, pilot, defer, or decline.
• Merge-weave quickstart — run the smallest integration workflow.
• Canonical CLI/MCP surface — choose stable commands and tools.
• AX contract — understand bounded output, errors, parity, and exceptions.
• ADR-010 — understand assisted agent-work ownership and maturity.
• Documentation index — browse operator, fanout, MCP, audit, security, and contributor material.

Historical v2 design drafts are retained for provenance only. They do not describe a sibling package, active migration, or current runtime contract.

Development

nvm use
npm ci
npm run lint
npm run build

For implementation work, use the touched/adjacent gate selector and let CI prove the full suite on high-risk changes:

lexrunner gate select --base <base-sha> --head <head-sha> --json

Release validation remains exhaustive. See AGENTS.md, CONTRIBUTING.md, and the implementation gate contract.

Package and licensing

• Package: @smartergpt/lexrunner
• CLI: lexrunner (lex-pr compatibility alias)
• MCP bin: lexrunner-mcp
• Runtime dependency: @smartergpt/lex (MIT)
• LexRunner source license: Apache-2.0; earlier releases retain their applicable terms

See LICENSE.md, NOTICE.md, and ADR-008.

SmarterGPT was founded by Joseph Gustavson (Guffawaffle). See stewardship, contributing, and project identity. Commercial use and forks are permitted under the license; code licensing grants no credentials, tenant access or runtime authority.