Skip to content
LumenFlow

Private distribution

LumenFlow ships privately, through a licence-gated registry, to licensed developers on Windows, macOS and Linux. There is no public npm package and no GitHub-hosted installable release. GitHub holds source only.

Private licence registry and licence grants

Section titled “Private licence registry and licence grants”

@hellmai/lumenflow-* packages resolve from the registry URL in your licence grant, under a free or paid licence. You authenticate with the credential supplied with the grant. The non-secret project scope mapping is @hellmai:registry=<registry-url>. Anonymous and revoked access is denied at the registry, before any package content reaches a machine.

The exact-archive guard

Section titled “The exact-archive guard”

Every published npm tarball is checked before upload against an exact archive contract: no TypeScript source, no source maps (.js.map, .d.ts.map), and no test files. This is a mechanical, fail-closed check that runs as part of the release. A tarball that fails the check does not reach the registry.

The minify stage

Section titled “The minify stage”

The last release stage before publish transforms every implementation JavaScript module with whitespace and syntax minification and identifier mangling. This is readability friction, not an access control. It is not a security boundary. The licence gate and the runtime licence check are the controls.

Supported platforms

Section titled “Supported platforms”

The published product runs on the supported Node 26 line on Windows, macOS and Linux. Minified JavaScript runs on any Node build within the supported major line on these three platforms.

The runtime licence check

Section titled “The runtime licence check”

The runtime licence check runs at execution time, on top of the download-time control that the registry provides. A licence that has expired or been revoked stops the product from running, not only from being freshly downloaded. --help and lumenflow:doctor always run. Every other command needs a valid cached licence. See Runtime licence check for the grace window and cache locations.

Workspace consumers

Section titled “Workspace consumers”

From 1.0.10, lumenflow:upgrade pins @hellmai/lumenflow-* to the exact target version in every workspace package that declares it. This covers the pnpm-workspace.yaml globs or the workspaces field, and each declaration’s own dependency section. After the install, the upgrade refuses before committing if the lockfile still resolves more than one version of any package in the cohort. lumenflow:doctor reports that split as an error.

To detect and repair a workspace upgraded by 1.0.9, see Workspace consumers.

Upgrading on main while claims are live

Section titled “Upgrading on main while claims are live”

From 1.0.10, pnpm lumenflow:upgrade from the main checkout can run while WUs are claimed, when it is a same-scope upgrade. Such an upgrade writes only package.json, the lockfile, workspace.yaml pack pins, managed docs, hooks and the upgrade marker. It never touches a claim, a lane branch, a claim worktree or a WU record.

An upgrade that migrates WU records, the state namespace, the workspace, legacy CI or source, or that bridges the package scope (the 6.x to 1.0 path), keeps the claim refusal described in Upgrade an existing project.

  • Before it publishes, the upgrade reads every live claim from one origin snapshot. A claim that is completing refuses the upgrade. Retry once it finishes. Claim data that cannot be read becomes a notice line, not a refusal. An unreachable origin still fails at the push.

  • After the install, the upgrade prints one block per live claim, with the commands the claim’s holder runs, in order, from its own session. Then wu:done runs from the main checkout as usual:

    cd <claim worktree>
