HZR 0.3.8

HZR 0.3.8 — CLI clarity and workspace-aware diagnostics

HZR 0.3.8 improves day-to-day operator visibility without changing the honest-accounting or
bounded-output contracts from 0.3.7. The CLI explains itself better, doctor surfaces actionable
next steps and index readiness, MCP registrations pin to the selected workspace, and project-scoped
provider receipts can be matched to a workspace filter in hzr stats.

The release also adds non-destructive update discovery, a first-class activation status command,
and documentation that matches the current memory hygiene surface.

What changed

• Root hzr --help groups commands (Setup, Runtime, Search & Memory, Agent tools, Distribution,
  Legacy), fills global and common flag help, adds an Examples footer, and applies light HZR orange
  styling.
• High-traffic subcommands (update, stats, enable/disable, doctor, agent, mcp,
  memory leaves) gain long_about text and Examples footers.
• hzr update --check reports whether a newer GitHub release is available without downloading or
  installing. Exit 0 when the check succeeds; non-zero only on failure.
• hzr activation status lists project-only activation mode and enabled workspace roots in human
  and --json form.
• hzr install and hzr mcp config --apply pin MCP registrations with
  mcp serve --workspace <dir> so Desktop and Codex memory are not bound to /.
• hzr doctor warns when Claude Code has no HZR MCP registration and prints the
  claude mcp add remediation.
• hzr doctor human output separates permanent host limits (*_global_codec) as NOTE and lists
  actionable remediations under Next actions:. The JSON schema is unchanged.
• hzr doctor reports index_readiness when the semantic index is missing or not yet warm, with
  remediation to hzr index init or wait for the hzrd watcher.
• Provider usage receipts may carry a workspace project_path. hzr stats --workspace labels
  matching receipts project_matched and omits older unscoped rows from project provider totals;
  the global lifetime view still includes every receipt. Estimated savings remain separate from
  billed provider counters.
• hzr stats always shows the MCP channel in coverage, including mcp=0 when there was no MCP
  traffic.
• README and known-gap text no longer claim that memory forget, update, or prune are absent. The
  basic command list now documents hzr memory forget|update|prune alongside recall, store, and
  status, plus enable/disable where relevant.

Upgrade impact

No ledger, index, memory, or activation rewrite is required. Existing MCP registrations are not
mutated automatically; re-run hzr install or hzr mcp config --apply when you want workspace-pinned
registrations. Provider receipts written before this release remain global-only in project-scoped
stats until new scoped receipts arrive.

Upgrade and verify with:

hzr update
hzr --version
hzr activation status
hzr doctor --workspace .
hzr stats

Restart already-open agent sessions after upgrading so they reload managed hook and MCP contracts.

Verification

The release was checked with:

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets --all-features
scripts/verify-fork-core.sh --test
cd integrations/caveman-code && npm ci --ignore-scripts && node --test bridge.test.mjs
cd visualizer && bun run typecheck && bun test
scripts/smoke-install.sh /path/to/hzr.tar.gz /path/to/SHA256SUMS

The fork-core gate passed 1717 tests with one intentionally ignored test and matched the reviewed
141-warning inherited Clippy ratchet. The packaged smoke passed clean installation, project-only
activation, same-version re-attestation, tamper rejection, and upgrade/rollback checks. Provider-backed
benchmarks were not regenerated because this release changes CLI visibility and workspace attribution,
not model fidelity or billed-token measurement.

HZR 0.3.7

HZR 0.3.7 — Honest accounting and bounded output

HZR 0.3.7 makes the local reduction estimate state exactly which observed traffic it covers.
MCP calls, hook-routed CLI work, native host file tools, and inherited-stdio passthrough now have
explicit accounting routes. Native or unmeasurable operations remain visible without receiving
invented token counts or savings credit, and provider-billed usage remains a separate receipt.

The release also makes every bounded result explain its bound and recovery path. Search reports the
mode that actually ran, context candidates identify enclosing symbols when possible, and long
installer, daemon, MCP, and agent operations emit progress or remain bounded by a timeout.

What changed

• Operation rows carry typed channel, measurement, and route values. hzr stats
  reports the measured coverage share, explicitly unmeasured bypasses, daemon-unavailable gaps,
  and the hook_cli / mcp / native_host split.
• Claude receives a failure-silent PostToolUse observer for native Read, Grep, Glob,
  Edit, and Write. It sizes the serialized response, stores no tool content, changes no
  result, and grants no savings credit.
• Every successful MCP tool produces one neutral accounting row. Validation failures produce no
  success row, and an accounting write lost with the daemon unavailable becomes a visible gap.
