1.0.0 — 2026-07-14

Release Notes

Halfhand 1.0.0. The first stable release. From here on the contracts in
STABILITY.md hold: CLI flags/exit codes, --json output, the on-disk
database, MSRV, and the hh-core Rust API change only additively (or via a
documented deprecation). A database written by v0.1.0-beta.1 opens and
reads correctly under 1.0 — proven by the permanent
hh/tests/migration_from_beta.rs against a committed beta-created fixture.

Highlights

• Secret redaction (hh scan, hh redact): detect secrets in recorded
  sessions, report them without ever printing the value, and irreversibly
  redact in place — events and blobs rewritten, originals securely deleted,
  DB compacted. Exits 4 on findings so CI can gate on a clean scan.
• Export / HTML replay (hh export --bundle|--html, hh import):
  portable .hh archives (manifest + events + referenced blobs, zstd), a
  self-contained single-file HTML replay page (hh replay --web), and hh import to bring a bundle back under a new id. Exports are always
  redacted by default; opting out needs an interactive TTY confirmation.
• Codex CLI, Gemini CLI, and Claude Desktop adapters in addition to
  Claude Code, each with a fuzz target that never panics on malformed input.
• Cross-session FTS5 search (hh search): words, phrases, prefix *,
  AND/OR/NOT, with --agent/--kind/--since/--path filters and --json.
• Windows support (build-only per SRS §2.2): CI builds on
  windows-latest every push; PTY recording on Windows remains best-effort.
• Stability contract (STABILITY.md): the 1.0 promise for CLI, --json
  (schema frozen at 2), the on-disk DB (forward-only migrations),
  MSRV (1.75, minor-release bumps only), and hh-core semver (enforced by
  the cargo-semver-checks CI job).
• Release pipeline via cargo-dist: per-target binaries (mac/linux
  gnu+musl, windows msvc), SHA-256 checksums, shell + powershell installers,
  a Homebrew formula, and keyless GitHub artifact attestations
  (gh attestation verify). hh completions <shell> and a generated hh.1
  man page ship in every archive.
• Docs site (mdbook) on GitHub Pages, with a printable hand-run
  docs/manual-qa.md checklist and docs/1.0-definition-of-done.md mapping
  every release bar to its proof.

Added — 1.0 release-readiness

• hh completions <shell>: prints a shell completion script (bash, zsh,
  fish, powershell, elvish) via clap_complete (FR-6.2 ergonomics). New
  docs/completions.md page; --help example per shell. The scripts and the
  hh.1 man page are also generated at build time by the new hh-dist
  workspace crate (just dist-assets) and shipped in release archives.
• cargo-dist release pipeline: tag-triggered (v*) releases now produce
  per-target binaries (mac/linux gnu+musl, windows msvc) with the git sha
  embedded (HH_BUILD_SHA, NFR-8), SHA-256 checksums, a shell + powershell
  installer, keyless GitHub artifact attestations (verify with gh attestation verify), and an auto-pushed Homebrew formula to
  halfhand-org/homebrew-tap. Config lives in dist-workspace.toml; the
  workflow is generated by cargo dist generate. See CONTRIBUTING.md
  "Cutting a release".