node <main checkout>/node_modules/@hellmai/lumenflow-cli/dist/wu-rebase.js --id <wu-id>
pnpm -C <claim worktree> install --frozen-lockfile
pnpm -C <claim worktree> wu:brief --id <wu-id>
pnpm -C <claim worktree> wu:prep --id <wu-id>

  • A bound claim needs no policy refresh. The first step is the new release’s wu:rebase run from the claim worktree. The frozen install then moves the worktree onto the new release.

  • An upgrade that changes the pinned policy itself (the managed LUMENFLOW.md, or a policy key in workspace.yaml) stales every live pin, bound ones included. The upgrade then lists those claims under “Needs a policy refresh”. Their commands start with the main checkout’s wu:repair --claim --id <wu-id> --integration-target --refresh-policy, followed by the same rebase, install, wu:brief and wu:prep.

  • A claim made under 1.0.8 has no binding yet. It keeps one repair from the main checkout first: pnpm -C <main checkout> wu:repair --claim --id <wu-id> --integration-target --refresh-policy --reason "lumenflow:upgrade to <version>" --worktree "<claim worktree>".

  • The notice counts claims by class. A pin-valid claim is not finished by the upgrade. Its worktree still runs the older release, so it needs the listed wu:rebase and install before wu:prep and wu:done.

  • wu:prep and wu:done refuse a CLI release skew strictly. They print the rebase and install commands. When the lane branch already declares the running release and only the install is missing, wu:prep and wu:done run the worktree’s frozen-lockfile install and continue.

  • Cost: a bound claim pays rebase, install, brief and prep. A claim made before binding, or any claim across an upgrade that changed the pinned policy, pays one refresh more.

  • A completion that published before the upgrade is not failed by it.

  • --adopt-claimed-wu is not needed for ordinary upgrades.

Adopting a WU claimed under the previous release

Section titled “Adopting a WU claimed under the previous release”

From 1.0.10, a plain main-checkout upgrade prints the route for every live claim. The sequence below is the adoption route for an upgrade to 1.0.9.

A claim made before 1.0.9 has no claimed integration target binding. The new release refuses wu:prep until the claim is upgraded. The claim holder adopts it with the sequence below. It needs no git:sync-main, no force or override flag and no hand edit.

If your project pins the lifecycle package exactly, the main checkout still runs the previous release while the WU worktree already runs the new one. Run step 1 from the main checkout and steps 2 to 4 from the WU worktree.

# 1. Main checkout: replace the claim's dead session with a live one.
pnpm agent:session --wu <wu-id> --tier 2 --resume
export LUMENFLOW_AGENT_SESSION=<session_id from the resumed session>

# 2. WU worktree, with the same session exported:
cd <worktree-path>
pnpm wu:repair --claim --id <wu-id>
# 3. Prove and bind the original destination:
pnpm wu:repair --claim --integration-target --id <wu-id>
# The upgrade publishes the WU record to main, not to the lane branch: bring the
# lane up to date so wu:done does not see main changing the WU's own record.
pnpm wu:rebase --id <wu-id>
# 4. Continue as usual:
pnpm wu:brief --id <wu-id>
pnpm wu:prep --id <wu-id>   # then run the wu:done it prints
  • wu:claim publishes the claim without moving the main checkout, so main can still hold the pre-claim record. Session resume, claim repair and the upgrade read the claim at the integration tracking ref.
  • Run from a WU worktree, wu:repair --claim finds the main checkout from Git, and authenticates against the main checkout’s session store.
  • Claim repair accepts the resumed session when it is a live session of this WU, your Git identity matches the assignee, and the claim is live on origin.
  • Without a live session, claim repair refuses with Claim binding repair requires an active owner and session and prints the resume command above.

Root and worktree release skew

Section titled “Root and worktree release skew”
  • When wu:done from an older root cannot reuse the prep checkpoint, it re-runs the gates inside the new worktree. The gates derive the claim generation from the worktree’s own claim binding. A missing or ambiguous binding refuses.
  • wu:prep and wu:done compare the CLI release installed in the worktree with the one running the command. On a mismatch they refuse before the worktree gates run, and print both releases and the install command, pnpm --dir "<worktree>" install.
  • When wu:done cannot reuse the prep checkpoint because main changed overlapping files, it prints pnpm wu:rebase --id <wu-id>, then pnpm wu:prep --id <wu-id>.

Revocation semantics

Section titled “Revocation semantics”

Revoking a licence stops future downloads and, once the offline grace window lapses, new runs. It does not remove or disable a copy already installed and running on a consumer’s machine.

Explicit limits

Section titled “Explicit limits”
Section titled “Related”