dsh-loop-engine 0.1.5-rc2 → 0.1.5-rc4

package/lib/types/index.d.ts

@@ -1,53 +1,54 @@
 /**
- * Web-switchable agent loop engine, node half.
+ * Per-session agent loop engines, node half.
  *
  * Hosts the non-default agent-loop engines (Claude Code, Codex, Pi, Kimi Code)
- * and bridges them with the harness's single AgentFactory slot. The engine is
- * selected by the `agent-loop-engine` settings section; the selection is
- * realized by a managed block in the profile's `cordis.patch.yml` that
- * disables the base bundle's `agent-loop` row — exactly one AgentFactory may
- * register, so a non-default engine owns the slot by disabling the base loop
- * first, and `in-process` leaves the base row active (this plugin does NOT
- * register its own factory then).
+ * and routes each session to the engine it runs. The engine is the PLUGIN's own
+ * per-session fact (`session-engine-store.ts`), read first and over the recorded
+ * agent preset; a session the plugin has no record for keeps the preset answer,
+ * which is what makes every pre-existing session behave exactly as before.
+ * The harness admits exactly one AgentFactory per process, so "session A on
+ * Codex while session B runs Kimi" is realized by a single router factory
+ * ({@link RouterLoop}, which extends the harness's own `AgentLoop`) dispatching
+ * to one driver runtime per engine; `in-process` sessions keep the harness loop
+ * through that same router.
  *
- * The managed block is the ground truth the factory decision reads at boot:
- * apply() reads the file synchronously, so a committed engine change takes
- * effect on the next recomposition (restart); the config-only HMR watcher
- * re-applies the patch file but cannot re-register an AgentFactory mid-run.
- * The settings section is seeded from the block so the UI mirrors the file,
- * and a committed settings change writes the block (only when it differs).
+ * Because the router owns the slot, the plugin keeps the base bundle's
+ * `agent-loop` row disabled for as long as it is composed. That managed block
+ * lives in the profile's `cordis.patch.yml` (see `patch-manager.ts`) and is the
+ * plugin's only footprint in the harness's configuration; the block names no
+ * engine, because the engine is a per-session decision.
  *
- * A hosted engine also takes over the session's command and skill surface:
- * the block disables dsh's `command-goal` row, and the plugin authors a
- * stripped copy of the `standard` agent preset into the user preset root
- * (see `preset.ts`) and steers the `agent-presets` roster default to it, so
- * new sessions get the engine's commands and skills instead of the dsh-native
- * ones an external engine cannot honor. Switching back to `in-process`
- * restores the previous default.
+ * The plugin authors one preset per hosted engine into the user preset root
+ * (`$DSH_HOME/.agent-presets/loop-engine-<engine>`, see `preset.ts`), each a
+ * copy of `standard` minus the dsh-native command and skill rows an external
+ * engine replaces, and it serves every hosted engine's provider route label in
+ * the llm registry (`provider-route.ts`): an engine logs its own label into
+ * each session's request/header, and the web host refuses a turn whose session
+ * selection names a provider no adapter serves. The preset is now only the
+ * session's agent-plane composition (and the engine's own default for a session
+ * with no record) — it is no longer the thing that decides a running session's
+ * engine.
  *
- * While a hosted engine is mounted the plugin also serves its provider route
- * label (`claude-code` / `codex` / `pi` / `kimi`) from the llm registry with
- * a model-less placeholder adapter (see `provider-route.ts`): the engine logs
- * that label into each session's request/header, and the web host refuses a
- * turn whose session selection names a provider no adapter serves — without
- * the placeholder the second prompt of every hosted session would fail with
- * `model-unavailable`.
+ * The `agent-loop-engine` settings section carries the DEFAULT engine for new
+ * sessions — which preset the roster's default points at — not a process-wide
+ * switch: existing sessions keep the engine they run, and nothing is torn down or
+ * reloaded by it. (A PER-SESSION switch is a different thing: it is made from the
+ * chat composer, and when it involves the harness loop it releases that session's
+ * agent and reloads the page — `router-loop.ts` `move`, `client/reload.ts`.)
  *
  * @module dsh-loop-engine
  */
