Configuration

LumenFlow is configured via workspace.yaml in your project root (software_delivery block).

Minimal Config

software_delivery:
  lanes:
    definitions:
      - name: 'Framework: Core'
        code_paths: ['src/**']
  gates:
    format: true
    lint: true
    typecheck: true
    test: true

Config Sections

directories

Directory paths configuration

Field	Type	Default	Description
appsWeb	string	""	Working directory for a web app, if one exists.
worktrees	string	"worktrees/"	Directory where WU lifecycle worktrees are created.
ai	string	"ai/"	Directory for AI-related assets.
claude	string	".claude/"	Directory for Claude-specific configuration.
docs	string	"docs/"	Root directory for project documentation.
packages	string	"packages/"	Root directory for workspace packages.
tools	string	"tools/"	Directory for build and generator tooling.
memoryBank	string	"memory-bank/"	Directory backing the shared memory layer.
wuDir	string	"docs/tasks/wu"	Directory of WU YAML specs.
initiativesDir	string	"docs/tasks/initiatives"	Directory of initiative YAML records.
backlogPath	string	"docs/tasks/backlog.md"	Path to the generated backlog markdown file.
statusPath	string	"docs/tasks/status.md"	Path to the generated status markdown file.
skillsDir	string	".lumenflow/skills"	Canonical directory for LumenFlow skills.
agentsDir	string	".claude/agents"	Directory of agent definition files for the default client.
adrDir	string	"docs/architecture-decisions"	Directory of architecture decision records (ADRs).
plansDir	string	"docs/plans"	Directory of planning documents.
templatesDir	string	".lumenflow/templates"	Directory of WU and initiative template files.
onboardingDir	string	"docs/_frameworks/lumenflow/agent/onboarding"	Directory of agent onboarding documentation.
completeGuidePath	string	"docs/_frameworks/lumenflow/lumenflow-complete.md"	Path to the full LumenFlow workflow guide.
quickRefPath	string	see below	Path to the agent quick-reference commands document.
startingPromptPath	string	see below	Path to the agent starting-prompt document.
sizingGuidePath	string	"docs/_frameworks/lumenflow/wu-sizing-guide.md"	Path to the WU sizing guide document.
governancePath	string	"docs/governance/project-governance.md"	Path to the project governance document.
safeGitPath	string	"scripts/safe-git"	Path to the safe-git wrapper script relative to the project root.

Field details

quickRefPath default

docs/_frameworks/lumenflow/agent/onboarding/quick-ref-commands.md

startingPromptPath default

docs/_frameworks/lumenflow/agent/onboarding/starting-prompt.md

state

State paths configuration (.lumenflow directory structure)

Field	Type	Default	Description
base	string	".lumenflow"	Kernel-shared base state directory, not pack-namespaced.
stateDir	string	".lumenflow/state/packs/software-delivery"	Root state directory for the Software Delivery pack.
archiveDir	string	".lumenflow/state/packs/software-delivery/archive"	Directory holding archived WU events.
stampsDir	string	".lumenflow/state/packs/software-delivery/stamps"	Directory holding completion stamps for done WUs.
mergeLock	string	".lumenflow/state/packs/software-delivery/merge.lock"	Path to the merge lock file serializing lifecycle merges to main.
telemetry	string	".lumenflow/state/packs/software-delivery/telemetry"	Directory holding local telemetry state.
sessions	string	".lumenflow/sessions"	Kernel-shared agent sessions directory, not pack-namespaced.
incidents	string	".lumenflow/state/packs/software-delivery/incidents"	Directory holding recorded incident records.
commandsLog	string	".lumenflow/state/packs/software-delivery/commands.log"	Path to the executed-commands audit log file.
eventArchival	object	see below	Controls archival of old WU events to prevent unbounded growth.

Field details

eventArchival default

archiveAfter: 7776000000
keepArchives: true

git

Git configuration

