Compose a recovery runtime for your own checkout

The legacy @lumenflow/core micro-worktree is retired. Its successor is the public subpath @hellmai/lumenflow-packs-software-delivery/runtime/recovery/micro-worktree. Unlike the legacy module, the successor reads an explicit recovery runtime context and refuses when none is active: ambient process state grants no authority.

Migrate

1. Replace the import:

   // before
   import { withMicroWorktree } from '@lumenflow/core/micro-worktree';
   // after
   import { withMicroWorktree } from '@hellmai/lumenflow-packs-software-delivery/runtime/recovery/micro-worktree';

2. Compose the context for your checkout and run the operation inside it:

   import { withCheckoutRecoveryRuntime } from '@hellmai/lumenflow-packs-software-delivery/runtime/recovery/checkout-recovery-runtime';
   
   await withCheckoutRecoveryRuntime('/abs/path/to/main-checkout', () =>
     withMicroWorktree({ operation: 'wu-create', id: '<wu-id>', pushOnly: true, execute }),
   );

createRecoveryRuntimeContextForCheckout({ root }) returns the context without running anything, for callers that pass it to runWithRecoveryRuntimeContext or createRecoveryRuntime themselves. The LumenFlow CLI builds its own context from the same composition.

Guarantees

• The mainCheckoutMutation capability is bound to exactly the checkout you pass. The working directory is never consulted and no parent directory is searched.
• That checkout’s workspace.yaml supplies the git configuration.
• The root must be an absolute path to the top of a LumenFlow-initialised main checkout: a workspace.yaml file at the root and a real .git directory whose absolute git dir is exactly that directory. A linked worktree, a submodule, a separate-git-dir checkout, a symlinked .git, a subdirectory, a plain directory or a relative path is refused with a RECOVERY_ERROR naming the reason.
• Composition is refused while GIT_DIR, GIT_WORK_TREE, GIT_COMMON_DIR, GIT_INDEX_FILE, GIT_OBJECT_DIRECTORY, GIT_ALTERNATE_OBJECT_DIRECTORIES or GIT_NAMESPACE is set, because git would then act on a different repository than the path you passed. Unset them first.
• The path is resolved to its canonical form; the context reports that form.
• Outside the callback no context is active.

What the binding is not

The root binding is a label check on the capability: recovery code verifies the capability names the same workspace as the context. It is not filesystem confinement. Git ports accept any path, and the context is frozen shallowly. Do not treat the facade as a sandbox for untrusted operations.