@intx/hub-sessions 0.2.2 → 0.3.0

package/dist/session-service.js

@@ -1,20 +1,21 @@
 import { type } from "arktype";
 import { and, eq } from "drizzle-orm";
-import { createDefaultDirectorRegistry, } from "@intx/agent";
 import { getLogger } from "@intx/log";
 import { assembleMessage, assembleSignedContent, createDetachedSignatureFromProvider, } from "@intx/mime";
-import { listAssetsForTenant } from "@intx/db";
-import { grant as grantTable, workflowDeployment as workflowDeploymentTable, } from "@intx/db/schema";
+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 { sessionAsset as sessionAssetTable } from "@intx/db/schema";
 import { AssetRegistrySource, HttpRegistrySource, ManifestInvalidError, createClosureResolver, } from "@intx/tool-packaging";
 import { ToolPackageManifest, } from "@intx/types/tool-packages";
-import { defineWorkflow, } from "@intx/workflow/definition";
-import { createWorkflowDeployOrchestrator, deriveDeploymentAddress, walkCapabilities, wrapHarnessAsSingleStepWorkflow, } from "@intx/workflow-deploy";
+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 { buildAvailableSkillsStanza, } from "./available-skills-stanza.js";
-import { getSkillIndex } from "./skill-kind.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". */
@@ -29,9 +30,9 @@ export class SessionLaunchError extends Error {
         this.leakedAgent = leakedAgent;
     }
 }
-// Hub-side principal for reading skill repos. Skills are signed by the
-// hub itself, and listAgentAssets is being called on the hub to assemble
-// packs for delivery to a sidecar — so the hub principal is correct.
+// 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", 
@@ -59,75 +60,6 @@ function collectDistinctAssetIds(manifest) {
     }
     return out;
 }
