multi-forge 0.8.0__tar.gz → 0.8.1__tar.gz

{multi_forge-0.8.0 → multi_forge-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: multi-forge
-Version: 0.8.0
+Version: 0.8.1
 Summary: Multi-runtime agent toolkit: proxy routing, cost control, session management, policy enforcement, and workflow orchestration
 Project-URL: Homepage, https://github.com/hapa1i/multi-forge
 Project-URL: Repository, https://github.com/hapa1i/multi-forge

{multi_forge-0.8.0 → multi_forge-0.8.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "multi-forge"
-version = "0.8.0"
+version = "0.8.1"
 description = "Multi-runtime agent toolkit: proxy routing, cost control, session management, policy enforcement, and workflow orchestration"
 readme = "README.md"
 license = "Apache-2.0"

{multi_forge-0.8.0 → multi_forge-0.8.1}/src/forge/cli/hooks/commands.py

@@ -1016,7 +1016,7 @@ def worktree_create() -> None:
             # Fallback: try without -b (use detached HEAD)
             logger.debug("worktree-create: branched creation failed: %s", result.stderr.strip())
             result = subprocess.run(
-                [git, "worktree", "add", str(worktree_path)],
+                [git, "worktree", "add", "--detach", str(worktree_path)],
                 cwd=str(repo_root),
                 capture_output=True,
                 text=True,

{multi_forge-0.8.0 → multi_forge-0.8.1}/src/forge/cli/hooks/direct_commands.py

@@ -770,8 +770,8 @@ def _handle_policy_supervisor(argv: list[str]) -> None:
     - ``%policy supervisor``: show current config (including the bound consumer lane)
 
     The consumer-lane *runtime* is intentionally not settable here -- it is a resolving-command
-    flag (``forge policy supervisor set --runtime``) so the binding stays write-once. This path
-    only shows the bound lane.
+    flag (``forge policy supervisor set <target> --runtime``) so the binding stays write-once.
+    This path only shows the bound lane.
     """
     cwd = Path.cwd().resolve()
     store = resolve_session_store(cwd)

{multi_forge-0.8.0 → multi_forge-0.8.1}/src/forge/cli/hooks/policy.py

@@ -172,8 +172,8 @@ def register_supervisor_and_restore(engine: Any, effective: Any, manifest: Any)
 
     Returns the supervisor's injected consumer-lane binding (None when no supervisor is
     configured, or when it resolves to the default lane). The caller threads this same
-    value into the post-eval freeze so the binding records the lane that actually
-    dispatched -- not a fresh manifest read that could race a concurrent intent change.
+    value into the post-eval freeze so the binding records the lane committed for this
+    registered check -- not a fresh manifest read that could race an intent change.
     """
     sup = effective.policy.supervisor if effective.policy else None
     has_supervisor = bool(sup and sup.resume_id and not sup.suspended)

{multi_forge-0.8.0 → multi_forge-0.8.1}/src/forge/cli/memory.py

@@ -30,12 +30,17 @@ from forge.session.exceptions import (
 from forge.session.passport import (
     VALID_STRATEGY_NAMES,
     Passport,
+    PreparedPassportWrite,
+    apply_prepared_passport_write,
     derive_shadow_path,
+    prepare_passport_write,
     read_passport,
     remove_passport,
     resolve_passport_source,
     resolve_with_overrides,
     synthesize_passport,
+    upgrade_passport_envelope,
+    validate_okf_reserved_basenames,
     write_passport,
 )
 from forge.session.project_memory import (
@@ -87,6 +92,7 @@ def memory() -> None:
         forge memory track docs/changelog.md --strategy changelog    # author a passport (sessionless)
         forge memory list                                            # show passported docs
         forge memory passport show docs/changelog.md                 # inspect a passport
+        forge memory passport upgrade docs/changelog.md              # add the OKF envelope
         forge memory shadows review --for docs/impl_notes.md         # curate shadow proposals
     """
 
@@ -187,6 +193,9 @@ def track_cmd(
     except PassportError as e:
         raise click.ClickException(f"Malformed passport in {path}: {e}") from e
 
+    if passport is None and intent is not None and not intent.strip():
+        raise click.ClickException("--intent must be a non-empty string when creating a passport.")
+
     # Scan roots power the out-of-root warning and the collision check. A
     # corrupt config must not block authoring (system-boundary warn+degrade).
     roots = _resolve_scan_roots()
@@ -233,9 +242,9 @@ def track_cmd(
             new_pp = synthesize_passport(
                 strategy=strategy,  # type: ignore[arg-type]  # checked above
                 intent=intent,
-                writers=writers or "all-sessions",
+                writers=writers if writers is not None else "all-sessions",
             )
-            write_passport(abs_path, new_pp)
+            write_passport(abs_path, new_pp, okf_path=path)
         except PassportError as e:
             raise click.ClickException(str(e)) from e
         console.print(f"Passport created for [cyan]{path}[/cyan] (strategy: {strategy}).")
@@ -300,17 +309,16 @@ def _track_existing_shadow_only(
         )
 
     has_flags = strategy is not None or writers is not None
-    updated = False
-    if has_flags:
-        try:
+    resolved_pp = passport
+    pp_warnings: list[str] = []
+    prepared: PreparedPassportWrite | None = None
+    try:
+        if has_flags:
             resolved_pp, pp_warnings = resolve_with_overrides(passport, strategy=strategy, writers=writers)
-        except PassportError as exc:
-            raise click.ClickException(str(exc)) from exc
-        if pp_warnings:
-            write_passport(abs_path, resolved_pp)
-            updated = True
-            for w in pp_warnings:
-                console.print(f"[yellow]Warning:[/yellow] {w}")
+            if pp_warnings:
+                prepared = prepare_passport_write(abs_path, resolved_pp)
+    except PassportError as exc:
+        raise click.ClickException(str(exc)) from exc
 
     created = _auto_create_shadow(shadow_path, forge_root)
     shadow_abs = (forge_root / shadow_path).resolve()
@@ -318,7 +326,11 @@ def _track_existing_shadow_only(
         raise click.ClickException(f"Shadow file does not exist: {shadow_path}")
     if created:
         console.print(f"Shadow file created: {shadow_path}.")
-    if updated:
+    if pp_warnings:
+        assert prepared is not None
+        apply_prepared_passport_write(abs_path, prepared)
+        for w in pp_warnings:
+            console.print(f"[yellow]Warning:[/yellow] {w}")
         console.print(f"Passport updated in [cyan]{path}[/cyan] (shadow-only proposals at {shadow_path}).")
     else:
         console.print(f"Passport already present in [cyan]{path}[/cyan] (shadow-only proposals at {shadow_path}).")
@@ -353,6 +365,10 @@ def _track_propose(
     # Self-shadow: compare resolved paths, not raw strings
     resolved_shadow = (forge_root / shadow_path).resolve()
     resolved_official = (forge_root / path).resolve()
+    try:
+        validate_okf_reserved_basenames(shadow_path, resolved_shadow)
+    except PassportError as exc:
+        raise click.ClickException(f"Invalid shadow path: {exc}") from exc
     if resolved_shadow == resolved_official:
         raise click.ClickException("Shadow path cannot be the same as the official doc.")
 
@@ -360,17 +376,15 @@ def _track_propose(
     if collision:
         raise click.ClickException(collision)
 
-    # Auto-create shadow file if Forge-owned
-    created = _auto_create_shadow(shadow_path, forge_root)
-    shadow_abs = (forge_root / shadow_path).resolve()
-    if not shadow_abs.is_file():
-        raise click.ClickException(f"Shadow file does not exist: {shadow_path}")
-
-    # Passport handling: synthesize or update.
+    # Prepare the complete effective passport before materializing the shadow.
+    # For existing passports this deliberately omits ``okf_path`` so re-track
+    # never validates, repairs, or adds an outer envelope.
     # For existing passports, pass strategy only when the user explicitly provided --strategy
     # so the passport's own strategy is preserved by default.
+    pp_warnings: list[str]
+    prepared: PreparedPassportWrite | None = None
+    result_kind: str
     if isinstance(passport, Passport) and passport.update.mode == "shadow-only":
-        # Already shadow-only -- apply overrides if any
         try:
             resolved_pp, pp_warnings = resolve_with_overrides(
                 passport,
@@ -378,17 +392,12 @@ def _track_propose(
                 shadow_path=(shadow_path if shadow_path != passport.update.shadow_path else None),
                 writers=writers,
             )
+            if pp_warnings:
+                prepared = prepare_passport_write(abs_path, resolved_pp)
         except PassportError as e:
             raise click.ClickException(str(e)) from e
-        if pp_warnings:
-            write_passport(abs_path, resolved_pp)
-            for w in pp_warnings:
-                console.print(f"[yellow]Warning:[/yellow] {w}")
-            console.print(f"Passport updated in [cyan]{path}[/cyan]. Future sessions will use the new values.")
-        else:
-            console.print(f"Passport already present in [cyan]{path}[/cyan] (shadow-only proposals at {shadow_path}).")
+        result_kind = "updated" if pp_warnings else "unchanged"
     elif isinstance(passport, Passport):
-        # Convert existing direct passport to shadow-only
         try:
             resolved_pp, pp_warnings = resolve_with_overrides(
                 passport,
@@ -397,25 +406,45 @@ def _track_propose(
                 shadow_path=shadow_path,
                 writers=writers,
             )
+            prepared = prepare_passport_write(abs_path, resolved_pp)
         except PassportError as e:
             raise click.ClickException(str(e)) from e
-        write_passport(abs_path, resolved_pp)
-        for w in pp_warnings:
-            console.print(f"[yellow]Warning:[/yellow] {w}")
-        console.print(f"Passport in [cyan]{path}[/cyan] converted to shadow-only proposals at {shadow_path}.")
+        result_kind = "converted"
     else:
-        # No passport -- synthesize with default strategy
         try:
             new_pp = synthesize_passport(
                 strategy=new_passport_strategy,
                 intent=intent,
                 update_mode="shadow-only",
                 shadow_path=shadow_path,
-                writers=writers or "all-sessions",
+                writers=writers if writers is not None else "all-sessions",
             )
-            write_passport(abs_path, new_pp)
+            prepared = prepare_passport_write(abs_path, new_pp, okf_path=path)
         except PassportError as e:
             raise click.ClickException(str(e)) from e
+        pp_warnings = []
+        result_kind = "created"
+
+    # Materialization begins only after path, collision, effective-passport,
+    # frontmatter, and (for new tracking) OKF envelope validation all succeed.
+    created = _auto_create_shadow(shadow_path, forge_root)
+    shadow_abs = (forge_root / shadow_path).resolve()
+    if not shadow_abs.is_file():
+        raise click.ClickException(f"Shadow file does not exist: {shadow_path}")
+
+    if result_kind != "unchanged":
+        assert prepared is not None
+        apply_prepared_passport_write(abs_path, prepared)
+
+    for w in pp_warnings:
+        console.print(f"[yellow]Warning:[/yellow] {w}")
+    if result_kind == "updated":
+        console.print(f"Passport updated in [cyan]{path}[/cyan]. Future sessions will use the new values.")
+    elif result_kind == "unchanged":
+        console.print(f"Passport already present in [cyan]{path}[/cyan] (shadow-only proposals at {shadow_path}).")
+    elif result_kind == "converted":
+        console.print(f"Passport in [cyan]{path}[/cyan] converted to shadow-only proposals at {shadow_path}.")
+    else:
         console.print(
             f"Shadow-only passport written for [cyan]{path}[/cyan] "
             f"(strategy: {new_passport_strategy}, proposals at {shadow_path})."
@@ -1029,7 +1058,7 @@ def _review_curate(
 
 @memory.group("passport")
 def passport_group() -> None:
-    """Inspect and remove memory-doc passports."""
+    """Inspect, upgrade, and remove memory-doc passports."""
 
 
 @passport_group.command("show")
@@ -1115,6 +1144,58 @@ def passport_show_cmd(path: str, as_json: bool) -> None:
     console.print(table)
 
 
+@passport_group.command("upgrade")
+@click.argument("path")
+def passport_upgrade_cmd(path: str) -> None:
+    """Add missing OKF envelope fields to an existing passport."""
+    try:
+        ctx = ExecutionContext.from_cwd()
+    except ForgeOpError as e:
+        print_error(str(e), console=err_console)
+        print_tip("Run this command from an enabled Forge project.", console=err_console)
+        sys.exit(1)
+
+    if ctx.forge_root is None:
+        print_error("Not inside a Forge project.", console=err_console)
+        print_tip("Run 'forge extension enable' first.", console=err_console)
+        sys.exit(1)
+
+    from forge.cli.guards import enforce_target_project_compatibility
+
+    enforce_target_project_compatibility(ctx.forge_root)
+
+    resolved_base = ctx.forge_root.resolve()
+    reason = is_safe_designated_doc_path(path, ctx.forge_root, resolved_base)
+    if reason:
+        print_error(f"Invalid path: {reason}", console=err_console)
+        print_tip(
+            "Use a project-relative Markdown path inside this Forge project.",
+            console=err_console,
+        )
+        sys.exit(1)
+
+    abs_path = (ctx.forge_root / path).resolve()
+    if not abs_path.is_file():
+        print_error(f"File not found: {path}", console=err_console)
+        print_tip("Check the project-relative path and try again.", console=err_console)
+        sys.exit(1)
+
+    try:
+        added = upgrade_passport_envelope(abs_path, logical_path=path)
+    except PassportError as e:
+        print_error(f"Could not upgrade passport in {path}: {e}", console=err_console)
+        print_tip(
+            "Fix the reported frontmatter or path issue, then rerun this command.",
+            console=err_console,
+        )
+        sys.exit(1)
+
+    if added:
+        console.print(f"OKF envelope upgraded in [cyan]{path}[/cyan] (added: {', '.join(added)}).")
+    else:
+        console.print(f"OKF envelope already complete in [cyan]{path}[/cyan]; no changes made.")
+
+
 @passport_group.command("remove")
 @click.argument("path")
 @click.option("--json", "as_json", is_flag=True, default=False, help="Output as JSON")

{multi_forge-0.8.0 → multi_forge-0.8.1}/src/forge/cli/policy.py

@@ -288,9 +288,8 @@ def enable(bundles: tuple[str, ...], fail_mode: str, permissive: bool, session_n
     """
     if not bundles:
         # Fail loud, not a silent no-op: the CLI is the explicit surface and requires
-        # the bundles to enable. Restore-from-intent (re-enable the session's configured
-        # bundles) is the interactive `%policy enable` shortcut's job, not the CLI's --
-        # see design_workflows.md "Re-enable enforcement".
+        # the bundles to enable. The interactive `%policy enable` surface also requires
+        # explicit bundles; its distinction is that it writes overrides rather than intent.
         print_error_with_tip(
             "No policy bundles specified.",
             "Use --bundle tdd and/or --bundle coding_standards.",

{multi_forge-0.8.0 → multi_forge-0.8.1}/src/forge/cli/session_lane.py

@@ -139,8 +139,10 @@ _SESSION_OPTION = click.option(
 def session_lane() -> None:
     """Bind a consumer's LLM-work to a (runtime, backend, model) lane for the session.
 
-    Lanes are session-owned intent, frozen at first dispatch. The supervisor also
-    accepts 'forge policy supervisor set --runtime/--backend' (same storage).
+    Lanes are session-owned intent. An explicit supervisor lane freezes at its first
+    registered policy check; auxiliary-consumer lanes freeze at first real dispatch.
+    The supervisor also accepts
+    'forge policy supervisor set <target> --runtime/--backend' (same storage).
 
     \b
     Examples:

{multi_forge-0.8.0 → multi_forge-0.8.1}/src/forge/core/llm/__init__.py

@@ -1,7 +1,8 @@
 """Shared LLM client abstraction for Forge components.
 
-This module provides a unified, async-first interface for calling LLMs
-across different providers (LiteLLM, Anthropic).
+This module provides a unified, async-first interface for calling LLMs through
+remote/local LiteLLM endpoints and OpenRouter directly. A native Anthropic
+client is not implemented yet; ``anthropic/`` model ids route through LiteLLM.
 
 Usage:
     # Async usage (Proxy)

{multi_forge-0.8.0 → multi_forge-0.8.1}/src/forge/core/llm/clients/__init__.py

@@ -2,6 +2,7 @@
 
 Currently implemented:
 - LiteLLMClient: For both remote and local LiteLLM instances
+- OpenRouterClient: Direct OpenRouter through its OpenAI-compatible endpoint
 
 Deferred (not yet implemented):
 - AnthropicClient: Direct Anthropic API

{multi_forge-0.8.0 → multi_forge-0.8.1}/src/forge/core/state/io.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 
 import json
 import os
+import stat
 import tempfile
 from pathlib import Path
 from typing import Any
@@ -60,6 +61,7 @@ def atomic_write_text(
     content: str,
     *,
     mode: int | None = None,
+    preserve_existing_mode: bool = False,
     create_parents: bool = True,
 ) -> None:
     """Write text to a file atomically.
@@ -72,12 +74,21 @@ def atomic_write_text(
         path: Target file path.
         content: Text content to write.
         mode: Optional final file mode (for example, 0o600).
+        preserve_existing_mode: Preserve the target's permission bits when it exists.
+            A missing target retains the secure tempfile default. Mutually exclusive with ``mode``.
         create_parents: Create parent directories if they don't exist.
 
     Raises:
+        ValueError: If ``mode`` and ``preserve_existing_mode`` are both requested.
         OSError: If the write or rename fails.
     """
-    atomic_write_bytes(path, content.encode("utf-8"), mode=mode, create_parents=create_parents)
+    atomic_write_bytes(
+        path,
+        content.encode("utf-8"),
+        mode=mode,
+        preserve_existing_mode=preserve_existing_mode,
+        create_parents=create_parents,
+    )
 
 
 def atomic_write_bytes(
@@ -85,6 +96,7 @@ def atomic_write_bytes(
     content: bytes,
     *,
     mode: int | None = None,
+    preserve_existing_mode: bool = False,
     create_parents: bool = True,
 ) -> None:
     """Write bytes to a file atomically.
@@ -97,11 +109,24 @@ def atomic_write_bytes(
         path: Target file path.
         content: Bytes to write.
         mode: Optional final file mode (for example, 0o600).
+        preserve_existing_mode: Preserve the target's permission bits when it exists.
+            A missing target retains the secure tempfile default. Mutually exclusive with ``mode``.
         create_parents: Create parent directories if they don't exist.
 
     Raises:
+        ValueError: If ``mode`` and ``preserve_existing_mode`` are both requested.
         OSError: If the write or rename fails.
     """
+    if mode is not None and preserve_existing_mode:
+        raise ValueError("mode and preserve_existing_mode are mutually exclusive")
+
+    resolved_mode = mode
+    if preserve_existing_mode:
+        try:
+            resolved_mode = stat.S_IMODE(path.stat().st_mode)
+        except FileNotFoundError:
+            resolved_mode = None
+
     if create_parents:
         path.parent.mkdir(parents=True, exist_ok=True)
 
@@ -115,8 +140,8 @@ def atomic_write_bytes(
         with os.fdopen(fd, "wb") as f:
             f.write(content)
             f.flush()
-            if mode is not None:
-                os.fchmod(f.fileno(), mode)
+            if resolved_mode is not None:
+                os.fchmod(f.fileno(), resolved_mode)
             os.fsync(f.fileno())
         os.replace(temp_path, str(path))
         try:

{multi_forge-0.8.0 → multi_forge-0.8.1}/src/forge/install/codex_hooks.py

@@ -440,7 +440,7 @@ def apply_codex_merge(config_path: Path, entries: tuple[CodexHookEntry, ...]) ->
 
     backup_path = backup_codex_config(config_path)
     config_path.parent.mkdir(parents=True, exist_ok=True)
-    atomic_write_text(config_path, new_text)
+    atomic_write_text(config_path, new_text, preserve_existing_mode=True)
     return backup_path
 
 
@@ -548,7 +548,7 @@ def remove_codex_block(config_path: Path, entries: tuple[CodexHookEntry, ...]) -
         config_path.unlink()
         return CodexRemoveResult(removed=True, deleted_file=True, leftover_commands=leftover)
 
-    atomic_write_text(config_path, new_text)
+    atomic_write_text(config_path, new_text, preserve_existing_mode=True)
     return CodexRemoveResult(removed=True, leftover_commands=leftover)
 
 

{multi_forge-0.8.0 → multi_forge-0.8.1}/src/forge/policy/semantic/supervisor.py

@@ -109,15 +109,14 @@ _CLAUDE_MODEL_PIN_ENV_VARS = (
     "ANTHROPIC_DEFAULT_OPUS_MODEL",
 )
 
-# The supervisor as a consumer-lane binding (epic consumer_lanes, ticket T3). It
-# reads repo files (a `tool_agent` capability floor) and today always runs as
-# `claude -p`. In T3 only `runtime_id` is load-bearing -- it selects the dispatch
-# arm in `_dispatch_supervisor`. `backend_id`/`model` are nominal placement
-# metadata: the `claude_code` arm still derives transport (`base_url`) and the
-# `opus` pin dynamically (byte-identical contract), so they are not yet consulted.
-# `anthropic-direct` is a real catalog source (no single backend is "correct" for a
-# proxied supervisor, which routes through whatever proxy). T2 makes backend
-# load-bearing; T4 adds the `codex` arm + a narrow `SupervisorConfig` override.
+# The supervisor as a consumer-lane binding (epic consumer_lanes). It reads repo
+# files (a `tool_agent` capability floor), and `runtime_id` selects the dispatch arm
+# in `_dispatch_supervisor`: `claude_code` or `codex`. `backend_id`/`model` remain
+# nominal placement metadata for dispatch: the Claude arm derives transport
+# (`base_url`) and its `opus` pin dynamically, while Codex chooses its own model.
+# `backend_id` is nevertheless load-bearing for billing (for example `claude-max`).
+# `anthropic-direct` is a real catalog source; no single backend is "correct" for a
+# proxied Claude supervisor, which routes through whichever proxy was resolved.
 SUPERVISOR_CONSUMER = Consumer(
     id="supervisor",
     capability_floor="tool_agent",
@@ -494,9 +493,9 @@ def _dispatch_supervisor(
 ) -> SessionResult:
     """Dispatch one supervisor run on the resolved lane's runtime.
 
-    T3 implements only the ``claude_code`` arm (the existing path, verbatim).
-    The ``codex`` arm lands in T4 (epic consumer_lanes); any other runtime has
-    no supervisor adapter.
+    The shipped arms are ``claude_code`` (native resume, optionally proxied) and
+    ``codex`` (fresh, plan-fed ``codex exec``). Any other runtime has no supervisor
+    adapter and fails open through ``_SupervisorRoutingError``.
     """
     runtime = lane.runtime_id
     if runtime == "claude_code":

{multi_forge-0.8.0 → multi_forge-0.8.1}/src/forge/session/consumer_lanes.py

@@ -81,7 +81,7 @@ def confirmed_lane(state: SessionState, consumer: Consumer) -> LaneRecord | None
     """Return ``consumer``'s frozen lane record, or None if not yet bound.
 
     The resolving commands' already-bound reject reads this: a non-None result
-    means the lane is frozen, so ``policy supervisor set --runtime`` must refuse to
+    means the lane is frozen, so ``policy supervisor set <target> --runtime`` must refuse to
     change it (the binding is immutable once written, card D2).
     """
     binding = _confirmed_binding(state, consumer)
@@ -148,9 +148,10 @@ def set_intent_lane(state: SessionState, consumer: Consumer, lane_record: LaneRe
     """Record ``consumer``'s requested lane in ``intent`` (the resolving-command setter).
 
     The write companion to ``read_bound_lane``'s intent branch: resolving commands
-    (start/fork ``--supervisor-runtime``, ``policy supervisor set --runtime``) call this
-    to record the requested placement. The freeze (``ensure_consumer_lane_binding``) later
-    copies the lane that actually dispatched into ``confirmed``. Callers enforce the
+    (start/fork ``--supervisor-runtime``, ``policy supervisor set <target> --runtime``) call this
+    to record the requested placement. ``ensure_consumer_lane_binding`` later freezes the
+    lane at the consumer's lifecycle commitment point: first registered policy check for
+    the supervisor, first real dispatch for auxiliary consumers. Callers enforce the
     already-bound reject (``confirmed_lane``) before invoking this -- it does not itself
     guard against overwriting a request on an already-frozen session.
     """
@@ -192,10 +193,12 @@ def clear_intent_lane(state: SessionState, consumer: Consumer) -> None:
 def ensure_consumer_lane_binding(state: SessionState, consumer: Consumer, lane_record: LaneRecord | None) -> None:
     """Freeze ``consumer``'s explicitly-chosen lane into ``confirmed``, write-if-absent.
 
-    The single immutability seam (card D2). ``lane_record`` is the lane the hook injected at
-    registration (``read_bound_lane`` -- confirmed-first, else the intent override), NOT a fresh
-    manifest read, so the freeze records exactly what dispatched even if intent changes during
-    the (multi-second) supervisor call.
+    The single immutability seam (card D2). ``lane_record`` is the lane selected for the
+    consumer's lifecycle commitment (``read_bound_lane`` -- confirmed-first, else the intent
+    override), NOT a fresh manifest read. For the supervisor that commitment is the registered
+    policy check and may precede a runtime dispatch; auxiliary callers invoke this only after
+    committing to a real dispatch. The threaded value prevents a concurrent intent change from
+    freezing a lane the lifecycle event did not select.
 
     **The default lane is never frozen.** ``lane_record is None`` means no explicit choice was
     recorded (neither ``confirmed`` nor ``intent``) and the consumer ran on its default; we leave

{multi_forge-0.8.0 → multi_forge-0.8.1}/src/forge/session/overrides.py

@@ -209,7 +209,7 @@ def validate_key(key: str) -> list[str]:
 
     if first_part == "consumer_lanes":
         # Consumer-lane bindings (epic consumer_lanes, T1b) are set only through resolving commands
-        # (--supervisor-runtime at start/fork, 'forge policy supervisor set --runtime'), which expand a
+        # (--supervisor-runtime at start/fork, 'forge policy supervisor set <target> --runtime'), which expand a
         # runtime to a full validated LaneRecord and enforce the already-bound reject. A raw override --
         # partial (can't rehydrate a 3-field LaneRecord) or full-object (bypasses that validation, and
         # after first dispatch is recorded-but-ignored since dispatch reads the frozen confirmed binding)
@@ -217,7 +217,8 @@ def validate_key(key: str) -> list[str]:
         raise InvalidOverrideKeyError(
             key,
             "consumer lanes are set via resolving commands, not overrides",
-            hint="use --supervisor-runtime at session start/fork or 'forge policy supervisor set --runtime'",
+            hint="use --supervisor-runtime at session start/fork or "
+            "'forge policy supervisor set <target> --runtime'",
         )
 
     if "*" in key: