Lodestar 3.0.0 reference · docs/releases/v2.1.2.md. See the installation guide for prerequisites and upgrade steps.

# Lodestar 2.1.2

Package: `lodestar-agent-context@2.1.2`.

This release brings the 2.x rebuild to the public package and documentation. It is
for people who use coding agents across sessions and want useful project facts,
decisions, and unfinished work to survive without turning context management into
a second job.

## Why upgrade from 1.6

- **A clearer starting point.** Startup reads relevant project context and native
  sources without creating a database, claiming a handoff, or changing records.
  Unavailable required dependencies identify the affected context and correction.
- **Better evidence freshness.** Ordinary record reads compare local source bytes
  with the saved observation. Changed or unavailable evidence is flagged for
  reinspection; an old claim is not silently presented as newly verified.
- **One way to update.** CLI and native tools use contract 5. Reads provide an
  observed write basis; mutations check revisions and retain history. Exact retries
  recover accepted database results without duplicating the effect.
- **Less agent guesswork.** JSON command help and native describe expose complete
  input shapes. Recoverable errors preserve the identifiers and basis needed to
  inspect and correct a request. Native reads cannot dispatch a decision write.
- **Maintainable installation.** Setup plans and applies owned skill and launcher
  updates, keeps replaced bytes, detects local edits, and recovers interrupted
  installations. Startup reports the selected installation and its repair route.
- **Useful continuity after remapping.** Explicit canonical project mappings retain
  usable fact, work, and handoff corrections without relocating their history.
- **Complete transport.** UTF-8 file/stdin requests and argument arrays avoid shell
  quoting and command-length problems. Output files have byte-count and hash
  receipts. Duplicate JSON keys, malformed UTF-8, lossy numbers, and invalid data
  removal keys fail before mutation.

The automatic skill preference remains: orient for substantive project work and
preserve consequential corrections, decisions, and outcomes. User authority and
native instruction precedence remain intact. Missing optional Lodestar context
does not block work whose required inputs are already available.

## Changes since the local 2.1.1 package

- Preserve a typed `database_busy` refusal when contention occurs while preparing
  an update before its transaction starts. Exact retry remains the recovery path;
  unrelated errors keep their original classification.
- Correct missing-database guidance to require explicit initialization or selection
  of an existing store.
- Add the product landing page and shared photographic hero artwork.
- Rewrite the public README around practical use, improvements, and upgrade steps.
- Correct the documentation index and older top-level guidance.
- Share the current-contract packed executable smoke between CI and release
  verification, including explicit initialization, observed bases, exact replay,
  Unicode/line endings, and retirement.
- Correct test fixtures to use physical temporary paths on macOS and Windows.
- Strengthen contention tests to verify exact retry, one receipt, and one durable
  effect even when both initial writers receive a retryable busy refusal.
- Deploy the landing page after successful release publication and check that its
  advertised package version exists on npm.

## Install and upgrade

For a new installation, follow [installation](https://github.com/VerbalChainsaw/Lodestar/blob/v2.1.2/docs/installation.md). Existing 2.x
stores remain on schema 5; this release requires no new database migration.

An existing schema-4 store needs the explicit inspected conversion and a verified
backup described in [storage and recovery](https://github.com/VerbalChainsaw/Lodestar/blob/v2.1.2/README.md#storage-and-recovery).
Do not run old clients against a converted store or restore an older active image
after accepting new writes. Preserve the pre-conversion evidence for recovery.

Custom integrations must adopt contract 5 and use current JSON help or native
describe. Legacy raw-record writes, marker-capture hooks, and implicit startup
handoff claims are not current APIs. The supported native tools are
`lodestar_describe`, `lodestar_read`, and `lodestar_mutate`.

Run selected `setup --apply` upgrades and start fresh host sessions. Review locally
edited assets rather than forcing replacement. Installation does not change host
authentication or guarantee automatic model invocation.

## Compatibility and limits

Node.js 24.15.0 or newer is required. Release verification runs the core test suite
and exact packed executable checks on Windows, Linux, and macOS, with CodeQL as a
publication prerequisite. Windows/WSL operation keeps database access in Windows
Node through the one-shot launcher. These are distinct from native model-session
checks in Codex, Claude Code, OpenCode, and Hermes.

Local checks establish source evidence at read time, not the truth of a claim.
Remote sources are not automatically refreshed. An external action and its later
ledger update are not one transaction. See [limitations](https://github.com/VerbalChainsaw/Lodestar/blob/v2.1.2/docs/limitations.md) for
the supported recovery and host boundaries.