• mdbook docs site under docs/, published to GitHub Pages on release
  (and on push to main as a preview) via .github/workflows/docs.yml. The
  existing docs/*.md and docs/adr/*.md are rendered in place (no path
  moves, preserving the 93 in-repo references); new pages: Quickstart,
  Recording, Replay & Inspect, Adapters, FAQ, Stability, Security.
• Repo hygiene: bug-report and feature-request issue templates (the bug
  form requires hh --version and hh stats output), a PR template encoding
  the CLAUDE.md done-definition, CODE_OF_CONDUCT.md (Contributor Covenant
  2.1), and CONTRIBUTING.md (dev setup, adapter fixture-capture guide, fuzz/
  bench instructions, release runbook).
• hh-dist crate: a publish = false workspace crate that generates
  completion scripts and the man page from the single Cli definition, so
  cargo install halfhand still installs only hh.

Changed — 1.0 release-readiness

• README rewritten for 1.0 (245 → 116 lines): hero, install matrix
  (cargo/brew/script), 30-second demo, the honest "faithful playback" framing,
  badges, and a short "why local-first" section. Depth moved to the docs site.
• Release workflow replaced: the bespoke .github/workflows/release.yml
  is superseded by cargo-dist's generated workflow; re-run cargo dist generate to emit it from dist-workspace.toml.
• just fuzz-all now runs all eight fuzz targets (was missing
  codex_jsonl, gemini_jsonl, import_bundle).

Added — 1.0 stability groundwork

• STABILITY.md: the 1.0 promise for CLI flags/exit codes (additive-only,
  deprecate-before-remove), --json (schema frozen, additive-only, see
  below), the on-disk DB (forward-only automatic migrations; --json and
  hh export bundles — not raw SQL — are the supported programmatic
  interface), MSRV (bumps are minor releases only), and hh-core's Rust API
  (enforced today by the cargo-semver-checks CI job).
• JSON schema bumped to schema:2, frozen for the 1.0 series: additive
  changes (new fields, new enum values, new body shapes) no longer bump the
  integer, reversing the beta-era policy. schema:2 folds in drift that
  shipped without a version bump in the previous entry below — three new
  agent_kind values and the redaction_audit lifecycle body — documented
  field-by-field with a diff from schema:1 in docs/json.md. A new
  hh-core::event::JSON_SCHEMA_VERSION constant is now the single source of
  truth every JSON-emitting call site (including hh-core::bundle, for hh export --bundle) reads from, replacing several independently hardcoded
  1s.
• Docs/code reconciliation audit: README.md's command table was missing
  hh gc/hh stats/hh import/hh search and still called the Codex/
  Gemini/Claude Desktop adapters "planned for v0.2" after they'd shipped
  (see the entry below); docs/json.md's agent_kind table and
  docs/search.md's --agent filter list were missing claude-desktop (and
  docs/search.md also missing mcp-only); hh mcp-proxy --session-hint's
  --help text implied it was stored when it is in fact accepted but not
  yet persisted anywhere (now documented honestly in docs/mcp-proxy.md).
• hh-core::deprecation::warn_deprecated: the standard stderr format for
  a deprecation warning (hh: warning: <what> is deprecated; <guidance>),
  deduplicated per unique warning id so a call site can never print more than
  once per invocation. Config::load's legacy halfhand.toml/hh.toml
  fallback notice now goes through it.
• CLI conformance test (hh/tests/cli_conformance.rs): snapshot-tests
  hh --help and every hh <sub> --help, and asserts the documented exit
  codes — 2 usage error, 3 session not found, 4 hh scan with
  findings.

Added — Codex CLI, Gemini CLI, and Claude Desktop adapters; cross-session search (docs/search.md, docs/adr/0003-fts-index-strategy.md)

• Codex CLI adapter: tails ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl,
  converting response_item (message, reasoning, function_call,
  custom_tool_call) and event_msg (user_message, agent_message,
  token_count, exec_command_end) records to the same structured event model
  as the Claude Code adapter (agent_kind = codex-cli).
• Gemini CLI adapter: tails ~/.gemini/tmp/<hash>/chats/session-*.jsonl,
  converting user/gemini records (tool calls, thoughts, tokens)
  (agent_kind = gemini-cli).
• Claude Desktop adapter: reuses the Claude Code JSONL tailer/parser
  (identical transcript format) under its own agent_kind = claude-desktop
  so hh list/hh inspect distinguish the two.
• Force any of the four with hh run --adapter <claude-code|claude-desktop| codex-cli|gemini-cli> -- <command>; auto-detection matches on the wrapped
  command's basename same as before.
• hh search <query> [--agent] [--kind] [--since] [--path] [--limit] [--json]: FTS5 full-text search across every recorded session's event
  summaries and message bodies, with highlighted snippets in the table view.
  Backed by a new events_fts virtual table (migration 0004, additive) kept
  incrementally in sync by the writer thread on every append, and maintained
  (rows removed) on hh delete and hh redact — a redacted secret is
  provably not findable via search (property-tested). --limit defaults to
  50, capped at 500.
• Fuzz targets for the new Codex/Gemini JSONL parsers (fuzz/fuzz_targets/ codex_jsonl.rs, gemini_jsonl.rs) and a search benchmark (target <100ms
  across 100 sessions × 1000 events).
• AgentKind marked #[non_exhaustive] (new variants append at the end, so
  existing discriminants don't shift); cargo-semver-checks CI excludes the
  one-time enum_marked_non_exhaustive lint for it.

Added — redaction pipeline (SRS §8, docs/redaction-design.md)

• Secret detection engine (hh-core::redact): compiled detectors for
  AWS access key ids, GitHub/GitLab/Slack tokens, PEM private-key blocks
  (including truncated fragments), JWTs, a conservative high-entropy
  scanner, and user-defined regexes via the new config [redaction] rules.
  Matches are replaced with {{REDACTED:<type>:<hash8>}} where hash8 is
  a BLAKE3 prefix of the secret — one-way, but stable, so the same secret
  correlates across events without being stored. Contract (property-tested
  and fuzzed via the new redact_detect target): false positives are
  acceptable, false negatives on the named token types are bugs.
• hh scan <session|last|--all> [--json]: reports detected secrets
  (type, step, location, hash8) without ever printing them. Exit code 4
  when findings exist — the documented redaction/policy exit code — so CI
  can ...

v0.1.0-beta.1

What's Changed

• Worktree vectorized sniffing walrus by @saadmanrafat in #1
• feat: implement FR-3 interactive replay TUI by @saadmanrafat in #2
• Merge pull request #2 from halfhandorg/worktree-fr3-replay-tui by @saadmanrafat in #4
• Merge pull request #4 from halfhandorg/main by @saadmanrafat in #5
• fix(record): correct macOS-only file-watcher and adapter test flakiness by @saadmanrafat in #3

New Contributors

• @saadmanrafat made their first contribution in #1

Full Changelog: https://github.com/halfhandorg/halfhand/commits/v0.1.0-beta.1