• Inherited-stdio passthrough is explicitly unmeasured instead of a misleading zero-token
  delivery. Captured RAW output remains a neutral baseline with equal input/output estimates.
• Bounded and ranged reads report file totals, omitted spans, and shell-safe recovery commands.
  Long-line shortening names --level none; memory exploration reports N of M shown and
  points to --detail verbose.
• Memory recall exposes total_matches; bounded context memory names omitted bytes and the
  record id; search responses expose next_step.
• Search text and structured output always report effective mode, fallback reason, and scan
  diagnostics, including zero-hit results. Exact mode preserves trailing whitespace and is
  explicitly per-line.
• Search candidates use symbol outlines and line spans to resolve the smallest enclosing symbol.
  Every unresolved symbol carries a typed reason, and aggregate outline failures are warnings.
• MCP output schemas declare their nested properties and required fields and are checked against
  representative structured content.
• Installer and bundle downloads show progress outside a TTY and have an overall timeout. MCP
  search/planning sends progress notifications; foreground hzrd and long agent runs emit
  liveness output.
• Public symlink swaps use one portable helper. Re-running hzr install --force with identical
  bundle bytes preserves the current-based public symlinks.
• The dashboard separates optimized, measured RAW, native-observed, and unmeasured operations.

Upgrade impact

The ledger schema is migrated additively on first write; existing operation rows retain their
previous measured CLI interpretation. Indexes, memory records, project activation, and provider
receipts are not rewritten.

A normal install adds the native PostToolUse observer to HZR's marker-owned Claude hook entries.
Unrelated settings and hooks remain preserved by the existing transactional installer. In
project-only mode, the observer follows the same selected-workspace activation policy.

Upgrade and verify with:

hzr update
hzr --version
hzr hooks status
hzr stats
hzr doctor --workspace .

Restart already-open agent sessions after upgrading so they reload the managed hook and MCP
contracts.

Verification

The release was checked with:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-targets --all-features
scripts/verify-fork-core.sh --test
cd visualizer && bun run typecheck && bun test
scripts/smoke-install.sh /path/to/hzr.tar.gz /path/to/SHA256SUMS

The fork-core gate passed 1717 tests with one intentionally ignored test and matched the reviewed
141-warning inherited Clippy ratchet. The packaged smoke passed clean installation, project-only
activation, same-version re-attestation, tamper rejection, and upgrade/rollback checks. It also
verifies that doctor recognizes the canonical dispatcher, SessionStart initializer, and
PostToolUse observer. Provider-backed benchmarks were not regenerated because this release
changes coverage and output contracts, not model fidelity or billed-token measurement.

HZR 0.3.6

HZR 0.3.6 — Reliable notifications and resilient index startup

HZR 0.3.6 fixes the path that tells users and agents a newer published version exists. The updater
itself already downloaded, verified, and atomically installed release bundles correctly; discovery
was unreliable because a pre-release “nothing newer” result stayed cached for 24 hours and only one
agent surface invoked the check.

It also restores canonical search in repositories that still contain dormant nested .grepai
directories created by older grepai/RTK invocations. Those stores remain preserved and visible to
diagnostics, but no longer turn a hygiene finding into a search outage.

No update is installed automatically. HZR reports availability and waits for explicit approval.

What changed

• A check that finds no newer version expires after one hour instead of 24 hours. A release
  published after an earlier same-day check is therefore discovered within the next hourly window.
• A known newer version remains cached for 24 hours, avoiding unnecessary GitHub API traffic while
  keeping the notice available to later sessions.
• Claude's managed SessionStart hook returns structured output with both systemMessage for the
  visible interface and additionalContext for the model.
• Codex checks during the mandatory installed HZR.md bootstrap. The update notice is written
  separately from fork-core stdout, so an exact contract read remains exact.
• Agent-facing notices explicitly require telling the user once and prohibit running hzr update
  without approval.
• Network errors remain silent and fail-open: workspace initialization and tool execution continue.
• A dormant nested .grepai is now a non-blocking doctor warning. HZR takes only the canonical
  owner lock, launches only the canonical watcher, and leaves every nested byte untouched.
• A nested index.gob.lock held by an active legacy writer is still a hard error, preventing two
  grepai writers from running against one repository.
• Explicit migration remains fail-closed when several stores make the intended source ambiguous;
  this availability fix does not guess, merge, delete, or silently archive user data.

Why 0.3.5 could stay silent

If HZR 0.3.5 checked GitHub before a release was published, it cached latest_version: null for a
full day. Every session in that interval classified the cache as current and skipped the network.
In addition, plain Claude SessionStart stdout entered model context but was not a guaranteed visible
user notification, while Codex's bootstrap did not call the update path at all.

