@intx/hub-sessions 0.1.2 → 0.3.0

package/dist/session-service.js

@@ -0,0 +1,1191 @@
+import { type } from "arktype";
+import { and, eq } from "drizzle-orm";
+import { getLogger } from "@intx/log";
+import { assembleMessage, assembleSignedContent, createDetachedSignatureFromProvider, } from "@intx/mime";
+import { buildCredentialDelivery, listAssetsForTenant, } from "@intx/db";
+import { grant as grantTable, sidecarAllocation as sidecarAllocationTable, workflowDefinition as workflowDefinitionTable, workflowRun as workflowRunTable, } from "@intx/db/schema";
+import { base64Encode, hexEncode } from "@intx/types";
+import { generateId } from "@intx/hub-common";
+import { sessionAsset as sessionAssetTable } from "@intx/db/schema";
+import { AssetRegistrySource, HttpRegistrySource, ManifestInvalidError, createClosureResolver, } from "@intx/tool-packaging";
+import { ToolPackageManifest, } from "@intx/types/tool-packages";
+import { computeWireDefinitionHash } from "@intx/types/wire-definition-hash";
+import { buildInertProjectionStepSources, deriveRunAddress, enumerateInertOnTriggerBodies, pickStepInferenceSource, WorkflowDefinitionInvalidError, } from "@intx/workflow-deploy";
+import { DEFAULT_ASSET_REF, } from "./asset-service.js";
+import { buildSourceAssetMounts, } from "./workflow-closure-resolution.js";
+import { restoreWorkflowRunToAllocation } from "./workflow-run-restore.js";
+import { committedReadsToSourceTree } from "./committed-source-tree.js";
+import { installAndApproveWorkflowDefinition, } from "./workflow-probe-gate.js";
+const logger = getLogger(["interchange", "hub", "session-service"]);
+export class SessionLaunchError extends Error {
+    /** Which phase failed: "write", "provision", "pack", or "start". */
+    phase;
+    /** True if the sidecar has a provisioned agent that could not be cleaned up. */
+    leakedAgent;
+    constructor(phase, cause, leakedAgent) {
+        const msg = cause instanceof Error ? cause.message : "Session launch failed";
+        super(msg, { cause });
+        this.name = "SessionLaunchError";
+        this.phase = phase;
+        this.leakedAgent = leakedAgent;
+    }
+}
+// Hub-side principal for reading asset repos. Assets are signed by the
+// hub itself, and the launch fan-out reads them on the hub to assemble
+// packs for delivery to a sidecar -- so the hub principal is correct.
+const HUB_PRINCIPAL = { kind: "hub" };
+async function createPackSha(pack) {
+    const digest = await crypto.subtle.digest("SHA-256", 
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- ArrayBuffer-backed at the call site; Web Crypto's BufferSource type rejects Uint8Array<ArrayBufferLike> under TS 5.9 (microsoft/TypeScript#62240)
+    pack);
+    return hexEncode(new Uint8Array(digest));
+}
+/**
+ * Walk a resolved tool-package manifest and return every distinct
+ * `assetId` referenced by a `kind: "asset"` entry. Order is the
+ * resolver's BFS order so the fan-out below is deterministic for
+ * tests; a `Set` would be wrong here because tests assert specific
+ * orderings.
+ */
+function collectDistinctAssetIds(manifest) {
+    const seen = new Set();
+    const out = [];
+    for (const entry of manifest.entries) {
+        if (entry.source.kind !== "asset")
+            continue;
+        if (seen.has(entry.source.assetId))
+            continue;
+        seen.add(entry.source.assetId);
+        out.push(entry.source.assetId);
+    }
+    return out;
+}
+/**
+ * Translate the orchestrator's structural `DeployContent` (which types
+ * `toolPackageManifest` as `unknown`) back into the hub-sessions
+ * `DeployContent` shape. The orchestrator round-trips whatever the
+ * caller supplied, but the surface type widens `toolPackageManifest` to
+ * `unknown`; the validator narrows it back to the canonical shape
+ * `agentRepoStore.writeDeployTree` consumes.
+ *
+ * Exported so a test fixture that forwards orchestrator-shaped deploy
+ * content into `launchSession` narrows it the same validated way the
+ * production multi-step callback does, rather than casting `unknown`.
+ */
+export function bridgeOrchestratorDeployContent(content) {
+    const bridged = { systemPrompt: content.systemPrompt };
+    if (content.toolPackageManifest !== undefined) {
+        const validated = ToolPackageManifest(content.toolPackageManifest);
+        if (validated instanceof type.errors) {
+            throw new Error(`orchestrator deploy content carries an invalid toolPackageManifest: ${validated.summary}`);
+        }
+        bridged.toolPackageManifest = validated;
+    }
+    if (content.assetMounts !== undefined) {
+        bridged.assetMounts = content.assetMounts;
+    }
+    return bridged;
+}
+/**
+ * Emit the source-ref deploy frame onto `SidecarRouter.sendAgentDeploy`. The
+ * router accepts an optional `workflow` projection on the deploy frame; the
+ * sidecar's deploy router uses field presence to route the frame to the
+ * workflow deploy path, and returns the supervisor public key on the
+ * `agent.deploy.ack`.
+ *
+ * The gate/freeze layer already hashed the inert projection, so the frozen hash
+ * and the inert projection ride the frame verbatim -- this never recomputes the
+ * content hash. Recomputing over a live wire lineage would diverge from the
+ * inert projection the child re-verifies against.
+ *
+ * Exported so the co-located caller-site test can assert that the constructed
+ * closure reaches the wire surface via `sendAgentDeploy` with a `workflow`
+ * field structurally matching the `AgentDeployFrame.workflow` schema.
+ */
+export async function sendMultiStepDeployFrame(args) {
+    const workflow = {
+        // The deploy frame carries no inline definition: the sidecar evaluates the
+        // pinned code closure from `sourceRef` and re-verifies it against
+        // `approvedWireHash`. Only the gate-frozen hash and the pin ride the frame.
+        sources: args.sources,
+        approvedWireHash: args.approvedWireHash,
+        sourceRef: args.sourceRef,
+        ...(args.credentials !== undefined
+            ? { credentials: args.credentials }
+            : {}),
+        ...(args.referencedDefinitions !== undefined &&
+            args.referencedDefinitions.length > 0
+            ? { referencedDefinitions: [...args.referencedDefinitions] }
+            : {}),
+        ...(args.assets !== undefined && args.assets.length > 0
+            ? { assets: [...args.assets] }
+            : {}),
+    };
+    // A prepared exclusive deploy routes its frame to the dedicated allocation; a
+    // shared deploy sends it on the shared router. The frozen projection/hash/pin
+    // ride verbatim in both cases -- only the transport differs.
+    if (args.allocationTarget !== undefined) {
+        if (args.sidecarAllocationRouter === undefined) {
+            throw new Error("Exclusive deployment routing is not configured");
+        }
+        return args.sidecarAllocationRouter.sendAgentDeployToAllocation(args.allocationTarget, args.agentAddress, args.config, workflow);
+    }
+    return args.sidecarRouter.sendAgentDeploy(args.agentAddress, args.config, workflow);
+}
+function isAssetDeployArgs(args) {
+    return args.source.kind === "asset";
+}
+/**
+ * The single public composition entrypoint for a code-sourced (npm) deploy. It
+ * consumes the approve output and builds the source-ref deploy frame internally,
+ * so the security-load-bearing hand-off -- frozen wire hash, inert projection,
+ * frozen closure -- is assembled in one place from one cohesive object rather
+ * than reassembled by each caller. The frozen approval's hash and projection
+ * ride the frame verbatim: nothing here recomputes the hash or re-resolves the
+ * closure, so the child re-verify over the inert projection matches the gate's
+ * freeze.
+ *
+ * Credential MATERIAL for the definition's tenant-owned bindings is resolved
+ * here (`buildCredentialDelivery`) and delivered to the child on the frame.
+ * Credential GRANT enforcement is a SEPARATE layer: the `credential:{id}` /
+ * `use` grant the runtime gate checks is minted per-run by run-grant
+ * materialization into `runs/<runId>/grants.json`, not carried on this frame --
+ * the deploy-time `config.grants` spawn-time snapshot is suppressed once the
+ * sidecar wires per-run grant pushes, so it is not the enforcement transport.
+ *
+ * A gate outcome that did not approve cannot deploy: an unapproved `approval`
+ * fails closed here rather than shipping an unfrozen definition.
+ *
+ * This emits the source-ref deploy frame ONLY -- it does NOT write the anchor
+ * `workflow_run` row. `deployCodeSourcedWorkflow` wraps it with the shared-path
+ * INSERT; the prepared exclusive path wraps it with an UPDATE-under-lock of the
+ * anchor row that already exists from prepare time. It returns the frozen
+ * definition id so each wrapper writes the same content-addressed identity the
+ * gate persisted.
+ */
+async function emitSourceRefDeployFrame(args) {
+    const { approval, projection, closure } = args.approved;
+    if (!approval.ok) {
+        throw new Error(`deployCodeSourcedWorkflow: refusing to deploy an unapproved workflow (gate reason: ${approval.reason})`);
+    }
+    // Fail-closed persisted-definition guard. The anchor row this writes carries
+    // an FK to `workflow_definition`, so a phantom `definitionId` would otherwise
+    // reach the INSERT and fail with a raw constraint violation. A mis-wired
+    // caller -- or a test double that skips the approve step's DB writer -- could
+    // pass an approval whose definition was never persisted; verify it exists and
+    // fail with a domain error before deploying, rather than deploying and then
+    // failing the anchor insert into a deployed-but-unanchored state.
+    const persistedDefinition = await args.db.query.workflowDefinition.findFirst({
+        where: eq(workflowDefinitionTable.id, approval.definitionId),
+        columns: { id: true },
+    });
+    if (persistedDefinition === undefined) {
+        throw new Error(`deployCodeSourcedWorkflow: approval.definitionId ${approval.definitionId} does not reference a persisted workflow_definition row`);
+    }
+    // Coherence guard, run BEFORE the deploy frame: the anchor row's id and its
+    // routing address must name the same run. The deployment mail address is
+    // frozen into the approved package bytes at authoring time, so its run id is
+    // fixed before this runs and the caller owns `anchorRunId`. A mismatched
+    // (anchorRunId, agentAddress) pair would let run-grant materialization find
+    // the anchor by `address` while `deriveRunAddress` from `anchorRunId` names a
+    // different run -- a silent grant-identity split. Fail closed here, before the
+    // frame is sent or any row is persisted, rather than deploying an incoherent
+    // pair.
+    const derivedAddress = deriveRunAddress({
+        runId: args.anchorRunId,
+        domain: args.deploymentDomain,
+    });
+    if (derivedAddress !== args.agentAddress) {
+        throw new Error(`deployCodeSourcedWorkflow: anchorRunId ${args.anchorRunId} derives address ${derivedAddress} but agentAddress is ${args.agentAddress}`);
+    }
+    // Resolve the operator-approved credential bindings into delivered material.
+    // Tenant-owned resolution keys off the definition's tenant and walks up the
+    // hierarchy; it does not consult creator/invoker (the only locator today is
+    // `tenant`). A code-sourced deployment has no single authenticated invoker,
+    // so invoker is null; when principal-owned locators arrive, the asset creator
+    // must be resolved and passed here. A resolution failure is fail-closed.
+    const bindings = projection.credentialBindings ?? [];
+    let credentials;
+    if (bindings.length > 0) {
+        if (args.credentialCipher === undefined) {
+            throw new Error("deployCodeSourcedWorkflow: definition carries credential bindings but " +
+                "no credentialCipher was supplied; cannot resolve credential material");
+        }
+        const delivery = await buildCredentialDelivery({
+            db: args.db,
+            tenantId: args.tenantId,
+            bindings,
+            creatorPrincipalId: null,
+            invokerPrincipalId: null,
+            credentialCipher: args.credentialCipher,
+        });
+        if (!delivery.ok) {
+            throw new Error(`deployCodeSourcedWorkflow: credential binding resolution failed: ${delivery.reason.message}`);
+        }
+        credentials = delivery.delivery;
+    }
+    // Pin per-step inference sources for the projection's inline onTrigger bodies.
+    // The hub holds only the frozen inert projection, so it enumerates the inline
+    // bodies from the wire form and resolves each body step's source through the
+    // same resolver + operator-approval gate the top-level steps use
+    // (`pickStepInferenceSource` against `approval.approvedGrants`). Each body's
+    // wire hash is recomputed from the inert body verbatim, so a body child's
+    // re-verify over the re-evaluated closure clears the same barrier a top-level
+    // re-verify does. The pinned sources ride OUTSIDE the hash; their trust comes
+    // from being resolved here under the approval gate, which is why the pin stays
+    // hub-side and is never caller-supplied.
+    //
+    // These entries ride the `referencedDefinitions` wire field. Each entry's
+    // `definition` is the approved inert body def straight from the frozen,
+    // hash-covered projection (id set to the ref); the sidecar reads that id to
+    // key the per-body approved hash and to stage the body's `sources.json`, which
+    // the body child reads to pin its steps. The body child resolves the body
+    // DEFINITION itself in-memory from the re-verified closure and hard-fails
+    // rather than reading it off disk, so no body workflow.json is staged (see the
+    // staging loop in workflow-host-wiring.ts and the anti-fallback guard in
+    // workflow-host run-child.ts).
+    const referencedDefinitions = await Promise.all(enumerateInertOnTriggerBodies(projection).map(async (body) => {
+        const sources = {};
+        for (const bodyStepId of body.definition.stepOrder) {
+            // Agent-bearing body steps run inference and need a source pinned
+            // through the approval gate. A non-agent body step (sleep,
+            // awaitSignal) declares no preference and runs no inference, so it
+            // advertises no `inference.source` grant the gate could approve --
+            // but the deploy frame's coverage contract still requires a source
+            // entry for EVERY body step. Pin the deploy's default source as an
+            // inert placeholder for such a step: the body child resolves a
+            // step's source only when that step invokes inference, so this entry
+            // is never read, which is why it needs no operator approval.
+            const preferred = body.preferredByStep[bodyStepId] ?? null;
+            if (preferred === null) {
+                const placeholder = args.config.sources.find((s) => s.id === args.config.defaultSource);
+                if (placeholder === undefined) {
+                    throw new WorkflowDefinitionInvalidError(body.ref, `non-agent body step ${bodyStepId} needs an inert placeholder source, but the deploy config carries no defaultSource entry to pin`);
+                }
+                sources[bodyStepId] = [placeholder];
+                continue;
+            }
+            sources[bodyStepId] = [
+                pickStepInferenceSource({
+                    preferred,
+                    stepId: bodyStepId,
+                    workflowId: body.ref,
+                    config: args.config,
+                    operatorApprovals: approval.approvedGrants,
+                }),
+            ];
+        }
+        return {
+            definition: body.definition,
+            sources,
+            approvedWireHash: await computeWireDefinitionHash(body.definition),
+        };
+    }));
+    // An asset-sourced pin's `kind:"asset"` closure entries read from source
+    // assets the sidecar cannot fetch itself; deliver them inline on the frame so
+    // the sidecar checks them out into its durable per-deployment source store. A
+    // registry pin fetches its tarballs over HTTP and delivers none.
+    const assets = isAssetDeployArgs(args)
+        ? await buildSourceAssetMounts(closure, args.resolveAttachment)
+        : [];
+    const result = await sendMultiStepDeployFrame({
+        lineage: "source-ref",
+        sidecarRouter: args.sidecarRouter,
+        ...(args.sidecarAllocationRouter !== undefined
+            ? { sidecarAllocationRouter: args.sidecarAllocationRouter }
+            : {}),
+        ...(args.allocationTarget !== undefined
+            ? { allocationTarget: args.allocationTarget }
+            : {}),
+        agentAddress: args.agentAddress,
+        config: args.config,
+        sources: args.sources,
+        approvedWireHash: approval.approvedWireHash,
+        sourceRef: { source: args.source, closure },
+        ...(credentials !== undefined ? { credentials } : {}),
+        ...(referencedDefinitions.length > 0 ? { referencedDefinitions } : {}),
+        ...(assets.length > 0 ? { assets } : {}),
+    });
+    return { publicKey: result.publicKey, definitionId: approval.definitionId };
+}
+/**
+ * The single public composition entrypoint for a SHARED code-sourced (npm)
+ * deploy: emit the source-ref frame, then INSERT the deployment's anchor
+ * `workflow_run` row -- the deployment's first-class record that owns its
+ * routing address and public key. Run-grant materialization keys off this row
+ * (address + live status), so WITHOUT it no per-run grants (tool, capability, OR
+ * credential) ever materialize for a source-ref deployment. Born "deployed"
+ * (live but pre-trigger): the first trigger's materialization flips it to
+ * "running" via `anchorWithPrincipal`'s guarded update, which a row born
+ * "running" would skip. Its `anchorRunId` equals its own id, so the anchor
+ * references itself. The deployer read grant is deferred to the production
+ * route, which carries the authenticated deployer principal; this stays a
+ * single insert with no grant row to pair atomically.
+ *
+ * The prepared exclusive path does NOT use this wrapper: its anchor row already
+ * exists from prepare time, so it wraps `emitSourceRefDeployFrame` with an
+ * UPDATE-under-allocation-lock instead of this INSERT.
+ */
+export async function deployCodeSourcedWorkflow(args) {
+    const { publicKey, definitionId } = await emitSourceRefDeployFrame(args);
+    await args.db.insert(workflowRunTable).values({
+        id: args.anchorRunId,
+        tenantId: args.tenantId,
+        anchorRunId: args.anchorRunId,
+        definitionId,
+        address: args.agentAddress,
+        publicKey,
+        status: "deployed",
+        createdAt: new Date(),
+    });
+    return { publicKey };
+}
+export function createSessionService(deps) {
+    const { sidecarRouter, sidecarAllocationRouter, agentRepoStore, assetService, db, toolPackageRegistries, } = deps;
+    if (assetService !== undefined && db === undefined) {
+        throw new Error("createSessionService: db is required when assetService is set");
+    }
+    if (toolPackageRegistries !== undefined && db === undefined) {
+        throw new Error("createSessionService: db is required when toolPackageRegistries is set");
+    }
+    function requireAllocationRouter() {
+        if (sidecarAllocationRouter === undefined) {
+            throw new Error("Exclusive deployment routing is not configured");
+        }
+        return sidecarAllocationRouter;
+    }
+    /**
+     * Stage one per-step deploy on the sidecar: resolve assets and tool
+     * packages, write the deploy tree, provision the step, and deliver the
+     * deploy + asset packs (Phases 0-2b). Phase 1 binds a transient route for
+     * the step address, fires a no-spawn provision frame (init repo + record
+     * hub key), and unbinds the route once the packs land -- no warm harness and
+     * no child. The deployment-level workflow frame, sent once after every step
+     * is staged, spawns the child. A call without `stageOnly` is rejected -- the
+     * legacy warm-harness and single-step-head paths are gone.
+     */
+    async function executeLaunchPhases(params) {
+        const { agentAddress, agentId, runId, config, deployContent } = params;
+        const toolPackagePins = params.toolPackagePins ?? [];
+        const stageOnly = params.stageOnly ?? false;
+        let effectiveDeployContent = deployContent;
+        // Phase 0a-bis: Resolve the agent's tool-package pins into a full
+        // closure manifest. Empty pins skip the resolver entirely. A
+        // ManifestInvalidError (e.g. unsatisfied peer dependency) is a
+        // launch-time failure — the deploy never ships and the sidecar
+        // is not touched.
+        //
+        // The resolver runs once per launch with no cross-launch caching;
+        // the packument cache scopes only within a single closure walk.
+        // Acceptable at the current N (handful of agents, small pin sets
+        // per agent) — a tenant-scoped packument cache or a per-pin set
+        // resolved-manifest cache would be the obvious scaling lever
+        // when launch latency becomes the bottleneck.
+        const manifestAssetAttachments = [];
+        if (toolPackagePins.length > 0) {
+            if (toolPackageRegistries === undefined) {
+                throw new SessionLaunchError("write", new Error(`agent ${agentId} has ${String(toolPackagePins.length)} pinned tool package(s) but the session service has no toolPackageRegistries configured`), false);
+            }
+            if (assetService === undefined) {
+                throw new SessionLaunchError("write", new Error(`agent ${agentId} has pinned tool packages but the session service has no assetService configured for asset-backed registries`), false);
+            }
+            let manifest;
+            let assetIndex;
+            try {
+                const built = await buildAndResolve({
+                    agentId,
+                    tenantId: config.tenantId,
+                    pins: toolPackagePins,
+                    registries: toolPackageRegistries,
+                    assetService,
+                });
+                manifest = built.manifest;
+                assetIndex = built.assetIndex;
+            }
+            catch (err) {
+                if (err instanceof ManifestInvalidError) {
+                    logger.warn `tool-package manifest validation failed for agent ${agentId}: ${err.message}`;
+                }
+                throw new SessionLaunchError("write", err, false);
+            }
+            const assetMounts = new Map();
+            try {
+                for (const assetId of collectDistinctAssetIds(manifest)) {
+                    const asset = assetIndex.get(assetId);
+                    if (asset === undefined) {
+                        // The asset id appears in the manifest but is not in the
+                        // tenant-visible asset set. This can only happen if the
+                        // resolver's registry map and the asset index disagree —
+                        // the same scan populated both, so reaching this branch
+                        // would indicate an upstream invariant violation.
+                        throw new Error(`resolved tool-package manifest references asset ${assetId} which is not visible to tenant ${config.tenantId}`);
+                    }
+                    const mountPath = `package-registries/${asset.name}/`;
+                    assetMounts.set(assetId, mountPath);
+                    manifestAssetAttachments.push(await resolveAssetAttachment({
+                        asset,
+                        mountPath,
+                    }));
+                }
+            }
+            catch (err) {
+                throw new SessionLaunchError("write", err, false);
+            }
+            effectiveDeployContent = {
+                ...effectiveDeployContent,
+                toolPackageManifest: manifest,
+                ...(assetMounts.size > 0 ? { assetMounts } : {}),
+            };
+        }
+        // Phase 0b: Write deploy tree and produce packfile (hub-local, no
+        // sidecar state to clean up if this fails).
+        let pack;
+        let commitSha;
+        let ref;
+        try {
+            await agentRepoStore.writeDeployTree(agentId, effectiveDeployContent);
+            ({ pack, commitSha, ref } =
+                await agentRepoStore.createDeployPack(agentId));
+        }
+        catch (err) {
+            throw new SessionLaunchError("write", err, false);
+        }
+        // A stage-only per-step deploy binds a transient route for the step
+        // address so the packs below route to the deployment's sidecar; the
+        // route is held only for the pack window and dropped in the `finally`.
+        if (stageOnly) {
+            try {
+                if (params.allocationTarget === undefined) {
+                    sidecarRouter.bindStepRoute(agentAddress);
+                }
+                else {
+                    await requireAllocationRouter().bindAllocatedStepRoute(params.allocationTarget, agentAddress);
+                }
+            }
+            catch (err) {
+                throw new SessionLaunchError("provision", err, false);
+            }
+        }
+        try {
+            // Phase 1: Provision on sidecar. A stage-only per-step deploy sends a
+            // no-spawn provision frame: the sidecar inits the step's agent-state
+            // repo and records the hub key, but spawns nothing. Firing the frame
+            // before the Phase 2 pack is the ordering barrier -- the repo must
+            // exist before the pack applies.
+            try {
+                if (stageOnly) {
+                    if (params.allocationTarget === undefined) {
+                        await sidecarRouter.sendProvisionStep(agentAddress, config);
+                    }
+                    else {
+                        await requireAllocationRouter().sendProvisionStepToAllocation(params.allocationTarget, agentAddress, config);
+                    }
+                }
+                else {
+                    // Every caller supplies `stageOnly`. A deploy without it has no
+                    // provisioning shape -- the legacy warm-harness and single-step-head
+                    // paths are gone -- so fail loud rather than ship a deploy pack the
+                    // sidecar never provisioned a repo for.
+                    throw new Error("executeLaunchPhases: a deploy requires stageOnly");
+                }
+            }
+            catch (err) {
+                throw new SessionLaunchError("provision", err, false);
+            }
+            // Phase 2: Pack delivery. A stage-only step has no supervisor to
+            // undeploy, so on failure it only drops its transient route (in the
+            // `finally`). The step's inited agent-state repo is left on the sidecar:
+            // the deploy aborts before the deployment frame is sent, so there is
+            // nothing to undeploy, and a redeploy of the same deployment overwrites
+            // the orphaned repo. This is an acceptable minor leak on the exceptional
+            // staging-failure path, not a live-path cost.
+            try {
+                if (params.allocationTarget === undefined) {
+                    await sidecarRouter.sendPack(agentAddress, pack, ref, commitSha);
+                }
+                else {
+                    await requireAllocationRouter().sendPackToAllocation(params.allocationTarget, agentAddress, pack, ref, commitSha);
+                }
+            }
+            catch (err) {
+                if (!stageOnly && params.allocationTarget === undefined) {
+                    await attemptCleanup(agentAddress, "pack", err);
+                }
+                throw new SessionLaunchError("pack", err, !stageOnly && params.allocationTarget !== undefined);
+            }
+            // Phase 2b: Asset-pack fan-out. For each attached asset, build a
+            // pack, reserve the manifest row, then send the pack. The manifest
+            // reservation MUST happen before the pack send: if the sidecar acks
+            // but the row is missing, the session has materialization without
+            // a recorded manifest. An allocated replacement may reuse the exact
+            // row its predecessor recorded; ordinary launches still require a new
+            // row. If reservation fails, the pack send must not happen.
+            //
+            // The fan-out materializes the package-registry assets the
+            // tool-package resolver picked. They live behind tenant
+            // inheritance rather than a per-agent attachment row, so the
+            // session service synthesizes the attachment view in
+            // `manifestAssetAttachments`.
+            const fanOut = manifestAssetAttachments;
+            if (assetService !== undefined && fanOut.length > 0) {
+                // Track the rows this attempt owns so a later fan-out failure can roll
+                // them back in lockstep with the sidecar undeploy. Allocated rows are
+                // durable recovery intent, not attempt-owned materialization state, so
+                // replacement failures must leave them in place for the next worker.
+                const committed = [];
+                for (const att of fanOut) {
+                    try {
+                        const committedRecord = await sendAttachmentPack(runId, agentAddress, att, params.allocationTarget);
+                        if (committedRecord !== null)
+                            committed.push(committedRecord);
+                    }
+                    catch (err) {
+                        await rollbackCommittedAttachments(committed);
+                        if (!stageOnly && params.allocationTarget === undefined) {
+                            await attemptCleanup(agentAddress, "pack", err);
+                        }
+                        throw new SessionLaunchError("pack", err, !stageOnly && params.allocationTarget !== undefined);
+                    }
+                }
+            }
+        }
+        finally {
+            if (stageOnly) {
+                if (params.allocationTarget === undefined) {
+                    sidecarRouter.unbindStepRoute(agentAddress);
+                }
+                else {
+                    requireAllocationRouter().unbindAllocatedStepRoute(params.allocationTarget, agentAddress);
+                }
+            }
+        }
+    }
+    /**
+     * Stage one step of a multi-step workflow deploy: bind a transient route
+     * for the step address, fire a no-spawn provision frame (the sidecar inits
+     * the step's agent-state repo and records the hub key), deliver the deploy
+     * and asset packs, and unbind the route -- no warm harness. The multi-step
+     * branch stages every step this way, then fires ONE deployment-level
+     * workflow frame that writes the step grants and spawns the supervised
+     * workflow-process child; the child reads each step's staged deploy tree
+     * from disk and runs the step itself.
+     */
+    async function stageWorkflowStep(params) {
+        await executeLaunchPhases({
+            agentAddress: params.agentAddress,
+            agentId: params.agentId,
+            runId: params.runId,
+            config: params.config,
+            deployContent: params.deployContent,
+            stageOnly: true,
+            ...(params.toolPackagePins !== undefined
+                ? { toolPackagePins: params.toolPackagePins }
+                : {}),
+            ...(params.allocationTarget !== undefined
+                ? { allocationTarget: params.allocationTarget }
+                : {}),
+        });
+    }
+    // Resolve the npm registry config a code-sourced install resolves external
+    // deps against, by the registry name. A code-sourced deploy needs the
+    // registry map configured; a hub that mounts the deploy surface without it is
+    // mis-wired, so this fails loud rather than defaulting a registry URL.
+    function requireRegistryConfig(registryName) {
+        if (toolPackageRegistries === undefined) {
+            throw new Error("deployWorkflowFromSource: the session service has no toolPackageRegistries configured; a code-sourced deploy cannot resolve its dependency closure");
+        }
+        const config = toolPackageRegistries.httpRegistries.get(registryName);
+        if (config === undefined) {
+            throw new Error(`deployWorkflowFromSource: no HTTP registry named ${JSON.stringify(registryName)} is configured`);
+        }
+        return config;
+    }
+    // Build the git-pack resolver a source/tarball asset arm delivers inline. The
+    // pin names one backing asset, so the resolver binds that asset's repo (its
+    // kind fixed by the arm) and its default ref; a request for any OTHER asset id
+    // is a closure that reaches beyond its single backing asset and fails loud
+    // rather than silently packing the wrong repo.
+    function bindAssetAttachmentResolver(assetId, repoKind) {
+        return async (requestedAssetId) => {
+            if (requestedAssetId !== assetId) {
+                throw new Error(`deployWorkflowFromSource: closure references asset ${requestedAssetId}, but only the pinned source asset ${assetId} is deliverable`);
+            }
+            const repoId = { kind: repoKind, id: assetId };
+            const commitSha = await agentRepoStore.repoStore.resolveRef(HUB_PRINCIPAL, repoId, DEFAULT_ASSET_REF);
+            if (commitSha === null) {
+                throw new Error(`deployWorkflowFromSource: source asset ${assetId} has no commit on ${DEFAULT_ASSET_REF}`);
+            }
+            const { pack, ref } = await agentRepoStore.repoStore.createPack(HUB_PRINCIPAL, repoId, DEFAULT_ASSET_REF);
+            return { pack, ref, commitSha };
+        };
+    }
+    // Assemble the install args for the concrete source arm. Mirrors the
+    // `isAssetSourceInstallArgs`/`isAssetTarballInstallArgs` guards the probe gate
+    // narrows on: an asset-`source` arm binds committed reads at the pinned commit
+    // plus the npm registry for external deps; an asset-`tarball` arm binds the
+    // asset's blob reads and a pin; a `registry` arm carries only its registry
+    // config and a pin. A `pin` missing where the arm requires it fails closed.
+    async function buildInstallArgs(params, resolveAttachment) {
+        if (db === undefined) {
+            throw new Error("deployWorkflowFromSource requires a db handle to freeze the approval");
+        }
+        const dbHandle = db;
+        const common = {
+            entry: params.entry,
+            assetId: params.definitionAssetId,
+            approvals: { mode: "approve-probed" },
+            router: sidecarRouter,
+            db: dbHandle,
+        };
+        const source = params.source;
+        if (source.kind === "asset") {
+            if (resolveAttachment === null) {
+                throw new Error("deployWorkflowFromSource: an asset-sourced deploy requires an attachment resolver");
+            }
+            if (source.package.format === "source") {
+                const committed = await agentRepoStore.repoStore.openCommittedReadsAtCommit(HUB_PRINCIPAL, { kind: "workflow", id: source.assetId }, source.package.commitSha);
+                if (committed === null) {
+                    throw new Error(`deployWorkflowFromSource: source asset ${source.assetId} has no commit ${source.package.commitSha}`);
+                }
+                const registryName = requireDefaultRegistryName();
+                return {
+                    ...common,
+                    source,
+                    reads: committedReadsToSourceTree(committed),
+                    registryName,
+                    registryConfig: requireRegistryConfig(registryName),
+                    resolveAttachment,
+                };
+            }
+            if (params.pin === undefined) {
+                throw new Error("deployWorkflowFromSource: an asset-tarball deploy requires a name@range pin");
+            }
+            if (assetService === undefined) {
+                throw new Error("deployWorkflowFromSource: an asset-tarball deploy requires an asset service to read the package blobs");
+            }
+            const tarballAssetId = source.assetId;
+            const tarballService = assetService;
+            return {
+                ...common,
+                source,
+                pin: params.pin,
+                readBlob: (path) => tarballService.readAssetBlob({ assetId: tarballAssetId, path }),
+                listBlobs: (dir) => tarballService.listAssetBlobs({ assetId: tarballAssetId, dir }),
+                resolveAttachment,
+            };
+        }
+        if (params.pin === undefined) {
+            throw new Error("deployWorkflowFromSource: a registry deploy requires a name@range pin");
+        }
+        return {
+            ...common,
+            source,
+            pin: params.pin,
+            registryConfig: requireRegistryConfig(source.registry),
+        };
+    }
+    function requireDefaultRegistryName() {
+        if (toolPackageRegistries === undefined) {
+            throw new Error("deployWorkflowFromSource: the session service has no toolPackageRegistries configured; a code-sourced deploy cannot resolve its dependency closure");
+        }
+        return toolPackageRegistries.defaultRegistry;
+    }
+    // Bind the pack resolver an asset arm delivers inline. An asset arm delivers
+    // its backing repo (its kind fixed by `package.format`); a registry arm
+    // fetches its tarballs over HTTP and delivers no asset, so it binds nothing.
+    // Both the install (probe) and the deploy rebind the SAME resolver from the
+    // source, so a prepared deploy reconstructs it from the frozen `source`.
+    function bindSourceAttachmentResolver(source) {
+        return source.kind === "asset"
+            ? bindAssetAttachmentResolver(source.assetId, source.package.format === "source" ? "workflow" : "package-registry")
+            : null;
+    }
+    // Install + probe + gate + freeze a code-sourced definition, returning the
+    // frozen bundle and the (asset-only) attachment resolver. The gate outcome is
+    // NOT asserted here: `deployWorkflowFromSource` and `installAndApproveWorkflowSource`
+    // each surface a non-approval as their own domain error. This is the shared
+    // freeze both the shared deploy and the exclusive prepare run.
+    async function prepareCodeSourcedApproval(params) {
+        const resolveAttachment = bindSourceAttachmentResolver(params.source);
+        const installArgs = await buildInstallArgs(params, resolveAttachment);
+        const approved = await installAndApproveWorkflowDefinition(installArgs);
+        return { approved, resolveAttachment };
+    }
+    // Freeze a code-sourced approval on shared capacity WITHOUT deploying it. The
+    // exclusive prepare path persists the returned bundle and deploys it to a
+    // dedicated allocation later. A non-approval fails closed as an invalid
+    // definition.
+    async function installAndApproveWorkflowSource(params) {
+        const { approved } = await prepareCodeSourcedApproval(params);
+        if (!approved.approval.ok) {
+            throw new WorkflowDefinitionInvalidError(approved.projection.id, `code-sourced workflow install did not approve (reason: ${approved.approval.reason})`);
+        }
+        return approved;
+    }
+    async function deployWorkflowFromSource(params) {
+        if (db === undefined) {
+            throw new Error("deployWorkflowFromSource requires a db handle to record the deployment's anchor run");
+        }
+        const source = params.source;
+        const { approved, resolveAttachment } = await prepareCodeSourcedApproval(params);
+        if (!approved.approval.ok) {
+            throw new WorkflowDefinitionInvalidError(approved.projection.id, `code-sourced workflow install did not approve (reason: ${approved.approval.reason})`);
+        }
+        // Pin every top-level step's inference source under the frozen approval,
+        // then hand the frozen bundle to the source-ref deploy.
+        const sources = buildInertProjectionStepSources({
+            projection: approved.projection,
+            config: params.config,
+            operatorApprovals: approved.approval.approvedGrants,
+        });
+        const commonDeploy = {
+            approved,
+            sidecarRouter,
+            agentAddress: params.agentAddress,
+            config: params.config,
+            sources,
+            db,
+            tenantId: params.tenantId,
+            anchorRunId: params.anchorRunId,
+            deploymentDomain: params.deploymentDomain,
+        };
+        // Branch on the source discriminant so the deploy args match the
+        // asset/registry arms of `DeployCodeSourcedWorkflowArgs`: an asset arm
+        // carries the attachment resolver (asserted non-null here to satisfy the
+        // union and fail loud on a mis-wired caller), a registry arm carries none.
+        let result;
+        if (source.kind === "asset") {
+            if (resolveAttachment === null) {
+                throw new Error("deployWorkflowFromSource: asset source deploy is missing its attachment resolver");
+            }
+            result = await deployCodeSourcedWorkflow({
+                ...commonDeploy,
+                source,
+                resolveAttachment,
+            });
+        }
+        else {
+            result = await deployCodeSourcedWorkflow({ ...commonDeploy, source });
+        }
+        // Seed the deploying principal's read grant on the deployment's workflow-run
+        // resource. `deployCodeSourcedWorkflow` wrote the anchor row but deliberately
+        // leaves this grant to the route, which carries the authenticated deployer
+        // principal.
+        const now = new Date();
+        await db.insert(grantTable).values({
+            id: generateId("grant"),
+            tenantId: params.tenantId,
+            principalId: params.config.principalId,
+            resource: `workflow-run:${params.anchorRunId}`,
+            action: "read",
+            effect: "allow",
+            origin: "creator",
+            createdAt: now,
+            updatedAt: now,
+        });
+        return {
+            anchorRunId: params.anchorRunId,
+            deploymentAddress: params.agentAddress,
+            publicKey: result.publicKey,
+        };
+    }
+    /**
+     * Update a prepared anchor run's `publicKey` under the allocation-ownership
+     * lock. The anchor row was inserted at prepare time; this stamps the
+     * supervisor key returned by the deploy ack, but only while the allocation
+     * still names this exact accepted generation for this anchor. A lost lock (the
+     * allocation moved on, another worker took the generation) fails closed as a
+     * leaked-agent `SessionLaunchError` -- the deploy already reached the sidecar,
+     * so the caller must treat the sidecar agent as possibly live. Used by the
+     * `deployPreparedCodeSourcedWorkflow` prepared path.
+     */
+    async function updateAnchorPublicKeyUnderAllocationLock(args) {
+        if (db === undefined) {
+            throw new Error("updateAnchorPublicKeyUnderAllocationLock requires a db handle");
+        }
+        const dbHandle = db;
+        try {
+            const updated = await dbHandle.transaction(async (tx) => {
+                const [allocation] = await tx
+                    .select({
+                    id: sidecarAllocationTable.id,
+                    anchorRunId: sidecarAllocationTable.anchorRunId,
+                    status: sidecarAllocationTable.status,
+                    generation: sidecarAllocationTable.generation,
+                    ensureAcceptedGeneration: sidecarAllocationTable.ensureAcceptedGeneration,
+                })
+                    .from(sidecarAllocationTable)
+                    .where(eq(sidecarAllocationTable.id, args.allocationTarget.allocationId))
+                    .limit(1)
+                    .for("update");
+                if (allocation === undefined ||
+                    allocation.anchorRunId !== args.anchorRunId ||
+                    allocation.status !== "allocated" ||
+                    allocation.generation !== args.allocationTarget.generation ||
+                    allocation.ensureAcceptedGeneration !==
+                        args.allocationTarget.generation) {
+                    return null;
+                }
+                const [anchor] = await tx
+                    .update(workflowRunTable)
+                    .set({ publicKey: args.publicKey })
+                    .where(and(eq(workflowRunTable.id, args.anchorRunId), eq(workflowRunTable.anchorRunId, args.anchorRunId), eq(workflowRunTable.tenantId, args.tenantId)))
+                    .returning({ id: workflowRunTable.id });
+                return anchor ?? null;
+            });
+            if (updated === null) {
+                throw new Error(`Prepared anchor run ${args.anchorRunId} lost allocation ownership before initialization completed`);
+            }
+        }
+        catch (error) {
+            throw new SessionLaunchError("start", error, true);
+        }
+    }
+    /**
+     * Deploy a previously-frozen code-sourced approval bundle to a dedicated
+     * allocation. The anchor `workflow_run` row already exists from prepare time
+     * (with its `definitionId` set), so this UPDATES it under the
+     * allocation-ownership lock
+     * rather than inserting. No re-probe: the frozen projection/hash/closure ride
+     * verbatim from `params.approved`, and the per-step inference sources are
+     * re-pinned from the re-resolved chain (deliberately NOT frozen, since a
+     * resolved source carries a credential secret).
+     */
+    async function deployPreparedCodeSourcedWorkflow(params) {
+        if (db === undefined) {
+            throw new Error("deployPreparedCodeSourcedWorkflow requires a db handle to update the prepared anchor run");
+        }
+        const dbHandle = db;
+        const approval = params.approved.approval;
+        if (!approval.ok) {
+            throw new Error("deployPreparedCodeSourcedWorkflow: refusing to deploy an unapproved workflow bundle");
+        }
+        const allocationRouter = requireAllocationRouter();
+        const source = params.source;
+        const resolveAttachment = bindSourceAttachmentResolver(source);
+        // Re-pin every top-level step's inference source from the re-resolved chain
+        // under the frozen approval -- the same pin the shared deploy computes.
+        const sources = buildInertProjectionStepSources({
+            projection: params.approved.projection,
+            config: params.config,
+            operatorApprovals: approval.approvedGrants,
+        });
+        // Restore the Hub-authoritative run ref onto the exact allocation generation
+        // before its address is routed.
+        await restoreWorkflowRunToAllocation({
+            agentRepoStore,
+            allocationRouter,
+            allocationTarget: params.allocationTarget,
+            agentAddress: params.agentAddress,
+        });
+        const commonEmit = {
+            approved: params.approved,
+            sidecarRouter,
+            sidecarAllocationRouter: allocationRouter,
+            allocationTarget: params.allocationTarget,
+            agentAddress: params.agentAddress,
+            config: params.config,
+            sources,
+            db: dbHandle,
+            tenantId: params.tenantId,
+            anchorRunId: params.anchorRunId,
+            deploymentDomain: params.deploymentDomain,
+            ...(params.credentialCipher !== undefined
+                ? { credentialCipher: params.credentialCipher }
+                : {}),
+        };
+        // Branch on the source discriminant so the emit args match the asset/registry
+        // arms: an asset arm carries the rebuilt attachment resolver (asserted
+        // non-null to satisfy the union), a registry arm carries none.
+        let result;
+        if (source.kind === "asset") {
+            if (resolveAttachment === null) {
+                throw new Error("deployPreparedCodeSourcedWorkflow: asset source deploy is missing its attachment resolver");
+            }
+            result = await emitSourceRefDeployFrame({
+                ...commonEmit,
+                source,
+                resolveAttachment,
+            });
+        }
+        else {
+            result = await emitSourceRefDeployFrame({ ...commonEmit, source });
+        }
+        await updateAnchorPublicKeyUnderAllocationLock({
+            tenantId: params.tenantId,
+            anchorRunId: params.anchorRunId,
+            allocationTarget: params.allocationTarget,
+            publicKey: result.publicKey,
+        });
+        return {
+            anchorRunId: params.anchorRunId,
+            deploymentAddress: params.agentAddress,
+            publicKey: result.publicKey,
+        };
+    }
+    async function rollbackCommittedAttachments(committed) {
+        if (db === undefined)
+            return;
+        if (committed.length === 0)
+            return;
+        // Per-row try/catch so a single rollback failure does not stop the
+        // sweep — every committed row needs to come off the books before
+        // the caller emits the original sendPack error.
+        for (const record of committed) {
+            try {
+                await db
+                    .delete(sessionAssetTable)
+                    .where(and(eq(sessionAssetTable.runId, record.runId), eq(sessionAssetTable.mountPath, record.mountPath), eq(sessionAssetTable.assetPackSha, record.assetPackSha), eq(sessionAssetTable.sourceCommitSha, record.sourceCommitSha)));
+            }
+            catch (err) {
+                logger.warn `session_asset rollback failed for earlier-committed instance=${record.runId} mountPath=${record.mountPath}: ${err instanceof Error ? err.message : String(err)}`;
+            }
+        }
+    }
+    async function sendAttachmentPack(runId, agentAddress, attachment, allocationTarget) {
+        if (db === undefined) {
+            // Guarded at construction; reassert defensively so the
+            // narrowing is visible to readers and a future refactor cannot
+            // accidentally invoke this without a db.
+            throw new Error("sendAttachmentPack invoked without a db handle");
+        }
+        const { mountPath, sourceCommitSha, repoId, pack, ref } = attachment;
+        const assetPackSha = await createPackSha(pack);
+        const record = {
+            runId,
+            mountPath,
+            assetPackSha,
+            sourceCommitSha,
+        };
+        // Reserve the manifest row before the pack send so we never end up in the
+        // materialized-without-manifest state. Only an allocated launch may reuse
+        // an identical row: replacement workers keep the stable instance id and
+        // mount path, while the shared path retains its duplicate-launch guard.
+        const rollbackRecord = allocationTarget === undefined ? record : null;
+        if (allocationTarget === undefined) {
+            await db
+                .insert(sessionAssetTable)
+                .values({ ...record, materializedAt: new Date() });
+        }
+        else {
+            const inserted = await db
+                .insert(sessionAssetTable)
+                .values({ ...record, materializedAt: new Date() })
+                .onConflictDoNothing({
+                target: [sessionAssetTable.runId, sessionAssetTable.mountPath],
+            })
+                .returning({ runId: sessionAssetTable.runId });
+            if (inserted.length === 0) {
+                const existing = await db.query.sessionAsset.findFirst({
+                    where: and(eq(sessionAssetTable.runId, runId), eq(sessionAssetTable.mountPath, mountPath)),
+                    columns: {
+                        assetPackSha: true,
+                        sourceCommitSha: true,
+                    },
+                });
+                if (existing === undefined) {
+                    throw new Error(`session_asset ${runId}/${mountPath} disappeared after its insert conflicted`);
+                }
+                if (existing.assetPackSha !== assetPackSha ||
+                    existing.sourceCommitSha !== sourceCommitSha) {
+                    throw new Error(`session_asset ${runId}/${mountPath} conflicts with the allocated workflow's restored asset`);
+                }
+            }
+        }
+        try {
+            const options = { mountPath, repoId };
+            if (allocationTarget === undefined) {
+                await sidecarRouter.sendPack(agentAddress, pack, ref, sourceCommitSha, options);
+            }
+            else {
+                await requireAllocationRouter().sendPackToAllocation(allocationTarget, agentAddress, pack, ref, sourceCommitSha, options);
+            }
+        }
+        catch (err) {
+            // Shared launches own the row they just created and roll it back when
+            // the send fails. Allocated rows are durable recovery intent: even a row
+            // first inserted by this attempt can already be reused by another
+            // reconciler, so no replacement attempt may delete it.
+            // The forensic value of a manifest-without-materialization row is
+            // negligible because no agent will read against it. Wrap the
+            // rollback in its own try/catch so a rollback failure (DB gone,
+            // connection killed mid-launch) is logged rather than masking the
+            // primary sendPack error — the caller needs to see the original
+            // failure, not the secondary one.
+            if (rollbackRecord !== null) {
+                try {
+                    await db
+                        .delete(sessionAssetTable)
+                        .where(and(eq(sessionAssetTable.runId, rollbackRecord.runId), eq(sessionAssetTable.mountPath, rollbackRecord.mountPath), eq(sessionAssetTable.assetPackSha, rollbackRecord.assetPackSha), eq(sessionAssetTable.sourceCommitSha, rollbackRecord.sourceCommitSha)));
+                }
+                catch (rollbackErr) {
+                    const msg = rollbackErr instanceof Error
+                        ? rollbackErr.message
+                        : String(rollbackErr);
+                    logger.warn `session_asset rollback failed for instance=${runId} mountPath=${mountPath}: ${msg}`;
+                }
+            }
+            throw err;
+        }
+        return rollbackRecord;
+    }
+    /**
+     * Build a per-agent `ClosureResolver` from the tenant's visible
+     * package-registry assets plus the statically-configured HTTP
+     * registries, then run the closure resolution against `pins`.
+     *
+     * Returns the resolved manifest and an asset-id-keyed index of the
+     * package-registry assets the resolver knew about, so the caller can
+     * derive mount paths from the asset name without a second DB hit.
+     */
+    async function buildAndResolve(args) {
+        if (db === undefined) {
+            // Guarded at construction; restate for the narrowing.
+            throw new Error("buildAndResolve invoked without a db handle");
+        }
+        const visibleAssets = await listAssetsForTenant(db, args.tenantId, "package-registry");
+        const registryMap = new Map();
+        // `assetIndex` carries only the assets the resolver might have
+        // read from — i.e. one row per registry name, the one that won
+        // its `(kind, name)` slot. Shadowed assets that lost the
+        // collision are deliberately excluded: the resolver can never
+        // reach them, so the fan-out path must never see them in the
+        // index either. The walker walks leaf-to-root inside
+        // `listAssetsForTenant`, so the first occurrence of any
+        // `(kind, name)` wins — we replay the same shadowing here.
+        // Shadowed assets — those that lose the `(kind, name)` collision
+        // contest at a lower tenancy level — are dropped entirely from
+        // the per-launch registry map. They never appear in `assetIndex`
+        // either, so the fan-out that translates `kind: "asset"` manifest
+        // entries back to asset rows cannot reach them. This matches the
+        // resolver's view: a closure built from this map sees exactly
+        // the assets the resolver would have read from, and shadowed
+        // tarballs are invisible to both layers.
+        const assetIndex = new Map();
+        for (const row of visibleAssets) {
+            if (registryMap.has(row.name))
+                continue;
+            const asset = {
+                id: row.id,
+                tenantId: row.tenantId,
+                kind: "package-registry",
+                name: row.name,
+                displayName: row.displayName,
+                creatorPrincipalId: row.creatorPrincipalId,
+                createdAt: row.createdAt,
+                updatedAt: row.updatedAt,
+            };
+            assetIndex.set(asset.id, asset);
+            registryMap.set(asset.name, new AssetRegistrySource({
+                name: asset.name,
+                assetId: asset.id,
+                readBlob: (path) => args.assetService.readAssetBlob({
+                    assetId: asset.id,
+                    path,
+                }),
+                listBlobs: (dir) => args.assetService.listAssetBlobs({
+                    assetId: asset.id,
+                    dir,
+                }),
+            }));
+        }
+        for (const [name, cfg] of args.registries.httpRegistries) {
+            // Asset wins on collision with an HTTP registry of the same
+            // name; symmetric with the inner-shadows-outer rule that
+            // governs the tenant walker.
+            if (registryMap.has(name))
+                continue;
+            registryMap.set(name, new HttpRegistrySource({ name, config: cfg }));
+        }
+        if (!registryMap.has(args.registries.defaultRegistry)) {
+            throw new Error(`agent ${args.agentId}: defaultRegistry "${args.registries.defaultRegistry}" is neither a tenant-visible package-registry asset nor a configured HTTP registry`);
+        }
+        const resolver = createClosureResolver({
+            registries: registryMap,
+            defaultRegistry: args.registries.defaultRegistry,
+            ...(args.registries.scopeRouting !== undefined
+                ? { scopeRouting: args.registries.scopeRouting }
+                : {}),
+        });
+        const manifest = await resolver.resolveClosure(args.pins);
+        return { manifest, assetIndex };
+    }
+    /**
+     * Build a `ResolvedAttachment` for an asset the tool-package resolver
+     * picked from. The pack is read from the asset's main ref (the same
+     * ref the resolver consumed tarballs from).
+     */
+    async function resolveAssetAttachment(args) {
+        const repoId = { kind: args.asset.kind, id: args.asset.id };
+        const sourceCommitSha = await agentRepoStore.repoStore.resolveRef(HUB_PRINCIPAL, repoId, DEFAULT_ASSET_REF);
+        if (sourceCommitSha === null) {
+            throw new Error(`tool-package asset ${args.asset.kind}/${args.asset.id} has no commit on ${DEFAULT_ASSET_REF}`);
+        }
+        const { pack, ref: returnedRef } = await agentRepoStore.repoStore.createPack(HUB_PRINCIPAL, repoId, DEFAULT_ASSET_REF);
+        return {
+            mountPath: args.mountPath,
+            sourceCommitSha,
+            repoId,
+            pack,
+            ref: returnedRef,
+        };
+    }
+    async function attemptCleanup(agentAddress, failedPhase, originalErr) {
+        try {
+            await sidecarRouter.sendAgentUndeploy(agentAddress, failedPhase);
+        }
+        catch (cleanupErr) {
+            logger.error `Failed to clean up agent ${agentAddress} after ${failedPhase} failure: ${String(cleanupErr)}`;
+            // Preserve the original error as cause so the root cause is not
+            // lost when the cleanup also fails.
+            throw new SessionLaunchError(failedPhase, originalErr, true);
+        }
+    }
+    async function sendUserMessage(params) {
+        const { agentAddress, from, messageId, date, content, attachments, inReplyTo, references, sessionId, tenantId, cryptoProvider, } = params;
+        const headers = {
+            from,
+            to: [agentAddress],
+            cc: undefined,
+            date,
+            messageId,
+            subject: undefined,
+            inReplyTo,
+            references,
+            mimeVersion: "1.0",
+            interchangeType: "conversation.message",
+            interchangeCorrelationId: undefined,
+            interchangeTenantId: tenantId,
+            interchangeAgentId: undefined,
+            interchangeSessionId: sessionId,
+            interchangeOfferingId: undefined,
+            interchangeSchemaVersion: undefined,
+            traceparent: undefined,
+            tracestate: undefined,
+        };
+        const signedContent = assembleSignedContent({
+            kind: "conversation",
+            text: content,
+            ...(attachments !== undefined ? { attachments } : {}),
+        });
+        const signature = await createDetachedSignatureFromProvider(signedContent, cryptoProvider);
+        const rawMessage = assembleMessage(headers, signedContent, signature);
+        const base64 = base64Encode(rawMessage);
+        const delivered = sidecarRouter.routeMail(agentAddress, base64, messageId);
+        if (!delivered) {
+            throw new Error(`Failed to deliver message to ${agentAddress}: agent is unreachable`);
+        }
+        return rawMessage;
+    }
+    async function endSession(agentAddress, reason) {
+        await sidecarRouter.sendAgentUndeploy(agentAddress, reason);
+    }
+    return {
+        stageWorkflowStep,
+        deployWorkflowFromSource,
+        installAndApproveWorkflowSource,
+        deployPreparedCodeSourcedWorkflow,
+        sendUserMessage,
+        endSession,
+    };
+}