Lodestar v2.1.4

Lodestar 2.1.4

Package: lodestar-agent-context@2.1.4.

This release fixes an installation defect in the optional Codex plugin. Versions
through 2.1.3 could be installed and enabled by Codex, but their cached MCP server
could not find the shared runtime. The CLI and MCP adapter worked inside the full
npm package; the plugin's advertised directory did not contain that full package.

What changed

• The package root is now the plugin root. Root plugin and MCP manifests ensure
  that Codex caches the adapter, executable, shared declarations, and runtime
  together. The implementation continues to use one core and one mutation contract.
• A local marketplace entry points to that complete root. Installation instructions
  explain the optional plugin, native skill setup, and upgrading a cached plugin.
• A plugin hosted inside WSL uses the installed WSL launcher to reach the
  Windows-owned database. Declared path arguments are translated before stdin
  transport, preserving long reads and the complete guarded mutation body.
• Package tests and release smoke checks launch the declared plugin from an
  isolated cache, with no source-runtime overrides. They exercise actual requests
  and inspect persisted results, replay behavior, and refusal of stale writes.

The earlier tests used real processes and databases, but ran the adapter inside
the full npm layout. They did not reproduce Codex copying only the declared plugin
root. The new check covers that missing installation boundary.

Upgrade

Upgrade the CLI with:

npm install --global lodestar-agent-context@2.1.4
lodestar setup --target all
lodestar setup --target all --apply

For the optional Codex plugin, use the complete package root. Custom marketplace
entries pointing at codex-plugin/ must be updated before reinstalling. A global
npm upgrade does not update a plugin already copied into Codex's cache. Follow
plugin installation,
keep one active Lodestar plugin, and begin a fresh task after updating it.

The CLI and native skill remain useful without the optional plugin. Automatic
invocation eligibility remains enabled as corrected in 2.1.3. Host settings and
native instructions retain their authority.

Compatibility

Requires Node.js 24.15.0 or newer. Contract 5 and schema 5 are unchanged; existing
2.x stores require no new migration. Windows/WSL access still uses the Windows-owned
one-shot boundary. Release checks run on Windows, Linux, and macOS. Installation
and protocol tests establish executable behavior; they do not guarantee that every
model task selects a skill or tool.

Lodestar v2.1.3

Update (2026-09-08): Lodestar 2.1.4 fixes startup of the optional Codex plugin after native caching and corrects WSL plugin routing. It also retains the automatic skill invocation correction from 2.1.3. Upgrade the CLI and separately reinstall any cached plugin using the complete package root; see the 2.1.4 installation notes. Contract 5 and schema 5 are unchanged.

Lodestar 2.1.3

Package: lodestar-agent-context@2.1.3.

This patch fixes a Codex integration defect in 2.1.2: Lodestar's skill description
requested automatic use, but its native metadata disabled implicit invocation.
Codex could discover an enabled skill while excluding it from automatic use.
Restarting or reinstalling that package did not correct the policy.

What changes

• The maintained skill and Codex plugin now explicitly allow implicit invocation.
  Codex can select Lodestar for relevant project work without a skill mention.
• Setup distributes the corrected metadata through the existing owned upgrade
  path, retaining backups and refusing to overwrite independently edited files.
• Packed executable checks now exercise native installation, installed invocation
  policy, plugin parity, startup installation status, preservation of user settings,
  and refusal to overwrite a locally changed invocation policy.
• Documentation checks discover release notes automatically. Release checks require
  the plugin version and packaged release notes to match the package version.

Upgrade

npm install --global lodestar-agent-context@2.1.3
lodestar setup --target all
lodestar setup --target all --apply
lodestar skills verify --target all

Select an individual target if that is the host you use. Review local conflicts
reported by setup; do not force replacement without inspecting the changed files.
Start fresh host sessions after the upgrade. Existing 2.x databases remain on schema
5 and require no migration or reinitialization.

For new installations and explicit host locations, see
installation and startup.

Scope and verification

Automatic eligibility does not create a startup service or guarantee that every
prompt invokes Lodestar. Host-level skill disabling remains effective. User and
native project instructions retain their authority.