Upgrade impact

The upgrade does not rewrite indexes, memory, ledger rows, or project activation. Dormant nested
stores remain in place until an operator deliberately handles them. The installer
rewires the marker-owned Claude SessionStart command to request structured hook output and preserves
unrelated hooks and settings through the existing transactional backup and compare-and-swap path.

Upgrade and verify with:

hzr update
hzr --version
hzr hooks status
hzr doctor --workspace .

Restart already-open agent sessions after upgrading so they reload the managed hook and contract.

Verification

The release gate includes focused RED/GREEN regression tests for negative-cache expiry, structured
SessionStart output, Codex contract-bootstrap detection, and canonical index availability in the
presence of a byte-preserved dormant nested store, followed by:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-targets --all-features
rustup run 1.85.0 cargo check --locked --workspace --all-targets --all-features
scripts/verify-fork-core.sh --test
cd integrations/caveman-code && npm ci --ignore-scripts && node --test bridge.test.mjs
cd visualizer && bun install --frozen-lockfile && bun test && bun run typecheck && bun run build

The bundle smoke gate additionally verifies clean installation, same-version re-attestation,
project-only adoption, hook rewiring, upgrade behavior, public entrypoints, and all four pinned
engines before publication.

HZR 0.3.5

HZR 0.3.5 — Project-only activation and scoped evidence

HZR 0.3.5 makes “enable HZR here, keep the comparison project untouched” a real product mode.
Index and memory data were already isolated by repository, but the integration layer was global:
agent instructions applied everywhere, Claude initialized every opened directory, MCP registrations
were client-wide, and hzr stats reported one lifetime total. Those boundaries now switch together.

No provider-cost or task-quality improvement is claimed. Scoped statistics are still local
before/after output estimates, and provider receipts remain explicitly global until their schema
carries a workspace identity.

Project-only activation

From the project that should use HZR:

hzr install --project-only --dry-run
hzr install --project-only --force

Fresh release installation supports the same mode with:

HZR_PROJECT_ONLY=1 sh /tmp/hzr-install.sh

The selected-mode contract is fail-closed:

• enabled workspaces are stored as validated repository/worktree SHA-256 identities plus their
  canonical display root;
• the one global Claude hook runs init --if-enabled and emits no routing decision outside the
  enabled set;
• managed CLAUDE.md and AGENTS.md blocks live in enabled project roots instead of user-global
  files;
• HZR-owned global Codex and Claude Desktop MCP registrations are removed with the same
  content-addressed backup/CAS protections used during installation;
• MCP refuses unsafe, uninitialized, or unselected workspace bindings before any project-scoped
  daemon request.

Additional projects can be changed independently:

hzr enable --workspace /path/to/project
hzr disable --workspace /path/to/project

disable removes the activation entry and local managed instruction blocks. It does not delete the
managed index, memory, visualizer registration, or accounting history.

The default installation remains all-project for backward compatibility. A confirmed
hzr install --force switches selected activation back to the default and restores global managed
instructions and native MCP registrations.

Project-scoped statistics

hzr stats --workspace /path/to/project

The project filter applies consistently to direct output reduction, subsystem and command totals,
and the optimizer-bypass numerator and denominator. Descendant working directories are included;
string-prefix siblings are excluded.

Provider usage and degraded-hook accounting retain a visible global lifetime label. HZR does not
attribute those rows to a project without source evidence.

MCP binding is stricter

A directory that merely looks like a project can no longer own an MCP namespace. The server now
requires a verified managed .grepai placement, and selected mode also requires an activation
entry. Filesystem root, home, home ancestors, uninitialized projects, and unselected projects all
return a model-visible error before dispatch. The workspace-independent hzr_codec remains
available when binding is refused.

Project-only installation does not install a client-global MCP registration. A manually pasted
--workspace registration is still visible to every session using that client profile, so use a
separate profile when the MCP tool itself must be absent from baseline projects.

Observatory state correction

The dashboard now reports an index with ready on-disk artifacts and an intentionally idle on-demand
watcher as Standby. It no longer remains in Rebuilding for hours after a daemon restart when no
rebuild is active.

Upgrade impact

The upgrade does not rewrite memory rows, index artifacts, or ledger records. Existing configuration
deserializes as activation.mode = "all", preserving prior behavior. Project-only installation
removes only marker-owned global instructions and HZR-owned MCP registrations; unrelated hooks,
instructions, and MCP servers are preserved and backed up before changed files are committed.

