Compatibility Matrix

The current published stable is v1.0.122. LumenFlow publishes its public npm packages together; use one matching version across a consumer repository.

Public packages

This table describes the current source release inventory. A package becomes available to install when a release containing it is published.

Package	Purpose
@hellmai/lumenflow-agent	Agent definitions and skill loading
@hellmai/lumenflow-cli	Command-line surface and setup tooling
@hellmai/lumenflow-conductor-sdk	Conductor event and handler contracts
@hellmai/lumenflow-control-plane-sdk	Control-plane transport and configuration contracts
@hellmai/lumenflow-host	Runtime host composition
@hellmai/lumenflow-initiatives	Initiative projections and planning support
@hellmai/lumenflow-kernel	Task, scope, policy, evidence, and pack primitives
@hellmai/lumenflow-mcp	MCP server, tools, and resources
@hellmai/lumenflow-memory	Session memory, signals, and checkpoints
@hellmai/lumenflow-metrics	Flow and delivery metrics
@hellmai/lumenflow-packs-agent-runtime	Governed agent-runtime pack
@hellmai/lumenflow-packs-app-backends	App backend contract, adapter SPI and conformance kit
@hellmai/lumenflow-packs-app-delivery	App build, submit and update job contract
@hellmai/lumenflow-packs-campus	Campus domain pack
@hellmai/lumenflow-packs-customer-support	Local ticket routing and unsent response drafts
@hellmai/lumenflow-packs-data-analytics	Local CSV/JSON structural quality checks
@hellmai/lumenflow-packs-protocol-adapters	Protocol-adapter pack
@hellmai/lumenflow-packs-reliability-operations	Read-only reliability investigation pack
@hellmai/lumenflow-packs-security-assurance	Local assessment of supplied unvalidated findings
@hellmai/lumenflow-packs-sidekick	Workspace productivity pack
@hellmai/lumenflow-packs-software-delivery	WUs, lanes, gates, and worktree lifecycle pack
@hellmai/lumenflow-runtime	Kernel runtime and scheduling services
@hellmai/lumenflow-shims	Git and process safety shims
@hellmai/lumenflow-surfaces	HTTP and other runtime surfaces

The upgrade command preserves the dependency sections and optional packages already selected by the consumer:

pnpm lumenflow:upgrade --latest
pnpm lumenflow:doctor

Runtime requirements

Surface	Minimum	Recommended	Notes
@hellmai/lumenflow-cli executables	Node.js 26.0.0	Node.js 26.8.1 Current	The published engine rejects earlier releases
Public library APIs	Declared package engine	Node.js 26.8.1 Current	Check the installed package manifest
pnpm	11.4.0	12.3.4 Current	Primary package-manager path
npm	10.0.0	12.0.2	Supported for local package installation

Caution

The scoped CLI package is not itself an executable because it exposes many named binaries. Install it locally, then run the injected pnpm lumenflow and pnpm wu:* scripts.

Current instead of LTS

LumenFlow intentionally tracks the current stable Node.js 26 line. Node.js 24 remains an LTS release, but consumers and CI use Node.js 26 so the published contract, generated workflows, and local development match the user’s selected latest-stable toolchain.

Operating systems

This section states the platform contract, not the state of any installation today. The contract is being implemented across the cross-platform initiative’s phases 2 to 5; until those land, verify actual behaviour on your own host rather than inferring it from this page.

LumenFlow’s platform contract covers Windows, macOS, and Linux natively, under one equal guarantee envelope: the same lifecycle results and evidence, the same enforcement of lifecycle hooks and generated CI, the same owner isolation for protected state and credentials, the same enforced-or-refused sandbox rule, the same Connected Compute availability rule, and the same literal performance ceilings with no per-operating-system multiplier. Differences between hosts are differences of mechanism — which confinement primitive, which secret store, which executable name — never a weaker promise.

Where a guarantee cannot be met on a host, the surface refuses and says why rather than proceeding unprotected. Reporting the posture in force on the running host is part of the contract. pnpm lumenflow:doctor prints a Sandbox Posture section that shows it.

Process invocation (implemented). Every LumenFlow-assembled argv-form pnpm, npm and npx spawn — across gates, prep, claim, dependency commands, doctor, upgrade, release, approvals, init, completion, recovery and the shims — resolves its executable through one shared helper before spawning, and never sets shell: true. On Linux and macOS the binary is passed through unchanged, so behaviour is byte-identical to before. On Windows it becomes either a resolved native executable or an explicit cmd.exe /d /s /v:off /c invocation whose argument string LumenFlow escapes itself, quoting and caret-escaping being two alternative forms rather than both at once. A shim that is not on PATH fails closed with a named error, and an argument carrying a line break is refused rather than escaped.

