Skip to content

v4.1.0 — X4 AI Assistant Toolkit

Choose a tag to compare

@WingedGuardian WingedGuardian released this 05 Nov 16:48
· 407 commits to master since this release

v4.1.0 of the X4 AI Assistant Toolkit keeps your derived data current without you asking, adds new ways to see where a value or a saved variable comes from, and tightens what the guards watch. Released 2026-11-05 (the CHANGELOG heading reads 2026-11-04).

Claude Code and Codex remain the first-class integrations. OpenCode is best effort. The guards read known command forms; they are not a sandbox.

What changes for you

Your saves and profile

  • Save sentinel. After every tool call it reports any save that was modified or removed with no backup taken first, whatever changed it, including scripts the pre-call guard cannot read. It never blocks. It guards against accidents and careless scripts, not a determined attacker.
  • Save locks cannot be turned on in this version. save-lock on and setup.sh --save-lock refuse and change nothing. A lock also binds X4 itself, so you could not save over a locked save, and Windows permissions cannot tell X4 and agents apart. If you hold locks from an earlier development build (not a public release), python tools/agent-harness.py save-lock status|off|unlock still work; off and unlock need an elevated prompt. Saves stay protected by the guards, the backup taken before a save is changed, and the sentinel.
  • Agents ask before every game launch or restart they start, naming the game, mode, desktop and test profile or save. Earlier approvals and "continue" do not count.
  • Fewer repeat prompts for the mod list. Editing the profile's root content.xml (enabling or disabling a mod you asked to install) no longer asks a second time. Deleting it, other profile files and saves still ask. A move onto content.xml still asks, because it also removes its source.
  • Deleting a deployed mod asks once per command, naming every mod the command touches. Deleting the install itself or extensions/ wholesale, and reference/, stay blocked.
  • A typed file deletion of a deployed mod folder or ordinary XML now asks instead of being rejected as a direct edit of the deployed copy. Direct writes, write-only batches, explicit moves, archive protections, save preservation and whole-install/reference blocks keep their prior policy.
  • Guards read more indirect commands: deletes or writes handed to another program such as watch, wsl, tmux, ssh to this machine and similar runners, and creating a junction or link into a protected folder is refused. A list of runners cannot be complete; see the limits below.
  • Codex: a profile XML edit the guard asks about can be approved once with a printed PROFILE_EDIT_APPROVAL <digest> line (24-hour expiry, used once, refused if the file changed). Details are in docs/profile-edit-approval.md in the repository and the release zip.

Keeping derived data current

  • x4fresh prints one verdict per derived store (effective store, xref index, BaseX x4raw and x4eff): FRESH, STALE, UNKNOWN, MISSING, REBUILDING or NOT-BUILT, plus what the last build could not include. x4fresh rebuild rebuilds what is not fresh; x4fresh accept records losses you understand so they stop repeating.
  • Background rebuild at session start (Claude Code and Codex) for the effective store and xref index. It waits while X4 is running. The BaseX databases are only reported, never rebuilt unattended. To stop it, set X4_FRESH_AUTO=off.
  • A mod edited while a build runs no longer reads FRESH afterwards.