Upgrade and verify with:

hzr update
hzr hooks status
hzr doctor --workspace .
hzr stats --workspace .

Restart already-open agent sessions after changing activation mode so they reload hooks,
instructions, and MCP configuration.

Verification

The release gate includes:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-targets --all-features
rustup run 1.85.0 cargo check --locked --workspace --all-targets --all-features
scripts/verify-fork-core.sh --test
cd integrations/caveman-code && npm ci --ignore-scripts && node --test bridge.test.mjs
cd visualizer && bun install --frozen-lockfile && bun test && bun run typecheck && bun run build

The bundle smoke gate additionally exercises clean installation, same-version re-attestation,
all-project adoption, project-only adoption, public hzr and compatibility rtk entrypoints, and
all four pinned engines before publication.

HZR 0.3.4

HZR 0.3.4 — Better evidence, safe memory lifecycle, truthful observability

HZR 0.3.4 hardens the information given to coding agents and closes the memory-lifecycle gap
left in 0.3.3. Context plans now preserve retrieval signal instead of favoring short artifacts,
managed agents receive repository instructions and locatable evidence, and memory maintenance is
available without weakening project isolation or making pruning destructive by default.

The observatory also stops presenting synthetic search probes as user activity. Provider usage,
local estimates, index health, and recorded operations remain separate evidence classes.

No benchmark percentage changes are claimed in this release. The new deterministic gates prove
the implementation contracts; provider-backed task quality and economics remain a separate
release-evidence requirement.

Context plans rank evidence instead of file size

The previous fusion score was effectively reciprocal rank with a large constant. Over HZR's short
candidate lists, strong and weak results collapsed into a narrow band. The selection utility then
divided by the square root of token count, so a tiny manifest or opaque artifact could outrank a
longer file containing the answer.

• Scores are normalized within each retrieval source before weighted fusion, preserving the
  magnitude that source actually observed.
• Candidate length is enforced as a budget constraint, not treated as evidence of relevance.
• Weak candidates are rejected with relevance_floor; unlocatable code artifacts are demoted.
• Durable memory receives a minority share of the input budget, so stale prose cannot displace the
  code it describes.
• The configured output reserve and safety margin are subtracted before context selection.
• Symbol-shaped intents add a bounded exact search alongside ranked retrieval.
• Long memory bodies are bounded while preserving both the initial context and latest tail.
• coverage now reports addressable evidence, while confidence reports separation between the
  leading candidate and the remaining field.

Managed agents receive instructions and locatable evidence

The Caveman bridge previously disabled duplicate SDK subsystems correctly, but also suppressed the
repository instructions the model needed to work safely. It then appended the planner's complete
JSON response to the prompt.

• Bounded root AGENTS.md and CLAUDE.md files are loaded as repository-control instructions.
• Agents are told to discover more-specific nested AGENTS.md files before editing below them.
• Prefetched context is rendered as a bounded, explicitly untrusted evidence brief with paths,
  symbols, line spans, relevance, token counts, and selected content.
• Raw planner JSON is no longer injected into the model prompt.
• Native Caveman tools, hooks, memory, repo maps, and prompt templates remain disabled; HZR stays
  the only control plane.
• Managed prompts are bounded at 64 KiB, project instructions at 24 KiB, and prefetched evidence at
  16,000 characters.
• High and irreversible codec requests force exact fidelity in the daemon path.

Memory maintenance is scoped and safe by default

hzr memory update, hzr memory forget, and hzr memory prune are now available through the CLI,
daemon API, native MCP server, and managed-agent bridge.

• Every mutation first enumerates typed ICM records and applies the same positive project/global
  namespace filter used by recall.
• A project request cannot mutate another repository or the global namespace.
• Pruning is a preview unless the CLI receives --apply or an API/MCP caller explicitly disables
  dry_run.
• High and critical memories are never selected by threshold pruning, regardless of weight.
• Partial prune failures report how many records were deleted and require inspection before retry.
• Mutation transport failures remain explicitly ambiguous; HZR never falls back to a second store.

The public loopback dashboard now redacts memory summaries, raw excerpts, keywords, and source
data. Full bounded details moved to the bearer-authenticated
GET /v1/memory/topics/{opaque_topic_id} endpoint. Repository filtering and opaque topic IDs are
unchanged.

MCP cancellation and usage accounting survive failures

• Native MCP tool calls run concurrently instead of serializing every request behind one slow
  operation.
• notifications/cancelled aborts an in-flight tool call and suppresses any late response.
• Duplicate in-flight request IDs are rejected, and stdin EOF aborts remaining work.
• Failed managed-provider usage receipts are written to private 0600 outbox entries under a
  0700 directory and replayed after the daemon recovers.