This does not cover the shell-string command paths that keep their shell treatment deliberately — operator-authored gates.commands.* entries and the release pipeline’s runCommand strings, where the host shell performs the lookup itself. A ratchet fails the build on any new bare package-manager spawn, including through exec/execSync, an already-resolved executable constant, an import alias, or a local exec-shaped indirection.

Windows behaviour is verified by platform-parameterized unit tests with injected host facts and by a round-trip model of the documented cmd.exe parsing stages. Neither is execution evidence: running on a real Windows or macOS runner is the cross-platform CI leg, which has not landed yet, so verify on your own host before relying on it.

Installed LumenFlow commands (implemented). When LumenFlow itself runs one of its installed commands — wu:claim’s check that a new worktree can run wu:brief, wu:edit and wu:prep, wu:done’s gate run in a consumer worktree, and wu:proto’s claim step — it finds the installed @hellmai/lumenflow-cli package by Node’s own node_modules lookup, reads the package’s bin entry, and runs that JavaScript file with the current Node executable. It never runs the package manager’s node_modules/.bin launcher, which is a shell script on Linux and macOS and a .cmd/.ps1 pair on Windows, where the extensionless file cannot be started at all. A ratchet fails the build on any shipped path into node_modules/.bin. When such a command cannot run, wu:claim reports the exact command, the operating system’s spawn error (for example EINVAL) or the exit code with the command’s output, and a remedy for the kind of repository you are in.

Shim entry guards and path semantics (implemented). The git and pnpm safety shims (@hellmai/lumenflow-shims) and the prompt-linter CLI entry each invoke main() behind import.meta.main rather than the older process.argv[1]-based comparison, which never matches on Windows because import.meta.url is a file:// URL while process.argv[1] is a native backslash path — the guard failed silently, exiting 0 having done nothing. Home-directory, PATH, and git/pnpm-executable discovery resolve per platform (os.homedir(), path.delimiter, a where/which lookup with a .cmd/.exe-aware target) instead of assuming POSIX. Both copies of resolvePlanFile (--file, initiative related_plan) recognize a Windows drive-letter or UNC absolute path, not only a leading /. The gates-latest.log convenience pointer falls back to a plain file copy when symlink creation is denied (the expected shape on an unprivileged Windows account), instead of silently reporting failure.

Access principal encoding (implemented). The access boundary limited to the file owner accepts any real Windows account name when building the icacls access-control entry, including one containing a space — the Windows OOBE default account name is a two-word “First Last” such as “John Smith” — a backslash (the DOMAIN\user form), parentheses, or non-ASCII characters. The principal is embedded verbatim, never hashed or replaced with a synthetic token, because icacls must resolve a real account to grant it access. Only characters that would make the access-control entry’s own grammar ambiguous or exploitable are refused: the : delimiter the port injects, a comma (icacls’s multi-grantee separator), an asterisk (its wildcard/SID marker), a double quote, and a forward slash (its flag prefix) — none of which ever appears in a real Windows account name.

wu:recover reconcile postconditions (implemented). The private-file checks in the reconcile recovery path used to assert exact POSIX mode bits with no Windows branch, so they refused unconditionally there — Node reports a fixed mode/uid pair for every file on Windows, never the bits the check needed. These postconditions now route through the same owner-isolation port: unchanged mode-bit checks on Linux/macOS, and on Windows an apply-and-verify call to restrictToOwner() instead of reading mode bits Node cannot make meaningful there. A DACL refusal still fails the postcondition closed with a named error; there is no silent skip.

Micro-worktree privacy postcondition (implemented). lane:setup, wu:claim, wu:prep and every other command that creates or inspects a micro-worktree used to refuse with “Refusing to normalize a non-private micro-worktree artifact” on every Windows host, because Node synthesises st_mode on win32 from the read-only file attribute alone (a read-only file — including git’s own object files — reports 0o444, which the POSIX-only check misread as insecure). The check now never reads mode bits at all on win32: the micro-worktree lives under the user’s own temp directory, whose ACL is already per-user by default there. POSIX behaviour — including refusing a genuinely group- or world-readable artifact — is unchanged.