Investigating mods and saves

  • x4effective dump <vpath> --annotate marks every node an overlay changed with a comment naming the mod, op and patch line, and lists removals. It reports who won each node, not who introduced it; after a whole-file replace no node is annotated. (#15)
  • x4save vars <pattern> [save] lists named variables matching a regex, such as MD cue variables, with where each lives. Tables, lists and groups are shown as table#<id>, list#<id> and group#<id> and are not expanded or searched. A no-match result names what was not searched. Only gzipped *.xml.gz saves are read. (#16)
  • x4effective find TEXT looks entities up by the name the player reads.
  • x4effective dump on a bare path to a file only a DLC ships now returns the document mods actually patch, with a note. It used to return the unpatched file with no warning (588 of 716 patched DLC documents on the development machine).
  • x4diff now compares each mod's content.xml, and --file accepts ./path, backslashes and absolute paths. It used to say "no differences" for a manifest whose version had changed.
  • x4modlist downloads DIR... reads manifests inside downloaded .zip, .7z and .rar files without extracting them and compares them with what is installed. It also warns about a profile entry turning an id off, a same-name mod under a different id, a test profile that would load the mod, and merged icon totals past what one install was measured to load. .7z and .rar need 7-Zip. It exits 3 when any archive was unreadable.
  • x4modlist refresh --dry-run shows which rows a refresh would fetch, search for or skip, with no network, key or write.
  • Experimental: x4similar --geometry and --geometry-audit compare ship render surfaces. Real-hull thresholds and runtime poses are not qualified. Needs the optional geometry extra (see tools/x4validate/docs/GEOMETRY.md).

Disk housekeeping

  • Retention follows a certainty rule. Age, size and file names only trigger a review. Housekeeping retires a payload only when it re-proves an identical retained copy or you declare those exact bytes obsolete.
  • Rebuildable BaseX caches are now deleted permanently, with no backup and no Recycle Bin copy. This reverses v4.0.0 for these caches only. Everything else housekeeping removes still goes to the Recycle Bin or stays.
  • Optional cold backup vault and task archiving in x4housekeep (off unless configured in your private x4-housekeep.json).
  • The session-start note warns when the Recycle Bin is large (default over 10 GiB).

Working across sessions

  • Session charter and ledger: a session's first prompt is recorded as its origin, and agreed work is tracked in a ledger that is shown at every session start.
  • find-session skill finds the past Claude Code or Codex session where something was discussed. It needs obra/episodic-memory installed separately.

If you make mods

  • x4-mod-release-review now ends with the whole upload pack in one folder, and scripts/verify-mod-pack.py refuses a pack with a missing or empty file, <br, an HTML entity, CRLF, a header line in a paste file, a changelog line over 120 characters, or an archive that differs from the manifest.

Fixes

  • x4save vars | head and x4effective ... | head end quietly when the reader closes the pipe, instead of reporting a broken save or a traceback.
  • Save sentinel: a save that vanishes mid-scan is the only one reported lost; a record locked by another session no longer causes a false "record lost" alarm; a denied save folder no longer stops every look.
  • x4housekeep no longer treats an unreadable live-work source as "no live work".
  • The test suite now passes on an installed toolkit.
  • Upgrade previews report why they failed and exit 2, and a default apply no longer creates a config the install never had.

Upgrading to 4.1.0

  1. Rerun the installer with --over-existing (-OverExisting in PowerShell). Local notes, x4-paths.env and .claude/settings.local.json stay in place. If you edited .claude/settings.json, use the reviewed upgrade-stage / upgrade-apply workflow in ADAPTING.md.
  2. The effective store and BaseX x4eff read STALE until rebuilt once. Session start rebuilds the store and xref index; rebuild BaseX yourself with x4fresh rebuild.
  3. The first rebuild reports known losses and x4fresh status exits 3 until you run x4fresh accept once. Nothing failed: truncated property subtrees are now listed by name.
  4. If you use x4housekeep: run python scripts/x4housekeep.py version and record the new digest in approved_sha256. The hold on folders with a running job now applies only if job_ledger names a resource-job ledger.
  5. Upgrading from 3.x: read the 4.0 upgrade notes first (config location, edited CLAUDE.md).

Known limits

  • The guards judge a shell command by how its path is written. A write through an existing link, Windows admin-share and Cygwin spellings, and programs that run a command string inside themselves (awk system(), os.system, find -exec bash -c, docker, systemd-run and others) are not read. The full list is in the "Known gaps" section of the CHANGELOG.
  • The sentinel decides "the game wrote this" from two signs and cannot separate writers inside that window. The signs were measured from file stamps; no game session was run.
  • No CI timing exists yet for the fix to the slow 3,589-path file check (BLIND-SPOTS F340).
  • The elevated save-lock unlock was not run end to end for this release.
  • Closed-pipe handling covers x4effective and x4save only; 10 of the other console tools still exit 120 for --help into a closed pipe.
  • Windows is the primary environment. OpenCode does not run a session-start hook, so it has no background rebuild.

Full details and evidence: CHANGELOG.

Independent fan project. No Egosoft game data, AI model or subscription is bundled.

Validation and release asset

  • CI: run 41992260237 on 03135fd9, all 14 jobs green on attempt 2. Attempt 1 failed one parser test on a PowerShell translation timeout and the cold-archive leg on a runner disk quota; both passed when re-run on the same commit, so both are recorded here as intermittent, not as a clean first pass. Tests: Ubuntu 7,501 passed, 418 skipped; Windows 7,943 passed, 64 skipped; installed copy 6,522 passed, 891 skipped; cold archive 7,287 passed, 486 skipped; 0 failed in each.
  • Tag: v4.1.0 at 03135fd92b3afbc7430861abe2e419a15852515d
  • Archive: X4.Foundations.AI.Assistant.Toolkit-v4.1.0.zip, size 11,455,570 bytes, SHA-256 facbd602b6a3894ad2b5a778445db3cb6a7db24419ea9154911427edc8224c1c