-import { Context } from '@deepseek-ai/cordis';
+import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
 import { type Config as ClaudeCodeConfig } from './engine-claude/loop.ts';
 import type { CodexApprovalPolicy, CodexSandboxMode } from './engine-codex/types.ts';
-import { type LoopEngineId } from './settings.ts';
 export declare const name = "loop-engine";
 /**
  * Services the plugin's own fiber requires. The plugin declares none of its
- * own: the optional host services it reads (`commands`, `skills`) are resolved
- * lazily via `ctx.get` and may be absent, and the hosted engine factories
- * (Claude Code / Codex) declare their own `inject` when the plugin mounts them
- * as children. Empty keeps the plugin from demanding a service that a minimal
- * profile does not provide.
+ * own: the optional host services it reads (`commands`, `skills`, `agentPresets`,
+ * `llm`) are resolved lazily via `ctx.get` and may be absent, and the router
+ * declares the harness loop's own dependency set when it mounts. Empty keeps
+ * the plugin from demanding a service that a minimal profile does not provide.
  */
 export declare const inject: never[];
 /** Composition entry for the loop engine selection and the hosted engine drivers. */
@@ -77,9 +78,8 @@ export interface Config extends ClaudeCodeConfig {
  * matching the permissive interface and read path (`resolvePatchPath` defaults
  * the patch path; each engine driver resolves only the knobs it owns and
  * omitted deployment tunables fall back to the session). The composition entry
- * is an engine-agnostic superset: the selectable knobs belong to whichever
- * engine the settings pick at runtime, so both engines' knobs may coexist and
- * only the selected one is consumed.
+ * is an engine-agnostic superset: every hosted engine's knobs live here at
+ * once, because any session may select any engine.
  */
 export declare const Config: z<Config>;
 /** Resolve the managed patch file from configuration, defaulting to the web profile. */
@@ -87,28 +87,29 @@ export declare function resolvePatchPath(config: Config): string;
 /** Atomically replace the patch file (same-directory temp + rename). */
 export declare function writePatchFile(path: string, text: string): Promise<void>;
 /**
- * Synchronously atomically replace the patch file. The engine-selection
- * onChange is a synchronous hook with no await, and the write MUST land before
- * the caller is told the switch committed — otherwise a user who restarts
- * `dsh web` immediately reads the stale file and the previous engine boots.
+ * Synchronously atomically replace the patch file. The settings onChange that
+ * commits a default-engine change is a synchronous hook with no await, and the
+ * write MUST land before the caller is told the change committed — otherwise a
+ * user who restarts `dsh web` immediately reads the stale file.
  * @param path - the profile's patch file.
  * @param text - the next file content.
  */
 export declare function writePatchFileSync(path: string, text: string): void;
 /**
- * Rewrite the managed block for a target engine, preserving the rest of the
- * file byte for byte. Only writes when the file actually differs.
+ * Ensure the profile's patch file carries the plugin's managed block, which
+ * disables the base bundle's `agent-loop` row so this plugin's router owns the
+ * single AgentFactory slot. Idempotent: a file already carrying a block and no
+ * legacy block is left untouched.
  * @param path - the profile's patch file.
- * @param engine - the target engine.
  * @returns whether a write occurred.
  */
-export declare function syncManagedBlock(path: string, engine: LoopEngineId): Promise<boolean>;
+export declare function syncManagedBlock(path: string): Promise<boolean>;
 /**
- * Apply the plugin: seed the settings section from the managed block, host
- * the non-default engine factory when the block says so, and translate
- * committed engine changes into managed-block writes.
+ * Apply the plugin: own the profile's managed block, mount the routing factory,
+ * author the per-engine presets, and serve every hosted engine's provider
+ * route. The settings section carries the deployment's default engine.
  * @param ctx - the composing context.
- * @param config - composition entry for the managed patch file.
+ * @param config - composition entry for the managed patch file and engine knobs.
  */
 export declare function apply(ctx: Context, config: Config): void;
 //# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -1,11 +1,14 @@
 /**
  * Package-owned invariant companion for the loop engine selection.
  *
- * The plugin's owned relationship is the patch-manager round trip: rendering
- * a managed block for an engine and reading it back must produce the same
- * engine, and the `in-process` engine must render an absent block (so the base
- * bundle's `agent-loop` row stays mounted). The companion asserts both against
- * the pure transform, binding the writer's inverse to the reader directly.
+ * The plugin's owned relationship is the patch-manager round trip: applying the
+ * managed block must be a fixed point, the block must be the one that frees the
+ * single AgentFactory slot for the router, a legacy block naming a single engine
+ * must be migrated to the engine-agnostic form while still being readable as a
+ * legacy pin, and a comment-only layer must be re-seeded to a loadable
+ * top-level array rather than left as `null`. The companion asserts those
+ * against the pure transform, binding the writer's inverse to the reader
+ * directly.
  *
  * @module dsh-loop-engine/invariant
  */

package/lib/types/model-selection-reset.d.ts

@@ -0,0 +1,271 @@
+/**
+ * Keep a session's model selection on the seat the engine driving it owns.
+ *
+ * A session's model selection FOLLOWS ITS ENGINE, in both directions:
+ *
+ *  - a HOSTED engine owns its model natively, and logs the one shared provider
+ *    label (`external`, {@link HOSTED_ROUTE_LABEL}) into the session's
+ *    `request/header`; the host derives the session's selection from the latest
+ *    header (`packages/api/session-controller/src/agent.ts`, `selectionFor`), so
+ *    a session a hosted engine drives selects `external`. That label is served
+ *    only by this plugin's placeholder route (`provider-route.ts`), which
+ *    advertises exactly one entry under it — {@link HOSTED_DEFAULT_MODEL}. So
+ *    the seat of a hosted session is `external/default`, and this module is what
+ *    puts that in the log BEFORE the engine's first request would. (A session
+ *    whose log still carries an EARLIER build's per-engine label —
+ *    `claude-code` / `codex` / `pi` / `kimi` — is recognized as hosted too,
+ *    {@link isHostedProviderRoute}, and rewritten to `external/default` on its
+ *    next build or switch: no adapter serves those labels any more, so leaving
+ *    one in place would fail the host's own route check with
+ *    `model-unavailable`.)
+ *  - the HARNESS LOOP (`in-process`) DOES call a real model, so it must select
+ *    something a real adapter serves, and the only selection this plugin can name
+ *    honestly is the deployment's own default:
+ *    `agentDefaultModel.currentSelection()`, the value the host's
+ *    `agentOptions()` gives every session it creates without one
+ *    (`packages/core/agent-default-model/src/index.ts`,
+ *    `packages/api/session-controller/src/agent.ts`). That default can name one of
+ *    these routes ITSELF — `session.selectModel` saves whatever the model menu
+ *    submitted as the deployment default, and the menu carries the hosted route
+ *    as an entry — so the deployment's COMPOSED default model (the settings
+ *    descriptor's `base` layer, what `packages/bundle/base/cordis.patch.yml`
+ *    configures) is what this plugin names instead, and says so once. See
+ *    {@link defaultSelection}.
+ *
+ * The write is the harness's own `model/selection` event: log-only, already a
+ * known session event type (`packages/core/session/src/known-event-types.ts`),
+ * and exactly what the host's own model picker appends
+ * (`ApiSessionAgentController.selectForNextRequest`). That is what makes it the
+ * one way a plugin can say "this session's next build selects X" without owning
+ * the host's in-memory selection: the event folds into the `modelSelection`
+ * projection, and the selection the host installs for the session's next agent
+ * reads it back (`selectionFor` prefers the projection's `pending` over the
+ * logged header).
+ *
+ * TWO triggers ask for it, and both answer through the same write:
+ *
+ *  - {@link ModelSelectionReset.resetFor} — a session SWITCHED to another
+ *    engine. The host reads a session's selection from its log and the change is
+ *    about to land on that session's next build, so the write has to happen at
+ *    the switch rather than at the next request.
+ *  - {@link ModelSelectionReset.guardFor} — a session being BUILT. The router
+ *    wraps the caller's `setup` for it, which is the one moment the plugin holds
+ *    the session before the host installs the selection for it
+ *    (`composeAgent`'s `setup` → `installSelection`), so the write still lands
+ *    before the first request — and it is what gives a NEW session on a hosted
+ *    engine its seat. For the harness loop this trigger also settles a defect the
+ *    build path owns: `session.selectModel` saves the pick it was given as the
+ *    DEPLOYMENT default (`packages/api/session-controller/src/commands.ts`
+ *    `selectModel` → `AgentDefaultModelConfig.saveSelection`), that default is
+ *    the selection of every session with nothing in its log, and the menu now
+ *    carries the hosted route as an entry — so ONE pick made while a hosted
+ *    session was open would otherwise hand every session built on the harness
+ *    loop a route no adapter serves.
+ *
+ * THREE judgements keep those writes honest, and both triggers share them
+ * ({@link ModelSelectionReset.appendSeat}):
+ *
+ *  - a REAL model selection is never overwritten. The test is the provider
+ *    ({@link isHostedProviderRoute}): only a label some hosted engine logs is a
+ *    seat this module owns. An explicit pick — the model menu's own event, which
+ *    also becomes the deployment default — survives every engine change, which is
+ *    what the browser half's model notice tells the user: under a hosted engine a
+ *    dsh model is inert, not forbidden.
+ *  - a session that already selects the target (provider and model) is left
+ *    alone, so repeated switches never grow the log.
+ *  - an engine SWITCH has nothing to write for a session whose log names no
+ *    selection at all: there is no seat to rewrite, and naming a session's first
+ *    seat is the BUILD trigger's job ({@link ModelSelectionReset.guardFor}), not
+ *    a switch's. Such a session still selects the deployment default — the host's
+ *    own fallback — so nothing is broken while the seat shows it.
+ *
+ * A deployment that composes no `agentDefaultModel` service, or one whose
+ * service cannot name a usable selection, is not an error here: the trigger is
+ * either the user's own action or a session about to run, and neither must fail
+ * over a selection this plugin cannot name. The write is skipped with ONE
+ * warning, and the session keeps whatever its log records.
+ *
+ * @module dsh-loop-engine/model-selection-reset
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { SessionModelSelection } from './driver-core/host-servers.ts';
+import type { LoopEngineId } from './settings.ts';
+declare module '@deepseek-ai/dsh-session/types' {
+    interface SessionEventMap {
+        /**
+         * Complete validated model selection requested for subsequent prompt
+         * assembly. Log-only: it never enters derived model history.
+         */
+        'model/selection': {
+            /** Registered provider route. */
+            readonly provider: string;
+            /** Provider-owned model id. */
+            readonly model: string;
+            /** Adapter-owned reasoning effort, or provider/default behavior when absent. */
+            readonly reasoningEffort?: string;
+        };
+    }
+}
+/** The host's `agentDefaultModel` service (`packages/core/agent-default-model`), as this read needs it. */
+export interface AgentDefaultModelService {
+    /**
+     * The selection the host gives an Agent created without one. Read live on
+     * every call, because the settings layer it reads may change at any time.
+     * @returns the deployment's default provider, model, and optional effort.
+     */
+    currentSelection(): SessionModelSelection;
+}
+/**
+ * Keeps a session's model selection on the seat the engine driving it owns — the
+ * shared `external/default` of a hosted engine, or a real model for the harness
+ * loop.
+ *
+ * One instance per router: the "cannot name a default" and "the default itself
+ * names a hosted route" warnings are each owed once per process, not once per
+ * session.
+ */
+export declare class ModelSelectionReset {
+    private readonly ctx;
+    private readonly warn;
+    /** Whether the one warning this deployment is owed has been reported. */
+    private warned;
+    /** Whether the one report that the deployment default names a hosted route has been made. */
+    private reportedHostedDefault;
+    /**
+     * @param ctx - context carrying the host's default-model service, its settings
+     *   (for the configured default), and the session-projection registry.
+     * @param warn - diagnostic sink, used at most once per problem.
+     */
+    constructor(ctx: Context, warn: (message: string) => void);
+    /**
+     * Give one session the selection the engine it is being SWITCHED TO owns,
+     * unless its log already names a real model of its own.
+     *
+     * The switch trigger. A session whose log names no selection at all is left
+     * alone: a switch rewrites a seat an engine already put there, and naming a
+     * session's first seat belongs to the build of a session being created
+     * ({@link guardFor}) rather than to a change of engine.
+     * @param session - the live Session the engine switch is being recorded for.
+     * @param engine - the engine the session is being moved to.
+     * @returns whether a `model/selection` event was appended.
+     */
+    resetFor(session: Session, engine: LoopEngineId): boolean;
+    /**
+     * Give one session the selection the engine BUILDING it owns, inside the
+     * router's wrapped `setup` — before the caller's own setup installs the
+     * session's selection — so a selection written here is the one the host reads
+     * back for the agent being built.
+     *
+     * The harness loop's own build keeps its narrower precondition: it makes real
+     * model calls, so it is the one build that must not be left selecting a
+     * placeholder route, and a session whose own log already names a real model
+     * needs nothing written for it. A hosted engine is being given its seat here,
+     * which is what a new session on it starts from.
+     * @param session - the session whose agent is being composed.
+     * @param engine - the engine composing it.
+     * @returns whether a `model/selection` event was appended.
+     */
+    guardFor(session: Session, engine: LoopEngineId): boolean;
+    /**
+     * Whether the selection this session's next request would use names one of
+     * the hosted engines' provider routes — a label this plugin serves as a
+     * placeholder and cannot answer a real model call on.
+     *
+     * The read is the host's own (`selectionFor`): a pending selection, else the
+     * logged header, else the deployment's default. A session with nothing in its
+     * log is therefore judged on the deployment default — the value the model menu
+     * can write a hosted label into — and that default is read AS IT IS, never as
+     * {@link defaultSelection} would substitute it: the substitution only exists
+     * once it is written into the session, so judging the substitute would skip
+     * the write that makes it real.
+     * @param session - the session whose selection is being judged.
+     * @returns whether that selection names a hosted engine route.
+     */
+    private selectsHostedRoute;
+    /**
+     * Append the selection one engine's seat carries, by the judgements both
+     * triggers share.
+     *
+     * A real model selection is never overwritten — the provider is the test,
+     * because only a label some hosted engine logs is a seat this module owns — and
+     * a session that already selects the target route is left alone. Provider and
+     * model are the comparison: a reasoning effort the target carries is not a
+     * reason to log a second event for a session that already selects the same
+     * route, and re-appending would only grow the log on every switch.
+     * @param session - the session whose selection is being written.
+     * @param engine - the engine whose seat the session should select.
+     * @returns whether a `model/selection` event was appended.
+     */
+    private appendSeat;
+    /**
+     * The selection one engine's seat carries: a hosted engine's shared
+     * `external/default`, or — for the harness loop — the deployment's default,
+     * with the substitution {@link defaultSelection} documents.
+     * @param engine - the engine a session runs, or is being moved to.
+     * @returns the selection to write, or undefined when this process cannot name
+     *   one for that engine.
+     */
+    private seatOf;
+    /**
+     * The selection the host will use for this session, by the host's own read —
+     * the shared read in `driver-core/session-model.ts` (`currentSelection`),
+     * which the four hosted drivers also use to resolve the model they hand over.
+     * @param session - the session whose selection is being read.
+     * @returns the current selection, or undefined when the log records none.
+     */
+    private currentSelection;
+    /**
+     * The selection the deployment's own `agentDefaultModel` service answers, or
+     * undefined when this process cannot read one (reported once).
+     *
+     * Read twice for two different questions — as the selection a session with
+     * nothing in its log would use ({@link selectsHostedRoute}), and as the value
+     * this plugin restores ({@link defaultSelection}) — so the substitution below
+     * never hides the fact that the saved default itself is unusable.
+     * @returns the validated default, or undefined when it cannot be named.
+     */
+    private deploymentDefault;
+    /**
+     * The selection this plugin restores: the deployment's default, or — when that
+     * default names a hosted engine ROUTE — the model the deployment's own
+     * composition declares instead.
+     *
+     * The route case is not hypothetical: `session.selectModel` saves whatever the
+     * model menu submitted as the deployment default, and the menu carries the
+     * hosted route as an entry, so one pick made while a hosted session was open
+     * puts a label there that no adapter serves a real model on — handing it to a
+     * session the harness loop drives would fail that session's first request
+     * loud. The composed default is a real model the deployment itself asked for,
+     * so nothing is guessed on its behalf.
+     * @returns the restored selection, or undefined to skip the write.
+     */
+    private defaultSelection;
+    /**
+     * The model the DEPLOYMENT's own composition declares as its default, read
+     * from the settings descriptor's `base` layer — the value a saved (user-layer)
+     * default overrode.
+     *
+     * This is what replaces a default that names a hosted route, and it is read
+     * live because the composition is what the deployment itself configured:
+     * `packages/bundle/base/cordis.patch.yml` gives the `agent-default-model` row
+     * a real provider and model, and only the user layer can hold a pick made from
+     * the model menu.
+     * @returns the configured default, or undefined when this deployment composes
+     *   no default-model section, cannot enumerate settings, configured no usable
+     *   provider/model, or configured a hosted route there too.
+     */
+    private configuredDefault;
+    /** Read the host session-projection registry, structurally. */
+    private projections;
+    /**
+     * Report the one thing this read could not answer, once per plugin lifetime.
+     *
+     * Repeated triggers must not repeat it: a deployment without the service would
+     * otherwise log a line per session built for as long as it runs.
+     * @param problem - what this process cannot read, with the reason.
+     * @returns undefined, so callers can `return this.unavailable(…)` to skip.
+     */
+    private unavailable;
+}
+//# sourceMappingURL=model-selection-reset.d.ts.map

