# falsegreen-agent
`falsegreen-agent` is a bounded local Rust coding-agent harness. It turns a human-frozen task into
workspace-confined model/tool activity and submits candidate source to canonical FalseGreen. The
worker, its tests, and `candidate_ready` can never mint acceptance.
FalseGreen verification and permission to claim completion are deliberately separate:
```text
verification Accepted + authority_ready=false + may_claim_complete=false
-> AcceptedAwaitingAuthority (not Completed)
verification Accepted + authority_ready=true + may_claim_complete=true
-> Completed
verification Failed/Incomplete/Invalid
-> bounded repair path or Failed
```
NeoHorse-1-9B Q8_0 is the selected V1 reference/default model. The agent remains model-neutral
behind `InferenceProvider`, `ModelCapabilities`, and its OpenAI-compatible provider.
The normal CLI provides an Ollama-free managed local stack. It detects the host, acquires the pinned
llama.cpp build and NeoHorse artifact into a verified user cache, starts an owned loopback-only
`llama-server`, connects configured MCP servers through `rmcp`, and uses the statically linked
FalseGreen Core client. Valid cached artifacts are reused on later runs.
## Build and verify
```bash
cargo fmt --all -- --check
cargo clippy --all-targets --all-features --locked -- -D warnings
cargo test --all --locked
cargo build --release --locked
git diff --check
```
## Install and run
```bash
cargo install --path . --locked
falsegreen-agent login
cd /path/to/your/project
falsegreen-agent
```
`falsegreen-agent login` prompts for an enrollment key and stores the resulting session in the same
protected platform credential store used by the standalone `falsegreen` client. The enrollment key
is not retained. Existing standalone credentials are discovered automatically. Authentication can
be inspected or revoked without installing the standalone binary:
```bash
falsegreen-agent status
falsegreen-agent logout
```
The first managed run downloads the pinned llama.cpp runtime and the 9,527,501,632-byte NeoHorse
model, verifies their exact sizes and SHA-256 digests, then starts a private loopback server. Allow
at least 11 GB of free cache space. The cache defaults to the platform/XDG cache directory and can
be overridden with `FALSEGREEN_AGENT_CACHE_DIR` or `--cache-dir`.
## Normal V1 run
Run the agent from the Git repository it may change. The `run` subcommand and
`--workspace` are optional:
```bash
falsegreen-agent task select task_...
falsegreen-agent "the complete frozen implementation task"
```
The current directory becomes the confined workspace. Durable event state is
placed outside it, NeoHorse is the pinned managed default, FalseGreen is the
embedded completion boundary, and configured MCP servers are discovered. When
no paused session or saved task exists, an interactive commandless run prompts
for the coding goal and FalseGreen task ID. A later command with no goal resumes
the most recent safely paused session:
```bash
falsegreen-agent
```
Use `falsegreen-agent doctor` for readiness checks and `--json` for automation.
See [the one-command UX contract](docs/ONE_COMMAND_UX.md).
An infrastructure-failed terminal session that already contains complete candidate provenance may
be replaced explicitly without reopening it or invoking the model again:
```bash
falsegreen-agent replace-session session_... --candidate-sha256 <exact-sha256>
falsegreen-agent resume <replacement-session-id>
```
Replacement creation is fail-closed, permits one direct replacement with no chains, and atomically
records both a first-class relation and durable event. Resume requires the exact inherited Task,
candidate, and full Git/workspace identity. Replacement sessions are verification-only: canonical
rejection cannot reopen model repair. See the
[replacement-session contract](docs/REPLACEMENT_SESSIONS.md).
## Advanced external-provider run
An explicit endpoint bypasses managed acquisition. Pinned NeoHorse still requires the exact named
artifact and digest, but an arbitrary external runtime never inherits a full-stack qualification:
```bash
falsegreen-agent \
--workspace /path/to/repository \
--db /separate/state/events.db \
--goal "the complete frozen implementation task" \
--fg-task task_... \
--endpoint http://127.0.0.1:8080 \
--model-artifact /models/NeoHorse-1-9B-Q8_0.gguf
```
The verifier is the statically linked FalseGreen Rust client and uses the protected session created
by either `falsegreen-agent login` or `falsegreen login`. Normal agent operation and authentication
do not launch or require a separately installed `falsegreen` executable. `FALSEGREEN_API_URL`
remains the compatible endpoint override.
## Pinned Core dependency
`Cargo.toml` pins `truemagic-coder/falsegreen` by exact Git revision and
`Cargo.lock` records the same source. To update Core, review a specific Core
commit, replace only the dependency `rev`, update the lockfile, then run the
full format, lint, authority-boundary test, and release-build commands above.
Never replace the immutable revision with a branch or tag, and never carry a
lockfile that resolves a different Core commit.
The selected profile fixes repository, revision, artifact digest, Q8_0 quantization, 8,192-token
context, runtime family, and MTP-disabled setting. The normal path obtains the model and runtime
automatically and uses the embedded FalseGreen client. The official managed llama.cpp packages
are a different distribution/backend from the prior frozen qualification and therefore remain
unqualified until their own full-stack qualification succeeds. See
[the exact profile](docs/NEOHORSE_V1_PROFILE.md) and
[managed runtime contract](docs/MANAGED_RUNTIME.md).
An experimental provider/model must be explicitly marked unqualified:
```bash
falsegreen-agent run ... --unqualified-model experimental-model
```
Qualified-profile metadata cannot be overridden piecemeal. An unqualified configuration never
inherits the V1 qualification claim.
## Durable operation
The event database must be outside the implementation workspace. Every model request, response,
tool request/result, candidate, verification, repair, state transition, and source fingerprint is
append-only. Use `--pause-after-model-turns N` to end a process at a persisted turn boundary; resume
with `--session session_...`. Resume verifies the exact checkpoint candidate fingerprint before
another model request or tool call.
Terminal history is immutable. A supported replacement creates a distinct `CandidateReady`
session linked to one infrastructure-failed predecessor, verifies the current workspace against
the carried candidate and complete Git provenance before runtime setup, and goes directly to
canonical verification on explicit resume. It never treats the predecessor as active, never
invokes inference to adopt the candidate, and cannot enter model repair after a non-accepted
verification result.
Exit codes distinguish the authority states: `0` means authoritative `Completed`, `3` means
canonical `Accepted` awaiting completion authority, `75` means an intentional resumable pause,
and other nonzero results are non-complete.
Native tools are `read_file`, `search`, `apply_patch`, bounded argv-based `shell`, and read-only
`git`. Paths are workspace-confined; patch paths are checked; command time/output and file reads are
bounded; unknown or malformed calls fail safely. This is a local development boundary, not a
production security sandbox.
Track 5 adds an optional trusted GenUI/GenTUI presentation seam. `--genui`
augments human run output with a deterministic terminal surface; it does not
replace chat, generate UI code, emit ANSI, or become an authority surface.
The versioned component/action contract, MCP schema adapter, bounds, stale
action checks, and security rules are documented in
[docs/GENUI_TRACK5.md](docs/GENUI_TRACK5.md). FalseGreen Core remains the
only acceptance authority.
This release ships the accepted Agent foundation, FalseGreen-native state surfaces through G4, and
the independently accepted G5 V10 generative composition path. G5 remains a constrained,
read-only presentation composition layer: trusted handles and host-owned authority are required,
model proposals cannot grant execution authority, and live fences preserve the existing
workspace, durable-state, MCP, policy, confirmation, and renderer boundaries. See
[the G5 composition contract](docs/GENUI_G5_GENERATIVE_COMPOSITION.md).
Optional MCP tools can be discovered from strict versioned JSON with `--mcp-config PATH`. The
official Rust `rmcp` SDK supplies stdio and Streamable HTTP transport, initialization/capability
negotiation, `tools/list`, `tools/call`, cancellation, and cleanup. Remote tools are exposed through
stable collision-resistant `mcp__...` names and retain bounded durable call provenance. See the
[MCP client configuration](docs/MCP_CLIENT.md).
See [architecture](docs/ARCHITECTURE.md), [V1 qualification](docs/PHASE2_RESULT.md),
[model decision](docs/MODEL_EVALUATION.md), and [dogfood history](docs/DOGFOOD.md).