-/**
- * Dedup the union of `direct` and `resolved` attachments by asset id
- * (taken from `repoId.id`), with `direct` taking precedence whenever
- * both name the same asset.
- *
- * The package-registry "both name the same asset" case is refused
- * upstream at the resolver block (a direct attachment plus a resolver
- * pin for the same package-registry asset would emit assetMounts at
- * the resolver's ref while the direct attachment materializes at the
- * operator's chosen ref, leaving the loader to resolve manifest
- * entries against tarballs that do not exist at the materialized
- * mount). Skill attachments cannot collide via the resolver path —
- * the resolver only emits package-registry entries — so the dedup
- * still has to handle skill self-collisions defensively and to fall
- * through cleanly when both sources happen to name an asset the
- * upstream check has not flagged.
- *
- * The function takes the two sources as named parameters rather than a
- * pre-merged list so the precedence rule is structural: a future
- * refactor cannot accidentally swap the order by re-arranging an
- * intermediate spread.
- */
-function dedupAttachmentsByAssetId(args) {
-    const seen = new Set();
-    const out = [];
-    for (const att of args.direct) {
-        if (seen.has(att.repoId.id))
-            continue;
-        seen.add(att.repoId.id);
-        out.push(att);
-    }
-    for (const att of args.resolved) {
-        if (seen.has(att.repoId.id))
-            continue;
-        seen.add(att.repoId.id);
-        out.push(att);
-    }
-    return out;
-}
-/**
- * Compute the materialization path for an attachment from the asset's
- * kind and name. v1 does not let users override the path — the path is
- * a function of the asset, full stop. Today only `skill` has a defined
- * mapping (`skills/<asset.name>/`); other kinds reach this code path
- * via the `never` branch and throw, per the defensive-coding rule that
- * we never silently invent a default for an unhandled kind.
- *
- * Asset names are validated lowercase-kebab at `createAsset`, which is
- * the only entry path into this function, so the resulting path is
- * safe under `applyAssetPack`'s per-segment validator.
- */
-function resolveMountPath(row) {
-    switch (row.asset.kind) {
-        case "skill":
-            return `skills/${row.asset.name}/`;
-        case "package-registry":
-            return `package-registries/${row.asset.name}/`;
-        case "agent-state":
-            throw new Error(`mount_path_required: agent_asset row ${row.id} references agent-state asset ${row.asset.id}; agent-state attachments are not supported`);
-        case "workflow":
-            throw new Error("kind handler not yet registered: workflow");
-        case "workflow-run":
-            throw new Error("kind handler not yet registered: workflow-run");
-        default: {
-            const exhaustive = row.asset.kind;
-            throw new Error(`mount_path_required: no default mountPath for asset kind ${String(exhaustive)} on row ${row.id}`);
-        }
-    }
-}
 /**
  * Translate the orchestrator's structural `DeployContent` (which types
  * `toolPackageManifest` as `unknown`) back into the hub-sessions
@@ -155,118 +87,288 @@ export function bridgeOrchestratorDeployContent(content) {
     return bridged;
 }
 /**
- * Wire the workflow-deploy orchestrator's `sendMultiStepDeploy`
- * dependency against `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. The supervisor public key returned by the
- * sidecar's `agent.deploy.ack` is threaded back as the
- * `MultiStepDeployResult.publicKey`.
+ * 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`.
  *
- * Exported so the co-located caller-site test can assert that the
- * closure constructed in `launchSession` reaches the wire surface via
- * `sendAgentDeploy` with a `workflow` field structurally matching the
- * `AgentDeployFrame.workflow` schema.
+ * 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) {
-    // The wire validator's projection types `stepOrder` and `triggers`
-    // as mutable arrays while `WorkflowDefinition` declares them as
-    // `readonly`. The wire serializer never mutates the arrays; the
-    // shallow copies pay the readonly-widen at the boundary. Every
-    // field listed here must match the structural envelope the
-    // workflow-process child re-validates against on materialization
-    // (`workflowDefinitionEnvelopeSchema`): `id`, `triggers`, `steps`,
-    // `stepOrder`, optional `state`. The sidecar deploy router
-    // serializes this object verbatim into `workflow.json`; a missing
-    // envelope-required field here would round-trip into the child's
-    // envelope rejection on disk.
-    const wireDefinition = {
-        id: args.definition.id,
-        triggers: [...args.definition.triggers],
-        stepOrder: [...args.definition.stepOrder],
-        steps: args.definition.steps,
-        ...(args.definition.state !== undefined
-            ? { state: args.definition.state }
+    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] }
             : {}),
     };
-    return args.sidecarRouter.sendAgentDeploy(args.agentAddress, args.config, {
-        definition: wireDefinition,
+    // 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 };
 }
 /**
- * `WorkflowRepoWriter` backed by the hub's repo substrate. Writes the
- * orchestrator-produced workflow tree (`workflow.json`,
- * `capability-declarations.json`, `.gitignore`) into a `workflow`-kind
- * repo keyed by the workflow definition id, committing on the published
- * asset ref. The hub principal is the only writer of the workflow repo,
- * matching `workflowAuthorize`'s hub-writes / sidecar-reads split.
+ * 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.
  */
-function createHubWorkflowRepoWriter(agentRepoStore) {
-    return {
-        async writeWorkflowRepo(args) {
-            const repoId = { kind: "workflow", id: args.workflowRepoId };
-            const files = {};
-            for (const [path, contents] of args.files) {
-                files[path] = contents;
-            }
-            await agentRepoStore.repoStore.writeTree(HUB_PRINCIPAL, repoId, DEFAULT_ASSET_REF, { files, message: "Write workflow deploy tree" });
-        },
-    };
+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, agentRepoStore, assetService, db, toolPackageRegistries, } = 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 a deploy on the sidecar: resolve assets and tool packages, write
-     * the deploy tree, provision the agent, and deliver the deploy + asset
-     * packs (Phases 0-2b). Phase 1's provision has two shapes:
-     *   - `workflowFrame` set: the single-step head hand-off fires the
-     *     deployment `agent.deploy` frame that spawns the workflow-process
-     *     child. Returns the supervisor public key.
-     *   - `stageOnly` set: a multi-step per-step stage 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
-     *     child.
-     * A call with neither is rejected -- the legacy warm-harness path
-     * is gone.
+     * 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, instanceId, config, deployContent } = params;
+        const { agentAddress, agentId, runId, config, deployContent } = params;
         const toolPackagePins = params.toolPackagePins ?? [];
         const stageOnly = params.stageOnly ?? false;