The release workflow runs tests and packed executable checks on Windows, Linux,
and macOS, with CodeQL required before publication. These checks verify packaging,
installation, policy, and CLI behavior; they do not certify every host or model's
skill-selection decisions.

Contract 5, schema 5, the one-shot executable, and the database mutation contract
are unchanged by this patch.

Lodestar v2.1.2

Update (2026-09-08): Lodestar 2.1.4 fixes startup of the optional Codex plugin after native caching and corrects WSL plugin routing. It also retains the automatic skill invocation correction from 2.1.3. Upgrade the CLI and separately reinstall any cached plugin using the complete package root; see the 2.1.4 installation notes. Contract 5 and schema 5 are unchanged.

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. 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.
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 for
the supported recovery and host boundaries.

Lodestar v1.6.0

Lodestar 1.6.0

Package: lodestar-agent-context@1.6.0.

The lean release

This is the first Lodestar release published since 1.4.1. It carries the
1.5.0 boundary tightening — Lodestar no longer owns external skill
directories or repository agent files, and its skill and agent surfaces are
read-only verification — and the lean-reduction work that follows: retired
subsystems are removed, the remaining record paths are batched and measured,
the hooks fail soft, and the managed skill payload grew additively.

Retired subsystems removed

• The v0.7 generation-store importer is gone (lodestar import, the
  legacy-v070 modules, and the migration guide). The registry is schema v4
  with one internal migration path; there is no legacy-store bridge.
• The startup-budget mechanism is gone entirely. start always returns every
  optional record: no --startup-budget flag, no environment or config
  sources, no truncation surface. more and next stay in the envelope but
  never fire for startup.
• The Stop hook no longer captures decision/DEAD/SUPERSEDED ledger markers:
  the ledger changes only through explicit lodestar decision commands. NOTE
  markers still quarantine as pending candidates.
• The release hero-image gate is gone: CI neither requires nor attaches the
  launch hero to GitHub releases. The artwork stays in docs/assets for the
  README and historical release notes.

Faster reads, measured

Startup context, find, links, decisions, pending, and work lists now assemble
records with a constant number of queries instead of one query per record. On
a 1,000-record registry: start ~118ms -> ~44ms and find ~134ms -> ~24ms.

Gentler defaults

• put without content.state stores known; a source without metadata
  or metadata.inspection stores not_inspected. Explicit states still
  validate; the knowledge and inspection axes remain the full record model.
• Default find omits reserved startup-snapshot cache records (an explicit
  --kind startup-snapshot still finds them).
• find --limit <n> --offset <m> paginates, and a truncated page reports the
  exact next command with the correct offset.

Fail-soft hooks

A missing or broken Lodestar runtime no longer blocks session start, and a
host that omits identity fields no longer blocks prompt submission.

Envelope cleanup

The empty available stub is gone from the startup envelope (a leftover of
the retired budget mechanism).

Skill payload growth (additive)

The managed skill payload now includes the adderall skill, and the current
reference material is restored: the center-audit compact-mode and
worked-example references, the director-protocol agent configuration, and
the ladder-audit README. The payload was only added to — nothing was
removed or shrunk.

Marker parsing hardened