Field	Type	Default	Description
mainBranch	string	"main"	Name of the repository main branch.
defaultRemote	string	"origin"	Name of the default git remote.
requireRemote	boolean	true	When true, wu:create and wu:claim fail without a remote “origin”.
declaresClaimRefProtection	boolean	false	Declares that the remote server protects refs/lumenflow/claim-* from deletion and rewrite. A declaration only: LumenFlow does not verify server enforcement.
agentBranchPatterns	string[]	[]	Custom agent branch patterns merged with the patterns shipped in the release.
agentBranchPatternsOverride	string[]	-	Agent branch patterns that fully replace the shipped patterns when set.
disableAgentPatternRegistry	boolean	false	Ignores the patterns shipped in the release; uses only agentBranchPatterns, or agent/* when none are set.
secret_scanning	object	see below	Disabled by default. Enabled scans refuse findings, incomplete scope and scanner failures before publication; no binary download.
push_retry	object	see below	Retry-with-rebase behaviour for non-fast-forward push errors. A local pre-push hook refusal or a remote rejection is never retried.
object_durability	boolean	true	When true, setup sets local core.fsync=committed and core.fsyncMethod=batch so git objects survive an unclean shutdown.

Field details

secret_scanning default

enabled: false
timeout_ms: 30000

push_retry default

enabled: true
retries: 8
min_delay_ms: 100
max_delay_ms: 2000
jitter: true

wu

WU (Work Unit) configuration

Field	Type	Default	Description
brief	object	see below	Claim-time wu:brief automation policy and freshness threshold.
lifecycleDurations	boolean	false

Field details

brief default

policyMode: auto
freshnessMinutes: 1440

gates

Quality gates configuration

Field	Type	Default	Description
maxEslintWarnings	integer	100	Maximum ESLint warning count the lint gate tolerates before failing.
enableCoverage	boolean	true	Enables the test coverage gate.
minCoverage	number	90	Minimum required test coverage percentage.
tdd_diff_evidence	object	-	Controls which WU types the TDD diff-evidence gate applies to and how it enforces.
tdd_ordering	object	-	Controls the RED-first commit-order gate: which WU types it applies to and its thresholds.
execution_lock	object	see below	Semaphore for ad-hoc test and build runs started outside a gate. Gate runs take no lock and are never queued or refused on capacity; see resource_guard.
resource_guard	object	see below	Live-signal start guards checked before each gate step spawns. They delay a step for at most a time budget and never queue or refuse a gate run.
merge_lock	object	see below	Bounded wait for wu:create/wu:edit/other micro-worktree writers and wu:done to acquire the repository-wide merge lock before failing.
shared_build_output_roots	string[]	[]	Build-output roots this workspace shares with other checkouts, for the gate build-output lock only (not gates.execution_lock).
execution	object	-	Built-in language preset selection; custom execution commands are retired.
commands	object	see below	Configurable test/lint/typecheck/format commands consumed by the gates runner.
ignore_patterns	string[]	-	Glob patterns to ignore when detecting changed tests for the scoped test gate.
widen_on_deferred_only_tests	boolean	false	Whether the test gate widens to the configured incremental/full test command when every declared tests.unit path is a deferred real-process timing suite.
lane_health	”warn” | “error” | “off”	"warn"	How the lane health check behaves during gates: warn, error, or off.
co_change	object[]	[]	Rules requiring a companion file change when trigger files are modified.
conditional_commands	object[]	[]	Commands that run only when their trigger_patterns match changed files.
include_builtin_co_change_defaults	boolean	true	Merges the built-in database schema-to-migration co-change rules when true.
delivery_review	object	see below	Native delivery review gate evaluating acceptance-criteria satisfaction.
overrides	object	see below	Per-gate-id overrides of framework gate definition defaults, keyed by gate id.
local_prep	object	see below	Opt-in local-prep profile extending wu:prep with build/integration/e2e-smoke gates.
resources	object	-	Vendor-agnostic environment variables and per-runner resource caps for gate subprocesses.
parity_suites	string[]	[]	Repo-specific parity/drift test paths appended to the always-on framework defaults.
unmergeable_paths	string[]	-	Glob patterns for files that cannot be merged by hand (generated outputs, lockfiles, ledgers, baselines).
docs_currency	object	-	Docs-currency gate layout.
embedded	object	see below	EXPERIMENTAL, not yet active: no engine reads this section yet.
throughput_baseline	object	see below	Release throughput ratchet baseline path and tolerance percentage.

Field details

execution_lock default

concurrency: 16
wait_ms: 120000
on_wait_exhausted: fail-closed

resource_guard default

memory:
  mode: observe
  defer_budget_ms: 300000
  floor_bytes: 1073741824

merge_lock default

wait_ms: 30000

shared_build_output_roots description

Build-output roots this workspace shares with other checkouts, for the gate build-output lock only (not gates.execution_lock). Empty (the default) keys each run on its own resolved output root, so disjoint checkouts run concurrently. One declared root serializes every run declaring the identical root. Two or more distinct roots cannot be one lock directory, so the workspace falls back to the machine-wide lock. Relative entries resolve against the checkout root and are compared after native realpath, which collapses symlinks and junctions but not Windows subst or mapped drives: declare the same spelling everywhere.

commands default

test_full: ''
test_docs_only: ''
test_incremental: ''
migration_verify: ''

widen_on_deferred_only_tests description

Whether the test gate widens to the configured incremental/full test command when every declared tests.unit path is a deferred real-process timing suite. Defaults to false (no widening; the gate reports the deferral with evidence instead).

delivery_review default

enabled: false
auto_run: false
block_partial: false
verifier_command: ''
verifier_command_mode: always
skip_types:
  - documentation
  - process

overrides default

{}

local_prep default

build:
  enabled: false
build_scope: applicable
integration_test:
  enabled: false
e2e_smoke:
  enabled: false
  tag: smoke
latency_budget_warn_ms: 180000
latency_budget:
  enforced: false
  docs_only_ms: 3600000
  broad_ms: 3600000
  full_ms: 7200000
report_all: true
reuse_evidence: true

unmergeable_paths description

Glob patterns for files that cannot be merged by hand (generated outputs, lockfiles, ledgers, baselines). Overlapping code_paths on these keep the claim and monolithic-file-contention refusal; overlap on any other path is advisory. A non-empty list replaces the built-in defaults.

docs_currency description

Docs-currency gate layout. product_paths and docs_surfaces: which paths are product code and which are docs surfaces. decisions_dir and decisions_index: where the decision records (ADR files) and their index are (defaults: docs/09-architecture-decisions and README.md inside it).

embedded default

reusable_gates: []
required_gates: []
env_allowlist: []
toolchain_probes: []
base_aware_commands: []
selection_outputs: []
gate_domains: {}
docs_only_patterns: []
tool_cache_paths:
  - .eslintcache
  - '*.tsbuildinfo'
  - node_modules/.cache
declared_outputs: {}
policy_files: []

embedded description

EXPERIMENTAL, not yet active: no engine reads this section yet. Embedded gate mode policy (claimless, remote-less workspace). Strict: unknown keys, gate ids outside the embedded allowlist and escaping paths are refused, and an invalid key fails the whole configuration parse. Every field defaults to the fail-closed value; package_manager has no default and is required to run in embedded mode.

throughput_baseline default

path: .lumenflow/throughput-baseline.json
tolerance_percent: 25
tolerance_floor_hours: 0.5

memory

Memory layer configuration

Field	Type	Default	Description
progress_signals	object	-	Progress signal triggers and cadence for sub-agent coordination.
delegation_context_max_size	integer	4096	Maximum bytes of memory context injected into delegation prompts.
spawn_context_max_size	unknown	-	Deprecated; rejected at parse time. Use delegation_context_max_size instead.
enforcement	object	-	Auto-checkpoint hooks and checkpoint requirement for wu:done.
decay	object	-	Automated archival of stale memory nodes during lifecycle events.

memory.progress_signals

Progress signals configuration for sub-agent coordination

Field	Type	Default	Description
enabled	boolean	false	Makes progress signals mandatory (vs. optional) in spawn prompts.
frequency	integer	0	Sends a progress signal every N tool calls; 0 disables frequency-based signals.
on_milestone	boolean	true	Signals after each acceptance criterion is completed.
on_tests_pass	boolean	true	Signals when tests first pass.
before_gates	boolean	true	Signals before running gates.
on_blocked	boolean	true	Signals when work becomes blocked.
auto_checkpoint	boolean	false	Automatically checkpoints memory at signal milestones.

ui

UI configuration

Field	Type	Default	Description
errorBoxWidth	integer	70	Character width of rendered CLI error boxes.
statusPreviewLines	integer	5	Number of lines shown in a status preview.
readinessBoxWidth	integer	50	Character width of rendered CLI readiness boxes.

yaml

YAML serialization configuration

Field	Type	Default	Description
lineWidth	integer	100	Line-wrap width for generated YAML output; -1 disables wrapping.

agents

Agents configuration

Field	Type	Default	Description
defaultClient	string	"claude-code"	Client identity used when a command is not given an explicit —client.
clients	object	see agents.clients.*	Per-client configuration overrides, keyed by client id.
routing	object	-	Vendor-neutral role defaults and initiative-specific model routing overrides.
roster	string[]	see below	Recommended default roster of agent names for orchestration.
mandatory	object	see below	Agents that are mandatory for a claim, and the trigger patterns that require them.
methodology	object	see agents.methodology	Agent-facing project methodology defaults (TDD, architecture, etc.).
stream_watchdog	object	-	Silent-agent kill timeout and heartbeat cadence for orchestrator stream watchdogs.
monitor_quality_signals	object	-	Mid-execution quality signal policy: flags production code committed with no tests.
monitor_trajectory_signals	object	-	Trajectory classifier thresholds for stagnating/thrashing signal detection.
signals	object	-	Idle-orchestrator push-eligible signal types and idle threshold.
context_discipline	object	see below	Advisory context-loading discipline guidance projected into agent surfaces.
lifecycle_enforcement	object	see below	Lifecycle enforcement backstop policy version and integrity manifest path.

Field details

roster default

- general-purpose
- lumenflow-pm
- test-engineer
- code-reviewer
- bug-triage
- lumenflow-enforcer
- initiative-architect

mandatory default

names: []
triggers: {}

context_discipline default

enabled: true
full_file_read_exceptions: []

lifecycle_enforcement default

enabled: true
policy_version: software-delivery-lifecycle-policy/v1
integrity_manifest: .lumenflow/state/packs/software-delivery/lifecycle-enforcement/integrity-manifest.json

agents.methodology

Methodology defaults (agent-facing project defaults)

Field	Type	Default	Description
enabled	boolean	true	Enables the generated Project Defaults methodology output.
enforcement	”required” | “recommended”	"required"	Whether the listed methodology principles are required or merely recommended.
principles	string[]	see below	Methodology principles applied to every WU by default.
notes	string	-	Free-text notes appended to the Project Defaults block.

Field details

principles default

- TDD
- Hexagonal Architecture
- SOLID
- DRY
- YAGNI
- KISS
- Library-First

agents.clients.*

Client configuration (per-client settings)

Field	Type	Default	Description
skillsDir	string	-	Skills directory path override for this client.
agentsDir	string	-	Agents directory path override for this client.
blocks	object[]	[]	Client-specific content blocks injected into wu:spawn output.
skills	object	-	Recommended and lane-specific skill guidance for wu:spawn.
methodology	object	-	Vendor-neutral methodology delivery facts for this host adapter.
capabilities_map	object	-	Maps abstract classifier capability tags to this client’s skill names.
features	object	-	Per-client activation flags for native pack/runtime features.
routing	object	-	Per-client mapping from the vendor-neutral model_profile vocabulary to this client’s model aliases.
capabilities	object	-	Declarative per-client capability flags, such as harnessPush.

worker_custody

Linux worker custody pool. Unset slots uses the capacity-aware default; see Connected Compute

Field	Type	Default	Description
slots	integer	-	Worker custody slots one process may admit (1-32).
deadline_ms	integer	-	One bounded deadline budget in milliseconds (5000-120000) for the worker custodian: the host wait for each custodian acknowledgement and the private entry waits derive from it.

Field details

slots description

Worker custody slots one process may admit (1-32). Unset uses the capacity-aware default: total memory / 4 GiB, limited by the custody tmpfs size where /var/tmp is a tmpfs, clamped to 2-32. Env LUMENFLOW_WORKER_CUSTODY_SLOTS overrides. A live slot is never stolen at any size.

deadline_ms description

One bounded deadline budget in milliseconds (5000-120000) for the worker custodian: the host wait for each custodian acknowledgement and the private entry waits derive from it. Unset uses 30000. It is never scaled by load. On expiry admission still closes and every counted resource is retained, exactly as before.

evidence_retention

Kernel evidence retention read by evidence:prune. Every key is optional and nothing is archived by default; a flag or environment variable can only raise these values; see Evidence retention

Field	Type	Default	Description
segment_max_age_days	number	-	Sealed trace segments whose newest trace is older than this many days (at least 1) are archived (gzip, never deleted) once every run in them is terminal.
segment_retain_bytes	integer	-	Oldest sealed segments (at least one day old) are archived until the remaining sealed segments total at most this many bytes.
min_blob_age_ms	integer	-	An unreferenced blob younger than this many ms is kept (floor 600000). Default 3600000. A flag or LUMENFLOW_EVIDENCE_MIN_BLOB_AGE_MS can only raise it.
settle_ms	integer	-	Wait (ms) between quarantining unreachable blobs and the final reachability check (floor 5000).

Field details

segment_max_age_days description

Sealed trace segments whose newest trace is older than this many days (at least 1) are archived (gzip, never deleted) once every run in them is terminal. Unset: no segment is archived. Only this workspace key switches archiving on; a flag or LUMENFLOW_EVIDENCE_SEGMENT_MAX_AGE_DAYS can only raise it.

segment_retain_bytes description

Oldest sealed segments (at least one day old) are archived until the remaining sealed segments total at most this many bytes. Unset: no size rule. A flag or LUMENFLOW_EVIDENCE_SEGMENT_RETAIN_BYTES can only raise it.

settle_ms description

Wait (ms) between quarantining unreachable blobs and the final reachability check (floor 5000). Default 30000. A flag or LUMENFLOW_EVIDENCE_SETTLE_MS can only raise it.

status_projection

Presentation settings for status:context. Every key is optional; the stale-claim marker is a label only and never hides a claim; see Status projection

Field	Type	Default	Description
stale_claim_after_days	number	-	Days without a lifecycle event after which status:context marks an in-progress claim stale-claim (a label only: the claim stays visible).

Field details

stale_claim_after_days description

Days without a lifecycle event after which status:context marks an in-progress claim stale-claim (a label only: the claim stays visible). Default 3; fractions of a day are allowed, the maximum is 365.

escalation

Escalation mode: who resolves a human escalation. Lives in the trusted policy (workspace.yaml software_delivery.escalation), so changing it is a governed policy change; the default is human. See Escalation modes

Field	Type	Default	Description
mode	”human” | “delegated” | “off”	"human"	”human” (default): a human resolves a human escalation.
delegated_resolution	object	see escalation.delegated_resolution	The delegated route, read only when mode is “delegated”; see the escalation.delegated_resolution section.

Field details

mode description

“human” (default): a human resolves a human escalation. “delegated”: an independent agent seat resolves it under delegated_resolution. “off”: triggers are still detected and recorded but never gate wu:done; agents decide and the landed WU records the escalation as advisory with the policy digest. An invalid value fails closed.

escalation.delegated_resolution

The delegated route, read only when escalation.mode is delegated. Defaults are the safe ones: review and gates required, security_p0 excluded. Separation of duties is the floor and has no setting. See Escalation modes

Field	Type	Default	Description
triggers	string[]	["sensitive_data","budget","cross_lane_arch"]	Escalation triggers an agent seat may resolve (sensitive_data, security_p0, budget, cross_lane_arch).
require_independent_review	boolean	true	Require a zero-findings independent review verdict (wu:review) on the exact candidate tip.
require_green_gates	boolean	true	Require green gate-set checkpoint evidence (wu:prep) on the exact candidate tip. Relax only explicitly; the evidence records that the policy did not require it.
resolver	”different-seat” | “named-roles”	"different-seat"	Who may resolve: “different-seat” (any authenticated agent seat other than the claim holder) or “named-roles” (also holding a lifecycle role in allowed_resolver_roles).
allowed_resolver_roles	string[]	[]	Lifecycle roles (the resolving session record lifecycle_role) that may resolve when resolver is “named-roles”; must be empty otherwise.

Field details

triggers description

Escalation triggers an agent seat may resolve (sensitive_data, security_p0, budget, cross_lane_arch). A WU is delegable only if ALL its triggers are listed; a trigger not listed, or a flag-only escalation, stays on the human route. security_p0 is not in the default.

require_independent_review description

Require a zero-findings independent review verdict (wu:review) on the exact candidate tip. Relax only explicitly; the evidence records that the policy did not require it.

resolver description

Who may resolve: “different-seat” (any authenticated agent seat other than the claim holder) or “named-roles” (also holding a lifecycle role in allowed_resolver_roles). Separation of duties (the resolver is not the claim holder or an approval requester) is the floor and has no setting.

Framework Agnostic Configuration

LumenFlow supports different package managers and consumer-owned test runner labels. Configure these inside the software_delivery block:

Field	Type	Default	Description
package_manager	"pnpm" | "npm" | "yarn" | "bun"	"pnpm"	Package manager for CLI operations
test_runner	string	-	Optional label for your configured test runner
build_command	string	"pnpm build"	Custom build command for CLI bootstrap

test_runner is metadata for your workspace, not a production default. LumenFlow does not infer a runner from source files or inject runner-specific behaviour unless you configure matching gate commands or gates.resources rules.

Example: npm + Jest

software_delivery:
  package_manager: npm
  test_runner: jest
  build_command: npm run build
  gates:
    commands:
      test_full: npm test
      test_docs_only: npm test -- --testPathPattern=docs
      test_incremental: npm test -- --onlyChanged

Example: yarn + Nx

software_delivery:
  package_manager: yarn
  test_runner: jest
  build_command: yarn nx build @hellmai/lumenflow-cli
  gates:
    commands:
      test_full: yarn nx run-many --target=test --all
      test_docs_only: yarn nx test docs
      test_incremental: yarn nx affected --target=test

Example: bun

software_delivery:
  package_manager: bun
  test_runner: 'bun:test'
  build_command: bun run --filter @hellmai/lumenflow-cli build
  gates:
    commands:
      test_full: bun test
      test_incremental: bun test

Environment Overrides

Config values can be overridden via environment variables:

Variable	Overrides
LUMENFLOW_CLI_DIST_CACHE	CLI build cache root (default ~/.lumenflow/cache/cli-dist)
LUMENFLOW_WORKER_CUSTODY_SLOTS	worker_custody.slots: Linux worker custody pool size, 1-32
LUMENFLOW_EVIDENCE_SEGMENT_MAX_AGE_DAYS	evidence_retention.segment_max_age_days: archive sealed trace segments older than this many days; a flag or variable can only raise the workspace value
LUMENFLOW_EVIDENCE_SEGMENT_RETAIN_BYTES	evidence_retention.segment_retain_bytes: size cap for sealed trace segments; can only raise the workspace value
LUMENFLOW_EVIDENCE_MIN_BLOB_AGE_MS	evidence_retention.min_blob_age_ms: unreferenced blobs younger than this are kept; can only raise the workspace value
LUMENFLOW_EVIDENCE_SETTLE_MS	evidence_retention.settle_ms: wait before the final reachability check; can only raise the workspace value

CLI build cache

Lifecycle commands that require a freshly built CLI resolve the build output by a digest of its inputs (sources, dependencies, build configuration, Node major and ABI) and keep it in a per-machine cache outside every checkout. An output that already matches the current inputs is used as-is, a cached build for the same digest is activated instead of rebuilt, and activation replaces each file by rename so a concurrent reader never sees a missing or partial one.

# Move the cache root (for a sandbox, a test run, or a non-default home)
LUMENFLOW_CLI_DIST_CACHE=/var/tmp/lumenflow-cli-dist pnpm wu:prep --id

A cache root that resolves inside a checkout is refused with a logged reason and the default root is used instead: cached build outputs written into a checkout appear as untracked files and block the lifecycle dirty-checkout guard for every work unit on that checkout.

Host configuration (confinement.yaml)

wu:sandbox --network allowlist on Linux reads its egress rules from a single host-level file, confinement.yaml, never from anything in the repository. It sits in the same per-OS user configuration directory the cached licence file already uses:

Windows: %APPDATA%\lumenflow\confinement.yaml
macOS:   ~/Library/Application Support/lumenflow/confinement.yaml
Linux:   $XDG_CONFIG_HOME/lumenflow/confinement.yaml (falls back to ~/.config/lumenflow)

It is hand-edited (no config:set support) and parsed fresh on every load through a .strict() schema: an unknown top-level key, or an unknown key on one egress rule, refuses the whole load. A missing file means no egress rule is configured (fail-closed: the allowlist is then empty, so nothing but the proxy itself is reachable).

egress:
  - host: registry.npmjs.org
    port: 443
    reason: 'npm package installs'

Every rule carries its own reason (required, for the operator reading it back, and for the proxy’s own connection log). Each rule is validated before the sandbox starts, not only at connect time: a CIDR-shaped host (only exact host:port pairs are supported), a host with no port, a host that is neither a valid hostname nor a valid IP literal (a wildcard, an embedded port, whitespace, or an empty label), or a name that resolves only to private addresses, is each refused with a named reason before any mount is pinned.

trusted_repos and profiles (boxed sessions, Linux only)

wu-sandbox --box (see the project’s internal design record, “Boxed Agent Session Local Governance”) reads the SAME confinement.yaml, extended with a trusted_repos[] list and a profiles map, both parsed through the same .strict() schema:

trusted_repos:
  - canonical: /path/to/lumenflow-dev
    origin: git@github.com:hellmai/lumenflow-dev.git
    credential: /path/to/.ssh/lumenflow-relay
    known_hosts: /path/to/.ssh/known_hosts
    integration_branch: main
    git_identity:
      name: LumenFlow Agent
      email: agent@example.invalid
    agent_cpus: '0-7'
    unconfined_claims: allow
profiles:
  agent:
    egress:
      - host: registry.npmjs.org
        port: 443
        reason: 'npm package installs inside the box'

Each trusted_repos[] entry names: canonical (the repository’s own checkout path, bound read-write to the box’s clone), origin (the URL the host relay forwards accepted pushes to), credential and known_hosts (host-local file paths the relay’s own confinement reads — never read or logged by any other LumenFlow command, and never present inside a box), the integration_branch (default main), an optional writable_refs override (defaults to the integration branch, refs/heads/lane/** and refs/lumenflow/claims/**; any pattern under refs/tags/** is refused at load time), a git_identity for the relay’s own forwarded commits (if any), optional private_scopes (mapped to a dead address inside the box, never resolved), agent_cpus (a taskset range), and unconfined_claims (allow, the default, or refuse). profiles.agent.egress adds this profile’s own allowlisted hosts on top of the top-level egress list above.

unconfined_claims: refuse is a box-only floor for that repository: from the next command, wu:claim, wu:brief, wu:prep, wu:done, wu:recover, wu:rebase, the pre-commit check and every micro-worktree writer run outside a box exit with requester-unconfined and append one line to ~/.lumenflow/boxes/confinement.log.jsonl, while host-only steps (release --publish-only, wu-sandbox --check) keep working. An existing but invalid confinement.yaml refuses; setting the value back to allow takes effect on the next command. wu-sandbox --box stays opt-in until it is enabled in the workspace configuration.

wu-sandbox --check [--box <name>] [--profile <name>] prints the effective relay policy (the integration branch, the writable-ref patterns, and the credential’s path only, never its content), the egress rules with their reasons, mounts, sockets and engine facts, then the posture of one start, for an operator to read back before relying on it.

Validation

Validate your config:

pnpm validate

---

Next Steps

• CLI Commands – All commands
• WU Schema – WU YAML structure