Hydra Engine 12.3-hydra.2

Released 2026-10-26. Based on upstream Ghidra master (12.3 DEV) as of 2026-10-26,
commit 057a646233edfb21768a42a0aabc1d1a7709da19: the same upstream commit as 12.3-hydra.1
(upstream had no newer commit when this release was cut).

What's new for integrators

Several agents can now change things at the same time, each in the way that fits its work:

• A working copy of a project (fork_project) while every other client keeps reading the
  master: a block clone on ReFS (about 0.2 s and 3-5 MB for a 1.5 GB project), a full copy
  elsewhere (8.5 s for the same project to NTFS), with the source
  and base revision recorded next to the fork.
• A private overlay of a program others read (open_program with overlay,
  apply_overlay): renames, labels, comments, signatures and data types only that client sees,
  never saved unless promoted into a working copy (promote_overlay).
• Several writers: several clients write one project (different programs in parallel), or
  one program in shared mode ("share": true), with every change journalled with its author,
  expect against lost updates, an atomic edit command and discard_edits.
• Revisions and refresh: answers say when another process saved a project a read-only
  view serves (stale); refresh reopens it for all its clients at once.
• Who holds it, and what to do: busy, conflict and not_owner name the holder
  (holderInfo) and suggest the action (retry, fork_project with a ready request, an
  overlay, share, reread, open_read_only).
• Imports in parallel (maxImports), with a visible, cancellable queue in status.imports.
• Per-request client/harness labels, so one MCP server serving several agents can tell
  them apart in holders, status, the import queue and cancel.
• A versioned integration contract: hello and status carry protocol, minClient,
  hydraVersion, ghidraVersion and installId; the client ships as its own release asset,
  hydra-client-12.3-hydra.2.zip, and refuses an engine it cannot drive. The export contract
  of long scripts (artifact path, progress, cancel, partial files) is documented and tested.

Compatibility

• Protocol 2, unchanged. Everything above is new commands and new fields; nothing was
  renamed or removed, except that the busy details of a program lock carry the program's key
  in program (its project path moved to path). The engine answers minClient: "1.0.0".
• Client 1.0.0 (ghidra_session.py, CLIENT_VERSION) is the first versioned client;
  pin it together with the engine. The unversioned client of 12.3-hydra.1 still speaks protocol
  2 but does not check the engine.
• Projects: a project saved by this build cannot be opened by Ghidra 12.2 or 12.1.4
  (upstream master writes data type databases at version 3). Projects analysed with 12.1.4
  open read-only without being written, upgraded in memory and then served from the upgrade
  cache; fork_project makes a writable copy that leaves the original as it was. The
  legacy-12.1.4 branch remains for projects that must stay on 12.1.4.
• Platforms: built and tested on Windows 11 x64 only (locally and in the release
  workflow). Linux and macOS are not released or tested routinely.

Downloads

• hydra-engine-12.3-hydra.2-win_x86_64.zip: the headless install for Windows x64 (gradle zipHeadless); the release workflow ran the three test suites on it after unzipping it.
• hydra-client-12.3-hydra.2.zip: ghidra_session.py (standard library only) stamped with
  this release, LICENSE and a short README.txt.
• SHA256SUMS for both.

You need a JDK 25 and Python 3.10 or later; the install has no JDK.

Known limits