-        if (params.workflowFrame !== undefined && stageOnly) {
-            throw new Error("executeLaunchPhases: workflowFrame and stageOnly are mutually exclusive");
-        }
-        const workflowFrame = params.workflowFrame;
-        // Phase 0: Resolve attached assets first so the skill index is in
-        // hand before the deploy tree is written. The `<available_skills>`
-        // stanza describing every attached skill must land in
-        // `deploy/prompt.md`, so it has to be composed before
-        // `writeDeployTree` produces the on-disk tree.
-        let attachments = [];
-        let availableSkills = [];
-        if (assetService !== undefined) {
-            try {
-                attachments = await resolveAttachments(assetService, agentId);
-                availableSkills = collectAvailableSkills(attachments);
-            }
-            catch (err) {
-                throw new SessionLaunchError("write", err, false);
-            }
-        }
-        const stanza = buildAvailableSkillsStanza(availableSkills);
-        let effectiveDeployContent = stanza.length === 0
-            ? deployContent
-            : {
-                ...deployContent,
-                systemPrompt: `${deployContent.systemPrompt}\n\n${stanza}\n`,
-            };
+        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
@@ -308,25 +410,6 @@ export function createSessionService(deps) {
             }
             const assetMounts = new Map();
             try {
-                // Refuse to mix a direct package-registry attachment with a
-                // resolver-driven pin against the same asset id. The resolver
-                // path emits an `assetMounts` entry pointing at the asset's
-                // DEFAULT_ASSET_REF tip, but a direct attachment may carry any
-                // ref the operator chose at attach time. The downstream dedup
-                // in `dedupAttachmentsByAssetId` lets the direct attachment win
-                // — its bytes would materialize at the operator's chosen ref
-                // while `assetMounts` still names the resolver's ref, leaving
-                // the loader to resolve manifest entries against tarballs that
-                // do not exist at the materialized mount. Surface the conflict
-                // at launch as a manifest-shaped violation rather than letting
-                // the integrity mismatch surface deep inside the sidecar apply.
-                const directPackageRegistryAttachments = attachments.filter((att) => att.assetKind === "package-registry");
-                for (const assetId of collectDistinctAssetIds(manifest)) {
-                    const conflict = directPackageRegistryAttachments.find((att) => att.repoId.id === assetId);
-                    if (conflict !== undefined) {
-                        throw new ManifestInvalidError(`package-registry asset ${conflict.assetKind}/${conflict.assetName} (${assetId}) is both directly attached to the agent and selected by the tool-package resolver; attach OR pin via tenancy, not both`);
-                    }
-                }
                 for (const assetId of collectDistinctAssetIds(manifest)) {
                     const asset = assetIndex.get(assetId);
                     if (asset === undefined) {
@@ -339,7 +422,7 @@ export function createSessionService(deps) {
                     }
                     const mountPath = `package-registries/${asset.name}/`;
                     assetMounts.set(assetId, mountPath);
-                    manifestAssetAttachments.push(await resolveDirectAssetAttachment({
+                    manifestAssetAttachments.push(await resolveAssetAttachment({
                         asset,
                         mountPath,
                     }));
@@ -372,192 +455,111 @@ export function createSessionService(deps) {
         // route is held only for the pack window and dropped in the `finally`.
         if (stageOnly) {
             try {
-                sidecarRouter.bindStepRoute(agentAddress);
+                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 single-step workflow deploy sends
-            // the deployment `agent.deploy` frame carrying the workflow definition
-            // + source pins: the sidecar's deploy router initializes the head repo
-            // on receipt (so the Phase 2 pack has a repo to apply into) and spawns
-            // the workflow-process child. A stage-only per-step deploy sends a
+            // 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. A workflow frame's ack surfaces the
-            // supervisor public key to the caller.
-            let deployAckPublicKey;
+            // exist before the pack applies.
             try {
-                if (workflowFrame !== undefined) {
-                    const ack = await sendMultiStepDeployFrame({
-                        sidecarRouter,
-                        agentAddress,
-                        config,
-                        definition: workflowFrame.definition,
-                        sources: workflowFrame.sources,
-                    });
-                    deployAckPublicKey = ack.publicKey;
-                }
-                else if (stageOnly) {
-                    await sidecarRouter.sendProvisionStep(agentAddress, config);
+                if (stageOnly) {
+                    if (params.allocationTarget === undefined) {
+                        await sidecarRouter.sendProvisionStep(agentAddress, config);
+                    }
+                    else {
+                        await requireAllocationRouter().sendProvisionStepToAllocation(params.allocationTarget, agentAddress, config);
+                    }
                 }
                 else {
-                    // Every caller supplies `workflowFrame` (single-step head) or
-                    // `stageOnly` (multi-step per-step). A deploy with neither has no
-                    // provisioning shape -- the legacy warm-harness path is gone -- so
-                    // fail loud rather than ship a deploy pack the sidecar never
-                    // provisioned a repo for.
-                    throw new Error("executeLaunchPhases: a deploy requires either workflowFrame or stageOnly");
+                    // 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. On failure, the warm/workflow paths tear the
-            // sidecar deployment down; a stage-only step has no supervisor to
-            // undeploy, so it only drops its transient route (in the `finally`).
-            // The step's inited agent-state repo is left on the sidecar: the
-            // orchestrator aborts the whole deploy 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.
+            // 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 {
-                await sidecarRouter.sendPack(agentAddress, pack, ref, commitSha);
+                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)
+                if (!stageOnly && params.allocationTarget === undefined) {
                     await attemptCleanup(agentAddress, "pack", err);
-                throw new SessionLaunchError("pack", err, false);
+                }
+                throw new SessionLaunchError("pack", err, !stageOnly && params.allocationTarget !== undefined);
             }
             // Phase 2b: Asset-pack fan-out. For each attached asset, build a
-            // pack, insert the manifest row, then send the pack. The manifest
-            // insert MUST happen before the pack send: if the sidecar acks
+            // 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. If the row insert fails, the pack send
-            // must not happen.
-            //
-            // The fan-out covers two sources: the agent's direct attachments
-            // (skills, today) and the package-registry assets the tool-package
-            // resolver picked from. The latter live behind tenant inheritance
-            // rather than a per-agent attachment row, so the session service
-            // synthesizes the attachment view in `manifestAssetAttachments`.
+            // 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.
             //
-            // Both sources can name the same `package-registry` asset — a
-            // direct attachment and a resolver pin would each compute
-            // `mountPath = "package-registries/<asset.name>/"` and collide on
-            // the `(instanceId, mountPath)` PK in `session_asset`. Dedup by
-            // asset id BEFORE the inserts and let the direct attachment win:
-            // it is an explicit operator action and carries an `agentAssetId`
-            // the audit query joins against. The resolver-derived row would
-            // produce the same materialized contents, so dropping it is
-            // semantically lossless.
-            const fanOut = dedupAttachmentsByAssetId({
-                direct: attachments,
-                resolved: manifestAssetAttachments,
-            });
+            // 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 every successfully committed attachment so a later
-                // fan-out failure can roll back the earlier rows in lockstep
-                // with the sidecar undeploy. Without this, fan-out[0] succeeds,
-                // fan-out[1] fails, attemptCleanup tears down the sidecar — but
-                // fan-out[0]'s session_asset row survives and a future
-                // materialization query reads a manifest the sidecar no longer
-                // honors.
+                // 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 {
-                        await sendAttachmentPack(instanceId, agentAddress, att);
-                        committed.push(att);
+                        const committedRecord = await sendAttachmentPack(runId, agentAddress, att, params.allocationTarget);
+                        if (committedRecord !== null)
+                            committed.push(committedRecord);
                     }
                     catch (err) {
-                        await rollbackCommittedAttachments(instanceId, committed);
-                        if (!stageOnly)
+                        await rollbackCommittedAttachments(committed);
+                        if (!stageOnly && params.allocationTarget === undefined) {
                             await attemptCleanup(agentAddress, "pack", err);
-                        throw new SessionLaunchError("pack", err, false);
+                        }
+                        throw new SessionLaunchError("pack", err, !stageOnly && params.allocationTarget !== undefined);
                     }
                 }
             }
-            return deployAckPublicKey === undefined
-                ? undefined
-                : { publicKey: deployAckPublicKey };
         }
         finally {
             if (stageOnly) {
-                sidecarRouter.unbindStepRoute(agentAddress);
+                if (params.allocationTarget === undefined) {
+                    sidecarRouter.unbindStepRoute(agentAddress);
+                }
+                else {
+                    requireAllocationRouter().unbindAllocatedStepRoute(params.allocationTarget, agentAddress);
+                }
             }
         }
     }
-    /**
-     * Deploy a one-step workflow once at the head. Reuses the full
-     * launch-phase machinery (deploy-tree write, pack, asset fan-out) via
-     * `executeLaunchPhases`, swapping the Phase 1 provision frame for the
-     * workflow frame. The workflow frame makes the sidecar initialize the
-     * head repo and spawn the workflow-process child; the follow-up pack
-     * lands the head's deploy tree. Returns the supervisor's principal
-     * public key from the frame's ack. A workflow-frame launch always
-     * yields a deploy-ack key; its absence is a wiring bug, not a
-     * tolerable case.
-     */
-    const deploySingleStepAtHead = async (deployParams) => {
-        const result = await executeLaunchPhases({
-            agentAddress: deployParams.agentAddress,
-            agentId: deployParams.agentId,
-            instanceId: deployParams.instanceId,
-            config: deployParams.config,
-            deployContent: bridgeOrchestratorDeployContent(deployParams.deployContent),
-            workflowFrame: {
-                definition: deployParams.definition,
-                sources: deployParams.sources,
-            },
-            ...(deployParams.toolPackagePins !== undefined
-                ? { toolPackagePins: deployParams.toolPackagePins }
-                : {}),
-        });
-        if (result === undefined) {
-            throw new Error("single-step deploy at head: executeLaunchPhases returned no deploy-ack public key for a workflow-frame deploy");
-        }
-        return result;
-    };
-    /**
-     * Build the workflow-deploy orchestrator (with its launch-session and
-     * multi-step callbacks) and run one deploy. Shared by `launchSession`
-     * and `deployWorkflowDefinition`, which differ only in the workflow
-     * repo writer, the director registry, and the deploy args.
-     */
-    async function runWorkflowDeploy(args) {
-        // The per-step launcher: stage each step's deploy tree WITHOUT a warm
-        // harness (the supervised child runs the step), with the orchestrator's
-        // structural `DeployContent` narrowed back to the hub-sessions shape
-        // first.
-        const launchSessionCallback = (orchestratorParams) => stageWorkflowStep({
-            agentAddress: orchestratorParams.agentAddress,
-            agentId: orchestratorParams.agentId,
-            instanceId: orchestratorParams.instanceId,
-            config: orchestratorParams.config,
-            deployContent: bridgeOrchestratorDeployContent(orchestratorParams.deployContent),
-            ...(orchestratorParams.toolPackagePins !== undefined
-                ? { toolPackagePins: orchestratorParams.toolPackagePins }
-                : {}),
-        });
-        const sendMultiStepDeployCallback = (deployParams) => sendMultiStepDeployFrame({
-            sidecarRouter,
-            agentAddress: deployParams.agentAddress,
-            config: deployParams.config,
-            definition: deployParams.definition,
-            sources: deployParams.sources,
-        });
-        const orchestrator = createWorkflowDeployOrchestrator({
-            directorRegistry: args.directorRegistry,
-            workflowRepo: args.workflowRepo,
-            launchSession: launchSessionCallback,
-            sendMultiStepDeploy: sendMultiStepDeployCallback,
-            deploySingleStepAtHead,
-        });
-        return orchestrator.deployWorkflow(args.deployArgs);
-    }
     /**
      * 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
@@ -572,149 +574,356 @@ export function createSessionService(deps) {
         await executeLaunchPhases({
             agentAddress: params.agentAddress,
             agentId: params.agentId,
-            instanceId: params.instanceId,
+            runId: params.runId,
             config: params.config,
             deployContent: params.deployContent,
             stageOnly: true,
             ...(params.toolPackagePins !== undefined
                 ? { toolPackagePins: params.toolPackagePins }
                 : {}),
+            ...(params.allocationTarget !== undefined
+                ? { allocationTarget: params.allocationTarget }
+                : {}),
         });
     }
-    /**
-     * Deploy a single-agent instance through the single-step-at-head path: wrap
-     * the harness as a one-step workflow (the same wrap `launchSession` uses) and
-     * route it through `deploySingleStepAtHead` with the instance's REAL identity
-     * -- so the head address IS the instance address and the deploy runs as a
-     * supervised workflow-process child.
-     *
-     * Unlike the orchestrator's `runSingleStepAtHead`, this calls
-     * `deploySingleStepAtHead` directly with the route's real `agentId`
-     * (`row.id`), NOT a `deriveDeploymentAgentId(deploymentId)` -- the child
-     * resolves skills, deploy tree, and tool-package pins by `agentId`, so
-     * collapsing it to the deployment id would strip the instance's attachments.
-     * It writes no `workflow_deployment` row (a plain instance has no workflow
-     * asset). Returns the head's agent-key ack.
-     */
-    async function deployInstanceAtHead(params) {
-        const { agentAddress, agentId, instanceId, config, deployContent } = params;
-        const singleStepAgent = wrapHarnessAsSingleStepWorkflow({
-            config,
-            deployContent,
-        });
-        const workflow = defineWorkflow({
-            id: `wf_${agentId}`,
-            agent: singleStepAgent,
-            trigger: { type: "mail", to: agentAddress },
+    // 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,
         });
-        // The sole step's id, read off the built definition.
-        const stepId = workflow.stepOrder[0];
-        if (stepId === undefined) {
-            throw new Error(`instance deploy for ${agentAddress}: the wrapped single-step workflow has an empty stepOrder`);
-        }
-        // Pin the step's inference sources to the instance's FULL ordered source
-        // chain so the workflow-process child's reactor fails over across it at
-        // runtime. The route already resolved and authorized `config.sources`
-        // against the tenant catalog, so it is pinned directly rather than re-run
-        // through the orchestrator's operator-approval gate.
-        //
-        // Fail loud on the invariant the reactor depends on: the reactor resolves
-        // its initial source by id (`defaultSource`) and fails over FORWARD-ONLY
-        // with no wrap, so the default must be element 0 or part of the chain is
-        // unreachable -- and if the default were last, failover would silently
-        // no-op. The route guarantees `config.sources[0].id === config.defaultSource`
-        // (head = active); assert it here so a future reordering fails loudly
-        // rather than silently disabling failover.
-        if (config.sources.length === 0) {
-            throw new Error(`instance deploy for ${agentAddress}: config.sources is empty; at least the default source is required`);
-        }
-        if (config.sources[0]?.id !== config.defaultSource) {
-            throw new Error(`instance deploy for ${agentAddress}: config.sources[0] (${JSON.stringify(config.sources[0]?.id)}) must be the default source ${JSON.stringify(config.defaultSource)}; the reactor fails over forward from the default and would otherwise skip the head`);
-        }
-        return deploySingleStepAtHead({
-            agentAddress,
-            agentId,
-            instanceId,
-            config,
-            deployContent,
-            definition: workflow,
-            sources: { [stepId]: config.sources },
-            hubPublicKey: hexEncode(agentRepoStore.getSigningPublicKey()),
-            ...(params.toolPackagePins !== undefined
-                ? { toolPackagePins: params.toolPackagePins }
-                : {}),
+        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,
+        };
     }
-    async function deployWorkflowDefinition(params) {
-        const { tenantId, deploymentId, deploymentDomain, definition, definitionAssetId, config, deployContent, } = params;
-        // The deploy is initiated by an authorized tenant operator against a
-        // workflow asset they authored; approve exactly the grant surface the
-        // definition declares. The same director registry feeds both this
-        // approval-set derivation and the orchestrator's gate so the walk the
-        // route approves and the walk the orchestrator enforces are identical.
-        const directorRegistry = createDefaultDirectorRegistry();
-        const walk = walkCapabilities(definition, directorRegistry);
-        const operatorApprovals = new Set([...walk.perStep.values()].flatMap((declarations) => [
-            ...declarations.grants,
-        ]));
-        const result = await runWorkflowDeploy({
-            workflowRepo: createHubWorkflowRepoWriter(agentRepoStore),
-            directorRegistry,
-            deployArgs: {
-                workflow: definition,
-                deploymentId,
-                deploymentDomain,
-                config,
-                deployContent,
-                operatorApprovals,
-                hubPublicKey: hexEncode(agentRepoStore.getSigningPublicKey()),
-                ...(params.toolPackagePins !== undefined
-                    ? { toolPackagePins: params.toolPackagePins }
-                    : {}),
-            },
-        });
+    /**
+     * 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("deployWorkflowDefinition requires a db handle to record the workflow_deployment projection row");
+            throw new Error("updateAnchorPublicKeyUnderAllocationLock requires a db handle");
         }
-        const now = new Date();
-        await db.transaction(async (tx) => {
-            await tx.insert(workflowDeploymentTable).values({
-                id: deploymentId,
-                tenantId,
-                definitionAssetId,
-                address: deriveDeploymentAddress({ deploymentId, deploymentDomain }),
-                // publicKey is left null here; the sidecar's deploy-ack persists the
-                // deployment's minted key once the child has spawned.
-                status: "deployed",
-                createdAt: now,
+        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;
             });
-            // Seed a read grant on the deployment's workflow-run resource for the
-            // deploying principal so they can observe run events out of the box,
-            // mirroring the per-instance agent-state read grant the agent deploy
-            // path seeds for the creator. Without this a non-owner deployer would
-            // deploy a workflow they cannot read the runs of.
-            await tx.insert(grantTable).values({
-                id: generateId("grant"),
-                tenantId,
-                principalId: config.principalId,
-                resource: `workflow-run:${deploymentId}`,
-                action: "read",
-                effect: "allow",
-                origin: "creator",
-                createdAt: now,
-                updatedAt: now,
+            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 {
-            deploymentId,
-            deploymentAddress: deriveDeploymentAddress({
-                deploymentId,
-                deploymentDomain,
-            }),
+            anchorRunId: params.anchorRunId,
+            deploymentAddress: params.agentAddress,
             publicKey: result.publicKey,
         };
     }
-    async function rollbackCommittedAttachments(instanceId, committed) {
+    async function rollbackCommittedAttachments(committed) {
         if (db === undefined)
             return;
         if (committed.length === 0)
@@ -722,96 +931,103 @@ export function createSessionService(deps) {
         // 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 att of committed) {
+        for (const record of committed) {
             try {
                 await db
                     .delete(sessionAssetTable)
-                    .where(and(eq(sessionAssetTable.instanceId, instanceId), eq(sessionAssetTable.mountPath, att.mountPath)));
+                    .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=${instanceId} mountPath=${att.mountPath}: ${err instanceof Error ? err.message : String(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(instanceId, agentAddress, attachment) {
+    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 { agentAssetId, source, mountPath, sourceCommitSha, repoId, pack, ref, } = attachment;
+        const { mountPath, sourceCommitSha, repoId, pack, ref } = attachment;
         const assetPackSha = await createPackSha(pack);
-        // Insert manifest row before the pack send so we never end up in
-        // the materialized-without-manifest state. Both direct and
-        // resolver-derived materializations write a row; the `source`
-        // column records which path produced it, and `agentAssetId` is
-        // null for resolver-derived rows.
-        await db.insert(sessionAssetTable).values({
-            instanceId,
-            agentAssetId,
+        const record = {
+            runId,
             mountPath,
             assetPackSha,
             sourceCommitSha,
-            source,
-            materializedAt: new Date(),
-        });
+        };
+        // 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 {
-            await sidecarRouter.sendPack(agentAddress, pack, ref, sourceCommitSha, {
-                mountPath,
-                repoId,
-            });
+            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) {
-            // Roll back the manifest row when the send fails so the manifest
-            // and the materialized state on the sidecar can never disagree.
+            // 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.
-            try {
-                await db
-                    .delete(sessionAssetTable)
-                    .where(and(eq(sessionAssetTable.instanceId, instanceId), eq(sessionAssetTable.mountPath, mountPath)));
-            }
-            catch (rollbackErr) {
-                const msg = rollbackErr instanceof Error
-                    ? rollbackErr.message
-                    : String(rollbackErr);
-                logger.warn `session_asset rollback failed for instance=${instanceId} mountPath=${mountPath}: ${msg}`;
+            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;
         }
-    }
-    async function resolveAttachments(service, agentId) {
-        const rows = await service.listAgentAssets(agentId);
-        const resolved = [];
-        for (const row of rows) {
-            resolved.push(await resolveAttachment(row));
-        }
-        return resolved;
-    }
-    async function resolveAttachment(row) {
-        const mountPath = resolveMountPath(row);
-        const repoId = { kind: row.asset.kind, id: row.asset.id };
-        const sourceCommitSha = await agentRepoStore.repoStore.resolveRef(HUB_PRINCIPAL, repoId, row.ref);
-        if (sourceCommitSha === null) {
-            throw new Error(`attachment_ref_unresolved: ${row.asset.kind}/${row.asset.id} has no commit on ${row.ref}`);
-        }
-        const { pack, ref: returnedRef } = await agentRepoStore.repoStore.createPack(HUB_PRINCIPAL, repoId, row.ref);
-        return {
-            agentAssetId: row.id,
-            source: "direct",
-            assetName: row.asset.name,
-            assetKind: row.asset.kind,
-            mountPath,
-            sourceCommitSha,
-            repoId,
-            pack,
-            ref: returnedRef,
-        };
+        return rollbackRecord;
     }
     /**
      * Build a per-agent `ClosureResolver` from the tenant's visible
@@ -895,13 +1111,11 @@ export function createSessionService(deps) {
         return { manifest, assetIndex };
     }
     /**
-     * Build a `ResolvedAttachment` for an asset the resolver picked
-     * from but which has no per-agent attachment row. The pack is read
-     * from the asset's main ref (the same ref the resolver consumed
-     * tarballs from), and `agentAssetId` is `null` so the fan-out path
-     * knows to skip the `session_asset` insert.
+     * 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 resolveDirectAssetAttachment(args) {
+    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) {
@@ -909,10 +1123,6 @@ export function createSessionService(deps) {
         }
         const { pack, ref: returnedRef } = await agentRepoStore.repoStore.createPack(HUB_PRINCIPAL, repoId, DEFAULT_ASSET_REF);
         return {
-            agentAssetId: null,
-            source: "resolved",
-            assetName: args.asset.name,
-            assetKind: args.asset.kind,
             mountPath: args.mountPath,
             sourceCommitSha,
             repoId,
@@ -920,22 +1130,6 @@ export function createSessionService(deps) {
             ref: returnedRef,
         };
     }
-    function collectAvailableSkills(resolved) {
-        const entries = [];
-        for (const att of resolved) {
-            if (att.assetKind !== "skill")
-                continue;
-            const index = getSkillIndex(att.repoId.id, att.ref);
-            for (const entry of index) {
-                entries.push({
-                    qualifiedName: `${att.assetName}/${entry.name}`,
-                    description: entry.description,
-                    workspacePath: `workspace/${att.mountPath}${entry.workspaceSubpath}`,
-                });
-            }
-        }
-        return entries;
-    }
     async function attemptCleanup(agentAddress, failedPhase, originalErr) {
         try {
             await sidecarRouter.sendAgentUndeploy(agentAddress, failedPhase);
@@ -977,7 +1171,7 @@ export function createSessionService(deps) {
         const signature = await createDetachedSignatureFromProvider(signedContent, cryptoProvider);
         const rawMessage = assembleMessage(headers, signedContent, signature);
         const base64 = base64Encode(rawMessage);
-        const delivered = sidecarRouter.routeMail(agentAddress, base64);
+        const delivered = sidecarRouter.routeMail(agentAddress, base64, messageId);
         if (!delivered) {
             throw new Error(`Failed to deliver message to ${agentAddress}: agent is unreachable`);
         }
@@ -988,9 +1182,9 @@ export function createSessionService(deps) {
     }
     return {
         stageWorkflowStep,
-        deployInstanceAtHead,
-        deploySingleStepAtHead,
-        deployWorkflowDefinition,
+        deployWorkflowFromSource,
+        installAndApproveWorkflowSource,
+        deployPreparedCodeSourcedWorkflow,
         sendUserMessage,
         endSession,
     };