package/lib/types/patch-manager.d.ts

@@ -2,65 +2,83 @@
  * Managed-block editing for a profile's `cordis.patch.yml`.
  *
  * The plugin owns one contiguous block inside the user's patch file, delimited
- * by a begin/end marker pair, and rewrites only that span on engine switches
- * — everything else the user wrote (other patches, their comments) survives
- * byte for byte. The block's content is the loader patch that takes the loop
- * engine over: it disables the base bundle's `agent-loop` row so this plugin's
- * factory (hosted by dsh-loop-engine) can register without colliding, because
- * the harness admits exactly one AgentFactory:
+ * by a begin/end marker pair, and rewrites only that span — everything else the
+ * user wrote (other patches, their comments) survives byte for byte. The block
+ * is what hands the process-wide AgentFactory slot to this plugin's router: it
+ * disables the base bundle's `agent-loop` row, because the harness admits
+ * exactly one AgentFactory and the router (which extends the harness loop, and
+ * therefore serves `in-process` sessions too) registers itself as that one.
  *
- *   # -- dsh-loop-engine managed block: claude-code --
+ *   # -- dsh-loop-engine managed block --
  *   - id: agent-loop
  *     disabled: true
  *   - id: command-goal
  *     disabled: true
  *   # -- /dsh-loop-engine managed block --
  *