• Entries are removed only after the usage endpoint confirms recording. Ledger trace_id
  idempotency prevents replay from creating duplicate provider records.

The observatory reports recorded activity

The grepai panel no longer runs a hard-coded semantic canary and labels it as live user traffic.
Index readiness comes from the managed watcher and artifact evidence. Routed-search activity is
shown only when a real optimized HZR search exists in the selected project's ledger, including its
exact command, working directory, latency, and observed attribution. When no such request exists,
the UI says so.

Installation reports progress and the resulting layout

The self-contained bundle is large enough that a silent transfer can look stalled. The installer
now reports five numbered steps, shows curl or wget transfer progress on an interactive terminal,
and finishes with the version root, active-version pointer, command entry points, data directory,
dashboard URL, health check, and concrete next-use commands. PATH guidance is printed only when the
configured bin directory is absent from the current PATH.

The atomic active-version swap also cleans up its pending .current-<pid> symlink if installation
exits before the replacement completes.

Upgrade impact

The upgrade does not rewrite existing memory rows or project configuration. The new usage outbox is
created only when a managed provider receipt cannot reach the daemon. Public dashboard clients that
previously displayed memory content now receive redacted fields and must use the authenticated API
when content inspection is required.

Upgrade and verify the installed ownership model with:

hzr update
hzr mcp status
hzr doctor

Restart already-open Codex or Claude Desktop sessions after upgrading so they reload the expanded
MCP tool catalog and managed instructions.

Verification

The release gate includes:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-targets --all-features
rustup run 1.85.0 cargo check --locked --workspace --all-targets --all-features
scripts/verify-fork-core.sh --test
cd integrations/caveman-code && npm ci --ignore-scripts && node --test bridge.test.mjs
cd visualizer && bun install --frozen-lockfile && bun test && bun run typecheck && bun run build

The bundle gate additionally verifies the manifest, clean installation, same-version
re-attestation, public hzr and compatibility rtk entrypoints, all four pinned engines, and the
installed 0.3.4 behavior before publication.

Provider-paired quality/economic trials, Windows native artifacts, and release SBOM/license evidence
remain explicit gates for a future state-of-the-art or Windows-support claim; this release does not
represent those external checks as complete.

HZR 0.3.3

HZR 0.3.3 — One store, exact contracts, evidence an agent can use

Three lines of work land in this release, and all are about the same thing: a contract that
did not match the runtime behind it. MCP and CLI memory now share one project binding, agent
evidence has exact paths and symbols, and green observatory states open into verifiable memory,
search and request detail instead of stopping at a status tile.

The first was silent. The MCP surface and the CLI wrote to different memory namespaces in
the same repository while both reported success, and a context plan handed agents ranked
file paths with no code in them — so the agent opened every file anyway, which is the work
the plan exists to save.

The second was visible but wrong in shape: a flag promised one kind of evidence while the
runtime returned another. Markdown outlines, line coordinates, exact heads, leading-hyphen
searches, memory provenance and the installed instructions now agree with their public
contract.

Everything below was reproduced before it was changed, and verified after. No benchmark
percentage changes in this release.

The one-store guarantee held everywhere except through MCP

The project memory namespace is derived from the directory the MCP client launched
hzr mcp serve from. Clients choose that badly:

Client	Launch directory observed	Namespace it bound
Claude desktop app	/	the filesystem root
Codex	~/Documents/Codex/<date>/<chat>	a fresh one per chat
Claude Code	the project	correct

So a memory stored through MCP landed in the root's namespace while a CLI recall looked in
the repository's namespace and found nothing. Reproduced symmetrically: a sentinel stored
over MCP was invisible to hzr memory recall, and one stored over the CLI was invisible to
hzr_memory_recall. Both writes reported success — the fake-success failure this adapter was
built to prevent, arriving through the one input it does not control.

• The binding is classified before it is used. The filesystem root, the home directory and
  any ancestor of it can never own a project namespace.
• A refused binding returns isError with the remediation rather than writing where nothing
  will read. hzr_codec needs no workspace and keeps working.
• The initialize handshake states the resolved binding, so an agent can tell which project
  its memory belongs to instead of inferring it from a hash.
• hzr mcp config --client <c> --workspace <dir> pins the project in the snippet you paste.
  An unpinned snippet says why that matters.
• A directory that is merely not a git repository still binds, because HZR supports projects
  before git init everywhere else.

Doctor names the cause, not the symptom