The quoted-value matcher in the marker grammar is now the unambiguous
(?:[^"\\]|\\.)* form, removing a ReDoS-shaped overlap between escape and
plain-character alternatives (reported by CodeQL as high severity). Parsing
behavior is unchanged for valid markers.

Requires Node.js 24.15.0 or newer.

Lodestar v1.4.1

Lodestar 1.4.1

Agent startup doctrine and native instruction files now have one owner instead of
competing copies of reality.

npm install --global lodestar-agent-context@1.4.1
lodestar skills sync --target all
lodestar skills verify --target all

One rule, one owner

The Director Golden Operating Rules now ship as the sole required global governance
record, g:lodestar:required-governance. Its machine-readable source is
managed-assets/governance.json; docs/GOLDEN-RULES.md is generated from that same
source as the complete human-readable recovery copy. Historical governance IDs no
longer compete in required startup context.

Lodestar supports two deliberate project shapes:

• A full native AGENTS.md or equivalent owns version-controlled project rules and
  directs the agent to Lodestar for durable decisions, knowledge, work presence, and
  continuity.
• A minimal native file bootstraps Lodestar only when lodestar start is proven to
  return every required governing rule without truncation or omission.

The two shapes are alternatives. Evolving the same rule in both places creates a
split-brain contract in which a native agent file and Lodestar startup can instruct an
agent differently.

The minimal stub is generated truth

The shipped minimal AGENTS.md stub now matches the package-owned bootstrap exactly.
The package test enforces that identity, so command-surface changes cannot leave a
second hand-written stub stale.

Published model-facing assets are also scanned for the retired handoff save,
handoff validate, and handoff clear verbs. The supported continuity surface remains:

lodestar handoff arm|status|checkpoint|now|disarm

Startup headroom restored

Lodestar's general default startup envelope is now 24 KiB, leaving the established
4 KiB minimum project headroom after the complete Golden Rules are loaded. Explicit
budgets still win, and the Codex adapter retains its measured 16 KiB host boundary.

Codex startup and stop-hook recovery now shed oversized optional continuity content
without truncating or inferring required authority.

Upgrading

There is no schema change and no registry migration. Install the package, then sync and
verify the managed client skills so every configured agent receives the same template
contract.

npm install --global lodestar-agent-context@1.4.1
lodestar skills sync --target all
lodestar skills verify --target all

Requires Node.js 24.15.0 or newer.

Lodestar 1.4.0 — the budget is yours to set

Lodestar 1.4.0

The startup budget stopped being a number somebody else picked.

npm install --global lodestar-agent-context@1.4.0
lodestar start --cwd . --startup-budget 65536

16 KiB was a guess

Startup context is injected into every session before you type anything, so it has to be
bounded — unbounded, it competes with the work itself. That much is real.

The number was not. 16,384 bytes is roughly 4K tokens: generous for a small local model,
about two percent of a 200K-context host. The same figure applied to both, and nothing
could change it. A project would shed fifty records to protect two percent of a context
window that had room to spare.

Set it where it belongs

--startup-budget 65536             this run
LODESTAR_STARTUP_BUDGET=65536      this host
config record, project scope       this project
config record, global scope        this machine

Most immediate wins. A project setting beats a machine one, because the project is the
narrower statement. A config record is an ordinary record:

{ "id": "config:startup", "type": "config", "name": "Startup budget",
  "scope": "global",
  "content": { "state": "known", "value": { "startup_budget_bytes": 65536 } } }

Adjustable, not unbounded

A budget you can raise without noticing stops being a forcing function, and Lodestar
becomes another place sprawl accumulates — in SQLite instead of Markdown. So the
discipline moved from the wall to the reporting:

"budget": { "bytes": 65536, "source": "option" }

Every projection states the budget in force and where it came from. doctor measures
against the same number rather than its own copy, and reports against the strictest
budget any project in the registry runs under. Raising it is a choice on the record, not
a silent drift.

Values outside 8 KiB–256 KiB are typos, not instructions, and fall back to the default —
a stray 10 cannot strangle startup and a stray 999999999 cannot defeat the bound.

What it looks like

The same project, same records, two budgets:

16 KiB   0 context carried, 2 stubs, 53 names hidden entirely
64 KiB   10 context carried, 44 stubs, nothing hidden

The 1.3.0 shed ladder still runs underneath at any budget, so a projection is bounded by
whatever number is in force and start still always returns.

Upgrading

Schema unchanged since 1.2.0. data.budget is new. The default is 16 KiB, so a
registry that sets nothing behaves exactly as before.

npm install --global lodestar-agent-context@1.4.0
codex plugin add lodestar@personal

Requires Node.js 24.15.0 or newer.

Lodestar 1.3.0 — start always runs

Lodestar 1.3.0

start cannot refuse to run any more, and nothing it drops disappears.

npm install --global lodestar-agent-context@1.3.0
lodestar start --cwd .

The budget was working against its own purpose

The 16 KiB startup budget exists to stop three things: losing context, thrashing, and
reading more than a session needs. It was causing all three.

It refused to run. Required records totalling more than the budget threw
resource_limit. start is the first command of every session, so that stopped all
work in the project — over a record someone marked required, often in a different
project entirely, since a global required record is charged to all of them.

It dropped context and told the agent to go looking. Shed records vanished from the
projection, leaving a count and lodestar find --limit 50. The agent then ran a broad
search and re-read up to fifty records to find one it had a moment earlier. The budget
saved a few kilobytes and spent far more getting them back.

Demote, don't delete

Everything the projection cannot carry is now named:

"available": [
  { "id": "p:sunosavvy:regression", "name": "Regression surface", "kind": "rule" }
],
"omitted": { "context": 54, "required": 2, "hidden": 3 }

A stub costs about a twentieth of a record. The agent sees everything that exists in
scope and fetches the one thing it needs with a single lodestar get — no search, no
re-reading.

A fixed order, by value

1  optional context records      demoted to stubs
2  advisory work                 demoted to stubs
3  stubs of optional records     dropped, counted in omitted.hidden
4  required records              demoted to stubs
5  the governance record         last, only if nothing else remains

A required record's content outranks an optional record's name, so step 3 comes before
step 4. Startup always returns.

Verified against 48 KiB of required records inside a 16 KiB budget: start succeeds,
carries four in full, names the other nine, and reports {"required": 9}.

The cost is now visible where it is spent

Marking a record required is where the budget is committed, and it used to say nothing:

lodestar doctor — required records in project:p:sunosavvy now total 17204 of the
16384 startup budget, so start will demote some

Reported, never refused — a bulk import must not fail on its last record.

Upgrading

Schema unchanged since 1.2.0. data.available is new; data.omitted gains
required and hidden counts. Nothing was removed.

npm install --global lodestar-agent-context@1.3.0
codex plugin add lodestar@personal

Requires Node.js 24.15.0 or newer.

Lodestar 1.2.7 — the budget check can finally see the outage

Lodestar 1.2.7

doctor was watching the wrong number, and continuity refusals told agents a rule
without telling them the way out.

npm install --global lodestar-agent-context@1.2.7
lodestar doctor

The budget check could not see the outage it was built for

start renders a bounded projection into 16 KiB. When required records exceed it, it
sheds; past a point it refuses. The cost charged to a session is global required
records plus that project's own.

doctor measured only the global half. So a registry with a modest global footprint
reported healthy while its heaviest project was nearly dead:

before   global 10029 of 16384, headroom 6355        healthy
after    worst project 15187 of 16384, 1197 left     startup_budget_low

Both describe the same registry. Only the second predicts the failure.

The check now reports worst_project — its scope, its own required bytes, its total
startup cost, and what remains — and raises the issue against that project by name.

A check that disagreed with itself

startup_budget.healthy used half the budget as its threshold. The issue used 4 KiB of
headroom. Ordinary registries landed between the two and printed:

{ "healthy": true, "issues": [], "checks": { "startup_budget": { "healthy": false } } }

A nested false with no issue and no action is worse than no signal — it asks the reader
to act and gives them nothing to act on. One threshold now drives the flag and the issue
together, so they cannot diverge again.

Refusals now name their exit

Three continuity states stated a rule and stopped:

handoff_not_armed    This session does not own an armed lane.
handoff_conflict     This session already owns an armed lane.
handoff_pending      Cannot disarm while recovery is pending.

Every one of those states has a way out. None of them said so. An agent that reads only
the rule concludes the operation is impossible, stops asking Lodestar, and drives the
raw CLI — which is how a working system gets routed around.

Each now carries the command that resolves it, and the tests assert that the named exit
actually works rather than merely that the refusal happened.

help and version

lodestar help and lodestar version returned unknown_command; only --help and
--version were accepted. Both spellings now answer, including lodestar help <command>.

Upgrading

Schema unchanged since 1.2.0. Refresh the plugin and restart the host so the running
process loads it:

npm install --global lodestar-agent-context@1.2.7
codex plugin add lodestar@personal

Requires Node.js 24.15.0 or newer.

Lodestar 1.2.6 — a stuck project can save again

Lodestar 1.2.6

A project could permanently lose the ability to save continuity, and the command to save
one was refused unless typed in exactly one spelling. This release fixes both.

npm install --global lodestar-agent-context@1.2.6
lodestar start --cwd .

A delivered baton kept guarding the door

A recovery record has two states. pending means a baton is waiting for the next
session. claimed means a successor has already read it.

handoff now refused to write when a recovery existed and the caller was not its
claimant. That is right for pending — overwriting an undelivered baton destroys
someone else's work — but wrong for claimed, where the content has already been
handed over and nothing remains to protect.

The consequence was permanent. A claimed recovery cannot be re-claimed by anyone but
its claimant, so if that session never saved a baton of its own, every later session
got:

handoff_conflict: A pending or claimed project recovery is owned by another session.

There is no handoff clear, and handoff disarm only retires a lane. The project was
stuck with no way out short of editing the registry by hand.

This is reachable in ordinary use. Resume a session, let Lodestar hand you the baton,
then close the host without saving a new one — that project is now wedged.

What changed

handoff now refuses in exactly one case: a pending recovery written by a
different session. Nothing else blocks a save.

pending,  another session   refused   an undelivered baton is someone else's work
pending,  same session      allowed   supersedes your own draft, still idempotent
claimed,  any session       allowed   the content was already delivered

A pending baton never wedges anything, because the next session in the project claims
it on startup and can then save. Removing the claimed case removes the only state that
had no exit.

The refusal message now says unclaimed rather than pending or claimed, and carries
the recovery id, its generation, and what to do next.

One phrase, one spelling

Writing a baton requires the user to say it, not the agent. That gate compared the whole
prompt against one literal string, so every ordinary way of typing a command was refused:

handoff now        authorized
$handoff now       refused
/handoff now       refused
Handoff Now        refused
handoff now.       refused
lodestar handoff now   refused

Agents prefix sigils by habit. A refusal here reads as "you are not allowed to do this",
so the agent stops asking and drives the raw CLI instead — routing around the very gate
that was supposed to hold.

The security property was never the spelling. It is that the whole prompt is the
command and nothing else, which is what keeps a passing mention from authorizing a
write. Case, spacing, a leading sigil, and a trailing period cannot change intent, so
they no longer matter. Prose still does not authorize:

handoff now please         unauthorized
please handoff now         unauthorized
don't handoff now          unauthorized
handoff now and then disarm    unauthorized

If a project is already stuck

Nothing to repair. Upgrade and save a baton as usual — the stale claim no longer
blocks it, and the next save opens a fresh generation. Earlier packets are kept.

Upgrading

Schema unchanged since 1.2.0. Refresh the plugin and restart the host so the running
process loads it:

npm install --global lodestar-agent-context@1.2.6
codex plugin add lodestar@personal

Requires Node.js 24.15.0 or newer.

Lodestar v1.2.5

Lodestar 1.2.5

Tool calls failed when the host spelled a tool name differently than the plugin
expected. This release makes recognition namespace-agnostic.

npm install --global lodestar-agent-context@1.2.5
lodestar start --cwd .

One tool, three spellings

A host may present the same tool as lodestar_work_start,
lodestar__lodestar_work_start, or lodestar/lodestar_work_start. The hook stored
whichever string it received, and execution compared against a reconstructed one. When
those disagreed the call failed with:

Invalid, expired, mismatched, or replayed host attestation

That message describes a security failure, so a naming mismatch looked like tampering.
Both sides now compare the canonical suffix. The token stays bound to its session, turn,
cwd, and arguments — only the spelling stopped mattering.

Verified across every form, for both families:

work_start        lodestar_ / lodestar__ / lodestar/     ok
handoff_status    lodestar_ / lodestar__ / lodestar/     ok

Near misses still miss: notlodestar_work_start, lodestar_work_bogus, and
work_start are not recognized.

Upgrading

Schema unchanged since 1.2.0. Refresh the plugin and restart the host so the running
process loads it:

npm install --global lodestar-agent-context@1.2.5
codex plugin add lodestar@personal

Requires Node.js 24.15.0 or newer.