Control-plane credentials and agent session proofs (implemented). After cloud:connect, every load of the host enrollment used to fail on Windows with “Host control-plane enrollment is invalid”, and re-running cloud:connect could not fix it. The same problem made every agent session proof read as absent. Both checks refused a file whose permission bits looked group- or world-readable. On Windows those bits are not real: Node reports 0o666 for any writable file there, whatever its ACL. On Windows these checks no longer read permission bits. The files are instead protected when they are written, with the same access-control list limited to the file owner described above: the secrets directory, the token file, the enrollment directory and record, and the private session-proof directory. cloud:connect now reads the enrollment and the token back before it changes workspace.yaml. It fails with the cause, instead of reporting success, when they do not load. It also prints which owner-isolation mechanism it used (posix-mode or windows-dacl). Linux and macOS behaviour is unchanged: a group- or world-readable token file or enrollment record is still refused.

Generated consumer scripts (implemented). A package.json script that names only a bin (for example "wu:create": "wu-create") resolves through pnpm’s auto-generated node_modules/.bin/wu-create.cmd shim on Windows. That shim wraps the invocation in an IF EXIST ( ) ELSE ( ) block; once an appended argument contains a literal ) — a WU title with a parenthesised WU number, which is routine — the ) closes the block early and the rest of the command line runs malformed. lumenflow init, lumenflow:upgrade and lumenflow:integrate now generate every script as a direct node node_modules/@hellmai/lumenflow-cli/<dist entry> invocation instead, which never routes through that shim.

MCP protocol compatibility

Surface	Certified protocol	Legacy posture
@hellmai/lumenflow-mcp stdio	2026-07-28	Rejected by the served LumenFlow configuration
Authenticated Streamable HTTP	2026-07-28	Rejected; modern requests are stateless
TypeScript SDK v2 integration	2026-07-28	Explicit compatibility is available downstream
LumenFlow v7 release evidence	2026-07-28 only	Legacy connections are non-certifying

LumenFlow-owned clients pin the certified revision and fail closed on downgrade. Modern discovery is server/discover with per-request metadata and headers; it does not use initialize or Mcp-Session-Id. LumenFlow’s ordinary task_* tools are not the io.modelcontextprotocol/tasks extension, which is not advertised.

Workspace configuration

Current workspaces have two distinct lane surfaces:

• top-level lanes are kernel LaneSpec entries with scope permissions;
• software_delivery.lanes.definitions are delivery lane definitions with names and code paths.

Use pnpm lane:create, pnpm lane:edit, and pnpm config:set rather than copying a legacy flat configuration or hand-editing workspace.yaml. See Workspace Spec for the complete current shape.

Gate preset compatibility

Preset	Primary tools
node	Prettier, ESLint, TypeScript, Vitest or the repository test script
python	Ruff, mypy, pytest
go	gofmt, golangci-lint, go vet, go test
rust	rustfmt, clippy, cargo check, cargo test
dotnet	dotnet format, build, test
java	Spotless, Checkstyle, javac, Maven or Gradle/JUnit
ruby	RuboCop, Sorbet, RSpec
php	PHP-CS-Fixer, PHPStan, Psalm, PHPUnit

The repository’s configured commands remain authoritative. Run pnpm gates to verify the actual consumer configuration.

Version support

Major line	Status	Recommended action
7.x	Current	Stay on the latest published patch
6.x	Upgrade path	Run pnpm lumenflow:upgrade --latest and review migration output
5.x and earlier	End of life	Upgrade through 6.x migration guidance, then to current

v7 requires Node.js 26 and pnpm 11 for the primary CLI path, removes the deprecated @hellmai/lumenflow-core package, adopts Pack Contract v2 and signed OCI distribution, and tightens web, process, credential, registry, and lifecycle security boundaries. Read the v7 changelog before upgrading automation that depends on package paths, pack transport, or legacy gate configuration.

Release-specific breaking changes and migrations live in the Changelog. Do not infer current behavior from an old major’s configuration examples.

Agent hosts and repository access

LumenFlow supports any agent host that can read LUMENFLOW.md and invoke the public CLI or MCP surface. Host-specific instruction files and hooks are project-owned, not versioned LumenFlow interfaces. Git hosting permissions determine who may clone or push; LumenFlow only requires an attributable local Git identity for governed work.

Lifecycle enforcement remains provider-neutral: repository-owned delegators protect the manifest, receipts, journals, hooks, and managed CI block, while lumenflow:doctor exposes their compliance state. Only enforced is certifying; disabled, missing, stale, tampered, unavailable, or uninstalled consumers cannot claim certification.

Verify an installation

node --version
pnpm list @hellmai/lumenflow-cli
pnpm lumenflow:doctor
pnpm lumenflow:commands