- * The `command-goal` row goes down with the loop: a hosted engine owns the
- * session's command surface, and dsh's `/goal` would otherwise collide with
- * an engine's own goal command (Kimi) or dangle over a goal service nothing
- * drives (the other engines). The remaining dsh-native commands (`/export`,
- * `/feedback`, `/permission`) are engine-agnostic session/settings controls
- * that keep working under a hosted engine, so they stay.
+ * The block names no engine. Which engine a session runs is a PER-SESSION
+ * decision carried by its agent preset, so it cannot live in a process-wide
+ * configuration file; the block's only job is to free the slot for the router.
+ * The `command-goal` row goes down with the loop: it is the host-plane copy of
+ * dsh's goal command, and a goal service nothing drives has no business being
+ * mounted for a profile whose loop is decided per session. The remaining
+ * dsh-native commands (`/export`, `/feedback`, `/permission`) are
+ * engine-agnostic session and settings controls that keep working under every
+ * engine. Per-session command surfaces are the preset's business — a hosted
+ * session joins an engine preset that strips `command-goal` itself, which is the
+ * only place that reaches the preset-layer registration.
  *
- * `in-process` renders an absent block (the base bundle's `agent-loop` row
- * stays active and supplies the factory), so switching back removes the span
- * entirely. Any other engine renders the same disable block, and the begin
- * marker carries the specific engine id (`# -- dsh-loop-engine managed block:
- * claude-code --`) so `currentEngineOf` can read which non-default engine owns
- * the slot from the file alone. All functions here are pure string transforms —
- * file I/O and durability live in the plugin's apply.
+ * Blocks written before the plugin routed per session carried the single
+ * engine's id in the begin marker (`# -- dsh-loop-engine managed block:
+ * claude-code --`). {@link legacyBlockEngineOf} reads that form so an upgrade
+ * can carry the pinned engine into the settings seed before the block is
+ * rewritten to the engine-agnostic form; a legacy block is otherwise treated as
+ * a present block by {@link hasManagedBlock}.
+ *
+ * All functions here are pure string transforms — file I/O and durability live
+ * in the plugin's apply.
  *
  * @module dsh-loop-engine/patch-manager
  */
 import type { LoopEngineId } from './settings.ts';
 /** Begin marker of the plugin-managed span inside a profile patch file. */
-export declare const MANAGED_BLOCK_BEGIN = "# -- dsh-loop-engine managed block: ";
+export declare const MANAGED_BLOCK_BEGIN = "# -- dsh-loop-engine managed block --";
+/**
+ * Begin-marker prefix of the pre-routing block form, which named the one engine
+ * the profile was pinned to.
+ */
+export declare const LEGACY_MANAGED_BLOCK_BEGIN = "# -- dsh-loop-engine managed block: ";
 /** End marker of the plugin-managed span inside a profile patch file. */
 export declare const MANAGED_BLOCK_END = "# -- /dsh-loop-engine managed block --";
-/** Render the managed block for one engine; `in-process` returns the empty span. */
-export declare function renderManagedBlock(engine: LoopEngineId): string;
-/** Whether a patch-file text contains the managed block span. */
+/** The loader patch that frees the single AgentFactory slot for the router. */
+export declare function renderManagedBlock(): string;
+/**
+ * Whether a patch-file text contains the LEGACY managed block span, which
+ * named the single engine the profile used to be pinned to.
+ */
+export declare function hasLegacyManagedBlock(text: string): boolean;
+/**
+ * Whether a patch-file text contains the managed block span, in either the
+ * current or the legacy form.
+ */
 export declare function hasManagedBlock(text: string): boolean;
 /**
- * The engine id the managed block's begin marker names, when this build knows
- * it. `undefined` covers both "no managed block" and "the block names an engine
- * this build does not recognize" — the second being the state where the block
- * still disables the base `agent-loop` row while no factory can take the slot.
+ * The engine a LEGACY managed block pinned the profile to, when the block has
+ * that form and names an engine this build knows. `undefined` covers the
+ * current engine-agnostic block, no block at all, and a legacy block naming an
+ * engine this build does not recognize.
  */
-export declare function managedBlockEngineOf(text: string): LoopEngineId | undefined;
-/** Derive the current engine from a patch-file text by the managed block's begin marker. */
-export declare function currentEngineOf(text: string): LoopEngineId;
+export declare function legacyBlockEngineOf(text: string): LoopEngineId | undefined;
 /**
- * Produce the next patch-file text for a target engine, preserving every byte
- * outside the managed span. Appends the span when absent; replaces or removes
- * it when present. The managed block is a root-level collection, so a leftover
- * seed `[]` is dropped when adding it, and a removal that leaves no entries is
- * re-seeded back to `[]` — either way the file stays a single valid top-level
- * array the harness can boot.
+ * Produce the next patch-file text carrying the managed block, preserving every
+ * byte outside the managed span. Appends the span when absent and replaces it
+ * when present — including a legacy span, which is rewritten to the current
+ * form. The managed block is a root-level collection, so a leftover seed `[]`
+ * is dropped with it, leaving the file a single valid top-level array the
+ * harness can boot: the block's own `- id: agent-loop` is a column-0 entry, so
+ * a file carrying it never needs a re-seed.
  * @param text - current patch-file text.
- * @param engine - target engine.
  * @returns the rewritten patch-file text.
  */
-export declare function applyManagedBlock(text: string, engine: LoopEngineId): string;
+export declare function applyManagedBlock(text: string): string;
 //# sourceMappingURL=patch-manager.d.ts.map