Changelog

This is the narrative changelog, grouped by release theme. For the generated per-release feed (one entry per release tag, current release line first, showing the version and date), see the auto-generated changelog.

The current published stable version is v1.0.122. All @hellmai/lumenflow-* packages ship together; see the Compatibility Matrix for Node.js and package-manager support.

v1.0.0 — v1.0.3: the 1.0 relaunch

v1.0.0 is a relaunch, not a continuation of the v7.x line. LumenFlow moved from the public @lumenflow/* npm scope to @hellmai/lumenflow-*. Packages are distributed through a private, licence-gated registry under free or paid licence grants. GitHub holds source only and no longer carries an installable release. Published JavaScript contains no TypeScript source, source maps or test files, and is minified before publish. Access control is the licence gate, not the artifact’s readability.

See private distribution for how packages reach licensed developers.

Why the numbering reset. v1.0.0 marks the new package scope and private distribution model, not a downgrade from v7. It is the first version published under @hellmai/lumenflow-*, and the old public @lumenflow/* v7.x line never carries that scope or that access model.

v1.0.0 — the relaunch

Released 23 Sep 2026. The first version published under the new scope and distribution model. A licensed developer can install and run it from the private registry. Anonymous or revoked access is denied before any file reaches a machine. The published archive contains no .ts source, source map or test file. Supported targets are Windows, macOS and Linux. The Linux new-developer path was proven end to end. Native Windows and macOS install proofs were pending at this release (see v1.0.1 below).

v1.0.1

Released 23 Sep 2026. A same-day follow-up with 23 changes, mostly native-platform and lifecycle-robustness fixes found immediately after the relaunch:

• Native Windows consumers could not set up lanes or create WUs. This is fixed. A tri-platform lifecycle proof was added. Its Linux leg ran, and its Windows and macOS legs were pending.
• The CLI now obtains and renews its own signed licence from the registry sign-in, so a consumer no longer re-downloads a licence file by hand.
• wu:rebase --continue no longer aborts with a generic message after a resolved content conflict. It is no longer refused by git when a LumenFlow write dirties the tracked ledger mid-rebase.
• lumenflow:doctor no longer exits 1 against LumenFlow’s own repository. lumenflow:commands recovered a 50.6 percent regression against the pre-relaunch baseline.
• A dead claim now releases its lane slot only on host-independent evidence. wu:prune no longer errors on a detached scratch worktree. wu:repair --admin --status now writes its ledger event.
• Claim-to-done phase timing now accounts for holds and silent claims, instead of counting that time as idle.
• State writes never leave the working tree dirty. A path-safety check blocks committing governed ledger entries that snapshot a WU mid-write.
• wu:edit --notes accepts two --notes flags in one invocation instead of dropping one. The package-manager spawn check resolves identifiers, ternaries and renamed imports it previously missed.
• main:sweep runs as a named gate, so a landing that would break a swept file cannot land. The handoff-receipt contract was proven at every edge case tested.
• A freshly initialised consumer no longer fails format:check on LumenFlow’s generated output.
• The release verification report for the relaunch was recorded. An unhelpful error from the manifest script builder, which blocked the 1.0.1 cut, was fixed.

v1.0.2

Released 24 Sep 2026. Almost entirely documentation-truth and new-developer-path fixes. Several Starlight and arc42 pages had drifted from what the code does, and the new-developer path had commands that failed on a first run.

• Starlight pages were corrected to match the code, including the software-delivery overview. arc42 pages, ADRs, the agent framework docs and the shipped templates were brought back into parity with the code.
• docs:validate no longer reports success while the CLI reference generator silently drops content. The wu:rebase reference page gained its missing generated options table.
• The new-developer path: a new pnpm init project no longer fails its first gates on a placeholder test. A fresh consumer’s first-read instructions no longer give commands that fail. lumenflow:upgrade no longer refuses every pnpm-initialised project with a false “private registry” reason. lumenflow init no longer writes project files before its git-identity refusal.
• wu:create --validate now creates and pushes a real WU instead of performing a dry run. wu:edit --notes keeps working under lane validation, and lane validation no longer demotes a locked lane and silently blocks every claim in it.
• workspace.yaml no longer disagrees with itself about the two lane planes for the docs lanes.
• Governed commands run inside a claimed worktree no longer dirty the tracked WU ledger. The file-contention check reads the claimed WU’s real scope. A gate failure summary no longer prints misleading wording.
• A release smoke check for devEngines routing, which failed on every real release run, was fixed.
• The wu-sizing guidance now includes design-first as step 0, with no configuration toggle.

v1.0.3

Released 29 Sep 2026. The largest patch in the 1.0 line, with about 50 wu:done landings. Three threads dominate.

Agent confinement. The confinement tiers are documented precisely. Claims about complete mediation are scoped to what is actually mediated. On Linux, the release adds a sandbox engine for command-mode confinement, opt-in boxed agent sessions, and an egress allowlist that reaches only host-configured destinations through a confined proxy. The proxy’s added per-connect latency was reduced. wu-sandbox --box runs the harness on a slow first start. A fresh build no longer waits silently at 0% CPU for up to 30 minutes in an affected environment.

Mixed-version lifecycle compatibility, for consumers upgrading across the 1.0 line:

• wu:done and wu:recover accept a prior-version handoff receipt and name any refusal precisely.
• The upgrade bridge’s source-import scan reaches imports outside the source folder. Half-migrated consumers with legacy runtime imports are covered.
• Published @hellmai/lumenflow-* packages depend on each other at exact pinned versions instead of a range, so a mixed-version install cannot happen.
• The upgrade dry run’s count of skipped source-import-protected files is corrected.
• wu:recover gained --action retire for a released, cancelled or done WU. On that path, only a durable tag is accepted as proof.

Everything else is a set of main-branch repairs and test fixes made while landing the above. Among them:

• wu:claim no longer crashes from an import-time error.
• wu:create and wu:edit repeatable flags no longer corrupt text with literal backslash-n sequences.
• Several maintenance scripts honour --help and -h instead of running their default action.
• mem:signal stamps every signal with the real acting session.
• Dead software-delivery configuration keys were retired.
• Go and Java presets work end to end.

Security. config:set and config:unset validate keys more strictly. Upgrade to 1.0.3 or later.

v1.0.4

Upgrade note: your own packs declaring a v6-era kernel/host range. From 1.0.4, kernel start checks every pack against the kernel’s real version instead of a stale 6.1.6 default. A local pack made by pack:author or pack:scaffold up to 1.0.3, or during the 6.x era, declares ^6.0.0 and would be refused. lumenflow:upgrade to 1.0.4 rewrites that range to ^1.0.0 in each source: local pack’s manifest.yaml, refreshes the pack’s integrity pin, and prints and commits each change. It stops before changing anything if a local pack declares any other unsatisfied range, and it names the file, field and range. See lumenflow:upgrade.

v1.0.5 — v1.0.108: the 1.0 line by theme

Releases 1.0.5 (30 Sep 2026) to 1.0.108 (26 Oct 2026) are summarised here by theme. Tag 1.0.106 exists only as a commit and has no tag. Each version number in brackets is the release that first shipped the change.

Release and upgrade safety

• Patch releases are cut from a fixed commit and publish faster. A cut runs no sweep (1.0.13), and the cut smoke runs from that commit (1.0.15).
• A red post-landing sweep raises a release incident at once (1.0.17).
• The upgrade bumps every tracked package.json that pins @hellmai/lumenflow-* (1.0.16).
• A claim made under the previous release carries across the upgrade (1.0.11).

Claims, lanes and recovery

• Stale claim markers are superseded through a governed path (1.0.46 and 1.0.48).
• A claim publication refused by a git hook is classed as rejected, so repair can retry it (1.0.49).
• wu:repair --claim restores a missing claim marker for the holder (1.0.15).
• A blocked claim whose holder session has ended is handled (1.0.56).
• A lane with no wip_limit or lock_policy takes no lane lock (1.0.70).

Sandbox and confinement

• The Linux sandbox forwarder is found in an installed consumer (1.0.8).
• Per-invocation loopback grants are accepted (1.0.20 and 1.0.21).
• The host exposes a public confined command runner (1.0.27).
• On Linux, tool launches add a filesystem confinement layer where the host supports it (1.0.108).

Security. A sandbox environment exposure is fixed (1.0.46). Upgrade to 1.0.46 or later.

Agent runtime and governed loops

• Consumers run a whole agent loop on runGovernedAgentLoop (1.0.22).
• agent:launch runs a captured external agent CLI adapter under host governance (1.0.18).
• Embedded assignments can enforce USD budgets (1.0.17).
• Governed web:search and web:read tools sit behind a host-supplied search provider (1.0.31).
• A governed agent can drive one browser session across many steps (1.0.42).
• The lumenflow_cloud provider kind routes agent turns through LumenFlow Cloud governed inference (1.0.45).
• Prompt caching: messages_compatible profiles place cache control on the system and tool blocks (1.0.35). Automatic prompt caching places a rolling breakpoint on the last message (1.0.107).
• Usage input_tokens means the whole prompt on every provider route (1.0.41).

Control-plane SDK and Cloud contract

• Every key-callable Cloud route family is a typed, generated client (1.0.31).
• The model-config client covers list, put, remove and test (1.0.55).
• A delivery outbox gives at-least-once ordered delivery with idempotency keys (1.0.28).
• Generated SDK response schemas no longer fail on an additive hosted enum value, such as a new cost basis (1.0.59).

App backends and delivery jobs

• The app-backends pack has a provider-neutral backend contract (1.0.30), a standalone verifier and plain-Postgres importer (1.0.36), and adoption of an existing Postgres backend by connection reference (1.0.45).
• The delivery pack publishes a provider-neutral app build, submit and update job contract (1.0.43).

Licence and first run

• lumenflow:doctor reports an expired registry licence (1.0.72).
• First run asks you to accept the licence terms.

Escalation and human approval

• A sensitive-data escalation detected at wu:prep or wu:done now gates the landing (1.0.40).
• wu:escalate --resolve accepts only a verified human resolver identity (1.0.95).
• Approvals and enforced human escalation require authenticated human identities (1.0.108).

v7.0.0 — Governed execution, security closure, and faster delivery

Released 25 Aug 2026. v7 is a major release that aligns the public package family on one governed execution contract. It adds launch-quality hardening, Campus EMIT completion, trajectory supervision, gate-cycle economics, and a closed dependency boundary.

What changes for consumers

• Node.js 26 and pnpm 11 are the primary supported CLI toolchain. All published packages must use the same v7 version.
• The deprecated @hellmai/lumenflow-core compatibility package is removed. Import from the owning public package and run pnpm lumenflow:upgrade --latest before the first v7 WU.
• Pack Contract v2 and signed OCI distribution make digest, signature, SBOM, provenance, namespace ownership, quarantine and exact-digest readback part of the pack trust boundary.
• Security. Web workspace operations authenticate before any access and stay bound to the caller’s workspace. Upgrade to v7.
• Connected Compute refuses remote cleartext bearer transport. It takes tokens from an environment variable (--token-env) instead of the command line, so credentials stay out of the command line and shell history.
• New installs derive a safe path-scoped test_incremental when project evidence supports it. Safety and normal tests share one execution, uncovered changed code gets one related sweep, and unchanged prep checkpoints are reused by wu:done.
• Full tests remain fail-closed for unsafe or missing scope, test configuration or untracked changes, failed change detection, main-snapshot comparison, or an explicit --full-tests. Fresh completion checks remain separate.

Operations and release posture

• Releases refuse an unverified main branch. The Reliability Operations pack is published as signed OCI with SBOM, provenance and exact public readback.
• Gate runs report all applicable failures, scope builds to the affected packages, and use bounded concurrency.
• Append-only gate-attempt evidence and trajectory stagnation and thrashing signals let orchestrators redirect unproductive loops, without prescribing a model, vendor or automatic termination.
• Campus reads use persisted state. GPU attestation emits verified quote evidence. The EMIT energy contract is shared across SDKs.

Upgrade checklist

1. Install Node.js 26 and pnpm 11, then run pnpm lumenflow:upgrade --latest.
2. Replace every @hellmai/lumenflow-core import using the generated migration guidance.
3. Review workspace.yaml gate commands and keep the generated test_incremental distinct from test_full.
4. Reinstall or pin packs through the governed v2 and OCI path, then run pnpm lumenflow:doctor.
5. Update Connected Compute enrolment to --token-env. Use HTTPS, except for explicit loopback development endpoints.
6. If you host the local workspace web runtime, set LUMENFLOW_WEB_CLI_ENTRYPOINT to the absolute, host-owned pack-install.js entrypoint. Pack install fails closed when it is absent or relative.
7. Run one complete wu:prep and wu:done cycle, and preserve any project-owned fresh completion checks.

v5.18.0 — Model-agnostic fleet lifecycle safety

Released 14 Jun 2026. v5.18.0 is a fleet lifecycle safety release. It protects active agent work from concurrent cleanup, adds a non-destructive restore path for missing active worktrees, reconciles stale delegation rows against WU records, and makes broad review and audit work first-class in WU sizing.

This is a minor release because it changes public workflow behaviour and recovery guidance without breaking existing WU specs.

What shipped

• Active and recent WU leases block wu:prune --execute. Recoverable tracked removals write quarantine audit evidence under .lumenflow/quarantine/worktrees/cleanup.jsonl.
• wu:recover --action restore recreates a missing active worktree from the lane branch without resetting WU status, branch, baseline metadata or completion evidence.
• orchestrate:monitor reconciles delegation rows against WU records, done stamps, execution evidence, launch records and signals before it treats work as pending or stuck.
• flow:bottlenecks and flow:report surface actionable cycle and lane-contention diagnostics.
• review-audit is accepted as a sizing exception for broad, read-heavy audits.
• Initiative plan linking safely publishes local plan bodies. Skip-setup worktrees discover nested package manifests before they project package-level node_modules links.

Architecture and docs

Lifecycle authority comes from WU, lane, session, lease, branch, worktree, stamp and audit evidence. It does not come from provider names, model names, hosted runners, client UIs or plugins. The public Fleet Lifecycle Authority page describes this contract.

Pack decision

No new pack is introduced in this release. Fleet lifecycle safety belongs to the kernel and the Software Delivery Pack lifecycle, because it governs every WU. Migration guidance: use governed restore, quarantine and reconciliation flows instead of raw Git worktree cleanup or destructive reset and reclaim recovery.

v5.17.0 — EMIT energy telemetry and provenance

Released 13 Jun 2026. v5.17.0 adds the EMIT energy side of the platform. LumenFlow now has one shared emit:energy_meter_recorded event contract for joule observations across kernel runtime, SDKs and pack emitters.

This is a minor release because it adds a new observation surface without breaking existing EMIT streams.

What shipped

• Shared SDK types, schemas and fixtures for measured, modeled and facility energy rows.
• Connected compute device support for joules measured through hardware-facing meter classes, such as GPU telemetry, Linux powercap, IPMI and Redfish power distribution interfaces.
• Managed inference modeling for per-run token energy, where provider platforms expose usage but not meter-level joules.
• Campus Pack facility allocation through facility_energy, pue_applied and provenance fields, without mixing carbon attribution into the kernel event.
• A neutral, observation-only event contract across live builders, SDK contracts, fixtures and docs.

Architecture and docs

The meter axis and provenance contract are described on the public EMIT energy page.

Pack decision

No new Energy Pack is introduced in this release. Run-grain connected compute energy belongs in the shared EMIT kernel and SDK surface. Facility allocation stays with the Campus Pack. Hosted attribution, carbon factors, proof assembly and billing are outside the released packages.

v5.8.11 — Kernel hardening

Released 22 May 2026. v5.8.11 is the first release of an architectural sweep. It closes classes of bugs at compile time, makes the kernel vendor-agnostic in code, and decomposes the largest files in the repository. v5.8.4 through v5.8.10 were tagged but never published. v5.8.11 is the first tag in this series to ship all 17 @hellmai/lumenflow-* packages to npm.

If you held back from upgrading because the framework felt internally inconsistent, this release tightens those internals so they cannot regress.

Kernel hardening

• Lifecycle writes go through a single path that pushes only to the remote. Writing to the wrong checkout is rejected at compile time.
• Infrastructure calls in the kernel go through a small set of replaceable ports: clock, process execution, environment, telemetry and randomness. Typed domain errors replace generic ones.
• The largest framework modules were split into focused modules. File-size and architecture rules are checked in CI, so later changes cannot grow them back.

Migration notes

• @hellmai/lumenflow-core removal. Its 23 subpath exports were deprecated in v5.8.11. The package was removed in v7. See the migration guide.
• v5.8.11 had no runtime breaks. At that release, the @hellmai/lumenflow-cli package, the @hellmai/lumenflow-core root barrel and the MCP coordination APIs remained unchanged. v7 later removed @hellmai/lumenflow-core.

Note

Versions v5.8.4 through v5.8.10 are stale tags. Use v5.8.11 or later.

Conductor-mode kernel surfaces (v4.24)

Released 18 Apr 2026. Ten changes across five phases. The kernel’s outbound sync stream moves from a 3-kind lifecycle stream to a 14-kind tagged-union event contract. The release also adds a scope-gated tool surface and an agent-host reachability registry. External control surfaces can now drive LumenFlow orchestration remotely, without reading agent-local files.

• SDK contract. The delegation registry, the WU event mirror and a tagged-union kernel event type with 30 variants. The schema version is 2.
• Emitters. A builder for the 14 conductor event kinds, with event ids for idempotency.
• Inbound control surface. A GET /tools discovery endpoint with pack-aware metadata. Per-tool auth scopes on POST /tools/:name, capability-scoped tokens, and a 403 missing_scopes response.
• Reachability and sync. Agent-host enrolment registers a reachable URL and a reachability class (reverse-tunnel, public, lan or unreachable). The control-plane event subscriber runs in sidecar mode, so sync is sub-minute, driven by control_plane.sync_interval.
• Conductor emissions. Narrow emissions for next safe actions and capacity snapshots are shown in orchestrate:init-status.

v4.23 — Orchestration becomes its own feature area

Released Apr 2026. Three changes complete the orchestration control-plane work. Orchestration docs move to their own top-level section. Reconciliation covers capacity and integrity. The control-plane SDK becomes the single contract every surface speaks.

• The orchestration contract is unified in @hellmai/lumenflow-control-plane-sdk. The CLI, MCP and tests import the same shapes.
• /orchestration/ is a top-level Starlight feature area with pages for the overview, lifecycle, state machine, artifact bundle, capacity and integrity, and the SDK.
• Capacity and integrity evidence feed reconciliation. Orchestration refuses to advance on contaminated or over-capacity workspaces.

v4.22 — Evidence-based control plane lands

Released Apr 2026. Most of the control-plane work ships. The evidence-based control-plane state model is ratified. Launch receipts become durable artifacts. A 10-state classifier replaces the collapsed in_progress status. MCP coordination tools expose the same JSON the CLI writes.

• One initiative state model, with many launchers.
• Launch receipts and logical-wave artifacts persist for initiative orchestration.
• Orchestration status reconciles from execution evidence.
• Reconciliation, integrity checks and capacity-aware advancement.
• The orchestration state contract is published in @hellmai/lumenflow-control-plane-sdk.
• The orchestration JSON is exposed through MCP coordination tools.
• Orchestration docs and templates are updated for the evidence-based control plane.

Earlier releases

For the full history from v1.0.0 onward, including patch releases and version-alignment bumps, see the auto-generated changelog. Every release tag is listed there.