• The data type database version 3 limit above, and a development snapshot as the base
  (upstream master is Ghidra's next version under work, not a Ghidra release).
• Overlays change only through their five operations (rename, label, comment, signature, data
  type) and show the program as stored when they opened, not other writers' unsaved changes.
• A fork is a block clone only on ReFS (Windows 11 24H2 and later); on NTFS it is a full copy,
  which auto mode refuses above forkCopyLimitMb (default 2048).
• The author journal lives in the daemon's memory while the program is open and keeps the last
  200,000 entries; discard_edits reverts renames, labels and comments only.
• Headless only: no window, help, javadoc or Python type stubs.

Added

• Holder information in busy, conflict and not_owner (HeadlessSession). The error
  details name who holds the project, program or lock: holderInfo (client, name,
  harness, label, command, heldMs; for another process, the user, host and time from
  Ghidra's project lock file and whether that process is alive), the project or program identity
  (project, gpr, program key, path, sha256), and suggest: retry,
  fork_project (with a ready suggestion request) where a working copy is the answer,
  share (join a shared program), reread (a value changed since it was read), or
  open_read_only. holder stays a string as before; everything else is new fields.

• fork_project (HeadlessSession): copies a project into a working copy for the caller
  while the source and its read-only views stay open and in use. A block clone on ReFS (Windows
  11 24H2 and later), else a full copy; mode auto (clone, or a full copy up to
  forkCopyLimitMb, default 2048), copy-on-write (clone or refuse) or full. The answer has
  the new project id, the paths, the source's identity and base revision, method, cloned
  (measured), bytes, files and times. The fork records its source, base revision and lineage
  in <name>.fork.json next to its .gpr, shown as fork by project. A source another
  client or process writes is refused, naming it. New launcher setting forkCopyLimitMb
  (GHIDRA_SESSION_FORK_COPY_LIMIT_MB), daemon option -forkCopyLimitMb.

• Revisions and refresh (HeadlessSession): every project and program has a revision
  (a fingerprint of the saved files), shown by open_project, project, projects,
  open_program, info, save and status with diskRevision, stale and generation.
  Answers carry stale (a read-only view whose project another process saved) and, once,
  refreshed (another client refreshed it). New command refresh (alias reopen) reopens a
  read-only view for all its clients at once, under the same keys. The Python client gains
  call_raw and last_response.

• Integration contract (Ghidra/Features/HeadlessSession, support/ghidra_session.py):
  hello, status and the endpoint file now carry protocol, minClient, hydraVersion,
  ghidraVersion, installId and startedAt; the Python client has a CLIENT_VERSION
  (1.0.0) and refuses, with IncompatibleError (exit code 4 on the command line), an engine of
  another protocol or one whose minClient is newer than itself; status and stop still work
  on such an engine. ghidra_session.py version prints the client's version. README: "Pinning
  and upgrading", and a compatibility statement for projects analysed with Ghidra 12.1.4.

• Client release artifact: the release workflow also publishes hydra-client-<version>.zip
  (the standard-library-only ghidra_session.py stamped with the release, LICENSE, a short
  README.txt), listed in SHA256SUMS. .github/scripts/package-client.sh builds it and
  checks the packaged file; CI runs it as a dry run.

• Status shows requests: each client in status lists its unanswered requests (id, cmd,
  artifact, ms, message, progress, maximum) and its clientVersion.

• Script exports: script takes an optional artifact (a path the script writes), echoed in
  status and in the result; examples/scripts/ExportJsonl.java is a sample export with
  progress and an inspectable partial file; README "Scripts" states the export contract
  (output outside the project, not capped by maxChars, partial files after cancel and shutdown).

• Concurrency documentation: README "Who can do what at the same time": readers, writers,
  projects, imports, and what conflict, busy and not_owner mean.

• Tests: examples/contract_tests.py (identity fields, client compatibility, a 600,000-line
  export with progress, cancel and shutdown), run by CI and the release workflow.

• The import queue is visible and cancellable. Imports that cannot run yet (one at a time
  when this was added; up to maxImports since "Imports run in parallel" below) queue
  first-come, first-served without holding a scheduler slot. status.imports shows the
  holder (client label, project, file, running time), the queue with each entry's position and an
  estimated wait (from the durations of earlier imports), and the history. A queued import
  sends progress events "waiting behind ..." and its answer reports queue (waitedMs,
  positionAtEntry, behind). Cancelling a queued import removes it without touching the
  running one; cancelling the running one starts the next. A numeric wait now limits the queue
  wait; without one a queued import waits until it runs or is cancelled.

• Per-request client and harness labels. Any request may carry them; they replace the
  connection's name for that request in busy/conflict holders (holder and holderInfo), status (requests, scheduler
  lanes, owner of a writable program, youAre), the import queue and the log, and they scope
  cancel (all reaches only that label's requests; target refuses another label's request).
  Ownership is unchanged (still per connection). One MCP server serving several agents can now
  tell which agent holds a program or an import. ghidra_session.py: labels on any call, and
  labelled(client=, harness=) views with cancel_all().

• daemon_tests.py:...

Hydra Engine 12.3-hydra.1

Released 2026-10-26. The first release. Based on upstream Ghidra master (12.3 DEV) as of
2026-10-26, commit 057a646233edfb21768a42a0aabc1d1a7709da19.

Downloads

One zip, hydra-engine-12.3-hydra.1-win_x86_64.zip: the headless install for Windows x64
(gradle zipHeadless), on which the release workflow ran both test suites after unzipping it.
You need a JDK 25 and Python 3.10 or later; the install has no JDK.

Known limits

• Projects saved by this build cannot be opened by Ghidra 12.2 or 12.1.4. Upstream master
  writes data type databases at version 3; 12.2 and 12.1.4 read version 2. A project opened
  read-only is not written; open older projects writable only from a copy. The
  legacy-12.1.4 branch serves projects that must stay on 12.1.4.
• Based on a development snapshot. Upstream master is Ghidra's next version under work
  (12.3 DEV), not a Ghidra release.
• Windows only. CI and releases build and test on Windows. The module and launcher have no
  Windows-only path, and a one-off dry run of the release workflow on 2026-10-26 built Linux x64
  and macOS arm64 installs that passed both test suites, but neither is released or tested
  routinely; build from source there (gradle buildHeadless).
• Headless only. No window, help, javadoc or Python type stubs; the full Ghidra build is
  still gradle buildGhidra, from source.

Added

• HeadlessSession module (Ghidra/Features/HeadlessSession): a shared, per-user headless
  session daemon. One JVM serves many projects and many clients over JSON lines on an
  authenticated loopback socket (or stdio), with protocol version 2.
  • Projects opened in place: read-only without a lock, or writable with one.
  • Programs opened and switched without importing; imports with any Ghidra loader,
    deduplicated by SHA-256.
  • Analysis, decompiling, renames, comments, saves, and GhidraScripts (Java or Python) with
    arguments; scripts on programs a client does not own run contained and are rolled back.
  • Fair scheduling (quick and long lanes, round-robin by client), one writer and many readers
    per program, per-client cancel, clean release when a client dies, idle shutdown, warm
    programs kept open for the next client.
• ghidra_session.py: a standard-library-only Python launcher, daemon manager and client
  (connect()), with no .bat or .sh launcher. Fast start with a class search cache and,
  on JDK 25+, an AOT cache.
• Tests: examples/session_smoke.py and examples/daemon_tests.py.
• Headless build (gradle buildHeadless, gradle/hydra/headless.gradle): an install
  without the window-only modules, the help, javadoc and Python stubs, and with a check that no
  module of the install depends on one it leaves out. The full build is still gradle buildGhidra.
• Repository: this README (Ghidra's original is README-GHIDRA.md), NOTICE-HYDRA, a
  security policy and contributor guide in .github/, issue and pull request templates, and CI
  (.github/workflows/ci.yml) that builds the headless install and runs both test suites.
• Releases (.github/workflows/release.yml): a tag v<version> builds the headless zip on
  Windows, runs both test suites on the unzipped install, and publishes the zip, SHA256SUMS
  and this file's section as a GitHub Release.

Branches

• main: the above, on upstream master.
• legacy-12.1.4: the same module on Ghidra 12.1.4, kept for projects analysed with 12.1.4.

Download and testing

Built by the release workflow from 83b082ca9931f7d870a0a3372f775e96c8c8b2b7, then unzipped and tested there.

File	Size	Built and tested on	Result
hydra-engine-12.3-hydra.1-win_x86_64.zip	361 MiB	windows-latest (Windows-2025Server, openjdk version "25.0.4.1" 2026-08-18 LTS)	built; session_smoke.py and daemon_tests.py passed on the unzipped install

SHA-256 (also in SHA256SUMS):

4102c5dffbb7e26a90adfd20e025b4a0dd461ae147179082fb112562f3af6c47  hydra-engine-12.3-hydra.1-win_x86_64.zip