client_mcp_ownership audited Codex's config.toml and the desktop app's
claude_desktop_config.json. Nothing read ~/.claude.json, so a direct icm server
registered there — the one thing the contract forbids — passed the ownership check while
spawning a second memory writer on every session start. Doctor reported the resulting orphan
processes and told the user to stop processes the client immediately respawns.

• Claude Code is audited, including per-project projects.<path>.mcpServers, and never
  written: it is the user's session state, not an HZR file. Writing it is refused rather than
  skipped, so the rule stays checked.
• Each client gets the remediation that applies to it — claude mcp remove icm for the file
  HZR must not touch, the config snippet for the two it may.
• New client_mcp_workspace check: a registered server with no --workspace takes its
  namespace from the client's launch directory. That is the cause of the split namespace
  above, and it was previously silent.

A plan candidate now contains evidence

symbol, line_start and line_end have been in the protocol since the first release and
the planner never filled them in. A candidate was {path, score, sources, estimated_tokens}
— nothing that could not be had from ls.

Measured on the intent "how does the bash hook decide to rewrite a command": 11809/16000
tokens spent, coverage 0.50, relevance spread 0.0123–0.0161 (no ranking signal), and the file
that actually answered it was not among the candidates.

• Every candidate carries its symbol outline with line spans, from the fork's own extractor
  (rtk read <file> --symbols) rather than a second, weaker one grown inside HZR.
• Verified live: a candidate that reported only src/lib.rs now reports src/lib.rs:4-12
  with decide_rewrite(function, 4-12).
• Bounded to 24 symbols, with the omitted count and the command that shows the rest, so a
  large generated file cannot spend the plan's budget on its own symbol list.
• Best-effort by design: an unreadable, binary or unsupported-language file contributes no
  outline and degrades to the path it was before. A plan must not fail over one lead.

Search stops lying about where and what it found

• A file scope failed entirely. --path never sent --project-root in exact mode, so
  the fork treated the search path as the project root and any file path failed with
  "project root is not a directory" — delivered as an opaque HTTP 503. The same query in
  semantic mode worked, which made it look like a mode quirk rather than a missing argument.
• A scoped hit reported an unusable path. The fork reports hit paths relative to
  --path: scoping to src reported lib.rs, which does not exist at the root, and scoping
  to a file reported the empty string, which normalized to .. Hits are rebased onto the
  project root.
