Skip to content

v3.12.3

Choose a tag to compare

@github-actions github-actions released this 11 Nov 22:06
· 9 commits to main since this release
013ddb1

Added

  • Process v1 G6 and checker ≠ author on Hive tasks. Submitting a task that carries
    process now runs the G6 gate in the Instance: the locked tests must be unchanged against
    spec_commit and 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 without process keep 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
    of rust/crates/lean-ctx-hive/src/tasks/process.rs.
    G6 also asks the compiler which locked tests exist at spec_commit (one extra build in a
    private copy; no test of spec_commit runs), 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 in tasks/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, plus unparsable) and returns a leanctx.process.tripwires/v1 report; 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_ID set 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's self_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 different wkr_, so let it expire or release it and claim again.

  • Meta Muse Code agent target (#2198). lean-ctx init --agent muse and setup register the
    lean-ctx MCP server in $XDG_CONFIG_HOME/muse/settings.json (default
    ~/.config/muse/settings.json). The writer adds the mandatory "schema_version": 1 when it is
    missing, keeps every other key and server, and merges into the root the file already uses —
    canonical mcpServers or legacy mcp_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 the lean-ctx entry, and doctor checks the entry. Muse Code is MCP-only: its
    PreToolUse output schema is closed and an allow never skips approval, so shell rewrites would
    add prompts. Guidance reaches it through the project AGENTS.md it 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
    PATCH at the task's fields_version, read again and resent once on stale_base), from
    Hive Desktop over /v1/local/hive/tasks/{n}/priority|labels (tasks.ack), and by a Queen
    session with ctx_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 marked partial (JSON partial: true, a (partial: …) line in text). JSON
    rows carry priority, labels and fields_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 post and
    send refuse an agent's message, with a named rule and nothing rewritten, when it
    speaks for a person (on_behalf_of, 400 invalid_field: the on_behalf_of field 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, progress and finding posts are not checked.
    The relay applies the same rules to older queued posts and keeps a post that breaks
    them local (counted as withheld). Publishes the Hive refuses are remembered per sender
    in the new bus/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, env LEAN_CTX_HIVE_QUEEN_IDENTITY, which wins) the default warn
    passes a sender presenting as the Queen (role queen, 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 new bus/queen-warnings.json; enforce refuses it, and any other value
    counts as enforce. Switch to enforce only once queen-sessions.json lists 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); a deny_write class refuses (deny_write:<class>); the rights
    file itself is never written (rights_file); denied_tools refuses a tool, aliases
    included (denied_tools). It applies to ctx_shell/shell (a command whose writes
    cannot be judged is refused: unanalysable), ctx_execute, LeanCTX's own writes, the new
    lean-ctx hook rights for native Edit/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/call field rightsFile (local
    socket only, else 400 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/local route of the daemon socket,
    released with one receipt for the bytes sent, and listed in one capabilities document
    with every verb and the transports that answer it (docs/contracts/local-read-v1.md,
    local-service-v1.md): session stats and cost per LEAN_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.sessions and
    policy.session, CLI-only before, are served on the daemon socket at /v1/local/hive/sync,
    /v1/local/hive/policy/sessions and /v1/local/hive/policy/sessions/{id}, released through
    the same release point (one receipt) and listed in capabilities. policy.sessions
    installed adds vaults: one row per vault the installed policy reaches on this machine
    (vault_id, ns, name, linked roots) and which policy applies (vault, default, or
    unverified when 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_NAME names an agent session; presence list
    rows carry the session name, agent host, Instance (machine) and project with its vault;
    hive presence rows carry the names a Hive relays with a presence.

  • A person's bus post can leave the machine. bus post answers cloud (queued,
    local_only, withheld or held, with the reason); a post to a vault bus is published as the
    person once the Hive accepts a person's publish (hello.ack feature person_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=amend and
    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 (update kind: amendment, amended_from, amended_to). On a
    vault it needs the Hive route POST /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 setup and lean-ctx hive connect now install the daemon as a supervised service
    that starts at login and restarts after a crash: the systemd user unit lean-ctx-daemon
    on Linux (loginctl enable-linger <user> keeps it running on a headless machine while
    logged out), the LaunchAgent com.leanctx.daemon on macOS. This changes an upgrade: the
    next setup or hive connect installs 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
    (bus log.advanced, trust.advanced), and otherwise every [hive] pull_interval_minutes
    (default 5). Only vaults already shared from this machine sync. lean-ctx doctor reports
    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 sync still works and syncs
    the current project at once. Details: docs/guides/hive-background-sync.md.

  • The build says where it came from. lean-ctx --version names the build kind after the
    version: official only for the upstream release workflow, otherwise (dogfood <sha>) for
    the promoted Instance state, (dev <sha>) for any other checkout (, dirty with local
    changes) or (source) for a tree without git. The capabilities document carries a
    build block (kind, commit, dirty, official), and lean-ctx doctor shows 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 --apply is given,
    and it writes nothing when the checkout's .emspace link does not name the exported space.
    Page descriptions cannot be written to Hive yet, so it fails closed: --apply refuses
    while any page carries a description (or the export's shape could hide one), unless
    --drop-descriptions is 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 of gh/glab/curl/wget/registry queries and of their wrapped
    forms (sh -c, env, timeout, &&/| chains) — is admitted with its origin class.
    Trust is min(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 is warn. 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 x taints at once and a later ctx_read x in 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 run outside_call and 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-run lists 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, and doctor names 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 write to 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,
    proofs or 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 the ctx_shell / ctx_execute approval prompt itself, and the gate ran the
    command as approved: with shell_security = "enforce" and only winapp ui list-windows *
    listed, winapp ui status ran. Codex now gets the same approval form with a choice as every
    client, and a person answers it with a choice. A decline under its never policy and an accept
    from its automatic reviewer both refuse the command and name lean-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, every Default_Ignorable_Code_Point removed (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.0 confusables.txt, not a hand-picked list, so a small capital ᴜ, an
    Armenian գ or a Coptic Ⲛ is caught like a Cyrillic е. So From the Que\u{34F}en:,
    a role Qu\u{FE0F}een or Qᴜeen, or a forged [unverif\u{34F}ied Queen sender: …] or
    [unᴠerified Queen sender: …], or one with an ASCII l, 1 or | for an I
    ([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
    (with unicode-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
    release rusqlite 0.41 ships, fixing RUSTSEC-2026-0459. The vendored MCP SDK rmcp moves
    from 2.0 to 3.9, which bounds HTTP response bodies an MCP server sends to lean-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
    rmcp shrink to two, since 3.9 contains the other fixes; one keeps the #1454 answer, so a
    client that probes with server/discover before initialize (MCP Go SDK, Antigravity) still
    gets -32601 and falls back to initialize. lean-ctx-embed now 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 ran evil_binary under 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, so echo a<<EOF followed 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, so echo 'a'#' let a quote pair across a hidden line; inside an index $x[ 0#' it is
    expression mode, where 0# 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=#%H pass) or that follows a [, ( or {. POSIX hosts are unchanged.

  • ctx_package save no 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 let ctx_package save create
    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 cd the gate
    cannot follow, curl and wget were judged only by their output files. curl --hsts,
    --alt-svc, --ssl-sessions and every %output{FILE} of -w/--write-out, and wget
    --save-cookies, --hsts-file, --warc-file, --rejected-log and the matching
    -e/--execute settings also write files, so a relative config.toml could 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 @FILE format can
    name any file and is refused as an unknown target; ctx_shell refuses 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-gnu binary 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.json records the new measurement.

  • Changelog entries are fragments, so merge requests stop conflicting on
    CHANGELOG.md.
    A merge request adds its entry as one file in changelog.d/
    (front matter section, optional version, then the bullet) instead of editing
    [Unreleased]. scripts/changelog-fragments.py --check validates them (run in CI
    through scripts/tests), --preview shows 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 edits CHANGELOG.md directly.

  • Bus posts: --as only from the own session, queen as an address, every post
    rate-limited.
    bus post --as is accepted only from the agent's own app session
    (LEAN_CTX_SESSION_ID). A post to queen reaches the registered Queen (no_queen when
    there is none) in the CLI, socket and ctx_agent post; a role named queen stays a label.
    ctx_agent post takes kind, task_id and thread with 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 take kind or as: both are
    unknown parameters. Relay frames carry task_id and thread independently 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-protocol 0.6.0,
    lean-ctx-workgraph 0.2.0, lean-ctx-ocla 6.0.0, lean-ctx-doc 0.2.0 and
    lean-ctx-fs 0.2.0. Their dependents require exactly these versions.

Fixed

  • Rule injection respects its token cap for the first rule too. A large AGENTS.md or CLAUDE.md is no longer appended in full to every ctx_read reply; 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).

  • -h after a subcommand prints help instead of running it: lean-ctx cache prune -h and cache clear -h no longer prune or clear; -h before -- now means help like --help, except for read, grep, ls and similar commands whose arguments may be a pattern or path, and cache invalidate -- -h invalidates a file named -h (#2230)

  • Running the test suite no longer rewrites your real hooks. A cargo test binary (target/debug/deps/…) is never written into ~/.claude/settings.json, agent hooks or shell hooks of the real account; an installed lean-ctx on PATH is used instead, and a developer's own target/release/lean-ctx stays allowed (#2232).

  • timeout, nice, env and for loops no longer trip the state guard: timeout 120 find ~ -name x, nice ls ~, for d in ~ /tmp; do ls $d; done and timeout 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 under C:/Users/…/AppData/Local/Author Software/…/lean-ctx.exe was 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, update and
    doctor --fix replace existing unquoted entries, and doctor reports them as stale.

  • ctx_patch op=create fills an existing empty file (#2223, reported by @HaleTom). A
    0-byte file had no lines to anchor and no text for replace_unique, so no op could write
    it. create now accepts an existing empty regular file (not a symlink) and keeps its
    permissions; non-empty files are still refused. replace_unique with an empty
    old_text now fills an existing empty file too, through the same guarded write path;
    on a missing file it points to op=create, on a file with content to anchored ops, and
    nothing is overwritten (#2223).

  • ctx_knowledge remember answers 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 ⚠ CONTRADICTION on 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 move config.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 real config.toml there 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 after doctor --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 to hook govern there,
    which did not write the last_compaction.json marker that only hook observe wrote, so a
    ctx_read after the compaction still answered [unchanged]. hook govern now writes
    the marker for these events.

  • ctx_session compact belongs 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 that x-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, typeset and umask as programs.
    unset CLAUDECODE … asked
    "allow CLAUDECODE?" and hung the worker. Command substitutions in those operands
    (export X=$(cmd), backticks), any command after them, and export -f stay checked.

  • hook rewrite honours excluded_commands (#2194). With excluded_commands = ["git"] the shell hook still wrapped git … in lean-ctx -c, which broke Claude Code's
    worktree-isolated subagents. The hook now reads the same merged config as the shell path
    (global config.toml plus 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=value prefix 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, and hook deny
    for native shell tools (Claude Code's Bash, Cursor's Shell and the other spellings
    hook deny covers). A shell read (cat/head/tail/sed -n/awk/Get-Content)
    of a redirect_exclude path 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, so cargo test && git status loses compression for cargo test too; 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 ran where.exe per editor (about 80 process spawns a minute). The
    list is now cached per home directory and config generation (a new Config::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
    without project_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-less hive.status document: every field as before, project null, never the
    service's own working directory. hive status --json --contract local-read/1 prints
    project: null the same way when the cwd is ~ or /. With a project the answer is
    unchanged; a path outside the Workspace stays forbidden. Capabilities mark the route
    "project": "optional" (true and false keep 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-id an earlier hive link wrote
    (32 random hex characters) outranked the origin, so every linked checkout had its own
    identity, and a re-run hive connect kept the vault it had resolved before hive link
    named another one. hive link never 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 link says so, hive status flags it (MISMATCH and, in --json,
    vault_mismatch), and nothing is sent into it any more: tasks, bus posts and leases, docs,
    the live bus, task proposals, sync and hive connect refuse with vault_mismatch until
    hive connect or 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 with vault_mismatch instead of splitting it, and connect
    warns when Hive binds the repository to another vault than this machine uses. Migration:
    nothing to run; the next hive connect or 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 run lean-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 --stop ran systemctl --user stop lean-ctx-daemon (macOS: launchctl bootout of the
    LaunchAgent) before it looked at the data dir. The service manager addresses that unit by
    name, so serve --stop with a scratch LEAN_CTX_DATA_DIR stopped the user's real,
    supervised daemon. Now serve --stop, daemon stop|restart and the lifecycle stop/restart
    resolve the daemon only through the active data dir's daemon.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 --stop and daemon stop print No lean-ctx daemon is running for data dir <dir>. Nothing was stopped. and exit 1, signalling nothing.
    The daemon serve --daemon starts now leads its own process group. Before, it stayed in
    the caller's group, so a script or an app running serve --daemon, serve --status and
    serve --stop in one group saw it as not running (stale PID file …). A daemon that
    serve --stop ends through its endpoint is reported as stopped and exits 0.
    serve --status and daemon status name 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 with LEAN_CTX_DATA_DIR (or another directory override) or a sandbox
    HOME never stops, starts, installs or removes them. daemon enable|disable refuse there
    with exit 1, and doctor no longer reports or recommends them. lean-ctx stop from 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) stopped lean-ctx-proxy, handed off the proxy on the
    account's default port, rewrote the unit and ran enable --now. proxy disable and
    uninstall stopped, disabled and removed it. After an update, systemctl --user restart lean-ctx-proxy ran, 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. crontab is per user and ignores HOME, so lean-ctx uninstall with a
    sandbox HOME deleted the real lean-ctx … update cron line. Now, with LEAN_CTX_DATA_DIR
    (or another directory override) or a sandbox HOME, all of them leave the services alone and
    print Not this instance: …. update --schedule N|notify|off exit 1. update --schedule status reports Auto-update: disabled without 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 --help and update --help say so.

  • lean-ctx serve refuses unknown flags and arguments. An unknown flag, a stray argument,
    a missing or non-numeric value now prints lean-ctx serve: <reason> and exits 2 without
    starting anything. Before, serve skipped what it did not know and started HTTP on
    127.0.0.1:8080, so a feature probe such as serve --print-socket opened a listener.
    serve --help now lists every supported flag.

  • Editor and binary detection resolve executables in-process (#2195, #2199). No more where/which
    spawns (each one a conhost.exe on a console-less Windows daemon), and on Windows the PATHEXT
    match wins over the bare name like cmd does, so an npm install embeds lean-ctx.cmd rather than the
    extensionless shell shim beside it.

  • The Cockpit starts on Windows (#2203). It was started with a cleared environment, which also
    removed SystemRoot; Winsock could not load (os error 10106), so it never opened its port and the
    dashboard answered 503 start_failed. SystemRoot is 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-gnu build looked for a Cockpit package target no channel publishes and reported
    every Cockpit as verification_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 POSIX SHELL/MSYSTEM, so ordinary
    PowerShell lines such as $f = "C:\x"; Test-Path $f were 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 after ctx_knowledge changed 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's log.advanced hint 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's Retry-After asks.

  • 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 longer Retry-After from Hive. A
    manual lean-ctx hive sync is 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 one contradicts edge the Hive resolution names had been
    written by the other Instance and pulled again, so ctx_knowledge recall and
    lean-ctx knowledge list disagreed 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 --all and agent messages --all release 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 back withheld (release.unadmitted_content) and Hive Desktop, which reads
    each host's bus with bus 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's withheld; 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/tmp on 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) and all event streams were released under an empty
    project root, which the policy resolver refuses; every such document came back as
    withheld — release.unadmitted_content while 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/daemon no 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 returned running: false, no PID and
    no socket while lean-ctx daemon status showed it running. The route now
    recognizes itself when daemon.pid names 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 and hive_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 (honouring Retry-After) while the last good answer is
    served marked stale (age_s, reason, retry_after_s). Without a kept answer the caller
    gets rate_limited, never "not found"; Local Read v1 gains that code and the optional
    stale field. New lean-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 propose and
    hive tasks propose only 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 for hive status and restarts it with backoff
    (5 seconds doubling, at most 5 minutes). hive bus relay prints 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 above i32::MAX could turn into a signal to the whole process group or to every
    process of the user. Signal targets now accept only 1 to i32::MAX and 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-ctx

Note: After upgrading via cargo/npm/brew, run lean-ctx setup to refresh shell aliases. lean-ctx update does this automatically.

Full Changelog: v3.12.2...v3.12.3