Repository navigation
v3.12.3
Added
-
Process v1 G6 and checker ≠ author on Hive tasks. Submitting a task that carries
processnow runs the G6 gate in the Instance: the locked tests must be unchanged against
spec_commitand must actually run and pass in a clean rerun, else the submit is refused
with the rule and the paths, and nothing is sent. A verify is refused for the session that
claimed or submitted the result. Tasks withoutprocesskeep today's path, and no Hive
serves process tasks yet. Known gap: code under test runs as the agent's Unix user and
could forge a passing report; details and the planned fix are in the module documentation
ofrust/crates/lean-ctx-hive/src/tasks/process.rs.
G6 also asks the compiler which locked tests exist atspec_commit(one extra build in a
private copy; no test ofspec_commitruns), so a locked test the parser cannot name
(macro-generated,#[cfg_attr(test, test)]) must still pass in the judged run. This can
roughly double a G6 run's time.
G6 runs on Linux, macOS and Windows. On macOS a kqueue watch notices a renamed or removed
ancestor of the run tree (as inotify does on Linux). On Windows the run uses Git for
Windows'sh, an environment built from the known folders and a job object; there the
tree's ancestors have no rename protection and locked files are pinned by content,
attributes and write time (details intasks/gate_run.rs). -
P4 tripwires: new crate
lean-ctx-tripwires. A pure, deterministic diff analyzer that flags the documented reward-hacking tricks (touched tests or graders, removed or weakened asserts, new skips, a falling test count, fixture constants, branches on test inputs, time/hash/assert overrides, swallowed errors, mock-only tests, edit cycles, plusunparsable) and returns aleanctx.process.tripwires/v1report; a hit routes to a person, never to automatic acceptance. Not wired into the gate yet. -
Each app session is its own Hive worker (E48). An agent registered with
LEAN_CTX_SESSION_IDset gets the role<role>-s<tag>, where the tag is 8 base32
characters of a blake3 hash of the session id. It is stable across MCP restarts, so every Hive
Desktop session appears on Hive and in the roster as its own worker (coder-s…). A reviewer
session on the same Instance can now pass Hive'sself_verify, while a subagent of the same
session is still the same worker and is refused. Without a session id the shared
(host, role)worker is kept as before. One key (attach::agent_worker_key) now drives task
links, attach, roster, friction and worker accounting. The session id comes from the
environment, so this separates sessions as hygiene, not as a trust boundary: the boundary
stays the Instance. Upgrade note: a claim taken before the upgrade by the shared worker
belongs to a differentwkr_, so let it expire or release it and claim again. -
Meta Muse Code agent target (#2198).
lean-ctx init --agent museandsetupregister the
lean-ctx MCP server in$XDG_CONFIG_HOME/muse/settings.json(default
~/.config/muse/settings.json). The writer adds the mandatory"schema_version": 1when it is
missing, keeps every other key and server, and merges into the root the file already uses —
canonicalmcpServersor legacymcp_servers— because Muse disables MCP when both appear;
a file that already mixes them is left untouched with an error. Re-runs are no-ops,uninstall
removes only thelean-ctxentry, anddoctorchecks the entry. Muse Code is MCP-only: its
PreToolUse output schema is closed and anallownever skips approval, so shell rewrites would
add prompts. Guidance reaches it through the projectAGENTS.mdit auto-loads. -
Task priority: the boards carry the order of work. A task's priority (
high|
normal) and labels (up to 16 of[a-z0-9-]{1,32}) are set with
lean-ctx hive tasks priority <n> high|normal/labels <n> a,b|--clear(C0 2.2 E47
PATCHat the task'sfields_version, read again and resent once onstale_base), from
Hive Desktop over/v1/local/hive/tasks/{n}/priority|labels(tasks.ack), and by a Queen
session withctx_tasks action=prioritize. Local tasks take the same verbs
(lean-ctx tasks priority|labels,/v1/local/tasks/{n}/priority|labels, event
fields). Lists show high first, then by number, an older high task included (the high
tasks are fetched beside Hive's newest-100 page); a list a full Hive answer may have cut
is markedpartial(JSONpartial: true, a(partial: …)line in text). JSON
rows carrypriority,labelsandfields_version. A wrong value is refused before any
request. Only a person (the app, the person's own CLI) and Queen sessions the app
registered over the local socket (/v1/local/queens, socket only) set them; workers read
them. A self-declared bus role is never enough. -
The bus refuses approvals in a person's name (process v1 §7).
ctx_agent postand
sendrefuse an agent's message, with a named rule and nothing rewritten, when it
speaks for a person (on_behalf_of,400 invalid_field: theon_behalf_offield or
"on behalf of …" / "in the name of …" in its text), states or hands off a person's
decision (approval_on_behalf,403 forbidden_right: decision fields with a person as
decider, a handoff of an Inbox item, consent, G2/G9/G10 approval, release, deploy,
secret or rights decision, or a sentence such as "the owner approved …"; questions,
negations and "waiting for" never match), or passes on what was refused for the sender
(denied_forwarded,403 forbidden_right: a place Hive denied, a publish Hive refused,
a vetoed lock or handoff). These three are always enforced. The checks cover questions,
answers, offers and handoffs;status,progressandfindingposts are not checked.
The relay applies the same rules to older queued posts and keeps a post that breaks
them local (counted aswithheld). Publishes the Hive refuses are remembered per sender
in the newbus/refused.json(7 days, at most 1000), so no agent passes them on. Only a
registered Queen session appears as the Queen: under the new[hive] queen_identity
(warn|enforce, envLEAN_CTX_HIVE_QUEEN_IDENTITY, which wins) the defaultwarn
passes a sender presenting as the Queen (rolequeen, the name "Queen", a "From the
Queen:" label) that is no registered Queen session, puts
[unverified Queen sender: <name>, agent <id>, role <role>]in front of its text and
logs it in the newbus/queen-warnings.json;enforcerefuses it, and any other value
counts asenforce. Switch toenforceonly oncequeen-sessions.jsonlists every
Queen session: Queens on another machine are not registered with the host yet. Not
covered yet: app session messages (hive_message_session, an app tool, not the bus). -
Rights per session (process v1 §9). The launcher (Hive Desktop) writes one rights file
per session (leanctx.session-rights/v1) and starts the session with the new
LEAN_CTX_RIGHTS_FILE=<absolute path>. It narrows what that session may write, below the
Instance's own path jail: writes only inside the role's write scopes, such as its own
worktree (write_scope); after G2 no role, the Spec Writer included, writes a locked path
(the feature list, a locked test, a directory or hard link holding one;
feature_list_locked); adeny_writeclass refuses (deny_write:<class>); the rights
file itself is never written (rights_file);denied_toolsrefuses a tool, aliases
included (denied_tools). It applies toctx_shell/shell(a command whose writes
cannot be judged is refused:unanalysable),ctx_execute, LeanCTX's own writes, the new
lean-ctx hook rightsfor nativeEdit/Write/MultiEdit/NotebookEdit/Bash/
apply_patch(an unknown native tool is refused:unknown_tool), and calls forwarded to
the daemon, which carry the file as the new/v1/tools/callfieldrightsFile(local
socket only, else400 rights_file_refused; a profiled session may not use the daemon
socket itself:daemon_socket). Every refusal names its rule. Reads are not narrowed. A
rights file that is set but missing, unreadable, insecure or invalid refuses every tool
call and every write; it never falls back to the Instance's rules. No rights file set
means no change: the Instance's rules apply as before. This is a best-effort first line;
the guarantee is the G6 locked-path check, and the known limits are listed in the module
doc (rust/src/core/session_rights.rs). -
Local Read / Local Service contract for LeanCTX | Hive Desktop. Every Local Read kind
is a versioned JSON document on the CLI and a/v1/localroute of the daemon socket,
released with one receipt for the bytes sent, and listed in onecapabilitiesdocument
with every verb and the transports that answer it (docs/contracts/local-read-v1.md,
local-service-v1.md): session stats and cost perLEAN_CTX_SESSION_ID, gain/spend
rollups (daily and per project), the agent bus (bus list|read|post|leases|claim|release),
presence list, knowledge writes, evidence verification and export, providers, effective
policies with the organization policy's signature state,agents, and the new
lean-ctx daemon status --json(running,pid,socket,autostart,service_name). -
Sync and policy evidence on the local service.
hive.sync,policy.sessionsand
policy.session, CLI-only before, are served on the daemon socket at/v1/local/hive/sync,
/v1/local/hive/policy/sessionsand/v1/local/hive/policy/sessions/{id}, released through
the same release point (one receipt) and listed in capabilities.policy.sessions
installedaddsvaults: one row per vault the installed policy reaches on this machine
(vault_id,ns,name, linkedroots) and which policy applies (vault,default, or
unverifiedwhen the installed policy files are damaged or too old — fails closed). Read
only, from local files; nothing contacts Hive (docs/contracts/local-read-v1.md§23). -
Presence with names.
LEAN_CTX_SESSION_NAMEnames an agent session;presence list
rows carry the session name, agent host, Instance (machine) and project with its vault;
hive presencerows carry the names a Hive relays with a presence. -
A person's bus post can leave the machine.
bus postanswerscloud(queued,
local_only,withheldorheld, with the reason); a post to a vault bus is published as the
person once the Hive accepts a person's publish (hello.ackfeatureperson_publish). -
tasks amend: correct a submitted result, record a done task's merge. A submit ends
the claim, so a new head or a merge commit could not be recorded afterwards ("this machine
holds no claim").lean-ctx tasks amend/hive tasks amend,ctx_tasks action=amendand
POST /v1/local/tasks/{n}/amend(listed in capabilities) let the agent that submitted a
result replace its evidence and summary while it is submitted; once it is done, the
submitter, a person or a registered Queen session records the merge commit once (--merge <sha>,result.merge); never the reviewer (not_merger).
Every amendment passes the release first (a withheld one writes nothing) and lands in the
task history as old → new (updatekind: amendment,amended_from,amended_to). On a
vault it needs the Hive routePOST /v1/vaults/{id}/tasks/{n}/amend, which no Hive serves
yet: it fails closed with "not supported by Hive yet" and sends nothing. -
Hive background sync: a connected Instance keeps its shared vaults in sync by itself.
lean-ctx setupandlean-ctx hive connectnow install the daemon as a supervised service
that starts at login and restarts after a crash: the systemd user unitlean-ctx-daemon
on Linux (loginctl enable-linger <user>keeps it running on a headless machine while
logged out), the LaunchAgentcom.leanctx.daemonon macOS. This changes an upgrade: the
nextsetuporhive connectinstalls a service that was not there before. The daemon
syncs a local change (a remembered fact, a written doc page) 5 s after the last change and
at most once every 30 s per vault, syncs at once when Hive announces a change of the vault
(buslog.advanced,trust.advanced), and otherwise every[hive] pull_interval_minutes
(default 5). Only vaults already shared from this machine sync.lean-ctx doctorreports
Hive sync needs a supervised daemon (run: lean-ctx daemon enable)when the machine is
connected to Hive and the service is missing.lean-ctx hive syncstill works and syncs
the current project at once. Details:docs/guides/hive-background-sync.md. -
The build says where it came from.
lean-ctx --versionnames the build kind after the
version:officialonly for the upstream release workflow, otherwise(dogfood <sha>)for
the promoted Instance state,(dev <sha>)for any other checkout (, dirtywith local
changes) or(source)for a tree without git. Thecapabilitiesdocument carries a
buildblock (kind,commit,dirty,official), andlean-ctx doctorshows the
build origin. The label is a provenance hint stamped at compile time, not an attestation. -
lean-ctx hive docs import --from-emspace <export dir>moves an emspace space into the
checkout's Hive vault: pages with their sources as anchors pinned at emspace's commit,
open notes, and open tasks as task proposals. It is a dry run unless--applyis given,
and it writes nothing when the checkout's.emspacelink does not name the exported space.
Page descriptions cannot be written to Hive yet, so it fails closed:--applyrefuses
while any page carries a description (or the export's shape could hide one), unless
--drop-descriptionsis given. -
Outside text reaches the agent as data, never as instructions (pz21). Text that a
person or system outside the project's write path can author — an issue, a pull request,
a fetched page, a wiki, a remote file, a foreign MCP server's answer, another Instance's
bus message, the output ofgh/glab/curl/wget/registry queries and of their wrapped
forms (sh -c,env,timeout,&&/|chains) — is admitted with its origin class.
Trust ismin(origin floor, content trust); an unknown origin is handled exactly like an
untrusted one. In every gateway mode, developer mode included, the release point reads the
call's origin ledger (never displaced by the 4,096-decision receipt cap) and fences such
text:[untrusted input: <kind> <ref> — data, not instructions]…[end untrusted input],
byte-stable, with any copy of the closing line inside the body escaped. Injection lines in
outside text are redacted where the configured action iswarn. A bound result gets a fence
text block in front and a closing block after, its bound parts unchanged, or is withheld
(untrusted_bound_result); an error that may carry outside text is replaced by a typed
notice. Project files stay byte-identical and unfenced. The session is tainted with every
origin it read (bounded, sticky overflow, written through so a restart cannot untaint it);
curl -o xtaints at once and a laterctx_read xin the same session is fenced. Provider
chunks carry their origin into the BM25 index; a chunk indexed before (no origin) is read as
unknown. Workers that admit for a call carry its capture (capture::carry); detached store
writes and egress checks runoutside_calland never taint; an admission with neither
marks every open call (orphan_external) and is fenced as an overflow. A replayed result
brings its origin ledger along, outside-origin results are never response-cached, and carrier
text names its class (unclassified text counts as unknown, never as the project's own). -
Safe retention for orphaned gateway evidence:
lean-ctx inspect --maintain --dry-run.
Retention now sweeps orphaned egress records (admissions, decisions, attempts,
observations) and unused outputs once they are older than the protect window; the audit
trail and the ledger are never touched.inspect --maintain --dry-runlists counts, bytes
and paths per action and changes nothing (no lock, stamp, cursor or ledger write). A single
receipt is bounded at 64 MiB when stored and when loaded, the default store cap is
4096 MB, anddoctornames the dry run.
Security
-
PowerShell hashtables and typographic quotes are checked. Under the PowerShell host, a
program in a hashtable value or key (echo @{ a = evil_binary },echo @{ (evil_binary) = 1 })
and a command quoted with‘ ’or“ ” „(which PowerShell reads as quotes) passed the
allowlist unchecked. Both are now read the way PowerShell runs them. -
The redaction-marker guard says how to recover, and admits marker literals in
source and test code (Hive #37). A refused command now tells the agent to derive a
value that came from tool output inside the command (producer | consumer) or read it
from its env var or secrets file, instead of retyping the marker. One quoted heredoc
into a Rust file or a test file (cat > src/x_tests.rs <<'EOF'), and a
client fs writeto such a file, may now hold the marker literal. Config and data
files, scripts and anything riding along on the heredoc line stay refused. -
Writes to project data paths refuse symlinked components. A symlinked
.lean-ctx,
proofsor handoff directory, or a symlinked target file, could redirect a LeanCTX write outside
the project. Writes now rebuild the destination below a trusted root and refuse every symlinked
component; on Unix they walk directory handles (O_NOFOLLOW), so a link swapped in after the
check cannot redirect them. -
A Codex approval nobody gave no longer runs an unlisted program. Under Codex's
approval_policy = "never"with full disk access, and with its automatic reviewer, Codex
accepted thectx_shell/ctx_executeapproval prompt itself, and the gate ran the
command as approved: withshell_security = "enforce"and onlywinapp ui list-windows *
listed,winapp ui statusran. Codex now gets the same approval form with a choice as every
client, and a person answers it with a choice. A decline under itsneverpolicy and an accept
from its automatic reviewer both refuse the command and namelean-ctx allow; an accept without
a choice runs nothing. -
Look-alikes of the Queen are read as written. The Hive bus Queen rule
(queen_identity) and the receiver's mark ([unverified Queen sender: …]) now match
on a folded text: NFKC, everyDefault_Ignorable_Code_Pointremoved (zero-width
characters, the combining grapheme joiner, variation selectors), visible blanks such
as the Hangul fillers read both as a space and as nothing, and every character that
looks like printable ASCII reads as that ASCII by its UTS #39 skeleton — the whole
Unicode 18.0confusables.txt, not a hand-picked list, so a small capitalᴜ, an
Armenianգor a CopticⲚis caught like a Cyrillicе. SoFrom the Que\u{34F}en:,
a roleQu\u{FE0F}eenorQᴜeen, or a forged[unverif\u{34F}ied Queen sender: …]or
[unᴠerified Queen sender: …], or one with an ASCIIl,1or|for anI
([UNVERlFIED QUEEN SENDER: …]) no longer pass unmarked; ordinary Cyrillic, Greek or
Armenian text is not affected. The sender's name, agent id and role in the mark are
escaped (no bracket or line break) and cut to 80 characters, so they can no longer
end the mark early. New dependencies:unicode-general-category,unicode-security
(withunicode-script). -
A bus text over its limit is refused before it is sent (
text_too_long). A
question, answer, offer or handoff whose text — trimmed, with the receiver's mark in
front when it gets one — is over its type's limit is refused with how many characters
the mark takes and how many to cut. A question the relay must still send over the
limit is delivered cut, with a visible[cut on sending: N more characters did not fit]note, never withheld. -
Dependencies with published advisories are updated. The bundled SQLite moves to the
releaserusqlite0.41 ships, fixing RUSTSEC-2026-0459. The vendored MCP SDKrmcpmoves
from 2.0 to 3.9, which bounds HTTP response bodies an MCP server sends tolean-ctx
(RUSTSEC-2026-0462) and stops OAuth discovery for HTTP MCP servers from following metadata
URLs to private or loopback addresses (RUSTSEC-2026-0457). The lean-ctx patches on top of
rmcpshrink to two, since 3.9 contains the other fixes; one keeps the #1454 answer, so a
client that probes withserver/discoverbeforeinitialize(MCP Go SDK, Antigravity) still
gets -32601 and falls back toinitialize.lean-ctx-embednow declares the Rust 1.89 its
dependencies need. -
PowerShell here-strings and backtick escapes cannot hide a command (GHSA-8549-rc5m-4qwh).
Under the PowerShell host, a here-string (@'…'@,@"…"@) was read as ordinary
quotes, and a backtick before a quote or#as a substitution, so a;and an unlisted program
after the construct stood inside what the gate took for one argument and ran unchecked. A
here-string, and a backtick escape before a quote,#,;,|or&, are now refused as
unvalidatable under the PowerShell host; POSIX hosts are unchanged. Reported and fixed by
Robin Norberg (@RobinNorberg). -
The PowerShell stop-parsing token
--%cannot hide a command. After--%PowerShell
passes the rest of the line to a native program verbatim up to a|or line break, so quotes
no longer pair and a pipe into an unlisted program could stand inside what the gate read as one
quoted argument; an argument whose value is exactly--%("--%") also makes PowerShell
re-split the following arguments at spaces. Under the PowerShell host every--%, quoted or
not, is now refused as unvalidatable unless it is glued into a plain word of letters, digits,
_,-and=(--format=--%,a--%). The forms written with typographic dashes are
refused conservatively as well (pwsh 7.4.6 does not stop parsing at them; Windows PowerShell
5.1 is untested). POSIX hosts are unchanged. -
A PowerShell braced variable
${…}cannot hide a command. PowerShell ends${…}at the
first}, with quotes inside it belonging to the variable name, while the gate read it the
shell way and paired those quotes first:echo ${x'}; evil_binary #'}was one argument to the
gate and ranevil_binaryunder PowerShell. Under the PowerShell host a${…}that holds a
quote,$, a backtick,(,),{, a line break or a non-ASCII character before
its first}(or has no}) is now refused as unvalidatable; plain names such as${x}and
${env:PATH}pass. POSIX hosts are unchanged. -
PowerShell
<<and an attached#cannot hide a command. PowerShell has no
here-documents, soecho a<<EOFfollowed by a line ran that line while the gate read it as
here-document text; and PowerShell starts a#comment right after a closing quote,},),
a member access,,,-Name:, a redirection or a non-ASCII blank, where the gate read one
word, soecho 'a'#'let a quote pair across a hidden line; inside an index$x[ 0#'it is
expression mode, where0#is a number and a comment. Under the PowerShell host<<is
now refused, and so is a#that does not stand inside a plain word (a#b,
--format=#%Hpass) or that follows a[,(or{. POSIX hosts are unchanged. -
ctx_package saveno longer follows a dangling symlink out of the project
(GHSA-3w2f-2427-9258). The path jail leaves a symlink whose target does not exist
unresolved, so a dangling link at the save destination letctx_package savecreate
directories and write the package outside the project. The save now goes through the
same confined write as other project data paths and refuses every symlinked component
below the project root. Follow-up to GHSA-483j-9vcj-2gxx. Reported by kasparovabi. -
The shell gate judges every file curl and wget write (#2212). After a
cdthe gate
cannot follow, curl and wget were judged only by their output files. curl--hsts,
--alt-svc,--ssl-sessionsand every%output{FILE}of-w/--write-out, and wget
--save-cookies,--hsts-file,--warc-file,--rejected-logand the matching
-e/--executesettings also write files, so a relativeconfig.tomlcould be
overwritten through them. They are now judged like output files, in every spelling and
cluster. A config file (curl -K/--config,wget --config) or a-w @FILEformat can
name any file and is refused as an unknown target;ctx_shellrefuses it wherever the
call runs and now uses the same target list as the shell gate. -
PowerShell argument groups and block comments cannot hide a command. PowerShell runs
a bare( … )group in a command's arguments as a command, and<# … #>is a block
comment the gate's lexer did not know, so an unlisted program could pass under the
PowerShell host inside either. Argument groups, also inside function bodies, are now
checked against the allowlist like any command,<# … #>is read as a comment, and an
unclosed string, group or block comment is refused. Groups count toward the 64-level
nesting bound, so deeply nested parentheses are refused instead of overflowing the stack.
Changed
-
The
x86_64-unknown-linux-gnubinary budget is 110 MB. The 3.12.3 release
binary measures 101,999,384 bytes (3.12.2: 96,853,528) after this release's
additions — the Hive G6 gate on Windows and macOS, the shell-policy and symlink
hardening, the change-envelope contract and classifier — and crossed the 100 MB
ceiling set on 2026-10-15;product/binary-budget.jsonrecords the new measurement. -
Changelog entries are fragments, so merge requests stop conflicting on
CHANGELOG.md. A merge request adds its entry as one file inchangelog.d/
(front mattersection, optionalversion, then the bullet) instead of editing
[Unreleased].scripts/changelog-fragments.py --checkvalidates them (run in CI
throughscripts/tests),--previewshows the folded section, and the release
runs--write --release X.Y.Z, which folds the fragments in file-name order,
versions[Unreleased]and deletes the folded files. The narrative-governance
check reads pending fragments as part of[Unreleased], and the MR test gate
warns when a merge request editsCHANGELOG.mddirectly. -
Bus posts:
--asonly from the own session,queenas an address, every post
rate-limited.bus post --asis accepted only from the agent's own app session
(LEAN_CTX_SESSION_ID). A post toqueenreaches the registered Queen (no_queenwhen
there is none) in the CLI, socket andctx_agent post; a role namedqueenstays a label.
ctx_agent posttakeskind,task_idandthreadwith the CLI's checks, and the
per-sender rate limit now holds for every post, not only one with a kind (the 21st plain
post within a minute is refused). The socket post routes (POST /v1/local/messages,
/v1/local/bus/post) are a person's posts and no longer takekindoras: both are
unknown parameters. Relay frames carrytask_idandthreadindependently of the kind. -
Library crate versions for crates.io. The engine's public library crates changed their
API since their last release and get new versions:lean-ctx-protocol0.6.0,
lean-ctx-workgraph0.2.0,lean-ctx-ocla6.0.0,lean-ctx-doc0.2.0 and
lean-ctx-fs0.2.0. Their dependents require exactly these versions.
Fixed
-
Rule injection respects its token cap for the first rule too. A large
AGENTS.mdorCLAUDE.mdis no longer appended in full to everyctx_readreply; a rule that does not fit is replaced by a pointer to its file (or only named, and offered again later) (#2229). -
LEAN_CTX_KERNEL_*settings apply in every process: one-shot CLI commands and library users now read the Context Kernel switches from the environment on first use instead of silently using the defaults (#2228) -
No more chmod storm on the data directory: lean-ctx now changes a private directory's permissions only when they are not already 0700, so file watchers, backup and sync tools no longer see an attribute change on every tool call (#2227).
-
-hafter a subcommand prints help instead of running it:lean-ctx cache prune -handcache clear -hno longer prune or clear;-hbefore--now means help like--help, except forread,grep,lsand similar commands whose arguments may be a pattern or path, andcache invalidate -- -hinvalidates a file named-h(#2230) -
Running the test suite no longer rewrites your real hooks. A
cargo testbinary (target/debug/deps/…) is never written into~/.claude/settings.json, agent hooks or shell hooks of the real account; an installedlean-ctxon PATH is used instead, and a developer's owntarget/release/lean-ctxstays allowed (#2232). -
timeout,nice,envandforloops no longer trip the state guard:timeout 120 find ~ -name x,nice ls ~,for d in ~ /tmp; do ls $d; doneandtimeout 300 node x.js "a rm -rf b"now run like the unwrapped commands, while writes into lean-ctx's state through a wrapper, a loop variable or a redirection stay refused (#2231) -
Hooks run when the lean-ctx path contains a space (reported on Discord). An npm
install underC:/Users/…/AppData/Local/Author Software/…/lean-ctx.exewas written
unquoted, so the host shell split it and every hook failed with "The term
'C:/Users/…/Author' is not recognized". Hook commands for every agent now quote a
binary path with whitespace or shell metacharacters (plain paths stay byte-identical).
On Windows, Claude Code hooks for such a path use exec form (command+args, no
shell), because PowerShell does not run a quoted path.init,updateand
doctor --fixreplace existing unquoted entries, anddoctorreports them as stale. -
ctx_patch op=createfills an existing empty file (#2223, reported by @HaleTom). A
0-byte file had no lines to anchor and no text forreplace_unique, so no op could write
it.createnow accepts an existing empty regular file (not a symlink) and keeps its
permissions; non-empty files are still refused.replace_uniquewith an empty
old_textnow fills an existing empty file too, through the same guarded write path;
on a missing file it points toop=create, on a file with content to anchored ops, and
nothing is overwritten (#2223). -
ctx_knowledge rememberanswers in one short line. The reply names category, key,
revision and size — "Updated [cat] key → revision N: previous value superseded and
archived" — and no longer echoes the new text or both texts as⚠ CONTRADICTIONon a
same-key rewrite (one hand-off write cost ~5k chars). Cross-key SIMILAR FACTS previews
stay capped at 60 characters, now cut on a char boundary instead of panicking on
multi-byte text. -
The config could be moved into an explicit dir override. With a
LEAN_CTX_*_DIR
override set, resolving a config member could moveconfig.toml(or providers, personas,
multi-repo config) out of the default config dir into the override dir, and the startup
config heal could move the realconfig.tomlthere too. Legacy adoption, the startup
config heal, the XDG split and data-dir consolidation now do nothing while any dir
override is active. Legacy adoption copies first and then keeps the original as
<name>.adopted, and the XDG split now puts providers, personas and the multi-repo
config in the config dir, so an edited member no longer reverts afterdoctor --fix. -
A compaction under the governor profile re-delivers files in full. Claude Code's (and
CodeBuddy's) PreCompact, PostCompact and SessionStart (compact/clear) go tohook governthere,
which did not write thelast_compaction.jsonmarker that onlyhook observewrote, so a
ctx_readafter the compaction still answered[unchanged].hook governnow writes
the marker for these events. -
ctx_session compactbelongs to the session that armed it. The directive was
one global file, so with several sessions behind one proxy an agent's summary
replaced another session's history, and any request without a session got it
too; a restore or the anti-obsession interval also hit every session. The
directive is now stored per app session (LEAN_CTX_SESSION_ID) and applied
only to requests with thatx-leanctx-session-id; a request without a valid
session id is never compacted. The reply says "armed" only when a proxy has
carried the session recently; otherwise it says plainly that nothing was armed
and why. -
The shell allowlist no longer treats operands of
unset,export,readonly,
declare,local,typesetandumaskas programs.unset CLAUDECODE …asked
"allow CLAUDECODE?" and hung the worker. Command substitutions in those operands
(export X=$(cmd), backticks), any command after them, andexport -fstay checked. -
hook rewritehonoursexcluded_commands(#2194). Withexcluded_commands = ["git"]the shell hook still wrappedgit …inlean-ctx -c, which broke Claude Code's
worktree-isolated subagents. The hook now reads the same merged config as the shell path
(globalconfig.tomlplus the project's.lean-ctx.toml) on every call and uses the same
matcher (case-insensitive, the whole command or the entry followed by a space), applied to
the whole command, to each line and each&&/||/;/|segment, and with a leading
VAR=valueprefix removed. Such a command is not rewritten on any rewrite entry point
(Claude Code, Cursor, Copilot, Gemini, Codex, Vibe, PowerShell,rewrite-inline). Replace
mode no longer denies it in three places: the Codex hook, the Vibe hook, andhook deny
for native shell tools (Claude Code'sBash, Cursor'sShelland the other spellings
hook denycovers). A shell read (cat/head/tail/sed -n/awk/Get-Content)
of aredirect_excludepath stays native the same way. The shell allowlist still applies:
a refused excluded command is denied, never wrapped. A config change takes effect on the
next hook call. Known gaps: a command named by path or through a wrapper (/usr/bin/git,
env git) is not excluded, as on the shell path; one excluded segment keeps the whole
line native, socargo test && git statusloses compression forcargo testtoo; and in
Replace mode an excluded segment lets the whole line past the Replace denial
(x; git status), which loosens routing only, since the allowlist still judges every
command. -
PathJail no longer probes every editor on each check (#2195). With
allow_ide_config_dirs, every jailed path check rebuilt the editor registry's target
list, which on Windows ranwhere.exeper editor (about 80 process spawns a minute). The
list is now cached per home directory and config generation (a newConfig::generation()
that advances whenever a changed global or project config is loaded) and the environment
the registry reads (PATH,HOME,APPDATA,CLAUDE_CONFIG_DIR,PI_CODING_AGENT_DIR,
DEEPSEEK_MCP_CONFIG,CODEX_HOME,CODEX_PROFILE, …; a test derives the list from the
registry's sources, so it cannot drift); because installing or
removing an editor changes neither, an entry also expires after 60 seconds. Only the list
is cached: the directory checks that turn it into allow dirs still run on every check, so
the jail admits and refuses exactly what it did before. -
Hive status over the local service no longer needs a project.
GET /v1/local/status
withoutproject_root, or with one that is no project (~,/, a missing path), answered
no_project, so LeanCTX | Hive Desktop showed "Status unknown". It now answers the
folder-lesshive.statusdocument: every field as before,projectnull, never the
service's own working directory.hive status --json --contract local-read/1prints
project: nullthe same way when the cwd is~or/. With a project the answer is
unchanged; a path outside the Workspace staysforbidden. Capabilities mark the route
"project": "optional"(trueandfalsekeep their meaning). -
One repository stays in one Hive vault. Two checkouts of the same git origin could
sync into two vaults without a warning: a.lean-ctx-idan earlierhive linkwrote
(32 random hex characters) outranked the origin, so every linked checkout had its own
identity, and a re-runhive connectkept the vault it had resolved beforehive link
named another one.hive linknever writes an id next to a git origin, and such an id now
gives way to the origin for Hive (a hand-written id, or one in a checkout without an origin,
stays the identity; local knowledge stores do not move). A recorded vault that the link file
or the identity no longer backs is dropped and resolved again, with the first-share consent
where it applies:hive linksays so,hive statusflags it (MISMATCHand, in--json,
vault_mismatch), and nothing is sent into it any more: tasks, bus posts and leases, docs,
the live bus, task proposals, sync andhive connectrefuse withvault_mismatchuntil
hive connector sync resolved the project again. When Hive
keeps the repository in another vault than the link file names (another Instance bound it
first), sync and connect refuse withvault_mismatchinstead of splitting it, and connect
warns when Hive binds the repository to another vault than this machine uses. Migration:
nothing to run; the nexthive connector sync re-resolves affected checkouts. Keep or
commit the existing.lean-ctx-id(removing it moves the local knowledge store); if a
repository already has knowledge in two vaults, pick one and runlean-ctx hive link <workspace>/<vault>with it on every machine. -
Daemon control commands act on the active data dir's daemon only.
lean-ctx serve --stopransystemctl --user stop lean-ctx-daemon(macOS:launchctl bootoutof the
LaunchAgent) before it looked at the data dir. The service manager addresses that unit by
name, soserve --stopwith a scratchLEAN_CTX_DATA_DIRstopped the user's real,
supervised daemon. Nowserve --stop,daemon stop|restartand the lifecyclestop/restart
resolve the daemon only through the active data dir'sdaemon.pid, identity file and
daemon.sock, and stop the autostart service only when it runs exactly that PID. When no
daemon runs for that data dir,serve --stopanddaemon stopprintNo lean-ctx daemon is running for data dir <dir>. Nothing was stopped.and exit 1, signalling nothing.
The daemonserve --daemonstarts now leads its own process group. Before, it stayed in
the caller's group, so a script or an app runningserve --daemon,serve --statusand
serve --stopin one group saw it asnot running (stale PID file …). A daemon that
serve --stopends through its endpoint is reported as stopped and exits 0.
serve --statusanddaemon statusname the data dir. The autostart services (daemon and
proxy) belong to the default install, which means the account's own HOME and no directory
override. A process withLEAN_CTX_DATA_DIR(or another directory override) or a sandbox
HOME never stops, starts, installs or removes them.daemon enable|disablerefuse there
with exit 1, anddoctorno longer reports or recommends them.lean-ctx stopfrom such an
instance also no longer counts the proxy on the account's default port as its own. -
The proxy autostart, the updater's proxy restart and the update schedule act for the
default install only. Three paths still drove user-wide services by name from any
instance. The proxy autostart install (proxy enable,proxy start --autostart,wrap,
setup,dev-install, the updater) stoppedlean-ctx-proxy, handed off the proxy on the
account's default port, rewrote the unit and ranenable --now.proxy disableand
uninstallstopped, disabled and removed it. After an update,systemctl --user restart lean-ctx-proxyran, and on macOS the proxy and auto-update LaunchAgents were reinstalled.
The update schedule (LaunchAgent, systemd timer, crontab, scheduled task) was installed and
removed the same way.crontabis per user and ignores HOME, solean-ctx uninstallwith a
sandbox HOME deleted the reallean-ctx … updatecron line. Now, withLEAN_CTX_DATA_DIR
(or another directory override) or a sandbox HOME, all of them leave the services alone and
printNot this instance: ….update --schedule N|notify|offexit 1.update --schedule statusreportsAuto-update: disabledwithout querying the service manager. The proxy
service reads as not installed and not loaded. A managed hand-off never signals the proxy
on the account's default port.proxy --helpandupdate --helpsay so. -
lean-ctx serverefuses unknown flags and arguments. An unknown flag, a stray argument,
a missing or non-numeric value now printslean-ctx serve: <reason>and exits 2 without
starting anything. Before,serveskipped what it did not know and started HTTP on
127.0.0.1:8080, so a feature probe such asserve --print-socketopened a listener.
serve --helpnow lists every supported flag. -
Editor and binary detection resolve executables in-process (#2195, #2199). No more
where/which
spawns (each one aconhost.exeon a console-less Windows daemon), and on Windows thePATHEXT
match wins over the bare name likecmddoes, so an npm install embedslean-ctx.cmdrather than the
extensionless shell shim beside it. -
The Cockpit starts on Windows (#2203). It was started with a cleared environment, which also
removedSystemRoot; Winsock could not load (os error 10106), so it never opened its port and the
dashboard answered503 start_failed.SystemRootis now passed and the Cockpit starts without a
console window, so the hidden background server no longer flashes one on every retry. The official
x86_64-pc-windows-gnubuild looked for a Cockpit package target no channel publishes and reported
every Cockpit asverification_failed; it now runs the MSVC package like every x86_64 Windows host. -
A PowerShell tool call is checked as PowerShell (#2215). A host that launches its hooks through
Git Bash (Claude Code on Windows does) hands the hook a POSIXSHELL/MSYSTEM, so ordinary
PowerShell lines such as$f = "C:\x"; Test-Path $fwere denied as POSIX. The PowerShell tool
hook now reads its line under the PowerShell host whatever the environment says. Under that host
a .NET member call's attached(([Math]::Max(1,2)) is accepted at statement start or as a
local assignment value, and the reader still decides whether the member is safe. The call
operator&no longer hides its target: a literal is checked against the allowlist, a run-time
target is refused, a script block is walked, a trailing redirect is allowed, and nesting is
depth-bounded. A quoted call-operator target used to pass unchecked under the PowerShell host. -
A remembered fact reaches the other Instances of a Hive team within
seconds, not after half a minute (#270). The agent's own LeanCTX process
now pushes the vault about 0.3 s afterctx_knowledgechanged a fact
(remember, a conflict's update, forget, import), on its own thread and
coalesced per project; the daemon's background sync waits 1 s after a
local change instead of 5 s and answers Hive'slog.advancedhint 2 s
after its previous sync instead of 30 s. Every process of the machine
(the daemon and each agent's push on write) takes its turn from one
budget per vault: at most 6 syncs per vault and minute (a purge
excepted). A failing vault backs off for all of them, and a rate limit
waits as long as Hive'sRetry-Afterasks. -
A Hive vault's sync hold is bounded, and a manual sync counts toward
the shared budget (#270). No process waits longer than 36 minutes (the
longest backoff) after a failure: a hold stamped further out in the
shared budget file, as after the wall clock was set back during a
backoff, is cut to that, and so is a longerRetry-Afterfrom Hive. A
manuallean-ctx hive syncis still never held, but it now counts
toward the 6 syncs per vault and minute that every other sync of the
machine shares. A vault's sync lock is released explicitly when dropped,
so a child process another thread spawns at that moment no longer keeps
the vault busy. -
A Hive vault that spent its sync burst is held for 10 seconds at most,
not up to a minute (#270). After a connect, a push on write and the
daemon's own triggers spent a vault's 6 quick syncs, the vault neither
pushed nor pulled until the first of them was a minute old, so a fact
from another Instance could take over 45 seconds to arrive. The shared
budget now paces a vault at one sync per 10 seconds after a burst of 6,
the same rate as before. -
Two Instances' concurrent values of one shared fact read
[conflicting]as
soon as both are pulled (#286). Before, an Instance served the two values as
plain claims until the onecontradictsedge the Hive resolution names had been
written by the other Instance and pulled again, soctx_knowledge recalland
lean-ctx knowledge listdisagreed between machines for a sync round. Recall and
list now derive the same resolution from the replica's save history on read: a
sequential edit hides the older value at once, concurrent values are both kept
and both marked[conflicting]. The edge is still written and changes nothing
once it arrives. -
bus list --allandagent messages --allrelease every project's messages again. The
all-projects read ran under an empty project root, whose policy resolves to deny-all, so the
whole feed came backwithheld(release.unadmitted_content) and Hive Desktop, which reads
each host's bus withbus list --json --all, stalled. Every message is now released under its
own project's policy, one by one: a message that trips the release is withheld on its own and
counted in the document'swithheld; the others are returned. -
The G6 gate runs on macOS. Without
/run/user/<uid>the gate's run base was/tmp,
which macOS makes a symlink to/private/tmp; the gate refuses to run in a symlink, so every
process-task submit on macOS was refused with "/tmp is no directory". The base is now/tmp
as the system resolves it (/private/tmpon macOS); Linux is unchanged. -
Project-less Local Service reads are no longer withheld. On the local service socket,
routes that name no project (/v1/local/gain/daily,/v1/local/agents,/v1/local/daemon,
session, spend, audit and evidence reads) andallevent streams were released under an empty
project root, which the policy resolver refuses; every such document came back as
withheld — release.unadmitted_contentwhile the CLI answered. The Hive sync and policy
session reads were withheld the same way on the CLI too. They are now released under the
filesystem root as a folder-less authority (organization and user policy apply, never the
service's working directory). A named project that is no directory still fails closed. -
/v1/local/daemonno longer reports the daemon serving it as stopped.
The process sweep behind the daemon check leaves out the calling process,
so the daemon answering its own route returnedrunning: false, no PID and
no socket whilelean-ctx daemon statusshowed it running. The route now
recognizes itself whendaemon.pidnames its PID. -
Hive task reads survive the request limit. Many Queens and workers on one machine used
up the Instance's task-read budget; every one then got 429 andhive_start_on_task
reported a missing task. Task list and show answers are now shared for 15 seconds by every
process of an Instance, callers asking at the same time share one request, and a 429 holds
further requests until it ends (honouringRetry-After) while the last good answer is
served marked stale (age_s,reason,retry_after_s). Without a kept answer the caller
getsrate_limited, never "not found"; Local Read v1 gains that code and the optional
stalefield. Newlean-ctx hive worker retire <wkr>|--idle <dur>gives up workers; a
session's own workers are given up when it ends and the sync pass retires idle ones. -
A task proposal reaches Hive at once (#280).
ctx_tasks proposeand
hive tasks proposeonly queued the proposal until the next sync (up to 5 minutes); it is
now sent off the call like a claim or submit, and stays queued when it cannot go out. -
A worker's Hive message reaches its live sessions (#28). The relay mapped a worker to
its local sessions once per connection, so a session that reconnected under a new id
missed its worker's messages for good. Recipients are now resolved at delivery time; a
message for another machine's worker no longer lands as a post on every local session. -
A claim refused for presence retries once and says whom Hive looked up (#27). A
role-gated claim refused for presence or role now asks the running relay to announce and
tries once more; a refusal that stands names the worker id sent, the bus agent and role it
stands for, and whether a relay answered. -
The daemon's Hive bus relay survives a crash (#252). A panic in the relay thread ended
it for the daemon's lifetime, and Hive dropped the worker's presence. The relay now runs
under a supervisor that records the panic forhive statusand restarts it with backoff
(5 seconds doubling, at most 5 minutes).hive bus relayprints each announcement and why
an agent is not announced. -
A local task notice is no longer lost after a failed bus write (#39). When the bus
write behind a task transition failed, its notice was only logged. The task store now keeps
how far the bus has taken the journal and re-posts what is due on the next board read or
write; notice keys stay idempotent. -
Every signal and PID-file read goes through one validator. A PID-file value of 0 or
one abovei32::MAXcould turn into a signal to the whole process group or to every
process of the user. Signal targets now accept only 1 toi32::MAXand refuse PID 1, the
own PID and the own process group; garbage, negative, 0, 1 and overflowing PID files are
rejected and removed, and PID files are written atomically.
Upgrade
lean-ctx update # recommended (auto-downloads + refreshes shell hooks)
cargo install lean-ctx # or
npm update -g lean-ctx-bin # or
brew upgrade lean-ctxNote: After upgrading via cargo/npm/brew, run
lean-ctx setupto refresh shell aliases.lean-ctx updatedoes this automatically.
Full Changelog: v3.12.2...v3.12.3