• Semantic mode emitted source truncated mid-token. grepai chunks are byte windows, so a
  chunk's first line can begin mid-identifier — line 194 of hook_runner.rs came back as
  en(Value::as_str) else {, the tail of .and_then(Value::as_str) else {. Source that looks
  real and does not parse is worse than no source. A fragment is now completed from the
  recorded line, and only when it provably occurs there, so an index older than the file
  keeps the engine's text rather than having an unrelated line substituted for it.

The contract says what the code does

• Hook coverage. The PreToolUse matcher is Bash|Agent|Task. Nothing redirects a
  native Read, Grep, Edit, Write or Glob, and nothing records one — those calls are
  absent from hzr stats on both sides of its ratio, so a session that reads files natively
  shows a high reduction over a small measured fraction of what it spent. The preference
  table is the agent's to follow, not something the hook enforces.
• The codec. It was described as compressing prose. Its only transform is removing exact
  duplicate paragraphs under verified protected spans. Verified on 4 KB of deliberately
  verbose single-paragraph prose: it comes back byte-identical, and that is a correct result,
  not a failure.
• The repo map. hzr rtk -- memory explore <dir> gives entry points, hot paths and API
  surface, and the Explore-deny hook already pointed agents at it while the command table
  omitted it. Documented, along with read --symbols.

A subagent gets a brief, not a JSON dump

The plan was prepended to a subagent's prompt as a minified ContextPlanApiResponse — no
glossary, no statement of what the entries were, no instruction. A subagent either ignores
that or treats ranked guesses as findings; the second is worse. Leads are now named as
path:start-end with their symbol, declared unverified with the commands that confirm them,
and an empty plan says it found nothing rather than reading as "nothing relevant exists".

Markdown --outline now means an outline

hzr rtk -- read README.md --outline

Markdown previously went through the source-code symbol extractor and returned
(no symbols found). HZR now emits the ATX heading hierarchy (# through ######) with
original source spans. Rust, Python, TypeScript, JavaScript, Go and Java keep their existing
symbol-oriented outline.

The default Markdown read remains a bounded, self-described digest. Use --outline when the
heading tree is the evidence you need, --level none for exact full content, or --from and
--to for an exact range.

Line-oriented flags preserve exact evidence

• read -n now defaults to exact content and prints original source coordinates.
• Ranged and tail reads no longer restart numbering at line 1.
• read --max-lines N returns exactly the first N lines. It no longer replaces the
  remainder with a smart truncation marker.

These semantics make the output safe to cite in a later edit or review without translating
coordinates back to the source file.

Exact search accepts option-shaped literals

Exact search is still literal and case-sensitive. The planner now puts search options before
-- and the query after it, so a literal beginning with - cannot be parsed as a fork-core
option:

hzr search --mode exact -- "--outline"

Legacy memory is retained without leaking across projects

Old imported memory rows do not contain trustworthy repository provenance. Earlier HZR
versions assigned every such row to the repository that happened to run the import, which
could make another project's facts reachable there.

HZR 0.3.3 keeps those records in the canonical store for audit and explicit migration, but
quarantines them from automatic project recall. Current project and global memories are
unchanged; no database rows are deleted or rewritten by the upgrade.

The live observatory is now an inspection surface

Open the same daemon-owned loopback UI after installation:

http://127.0.0.1:47391/

• ICM Ready is backed by a supervised probe and a positively repository-filtered snapshot.
  Select a topic in the deterministic Cytoscape graph to load at most 100 bounded memory
  records, then inspect one record's summary, importance, weight, timestamps, source,
  keywords and opaqu...

HZR 0.3.2

HZR 0.3.2 — Honest accounting

HZR reported a reduction ratio that was measuring a shrinking fraction of the traffic it
claimed to cover. This release makes the uncovered part visible, hands agents the commands
that close it, and fixes the search mode whose name promised something it did not deliver.

Reference point: comparisons below are against upstream RTK v0.44.1, the engine HZR
forks. Where a row says upstream, that behaviour is unchanged in rtk today.

Already on 0.3.1? The implementation landed before that tag, so your runtime already has
it. 0.3.2 adds the MSRV fix that turned CI green and publishes these notes as the release
description.

Optimizer bypass is measured and named

• A command routed through raw reaches the shell unfiltered. It delivers exactly as many
  tokens as its baseline and therefore contributes zero avoided tokens. When RAW is included
  in the accounting boundary, the baseline grows while net avoided output does not, so the total
  reduction percentage goes down. The separate bypass share makes that loss of coverage explicit.
• hzr stats prints the bypass share directly beneath the headline: operations, delivered
  tokens, and each bypassed tool ranked by cost.
• Every bypassed read or search carries a copyable replacement, reconstructed from its
  costliest recorded invocation — sed -n 120,180p f becomes
  hzr rtk -- read f --from 120 --to 180.
• Where no equivalent exists (cargo, git, ps, tar), the panel says so instead of
  inventing one.
• Upstream: RTK reports savings per command and has no notion of a bypassed route.

Agents are corrected, not only measured

• The PreToolUse hook answers a bypassed read or search with the equivalent command already
  filled in.
• The decision is Ask, never Deny — raw stays one keystroke away, because it remains
  correct for checksums, parsers, generated files and complete logs.
• Commands with no first-class equivalent are never interrupted.

--mode exact is finally exact

• Exact mode delegated to a ranked term model: the query was lowercased, split on
  non-alphanumerics, stripped of stop words, stemmed, and the survivors OR-ed into one regex,
  so hzr search "fn record_degraded_rewrite" --mode exact matched every file containing fn.
• It is now a literal, case-sensitive lookup — rtk rgai --literal in fork-core, wired to
  HZR's exact mode.
• --path accepts several directories. --path crates fork-core/src used to fail with
  error: unexpected argument.

Query fn record_degraded_rewrite	Files returned
RTK upstream v0.44.1 — rgai	21 (ranked terms)
HZR 0.3.1 and later — --mode exact	1 (literal)

Accounting coverage can return to COMPLETE

• Coverage was line_count(degraded-rewrites.log) == 0 over an append-only file that nothing
  truncated, so one install performed while the daemon was down pinned hzr stats to
  ▲ INCOMPLETE permanently.
• It is now an open gap: the next managed rewrite closes it, and the lifetime count stays
  visible, so closing a gap never looks like erasing one.

The density codec is reachable and measurable

• hzr-codec existed but nothing called it — not the hook path, not the planner, not MCP.
• It is now the hzr_codec MCP tool, and its transforms are recorded in the efficiency ledger
  under a codec subsystem.
• The shadow profile reports what compression would have saved without altering the text.

Engine health is read, not asserted

• caveman-code was reported with a hardcoded state and a hardcoded version string, so an
  installation missing the runtime looked identical to a working one.
• The version now comes from engines.lock.toml; a missing bridge or package is reported as
  degraded together with the command that repairs it.
• Engines that rest by design no longer colour the overall verdict.

The live observatory proves memory and search

• ICM Ready requires a successful supervised probe and a read-only snapshot of the canonical
  store. FTS5-only retrieval is a supported ready capability; a missing database is
  unavailable, never a synthetic empty project.
• Project memory is a privacy-safe topic graph — opaque node IDs, aggregate counts, bounded
  relationships. Memory bodies and store paths never enter the API.
• grepai reports generation and configuration fingerprints, artifact freshness, watcher
  PID/uptime and ownership. A cached semantic canary must return visible hits before semantic
  search is Ready, and the canary cannot credit its own ledger.
• Provider tokens and cost appear only from accepted receipts. Without a receipt source the UI
  says No provider receipts rather than displaying an invented zero.

One rule behind all of it

• "Did this operation go through the optimizer?" was answered in three places — the ledger, a
  hand-written SQL predicate and the CLI — with three different answers.
• It is now one classifier in hzr-core::operation, and the SQL predicate is generated from
  the same marker list, so the terminal, the dashboard and the ledger cannot drift apart again.

Fixed in 0.3.2

• A let chain in hzr-core::operation compiled locally but not on the declared MSRV
  (rust-version = "1.85"), failing the msrv CI job and blocking the release workflow.
• The GitHub Release description is taken from this file instead of an auto-generated commit
  list, so the published release and the repository state the same thing.
• CI uses the official Node 24 editions of GitHub's checkout, Node, Go, artifact and attestation
  actions. Go caching is disabled where engine sources are cloned only after setup, eliminating
  both the Node 20 deprecation annotations and the misleading missing-go.sum cache warning.

Upgrading

hzr update

Nothing in your ledger is rewritten. The bypass panel appears on the next hzr stats, and
coverage closes on the next rewrite the daemon serves.

Verification

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-targets --all-features
rustup run 1.85.0 cargo check --locked --workspace --all-targets --all-features
scripts/verify-fork-core.sh --test
cd visualizer && bun test && bun run typecheck && bun run build

The tag workflow additionally builds Linux and macOS bundles for x64 and ARM64, attests build
provenance and publishes the pre-release.

HZR 0.3.1

Full Changelog: v0.2.0...v0.3.1

HZR 0.2.0

HZR 0.2.0 — first public release

heAdz0r's Zero-Redundancy engine turns the proven command-efficiency core into one local-first control plane for coding agents.

Highlights

• One installer delivers the complete versioned runtime; no separate engine or Node.js setup.
• The installer re-attests existing same-version roots and rejects tampered, missing, or symlink-injected artifacts before switching current.
• A production user service owns the single hzrd through stable current/bin/hzrd on macOS and Linux.
• One owner for command execution, semantic code retrieval, durable memory, context policy, response density, and accounting.
• hzr mcp serve exposes the same HZR memory and search to MCP clients without creating another store or daemon owner.
• hzr stats reports cumulative local efficiency and observed provider usage as separate measurement domains.
• Claude and Codex adoption migrates legacy RTK/ICM directives and client MCP registrations transactionally, with content-addressed backups.
• Platform RTK history can be snapshotted and imported row-idempotently with hzr migrate history.
• Legacy ICM durable data can be merged with hzr migrate memory; both databases are
  snapshotted, the source stays untouched, and a content-addressed manifest makes retries no-ops.
• Clean installs use explicit FTS-only ICM by default, avoiding an implicit embedding-model
  download on the first write; provisioned deployments can enable engines.icm_embeddings.
• Claude/Codex global response paths are explicitly reported as unintercepted, so MCP
  adoption is never misreported as codec savings.
• The full inherited engine remains intact and evolves inside HZR with immutable v0.1.0 provenance and regression gates.

Install

curl --proto '=https' --tlsv1.2 -fL \
  https://raw.githubusercontent.com/heAdz0r/hzr/v0.2.0/install.sh \
  -o /tmp/hzr-install.sh
less /tmp/hzr-install.sh
sh /tmp/hzr-install.sh

The installer verifies the release checksum, internal bundle manifest, mandatory file modes,
and allowed symlink layout before switching the active version.

Supported release artifacts

• macOS Apple Silicon
• macOS Intel
• Linux x86_64
• Linux ARM64

Windows is not included in 0.2.0.

Honest measurement boundary

HZR does not claim a universal savings percentage from synthetic estimates. Provider-reported usage and estimated local tool-output reduction remain visibly separate; end-to-end cost claims require paired accepted-task benchmarks.

See the README, PRD, and security policy for the complete contract.